Security
What the build does to keep an app safe, and what is left to you. The short version: every web build ships a strict Content-Security-Policy, markup can never become HTML, type checks cannot be switched off, secrets belong in secure storage or on your server, and duolith scan tells you what each dependency does on each target.
The Content-Security-Policy
Every duolith build writes a policy into each HTML file it makes, as a <meta http-equiv="Content-Security-Policy"> before any script, and into dist/_headers, which Netlify and Cloudflare Pages send as a response header (decision 0150):
default-src 'self'; script-src 'self' 'sha256-…'; 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'
The header also carries frame-ancestors 'none', so no other site can frame the app. The sha256- sources are the hashes of the app shell's own inline scripts (starting the router, the colour-scheme and platform-look scripts, the DUOLITH_PUBLIC_* environment values, and, unless the build has --no-optimize, the import map), worked out at build time, so the policy allows those scripts and no other inline script. There is no 'unsafe-eval'. A project with Rust modules also gets 'wasm-unsafe-eval', which lets WebAssembly compile and nothing more.
Letting the app reach another origin
The default allows only the app's own origin. An app that calls an API, loads images from a CDN or sends analytics elsewhere lists those origins in duolith.yaml; they are added to the default:
security:
content-security-policy:
connect-src: [https://api.example.com, wss://live.example.com]
img-src: [https://images.example.com]
Each source is its own item. connect-src covers fetch, api(), stream()'s event sources and web sockets, httpTransport() from @duolith/adapters, and analytics beacons; img-src covers images, font-src fonts and media-src audio and video. examples/data lets its pages reach its mock server this way. Keywords keep their single quotes, inside the YAML quotes: script-src: ["'self'", https://cdn.example.com]. A directive that takes no sources is written with true: upgrade-insecure-requests: true.
The build checks the addresses it can see
An address of another site written as text in a page or component, such as <image src="https://images.example.com/cat.png">, api("https://api.example.com"), stream("wss://live.example.com"), httpTransport("https://logs.example.com"), fetch(...), new WebSocket(...) or a url(...) in a style block, is checked against the policy when you build. One the policy does not allow is E0551, with the line to add to duolith.yaml:
pages/index.duo:6:20: error[E0551]: the Content-Security-Policy does not allow requests from https://api.example.com, so browsers would block https://api.example.com
help: Allow it in duolith.yaml:
security:
content-security-policy:
connect-src: [https://api.example.com]
An address built from data, or read with environment(), is only known when the app runs: list its origin yourself, or the browser blocks the request and logs a Refused to connect message naming the directive to change.
Replacing the policy, or turning it off
To replace the policy, write it on one line; to write none, use off:
security:
content-security-policy: "default-src 'self'; connect-src *"
# or
security:
content-security-policy: off
A written policy is yours, except that the build merges in what the app shell needs to start: 'self' and the hashes of its inline scripts in script-src, and 'self' 'unsafe-inline' in style-src. A directive you leave out starts as a copy of your default-src, as browsers read it, so the example above becomes default-src 'self'; connect-src *; script-src 'self' 'sha256-…'; style-src 'self' 'unsafe-inline'. Without that, the browser would refuse the script that starts the router and the page would stay blank. frame-ancestors, report-uri and sandbox only work as a header, so they go into _headers and not the <meta> tag.
Settings the build refuses
The build stops with E0550 on anything the browser would read differently from what was meant. Run duolith explain E0550 for the whole list:
| Setting | Why |
|---|---|
duolith.yaml that is not YAML | The build cannot tell which policy you meant |
security: off, or a key under security other than content-security-policy | A typo would leave the default in place without a word |
conect-src, or any directive no browser knows | Browsers ignore it |
connect-src: [8080], or a list item that is not text | It would be dropped |
script-src: [self] | Without its quotes, self is a host name |
'unsafe-inline' in script-src | Browsers ignore it next to the shell's hashes |
a hash or nonce in style-src | Browsers would then ignore the 'unsafe-inline' the screens' styles need |
a source with a space, ; or ,, a directive written twice, or a written policy over several lines | It would start another source or directive |
Other hosts
A host that does not read _headers still gets the <meta> policy, which protects everything except framing. To forbid framing there too, send the line from dist/_headers as a Content-Security-Policy header in the host's own configuration (for nginx, add_header Content-Security-Policy "…" always;).
Native
There is no web view on iOS or Android, so there is no HTML and no policy: the bundle is code the shell runs, and a link to another site is handed to the platform rather than shown inside the app.
duolith test opens pages under the build's policy and fails a test on any violation of it. A mock written as a function is compiled before the page loads, where the policy does not reach, so mocks keep working; the screenshot suites keep the policy too, and fail on any violation.
Markup never becomes HTML
Text and {expressions} in markup are always text. There is no innerHTML, set:html or dangerouslySetInnerHTML, so a comment or a name typed by a user can never become a script, whatever it contains. A link may only be one of the app's paths or an http:, https:, mailto:, tel: or sms: address: the compiler refuses any other scheme written as text (E0170) and a path the build does not serve (E0353), and the runtime refuses the rest, such as a javascript: address built at run time (decision 0040).
Type checks cannot be switched off
Every build type-checks every page with TypeScript's strictest options (decisions 0096 and 0097) and refuses what would make it skip or trust code it cannot see: @ts-ignore and its kind (E0357), any, eval, new Function and text given to setTimeout (E0358), and declare of something that does not exist (E0359). Data of unknown shape, such as a response body, arrives as unknown, and the page checks its shape before using it.
Secrets
- Nothing in the app is secret. Everything a web build or a native bundle holds can be read by anyone who has it, environment values (
environment()) included. API keys that must stay secret belong on your server. - Tokens the user's session needs go in
secureStoragefrom@duolith/effects: the Keychain on iOS, the Keystore on Android, and on the web AES-GCM with a key kept in IndexedDB that the page cannot read out (decision 0052). Never instorage(key-value storage), which is plain. - Sign-in uses PKCE for Apple and Google and keeps its credentials in secure storage. See effects.md.
Dependencies
duolith scan gives every npm dependency a verdict per target (decision 0073): whether it runs on the web, iOS and Android, and what it reaches for (the DOM, Node built-ins, eval). Run it after adding a package, and read its warnings before shipping. Rust modules are compiled from source in modules/ and checked like the rest of the project.
Privacy declarations
A build writes the App Store privacy manifest and the Play data-safety answers from what the app imports (decision 0051 and production.md). Check them before you submit: the build cannot see what your own server does with the data.
Reporting a problem in the framework
Do not open a public issue for a security problem in Duolith itself; write to the maintainers privately. Until the project has an address for reports, that is Mik.