proteum 2.6.0 → 2.7.0

package/README.md

@@ -276,13 +276,16 @@ my-app/
 | Topic | Guide |
 | --- | --- |
 | Client navigation (blocking, deferred, prefetch) | [docs/client-navigation.md](docs/client-navigation.md) |
+| Client assets (hashed names, cache headers, stale builds) | [docs/client-assets.md](docs/client-assets.md) |
 | Diagnostics & explainability | [docs/diagnostics.md](docs/diagnostics.md) |
 | Model Context Protocol (MCP) | [docs/mcp.md](docs/mcp.md) |
 | Request tracing & perf | [docs/request-tracing.md](docs/request-tracing.md) |
+| HTTP security headers & CSP | [docs/http-security-headers.md](docs/http-security-headers.md) |
 | Agent routing & token efficiency | [docs/agent-routing.md](docs/agent-routing.md) |
 | Dev commands | [docs/dev-commands.md](docs/dev-commands.md) |
 | Dev sessions | [docs/dev-sessions.md](docs/dev-sessions.md) |
 | Migrating to 2.5 | [docs/migration-2.5.md](docs/migration-2.5.md) |
+| Release history | [docs/HISTORY.md](docs/HISTORY.md) |
 
 ## 🧭 Philosophy
 

package/cli/compiler/client/index.ts

@@ -15,6 +15,7 @@ import CssMinimizerPlugin from '../common/cssMinimizer';
 import { toRspackAliases } from '../common/rspackAliases';
 import { resolveUiSingletonAliases } from '../common/uiSingletons';
 import identityAssets from './identite';
+import { getClientOutputNames } from './outputNames';
 import cli from '../..';
 import { logVerbose } from '../../runtime/verbose';
 
@@ -126,6 +127,8 @@ export default function createCompiler(
     const transpileModuleDirectories = app.transpileModuleDirectories;
     const lightningCssTargets = resolveLightningCssTargets(app);
     const hmrClientEntry = path.join(frameworkSourceRoot, 'client', 'dev', 'hmr.ts');
+    // Content-hashed in production, entries included: see outputNames.ts.
+    const outputNames = getClientOutputNames(dev);
 
     const commonConfig = createCommonConfig(app, 'client', mode, outputTarget);
 
@@ -172,7 +175,7 @@ export default function createCompiler(
         output: {
             pathinfo: dev,
             path: outputPath + '/public',
-            filename: '[name].js', // Output client.js
+            filename: outputNames.entry,
             assetModuleFilename: '[hash][ext]',
             environment: {
                 arrowFunction: true,
@@ -185,9 +188,9 @@ export default function createCompiler(
                 optionalChaining: true,
                 templateLiteral: true,
             },
-            cssFilename: '[name].css',
-            cssChunkFilename: '[name].css',
-            chunkFilename: dev ? '[name].js' : '[id].[contenthash:8].js',
+            cssFilename: outputNames.css,
+            cssChunkFilename: outputNames.css,
+            chunkFilename: outputNames.chunk,
         },
 
         resolve: {
@@ -290,7 +293,9 @@ export default function createCompiler(
                   ]),
 
             // Extract CSS in dev too so SSR emits the same stylesheet links as production.
-            new rspack.CssExtractRspackPlugin({}),
+            // The extract plugin names its files itself (its default is `[name].css`); `output.cssFilename`
+            // only applies to native CSS, so the hashed name is passed here.
+            new rspack.CssExtractRspackPlugin({ filename: outputNames.css, chunkFilename: outputNames.css }),
 
             ...createClientBundleAnalysisPlugins(app, outputTarget),
         ],

package/cli/compiler/client/outputNames.ts

@@ -0,0 +1,28 @@
+/*----------------------------------
+- CLIENT OUTPUT NAMES
+----------------------------------*/
+
+export type TClientOutputNames = {
+    // Entry files: `runtime`, `framework`, `vendors`, `client`
+    entry: string;
+    // Async JS chunks
+    chunk: string;
+    // Entry and page CSS
+    css: string;
+};
+
+/*
+ * Production files carry a content hash, entries included. An unhashed `runtime.js` that a
+ * browser or CDN keeps after a deploy still maps chunk ids to files that no longer exist
+ * (21 Oct 2026: a 4 h CDN browser TTL served the old runtime, its chunks 404ed). The same holds
+ * for CSS: a page chunk keeps its name across builds, so new HTML could pair with a stylesheet
+ * from the previous build. The HTML reads every name from `client-manifest.json`, so nothing
+ * names these files, and the router's public cache classifies `name.<hash>.ext` as versioned.
+ *
+ * Dev keeps stable names: HMR and the dev middleware rely on them, and dev serves `no-store`.
+ * `[name]` stays before the hash so the network panel and bundle analysis stay readable.
+ */
+export const getClientOutputNames = (dev: boolean): TClientOutputNames =>
+    dev
+        ? { entry: '[name].js', chunk: '[name].js', css: '[name].css' }
+        : { entry: '[name].[contenthash:8].js', chunk: '[id].[contenthash:8].js', css: '[name].[contenthash:8].css' };

package/cli/compiler/common/files/autres.ts

@@ -23,6 +23,8 @@ module.exports = (app: App, dev: boolean, client: boolean) => [
         test: /\.(woff(2)?|ttf|eot)(\?v=\d+\.\d+\.\d+)?$/,
         //loader: 'file-loader',
         type: 'asset/resource',
-        generator: { filename: 'fonts/[name].[ext]' },
+        // Hashed so the router serves fonts immutable. `[ext]` carries its own dot: the former
+        // `[name].[ext]` emitted `figtree-latin..woff2`, unhashed and revalidated on every load.
+        generator: { filename: 'fonts/[name].[contenthash:8][ext]' },
     },
 ];

package/cli/scaffold/templates.ts

@@ -218,6 +218,10 @@ export const routerBaseConfig = {
         upload: {
             maxSize: '10mb',
         },
+        // Content-Security-Policy for router answers (HTML only under /api): see Proteum's docs/http-security-headers.md.
+        csp: {
+            scripts: [],
+        },
     },
     context: () => ({}),
 } satisfies RouterBaseConfig;

