@webjsdev/server 0.8.33 → 0.8.34

package/index.d.ts

@@ -457,6 +457,21 @@ export declare function findOrphanComponents(
   appDir: string,
 ): Promise<Array<{ className: string; file: string }>>;
 
+// ---------------------------------------------------------------------------
+// elision-report.js (#646)
+// ---------------------------------------------------------------------------
+
+/**
+ * App-level elision report: the page/layout route modules that SHIP WHOLE to
+ * the browser instead of being elided as carriers, each with the first
+ * client-effecting blocker that pins it (or `null` when the module's own code
+ * is the cause) plus a human reason. A reporting layer over `analyzeElision`,
+ * consumed by the `webjs doctor` carrier-hygiene advisory (#646).
+ */
+export declare function analyzeAppElision(
+  appDir: string,
+): Promise<{ analysed: boolean; shipped: Array<{ file: string; blocker: string | null; reason: string }> }>;
+
 // ---------------------------------------------------------------------------
 // context.js (per-request context helpers)
 // ---------------------------------------------------------------------------

package/index.js

@@ -42,6 +42,7 @@ export {
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
+export { analyzeAppElision } from './src/elision-report.js';
 export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
@@ -68,8 +69,6 @@ export { createAuth, Credentials, Google, GitHub } from './src/auth.js';
 export {
   testRequest,
   toRequest,
-  getCsrf,
-  readCsrfCookie,
   getSetCookies,
   cookiesToHeader,
   withCookies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.33",
+  "version": "0.8.34",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/actions.js

@@ -3,7 +3,7 @@ import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import { walk } from './fs-walk.js';
-import { verify as verifyCsrf, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
+import { verifyOrigin } from './csrf.js';
 import { getSerializer } from './serializer.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import {
@@ -311,7 +311,6 @@ export async function serveActionStub(idx, absFile) {
  */
 function buildStubBody({ hash, method, fnNames, actionUrl }) {
   const URL_ARG = URL_ARG_VERBS.has(method);
-  const SAFE = SAFE_VERBS.has(method);
   const J = JSON.stringify;
   const lines = [];
   lines.push(`// webjs: generated server-action stub (${method})`);
@@ -334,7 +333,8 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   lines.push(`const __METHOD = ${J(method)};`);
   lines.push(`const __MAX = ${MAX_URL_ARGS};`);
   lines.push(`const __CT = ${J(RPC_CONTENT_TYPE)};`);
-  lines.push(`function __csrf() { const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/); return m ? decodeURIComponent(m[1]) : ''; }`);
+  // CSRF is enforced server-side by an Origin-header check, so the stub sends
+  // nothing extra: the browser attaches `Origin` to a same-origin POST itself.
   // Shared: parse a response, surface invalidation, register a GET's tags
   // (stamped with the clock SAMPLED BEFORE the fetch, so a mutation in flight is
   // caught on the next read).
@@ -383,8 +383,8 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // captured SYNCHRONOUSLY at __call entry (#492): the active render signal must
   // be read before the stub's first await (stringify), or the render's
   // synchronous window has already closed and cleared it.
-  lines.push(`async function __body(fn, body, m, csrf, sig) {`);
-  lines.push(`  const headers = { 'content-type': __CT }; if (csrf) headers[${J(CSRF_HEADER)}] = __csrf();`);
+  lines.push(`async function __body(fn, body, m, sig) {`);
+  lines.push(`  const headers = { 'content-type': __CT };`);
   lines.push(`  const res = await fetch(__URL + fn, { method: m, headers, credentials: 'same-origin', body, signal: sig });`);
   lines.push(`  return __handle(res, fn, null);`);
   lines.push(`}`);
@@ -394,14 +394,14 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  const sig = __sig();`); // sync capture before any await
     lines.push(`  const key = await __s(args);`);
     lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
-    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', ${SAFE ? 'false' : 'true'}, sig);`);
+    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', sig);`);
     if (method === 'GET') {
       lines.push(`  const bypass = __stale(key);`);
       lines.push(`  const since = __mark();`);
       lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: 'GET', credentials: 'same-origin', cache: bypass ? 'no-cache' : 'default', signal: sig });`);
       lines.push(`  return __handle(res, fn, key, since);`);
     } else {
-      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, headers: { ${J(CSRF_HEADER)}: __csrf() }, credentials: 'same-origin', signal: sig });`);
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, credentials: 'same-origin', signal: sig });`);
       lines.push(`  return __handle(res, fn, null);`);
     }
     lines.push(`}`);
@@ -413,7 +413,7 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  const sig = __sig();`); // sync capture before any await
     lines.push(`  const key = await __s(args);`);
     lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
