Saltar a contenido

ADR 005: Autenticación y oauth2-server híbrido

Estado

Aceptado — 2026-06 · Implementación parcial (JWT middleware, login demo, scopes por panel) · Objetivo: oauth2-server interno/externo completo

Relacionado con ADR 004, ADR 010, ADR 023.

Contexto

Cortex/HIVE expone varios panels y transports (REST, MCP, WS). La autenticación debe:

  1. Proteger API y transports cuando el despliegue lo exija.
  2. Soportar emisor interno (desarrollo/staging) y externo (IdP OIDC).
  3. Aplicar scopes por panel (PanelAuthPolicy) sin acoplar dominio.

Decisión

Modos (AUTH_MODE)

Modo Comportamiento
optional (default dev) Sin enforcement REST; rate limit desactivado
required Bearer JWT obligatorio en rutas protegidas
internal Emisor interno HS256 (JWT_SECRET)
external Validación JWKS contra IdP (OIDC_JWKS_URI)

Variables canónicas: ver Configuración. Los alias CORTEX_* están deprecados (dual-read temporal).

Scopes por panel

  • Cada panel_id puede declarar PanelAuthPolicy (scopes requeridos).
  • GET /api/v1/panels/{id} valida scopes del token salvo bypass control para operadores de plataforma.

Objetivo oauth2-server

Módulo cortex_framework.oauth2_server (futuro) con:

  • Registro de clients OAuth2, authorization code + PKCE para SPA.
  • Usuarios y roles en PostgreSQL (sustituir DEFAULT_USERS demo).
  • Refresh tokens y revocación.
  • JWKS RS256 con rotación de claves.
  • Auth unificado en MCP y WS (mismo Bearer que REST).

Implementado hoy

Pieza Ubicación
AuthMiddleware Bearer JWT framework/cortex_framework/api/auth.py
Login demo + /me framework/cortex_framework/api/auth_routes.py
Usuarios PG (platform_auth_users) framework/cortex_framework/auth/auth_users.py
Refresh / revoke tokens PG (platform_refresh_tokens) + fallback memoria
OAuth2 PKCE (authorize + token) framework/cortex_framework/oauth2_server/
Discovery OIDC + JWKS sintético framework/cortex_framework/api/oidc_metadata.py
Validación externa JWKS framework/cortex_framework/api/token_validator.py
Scopes panel framework/cortex_framework/api/panel_scope_guard.py
Auth MCP (POST /mcp) AuthMiddleware + framework/tests/test_mcp_auth.py
Auth WS (query token) framework/cortex_framework/io/ws/router.py + test_ws_auth.py
Shell React login/guard framework/web-shadcn, @cortex/panel-core

Pendiente (fases de construcción)

Fase Entregable Estado
5.1 Usuarios PG, refresh en PG, staging con required Parcial (PG listo; documentar staging)
5.1 Refresh/revoke en memoria (fallback) Hecho
5.2 Bearer en MCP; JWT en handshake WS Hecho (AgentChatWidget envía ?token=)
5.4 Módulo oauth2-server interno (PKCE, RS256) Parcial (PKCE hecho; RS256 rotación pendiente)
5.6 Modo external E2E con IdP real Pendiente

Consecuencias

  • Positivas: contrato estable para panel y plugins; scopes desacoplados del dominio.
  • Negativas: modo external E2E y rotación RS256 pendientes (fases 5.4/5.6).
  • Migración: mantener /api/v1/auth/login durante transición al oauth2-server.

Referencias