proteum 2.6.0 → 2.7.0

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

@@ -0,0 +1,343 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import type express from 'express';
+import onHeaders from 'on-headers';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+/** A Content-Security-Policy written by its real directive names, e.g. `{ 'frame-ancestors': ["'self'"] }`. */
+export type TCspDirectives = Readonly<Record<string, readonly string[]>>;
+
+export type TCspReportOnly = {
+    /** A complete policy, sent as `Content-Security-Policy-Report-Only` on the answers that carry the app policy. */
+    policy: TCspDirectives;
+    /** Appended to the report-only policy as `report-uri`. */
+    reportUri?: string;
+};
+
+/** The four historical lists. Proteum adds `'unsafe-inline' 'self' 'unsafe-eval'` to the scripts. */
+export type TCspLegacyConfig = {
+    default?: readonly string[];
+    styles?: readonly string[];
+    images?: readonly string[];
+    scripts: readonly string[];
+    /** More enforced directives by their real names, appended after the four lists. */
+    directives?: TCspDirectives;
+    policy?: undefined;
+    reportOnly?: TCspReportOnly;
+};
+
+/** A complete enforced policy written in full by the app: Proteum adds nothing to it. */
+export type TCspPolicyConfig = {
+    policy: TCspDirectives;
+    default?: undefined;
+    styles?: undefined;
+    images?: undefined;
+    scripts?: undefined;
+    directives?: undefined;
+    reportOnly?: TCspReportOnly;
+};
+
+export type TCspConfig = TCspLegacyConfig | TCspPolicyConfig;
+
+export type TContentSecurityPolicyHeaders = {
+    /** The enforced `Content-Security-Policy` value: router answers outside `/api`, HTML under `/api`. */
+    policy: string;
+    /** The `Content-Security-Policy-Report-Only` value, on the answers that carry the app policy, when configured. */
+    reportOnly?: string;
+};
+
+type TDirectiveEntries = Array<[string, string[]]>;
+
+/*----------------------------------
+- CONSTANTS
+----------------------------------*/
+
+export const contentSecurityPolicyHeader = 'Content-Security-Policy';
+export const contentSecurityPolicyReportOnlyHeader = 'Content-Security-Policy-Report-Only';
+
+/** Directives the four legacy lists own, whether or not the list is filled. */
+const legacyDirectiveNames = new Set(['default-src', 'script-src', 'style-src', 'img-src']);
+const legacyListNames = ['default', 'styles', 'images', 'scripts'] as const;
+const cspKeys = new Set<string>([...legacyListNames, 'directives', 'policy', 'reportOnly']);
+const reportOnlyKeys = new Set(['policy', 'reportUri']);
+
+/** The CSP 3 directives a browser understands: any other name is a typo the browser would ignore. */
+const knownDirectiveNames = new Set([
+    'base-uri',
+    'block-all-mixed-content',
+    'child-src',
+    'connect-src',
+    'default-src',
+    'fenced-frame-src',
+    'font-src',
+    'form-action',
+    'frame-ancestors',
+    'frame-src',
+    'img-src',
+    'manifest-src',
+    'media-src',
+    'object-src',
+    'report-to',
+    'report-uri',
+    'require-trusted-types-for',
+    'sandbox',
+    'script-src',
+    'script-src-attr',
+    'script-src-elem',
+    'style-src',
+    'style-src-attr',
+    'style-src-elem',
+    'trusted-types',
+    'upgrade-insecure-requests',
+    'webrtc',
+    'worker-src',
+]);
+/** Directives that take no value at all. */
+const valuelessDirectiveNames = new Set(['upgrade-insecure-requests', 'block-all-mixed-content']);
+/** Directives whose value list may be empty. */
+const optionalValueDirectiveNames = new Set(['sandbox', 'trusted-types']);
+/** Directives whose values are tokens or addresses, not sources. */
+const nonSourceDirectiveNames = new Set(['sandbox', 'report-uri', 'report-to']);
+/** Keywords that only mean something inside single quotes: bare, they name a host. */
+const quotedKeywords = new Set([
+    'self',
+    'none',
+    'unsafe-inline',
+    'unsafe-eval',
+    'unsafe-hashes',
+    'strict-dynamic',
+    'report-sample',
+    'wasm-unsafe-eval',
+]);
+/** Printable ASCII with no whitespace, `;` or `,`: anything else breaks the header or the directive list. */
+const headerTokenPattern = /^[\x21-\x2b\x2d-\x3a\x3c-\x7e]+$/;
+/** HTML documents: under `/api`, the only answers that get the app policy. */
+const documentContentTypePattern = /^\s*(?:text\/html|application\/xhtml\+xml)\s*(?:;|$)/i;
+
+/*----------------------------------
+- BUILD (boot time)
+----------------------------------*/
+
+const fail = (message: string): never => {
+    throw new Error(`[http.csp] ${message}`);
+};
+
+// @boundary The csp config may be written in plain JavaScript (or spread from shared objects), so every
+// reader below takes its input as untyped and checks each field before use.
+type TConfigInput = unknown;
+
+const isPlainRecord = (value: TConfigInput): value is Record<string, TConfigInput> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const readToken = (label: string, token: TConfigInput): string => {
+    if (typeof token !== 'string' || !headerTokenPattern.test(token))
+        return fail(`${label} must be a non-empty source in printable ASCII with no whitespace, ";" or "," (got ${JSON.stringify(token)}).`);
+    return token;
+};
+
+/**
+ * A legacy list entry keeps its 2.6 meaning: helmet joined the entries with spaces, so an entry holding
+ * several space-separated sources is kept as written (each source checked) and writes the same bytes.
+ */
+const readLegacyList = (label: string, value: TConfigInput): string[] => {
+    if (value === undefined) return [];
+    if (!Array.isArray(value)) return fail(`${label} must be an array of sources.`);
+
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string') return fail(`${label}[${index}] must be a string.`);
+
+        const sources = entry.split(' ').filter((source) => source !== '');
+        if (sources.length === 0)
+            return fail(`${label}[${index}] is empty: an empty entry would send an empty source list, which blocks everything.`);
+        for (const source of sources) readToken(`${label}[${index}]`, source);
+
+        return entry;
+    });
+};
+
+const readSource = (label: string, directiveName: string, source: TConfigInput): string => {
+    const token = readToken(label, source);
+    if (nonSourceDirectiveNames.has(directiveName)) return token;
+
+    if (quotedKeywords.has(token.toLowerCase()))
+        return fail(`${label} is the bare word ${JSON.stringify(token)}, which names a host: write "'${token}'" with its single quotes.`);
+    const startsQuoted = token.startsWith("'");
+    const endsQuoted = token.endsWith("'");
+    if ((startsQuoted || endsQuoted) && !(startsQuoted && endsQuoted && token.length > 2 && !token.slice(1, -1).includes("'")))
+        return fail(`${label} has unbalanced single quotes: ${JSON.stringify(token)}.`);
+
+    return token;
+};
+
+/** Validates a directive record and returns it as ordered `[name, sources]` entries. */
+const readDirectives = (label: string, value: TConfigInput): TDirectiveEntries => {
+    if (!isPlainRecord(value)) return fail(`${label} must be an object of directive name to sources.`);
+
+    return Object.entries(value).map(([name, sources]) => {
+        if (!knownDirectiveNames.has(name))
+            return fail(`${label} has an unknown directive name ${JSON.stringify(name)}: use a real CSP directive name, lowercase, e.g. "frame-ancestors".`);
+        if (!Array.isArray(sources)) return fail(`${label}['${name}'] must be an array of sources.`);
+
+        const values = sources.map((source, index) => readSource(`${label}['${name}'][${index}]`, name, source));
+        if (valuelessDirectiveNames.has(name) && values.length > 0)
+            return fail(`${label}['${name}'] takes no value: write an empty array.`);
+        if (values.length === 0 && !valuelessDirectiveNames.has(name) && !optionalValueDirectiveNames.has(name))
+            return fail(`${label}['${name}'] is empty: a directive needs at least one source.`);
+
+        return [name, values];
+    });
+};
+
+/** A misspelt key (`reportonly`, `directive`) would otherwise boot and send nothing. */
+const assertKnownKeys = (label: string, value: Record<string, TConfigInput>, known: ReadonlySet<string>) => {
+    const unknownKeys = Object.keys(value).filter((key) => !known.has(key));
+    if (unknownKeys.length > 0)
+        fail(`${label} has unknown keys ${unknownKeys.map((key) => JSON.stringify(key)).join(', ')}: expected ${[...known].join(', ')}.`);
+};
+
+/** Serializes directives in helmet 4.6's exact format, so legacy headers stay byte for byte. */
+const serializeDirectives = (directives: TDirectiveEntries) =>
+    directives.map(([name, values]) => (values.length === 0 ? name : `${name} ${values.join(' ')}`)).join(';');
+
+const buildLegacyDirectives = (config: Record<string, TConfigInput>): TDirectiveEntries => {
+    if (config.scripts === undefined) fail('csp.scripts is required with the list form (an empty array is fine), or write the whole policy in csp.policy.');
+    const defaults = readLegacyList('csp.default', config.default);
+    const scripts = readLegacyList('csp.scripts', config.scripts);
+    const styles = readLegacyList('csp.styles', config.styles);
+    const images = readLegacyList('csp.images', config.images);
+
+    const directives: TDirectiveEntries = [];
+    if (defaults.length > 0) directives.push(['default-src', defaults]);
+    directives.push(['script-src', ["'unsafe-inline'", "'self'", "'unsafe-eval'", ...scripts]]);
+    if (styles.length > 0) directives.push(['style-src', styles]);
+    if (images.length > 0) directives.push(['img-src', images]);
+
+    if (config.directives !== undefined) {
+        const extra = readDirectives('csp.directives', config.directives);
+        for (const [name] of extra) {
+            if (legacyDirectiveNames.has(name))
+                fail(`csp.directives names ${JSON.stringify(name)}, which the legacy lists own: use default, scripts, styles or images, or write the whole policy in csp.policy.`);
+        }
+        directives.push(...extra);
+    }
+
+    return directives;
+};
+
+const buildReportOnlyDirectives = (value: TConfigInput): TDirectiveEntries => {
+    if (!isPlainRecord(value)) return fail('csp.reportOnly must be an object with a policy.');
+    assertKnownKeys('csp.reportOnly', value, reportOnlyKeys);
+
+    const directives = readDirectives('csp.reportOnly.policy', value.policy);
+    if (directives.length === 0) fail('csp.reportOnly.policy has no directive.');
+
+    if (value.reportUri !== undefined) {
+        const reportUri = readToken('csp.reportOnly.reportUri', value.reportUri);
+        if (directives.some(([name]) => name === 'report-uri'))
+            fail('csp.reportOnly sets report-uri twice: keep reportUri or the policy entry, not both.');
+        directives.push(['report-uri', [reportUri]]);
+    }
+
+    return directives;
+};
+
+/**
+ * Builds the policy header values once, at boot.
+ * Throws on any malformed config, so a broken header can never reach production.
+ */
+export const buildContentSecurityPolicyHeaders = (cspConfig: TCspConfig): TContentSecurityPolicyHeaders => {
+    const config: TConfigInput = cspConfig;
+    if (!isPlainRecord(config)) return fail('csp must be an object.');
+    assertKnownKeys('csp', config, cspKeys);
+
+    let directives: TDirectiveEntries;
+    if (config.policy !== undefined) {
+        const legacyFields = [...legacyListNames, 'directives'].filter((name) => config[name] !== undefined);
+        if (legacyFields.length > 0)
+            fail(`csp.policy replaces the whole policy, so ${legacyFields.join(', ')} must be absent.`);
+
+        directives = readDirectives('csp.policy', config.policy);
+        if (directives.length === 0) fail('csp.policy has no directive.');
+    } else {
+        directives = buildLegacyDirectives(config);
+    }
+
+    const headers: TContentSecurityPolicyHeaders = { policy: serializeDirectives(directives) };
+    if (config.reportOnly !== undefined) headers.reportOnly = serializeDirectives(buildReportOnlyDirectives(config.reportOnly));
+
+    return headers;
+};
+
+/*----------------------------------
+- WRITE (request time)
+----------------------------------*/
+
+const readContentType = (res: express.Response) => {
+    const value = res.getHeader('Content-Type');
+    if (Array.isArray(value)) return value[0];
+    return typeof value === 'string' ? value : undefined;
+};
+
+/** Adds the report-only policy when the headers are written, if the answer still carries the app policy. */
+const writeReportOnlyWithAppPolicy = (res: express.Response, headers: TContentSecurityPolicyHeaders) => {
+    if (headers.reportOnly === undefined) return;
+    if (res.getHeader(contentSecurityPolicyHeader) !== headers.policy) return;
+    if (res.hasHeader(contentSecurityPolicyReportOnlyHeader)) return;
+
+    res.setHeader(contentSecurityPolicyReportOnlyHeader, headers.reportOnly);
+};
+
+/**
+ * Outside `/api`: every router answer gets the app policy, whatever its type, as in 2.6
+ * (a worker takes its policy from its own script's answer, so a route-served worker must keep it).
+ * Set at the start of the request, so a route that writes its own policy replaces it.
+ */
+export const createAppContentSecurityPolicy =
+    (headers: TContentSecurityPolicyHeaders): express.RequestHandler =>
+    (_req, res, next) => {
+        res.setHeader(contentSecurityPolicyHeader, headers.policy);
+        if (headers.reportOnly !== undefined)
+            onHeaders(res, function writeReportOnly(this: express.Response) {
+                writeReportOnlyWithAppPolicy(this, headers);
+            });
+
+        next();
+    };
+
+/**
+ * Under `/api`: decides the policy when the headers are about to be written, by the final status and Content-Type.
+ * Mount it after helmet: the value helmet wrote at the start of the request is the baseline.
+ * - a route wrote or removed its own policy: everything is left as it is;
+ * - a 304: no policy at all, so the browser keeps the one its stored copy came with;
+ * - an HTML document: the app policy, plus the report-only policy when configured;
+ * - anything else: helmet's value stays.
+ */
+export const createApiContentSecurityPolicyWriter =
+    (headers: TContentSecurityPolicyHeaders): express.RequestHandler =>
+    (_req, res, next) => {
+        const baseline = res.getHeader(contentSecurityPolicyHeader);
+
+        onHeaders(res, function writeContentSecurityPolicy(this: express.Response) {
+            if (this.getHeader(contentSecurityPolicyHeader) !== baseline) return;
+
+            // A 304 refreshes the stored copy's headers: helmet's default there would replace the page's policy.
+            if (this.statusCode === 304) {
+                this.removeHeader(contentSecurityPolicyHeader);
+                return;
+            }
+
+            const contentType = readContentType(this);
+            if (contentType === undefined || !documentContentTypePattern.test(contentType)) return;
+
+            this.setHeader(contentSecurityPolicyHeader, headers.policy);
+            writeReportOnlyWithAppPolicy(this, headers);
+        });
+
+        next();
+    };