-    lines.push(`  return __body(fn, key, __METHOD, true, sig);`);
+    lines.push(`  return __body(fn, key, __METHOD, sig);`);
     lines.push(`}`);
   }
   for (const name of fnNames) {
@@ -436,8 +436,10 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
  *   invoked when the action throws unexpectedly, BEFORE the sanitized 500 is
  *   returned, so an APM integration sees the original error. The caller wraps
  *   it so a throwing sink can never affect the response.
+ * @param {string[]} [allowedOrigins] cross-site origins the CSRF check allows
+ *   (the app's `webjs.allowedOrigins`), for reverse-proxy / multi-domain setups.
  */
-export async function invokeAction(idx, hash, fnName, req, onError) {
+export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = []) {
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
   const mod = await loadModule(file, idx.dev);
@@ -459,10 +461,14 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
       { status: 405, headers: { allow: [...allowed].join(', ') } },
     );
   }
-  // CSRF: required for every verb except a safe GET (a read with no state
-  // change, which is also browser-cacheable so it cannot carry a fresh token).
-  if (!SAFE_VERBS.has(method) && !verifyCsrf(req)) {
-    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
+  // CSRF: an Origin-header check on every state-changing verb (a safe GET is a
+  // read with no state change). A browser sets `Origin` on a cross-site POST to
+  // the ATTACKER's origin, so a forged request fails the host match. No token
+  // or cookie is involved, which keeps SSR HTML free of `Set-Cookie` and so
+  // CDN-cacheable. See csrf.js.
+  if (!SAFE_VERBS.has(method)) {
+    const v = verifyOrigin(req, allowedOrigins);
+    if (!v.ok) return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
   }
 
   // Args ride the URL for a URL-arg request (GET / DELETE), else the body.

package/src/component-elision.js

@@ -843,7 +843,7 @@ export async function computeElidableComponents(components, moduleGraph, readFil
  * @param {import('./module-graph.js').ModuleGraph} moduleGraph
  * @param {(file: string) => Promise<string>} readFileFn
  * @param {string} [appDir]
- * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]> }>}
+ * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }> }>}
  */
 export async function analyzeElision(components, routeModules, moduleGraph, readFileFn, appDir) {
   /** @type {Set<string>} */
@@ -1069,6 +1069,17 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     clientRouterFiles.has(file) ||
     clientGlobalOrBareFiles.has(file);
 
+  // A human reason for WHY a file does client work, for the advisory that
+  // names why a page/layout ships (#646). Mirrors the isClientEffecting
+  // branches, most specific first.
+  const clientEffectReason = (file) => {
+    if (componentFiles.has(file) && mustShip.has(file)) return 'is an interactive component';
+    if (clientRouterFiles.has(file)) return 'imports the client router';
+    if (reactiveFiles.has(file)) return 'imports a reactive primitive (signal / computed / watch)';
+    if (clientGlobalOrBareFiles.has(file)) return 'references a browser global at module scope, runs code at module scope, or has a bare side-effect import';
+    return 'does client work';
+  };
+
   // Route modules fall into three classes by their effective client closure
   // (skipping elided components and server stubs, which never load on the
   // client):
@@ -1091,9 +1102,18 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   const inertRouteModules = new Set();
   /** @type {Map<string, string[]>} route file -> component files to emit in its place */
   const importOnlyRouteModules = new Map();
+  // Advisory (#646): for each route module that SHIPS WHOLE (neither inert nor
+  // import-only), record the first client-effecting blocker so a tool can name
+  // why it ships. blocker is null when the module's OWN code is the cause.
+  /** @type {Map<string, { blocker: string|null, reason: string }>} */
+  const shippedRouteModules = new Map();
   for (const file of routeModules) {
     if (!fileTags.has(file)) continue; // unreadable / not analysed: ship (omit from both sets)
-    if (isClientEffecting(file)) continue; // the module itself ships whole
+    if (isClientEffecting(file)) {
+      // The module itself ships whole; its own signal is the blocker.
+      shippedRouteModules.set(file, { blocker: null, reason: clientEffectReason(file) });
+      continue;
+    }
     const closure = appDir ? transitiveDeps(moduleGraph, [file], appDir, skip) : [];
     const effecting = closure.filter(isClientEffecting);
     if (effecting.length === 0) { inertRouteModules.add(file); continue; }
@@ -1111,11 +1131,15 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     // closure and still loads via the IntersectionObserver `observeLazy` path.
     if (effecting.every((f) => componentFiles.has(f))) {
       importOnlyRouteModules.set(file, effecting);
+    } else {
+      // A client-effecting non-component is reachable; ship the whole module.
+      // Name the FIRST such non-component as the blocker for the advisory.
+      const blocker = effecting.find((f) => !componentFiles.has(f));
+      shippedRouteModules.set(file, { blocker, reason: clientEffectReason(blocker) });
     }
-    // else: a client-effecting non-component is reachable; ship the whole module.
   }
 
-  return { elidableComponents, inertRouteModules, importOnlyRouteModules };
+  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules };
 }
 
 /** Match a whole-line side-effect import: `import './x.js';` (no bindings). */

package/src/csrf.js

