HQBase Cloudflare Auth

Public AGPL redirect relay for HQBase's verified Cloudflare OAuth client at auth.hqbase.io.

The customer-owned HQBase Worker creates the PKCE verifier and exchanges the authorization code directly with Cloudflare. This relay validates an allowed customer callback, signs expiring state, shows the exact destination before consent, redirects to Cloudflare, and relays the returned code. The authorization code passes through the relay callback, but the relay never exchanges it, receives OAuth access or refresh tokens, or calls a customer API.

Initial setup, domain changes, and signed updates use /oauth/authorize and /oauth/callback. Each operation maps to a fixed callback path and least-privilege scope set:

• setup → /api/setup/cloudflare/oauth/callback
• domains → /api/domains/cloudflare/oauth/callback
• updates → /api/updates/cloudflare/oauth/callback

Callers cannot supply client IDs, redirect URIs, callback paths, or OAuth scopes.

Set OAUTH_STATE_SECRET with wrangler secret put. Register https://auth.hqbase.io/oauth/callback as the public PKCE client redirect URI.

Security boundary

• OAUTH_STATE_SECRET is the only relay secret. Use at least 32 random bytes and never commit it.
• The public client ID, redirect URI, and operation scopes are non-secret configuration.
• Automatic invocation URL logs are disabled because Cloudflare returns the authorization code in the callback query.
• Relay responses are not cached or transformed, preserve only the origin for the same-origin confirmation POST, cannot be framed, and permit form navigation only through the relay to Cloudflare's dashboard. Cloudflare edge features must not inject analytics scripts into relay HTML.
• Continuation requires exact origin, signed expiring state, and a deliberate same-origin browser navigation. A matching host-bound cookie strengthens the handoff when browser privacy policy returns it, but suppressing that cookie does not break the confirmation action.
• The originating HQBase Worker owns the PKCE verifier, token exchange, temporary encrypted grant, Cloudflare API calls, and revocation.

Organizations that block public OAuth applications do not need this relay. HQBase supports a private customer-managed OAuth client that redirects directly to the customer Worker.

Run your own relay

1. Create a Cloudflare OAuth client using Authorization Code, PKCE, and token endpoint authentication method none.

2. Register your relay's exact /oauth/callback HTTPS URL and configure the fixed operation scope sets in wrangler.jsonc.

3. Generate a state secret and set it interactively:

   pnpm exec wrangler secret put OAUTH_STATE_SECRET

4. Run pnpm check and pnpm deploy:dry-run, then deploy from your own protected environment.

5. Compile your relay URL, client ID, and redirect URI into your HQBase fork's product configuration.

Delivery

Pull requests and main run the complete quality gate and Wrangler dry-run. A successful main workflow deploys the relay through the protected production GitHub Environment and verifies https://auth.hqbase.io/health. Local pnpm deploy is reserved for incident recovery.

Forks run the quality job but cannot trigger the HQBase production deployment.

License

HQBase Cloudflare Auth is free software under AGPL-3.0-only. See LICENSE.