@alxia/secure-headers 0.2.0 → 0.4.0

package/README.md

@@ -18,14 +18,16 @@ app.use(secureHeaders());
 app.use(secureHeaders({ contentSecurityPolicy: "default-src 'self'", xFrameOptions: false }));
 ```
 
-A header a route sets itself is kept: a page that needs its own policy sets
-it on its reply.
+`secureHeaders()` is a middleware: every response that comes back through
+it carries the headers, a 404's, an error's and a refused preflight's
+included. 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
+declared after the middleware as `ctx.nonce`. The header and the context always
 carry the same one, so a page's inline scripts need no `'unsafe-inline'`.
 
 ```ts
@@ -94,15 +96,29 @@ value is refused at startup. `nonce` is off by default.
 
 | export | |
 | --- | --- |
-| `secureHeaders(options?)` | the plugin: a function `Plugin`, or with `nonce: true` a `NoncePlugin` |
+| `secureHeaders(options?)` | the middleware, for `app.use`: a `SecureHeaders`, or with `nonce: true` a `NonceMiddleware` |
 | `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` |
+| `SecureHeaders` | what `secureHeaders()` returns: a middleware that adds nothing to the context |
+| `NonceMiddleware` | what `secureHeaders({ nonce: true })` returns: a middleware adding `NonceContext` |
+
+## Traps
+
+`use` it first: a route declared before `app.use(secureHeaders())` gets no
+header, and `ctx.nonce` exists only on routes declared after it. It
+settles `next()` without swallowing the error: a `try`/`catch` middleware
+catches it wherever it stands, but only one declared after
+`secureHeaders()` has the headers on its reply. Declare error-handling
+middleware after it.
+
+```ts
+const app = alxia().use(secureHeaders()).use(errorHandler).get(...);
+```
 
 ## Documentation
 
-- [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.
+- [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 middlewares, 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,3 +1,3 @@
 export { NONCE, type NonceContext } from './nonce';
-export { type NoncePlugin, type SecureHeadersOptions, type Setting, secureHeaders, } from './secure-headers';
+export { type NonceMiddleware, type SecureHeaders, 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,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"}
+{"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,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,aAAa,GACb,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -16,20 +16,11 @@ 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 {
-  definePlugin,
+  defineMiddleware,
+  markFactory,
+  settle,
   withHeaders
 } from "@alxia/core";
 var DEFAULTS = {
@@ -69,17 +60,21 @@ function secureHeaders(options = {}) {
       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));
+    return defineMiddleware(async function secureHeaders(ctx, next) {
+      return set(await settle(ctx, next()));
+    });
   }
   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;
+  return defineMiddleware(async function secureHeaders(ctx, next) {
+    const added = { nonce: freshNonce() };
+    const response = await settle(ctx, next(added));
+    return set(response, withNonce(added.nonce));
+  });
 }
 function fixedHeaders(options) {
   const headers = new Map;
@@ -109,10 +104,11 @@ function setter(headers, hide) {
     }
   });
 }
+markFactory(secureHeaders);
 export {
   NONCE,
   secureHeaders
 };
 
-//# debugId=3F73DEF9D20E37B064756E2164756E21
+//# debugId=DA6BBAE79DDA945364756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/nonce.ts", "../src/secure-headers.ts"],
   "sourcesContent": [
-    "/**\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"
+    "/**\n * The per-request nonce of `secureHeaders({ nonce: true })`: where it goes\n * in the policy, and how one is made.\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",
+    "import {\n\tdefineMiddleware,\n\ttype Empty,\n\ttype Middleware,\n\tmarkFactory,\n\ttype Next,\n\tsettle,\n\twithHeaders,\n} from '@alxia/core';\nimport { freshNonce, NONCE, type NonceContext, 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()` returns: a middleware, for `app.use`, that sets\n * the headers on every response after it.\n */\nexport type SecureHeaders = Middleware<Empty, Promise<Response>>;\n\n/**\n * What `secureHeaders({ nonce: true })` returns: a middleware, for\n * `app.use`, whose routes after it read `nonce`, and which sets the header\n * with the same one.\n */\nexport type NonceMiddleware = Middleware<Empty, Promise<Next<NonceContext>>>;\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 middleware: each response of the\n * routes after it and of a request no route matches — a 404, an error —\n * gets them. A header a route set itself is kept: a page that needs its\n * own `Content-Security-Policy` — `@alxia/graphql`'s IDE — 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): NonceMiddleware;\nexport function secureHeaders(\n\toptions?: SecureHeadersOptions & { readonly nonce?: false },\n): SecureHeaders;\nexport function secureHeaders(\n\toptions: SecureHeadersOptions & NonceOption = {},\n): SecureHeaders | NonceMiddleware {\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 defineMiddleware(async function secureHeaders(ctx, next) {\n\t\t\treturn set(await settle(ctx, next()));\n\t\t});\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 set = setter(headers, hide);\n\treturn defineMiddleware(async function secureHeaders(ctx, next) {\n\t\tconst added: NonceContext = { nonce: freshNonce() };\n\t\tconst response = await settle(ctx, next(added));\n\t\treturn set(response, withNonce(added.nonce)) as typeof response;\n\t});\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/** 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\nmarkFactory(secureHeaders);\n"
   ],
