Duolith docs

0150. A strict Content-Security-Policy on every web build

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), approved by Mik on 16 Nov 2026 as a product default
  • Planning item: none (v1 gap audit, domain G: security basics)

Context

A web build is static files a team puts on any host. Without a Content-Security-Policy, a single injected <script> (from a compromised dependency, a stored comment rendered as HTML by mistake, or a hostile browser extension's page) runs with the app's full rights: it can read the session the sign-in effect keeps, call the app's API and post anywhere. The framework controls every byte of the app shell, so it can write a policy that allows exactly what it emits and nothing else, which almost no team writes by hand.

What the shell needs: its own modules from the same origin; two or three small inline scripts (the one that starts the router, the colour-scheme script that runs before the first paint, and the live-reload hook under duolith dev), whose text is fixed; inline <style> elements, since each screen's styles are inlined for the first paint and the router adds later screens' styles; images from the app and blob:/data: URLs (the image cache and the camera effect make them); and WebAssembly when the project has Rust modules (decision 0078).

Decision

  1. Every web build writes a strict policy, as a <meta http-equiv="Content-Security-Policy"> in each copy of the app shell (before any script) and as _headers at the root of dist/, the file Netlify and Cloudflare Pages read headers from. The header form adds frame-ancestors 'none', which only a header can carry. ``text default-src 'self'; script-src 'self' 'sha256-<each inline script>'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; media-src 'self' blob:; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self' ` Inline scripts are allowed only by the SHA-256 of the shell's own, computed at build time (crates/emit-web/src/security.rs). There is no 'unsafe-inline' for scripts and no 'unsafe-eval'. A project with a modules/ folder also gets 'wasm-unsafe-eval'`, which lets WebAssembly compile and nothing else.
  1. **A project configures it in duolith.yaml**, under security: content-security-policy:: A setting that would write a policy the browser reads differently from what was meant is E0550 and the build stops: a duolith.yaml that is not YAML, an unknown key under security, a directive no browser knows, a source that is not text or holds a space, ; or ,, a keyword without its quotes, 'unsafe-inline' for scripts (ignored next to hashes), a hash or nonce for styles, and a written policy over several lines. An address of another site the build can see written as text (an image's src, the address given to api(), stream(), httpTransport(), fetch, new WebSocket or new EventSource, a stylesheet's url()) that the policy does not allow is E0551, so a blocked request fails the build rather than the screen.
    • a group of directives adds sources to the default (connect-src: [https://api.example.com]), which is what almost every app needs for its API, image host or analytics endpoint;
    • a policy written out on one line replaces the default, with what the shell needs to start merged in ('self' and the inline scripts' hashes in script-src, 'self' 'unsafe-inline' in style-src, each starting from default-src when left out), so a written policy can never blank the app and never needs hand-written hashes that break on upgrade;
    • off writes none.
  1. Inline styles stay allowed. Hashing every screen's styles is possible for the first paint but not for the styles the router adds at run time, and a nonce needs a server. CSS injection is a far smaller risk than script injection, and the policy still blocks every script it carries.
  1. Native builds have no policy: there is no web view and no HTML on native (decision 0045), so nothing in the bundle is a page a browser parses.

Alternatives considered

OptionWhy not
No policy; document how to write oneAlmost nobody does, and the hashes of the shell's scripts change with the framework, so a hand-written policy breaks on upgrade
Move the inline scripts to files and use script-src 'self'The colour-scheme script must run before the stylesheet applies; a blocking external script costs a request on the first paint. Hashes cost nothing
A nonce per responseNeeds a server to make one per request; a web build is static files
'strict-dynamic'Only helps with nonces or hashes that load further scripts; the shell's modules load by URL from 'self' already
Report-only by defaultReports go nowhere without an endpoint; a policy that blocks is the point

Consequences

  • An app that calls another origin (its API, a CDN for images, an analytics endpoint) must add it under connect-src, img-src and so on, or the browser blocks the call and logs why. examples/data adds its mock server this way. The guide (docs/guide/security.md) says so first.
  • A third-party script tag is refused unless the project adds its origin to script-src; that is intended.
  • The colour-scheme script's hash, which docs/guide/styling.md gives, is now checked by a test, so it cannot drift from the script.
  • Hosts that ignore _headers still get the <meta> policy; only frame-ancestors is lost there, and the guide says how to send it from other hosts.
  • Mik to confirm: the default sources, 'unsafe-inline' for styles, and whether off should exist at all.