Staff Sites Basic Auth Gate

Staff Sites Lightweight Basic Password Gate & Zero Trust Cutover

1. Architectural Overview & Context

Internal staff applications (such as apps/command-center and internal documentation or staging environments) require immediate protection against search engine crawlers, automated vulnerability scanners, and unauthenticated public indexing.

This write-up captures the lightweight HTTP Basic Authentication gate implemented in @siteswarm/governance/security and integrated into staff surfaces as part of Epic #555 (Cloudflare Zero Trust perimeter and access governance for staff surfaces) and Issue #554.

Incoming Request
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ Exemption Seam Check                                   │
│  - /api/health, /health                                │
│  - /_astro/*, /assets/*, /favicon.*, /robots.txt       │
└──────┬─────────────────────────────────────────────────┘
       │
       ├─► [Exempt Path] ───────────────► Forward to Route Handler (HTTP 200 OK)
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ Cloudflare Zero Trust Check                            │
│  - Header: Cf-Access-Jwt-Assertion                     │
└──────┬─────────────────────────────────────────────────┘
       │
       ├─► [Assertion Present] ─────────► Zero Trust Cutover Bypass
       │                                  Validate RS256 JWT & Enforce RBAC
       ▼
┌────────────────────────────────────────────────────────┐
│ HTTP Basic Auth Credential Challenge                   │
│  - Header: Authorization: Basic <base64>               │
│  - Config: STAFF_GATE_USER / STAFF_GATE_PASSWORD       │
│  - Default: admin / admin                              │
└──────┬─────────────────────────────────────────────────┘
       │
       ├─► [Valid Credentials] ─────────► Establish Staff Session (Role: Admin)
       │
       └─► [Missing / Invalid] ─────────► HTTP 401 Unauthorized
                                          WWW-Authenticate: Basic realm="..."

2. Target Components & Modular Seams

Shared Security Seam (@siteswarm/governance/security):
- packages/governance/src/security/staff-gate.ts: Core edge-compatible verification functions (evaluateStaffGate, handleStaffGate, timingSafeEqualString, parseBasicAuthHeader, createStaffGateChallengeResponse).
- Constant-time string comparison avoids timing side-channel attacks.
- Zero-exception safe Base64 parsing guards edge isolates against unhandled 500 crashes on malformed input.
Application Middleware (apps/command-center/src/middleware.ts):
- Pure Astro SSR middleware delegating to handleCommandCenterMiddleware.
- Populates authenticated staff identity (context.locals.user, context.locals.role) upon successful credential verification.

3. Configuration & Secrets Reference

The gate defaults to admin / admin for local development and preview environments, and can be customized via environment variables or Cloudflare Worker secrets:

Variable	Type	Default	Description
`STAFF_GATE_USER`	String	`admin`	Expected username for HTTP Basic Auth
`STAFF_GATE_PASSWORD`	String	`admin`	Expected password for HTTP Basic Auth
`STAFF_GATE_ENABLED`	Boolean string (`true`/`false`)	`true`	When set to `false`, the basic password gate is bypassed

4. Synthetic Health Probe Exemption Seams

Automated deployment health checks, Cloudflare Health Checks, and synthetic monitoring probes (e.g. /api/health) must never be challenged with HTTP 401 or fail during edge deploys (resolving #474 deployment failure hazards).

The following paths and prefixes are exempt by default:

/api/health
/health
/_astro/*
/assets/*
/favicon.*
/robots.txt
/sitemap.xml

5. Cutover & Decommissioning Path

Once Cloudflare Zero Trust (Cloudflare Access / IdP) is fully provisioned in front of staff sites (#520, #342), the basic password gate transitions through two clean operational phases:

Phase 1: Zero Trust Assertion Bypass (Zero-Downtime Transition)

When traffic routes through Cloudflare Access, Cloudflare automatically injects the cryptographic assertion header Cf-Access-Jwt-Assertion.
The staff gate detects this header and skips the basic password challenge (reason: "zero_trust_bypass").
The downstream Cloudflare Access engine (authenticateAccessRequest) verifies the RS256 signature against the Cloudflare JWKS endpoint and enforces route-level RBAC per ADR-0004 §6.1.
Direct traffic attempting to circumvent Cloudflare Access is stopped by the basic password challenge.

Phase 2: Full Decommissioning

When Cloudflare Access is universally enforced at DNS / Cloudflare zone boundaries:

Set STAFF_GATE_ENABLED=false in environment secrets or remove the basic auth challenge step in apps/command-center/src/lib/middleware-handler.ts.
The middleware relies solely on authenticateAccessRequest for Zero Trust perimeter authentication.

6. Decisions Intentionally Deferred

Cloudflare Access IdP Account Sync (#520): Deferring identity-provider SAML/OIDC user sync until Cloudflare Zero Trust IdP accounts are connected.
Session Storage & Encrypted Cookies: Storing authenticated staff sessions in encrypted cookies or D1 session stores is deferred; this gate operates as an ephemeral HTTP challenge for bot filtering.
Public Client Surface Deployment: Deploying basic auth gates to public client apps (e.g. bakery, auto repair) is out of scope and deferred; only internal staff surfaces are gated.