Saltar a contenido

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 401 sin token, con token inválido o expirado, o con un pre-token; 403 queda reservado para las reglas de negocio (usuario inactivo, sin empresa, etc.) que ya traducen los routers.
  • root no lleva permisos en 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/v1 salvo auth y el well-known.
  • La auditoría (created_by/updated_by) puede alimentarse de UsuarioActual en 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.