# 🔐 candados: Acceso Seguro a Contraseñas (Sin Exponer)

## 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 (30 min) antes de liberar credenciales.

**Principio fundamental:** Las contraseñas **NUNCA** deben aparecer en pantalla, logs ni archivos temporales visibles.

---

## ⚠️ REGLA DE ORO — NUNCA MOSTRAR CONTRASEÑAS

Esta herramienta está diseñada para que las contraseñas **NUNCA** se muestren en pantalla ni queden registradas en logs, históricos de shell o archivos temporales visibles.

```
┌─────────────────────────────────────────────────────────────────────┐
│  🛡️  NUNCA uses `get` en comandos automatizados o logs             │
│                                                                     │
│  ✅ CORRECTO:  ruby candados.rb run <clave> 'ssh $USR@host'        │
│  ❌ INCORRECTO: ruby candados.rb get <clave> | algo                │
│                                                                     │
│  El comando `get` imprime la contraseña a stdout → queda en logs   │
│  El comando `run` inyecta USR/PASS en el entorno → no deja rastro  │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 📥 MÉTODOS PARA CARGAR CONTRASEÑAS EN VARIABLES

### ★ MÉTODO 1: `run` (PRIMARIO - Recomendado para comandos)

Ejecuta un comando con `USR` y `PASS` inyectadas en su entorno. La contraseña **NUNCA** se imprime ni queda en logs.

```bash
# Sintaxis
ruby candados.rb run <clave> 'comando que usa $USR y $PASS'

# Ejemplos
ruby candados.rb run srv-dasu:rmonla 'sshpass -p $PASS ssh $USR@host'
ruby candados.rb run srv-ns8:root 'ssh $USR@$HOSTNAME "comando"'
```

**¿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**

### ★ MÉTODO 2: `load` (Para shell interactivo)

Carga `USR` y `PASS` en variables de entorno del shell actual. Usa un archivo temporal (600) que se auto-elimina tras el source.

```bash
# Sintaxis
eval $(ruby candados.rb load <clave>)

# Ejemplo
eval $(ruby candados.rb load srv-dasu:rmonla)
# → Carga $USR y $PASS en tu shell actual
sshpass -p $PASS ssh $USR@servidor
```

**Seguridad:** El archivo temporal tiene permisos `600` y se auto-borra inmediatamente después del `source`.

---

## ⚙️ 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 30 min via `.session` (permisos 600).
- **Master Key**: `.master.key` local (permisos 600, nunca se comparte).

## 🔒 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`

## 🔑 Resolución Automática de Claves

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 |
| `load <clave>` | ✅ Archivo temporal 600 | Carga en shell (usar con `eval`) |
| `sudo <cmd>` | ✅ Nada expuesto | Ejecuta con privilegios desde bóveda |
| `authorize` | ✅ | Abrir candado (30 min) |
| `cerrar` | ✅ | Cerrar sesión manualmente |
| `set <clave>` | ✅ Input sin eco | Guardar secreto |
| `list` | ✅ | Listar claves (no muestra valores) |
| `get <clave>` | ⚠ Imprime a stdout | Obtener valor directo (⚠ solo uso manual) |

## 🛡️ 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 (sesión de 30 min)
2. **Usar `run`** como método primario (inyecta USR/PASS, no imprime)
3. **Usar `load`** para shell interactivo (eval + source)
4. **Evitar `get`** en automatizaciones (imprime la contraseña)
5. **Cerrar sesión** con `cerrar` cuando ya no se necesite

```bash
# Flujo típico
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*