package/client/app/staleBuild.ts

@@ -0,0 +1,80 @@
+/*----------------------------------
+- STALE BUILD RECOVERY
+----------------------------------*/
+
+/*
+ * A page running an older build asks for chunk files that a deploy removed. The only cure is a
+ * fresh document: the new HTML names the new, content-hashed entry files, so a reload loads the
+ * new build. One reload per build id, kept in sessionStorage, so a chunk that is missing in the
+ * new build too (a deploy race, a CDN that kept a 404) ends on the error instead of a loop.
+ *
+ * - Every build id that reloaded is kept, not only the last one: during a rollout two builds can
+ *   answer at once, and a single slot let the tab bounce between them for as long as it lasted.
+ * - A route chunk that loads clears the list, so a reload spent on a network blip does not take
+ *   the recovery away from the real deploy that comes later in the same tab.
+ * - Offline, a chunk fails because there is no network, not because the build is gone: no reload,
+ *   which would only swap the page for the browser's offline screen.
+ */
+
+export const STALE_BUILD_RELOAD_KEY = 'proteum:stale-build-reload';
+
+// A rollout overlaps two builds at most; the cap only bounds what a long-lived tab can store
+const MAX_RELOADED_BUILDS = 5;
+
+type TReloadStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+export type TStaleBuildReloadOptions = {
+    storage?: () => TReloadStorage;
+    reload?: () => void;
+    isOnline?: () => boolean;
+};
+
+const defaultStorage = () => window.sessionStorage;
+
+const readReloadedBuilds = (store: TReloadStorage) => (store.getItem(STALE_BUILD_RELOAD_KEY) || '').split(',').filter(Boolean);
+
+// The shapes rspack's runtime rejects with: `ChunkLoadError` for a JS chunk, the code for a CSS chunk.
+export const isChunkLoadError = (error: Error) =>
+    error.name === 'ChunkLoadError' || ('code' in error && error.code === 'CSS_CHUNK_LOAD_FAILED');
+
+/**
+ * Reloads the page once for `buildId` and returns true, or returns false when this build already
+ * reloaded in this tab, when the browser is offline, or when sessionStorage is unavailable (no
+ * guard means no reload).
+ */
+export const reloadOnceForStaleBuild = (
+    buildId: string,
+    {
+        storage = defaultStorage,
+        reload = () => window.location.reload(),
+        isOnline = () => window.navigator.onLine !== false,
+    }: TStaleBuildReloadOptions = {},
+): boolean => {
+    if (!isOnline()) return false;
+
+    try {
+        const store = storage();
+        const reloaded = readReloadedBuilds(store);
+        if (reloaded.includes(buildId)) return false;
+
+        store.setItem(STALE_BUILD_RELOAD_KEY, [...reloaded, buildId].slice(-MAX_RELOADED_BUILDS).join(','));
+    } catch (error) {
+        // Storage blocked (private mode, sandboxed frame, quota): without the guard a reload could loop
+        console.warn('Stale build recovery skipped: sessionStorage is unavailable.', error);
+        return false;
+    }
+
+    reload();
+    return true;
+};
+
+/** A route chunk loaded: the running build is whole, so a later missing chunk gets its reload again. */
+export const clearStaleBuildReloads = (storage: () => TReloadStorage = defaultStorage) => {
+    try {
+        const store = storage();
+        if (store.getItem(STALE_BUILD_RELOAD_KEY) !== null) store.removeItem(STALE_BUILD_RELOAD_KEY);
+    } catch (error) {
+        // Nothing to clear when storage is blocked: the reload was never granted either
+        console.warn('Stale build recovery could not reset its guard.', error);
+    }
+};

