CreaRack-SL

Feature: Autenticación local del Agent — Fase 1 (Backend inerte)

Vista limpiaEditar
Funcionalidadactivecreado Wed Jun 10#terminal#feature#agent#auth#security#backend#fase-1#audit-2026

Resumen

Sesión 125 (2026-06-10): primer paso del cierre de la Raíz 3 de la Auditoría Suprema. Implementación backend (totalmente inerte) de autenticación local cross-origin del Agent.

La feature se despliega en 3 fases:

  1. Fase 1 (este commit): backend + endpoints inertes + tests. Ningún cliente lo usa.
  2. Fase 2: frontend web — recoger y usar el token en requests locales.
  3. Fase 3: Agent .exe — generar, depositar y validar tokens.

Qué cambia en esta release

Backend

  • Nuevo campo: AgentInstance.local_token_enc (TextField, cifrado con Fernet).
  • Migración BD: terminal/0003_agentinstance_local_token_enc.py.
  • Dos endpoints nuevos:
    • POST /api/agent/register-local-token — Agent deposita token (auth=None, autoverificado con JWT).
    • GET /api/agent/local-token — Frontend recoge token (sesión + fleet:view + aislamiento org).
  • Schemas: AgentLocalTokenSchema en terminal/api/auth.py.
  • Cifrado seguro: CredentialManager (Fernet) garantiza que el token nunca se guarda en claro.

Visible para clientes

Ningún cambio: la feature es totalmente inerte. Ningún cliente llama a los nuevos endpoints hasta la Fase 2.

Testing

  • Suite completa: tests/api/test_terminal_local_token.py (115 LOC).
  • Cobertura:
    • Round-trip: Agent deposita, frontend recoge descifrado.
    • Autenticación: Agent JWT requerido en POST, sesión en GET.
    • Refresh tokens rechazados en POST.
    • Aislamiento cross-tenant: admin de org B no puede leer token de org A (404).
    • Sesión en GET: Agent JWT rechazado (403).
    • Permisos granulares: solo fleet:view permite leer.
    • Valores ausentes: Agent sin token aún → 404.

Propósito & Impacto

Problema

El Agent hoy no autentica requests locales. Cualquier página web puede enviar comandos a localhost:5050 sin restricción (Raíz 3 de la Auditoría Suprema).

Solución

Guardar de forma cifrada el token local del Agent. En Fase 2, el frontend lo usa en requests. En Fase 3, el Agent lo rechaza si falta o es inválido.

Impacto en seguridad

  • Inerte esta fase: cero impacto visible (endpoints existen pero nadie los llama).
  • Preparatorio: sienta las bases para Fase 2 y 3.
  • Plan Hardening E: implementa CredentialManager + Fernet para secretos en BD.

Cambios técnicos

Ficheros modificados

  • CHANGELOG.md — entrada descriptiva sesión 125.
  • RELEASE_NOTES.md — nota breve para usuarios (s125).
  • terminal/models.py — campo local_token_enc + documentación.
  • terminal/api/auth.py — 2 endpoints + helper AgentLocalTokenSchema.
  • terminal/migrations/0003_agentinstance_local_token_enc.py — migración (AddField).
  • tests/api/test_terminal_local_token.py — suite de tests (nuevo fichero).

Dependencias

  • core.security.credential_manager.CredentialManager — cifrado Fernet.
  • core.utils.get_current_org — aislamiento por org.
  • core.utils.require_perm — validación de permisos.

Schema de la DB

ALTER TABLE terminal_agentinstance ADD COLUMN local_token_enc TEXT NOT NULL DEFAULT '';

ADR & Decisiones

ADR: decision--20260610--terminal-auth-local-cross-origin

  • Almacenamiento: Fernet (simétrico, cifrado en reposo).
  • Endpoints: 2 (uno para Agent, uno para frontend).
  • Autenticación: Agent JWT en POST, sesión en GET.
  • RLS: aislamiento por organización en GET.

Versionado

Sin cambio de versión visible: la feature es inerte, no altera comportamiento del cliente.

(Próximo cambio de versión será cuando Fase 2 ó 3 active la feature.)

Fase 2 — Próximo paso

  • Frontend: actualizar lógica de conexión local para:
    1. Solicitar token vía GET /api/agent/local-token.
    2. Pasarlo en header/body a requests contra localhost:5050.
  • Alcance: cambios en la web, lógica local del navegador.

Fase 3 — Agent .exe

  • Agent: generar UUID local, depositarlo vía POST /api/agent/register-local-token.
  • Agent: validar requests que lleguen de la web (usar token).
  • Alcance: cambios en el binario del Agent (C# / TypeScript).

Véase también

  • [[decision—20260610—terminal-auth-local-cross-origin]]
  • [[entity—terminal—endpoint—register-local-token]]
  • [[entity—terminal—endpoint—get-local-token]]
  • [[entity—terminal—model—agentinstance]]
  • [[concept—security—credential-encryption]]

Referenciado desde

Inicio
Yo