Auth y Sesión API

Propósito

Familia de endpoints que cubren el contrato de identidad y acceso entre Sevastopol y Orchestrator: login con 2FA opcional, validación de sesión, gestión de tenants, resolución del tenant activo, permisos por ruta y el menú dinámico que Sevastopol pinta según rol.

Estos endpoints son consumidos en su mayoría por el middleware de Sevastopol, no directamente por las islands. Excepción: POST /api/auth/login desde index.astro y POST /api/auth/logout desde el header.

Mapa de Familias

Familia	Prefijo	Router	Servicio responsable
Autenticación	/api/auth	routes/command/auth.ts	AuthService
Sesiones	/api/sessions	routes/command/sessions.ts	SessionService
Tenants (multi-empresa)	/api/tenant	routes/command/tenant.ts	TenantResolver
Bases de tenant	/api/tenant-db	routes/command/tenant-db.ts	TenantDbService
Permisos por ruta	/api/permissions	routes/admin/...	PermissionService
Menú dinámico	/api/menu	routes/command/menu.ts	MenuService

Autenticación

POST /api/auth/login

Verifica usuario y contraseña, devuelve un JWT en cookie sid (HttpOnly, Secure en producción) y datos básicos del usuario. Si el usuario tiene 2FA habilitado, la respuesta indica requires_2fa: true y la cookie no se setea hasta POST /2fa/verify.

Request

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"$PASSWORD"}' \
  -c cookies.txt

Response 200

{
  "success": true,
  "user": { "id": 1, "username": "admin", "role": "SUPER_ADMIN" },
  "requires_2fa": false
}

Response 401

{ "success": false, "error": "Invalid credentials" }

POST /api/auth/validate

Valida la cookie sid y devuelve los datos del usuario y tenant si la sesión está vigente. Lo invoca el middleware de Sevastopol en cada navegación protegida.

POST /api/auth/logout

Invalida la sesión y limpia la cookie sid.

Endpoints 2FA

Método	Ruta	Uso
POST	/api/auth/2fa/setup	Genera el secreto TOTP y QR para enrolar al usuario actual.
POST	/api/auth/2fa/enable	Activa 2FA tras verificar el primer código.
POST	/api/auth/2fa/disable	Desactiva 2FA (requiere código vigente).
POST	/api/auth/2fa/verify	Verifica el código TOTP durante el login.

Sesiones

GET /api/sessions

Lista sesiones activas del usuario actual (útil para “cerrar sesión en otros dispositivos”).

DELETE /api/sessions/:id

Revoca una sesión específica.

Tenants

Los endpoints de tenant resuelven la empresa activa del usuario y la lista de tenants accesibles. Sevastopol los consume al cambiar de empresa desde el TenantPicker.

Método	Ruta	Uso
GET	/api/tenant	Lista tenants accesibles para el usuario autenticado.
POST	/api/tenant	Crea un tenant nuevo (admin).
PUT	/api/tenant	Actualiza el tenant activo del usuario.
DELETE	/api/tenant	Desactiva el tenant.
GET	/api/tenant-db	Lista bases de tenant disponibles.
DELETE	/api/tenant-db/:id	Elimina una base de tenant (operación destructiva, admin).

Request

curl -X GET http://localhost:8000/api/tenant -b cookies.txt

Response 200

{
  "success": true,
  "data": [
    { "id": "uuid", "rut": "76123456-7", "business_name": "Empresa SPA", "active": true }
  ]
}

Permisos y Menú

GET /api/permissions

Devuelve el catálogo de permisos por ruta (RBAC) para el rol del usuario activo. El middleware authorizeRoute del Orchestrator usa la misma tabla para autorizar cada request.

GET /api/menu

Devuelve el árbol de navegación que Sevastopol debe pintar para el usuario actual, filtrado por permisos. Es la fuente de verdad del sidebar.

Notas de seguridad

• La cookie sid es HttpOnly y SameSite=Lax; no es legible desde JavaScript del navegador.
• Endpoints de mutación (POST, PUT, DELETE) requieren tenant resuelto en sesión.
• POST /api/auth/login está protegido por loginRateLimiter para mitigar fuerza bruta.
• Para inspeccionar el flujo completo, ver Autenticación y el middleware de Sevastopol.