MAINTENANCE_AGENT_TOKEN — Autenticación headless para Maintenance-Weekly

`MAINTENANCE_AGENT_TOKEN` — Autenticación headless para Maintenance-Weekly

Resumen

Introduce un token Bearer dedicado (MAINTENANCE_AGENT_TOKEN) que permite al routine automatizado Maintenance-Weekly (referencia interna: s69) autenticarse contra la API de CreaRack Pro sin intervención humana, evitando el flujo OAuth de claude.ai que falla en ejecuciones headless.

Problema que resuelve

El routine Maintenance-Weekly se ejecuta de forma programada y sin sesión de usuario activa. El mecanismo OAuth de claude.ai requiere interacción del navegador; en un run headless sin interfaz gráfica, ese flujo no puede completarse y el agente recibía 401 antes de llegar a ningún endpoint MCP.

La solución bifurca la autenticación:

Agentes interactivos: siguen usando OAuth / MCP_TOKENS CSV (sin cambios).
Agentes headless: usan MAINTENANCE_AGENT_TOKEN, un secret de larga vida almacenado como CF Pages Secret.

Arquitectura de la solución

Agente Maintenance-Weekly (s69)
  │
  ├─ [Futuro] CF Access Service Token → supera la capa CF Access
  │
  └─ Bearer MAINTENANCE_AGENT_TOKEN
         │
         ▼
   _middleware.ts
     timingSafeEqual check
         │
         ▼
   Endpoint MCP
     re-valida token → mapea a user `maintenance-agent`
         │
         ▼
   Lógica de negocio

Componentes implicados

Componente	Rol
`functions/api/_middleware.ts`	Primer checkpoint: acepta el token y llama `next()`
Endpoint MCP (destino)	Re-valida el token y resuelve el user `maintenance-agent`
CF Pages Secrets	Almacena `MAINTENANCE_AGENT_TOKEN` fuera del código
CF Access (pendiente)	Service Token para atravesar la capa de red previa

Trabajo pendiente

CF Access Service Token: crear el Service Token en el panel de Cloudflare Access para que el routine atraviese la autenticación de red antes de llegar al middleware. Sin esto, el agente headless sigue bloqueado en la capa CF Access. (Referenciado en commit c7f2910.)
Verificar que el endpoint MCP destino mapea correctamente el user maintenance-agent con los permisos mínimos necesarios.

Seguridad y principio de mínimo privilegio

El token se compara con timingSafeEqual (no comparación de cadenas directa).
El endpoint MCP re-valida el token independientemente: el middleware no eleva permisos, solo evita el 401 prematuro.
maintenance-agent debe tener permisos estrictamente acotados a las operaciones del routine semanal.
Rotar el token periódicamente o ante sospecha de compromiso.

Commits relacionados

Commit	Descripción
`2478e5f`	Introduce el routine Maintenance-Weekly (lado agente/scheduler)
`c7f2910`	Añade soporte del token en `_middleware.ts` (lado servidor)

Véase también

[[entity—workers—middleware—api-auth]]