@@ -1,47 +1,36 @@
-// Use Web Crypto (globalThis.crypto) for random + hash: works on Node >=20,
-// Deno, Bun, Cloudflare Workers. Avoids the node:crypto import and keeps
-// CSRF portable across runtimes.
-const webCrypto = /** @type {Crypto} */ (globalThis.crypto);
-
 /**
- * Double-submit cookie CSRF protection for `/__webjs/action/*` RPC endpoints.
+ * Cross-origin (CSRF) protection for `/__webjs/action/*` RPC endpoints, via
+ * Fetch-Metadata + Origin verification. This is the model Remix 3's
+ * `cop-middleware` and Go 1.25's `http.CrossOriginProtection` use, and the
+ * spiritual sibling of Next.js / Astro's Origin-vs-Host check.
  *
- * Flow:
- *   1. Every SSR response that lacks the cookie issues a fresh `webjs_csrf`
- *      cookie with `SameSite=Lax; Path=/` (and `Secure` when over HTTPS).
- *      The cookie is readable by JS (not HttpOnly) so the auto-generated
- *      action stub can echo it.
- *   2. The action-stub `fetch` sends the token back in `x-webjs-csrf`.
- *   3. `invokeAction` compares the header to the cookie with constant-time
- *      equality; mismatch → 403.
+ * Why not a token cookie: webjs previously issued a per-request `webjs_csrf`
+ * double-submit cookie on every SSR response. That made SSR HTML
+ * un-cacheable at a CDN (a CDN skips a response with `Set-Cookie`, and a
+ * cached one would share / poison the token across visitors). A header check
+ * needs nothing on the page, so SSR HTML carries no `Set-Cookie` and a page
+ * that opts into a public `Cache-Control` is edge-cacheable.
  *
- * This protects against classic CSRF (a malicious site triggering a POST
- * from a victim browser): cross-origin requests cannot read the cookie, so
- * they cannot set the header to the matching value.
+ * The check, on every state-changing verb (a safe GET is exempt):
+ *   1. `Sec-Fetch-Site` is the primary signal. The browser sets it on every
+ *      request and page JS cannot forge it. `same-origin` / `none` (a direct
+ *      navigation with no initiator) pass; `same-site` / `cross-site` are
+ *      rejected unless the source origin is in `webjs.allowedOrigins`.
+ *   2. When `Sec-Fetch-Site` is absent (an older browser), fall back to
+ *      comparing the `Origin` host to the request host; an absent `Origin`
+ *      can't be checked so it passes (a handcrafted / non-browser request
+ *      can't carry a victim's SameSite cookies cross-site anyway).
  *
- * Notes on scope:
- *   - Applies to internal RPC only. A `route.ts` REST endpoint (hand-written
- *     or via the `route()` adapter) is *not* CSRF-protected because it is
- *     intended for external consumers; such an endpoint should carry its own
- *     auth (bearer token, signed request, API key) the app provides via
- *     middleware.
+ * Scope:
+ *   - Internal RPC only. A `route.ts` REST endpoint (hand-written or via the
+ *     `route()` adapter) is intentionally NOT covered here; it is for external
+ *     consumers and must carry its own auth.
+ *   - Session / auth cookies stay `SameSite=Lax` as defense-in-depth.
  */
 
-export const CSRF_COOKIE = 'webjs_csrf';
-export const CSRF_HEADER = 'x-webjs-csrf';
-const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 7; // 7 days
-
-/** @returns {string} a 128-bit hex token */
-export function newToken() {
-  const bytes = new Uint8Array(16);
-  webCrypto.getRandomValues(bytes);
-  let s = '';
-  for (const b of bytes) s += b.toString(16).padStart(2, '0');
-  return s;
-}
-
 /**
- * Parse cookies off a standard Request.
+ * Parse cookies off a standard Request. Retained as a general cookie reader
+ * (used by `context.js` for `cookies()`), independent of CSRF.
  * @param {Request} req
  * @returns {Record<string,string>}
  */
@@ -60,37 +49,88 @@ export function parseCookies(req) {
   return out;
 }
 
