Middleware de autenticación API — _middleware.ts

Descripción

functions/api/_middleware.ts es el primer filtro de seguridad que evalúa todos los requests entrantes bajo la ruta /api/* en el despliegue de Cloudflare Pages. Actúa antes de que cualquier endpoint MCP o handler específico reciba la petición.

El middleware implementa validación de tokens Bearer en dos capas:

Si ninguna capa valida el token, el middleware devuelve 401 antes de que la request alcance el endpoint MCP destino.

Variables de entorno (CF Pages Secrets)

MAINTENANCE_AGENT_TOKEN=<secret>   # Token dedicado del agente headless
MCP_TOKENS=<name1:token1,name2:token2,...>   # Tokens multi-tenant (formato CSV)

Ambas variables se leen desde el contexto de CF Pages (context.env).

Flujo de autenticación

Request → _middleware.ts
  │
  ├─ ¿Bearer token presente?
  │     │
  │     ├─ MAINTENANCE_AGENT_TOKEN env != null
  │     │   └─ timingSafeEqual(env.MAINTENANCE_AGENT_TOKEN, token)
  │     │         ✓ → next()   (pasa al endpoint MCP)
  │     │
  │     └─ MCP_TOKENS CSV split → busca par name:token
  │           ✓ → next()   (pasa al endpoint MCP)
  │
  └─ Sin match → 401 Unauthorized

La comparación usa timingSafeEqual en ambas capas para evitar timing attacks.

Rutas públicas (PUBLIC_PATHS)

Existen rutas excluidas de la validación de token (definidas en la constante PUBLIC_PATHS). Estas no pasan por la lógica Bearer.

Interacción con Cloudflare Access

⚠️ Pendiente (a fecha 2026-05-18): el routine headless necesita además un CF Access Service Token para atravesar la capa de Cloudflare Access antes de que llegue al middleware. Sin ese Service Token, el request recibe 401/403 en la capa Access previa al middleware, aunque lleve el MAINTENANCE_AGENT_TOKEN correcto.

El middleware es el segundo filtro; CF Access es el primero. Ambos deben estar configurados para que un agente headless opere sin intervención humana.

Seguridad

• timingSafeEqual previene ataques de tiempo en la comparación de tokens.
• MAINTENANCE_AGENT_TOKEN tiene un scope reducido: el endpoint MCP que lo recibe lo re-valida y lo mapea al usuario virtual maintenance-agent. No otorga acceso más allá de lo que ese endpoint permita.
• El token dedicado debe rotarse siguiendo el Secret Rotation Playbook cuando expire o se sospeche compromiso.

Historial relevante

Véase también

• [[feature—workers—maintenance-agent-token]]