package/client/services/router/index.tsx

@@ -36,6 +36,7 @@ import type { TFrontRenderer, TPageDataProvider, TPageRenderer } from '@common/r
 import App from '@client/app/component';
 import type ClientApplication from '@client/app';
 import Service from '@client/app/service';
+import { clearStaleBuildReloads, isChunkLoadError, reloadOnceForStaleBuild } from '@client/app/staleBuild';
 
 // Specific
 import ClientRequest, { isClientRequest } from './request';
@@ -381,6 +382,8 @@ export default class ClientRouter<
 
             debug && console.log(`Route fetched: ${route.chunk}`, fetched);
             withProfiler((runtime) => runtime.finishStep(stepId));
+            // The running build is whole: a later missing chunk (the next deploy) gets its reload again
+            clearStaleBuildReloads();
 
             return fetched;
         } catch (e) {
@@ -388,6 +391,13 @@ export default class ClientRouter<
                 runtime.finishStep(stepId, 'error', e instanceof Error ? e.message : String(e)),
             );
             console.error(`Failed to fetch the route ${route.chunk}`, e);
+
+            // A missing chunk means this page runs a build that a deploy replaced: one reload loads
+            // the new one. Settling would render the error page for a frame before the reload, so the
+            // navigation waits for the document to be replaced. See client/app/staleBuild.ts.
+            if (e instanceof Error && isChunkLoadError(e) && reloadOnceForStaleBuild(String(BUILD_ID)))
+                return new Promise<never>(() => {});
+
             try {
                 this.app.handleUpdate();
             } catch (error) {}

package/docs/HISTORY.md

