Cloudflare Access Zero Trust & Edge JWT Isolation
Dual-layer Cloudflare Access architecture (Zero Trust edge gate + Worker RS256 JWT verification) protecting staging.slloy.com, /admin, and docs.slloy.com.
Slloy uses a Dual-Layer Cloudflare Access Zero Trust Architecture across three internal/pre-release surfaces:
staging.slloy.com: Full-site staging gate (STAGING_ACCESS_TEAM_DOMAIN+STAGING_ACCESS_AUD), with an explicit bypass only forPOST /api/payments/webhook/stripe.slloy.com/admin*&slloy.com/api/admin/*: Production admin console boundary gate (ADMIN_ACCESS_TEAM_DOMAIN+ADMIN_ACCESS_AUD), while keeping publicslloy.compages open.docs.slloy.com: Internal operations and engineering documentation portal (slloy-docWorker,ACCESS_TEAM_DOMAIN+ACCESS_AUD).
1. Why Dual-Layer Protection (Edge Gate + Worker JWT Verification)?
- Layer 1 — Cloudflare Zero Trust Edge Gate:
- Intercepts unauthenticated visitors at the Cloudflare edge before reaching the Worker, presenting the Cloudflare Access login page (Email One-Time PIN or Google OAuth) or checking
CF-Access-Client-Id/CF-Access-Client-Secretservice tokens for CI smoke tests. - Upon authentication, Cloudflare injects a signed RS256 JWT in the
Cf-Access-Jwt-Assertionrequest header.
- Intercepts unauthenticated visitors at the Cloudflare edge before reaching the Worker, presenting the Cloudflare Access login page (Email One-Time PIN or Google OAuth) or checking
- Layer 2 — In-Worker Cryptographic Verification (
stagingAccess.ts/worker.ts):- Defends against misconfigured routes, accidentally disabled Zero Trust policies, or direct origin/Worker requests.
- The Worker independently verifies the
Cf-Access-Jwt-Assertionheader signature, issuer (iss), audience (aud), and expiration (exp/nbf) against${TEAM_DOMAIN}/cdn-cgi/access/certs. - If the header is missing or invalid, the Worker immediately returns
HTTP 401(STAGING_ACCESS_REQUIRED,ADMIN_ACCESS_REQUIRED, orACCESS_REQUIRED) withCache-Control: private, no-storeandX-Robots-Tag: noindex, nofollow.
2. RS256 JWT Verification Contract (server/src/stagingAccess.ts)
Both slloy (server/src/stagingAccess.ts + server/src/http/middleware/access.ts) and slloy-doc (worker.ts) enforce the exact same verification contract:
- Startup / Configuration Validation (
validateAccessSettings):TEAM_DOMAINmust match/^https:\/\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.cloudflareaccess\.com$/(e.g.,https://slloy.cloudflareaccess.com, no trailing slash).AUDmust be a 64-character lowercase hexadecimal Application Audience (AUD) tag (/^[a-f0-9]{64}$/).- Configuring only one of
TEAM_DOMAINorAUDis treated as a fatal configuration error.
- JWKS Fetching & Rate-Limited Key Refresh (
fetchCerts&keyFor):- Fetches RSA public keys (
kty === "RSA") from${teamDomain}/cdn-cgi/access/certs(5,000 mstimeout) and imports them forRS256verification. - Caches imported
CryptoKeys in isolate memory mapped bykid. - When an incoming JWT header contains an unknown
kid(e.g., after Cloudflare rotates signing keys), the verifier refreshes/cdn-cgi/access/certsat most once every60seconds (certsRefreshIntervalMs = 60_000) and deduplicates concurrent in-flight refreshes. This prevents an attacker from flooding the Worker with fakekidvalues to DDoS the certs endpoint.
- Fetches RSA public keys (
- Claims Verification:
- Header
alg === "RS256"and non-emptykid. - Cryptographic RS256 signature matches the JWK for
kid. iss === teamDomain.aud(string or string array) contains the application'sAUD.exp > nowandnbf <= now.
- Header
- Forced Response Headers:
- Every response served behind an Access gate has
Cache-Control: no-store(orprivate, no-store) andX-Robots-Tag: noindex, nofollowforcefully applied so sensitive content is never stored in shared CDN caches or indexed by crawlers.
- Every response served behind an Access gate has
3. Surface-by-Surface Configuration Summary
| Surface | Zero Trust Application Path | Worker Env / Secrets | Unauthorized Response | Special Rules |
|---|---|---|---|---|
Staging (slloy-staging-api) | staging.slloy.com (entire host) + separate Bypass app for staging.slloy.com/api/payments/webhook/stripe | STAGING_ACCESS_TEAM_DOMAINSTAGING_ACCESS_AUD | 401 {"error":"STAGING_ACCESS_REQUIRED"} | POST /api/payments/webhook/stripe bypasses Access and verifies stripe-signature. /api/health is not exempted (anonymous 401 proves liveness; CI passes Service Token for 200 ok:true). |
Production Admin (slloy-production-api) | slloy.com/admin* and slloy.com/api/admin/* (shared in one Access App with a single AUD) | ADMIN_ACCESS_TEAM_DOMAINADMIN_ACCESS_AUD | 401 {"error":"ADMIN_ACCESS_REQUIRED"} | Only intercepts /admin, /admin/*, /api/admin, /api/admin/*. All public pages and /api/* pass through untouched. |
Documentation (slloy-doc) | docs.slloy.com (entire host) | ACCESS_TEAM_DOMAIN (vars: https://slloy.cloudflareaccess.com)ACCESS_AUD (secret) | 401 {"error":"ACCESS_REQUIRED"} | Uses zero-dependency WebCrypto (crypto.subtle) in worker.ts before serving static Fumadocs export from env.ASSETS. Always attaches Cache-Control: private, no-store and X-Robots-Tag: noindex, nofollow. |
Critical Rollout Order
[!CAUTION] Always create and activate the Cloudflare Zero Trust Access Application in the dashboard BEFORE setting the
*_ACCESS_AUDsecret on the Worker. If you upload the WorkerAUDsecret before Cloudflare Edge starts injectingCf-Access-Jwt-Assertion, the Worker will immediately returnHTTP 401(instead of redirecting to the Cloudflare login screen) for every visitor.
Admin SPA, 3-Tier RBAC, Cost Accounting & Moderation
Architecture of the /admin SPA, 3-tier staff RBAC, DB-backed login rate limiting, paidCny vs. estimateCny financial reporting, prompt batch ops, and share privacy.
Production Deployment Handbook (Cloudflare Workers)
Complete production architecture, Neon + Hyperdrive setup, R2 media buckets, Cloudflare Queues, Worker secrets, GitHub environment isolation, and rollback runbook.