[P2604] Fase 15: Optimización IA e integración de herramienta candados. Sincronización de bitácoras y actualización de planes de proyecto.

adn/tools/candados/README.md

@@ -0,0 +1,106 @@
+# 🔐 candados: Gestión Segura de Secretos
+
+## Resumen Ejecutivo
+`candados` es la herramienta central de seguridad del ecosistema ADN. Cifra y gestiona secretos con **AES-256-GCM**, implementando un sistema de **Candado Temporal** que requiere autorización explícita (5 min) antes de liberar credenciales.
+
+**Principio fundamental:** Las contraseñas **NUNCA** deben aparecer en pantalla, logs ni archivos temporales.
+
+---
+
+## ⚙️ Arquitectura
+- **Cripto**: Motor AES-256-GCM con IV aleatorio y autenticación.
+- **Bóveda**: Persistencia cifrada en `.boveda.json` (permisos 600).
+- **MFA Temporal**: Sesiones de 5 min via `.session` (permisos 600).
+- **Master Key**: `.master.key` local (permisos 600, nunca se comparte).
+
+## 🚀 Comando Primario: `run` ★
+
+El comando `run` es la forma **recomendada** de usar credenciales. Inyecta `USR` y `PASS` directamente en el entorno del subproceso sin imprimir nada:
+
+```bash
+# 1. Autorizar (dura 5 min)
+ruby candados.rb authorize
+
+# 2. Ejecutar comando con credenciales inyectadas
+ruby candados.rb run srv-dasu:rmonla 'sshpass -p $PASS ssh $USR@host "comando"'
+
+# Retrocompatible con variable legacy (SSHPASS, etc.)
+ruby candados.rb run admindasu SSHPASS 'sshpass -e ssh root@host'
+```
+
+**¿Qué pasa internamente?**
+1. Descifra las credenciales de la bóveda
+2. Las inyecta como `USR` y `PASS` en el entorno del subproceso
+3. Ejecuta el comando
+4. Limpia las variables al terminar
+5. **Nada se imprime en pantalla ni queda en logs**
+
+## 🔒 Comando: `sudo`
+
+Ejecuta comandos con privilegios, resolviendo la contraseña automáticamente:
+
+```bash
+ruby candados.rb sudo tailscale set --operator=$USER
+ruby candados.rb sudo apt update
+```
+
+La clave se busca automáticamente:
+1. `<hostname>:<usuario>:sudo` (ej: `ns8:rmonla:sudo`)
+2. Variantes normalizadas del hostname
+3. Fallback genérico: `sudo`
+
+## 📦 Comando Secundario: `load`
+
+Para uso interactivo cuando se necesitan las variables en el shell actual. **Nunca imprime la contraseña:**
+
+```bash
+eval $(ruby candados.rb load srv-dasu:rmonla)
+# USR y PASS están disponibles en el shell
+```
+
+Internamente escribe los exports a un archivo temporal (`/tmp/.candados_env_<hex>`) con permisos `600`, y a stdout solo emite el comando `source` + autoborrado.
+
+## 🔑 Resolución Automática de Pares
+
+Los comandos `run` y `load` detectan automáticamente el par usuario/contraseña:
+
+| Formato de clave | USR | PASS |
+|---|---|---|
+| `srv-dasu:rmonla` | `rmonla` (parte después de `:`) | Valor cifrado |
+| `tailscale_dasuten_pass` | Busca `tailscale_dasuten_user` | Valor cifrado |
+| `admindasu` | Busca `admindasu_user` (si existe) | Valor cifrado |
+
+## 📋 Referencia Rápida
+
+| Comando | Seguridad | Descripción |
+|---|---|---|
+| `run <clave> <cmd>` | ✅ Nada expuesto | **★ PRIMARIO** - Ejecuta con USR/PASS inyectados |
+| `sudo <cmd>` | ✅ Nada expuesto | Ejecuta con privilegios desde bóveda |
+| `load <clave>` | ✅ Archivo temporal 600 | Carga en shell (usar con `eval`) |
+| `get <clave>` | ⚠ Imprime a stdout | Obtener valor directo (usar con cuidado) |
+| `authorize` | ✅ | Abrir candado (5 min) |
+| `set <clave>` | ✅ Input sin eco | Guardar secreto |
+| `list` | ✅ | Listar claves |
+
+## 🛡️ Auditoría
+
+Archivo `access.log` (permisos 600) registra:
+- **Timestamp** y **Usuario** del SO
+- **Acción**: `AUTHORIZE`, `GET`, `LOAD`, `RUN`, `SUDO`, `LOCK`, `DENIED`, `EXPIRED`
+- **Detalle**: Clave solicitada y comando ejecutado
+
+## 🧠 Contexto para IA
+
+1. **Siempre** ejecutar `authorize` antes de operar
+2. **Usar `run`** como método primario (inyecta, no imprime)
+3. **Evitar `get`** en comandos automatizados (filtra en logs)
+4. Cerrar sesión con `cerrar` cuando ya no se necesite
+
+```bash
+ruby candados.rb authorize
+ruby candados.rb run srv-dasu:rmonla 'sshpass -p $PASS ssh $USR@host "ls"'
+ruby candados.rb cerrar
+```
+
+---
+*Generado siguiendo docs/prompt/documentacion.md*