System Overview

Aero2 is a multi-tenant authentication and authorization platform built on Cloudflare Workers. A single Worker deployment handles all subdomains, serving both the developer dashboard and per-application auth pages.

Tech Stack

Layer	Technology
Runtime	Cloudflare Workers (V8 isolates)
Web Framework	Hono
Database	Cloudflare D1 (SQLite at the edge)
Stateful Objects	Durable Objects (JWKS key management)
Frontend	React 19 + Vite
Validation	Zod
Auth Libraries	jose (JWT), oauth4webapi
Linting	Biome
Testing	Vitest + @cloudflare/vitest-pool-workers, Playwright

Architecture Diagram

                         Incoming Request
                              |
                    +---------v---------+
                    | Cloudflare Worker  |
                    +-------------------+
                              |
              +---------------v----------------+
              |     Middleware Chain            |
              |  1. Subdomain Routing          |
              |  2. Security Headers           |
              |  3. CSRF Protection            |
              |  4. Authentication             |
              |  5. Authorization (RBAC)       |
              +---------------+----------------+
                              |
              +---------------v----------------+
              |     Hono Route Handlers        |
              |  - OP endpoints (/oauth2/*)    |
              |  - RP endpoints (/rp/*)        |
              |  - API endpoints (/api/*)      |
              |  - Frontend (SPA catch-all)    |
              +------+----------------+--------+
                     |                |
              +------v------+  +-----v---------+
              | D1 Database |  | Durable Objects|
              | (SQLite)    |  | (JWKS keys)    |
              +-------------+  +----------------+

Dual Role

Aero2 serves two roles simultaneously:

OIDC Provider (OP): Issues ID tokens, access tokens, and refresh tokens to registered OAuth clients. Implements the Authorization Code Flow with PKCE, token refresh, revocation, UserInfo, and OIDC Discovery.
Relying Party (RP): Delegates authentication to external identity providers (GitHub, Google, and dynamically configured OIDC/OAuth2 providers). Handles the OAuth callback, creates or links user accounts, and establishes sessions.

Multi-Tenant Design

A single deployment serves multiple applications via subdomain routing. Each application gets its own subdomain, user pool, identity providers, branding, and settings. The app_id column on all tenant-scoped tables enforces data isolation.

See Multi-Tenancy Design for the full entity model and isolation guarantees.

Key Directories

Directory	Purpose
`src/backend/`	Hono API routes, middleware, utilities
`src/backend/middleware/`	Auth, RBAC, rate limiting, CSRF middleware
`src/backend/utils/`	Token signing/verification, encryption, crypto
`src/frontend/`	React 19 SPA (pages, components, contexts)
`src/frontend/components/ui/`	Reusable UI component library
`migrations/`	D1 database schema migrations (numbered SQL files)
`docs/`	Documentation site (Nextra/MDX)
`tests/`	Vitest unit and integration tests

Key Source Files

File	Purpose
`src/backend/index.ts`	Main Hono app, route mounting, global middleware
`src/backend/op.ts`	OIDC Provider endpoints (authorize, token, userinfo, revoke)
`src/backend/rp.ts`	Relying Party endpoints (authorize redirect, callback)
`src/backend/idp.ts`	Identity Provider CRUD API
`src/backend/clients.ts`	OAuth client CRUD API
`src/backend/roles.ts`	Role and permission management API
`src/backend/jwks.ts`	JWKS Durable Object (key generation, rotation, signing)
`src/backend/middleware/auth.ts`	JWT verification, session validation, RBAC checks
`src/backend/utils/token.ts`	JWT signing and verification utilities
`src/backend/utils/crypto.ts`	PBKDF2 hashing, AES-256-GCM encryption, HMAC