fix: UV_NO_CACHE=1 para evitar error de permisos al arrancar como UID 1000

Versión para VPS donde Docker, Nginx y usuario pedrito ya existen.
Elimina: instalación de Docker, Nginx, creación de usuario, configuración DNS.
Agrega: tabla de estado inicial, nota sobre docker-compose v1 vs v2.
De 20 secciones (60-90 min) a 17 secciones (30-45 min).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)"
+    ]
+  }
+}

CHANGELOG.md

@@ -11,6 +11,28 @@ Versiones: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.4.0] — 2026-05-26
+
+### Security
+
+- **Envelope encryption v3 en `vault.py`** — credenciales cifradas en dos capas independientes:
+  - DEK (Data Encryption Key): 32 bytes aleatorios, única por operación de cifrado.
+  - Wrapping Key: derivada de `FERNET_KEY` con PBKDF2-HMAC-SHA256, 600k iteraciones, salt de 16 bytes aleatorio por tenant. ~200ms por derivación — fuerza bruta inviable incluso con GPU.
+  - Formato en DB: `{"v":3,"s":"<salt_b64>","k":"<dek_enc>","p":"<payload_enc>"}`
+  - Propiedades: robar la DB sin `FERNET_KEY` es inútil; robar `FERNET_KEY` sin la DB también.
+- **Cache de wrapping keys** (`lru_cache`) — evita ejecutar PBKDF2 600k iter por cada tenant en cada ciclo del poller. Cache key incluye fingerprint del KEK para invalidar si cambia `FERNET_KEY`.
+- **Compatibilidad v1 preservada** — `descifrar_credenciales` detecta automáticamente formato v1 (Fernet token puro) vs v3 (JSON). No se generan nuevas v1.
+
+### Added
+
+- **`scripts/migrar_vault_v3.py`** — migración segura de credenciales v1 → v3:
+  - Verifica que todos los tenants v1 sean descifrables ANTES de tocar la DB (aborta si alguno falla).
+  - Backup automático de la DB antes de cualquier escritura.
+  - Flag `--dry-run` para ver qué haría sin modificar nada.
+  - Commit atómico: o migra todos o no migra ninguno.
+
+---
+
 ## [0.3.1] — 2026-05-26
 
 ### Security

CLAUDE.md

@@ -47,16 +47,55 @@ Toda llamada a `logger.*()` con datos externos pasa por acá.
 
 ## Arquitectura
 
+```mermaid
+graph TD
+    ABOGADO["👤 Abogado"]
+    TG(["Telegram API"])
+    CSJ(["apps.csj.gov.py · PJ"])
+
+    subgraph VPS ["VPS — Ubuntu 22.04"]
+        NGX["🔐 Nginx\nSSL · 30 r/s webhook · 10 r/min health\nX-Content-Type-Options · X-Frame-Options"]
+
+        subgraph DOCKER ["🐳 Docker container"]
+            WH["POST /webhook\n→ 404 si token inválido\nsecrets.compare_digest"]
+            HL["GET /health\npúblico: status + timestamp"]
+            HH["GET /health/history\nBearer auth · chat_id enmascarado SHA256"]
+            ONB["Onboarding FSM · 8 pasos\ninvite atómico UPDATE WHERE usado=0\ntiming ≥800ms · compare_digest"]
+            CMD["Comandos\n/notif · /exp · /pdf · /estado · /ayuda"]
+            POLLER["Poller · APScheduler\nmulti-tenant · lun-vie 7-18h"]
+            VAULT["🔐 vault.py\nPBKDF2-SHA256 600k iter\nDEK 32B por cifrado · envelope v3"]
+            CFG["🔐 config.py · Settings\nenv vars borradas post-init"]
+            SCRUB["scrub()\ntodo dato externo a logs\npasa por acá antes de escribir"]
+        end
+
+        DB[("pasante.db\ntenants · audit_log\ninvite_codes · migrations")]
+        SNAP["snapshot_{chat_id}.json\ndiff notificaciones por tenant"]
+    end
+
+    ABOGADO <-->|"HTTPS"| TG
+    TG -->|"HTTPS + X-Secret-Token"| NGX
+    NGX --> WH
+    NGX --> HL
+    NGX --> HH
+    WH --> ONB
+    WH --> CMD
+    ONB -->|"cifra credenciales"| VAULT
+    VAULT <-->|"credentials_enc"| DB
+    CMD --> DB
+    HH -->|"audit_log — chat_id enmascarado"| DB
+    POLLER -->|"HTTPS + Bearer + usuario-rol:16"| CSJ
+    CSJ -->|"notificaciones JSON"| POLLER
+    POLLER --> SNAP
+    POLLER -->|"alertas"| TG
+    POLLER -->|"descifra por tenant"| VAULT
+    CFG -.->|"configura"| VAULT
+    CFG -.->|"configura"| POLLER
+
+    classDef secure fill:#fef2f2,stroke:#991b1b,color:#450a0a
+    class NGX,VAULT,CFG,SCRUB secure
 ```