package/tests/app-shaped-typecheck.test.cjs

@@ -0,0 +1,74 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const ts = require('typescript');
+
+const coreRoot = path.join(__dirname, '..');
+
+/** The `declare module '<name>'` names of a declaration file. */
+const declaredModules = (filepath) =>
+    [...fs.readFileSync(filepath, 'utf8').matchAll(/^declare module '([^']+)'/gm)].map((match) => match[1]);
+
+// Apps include `types/global` only (see the scaffold's server tsconfig), while Proteum's own tsc also reads
+// `types/vendors.d.ts`: a vendor declared in the root file alone typechecks here and fails in every app.
+test('every vendor module declared for Proteum is declared for apps too', () => {
+    const root = declaredModules(path.join(coreRoot, 'types/vendors.d.ts'));
+    const global = new Set(declaredModules(path.join(coreRoot, 'types/global/vendors.d.ts')));
+
+    assert.deepEqual(
+        root.filter((name) => !global.has(name)),
+        [],
+        'add these blocks to types/global/vendors.d.ts',
+    );
+});
+
+test('an app-shaped program reaching the HTTP server finds a declaration for every untyped vendor', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-app-typecheck-'));
+    try {
+        fs.mkdirSync(path.join(appRoot, 'node_modules'));
+        fs.mkdirSync(path.join(appRoot, 'server'));
+        fs.symlinkSync(coreRoot, path.join(appRoot, 'node_modules', 'proteum'), 'dir');
+        fs.writeFileSync(
+            path.join(appRoot, 'server', 'probe.ts'),
+            "import HttpServer from '@server/services/router/http';\nexport type Probe = typeof HttpServer;\n",
+        );
+
+        // The shape of an app's server tsconfig: Proteum's base config, `types/global` only, noImplicitAny.
+        const proteum = './node_modules/proteum';
+        const config = ts.parseJsonConfigFileContent(
+            {
+                extends: `${proteum}/tsconfig.common.json`,
+                compilerOptions: {
+                    noEmit: true,
+                    rootDir: '.',
+                    baseUrl: '.',
+                    noImplicitAny: true,
+                    paths: {
+                        '@client/*': [`${proteum}/client/*`],
+                        '@common/*': [`${proteum}/common/*`],
+                        '@server/*': [`${proteum}/server/*`],
+                        react: [`${proteum}/node_modules/preact/compat`],
+                        'react-dom': [`${proteum}/node_modules/preact/compat`],
+                        'react/jsx-runtime': [`${proteum}/node_modules/preact/jsx-runtime`],
+                    },
+                },
+                include: ['./server/probe.ts', `${proteum}/types/global`],
+            },
+            ts.sys,
+            appRoot,
+        );
+        const program = ts.createProgram(config.fileNames, config.options);
+
+        // TS7016 is the B1 failure: a vendor with no types and no declaration. The harness has no generated
+        // `.proteum` files and no app code, so the other diagnostics are not this test's subject.
+        const missingDeclarations = ts
+            .getPreEmitDiagnostics(program)
+            .filter((diagnostic) => diagnostic.code === 7016)
+            .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('.')[0]);
+
+        assert.deepEqual(missingDeclarations, []);
+    } finally {
+        fs.rmSync(appRoot, { recursive: true, force: true });
+    }
+});

