Content Security Policy (CSP)

TL;DR

CSP is a response header that tells the browser “only execute scripts/styles/etc. from these sources.” Even if XSS injects a <script>, the browser refuses to execute it if the source isn’t allowed. The senior knowledge: how directives work, nonce vs hash vs 'self', the killer footgun ('unsafe-inline' + 'unsafe-eval'), how to roll out via report-only mode, and how it interacts with Trusted Types for an even stronger XSS posture.

In depth

What does CSP look like, basically?

Response header listing allowed sources per resource type:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.example.com 'nonce-abc123';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' https://api.example.com;
  frame-ancestors 'none';

Effect:

• Scripts may load from 'self' (same origin), cdn.example.com, or inline scripts with nonce="abc123".
• Styles may load from 'self' or inline.
• Images may load from 'self', data URLs, or any HTTPS origin.
• API calls (XHR, fetch, WebSocket) only to 'self' or api.example.com.
• This page can’t be framed (anti-clickjacking).

Any other source → browser blocks the request (or refuses to execute, for inline).

Common directives.

default-src 'self'; object-src 'none'; base-uri 'self' is a solid minimal baseline. Then add per-resource as needed.

Source list keywords — 'self', 'none', 'unsafe-inline', 'unsafe-eval'.

• 'self' — same origin (scheme + host + port).
• 'none' — nothing allowed.
• 'unsafe-inline' — allow inline <script>, style=, event handlers. Defeats most of CSP for that resource.
• 'unsafe-eval' — allow eval, Function(). Some old libs need it.
• data: — data: URLs (for images/fonts).
• https: — any HTTPS origin.
• 'wasm-unsafe-eval' — allow WebAssembly compilation (modern WASM apps).

The senior tell: 'unsafe-inline' in script-src makes CSP cosmetic. XSS still works. The whole point of CSP for XSS defense is blocking inline scripts — 'unsafe-inline' undoes it.

nonce and hash — the inline-script escape hatches.

When you genuinely need inline scripts (analytics snippets, hydration data, SSR’d state), use nonce or hash instead of 'unsafe-inline'.

Nonce: server generates a random value per request, includes in CSP header AND in the nonce attribute of each allowed inline script:

Content-Security-Policy: script-src 'nonce-abc123' 'self'

<script nonce="abc123">window.__INITIAL_DATA__ = {...};</script>

The browser executes only <script> tags with the matching nonce. Attackers don’t know the nonce; injected scripts have no nonce; blocked.

Hash: include a SHA-256/384/512 hash of the script’s exact content. The browser computes the hash of each inline script; matches → allowed.

Content-Security-Policy: script-src 'sha256-Ed7K...x4='

Use nonce for dynamic inline content (per-request). Use hash for static, build-time inline scripts.

strict-dynamic — modern recommended.

'strict-dynamic' tells the browser: “trust this nonce/hash’d script, and any scripts it loads dynamically.” Lets a nonce’d loader script include other scripts without listing each.

Content-Security-Policy: script-src 'nonce-abc123' 'strict-dynamic' 'unsafe-inline' https:

(The 'unsafe-inline' and https: are fallbacks for browsers that don’t support 'strict-dynamic'; modern browsers ignore them when 'strict-dynamic' is present.)

This is the recommended modern pattern for SPAs that load chunks dynamically (Next.js, Vite). Without 'strict-dynamic', every chunk URL has to be in the source list.

How do you roll out CSP without breaking things?

Content-Security-Policy-Report-Only — the browser reports violations but doesn’t block:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri /csp-report

The browser POSTs JSON violation reports to /csp-report. You collect, analyze, iterate the policy. When violations are zero (or only attacks), flip to enforcing Content-Security-Policy.

This is mandatory for any real app — CSP affects every page, and one wrong directive can block half your assets. Roll out via report-only over weeks; switch to enforcement only when reports are clean.

report-uri vs report-to.

• report-uri — older, simple POST endpoint. Widely supported.
• report-to — newer, uses the Reporting API (Reporting-Endpoints header). More flexible. Less universal.

In practice, set both:

Reporting-Endpoints: csp-endpoint="/csp-report"
Content-Security-Policy:
  default-src 'self';
  report-uri /csp-report;
  report-to csp-endpoint;

Use a CSP reporting service (Sentry, Report URI, Datadog) to aggregate — raw reports are noisy.

CSP for SPAs — what’s tricky?

• Inline scripts for hydration data (__NEXT_DATA__, __NUXT__) need nonces/hashes per page. Frameworks auto-emit these.
• Dynamic chunks loaded by the bundler — list with 'strict-dynamic' or by exact URLs.
• HMR in dev uses inline scripts + eval; relax CSP in dev, tighten in prod.
• Third-party scripts (analytics, ads) — list each origin in script-src. Bigger third-party surface = bigger CSP.
• Style-in-JS / Emotion / styled-components — emit inline <style> tags. Use 'unsafe-inline' in style-src OR (better) hash-based or nonce-based styles. Some libraries support hash; check.

For a modern Next.js SPA:

Content-Security-Policy:
  default-src 'self';
  script-src 'nonce-{{NONCE}}' 'strict-dynamic';
  style-src 'self' 'nonce-{{NONCE}}';
  img-src 'self' data: https:;
  font-src 'self';
  connect-src 'self' https://api.example.com;
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';
  report-to csp-endpoint;

What’s Trusted Types and how does it pair with CSP?

Trusted Types blocks dangerous DOM sinks (innerHTML, script.src, etc.) from accepting raw strings — they must be wrapped in a trusted type via a “policy.”

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types my-sanitizer

const policy = trustedTypes.createPolicy("my-sanitizer", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

el.innerHTML = policy.createHTML(userHtml);   // ok
el.innerHTML = userHtml;                       // throws TypeError

This catches DOM-based XSS even when an attacker bypasses output encoding — they can’t write to innerHTML without going through a policy that sanitizes.

Chrome/Edge only currently; polyfills exist. Adoption is growing.

Common CSP mistakes.

• script-src 'unsafe-inline' — defeats CSP for XSS defense.
• script-src * — allows any origin. Useless.
• Forgetting object-src 'none' — old Flash/<object> attacks.
• frame-ancestors 'none' missing — clickjacking risk.
• base-uri 'self' missing — <base href> can hijack relative URLs.
• Not reporting — you don’t know what’s failing in real users’ browsers.
• Different policies in dev vs prod without testing — CSP issues only appear in prod.

Gotchas / edge cases

• <meta http-equiv="Content-Security-Policy"> — fallback when you can’t set headers. Limited (some directives ignored, like frame-ancestors). Always prefer the header.
• Service worker fetches — bypass CSP for the response itself, but the cached responses still execute under CSP.
• iframe srcdoc= content — child inherits parent CSP plus its own restrictions.
• Browser extensions can inject scripts; CSP doesn’t block extensions (intentional — they’re “trusted by user”).
• CSP and Stripe / third-party widgets — these often need unsafe-inline for their iframes. Read each provider’s CSP guidance.
• Reporting noise — extensions, browser quirks, ad blockers all generate reports. Filter aggressively.

Cross-references

• XSS (CSP defends against it): XSS — Stored, Reflected, DOM-Based
• Security headers (CSP is one of many): Subresource Integrity, HSTS, Security Headers

Further reading

• MDN — CSP: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
• CSP Reference (directive cheat sheet): https://content-security-policy.com/
• web.dev — Strict CSP: https://web.dev/articles/strict-csp
• Trusted Types: https://web.dev/articles/trusted-types