system-docs/04_SEGURIDAD/secretos.md

# Gestión de Secretos TZZR

**Versión:** 5.0
**Fecha:** 2024-12-24

---

## Arquitectura de Secretos

### Principio Fundamental

> **DECK y CORP son instancias autónomas. Deben operar independientemente de ARCHITECT.**

ARCHITECT es el constructor/coordinador. DECK y CORP son instancias diseñadas para trabajar solas.

### Modelo de Gestión

```
┌─────────────────────────────────────────────────────────────────┐
│                        ARCHITECT                                │
│                       (Constructor)                             │
│                                                                 │
│                    ┌──────────────┐                             │
│                    │   Infisical  │ ← Gestión centralizada      │
│                    │   :8082      │   Single source of truth    │
│                    └──────┬───────┘                             │
│                           │                                     │
└───────────────────────────┼─────────────────────────────────────┘
                            │
               sync/push    │   (en deploy o periódico)
                            │
           ┌────────────────┴────────────────┐
           ▼                                 ▼
┌──────────────────────┐        ┌──────────────────────┐
│        DECK          │        │        CORP          │
│     (Instancia)      │        │     (Instancia)      │
│                      │        │                      │
│   ┌──────────────┐   │        │   ┌──────────────┐   │
│   │ Vaultwarden  │   │        │   │ Vaultwarden  │   │
│   │    :8085     │   │        │   │    :8081     │   │
│   └──────┬───────┘   │        │   └──────┬───────┘   │
│          │           │        │          │           │
│          ▼           │        │          ▼           │
│   CLARA, ALFRED      │        │   MARGARET, JARED    │
│   leen de aquí       │        │   MASON, FELDMAN     │
│                      │        │   leen de aquí       │
└──────────────────────┘        └──────────────────────┘
```

### Gestores por Servidor

| Servidor | Gestor | Puerto | Rol |
|----------|--------|--------|-----|
| ARCHITECT | Infisical | 8082 | Gestión central, source of truth |
| DECK | Vaultwarden | 8085 | Operación autónoma DECK |
| CORP | Vaultwarden | 8081 | Operación autónoma CORP |

---

## Flujo de Secretos

### Administración (en ARCHITECT)

```
Administrador
     │
     ▼
┌─────────────┐
│  Infisical  │  ← Crear/modificar/rotar secretos aquí
│  (central)  │
└─────────────┘
```

### Sincronización (ARCHITECT → Instancias)

```
Infisical (ARCHITECT)
     │
     │  Script de sync / deploy
     │
     ├────────────────┬────────────────┐
     ▼                ▼                ▼
Vaultwarden      Vaultwarden      (otras instancias
   DECK             CORP            futuras)
```

### Operación (en cada instancia)

```
┌──────────────────────────────────────┐
│              DECK                    │
│                                      │
│  CLARA ──────► Vaultwarden ◄─────── ALFRED
│                   :8085              │
│                                      │
│  ✅ No depende de ARCHITECT          │
│  ✅ Opera si ARCHITECT está caído    │
└──────────────────────────────────────┘
```

---

## Estado Actual: Problema

**Triple gestión sin sincronización:**

