[Seguridad] Consolidar scripts de bóveda en scripts/seguridad/ + documentar mecanismo candado.rb en ADN

adn/03_seguridad.md

@@ -2,7 +2,7 @@
 
 > Referencia canónica: [`adn/00_indice.md`](00_indice.md)
 
-Esta hebra gobierna los protocolos de seguridad de red, gestión de secretos y contingencia ante fallos críticos de conectividad.
+Esta hebra gobierna los protocolos de seguridad de red, gestión de secretos, autorización SSH y contingencia ante fallos críticos de conectividad.
 
 ## 1. Protocolo de Seguridad de Red (Hombre Muerto)
 
@@ -18,24 +18,76 @@ Esta hebra gobierna los protocolos de seguridad de red, gestión de secretos y c
 
 ## 2. Gestión de Secretos (Bóveda Operativa)
 
+Todos los artefactos de seguridad residen en `scripts/seguridad/`.
+
 ### 2.1 Prohibición de Texto Plano
 La Inteligencia Artificial operante tiene **expresamente prohibido** solicitar contraseñas administrativas, tokens o claves privadas al operador, así como también plasmarlas en logs, comandos literales temporales o en la bitácora.
 
-### 2.2 Consumo Efímero de Bóveda
-Ante requerimientos de escalada de privilegios (`sudo`, `root`, `sshpass`), la IA accederá de forma autónoma a la bóveda encriptada:
+### 2.2 Componentes de la Bóveda
 
-- **Ubicación**: `scripts/.agent_secrets.json`
-- **Interfaz**: `ruby scripts/secret_box.rb decrypt <payload>`
-- **Cifrado**: AES-256-GCM con `.master.key` local (ignorada en Git).
-- **Ejecución**: Exclusivamente inyectando subshells para enmascarar la variable en los árboles de procesos:
-  ```bash
-  CMD_PASS=$(ruby scripts/secret_box.rb decrypt "$PAYLOAD")
-  sshpass -p "$CMD_PASS" ssh ...
-  ```
+| Archivo | Ubicación | Git | Descripción |
+| :--- | :--- | :---: | :--- |
+| `secret_box.rb` | `scripts/seguridad/` | ✅ | Motor de cifrado AES-256-GCM. Encripta/desencripta payloads. |
+| `.agent_secrets.json` | `scripts/seguridad/` | ❌ | Payloads cifrados (sudo, rsa, domain_admin). |
+| `.master.key` | Raíz del proyecto | ❌ | Clave maestra de la bóveda (nunca en Git). |
+
+### 2.3 Consumo Efímero de Bóveda
+
+Ante requerimientos de escalada de privilegios (`sudo`, `root`, `sshpass`), la IA accederá de forma autónoma a la bóveda:
+
+```bash
+# Ejemplo: ejecutar comando con privilegios en un nodo remoto
+CMD_PASS=$(ruby scripts/seguridad/secret_box.rb decrypt "$PAYLOAD")
+sshpass -p "$CMD_PASS" ssh root@10.0.10.205 "comando"
+```
+
+**Payloads disponibles** (en `.agent_secrets.json`):
+- `sudo`: Contraseña de sudo/root del entorno local.
+- `rsa`: Passphrase de la llave SSH (`~/.ssh/id_rsa`).
+- `domain_admin`: Credenciales de administrador del dominio `dasuten.utnlr`.
+
+## 3. Autorización SSH (Candado)
+
+### 3.1 Problema
+La llave SSH del operador está protegida con passphrase. El agente SSH no retiene las identidades entre sesiones. La IA no puede inyectar la passphrase de forma no interactiva sin `expect`.
+
+### 3.2 Solución: `candado.rb`
+El operador ejecuta el script **interactivamente** para autorizar a la IA durante una ventana de tiempo:
+
+```bash
+ruby scripts/seguridad/candado.rb [minutos]
+```
+
+**Flujo:**
+1. 🧹 Limpia identidades previas del agente SSH (`ssh-add -D`).
+2. 🔑 Pide la passphrase al operador (`ssh-add`).
+3. ✅ Verifica que la llave se cargó correctamente.
+4. 🔓 Genera un token temporal (`.agent_token`, 5 min por defecto).
+5. La IA puede ahora ejecutar comandos SSH sin intervención.
+
+### 3.3 Flujo Operativo Completo
+
+```
+OPERADOR                          IA (Agente)
+   │                                  │
+   │  ruby candado.rb 10              │
+   │  → Ingresa passphrase            │
+   │  → Token activo 10 min           │
+   │                                  │
+   │  "Listo, el candado está abierto"│
+   │─────────────────────────────────→│
+   │                                  │  ssh root@srv-dasu "qm create..."
+   │                                  │  (usa llave cargada en agente)
+   │                                  │
+   │                  ⏳ Token expira  │
+   │                                  │  ssh → ❌ (sin identidad)
+```
+
+## 4. Archivos Protegidos (`.gitignore`)
 
-### 2.3 Archivos Protegidos (`.gitignore`)
 Los siguientes artefactos **nunca** deben ser rastreados por Git:
 - `.master.key` (clave maestra de la bóveda)
-- `scripts/.agent_secrets.json` (payloads cifrados)
+- `scripts/seguridad/.agent_secrets.json` (payloads cifrados)
+- `.agent_token` (token temporal de autorización)
 - `*.key` (claves privadas)
 - `tmp/` (artefactos transitorios de la IA)