Request Lifecycle

This page documents how an incoming HTTP request flows through the Aero2 Worker, from initial receipt to final response.

Request Flow

  Client Request
       |
       v
  1. Cloudflare Worker receives request
       |
       v
  2. Subdomain routing middleware
     - Extract Host header
     - Determine app context (dashboard, app subdomain, bare domain)
     - Set app_id on Hono context
       |
       v
  3. Security headers middleware
     - HSTS (Strict-Transport-Security)
     - X-Frame-Options: DENY
     - X-Content-Type-Options: nosniff
     - Referrer-Policy: strict-origin-when-cross-origin
     - Permissions-Policy (restrict camera, mic, geolocation, etc.)
     - Content-Security-Policy (per route type: API vs SPA)
       |
       v
  4. CSRF protection middleware
     - Applies to POST/PUT/DELETE/PATCH with cookie authentication
     - Validates Origin header matches Host
     - Falls back to Referer header check
     - Rejects requests missing both Origin and Referer
     - Bearer token requests bypass CSRF (not cookie-based)
       |
       v
  5. CORS middleware
     - Per-app origin validation
     - Handles preflight OPTIONS requests
     - Sets Access-Control-Allow-Origin, Methods, Headers
       |
       v
  6. Hono route matching
     - /oauth2/*    -> OIDC Provider routes
     - /rp/*        -> Relying Party routes
     - /api/*       -> API routes (users, clients, IdPs, roles, sessions, audit)
     - /health      -> Health check endpoints
     - /.well-known/* -> OIDC Discovery
     - /*           -> Frontend SPA catch-all
       |
       v
  7. Authentication middleware (on protected routes)
     - Extract token from Authorization header (Bearer) or session cookie
     - Fetch JWKS from Durable Object
     - Verify JWT signature (RS256 only)
     - Validate claims: issuer, audience, expiry, token_use
     - Check session not revoked (D1 lookup)
     - Check user not disabled
     - Attach user and session to Hono context
       |
       v
  8. Authorization middleware (on admin routes)
     - Load user roles from D1
     - Load role permissions from D1
     - Check required permission for the endpoint
     - Return 403 if insufficient permissions
       |
       v
  9. Route handler (business logic)
     - Validate request body/params with Zod
     - Execute D1 queries (parameterized)
     - Call Durable Objects if needed (JWKS signing)
     - Write audit log entries
     - Build response
       |
       v
  10. Response
      - JSON for API endpoints
      - HTML for SPA pages
      - Redirects for OAuth flows
      - Appropriate status codes and headers

Middleware Order

The middleware chain is applied in a specific order. The sequence matters because later middleware depends on context set by earlier middleware.

Order	Middleware	File	Purpose
1	Subdomain routing	`middleware/tenant.ts`	Sets app context
2	Security headers	`index.ts`	Sets HSTS, CSP, etc.
3	CSRF protection	`index.ts`	Validates Origin for state-changing requests
4	CORS	`index.ts`, `op.ts`	Handles cross-origin requests
5	Rate limiting	`middleware/ratelimit.ts`	Throttles requests per IP/user
6	Authentication	`middleware/auth.ts`	Verifies JWT, attaches user
7	Authorization	`middleware/auth.ts`	Checks RBAC permissions

Route-Specific Behavior

Public Routes (no auth required)

GET /health -- Health check
GET /health/live -- Liveness probe
GET /.well-known/openid-configuration -- OIDC Discovery
GET /oauth2/jwks.json -- Public JWKS endpoint
GET /oauth2/authorize -- Authorization endpoint (redirects to login)
POST /oauth2/token -- Token endpoint (client authenticates via body)
POST /oauth2/revoke -- Token revocation
GET /rp/authorize/:idp -- Start external IdP flow
GET /rp/callback/:idp -- Handle external IdP callback

Authenticated Routes (session or bearer token)

GET /api/users/me -- Current user profile
GET /api/sessions -- User's active sessions
DELETE /api/sessions/:id -- Revoke a session
GET /oauth2/userinfo -- OIDC UserInfo

Admin Routes (requires specific permissions)

GET/POST/PUT/DELETE /api/users/* -- User management (requires users:*)
GET/POST/PUT/DELETE /api/clients/* -- Client management (requires clients:*)
GET/POST/PUT/DELETE /api/idps/* -- IdP management (requires idps:*)
GET/POST/PUT/DELETE /api/roles/* -- Role management (requires roles:*)
GET /api/audit-logs -- Audit log viewer (requires admin)

Error Handling

Errors at each stage produce appropriate HTTP responses:

Stage	Error	Response
Subdomain routing	Unknown subdomain	404 Application not found
CSRF	Missing Origin/Referer	403 Forbidden
Rate limiting	Too many requests	429 Too Many Requests + Retry-After header
Authentication	Invalid/expired token	401 Unauthorized
Authorization	Insufficient permissions	403 Forbidden
Validation	Invalid request body	400 Bad Request + error details
Route handler	Not found	404 Not Found
Route handler	Internal error	500 Internal Server Error (generic message)