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.pycon las primitivas:PasswordHasherArgon2id como singleton (64 MiB,t=3,p=1,hash_len=32,salt_len=16— ADR 0020), conhash_password,verify_passwordynecesita_rehash(patrón rehash on login).- Firma/verificación JWT RS256 con
iss/audfijos de plataforma (com.godexerp.identidad/com.godexerp.plataforma),iat/exp/jtifijados por la función, ykiden el header. obtener_jwks()paraGET /.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_AUDIENCEcon 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]enpyproject.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.