-main.py               ← entrypoint, arranca bot + poller en paralelo
-config.py             ← Settings via pydantic-settings (ÚNICA fuente de config)
-csj_client.py         ← HTTP client del PJ (login + notificaciones, read-only)
-poller.py             ← loop de polling + diff + dispara alertas
-telegram_bot.py       ← envía mensajes y maneja /comandos básicos
-storage.py            ← snapshot en JSON local (sin DB por ahora)
-utils/
-  sanitize.py         ← credential_scrubber() — NUNCA loggear sin pasar por acá
-```
+
+Ver [SECURITY.md](SECURITY.md) para el diagrama de arquitectura de seguridad detallado.
 
 ---
 
@@ -68,11 +107,13 @@ utils/
 | HTTP client | `httpx` async |
 | Bot | `python-telegram-bot v21` async |
 | Scheduler | `APScheduler 3` |
-| Cifrado | `cryptography` (Fernet) |
+| Cifrado | `cryptography` (Fernet + PBKDF2) |
+| HTTP server | `aiohttp>=3.9` (health check + webhook) |
 | Config | `pydantic-settings` |
 | Logging | `structlog` (JSON en prod, ConsoleRenderer en dev) |
+| Infraestructura | Docker + docker-compose |
 
-Sin Playwright. Sin Postgres. Sin Redis. Sin LLM. Sin Docker por ahora (opcional).
+Sin Playwright. Sin Postgres. Sin Redis. Sin LLM.
 
 **No introducir librerías fuera de esta lista sin justificación explícita.**
 

Dockerfile

@@ -21,4 +21,6 @@ USER 1000
 
 EXPOSE 8080
 
+ENV UV_NO_CACHE=1
+
 ENTRYPOINT ["uv", "run", "python", "main.py"]

PROMPT_CLAUDE_CODE_SPRINT4.md

@@ -0,0 +1,319 @@
+# Prompt para Claude Code — Sprint 4: Features 3, 5 y 1
+
+Lee `CLAUDE.md` antes de empezar. Las invariantes de seguridad aplican.
+Implementar las tres features en orden: primero F5 (más simple), luego F3, luego F1.
+
+---
+
+## Feature 5 — Frases libres → comandos (sin LLM)
+
+### Contexto
+El bot hoy responde a texto libre con "no entendí eso, mirá /ayuda".
+Hay frases obvias que debería mapear a comandos existentes sin necesidad de LLM.
+
+### Implementación
+En `telegram_bot.py`, modificar `handle_texto_libre()` para que antes de
+responder "no entendí", intente mapear el texto a un comando conocido.
+
+```python
+FRASES_COMANDOS = {
+    # Notificaciones
+    "novedades": "notif",
+    "actualizaciones": "notif",
+    "que hay nuevo": "notif",
+    "qué hay nuevo": "notif",
+    "hay algo nuevo": "notif",
+    "alguna novedad": "notif",
+    "notificaciones": "notif",
+    "notificacion": "notif",
+    "notificación": "notif",
+    "revisar": "notif",
+    "actualizar": "notif",
+    # Estado
+    "estado": "estado",
+    "como estas": "estado",
+    "cómo estás": "estado",
+    # Ayuda
+    "ayuda": "ayuda",
+    "help": "ayuda",
+    "que podes hacer": "ayuda",
+    "qué podés hacer": "ayuda",
+    "comandos": "ayuda",
+}
+```
+
+Lógica de matching: normalizar el texto del usuario (lowercase, sin acentos,
+sin signos de puntuación) y buscar si alguna frase del diccionario está
+contenida en el texto normalizado.
+
+Si hay match → ejecutar el handler correspondiente directamente.
+Si no hay match → respuesta actual ("no entendí eso...").
+
+Casos especiales a detectar por regex:
+- "expediente 198/2026" o "exp 198" → ejecutar cmd_exp con ese argumento
+- "pdf 198/2026" → ejecutar cmd_pdf con ese argumento
+
+### Verificación
+- [ ] "novedades" ejecuta lo mismo que /notif
+- [ ] "qué hay nuevo?" ejecuta lo mismo que /notif
+- [ ] "expediente 198/2026" ejecuta lo mismo que /exp 198/2026
+- [ ] Texto completamente irrelevante ("hola qué tal") sigue respondiendo con el mensaje de ayuda
+- [ ] No interfiere con el flujo de onboarding
+
+---
+
+## Feature 3 — Extracto de PDF sin LLM
+
+### Contexto
+Cuando llega una notificación con documento adjunto, el abogado quiere saber
+qué dice sin tener que descargar y abrir el PDF. La solución es extraer el
+texto del PDF con `pypdf` y mostrar las primeras líneas como extracto.
+
+Sin LLM. Sin interpretación. Texto crudo del documento con disclaimer.
+
+### Nueva dependencia
+Agregar a `pyproject.toml`:
+```
+"pypdf>=4.0",
+```
+
+### Nuevo módulo `pdf_extractor.py`
+
+```python
+"""
+pdf_extractor.py — Extracción de texto de PDFs judiciales.
+
+Sin LLM. Sin interpretación. Solo extracción de texto crudo.
+El abogado lee el extracto y decide. Pedrito no interpreta.
+
+Los PDFs nunca se guardan en disco — se procesan en memoria.
+"""
+
+from pypdf import PdfReader
+import io
+
+MAX_CHARS = 600  # máximo de caracteres a mostrar
+
+def extraer_extracto(pdf_bytes: bytes) -> str | None:
+    """
+    Extrae las primeras líneas de texto de un PDF judicial.
+    
+    Retorna el extracto como string, o None si el PDF no tiene texto
+    extraíble (PDF escaneado, imagen, etc.)
+    
+    Los PDFs del PJ son nativos (no escaneados), así que pypdf funciona.
+    """
+    try:
+        reader = PdfReader(io.BytesIO(pdf_bytes))
+        texto = ""
+        for page in reader.pages:
+            texto += page.extract_text() or ""
+            if len(texto) >= MAX_CHARS:
+                break
+        
+        texto = texto.strip()
+        if not texto:
+            return None
+            
+        # Limpiar saltos de línea múltiples
+        import re
+        texto = re.sub(r'\n{3,}', '\n\n', texto)
+        
+        if len(texto) > MAX_CHARS:
+            texto = texto[:MAX_CHARS] + "..."
+            
+        return texto
+    except Exception:
+        return None
+```
+
+### Integración en el flujo de notificaciones
+
+En `poller.py`, método `revisar_ahora()`, cuando se detecta una notificación
+nueva y se va a enviar al abogado:
+
+1. Intentar descargar el PDF (ya existe `descargar_documento_principal()`)
+2. Si descarga OK → extraer extracto con `extraer_extracto()`
+3. Enviar notificación con extracto incluido
+4. Si descarga falla o PDF sin texto → enviar notificación sin extracto (degradación elegante)
+
+### Formato del mensaje con extracto
+
+```
+📋 Nueva notificación judicial
+
+{caratula}
+Exp. {numero}/{anio} — {juzgado}
+
+Tipo: {tipo}
+Fecha: {fecha}
+
+📄 Extracto del documento:
+{extracto}
+
+⚠️ Este es el texto crudo del documento. Verificá
+el original antes de actuar.
+
+[Ver PDF] [Ir al sistema del PJ]
+```
+
+Si no hay extracto disponible, el mensaje es igual pero sin la sección
+"📄 Extracto del documento".
+
+### En `cmd_pdf()` de `telegram_bot.py`
+
+Cuando el abogado pide `/pdf 198/2026`, después de enviar el archivo también
+enviar el extracto como mensaje de texto separado:
+
+```
+📄 Contenido del documento:
+{extracto}
+
+⚠️ Verificá el original antes de actuar.
+```
+
+### Verificación
+- [ ] Una notificación nueva llega con el extracto incluido
+- [ ] Si el PDF no tiene texto extraíble, la notificación llega igual sin extracto
+- [ ] El extracto no supera 600 caracteres
+- [ ] El disclaimer siempre aparece cuando hay extracto
+- [ ] Los bytes del PDF nunca se escriben a disco
+- [ ] `scrub()` en cualquier log que mencione el contenido del extracto
+- [ ] Agregar `pypdf` a `pyproject.toml`
+
+---
+
+## Feature 1 — Backend de administración web (FastAPI + HTML puro)
+
+### Contexto
+Panel de administración interno para gestionar tenants y ver actividad.
+Solo para el admin (Marcos). No es un producto — es una herramienta operativa.
+HTML puro servido por FastAPI. Sin framework frontend. Funcional sobre bonito.
+
+### Nueva dependencia
+Agregar a `pyproject.toml`:
+```
+"fastapi>=0.115",
+"uvicorn>=0.32",
+"jinja2>=3.1",
+```
+
+### Estructura de archivos nuevos
+
+```
+admin/
+  __init__.py
+  app.py          ← FastAPI app del panel
+  auth.py         ← autenticación básica (token en .env)
+  templates/
+    base.html     ← layout común
+    tenants.html  ← listado de tenants
+    tenant.html   ← detalle de un tenant
+    audit.html    ← audit log
+```
+
+### Autenticación del panel
+
+Token estático en `.env`:
+```
+ADMIN_TOKEN=genera-uno-con-secrets.token_hex(32)
+```
+
+Middleware simple: si el request no tiene el header `X-Admin-Token` con el
+valor correcto → 403. No hace falta sesiones ni cookies para este sprint.
+
+Agregar a `Settings` en `config.py`:
+```python
+admin_token: str = ""
+admin_port: int = 8080
+```
+
+### Rutas del panel
+
+```
+GET  /              → redirect a /tenants
+GET  /tenants       → listado de todos los tenants
+GET  /tenants/{id}  → detalle de un tenant
+POST /tenants/{id}/resetear  → resetea el tenant (borra DB + snapshot)
+GET  /audit         → audit log, últimas 200 entradas, filtrable por chat_id
+GET  /audit?chat_id=X → audit log filtrado por tenant
+```
+
+### Página /tenants — tabla con columnas
+
+| chat_id | nombre | estado | tono | timezone | cédula (primeros 3 dígitos + ***) | último chequeo | acciones |
+|---------|--------|--------|------|----------|-----------------------------------|----------------|---------|
+
+La cédula se muestra parcialmente — nunca en texto plano.
+"Acciones" tiene un botón "Resetear" que hace POST a `/tenants/{id}/resetear`.
+
+### Página /tenants/{id} — detalle
+
+- Todos los campos del tenant
+- Últimas 20 entradas del audit_log para ese chat_id
+- Botón resetear
+
+### Página /audit — tabla con columnas
+
+| timestamp (hora local) | chat_id | nombre tenant | evento | resultado | detalle (JSON colapsado) |
+
+Filtro por chat_id con un input de texto simple.
+Paginación básica: 200 registros por página, botón "más antiguos".
+
+### Arrancar el panel junto con el bot
+
+En `main.py`, arrancar el servidor de administración en un thread separado:
+
+```python
+import uvicorn
+import threading
+
+def run_admin():
+    uvicorn.run("admin.app:app", host="127.0.0.1", port=settings.admin_port, log_level="warning")
+
+admin_thread = threading.Thread(target=run_admin, daemon=True)
+admin_thread.start()
+```
+
+El panel corre en `127.0.0.1:8080` — solo accesible via SSH tunnel, no expuesto públicamente.
+
+Para acceder desde tu Mac:
+```bash
+ssh -L 8080:127.0.0.1:8080 pedrito@<IP_VPS>
+# Luego abrir http://localhost:8080 en el browser
+```
+
+### Seguridad del panel
+
+- Solo escucha en 127.0.0.1 (no en 0.0.0.0) — inaccesible desde internet
+- Requiere el token en cada request
+- Las cédulas nunca se muestran completas
+- Los bearer tokens del PJ nunca aparecen en el panel
+- El panel es de solo lectura excepto la acción "resetear"
+
+### Verificación
+- [ ] `GET /tenants` muestra los tenants registrados con cédula parcial
+- [ ] `POST /tenants/{id}/resetear` borra el tenant y su snapshot
+- [ ] `GET /audit` muestra las últimas 200 entradas
+- [ ] `GET /audit?chat_id=X` filtra correctamente
+- [ ] Sin `ADMIN_TOKEN` en el request → 403
+- [ ] El panel NO es accesible desde internet (solo 127.0.0.1)
+- [ ] El panel arranca junto con el bot sin errores
+- [ ] Agregar `fastapi`, `uvicorn`, `jinja2` a `pyproject.toml`
+
+---
+
+## Orden de implementación sugerido
+
+1. Feature 5 (frases libres) — 2-3 horas, sin dependencias nuevas
+2. Feature 3 (extracto PDF) — 3-4 horas, una dependencia nueva
+3. Feature 1 (panel admin) — 4-6 horas, más compleja
+
+## Lo que NO hacer en este sprint
+
+- No usar LLM para nada — ni resumen, ni clasificación, ni mapeo de intenciones
+- No exponer el panel en un puerto público
+- No guardar PDFs en disco
+- No mostrar cédulas completas en el panel
+- No cambiar el onboarding
+- No cambiar el flujo de notificaciones existente más allá de agregar el extracto

SECURITY.md

@@ -0,0 +1,179 @@
+# Arquitectura de seguridad — Pedrito Hechakuaa
+
+Versión actual: **v0.4.1**. Ver [CHANGELOG.md](CHANGELOG.md) para historial.
+
+---
+
+## 1. Defensa en profundidad
+
+Cada vector de ataque identificado tiene al menos un control en la capa de red,
+uno en la aplicación, y uno en los datos.
+
+```mermaid
+graph LR
+    subgraph THREATS ["Vectores de ataque"]
+        T1["🌐 Red pública\nport scan · DDoS · flood"]
+        T2["📨 Webhook spoofing\nfake Telegram updates"]
+        T3["🔍 Health endpoint\nexfiltración de datos internos"]
+        T4["🔑 Onboarding\nbrute-force de códigos de invitación"]
+        T5["💾 Robo de DB\ncredenciales en texto plano"]
+        T6["🧠 Acceso a proceso\n/proc/pid/environ · docker inspect"]
+        T7["👤 Usuario no registrado\nreconocimiento de comandos"]
+    end
+
+    subgraph DEFENSES ["Controles implementados"]
+        D1["UFW: solo 22/80/443\nNginx rate-limit 30r/s webhook\n10r/min health · security headers"]
+        D2["X-Secret-Token\nsecrets.compare_digest\n→ 404 si falla (no confirma endpoint)"]
+        D3["Bearer auth en /history\nchat_id enmascarado SHA256[:8]\n/health público devuelve mínimo"]
+        D4["UPDATE atómico WHERE usado=0\ntiming mínimo ≥800ms\nsecrets.compare_digest vs master code"]
+        D5["vault.py v3: PBKDF2 + DEK/KEK\nrobar DB sin FERNET_KEY = inútil\nrobar FERNET_KEY sin DB = inútil"]
+        D6["os.environ.pop() post-init\nFERNET_KEY · tokens · secrets borrados\n(protege /proc · no docker inspect)"]
+        D7["Silencio total a desconocidos\nallowlist por chat_id\nrespuestas mínimas no revelan arquitectura"]
+    end
+
+    T1 --> D1
+    T2 --> D2
+    T3 --> D3
+    T4 --> D4
+    T5 --> D5
+    T6 --> D6
+    T7 --> D7
+
+    classDef threat fill:#fef2f2,stroke:#991b1b,color:#450a0a
+    classDef defense fill:#f0fdf4,stroke:#166534,color:#052e16
+    class T1,T2,T3,T4,T5,T6,T7 threat
+    class D1,D2,D3,D4,D5,D6,D7 defense
+```
+
+---
+
+## 2. Cifrado de credenciales — vault.py v3
+
+El sistema usa **envelope encryption** en dos capas. Comprometer una capa sola
+no es suficiente para obtener credenciales en texto plano.
+
+```mermaid
+graph TD
+    subgraph INPUT ["Entrada"]
+        FKEY["FERNET_KEY\n(del .env — jamás toca disco como texto)"]
+        CREDS["usuario + password\n(del abogado en Telegram)"]
+    end
+
+    subgraph GEN ["Generación de material criptográfico"]
+        SALT["salt = os.urandom(16)\n16 bytes aleatorios\núnico por cada operación de cifrado"]
+        DEK["dek = os.urandom(32)\n32 bytes aleatorios\núnico por cada operación de cifrado"]
+    end
+
+    subgraph KEK_LAYER ["Capa KEK — derivación de clave wrapping"]
+        PBKDF2["PBKDF2-HMAC-SHA256\n600.000 iteraciones · ~200ms\nwrapping_key = PBKDF2(FERNET_KEY, salt)\nfuerza bruta inviable incluso con GPU"]
+        WRAP["dek_enc = Fernet(wrapping_key).encrypt(dek)\nla DEK queda protegida por la clave derivada"]
+    end
+
+    subgraph DEK_LAYER ["Capa DEK — cifrado de datos"]
+        PAYLOAD["payload = JSON con usuario + password"]
+        PENC["payload_enc = Fernet(dek).encrypt(payload)\nlos datos quedan protegidos por clave efímera"]
+    end
+
+    subgraph STORED ["Guardado en DB — credentials_enc"]
+        JSON_OUT["{v:3, s:salt_b64, k:dek_enc_b64, p:payload_enc_b64}"]
+    end
+
+    FKEY --> PBKDF2
+    SALT --> PBKDF2
+    PBKDF2 --> WRAP
+    DEK --> WRAP
+    DEK --> PENC
+    CREDS --> PAYLOAD --> PENC
+    WRAP --> JSON_OUT
+    PENC --> JSON_OUT
+    SALT --> JSON_OUT
+
+    classDef input fill:#eff6ff,stroke:#1d4ed8,color:#1e3a8a
+    classDef crypto fill:#f0fdf4,stroke:#166534,color:#052e16
+    classDef stored fill:#fefce8,stroke:#854d0e,color:#451a03
+    class FKEY,CREDS input
+    class SALT,DEK,PBKDF2,WRAP,PAYLOAD,PENC crypto
+    class JSON_OUT stored
+```
+
+### Por qué dos capas
+
+| Atacante tiene acceso a... | Puede obtener credenciales? |
+|----------------------------|-----------------------------|
+| Solo la DB (`pasante.db`) | No — DEK y payload cifrados con clave derivada de FERNET_KEY |
+| Solo `FERNET_KEY` | No — el salt está en la DB; sin él no se puede derivar la wrapping key |
+| DB + `FERNET_KEY` | Sí — pero requiere acceso completo al servidor |
+| Una credencial descifrada | No afecta las demás — cada tenant tiene salt y DEK únicos |
+
+---
+
+## 3. Ciclo de vida de credenciales
+
+```mermaid
+sequenceDiagram
+    actor Abogado
+    participant ONB as Onboarding FSM
+    participant BOT as telegram_bot
+    participant VAULT as vault.py
+    participant DB as pasante.db
+    participant POLL as Poller
+    participant CSJ as apps.csj.gov.py
+
+    Note over Abogado,DB: — Alta de abogado —
+
+    Abogado->>BOT: envía contraseña por Telegram
+    BOT->>BOT: delete_message() — borra el mensaje del chat
+    BOT->>ONB: procesa credencial
+    ONB->>VAULT: cifrar_credenciales(chat_id, usuario, password, fernet_key)
+    Note over VAULT: genera salt (16B) + DEK (32B) aleatorios
+    Note over VAULT: PBKDF2(FERNET_KEY, salt, 600k iter) → wrapping_key
+    Note over VAULT: Fernet(wrapping_key).encrypt(DEK) → dek_enc
+    Note over VAULT: Fernet(DEK).encrypt(payload) → payload_enc
+    VAULT-->>ONB: JSON envelope v3
+    ONB->>DB: UPDATE tenants SET credentials_enc = ?
+    Note over ONB: del password — limpieza de memoria inmediata
+
+    Note over Abogado,CSJ: — Ciclo de polling (cada hora) —
+
+    POLL->>DB: SELECT credentials_enc FROM tenants WHERE estado='activo'
+    POLL->>VAULT: descifrar_credenciales(chat_id, credentials_enc, fernet_key)
+    Note over VAULT: lru_cache(wrapping_key) si mismo (salt, fernet_key) ya derivado
+    Note over VAULT: Fernet(wrapping_key).decrypt(dek_enc) → DEK
+    Note over VAULT: Fernet(DEK).decrypt(payload_enc) → usuario, password
+    VAULT-->>POLL: (usuario, password) — solo en memoria
+    POLL->>CSJ: POST /autenticador/login {usuario, clave}
+    CSJ-->>POLL: bearerToken (TTL 1h)
+    Note over POLL: del usuario, password — limpieza de memoria
+    POLL->>CSJ: GET /Notificaciones/PorRecibir (Bearer)
+    CSJ-->>POLL: lista de notificaciones
+    POLL->>Abogado: alerta Telegram si hay novedades
+```
+
+---
+
+## 4. Controles transversales
+
+| Control | Implementación | Archivo |
+|---------|---------------|---------|
+| Log sanitization | `scrub()` — todo dato externo pasa por acá antes de `logger.*()` | `utils/sanitize.py` |
+| Audit trail | `audit.log()` — quién, qué, cuándo, resultado — sin payload sensible | `audit.py` |
+| Rate limiting (HTTP) | `limit_req_zone` en Nginx — 30r/s webhook, 10r/min health | `DEPLOY.md § 11` |
+| Rate limiting (bot) | Ventana deslizante 20 req/60s por chat_id | `utils/rate_limiter.py` |
+| Comparación de secrets | `secrets.compare_digest()` — evita timing oracle en todas las validaciones | `health.py`, `onboarding.py` |
+| Env vars post-init | `os.environ.pop()` para FERNET_KEY, tokens y secrets tras cargar Settings | `main.py` |
+| Invite codes | `UPDATE WHERE usado=0` atómico — elimina TOCTOU race condition | `database.py` |
+| chat_id en logs | Enmascarado como `usr_` + SHA256[:8] — no reversible, sí correlacionable | `health.py` |
+| Respuestas a desconocidos | Silencio total; `/health` público devuelve solo `{status, timestamp}` | `telegram_bot.py`, `health.py` |
+| Acuse de notificaciones | `PUT /Notificaciones/{id}/recibir` **NUNCA se llama** — efecto procesal irreversible | invariante global |
+
+---
+
+## 5. Limitaciones conocidas
+
+| Limitación | Motivo | Mitigación |
+|------------|--------|------------|
+| `docker inspect` expone env vars | Docker no puede evitarlo por diseño | Usar Docker secrets en v1; FERNET_KEY en vault externo (HashiCorp Vault) |
+| Credenciales en memoria no se pueden zerear | Python `str` es inmutable; GC no garantizado | `del` inmediato post-uso; sin referencias persistentes |
+| lru_cache mantiene wrapping keys en RAM | Tradeoff performance vs isolation | Cache key incluye fingerprint del KEK; se invalida si cambia FERNET_KEY |
+| `.env` en disco del servidor | Necesario para arrancar | Permisos `600`, usuario dedicado `pedrito`, fuera del directorio web |
+| Backup de DB sin cifrar | `data/pasante.db.bak` queda en disco | Incluir en política de backup cifrado; mismos permisos que la DB |

scripts/migrar_vault_v3.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+scripts/migrar_vault_v3.py — Migración de credenciales v1 → v3 (PBKDF2 + envelope encryption).
+
+Qué hace:
+  1. Lee FERNET_KEY del .env
+  2. Conecta a la DB y lista todos los tenants con credentials_enc
+  3. Saltea tenants ya en v3 (JSON, empieza con '{')
+  4. Para cada tenant v1: descifra con el algoritmo legacy, re-cifra con v3
+  5. Si algún tenant falla al descifrar: aborta SIN escribir nada
+  6. Si todo OK: hace backup de la DB, aplica todos los UPDATE en una transacción atómica
+
+Uso:
+    python scripts/migrar_vault_v3.py             # migra de verdad
+    python scripts/migrar_vault_v3.py --dry-run   # solo muestra qué haría, no escribe
+
+Seguridad:
+  - Las credenciales descifradas NUNCA se escriben en disco ni en logs
+  - El backup de la DB se hace ANTES de cualquier modificación
+  - Si el proceso se interrumpe a mitad, el backup permite restaurar
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Migra credenciales de vault v1 a v3 (PBKDF2 + envelope encryption)"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Muestra qué haría sin escribir nada en la DB",
+    )
+    args = parser.parse_args()
+
+    env_path = Path(".env")
+    if not env_path.exists():
+        print("ERROR: No encontré .env. Ejecutá desde el directorio raíz del proyecto.")
+        sys.exit(1)
+
+    # Leer FERNET_KEY del .env
+    import re
+    env_contenido = env_path.read_text(encoding="utf-8")
+    m = re.search(r"^FERNET_KEY=(.+)$", env_contenido, re.MULTILINE)
+    if not m or not m.group(1).strip():
+        print("ERROR: FERNET_KEY no encontrada o vacía en .env")
+        sys.exit(1)
+    fernet_key = m.group(1).strip()
+
+    from config import get_settings
+    from database import run_migrations, get_conn
+    import vault
+
+    settings = get_settings()
+    await run_migrations(settings.db_path)
+    conn = get_conn()
+
+    # Traer todos los tenants con credentials_enc
+    async with conn.execute(
+        "SELECT chat_id, credentials_enc FROM tenants WHERE credentials_enc IS NOT NULL"
+    ) as cur:
+        tenants = list(await cur.fetchall())
+
+    if not tenants:
+        print("No hay tenants con credenciales en la DB. Nada que migrar.")
+        return
+
+    total = len(tenants)
+    ya_v3 = 0
+    a_migrar: list[tuple[int, str]] = []  # (chat_id, credentials_enc_v1)
+
+    for row in tenants:
+        if vault.es_formato_v3(row["credentials_enc"]):
+            ya_v3 += 1
+        else:
+            a_migrar.append((row["chat_id"], row["credentials_enc"]))
+
+    print()
+    print("=== Migración vault v1 → v3 ===")
+    print()
+    print(f"  Tenants totales:   {total}")
+    print(f"  Ya en v3:          {ya_v3}  (se saltean)")
+    print(f"  A migrar (v1):     {len(a_migrar)}")
+    print()
+
+    if not a_migrar:
+        print("  Todos los tenants ya están en v3. Nada que hacer.")
+        return
+
+    if args.dry_run:
+        print("  [DRY RUN] Los siguientes tenants serían migrados:")
+        for chat_id, _ in a_migrar:
+            print(f"    chat_id={chat_id}")
+        print()
+        print("  [DRY RUN] No se escribió nada.")
+        return
+
+    # Descifrar todos ANTES de tocar la DB — abortar si alguno falla
+    actualizaciones: list[tuple[str, int]] = []  # (nuevo_enc, chat_id)
+    errores: list[tuple[int, str]] = []
+
+    print("  Verificando que todos los v1 sean descifrables...")
+    for chat_id, credentials_enc in a_migrar:
+        try:
+            usuario, password = vault.descifrar_credenciales(chat_id, credentials_enc, fernet_key)
+            nuevo_enc = vault.cifrar_credenciales(chat_id, usuario, password, fernet_key)
+            actualizaciones.append((nuevo_enc, chat_id))
+            del usuario, password  # no dejar en memoria más de lo necesario
+        except ValueError as e:
+            errores.append((chat_id, str(e)))
+            print(f"  ERROR tenant {chat_id}: {e}")
+
+    if errores:
+        print()
+        print(f"  {len(errores)} tenant(s) no pudieron descifrarse.")
+        print("  La DB NO fue modificada. Revisá los errores de arriba.")
+        sys.exit(1)
+
+    print(f"  OK — {len(actualizaciones)} tenant(s) listos para migrar.")
+    print()
+
+    # Confirmar
+    confirmar = input("  Escribí 'migrar' para confirmar y escribir en la DB: ").strip()
+    if confirmar != "migrar":
+        print("  Operación cancelada.")
+        sys.exit(0)
+
+    # Backup de la DB ANTES de cualquier escritura
+    db_path = settings.db_path
+    bak_path = db_path.with_suffix(".db.bak")
+    shutil.copy2(db_path, bak_path)
+    print(f"\n  Backup guardado en {bak_path}")
+
+    # Aplicar todos los UPDATE en una sola transacción
+    for nuevo_enc, chat_id in actualizaciones:
+        await conn.execute(
+            "UPDATE tenants SET credentials_enc = ? WHERE chat_id = ?",
+            (nuevo_enc, chat_id),
+        )
+    await conn.commit()
+
+    print(f"  {len(actualizaciones)} tenant(s) migrados a v3.")
+    print()
+    print("  ✅ Migración completada.")
+    print(f"  Backup de la DB anterior: {bak_path}")
+    print()
+    print("  Próximo paso: reiniciar el bot.")
+    print("    systemctl restart pedrito   (en VPS con systemd)")
+    print("    docker compose restart      (en VPS con Docker)")
+    print("    o Ctrl+C y uv run python main.py   (en local)")
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

telegram_bot.py

@@ -10,6 +10,7 @@ Responsabilidades:
 from __future__ import annotations
 
 import re
+import unicodedata
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 from zoneinfo import ZoneInfo
@@ -47,6 +48,41 @@ logger = structlog.get_logger(__name__)
 
 PJ_URL = "https://apps.csj.gov.py/gestion-partes/notificaciones-electronicas"
 
+# ──────────────────────────────────────────────────────────────────────────────
+# Mapeo de frases libres a comandos (sin LLM)
+# ──────────────────────────────────────────────────────────────────────────────
+
+_FRASES_COMANDOS: dict[str, str] = {
+    "novedades": "notif",
+    "actualizaciones": "notif",
+    "que hay nuevo": "notif",
+    "qué hay nuevo": "notif",
+    "hay algo nuevo": "notif",
+    "alguna novedad": "notif",
+    "notificaciones": "notif",
+    "notificacion": "notif",
+    "notificación": "notif",
+    "revisar": "notif",
+    "actualizar": "notif",
+    "estado": "estado",
+    "como estas": "estado",
+    "cómo estás": "estado",
+    "ayuda": "ayuda",
+    "help": "ayuda",
+    "que podes hacer": "ayuda",
+    "qué podés hacer": "ayuda",
+    "comandos": "ayuda",
+}
+
+
+def _normalizar(texto: str) -> str:
+    """Lowercase, sin acentos, sin puntuación — para comparación de frases."""
+    texto = texto.lower().strip()
+    texto = unicodedata.normalize("NFD", texto)
+    texto = "".join(c for c in texto if unicodedata.category(c) != "Mn")
+    texto = re.sub(r"[^\w\s]", " ", texto)
+    return re.sub(r"\s+", " ", texto).strip()
+
 # ──────────────────────────────────────────────────────────────────────────────
 # Helpers de formato
 # ──────────────────────────────────────────────────────────────────────────────
@@ -626,6 +662,45 @@ class PedritoBot:
         if self._onboarding.is_in_onboarding(chat_id):
             await self._onboarding.handle_mensaje(update, context)
 
+    async def _intentar_mapear_comando(
+        self,
+        update: Update,
+        context: ContextTypes.DEFAULT_TYPE,
+        texto: str,
+    ) -> bool:
+        """
+        Intenta mapear texto libre a un comando conocido sin LLM.
+        Retorna True si encontró match y ejecutó el handler correspondiente.
+        """
+        texto_norm = _normalizar(texto)
+        texto_lower = texto.lower()
+
+        # Regex especiales sobre texto original (preserva la "/")
+        m_exp = re.search(r"\bexp(?:ediente)?\b\s+(\d+(?:/\d+)?)", texto_lower)
+        if m_exp:
+            context.args = [m_exp.group(1)]  # type: ignore[assignment]
+            await self.cmd_exp(update, context)
+            return True
+
+        m_pdf = re.search(r"\bpdf\b\s+(\d+/\d+)", texto_lower)
+        if m_pdf:
+            context.args = [m_pdf.group(1)]  # type: ignore[assignment]
+            await self.cmd_pdf(update, context)
+            return True
+
+        # Matching por frases del diccionario
+        for frase, comando in _FRASES_COMANDOS.items():
+            if _normalizar(frase) in texto_norm:
+                if comando == "notif":
+                    await self.cmd_notif(update, context)
+                elif comando == "estado":
+                    await self.cmd_estado(update, context)
+                elif comando == "ayuda":
+                    await self.cmd_ayuda(update, context)
+                return True
+
+        return False
+
     async def handle_texto_libre(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         """Responde a texto que no es comando ni está en un flujo de onboarding."""
         chat_id = update.effective_chat.id  # type: ignore[union-attr]
@@ -635,11 +710,16 @@ class PedritoBot:
             return  # el onboarding lo maneja en handle_mensaje, no responder acá
 
         tenant = await get_tenant(chat_id)
-        if tenant and tenant.get("estado") == "activo":
+        if not (tenant and tenant.get("estado") == "activo"):
+            # Usuarios sin registro: silencio total.
+            return
+
+        texto_original = (update.effective_message.text or "")  # type: ignore[union-attr]
+        if await self._intentar_mapear_comando(update, context, texto_original):
+            return
+
         texto = _escape_md(_texto_tono("texto_no_reconocido", tenant))
         await update.effective_message.reply_text(texto, parse_mode=ParseMode.MARKDOWN_V2)  # type: ignore[union-attr]
-        # Usuarios sin registro: silencio total.
-        # No confirmar que el bot existe ni qué hace — quien lo debe usar ya sabe cómo.
 
     # ──────────────────────────────────────────────────────────────────────────
     # Handlers de callbacks

vault.py

@@ -1,55 +1,182 @@
 """
 vault.py — Cifrado de credenciales por tenant.
 
-Cada tenant tiene sus credenciales cifradas con una clave derivada de:
-  FERNET_KEY (global, del .env) + str(chat_id) (único por tenant)
+## Arquitectura v3: Envelope Encryption con PBKDF2 + DEK por tenant
 
-Esto asegura que las credenciales de un tenant no se pueden descifrar
-con solo la FERNET_KEY — hace falta también el chat_id.
+Cada credencial se cifra en dos capas independientes:
+
+  1. DEK (Data Encryption Key): 32 bytes aleatorios, única por operación de cifrado.
+  2. KEK→Wrapping Key: derivada de FERNET_KEY usando PBKDF2-HMAC-SHA256 con salt único
+     por tenant. El salt se genera al cifrar y se guarda junto al ciphertext.
+
+La KEK (FERNET_KEY del .env) nunca cifra datos directamente — solo envuelve la DEK.
+
+Formato credentials_enc v3:
+    JSON compacto: {"v":3,"s":"<salt_b64>","k":"<dek_enc_b64>","p":"<payload_enc_b64>"}
+
+    s = salt de 16 bytes (base64url) para derivar la wrapping key via PBKDF2
+    k = DEK cifrada con Fernet(wrapping_key)
+    p = {"usuario": ..., "password": ...} cifrado con Fernet(DEK)
+
+Ventajas sobre v1 (SHA256):
+  - PBKDF2 (600k iter): derivar la wrapping key cuesta ~200ms — fuerza bruta inviable
+  - Salt único por tenant: mismo FERNET_KEY + mismo password → ciphertexts distintos
+  - DEK aleatoria: comprometer una credencial no ayuda con las demás
+  - Dos capas: robar la DB sin FERNET_KEY es inútil; robar FERNET_KEY sin la DB también
+
+## Formato v1 (legacy, solo lectura)
+
+Fernet(SHA256(FERNET_KEY + str(chat_id))) — mantenido para migración desde el script
+`scripts/migrar_vault_v3.py`. No se generan nuevos v1.
 """
 from __future__ import annotations
 
 import base64
 import hashlib
 import json
+import os
+from functools import lru_cache
 
 import structlog
 from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 
 from utils.sanitize import scrub
 
 logger = structlog.get_logger(__name__)
 
+# PBKDF2: NIST SP 800-132 (2023) recomienda mínimo 600k iteraciones para SHA-256
+_PBKDF2_ITERATIONS = 600_000
+_SALT_BYTES = 16
+_DEK_BYTES = 32
 
-def _derive_key(fernet_key: str, chat_id: int) -> bytes:
-    """Deriva una clave Fernet única por tenant usando SHA-256(fernet_key + chat_id)."""
-    raw = (fernet_key + str(chat_id)).encode()
-    digest = hashlib.sha256(raw).digest()
-    return base64.urlsafe_b64encode(digest)
 
+def _derive_wrapping_key(kek: str, salt: bytes) -> bytes:
+    """
+    Deriva una wrapping key de 32 bytes usando PBKDF2-HMAC-SHA256.
+    ~200ms intencionalmente — hace fuerza bruta inviable incluso con GPU.
+    """
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=_DEK_BYTES,
+        salt=salt,
+        iterations=_PBKDF2_ITERATIONS,
+    )
+    return base64.urlsafe_b64encode(kdf.derive(kek.encode("utf-8")))
+
+
+@lru_cache(maxsize=256)
+def _wrapping_key_cached(kek_fingerprint: str, salt_hex: str, kek: str) -> bytes:
+    """
+    Cache de wrapping keys por (salt, kek) para no ejecutar PBKDF2 600k veces
+    en el mismo proceso cuando el poller revisa múltiples tenants.
+
+    kek_fingerprint es el SHA256[:8] de kek — sirve para invalidar entradas
+    si el FERNET_KEY cambia (nueva instancia del proceso).
+    """
+    return _derive_wrapping_key(kek, bytes.fromhex(salt_hex))
+
+
+def _get_wrapping_key(kek: str, salt: bytes) -> bytes:
+    """Obtiene wrapping key del cache o la deriva si no está."""
+    fingerprint = hashlib.sha256(kek.encode()).hexdigest()[:8]
+    return _wrapping_key_cached(fingerprint, salt.hex(), kek)
+
+
+# ── API pública ───────────────────────────────────────────────────────────────
 
 def cifrar_credenciales(chat_id: int, usuario: str, password: str, fernet_key: str) -> str:
-    """Retorna JSON cifrado con Fernet listo para guardar en DB."""
-    key = _derive_key(fernet_key, chat_id)
-    f = Fernet(key)
-    payload = json.dumps({"usuario": usuario, "password": password}).encode()
-    encrypted = f.encrypt(payload).decode()
-    logger.info("credenciales_cifradas", chat_id=chat_id)
-    return encrypted
+    """
+    Cifra credenciales con envelope encryption v3.
+    Retorna JSON compacto listo para guardar en DB.
+    """
+    # Capa 1: generar salt (para PBKDF2) y DEK aleatoria
+    salt = os.urandom(_SALT_BYTES)
+    dek_raw = os.urandom(_DEK_BYTES)
+    dek_b64 = base64.urlsafe_b64encode(dek_raw)
+
+    # Capa 2: cifrar DEK con wrapping key derivada de FERNET_KEY + salt
+    wrapping_key = _get_wrapping_key(fernet_key, salt)
+    f_wrap = Fernet(wrapping_key)
+    dek_enc = f_wrap.encrypt(dek_b64)
+
+    # Capa 3: cifrar payload con DEK
+    f_dek = Fernet(dek_b64)
+    payload_bytes = json.dumps({"usuario": usuario, "password": password}).encode()
+    payload_enc = f_dek.encrypt(payload_bytes)
+
+    envelope = {
+        "v": 3,
+        "s": base64.urlsafe_b64encode(salt).decode(),
+        "k": dek_enc.decode(),
+        "p": payload_enc.decode(),
+    }
+
+    logger.info("credenciales_cifradas_v3", chat_id=chat_id)
+    return json.dumps(envelope, separators=(",", ":"))
 
 
 def descifrar_credenciales(chat_id: int, credentials_enc: str, fernet_key: str) -> tuple[str, str]:
     """
-    Retorna (usuario, password).
-    Levanta ValueError si no se puede descifrar (clave incorrecta o datos corruptos).
+    Descifra credenciales. Soporta v1 (legacy) y v3 (actual).
+    Levanta ValueError si no se puede descifrar.
     """
-    key = _derive_key(fernet_key, chat_id)
+    stripped = credentials_enc.strip()
+    if stripped.startswith("{"):
+        return _descifrar_v3(chat_id, stripped, fernet_key)
+    return _descifrar_v1(chat_id, stripped, fernet_key)
+
+
+def es_formato_v3(credentials_enc: str) -> bool:
+    """Retorna True si las credenciales ya están en formato v3."""
+    return credentials_enc.strip().startswith("{")
+
+
+# ── Implementaciones internas ─────────────────────────────────────────────────
+
+def _descifrar_v3(chat_id: int, credentials_enc: str, fernet_key: str) -> tuple[str, str]:
+    try:
+        envelope = json.loads(credentials_enc)
+        if envelope.get("v") != 3:
+            raise ValueError(f"Versión desconocida: {envelope.get('v')}")
+
+        salt = base64.urlsafe_b64decode(envelope["s"])
+        dek_enc = envelope["k"].encode()
+        payload_enc = envelope["p"].encode()
+
+        # Descifrar DEK con wrapping key derivada de PBKDF2
+        wrapping_key = _get_wrapping_key(fernet_key, salt)
+        f_wrap = Fernet(wrapping_key)
+        dek_b64 = f_wrap.decrypt(dek_enc)
+
+        # Descifrar payload con DEK
+        f_dek = Fernet(dek_b64)
+        payload = json.loads(f_dek.decrypt(payload_enc).decode())
+
+        return payload["usuario"], payload["password"]
+
+    except (InvalidToken, KeyError, ValueError, json.JSONDecodeError) as e:
+        logger.error("error_descifrar_v3", chat_id=chat_id, error=scrub(str(e)))
+        raise ValueError(
+            f"No se pudieron descifrar credenciales (v3) para chat_id={chat_id}"
+        ) from e
+
+
+def _descifrar_v1(chat_id: int, credentials_enc: str, fernet_key: str) -> tuple[str, str]:
+    """
+    Legacy: clave derivada con SHA256(fernet_key + chat_id).
+    Disponible para migración — no se generan nuevas v1.
+    """
+    raw = (fernet_key + str(chat_id)).encode()
+    key = base64.urlsafe_b64encode(hashlib.sha256(raw).digest())
     f = Fernet(key)
     try:
         payload = json.loads(f.decrypt(credentials_enc.encode()).decode())
+        logger.warning("credenciales_v1_descifradas_migracion_pendiente", chat_id=chat_id)
         return payload["usuario"], payload["password"]
     except (InvalidToken, KeyError, ValueError) as e:
-        logger.error("error_descifrar_credenciales", chat_id=chat_id, error=scrub(str(e)))
+        logger.error("error_descifrar_v1", chat_id=chat_id, error=scrub(str(e)))
         raise ValueError(
-            f"No se pudieron descifrar credenciales para chat_id={chat_id}"
+            f"No se pudieron descifrar credenciales (v1) para chat_id={chat_id}"
         ) from e