@@ -0,0 +1,8 @@
+# History
+
+Notable framework changes, newest first. Commit messages hold the rest.
+
+## 2.7.0 (2026-11-12)
+
+- Security headers on every answer of Proteum's stack: helmet now runs first in `HttpServer.start()`, before the `/api` fast path, so answers under `/api` carry the base headers and no `X-Powered-By`. Under `/api`, HTML gets the app policy, other answers helmet's default policy, and a 304 none; outside `/api` every router answer keeps the app policy as before, and a route's own policy still wins. `http.csp` gains `directives`, `policy` and `reportOnly` (sent wherever the app policy goes), and a malformed policy now fails at boot. Nothing to change in apps to keep today's policy. See [http-security-headers.md](http-security-headers.md).
+- Client assets (the changes committed as 2.6.1, never published on their own): production entry files, entry and page CSS and fonts are named with a content hash and served immutable, responsive images are served immutable, a `/public` 404 answers `Cache-Control: no-store`, and a page reloads once per build when a deploy removed a chunk it needs. Code or tests that name `client.js`, `client.css`, `runtime.js`, `framework.js` or `vendors.js` must read the names from the manifest. See [client-assets.md](client-assets.md).

package/docs/client-assets.md

@@ -0,0 +1,37 @@
+# Client assets: names, caching and stale builds
+
+## File names
+
+| Output | Dev | Production |
+| --- | --- | --- |
+| Entry JS (`runtime`, `framework`, `vendors`, `client`) | `[name].js` | `[name].[contenthash:8].js` |
+| Async JS chunks | `[name].js` | `[id].[contenthash:8].js` |
+| Entry and page CSS | `[name].css` | `[name].[contenthash:8].css` |
+| Fonts | `fonts/[name].[contenthash:8][ext]` | `fonts/[name].[contenthash:8][ext]` |
+| Images (responsive-loader, production) | | `<hash>-<width>.<ext>` |
+| Other modules | `[hash][ext]` | `[hash][ext]` |
+
+Sources: `cli/compiler/client/outputNames.ts` and `cli/compiler/common/files/*.ts`. Entries, CSS and fonts carry a hash since 2.6.1.
+
+Nothing may name these files by hand. The server reads every entry and page asset from `client-manifest.json` (written after each client build by `cli/compiler/common/clientManifest.ts`), and the document renders the tags from it.
+
+## Cache headers
+
+`/public` files are served by the router with `cache.publicAssets` (`server/services/router/http/cache.ts`):
+
+- `versioned` (default `public, max-age=31536000, immutable`): a file whose name ends in `.<hex hash>.<ext>` or `<hex hash>-<width>.<ext>`, or a request with `?v=`. In production this covers every entry, chunk, stylesheet, font and responsive image the build emits.
+- `unversioned` (default `public, max-age=0, must-revalidate`): any other file, mostly what the app ships in its own `public/` folder (icons, Open Graph images, videos).
+- `dev` (default `no-store`).
+- A `/public` 404 is always `no-store`, so a CDN never keeps a 404 for a file that a newer instance serves.
+
+A CDN can rewrite these headers. Cloudflare's zone setting Browser Cache TTL, for example, raises any lower `max-age` to its value (4 hours by default) unless it is set to "Respect Existing Headers". Hashed names make that harmless for the files the HTML names; an app that wants the unversioned files never cached can set `unversioned` to `no-store`.
+
+## Stale builds
+
+A tab opened before a deploy runs the previous build. When it navigates to a page whose chunk the deploy removed, the chunk request fails with a `ChunkLoadError` (or a CSS chunk error). The client router then reloads the page once (`client/app/staleBuild.ts`): the new HTML names the new hashed files, so the reload runs the new build.
+
+- One reload per build id, remembered in `sessionStorage` under `proteum:stale-build-reload` (every build id that reloaded, so two builds answering during a rollout reload once each). If the same build misses a chunk again, or `sessionStorage` is unavailable, the router calls the app's `handleUpdate()` and throws "A new version of the website is available. Please refresh the page.", as it does for any other route load failure.
+- A route chunk that loads clears the list, so a reload spent on a network blip does not take the recovery away from a real deploy later in the same tab.
+- Offline (`navigator.onLine === false`) a failed chunk is the network: no reload, the error shows.
+- A route module that loaded but failed for another reason never reloads; it goes straight to `handleUpdate()`.
+- `handleUpdate()` should not reload on its own without a guard: the router has already made the one reload, and an unguarded second one can loop.

package/docs/http-security-headers.md