-/** @param {Request} req */
-export function readToken(req) {
-  return parseCookies(req)[CSRF_COOKIE] || null;
+/** Lower-cased host from a URL-or-origin string, or '' if unparseable. */
+function hostOf(value) {
+  if (!value) return '';
+  try { return new URL(value).host.toLowerCase(); } catch { return ''; }
 }
 
 /**
- * Serialise a Set-Cookie value for the CSRF token.
- * @param {string} token
- * @param {{ secure?: boolean }} [opts]
+ * The host the request was addressed to. Honors `x-forwarded-host` first
+ * (set by a reverse proxy / CDN like the Cloudflare-in-front-of-Railway
+ * setup), then the `Host` header, then the request URL.
+ *
+ * Trust note: `x-forwarded-host` is only meaningful behind a proxy that
+ * overwrites it. This is NOT a CSRF weakness, because a CSRF attack is
+ * browser-driven and a browser cannot set `x-forwarded-host` (or `Origin`);
+ * only a direct non-browser client can, and such a client carries no victim
+ * SameSite cookies to abuse. The primary `Sec-Fetch-Site` path does not use
+ * this at all.
+ * @param {Request} req
  */
-export function cookieHeader(token, opts = {}) {
-  const parts = [
-    `${CSRF_COOKIE}=${encodeURIComponent(token)}`,
-    'Path=/',
-    'SameSite=Lax',
-    `Max-Age=${COOKIE_MAX_AGE_SECONDS}`,
-  ];
-  if (opts.secure) parts.push('Secure');
-  return parts.join('; ');
+export function requestHost(req) {
+  const xfh = req.headers.get('x-forwarded-host');
+  if (xfh) return xfh.split(',')[0].trim().toLowerCase();
+  const host = req.headers.get('host');
+  if (host) return host.toLowerCase();
+  return hostOf(req.url);
+}
+
+/** Is the request's `Origin` host in the configured allowlist? */
+function originAllowed(req, allowedOrigins) {
+  const origin = req.headers.get('origin');
+  if (!origin || origin === 'null') return false;
+  const h = hostOf(origin);
+  if (!h) return false;
+  const allow = new Set(
+    // A full-origin entry (`https://x.example`) is host-parsed; a bare host
+    // (`x.example` or a copy-pasted `x.example/`) is lower-cased and stripped
+    // of a stray trailing slash so it still matches.
+    allowedOrigins.map((o) => (o.includes('://') ? hostOf(o) : o.toLowerCase().replace(/\/+$/, ''))),
+  );
+  return allow.has(h);
 }
 
 /**
- * Constant-time verification of the double-submit.
+ * Cross-origin (CSRF) verification for a state-changing action request.
  * @param {Request} req
+ * @param {string[]} [allowedOrigins] hosts or full origins allowed cross-site
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function verifyOrigin(req, allowedOrigins = []) {
+  // Primary: the Sec-Fetch-Site fetch-metadata header (browser-set, not
+  // forgeable by page JS, sent on every request).
+  const secFetchSite = (req.headers.get('sec-fetch-site') || '').toLowerCase();
+  if (secFetchSite === 'same-origin' || secFetchSite === 'none') return { ok: true };
+  if (secFetchSite) {
+    // 'same-site' or 'cross-site': reject unless the source origin is trusted.
+    return originAllowed(req, allowedOrigins)
+      ? { ok: true }
+      : { ok: false, reason: `cross-origin request (Sec-Fetch-Site: ${secFetchSite})` };
+  }
+  // Fallback (no Sec-Fetch-Site, older browser): compare Origin host to host.
+  const origin = req.headers.get('origin');
+  if (!origin) return { ok: true, reason: 'no-origin' };
+  const sourceHost = origin === 'null' ? 'null' : hostOf(origin);
+  const host = requestHost(req);
+  if (sourceHost && host && sourceHost === host) return { ok: true };
+  return originAllowed(req, allowedOrigins)
+    ? { ok: true }
+    : { ok: false, reason: `origin ${sourceHost || '(none)'} does not match host ${host || '(none)'}` };
+}
+
+/**
+ * Read `webjs.allowedOrigins` (string[]) from a parsed package.json. Pure;
+ * the caller supplies the package.json read (mirrors `readBasePath`).
+ * @param {unknown} pkg
+ * @returns {string[]}
  */
-export function verify(req) {
-  const cookie = readToken(req);
-  const header = req.headers.get(CSRF_HEADER);
-  if (!cookie || !header) return false;
-  if (cookie.length !== header.length) return false;
-  let diff = 0;
-  for (let i = 0; i < cookie.length; i++) diff |= cookie.charCodeAt(i) ^ header.charCodeAt(i);
-  return diff === 0;
+export function readAllowedOrigins(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.allowedOrigins;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((x) => typeof x === 'string' && x.length > 0);
 }

package/src/dev.js

@@ -87,6 +87,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
+import { readAllowedOrigins } from './csrf.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
@@ -362,6 +363,24 @@ export async function readBasePathFromApp(appDir) {
   }
 }
 
+/**
+ * Read the cross-origin allowlist (`webjs.allowedOrigins`) from the app's
+ * package.json. These hosts / origins are accepted by the action CSRF check
+ * even when cross-site (reverse-proxy / multi-domain setups). A missing or
+ * unreadable config yields `[]`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string[]>}
+ */
+export async function readAllowedOriginsFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readAllowedOrigins(pkg);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Read the CSP config (`webjs.csp`) from the app's package.json and
  * normalize it (issue #233). A missing, malformed, or unreadable config
@@ -495,6 +514,9 @@ export async function createRequestHandler(opts) {
   const basePathValue = await readBasePathFromApp(appDir);
   await setBasePath(basePathValue);
 
+  // Cross-origin allowlist for the action CSRF check (#659), read once.
+  const allowedOriginsValue = await readAllowedOriginsFromApp(appDir);
+
   // Client-router opt-out (#629): bind it eagerly at handler construction (the
   // same timing as setBasePath above), so a handler's module-global is set
   // before any render even if a request arrives before the first warm. The
@@ -1306,7 +1328,7 @@ export async function createRequestHandler(opts) {
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
       await ensureReady();
-      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled: cspConfig.enabled });
+      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled: cspConfig.enabled, allowedOrigins: allowedOriginsValue });
       if (state.middleware) {
         try {
           return await state.middleware(req, next);
@@ -1740,7 +1762,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
 }
 
 async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled } = ctx;
+  const { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled, allowedOrigins } = ctx;
   const url = new URL(req.url);
   // Decode percent-encoded characters so filesystem lookups match real
   // filenames. Dynamic route segments like `[slug]` and route groups like
@@ -1778,7 +1800,7 @@ async function handleCore(req, ctx) {
     // Pass the onError sink (issue #239): a server action that throws
     // unexpectedly is reported to the APM hook before the sanitized 500.
     const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;
-    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError);
+    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError, allowedOrigins);
   }
 
   // Static: /public/*

package/src/elision-report.js

