# 🔐 ns8-candados: Gestión de Secretos y Autorización SSH

## Resumen Ejecutivo
`ns8-candados` es una herramienta de seguridad robusta diseñada para centralizar, cifrar y gestionar secretos operativos del ecosistema `srv-ns8`. Utiliza el algoritmo industrial **AES-256-GCM** para garantizar la integridad y confidencialidad de las credenciales. Su arquitectura implementa un sistema de **Candado Temporal (MFA)** que requiere una autorización explícita para liberar secretos, protegiendo la información incluso si el servidor se ve comprometido.

---

## 🔍 Análisis Estructural
- **Tipo de Proyecto**: Utilidad de seguridad CLI escrita en Ruby.
- **Organización**: Estructura modular centrada en la protección del dato:
  - `Cripto`: Motor criptográfico AES-256-GCM con IV aleatorio.
  - `Boveda`: Persistencia cifrada en `.boveda.json`.
  - **MFA / Autorización**: Sistema de sesiones temporales basadas en archivos con permisos restringidos.
- **Archivos Fundamentales**:
  - `ns8-candados.rb`: Lógica central.
  - `.master.key` (Local): La semilla de cifrado (permisos 600).
  - `.boveda.json`: Almacén de secretos cifrados (permisos 600).
  - `.session`: Token de autorización temporal (vida: 5 min, permisos 600).

## ⚙️ Configuración y Dependencias
- **Tecnologías**: Ruby, OpenSSL.
- **Seguridad de Archivos**: Todos los archivos sensibles se manejan con `chmod 600`, asegurando que **solo el propietario** de la herramienta pueda operar.
- **Comandos de Gestión**:
  - `ruby ns8-candados.rb authorize`: **Abre el candado**. Habilita el acceso a secretos durante 5 minutos.
  - `ruby ns8-candados.rb cerrar`: **Cierra el candado** manualmente eliminando la sesión activa.
  - `ruby ns8-candados.rb list`: Lista las claves guardadas (requiere autorización).
  - `ruby ns8-candados.rb get <clave>`: Recupera el valor descifrado (requiere autorización).

## 🛡️ Auditoría (logging)
La herramienta mantiene un archivo `access.log` en su directorio local que registra de forma inmutable:
- **Timestamp**: Fecha y hora exacta de la acción.
- **Usuario**: El usuario del sistema operativo que ejecutó el comando.
- **Acción**: `AUTHORIZE`, `GET`, `LOCK`, `DENIED` o `EXPIRED`.
- **Detalle**: Nombre de la clave solicitada (solo en comandos `get`).

El archivo tiene permisos `600` para asegurar que solo el propietario pueda auditar los accesos.

## 🧠 Contexto para IA
- **Flujo Obligatorio**: Los agentes de IA DEBEN ejecutar `authorize` antes de intentar recuperar cualquier clave.
- **Captura Segura**: Capturar siempre la salida en variables silenciadas:
  ```bash
  ruby tools/ns8-candados/ns8-candados.rb authorize
  PASS=$(ruby tools/ns8-candados/ns8-candados.rb get clave)
  # Operar y luego cerrar:
  ruby tools/ns8-candados/ns8-candados.rb cerrar
  ```

## 🚀 Próximos Pasos

### Propuestas de Mejora
- **Auditoría**: Implementar un `access.log` para trazar quién y cuándo abrió el candado.
- **Notificación**: Enviar un mensaje (ej. Telegram/Mail) cada vez que se ejecute `authorize`.

---
*Generado siguiendo docs/prompt/documentacion.md*