-  "mappings": "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",
-  "debugId": "3F73DEF9D20E37B064756E2164756E21",
+  "mappings": "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",
+  "debugId": "DA6BBAE79DDA945364756E2164756E21",
   "names": []
 }

package/dist/nonce.d.ts

@@ -1,7 +1,6 @@
 /**
  * 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.
+ * in the policy, and how one is made.
  */
 /**
  * Where the nonce goes in `contentSecurityPolicy`: each occurrence becomes
@@ -32,10 +31,4 @@ export interface NonceContext {
 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

@@ -1 +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"}
+{"version":3,"file":"nonce.d.ts","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAAA;;;GAGG;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"}

package/dist/secure-headers.d.ts

@@ -1,4 +1,4 @@
-import { type Alxia, type Empty, type Plugin, type Requiring } from '@alxia/core';
+import { type Empty, type Middleware, type Next } 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;
@@ -21,14 +21,21 @@ export interface SecureHeadersOptions {
     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.
+ * What `secureHeaders()` returns: a middleware, for `app.use`, that sets
+ * the headers on every response after it.
  */
-export type NoncePlugin = Alxia<NonceContext, Empty, '', never> & Requiring<Empty>;
+export type SecureHeaders = Middleware<Empty, Promise<Response>>;
 /**
- * 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` —
- * `@alxia/openapi`'s reference page — sets it.
+ * What `secureHeaders({ nonce: true })` returns: a middleware, for
+ * `app.use`, whose routes after it read `nonce`, and which sets the header
+ * with the same one.
+ */
+export type NonceMiddleware = Middleware<Empty, Promise<Next<NonceContext>>>;
+/**
+ * Secure headers on every response, as a middleware: each response of the
+ * routes after it and of a request no route matches — a 404, an error —
+ * gets them. A header a route set itself is kept: a page that needs its
+ * own `Content-Security-Policy` — `@alxia/graphql`'s IDE — sets it.
  *
  * ```ts
  * app.use(secureHeaders({ contentSecurityPolicy: "default-src 'self'" }));
@@ -45,8 +52,8 @@ export type NoncePlugin = Alxia<NonceContext, Empty, '', never> & Requiring<Empt
  */
 export declare function secureHeaders(options: SecureHeadersOptions & {
     readonly nonce: true;
-}): NoncePlugin;
+}): NonceMiddleware;
 export declare function secureHeaders(options?: SecureHeadersOptions & {
     readonly nonce?: false;
-}): Plugin;
+}): SecureHeaders;
 //# 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,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"}