| Fuente | Ubicación | Estado |
|--------|-----------|--------|
| Infisical | ARCHITECT :8082 | Parcialmente usado |
| creds_* | PostgreSQL ARCHITECT | Activo |
| .env | /opt/*/.env en cada servidor | Activo, **permisos 644** |

**Problemas:**
- Secretos duplicados en múltiples lugares
- Sin sincronización entre fuentes
- .env legibles por todos (644)
- Vaultwarden de DECK/CORP no integrados

---

## Decisión D-001: Arquitectura de Secretos

### Objetivo

1. **Infisical** (ARCHITECT): Única fuente de verdad para administración
2. **Vaultwarden** (DECK/CORP): Gestores locales para operación autónoma
3. **Sync**: Mecanismo de propagación Infisical → Vaultwarden

### División de Responsabilidades

| Tipo de Secreto | Gestión en | Operación en |
|-----------------|------------|--------------|
| API keys externas (OpenAI, etc.) | Infisical | Vaultwarden local |
| R2 credentials | Infisical | Vaultwarden local |
| Gitea tokens | Infisical | Vaultwarden local |
| DB password DECK | Infisical | Vaultwarden DECK |
| DB password CORP | Infisical | Vaultwarden CORP |
| Tokens internos DECK | Infisical | Vaultwarden DECK |
| Tokens internos CORP | Infisical | Vaultwarden CORP |

### Flujo de Trabajo

```
1. Admin modifica secreto en Infisical (ARCHITECT)
              │
              ▼
2. Script de sync detecta cambio
              │
              ▼
3. Propaga a Vaultwarden de DECK y/o CORP
              │
              ▼
4. Servicios locales usan Vaultwarden local
              │
              ▼
5. ARCHITECT puede caer → DECK/CORP siguen operando
```

---

## Plan de Migración

### Fase 1: Inventario

```
├── Catalogar todos los secretos en creds_*
├── Catalogar todos los secretos en .env
├── Identificar duplicados/inconsistencias
└── Mapear qué secretos necesita cada instancia
```

### Fase 2: Centralización en Infisical

```
├── Migrar todos los secretos a Infisical
├── Organizar por instancia (DECK, CORP)
├── Establecer políticas de acceso
└── Documentar cada secreto
```

### Fase 3: Configurar Vaultwarden en Instancias

```
├── DECK: Configurar Vaultwarden :8085
│   ├── Crear organización "DECK"
│   ├── Importar secretos de DECK desde Infisical
│   └── Configurar acceso para servicios
│
└── CORP: Configurar Vaultwarden :8081
    ├── Crear organización "CORP"
    ├── Importar secretos de CORP desde Infisical
    └── Configurar acceso para servicios
```

### Fase 4: Implementar Sync

```
├── Crear script de sincronización
│   └── infisical export → vaultwarden import
├── Configurar trigger (manual, cron, o webhook)
└── Probar sync en ambas direcciones
```

### Fase 5: Actualizar Servicios

```
├── CLARA: Leer de Vaultwarden DECK
├── ALFRED: Leer de Vaultwarden DECK
├── MARGARET: Leer de Vaultwarden CORP
├── JARED: Leer de Vaultwarden CORP
├── MASON: Leer de Vaultwarden CORP
└── FELDMAN: Leer de Vaultwarden CORP
```

### Fase 6: Deprecación

```
├── Eliminar archivos .env
├── Marcar creds_* como "solo referencia histórica"
└── Documentar proceso completo
```

---

## Implementación

### Lectura desde Vaultwarden (Python)

```python
import requests

VAULTWARDEN_URL = "http://localhost:8085"  # DECK
# VAULTWARDEN_URL = "http://localhost:8081"  # CORP

def get_secret(name: str) -> str:
    """Obtiene secreto de Vaultwarden local."""
    # Implementar según API de Vaultwarden/Bitwarden
    pass
```

### Script de Sync (Infisical → Vaultwarden)

```bash
#!/bin/bash
# /opt/scripts/sync_secrets.sh

# Exportar desde Infisical
infisical export --env=deck --format=json > /tmp/deck_secrets.json
infisical export --env=corp --format=json > /tmp/corp_secrets.json

# Importar a Vaultwarden DECK
ssh deck 'bw import --format json /tmp/deck_secrets.json'

# Importar a Vaultwarden CORP
ssh corp 'bw import --format json /tmp/corp_secrets.json'

# Cleanup
rm /tmp/*_secrets.json
```

---

## Mitigación Inmediata

### Paso 1: Permisos .env (URGENTE)

```bash
# DECK
ssh -i ~/.ssh/tzzr root@72.62.1.113 'chmod 600 /opt/clara/.env /opt/alfred/.env'

# CORP
ssh -i ~/.ssh/tzzr root@92.112.181.188 'chmod 600 /opt/margaret/.env /opt/mason/.env /opt/feldman/.env'
```

### Paso 2: Verificar Vaultwarden

```bash
# DECK
curl -s http://72.62.1.113:8085/api/health

# CORP
curl -s http://92.112.181.188:8081/api/health
```

---

## Rotación de Secretos

### Política

| Tipo | Frecuencia | Responsable |
|------|------------|-------------|
| API Keys externas | 90 días | Admin vía Infisical |
| Contraseñas DB | 180 días | Admin vía Infisical |
| SSH Keys | 365 días | Admin vía Infisical |
| Tokens Gitea | 180 días | Admin vía Infisical |

### Proceso

```
1. Rotar en Infisical (ARCHITECT)
2. Ejecutar sync a Vaultwarden (DECK/CORP)
3. Verificar servicios operando
4. Documentar rotación
```

---

## Verificación

### Checklist

- [ ] Infisical operativo en ARCHITECT
- [ ] Vaultwarden operativo en DECK (:8085)
- [ ] Vaultwarden operativo en CORP (:8081)
- [ ] Sync configurado y probado
- [ ] Servicios leen de Vaultwarden local
- [ ] .env eliminados o con permisos 600
- [ ] DECK opera si ARCHITECT cae
- [ ] CORP opera si ARCHITECT cae

### Test de Autonomía

```bash
# 1. Detener ARCHITECT (simulado)
# 2. Verificar DECK sigue operando
curl http://72.62.1.113:5051/health  # CLARA

# 3. Verificar CORP sigue operando
curl http://92.112.181.188:5051/health  # MARGARET
```

---

## Resumen

| Componente | Rol |
|------------|-----|
| **Infisical (ARCHITECT)** | Gestión centralizada, source of truth |
| **Vaultwarden (DECK)** | Operación autónoma instancia personal |
| **Vaultwarden (CORP)** | Operación autónoma instancia empresarial |
| **Sync** | Propagación de cambios |

**Principio clave:** Las instancias (DECK, CORP) nunca dependen de ARCHITECT en runtime.