Saltar a contenido

0007. Seguridad: hashing Argon2id y firma/verificación de JWT

Estado: Aceptado Fecha: 2026-09-28 Autor: Duval Alcivar Módulo(s) afectado(s): app/core/security.py, app/core/config.py, tests/

Contexto

El login (ADR 0011 de docs-site) necesita su fundación técnica: hashear las contraseñas y firmar/verificar los JWT. Sin app/core/security.py no se puede empezar el flujo de auth; es el primer eslabón de la cadena.

Decisión

  • app/core/security.py con las primitivas:
  • PasswordHasher Argon2id como singleton (64 MiB, t=3, p=1, hash_len=32, salt_len=16 — ADR 0020), con hash_password, verify_password y necesita_rehash (patrón rehash on login).
  • Firma/verificación JWT RS256 con iss/aud fijos de plataforma (com.godexerp.identidad / com.godexerp.plataforma), iat/exp/jti fijados por la función, y kid en el header.
  • obtener_jwks() para GET /.well-known/jwks.json.
  • Refresh token opaco (64 bytes en hex) y su SHA-256, que es lo único que se persiste (ADR 0011).
  • Config nueva en app/core/config.py: clave privada inline (JWT_PRIVATE_KEY) o por ruta (JWT_PRIVATE_KEY_PATH), pública opcional (se deriva), JWT_KID, JWT_ISSUER/JWT_AUDIENCE con los valores fijos, TTLs (access 15 min, refresh 30 días, pre_token 5 min), clock skew 30 s y los parámetros de Argon2 sobre-escribibles (ARGON2_*).
  • Claves opcionales en la configuración: sin ellas el servicio arranca (catálogos, migraciones) y las funciones de seguridad fallan con un error claro al usarse. Se pueden volver obligatorias cuando auth esté completo.

Alternativas descartadas

  • PyJWT — el proyecto ya declara python-jose[cryptography] en pyproject.toml (con override de mypy); no se suma otra dependencia.
  • HS256 (secreto compartido) — descartado por el ADR 0006 transversal: cualquier servicio comprometido falsifica tokens.
  • Clave privada hardcodeada en el código — nunca; vive en .env/secretos del despliegue (ADR 0011).

Consecuencias

  • El login costará ~200-400 ms por la verificación Argon2id 64 MiB, una vez por login (nunca por request): por eso el hasher es singleton.
  • El JWKS se expone en /.well-known/jwks.json (endpoint en una etapa posterior con la capa de API).
  • Todos los TTLs y parámetros son ajustables por entorno sin tocar código.
  • Los tokens viejos migran solos con rehash on login al subir el coste de hashing.