admin/app.py — FastAPI con rutas /tenants, /tenants/{id}, /tenants/{id}/resetear, /audit

admin/auth.py — dependencia X-Admin-Token con secrets.compare_digest
4 templates HTML — funcionales, sin framework frontend
main.py — arranca admin en thread daemon; si ADMIN_TOKEN está vacío, no inicia el panel
Puerto 9090 (separado de health en 8080)
Cédula nunca expuesta — aparece como ***

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git checkout *)",
+      "Bash(git commit *)",
+      "Bash(git merge *)",
+      "Bash(git remote *)",
+      "Bash(uv sync *)",
+      "Bash(python -c \"from pdf_extractor import extraer_extracto; print\\('ok'\\)\")",
+      "Bash(python -c \"import poller; import telegram_bot; print\\('ok'\\)\")"
+    ]
+  }
+}

.env.example

@@ -33,6 +33,12 @@ TELEGRAM_EXTRA_IDS=
 # POLL_HORA_INICIO=7
 # POLL_HORA_FIN=18
 
+# ─── Panel de administración ──────────────────────────────────────────────────
+# Generar con: python -c "import secrets; print(secrets.token_hex(32))"
+# Acceso via SSH tunnel: ssh -L 9090:127.0.0.1:9090 pedrito@<IP>
+# Luego abrir http://localhost:9090 con header X-Admin-Token
+ADMIN_TOKEN=
+
 # ─── Otros (no tocar salvo que sepas lo que hacés) ──────────────────────────────
 # LOG_LEVEL=INFO
 # DATA_DIR=./data

CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog — Pedrito Hechakuaa
+
+Todos los cambios notables se documentan acá.
+
+Formato: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)  
+Versiones: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+
+---
+
+## [Unreleased]
+
+---
+
+## [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
+
+- **`/health/history` requiere auth** — `Authorization: Bearer <HEALTH_AUTH_TOKEN>`; sin token
+  devuelve 401 con header `WWW-Authenticate`. Sin auth configurada, retorna 401 igualmente.
+- **chat_ids enmascarados en historial** — reemplazados por hash SHA256[:8] opaco (`usr_a3b4c5d6`);
+  preserva correlación de eventos sin exponer Telegram IDs (PII).
+- **`/health` público mínimo** — sin auth devuelve solo `{status, timestamp}`. Con auth, respuesta
+  completa con métricas internas. Elimina exposición de conteo de tenants y timing del poller.
+- **Env vars borradas del proceso** — después de cargar `Settings()`, se eliminan de `os.environ`:
+  `FERNET_KEY`, `TELEGRAM_BOT_TOKEN`, `PJ_USUARIO_ENC`, `PJ_PASSWORD_ENC`, `WEBHOOK_SECRET`,
+  `HEALTH_AUTH_TOKEN`, `INVITE_CODE`. Protege contra `/proc/<pid>/environ`.
+- **Race condition TOCTOU en invite codes eliminada** — `SELECT + UPDATE` reemplazado por
+  `UPDATE WHERE codigo=? AND usado=0`; `rowcount=0` indica código no válido o ya usado.
+  Imposible que dos requests simultáneos consuman el mismo código.
+- **Timing oracle en validación de código mitigado** — delay mínimo garantizado de 800ms en
+  `_paso_codigo()` independientemente del resultado; `secrets.compare_digest()` para comparación
+  contra código del `.env`.
+- **Respuestas a usuarios no registrados reducidas al mínimo** — `_rechazar_no_registrado` ya no
+  revela la arquitectura de comandos; texto libre de usuarios sin registro recibe silencio total.
+- **Webhook inválido devuelve 404** — en vez de 403, no confirma la existencia del endpoint.
+- **Nginx rate limiting** documentado en `DEPLOY.md`: `limit_req_zone` 30r/s para webhook,
+  10r/min para health; headers `X-Content-Type-Options`, `X-Frame-Options`.
+- **`HEALTH_AUTH_TOKEN`** agregado a `config.py` y a la guía de `.env` en `DEPLOY.md`.
+
+---
+
+## [0.3.0] — 2026-05-25
+
+### Added
+
+- **Docker** — `Dockerfile` (imagen `ghcr.io/astral-sh/uv:python3.12-bookworm-slim`),
+  `docker-compose.yml` con `restart: unless-stopped` y healthcheck, `.dockerignore`.
+- **Health check HTTP** (`health.py`) — servidor aiohttp en puerto 8080:
+  - `GET /health` — estado del bot (ok/degraded)
+  - `GET /health/history` — últimos N eventos del audit log
+  - Watcher loop que alerta al admin via Telegram si el poller no actualiza en N horas
+- **Schema migrations** — directorio `migrations/001_initial_schema.sql`, función
+  `run_migrations()` en `database.py`; idempotente con `CREATE TABLE IF NOT EXISTS`.
+  Tabla `schema_migrations` lleva registro de versiones aplicadas.
+- **Webhook opt-in** — `POST /webhook` en aiohttp valida `X-Telegram-Bot-Api-Secret-Token` con
+  `compare_digest` y pone el Update en `application.update_queue` de PTB. Se activa con
+  `WEBHOOK_URL` en `.env`; vacío = long-polling.
+- `aiohttp>=3.9` como nueva dependencia.
+- `WEBHOOK_URL`, `WEBHOOK_SECRET`, `HEALTH_PORT`, `HEALTH_ALERT_HOURS` en `config.py`.
+- Poller notifica a health vía callback `on_poll_done(tenant_count)`.
+- `revisar_ahora()` retorna `int` (cantidad de tenants revisados).
+
+### Changed
+
+- `init_db()` reemplazado por `run_migrations()` en `main.py`; `init_db()` queda como alias
+  para compatibilidad con scripts.
+- `main.py` arranca `HealthServer` antes del poller; elige polling vs webhook según config;
+  registra webhook con Telegram en modo webhook; elimina webhook al detener.
+- `DEPLOY.md` actualizado con guía completa de 20 secciones: DNS Bluehost/cPanel (con mensaje
+  exacto en inglés para delegar), Nginx, Certbot/SSL, Docker, webhook, health check, rate limiting.
+
+---
+
+## [0.2.1] — 2026-05-25
+
+### Fixed
+
+- **Campos del API del PJ corregidos** — la API real usa `fechaNotificacion` (no `fecha`),
+  `descripcionDespacho` (no `juzgado`), `descripcionCircunscripcion` (no `circunscripcion`).
+  `NotificacionPendiente.__init__` ahora usa fallback `or` para ambos nombres.
+- **PDF callback** — usaba `cod_notificacion_origen` como ID de actuación; corregido a
+  `cod_actuacion_caso` (campo `codActuacionCaso` de la API).
+- **403 en `listar_notificaciones`** — manejado explícitamente como `CSJAuthError` en vez de
+  caer en `raise_for_status()` genérico.
+
+---
+
+## [0.2.0] — 2026-05-25
+
+### Added
+
+- **Multi-tenant** — `database.py` con SQLite vía aiosqlite; tabla `tenants` con credenciales
+  cifradas por chat_id; `list_active_tenants()`, `save_tenant()`, `delete_tenant()`.
+- **Onboarding flow** (`onboarding.py`) — máquina de estados de 8 pasos:
+  código de invitación → consentimiento → nombre → tono → timezone → cédula → password → guardado.
+- **Códigos de invitación** — tabla `invite_codes`, validación de un solo uso atómica,
+  fallback al código maestro del `.env`; `scripts/generar_codigo.py`.
+- **Audit log** — tabla `audit_log`, función `audit.log()` fire-and-forget; cobertura de todos
+  los eventos de onboarding, polling, comandos y errores.
+- **Rate limiting** (`utils/rate_limiter.py`) — ventana deslizante por chat_id, 20 req/60s;
+  reset en `/resetear`.
+- **FERNET_KEY rotation** (`scripts/rotar_fernet_key.py`) — re-cifra todos los tenants de forma
+  atómica; hace backup de `.env` antes de modificar; aborta si algún tenant falla.
+- Comando `/exp` — búsqueda de expedientes por número o carátula.
+- Comando `/pdf` — descarga PDF de la actuación más reciente via `permisoFirmado`.
+- Tono personalizable por abogado: formal / cotidiano / informal.
+- Zona horaria configurable por abogado.
+- `TELEGRAM_EXTRA_IDS` para autorizar IDs adicionales sin onboarding.
+- `DEPLOY.md` — primera versión de la guía de despliegue en VPS Ubuntu con systemd.
+
+### Changed
+
+- `poller.py` itera sobre todos los tenants activos (era single-tenant).
+- Snapshots por tenant: `data/snapshot_{chat_id}.json` (era `data/snapshot.json` global).
+- `vault.py` usa derivación de clave Fernet por chat_id: `base64(SHA256(FERNET_KEY + str(chat_id)))`.
+
+### Security
+
+- Contraseña del PJ borrada de memoria inmediatamente tras cifrar (`del password` en onboarding).
+- Mensaje de Telegram con la contraseña eliminado del chat vía `delete_message` antes de procesar.
+
+---
+
+## [0.1.0] — 2026-05-25
+
+### Added
+
+- Login al sistema judicial `apps.csj.gov.py`:
+  `GET /login` → cookie `cookiesession1` → `POST /autenticador/login` → bearer token (TTL 1h).
+- Polling de `GET /Notificaciones/PorRecibir` cada N minutos en horario hábil (lun-vie, 7-18hs).
+- Diff vs snapshot JSON local — solo notifica notificaciones con `codNotificacionOrigen` nuevo.
+- Relogin automático transparente al expirar el token.
+- Bot de Telegram con comandos: `/start`, `/notif`, `/estado`, `/ayuda`, `/salir`.
+- Credenciales del PJ cifradas con Fernet en `.env` (`scripts/cifrar_credenciales.py`).
+- `scrub()` en `utils/sanitize.py` — sanitiza bearer tokens, JWTs, cookies y passwords
+  antes de pasar cualquier dato externo a los logs.
+- Logging estructurado con `structlog` (JSON en prod, ConsoleRenderer en dev vía `isatty`).
+- Configuración vía `pydantic-settings` — único punto de config de la app (`config.py`).
+- Stack base: `httpx`, `python-telegram-bot[ext] v21`, `aiosqlite`, `cryptography`, `structlog`,
+  `pydantic-settings`, `apscheduler`.
+- Manejo de señales `SIGINT`/`SIGTERM` para shutdown limpio.

