@alxia/secure-headers 0.1.1 → 0.2.0

package/README.md

@@ -21,6 +21,54 @@ app.use(secureHeaders({ contentSecurityPolicy: "default-src 'self'", xFrameOptio
 A header a route sets itself is kept: a page that needs its own policy sets
 it on its reply.
 
+## A nonce per request
+
+`nonce: true` makes a fresh nonce for each request (128 random bits,
+base64), puts it in the policy as `'nonce-…'`, and gives it to the routes
+declared after the plugin as `ctx.nonce`. The header and the context always
+carry the same one, so a page's inline scripts need no `'unsafe-inline'`.
+
+```ts
+import { alxia } from '@alxia/core';
+import { secureHeaders } from '@alxia/secure-headers';
+
+const app = alxia()
+	.use(
+		secureHeaders({
+			nonce: true,
+			// The nonce is added to script-src (and script-src-elem).
+			contentSecurityPolicy: "default-src 'self'; script-src 'self'",
+		}),
+	)
+	.get('/', ({ nonce, reply }) =>
+		reply(200, `<script nonce="${nonce}">console.log('allowed')</script>`, {
+			headers: { 'content-type': 'text/html' },
+		}),
+	);
+// content-security-policy: default-src 'self'; script-src 'self' 'nonce-3q2+7w…=='
+```
+
+To place it yourself, in `style-src` say, write `NONCE` where it goes;
+each occurrence becomes the request's `'nonce-…'`, and `script-src` is then
+left as written:
+
+```ts
+import { NONCE, secureHeaders } from '@alxia/secure-headers';
+
+app.use(
+	secureHeaders({
+		nonce: true,
+		contentSecurityPolicy: `default-src 'self'; script-src 'self' ${NONCE}; style-src 'self' ${NONCE}`,
+	}),
+);
+```
+
+A policy with nowhere to put the nonce (no `script-src`, no `NONCE`) is
+refused at startup, the default policy included: give `contentSecurityPolicy`
+with `nonce: true`. Without `nonce: true`, the headers are what they always
+were. With `@alxia/react-router`, `nonceOf(loadContext)` hands it to
+`entry.server.tsx` ([its README](https://github.com/softistx/alxia/tree/develop/packages/react-router#a-csp-nonce)).
+
 ## Defaults
 
 | header | default | option |
@@ -39,19 +87,22 @@ it on its reply.
 | `Permissions-Policy` | not sent | `permissionsPolicy` |
 
 Each option takes a value, or `false` to leave the header out; an empty
-value is refused at startup.
+value is refused at startup. `nonce` is off by default.
 `X-Powered-By` and `Server` are removed unless `hidePoweredBy: false`.
 
 ## API
 
 | export | |
 | --- | --- |
-| `secureHeaders(options?)` | the plugin |
-| `SecureHeadersOptions` | its options |
+| `secureHeaders(options?)` | the plugin: a function `Plugin`, or with `nonce: true` a `NoncePlugin` |
+| `SecureHeadersOptions` | its options: the headers and `hidePoweredBy`; `nonce` is added by each overload |
 | `Setting` | a header option's type: its value, or `false` to leave it out |
+| `NONCE` | where the nonce goes in `contentSecurityPolicy`, each time it is named |
+| `NonceContext` | what `nonce: true` adds to the context: `nonce`, a string |
+| `NoncePlugin` | what `secureHeaders({ nonce: true })` returns: an app plugin adding `NonceContext` |
 
 ## Documentation
 
-- [Guide](https://github.com/softistx/alxia/tree/develop/packages/secure-headers/docs): every option and its default, which responses get the headers, a page's own policy, the order with other hooks, and recipes.
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/secure-headers/docs): every option and its default, the per-request nonce, which responses get the headers, a page's own policy, the order with other hooks, and recipes.
 - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/secure-headers/docs/troubleshooting.md): an error message or a browser refusal, and what to do about it.
 - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/secure-headers/docs/roadmap.md): what is coming, and what is not planned.

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { type SecureHeadersOptions, type Setting, secureHeaders, } from './secure-headers';
+export { NONCE, type NonceContext } from './nonce';
+export { type NoncePlugin, type SecureHeadersOptions, type Setting, secureHeaders, } from './secure-headers';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,aAAa,GACb,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,aAAa,GACb,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,5 +1,37 @@
+// src/nonce.ts
+var NONCE = "'nonce-{alxia}'";
+var SCRIPT_DIRECTIVES = new Set(["script-src", "script-src-elem"]);
+function policyWithNonce(policy) {
+  const placed = policy.includes(NONCE) ? policy : policy.split(";").map((directive) => {
+    const name = directive.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    return SCRIPT_DIRECTIVES.has(name) ? `${directive.trimEnd()} ${NONCE}` : directive;
+  }).join(";");
+  if (!placed.includes(NONCE)) {
+    throw new TypeError(`secureHeaders: nonce is on, but the content-security-policy has no script-src to add it to: write one, or place NONCE where the nonce goes (the policy is "${policy}")`);
+  }
+  const parts = placed.split(NONCE);
+  return (nonce) => parts.join(`'nonce-${nonce}'`);
+}
+function freshNonce() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return btoa(String.fromCharCode(...bytes));
+}
+function nonceStore() {
+  const nonces = new WeakMap;
+  return (url) => {
+    let nonce = nonces.get(url);
+    if (nonce === undefined) {
+      nonce = freshNonce();
+      nonces.set(url, nonce);
+    }
+    return nonce;
+  };
+}
 // src/secure-headers.ts
-import { withHeaders } from "@alxia/core";
+import {
+  definePlugin,
+  withHeaders
+} from "@alxia/core";
 var DEFAULTS = {
   "content-security-policy": "default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
   "strict-transport-security": "max-age=31536000; includeSubDomains",
@@ -29,7 +61,28 @@ var OPTION = {
   "permissions-policy": "permissionsPolicy"
 };
 function secureHeaders(options = {}) {
-  const headers = [];
+  const headers = fixedHeaders(options);
+  const hide = options.hidePoweredBy ?? true;
+  const policy = headers.get("content-security-policy");
+  if (!options.nonce) {
+    if (policy?.includes(NONCE)) {
+      throw new TypeError("secureHeaders: contentSecurityPolicy names NONCE, but nonce is off: give nonce: true");
+    }
+    const set = setter(headers, hide);
+    return (app) => app.onResponse((response) => set(response));
+  }
+  if (policy === undefined) {
+    throw new TypeError("secureHeaders: nonce is on, but contentSecurityPolicy is false: a nonce is only read through the content-security-policy header");
+  }
+  headers.delete("content-security-policy");
+  const withNonce = policyWithNonce(policy);
+  const nonceOf = nonceStore();
+  const set = setter(headers, hide);
+  const plugin = definePlugin()((app) => app.onResponse((response, ctx) => set(response, withNonce(nonceOf(ctx.url)))).derive(({ url }) => ({ nonce: nonceOf(url) })));
+  return plugin;
+}
+function fixedHeaders(options) {
+  const headers = new Map;
   for (const [name, fallback] of Object.entries(DEFAULTS)) {
     const setting = options[OPTION[name]];
     if (typeof setting === "string" && setting.trim() === "") {
@@ -37,23 +90,29 @@ function secureHeaders(options = {}) {
     }
     const value = setting === undefined ? fallback : setting;
     if (typeof value === "string")
-      headers.push([name, value]);
+      headers.set(name, value);
   }
-  const hide = options.hidePoweredBy ?? true;
-  return (app) => app.onResponse((response) => withHeaders(response, (current) => {
+  return headers;
+}
+function setter(headers, hide) {
+  return (response, policy) => withHeaders(response, (current) => {
     for (const [name, value] of headers) {
       if (!current.has(name))
         current.set(name, value);
     }
+    if (policy !== undefined && !current.has("content-security-policy")) {
+      current.set("content-security-policy", policy);
+    }
     if (hide) {
       current.delete("x-powered-by");
       current.delete("server");
     }
-  }));
+  });
 }
 export {
+  NONCE,
   secureHeaders
 };
 
-//# debugId=DD4A7A8B39A4596664756E2164756E21
+//# debugId=3F73DEF9D20E37B064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/secure-headers.ts"],
+  "sources": ["../src/nonce.ts", "../src/secure-headers.ts"],
   "sourcesContent": [
-    "import { type Plugin, withHeaders } from '@alxia/core';\n\n/** A header's value, or `false` to leave it out. An empty value is refused. */\nexport type Setting = string | false;\n\nexport interface SecureHeadersOptions {\n\t/** Defaults to a policy for an API: nothing loads, nothing frames it. */\n\treadonly contentSecurityPolicy?: Setting;\n\treadonly strictTransportSecurity?: Setting;\n\treadonly xContentTypeOptions?: Setting;\n\treadonly xFrameOptions?: Setting;\n\treadonly referrerPolicy?: Setting;\n\treadonly crossOriginOpenerPolicy?: Setting;\n\treadonly crossOriginResourcePolicy?: Setting;\n\treadonly crossOriginEmbedderPolicy?: Setting;\n\treadonly originAgentCluster?: Setting;\n\treadonly xDnsPrefetchControl?: Setting;\n\treadonly xPermittedCrossDomainPolicies?: Setting;\n\t/** Off by default: a policy is the app's to write. */\n\treadonly permissionsPolicy?: Setting;\n\t/** Whether `X-Powered-By` and `Server` are removed. On by default. */\n\treadonly hidePoweredBy?: boolean;\n}\n\nconst DEFAULTS = {\n\t'content-security-policy':\n\t\t\"default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'\",\n\t'strict-transport-security': 'max-age=31536000; includeSubDomains',\n\t'x-content-type-options': 'nosniff',\n\t'x-frame-options': 'DENY',\n\t'referrer-policy': 'no-referrer',\n\t'cross-origin-opener-policy': 'same-origin',\n\t'cross-origin-resource-policy': 'same-origin',\n\t'cross-origin-embedder-policy': false,\n\t'origin-agent-cluster': '?1',\n\t'x-dns-prefetch-control': 'off',\n\t'x-permitted-cross-domain-policies': 'none',\n\t'permissions-policy': false,\n} as const satisfies Record<string, Setting>;\n\nconst OPTION: Record<keyof typeof DEFAULTS, keyof SecureHeadersOptions> = {\n\t'content-security-policy': 'contentSecurityPolicy',\n\t'strict-transport-security': 'strictTransportSecurity',\n\t'x-content-type-options': 'xContentTypeOptions',\n\t'x-frame-options': 'xFrameOptions',\n\t'referrer-policy': 'referrerPolicy',\n\t'cross-origin-opener-policy': 'crossOriginOpenerPolicy',\n\t'cross-origin-resource-policy': 'crossOriginResourcePolicy',\n\t'cross-origin-embedder-policy': 'crossOriginEmbedderPolicy',\n\t'origin-agent-cluster': 'originAgentCluster',\n\t'x-dns-prefetch-control': 'xDnsPrefetchControl',\n\t'x-permitted-cross-domain-policies': 'xPermittedCrossDomainPolicies',\n\t'permissions-policy': 'permissionsPolicy',\n};\n\n/**\n * Secure headers on every response, as a plugin. A header a route set\n * itself is kept: a page that needs its own `Content-Security-Policy` —\n * `@alxia/openapi`'s reference page — sets it.\n *\n * ```ts\n * app.use(secureHeaders({ contentSecurityPolicy: \"default-src 'self'\" }));\n * ```\n */\nexport function secureHeaders(options: SecureHeadersOptions = {}): Plugin {\n\tconst headers: [string, string][] = [];\n\tfor (const [name, fallback] of Object.entries(DEFAULTS) as [\n\t\tkeyof typeof DEFAULTS,\n\t\tSetting,\n\t][]) {\n\t\tconst setting = options[OPTION[name]];\n\t\tif (typeof setting === 'string' && setting.trim() === '') {\n\t\t\t// An empty header says nothing a browser can act on: leave it out.\n\t\t\tthrow new TypeError(\n\t\t\t\t`secureHeaders: ${OPTION[name]} is empty; give false to leave the ${name} header out`,\n\t\t\t);\n\t\t}\n\t\tconst value = setting === undefined ? fallback : setting;\n\t\tif (typeof value === 'string') headers.push([name, value]);\n\t}\n\tconst hide = options.hidePoweredBy ?? true;\n\treturn (app) =>\n\t\tapp.onResponse((response) =>\n\t\t\twithHeaders(response, (current) => {\n\t\t\t\tfor (const [name, value] of headers) {\n\t\t\t\t\tif (!current.has(name)) current.set(name, value);\n\t\t\t\t}\n\t\t\t\tif (hide) {\n\t\t\t\t\tcurrent.delete('x-powered-by');\n\t\t\t\t\tcurrent.delete('server');\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n}\n"
+    "/**\n * The per-request nonce of `secureHeaders({ nonce: true })`: where it goes\n * in the policy, how one is made, and how the context and the header read\n * the same one.\n */\n\n/**\n * Where the nonce goes in `contentSecurityPolicy`: each occurrence becomes\n * `'nonce-<value>'`, the request's own value. Without it, `nonce: true`\n * adds the nonce to `script-src` and `script-src-elem`.\n *\n * ```ts\n * secureHeaders({\n *   nonce: true,\n *   contentSecurityPolicy: `default-src 'self'; style-src 'self' ${NONCE}`,\n * });\n * ```\n */\nexport const NONCE = \"'nonce-{alxia}'\";\n\n/** What `secureHeaders({ nonce: true })` adds to the context of the routes after it. */\nexport interface NonceContext {\n\t/**\n\t * This request's nonce, base64, the one its `Content-Security-Policy`\n\t * allows: what a page puts on its `<script nonce>`.\n\t */\n\treadonly nonce: string;\n}\n\n/** The directives the nonce is added to when the policy does not place it. */\nconst SCRIPT_DIRECTIVES = new Set(['script-src', 'script-src-elem']);\n\n/**\n * The policy as a function of the nonce: split where `NONCE` stands, or\n * where it is added to the script directives. Throws when there is\n * nowhere to put it.\n */\nexport function policyWithNonce(policy: string): (nonce: string) => string {\n\tconst placed = policy.includes(NONCE)\n\t\t? policy\n\t\t: policy\n\t\t\t\t.split(';')\n\t\t\t\t.map((directive) => {\n\t\t\t\t\tconst name = directive.trim().split(/\\s+/)[0]?.toLowerCase() ?? '';\n\t\t\t\t\treturn SCRIPT_DIRECTIVES.has(name)\n\t\t\t\t\t\t? `${directive.trimEnd()} ${NONCE}`\n\t\t\t\t\t\t: directive;\n\t\t\t\t})\n\t\t\t\t.join(';');\n\tif (!placed.includes(NONCE)) {\n\t\tthrow new TypeError(\n\t\t\t`secureHeaders: nonce is on, but the content-security-policy has no script-src to add it to: write one, or place NONCE where the nonce goes (the policy is \"${policy}\")`,\n\t\t);\n\t}\n\tconst parts = placed.split(NONCE);\n\treturn (nonce) => parts.join(`'nonce-${nonce}'`);\n}\n\n/** 128 random bits, base64: a fresh nonce. */\nexport function freshNonce(): string {\n\tconst bytes = crypto.getRandomValues(new Uint8Array(16));\n\treturn btoa(String.fromCharCode(...bytes));\n}\n\n/**\n * One nonce per request, made when first asked for. Keyed by the request's\n * `URL`: the one object every hook and the route of a request share, where\n * a `bodyLimit` hands the route a `Request` of its own.\n */\nexport function nonceStore(): (url: URL) => string {\n\tconst nonces = new WeakMap<URL, string>();\n\treturn (url) => {\n\t\tlet nonce = nonces.get(url);\n\t\tif (nonce === undefined) {\n\t\t\tnonce = freshNonce();\n\t\t\tnonces.set(url, nonce);\n\t\t}\n\t\treturn nonce;\n\t};\n}\n",
+    "import {\n\ttype Alxia,\n\tdefinePlugin,\n\ttype Empty,\n\ttype Plugin,\n\ttype Requiring,\n\twithHeaders,\n} from '@alxia/core';\nimport { NONCE, type NonceContext, nonceStore, policyWithNonce } from './nonce';\n\n/** A header's value, or `false` to leave it out. An empty value is refused. */\nexport type Setting = string | false;\n\nexport interface SecureHeadersOptions {\n\t/** Defaults to a policy for an API: nothing loads, nothing frames it. */\n\treadonly contentSecurityPolicy?: Setting;\n\treadonly strictTransportSecurity?: Setting;\n\treadonly xContentTypeOptions?: Setting;\n\treadonly xFrameOptions?: Setting;\n\treadonly referrerPolicy?: Setting;\n\treadonly crossOriginOpenerPolicy?: Setting;\n\treadonly crossOriginResourcePolicy?: Setting;\n\treadonly crossOriginEmbedderPolicy?: Setting;\n\treadonly originAgentCluster?: Setting;\n\treadonly xDnsPrefetchControl?: Setting;\n\treadonly xPermittedCrossDomainPolicies?: Setting;\n\t/** Off by default: a policy is the app's to write. */\n\treadonly permissionsPolicy?: Setting;\n\t/** Whether `X-Powered-By` and `Server` are removed. On by default. */\n\treadonly hidePoweredBy?: boolean;\n}\n\n/**\n * The nonce switch, beside `SecureHeadersOptions` rather than in it, so that\n * options typed by that interface still pick the plugin without a nonce.\n */\ninterface NonceOption {\n\t/**\n\t * A fresh nonce for each request, in `contentSecurityPolicy` and on the\n\t * context as `nonce`. Placed where the policy names `NONCE`, or added to\n\t * its `script-src`. Off by default.\n\t */\n\treadonly nonce?: boolean;\n}\n\n/**\n * What `secureHeaders({ nonce: true })` returns: an app plugin, whose routes\n * after it read `nonce`, and whose hook sets the header with the same one.\n */\nexport type NoncePlugin = Alxia<NonceContext, Empty, '', never> &\n\tRequiring<Empty>;\n\nconst DEFAULTS = {\n\t'content-security-policy':\n\t\t\"default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'\",\n\t'strict-transport-security': 'max-age=31536000; includeSubDomains',\n\t'x-content-type-options': 'nosniff',\n\t'x-frame-options': 'DENY',\n\t'referrer-policy': 'no-referrer',\n\t'cross-origin-opener-policy': 'same-origin',\n\t'cross-origin-resource-policy': 'same-origin',\n\t'cross-origin-embedder-policy': false,\n\t'origin-agent-cluster': '?1',\n\t'x-dns-prefetch-control': 'off',\n\t'x-permitted-cross-domain-policies': 'none',\n\t'permissions-policy': false,\n} as const satisfies Record<string, Setting>;\n\nconst OPTION: Record<keyof typeof DEFAULTS, keyof SecureHeadersOptions> = {\n\t'content-security-policy': 'contentSecurityPolicy',\n\t'strict-transport-security': 'strictTransportSecurity',\n\t'x-content-type-options': 'xContentTypeOptions',\n\t'x-frame-options': 'xFrameOptions',\n\t'referrer-policy': 'referrerPolicy',\n\t'cross-origin-opener-policy': 'crossOriginOpenerPolicy',\n\t'cross-origin-resource-policy': 'crossOriginResourcePolicy',\n\t'cross-origin-embedder-policy': 'crossOriginEmbedderPolicy',\n\t'origin-agent-cluster': 'originAgentCluster',\n\t'x-dns-prefetch-control': 'xDnsPrefetchControl',\n\t'x-permitted-cross-domain-policies': 'xPermittedCrossDomainPolicies',\n\t'permissions-policy': 'permissionsPolicy',\n};\n\n/**\n * Secure headers on every response, as a plugin. A header a route set\n * itself is kept: a page that needs its own `Content-Security-Policy` —\n * `@alxia/openapi`'s reference page — sets it.\n *\n * ```ts\n * app.use(secureHeaders({ contentSecurityPolicy: \"default-src 'self'\" }));\n * ```\n *\n * With `nonce: true`, each request gets a nonce of its own, in the policy\n * and on the context of the routes declared after it:\n *\n * ```ts\n * app\n *   .use(secureHeaders({ nonce: true, contentSecurityPolicy: \"script-src 'self'\" }))\n *   .get('/', ({ nonce, reply }) => reply(200, `<script nonce=\"${nonce}\">…</script>`));\n * ```\n */\nexport function secureHeaders(\n\toptions: SecureHeadersOptions & { readonly nonce: true },\n): NoncePlugin;\nexport function secureHeaders(\n\toptions?: SecureHeadersOptions & { readonly nonce?: false },\n): Plugin;\nexport function secureHeaders(\n\toptions: SecureHeadersOptions & NonceOption = {},\n): Plugin | NoncePlugin {\n\tconst headers = fixedHeaders(options);\n\tconst hide = options.hidePoweredBy ?? true;\n\tconst policy = headers.get('content-security-policy');\n\tif (!options.nonce) {\n\t\tif (policy?.includes(NONCE)) {\n\t\t\tthrow new TypeError(\n\t\t\t\t'secureHeaders: contentSecurityPolicy names NONCE, but nonce is off: give nonce: true',\n\t\t\t);\n\t\t}\n\t\tconst set = setter(headers, hide);\n\t\treturn (app) => app.onResponse((response) => set(response));\n\t}\n\tif (policy === undefined) {\n\t\tthrow new TypeError(\n\t\t\t'secureHeaders: nonce is on, but contentSecurityPolicy is false: a nonce is only read through the content-security-policy header',\n\t\t);\n\t}\n\theaders.delete('content-security-policy');\n\tconst withNonce = policyWithNonce(policy);\n\tconst nonceOf = nonceStore();\n\tconst set = setter(headers, hide);\n\tconst plugin: NoncePlugin = definePlugin()((app) =>\n\t\tapp\n\t\t\t.onResponse((response, ctx) => set(response, withNonce(nonceOf(ctx.url))))\n\t\t\t.derive(({ url }): NonceContext => ({ nonce: nonceOf(url) })),\n\t);\n\treturn plugin;\n}\n\n/** Each header the options leave in, by name, with its value. Throws on an empty one. */\nfunction fixedHeaders(options: SecureHeadersOptions): Map<string, string> {\n\tconst headers = new Map<string, string>();\n\tfor (const [name, fallback] of Object.entries(DEFAULTS) as [\n\t\tkeyof typeof DEFAULTS,\n\t\tSetting,\n\t][]) {\n\t\tconst setting = options[OPTION[name]];\n\t\tif (typeof setting === 'string' && setting.trim() === '') {\n\t\t\t// An empty header says nothing a browser can act on: leave it out.\n\t\t\tthrow new TypeError(\n\t\t\t\t`secureHeaders: ${OPTION[name]} is empty; give false to leave the ${name} header out`,\n\t\t\t);\n\t\t}\n\t\tconst value = setting === undefined ? fallback : setting;\n\t\tif (typeof value === 'string') headers.set(name, value);\n\t}\n\treturn headers;\n}\n\n/** The `onResponse` hook: every header the response lacks, then the policy given per request. */\nfunction setter(headers: ReadonlyMap<string, string>, hide: boolean) {\n\treturn (response: Response, policy?: string) =>\n\t\twithHeaders(response, (current) => {\n\t\t\tfor (const [name, value] of headers) {\n\t\t\t\tif (!current.has(name)) current.set(name, value);\n\t\t\t}\n\t\t\tif (policy !== undefined && !current.has('content-security-policy')) {\n\t\t\t\tcurrent.set('content-security-policy', policy);\n\t\t\t}\n\t\t\tif (hide) {\n\t\t\t\tcurrent.delete('x-powered-by');\n\t\t\t\tcurrent.delete('server');\n\t\t\t}\n\t\t});\n}\n"
   ],
-  "mappings": ";AAAA;AAwBA,IAAM,WAAW;AAAA,EAChB,2BACC;AAAA,EACD,6BAA6B;AAAA,EAC7B,0BAA0B;AAAA,EAC1B,mBAAmB;AAAA,EACnB,mBAAmB;AAAA,EACnB,8BAA8B;AAAA,EAC9B,gCAAgC;AAAA,EAChC,gCAAgC;AAAA,EAChC,wBAAwB;AAAA,EACxB,0BAA0B;AAAA,EAC1B,qCAAqC;AAAA,EACrC,sBAAsB;AACvB;AAEA,IAAM,SAAoE;AAAA,EACzE,2BAA2B;AAAA,EAC3B,6BAA6B;AAAA,EAC7B,0BAA0B;AAAA,EAC1B,mBAAmB;AAAA,EACnB,mBAAmB;AAAA,EACnB,8BAA8B;AAAA,EAC9B,gCAAgC;AAAA,EAChC,gCAAgC;AAAA,EAChC,wBAAwB;AAAA,EACxB,0BAA0B;AAAA,EAC1B,qCAAqC;AAAA,EACrC,sBAAsB;AACvB;AAWO,SAAS,aAAa,CAAC,UAAgC,CAAC,GAAW;AAAA,EACzE,MAAM,UAA8B,CAAC;AAAA,EACrC,YAAY,MAAM,aAAa,OAAO,QAAQ,QAAQ,GAGjD;AAAA,IACJ,MAAM,UAAU,QAAQ,OAAO;AAAA,IAC/B,IAAI,OAAO,YAAY,YAAY,QAAQ,KAAK,MAAM,IAAI;AAAA,MAEzD,MAAM,IAAI,UACT,kBAAkB,OAAO,2CAA2C,iBACrE;AAAA,IACD;AAAA,IACA,MAAM,QAAQ,YAAY,YAAY,WAAW;AAAA,IACjD,IAAI,OAAO,UAAU;AAAA,MAAU,QAAQ,KAAK,CAAC,MAAM,KAAK,CAAC;AAAA,EAC1D;AAAA,EACA,MAAM,OAAO,QAAQ,iBAAiB;AAAA,EACtC,OAAO,CAAC,QACP,IAAI,WAAW,CAAC,aACf,YAAY,UAAU,CAAC,YAAY;AAAA,IAClC,YAAY,MAAM,UAAU,SAAS;AAAA,MACpC,IAAI,CAAC,QAAQ,IAAI,IAAI;AAAA,QAAG,QAAQ,IAAI,MAAM,KAAK;AAAA,IAChD;AAAA,IACA,IAAI,MAAM;AAAA,MACT,QAAQ,OAAO,cAAc;AAAA,MAC7B,QAAQ,OAAO,QAAQ;AAAA,IACxB;AAAA,GACA,CACF;AAAA;",
-  "debugId": "DD4A7A8B39A4596664756E2164756E21",
+  "mappings": "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",
+  "debugId": "3F73DEF9D20E37B064756E2164756E21",
   "names": []
 }

package/dist/nonce.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The per-request nonce of `secureHeaders({ nonce: true })`: where it goes
+ * in the policy, how one is made, and how the context and the header read
+ * the same one.
+ */
+/**
+ * Where the nonce goes in `contentSecurityPolicy`: each occurrence becomes
+ * `'nonce-<value>'`, the request's own value. Without it, `nonce: true`
+ * adds the nonce to `script-src` and `script-src-elem`.
+ *
+ * ```ts
+ * secureHeaders({
+ *   nonce: true,
+ *   contentSecurityPolicy: `default-src 'self'; style-src 'self' ${NONCE}`,
+ * });
+ * ```
+ */
+export declare const NONCE = "'nonce-{alxia}'";
+/** What `secureHeaders({ nonce: true })` adds to the context of the routes after it. */
+export interface NonceContext {
+    /**
+     * This request's nonce, base64, the one its `Content-Security-Policy`
+     * allows: what a page puts on its `<script nonce>`.
+     */
+    readonly nonce: string;
+}
+/**
+ * The policy as a function of the nonce: split where `NONCE` stands, or
+ * where it is added to the script directives. Throws when there is
+ * nowhere to put it.
+ */
+export declare function policyWithNonce(policy: string): (nonce: string) => string;
+/** 128 random bits, base64: a fresh nonce. */
+export declare function freshNonce(): string;
+/**
+ * One nonce per request, made when first asked for. Keyed by the request's
+ * `URL`: the one object every hook and the route of a request share, where
+ * a `bodyLimit` hands the route a `Request` of its own.
+ */
+export declare function nonceStore(): (url: URL) => string;
+//# sourceMappingURL=nonce.d.ts.map

package/dist/nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.d.ts","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,oBAAoB,CAAC;AAEvC,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAKD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAmBzE;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAUjD"}

package/dist/secure-headers.d.ts

@@ -1,4 +1,5 @@
-import { type Plugin } from '@alxia/core';
+import { type Alxia, type Empty, type Plugin, type Requiring } from '@alxia/core';
+import { type NonceContext } from './nonce';
 /** A header's value, or `false` to leave it out. An empty value is refused. */
 export type Setting = string | false;
 export interface SecureHeadersOptions {
@@ -19,6 +20,11 @@ export interface SecureHeadersOptions {
     /** Whether `X-Powered-By` and `Server` are removed. On by default. */
     readonly hidePoweredBy?: boolean;
 }
+/**
+ * What `secureHeaders({ nonce: true })` returns: an app plugin, whose routes
+ * after it read `nonce`, and whose hook sets the header with the same one.
+ */
+export type NoncePlugin = Alxia<NonceContext, Empty, '', never> & Requiring<Empty>;
 /**
  * Secure headers on every response, as a plugin. A header a route set
  * itself is kept: a page that needs its own `Content-Security-Policy` —
@@ -27,6 +33,20 @@ export interface SecureHeadersOptions {
  * ```ts
  * app.use(secureHeaders({ contentSecurityPolicy: "default-src 'self'" }));
  * ```
+ *
+ * With `nonce: true`, each request gets a nonce of its own, in the policy
+ * and on the context of the routes declared after it:
+ *
+ * ```ts
+ * app
+ *   .use(secureHeaders({ nonce: true, contentSecurityPolicy: "script-src 'self'" }))
+ *   .get('/', ({ nonce, reply }) => reply(200, `<script nonce="${nonce}">…</script>`));
+ * ```
  */
-export declare function secureHeaders(options?: SecureHeadersOptions): Plugin;
+export declare function secureHeaders(options: SecureHeadersOptions & {
+    readonly nonce: true;
+}): NoncePlugin;
+export declare function secureHeaders(options?: SecureHeadersOptions & {
+    readonly nonce?: false;
+}): Plugin;
 //# sourceMappingURL=secure-headers.d.ts.map

package/dist/secure-headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-headers.d.ts","sourceRoot":"","sources":["../src/secure-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAe,MAAM,aAAa,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAErC,MAAM,WAAW,oBAAoB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACjD,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACjC;AAiCD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CA6BxE"}
+{"version":3,"file":"secure-headers.d.ts","sourceRoot":"","sources":["../src/secure-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,KAAK,EAEV,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,EAEd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAS,KAAK,YAAY,EAA+B,MAAM,SAAS,CAAC;AAEhF,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAErC,MAAM,WAAW,oBAAoB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACjD,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACjC;AAeD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,GAC9D,SAAS,CAAC,KAAK,CAAC,CAAC;AAiClB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACtD,WAAW,CAAC;AACf,wBAAgB,aAAa,CAC5B,OAAO,CAAC,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACzD,MAAM,CAAC"}

package/docs/README.md

@@ -6,6 +6,6 @@ headers, and what to do when a browser refuses what they forbid.
 
 | Page | Read it when |
 | --- | --- |
-| [Guide](guide.md) | changing or dropping a header, giving a page its own policy, ordering it with other hooks, or testing the headers |
+| [Guide](guide.md) | changing or dropping a header, a nonce per request, giving a page its own policy, ordering it with other hooks, or testing the headers |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message: a TypeScript error, a browser refusal, a header that is or is not there |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -1,8 +1,8 @@
 # Guide
 
 This page covers `secureHeaders`: what it sends, how to change or drop each
-header, which responses it reaches, and how a page or another plugin sets
-its own policy.
+header, the per-request nonce, which responses it reaches, and how a page or
+another plugin sets its own policy.
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -21,7 +21,8 @@ Every response of that app now carries the headers below, and none carries
 ## The signature
 
 ```ts
-function secureHeaders(options?: SecureHeadersOptions): Plugin;
+function secureHeaders(options: SecureHeadersOptions & { readonly nonce: true }): NoncePlugin;
+function secureHeaders(options?: SecureHeadersOptions & { readonly nonce?: false }): Plugin;
 
 interface SecureHeadersOptions {
 	readonly contentSecurityPolicy?: string | false;
@@ -40,6 +41,9 @@ interface SecureHeadersOptions {
 }
 ```
 
+`nonce` is not in `SecureHeadersOptions`: each overload adds it, so options
+typed by that interface still give the plain `Plugin`.
+
 `secureHeaders` returns a function `Plugin` from `@alxia/core`: give it to
 `use`, called, and the app keeps its type. It adds one global `onResponse`
 hook, so where it sits in the chain does not matter for which routes it
@@ -49,7 +53,13 @@ app's. To vary a header for some routes, set it on their replies
 ([below](#a-header-a-route-sets-is-kept)).
 
 The options are read once, when `secureHeaders(…)` is called; the header
-values are fixed from then on.
+values are fixed from then on, but for the nonce, which is new on every
+request.
+
+With `nonce: true` it returns a `NoncePlugin` instead: an app plugin, still
+given to `use` called, whose hook covers every route as above, and which
+adds `nonce` to the context of the routes declared after it
+([below](#a-nonce-per-request)).
 
 ## The options
 
@@ -74,6 +84,7 @@ leave the header out. An option left out keeps the default.
 | Option | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `hidePoweredBy` | `boolean` | `true` | removes `X-Powered-By` and `Server` from every response, a route's own included |
+| `nonce` | `boolean` | `false` | a fresh nonce per request, in the policy and on the context: [A nonce per request](#a-nonce-per-request) |
 
 ### A value
 
@@ -166,6 +177,110 @@ That is how `@alxia/openapi`'s reference page and `@alxia/graphql`'s IDE
 load under the strict default: each sets the `Content-Security-Policy` it
 needs, and `secureHeaders` keeps it.
 
+## A nonce per request
+
+A policy that allows a page's inline scripts without `'unsafe-inline'`
+names a nonce: `script-src 'nonce-…'`, and the same value on each
+`<script nonce="…">`. It must be unguessable and new on every response.
+`nonce: true` does both halves.
+
+```ts
+import { alxia } from '@alxia/core';
+import { secureHeaders } from '@alxia/secure-headers';
+
+const app = alxia()
+	.use(
+		secureHeaders({
+			nonce: true,
+			contentSecurityPolicy: "default-src 'self'; script-src 'self'; frame-ancestors 'none'",
+		}),
+	)
+	.get('/', ({ nonce, reply }) =>
+		reply(
+			200,
+			`<!doctype html><script nonce="${nonce}">document.title = 'ready'</script>`,
+			{ headers: { 'content-type': 'text/html; charset=utf-8' } },
+		),
+	);
+
+const response = await app.request('/');
+response.headers.get('content-security-policy');
+// "default-src 'self'; script-src 'self' 'nonce-Gm1y0S3h1JZcVvXQ4l6x0A=='; frame-ancestors 'none'"
+await response.text();
+// "<!doctype html><script nonce=\"Gm1y0S3h1JZcVvXQ4l6x0A==\">…"
+```
+
+### What it is
+
+16 bytes from `crypto.getRandomValues`, base64: 24 characters, `==` at the
+end. Each request makes its own, when the first hook or route asks for it,
+and every reader of that request — the route, its hooks, the header — gets
+the same one. Two requests never share one.
+
+### Where it goes in the policy
+
+| The policy | The nonce goes |
+| --- | --- |
+| names `NONCE` | where `NONCE` stands, each time, and nowhere else |
+| has no `NONCE`, has `script-src` or `script-src-elem` | at the end of each of those directives (their name in any case) |
+| has neither, as the default policy | nowhere: `secureHeaders()` throws at startup; give `contentSecurityPolicy` with `nonce: true` |
+
+`NONCE`, exported, is a placeholder string (`'nonce-{alxia}'`) that no real
+policy contains. Use it to put the nonce in `style-src`, or in a directive
+of your own choosing:
+
+```ts
+import { NONCE, secureHeaders } from '@alxia/secure-headers';
+
+app.use(
+	secureHeaders({
+		nonce: true,
+		contentSecurityPolicy: [
+			"default-src 'self'",
+			`script-src 'self' ${NONCE} 'strict-dynamic'`,
+			`style-src 'self' ${NONCE}`,
+		].join('; '),
+	}),
+);
+```
+
+Leaving `style-src` alone is the default on purpose: once a directive holds
+a nonce, browsers ignore its `'unsafe-inline'`, and `style="…"` attributes,
+which take no nonce, stop applying
+([troubleshooting](troubleshooting.md#inline-style-attributes-stop-applying-once-style-src-has-the-nonce)).
+
+### Who reads it
+
+The header covers every response, as without the nonce: 404s, 500s and the
+routes declared before the plugin get a policy with a nonce of their own.
+`ctx.nonce` is typed and set on the routes declared **after** `use`, in
+their hooks and their handler, as any plugin's context:
+
+```ts
+alxia()
+	.get('/early', ({ reply }) => reply(200, 'policy with a nonce, no ctx.nonce'))
+	.use(secureHeaders({ nonce: true, contentSecurityPolicy: "script-src 'self'" }))
+	.derive(({ nonce }) => ({ scriptTag: (code: string) => `<script nonce="${nonce}">${code}</script>` }))
+	.get('/late', ({ scriptTag, reply }) => reply(200, scriptTag('…')));
+```
+
+A route that sets its own `Content-Security-Policy` keeps it, as
+[above](#a-header-a-route-sets-is-kept); its `ctx.nonce` is then in no
+header, unless it writes it into its own policy.
+
+### With React Router
+
+`@alxia/react-router` reads the nonce from the context, if one is there,
+with `nonceOf(loadContext)` in `entry.server.tsx`. Neither package depends
+on the other. See
+[its guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md#a-csp-nonce).
+
+### Without `nonce: true`
+
+Nothing changes: the same headers, the same values, no `nonce` on the
+context. A policy that names `NONCE` without `nonce: true` is refused at
+startup, so the placeholder never reaches a browser.
+
 ## Which responses get the headers
 
 The plugin runs as an `onResponse` hook, so it reaches what the app's
@@ -259,6 +374,8 @@ app.use(
 
 Or keep the strict default for the API and give the pages their policy on
 their reply, as in [A header a route sets is kept](#a-header-a-route-sets-is-kept).
+When the pages run inline scripts, add `nonce: true` rather than
+`'unsafe-inline'`: [A nonce per request](#a-nonce-per-request).
 
 ### Framed by your own origin
 

package/docs/roadmap.md

@@ -25,6 +25,15 @@ Nothing scheduled yet.
 
 ## Shipped
 
+### Next release
+
+- **A nonce per request.** `secureHeaders({ nonce: true })` makes a fresh,
+  random nonce for each request, adds it to the policy's `script-src`, or
+  wherever the policy names `NONCE`, and gives the same one to the routes
+  after it as `ctx.nonce`, typed. A page's inline scripts run without
+  `'unsafe-inline'`; `@alxia/react-router`'s `nonceOf` hands it to React
+  Router. Without the option, nothing changes.
+
 ### 0.1.0
 
 - **Secure headers on every response.** `secureHeaders()` is a plugin for

package/docs/troubleshooting.md

@@ -2,25 +2,33 @@
 
 Each entry is headed by the text you see: a TypeScript error, an exception,
 a browser console message, or a header that is or is not on a response.
-`secureHeaders` itself throws nothing; what goes wrong is a type, a
-browser refusing what a header forbids, or a header in the wrong place.
+`secureHeaders` throws only at startup, on options it cannot send; what
+goes wrong otherwise is a type, a browser refusing what a header forbids,
+or a header in the wrong place.
 
 **Types**
 
 - [`Type 'true' is not assignable to type 'Setting | undefined'`](#type-true-is-not-assignable-to-type-setting--undefined)
-- [`… is not assignable to parameter of type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'`](#-is-not-assignable-to-parameter-of-type-secureheadersoptions-with-exactoptionalpropertytypes-true)
-- [`Object literal may only specify known properties, and '…' does not exist in type 'SecureHeadersOptions'`](#object-literal-may-only-specify-known-properties-and--does-not-exist-in-type-secureheadersoptions)
-- [`No overload matches this call` … `has no properties in common with type 'SecureHeadersOptions'`](#no-overload-matches-this-call--has-no-properties-in-common-with-type-secureheadersoptions)
+- [`No overload matches this call` … `is not assignable to type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'`](#no-overload-matches-this-call--is-not-assignable-to-type-secureheadersoptions-with-exactoptionalpropertytypes-true)
+- [`No overload matches this call` … `Object literal may only specify known properties, and '…' does not exist in type 'SecureHeadersOptions & …'`](#no-overload-matches-this-call--object-literal-may-only-specify-known-properties-and--does-not-exist-in-type-secureheadersoptions--)
+- [`No overload matches this call` … `Property 'nonce' is missing in type 'Alxia<Empty, Empty, "", never>'`](#no-overload-matches-this-call--property-nonce-is-missing-in-type-alxiaempty-empty--never)
+- [`Property 'nonce' does not exist on type 'Context<…>'`](#property-nonce-does-not-exist-on-type-context)
+- [`No overload matches this call` … `Type 'boolean' is not assignable to type 'true'`](#no-overload-matches-this-call--type-boolean-is-not-assignable-to-type-true)
 
 **Runtime**
 
 - [`TypeError: secureHeaders: … is empty; give false to leave the … header out`](#typeerror-secureheaders--is-empty-give-false-to-leave-the--header-out)
 - [`TypeError: alxia().use(secureHeaders).get is not a function`](#typeerror-alxiausesecureheadersget-is-not-a-function)
+- [`TypeError: secureHeaders: nonce is on, but the content-security-policy has no script-src to add it to: …`](#typeerror-secureheaders-nonce-is-on-but-the-content-security-policy-has-no-script-src-to-add-it-to-)
+- [`TypeError: secureHeaders: nonce is on, but contentSecurityPolicy is false: …`](#typeerror-secureheaders-nonce-is-on-but-contentsecuritypolicy-is-false-)
+- [`TypeError: secureHeaders: contentSecurityPolicy names NONCE, but nonce is off: give nonce: true`](#typeerror-secureheaders-contentsecuritypolicy-names-nonce-but-nonce-is-off-give-nonce-true)
 
 **In the browser**
 
 - [`Refused to load the … because it violates the following Content Security Policy directive: "default-src 'none'"`](#refused-to-load-the--because-it-violates-the-following-content-security-policy-directive-default-src-none)
 - [`Refused to send form data to '…' because it violates the following Content Security Policy directive: "form-action 'none'"`](#refused-to-send-form-data-to--because-it-violates-the-following-content-security-policy-directive-form-action-none)
+- [`Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-script-src-self-nonce-)
+- [Inline style attributes stop applying once `style-src` has the nonce](#inline-style-attributes-stop-applying-once-style-src-has-the-nonce)
 - [`Refused to frame '…' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'none'"`](#refused-to-frame--because-an-ancestor-violates-the-following-content-security-policy-directive-frame-ancestors-none)
 - [`net::ERR_BLOCKED_BY_RESPONSE.NotSameOrigin`](#neterr_blocked_by_responsenotsameorigin)
 - [`window.opener` is `null` in a sign-in popup](#windowopener-is-null-in-a-sign-in-popup)
@@ -40,10 +48,16 @@ browser refusing what a header forbids, or a header in the wrong place.
 **When:** a header option is given `true`, an object or an array.
 
 ```text
-error TS2322: Type 'true' is not assignable to type 'Setting | undefined'.
-error TS2322: Type '{ defaultSrc: string[]; }' is not assignable to type 'Setting | undefined'.
+error TS2769: No overload matches this call.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+    Type 'true' is not assignable to type 'Setting'.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin', gave the following error.
+    Type 'true' is not assignable to type 'Setting | undefined'.
 ```
 
+An object, `{ defaultSrc: [...] }`, reads the same with its own type in
+place of `'true'`.
+
 `hidePoweredBy` given anything but a boolean is the same error, against
 `'boolean | undefined'`.
 
@@ -63,13 +77,18 @@ app.use(
 );
 ```
 
-### `… is not assignable to parameter of type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'`
+### `No overload matches this call` … `is not assignable to type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'`
 
 **When:** an option is set to `undefined`, often from a condition, with
 `exactOptionalPropertyTypes` on.
 
 ```text
-error TS2379: Argument of type '{ xFrameOptions: undefined; }' is not assignable to parameter of type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
+error TS2769: No overload matches this call.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+    Argument of type '{ xFrameOptions: undefined; }' is not assignable to parameter of type 'SecureHeadersOptions & { readonly nonce: true; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
+      Type '{ xFrameOptions: undefined; }' is not assignable to type 'SecureHeadersOptions' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin', gave the following error.
+    Argument of type '{ xFrameOptions: undefined; }' is not assignable to parameter of type 'SecureHeadersOptions & { readonly nonce?: false; }' with 'exactOptionalPropertyTypes: true'. …
 ```
 
 **Why:** the options are optional, not `undefined`-able. Under that flag a
@@ -83,17 +102,21 @@ const production = Bun.env.NODE_ENV === 'production';
 app.use(secureHeaders({ ...(production ? {} : { strictTransportSecurity: false }) }));
 ```
 
-### `Object literal may only specify known properties, and '…' does not exist in type 'SecureHeadersOptions'`
+### `No overload matches this call` … `Object literal may only specify known properties, and '…' does not exist in type 'SecureHeadersOptions & …'`
 
 **When:** an option names a header the plugin does not send, or uses
 another library's name for one.
 
 ```text
-error TS2353: Object literal may only specify known properties, and 'xPoweredBy' does not exist in type 'SecureHeadersOptions'.
+error TS2769: No overload matches this call.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+    Object literal may only specify known properties, and 'xPoweredBy' does not exist in type 'SecureHeadersOptions & { readonly nonce: true; }'.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin', gave the following error.
+    Object literal may only specify known properties, and 'xPoweredBy' does not exist in type 'SecureHeadersOptions & { readonly nonce?: false; }'.
 ```
 
 **Why:** the options are the twelve headers in the
-[guide](guide.md#the-options), plus `hidePoweredBy`. `X-Powered-By` and
+[guide](guide.md#the-options), plus `hidePoweredBy` and `nonce`. `X-Powered-By` and
 `Server` are governed by `hidePoweredBy`; anything else —
 `Content-Security-Policy-Report-Only`, `X-XSS-Protection` — is not sent by
 the plugin.
@@ -114,20 +137,22 @@ const app = alxia()
 	);
 ```
 
-### `No overload matches this call` … `has no properties in common with type 'SecureHeadersOptions'`
+### `No overload matches this call` … `Property 'nonce' is missing in type 'Alxia<Empty, Empty, "", never>'`
 
 **When:** `secureHeaders` is given to `use` without being called.
 
 ```text
 error TS2769: No overload matches this call.
   Overload 1 of 2, '(plugin: (app: Alxia<Empty, Empty, "", never>) => AnyAlxia): AnyAlxia', gave the following error.
-    Argument of type '(options?: SecureHeadersOptions | undefined) => Plugin' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => AnyAlxia'.
+    Argument of type '{ (options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin; (options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin; }' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => AnyAlxia'.
       Types of parameters 'options' and 'app' are incompatible.
-        Type 'Alxia<Empty, Empty, "", never>' has no properties in common with type 'SecureHeadersOptions'.
+        Type 'Alxia<Empty, Empty, "", never>' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'.
+          Property 'nonce' is missing in type 'Alxia<Empty, Empty, "", never>' but required in type '{ readonly nonce: true; }'.
 ```
 
 **Why:** `secureHeaders` makes the plugin from its options; the plugin is
-what it returns.
+what it returns. TypeScript tries the app as the options of its first
+overload, the nonce one, and says what that lacks.
 
 **Fix:** call it, with or without options:
 
@@ -135,6 +160,54 @@ what it returns.
 app.use(secureHeaders());
 ```
 
+### `Property 'nonce' does not exist on type 'Context<…>'`
+
+**When:** a route or a hook reads `nonce` from its context.
+
+```text
+error TS2339: Property 'nonce' does not exist on type 'Context<Empty, "/", Empty>'.
+```
+
+**Why:** only `secureHeaders({ nonce: true })` adds it, and only to the
+routes declared after its `use`. Without `nonce: true`, or on a route
+declared before it, there is none.
+
+**Fix:** turn it on, and declare the routes that read it after it:
+
+```ts
+alxia()
+	.use(secureHeaders({ nonce: true, contentSecurityPolicy: "script-src 'self'" }))
+	.get('/', ({ nonce, reply }) => reply(200, nonce));
+```
+
+### `No overload matches this call` … `Type 'boolean' is not assignable to type 'true'`
+
+**When:** `nonce` is given a `boolean` that is not a literal: a flag from
+the environment, say.
+
+```text
+error TS2769: No overload matches this call.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+    Type 'boolean' is not assignable to type 'true'.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin', gave the following error.
+    Type 'boolean' is not assignable to type 'false'.
+```
+
+**Why:** `nonce: true` changes the plugin's type, since it adds `nonce`
+to the context. A `boolean` leaves TypeScript unable to say whether the
+routes read one.
+
+**Fix:** pick the call by the flag, so each has a literal:
+
+```ts
+const policy = "default-src 'self'; script-src 'self'";
+const app = useNonce
+	? alxia().use(secureHeaders({ nonce: true, contentSecurityPolicy: policy }))
+	: alxia().use(secureHeaders({ contentSecurityPolicy: policy }));
+```
+
+Or keep it on everywhere: the nonce costs one random draw per request.
+
 ## Runtime
 
 ### `TypeError: secureHeaders: … is empty; give false to leave the … header out`
@@ -173,6 +246,65 @@ const app = alxia()
 	.get('/', ({ reply }) => reply(200, 'ok'));
 ```
 
+### `TypeError: secureHeaders: nonce is on, but the content-security-policy has no script-src to add it to: …`
+
+**When:** `nonce: true`, with a policy that has neither a `script-src` (or
+`script-src-elem`) nor `NONCE` — the default policy among them. It throws
+at startup:
+
+```text
+TypeError: secureHeaders: nonce is on, but the content-security-policy has no script-src to add it to: write one, or place NONCE where the nonce goes (the policy is "default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'")
+```
+
+**Why:** the nonce goes in a directive. Without `script-src`, scripts fall
+back on `default-src`, and adding a `script-src` of the plugin's own would
+change what else they may load.
+
+**Fix:** write the `script-src` you want, or say where the nonce goes:
+
+```ts
+import { NONCE, secureHeaders } from '@alxia/secure-headers';
+
+app.use(secureHeaders({ nonce: true, contentSecurityPolicy: "default-src 'self'; script-src 'self'" }));
+app.use(secureHeaders({ nonce: true, contentSecurityPolicy: `default-src 'self' ${NONCE}` }));
+```
+
+### `TypeError: secureHeaders: nonce is on, but contentSecurityPolicy is false: …`
+
+**When:** `nonce: true` and `contentSecurityPolicy: false` together.
+
+```text
+TypeError: secureHeaders: nonce is on, but contentSecurityPolicy is false: a nonce is only read through the content-security-policy header
+```
+
+**Why:** a browser only honours a nonce the response's policy names; with
+no policy there is nothing for it to allow.
+
+**Fix:** give a policy, or drop `nonce`. A route that writes its own policy
+with `ctx.nonce` still needs the plugin's: give the app one, and let the
+route's replace it ([guide](guide.md#who-reads-it)).
+
+### `TypeError: secureHeaders: contentSecurityPolicy names NONCE, but nonce is off: give nonce: true`
+
+**When:** the policy holds `NONCE`, and `nonce` is left out or `false`.
+It throws at startup:
+
+```text
+TypeError: secureHeaders: contentSecurityPolicy names NONCE, but nonce is off: give nonce: true
+```
+
+**Why:** without `nonce: true` the placeholder would go out as it is,
+`'nonce-{alxia}'`, which allows nothing and reads as a mistake in a
+browser's console.
+
+**Fix:**
+
+```ts
+import { NONCE, secureHeaders } from '@alxia/secure-headers';
+
+app.use(secureHeaders({ nonce: true, contentSecurityPolicy: `script-src 'self' ${NONCE}` }));
+```
+
 ## In the browser
 
 These messages are Chrome's wording; Firefox and Safari report the same
@@ -220,6 +352,51 @@ form, even to itself.
 const PAGE_POLICY = "default-src 'self'; form-action 'self'; base-uri 'self'; frame-ancestors 'none'";
 ```
 
+### `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`
+
+**When:** `nonce: true` is on, and a page's inline script does not run.
+Chrome adds `Either the 'unsafe-inline' keyword, a hash ('sha256-…'), or a
+nonce ('nonce-...') is required to enable inline execution.`
+
+**Why:** the script carries no nonce, or another request's: one cached with
+the page, or written into the HTML at build time. Each response allows only
+its own.
+
+**Fix:** write the request's `ctx.nonce` on each `<script>`, and never
+cache a page whose HTML holds one:
+
+```ts
+.get('/', ({ nonce, reply }) =>
+	reply(200, `<script nonce="${nonce}">…</script>`, {
+		headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+	}),
+)
+```
+
+With React Router, `nonceOf(loadContext)` in `entry.server.tsx` does it for
+every script it renders; see
+[its troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#a-script-of-the-page-has-no-nonce).
+
+### Inline style attributes stop applying once `style-src` has the nonce
+
+**When:** `NONCE` is put in `style-src`, which also has `'unsafe-inline'`,
+and every `style="…"` attribute is ignored: Chrome prints `Refused to apply
+inline style because it violates the following Content Security Policy
+directive: "style-src 'self' 'unsafe-inline' 'nonce-…'". Note that
+'unsafe-inline' is ignored if either a hash or nonce value is present in
+the source list.`
+
+**Why:** a nonce in a directive turns its `'unsafe-inline'` off, and an
+attribute cannot carry a nonce. That is why `nonce: true` alone leaves
+`style-src` as written.
+
+**Fix:** keep the nonce out of `style-src`, or allow the attributes in a
+directive of their own:
+
+```ts
+contentSecurityPolicy: `default-src 'self'; script-src 'self'; style-src-elem 'self' ${NONCE}; style-src-attr 'unsafe-inline'`,
+```
+
 ### `Refused to frame '…' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'none'"`
 
 **When:** a page puts a response of the app in an `<iframe>`. With the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/secure-headers",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "Secure HTTP headers for alxia: HSTS, CSP, nosniff and the rest, each one adjustable",
 	"license": "MIT",
 	"type": "module",
@@ -41,13 +41,13 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/client": "^0.2.0",
-		"@alxia/core": "^0.2.0",
+		"@alxia/client": "^0.2.1",
+		"@alxia/core": "^0.3.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.2.0"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.3.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }