Volver a la wiki

Servicio local_token · Generación y validación del token de auth del Agent

Resumen

Módulo terminal/agent/core/local_token.py (177 líneas). Encargado de generar, persistir y validar el token local que el Agent exige en toda su API HTTP y WebSocket. Token opaco (secrets.token_urlsafe(32)), persistido cifrado en DPAPI, verificado en tiempo constante.

Interfaz pública

get_or_create_local_token() -> str

Devuelve el token local, generándolo y persistiéndolo la primera vez.

Lógica:

  1. Si hay token cacheado en _cached_token, devolverlo.
  2. Si LOCAL_TOKEN_FILE existe, descifrarlo y cachearlo.
  3. Si descifrado falla (fichero corrupto), regenerar + persistir.
  4. Si no existe, generar con secrets.token_urlsafe(32), persistir en %APPDATA%/CreaRackAgent/local_token.enc (cifrado DPAPI), cachear.
  5. Si persistencia falla, usar token en memoria (sin fallar).

Returns: Token de 43-44 caracteres base64url.

Manejo de fallos: Sin excepciones al caller; logger warnings para ficheros dañados o sin permiso de escritura.

verify_local_token(candidate: str | None) -> bool

Compara el candidato con el token local en tiempo constante.

Lógica:

if not candidate:
    return False
return hmac.compare_digest(candidate, get_or_create_local_token())

Inmunidad a timing attacks: hmac.compare_digest() siempre tarda lo mismo, independientemente de dónde falle la comparación.

auth_required(auth_manager) -> bool

Determina si la API local debe exigir el token Bearer.

Lógica: True solo si el Agent está vinculado a un SaaS:

Pre-activación: auth_required() = False → sin exigencia, compat con .exe viejos.

extract_bearer(headers) -> str | None

Parsea el token del header Authorization: Bearer <token>.

Lógica: Busca el prefijo "Bearer " (case-insensitive en la clave), extrae y trimea.

Ejemplos:

allowed_origins_for(auth_manager, port: int) -> list[str]

Calcula los origins CORS permitidos.

Lógica:

Ejemplo:

allowed_origins_for(_FakeAuth(saas_url="https://crearack.com"), 7777)
# → ["http://127.0.0.1:7777", "http://localhost:7777", "https://crearack.com"]

install_local_security(app, get_auth_manager, port: int, csp_frame_ancestors: str) -> None

Instala en la app FastAPI los security headers, gate de auth local y CORS (Fase 3).

Middlewares (en orden):

  1. Security headers (CSP + X-Frame):

    • Content-Security-Policy: valor de csp_frame_ancestors
    • X-Frame-Options: ALLOWALL

  2. Gate Bearer (require_local_token):

    • Si method == OPTIONS → pasar (preflight CORS).
    • Si path in EXEMPT_PATHS → pasar.
    • Si not auth_required() → pasar (pre-activación).
    • Si verify_local_token(extract_bearer(headers)) → pasar.
    • Else → 401 {"error": "Local auth token required"}.

  3. CORS (CORSMiddleware de FastAPI, capa externa):

    • allow_origins: resultado de allowed_origins_for().
    • allow_credentials: False.
    • allow_methods: ["*"].
    • allow_headers: ["*"].

Importancia del orden: CORS es la capa más EXTERNA para que aplique preflight y añada headers CORS también a los 401 del gate.

Rutas exentas (EXEMPT_PATHS)

El gate Bearer no se aplica a:

EXEMPT_PATHS = frozenset({
    "/",                        # Health check, sin datos sensibles
    "/info",                    # agent_id, agent_version (bootstrap frontend)
    "/health",                  # Status local, sin acciones
    "/check",                   # Health probe
    "/favicon.ico",             # Recurso estático
    "/terminal/ui",             # HTML del iframe (no puede llevar headers)
    "/saas/configure",          # Flujo de activación: recibe el SaaS URL
    "/saas/status",             # Comprueba estado de vinculación
    "/saas/connect",            # Finaliza activación (SaaS aún no tiene token)
})

Razón: Bootstrap del frontend (descubrir agent_id, configurar SaaS) debe funcionar ANTES de que el token esté depositado en el servidor.

Persistencia: DPAPI

El token se almacena en %APPDATA%/CreaRackAgent/local_token.enc cifrado con DPAPI (Data Protection API de Windows).

Módulo relacionado: [[entity—agent—service—local-token]], que proporciona encrypt_secret() y decrypt_secret().

Ventajas:

Fallos tolerables:

Caching en memoria

Variable global _cached_token: str | None.

Seguridad adicional

Flujo de uso

1. Agent arranca (main.py):
   → install_local_security() instala middlewares
   → get_auth_manager() devuelve auth_manager (puede ser None si pre-activación)
   → middleware require_local_token verifica cada request

2. Conecta a SaaS (connector.py):
   → _register_local_token() → POST /api/agent/register-local-token
   → SaaS custodia el token

3. Frontend (Fase 2) en navegador:
   → GET /api/agent/local-token (auténtico contra SaaS)
   → SaaS devuelve token (solo a sesión del tenant dueño)
   → Frontend inyecta en postMessage SET_AUTH_TOKEN → terminal.html
   → terminal.html manda {"action":"auth","token":...} en WS open

4. WS consola recibe token:
   → routes/terminal.py valida primer mensaje
   → verify_local_token() verifica
   → Sesión abierta (o close 4401)

Testing

Archivo: tests/agent/test_agent_local_auth.py

TestQué verifica
test_token_generated_and_persistedGeneración, persistencia en fichero, lectura posterior (cache + disco).
test_verify_tokenverify_local_token(token) correcto, incorrecto, None, "".
test_auth_required_only_when_linkedauth_required() solo True si saas_url + agent_id.
test_extract_bearerParseo de Authorization (case-insensitive, trim spaces).
test_exempt_paths_cover_bootstrapEXEMPT_PATHS incluye /info, /health, /terminal/ui, /saas/configure; excluye acciones sensibles.
test_corrupt_store_regeneratesDPAPI corrupta → regenera token correctamente.

Ejecución: ✓ Verdes en Docker. Patrón de carga por ruta (s124): no importa como package, carga como módulo directo.

Dependencias

Véase también

Subir