ADR-003: Cross-Origin Isolation from Day One

Status: Accepted Date: 2026-01-15

Context

Cross-origin isolation is required for SharedArrayBuffer, which enables WASM multithreading. Without it, SharedArrayBuffer is not available in the browser, and WASM threads cannot share memory. Enabling cross-origin isolation after the fact is disruptive because it restricts how third-party resources can be loaded.

Options Considered

1. Enable cross-origin isolation from day one (chosen)

  • Set COOP/COEP headers on all responses from the start
  • All external resources must use CORS or CORP headers
  • No third-party scripts or resources that don’t support cross-origin

2. Add cross-origin isolation later

  • Start without restrictions
  • Integrate third-party analytics, fonts, and embeds freely
  • Retrofit headers when threading is needed
  • Risk breaking integrations when headers are added

Decision

All SiliconGhetto web deployments — the website, docs, and all game hosting — ship with cross-origin isolation headers from day one:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Consequences

Positive

  • SharedArrayBuffer available immediately for WASM threading
  • performance.measureUserAgentSpecificMemory() available for memory profiling
  • High-resolution timers available (not restricted by Spectre mitigations)
  • No future migration pain — architecture is isolation-ready from the start

Negative

  • Cannot embed cross-origin resources without CORS/CORP headers
  • Third-party analytics scripts (Google Analytics, etc.) may not work
  • External images and fonts need explicit CORS configuration
  • iframe embeds from other origins are restricted

Mitigations

  • Self-host all assets (fonts, images, scripts)
  • Use privacy-respecting, self-hosted analytics if needed
  • Document CORS requirements for any future CDN or external asset integration
  • Provide clear error messages when resources fail due to CORP/CORS

Impact on Deployment

Every reverse proxy configuration (nginx, caddy) must include these headers. The deployment scripts and CI checks verify header presence. See the reverse proxy configs and deployment reference.

References