Skip to content

Commit 26965de

Browse files
MateoGonzalezLouridoMateoGonzalezLourido
committed
docs de .env
1 parent 9e9cdbb commit 26965de

2 files changed

Lines changed: 135 additions & 6 deletions

File tree

‎Docs/env_doc/env.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
1-
#Hay dos .env necesarios:
2-
- .env.secret: donde se guardan url de mongodb, apikeys, secretkeys...
3-
- .env.config: donde se guardan las configuraciones internas de la app que no son accesibles al usuario.
1+
# Variables de Entorno
42

5-
#Hay un archivo de ejemplo para ambos:
6-
- .env.secret.example
7-
- .env.config.example
3+
Hay dos archivos `.env` necesarios para arrancar la app:
4+
5+
- `.env.secret` — URI de MongoDB, API keys, claves de cifrado y secretos de autenticación.
6+
- `.env.config` — Configuración interna de la app (no expuesta al usuario).
7+
8+
Ambos se colocan en `env/` antes del primer arranque. El vault los cifra automáticamente y los elimina del disco; a partir de ese momento las variables se leen desde el baúl cifrado.
9+
10+
## Archivos de ejemplo
11+
12+
- [`Docs/env_doc/.env.secret.example`](.env.secret.example)
13+
- [`Docs/env_doc/.env.config.example`](.env.config.example)
14+
15+
## Sistema de cifrado (vault)
16+
17+
Ver [`Docs/env_doc/vault.md`](vault.md) para la documentación completa del vault.

‎Docs/env_doc/vault.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Vault de Variables de Entorno
2+
3+
## ¿Qué es?
4+
5+
El vault es un sistema que cifra los archivos `.env` del proyecto usando la API nativa del sistema operativo (`safeStorage` de Electron), y los elimina del disco en texto plano. En arranques posteriores, las variables se leen directamente desde los archivos cifrados del baúl.
6+
7+
El objetivo es que **las credenciales nunca queden en disco en texto plano** tras el primer arranque de la app.
8+
9+
---
10+
11+
## Archivos implicados
12+
13+
| Archivo | Rol |
14+
|---|---|
15+
| `env/.env.secret` | Variables sensibles (MongoDB, claves, API keys). Se consume una sola vez. |
16+
| `env/.env.config` | Configuración interna de la app. Se consume una sola vez. |
17+
| `backend/utils/env_vault.js` | Lógica del vault: migración, cifrado y carga. |
18+
| `<userData>/env_vault/*.enc` | Archivos cifrados persistentes. Los gestiona el vault, no tocar a mano. |
19+
20+
Los archivos `.example` en `Docs/env_doc/` sirven de plantilla y **nunca** son procesados por el vault (se ignoran por extensión).
21+
22+
---
23+
24+
## Flujo de arranque
25+
26+
```
27+
app.whenReady()
28+
│
29+
▼
30+
¿Hay .env en env/?
31+
│
32+
Sí │ No │
33+
▼ ▼
34+
cifrar con safeStorage ¿Hay .enc en userData/env_vault/?
35+
escribir .enc en userData/ │
36+
borrar .env original Sí │ No │
37+
│ ▼ ▼
38+
└──────────────────► descifrar .enc (sin vars)
39+
inyectar en
40+
process.env
41+
```
42+
43+
1. **Migración** (`migrarEnvAlBaul`): detecta `.env` no vacíos en `env/`, los cifra con `safeStorage.encryptString()`, escribe el `.enc` en `<userData>/env_vault/` y, solo si la escritura fue exitosa, borra el original.
44+
2. **Carga** (`cargarDesdeVaul`): lee los `.enc` del baúl, los descifra con `safeStorage.decryptString()`, parsea las variables y las inyecta en `process.env`. El baúl tiene prioridad sobre cualquier carga previa de dotenv.
45+
46+
Ambas funciones son invocadas por `inicializarVault()` dentro de `app.whenReady()` en `main.js`, antes de arrancar el servidor y la conexión a MongoDB.
47+
48+
---
49+
50+
## Backend de cifrado por SO
51+
52+
`safeStorage` delega el cifrado al llavero nativo del sistema operativo:
53+
54+
| SO | Backend |
55+
|---|---|
56+
| Linux | libsecret (gnome-keyring / kwallet) |
57+
| Windows | DPAPI |
58+
| macOS | Keychain |
59+
60+
Si el llavero no está disponible (p. ej. entorno headless sin gnome-keyring), el vault muestra un aviso y **no migra ni carga**. Los `.env` originales permanecen en disco sin cifrar.
61+
62+
---
63+
64+
## Ruta del baúl
65+
66+
Los `.enc` se almacenan en:
67+
68+
```
69+
<userData>/env_vault/<nombre-original>.enc
70+
```
71+
72+
`<userData>` es la ruta que devuelve `app.getPath('userData')` de Electron. Ejemplos típicos:
73+
74+
- **Linux**: `~/.config/Ravage/env_vault/`
75+
- **Windows**: `%APPDATA%\Ravage\env_vault\`
76+
- **macOS**: `~/Library/Application Support/Ravage/env_vault/`
77+
78+
---
79+
80+
## Primer uso
81+
82+
1. Copia los archivos de ejemplo y rellénalos:
83+
84+
```bash
85+
cp Docs/env_doc/.env.secret.example env/.env.secret
86+
cp Docs/env_doc/.env.config.example env/.env.config
87+
```
88+
89+
2. Edita `env/.env.secret` y `env/.env.config` con los valores reales.
90+
91+
3. Arranca la app. El vault migra y cifra los archivos automáticamente. Los `.env` desaparecen del directorio `env/`.
92+
93+
A partir del segundo arranque **no hace falta volver a crear los `.env`**; el vault los tiene cifrados.
94+
95+
---
96+
97+
## Re-migración y actualización de variables
98+
99+
Si necesitas cambiar una variable:
100+
101+
1. Crea de nuevo el `.env` correspondiente en `env/` con el contenido actualizado.
102+
2. Arranca la app. El vault detecta el archivo, lo cifra y sobreescribe el `.enc` anterior.
103+
104+
---
105+
106+
## Comportamiento ante errores
107+
108+
- Si el cifrado de un archivo falla, el original **no se borra** y se registra el error en consola con prefijo `[EnvVault]`.
109+
- Si el descifrado de un `.enc` falla, ese archivo se omite y el resto se sigue cargando.
110+
- Los errores no detienen el arranque de la app; el proceso continúa con las variables que sí se pudieron cargar.
111+
112+
---
113+
114+
## Variables disponibles
115+
116+
Ver los archivos de ejemplo para la lista completa:
117+
118+
- [`Docs/env_doc/.env.secret.example`](.env.secret.example) — credenciales y claves
119+
- [`Docs/env_doc/.env.config.example`](.env.config.example) — configuración interna

0 commit comments

Comments
 (0)