@@ -0,0 +1,114 @@
+# HTTP Security Headers
+
+Proteum's HTTP server sends the same security headers on every answer of its own stack, whatever the path, and picks the Content-Security-Policy by the path and, under `/api`, by the kind of answer at the moment the headers are written. Middleware an app mounts on the Express app before `HttpServer.start()` (a maintenance page, for example) answers before that stack and carries none of these headers, as in 2.6.
+
+Source: `server/services/router/http/index.ts` (`HttpServer.start()`) and `server/services/router/http/securityHeaders.ts`. Tests: `tests/http-server-security-headers.test.cjs`.
+
+## The Contract
+
+The rule in one sentence: outside `/api` no router answer changes its policy (every one carries the app policy, as in 2.6); under `/api`, HTML gets the app policy and everything else gets helmet's default.
+
+| Answer | Base headers | `Content-Security-Policy` | Report-only policy | `X-Powered-By` |
+|---|---|---|---|---|
+| Any answer from the router outside `/api` (pages, their 404, the error page, a cached static page, JSON, text, Markdown, feeds, a worker script a route serves) | yes | the app policy | the app's, when configured | absent |
+| HTML from the router under `/api` (pages, their 404, the error page, a cached static page) | yes | the app policy | the app's, when configured | absent |
+| Any other answer from the router under `/api` (JSON, Markdown, text, scripts, the router's redirects) | yes | helmet's default policy | none | absent |
+| A 304 Not Modified from the router under `/api` | yes | none: the browser keeps the policy its stored copy came with | none | absent |
+| A route or controller that set its own `Content-Security-Policy` | yes | the route's own, untouched | none added | absent |
+| A body-parser error under `/api`, before the router (for example a malformed JSON body) | yes | Express's own `default-src 'none'` | none | absent |
+| Static files (`/public/*`, `/robots.txt` and `/favicon.ico` when the file exists), `/ping` | yes | helmet's default policy | none | absent |
+
+When the app ships no `robots.txt` or `favicon.ico`, the request falls through to the router and its answer carries the app policy, as in 2.6. A redirect under `/api` that is typed `text/html` (one sent from the router's static page cache branch, or Express's `res.redirect` answered to a browser) counts as HTML and gets the app policy; the router's own redirects carry no `Content-Type` and keep helmet's default.
+
+"HTML" means a `Content-Type` of `text/html` or `application/xhtml+xml`. Outside `/api` the type does not matter, on purpose: a worker takes its policy from its own script's answer, so a worker served by a route (for example a map library's worker that fetches tiles from another host) must keep the app policy.
+
+"Base headers" are helmet 4.6's defaults: `Strict-Transport-Security: max-age=15552000; includeSubDomains`, `X-Frame-Options: SAMEORIGIN`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, `X-DNS-Prefetch-Control: off`, `Expect-CT: max-age=0`, `X-Download-Options: noopen`, `X-Permitted-Cross-Domain-Policies: none`, `X-XSS-Protection: 0`. `http.helmet` changes them (for example `referrerPolicy`). helmet 4.6 sends no `Cross-Origin-*` header, and the tests pin that.
+
+helmet's default policy is `default-src 'self';base-uri 'self';block-all-mixed-content;font-src 'self' https: data:;frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests` (256 bytes). `http.helmet.contentSecurityPolicy` replaces it; with `false`, the fallback answers carry no policy, and the others still get the app policy.
+
+How it is wired:
+
+- `x-powered-by` is disabled on the Express app, and `helmet(http.helmet)` is mounted once, first in `start()`, so every answer of Proteum's stack starts with the base headers and helmet's default policy.
+- Under `/api`, a policy writer is mounted before the API fast path (the short middleware stack `/api` requests take, ahead of the static files). It runs when the headers are about to be written, so it knows the final status and `Content-Type`:
+  - when the `Content-Security-Policy` value is no longer the one helmet wrote, a route chose its own: everything is left as it is;
+  - when the status is 304: the policy header is removed, so the browser keeps the policy of the copy it stored (helmet's default there would replace a page's policy);
+  - when the answer is HTML: the app policy, plus the report-only policy when one is configured and the route did not set one;
+  - otherwise: helmet's default stays.
+- Outside `/api`, after the static files and before the router, the app policy replaces helmet's default at the start of every request, as in 2.6. When a report-only policy is configured, it is added when the headers are written, if the answer still carries the app policy.
+- Static files are mounted before that, so they keep helmet's headers byte for byte, an `.html` or `.js` file under `/public` included.
+
+Rule: a route's own policy wins. A route or controller that sets `Content-Security-Policy` itself (for example a strict policy with a nonce) keeps it, under `/api` or anywhere else, and no report-only header is added to it. A route that sets its own report-only header keeps it too.
+
+The writers tell a route's own policy by its value, which leaves two edge cases no app has today: under `/api`, a route whose policy equals helmet's default byte for byte is treated as untouched, so an HTML answer gets the app policy; and with `http.helmet.contentSecurityPolicy: false`, a route under `/api` that removed the header gets the app policy back on HTML. Outside `/api`, a route whose policy equals the app policy byte for byte also gets the report-only header.
+
+## Config
+
+`http.csp` in the app's router config, required. All header strings are built once, at boot: a config the checks below refuse fails the boot with an `[http.csp]` error, never a broken header on a response.
+
+The list form (`scripts` is required, an empty array is fine):
+
+```ts
+csp: {
+    // The four historical lists, unchanged. Proteum adds `'unsafe-inline' 'self' 'unsafe-eval'` to the scripts,
+    // and sends no `default-src` when `default` is empty.
+    scripts: ['cdn.example.com'],
+    styles: ["'self'", "'unsafe-inline'"],
+    images: ["'self'", 'data:', 'https:'],
+    default: [],
+
+    // More enforced directives, by their real names, appended after the lists.
+    directives: {
+        'frame-ancestors': ["'self'"],
+        'object-src': ["'none'"],
+        'base-uri': ["'self'"],
+    },
+
+    // A second complete policy, sent as Content-Security-Policy-Report-Only wherever the app policy goes.
+    reportOnly: {
+        policy: { 'default-src': ["'self'"], 'connect-src': ["'self'", 'api.example.com'] },
+        reportUri: '/csp-report',
+    },
+},
+```
+
+Or a complete enforced policy, written in full by the app (Proteum adds nothing, so no silent `'unsafe-eval'`):
+
+```ts
+csp: {
+    policy: {
+        'default-src': ["'self'"],
+        'script-src': ["'self'", "'unsafe-inline'"],
+        'style-src': ["'self'", "'unsafe-inline'"],
+        'frame-ancestors': ["'self'"],
+    },
+    reportOnly: { policy: { 'default-src': ["'self'"] }, reportUri: '/csp-report' },
+},
+```
+
+`reportUri` is appended to the report-only policy only, as `report-uri <value>`. The enforced policy gets a report address only from a `report-uri` entry in `directives` or `policy`.
+
+In dev, Proteum's client build uses eval source maps and its reload channel listens on another port: when you write `policy`, or a `default-src` or `connect-src`, add `'unsafe-eval'` to `script-src` and the dev event address (`http://localhost:<port>`) to `connect-src` in the dev profile.
+
+Boot errors:
+
+- `csp` absent or not an object; the list form without `scripts`; a key `csp` or `csp.reportOnly` does not know (`reportonly`, `directive`, `reporturi`), which would otherwise boot and send nothing;
+- `policy` together with `scripts`, `styles`, `images`, `default` or `directives`;
+- `directives` naming `default-src`, `script-src`, `style-src` or `img-src` (the lists own them, filled or not);
+- a directive name that is not a CSP 3 directive (`frameAncestors` and `frame-ancestor` are refused, write `'frame-ancestors'`);
+- a directive with no source, except `upgrade-insecure-requests` and `block-all-mixed-content` (which take none and refuse any), `sandbox` and `trusted-types` (which may be empty);
+- a source that is not a string, is empty, or holds anything but printable ASCII with no whitespace, `;` or `,` (write international hosts in punycode; Latin-1 is refused too, though Node would send it, because browsers drop it);
+- in `directives`, `policy` and `reportOnly.policy`: a bare keyword (`self`, `none`, `unsafe-inline`, `unsafe-eval`, `unsafe-hashes`, `strict-dynamic`, `report-sample`, `wasm-unsafe-eval`) that would name a host, and a source with unbalanced single quotes;
+- an empty `policy`, a `reportOnly` without `policy` or with an empty one, a `reportUri` that is empty or not printable ASCII, and `reportUri` together with a `report-uri` entry in `reportOnly.policy`.
+
+The four lists keep most of their 2.6 leniency: an entry holding several sources separated by spaces is kept exactly as written (each source is still checked), so it writes the same bytes; and bare keywords are not checked there. An empty entry (`''` or only spaces) is refused: 2.6 sent it as an empty source list, which blocks everything.
+
+## Migration From 2.6
+
+Nothing to change to keep today's policy: for every config the checks accept, the four lists produce the same header as 2.6, byte for byte, and every router answer outside `/api` keeps it. What changes by itself:
+
+- answers under `/api` now carry the base headers and no `X-Powered-By`; HTML there gets the app policy, other answers helmet's default policy (256 bytes on each API answer), and a 304 there carries none;
+- connected-project answers (`/api/__proteum/connected/*`) are under `/api` and follow the same rule;
+- in the four lists, these entries booted in 2.6 and now stop the boot: an entry that is not a string (`undefined`, `null`, a number); an empty entry; any character outside printable ASCII (a typographic quote, a non-ASCII or Latin-1 host, a tab), which either failed each response or was dropped by browsers;
+- a key `csp` does not know now stops the boot.
+
+To add `frame-ancestors`, `object-src` and `base-uri`, add `csp.directives`. To trial a stricter policy, add `csp.reportOnly`; to enforce it, move it to `csp.policy`.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.6.0",
+	"version": "2.7.0",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -77,6 +77,7 @@
 		"mysql2": "^2.3.0",
 		"node-cmd": "^5.0.0",
 		"null-loader": "^4.0.1",
+		"on-headers": "^1.1.0",
 		"path-to-regexp": "^6.2.0",
 		"pg": "^8.21.0",
 		"postcss-loader": "^8.2.0",

package/server/services/router/http/cache.ts

@@ -69,7 +69,10 @@ type TPublicAssetResponse = {
     req?: TPublicAssetRequest;
 };
 
-const hashedPublicAssetPattern = /(^|[-_.])[a-f0-9]{6,}(?=(\.[^.]+)+$)/i;
+// `name.<hex hash>.ext`: async chunks, and since 2.6.1 the production entry files, CSS and fonts too
+// (cli/compiler/client/outputNames.ts), so every file the HTML names is served immutable.
+// `<hex hash>-<width>.ext` is responsive-loader's default name for each image size: hashed as well.
+const hashedPublicAssetPattern = /(^|[-_.])[a-f0-9]{6,}(-\d+)?(?=(\.[^.]+)+$)/i;
 
 export const resolveHttpCacheConfig = (config?: THttpCacheConfig): TResolvedHttpCacheConfig => ({
     html: {

package/server/services/router/http/index.ts

@@ -56,6 +56,12 @@ import {
     resolvePublicAssetCacheControl,
     type THttpCacheConfig,
 } from './cache';
+import {
+    buildContentSecurityPolicyHeaders,
+    createApiContentSecurityPolicyWriter,
+    createAppContentSecurityPolicy,
+    type TCspConfig,
+} from './securityHeaders';
 
 /*----------------------------------
 - CONFIG
@@ -73,7 +79,8 @@ export type Config = {
     upload: {
         maxSize: string; // Expression package bytes
     };
-    csp: { default?: string[]; styles?: string[]; images?: string[]; scripts: string[] };
+    /** See docs/http-security-headers.md: on every router answer outside `/api`, and on HTML under `/api`. */
+    csp: TCspConfig;
     cache?: THttpCacheConfig;
     cors?: CorsOptions;
     helmet?: Parameters<typeof helmet>[0];
@@ -82,9 +89,8 @@ export type Config = {
 export type Hooks = {};
 
 export { resolveHttpCacheConfig, type THttpCacheConfig } from './cache';
+export type { TCspConfig, TCspDirectives, TCspReportOnly } from './securityHeaders';
 
-type TContentSecurityPolicyOptions = NonNullable<Parameters<typeof helmet.contentSecurityPolicy>[0]>;
-type TContentSecurityPolicyDirectives = NonNullable<TContentSecurityPolicyOptions['directives']>;
 type TDevSessionAuthService = {
     config: {
         jwt: {
@@ -105,24 +111,6 @@ type TDevSessionResult =
           statusCode: number;
       };
 
-const createContentSecurityPolicy = (config: Config['csp']): TContentSecurityPolicyOptions => {
-    const directives: TContentSecurityPolicyDirectives = {
-        defaultSrc:
-            config.default && config.default.length > 0
-                ? [...config.default]
-                : helmet.contentSecurityPolicy.dangerouslyDisableDefaultSrc,
-        scriptSrc: ["'unsafe-inline'", "'self'", "'unsafe-eval'", ...config.scripts],
-    };
-
-    if (config.styles && config.styles.length > 0) directives.styleSrc = [...config.styles];
-    if (config.images && config.images.length > 0) directives.imgSrc = [...config.images];
-
-    return {
-        useDefaults: false,
-        directives,
-    };
-};
-
 const connectedProjectBootRetryCount = 10;
 const connectedProjectBootRetryDelayMs = 5_000;
 /**
@@ -452,10 +440,21 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
 
         // Config
         routes.set('trust proxy', 1); // Indique qu'on est sous le proxy apache
+        routes.disable('x-powered-by');
+
+        // Built once: a malformed policy fails the boot, never a response.
+        const contentSecurityPolicyHeaders = buildContentSecurityPolicyHeaders(this.config.csp);
+
+        // Base headers on every answer, `/api` included (docs/http-security-headers.md).
+        routes.use(helmet(this.config.helmet));
+
         /*----------------------------------
         - FAST PATH: API
         ----------------------------------*/
 
+        // HTML under /api (pages, their 404) gets the app policy; other /api answers keep helmet's default.
+        routes.use(apiOnly(createApiContentSecurityPolicyWriter(contentSecurityPolicyHeaders)));
+
         // Keep /api requests off the heavier page middleware stack below.
         routes.use(apiOnly(hpp()));
         routes.use(apiOnly(cookieParser()));
@@ -473,9 +472,6 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
         this.registerConnectedProjectRoutes(routes);
         routes.use(apiOnly(routeRequest));
 
-        // Diverses protections (dont le disable x-powered-by)
-        routes.use(helmet(this.config.helmet));
-
         /*----------------------------------
         - FICHIERS STATIQUES
         ----------------------------------*/
@@ -513,6 +509,10 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
                 },
             }),
             (req, res) => {
+                // Never cacheable: during a deploy an instance of the previous build can answer for a
+                // file the new build serves, and a CDN that kept that 404 broke every page naming the
+                // file until its TTL ran out (21 Oct 2026, a Cloudflare HIT on a chunk 404).
+                res.setHeader('Cache-Control', 'no-store');
                 res.status(404).send();
             },
         );
@@ -570,7 +570,8 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
 
         if (this.config.cors !== undefined) routes.use(cors(this.config.cors));
 
-        routes.use(helmet.contentSecurityPolicy(createContentSecurityPolicy(this.config.csp)));
+        // Every router answer outside /api keeps the app policy, as in 2.6; static files above keep helmet's.
+        routes.use(createAppContentSecurityPolicy(contentSecurityPolicyHeaders));
 
         this.registerDevTraceRoutes(routes);
         routes.use(routeRequest);