Skip to Content
Slloy Docs
Auth, Admin & Security

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:

  1. staging.slloy.com: Full-site staging gate (STAGING_ACCESS_TEAM_DOMAIN + STAGING_ACCESS_AUD), with an explicit bypass only for POST /api/payments/webhook/stripe.
  2. slloy.com/admin* & slloy.com/api/admin/*: Production admin console boundary gate (ADMIN_ACCESS_TEAM_DOMAIN + ADMIN_ACCESS_AUD), while keeping public slloy.com pages open.
  3. docs.slloy.com: Internal operations and engineering documentation portal (slloy-doc Worker, ACCESS_TEAM_DOMAIN + ACCESS_AUD).

1. Why Dual-Layer Protection (Edge Gate + Worker JWT Verification)?

  1. 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-Secret service tokens for CI smoke tests.
    • Upon authentication, Cloudflare injects a signed RS256 JWT in the Cf-Access-Jwt-Assertion request header.
  2. 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-Assertion header 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, or ACCESS_REQUIRED) with Cache-Control: private, no-store and X-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:

  1. Startup / Configuration Validation (validateAccessSettings):
    • TEAM_DOMAIN must match /^https:\/\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.cloudflareaccess\.com$/ (e.g., https://slloy.cloudflareaccess.com, no trailing slash).
    • AUD must be a 64-character lowercase hexadecimal Application Audience (AUD) tag (/^[a-f0-9]{64}$/).
    • Configuring only one of TEAM_DOMAIN or AUD is treated as a fatal configuration error.
  2. JWKS Fetching & Rate-Limited Key Refresh (fetchCerts & keyFor):
    • Fetches RSA public keys (kty === "RSA") from ${teamDomain}/cdn-cgi/access/certs (5,000 ms timeout) and imports them for RS256 verification.
    • Caches imported CryptoKeys in isolate memory mapped by kid.
    • When an incoming JWT header contains an unknown kid (e.g., after Cloudflare rotates signing keys), the verifier refreshes /cdn-cgi/access/certs at most once every 60 seconds (certsRefreshIntervalMs = 60_000) and deduplicates concurrent in-flight refreshes. This prevents an attacker from flooding the Worker with fake kid values to DDoS the certs endpoint.
  3. Claims Verification:
    • Header alg === "RS256" and non-empty kid.
    • Cryptographic RS256 signature matches the JWK for kid.
    • iss === teamDomain.
    • aud (string or string array) contains the application's AUD.
    • exp > now and nbf <= now.
  4. Forced Response Headers:
    • Every response served behind an Access gate has Cache-Control: no-store (or private, no-store) and X-Robots-Tag: noindex, nofollow forcefully applied so sensitive content is never stored in shared CDN caches or indexed by crawlers.

3. Surface-by-Surface Configuration Summary

SurfaceZero Trust Application PathWorker Env / SecretsUnauthorized ResponseSpecial Rules
Staging (slloy-staging-api)staging.slloy.com (entire host) + separate Bypass app for staging.slloy.com/api/payments/webhook/stripeSTAGING_ACCESS_TEAM_DOMAIN
STAGING_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_DOMAIN
ADMIN_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_AUD secret on the Worker. If you upload the Worker AUD secret before Cloudflare Edge starts injecting Cf-Access-Jwt-Assertion, the Worker will immediately return HTTP 401 (instead of redirecting to the Cloudflare login screen) for every visitor.

On this page