@alxia/secure-headers 0.1.1 → 0.3.0

package/docs/guide.md

@@ -1,8 +1,8 @@
 # Guide
 
 This page covers `secureHeaders`: what it sends, how to change or drop each
-header, which responses it reaches, and how a page or another plugin sets
-its own policy.
+header, the per-request nonce, which responses it reaches, and how a page or
+another middleware sets its own policy.
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -21,7 +21,8 @@ Every response of that app now carries the headers below, and none carries
 ## The signature
 
 ```ts
-function secureHeaders(options?: SecureHeadersOptions): Plugin;
+function secureHeaders(options: SecureHeadersOptions & { readonly nonce: true }): NonceMiddleware;
+function secureHeaders(options?: SecureHeadersOptions & { readonly nonce?: false }): SecureHeaders;
 
 interface SecureHeadersOptions {
 	readonly contentSecurityPolicy?: string | false;
@@ -40,16 +41,28 @@ interface SecureHeadersOptions {
 }
 ```
 
-`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
+`nonce` is not in `SecureHeadersOptions`: each overload adds it, so options
+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.
+values are fixed from then on, but for the nonce, which is new on every
+request.
+
+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)).
 
 ## The options
 
@@ -74,6 +87,7 @@ leave the header out. An option left out keeps the default.
 | Option | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `hidePoweredBy` | `boolean` | `true` | removes `X-Powered-By` and `Server` from every response, a route's own included |
+| `nonce` | `boolean` | `false` | a fresh nonce per request, in the policy and on the context: [A nonce per request](#a-nonce-per-request) |
 
 ### A value
 
@@ -92,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 }));
@@ -132,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:
 
@@ -160,25 +174,130 @@ 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/graphql`'s IDE loads under the strict default: it sets
+the `Content-Security-Policy` it needs, and `secureHeaders` keeps it.
+
+## A nonce per request
+
+A policy that allows a page's inline scripts without `'unsafe-inline'`
+names a nonce: `script-src 'nonce-…'`, and the same value on each
+`<script nonce="…">`. It must be unguessable and new on every response.
+`nonce: true` does both halves.
+
+```ts
+import { alxia } from '@alxia/core';
+import { secureHeaders } from '@alxia/secure-headers';
+
+const app = alxia()
+	.use(
+		secureHeaders({
+			nonce: true,
+			contentSecurityPolicy: "default-src 'self'; script-src 'self'; frame-ancestors 'none'",
+		}),
+	)
+	.get('/', ({ nonce, reply }) =>
+		reply(
+			200,
+			`<!doctype html><script nonce="${nonce}">document.title = 'ready'</script>`,
+			{ headers: { 'content-type': 'text/html; charset=utf-8' } },
+		),
+	);
+
+const response = await app.request('/');
+response.headers.get('content-security-policy');
+// "default-src 'self'; script-src 'self' 'nonce-Gm1y0S3h1JZcVvXQ4l6x0A=='; frame-ancestors 'none'"
+await response.text();
+// "<!doctype html><script nonce=\"Gm1y0S3h1JZcVvXQ4l6x0A==\">…"
+```
 
-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.
+### What it is
+
+16 bytes from `crypto.getRandomValues`, base64: 24 characters, `==` at the
+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
+
+| The policy | The nonce goes |
+| --- | --- |
+| names `NONCE` | where `NONCE` stands, each time, and nowhere else |
+| has no `NONCE`, has `script-src` or `script-src-elem` | at the end of each of those directives (their name in any case) |
+| has neither, as the default policy | nowhere: `secureHeaders()` throws at startup; give `contentSecurityPolicy` with `nonce: true` |
+
+`NONCE`, exported, is a placeholder string (`'nonce-{alxia}'`) that no real
+policy contains. Use it to put the nonce in `style-src`, or in a directive
+of your own choosing:
+
+```ts
+import { NONCE, secureHeaders } from '@alxia/secure-headers';
+
+app.use(
+	secureHeaders({
+		nonce: true,
+		contentSecurityPolicy: [
+			"default-src 'self'",
+			`script-src 'self' ${NONCE} 'strict-dynamic'`,
+			`style-src 'self' ${NONCE}`,
+		].join('; '),
+	}),
+);
+```
+
+Leaving `style-src` alone is the default on purpose: once a directive holds
+a nonce, browsers ignore its `'unsafe-inline'`, and `style="…"` attributes,
+which take no nonce, stop applying
+([troubleshooting](troubleshooting.md#inline-style-attributes-stop-applying-once-style-src-has-the-nonce)).
+
+### Who reads it
+
+The header covers every response 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, '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('…')));
+```
+
+A route that sets its own `Content-Security-Policy` keeps it, as
+[above](#a-header-a-route-sets-is-kept); its `ctx.nonce` is then in no
+header, unless it writes it into its own policy.
+
+### With React Router
+
+`@alxia/react-router` reads the nonce from the context, if one is there,
+with `nonceOf(loadContext)` in `entry.server.tsx`. Neither package depends
+on the other. See
+[its guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md#a-csp-nonce).
+
+### Without `nonce: true`
+
+Nothing changes: the same headers, the same values, no `nonce` on the
+context. A policy that names `NONCE` without `nonce: true` is refused at
+startup, so the placeholder never reaches a browser.
 
 ## Which responses get the headers
 
-The plugin runs as an `onResponse` hook, so it reaches what the app's
-`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 an `onError` reply | 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 |
+| the 500 sent when a deprecated `around` hook itself throws | no |
 
 ```ts
 const app = alxia().use(secureHeaders());
@@ -188,58 +307,75 @@ 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 (the
+route's `onError` reply, 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 deprecated `onResponse` and `around` hooks still run outside every
+middleware: an `onResponse` hook sees the headers `secureHeaders` set,
+wherever it is declared.
 
-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
 
@@ -259,6 +395,8 @@ app.use(
 
 Or keep the strict default for the API and give the pages their policy on
 their reply, as in [A header a route sets is kept](#a-header-a-route-sets-is-kept).
+When the pages run inline scripts, add `nonce: true` rather than
+`'unsafe-inline'`: [A nonce per request](#a-nonce-per-request).
 
 ### Framed by your own origin
 
@@ -364,6 +502,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())` keeps working as a deprecated alias.
 
 ## Next
 
@@ -25,10 +29,19 @@ Nothing scheduled yet.
 
 ## Shipped
 
+### Next release
+
+- **A nonce per request.** `secureHeaders({ nonce: true })` makes a fresh,
+  random nonce for each request, adds it to the policy's `script-src`, or
+  wherever the policy names `NONCE`, and gives the same one to the routes
+  after it as `ctx.nonce`, typed. A page's inline scripts run without
+  `'unsafe-inline'`; `@alxia/react-router`'s `nonceOf` hands it to React
+  Router. Without the option, nothing changes.
+
 ### 0.1.0
 
 - **Secure headers on every response.** `secureHeaders()` is a plugin for
-  `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