OAuth test lanes

This page is the configuration reference for the three OAuth lanes: production, staging, and local dev. Each lane has its own OAuth client in each provider, its own session secret, and its own JWT issuer.

The three lanes

Lane	Issuer	Cookie domain	Google client ID	Anthropic	Codex
Production	hivecast.ai	hivecast.ai (per-origin cookie)	<prod-google-client>	local-loopback (any port)	local-loopback (any port)
Staging	staging.hivecast.ai	staging.hivecast.ai	<staging-google-client>	local-loopback (any port)	local-loopback (any port)
Local dev	localhost-dev (or per-developer)	127.0.0.1/localhost	<dev-google-client> (allow http://127.0.0.1:5001/api/auth/callback/google redirect)	local-loopback (any port)	local-loopback (any port)

Cookies do NOT cross lanes (Domain is unset; per-origin only).

Configuration

System-auth config (auth.*) per lane:

# production
auth:
  sessionSecret: <hex-32+ chars>
  issuer: hivecast.ai
  providers:
    google:
      clientId: <prod-google-client-id>
      clientSecret: <prod-google-client-secret>

# staging
auth:
  sessionSecret: <different hex-32+ chars>
  issuer: staging.hivecast.ai
  providers:
    google:
      clientId: <staging-google-client-id>
      clientSecret: <staging-google-client-secret>

# local dev
auth:
  sessionSecret: <hex-32+ chars; per-developer or shared dev secret>
  issuer: localhost-dev
  providers:
    google:
      clientId: <dev-google-client-id>
      clientSecret: <dev-google-client-secret>

The sessionSecret MUST differ across lanes — otherwise tokens minted in one lane could (with luck) verify in another. Lane isolation depends on distinct secrets + distinct issuers.

Provider OAuth client registration

Google

In Google Cloud Console (OAuth 2.0 Client IDs), three separate clients:

Client	Authorized redirect URI	Notes
Production	https://hivecast.ai/api/auth/callback/google	+ JS origin https://hivecast.ai
Staging	https://staging.hivecast.ai/api/auth/callback/google	+ JS origin https://staging.hivecast.ai
Local dev	http://127.0.0.1:5001/api/auth/callback/google	+ JS origin http://127.0.0.1:5001. Google permits http://127.0.0.1 and http://localhost for dev.

GitHub (target state)

Three OAuth Apps. Same shape as Google.

Anthropic

One OAuth app at the provider. Loopback redirect — no per-environment client needed because the OAuth happens device-side, not cloud-side.

Codex (OpenAI)

Same as Anthropic.

What runs in each lane

Production

• https://hivecast.ai serving the platform.
• Real principal data; real Devices link here.
• Real customer billing.
• Don't break things in production.

Staging

• https://staging.hivecast.ai (or whatever URL you configure).
• Test principal accounts only.
• Production-like config but with staging OAuth clients.
• Used for end-to-end pre-release validation.

Local dev

• Two-runtime topology (matrix-web + matrix-edge) inside one Host Service.
• Sibling-Host pairing flow (see Authentication / Local testing).
• Per-developer or shared dev OAuth client, depending on team policy.

Lane isolation testing

To verify lanes don't bleed:

# Sign in to staging, get a cookie:
STAGING_TOKEN=$(curl ... staging.hivecast.ai/api/auth/login/google ...)

# Verify the staging cookie does NOT validate against production:
curl https://hivecast.ai/api/identity/whoami \
  -H "Cookie: mx_session=$STAGING_TOKEN"
# expect: 401 Unauthorized (different secret + different issuer)

The iss check in validateSession() rejects mismatched issuer values even if the secret were shared. Defense in depth: don't share the secret either.

Audit-trail considerations

Production audit logs MUST NOT contain staging or dev events. The lane-specific issuer string and per-lane state files keep this naturally separated. If a unified audit system is built later, it should respect the issuer as a tenant key.

Test user policy

Lane	Real users sign in?
Production	yes
Staging	dedicated test accounts only
Local dev	dedicated test accounts only

Restricting staging/dev to test accounts via Google's hd: parameter or Workspace policy is recommended for organizations using G Suite.

Local-loopback redirect URIs in each lane

Anthropic / Codex / OpenAI loopback OAuth happens on the Device regardless of which HiveCast lane it pairs to. This is a property of no-raw-OAuth-tokens-on-local-host: provider tokens never leave the Device, so there's nothing lane-specific about them.

See also

• Authentication / Staging OAuth — narrative.
• Authentication / Local testing — running auth without any cloud at all.
• Token schema — what makes lanes isolate.

Source: projects/matrix-3/packages/system-auth/src/google-oidc.ts (Google OIDC config); projects/matrix-3/packages/system-auth/src/index.ts (auth config wiring).