@@ -0,0 +1,89 @@
+/**
+ * App-level elision report (#646).
+ *
+ * A reporting layer over the `analyzeElision` verdict, NOT a second analysis
+ * and NOT a build (webjs is no-build; elision is the server's analysis pass,
+ * run at dev-server start and re-derived after each fs.watch rebuild). It
+ * builds the module graph, runs `analyzeElision`, and returns the page / layout
+ * route modules that SHIP WHOLE to the browser, each with the first
+ * client-effecting blocker that pins it (or its own signal when the module
+ * itself is the cause).
+ *
+ * Consumed by `webjs doctor` to ADVISE why a page/layout is not elided (an
+ * import-only #605 / inert #179 carrier stays out of the browser; a module that
+ * ships whole does not). Advisory only: a page legitimately MAY ship, and the
+ * analyser is biased toward shipping by design (server AGENTS invariant 7), so
+ * this never fails anything.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { buildModuleGraph } from './module-graph.js';
+import { scanComponents } from './component-scanner.js';
+import { buildRouteTable } from './router.js';
+import { analyzeElision } from './component-elision.js';
+
+/**
+ * @param {string} appDir
+ * @returns {Promise<{ analysed: boolean, shipped: Array<{ file: string, blocker: string|null, reason: string }> }>}
+ */
+export async function analyzeAppElision(appDir) {
+  // No `app/` means this is not a routable app (a bare component library, a
+  // lib-only fixture); nothing ships, so there is nothing to advise on.
+  if (!(await pathExists(join(appDir, 'app')))) return { analysed: false, shipped: [] };
+  // Elision off (opt-out) ships everything by design, so the advisory is moot.
+  if (!(await readElideEnabled(appDir))) return { analysed: false, shipped: [] };
+
+  let moduleGraph, components, routeTable;
+  try {
+    moduleGraph = await buildModuleGraph(appDir);
+    components = await scanComponents(appDir);
+    routeTable = await buildRouteTable(appDir);
+  } catch {
+    // A malformed app the analysis cannot process degrades to no advice (the
+    // dev server and `webjs check` surface the real problem).
+    return { analysed: false, shipped: [] };
+  }
+
+  // Exactly the page + layout set the dev server feeds to analyzeElision, so
+  // the verdict matches (error / loading / not-found modules always ship and
+  // are never elision candidates, so they are not in scope here).
+  const routeModuleSet = new Set();
+  for (const page of routeTable.pages || []) {
+    if (page.file) routeModuleSet.add(page.file);
+    for (const f of page.layouts || []) routeModuleSet.add(f);
+  }
+
+  const { shippedRouteModules } = await analyzeElision(
+    components, [...routeModuleSet], moduleGraph, (f) => readFile(f, 'utf8'), appDir,
+  );
+
+  const shipped = [...shippedRouteModules.entries()].map(([file, v]) => ({
+    file,
+    blocker: v.blocker,
+    reason: v.reason,
+  }));
+  return { analysed: true, shipped };
+}
+
+/** Mirror of the dev server's elide flag: WEBJS_ELIDE override, then webjs.elide. */
+async function readElideEnabled(appDir) {
+  const raw = process.env.WEBJS_ELIDE;
+  if (raw != null) {
+    const v = raw.trim().toLowerCase();
+    if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+    if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  }
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable: keep the default (on).
+  }
+  return true;
+}
+
+/** @param {string} p @returns {Promise<boolean>} */
+async function pathExists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}

package/src/html-cache.js