package/tests/client-output-names.test.cjs

@@ -0,0 +1,114 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+require('ts-node/register/transpile-only');
+
+const { rspack } = require('@rspack/core');
+const { getClientOutputNames } = require('../cli/compiler/client/outputNames');
+const createFileRules = require('../cli/compiler/common/files/autres');
+const { writeClientManifest } = require('../cli/compiler/common/clientManifest');
+const { defaultHttpCacheConfig, resolvePublicAssetCacheControl } = require('../server/services/router/http/cache');
+
+/*----------------------------------
+- HARNESS
+----------------------------------*/
+
+// A client shaped like a Proteum app: an entry with CSS, a runtime chunk and a lazy page chunk with its own CSS
+const writeFixture = (root) => {
+    const write = (file, content) => fs.writeFileSync(path.join(root, file), content);
+    write('index.js', "import './entry.css';\nimport(/* webpackChunkName: 'pages_domains' */ './page.js').then((page) => page.default());\n");
+    write('entry.css', "@font-face { font-family: Brand; src: url('./brand.woff2') format('woff2'); }\nbody { color: #111; }\n");
+    write('brand.woff2', 'wOF2 fixture bytes');
+    write('page.js', "import './page.css';\nexport default () => document.body.setAttribute('data-page', 'domains');\n");
+    write('page.css', '.page { color: #222; }\n');
+};
+
+const compile = (root, dev) => {
+    const names = getClientOutputNames(dev);
+    const compiler = rspack({
+        mode: dev ? 'development' : 'production',
+        context: root,
+        target: 'web',
+        devtool: false,
+        entry: { client: './index.js' },
+        output: { path: path.join(root, 'public'), publicPath: '/public/', filename: names.entry, chunkFilename: names.chunk },
+        module: {
+            rules: [
+                { test: /\.css$/, use: [rspack.CssExtractRspackPlugin.loader, require.resolve('css-loader')], type: 'javascript/auto' },
+                // The app compiler's own font rule
+                ...createFileRules(undefined, dev, true),
+            ],
+        },
+        plugins: [new rspack.CssExtractRspackPlugin({ filename: names.css, chunkFilename: names.css })],
+        optimization: { runtimeChunk: { name: 'runtime' }, minimize: false },
+    });
+
+    return new Promise((resolve, reject) =>
+        compiler.run((error, stats) => {
+            compiler.close(() => {});
+            if (error) return reject(error);
+            if (stats.hasErrors()) return reject(new Error(stats.toString({ all: false, errors: true })));
+            resolve(writeClientManifest(stats, root));
+        }),
+    );
+};
+
+const cacheControlFor = (asset) =>
+    resolvePublicAssetCacheControl({
+        res: { req: { originalUrl: `/public/${asset}` } },
+        filePath: `/app/bin/public/${asset}`,
+        profile: 'prod',
+        cache: defaultHttpCacheConfig.publicAssets,
+    });
+
+let root;
+beforeAll(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-output-names-'));
+    writeFixture(root);
+});
+afterAll(() => fs.rmSync(root, { recursive: true, force: true }));
+
+/*----------------------------------
+- TESTS
+----------------------------------*/
+
+test('production names every client file with a content hash, entries included', async () => {
+    const manifest = await compile(root, false);
+    const entry = manifest.entries.client;
+    const page = manifest.chunks.pages_domains;
+
+    assert.deepEqual(entry.js.map((asset) => asset.replace(/\.[a-f0-9]{8}\.js$/, '.js')), ['runtime.js', 'client.js']);
+    assert.deepEqual(entry.css.map((asset) => asset.replace(/\.[a-f0-9]{8}\.css$/, '.css')), ['client.css']);
+    assert.match(page.css[0], /^pages_domains\.[a-f0-9]{8}\.css$/);
+    assert.match(page.js[0], /^\d+\.[a-f0-9]{8}\.js$/);
+
+    // The stylesheet names the font, which carries its own hash
+    const font = fs.readdirSync(path.join(root, 'public', 'fonts'))[0];
+    assert.match(font, /^brand\.[a-f0-9]{8}\.woff2$/);
+    assert.match(fs.readFileSync(path.join(root, 'public', entry.css[0]), 'utf8'), new RegExp(`fonts/${font.replace('.', '\\.')}`));
+
+    // Every file the HTML names is served immutable, so no browser or CDN keeps an old runtime past a deploy
+    for (const asset of [...entry.js, ...entry.css, ...page.js, ...page.css, `fonts/${font}`]) {
+        assert.equal(fs.existsSync(path.join(root, 'public', asset)), true, asset);
+        assert.equal(cacheControlFor(asset), 'public, max-age=31536000, immutable', asset);
+    }
+});
+
+test('a content change renames the file that changed and leaves the others alone', async () => {
+    const before = await compile(root, false);
+    fs.writeFileSync(path.join(root, 'page.css'), '.page { color: #333; }\n');
+    const after = await compile(root, false);
+
+    assert.notEqual(after.chunks.pages_domains.css[0], before.chunks.pages_domains.css[0]);
+    assert.deepEqual(after.entries.client.css, before.entries.client.css);
+});
+
+test('dev keeps the stable names HMR and the dev middleware rely on', async () => {
+    const manifest = await compile(root, true);
+
+    assert.deepEqual(manifest.entries.client.js, ['runtime.js', 'client.js']);
+    assert.deepEqual(manifest.entries.client.css, ['client.css']);
+    assert.deepEqual(manifest.chunks.pages_domains.css, ['pages_domains.css']);
+});