Status: superseded · ADR-20 · Filed 2026-04-19
Decision
backend/app/main.py always mounts FastAPI’s CORSMiddleware with allowed_origins sourced from PRISM_ALLOWED_ORIGINS via the SPEC-019 resolver. When the allowlist is empty, the middleware enforces default-deny (spec-compliant browser behavior). Cloud mode (PRISM_MODE=cloud) refuses to start if any origin in the allowlist uses plain http:// — https is required. Extends ADR-18 (FQDN discipline) to the browser security plane.
Rationale
Before this ADR, backend/app/main.py had no CORS config at all. That’s accidentally secure (browsers block cross-origin reads when ACAO headers are absent) but indistinguishable from misconfiguration. Intentional default-deny is testable, observable, and survives refactors. Accidental default-deny is a landmine — a future UI integration hits the same browser-block failure mode with zero diagnostic signal; debugging it costs hours (cf. Wave 4B’s FQDN gotcha, same shape of bug: works in Terminal/curl, fails in browser/MCP subprocess). Always-mounted middleware with tiered allowlist makes the posture explicit, logged (provenance line), and part of install-time prompts. Cloud https enforcement is the natural extension: plain http on a public internet origin is never correct for a Bearer-auth API — refusing at install prevents a class of deployment misconfigurations.
Alternatives Considered
(a) Mount CORS only when PRISM_ALLOWED_ORIGINS is non-empty: prior draft; creates two code paths, the default posture is silent, no observability. (b) Wildcard (*) in personal mode: violates Fetch spec when combined with credentials, encourages sloppy security habits, masks real misconfigurations in dev. (c) Middleware per router: duplicates config, hard to audit. (d) Reverse-proxy CORS (nginx/traefik): not applicable to personal mode (no proxy in that deployment); adds infrastructure. (e) Defer until a UI exists (prior recommendation): violates the user’s stated ‘soft application’ principle — does it properly once, tested locally first, not half-scaffolded.
