0047. Inicio de sesión administrativo exclusivo para root¶
Estado: Aceptado Fecha: 2026-10-21 Autor: Duval Alcivar Módulo(s) afectado(s): app/api/deps.py, app/domains/usuarios/, tests/unit/auth/, tests/unit/
Contexto¶
El inicio de sesión normal resuelve empresas en dos pasos y emite un token de acceso con
empresa_id. La superficie administrativa es global, por lo que no debe
inventar una empresa ni entrar en el flujo de RLS de sesiones.
Decisión¶
Se agrega POST /api/v1/auth/admin/login, separado del inicio de sesión normal. Sólo un
usuario cuyo tipo persistido sea exactamente root puede emitir un token administrativo.
La regla es rechazar codigo != "root", sin enumerar roles ni tipos futuros.
El token contiene sub, usuario_id, username, tipo_usuario="root" y
scope="admin"; firmar_token agrega los atributos de plataforma. No contiene
empresa_id ni emite un token de actualización. UsuarioAdminActual y
get_admin_user validan la superficie administrativa por separado. Las rutas
normales siguen usando get_current_user, por lo que rechazan los tokens
administrativos al exigir una empresa.
La validación del nombre de usuario, la contraseña y el estado se comparte
internamente, pero el inicio de sesión normal conserva su flujo de empresas,
token previo y token de actualización sin comprobaciones administrativas. No se
confía en el cliente ni en encabezados: la firma JWT y los atributos se validan
en el servidor. Las futuras rutas administrativas deberán usar
get_admin_user.
Alternativas descartadas¶
- Reutilizar
get_current_user: exigeempresa_idy mezclaría dos superficies. - Usar una empresa ficticia: falsearía el contexto de autorización y la RLS.
- Enumerar roles permitidos: cada tipo futuro quedaría autorizado por omisión.
- Emitir un token de actualización administrativo: introduciría sesiones y RLS empresarial innecesarias.
Consecuencias¶
El panel administrativo obtiene credenciales globales sólo para root, y los
tipos desconocidos quedan rechazados por defecto. Se registra el intento en
log_sesiones con empresa_id=NULL. Cada nueva ruta admin debe validar el
token administrativo explícitamente; el token administrativo no autoriza rutas
normales.