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
- 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_headersat the root ofdist/, the file Netlify and Cloudflare Pages read headers from. The header form addsframe-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 amodules/folder also gets'wasm-unsafe-eval'`, which lets WebAssembly compile and nothing else.
- **A project configures it in
duolith.yaml**, undersecurity: content-security-policy:: A setting that would write a policy the browser reads differently from what was meant is E0550 and the build stops: aduolith.yamlthat is not YAML, an unknown key undersecurity, 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'ssrc, the address given toapi(),stream(),httpTransport(),fetch,new WebSocketornew EventSource, a stylesheet'surl()) 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 inscript-src,'self' 'unsafe-inline'instyle-src, each starting fromdefault-srcwhen left out), so a written policy can never blank the app and never needs hand-written hashes that break on upgrade; offwrites none.
- a group of directives adds sources to the default (
- 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.
- 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
| Option | Why not |
|---|---|
| No policy; document how to write one | Almost 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 response | Needs 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 default | Reports 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-srcand so on, or the browser blocks the call and logs why.examples/dataadds 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.mdgives, is now checked by a test, so it cannot drift from the script. - Hosts that ignore
_headersstill get the<meta>policy; onlyframe-ancestorsis lost there, and the guide says how to send it from other hosts. - Mik to confirm: the default sources,
'unsafe-inline'for styles, and whetheroffshould exist at all.