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

package/src/server/actions.ts

@@ -2,10 +2,10 @@
  * Server action primitives: revalidatePath, revalidateTag, and the action handler.
  *
  * - revalidatePath(path) re-renders the route at that path and returns the RSC
- *   flight payload for inline reconciliation.
- * - revalidateTag(tag) invalidates timber.cache entries by tag.
- *
- * Both are callable from anywhere on the server — actions, API routes, handlers.
+ *   flight payload for inline reconciliation. Server actions only.
+ * - revalidateTag(tag) invalidates timber.cache entries by tag. Callable from
+ *   any server code: deferred to the end of the action inside one, immediate
+ *   anywhere else.
  *
  * The action handler processes incoming action requests, validates CSRF,
  * enforces body limits, executes the action, and returns the response
@@ -16,9 +16,10 @@
 
 import { cache } from '../cache/cache-api.ts';
 import { canonicalize } from './canonicalize.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
 import { withSpan } from './tracing.ts';
 import { revalidationAls, type RevalidationState } from './als-registry.ts';
+import type { ReactCacheScope } from './react-cache-scope.ts';
 // ─── Types ───────────────────────────────────────────────────────────────
 
 /** Result of rendering a revalidation — payload root before RSC serialization. */
@@ -28,11 +29,33 @@ export interface RevalidationResult {
    * ordinary route payload. The client splits it in `applyActionResult`.
    */
   payload: unknown;
+  /**
+   * The `React.cache` scope the target route's middleware ran in. The
+   * revalidated tree renders in it, so middleware, access.ts and components
+   * share one scope — fresh, never the action body's (TIM-1529).
+   */
+  reactCacheScope: ReactCacheScope;
 }
 
 /** Renderer function that builds a React element tree for a given path. */
 export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
 
+/**
+ * Thrown by a `RevalidateRenderer` that decided not to render: the path
+ * was rejected, its params failed coercion, or its middleware answered
+ * with a `Response` that cannot become an element tree. `executeAction`
+ * drops the revalidation — the action result is still delivered, with no
+ * `_tree` piggybacked — and, because the drop was a decision, does not
+ * return it as an error to report. Identified by `instanceof`, so the
+ * message text never reaches clients.
+ */
+export class RevalidationDropped extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RevalidationDropped';
+  }
+}
+
 // Re-export the type from the registry for public API consumers.
 export type { RevalidationState } from './als-registry.ts';
 
@@ -67,6 +90,14 @@ export interface ActionHandlerResult {
   redirectTo?: string;
   /** Redirect status code. */
   redirectStatus?: number;
+  /**
+   * Errors the action survived after its body returned: a `revalidateTag`
+   * invalidation that rejected, or a `revalidatePath` render that threw.
+   * Each is already logged. They are returned rather than reported here
+   * because reporting needs the request, which the caller owns; the caller
+   * passes each to `onRequestError` once.
+   */
+  revalidationErrors: unknown[];
 }
 
 // ─── Revalidation State ──────────────────────────────────────────────────
@@ -83,49 +114,56 @@ export function _runWithRevalidationState<T>(state: RevalidationState, fn: () =>
   return revalidationAls.run(state, fn);
 }
 
