0031. Protección de las rutas CRUD con JWT¶
Estado: Aceptado Fecha: 2026-09-30 Autor: Duval Alcivar Módulo(s) afectado(s): app/api/deps.py, app/main.py, tests/unit/test_deps.py, tests/unit/*/test_router.py, docs/adr/
Contexto¶
Este servicio es el único de la plataforma que firma los JWT (ADR 0030), pero las rutas CRUD siguen abiertas: cualquiera con acceso a la red puede leer o modificar catálogos, empresas, usuarios y permisos sin presentar ninguna credencial. El login ya emite access tokens de 15 minutos; falta la otra mitad del candado: exigir ese token en las rutas que administran datos.
El candado de dos piezas¶
Un candado de bicicleta tiene dos piezas: la cerradura (el login, ADR 0030, que emite el carnet firmado) y el aro (la verificación en cada ruta, que revisa el carnet antes de dejar pasar). El ADR 0030 construyó la cerradura; este ADR construye el aro con una dependencia de FastAPI.
Una dependencia es un chequeo que corre antes que el endpoint: si falla, la
respuesta se corta ahí y el endpoint ni se ejecuta. get_current_user es ese
chequeo: lee el header Authorization: Bearer <token>, verifica la firma y los
claims, y si algo no cuadra responde 401 sin tocar la base de datos.
Qué exige el carnet¶
El access token (ADR 0030) trae estos claims de identidad; si alguno falta, el carnet no es de trabajo, es de otra cosa (por ejemplo un pre-token):
| Claim | Qué se exige |
|---|---|
sub |
Parseable como UUID (id del usuario) |
empresa_id |
Entero (la empresa en la que trabaja) |
username |
Texto no vacío |
tipo_usuario |
Texto (código de rol: usuario, root, externo) |
permisos |
Opcional; si no existe o no es lista, se toma como vacía |
El access también trae empresa_nombre (ADR 0045), el nombre que se muestra de
la empresa activa. Es material de presentación: get_current_user no lo
exige ni lo valida. Esta tabla enumera sólo los claims de identidad que sí se
verifican.
Por qué stateless¶
El jti del access no se verifica contra la base: la firma es la garantía
(ADR 0030). Los demás servicios de la plataforma ya verifican los tokens de
este servicio por firma y claims, sin consultar una base central; get_current_user
hace exactamente lo mismo. El access dura 15 minutos, así que el costo de no
revocar en el acto es acotado (ver «Qué no cubre»).
Decisión¶
Se protege todo /api/v1 excepto auth y el well-known montando los
routers CRUD dentro de un router padre que declara la dependencia:
router_protegido = APIRouter(dependencies=[Depends(get_current_user)])
Quedan protegidos los routers de catálogos, empresas, navegación, sucursales, entidades, tipos de usuario, usuarios y permisos. Quedan públicos:
| Endpoint | Por qué |
|---|---|
POST /api/v1/auth/login |
Es la puerta de entrada: emite el pre-token |
POST /api/v1/auth/login/empresa |
Consume el pre-token y emite los tokens |
POST /api/v1/auth/refresh |
Renueva el access con el refresh opaco |
POST /api/v1/auth/logout |
Cierra la sesión (idempotente) |
POST /api/v1/auth/logout-all |
Cierra todas las sesiones (idempotente) |
GET /.well-known/jwks.json |
Publica la clave pública para verificar la firma |
GET /docs y /openapi.json |
Documentación del servicio |
El pre-token no entra¶
El pre-token del paso 1 (ADR 0030) lleva scope=pre-auth y no trae
empresa_id, username ni tipo_usuario: por diseño es un «vale» temporal,
no un carnet de trabajo. get_current_user lo rechaza por partida doble: por
scope=pre-auth y por faltarle los claims de identidad. Ninguna ruta CRUD
acepta un pre-token.
Alternativas descartadas¶
- Proteger ruta por ruta — repetir la dependencia en cada endpoint propaga el riesgo de olvidar una; el router padre protege todo el dominio de una vez y el caso nuevo queda protegido por defecto.
- Middleware global que exija token en todo — habría que listar
excepciones para
auth, el well-known y la documentación, y el middleware no puede devolver el usuario al endpoint: la dependencia sí. - Verificar el jti contra la base en cada request — rompe el diseño stateless del ADR 0030: cada request consultaría la base y los demás servicios seguirían verificando solo por firma, con criterios distintos.
- Proteger por permiso granular ya — los claims de permisos existen, pero la plataforma todavía no define qué acción protege cada endpoint; exigir permisos ahora cerraría rutas sin un catálogo de acciones aprobado.
Consecuencias¶
- Toda ruta CRUD responde
401sin token, con token inválido o expirado, o con un pre-token;403queda reservado para las reglas de negocio (usuario inactivo, sin empresa, etc.) que ya traducen los routers. rootno llevapermisosen el access (ADR 0023 transversal): su acceso es total por claim, no por lista de acciones.- Los permisos del claim son los del momento de emisión: si se revocan acciones a mitad de la vida del access, el token viejo las sigue mostrando hasta que expire (15 minutos) o se renueve.
- El frontend debe enviar
Authorization: Bearer <access_token>en todas las llamadas a/api/v1salvoauthy el well-known. - La auditoría (
created_by/updated_by) puede alimentarse deUsuarioActualen un slice futuro; este ADR no la implementa.
Qué no cubre¶
- RLS (row-level security) a nivel de base: el filtro por empresa sigue pendiente y no es parte de este ADR.
- Protección por permiso granular: este ADR solo exige autenticación; la
autorización por acción (
permisos) se definirá cuando exista el catálogo de acciones por endpoint. - Revocación inmediata del access: un access robado sigue siendo válido
hasta su
exp(15 minutos); la revocación en caliente exigiría verificar el jti contra la base y rompería el diseño stateless del ADR 0030.