web-platform-conventionslisted

# Web Platform Conventions Applies to: the web frontend(s) in this repo. Mostly framework-agnostic; the proxy.ts section is Next.js-specific. > Naturalize: confirm the framework/version and where the CSP is built in `CLAUDE.md`. The defaults below assume a same-origin BFF/proxy architecture. ## Content-Security-Policy is a security-critical surface Treat the CSP as code that gates every network origin the page may reach. **Any new XHR/fetch origin, script host, or asset host must be added explicitly.** Never relax a directive to a wildcard to "make it work." ### `connect-src` policy - **Production: `'self'` only** — no `https:` wildcard, no `data:` / `blob:` / `javascript:`. Browser-initiated API calls should go through a same-origin BFF/proxy (e.g. `/api/proxy/*`), so `'self'` covers them. - Auth flows that navigate the browser to another origin (OAuth login/callback) use `window.location` navigations, which are governed by `form-action` / navigation directives, **not** `connect-src`. - Development may add `ws:` / `wss:` for the dev server's hot-reload. ### Before adding a new third-party SDK / analytics / external API 1. Add the **explicit origin** to `connect-src` (e.g. `https://browser.sentry-cdn.com`). Do NOT relax to `https:`. 2. If the SDK loads a script, also add the script host to `script-src`. 3. Add a test asserting both that the new origin is present **and** that the old strictness is preserved (no wildcard regression). 4. Smoke-test in dev — open DevTools