-/**
- * Get the current revalidation state. Throws if called outside an action context.
- * @internal
- */
-function getRevalidationState(): RevalidationState {
-  const state = revalidationAls.getStore();
-  if (!state) {
-    throw new Error(
-      'revalidatePath/revalidateTag called outside of a server action context. ' +
-        'These functions can only be called during action execution.'
-    );
-  }
-  return state;
-}
-
 // ─── Public API ──────────────────────────────────────────────────────────
 
 /**
  * Re-render the route at `path` and include the RSC flight payload in the
  * action response. The client reconciles inline — no separate fetch needed.
  *
- * Can be called from server actions, API routes, or any server-side context.
+ * Only callable inside a server action: it attaches a render to the action
+ * response, and nothing else has one. To refresh cached data from a
+ * `route.ts` handler, a webhook, or a job, use `revalidateTag()` or
+ * `cache.invalidate()`.
  *
  * @param path - The path to re-render (e.g. '/dashboard', '/todos').
  */
 export function revalidatePath(path: string): void {
-  const state = getRevalidationState();
+  const state = revalidationAls.getStore();
+  if (!state || state.closed) {
+    throw new Error(
+      'revalidatePath() can only be called inside a server action: it re-renders ' +
+        'the route into the action response, and there is no action response here. ' +
+        'To refresh cached data from a route handler or other server code, call ' +
+        'revalidateTag() or cache.invalidate() for the tags the route reads.'
+    );
+  }
   if (!state.paths.includes(path)) {
     state.paths.push(path);
   }
 }
 
 /**
- * Invalidate all timber.cache entries tagged with `tag`.
+ * Invalidate all timber.cache entries tagged with `tag`, and tombstone the
+ * pre-rendered component seeds that carry it.
  * Does not return a payload — the next request for an invalidated entry re-executes.
  *
+ * Callable from any server code. Inside a server action the invalidation is
+ * deferred until the action body returns, so a `revalidatePath()` render in
+ * the same action reads fresh data; the returned promise resolves at once.
+ * Anywhere else — a `route.ts` webhook, a job, or background work an action
+ * started that runs after the action body returned — it is
+ * `cache.invalidate({ tag })`, and the promise settles when the invalidation
+ * has. Await it before responding.
+ *
  * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
  */
-export function revalidateTag(tag: string): void {
-  const state = getRevalidationState();
+export function revalidateTag(tag: string): Promise<void> {
+  const state = revalidationAls.getStore();
+  if (!state || state.closed) return cache.invalidate({ tag });
   if (!state.tags.includes(tag)) {
     state.tags.push(tag);
   }
+  return Promise.resolve();
 }
 
 // ─── Helpers ────────────────────────────────────────────────────────────
@@ -157,6 +195,7 @@ export async function executeAction(
   spanMeta?: { actionFile?: string; actionName?: string }
 ): Promise<ActionHandlerResult> {
   const state: RevalidationState = { paths: [], tags: [] };
+  const revalidationErrors: unknown[] = [];
   let actionResult: unknown;
   let redirectTo: string | undefined;
   let redirectStatus: number | undefined;
@@ -180,6 +219,10 @@ export async function executeAction(
       } else {
         throw error;
       }
+    } finally {
+      // From here `paths` and `tags` are snapshotted below (or abandoned on
+      // a throw); later calls from un-awaited work must not queue into them.
+      state.closed = true;
     }
   });
 
@@ -201,6 +244,7 @@ export async function executeAction(
     for (const r of results) {
       if (r.status === 'rejected') {
         console.error('[timber] revalidateTag invalidation failed:', r.reason);
+        revalidationErrors.push(r.reason);
       }
     }
   }
@@ -232,8 +276,11 @@ export async function executeAction(
           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);
         }
       }
     }
@@ -243,6 +290,7 @@ export async function executeAction(
     actionResult,
     revalidation,
     invalidatedPaths,
+    revalidationErrors,
     ...(redirectTo ? { redirectTo, redirectStatus } : {}),
   };
 }

package/src/server/als-registry.ts

@@ -66,6 +66,14 @@ export const requestContextAls = getOrCreateAls<RequestContextStore>(
 );
 
 export interface RequestContextStore {
+  /**
+   * The request this context was opened for, or `null` in the build-time
+   * capture store, where there is none. Read only to report a failed
+   * `cache.component` background re-render, which outlives the code that had the request
+   * in hand (design/17 §"Which errors reach it"). Everything a page may read
+   * has its own field below.
+   */
+  request: Request | null;
   /** Incoming request headers (read-only view). */
   headers: Headers;
   /** Raw cookie header string, parsed lazily into a Map on first access. */
@@ -167,16 +175,26 @@ export interface CookieEntry {
 // Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
+/**
+ * One trace scope. The pipeline opens the request's scope; withSpan() opens a
+ * copy per span, so the span pointers below always name the span the code is
+ * running in, however sibling spans interleave (TIM-1538).
+ */
 export interface TraceStore {
-  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */
-  traceId: string;
-  /** OTEL span ID if available, undefined otherwise. */
+  /**
+   * The request's trace, shared by reference by every span scope in it.
+   * `traceId` is the 32-char lowercase hex trace ID (OTEL or UUID fallback);
+   * replaceTraceId() swaps it from inside the first span, and code outside
+   * that span (the request's completion log) sees the swap.
+   */
+  request: { traceId: string };
+  /** The enclosing OTEL span's ID if an SDK is active, undefined otherwise. */
   spanId?: string;
   /**
-   * Innermost active native platform span (e.g. Cloudflare's `Span` from
+   * The enclosing native platform span (e.g. Cloudflare's `Span` from
    * tracing.enterSpan()). Tracked so setSpanAttribute() can set attributes
    * after span creation — the platform API has no getActiveSpan() equivalent.
-   * Saved/restored by withSpan() around each callback. See TIM-1135.
+   * See TIM-1135.
    */
   platformSpan?: import('./tracing.ts').PlatformSpan;
 }
@@ -204,6 +222,13 @@ export interface RevalidationState {
   paths: string[];
   /** Tags to invalidate (populated by revalidateTag calls). */
   tags: string[];
+  /**
+   * Set once the action body has settled. ALS still hands this state to
+   * work the action started and did not await (a `waitUntil()` job), but
+   * `paths` and `tags` are no longer read, so a late `revalidateTag` must
+   * invalidate immediately instead of queueing into a list nobody drains.
+   */
+  closed?: boolean;
 }
 
 /** @internal — import via actions.ts public API */
@@ -255,3 +280,46 @@ export interface WorkersCachePurgeCtx {
 export const workersCachePurgeAls = getOrCreateAls<WorkersCachePurgeCtx>(
   Symbol.for('timber:workers-cache-purge-als')
 );
+
+// ─── React.cache Scope ───────────────────────────────────────────────────
+// Used by: react-cache-bridge.ts (runWithReactCacheScope(), the patched
+// getCacheForType on Flight's dispatcher)
+// Design doc: design/02-rendering-pipeline.md §"Cache Scoping Model"
+
+/**
+ * One request's `React.cache` storage — the Map React's `cache()` hands to
+ * `getCacheForType`, owned by timber instead of by a Flight `Request` so
+ * `middleware.ts`, `proxy.ts`, and route handlers share it with the render.
+ */
+export type ReactCacheScope = Map<() => unknown, unknown>;
+
+/** @internal — import via react-cache-bridge.ts public API */
+export const reactCacheScopeAls = getOrCreateAls<ReactCacheScope>(
+  Symbol.for('timber:react-cache-scope-als')
+);
+
+// ─── Prebuilt Capture ────────────────────────────────────────────────────
+// Used by: prebuilt/capture-state.ts (createCaptureScope(), noteWrapperRender())
+// Design doc: design/45-cache-lifetimes.md §Nesting Semantics
+
+/**
+ * One in-flight `cache.component` payload capture — a build-time entry or
+ * a request-time re-render. Scoped to the capture's async context so a
+ * concurrent request's render does not observe it.
+ */
+export interface PrebuiltCaptureStore {
+  /** The component being captured. */
+  outerId: string;
+  /**
+   * Props half of the captured entry's cache key (null when unkeyable).
+   * Rendering `outerId` again with this key is a cycle (TIM-1547).
+   */
+  outerPropsKey: string | null;
+  /** Wrapped components that rendered inside this capture, by component id. */
+  nested: Map<string, import('./prebuilt/capture-state.ts').NestedRecord>;
+}
+
+/** @internal — import via prebuilt/capture-state.ts */
+export const prebuiltCaptureAls = getOrCreateAls<PrebuiltCaptureStore>(
+  Symbol.for('timber:prebuilt-capture-als')
+);

package/src/server/chain-url-parts.ts

@@ -129,7 +129,7 @@ export function consumedUrlParts(
   index: number,
   match: RouteMatch
 ): string[] {
-  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const rawParams = match.rawSegmentParams;
   const partsThrough = (from: number, to: number) =>
     extractUrlParts(segments.slice(from, to + 1), rawParams);
 

package/src/server/children-interception.ts

@@ -77,7 +77,8 @@ export function createInterceptedRouteMatcher(root: ManifestSegmentNode): Interc
       // `validateInterceptionPlacement` rejects a dynamic one at build time,
       // precisely because the intercepted URL carries no value to bind it
       // with. So the intercepting subtree's params are the whole record.
-      segmentParams: result.slotParams,
+      rawSegmentParams: result.slotParams,
+      segmentParams: { ...result.slotParams },
       middlewareChain: collectMiddlewareChain(segments),
     };
   };

package/src/server/cookie-context.ts

@@ -2,8 +2,8 @@
  * Cookie Context — per-request cookie API and on-the-wire helpers.
  *
  * Split out of `request-context.ts` (TIM-853) so the cookie subsystem
- * — encoding contract, options grammar, parser, serializer, RYW map,
- * and rerender seed — lives in one file. The headers/scope/params APIs
+ * — encoding contract, options grammar, parser, serializer, and RYW map
+ * — lives in one file. The headers/scope/params APIs
  * stay in `request-context.ts` and call into this module via the
  * exported helpers.
  *
@@ -14,6 +14,11 @@
 
 import { requestContextAls, type RequestContextStore } from './als-registry.ts';
 import { isDebug } from './debug.ts';
+import {
+  ANY_COOKIE,
+  noteCookieReadForReactCache,
+  warnIfCachedCookieIsWritten,
+} from './react-cache-scope.ts';
 import {
   assertValidCookieName,
   assertValidCookieValue,
@@ -69,16 +74,22 @@ export function getCookieJar(): RequestCookies {
 
   const map = store.parsedCookies;
   return {
+    // Reads are noted (dev only) so a later write of the same cookie can
+    // warn if React.cache may have memoized the old value (TIM-1529 D3).
     get(name: string): string | undefined {
+      noteCookieReadForReactCache(name);
       return map.get(name);
     },
     has(name: string): boolean {
+      noteCookieReadForReactCache(name);
       return map.has(name);
     },
     getAll(): Array<{ name: string; value: string }> {
+      noteCookieReadForReactCache(ANY_COOKIE);
       return Array.from(map.entries()).map(([name, value]) => ({ name, value }));
     },
     get size(): number {
+      noteCookieReadForReactCache(ANY_COOKIE);
       return map.size;
     },
 
@@ -148,6 +159,7 @@ export function getCookieJar(): RequestCookies {
       // exactly what the developer wrote — never the encoded form.
       // For `{ raw: true }`, the wire form IS the logical form.
       map.set(name, raw ? wireValue : value);
+      warnIfCachedCookieIsWritten(name);
     },
 
     setFromHeaders(headers: Headers): void {
@@ -203,6 +215,7 @@ export function getCookieJar(): RequestCookies {
       store.cookieJar.set(name, { name, value: '', options: opts });
       // Remove from read view
       map.delete(name);
+      warnIfCachedCookieIsWritten(name);
     },
 
     clear(): void {
@@ -217,9 +230,11 @@ export function getCookieJar(): RequestCookies {
         });
       }
       map.clear();
+      warnIfCachedCookieIsWritten(ANY_COOKIE);
     },
 
     toString(): string {
+      noteCookieReadForReactCache(ANY_COOKIE);
       // Re-encode values when serializing as a Cookie header — the
       // RYW map holds decoded logical values, but a Cookie header has
       // to satisfy `cookie-octet`. Mirror the auto-encode contract on
@@ -341,52 +356,6 @@ const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
 
 // ─── Framework-Internal Helpers ───────────────────────────────────────────
 
-/**
- * Per-request seed map of cookie name → value, registered out-of-band so the
- * pipeline's `runWithRequestContext` call can pick it up without changing
- * the function's calling convention. Stored in a WeakMap keyed by the
- * synthetic Request object built for the rerender path, so the seed lives
- * exactly as long as the request and is collected with it.
- *
- * The seed exists to eliminate the parse/serialize round-trip on the no-JS
- * form-rerender path — see ONGOING_SECURITY.md H-3 (TIM-868). The action's
- * post-mutation RYW snapshot is threaded directly into the rerender scope's
- * `parsedCookies` map, bypassing `parseCookieHeader` entirely.
- */
-const seededRequestCookies = new WeakMap<Request, Map<string, string>>();
-
-/**
- * Register a pre-parsed cookie map to use as the request context seed for
- * the next `runWithRequestContext(req, …)` call with this exact `req`.
- *
- * Used by the no-JS form-rerender dispatcher in
- * `rsc-entry/wrap-action-dispatch.ts` to thread the action's post-mutation
- * cookie state into the rerender scope without serializing back through a
- * `Cookie:` header. See TIM-868 / TIM-837.
- *
- * @internal — framework use only.
- */
-export function seedRequestCookies(req: Request, cookies: Map<string, string>): void {
-  // Defensive copy: callers must not be able to mutate the rerender scope's
-  // map after seeding, and the rerender scope must not mutate the snapshot
-  // we hand back to other observers.
-  seededRequestCookies.set(req, new Map(cookies));
-}
-
-/**
- * Pop the seed (if any) for `req` and return it. Called from
- * `runWithRequestContext` exactly once per request — the seed is consumed
- * eagerly so it cannot leak into a hypothetical future re-use of the same
- * Request reference.
- *
- * @internal — framework use only.
- */
-export function consumeSeededCookies(req: Request): Map<string, string> | undefined {
-  const seed = seededRequestCookies.get(req);
-  if (seed) seededRequestCookies.delete(req);
-  return seed;
-}
-
 /**
  * Build a Map of cookie name → value reflecting the current request's
  * read-your-own-writes state. Includes incoming cookies plus any
@@ -472,6 +441,7 @@ function setRaw(
   // the caller. See design/29-cookies.md §"Cookie Attribute Validation".
   assertValidCookieOptions(options);
   store.cookieJar.set(name, { name, value, options });
+  warnIfCachedCookieIsWritten(name);
   // Deletion cookies (Max-Age=0) should not appear in the read map.
   if (options.maxAge === 0) {
     readMap.delete(name);

package/src/server/csp-nonce.ts

@@ -56,15 +56,3 @@ export function requestCspNonce(): string {
 export function getCspNonce(): string | undefined {
   return requestContextAls.getStore()?.cspNonce;
 }
-
-/**
- * The ` nonce="…"` attribute fragment for a timber-generated `<script>` tag,
- * or `''` when the request has no nonce. Callers interpolate it directly
- * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.
- *
- * The value comes from `generateNonce` and is base64, so no attribute
- * escaping is required.
- */
-export function nonceAttr(nonce: string | undefined): string {
-  return nonce ? ` nonce="${nonce}"` : '';
-}

package/src/server/csrf.ts

@@ -9,6 +9,9 @@
  * See design/13-security.md §"Security Testing Checklist" #6
  */
 
+import { logCsrfRejected } from './logger.ts';
+import { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../shared/csrf-reject.ts';
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 export interface CsrfConfig {
@@ -18,7 +21,31 @@ export interface CsrfConfig {
   csrf?: boolean;
 }
 
-export type CsrfResult = { ok: true } | { ok: false; status: 403 };
+/** Why a request failed the Origin check — one value per rejection path. */
+export type CsrfRejectReason =
+  | 'missing-origin'
+  | 'origin-not-allowed'
+  | '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.
+ */
+export interface CsrfRejection {
+  ok: false;
+  status: 403;
+  reason: CsrfRejectReason;
+  origin: string | null;
+  expected: readonly string[];
+}
+
+export type CsrfResult = { ok: true } | CsrfRejection;
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -76,19 +103,20 @@ export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
 
   // No Origin header on a mutation → reject
   if (!origin) {
-    return { ok: false, status: 403 };
+    return reject('missing-origin', null, []);
   }
 
   // If allowedOrigins is configured, use that instead of Host-based derivation
   if (config.allowedOrigins) {
-    const allowed = config.allowedOrigins.includes(origin);
-    return allowed ? { ok: true } : { ok: false, status: 403 };
+    return config.allowedOrigins.includes(origin)
+      ? { ok: true }
+      : reject('origin-not-allowed', origin, config.allowedOrigins);
   }
 
   // Auto-derive from Host header
   const host = req.headers.get('Host');
   if (!host) {
-    return { ok: false, status: 403 };
+    return reject('missing-host', origin, []);
   }
 
   // Compare full origins (scheme + host + port) using URL.origin for
@@ -97,7 +125,7 @@ export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
   try {
     originOrigin = new URL(origin).origin;
   } catch {
-    return { ok: false, status: 403 };
+    return reject('invalid-origin', origin, []);
   }
 
   const scheme = deriveRequestScheme(req);
@@ -105,8 +133,112 @@ export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
   try {
     expectedOrigin = new URL(`${scheme}://${host}`).origin;
   } catch {
-    return { ok: false, status: 403 };
+    return reject('invalid-host', origin, []);
   }
 
-  return originOrigin === expectedOrigin ? { ok: true } : { ok: false, status: 403 };
+  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 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.
+ */
+const MAX_LOGGED_VALUE = 200;
+
+function clip(value: string): string {
+  return value.length > MAX_LOGGED_VALUE ? `${value.slice(0, MAX_LOGGED_VALUE)}…` : value;
+}
+
+/**
+ * Clip and quote a request-derived value for the log. JSON quoting escapes
+ * quotes and control characters, so a crafted header cannot close the quote
+ * and forge `key=value` fields or a second line.
+ */
+function quote(value: string): string {
+  return JSON.stringify(clip(value));
+}
+
+const PROXY_HINT =
+  'If the app runs behind a proxy that rewrites Host or terminates TLS, forward the ' +
+  'original Host and X-Forwarded-Proto, or list the public origin in allowedOrigins ' +
+  'in timber.config.ts.';
+
+/**
+ * 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.
+ */
+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.";
+
+/** One sentence per rejection path: what was observed, and what to change. */
+function describeRejection(r: CsrfRejection, host: string | null): string {
+  const opaque = r.origin === 'null';
+  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':
+      if (opaque) return OPAQUE_ORIGIN_DETAIL;
+      return (
+        `origin ${origin} is not in allowedOrigins [${expected}]. ` +
+        'If this origin is legitimate, add it to allowedOrigins in timber.config.ts.'
+      );
+    case 'missing-host':
+      return `origin ${origin} could not be checked: request has no Host header. ${PROXY_HINT}`;
+    case 'invalid-host':
+      return `origin ${origin} could not be checked: Host header ${quote(host ?? '')} is not a valid host. ${PROXY_HINT}`;
+    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}`;
+  }
+}
+
+/**
+ * Turn a failed check into the response the client sees, and log why.
+ *
+ * The response is a 403 marked as a CSRF rejection (header + plain-text
+ * body) so it cannot be mistaken for an access-control 403. It never
+ * carries the observed or expected origins — `allowedOrigins` is server
+ * configuration, and a Host-derived origin can be an internal hostname
+ * behind a proxy. The server log gets the full diagnosis.
+ */
+export function csrfRejectionResponse(req: Request, rejection: CsrfRejection): Response {
+  logCsrfRejected(describeRejection(rejection, req.headers.get('Host')), {
+    method: req.method,
+    path: clip(new URL(req.url).pathname),
+    reason: rejection.reason,
+  });
+  return new Response('Forbidden: CSRF origin check failed\n', {
+    status: rejection.status,
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+      [CSRF_REJECT_HEADER]: CSRF_REJECT_VALUE,
+    },
+  });
 }

package/src/server/debug.ts

@@ -48,7 +48,6 @@
  *
  * This is the ONLY function that should gate client-visible dev behavior:
  * - Dev error pages with stack traces
- * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
  * - Error messages in action `INTERNAL_ERROR` payloads
  * - Pipeline error handler wiring (Vite overlay)
  *