@alxia/secure-headers 0.1.1 → 0.3.0

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, "", never>'`](#no-overload-matches-this-call--property-nonce-is-missing-in-type-alxiaempty--never)
+- [`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)
+- [`TypeError: use(): the plugin function returned function, not an app: …`](#typeerror-use-the-plugin-function-returned-function-not-an-app-)
+- [`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)
@@ -31,7 +39,9 @@ browser refusing what a header forbids, 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
 
@@ -40,10 +50,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; }): NonceMiddleware', gave the following error.
+    Type 'true' is not assignable to type 'Setting'.
+  Overload 2 of 2, '(options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): SecureHeaders', 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 +79,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; }): 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): SecureHeaders', 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,51 +104,59 @@ 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; }): 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): SecureHeaders', 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.
+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` … `has no properties in common with type 'SecureHeadersOptions'`
+### `No overload matches this call` … `Property 'nonce' is missing in type 'Alxia<Empty, "", never>'`
 
-**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 | undefined) => Plugin' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => AnyAlxia'.
+  Overload 1 of 11, '(plugin: (app: Alxia<Empty, "", never>) => AnyAlxia): AnyAlxia', gave the following error.
+    Argument of type '{ (options: SecureHeadersOptions & { readonly nonce: true; }): NonceMiddleware; (options?: (SecureHeadersOptions & { readonly nonce?: false; }) | undefined): Plugin; }' is not assignable to parameter of type '(app: Alxia<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, "", never>' is not assignable to type 'SecureHeadersOptions & { readonly nonce: true; }'.
+          Property 'nonce' is missing in type 'Alxia<Empty, "", never>' but required in type '{ readonly nonce: true; }'.
 ```
 
-**Why:** `secureHeaders` makes the plugin from its options; the plugin is
-what it returns.
+**Why:** `secureHeaders` makes the middleware from its options; the
+middleware is 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 +164,57 @@ what it returns.
 app.use(secureHeaders());
 ```
 
+### `Property 'nonce' does not exist on type 'RouteBase<…>'`
+
+**When:** a route or a middleware reads `nonce` from its context.
+
+```text
+error TS2339: Property 'nonce' does not exist on type 'RouteBase<RouteApp<"GET", Empty, "", never>, "/">'.
+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 `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:
+
+```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; }): NonceMiddleware', gave the following error.
+    Type 'boolean' is not assignable to type 'true'.
+  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 middleware'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`
@@ -156,14 +236,20 @@ Only `false` leaves a header out.
 app.use(secureHeaders({ xFrameOptions: false }));
 ```
 
-### `TypeError: alxia().use(secureHeaders).get is not a function`
+### `TypeError: use(): the plugin function returned function, not an app: …`
 
-**When:** the same mistake as above in JavaScript, or past a cast: the
-chain breaks on the next method after `use(secureHeaders)`.
+**When:** the same mistake as above in JavaScript, or past a cast:
+`alxia().use(secureHeaders)`, the factory given uncalled. It throws at
+startup:
 
-**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.
+```text
+TypeError: use(): the plugin function returned function, not an app: a plugin returns the app it is given; a middleware is made with defineMiddleware() and given to use()
+```
+
+**Why:** `app.use` takes a function that is not a middleware for a plugin:
+it calls it with the app, and expects the app back. Uncalled,
+`secureHeaders` reads the app as its options and returns a middleware, a
+function, not the app.
 
 **Fix:**
 
@@ -173,6 +259,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 middleware'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 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`
+
+**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 +365,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
@@ -299,11 +489,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:
 
@@ -317,22 +507,26 @@ 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; so does a deprecated `onResponse` hook,
+which runs after every middleware. 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
@@ -340,20 +534,20 @@ 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
+**Why:** the middleware decorates what comes back through it, and three
+responses do not: 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.
+when a deprecated `around` hook throws.
 
 **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
@@ -362,19 +556,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 }) =>
@@ -386,3 +587,55 @@ 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 (`onError`, 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.1.1",
+	"version": "0.3.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.0",
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.2.0"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }