hono-gateway

Hono Gateway (Workers) Rules

worker-api and sibling worker-* / webhook-* apps use Hono on Cloudflare Workers. For deep patterns load the hono and workers-best-practices skills.

Request lifecycle

flowchart TD
  Client["Client / front-app"] --> ReqId["request-id"]
  ReqId --> Sec["secure headers"]
  Sec --> CORS["CORS (/api/*)"]
  CORS --> CSRF["CSRF (unsafe methods)"]
  CSRF --> Timing["timing (dev only)"]
  Timing --> Timeout["timeout"]
  Timeout --> Body["body limit"]
  Body --> Validation["zValidator at boundary"]
  Validation --> Handler["thin route handler"]
  Handler --> Binding["service binding (optional)"]
  Handler --> Response["c.json()"]

Middleware order (src/index.ts)

Register in this order. The onion model runs "before" logic top-down and "after" logic (response mutation) bottom-up.

Root app (every route):

1. requestId() (hono/request-id) - first, so every error log and response can reference it. Sets c.get("requestId") and echoes the X-Request-Id response header. Add RequestIdVariables to the Hono generic's Variables so c.get("requestId") is typed.
2. secureHeaders() (hono/secure-headers) - HSTS, nosniff, no-referrer, COOP/CORP on by default (and X-Powered-By removed). Add a locked-down contentSecurityPolicy (default-src 'none'; frame-ancestors 'none') - harmless for JSON, hardening if a response is ever rendered. Set permissionsPolicy to deny camera/mic/geolocation/payment. CORP same-origin is fine for CORS-mode fetch from front-app; do not disable it to fix SPA reads.
3. cors() on /api/* - preflight OPTIONS must clear before auth/routes. Read the allowlist from c.env.CORS_ORIGINS per request (env is not available at module scope on Workers). Put X-Request-Id in exposeHeaders so browsers can read the id. Empty allowlist is permissive (*) in dev only; any other ENVIRONMENT (including staging / production and typos) must set origins or /api/* returns 503.
4. Origin / CSRF gate on /api/* - unsafe methods only (any Content-Type, including application/json); must not block CORS preflight. Allows when Origin is on the allowlist or Sec-Fetch-Site is same-origin / same-site. Hono built-in csrf() only covers form content-types - do not rely on it alone for this JSON SPA gateway.