@jk2908/solas 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.16.0
+
+### Breaking
+
+- Raised `engines.node` to `^22.23.4 || >=24.22.1`. Node 20 is end of life and does not receive the fix for CVE-2026-111497, a Brotli decoder flaw in Node that allows memory disclosure or code execution when a process decodes attacker-controlled Brotli data. Solas never decodes Brotli itself, but apps on `@jk2908/solas/runtime/node` should run a patched Node, particularly when they fetch responses an attacker can influence, since Node's `fetch` decodes `content-encoding: br` automatically.
+
+### Features
+
+- Middleware can pass a replacement request to `next(request)`, so it can add headers for downstream middleware and rendering.
+- A structured `csp` config generates nonce and hash-based policies for dynamic, full, and PPR routes. CSP keywords can be written without their surrounding quotes. It cannot be combined with a `Content-Security-Policy` header in the `headers` config; a request CSP still takes precedence. The static adapter writes the generated policy as a meta tag in each prerendered page.
+- Nonce-based CSP is supported for dynamically rendered HTML. Solas reads the nonce from the effective `Content-Security-Policy` set by middleware, an upstream proxy, or the `headers` config, applies it to the scripts it generates, and exposes it as `x-nonce` from `headers()`. Full routes do not receive nonces; PPR uses a nonce only for its resumed holes.
+- Fully prerendered routes served by Solas receive build-time SHA-256 hashes for their inline scripts and styles. Solas appends the hashes to the effective CSP, so the HTML can stay cacheable without a nonce.
+- PPR responses use hashes for the cached prelude and a request nonce for the resumed holes. Solas puts the nonce on the prelude bootstrap, so `strict-dynamic` and client-side nonce access keep working for the dynamic parts.
+- Client navigations, prefetches, and server actions reuse the document nonce, so inline styles and scripts rendered after the initial load keep matching the document CSP. Hoistable `<style href precedence>` tags, including `@jk2908/cxx`, receive the nonce when the app passes it to the tag.
+
 ## 0.15.1
 
 ### Fixes

package/README.md

@@ -6,7 +6,7 @@ Solas is experimental and under active development, so expect rough edges.
 
 ## Install
 
-Solas requires **Vite 8** (which uses Rolldown as the bundler).
+Solas requires **Vite 8** (which uses Rolldown as the bundler) and **Node.js 22.23.4, 24.22.1 or newer** when using the Node runtime. Node 20 is end of life, and these are the first releases with the fix for [CVE-2026-111497](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases), a Brotli decoder flaw in Node. Solas does not decode Brotli, but your app might, including through `fetch`, which decodes `content-encoding: br` for you.
 
 ```sh
 npm install @jk2908/solas react react-dom react-server-dom-webpack vite@^8
@@ -71,7 +71,7 @@ Use these filename conventions:
 - `+layout.tsx`: shared layout for a route branch.
 - `+page.tsx`: page component for a route.
 - `+endpoint.ts`: request handler. Can be placed in any folder and responds to all HTTP methods for its route path.
-- `+middleware.ts`: middleware that runs for the current route branch and is inherited by child routes. Parent and child middleware stack together.
+- `+middleware.ts`: middleware that runs for the current route branch and is inherited by child routes. Parent and child middleware stack together. Call `next()` to continue, or `next(request)` to pass a replacement request with different headers downstream.
 - `+loading.tsx`: loading fallback inherited by child routes.
 - `+401.tsx`: boundary for unauthorised responses in the current route branch and its children.
 - `+403.tsx`: boundary for forbidden responses in the current route branch and its children.
@@ -478,17 +478,7 @@ solas({
 })
 ```
 