CLAUDE.md

@@ -6,19 +6,21 @@ Pedrito Hechakuaa: un bot de Telegram que monitorea notificaciones pendientes
 en el sistema judicial de Paraguay (`apps.csj.gov.py`) y avisa cuando aparece
 algo nuevo. Uso propio de un solo abogado (single-tenant).
 
-**Scope estricto de la v0:**
+**Versión actual: v0.3.1** — ver historial completo en `CHANGELOG.md`.
-- Login al PJ + polling de notificaciones pendientes
-- Diff vs snapshot anterior → solo notifica lo nuevo
-- Telegram como canal de salida
-- Correr en local o VPS con docker-compose
 
-**Fuera del scope de v0 (no agregar sin consulta explícita):**
+**Scope implementado:**
+- Login al PJ + polling de notificaciones pendientes (multi-tenant)
+- Diff vs snapshot por tenant → solo notifica lo nuevo
+- Telegram como canal de salida con onboarding, tono personalizable y timezone
+- Búsqueda de expedientes y descarga de PDFs
+- Infraestructura: Docker, health check HTTP, schema migrations, webhook opt-in
+
+**Fuera del scope actual (no agregar sin consulta explícita):**
 - Motor de reglas de plazos
 - LLM / conversación libre
-- Multi-tenant
 - Web de onboarding
 - Actuaciones de expedientes (es v1)
-- Acuse de notificaciones (nunca en MVP)
+- Acuse de notificaciones (nunca — efecto procesal irreversible)
 
 ---
 