+{"version":3,"file":"secure-headers.d.ts","sourceRoot":"","sources":["../src/secure-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,KAAK,EACV,KAAK,UAAU,EAEf,KAAK,IAAI,EAGT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAqB,KAAK,YAAY,EAAmB,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,aAAa,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAiC7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACtD,eAAe,CAAC;AACnB,wBAAgB,aAAa,CAC5B,OAAO,CAAC,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACzD,aAAa,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, a nonce per request, 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 middlewares, 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

@@ -2,7 +2,7 @@
 
 This page covers `secureHeaders`: what it sends, how to change or drop each
 header, the per-request nonce, which responses it reaches, and how a page or
-another plugin sets its own policy.
+another middleware sets its own policy.
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -21,8 +21,8 @@ Every response of that app now carries the headers below, and none carries
 ## The signature
 
 ```ts
-function secureHeaders(options: SecureHeadersOptions & { readonly nonce: true }): NoncePlugin;
-function secureHeaders(options?: SecureHeadersOptions & { readonly nonce?: false }): Plugin;
+function secureHeaders(options: SecureHeadersOptions & { readonly nonce: true }): NonceMiddleware;
+function secureHeaders(options?: SecureHeadersOptions & { readonly nonce?: false }): SecureHeaders;
 
 interface SecureHeadersOptions {
 	readonly contentSecurityPolicy?: string | false;
@@ -42,22 +42,25 @@ 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
-reaches: every route, declared before or after it, is covered. Used inside
-a `group`, it still covers the whole app — a group's global hooks are the
-app's. To vary a header for some routes, set it on their replies
+typed by that interface still give the plain `SecureHeaders`.
+
+`secureHeaders` returns a middleware: give it to `app.use`, called, and the
+app keeps its type. `SecureHeaders` is a `Middleware` from `@alxia/core`
+that adds nothing to the context. It waits for the rest of the chain with
+`settle`, then sets the headers on the response, so it covers every route
+declared after it, and every request no route matches — a 404, a 405 —
+because those run all of the app's top-level middlewares too. A route
+declared **before** it is not covered. Used inside a `group`, it covers only
+that group's routes, and not a 404 under the group's prefix: declare it on
+the app. 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, 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
+With `nonce: true` it returns a `NonceMiddleware` instead: a middleware, still
+given to `app.use` called, that covers the same responses as above, and which
 adds `nonce` to the context of the routes declared after it
 ([below](#a-nonce-per-request)).
 
@@ -103,7 +106,7 @@ app.use(
 
 ### `false`
 
-`false` leaves the header out of every response the plugin touches.
+`false` leaves the header out of every response the middleware touches.
 
 ```ts
 app.use(secureHeaders({ xFrameOptions: false, strictTransportSecurity: false }));
@@ -143,11 +146,11 @@ const app = alxia()
 (await app.request('/')).headers.get('x-powered-by'); // null
 ```
 
-`hidePoweredBy: false` keeps whatever the route or another hook sent.
+`hidePoweredBy: false` keeps whatever the route or another middleware sent.
 
 ## A header a route sets is kept
 
-The plugin only fills in a header the response does not have yet. A route
+The middleware only fills in a header the response does not have yet. A route
 that needs its own policy sets it on its reply, and the other defaults
 still apply:
 
@@ -171,11 +174,10 @@ response.headers.get('x-frame-options');         // null                   — f
 ```
 
 `set.headers` in a handler or a `derive` works the same way, since it ends
-up on the response before the plugin reads it.
+up on the response before the middleware reads it.
 
-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.
+That is how `@alxia/graphql`'s IDE loads under the strict default: it sets
+the `Content-Security-Policy` it needs, and `secureHeaders` keeps it.
 
 ## A nonce per request
 
@@ -213,8 +215,8 @@ await response.text();
 ### 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
+end. Each request makes its own, when the middleware runs,
+and every reader of that request — the route, its middlewares, the header — gets
 the same one. Two requests never share one.
 
 ### Where it goes in the policy
@@ -251,14 +253,15 @@ which take no nonce, stop applying
 
 ### 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:
+The header covers every response that comes back through the middleware, as
+without the nonce: a 404 and a 500 get a policy with a nonce of their own.
+`ctx.nonce` is typed and set on the routes declared **after** `app.use`, in
+their middlewares and their handler, as any middleware's context. A route
+declared before it gets neither a policy nor a `ctx.nonce`:
 
 ```ts
 alxia()
-	.get('/early', ({ reply }) => reply(200, 'policy with a nonce, no ctx.nonce'))
+	.get('/early', ({ reply }) => reply(200, 'no policy from this middleware, 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('…')));
@@ -283,17 +286,17 @@ 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
-`onResponse` hooks reach:
+The middleware settles `next()`: it sets the headers on the response the
+client would get, whatever produced it.
 
 | Response | Headers |
 | --- | --- |
 | a route's reply, `static` and `file` included | yes |
-| the core's 400, 404, 405 and 500 | yes |
-| a `Response` an `onRequest` hook returned (a CORS preflight, a redirect) | yes |
-| a WebSocket upgrade that succeeds (`101`) | no: `onResponse` hooks do not run for it |
-| a page served with `page()` | no: `Bun.serve` serves it, around no hook |
-| the 500 sent when an `around` hook itself throws | no |
+| the core's 400, 404, 405 and 500, and a `try`/`catch` middleware's reply declared after it | yes |
+| a `Response` another middleware returned (a CORS preflight, a redirect) | yes, when that middleware is declared after `secureHeaders` |
+| a route declared before `app.use(secureHeaders())` | no: the middleware does not run for it |
+| a WebSocket upgrade that succeeds (`101`) | no: the upgrade is not a response a middleware can decorate |
+| a page served with `page()` | no: `Bun.serve` serves it, around no middleware |
 
 ```ts
 const app = alxia().use(secureHeaders());
@@ -303,58 +306,71 @@ response.status;                                // 404
 response.headers.get('x-content-type-options'); // 'nosniff'
 ```
 
-## Order with other `onResponse` hooks
+## Order with other middlewares
 
-`onResponse` hooks run in the order they are declared, and the plugin never
-overwrites a header that is already there. So:
+Middlewares nest: the first `use` is the outermost, and on the way out each
+one sees the response of the ones after it. The middleware never overwrites
+a header that is already there. So:
 
-- a hook declared **before** `secureHeaders` that sets one of its headers
-  wins;
-- a hook declared **after** it that sets one of its headers wins too, by
-  overwriting;
-- a hook declared **after** it that adds `X-Powered-By` or `Server` keeps
-  it: the plugin deleted them before that hook ran.
+- a middleware declared **after** `secureHeaders` that sets one of its
+  headers wins: `secureHeaders` finds it already there;
+- a middleware declared **before** it that sets one of its headers wins too,
+  by overwriting;
+- a middleware declared **before** it that adds `X-Powered-By` or `Server`
+  keeps it: `secureHeaders` deleted them before that one ran.
 
 ```ts
-import { alxia, withHeaders } from '@alxia/core';
+import { alxia, defineMiddleware, settle, withHeaders } from '@alxia/core';
 import { secureHeaders } from '@alxia/secure-headers';
 
+const referrerOrigin = defineMiddleware(async (ctx, next) =>
+	withHeaders(await settle(ctx, next()), (headers) => headers.set('referrer-policy', 'origin')),
+);
+
 const app = alxia()
-	.onResponse((response) =>
-		withHeaders(response, (headers) => headers.set('referrer-policy', 'origin')),
-	)
 	.use(secureHeaders())
+	.use(referrerOrigin)
 	.get('/', ({ reply }) => reply(200, 'ok'));
 
 (await app.request('/')).headers.get('referrer-policy'); // 'origin'
 ```
 
-## A header the plugin does not know
+Declare `secureHeaders()` among the observers, first: `logger()`,
+`telemetry()`, `secureHeaders()`, `cors()`, `compress()`. An
+error-handling middleware — a `try`/`catch` around `next()`, or
+`janusErrors()` — goes **after** it. `secureHeaders()` settles `next()`: it
+sets the headers on the response the error would be answered with (its
+`HttpError`'s status, or a 500), then the error
+goes on, so a `try`/`catch` catches it wherever it is declared; declared
+before `secureHeaders()`, its reply does not carry the headers. A guard on the app (`bearer`, a required
+session) declared before it answers its `401` without them.
 
-The plugin sends the twelve headers above and nothing else. Another one —
+## A header the middleware does not know
+
+The middleware sends the twelve headers above and nothing else. Another one —
 `Content-Security-Policy-Report-Only` while a policy is being tried, say —
-is a hook of your own, with `withHeaders` from `@alxia/core`:
+is a middleware of your own, with `settle` and `withHeaders` from
+`@alxia/core`:
 
 ```ts
-import { alxia, withHeaders } from '@alxia/core';
+import { alxia, defineMiddleware, settle, withHeaders } from '@alxia/core';
 import { secureHeaders } from '@alxia/secure-headers';
 
+const reportOnly = defineMiddleware(async (ctx, next) =>
+	withHeaders(await settle(ctx, next()), (headers) => {
+		if (!headers.has('content-security-policy-report-only')) {
+			headers.set('content-security-policy-report-only', "default-src 'self'; report-to csp");
+		}
+	}),
+);
+
 const app = alxia()
 	.use(secureHeaders())
-	.onResponse((response) =>
-		withHeaders(response, (headers) => {
-			if (!headers.has('content-security-policy-report-only')) {
-				headers.set(
-					'content-security-policy-report-only',
-					"default-src 'self'; report-to csp",
-				);
-			}
-		}),
-	);
+	.use(reportOnly);
 ```
 
-See [Hooks](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md#onresponse)
-in the core's guide for what an `onResponse` hook may do.
+See [Middleware](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md)
+in the core's guide for what a middleware may do.
 
 ## Recipes
 
@@ -481,6 +497,6 @@ test('a 404 is covered too', async () => {
 
 - [Troubleshooting](troubleshooting.md): a browser refuses something, or
   TypeScript does.
-- [Hooks](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md)
+- [Middleware](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md)
   and [Groups and plugins](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/groups-and-plugins.md)
   in the core's guide.

package/docs/roadmap.md

@@ -7,7 +7,11 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **Secure headers as a middleware.** `app.use(secureHeaders())`, declared
+  first, sets the headers on every response that comes back through it, a
+  404's, an error's and a 500's included; `NonceMiddleware` gives `nonce` to the
+  routes after it and `SecureHeaders` is the plain one.
+  `app.plugin(secureHeaders())`, the deprecated alias, was removed in 0.5.
 
 ## Next
 
@@ -37,7 +41,7 @@ Nothing scheduled yet.
 ### 0.1.0
 
 - **Secure headers on every response.** `secureHeaders()` is a plugin for
-  `use` that sends `Content-Security-Policy`, `Strict-Transport-Security`,
+  `app.plugin` that sends `Content-Security-Policy`, `Strict-Transport-Security`,
   `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`,
   `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy`,
   `Origin-Agent-Cluster`, `X-DNS-Prefetch-Control` and

package/docs/troubleshooting.md

@@ -11,14 +11,14 @@ or a header in the wrong place.
 - [`Type 'true' is not assignable to type 'Setting | undefined'`](#type-true-is-not-assignable-to-type-setting--undefined)
 - [`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)
+- [`Type 'undefined' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'`](#type-undefined-is-not-assignable-to-type-secureheadersoptions---readonly-nonce-true-)
+- [`Property 'nonce' does not exist on type 'RouteBase<…>'`](#property-nonce-does-not-exist-on-type-routebase)
 - [`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)
+- [`use(): argument 1 looks like a factory (secureHeaders): call it, use(secureHeaders())`](#use-argument-1-looks-like-a-factory-secureheaders-call-it-usesecureheaders)
 - [`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)
@@ -39,7 +39,9 @@ or a header in the wrong place.
 - [An option has no effect on a response](#an-option-has-no-effect-on-a-response)
 - [`X-Powered-By` or `Server` is still sent](#x-powered-by-or-server-is-still-sent)
 - [A response arrives without the headers](#a-response-arrives-without-the-headers)
-- [Routes outside a group get the headers](#routes-outside-a-group-get-the-headers)
+- [A 404 or a route outside a group has no headers](#a-404-or-a-route-outside-a-group-has-no-headers)
+- [A `try`/`catch` middleware's reply has no headers](#a-trycatch-middlewares-reply-has-no-headers)
+- [A route has no headers, though the others do](#a-route-has-no-headers-though-the-others-do)
 
 ## Types
 
@@ -49,9 +51,9 @@ or a header in the wrong place.
 
 ```text
 error TS2769: No overload matches this call.
-  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware', 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.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): SecureHeaders', gave the following error.
     Type 'true' is not assignable to type 'Setting | undefined'.
 ```
 
@@ -84,10 +86,10 @@ app.use(
 
 ```text
 error TS2769: No overload matches this call.
-  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware', 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.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): SecureHeaders', gave the following error.
     Argument of type '{ xFrameOptions: undefined; }' is not assignable to parameter of type 'SecureHeadersOptions & { readonly nonce?: false; }' with 'exactOptionalPropertyTypes: true'. …
 ```
 
@@ -109,9 +111,9 @@ another library's name for one.
 
 ```text
 error TS2769: No overload matches this call.
-  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NoncePlugin', gave the following error.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware', 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.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): SecureHeaders', gave the following error.
     Object literal may only specify known properties, and 'xPoweredBy' does not exist in type 'SecureHeadersOptions & { readonly nonce?: false; }'.
 ```
 
@@ -119,40 +121,43 @@ error TS2769: No overload matches this call.
 [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.
+the middleware.
 
-**Fix:** `hidePoweredBy` for those two; a hook of your own for another
+**Fix:** `hidePoweredBy` for those two; a middleware of your own for another
 header:
 
 ```ts
-import { alxia, withHeaders } from '@alxia/core';
+import { alxia, defineMiddleware, settle, withHeaders } from '@alxia/core';
 import { secureHeaders } from '@alxia/secure-headers';
 
+const reportOnly = defineMiddleware(async (ctx, next) =>
+	withHeaders(await settle(ctx, next()), (headers) =>
+		headers.set('content-security-policy-report-only', "default-src 'self'"),
+	),
+);
+
 const app = alxia()
 	.use(secureHeaders({ hidePoweredBy: true }))
-	.onResponse((response) =>
-		withHeaders(response, (headers) =>
-			headers.set('content-security-policy-report-only', "default-src 'self'"),
-		),
-	);
+	.use(reportOnly);
 ```
 
-### `No overload matches this call` … `Property 'nonce' is missing in type 'Alxia<Empty, Empty, "", never>'`
+### `Type 'undefined' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'`
 
-**When:** `secureHeaders` is given to `use` without being called.
+**When:** `secureHeaders` is given to `app.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 & { 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>' 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; }'.
+error TS2345: Argument of type '{ (options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware; (options?: (SecureHeadersOptions & { ...; }) | undefined): SecureHeaders; }' is not assignable to parameter of type '{ (options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware; (options?: (SecureHeadersOptions & { ...; }) | undefined): SecureHeaders; } & Step<...>'.
+  Type '{ (options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware; (options?: (SecureHeadersOptions & { ...; }) | undefined): SecureHeaders; }' is not assignable to type 'Step<BaseContext & Empty, (SecureHeadersOptions & { readonly nonce?: false; }) | undefined, MiddlewareReturn>'.
+    Types of parameters 'options' and 'ctx' are incompatible.
+      Type '(SecureHeadersOptions & { readonly nonce?: false; }) | undefined' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'.
+        Type 'undefined' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'.
+          Type 'undefined' is not assignable to type 'SecureHeadersOptions'.
 ```
 
-**Why:** `secureHeaders` makes the plugin from its options; the plugin is
-what it returns. TypeScript tries the app as the options of its first
-overload, the nonce one, and says what that lacks.
+**Why:** `secureHeaders` makes the middleware from its options; the
+middleware is what it returns. Given to `use` as it is, it is read as a
+middleware whose context is its options, and TypeScript says those do not
+fit its first overload, the nonce one.
 
 **Fix:** call it, with or without options:
 
@@ -160,16 +165,19 @@ overload, the nonce one, and says what that lacks.
 app.use(secureHeaders());
 ```
 
-### `Property 'nonce' does not exist on type 'Context<…>'`
+### `Property 'nonce' does not exist on type 'RouteBase<…>'`
 
-**When:** a route or a hook reads `nonce` from its context.
+**When:** a route or a middleware reads `nonce` from its context.
 
 ```text
-error TS2339: Property 'nonce' does not exist on type 'Context<Empty, "/", Empty>'.
+error TS2339: Property 'nonce' does not exist on type 'RouteBase<RouteApp<"GET", Empty, "">, "/">'.
+error TS2339: Property 'nonce' does not exist on type 'BaseContext & Empty'.
 ```
 
+The second is a `derive` or a middleware.
+
 **Why:** only `secureHeaders({ nonce: true })` adds it, and only to the
-routes declared after its `use`. Without `nonce: true`, or on a route
+routes declared after its `app.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:
@@ -187,13 +195,13 @@ 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.
+  Overload 1 of 2, '(options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware', 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.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): SecureHeaders', gave the following error.
     Type 'boolean' is not assignable to type 'false'.
 ```
 
-**Why:** `nonce: true` changes the plugin's type, since it adds `nonce`
+**Why:** `nonce: true` changes the middleware's type, since it adds `nonce`
 to the context. A `boolean` leaves TypeScript unable to say whether the
 routes read one.
 
@@ -229,14 +237,18 @@ Only `false` leaves a header out.
 app.use(secureHeaders({ xFrameOptions: false }));
 ```
 
-### `TypeError: alxia().use(secureHeaders).get is not a function`
+### `use(): argument 1 looks like a factory (secureHeaders): call it, use(secureHeaders())`
 
-**When:** the same mistake as above in JavaScript, or past a cast: the
-chain breaks on the next method after `use(secureHeaders)`.
+**When:** `alxia().use(secureHeaders)`, the factory given uncalled, in
+JavaScript or past a cast. It throws where the app is declared, since
+alxia 0.5; before, each request was answered with a 500 and the log said
+`GET /: a middleware (secureHeaders) returned function: …`. TypeScript
+refuses it first, with `"this looks like a factory given uncalled: …"` in
+the error.
 
-**Why:** `use` calls the function with the app. Uncalled, `secureHeaders`
-reads the app as its options and returns a plugin, not the app, so the
-next `.get` is called on a function.
+**Why:** `use` takes a middleware, a `(ctx, next)` function; `secureHeaders`
+makes one, and is marked as a factory, so `use`, a route and `plugin`
+refuse it.
 
 **Fix:**
 
@@ -257,7 +269,7 @@ TypeError: secureHeaders: nonce is on, but the content-security-policy has no sc
 ```
 
 **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
+back on `default-src`, and adding a `script-src` of the middleware's own would
 change what else they may load.
 
 **Fix:** write the `script-src` you want, or say where the nonce goes:
@@ -281,7 +293,7 @@ TypeError: secureHeaders: nonce is on, but contentSecurityPolicy is false: a non
 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
+with `ctx.nonce` still needs the middleware'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`
@@ -476,11 +488,11 @@ until it reads `max-age=0` from the host over HTTPS.
 
 **When:** an option is set, and some responses still carry another value.
 
-**Why:** the plugin never overwrites a header the response already has.
-A route set it on its reply or on `set.headers`, an `onResponse` hook
-declared before `secureHeaders` set it, or one declared after overwrote it.
-`@alxia/openapi`'s reference page and `@alxia/graphql`'s IDE set their own
-`Content-Security-Policy` on purpose.
+**Why:** the middleware never overwrites a header the response already has.
+A route set it on its reply or on `set.headers`, a middleware declared
+after `secureHeaders` set it on the way out, or one declared before it
+overwrote it.
+`@alxia/graphql`'s IDE sets its own `Content-Security-Policy` on purpose.
 
 **Fix:** find what sets it on that route, and change it there:
 
@@ -494,22 +506,25 @@ console.log(response.headers.get('content-security-policy'));
 **When:** `hidePoweredBy` is on (the default), and one of them is on the
 response.
 
-**Why:** the plugin deletes them when its hook runs. An `onResponse` hook
-declared after `secureHeaders` that adds one runs later, and keeps it. A
-proxy in front of the app may add its own `Server` too.
+**Why:** the middleware deletes them when the response comes back through
+it. A middleware declared **before** `secureHeaders` that adds one sees the
+response after that, and keeps it. A proxy in front of the app may add its
+own `Server` too.
 
-**Fix:** declare `secureHeaders` after the hook that adds the header, or
-stop that hook adding it:
+**Fix:** declare `secureHeaders` before the middleware that adds the header,
+or stop that middleware adding it:
 
 ```ts
-import { alxia, withHeaders } from '@alxia/core';
+import { alxia, defineMiddleware, settle, withHeaders } from '@alxia/core';
 import { secureHeaders } from '@alxia/secure-headers';
 
+const poweredBy = defineMiddleware(async (ctx, next) =>
+	withHeaders(await settle(ctx, next()), (headers) => headers.set('x-powered-by', 'my-app')),
+);
+
 const app = alxia()
-	.onResponse((response) =>
-		withHeaders(response, (headers) => headers.set('x-powered-by', 'my-app')),
-	)
-	.use(secureHeaders()); // its hook runs after, and deletes it
+	.use(secureHeaders()) // outermost: deletes the header on the way out
+	.use(poweredBy);
 ```
 
 ### A response arrives without the headers
@@ -517,20 +532,19 @@ const app = alxia()
 **When:** a response has none of the headers, though `secureHeaders` is
 in use.
 
-**Why:** the plugin is an `onResponse` hook, and three responses run no
-`onResponse` hook: a WebSocket upgrade that succeeds (the `101`), a page
-served with `page()`, which `Bun.serve` answers itself, and the 500 sent
-when an `around` hook throws.
+**Why:** the middleware decorates what comes back through it, and two
+responses do not: a WebSocket upgrade that succeeds (the `101`), and a page
+served with `page()`, which `Bun.serve` answers itself.
 
 **Fix:** serve a page that needs the headers through a route, `file` or
 `static` rather than `page()` — or give it its policy in its HTML with
 `<meta http-equiv="Content-Security-Policy" content="…">`, where browsers
-ignore `frame-ancestors`. An `around` hook whose own work may fail catches
-it and still returns what `next()` resolved to, which already carries the
-headers:
+ignore `frame-ancestors`. A middleware declared before `secureHeaders`,
+whose own work may fail, catches it and still returns what `next()`
+resolved to, which already carries the headers:
 
 ```ts
-app.around(async (_ctx, next) => {
+const timing = defineMiddleware(async (ctx, next) => {
 	const response = await next();
 	try {
 		recordTiming(response); // your own work
@@ -539,19 +553,26 @@ app.around(async (_ctx, next) => {
 	}
 	return response;
 });
+
+const app = alxia().use(timing).use(secureHeaders());
 ```
 
-### Routes outside a group get the headers
+### A 404 or a route outside a group has no headers
 
-**When:** `secureHeaders` is used inside a `group`, meant for its routes
-only, and every route of the app gets the headers.
+**When:** `secureHeaders` is used inside a `group`, and a route outside the
+group, or a request that matches no route, comes back without them.
 
-**Why:** it adds a global hook, and a group's global hooks are the app's.
+**Why:** a middleware declared in a `group` stays inside the group: it runs
+on its routes and on a request no route matches under its prefix, and on
+nothing else: not on a route outside the group, nor declared after it.
 
 **Fix:** use it on the app, and give the routes that differ their own
 values on their replies:
 
 ```ts
+import { alxia } from '@alxia/core';
+import { secureHeaders } from '@alxia/secure-headers';
+
 const app = alxia()
 	.use(secureHeaders())
 	.get('/embed', ({ reply }) =>
@@ -563,3 +584,54 @@ const app = alxia()
 		}),
 	);
 ```
+
+### A `try`/`catch` middleware's reply has no headers
+
+**When:** a middleware wraps `next()` in a `try`/`catch` to answer errors in
+its own format, is declared before `secureHeaders()`, and its reply comes
+back without the security headers.
+
+**Why:** `secureHeaders` settles `next()`: it sets the headers on the response
+the route boundary would give (the `HttpError`'s status, or a 500), then the error goes on to the middlewares around it. A `try`/`catch`
+declared **before** it catches the error, but its reply is made outside
+`secureHeaders`, so it carries no headers; the 500 inside did.
+
+**Fix:** declare the error-handling middleware after `secureHeaders`, so
+the headers are set on its reply:
+
+```ts
+import { alxia, defineMiddleware } from '@alxia/core';
+import { secureHeaders } from '@alxia/secure-headers';
+
+const errors = defineMiddleware(async (_ctx, next) => {
+	try {
+		return await next();
+	} catch (error) {
+		return Response.json({ error: String(error) }, { status: 500 });
+	}
+});
+
+const app = alxia()
+	.use(secureHeaders()) // first
+	.use(errors)
+	.get('/boom', () => {
+		throw new Error('boom');
+	});
+```
+
+### A route has no headers, though the others do
+
+**When:** one route's responses lack the headers, while a `404` or another
+route's have them.
+
+**Why:** a route declared **before** `app.use(secureHeaders())` does not run
+it. A request no route matches runs every top-level middleware wherever it
+is declared, which is why its `404` is covered.
+
+**Fix:** declare `secureHeaders` before the routes:
+
+```ts
+const app = alxia()
+	.use(secureHeaders())
+	.get('/early', ({ reply }) => reply(200, 'now covered'));
+```

package/package.json

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