-Pass a function to vary the headers per request, for example a per-request CSP nonce:
-
-```ts
-solas({
-	headers: req => ({
-		'Content-Security-Policy': `default-src 'self'; script-src 'nonce-${nonce(req)}'`,
-	}),
-})
-```
-
-The function can be async. Configured headers win over any header Solas sets.
+Pass a function to vary the headers per request. The function can be async. Configured headers win over any header Solas sets, except that a `Content-Security-Policy` on the request takes precedence over a configured one. See [Security > CSP](#csp) for the nonce pattern.
 
 ### `sitemap`
 
@@ -814,6 +804,49 @@ If you run Vite through Bun, use the Bun-backed commands instead:
 
 ## Security
 
+### CSP
+
+Use the `csp` config to generate a policy:
+
+```ts
+solas({
+	csp: {
+		directives: {
+			'default-src': ['self'],
+			'script-src': ['self'],
+			'style-src': ['self'],
+			'img-src': ['self', 'data:'],
+			'object-src': ['none'],
+			'base-uri': ['self'],
+		},
+	},
+})
+```
+
+CSP keywords such as `self` and `none` can be written without their surrounding quotes. Solas adds a per-request nonce to dynamic responses, build-time hashes to full prerenders, and both to PPR. It also keeps client navigations aligned with the document policy.
+
+Read the nonce in a server component for any inline `<style>` or `<script>` you render:
+
+```tsx
+const nonce = (await headers()).get('x-nonce')
+
+return <style nonce={nonce}>{`body { margin: 0 }`}</style>
+```
+
+Hoistable `<style href precedence>` tags, including `@jk2908/cxx`, need the same nonce prop. Add `'unsafe-eval'` in development for React's error stacks.
+
+Full hash-only pages should use `script-src 'self'` rather than `'strict-dynamic'`. Browsers do not propagate hash trust from the bootstrap to its dynamic `import()`. Dynamic and PPR responses can use `'strict-dynamic'` because their bootstrap has a nonce.
+
+To use a completely custom policy, set CSP in middleware or a `headers` function. A CSP on the request wins. When `csp` is configured, it owns the generated HTML policy; a CSP returned from a `headers` function is not used for HTML. Use one source.
+
+With the static adapter, the generated policy is written as a `<meta http-equiv="Content-Security-Policy">` tag in each prerendered page. `frame-ancestors`, `report-uri`, and `sandbox` are ignored in meta; use host-level headers if you need them.
+
+Solas expects one effective CSP policy. If middleware or a proxy sets multiple policies, combine them into a single header before Solas sees the response. The Fetch API merges multiple headers, and Solas cannot safely add hashes to that merged value.
+
+The build warns when the generated CSP header for a route exceeds 8 KB because of the prerendered style hash union. Reduce hash-bearing prerendered styles or raise the server header limit in that case.
+
+Hashes cover inline `<script>` and `<style>` elements, not `style` attributes. If full static pages can insert inline styles during client navigation, keep `style-src 'unsafe-inline'` for those pages.
+
 ### CSRF
 
 Solas protects server actions and `+endpoint` handlers against CSRF.

package/dist/adapters/cloudflare/vite.d.ts

@@ -20,5 +20,6 @@ export type SolasCloudflareOptions = {
 export declare function adapter(options?: SolasCloudflareOptions): {
     name: string;
     plugins: PluginOption[];
+    postbuild(config: import("vite").ResolvedConfig): import("../../internal/postbuild.js").PrerenderImport | undefined;
 };
 export {};

package/dist/adapters/cloudflare/vite.js

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { cloudflare as cloudflareVitePlugin } from '@cloudflare/vite-plugin';
 import * as Config from '../../config.js';
 import { writeCloudflareEntry } from '../../internal/codegen/environments.js';
-import { setPrerenderImport, setRscEntry } from '../../internal/postbuild.js';
 import { NAMESPACE_PREFIX } from '../../runtime/cloudflare/assets.js';
 import { withBindingsShim } from './bindings.js';
 const VIRTUAL_ENTRY = 'virtual:solas-cloudflare-entry';
@@ -120,18 +119,6 @@ export function adapter(options = {}) {
     const adapter = {
         name: 'solas-cloudflare',
         enforce: 'post',
-        configResolved(config) {
-            // the Cloudflare plugin points the `rsc` environment's build output at
-            // the Worker bundle during its `config` hook, so by now we know where
-            // Solas's prerender step should import the Worker from
-            const rscOutDir = config.environments.rsc?.build.outDir;
-            if (rscOutDir) {
-                setRscEntry(path.resolve(cwd, rscOutDir, 'index.js'));
-            }
-            // the Worker bundle imports `cloudflare:workers`, which only exists in
-            // workerd, so shim it around the Node import
-            setPrerenderImport(withBindingsShim);
-        },
         configEnvironment(name, environment) {
             // Pre-bundle the Worker environments so workerd never has to re-optimize
             // dependencies in the middle of a request. Scanning the app directory
@@ -168,5 +155,15 @@ export function adapter(options = {}) {
         },
     };
     const plugins = [adapter, ...cfPlugins];
-    return { name: 'cloudflare', plugins };
+    return {
+        name: 'cloudflare',
+        plugins,
+        postbuild(config) {
+            const rscOutDir = config.environments.rsc?.build.outDir;
+            if (!rscOutDir)
+                return;
+            const entry = path.resolve(cwd, rscOutDir, 'index.js');
+            return withBindingsShim(() => import(/* @vite-ignore */ entry));
+        },
+    };
 }

package/dist/adapters/static.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import * as Config from '../config.js';
+import { buildPolicy, injectMetaTag } from '../internal/csp.js';
 import { Features, guards } from '../internal/guards.js';
+import { staticRoutePath } from '../internal/prerender.js';
+import { loadManifest } from '../manifest.js';
 const ROOT_FILES = ['sitemap.xml', 'robots.txt'];
 /**
  * Static site adapter for Solas.
@@ -41,6 +44,35 @@ function adapter(options = {}) {
                         await fs.copyFile(source, path.join(target, file));
                     }
                 }
+                const manifest = await loadManifest();
+                const csp = manifest?.csp;
+                if (!csp)
+                    return;
+                const mode = manifest.trailingSlash === 'always' ? 'always' : 'never';
+                const styleHashes = [
+                    ...new Set(Object.values(manifest.artifacts).flatMap(artifact => artifact.csp?.style ?? [])),
+                ];
+                await Promise.all(Object.entries(manifest.artifacts).map(async ([route, artifact]) => {
+                    if (artifact.mode !== 'full')
+                        return;
+                    const file = path.join(target, staticRoutePath(route, mode));
+                    let html;
+                    try {
+                        html = await fs.readFile(file, 'utf-8');
+                    }
+                    catch {
+                        return;
+                    }
+                    const policy = buildPolicy(csp.directives, {
+                        hashes: {
+                            script: artifact.csp?.script ?? [],
+                            style: [...new Set([...(artifact.csp?.style ?? []), ...styleHashes])],
+                        },
+                    });
+                    if (!policy)
+                        return;
+                    await fs.writeFile(file, injectMetaTag(html, policy));
+                }));
             },
         },
     };

package/dist/config.js

@@ -1,3 +1,4 @@
+import { isRecord, isStringArray } from './utils/validation.js';
 export const NAME = 'Solas';
 export const SLUG = NAME.toLowerCase();
 export const PKG_NAME = `@jk2908/${SLUG}`;
@@ -18,6 +19,7 @@ export const TRAILING_SLASH_MODES = ['always', 'never', 'ignore'];
 export const RUNTIME_MANIFEST = 'runtime-manifest.json';
 const CONFIG_KEYS = new Set([
     'adapter',
+    'csp',
     'headers',
     'logger',
     'metadata',
@@ -85,6 +87,36 @@ export function validate(input, envUrl) {
             errors.push('headers must be an object or a function that returns one');
         }
     }
+    if ('csp' in input && input.csp !== undefined) {
+        const csp = input.csp;
+        if (!isRecord(csp)) {
+            errors.push('csp must be an object');
+        }
+        else {
+            for (const key of Object.keys(csp)) {
+                if (key !== 'directives') {
+                    errors.push(`Unknown csp key: ${key}`);
+                }
+            }
+            if (!isRecord(csp.directives)) {
+                errors.push('csp.directives must be an object of string arrays');
+            }
+            else {
+                for (const [name, values] of Object.entries(csp.directives)) {
+                    if (!isStringArray(values)) {
+                        errors.push(`csp.directives.${name} must be an array of strings`);
+                    }
+                }
+            }
+        }
+        if (isRecord(input.headers)) {
+            for (const key of Object.keys(input.headers)) {
+                if (key.toLowerCase() === 'content-security-policy') {
+                    errors.push('csp cannot be combined with a Content-Security-Policy header');
+                }
+            }
+        }
+    }
     if ('trustedOrigins' in input && input.trustedOrigins !== undefined) {
         if (!Array.isArray(input.trustedOrigins)) {
             errors.push('trustedOrigins must be an array of origins');
@@ -159,6 +191,3 @@ export function validate(input, envUrl) {
     }
     return input;
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/dist/index.js

@@ -28,7 +28,7 @@ const DEFAULT_CONFIG = {
  */
 function normaliseOrigin(value) {
     if (!value)
-        return undefined;
+        return;
     return new URL(value).origin;
 }
 function solas(c) {
@@ -356,7 +356,13 @@ function solas(c) {
         buildApp: {
             order: 'post',
             async handler() {
-                await postbuild(resolvedViteConfig?.root ?? process.cwd());
+                if (!resolvedViteConfig)
+                    throw new Error('Vite config not resolved yet');
+                const load = await config.adapter?.postbuild?.(resolvedViteConfig);
+                await postbuild(resolvedViteConfig.root, {
+                    csp: config.csp,
+                    load,
+                });
             },
         },
     };

package/dist/internal/browser-router/router.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { createFromFetch } from '@vitejs/plugin-rsc/browser';
+import { getDocumentNonce } from '../../utils/get-document-nonce.js';
 import { Logger } from '../../utils/logger.js';
 import * as Events from '../../events.js';
 import { BrowserRouterHistory } from './history.js';
@@ -43,9 +44,14 @@ function getPayloadUrl(path) {
     return url;
 }
 function performNavigationFetch(path, init) {
-    return STATIC
-        ? fetch(getPayloadUrl(path), init)
-        : fetch(path, { ...init, headers: { ...init?.headers, accept: 'text/x-component' } });
+    if (STATIC)
+        return fetch(getPayloadUrl(path), init);
+    const headers = new Headers(init?.headers);
+    headers.set('accept', 'text/x-component');
+    const nonce = getDocumentNonce();
+    if (nonce)
+        headers.set('x-solas-nonce', nonce);
+    return fetch(path, { ...init, headers });
 }
 const MAX_HASH_ATTEMPTS = 20;
 function nextFrame(callback) {

package/dist/internal/csp.d.ts

@@ -0,0 +1,37 @@
+import type { CspDirectives } from '../types.js';
+type PolicyInput = {
+    nonce?: string;
+    hashes?: CspHashes;
+};
+export type CspHashes = {
+    script: string[];
+    style: string[];
+};
+/**
+ * Resolve the nonce for a request.
+ *
+ * On RSC and action requests a document nonce supplied by the client wins.
+ * Otherwise the request CSP is authoritative, even when it has no nonce, and
+ * configured headers are the fallback.
+ */
+export declare function resolveNonce(requestCsp: string | null | undefined, configuredHeaders: Record<string, string>, clientNonce?: string | null): string | undefined;
+/**
+ * Build a policy from structured directives, adding a nonce and any prerender
+ * hashes that apply to the response.
+ */
+export declare function buildPolicy(directives: CspDirectives, { nonce, hashes }?: PolicyInput): string;
+/**
+ * Add hash sources to the directives that control inline scripts and styles.
+ * A policy that already allows everything through `'unsafe-inline'` or
+ * `'none'` is left alone, so adding a hash cannot silently tighten it.
+ */
+export declare function addHashesToPolicy(policy: string, hashes: CspHashes): string;
+/**
+ * Add the request nonce to the PPR bootstrap script.
+ */
+export declare function addNonceToBootstrap(html: string, nonce: string): string;
+/**
+ * Add a CSP meta tag to a static document.
+ */
+export declare function injectMetaTag(html: string, policy: string): string;
+export {};

package/dist/internal/csp.js

@@ -0,0 +1,145 @@
+const KEYWORDS = new Set([
+    'self',
+    'none',
+    'unsafe-inline',
+    'unsafe-eval',
+    'unsafe-hashes',
+    'strict-dynamic',
+    'report-sample',
+    'wasm-unsafe-eval',
+    'inline-speculation-rules',
+    'unsafe-allow-redirects',
+]);
+/**
+ * Resolve the nonce for a request.
+ *
+ * On RSC and action requests a document nonce supplied by the client wins.
+ * Otherwise the request CSP is authoritative, even when it has no nonce, and
+ * configured headers are the fallback.
+ */
+export function resolveNonce(requestCsp, configuredHeaders, clientNonce) {
+    if (clientNonce)
+        return clientNonce;
+    if (requestCsp)
+        return extractNonce(requestCsp);
+    return extractNonce(new Headers(configuredHeaders).get('content-security-policy'));
+}
+/**
+ * Build a policy from structured directives, adding a nonce and any prerender
+ * hashes that apply to the response.
+ */
+export function buildPolicy(directives, { nonce, hashes } = {}) {
+    const parsed = Object.entries(directives).map(([name, values]) => ({
+        name: name.toLowerCase(),
+        // keywords such as `self` can be written without quotes; hosts and schemes
+        // stay as written.
+        tokens: values.map(value => {
+            const token = value.trim();
+            if (token.length >= 2 && token.startsWith("'") && token.endsWith("'")) {
+                return token;
+            }
+            if (KEYWORDS.has(token.toLowerCase()))
+                return `'${token.toLowerCase()}'`;
+            if (/^(sha256|sha384|sha512|nonce)-/.test(token))
+                return `'${token}'`;
+            return token;
+        }),
+    }));
+    if (nonce) {
+        const token = `'nonce-${nonce}'`;
+        addNonceToDirective(parsed, ['script-src-elem', 'script-src', 'default-src'], token);
+        addNonceToDirective(parsed, ['style-src-elem', 'style-src', 'default-src'], token);
+    }
+    const policy = parsed.map(formatDirective).join('; ');
+    return hashes ? addHashesToPolicy(policy, hashes) : policy;
+}
+/**
+ * Add hash sources to the directives that control inline scripts and styles.
+ * A policy that already allows everything through `'unsafe-inline'` or
+ * `'none'` is left alone, so adding a hash cannot silently tighten it.
+ */
+export function addHashesToPolicy(policy, hashes) {
+    const directives = policy
+        .split(';')
+        .map(part => part.trim())
+        .filter(Boolean)
+        .map(parseDirective);
+    addHashesToDirective(directives, 'script', hashes);
+    addHashesToDirective(directives, 'style', hashes);
+    return directives.map(formatDirective).join('; ');
+}
+/**
+ * Add the request nonce to the PPR bootstrap script.
+ */
+export function addNonceToBootstrap(html, nonce) {
+    const match = /<script\b[^>]*\bid="_R_"[^>]*>/i.exec(html);
+    if (!match || /\bnonce\s*=/i.test(match[0]))
+        return html;
+    const tag = match[0].replace(/>$/, ` nonce="${escapeAttribute(nonce)}">`);
+    return html.slice(0, match.index) + tag + html.slice(match.index + match[0].length);
+}
+/**
+ * Add a CSP meta tag to a static document.
+ */
+export function injectMetaTag(html, policy) {
+    if (/<meta\b[^>]*http-equiv=["']?content-security-policy/i.test(html)) {
+        return html;
+    }
+    const head = /<head\b[^>]*>/i.exec(html);
+    if (!head)
+        return html;
+    const headEnd = head.index + head[0].length;
+    const charset = /<meta\b[^>]*charset=[^>]*>/i.exec(html.slice(headEnd));
+    const tag = `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(policy)}">`;
+    const at = charset ? headEnd + charset.index + charset[0].length : headEnd;
+    return html.slice(0, at) + tag + html.slice(at);
+}
+function extractNonce(csp) {
+    return csp?.match(/'nonce-([^']+)'/)?.[1] || undefined;
+}
+function addNonceToDirective(directives, names, token) {
+    const directive = names
+        .map(name => directives.find(candidate => candidate.name === name))
+        .find(Boolean);
+    if (!directive)
+        return;
+    if (directive.tokens.some(value => value.toLowerCase() === "'unsafe-inline'" || value.toLowerCase() === "'none'")) {
+        return;
+    }
+    if (!directive.tokens.includes(token))
+        directive.tokens.push(token);
+}
+function addHashesToDirective(directives, kind, hashes) {
+    const values = hashes[kind];
+    if (values.length === 0)
+        return;
+    const names = kind === 'script'
+        ? ['script-src-elem', 'script-src', 'default-src']
+        : ['style-src-elem', 'style-src', 'default-src'];
+    const directive = names
+        .map(name => directives.find(candidate => candidate.name === name))
+        .find(Boolean);
+    if (!directive)
+        return;
+    if (directive.tokens.some(token => token.toLowerCase() === "'unsafe-inline'" || token.toLowerCase() === "'none'")) {
+        return;
+    }
+    for (const value of values) {
+        if (!directive.tokens.includes(value))
+            directive.tokens.push(value);
+    }
+}
+function parseDirective(value) {
+    const [name, ...tokens] = value.split(/\s+/);
+    return { name: name.toLowerCase(), tokens };
+}
+function formatDirective(directive) {
+    return [directive.name, ...directive.tokens].join(' ');
+}
+function escapeAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/dist/internal/env/browser.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { StrictMode, Suspense, useCallback, useState, useTransition } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback, } from '@vitejs/plugin-rsc/browser';
+import { getDocumentNonce } from '../../utils/get-document-nonce.js';
 import { BrowserRouterProvider } from '../browser-router/router.js';
 import { RedirectBoundary } from '../navigation/redirect-boundary.js';
 import { Head } from '../render/head.js';
@@ -34,12 +35,14 @@ export async function browser() {
     setServerCallback(async (id, args) => {
         const url = new URL(window.location.href);
         const temporaryReferences = createTemporaryReferenceSet();
+        const headers = new Headers({ 'x-rsc-action-id': id });
+        const nonce = getDocumentNonce();
+        if (nonce)
+            headers.set('x-solas-nonce', nonce);
         const payload = await createFromFetch(fetch(url, {
             method: 'POST',
             body: await encodeReply(args, { temporaryReferences }),
-            headers: {
-                'x-rsc-action-id': id,
-            },
+            headers,
         }), { temporaryReferences });
         payloadSetter.current(payload);
         const { ok, data } = payload.returnValue ?? {};
@@ -53,7 +56,11 @@ export async function browser() {
     if (import.meta.hot) {
         import.meta.hot.on?.('rsc:update', async () => {
             try {
-                const p = await createFromFetch(fetch(window.location.href, { headers: { Accept: 'text/x-component' } }));
+                const headers = new Headers({ Accept: 'text/x-component' });
+                const nonce = getDocumentNonce();
+                if (nonce)
+                    headers.set('x-solas-nonce', nonce);
+                const p = await createFromFetch(fetch(window.location.href, { headers }));
                 payloadSetter.current(p);
             }
             catch (err) {

package/dist/internal/env/request-context.d.ts

@@ -10,10 +10,12 @@ export declare const RequestContext: {
         req: SolasRequest;
         prerender: "full" | "ppr" | null;
         cache: RequestCache;
+        nonce?: string | undefined;
     };
     write<R>(value: {
         req: SolasRequest;
         prerender: "full" | "ppr" | null;
         cache: RequestCache;
+        nonce?: string | undefined;
     }, fn: () => R | Promise<R>): R | Promise<R>;
 };