@@ -45,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)
+Ver [SECURITY.md](SECURITY.md) para el diagrama de arquitectura de seguridad detallado.
-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á
-```
 
 ---
 
@@ -66,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.**
 
@@ -253,9 +296,54 @@ Ante cambio de schema del PJ: actualizar `csj_client.py` y documentar en
 | Archivo | Propósito |
 |---------|-----------|
 | `CLAUDE.md` | Este archivo — reglas para Claude Code |
-| `OBSERVATIONS.md` | Hallazgos durante el desarrollo (crear si no existe) |
+| `CHANGELOG.md` | Historial de versiones — actualizar antes de cada release |
-| `TECH_DEBT.md` | Deuda técnica anotada (crear si no existe) |
+| `DEPLOY.md` | Guía de despliegue en VPS: Docker, Nginx, SSL, DNS |
-| `data/snapshot.json` | Estado persistido del poller |
+| `OBSERVATIONS.md` | Hallazgos durante el desarrollo (schema real del PJ, etc.) |
+| `TECH_DEBT.md` | Deuda técnica anotada |
+| `migrations/` | Archivos `.sql` de schema — nunca editar los ya aplicados |
+| `data/pasante.db` | Base de datos SQLite (tenants, audit_log, invite_codes) |
+| `data/snapshot_*.json` | Estado del diff de notificaciones por tenant |
+
+---
+
+## Gestión de versiones
+
+### Esquema: Semantic Versioning (semver 2.0)
+
+`MAJOR.MINOR.PATCH` — tags git con prefijo `v` (ej: `v0.3.1`).
+
+| Número | Incrementar cuando... | Ejemplos |
+|--------|----------------------|---------|
+| `MAJOR` | Cambio incompatible con versiones anteriores: migración de DB no retrocompatible, cambio de protocolo del PJ, rediseño de arquitectura | `v1.0.0` (migración a Postgres) |
+| `MINOR` | Feature nuevo sin romper lo existente: comando nuevo, integración nueva, mejora visible al usuario | `/recordatorio`, modo silencioso |
+| `PATCH` | Bug fix, security patch, mejora interna, documentación operacional | corrección de campo del PJ, hardening |
+
+### Reglas que Claude Code sigue siempre
+
+1. **Cada release requiere entrada en `CHANGELOG.md`** con fecha y secciones
+   `Added / Changed / Fixed / Security` según corresponda.
+2. **El tag se crea después del commit de changelog**, no antes.
+3. **`[Unreleased]`** acumula todos los cambios hasta que Marcos decide liberar.
+4. **Claude propone el número de versión** basándose en las reglas de arriba;
+   Marcos lo aprueba antes de tagear.
+5. **`git tag` y `git push --tags` los ejecuta Claude solo cuando Marcos lo confirma** —
+   son acciones externas (modifican el remoto) que requieren aprobación explícita.
+6. **Tags retroactivos** son válidos para dar historia a commits anteriores;
+   se crean con `git tag -a vX.Y.Z <hash>`.
+
+### Proceso de release (copy-paste)
+
+```bash
+# 1. CHANGELOG.md ya actualizado (mover [Unreleased] → [X.Y.Z] con fecha)
+git add CHANGELOG.md
+git commit -m "chore: release vX.Y.Z"
+
+# 2. Tag anotado
+git tag -a vX.Y.Z -m "vX.Y.Z — resumen en una línea"
+
+# 3. Push incluyendo el tag
+git push origin main --tags
+```
 
 ---
 

Dockerfile

@@ -15,10 +15,10 @@ COPY . .
 RUN uv sync --frozen
 
 # Directorio de datos persistente (montar como volumen)
-RUN mkdir -p /app/data && chown -R 1000:1000 /app/data
+RUN mkdir -p /app/data && chown -R 1000:1000 /app
 
 USER 1000
 
 EXPOSE 8080
 
-ENTRYPOINT ["uv", "run", "python", "main.py"]
+ENTRYPOINT [".venv/bin/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 |

admin/app.py

@@ -0,0 +1,159 @@
+"""
+admin/app.py — Panel de administración interno (FastAPI).
+
+Solo escucha en 127.0.0.1. Acceso via SSH tunnel:
+    ssh -L 9090:127.0.0.1:9090 pedrito@<IP_VPS>
+    Luego: http://localhost:9090
+
+Autenticación: header X-Admin-Token en cada request.
+"""
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+from fastapi import Depends, FastAPI, Form, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+
+from admin.auth import require_token
+
+_db_path: str = ""
+_admin_token: str = ""
+_data_dir: Path = Path("./data")
+
+templates = Jinja2Templates(directory="admin/templates")
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    app.state.db = await aiosqlite.connect(_db_path)
+    app.state.db.row_factory = aiosqlite.Row
+    yield
+    await app.state.db.close()
+
+
+def create_app(db_path: str, admin_token: str, data_dir: Path) -> FastAPI:
+    global _db_path, _admin_token, _data_dir
+    _db_path = db_path
+    _admin_token = admin_token
+    _data_dir = data_dir
+
+    app = FastAPI(lifespan=_lifespan, docs_url=None, redoc_url=None)
+
+    auth = Depends(require_token(admin_token))
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def _mask_cedula(credentials_enc: str | None) -> str:
+        """Muestra '***' — la cédula está cifrada y no se expone en el panel."""
+        if not credentials_enc:
+            return "—"
+        return "***"
+
+    def _parse_detalle(detalle_json: str | None) -> str:
+        if not detalle_json:
+            return ""
+        try:
+            return json.dumps(json.loads(detalle_json), ensure_ascii=False, indent=None)
+        except Exception:
+            return detalle_json or ""
+
+    # ── rutas ─────────────────────────────────────────────────────────────────
+
+    @app.get("/", include_in_schema=False)
+    async def root():
+        return RedirectResponse(url="/tenants")
+
+    @app.get("/tenants", response_class=HTMLResponse, dependencies=[auth])
+    async def lista_tenants(request: Request):
+        db: aiosqlite.Connection = request.app.state.db
+        async with db.execute("SELECT * FROM tenants ORDER BY created_at DESC") as cur:
+            rows = [dict(r) for r in await cur.fetchall()]
+        for r in rows:
+            r["cedula_masked"] = _mask_cedula(r.get("credentials_enc"))
+            r.pop("credentials_enc", None)
+        return templates.TemplateResponse("tenants.html", {"request": request, "tenants": rows})
+
+    @app.get("/tenants/{chat_id}", response_class=HTMLResponse, dependencies=[auth])
+    async def detalle_tenant(request: Request, chat_id: int):
+        db: aiosqlite.Connection = request.app.state.db
+        async with db.execute("SELECT * FROM tenants WHERE chat_id = ?", (chat_id,)) as cur:
+            row = await cur.fetchone()
+        if not row:
+            return HTMLResponse("<h1>Tenant no encontrado</h1>", status_code=404)
+        tenant: dict[str, Any] = dict(row)
+        tenant["cedula_masked"] = _mask_cedula(tenant.get("credentials_enc"))
+        tenant.pop("credentials_enc", None)
+
+        async with db.execute(
+            "SELECT * FROM audit_log WHERE chat_id = ? ORDER BY timestamp DESC LIMIT 20",
+            (chat_id,),
+        ) as cur:
+            logs = [dict(r) for r in await cur.fetchall()]
+        for entry in logs:
+            entry["detalle_str"] = _parse_detalle(entry.get("detalle"))
+
+        return templates.TemplateResponse(
+            "tenant.html", {"request": request, "tenant": tenant, "logs": logs}
+        )
+
+    @app.post("/tenants/{chat_id}/resetear", dependencies=[auth])
+    async def resetear_tenant(request: Request, chat_id: int):
+        db: aiosqlite.Connection = request.app.state.db
+        await db.execute("DELETE FROM tenants WHERE chat_id = ?", (chat_id,))
+        await db.execute("DELETE FROM audit_log WHERE chat_id = ?", (chat_id,))
+        await db.commit()
+        snapshot = _data_dir / f"snapshot_{chat_id}.json"
+        if snapshot.exists():
+            snapshot.unlink()
+        return RedirectResponse(url="/tenants", status_code=303)
+
+    @app.get("/audit", response_class=HTMLResponse, dependencies=[auth])
+    async def audit_log(request: Request, chat_id: str = "", page: int = 1):
+        db: aiosqlite.Connection = request.app.state.db
+        limit = 200
+        offset = (page - 1) * limit
+        if chat_id.strip():
+            try:
+                cid = int(chat_id.strip())
+                async with db.execute(
+                    "SELECT * FROM audit_log WHERE chat_id = ? ORDER BY timestamp DESC LIMIT ? OFFSET ?",
+                    (cid, limit, offset),
+                ) as cur:
+                    logs = [dict(r) for r in await cur.fetchall()]
+                async with db.execute(
+                    "SELECT COUNT(*) FROM audit_log WHERE chat_id = ?", (cid,)
+                ) as cur:
+                    total = (await cur.fetchone())[0]
+            except ValueError:
+                logs, total = [], 0
+        else:
+            async with db.execute(
+                "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT ? OFFSET ?",
+                (limit, offset),
+            ) as cur:
+                logs = [dict(r) for r in await cur.fetchall()]
+            async with db.execute("SELECT COUNT(*) FROM audit_log") as cur:
+                total = (await cur.fetchone())[0]
+
+        for entry in logs:
+            entry["detalle_str"] = _parse_detalle(entry.get("detalle"))
+
+        has_more = (offset + limit) < total
+        return templates.TemplateResponse(
+            "audit.html",
+            {
+                "request": request,
+                "logs": logs,
+                "chat_id_filter": chat_id,
+                "page": page,
+                "has_more": has_more,
+                "total": total,
+            },
+        )
+
+    return app

admin/auth.py

@@ -0,0 +1,22 @@
+"""
+admin/auth.py — Autenticación del panel de administración.
+
+Token estático via header X-Admin-Token.
+Si ADMIN_TOKEN no está configurado, el panel rechaza todos los requests.
+"""
+from __future__ import annotations
+
+import secrets
+
+from fastapi import HTTPException, Request
+
+
+def require_token(token_esperado: str):
+    """Devuelve una dependencia FastAPI que valida X-Admin-Token."""
+    async def _check(request: Request) -> None:
+        if not token_esperado:
+            raise HTTPException(status_code=403, detail="Panel no configurado: falta ADMIN_TOKEN")
+        token = request.headers.get("X-Admin-Token", "")
+        if not secrets.compare_digest(token, token_esperado):
+            raise HTTPException(status_code=403, detail="Token inválido")
+    return _check

admin/templates/audit.html

@@ -0,0 +1,50 @@
+{% extends "base.html" %}
+{% block title %} — Audit log{% endblock %}
+{% block content %}
+<h1>Audit log ({{ total }} registros)</h1>
+
+<form class="filter-bar" method="get" action="/audit">
+  <input type="text" name="chat_id" value="{{ chat_id_filter }}" placeholder="Filtrar por chat_id">
+  <button type="submit" class="btn btn-primary">Filtrar</button>
+  {% if chat_id_filter %}<a href="/audit" class="btn">Limpiar</a>{% endif %}
+</form>
+
+<table>
+  <thead>
+    <tr>
+      <th>Timestamp (UTC)</th>
+      <th>chat_id</th>
+      <th>Evento</th>
+      <th>Resultado</th>
+      <th>Detalle</th>
+    </tr>
+  </thead>
+  <tbody>
+  {% for entry in logs %}
+    <tr>
+      <td style="white-space:nowrap">{{ (entry.timestamp or "")[:19] }}</td>
+      <td>
+        {% if entry.chat_id %}
+          <a href="/tenants/{{ entry.chat_id }}">{{ entry.chat_id }}</a>
+        {% else %}—{% endif %}
+      </td>
+      <td><code>{{ entry.evento }}</code></td>
+      <td>{{ entry.resultado or "—" }}</td>
+      <td style="max-width:350px;word-break:break-all"><code>{{ entry.detalle_str }}</code></td>
+    </tr>
+  {% else %}
+    <tr><td colspan="5" style="text-align:center;color:#999">Sin registros</td></tr>
+  {% endfor %}
+  </tbody>
+</table>
+
+<div class="pagination">
+  {% if page > 1 %}
+    <a href="/audit?chat_id={{ chat_id_filter }}&page={{ page - 1 }}" class="btn">← Más recientes</a>
+  {% endif %}
+  <span>Página {{ page }}</span>
+  {% if has_more %}
+    <a href="/audit?chat_id={{ chat_id_filter }}&page={{ page + 1 }}" class="btn">Más antiguos →</a>
+  {% endif %}
+</div>
+{% endblock %}

admin/templates/base.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pedrito Admin{% block title %}{% endblock %}</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; margin: 0; background: #f5f5f5; color: #222; }
+    nav { background: #1a1a2e; color: #fff; padding: 0.75rem 1.5rem; display: flex; align-items: center; gap: 1.5rem; }
+    nav strong { font-size: 1.1rem; color: #e2e2ff; }
+    nav a { color: #adb5ff; text-decoration: none; font-size: 0.95rem; }
+    nav a:hover { color: #fff; }
+    main { max-width: 1100px; margin: 1.5rem auto; padding: 0 1rem; }
+    h1 { font-size: 1.4rem; margin-bottom: 1rem; }
+    table { width: 100%; border-collapse: collapse; background: #fff; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,.1); }
+    th { background: #e8e8f0; text-align: left; padding: 0.6rem 0.8rem; font-size: 0.85rem; color: #555; }
+    td { padding: 0.55rem 0.8rem; border-top: 1px solid #eee; font-size: 0.9rem; vertical-align: top; }
+    tr:hover td { background: #fafafa; }
+    .badge { display: inline-block; padding: 0.2rem 0.5rem; border-radius: 3px; font-size: 0.8rem; }
+    .badge-activo { background: #d4edda; color: #155724; }
+    .badge-pendiente { background: #fff3cd; color: #856404; }
+    .badge-suspendido { background: #f8d7da; color: #721c24; }
+    .btn { display: inline-block; padding: 0.35rem 0.75rem; border-radius: 4px; font-size: 0.85rem; text-decoration: none; border: none; cursor: pointer; }
+    .btn-primary { background: #4a6cf7; color: #fff; }
+    .btn-danger { background: #dc3545; color: #fff; }
+    .btn-sm { padding: 0.2rem 0.5rem; font-size: 0.8rem; }
+    form { display: inline; }
+    code { font-size: 0.8rem; background: #f0f0f0; padding: 1px 4px; border-radius: 3px; }
+    .detail-grid { display: grid; grid-template-columns: 180px 1fr; gap: 0.4rem 1rem; background: #fff; padding: 1rem 1.2rem; border-radius: 6px; box-shadow: 0 1px 3px rgba(0,0,0,.1); margin-bottom: 1.5rem; }
+    .detail-grid dt { font-weight: 600; font-size: 0.85rem; color: #666; }
+    .detail-grid dd { margin: 0; font-size: 0.9rem; }
+    .filter-bar { display: flex; gap: 0.5rem; margin-bottom: 1rem; align-items: center; }
+    .filter-bar input { padding: 0.4rem 0.7rem; border: 1px solid #ccc; border-radius: 4px; font-size: 0.9rem; }
+    .pagination { margin-top: 1rem; display: flex; gap: 0.5rem; align-items: center; font-size: 0.9rem; }
+  </style>
+</head>
+<body>
+<nav>
+  <strong>⚖️ Pedrito Admin</strong>
+  <a href="/tenants">Tenants</a>
+  <a href="/audit">Audit log</a>
+</nav>
+<main>
+  {% block content %}{% endblock %}
+</main>
+</body>
+</html>

admin/templates/tenant.html

@@ -0,0 +1,47 @@
+{% extends "base.html" %}
+{% block title %} — Tenant {{ tenant.chat_id }}{% endblock %}
+{% block content %}
+<h1>Tenant {{ tenant.chat_id }}</h1>
+
+<dl class="detail-grid">
+  <dt>chat_id</dt>     <dd>{{ tenant.chat_id }}</dd>
+  <dt>Nombre</dt>      <dd>{{ tenant.nombre_preferido or "—" }}</dd>
+  <dt>Estado</dt>      <dd><span class="badge badge-{{ tenant.estado or 'pendiente' }}">{{ tenant.estado or "pendiente" }}</span></dd>
+  <dt>Tono</dt>        <dd>{{ tenant.tono or "—" }}</dd>
+  <dt>Timezone</dt>    <dd>{{ tenant.timezone or "—" }}</dd>
+  <dt>Cédula</dt>      <dd><code>{{ tenant.cedula_masked }}</code></dd>
+  <dt>Creado</dt>      <dd>{{ (tenant.created_at or "")[:19] }}</dd>
+  <dt>Último activo</dt><dd>{{ (tenant.last_active or "")[:19] }}</dd>
+</dl>
+
+<form method="post" action="/tenants/{{ tenant.chat_id }}/resetear"
+      onsubmit="return confirm('¿Resetear tenant {{ tenant.chat_id }}? Esta acción borra el tenant y su snapshot.')">
+  <button type="submit" class="btn btn-danger">Resetear tenant</button>
+</form>
+
+<h2 style="margin-top:2rem;font-size:1.1rem">Últimas 20 entradas del audit log</h2>
+<table>
+  <thead>
+    <tr>
+      <th>Timestamp</th>
+      <th>Evento</th>
+      <th>Resultado</th>
+      <th>Detalle</th>
+    </tr>
+  </thead>
+  <tbody>
+  {% for entry in logs %}
+    <tr>
+      <td style="white-space:nowrap">{{ (entry.timestamp or "")[:19] }}</td>
+      <td><code>{{ entry.evento }}</code></td>
+      <td>{{ entry.resultado or "—" }}</td>
+      <td style="max-width:400px;word-break:break-all"><code>{{ entry.detalle_str }}</code></td>
+    </tr>
+  {% else %}
+    <tr><td colspan="4" style="text-align:center;color:#999">Sin registros</td></tr>
+  {% endfor %}
+  </tbody>
+</table>
+
+<p style="margin-top:1rem"><a href="/tenants">← Volver a tenants</a></p>
+{% endblock %}

admin/templates/tenants.html

@@ -0,0 +1,41 @@
+{% extends "base.html" %}
+{% block title %} — Tenants{% endblock %}
+{% block content %}
+<h1>Tenants ({{ tenants|length }})</h1>
+<table>
+  <thead>
+    <tr>
+      <th>chat_id</th>
+      <th>Nombre</th>
+      <th>Estado</th>
+      <th>Tono</th>
+      <th>Timezone</th>
+      <th>Cédula</th>
+      <th>Último activo</th>
+      <th>Acciones</th>
+    </tr>
+  </thead>
+  <tbody>
+  {% for t in tenants %}
+    <tr>
+      <td><a href="/tenants/{{ t.chat_id }}">{{ t.chat_id }}</a></td>
+      <td>{{ t.nombre_preferido or "—" }}</td>
+      <td><span class="badge badge-{{ t.estado or 'pendiente' }}">{{ t.estado or "pendiente" }}</span></td>
+      <td>{{ t.tono or "—" }}</td>
+      <td>{{ t.timezone or "—" }}</td>
+      <td><code>{{ t.cedula_masked }}</code></td>
+      <td>{{ (t.last_active or "")[:19] }}</td>
+      <td>
+        <a href="/tenants/{{ t.chat_id }}" class="btn btn-primary btn-sm">Ver</a>
+        <form method="post" action="/tenants/{{ t.chat_id }}/resetear"
+              onsubmit="return confirm('¿Resetear tenant {{ t.chat_id }}? Esta acción borra el tenant y su snapshot.')">
+          <button type="submit" class="btn btn-danger btn-sm">Resetear</button>
+        </form>
+      </td>
+    </tr>
+  {% else %}
+    <tr><td colspan="8" style="text-align:center;color:#999">Sin tenants registrados</td></tr>
+  {% endfor %}
+  </tbody>
+</table>
+{% endblock %}

config.py

@@ -57,6 +57,10 @@ class Settings(BaseSettings):
     # Código de invitación para registro (vacío = registro abierto)
     invite_code: str = ""
 
+    # Token para los endpoints HTTP protegidos (/health detallado, /health/history)
+    # Sin auth configurada los endpoints devuelven respuesta mínima (status only)
+    health_auth_token: str = ""
+
     # Webhook (vacío = long-polling)
     webhook_url: str = ""       # ej: https://bot.midominio.com
     webhook_secret: str = ""    # token secreto para X-Telegram-Bot-Api-Secret-Token
@@ -65,6 +69,10 @@ class Settings(BaseSettings):
     health_port: int = 8080
     health_alert_hours: int = 2  # alerta al admin si el poller no actualizó en N horas
 
+    # Panel de administración (solo 127.0.0.1, acceso via SSH tunnel)
+    admin_token: str = ""   # generar con: python -c "import secrets; print(secrets.token_hex(32))"
+    admin_port: int = 9090  # health_port usa 8080; admin usa puerto separado
+
     # Logging
     log_level: str = "INFO"
 

database.py

@@ -162,23 +162,20 @@ async def crear_invite_code(codigo: str) -> None:
 
 async def verificar_y_consumir_invite_code(codigo: str, chat_id: int) -> bool:
     """
-    Verifica que el código existe y no fue usado, lo marca como consumido y
+    Verifica y consume un código de invitación en una sola operación atómica.
-    retorna True. Retorna False si no existe o ya fue usado.
+
-    Operación atómica en una sola transacción SQLite.
+    Usa UPDATE con condición AND usado=0 en vez de SELECT+UPDATE para eliminar la
+    race condition TOCTOU: dos requests concurrentes con el mismo código solo
+    pueden actualizar la fila una vez — el segundo UPDATE afecta 0 rows y retorna False.
     """
     conn = _assert_conn()
-    async with conn.execute(
+    cur = await conn.execute(
-        "SELECT usado FROM invite_codes WHERE codigo = ?", (codigo,)
+        "UPDATE invite_codes SET usado = 1, usado_por = ?, usado_at = ? "
-    ) as cur:
+        "WHERE codigo = ? AND usado = 0",
-        row = await cur.fetchone()
-
-    if row is None or row["usado"]:
-        return False
-
-    await conn.execute(
-        "UPDATE invite_codes SET usado = 1, usado_por = ?, usado_at = ? WHERE codigo = ?",
         (chat_id, _now_iso(), codigo),
     )
     await conn.commit()
+    if cur.rowcount > 0:
         logger.info("invite_code_consumido", chat_id=chat_id)
         return True
+    return False

health.py

@@ -2,20 +2,34 @@
 health.py — Servidor HTTP para health check y webhook de Telegram.
 
 Rutas:
-    GET  /health          → JSON con estado actual del bot
+    GET  /health          → estado mínimo (público) | estado completo (con Bearer token)
-    GET  /health/history  → últimos N eventos del audit_log (?limit=50)
+    GET  /health/history  → últimos N eventos del audit_log — REQUIERE Bearer token
     POST /webhook         → recibe updates de Telegram (solo en modo webhook)
 
-Modo webhook opt-in: solo se activa si settings.webhook_url está configurado.
+Seguridad:
-En modo long-polling, /webhook no se registra.
+    - /health sin auth: solo devuelve {"status": "ok"|"degraded", "timestamp": "..."}
+      Sin conteos de tenants ni timing que revele inteligencia operacional.
+    - /health con auth: respuesta completa con métricas internas.
+    - /health/history siempre requiere auth.
+    - chat_ids en el historial se enmascaran como hashes opacos (no reversibles desde HTTP).
+    - Webhook valida X-Telegram-Bot-Api-Secret-Token con compare_digest.
+
+Configurar en .env:
+    HEALTH_AUTH_TOKEN=<token largo aleatorio>
+    (generar con: python -c "import secrets; print(secrets.token_hex(32))")
 """
 from __future__ import annotations
 
+import asyncio
+import hashlib
 import json
+import secrets
 from datetime import datetime, timedelta, timezone
+from zoneinfo import ZoneInfo
+
+_PY_TZ = ZoneInfo("America/Asuncion")
 from typing import TYPE_CHECKING
 
-import asyncio
 import aiohttp.web
 import structlog
 from telegram import Update
@@ -29,7 +43,7 @@ logger = structlog.get_logger(__name__)
 # ── Estado global del poller ──────────────────────────────────────────────────
 _last_poll_at: datetime | None = None
 _last_poll_tenant_count: int = 0
-_alert_sent: bool = False  # evitar spam de alertas consecutivas
+_alert_sent: bool = False
 
 
 def record_poll(tenant_count: int) -> None:
@@ -40,6 +54,17 @@ def record_poll(tenant_count: int) -> None:
     _alert_sent = False
 
 
+def _mask_chat_id(chat_id: int | None) -> str | None:
+    """
+    Convierte un chat_id en un identificador opaco no reversible.
+    Preserva la capacidad de correlacionar eventos del mismo usuario
+    sin exponer el Telegram ID real.
+    """
+    if chat_id is None:
+        return None
+    return "usr_" + hashlib.sha256(str(chat_id).encode()).hexdigest()[:8]
+
+
 # ── Servidor ──────────────────────────────────────────────────────────────────
 
 class HealthServer:
@@ -61,7 +86,11 @@ class HealthServer:
         await self._runner.setup()
         site = aiohttp.web.TCPSite(self._runner, "0.0.0.0", self._settings.health_port)
         await site.start()
-        logger.info("health_server_iniciado", port=self._settings.health_port)
+        logger.info(
+            "health_server_iniciado",
+            port=self._settings.health_port,
+            auth_configurada=bool(self._settings.health_auth_token),
+        )
 
         self._watcher_task = asyncio.create_task(self._watcher_loop())
 
@@ -76,37 +105,60 @@ class HealthServer:
             await self._runner.cleanup()
         logger.info("health_server_detenido")
 
+    # ── Auth ──────────────────────────────────────────────────────────────────
+
+    def _is_authenticated(self, request: aiohttp.web.Request) -> bool:
+        """
+        Valida el header Authorization: Bearer <token>.
+        Si health_auth_token no está configurado, siempre retorna False
+        (los endpoints protegidos devuelven respuesta mínima, no error).
+        """
+        if not self._settings.health_auth_token:
+            return False
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return False
+        provided = auth[7:]
+        # compare_digest previene timing attacks sobre el token de admin
+        return secrets.compare_digest(provided, self._settings.health_auth_token)
+
     # ── Handlers ─────────────────────────────────────────────────────────────
 
     async def _handle_health(self, request: aiohttp.web.Request) -> aiohttp.web.Response:
+        now = datetime.now(timezone.utc)
+        stale = False
+        if _last_poll_at:
+            stale = (now - _last_poll_at) > timedelta(hours=self._settings.health_alert_hours)
+
+        # Respuesta pública mínima — no revela conteos ni timing operacional
+        data: dict = {
+            "status": "degraded" if stale else "ok",
+            "timestamp": now.isoformat(),
+        }
+
+        # Respuesta extendida solo con auth válida
+        if self._is_authenticated(request):
             from database import get_conn
             conn = get_conn()
-
             async with conn.execute(
                 "SELECT COUNT(*) as n FROM tenants WHERE estado = 'activo'"
             ) as cur:
                 row = await cur.fetchone()
                 tenant_count = row["n"] if row else 0
 
-        now = datetime.now(timezone.utc)
             seconds_since_poll: int | None = None
-        stale = False
-
             if _last_poll_at:
-            delta = now - _last_poll_at
+                seconds_since_poll = int((now - _last_poll_at).total_seconds())
-            seconds_since_poll = int(delta.total_seconds())
-            stale = delta > timedelta(hours=self._settings.health_alert_hours)
 
-        data = {
+            data.update({
-            "status": "degraded" if stale else "ok",
-            "timestamp": now.isoformat(),
                 "tenants_activos": tenant_count,
                 "last_poll": _last_poll_at.isoformat() if _last_poll_at else None,
                 "last_poll_tenants": _last_poll_tenant_count,
                 "seconds_since_last_poll": seconds_since_poll,
                 "poll_interval_minutes": self._settings.poll_interval_minutes,
                 "webhook_mode": bool(self._settings.webhook_url),
-        }
+            })
+
         return aiohttp.web.Response(
             text=json.dumps(data, indent=2),
             content_type="application/json",
@@ -114,6 +166,20 @@ class HealthServer:
         )
 
     async def _handle_history(self, request: aiohttp.web.Request) -> aiohttp.web.Response:
+        # Este endpoint siempre requiere autenticación — contiene PII (chat_ids)
+        if not self._is_authenticated(request):
+            logger.warning(
+                "health_history_acceso_denegado",
+                ip=request.remote,
+                ua=request.headers.get("User-Agent", "")[:80],
+            )
+            return aiohttp.web.Response(
+                status=401,
+                text=json.dumps({"error": "Authentication required"}),
+                content_type="application/json",
+                headers={"WWW-Authenticate": 'Bearer realm="pedrito-health"'},
+            )
+
         from database import get_conn
         conn = get_conn()
 
@@ -129,16 +195,26 @@ class HealthServer:
         ) as cur:
             rows = await cur.fetchall()
 
+        # Enmascarar chat_ids: el consumidor puede correlacionar eventos del mismo usuario
+        # pero no puede determinar la identidad real sin acceso a la DB.
+        records = []
+        for r in rows:
+            row_dict = dict(r)
+            row_dict["chat_id"] = _mask_chat_id(row_dict.get("chat_id"))
+            records.append(row_dict)
+
         return aiohttp.web.Response(
-            text=json.dumps([dict(r) for r in rows], indent=2),
+            text=json.dumps(records, indent=2),
             content_type="application/json",
         )
 
     async def _handle_webhook(self, request: aiohttp.web.Request) -> aiohttp.web.Response:
-        secret = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
+        provided = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
-        if self._settings.webhook_secret and secret != self._settings.webhook_secret:
+        if self._settings.webhook_secret:
+            if not secrets.compare_digest(provided, self._settings.webhook_secret):
                 logger.warning("webhook_token_invalido", ip=request.remote)
-            return aiohttp.web.Response(status=403, text="Forbidden")
+                # Respuesta genérica — no revelar si es auth vs otro error
+                return aiohttp.web.Response(status=404, text="Not Found")
 
         try:
             body = await request.json()
@@ -155,9 +231,16 @@ class HealthServer:
         """Alerta al admin si el poller lleva más de health_alert_hours sin actualizar."""
         global _alert_sent
         while True:
-            await asyncio.sleep(300)  # revisar cada 5 minutos
+            await asyncio.sleep(300)
             if _last_poll_at is None or _alert_sent:
                 continue
+            ahora_py = datetime.now(_PY_TZ)
+            en_horario = (
+                ahora_py.weekday() < 5
+                and self._settings.poll_hora_inicio <= ahora_py.hour < self._settings.poll_hora_fin
+            )
+            if not en_horario:
+                continue
             delta = datetime.now(timezone.utc) - _last_poll_at
             if delta <= timedelta(hours=self._settings.health_alert_hours):
                 continue

main.py

@@ -7,8 +7,10 @@ Al arrancar: aplica migraciones y migra el tenant principal del .env si no exist
 from __future__ import annotations
 
 import asyncio
+import os
 import signal
 import sys
+import threading
 
 import structlog
 from telegram.ext import Application
@@ -71,8 +73,57 @@ async def _migrar_tenant_principal(settings) -> None:
     logger.info("tenant_principal_migrado", chat_id=chat_id)
 
 
+def _limpiar_env_sensibles() -> None:
+    """
+    Elimina variables sensibles del entorno del proceso después de cargar Settings.
+
+    Protege contra:
+    - cat /proc/<pid>/environ  (cualquier usuario con acceso al PID)
+    - herencia accidental de env vars por subprocesos
+    - stack traces que vuelquen os.environ
+
+    NO protege contra 'docker inspect' (que lee la config del contenedor, no el env live).
+    Para eso usar Docker secrets con Swarm mode.
+    """
+    _sensibles = (
+        "FERNET_KEY",
+        "TELEGRAM_BOT_TOKEN",
+        "PJ_USUARIO_ENC",
+        "PJ_PASSWORD_ENC",
+        "WEBHOOK_SECRET",
+        "HEALTH_AUTH_TOKEN",
+        "INVITE_CODE",
+        "ADMIN_TOKEN",
+    )
+    for var in _sensibles:
+        os.environ.pop(var, None)
+
+
+def _run_admin(settings) -> None:
+    """Arranca el panel de administración en su propio thread y event loop."""
+    import uvicorn
+    from admin.app import create_app
+
+    if not settings.admin_token:
+        logger.warning("admin_panel_sin_token_no_iniciado")
+        return
+
+    admin_app = create_app(
+        db_path=str(settings.db_path),
+        admin_token=settings.admin_token,
+        data_dir=settings.data_dir,
+    )
+    uvicorn.run(
+        admin_app,
+        host="127.0.0.1",
+        port=settings.admin_port,
+        log_level="warning",
+    )
+
+
 async def main() -> None:
     settings = get_settings()
+    _limpiar_env_sensibles()
 
     logger.info(
         "pedrito_hechakuaa_iniciando",
@@ -106,6 +157,10 @@ async def main() -> None:
         lambda chat_id: poller.revisar_ahora(chat_id=chat_id, es_manual=True)
     )
 
+    # Panel de administración (thread daemon — muere con el proceso principal)
+    admin_thread = threading.Thread(target=_run_admin, args=(settings,), daemon=True)
+    admin_thread.start()
+
     # Manejo de señales para shutdown limpio
     loop = asyncio.get_running_loop()
     health_server: HealthServer | None = None

onboarding.py

@@ -16,6 +16,9 @@ Estados:
 """
 from __future__ import annotations
 
+import asyncio
+import secrets
+import time
 from pathlib import Path
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
@@ -201,13 +204,28 @@ class OnboardingFlow:
 
     async def _paso_codigo(self, chat_id: int, codigo: str, update: Update) -> None:
         codigo = codigo.strip()
+        # Registrar tiempo de inicio para garantizar respuesta de duración constante.
+        # Objetivo: ocultar la diferencia de tiempo entre "código no existe en DB"
+        # (~0.001ms) y "código existe pero ya fue usado" (~3-5ms de DB lookup).
+        t0 = time.monotonic()
 
         # Primero: verificar contra la tabla de códigos de un solo uso (DB)
         valido = await verificar_y_consumir_invite_code(codigo, chat_id)
 
         # Fallback: código global del .env (ilimitado, para uso interno/pruebas)
+        # secrets.compare_digest previene timing attacks sobre el valor del .env
         if not valido and self._settings.invite_code:
-            valido = (codigo == self._settings.invite_code)
+            valido = secrets.compare_digest(
+                codigo.encode("utf-8"),
+                self._settings.invite_code.encode("utf-8"),
+            )
+
+        # Garantizar un tiempo mínimo de 800ms independientemente del resultado.
+        # Esto hace que medir tiempos de respuesta no revele información sobre los códigos.
+        elapsed = time.monotonic() - t0
+        _MIN_RESP_SECS = 0.8
+        if elapsed < _MIN_RESP_SECS:
+            await asyncio.sleep(_MIN_RESP_SECS - elapsed)
 
         if valido:
             await audit.log("onboarding_codigo_correcto", chat_id=chat_id)

pdf_extractor.py

@@ -0,0 +1,43 @@
+"""
+pdf_extractor.py — Extracción de texto de PDFs judiciales.
+
+Sin LLM. Sin interpretación. Solo texto crudo.
+Los PDFs nunca se guardan en disco — se procesan en memoria.
+"""
+from __future__ import annotations
+
+import io
+import re
+
+from pypdf import PdfReader
+
+MAX_CHARS = 600
+
+
+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, error de parseo).
+    """
+    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
+
+        texto = re.sub(r"\n{3,}", "\n\n", texto)
+
+        if len(texto) > MAX_CHARS:
+            texto = texto[:MAX_CHARS] + "..."
+
+        return texto
+    except Exception:
+        return None

poller.py

@@ -23,8 +23,10 @@ from csj_client import (
     CSJAuthError,
     CSJClient,
     CSJConnectionError,
+    CSJDocumentoNoDisponibleError,
     CSJPasswordTemporalError,
 )
+from pdf_extractor import extraer_extracto
 from database import delete_tenant, get_tenant, list_active_tenants, save_tenant
 from storage import Snapshot
 
@@ -66,6 +68,29 @@ class Poller:
             self._snapshots[chat_id] = Snapshot(path)
         return self._snapshots[chat_id]
 
+    async def _intentar_extracto(
+        self,
+        client: CSJClient,
+        notif: object,
+    ) -> str | None:
+        """Descarga el PDF de la notificación y extrae el texto. Degradación elegante: None si falla."""
+        from csj_client import NotificacionPendiente  # evita import circular en type hint
+        assert isinstance(notif, NotificacionPendiente)
+        if not (notif.cod_caso_judicial and notif.cod_actuacion_caso and notif.origen is not None):
+            return None
+        try:
+            pdf_bytes = await client.descargar_documento_principal(
+                cod_caso_judicial=notif.cod_caso_judicial,
+                origen_caso=notif.origen,
+                cod_actuacion_caso=notif.cod_actuacion_caso,
+                origen_actuacion=notif.origen,
+            )
+            return extraer_extracto(pdf_bytes)
+        except (CSJDocumentoNoDisponibleError, CSJConnectionError, CSJAuthError):
+            return None
+        except Exception:
+            return None
+
     # ──────────────────────────────────────────────────────────────────────────
     # Lógica de revisión por tenant
     # ──────────────────────────────────────────────────────────────────────────
@@ -117,7 +142,8 @@ class Poller:
 
                     if nuevas:
                         for notif in nuevas:
-                            await self._bot.enviar_notificacion(notif, tenant)  # type: ignore[attr-defined]
+                            extracto = await self._intentar_extracto(client, notif)
+                            await self._bot.enviar_notificacion(notif, tenant, extracto=extracto)  # type: ignore[attr-defined]
                             snapshot.marcar_vista(notif.cod_notificacion_origen)
                     elif es_manual:
                         await self._bot.enviar_sin_novedades(tenant, snapshot)  # type: ignore[attr-defined]
@@ -205,10 +231,13 @@ class Poller:
             hora_fin=self._settings.poll_hora_fin,
         )
 
+        if self._en_horario_habitual():
             logger.info("revision_inicial_al_arrancar")
             count = await self.revisar_ahora()
             if self._on_poll_done:
                 self._on_poll_done(count)
+        else:
+            logger.info("revision_inicial_skipped_fuera_de_horario")
 
         while self._running:
             try:

pyproject.toml

@@ -15,6 +15,10 @@ dependencies = [
     "python-dotenv>=1.0",
     "aiosqlite>=0.20",
     "aiohttp>=3.9",
+    "pypdf>=4.0",
+    "fastapi>=0.115",
+    "uvicorn>=0.32",
+    "jinja2>=3.1",
 ]
 
 [dependency-groups]

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
@@ -38,6 +39,7 @@ from csj_client import (
 )
 from database import get_tenant
 from onboarding import OnboardingFlow
+from pdf_extractor import extraer_extracto
 from storage import Snapshot
 
 if TYPE_CHECKING:
@@ -47,6 +49,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
 # ──────────────────────────────────────────────────────────────────────────────
@@ -258,8 +295,10 @@ class PedritoBot:
         return None
 
     async def _rechazar_no_registrado(self, update: Update) -> None:
+        # Mensaje mínimo: no revela qué hace el bot ni su arquitectura interna.
+        # Solo dice que hay un comando /start, lo cual es estándar en todos los bots de Telegram.
         await update.effective_message.reply_text(  # type: ignore[union-attr]
-            "Primero tenés que registrarte\\. Escribí /start\\.",
+            "Para usar este bot escribí /start\\.",
             parse_mode=ParseMode.MARKDOWN_V2,
         )
 
@@ -609,6 +648,13 @@ class PedritoBot:
             filename=filename,
             caption=caption,
         )
+        extracto = extraer_extracto(pdf_bytes)
+        if extracto:
+            await update.effective_message.reply_text(  # type: ignore[union-attr]
+                f"📄 *Contenido del documento:*\n{_escape_md(extracto)}\n\n"
+                "⚠️ _Verificá el original antes de actuar\\._",
+                parse_mode=ParseMode.MARKDOWN_V2,
+            )
         await audit.log("bot_pdf_enviado", chat_id=chat_id, detalle={"cod_caso": caso.cod_caso_judicial, "cod_actuacion": actuacion.cod_actuacion_caso}, tenant=tenant)
 
     # ──────────────────────────────────────────────────────────────────────────
@@ -624,6 +670,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]
@@ -633,11 +718,15 @@ 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"):
-            texto = _escape_md(_texto_tono("texto_no_reconocido", tenant))
+            # Usuarios sin registro: silencio total.
-        else:
+            return
-            texto = _escape_md("Solo respondo comandos específicos. Escribí /ayuda para ver la lista.")
 
+        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]
 
     # ──────────────────────────────────────────────────────────────────────────
@@ -701,13 +790,25 @@ class PedritoBot:
             document=pdf_bytes,
             filename=f"Actuacion_{cod_caso}_{cod_actuacion}.pdf",
         )
+        extracto = extraer_extracto(pdf_bytes)
+        if extracto:
+            await query.message.reply_text(  # type: ignore[union-attr]
+                f"📄 *Contenido del documento:*\n{_escape_md(extracto)}\n\n"
+                "⚠️ _Verificá el original antes de actuar\\._",
+                parse_mode=ParseMode.MARKDOWN_V2,
+            )
         await audit.log("bot_pdf_enviado", chat_id=chat_id, detalle={"cod_caso": int(cod_caso), "cod_actuacion": int(cod_actuacion)}, tenant=await get_tenant(chat_id))
 
     # ──────────────────────────────────────────────────────────────────────────
     # Mensajes proactivos (llamados desde el poller)
     # ──────────────────────────────────────────────────────────────────────────
 
-    async def enviar_notificacion(self, notif: NotificacionPendiente, tenant: dict) -> None:
+    async def enviar_notificacion(
+        self,
+        notif: NotificacionPendiente,
+        tenant: dict,
+        extracto: str | None = None,
+    ) -> None:
         """Envía una notificación nueva al tenant específico, con su tono."""
         assert self._app is not None
         chat_id: int = tenant["chat_id"]
@@ -723,13 +824,22 @@ class PedritoBot:
             nombre=nombre, exp=notif.expediente_str
         )
 
+        extracto_bloque = ""
+        if extracto:
+            extracto_bloque = (
+                f"\n\n📄 *Extracto del documento:*\n"
+                f"{_escape_md(extracto)}\n\n"
+                f"⚠️ _Este es el texto crudo del documento\\. Verificá el original antes de actuar\\._"
+            )
+
         texto = (
             f"{_escape_md(intro)}\n\n"
             f"📋 *Nueva notificación judicial*\n\n"
             f"{_escape_md(caratula)}\n"
             f"Exp\\. {_escape_md(notif.expediente_str)} \\— {_escape_md(juzgado)}\n\n"
             f"Tipo: {_escape_md(tipo)}\n"
-            f"Fecha: {_escape_md(fecha)}\n\n"
+            f"Fecha: {_escape_md(fecha)}"
+            f"{extracto_bloque}\n\n"
             f"⚠️ Para acusar esta notificación entrá directamente en el sistema del PJ\\."
         )
 

uv.lock

@@ -132,6 +132,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/00/b7/e3bf5133d697a08128598c8d0abc5e16377b51465a33756de24fa7dee953/aiosqlite-0.22.1-py3-none-any.whl", hash = "sha256:21c002eb13823fad740196c5a2e9d8e62f6243bd9e7e4a1f87fb5e44ecb4fceb", size = 17405, upload-time = "2025-12-23T19:25:42.139Z" },
 ]
 
+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
+]
+
 [[package]]
 name = "annotated-types"
 version = "0.7.0"
@@ -290,6 +299,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
 ]
 
+[[package]]
+name = "click"
+version = "8.4.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9b/98/518d8e5081007684232226f475082b30087d0f585e8457db087298259f49/click-8.4.1.tar.gz", hash = "sha256:918b5633eddf6b41c32d4f454bf0de810065c74e3f7dbf8ee5452f8be88d3e96", size = 353007, upload-time = "2026-05-22T04:08:37.769Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/0d/67e5b4109ea4a837e80daa87c2c696711955e40449a97e8926672534def2/click-8.4.1-py3-none-any.whl", hash = "sha256:482be17c6991b8c19c5429a1e995d9b0efdbb63172824c41f99965dc0ade8ec2", size = 116639, upload-time = "2026-05-22T04:08:35.26Z" },
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -352,6 +373,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9d/9a/0fea98a70cf1749d41d738836f6349d97945f7c89433a259a6c2642eefeb/cryptography-48.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:16cd65b9330583e4619939b3a3843eec1e6e789744bb01e7c7e2e62e33c239c8", size = 3792100, upload-time = "2026-05-04T22:59:14.884Z" },
 ]
 
+[[package]]
+name = "fastapi"
+version = "0.136.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/81/2d/ff8d91d7b564d464629a0fd50a4489c97fcb836ac230bf3a7269232a9b1f/fastapi-0.136.3.tar.gz", hash = "sha256:e487fae93ad408e6f47641ee4dfe389864fd7bec92e547ea8498fc13f43e83ab", size = 396410, upload-time = "2026-05-23T18:53:15.192Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/82/45359b62a067409bd929ae8a56b8ed13e5a8c8a61194b3c236920999ab83/fastapi-0.136.3-py3-none-any.whl", hash = "sha256:3d2a69bdf04b7e9f3afa292c3bc7a98816bbfafa10bc9b45f3f3700d2f761620", size = 117481, upload-time = "2026-05-23T18:53:16.924Z" },
+]
+
 [[package]]
 name = "frozenlist"
 version = "1.8.0"
@@ -496,6 +533,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
 ]
 
+[[package]]
+name = "jinja2"
+version = "3.1.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markupsafe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/df/bf/f7da0350254c0ed7c72f3e33cef02e048281fec7ecec5f032d4aac52226b/jinja2-3.1.6.tar.gz", hash = "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", size = 245115, upload-time = "2025-03-05T20:05:02.478Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" },
+]
+
 [[package]]
 name = "librt"
 version = "0.11.0"
@@ -556,6 +605,69 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ce/62/b40b382fa0c66fee1478073eb8db352a4a6beda4a1adccf1df911d8c289c/librt-0.11.0-cp314-cp314t-win_arm64.whl", hash = "sha256:dee008f20b542e3cd162ba338a7f9ec0f6d23d395f66fe8aeeec3c9d067ea253", size = 102572, upload-time = "2026-05-10T18:17:06.809Z" },
 ]
 
+[[package]]
+name = "markupsafe"
+version = "3.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5a/72/147da192e38635ada20e0a2e1a51cf8823d2119ce8883f7053879c2199b5/markupsafe-3.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e", size = 11615, upload-time = "2025-09-27T18:36:30.854Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/81/7e4e08678a1f98521201c3079f77db69fb552acd56067661f8c2f534a718/markupsafe-3.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce", size = 12020, upload-time = "2025-09-27T18:36:31.971Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/2c/799f4742efc39633a1b54a92eec4082e4f815314869865d876824c257c1e/markupsafe-3.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d", size = 24332, upload-time = "2025-09-27T18:36:32.813Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/2e/8d0c2ab90a8c1d9a24f0399058ab8519a3279d1bd4289511d74e909f060e/markupsafe-3.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d", size = 22947, upload-time = "2025-09-27T18:36:33.86Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/54/887f3092a85238093a0b2154bd629c89444f395618842e8b0c41783898ea/markupsafe-3.0.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a", size = 21962, upload-time = "2025-09-27T18:36:35.099Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/2f/336b8c7b6f4a4d95e91119dc8521402461b74a485558d8f238a68312f11c/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b", size = 23760, upload-time = "2025-09-27T18:36:36.001Z" },
+    { url = "https://files.pythonhosted.org/packages/32/43/67935f2b7e4982ffb50a4d169b724d74b62a3964bc1a9a527f5ac4f1ee2b/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f", size = 21529, upload-time = "2025-09-27T18:36:36.906Z" },
+    { url = "https://files.pythonhosted.org/packages/89/e0/4486f11e51bbba8b0c041098859e869e304d1c261e59244baa3d295d47b7/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b", size = 23015, upload-time = "2025-09-27T18:36:37.868Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/e1/78ee7a023dac597a5825441ebd17170785a9dab23de95d2c7508ade94e0e/markupsafe-3.0.3-cp312-cp312-win32.whl", hash = "sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d", size = 14540, upload-time = "2025-09-27T18:36:38.761Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/5b/bec5aa9bbbb2c946ca2733ef9c4ca91c91b6a24580193e891b5f7dbe8e1e/markupsafe-3.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c", size = 15105, upload-time = "2025-09-27T18:36:39.701Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/f1/216fc1bbfd74011693a4fd837e7026152e89c4bcf3e77b6692fba9923123/markupsafe-3.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f", size = 13906, upload-time = "2025-09-27T18:36:40.689Z" },
+    { url = "https://files.pythonhosted.org/packages/38/2f/907b9c7bbba283e68f20259574b13d005c121a0fa4c175f9bed27c4597ff/markupsafe-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", size = 11622, upload-time = "2025-09-27T18:36:41.777Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/d9/5f7756922cdd676869eca1c4e3c0cd0df60ed30199ffd775e319089cb3ed/markupsafe-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", size = 12029, upload-time = "2025-09-27T18:36:43.257Z" },
+    { url = "https://files.pythonhosted.org/packages/00/07/575a68c754943058c78f30db02ee03a64b3c638586fba6a6dd56830b30a3/markupsafe-3.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", size = 24374, upload-time = "2025-09-27T18:36:44.508Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/21/9b05698b46f218fc0e118e1f8168395c65c8a2c750ae2bab54fc4bd4e0e8/markupsafe-3.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", size = 22980, upload-time = "2025-09-27T18:36:45.385Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/71/544260864f893f18b6827315b988c146b559391e6e7e8f7252839b1b846a/markupsafe-3.0.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", size = 21990, upload-time = "2025-09-27T18:36:46.916Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/28/b50fc2f74d1ad761af2f5dcce7492648b983d00a65b8c0e0cb457c82ebbe/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", size = 23784, upload-time = "2025-09-27T18:36:47.884Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/76/104b2aa106a208da8b17a2fb72e033a5a9d7073c68f7e508b94916ed47a9/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", size = 21588, upload-time = "2025-09-27T18:36:48.82Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/99/16a5eb2d140087ebd97180d95249b00a03aa87e29cc224056274f2e45fd6/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", size = 23041, upload-time = "2025-09-27T18:36:49.797Z" },
+    { url = "https://files.pythonhosted.org/packages/19/bc/e7140ed90c5d61d77cea142eed9f9c303f4c4806f60a1044c13e3f1471d0/markupsafe-3.0.3-cp313-cp313-win32.whl", hash = "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", size = 14543, upload-time = "2025-09-27T18:36:51.584Z" },
+    { url = "https://files.pythonhosted.org/packages/05/73/c4abe620b841b6b791f2edc248f556900667a5a1cf023a6646967ae98335/markupsafe-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", size = 15113, upload-time = "2025-09-27T18:36:52.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/3a/fa34a0f7cfef23cf9500d68cb7c32dd64ffd58a12b09225fb03dd37d5b80/markupsafe-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", size = 13911, upload-time = "2025-09-27T18:36:53.513Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/d7/e05cd7efe43a88a17a37b3ae96e79a19e846f3f456fe79c57ca61356ef01/markupsafe-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", size = 11658, upload-time = "2025-09-27T18:36:54.819Z" },
+    { url = "https://files.pythonhosted.org/packages/99/9e/e412117548182ce2148bdeacdda3bb494260c0b0184360fe0d56389b523b/markupsafe-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", size = 12066, upload-time = "2025-09-27T18:36:55.714Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/e6/fa0ffcda717ef64a5108eaa7b4f5ed28d56122c9a6d70ab8b72f9f715c80/markupsafe-3.0.3-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", size = 25639, upload-time = "2025-09-27T18:36:56.908Z" },
+    { url = "https://files.pythonhosted.org/packages/96/ec/2102e881fe9d25fc16cb4b25d5f5cde50970967ffa5dddafdb771237062d/markupsafe-3.0.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", size = 23569, upload-time = "2025-09-27T18:36:57.913Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/30/6f2fce1f1f205fc9323255b216ca8a235b15860c34b6798f810f05828e32/markupsafe-3.0.3-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", size = 23284, upload-time = "2025-09-27T18:36:58.833Z" },
+    { url = "https://files.pythonhosted.org/packages/58/47/4a0ccea4ab9f5dcb6f79c0236d954acb382202721e704223a8aafa38b5c8/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", size = 24801, upload-time = "2025-09-27T18:36:59.739Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/70/3780e9b72180b6fecb83a4814d84c3bf4b4ae4bf0b19c27196104149734c/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", size = 22769, upload-time = "2025-09-27T18:37:00.719Z" },
+    { url = "https://files.pythonhosted.org/packages/98/c5/c03c7f4125180fc215220c035beac6b9cb684bc7a067c84fc69414d315f5/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", size = 23642, upload-time = "2025-09-27T18:37:01.673Z" },
+    { url = "https://files.pythonhosted.org/packages/80/d6/2d1b89f6ca4bff1036499b1e29a1d02d282259f3681540e16563f27ebc23/markupsafe-3.0.3-cp313-cp313t-win32.whl", hash = "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", size = 14612, upload-time = "2025-09-27T18:37:02.639Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/98/e48a4bfba0a0ffcf9925fe2d69240bfaa19c6f7507b8cd09c70684a53c1e/markupsafe-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", size = 15200, upload-time = "2025-09-27T18:37:03.582Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/72/e3cc540f351f316e9ed0f092757459afbc595824ca724cbc5a5d4263713f/markupsafe-3.0.3-cp313-cp313t-win_arm64.whl", hash = "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", size = 13973, upload-time = "2025-09-27T18:37:04.929Z" },
+    { url = "https://files.pythonhosted.org/packages/33/8a/8e42d4838cd89b7dde187011e97fe6c3af66d8c044997d2183fbd6d31352/markupsafe-3.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", size = 11619, upload-time = "2025-09-27T18:37:06.342Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/64/7660f8a4a8e53c924d0fa05dc3a55c9cee10bbd82b11c5afb27d44b096ce/markupsafe-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", size = 12029, upload-time = "2025-09-27T18:37:07.213Z" },
+    { url = "https://files.pythonhosted.org/packages/da/ef/e648bfd021127bef5fa12e1720ffed0c6cbb8310c8d9bea7266337ff06de/markupsafe-3.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", size = 24408, upload-time = "2025-09-27T18:37:09.572Z" },
+    { url = "https://files.pythonhosted.org/packages/41/3c/a36c2450754618e62008bf7435ccb0f88053e07592e6028a34776213d877/markupsafe-3.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97", size = 23005, upload-time = "2025-09-27T18:37:10.58Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/20/b7fdf89a8456b099837cd1dc21974632a02a999ec9bf7ca3e490aacd98e7/markupsafe-3.0.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d", size = 22048, upload-time = "2025-09-27T18:37:11.547Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/a7/591f592afdc734f47db08a75793a55d7fbcc6902a723ae4cfbab61010cc5/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda", size = 23821, upload-time = "2025-09-27T18:37:12.48Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/33/45b24e4f44195b26521bc6f1a82197118f74df348556594bd2262bda1038/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf", size = 21606, upload-time = "2025-09-27T18:37:13.485Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/0e/53dfaca23a69fbfbbf17a4b64072090e70717344c52eaaaa9c5ddff1e5f0/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe", size = 23043, upload-time = "2025-09-27T18:37:14.408Z" },
+    { url = "https://files.pythonhosted.org/packages/46/11/f333a06fc16236d5238bfe74daccbca41459dcd8d1fa952e8fbd5dccfb70/markupsafe-3.0.3-cp314-cp314-win32.whl", hash = "sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9", size = 14747, upload-time = "2025-09-27T18:37:15.36Z" },
+    { url = "https://files.pythonhosted.org/packages/28/52/182836104b33b444e400b14f797212f720cbc9ed6ba34c800639d154e821/markupsafe-3.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581", size = 15341, upload-time = "2025-09-27T18:37:16.496Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/18/acf23e91bd94fd7b3031558b1f013adfa21a8e407a3fdb32745538730382/markupsafe-3.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4", size = 14073, upload-time = "2025-09-27T18:37:17.476Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/f0/57689aa4076e1b43b15fdfa646b04653969d50cf30c32a102762be2485da/markupsafe-3.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab", size = 11661, upload-time = "2025-09-27T18:37:18.453Z" },
+    { url = "https://files.pythonhosted.org/packages/89/c3/2e67a7ca217c6912985ec766c6393b636fb0c2344443ff9d91404dc4c79f/markupsafe-3.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175", size = 12069, upload-time = "2025-09-27T18:37:19.332Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/00/be561dce4e6ca66b15276e184ce4b8aec61fe83662cce2f7d72bd3249d28/markupsafe-3.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634", size = 25670, upload-time = "2025-09-27T18:37:20.245Z" },
+    { url = "https://files.pythonhosted.org/packages/50/09/c419f6f5a92e5fadde27efd190eca90f05e1261b10dbd8cbcb39cd8ea1dc/markupsafe-3.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50", size = 23598, upload-time = "2025-09-27T18:37:21.177Z" },
+    { url = "https://files.pythonhosted.org/packages/22/44/a0681611106e0b2921b3033fc19bc53323e0b50bc70cffdd19f7d679bb66/markupsafe-3.0.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e", size = 23261, upload-time = "2025-09-27T18:37:22.167Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/57/1b0b3f100259dc9fffe780cfb60d4be71375510e435efec3d116b6436d43/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5", size = 24835, upload-time = "2025-09-27T18:37:23.296Z" },
+    { url = "https://files.pythonhosted.org/packages/26/6a/4bf6d0c97c4920f1597cc14dd720705eca0bf7c787aebc6bb4d1bead5388/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523", size = 22733, upload-time = "2025-09-27T18:37:24.237Z" },
+    { url = "https://files.pythonhosted.org/packages/14/c7/ca723101509b518797fedc2fdf79ba57f886b4aca8a7d31857ba3ee8281f/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc", size = 23672, upload-time = "2025-09-27T18:37:25.271Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/df/5bd7a48c256faecd1d36edc13133e51397e41b73bb77e1a69deab746ebac/markupsafe-3.0.3-cp314-cp314t-win32.whl", hash = "sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d", size = 14819, upload-time = "2025-09-27T18:37:26.285Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/8a/0402ba61a2f16038b48b39bccca271134be00c5c9f0f623208399333c448/markupsafe-3.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9", size = 15426, upload-time = "2025-09-27T18:37:27.316Z" },
+    { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" },
+]
+
 [[package]]
 name = "multidict"
 version = "6.7.1"
@@ -735,12 +847,16 @@ dependencies = [
     { name = "aiosqlite" },
     { name = "apscheduler" },
     { name = "cryptography" },
+    { name = "fastapi" },
     { name = "httpx" },
+    { name = "jinja2" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
+    { name = "pypdf" },
     { name = "python-dotenv" },
     { name = "python-telegram-bot", extra = ["ext"] },
     { name = "structlog" },
+    { name = "uvicorn" },
 ]
 
 [package.dev-dependencies]
@@ -758,12 +874,16 @@ requires-dist = [
     { name = "aiosqlite", specifier = ">=0.20" },
     { name = "apscheduler", specifier = ">=3.10" },
     { name = "cryptography", specifier = ">=44.0" },
+    { name = "fastapi", specifier = ">=0.115" },
     { name = "httpx", specifier = ">=0.28" },
+    { name = "jinja2", specifier = ">=3.1" },
     { name = "pydantic", specifier = ">=2.9" },
     { name = "pydantic-settings", specifier = ">=2.6" },
+    { name = "pypdf", specifier = ">=4.0" },
     { name = "python-dotenv", specifier = ">=1.0" },
     { name = "python-telegram-bot", extras = ["ext"], specifier = ">=21.9" },
     { name = "structlog", specifier = ">=24.4" },
+    { name = "uvicorn", specifier = ">=0.32" },
 ]
 
 [package.metadata.requires-dev]
@@ -1000,6 +1120,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
 ]
 
+[[package]]
+name = "pypdf"
+version = "6.12.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0a/6d/20879428577c1e57ecd41b69dc86beabf43db9287ad2e702207f8b48c751/pypdf-6.12.2.tar.gz", hash = "sha256:111669eb6680c04495ae0c113a1476e3bf93a95761d23c7406b591c80a6490b1", size = 6468184, upload-time = "2026-05-26T13:31:26.911Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/44/fee070a16639d9869bb6a7e0f3a1b3946da1d66f32b9260b4d19cb90d7b2/pypdf-6.12.2-py3-none-any.whl", hash = "sha256:67b2699357a1f3f4c945940ea80826349ee507c9e2577724a14b4941982c104d", size = 343865, upload-time = "2026-05-26T13:31:25.068Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "9.0.3"
@@ -1097,6 +1226,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9b/36/9c015cd052fca743dae8cb2aeb16b551444787467db42ceab0fc968865af/ruff-0.15.13-py3-none-win_arm64.whl", hash = "sha256:2471da9bd1068c8c064b5fd9c0c4b6dddffd6369cb1cd68b29993b1709ff1b21", size = 11179336, upload-time = "2026-05-14T13:44:33.026Z" },
 ]
 
+[[package]]
+name = "starlette"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/bf/616a066c2760f6c2b1ae3437cc28149734d069fbb46511712beae118a68c/starlette-1.2.0.tar.gz", hash = "sha256:3c5a6b23fff42492914e93890bb80cbfea72dbf37de268eec06185d62a4ca553", size = 2668923, upload-time = "2026-05-28T11:42:50.568Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/85/492183764d5d01d4514be3730fdb8e228a80605783099551c51627578b5d/starlette-1.2.0-py3-none-any.whl", hash = "sha256:36e0c76ac59157e75dc4b3bdeafba97fb04eaf1878045f15dbef666a6f092ed7", size = 73213, upload-time = "2026-05-28T11:42:48.801Z" },
+]
+
 [[package]]
 name = "structlog"
 version = "25.5.0"
@@ -1165,6 +1307,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/14/e2a54fabd4f08cd7af1c07030603c3356b74da07f7cc056e600436edfa17/tzlocal-5.3.1-py3-none-any.whl", hash = "sha256:eb1a66c3ef5847adf7a834f1be0800581b683b5608e74f86ecbcef8ab91bb85d", size = 18026, upload-time = "2025-03-05T21:17:39.857Z" },
 ]
 
+[[package]]
+name = "uvicorn"
+version = "0.48.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e6/bf/f6544ba992ddb9a6077343a576f9844f7f8f06ab819aefd00206e9255f18/uvicorn-0.48.0.tar.gz", hash = "sha256:a5504207195d08c2511bf9125ede5ac4a4b71725d519e758d01dcf0bc2d31c37", size = 91074, upload-time = "2026-05-24T12:08:41.925Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/be/72532be3da7acc5fdfbccdb95215cd04f995a0886532a5b423f929cda4cc/uvicorn-0.48.0-py3-none-any.whl", hash = "sha256:48097851328b87ec36117d3d575234519eb58c2b22d79666e9bbc6c49a761dad", size = 71410, upload-time = "2026-05-24T12:08:40.258Z" },
+]
+
 [[package]]
 name = "yarl"
 version = "1.24.2"

vault.py

@@ -1,55 +1,182 @@
 """
 vault.py — Cifrado de credenciales por tenant.
 
-Cada tenant tiene sus credenciales cifradas con una clave derivada de:
+## Arquitectura v3: Envelope Encryption con PBKDF2 + DEK por tenant
-  FERNET_KEY (global, del .env) + str(chat_id) (único por tenant)
 
-Esto asegura que las credenciales de un tenant no se pueden descifrar
+Cada credencial se cifra en dos capas independientes:
-con solo la FERNET_KEY — hace falta también el chat_id.
+
+  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)
+    Cifra credenciales con envelope encryption v3.
-    f = Fernet(key)
+    Retorna JSON compacto listo para guardar en DB.
-    payload = json.dumps({"usuario": usuario, "password": password}).encode()
+    """
-    encrypted = f.encrypt(payload).decode()
+    # Capa 1: generar salt (para PBKDF2) y DEK aleatoria
-    logger.info("credenciales_cifradas", chat_id=chat_id)
+    salt = os.urandom(_SALT_BYTES)
-    return encrypted
+    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).
+    Descifra credenciales. Soporta v1 (legacy) y v3 (actual).
-    Levanta ValueError si no se puede descifrar (clave incorrecta o datos corruptos).
+    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