@timber-js/app 0.2.0-alpha.209 → 0.2.0-alpha.210

package/src/routing/export-detect.ts

@@ -425,6 +425,94 @@ export function getPrerenderExport(filePath: string): PrerenderExportValue | und
   }
 }
 
+/**
+ * How a file declares the per-route CSRF exemption.
+ *
+ * - `'absent'` — no runtime export named `csrf`.
+ * - `'exempt'` — exactly `export const csrf = false` (wrappers like
+ *   `false as const` allowed), declared in this file.
+ * - `'invalid'` — some other `csrf` export: another value, `let`, a
+ *   destructured binding, a specifier or named re-export (`export { csrf }`,
+ *   `export { x as "csrf" }`), a function or class. `export * from` is not
+ *   followed: a `csrf` it carries is neither exempt nor an error.
+ *
+ * The exemption is read from source at build time, never from the loaded
+ * module, because the CSRF gate runs before any user code (see
+ * design/08-forms-and-actions.md §"Per-route exemption"). Only the literal
+ * form can be read that way; any other spelling is a build error rather
+ * than a silent "not exempt", so what the developer wrote is what runs.
+ */
+export type CsrfExport = 'absent' | 'exempt' | 'invalid';
+
+export function getCsrfExport(filePath: string): CsrfExport {
+  if (!existsSync(filePath)) return 'absent';
+  // Unparseable: not exempt (fail closed). The compiler reports the syntax
+  // error; guessing at a half-written file would misreport it.
+  const program = tryParse(readFileCached(filePath));
+  if (!program) return 'absent';
+
+  // Walk the statements directly rather than through `collectNamedExports`:
+  // every spelling that exports a runtime `csrf` must be seen here, and
+  // that helper does not see destructured declarations or string-literal
+  // specifier names. What cannot be seen at all — `export * from` — is
+  // not read, and is documented as such.
+  let found: CsrfExport = 'absent';
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ExportNamedDeclaration' || stmt.exportKind === 'type') continue;
+    for (const spec of stmt.specifiers ?? []) {
+      if (spec.exportKind !== 'type' && specifierName(spec.exported) === 'csrf') {
+        return 'invalid';
+      }
+    }
+    const decl = stmt.declaration as (AstNode & { kind?: string }) | undefined;
+    if (!decl) continue;
+    if (decl.id?.name === 'csrf') return 'invalid'; // function or class
+    if (decl.type !== 'VariableDeclaration') continue;
+    for (const d of decl.declarations ?? []) {
+      const id = d.id as AstNode | undefined;
+      if (id?.type === 'Identifier') {
+        if (id.name !== 'csrf') continue;
+        const init = d.init && (unwrapTransparent(d.init) as AstNode & { value?: unknown });
+        const literalFalse = init?.type === 'Literal' && init.value === false;
+        if (decl.kind !== 'const' || !literalFalse) return 'invalid';
+        found = 'exempt';
+      } else if (id && patternBinds(id, 'csrf')) {
+        return 'invalid'; // `export const { csrf } = …`
+      }
+    }
+  }
+  return found;
+}
+
+/** An export specifier's name: `csrf` or the string literal `"csrf"`. */
+function specifierName(node: { name?: string; value?: unknown } | undefined): string | undefined {
+  if (!node) return undefined;
+  return typeof node.value === 'string' ? node.value : node.name;
+}
+
+/** Whether a destructuring pattern binds `name` anywhere inside it. */
+function patternBinds(node: unknown, name: string): boolean {
+  if (!node || typeof node !== 'object') return false;
+  const n = node as Record<string, unknown>;
+  switch (n.type) {
+    case 'Identifier':
+      return n.name === name;
+    case 'ObjectPattern':
+      return ((n.properties as unknown[]) ?? []).some((prop) => {
+        const p = prop as Record<string, unknown>;
+        return patternBinds(p.type === 'RestElement' ? p.argument : p.value, name);
+      });
+    case 'ArrayPattern':
+      return ((n.elements as unknown[]) ?? []).some((el) => patternBinds(el, name));
+    case 'RestElement':
+      return patternBinds(n.argument, name);
+    case 'AssignmentPattern':
+      return patternBinds(n.left, name);
+    default:
+      return false;
+  }
+}
+
 /**
  * Check if a file starts with a specific directive (e.g. "use client").
  * Directives are string literal expression statements at the top of the file.

package/src/routing/manifest-codegen.ts

@@ -105,6 +105,12 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
       }
     }
 
+    // Read from route.ts source at scan time; the CSRF gate consults it
+    // before any user module loads (design/08 §"Per-route exemption").
+    if (node.csrfExempt) {
+      parts.push(`${nextIndent}csrfExempt: true,`);
+    }
+
     // Record-shaped conventions — table-driven
     for (const key of RECORD_FILE_KEYS) {
       const record = node[key];

package/src/routing/scanner.ts

@@ -25,6 +25,7 @@ import { validateSlotPlacement } from './slot-placement.ts';
 import { DEFAULT_PAGE_EXTENSIONS } from './types.ts';
 import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.ts';
 import { swallow } from '../server/logger.ts';
+import { getCsrfExport } from './export-detect.ts';
 import { ENCODED_SEPARATOR_RE, NULL_BYTE_RE } from '../server/canonicalize.ts';
 
 /**
@@ -303,6 +304,14 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
         `A URL is either an API endpoint or a rendered page, not both.`
     );
   }
+
+  // The per-route CSRF exemption is read from source here, at scan time, so
+  // the manifest carries it and the request gate never loads user code to
+  // decide it. Any other spelling of the export is a lint error
+  // (convention-lint.ts `checkCsrfExports`).
+  if (node.route && getCsrfExport(node.route.filePath) === 'exempt') {
+    node.csrfExempt = true;
+  }
 }
 
 /**

package/src/routing/types.ts

@@ -96,6 +96,13 @@ export interface SegmentNode<TFile = RouteFile> {
   middleware?: TFile;
   access?: TFile;
   route?: TFile;
+  /**
+   * Set when this segment's route.ts declares `export const csrf = false`.
+   * Read from source by the scanner, so the CSRF gate can consult it before
+   * any user module loads. See design/08-forms-and-actions.md
+   * §"Per-route exemption".
+   */
+  csrfExempt?: true;
   error?: TFile;
   default?: TFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */

package/src/server/action-handler.ts

@@ -73,7 +73,7 @@ export interface ActionDispatchConfig {
  *
  * **Important:** This function returns true for ANY POST with a form
  * Content-Type, including non-action POSTs to route.ts API handlers.
- * The caller (wrap-action-dispatch.ts) MUST check the matched route type
+ * The caller (rsc-entry/action-dispatcher.ts) MUST check the matched route type
  * before entering the action path — route.ts matches skip action detection
  * entirely so their body is not pre-parsed. See TIM-870.
  */
@@ -148,11 +148,12 @@ export async function handleActionRequest(
 
   // CSRF validation — reject cross-origin mutation requests.
   //
-  // Defense-in-depth: the pipeline boundary in rsc-entry/index.ts already
-  // validates Origin on every unsafe-method request before dispatch reaches
-  // here, so this call is a no-op on the happy path. It is intentionally
-  // retained so that handleActionRequest remains safe to call from any
-  // future entry point that bypasses the wrapper. See LOCAL-773.
+  // Defense-in-depth: the pipeline's CSRF gate (`csrfGate`) already checks
+  // every unsafe-method request before dispatch reaches here, so this call
+  // is a no-op on the happy path. It is intentionally retained so that
+  // handleActionRequest remains safe to call from any entry point that
+  // bypasses the gate — and it never applies the per-route exemption, which
+  // is for route.ts only. See LOCAL-773, TIM-1543.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
     return csrfRejectionResponse(req, csrfResult);
@@ -398,8 +399,8 @@ async function handleRscAction(
       'Content-Type': RSC_CONTENT_TYPE,
       'X-Timber-Redirect': result.redirectTo,
     };
-    if (result.invalidatedPaths && result.invalidatedPaths.length > 0) {
-      redirectHeaders['X-Timber-Revalidation-Path'] = result.invalidatedPaths.join(' ');
+    if (result.onlyOtherPagesNamed) {
+      redirectHeaders['X-Timber-Invalidated'] = '1';
     }
     return new Response(rscStream, { status: 200, headers: redirectHeaders });
   }
@@ -412,9 +413,11 @@ async function handleRscAction(
     'Content-Type': RSC_CONTENT_TYPE,
   };
 
-  // TIM-1454: Tell the client which paths were invalidated (non-matching).
-  if (result.invalidatedPaths && result.invalidatedPaths.length > 0) {
-    headers['X-Timber-Revalidation-Path'] = result.invalidatedPaths.join(' ');
+  // TIM-1454: Tell the client that revalidatePath named only other pages. A
+  // flag, not a path list: the client evicts every cached payload either
+  // way (TIM-1461).
+  if (result.onlyOtherPagesNamed) {
+    headers['X-Timber-Invalidated'] = '1';
   }
 
   if (result.revalidation) {

package/src/server/actions.ts

@@ -81,11 +81,16 @@ export interface ActionHandlerResult {
   /** Revalidation result if revalidatePath was called (element tree, not yet serialized). */
   revalidation?: RevalidationResult;
   /**
-   * Paths passed to `revalidatePath()` that don't match the current page
-   * (TIM-1454). The client invalidates its caches for these so the next
-   * navigation fetches fresh data.
+   * True when `revalidatePath()` was called only for pages other than the
+   * current one (TIM-1454). The client then evicts its caches and skips the
+   * refresh — nothing on screen was named. Whenever the current page was
+   * named this is false, even if other pages were named too: its re-render,
+   * or the refresh that replaces a dropped one, re-renders every layout it
+   * shares with them. Which paths were named is not reported: the client
+   * evicts every cached payload after any revalidation (TIM-1476), so a path
+   * list would carry nothing it acts on (TIM-1461).
    */
-  invalidatedPaths?: string[];
+  onlyOtherPagesNamed: boolean;
   /** Redirect location if a RedirectSignal was thrown during revalidation. */
   redirectTo?: string;
   /** Redirect status code. */
@@ -166,13 +171,6 @@ export function revalidateTag(tag: string): Promise<void> {
   return Promise.resolve();
 }
 
-// ─── Helpers ────────────────────────────────────────────────────────────
-
-function stripFragment(path: string): string {
-  const idx = path.indexOf('#');
-  return idx >= 0 ? path.slice(0, idx) : path;
-}
-
 // ─── Action Handler ──────────────────────────────────────────────────────
 
 /**
@@ -251,37 +249,35 @@ export async function executeAction(
 
   // Process path revalidation — build element tree (not yet serialized).
   //
-  // TIM-1454: Only render the path if it matches the current page. Non-matching
-  // paths are collected as `invalidatedPaths` — the client evicts them from its
-  // caches so the next navigation fetches fresh data.
+  // TIM-1454: Only a path that matches the current page is rendered. When
+  // every call names another page, `onlyOtherPagesNamed` tells the client to
+  // evict its caches instead. The matching path is looked for across every
+  // call, not just the first: an action that calls revalidatePath('/other')
+  // and then revalidatePath('/current') must still re-render the current
+  // page (TIM-1461).
   let revalidation: RevalidationResult | undefined;
-  let invalidatedPaths: string[] | undefined;
-
-  if (state.paths.length > 0) {
-    const path = state.paths[0];
+  const { requestPathname, requestSearch } = config;
+  const isCurrentPage = (path: string) =>
+    !requestPathname || revalidationPathMatches(path, requestPathname, requestSearch);
+  const path = state.paths.find(isCurrentPage);
+  const onlyOtherPagesNamed = state.paths.length > 0 && path === undefined;
 
-    if (
-      config.requestPathname &&
-      !revalidationPathMatches(path, config.requestPathname, config.requestSearch)
-    ) {
-      invalidatedPaths = [stripFragment(path)];
-    } else if (config.renderer) {
-      try {
-        revalidation = await config.renderer(path);
-      } catch (renderError) {
-        if (isRedirectSignal(renderError)) {
-          redirectTo = renderError.location;
-          redirectStatus = renderError.status;
-        } else if (isDenySignal(renderError)) {
-          console.error(
-            `[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`
-          );
-        } else if (renderError instanceof RevalidationDropped) {
-          console.error(`[timber] ${renderError.message}`);
-        } else {
-          console.error('[timber] revalidatePath render failed:', renderError);
-          revalidationErrors.push(renderError);
-        }
+  if (path !== undefined && config.renderer) {
+    try {
+      revalidation = await config.renderer(path);
+    } catch (renderError) {
+      if (isRedirectSignal(renderError)) {
+        redirectTo = renderError.location;
+        redirectStatus = renderError.status;
+      } else if (isDenySignal(renderError)) {
+        console.error(
+          `[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`
+        );
+      } else if (renderError instanceof RevalidationDropped) {
+        console.error(`[timber] ${renderError.message}`);
+      } else {
+        console.error('[timber] revalidatePath render failed:', renderError);
+        revalidationErrors.push(renderError);
       }
     }
   }
@@ -289,7 +285,7 @@ export async function executeAction(
   return {
     actionResult,
     revalidation,
-    invalidatedPaths,
+    onlyOtherPagesNamed,
     revalidationErrors,
     ...(redirectTo ? { redirectTo, redirectStatus } : {}),
   };
@@ -297,7 +293,6 @@ export async function executeAction(
 
 /**
  * Check if a `revalidatePath(path)` argument matches the request pathname.
-/**
  * Canonicalizes the revalidated path the same way the renderer does so
  * equivalent paths compare equal. Returns true when the paths match or
  * when comparison is inconclusive (validation failure → render to be safe).

package/src/server/als-registry.ts

@@ -238,7 +238,7 @@ export const revalidationAls = getOrCreateAls<RevalidationState>(
 
 // ─── Form Flash ───────────────────────────────────────────────────────────
 // Used by: form-flash.ts (getFormFlash())
-// Design doc: design/08-forms-and-actions.md §"No-JS Error Round-Trip"
+// Design doc: design/08-forms-and-actions.md §"No-JS Result Round-Trip"
 
 /** @internal — import via form-flash.ts public API */
 export const formFlashAls = getOrCreateAls<import('./form-flash.ts').FormFlashData>(

package/src/server/csrf.ts

@@ -1,9 +1,21 @@
 /**
- * CSRF protection — Origin header validation.
+ * CSRF protection — Fetch Metadata first, Origin as the fallback.
  *
- * Auto-derived from the Host header for single-origin deployments.
- * Configurable via allowedOrigins for multi-origin setups.
- * Disable with csrf: false (not recommended outside local dev).
+ * CSRF needs a victim's browser to attach cookies, and browsers mark the
+ * requests they send: `Sec-Fetch-Site` on HTTPS (and localhost) pages in
+ * every current browser, `Origin` on cross-site POSTs everywhere else. So
+ * the check trusts those two headers in that order, and lets a request
+ * carrying neither through — a webhook, curl, or a server-to-server
+ * `fetch`. The residual risk is browsers old enough to send neither on a
+ * form POST (Firefox < 70, IE11); SameSite cookies are the defense there.
+ * See design/08-forms-and-actions.md §"CSRF Protection".
+ *
+ * Prior art: Go's `net/http.CrossOriginProtection` (Go 1.25) and the OWASP
+ * CSRF cheat sheet (Fetch Metadata as a primary defense).
+ *
+ * The per-route exemption (`export const csrf = false` in route.ts) is not
+ * decided here: the caller owns route matching and applies it to a
+ * rejection. Disable globally with csrf: false (not recommended).
  *
  * See design/08-forms-and-actions.md §"CSRF Protection"
  * See design/13-security.md §"Security Testing Checklist" #6
@@ -15,33 +27,36 @@ import { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../shared/csrf-reject.ts'
 // ─── Types ────────────────────────────────────────────────────────────────
 
 export interface CsrfConfig {
-  /** Explicit list of allowed origins. Replaces Host-based auto-derivation. */
+  /**
+   * Origins trusted in addition to the request's own. Canonical origins
+   * only (`new URL(x).origin === x`); `validateConfig` enforces that.
+   */
   allowedOrigins?: string[];
   /** Set to false to disable CSRF validation entirely. */
   csrf?: boolean;
 }
 
-/** Why a request failed the Origin check — one value per rejection path. */
+/** Why a request failed the check — one value per rejection path. */
 export type CsrfRejectReason =
-  | 'missing-origin'
-  | 'origin-not-allowed'
+  | 'cross-origin'
   | 'missing-host'
   | 'invalid-host'
   | 'invalid-origin'
   | 'origin-mismatch';
 
 /**
- * A failed Origin check. `origin` is the request's Origin header (null when
- * absent); `expected` is the origin(s) it was compared against — the
- * `allowedOrigins` list, or the one origin derived from the Host header.
- * `expected` is empty when the check failed before an expected origin could
- * be determined. Both are for the server log only — never the response.
+ * A failed check. `origin` is the request's Origin header and `fetchSite`
+ * its Sec-Fetch-Site header (null when absent); `expected` is the origin(s)
+ * `origin` was compared against: the `allowedOrigins` list, preceded on
+ * `origin-mismatch` by the origin derived from the Host header. All three are for
+ * the server log only — never the response.
  */
 export interface CsrfRejection {
   ok: false;
   status: 403;
   reason: CsrfRejectReason;
   origin: string | null;
+  fetchSite: string | null;
   expected: readonly string[];
 }
 
@@ -52,6 +67,14 @@ export type CsrfResult = { ok: true } | CsrfRejection;
 /** HTTP methods that are considered safe (no mutation). */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 
+/**
+ * `Sec-Fetch-Site` values that mean the browser itself vouches for the
+ * request: `same-origin`, or `none` (user-initiated — typed URL, bookmark).
+ * Every other value, including ones no browser sends, is not same-origin.
+ * The header is forbidden to page scripts, so a page cannot forge it.
+ */
+const TRUSTED_FETCH_SITES = new Set(['same-origin', 'none']);
+
 // ─── Implementation ───────────────────────────────────────────────────────
 
 /**
@@ -78,46 +101,53 @@ function deriveRequestScheme(req: Request): string {
 }
 
 /**
- * Validate the Origin header against the request's full origin
- * (scheme + host + port).
+ * Decide whether an unsafe-method request may proceed.
  *
- * For mutation methods (POST, PUT, PATCH, DELETE):
- * - If `csrf: false`, skip validation.
- * - If `allowedOrigins` is set, Origin must match one exactly (no wildcards).
- * - Otherwise, Origin must match the derived request origin.
+ * In order:
+ * 1. `Sec-Fetch-Site` is `same-origin` or `none` → allow.
+ * 2. `Sec-Fetch-Site` has any other value → allow only if `Origin` is in
+ *    `allowedOrigins`.
+ * 3. No `Sec-Fetch-Site`, `Origin` present (a plain-HTTP page, or an
+ *    older browser) → `Origin` must be in `allowedOrigins` or equal the
+ *    origin derived from the scheme and `Host`.
+ * 4. Neither header → allow: not a browser, so no ambient cookies to abuse.
  *
- * Safe methods (GET, HEAD, OPTIONS) always pass.
+ * Safe methods (GET, HEAD, OPTIONS) and `csrf: false` always pass.
  */
 export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
-  // Safe methods don't need CSRF protection
-  if (SAFE_METHODS.has(req.method)) {
-    return { ok: true };
-  }
-
-  // Explicitly disabled
-  if (config.csrf === false) {
-    return { ok: true };
-  }
+  if (SAFE_METHODS.has(req.method)) return { ok: true };
+  if (config.csrf === false) return { ok: true };
 
+  const fetchSite = req.headers.get('Sec-Fetch-Site');
   const origin = req.headers.get('Origin');
+  const rejection = (reason: CsrfRejectReason, expected: readonly string[]): CsrfRejection => ({
+    ok: false,
+    status: 403,
+    reason,
+    origin,
+    fetchSite,
+    expected,
+  });
 
-  // No Origin header on a mutation → reject
-  if (!origin) {
-    return reject('missing-origin', null, []);
+  // Steps 1–2: the browser told us where the request came from.
+  if (fetchSite !== null) {
+    if (TRUSTED_FETCH_SITES.has(fetchSite)) return { ok: true };
+    if (origin !== null && config.allowedOrigins?.includes(origin)) return { ok: true };
+    return rejection('cross-origin', config.allowedOrigins ?? []);
   }
 
-  // If allowedOrigins is configured, use that instead of Host-based derivation
-  if (config.allowedOrigins) {
-    return config.allowedOrigins.includes(origin)
-      ? { ok: true }
-      : reject('origin-not-allowed', origin, config.allowedOrigins);
-  }
+  // Step 4: no browser marker at all.
+  if (origin === null) return { ok: true };
+
+  // Step 3: Origin only. The request's own origin, or a listed one — the
+  // same two sources step 2 trusts, so a same-origin POST from a page that
+  // gets no Fetch Metadata (plain HTTP) never needs listing (Go's
+  // CrossOriginProtection makes the same union).
+  const allowed = config.allowedOrigins ?? [];
+  if (allowed.includes(origin)) return { ok: true };
 
-  // Auto-derive from Host header
   const host = req.headers.get('Host');
-  if (!host) {
-    return reject('missing-host', origin, []);
-  }
+  if (!host) return rejection('missing-host', allowed);
 
   // Compare full origins (scheme + host + port) using URL.origin for
   // canonical port normalization (e.g. https://x:443 → https://x).
@@ -125,36 +155,28 @@ export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
   try {
     originOrigin = new URL(origin).origin;
   } catch {
-    return reject('invalid-origin', origin, []);
+    return rejection('invalid-origin', allowed);
   }
 
-  const scheme = deriveRequestScheme(req);
   let expectedOrigin: string;
   try {
-    expectedOrigin = new URL(`${scheme}://${host}`).origin;
+    expectedOrigin = new URL(`${deriveRequestScheme(req)}://${host}`).origin;
   } catch {
-    return reject('invalid-host', origin, []);
+    return rejection('invalid-host', allowed);
   }
 
   return originOrigin === expectedOrigin
     ? { ok: true }
-    : reject('origin-mismatch', origin, [expectedOrigin]);
-}
-
-function reject(
-  reason: CsrfRejectReason,
-  origin: string | null,
-  expected: readonly string[]
-): CsrfRejection {
-  return { ok: false, status: 403, reason, origin, expected };
+    : rejection('origin-mismatch', [expectedOrigin, ...allowed]);
 }
 
-// ─── Rejection Response// ─── Rejection Response ───────────────────────────────────────────────────
+// ─── Rejection Response ───────────────────────────────────────────────────
 
 /**
  * Longest request-derived value echoed into the server log. Origin, Host,
- * and the path are attacker-controlled; a request can carry kilobytes in
- * each, and every rejection writes a log line. Real values are far shorter.
+ * Sec-Fetch-Site, and the path are attacker-controlled; a request can carry
+ * kilobytes in each, and every rejection writes a log line. Real values are
+ * far shorter.
  */
 const MAX_LOGGED_VALUE = 200;
 
@@ -176,16 +198,20 @@ const PROXY_HINT =
   'original Host and X-Forwarded-Proto, or list the public origin in allowedOrigins ' +
   'in timber.config.ts.';
 
+const EXEMPTION_HINT =
+  'If this route.ts must accept cross-site browser requests (OIDC form_post, SAML, ' +
+  '3-D Secure returns), add `export const csrf = false` to it.';
+
 /**
  * Browsers send `Origin: null` from opaque contexts: sandboxed iframes, a POST
  * redirected across origins, file: pages. Every such context shares the one
- * value — an attacker's `<iframe sandbox>` included — so the hint must never
- * suggest allowlisting it.
+ * value — an attacker's `<iframe sandbox>` included — so config validation
+ * refuses it in `allowedOrigins` and the hint points at the exemption instead.
  */
 const OPAQUE_ORIGIN_DETAIL =
   'origin "null" is an opaque origin (sandboxed iframe, a POST redirected across ' +
-  'origins, or a file: page). Do not add "null" to allowedOrigins: every opaque ' +
-  "context sends it, including an attacker's sandboxed iframe.";
+  'origins, or a file: page). allowedOrigins cannot admit it: every opaque context ' +
+  `sends "null", including an attacker's sandboxed iframe. ${EXEMPTION_HINT}`;
 
 /** One sentence per rejection path: what was observed, and what to change. */
 function describeRejection(r: CsrfRejection, host: string | null): string {
@@ -193,20 +219,19 @@ function describeRejection(r: CsrfRejection, host: string | null): string {
   const origin = quote(r.origin ?? '');
   const expected = r.expected.map(quote).join(', ');
   switch (r.reason) {
-    case 'missing-origin':
-      return (
-        'request has no Origin header. Browsers send Origin on fetch and form POSTs; ' +
-        'non-browser clients calling an unsafe method must set it.'
-      );
     // The opaque-origin note replaces only the reasons where the origin
     // itself is the fault. A null-origin request that fails for another
     // reason (no Host, a bad Host) keeps that reason's diagnosis and hint.
-    case 'origin-not-allowed':
+    case 'cross-origin': {
       if (opaque) return OPAQUE_ORIGIN_DETAIL;
+      const from = r.origin === null ? 'with no Origin header' : `from origin ${origin}`;
+      const allowed = r.expected.length > 0 ? ` and is not in allowedOrigins [${expected}]` : '';
       return (
-        `origin ${origin} is not in allowedOrigins [${expected}]. ` +
-        'If this origin is legitimate, add it to allowedOrigins in timber.config.ts.'
+        `Sec-Fetch-Site ${quote(r.fetchSite ?? '')} request ${from}: the browser reports ` +
+        `it is not same-origin${allowed}. If this origin is legitimate, add it to ` +
+        `allowedOrigins in timber.config.ts. ${EXEMPTION_HINT}`
       );
+    }
     case 'missing-host':
       return `origin ${origin} could not be checked: request has no Host header. ${PROXY_HINT}`;
     case 'invalid-host':
@@ -214,8 +239,11 @@ function describeRejection(r: CsrfRejection, host: string | null): string {
     case 'invalid-origin':
       if (opaque) return OPAQUE_ORIGIN_DETAIL;
       return `Origin header ${origin} is not a valid origin.`;
-    case 'origin-mismatch':
-      return `origin ${origin} does not match the request origin ${expected}. ${PROXY_HINT}`;
+    case 'origin-mismatch': {
+      const [own, ...listed] = r.expected.map(quote);
+      const list = listed.length > 0 ? ` or allowedOrigins [${listed.join(', ')}]` : '';
+      return `origin ${origin} does not match the request origin ${own}${list}. ${PROXY_HINT}`;
+    }
   }
 }