@@ -190,10 +190,10 @@ export async function writeHtmlCache(url, rec, revalidateSeconds) {
  *  - status 200 (an error / redirect / 404 is request-specific)
  *  - NOT a streamed Suspense body (it cannot be buffered cheaply, and an
  *    unflushed stream has no stable bytes to cache)
- *  - NO non-framework Set-Cookie. A page that sets a session / per-user
- *    cookie is per-user output and must not be shared. The framework's own
- *    CSRF cookie (`webjs_csrf`) is allowed and re-minted per response on a
- *    cache hit, so its presence does not block caching.
+ *  - NO Set-Cookie at all. A page that sets a session / per-user cookie is
+ *    per-user output and must not be shared. SSR responses no longer carry a
+ *    framework cookie (action CSRF is an Origin / Sec-Fetch-Site check, not a
+ *    token cookie), so ANY Set-Cookie means per-user, do not cache.
  *  - CSP is OFF. With CSP enabled the inline boot script carries a fresh
  *    per-request nonce, so the body varies per request and a cached body
  *    would replay a stale nonce that the response's CSP header rejects.
@@ -206,36 +206,10 @@ export function isCacheableResponse(res, guards = {}) {
   if (res.status !== 200) return false;
   if (res.headers.has(STREAM_MARKER)) return false;
   if (guards.cspEnabled) return false;
-  if (hasNonFrameworkSetCookie(res)) return false;
+  if (res.headers.has('set-cookie')) return false;
   return true;
 }
 
-/**
- * True when the response carries a Set-Cookie OTHER than the framework's
- * own CSRF cookie. Reads each cookie individually via `getSetCookie()`, the
- * only correct way to enumerate multiple Set-Cookie values (a combined
- * `get('set-cookie')` cannot be split safely, since a cookie value or an
- * Expires date can contain a comma). When `getSetCookie` is unavailable
- * (a runtime older than Node 24) this FAILS SAFE: it reports a
- * non-framework cookie (do not cache) rather than parsing only the first of
- * a combined header and wrongly judging it framework-only.
- *
- * @param {Response} res
- * @returns {boolean}
- */
-function hasNonFrameworkSetCookie(res) {
-  const h = res.headers;
-  if (typeof h.getSetCookie !== 'function') {
-    // No reliable per-cookie enumeration: fail safe (treat as per-user).
-    return h.has('set-cookie');
-  }
-  for (const c of h.getSetCookie()) {
-    const name = c.split('=', 1)[0].trim().toLowerCase();
-    if (name !== 'webjs_csrf') return true;
-  }
-  return false;
-}
-
 /**
  * Evict the cached HTML for one path (server-side, on-demand
  * revalidation: the no-build ISR revalidation hook). A server action that

package/src/listener-bun.js

@@ -349,7 +349,7 @@ function maybeCompress(resp, req) {
  * on Bun too.
  * @param {{ requestTimeout?: number } | undefined} timeouts
  */
-function bunIdleTimeout(timeouts) {
+export function bunIdleTimeout(timeouts) {
   const reqMs = timeouts && timeouts.requestTimeout;
   if (reqMs === 0) return 0;
   let secs = Math.ceil((reqMs || 30_000) / 1000);

package/src/ssr.js

@@ -5,7 +5,6 @@ import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPre
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
-import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
 import { seedingEnabled, collectSeeds, buildSeedScript } from './action-seed.js';
 import { BUFFERED_MARKER, STREAM_MARKER } from './conditional-get.js';
@@ -316,7 +315,8 @@ export async function ssrNotFound(notFoundFile, opts) {
 }
 
 /**
- * Build an HTML Response and, if missing, attach the CSRF cookie.
+ * Build an HTML Response. Sets no cookie: action CSRF is an Origin /
+ * Sec-Fetch-Site check, so the page response is cookieless (CDN-cacheable).
  * @param {string} html
  * @param {number} status
  * @param {Request | undefined} req
@@ -335,10 +335,6 @@ function htmlResponse(html, status, req, url, metadata) {
   // final, so a warming response is reload-safe. See router-client.js
   // applySwap and publishedBuildId() in importmap.js.
   headers.set('x-webjs-build', publishedBuildId());
-  if (req && !readToken(req)) {
-    const secure = url ? url.protocol === 'https:' : false;
-    headers.append('set-cookie', cookieHeader(newToken(), { secure }));
-  }
   // Buffered (string) body: opt into the conditional-GET funnel so a
   // PUBLIC-cacheable page (metadata.cacheControl) gets a weak ETag + 304.
   // The funnel still excludes the no-store default, so a private page is
@@ -350,10 +346,10 @@ function htmlResponse(html, status, req, url, metadata) {
 /**
  * Rebuild a Response from a cached HTML record (#241). The stored body is
  * the stable per-page HTML; the per-response varying bits are re-minted
- * here so a new visitor still gets them: the CSRF cookie is freshly issued
- * when the request lacks one (it is a Set-Cookie header, never part of the
- * cached body), and the published build id is re-read so a post-deploy
- * client sees the current id. The BUFFERED marker opts the cached body into
+ * here so a new visitor still gets them: the published build id is re-read so
+ * a post-deploy client sees the current id. No cookie is set (action CSRF is
+ * an Origin / Sec-Fetch-Site check), which is what keeps a cached page
+ * cookieless and shareable. The BUFFERED marker opts the cached body into
  * the conditional-GET funnel exactly as a fresh render does, so a cached
  * PUBLIC-cacheable page still 304s. Output is observably identical to the
  * fresh render of the same route within the window.
@@ -366,10 +362,6 @@ function cachedHtmlResponse(rec, req, url) {
   const headers = new Headers({ 'content-type': rec.contentType });
   headers.set('cache-control', rec.cacheControl);
   headers.set('x-webjs-build', publishedBuildId());
-  if (req && !readToken(req)) {
-    const secure = url ? url.protocol === 'https:' : false;
-    headers.append('set-cookie', cookieHeader(newToken(), { secure }));
-  }
   headers.set(BUFFERED_MARKER, '1');
   return new Response(rec.body, { status: rec.status, headers });
 }
@@ -1525,10 +1517,6 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   // See htmlResponse: published build id on every response for the
   // client router's importmap-mismatch detection on partial swaps.
   headers.set('x-webjs-build', publishedBuildId());
-  if (req && !readToken(req)) {
-    const secure = url ? url.protocol === 'https:' : false;
-    headers.append('set-cookie', cookieHeader(newToken(), { secure }));
-  }
 
   if (!ctx.pending.length) {
     // No pending boundaries: this degrades to a single buffered (string)

package/src/testing.d.ts

@@ -2,8 +2,8 @@
  * Type overlay for `@webjsdev/server/testing` (the handle() test harness, #267).
  *
  * The runtime is packages/server/src/testing.js (JSDoc-annotated JavaScript);
- * this overlay exists so a TypeScript app's `import { testRequest, getCsrf }
- * from '@webjsdev/server/testing'` resolves precise types instead of emitting
+ * this overlay exists so a TypeScript app's `import { testRequest,
+ * invokeActionForTest } from '@webjsdev/server/testing'` resolves precise types instead of emitting
  * TS7016. The same declarations are re-exported from the package's main
  * `index.d.ts` (the helpers ship from both entry points). Zero runtime cost.
  */
@@ -14,16 +14,6 @@ export type Handle = (req: Request) => Promise<Response> | Response;
 /** A `createRequestHandler` return value, or a bare `handle` function. */
 export type AppOrHandle = { handle: Handle; appDir: string } | Handle;
 
-/** A CSRF token + cookie + header-name triple minted off the first SSR response. */
-export interface CsrfPair {
-  /** The bare token value for the `x-webjs-csrf` request header. */
-  token: string;
-  /** The header NAME (`x-webjs-csrf`). */
-  header: string;
-  /** The `name=value` cookie string for the `Cookie` request header. */
-  cookie: string;
-}
-
 /**
  * Coerce a bare path, full URL string, or pre-built `Request` into a `Request`.
  * A bare path is prefixed with a dummy origin; `init` is merged when provided.
@@ -40,21 +30,12 @@ export declare function testRequest(
   init?: RequestInit,
 ): Promise<Response>;
 
-/** Read the `webjs_csrf` cookie value off a response's `Set-Cookie` header(s). */
-export declare function readCsrfCookie(res: Response): string | null;
-
 /** Collect all `Set-Cookie` header values off a response. */
 export declare function getSetCookies(res: Response): string[];
 
 /** Reduce raw `Set-Cookie` strings to a single `name=value; name2=value2` `Cookie` header value. */
 export declare function cookiesToHeader(setCookies: string[]): string;
 
-/**
- * Mint a `{ token, header, cookie }` CSRF triple off the first SSR response.
- * `path` is the GET path used to issue the cookie (default `/`).
- */
-export declare function getCsrf(handle: Handle, path?: string): Promise<CsrfPair>;
-
 /** Merge an extra cookie string into a `RequestInit`'s `Cookie` header. */
 export declare function withCookies(init: RequestInit | undefined, cookieValue: string): RequestInit;
 
@@ -89,7 +70,8 @@ export declare function actionEndpoint(
 
 /**
  * Round-trip an action through its REAL RPC endpoint (serializer + CSRF + prod
- * error sanitization) and return the parsed return value.
+ * error sanitization) and return the parsed return value. Models a same-origin
+ * browser POST, so it passes the Origin / Sec-Fetch-Site CSRF check.
  */
 export declare function invokeActionForTest<T = unknown>(
   app: AppOrHandle,
@@ -97,7 +79,6 @@ export declare function invokeActionForTest<T = unknown>(
   fnName: string,
   args?: unknown[],
   opts?: {
-    csrf?: CsrfPair;
     appDir?: string;
     extraCookies?: string;
     throwOnError?: boolean;
@@ -106,7 +87,9 @@ export declare function invokeActionForTest<T = unknown>(
 
 /**
  * Lower-level variant of `invokeActionForTest` that returns the raw `Response`
- * (never throws on a non-2xx), so a test can assert the status directly.
+ * (never throws on a non-2xx), so a test can assert the status directly. Set
+ * `crossOrigin` (true or a specific origin) to model a cross-site request and
+ * assert the 403.
  */
 export declare function rawActionRequest(
   app: AppOrHandle,
@@ -114,8 +97,7 @@ export declare function rawActionRequest(
   fnName: string,
   args?: unknown[],
   opts?: {
-    csrf?: CsrfPair | null;
-    omitCsrf?: boolean;
+    crossOrigin?: boolean | string;
     appDir?: string;
     extraCookies?: string;
     contentType?: string;

package/src/testing.js

@@ -18,7 +18,7 @@
  *
  * ```js
  * import { createRequestHandler } from '@webjsdev/server';
- * import { testRequest, getCsrf, invokeActionForTest } from '@webjsdev/server/testing';
+ * import { testRequest, invokeActionForTest } from '@webjsdev/server/testing';
  *
  * const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
  *
@@ -33,7 +33,6 @@
  */
 
 import { hashFile, RPC_CONTENT_TYPE } from './actions.js';
-import { CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
 import { getSerializer } from './serializer.js';
 import { join, sep } from 'node:path';
 
@@ -83,24 +82,6 @@ export function testRequest(handle, input, init) {
   return handle(toRequest(input, init));
 }
 
-/**
- * Read the `webjs_csrf` cookie value off a response's `Set-Cookie` header(s).
- * Returns null when the response set no CSRF cookie.
- *
- * @param {Response} res
- * @returns {string | null}
- */
-export function readCsrfCookie(res) {
-  const cookies = getSetCookies(res);
-  for (const c of cookies) {
-    const m = new RegExp(`(?:^|\\s)${CSRF_COOKIE}=([^;]+)`).exec(c);
-    if (m) {
-      try { return decodeURIComponent(m[1]); } catch { return m[1]; }
-    }
-  }
-  return null;
-}
-
 /**
  * Collect every `Set-Cookie` value off a `Response`, preferring the
  * structured `getSetCookie()` (which keeps multiple cookies separate) and
@@ -134,32 +115,6 @@ export function cookiesToHeader(setCookies) {
     .join('; ');
 }
 
-/**
- * Do an initial GET to mint a CSRF token, returning the `{ cookie, token }`
- * pair so a test can send a CSRF-valid action request. `cookie` is a ready-made
- * `Cookie` request-header value; `token` is the bare value for the
- * `x-webjs-csrf` header. Reuses the REAL cookie / header names from `csrf.js`.
- *
- * @param {Handle} handle
- * @param {string} [path] the GET path used to issue the cookie (default `/`)
- * @returns {Promise<{ cookie: string, token: string, header: string }>}
- */
-export async function getCsrf(handle, path = '/') {
-  const res = await testRequest(handle, path);
-  const token = readCsrfCookie(res);
-  if (!token) {
-    throw new Error(
-      `getCsrf: GET ${path} issued no ${CSRF_COOKIE} cookie. The first SSR ` +
-      `response issues it; hit a real page route (or pass a path that renders).`,
-    );
-  }
-  return {
-    token,
-    header: CSRF_HEADER,
-    cookie: `${CSRF_COOKIE}=${encodeURIComponent(token)}`,
-  };
-}
-
 /**
  * Merge an extra cookie string into a `RequestInit`'s `Cookie` header,
  * preserving any cookie already on `init.headers`.
@@ -301,7 +256,6 @@ function isAbsolutePath(p) {
  * @param {string} fnName the exported action function name
  * @param {unknown[]} [args] positional args (serialized as the stub sends an arg array)
  * @param {{
- *   csrf?: { cookie: string, token: string },
  *   appDir?: string,
  *   extraCookies?: string,
  *   throwOnError?: boolean,
@@ -320,23 +274,17 @@ export async function invokeActionForTest(app, serverFilePath, fnName, args = []
   const throwOnError = opts.throwOnError !== false;
 
   const endpoint = await actionEndpoint(appDir, serverFilePath, fnName);
-  const csrf = opts.csrf || (await getCsrf(handle));
 
   const serializer = getSerializer();
   const body = await serializer.serialize(args);
 
-  let cookie = csrf.cookie || `${CSRF_COOKIE}=${encodeURIComponent(csrf.token)}`;
-  if (opts.extraCookies) cookie = `${cookie}; ${opts.extraCookies}`;
+  // Model a same-origin browser POST (the action CSRF check reads
+  // `Sec-Fetch-Site`, no token / cookie needed).
+  /** @type {Record<string,string>} */
+  const headers = { 'content-type': RPC_CONTENT_TYPE, 'sec-fetch-site': 'same-origin' };
+  if (opts.extraCookies) headers.cookie = opts.extraCookies;
 
-  const res = await testRequest(handle, endpoint, {
-    method: 'POST',
-    headers: {
-      'content-type': RPC_CONTENT_TYPE,
-      [CSRF_HEADER]: csrf.token,
-      cookie,
-    },
-    body,
-  });
+  const res = await testRequest(handle, endpoint, { method: 'POST', headers, body });
 
   const text = await res.text();
   const ct = res.headers.get('content-type') || '';
@@ -357,17 +305,17 @@ export async function invokeActionForTest(app, serverFilePath, fnName, args = []
 
 /**
  * Lower-level variant of `invokeActionForTest` that returns the raw `Response`
- * (never throws on a non-2xx), so a test can assert on the status directly
- * (e.g. a CSRF-missing request returns 403). Send `opts.csrf = null` /
- * `opts.omitCsrf = true` to deliberately omit the CSRF header + cookie.
+ * (never throws on a non-2xx), so a test can assert on the status directly.
+ * By default it models a same-origin browser POST (passes the CSRF check); set
+ * `opts.crossOrigin` (true, or a specific origin string) to model a cross-site
+ * request and assert the 403.
  *
  * @param {{ handle: Handle, appDir: string } | Handle} app
  * @param {string} serverFilePath
  * @param {string} fnName
  * @param {unknown[]} [args]
  * @param {{
- *   csrf?: { cookie: string, token: string } | null,
- *   omitCsrf?: boolean,
+ *   crossOrigin?: boolean | string,
  *   appDir?: string,
  *   extraCookies?: string,
  *   contentType?: string,
@@ -386,15 +334,13 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
 
   /** @type {Record<string,string>} */
   const headers = { 'content-type': opts.contentType || RPC_CONTENT_TYPE };
-  if (!opts.omitCsrf && opts.csrf !== null) {
-    const csrf = opts.csrf || (await getCsrf(handle));
-    headers[CSRF_HEADER] = csrf.token;
-    let cookie = csrf.cookie || `${CSRF_COOKIE}=${encodeURIComponent(csrf.token)}`;
-    if (opts.extraCookies) cookie = `${cookie}; ${opts.extraCookies}`;
-    headers.cookie = cookie;
-  } else if (opts.extraCookies) {
-    headers.cookie = opts.extraCookies;
+  if (opts.crossOrigin) {
+    headers['sec-fetch-site'] = 'cross-site';
+    headers.origin = typeof opts.crossOrigin === 'string' ? opts.crossOrigin : 'https://evil.example';
+  } else {
+    headers['sec-fetch-site'] = 'same-origin';
   }
+  if (opts.extraCookies) headers.cookie = opts.extraCookies;
 
   return testRequest(handle, endpoint, { method: 'POST', headers, body });
 }

package/webjs-config.schema.json

@@ -96,6 +96,12 @@
       "type": "string",
       "default": ""
     },
+    "allowedOrigins": {
+      "description": "Cross-origin hosts (or full origins) the action CSRF check accepts even when the request is cross-site. The action endpoint defends with a Sec-Fetch-Site check plus an Origin-vs-host fallback; list additional origins a reverse-proxy / multi-domain setup must allow here. A bare host or a full origin are both accepted. Read by readAllowedOrigins in csrf.js. Default [] (same-origin only).",
+      "type": "array",
+      "items": { "type": "string" },
+      "default": []
+    },
     "csp": {
       "description": "Content-Security-Policy config. Off by default. true enables a strict nonce-based default policy. An object customizes directives and report-only mode. Read by readCspConfig in csp.js.",
       "oneOf": [