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

package/src/server/logger.ts

@@ -8,10 +8,11 @@
  * See design/17-logging.md §"Production Logging"
  */
 
-import { getTraceStore } from './tracing.ts';
+import { generateTraceId, getTraceStore } from './tracing.ts';
 import { createDefaultLogger } from './default-logger.ts';
 import { isDevMode } from './debug.ts';
-import { isControlFlowSignal } from './primitives.ts';
+import { isControlFlowSignal } from './signal-identity.ts';
+import type { CsrfRejectReason } from './csrf.ts';
 
 // ─── Logger Interface ─────────────────────────────────────────────────────
 
@@ -56,7 +57,7 @@ function withTraceContext(data?: Record<string, unknown>): Record<string, unknow
   const store = getTraceStore();
   const enriched: Record<string, unknown> = { ...data };
   if (store) {
-    enriched.trace_id = store.traceId;
+    enriched.trace_id = store.request.traceId;
     if (store.spanId) {
       enriched.span_id = store.spanId;
     }
@@ -66,6 +67,24 @@ function withTraceContext(data?: Record<string, unknown>): Record<string, unknow
 
 // ─── Framework Event Emitters ─────────────────────────────────────────────
 
+/**
+ * Log a CSRF rejection. Level: warn — the 403 body is deliberately terse,
+ * so this line is the only place the rejected origin is visible (TIM-1459).
+ * `detail` names the observed origin and, where one exists, the expected one.
+ *
+ * The CSRF gate runs at the pipeline boundary, before the pipeline opens its
+ * trace scope, so a rejection mints its own `trace_id` — the field is always
+ * present (design/17-logging.md §"trace_id is Always Set").
+ */
+export function logCsrfRejected(
+  detail: string,
+  data: { method: string; path: string; reason: CsrfRejectReason }
+): void {
+  const fields = withTraceContext(data);
+  fields.trace_id ??= generateTraceId();
+  _logger.warn(`CSRF origin check failed: ${detail}`, fields);
+}
+
 /** Log a completed request. Level: info. */
 export function logRequestCompleted(data: {
   method: string;
@@ -110,6 +129,12 @@ export function logMiddlewareError(data: { method: string; path: string; error:
   _logger.error('unhandled error in middleware phase', withTraceContext(data));
 }
 
+/** Log unhandled error in route setup (matching, param coercion). Level: error. */
+export function logRouteSetupError(data: { method: string; path: string; error: unknown }): void {
+  if (isControlFlowSignal(data.error)) return;
+  _logger.error('unhandled error in route setup', withTraceContext(data));
+}
+
 /** Log unhandled render-phase error. Level: error. */
 export function logRenderError(data: {
   method: string;
@@ -158,6 +183,17 @@ export function logSwrRefetchFailed(data: { cacheKey: string; error: unknown }):
   _logger.warn('staleWhileRevalidate refetch failed', withTraceContext(data));
 }
 
+/** Log a cache value that loses fidelity through JSON serialization. Level: warn. */
+export function logLossyCacheValue(data: { cacheKey: string; types: string }): void {
+  _logger.warn(
+    'cache value contains types that lose fidelity through JSON serialization in ' +
+      'Redis/KV cache handlers: Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +
+      'The MemoryCacheHandler preserves them. Transform values to JSON-safe types before ' +
+      'caching, or use MemoryCacheHandler for values that require type preservation.',
+    withTraceContext(data)
+  );
+}
+
 /** Log cache miss. Level: debug. */
 export function logCacheMiss(data: { cacheKey: string }): void {
   _logger.debug('timber.cache MISS', withTraceContext(data));

package/src/server/param-coercion.ts

@@ -118,7 +118,12 @@ export function coerceSlotParams(
 }
 
 /**
- * Run segment param coercion on the matched route's segments.
+ * Coerce the matched route's raw segment params and return the result.
+ *
+ * Reads `match.rawSegmentParams` and never writes to `match`: the caller
+ * decides where the coerced params go. Reading the raw record makes the call
+ * repeatable — coercing a match twice runs every codec on the URL value both
+ * times, never on its own output.
  *
  * Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
  * design/41-global-params.md migration step 9). A route with no schema, or
@@ -132,24 +137,21 @@ export function coerceSlotParams(
  * See design/41-global-params.md §"Pipeline Integration"
  *
  * Stays `async` with nothing to await: it is injected as a
- * `CoerceSegmentParamsFn` into the revalidation renderer and the action
- * middleware runner, both of which await it. Narrowing the return type to
- * `void` would break those contracts and remove a microtask boundary the
- * pipeline's ordering has always had, for no gain.
+ * `CoerceSegmentParamsFn` into the revalidation renderer, which awaits
+ * it. Making it synchronous would
+ * change that contract and remove a microtask boundary the pipeline's
+ * ordering has always had, for no gain.
  */
 // eslint-disable-next-line @typescript-eslint/require-await -- see above
-export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+export async function coerceSegmentParams(match: RouteMatch): Promise<CoercedParams> {
   const globalCodecs = _globalCodecs;
-  // Unconditionally install a null-prototype target so the invariant
-  // "match.segmentParams is null-prototype" holds from the first line,
-  // regardless of whether any segment has a codec.
+  // Always a null-prototype record, whether or not any segment has a codec.
   const mergeTarget: CoercedParams = Object.create(null);
-  for (const key of Object.keys(match.segmentParams)) {
+  for (const key of Object.keys(match.rawSegmentParams)) {
     if (key !== '__proto__') {
-      mergeTarget[key] = match.segmentParams[key as keyof typeof match.segmentParams];
+      mergeTarget[key] = match.rawSegmentParams[key];
     }
   }
-  match.segmentParams = mergeTarget;
 
   // TIM-931/TIM-936: When a global schema is available, use it for coercion
   // instead of per-segment params.ts files. The global codec map is keyed
@@ -195,4 +197,5 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
       mergeTarget[key] = normalizeParamValue(parsed, key);
     }
   }
+  return mergeTarget;
 }

package/src/server/pipeline-helpers.ts

@@ -11,11 +11,22 @@
 
 import type { ProxyExport } from './proxy.ts';
 import { getSetCookieHeaders } from './cookie-context.ts';
-import { callOnRequestError } from './instrumentation.ts';
+import {
+  callOnRequestError,
+  hasOnRequestError,
+  type InstrumentationErrorContext,
+} from './instrumentation.ts';
 import { getTraceId } from './tracing.ts';
+import { requestContextAls } from './als-registry.ts';
 import { RedirectSignal } from './primitives.ts';
+import { isControlFlowSignal } from './signal-identity.ts';
+import { logRenderError, swallow } from './logger.ts';
+import { isAbortError } from './render-utils.ts';
+import { loadModule, ModuleLoadError, type ManifestLoader } from './safe-load.ts';
+import { getWaitUntil } from './waituntil-bridge.ts';
+import { isApiRouteChain, type ManifestSegmentNode } from './route-matcher.ts';
 import type { ProxyConfig } from './pipeline.ts';
-import { isRscRequest } from '../shared/rsc-media-type.ts';
+import type { PhaseName } from './pipeline-outcome.ts';
 
 // ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
 
@@ -70,6 +81,32 @@ export function applyCookieJar(headers: Headers): void {
   }
 }
 
+/**
+ * Bring a bag the jar was already applied to up to date with the jar.
+ *
+ * `applied` is what `getSetCookieHeaders()` returned when the jar was
+ * applied to `headers`. Values the jar no longer holds (a later write to the
+ * same name replaced them) are removed, and values it gained are appended.
+ * Every cookie then appears once, with its last write (design/29-cookies.md
+ * §"Last-Write-Wins for Same Name"). `Set-Cookie` values that did not come
+ * from the jar, such as a middleware appending to `ctx.headers` directly,
+ * are left alone.
+ */
+export function syncCookieJar(headers: Headers, applied: readonly string[]): void {
+  const current = getSetCookieHeaders();
+  const stale = applied.filter((value) => !current.includes(value));
+  const added = current.filter((value) => !applied.includes(value));
+  if (stale.length === 0 && added.length === 0) return;
+
+  const kept = headers.getSetCookie();
+  for (const value of stale) {
+    const index = kept.indexOf(value);
+    if (index !== -1) kept.splice(index, 1);
+  }
+  headers.delete('Set-Cookie');
+  for (const value of [...kept, ...added]) headers.append('Set-Cookie', value);
+}
+
 /**
  * Merge framework-managed response headers onto a terminal response without
  * overwriting headers the terminal response already set itself.
@@ -111,22 +148,43 @@ export function cloneWithMutableHeaders(response: Response): Response {
   });
 }
 
+// ─── Response Headers ──────────────────────────────────────────────────────
+
+/**
+ * A fresh response header bag for a page the pipeline renders, seeded with
+ * the default dynamic-page cache policy.
+ *
+ * Without a Cache-Control header, CDNs (particularly Cloudflare) may attempt
+ * to buffer/process the response differently, causing intermittent
+ * multi-second delays. This matches Next.js's default behavior. Every bag a
+ * rendered page can be written onto starts here — a matched route, the
+ * no-match 404, and a deny page for a proxy-phase signal — so none of them
+ * leaves without a cache policy. Middleware and route handlers may replace it.
+ */
+export function dynamicResponseHeaders(): Headers {
+  return new Headers({
+    'Cache-Control': 'private, no-cache, no-store, max-age=0, must-revalidate',
+  });
+}
+
 // ─── Redirect Builder ──────────────────────────────────────────────────────
 
 /**
  * Build a redirect Response from a RedirectSignal.
  *
- * For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
- * so the client router can perform a soft SPA redirect. A raw 302 would be
- * turned into an opaque redirect by fetch({redirect:'manual'}), crashing
- * createFromFetch. See design/19-client-navigation.md.
+ * For a client navigation (an RSC payload request for a page), returns 204 +
+ * X-Timber-Redirect so the client router can perform a soft SPA redirect. A
+ * raw 302 would be turned into an opaque redirect by
+ * fetch({redirect:'manual'}), crashing createFromFetch. See
+ * design/19-client-navigation.md. The caller decides what counts as a
+ * navigation: a route.ts match answers with a real 3xx whatever it accepts.
  */
 export function buildRedirectResponse(
   signal: RedirectSignal,
-  req: Request,
-  headers: Headers
+  headers: Headers,
+  navigation: boolean
 ): Response {
-  if (isRscRequest(req)) {
+  if (navigation) {
     headers.set('X-Timber-Redirect', signal.location);
     return new Response(null, { status: 204, headers });
   }
@@ -136,24 +194,211 @@ export function buildRedirectResponse(
 
 // ─── Instrumentation ───────────────────────────────────────────────────────
 
+/**
+ * Where an error was raised: a pipeline phase, a server action, or a
+ * handler that answers outside the page pipeline — a metadata route or the
+ * auto-generated sitemap — which reports like a route.ts handler.
+ */
+export type ErrorSource = PhaseName | 'action' | 'route';
+
 /**
  * Fire the user's onRequestError hook with request context.
- * Extracts request info from the Request object and calls the instrumentation hook.
+ *
+ * The one place a pipeline phase becomes the `phase` / `routeType` the hook
+ * reports, so every caller agrees. A render-phase error on a route.ts match
+ * is phase `'route'`, because the handler is what ran. Middleware reports
+ * as `'handler'`, its public name.
  */
 export async function fireOnRequestError(
   error: unknown,
   req: Request,
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
+  source: ErrorSource,
+  segments?: readonly ManifestSegmentNode[]
+): Promise<void> {
+  // One rule for every caller (design/17 §"Which errors reach it"): outcomes
+  // and aborts are not failures, and neither is anything a request raises
+  // after its client left — a driver throwing "connection closed" is not a bug.
+  if (!isReportableError(error) || req.signal?.aborted) return;
+  if (isRepeatedLoadFailure(error)) return;
+  await callHook(error, req, source, segments);
+}
+
+/**
+ * Module evaluations whose failure was already reported. A module that fails
+ * to evaluate rethrows the same error on every later import, and
+ * `loadModule()` wraps each one in a new `ModuleLoadError` with that error
+ * as its `cause`. One broken module is one bug until it changes, however many
+ * loads trip over it in a request or across requests: the page's boundaries,
+ * then the fallback page, then the next request. A WeakSet, so a module that
+ * is re-evaluated (an HMR edit) gets a new cause and is reported again.
+ */
+const reportedLoadFailures = new WeakSet<object>();
+
+/**
+ * The same for a module that threw a primitive (`throw 'broken'`), which a
+ * WeakSet cannot hold. Keyed on the file and the value instead, so a module
+ * re-broken after an edit with the very same value is not reported again.
+ * It grows with the number of broken modules, not with requests.
+ */
+const reportedPrimitiveLoadFailures = new Set<string>();
+
+function isRepeatedLoadFailure(error: unknown): boolean {
+  if (!(error instanceof ModuleLoadError)) return false;
+  const cause: unknown = error.cause;
+  if (typeof cause === 'object' && cause !== null) {
+    if (reportedLoadFailures.has(cause)) return true;
+    reportedLoadFailures.add(cause);
+    return false;
+  }
+  const key = `${error.filePath}\0${typeof cause}\0${String(cause)}`;
+  if (reportedPrimitiveLoadFailures.has(key)) return true;
+  reportedPrimitiveLoadFailures.add(key);
+  return false;
+}
+
+/**
+ * Call the hook with request context, with no filtering. Only
+ * `fireOnRequestError()` and background reporting call it: background work
+ * runs after the response, so its request having aborted says nothing about
+ * the failure.
+ */
+async function callHook(
+  error: unknown,
+  req: Request,
+  source: ErrorSource,
+  segments?: readonly ManifestSegmentNode[]
 ): Promise<void> {
+  if (!hasOnRequestError()) return;
   const url = new URL(req.url);
   const headersObj: Record<string, string> = {};
   req.headers.forEach((v, k) => {
     headersObj[k] = v;
   });
+  const apiRoute = source === 'route' || (segments !== undefined && isApiRouteChain(segments));
 
   await callOnRequestError(
     error,
     { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
+    {
+      phase: reportedPhase(source, apiRoute),
+      routePath: url.pathname,
+      routeType: source === 'action' ? 'action' : apiRoute ? 'route' : 'page',
+      traceId: getTraceId(),
+    }
   );
 }
+
+/**
+ * Whether an error is a failure `onRequestError` should hear about.
+ *
+ * Control-flow signals are outcomes the code chose — a `deny()` picks the
+ * page's status and data — and an abort is the client leaving. Callers answering
+ * a live request also skip everything once `req.signal` has aborted: a
+ * driver that throws "connection closed" after a disconnect is not a bug.
+ */
+export function isReportableError(error: unknown): boolean {
+  return !isControlFlowSignal(error) && !isAbortError(error);
+}
+
+/**
+ * Fire the hook without making the caller wait, for callers that cannot:
+ * Flight's `onError` is synchronous, and background work has no caller.
+ * The promise is registered with the request's `waitUntil` so platforms
+ * that stop work when the response ends (Workers, Lambda) let the hook
+ * finish. The hook's own failures are caught in `callOnRequestError()`.
+ */
+function fireInBackground(report: Promise<void>): void {
+  getWaitUntil()?.(
+    report.catch((hookError: unknown) => swallow(hookError, 'onRequestError could not be called'))
+  );
+}
+
+/**
+ * Log and report a render error that was answered in place rather than
+ * handed to the pipeline: a slot that degraded to its fallback, a Flight
+ * error row, a fallback page that failed and fell back again. The pipeline
+ * never sees these, so this is their one report. Errors that are not
+ * reportable (`isReportableError()`), or that arrive after the request
+ * aborted, are only logged.
+ */
+export function reportRenderError(
+  error: unknown,
+  req: Request,
+  details: { errorId?: string; segments?: readonly ManifestSegmentNode[] } = {}
+): void {
+  const { errorId, segments } = details;
+  logRenderError({ method: req.method, path: new URL(req.url).pathname, error, errorId });
+  fireInBackground(fireOnRequestError(error, req, 'render', segments));
+}
+
+/**
+ * Load a module the render can do without — a status page, an error page,
+ * `global-error.tsx`, a fallback page's layout — or report why it could not
+ * load and return `null`, so the next tier answers instead of the failure
+ * taking the page down. Every such load goes through here, whether it builds
+ * a boundary for a normal render or a fallback page, so a broken module is
+ * never skipped silently.
+ */
+export function loadFallbackModule(
+  file: ManifestLoader,
+  req: Request,
+  segments?: readonly ManifestSegmentNode[]
+): Promise<Record<string, unknown> | null> {
+  return loadModule(file).catch((loadError: unknown) => {
+    reportRenderError(loadError, req, { segments });
+    return null;
+  });
+}
+
+/**
+ * Run a `cache.component` stale-while-revalidate re-render as a singleflight
+ * body, and log and report its failure once for the flight. The stale
+ * payload already answered, so nothing else sees the failure.
+ *
+ * - **Once per flight.** A `.catch` on the flight's promise would run once
+ *   per request that joined it, so the report happens inside the body. A
+ *   body still running when the singleflight times out is reported then,
+ *   with the timeout error (the signal's reason), and its later rejection
+ *   is dropped.
+ * - **Against the request whose stale read started it**, read from the
+ *   request context the work runs in. With no request (the build-time
+ *   capture store) it is only logged.
+ * - **As phase `'render'`, route type `'page`.** A `cache.component` is a
+ *   server component, so the read that started this was a page render (a
+ *   revalidated page tree included). The request's own abort does not
+ *   suppress the report: the work runs after the response either way.
+ */
+export async function runBackgroundFlight(
+  signal: AbortSignal,
+  work: () => Promise<unknown>,
+  log: (error: unknown) => void
+): Promise<void> {
+  const failed = (error: unknown): void => {
+    log(error);
+    const request = requestContextAls.getStore()?.request;
+    if (request && isReportableError(error)) fireInBackground(callHook(error, request, 'render'));
+  };
+  const onTimeout = (): void => failed(signal.reason);
+  signal.addEventListener('abort', onTimeout, { once: true });
+  try {
+    await work();
+  } catch (error) {
+    if (!signal.aborted) failed(error);
+  } finally {
+    signal.removeEventListener('abort', onTimeout);
+  }
+}
+
+function reportedPhase(
+  source: ErrorSource,
+  apiRoute: boolean
+): InstrumentationErrorContext['phase'] {
+  switch (source) {
+    case 'middleware':
+      return 'handler';
+    case 'render':
+      return apiRoute ? 'route' : 'render';
+    default:
+      return source;
+  }
+}

package/src/server/pipeline-interception.ts

@@ -11,6 +11,11 @@
 
 import { classifyUrlSegment } from '../routing/segment-classify.ts';
 import type { InterceptionRewrite } from '../routing/interception.ts';
+import { computeSegmentTreePaths } from '../routing/segment-keys.ts';
+import { isRscRequest } from '../shared/rsc-media-type.ts';
+import { canonicalize } from './canonicalize.ts';
+import { parseClientStateTree } from './state-tree-diff.ts';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.ts';
 
 /**
  * Check if an intercepting route applies for this soft navigation.
@@ -150,3 +155,131 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   return pi === pathParts.length;
 }
+
+// ─── Pipeline Resolution ──────────────────────────────────────────────────
+
+/**
+ * Resolve which route renders a soft navigation that an intercepting route
+ * may claim. Returns the canonical match unchanged when no rewrite applies.
+ *
+ * Runs during route setup, so anything it throws is a `'setup'` outcome.
+ */
+export function resolveInterceptedRoute(
+  config: PipelineConfig,
+  req: Request,
+  canonicalPathname: string,
+  canonicalMatch: RouteMatch | null
+): { match: RouteMatch | null; interception?: InterceptionContext } {
+  const stripTrailingSlash = config.stripTrailingSlash ?? true;
+  let match = canonicalMatch;
+  let interception: InterceptionContext | undefined;
+
+  // Stage 2a: Intercepting route resolution (modal pattern).
+  // Only honored on RSC client-navigation requests (Accept: text/x-component)
+  // to prevent spoofing from plain HTML navigations or raw HTTP clients.
+  // The header value must be a valid relative pathname — reject schemes,
+  // authority, and control characters. Canonicalize before matching.
+  if (isRscRequest(req) && config.interceptionRewrites?.length) {
+    const rawSourceUrl = req.headers.get('X-Timber-URL');
+    const validatedSourceUrl = rawSourceUrl
+      ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
+      : null;
+    if (validatedSourceUrl) {
+      // The scope of an interception is the segment that owns the intercepting
+      // slot, so the guard asks whether the route the user is LEAVING renders
+      // that segment. Two independent answers to "what is on screen?", tried in
+      // order — deferred behind a thunk so neither runs unless a rewrite's
+      // target pattern matches.
+      //
+      // 1. What the client says it has mounted (X-Timber-State-Tree
+      //    `treePaths`). Authoritative about tree shape and nothing else.
+      // 2. What re-matching X-Timber-URL implies. Correct while the address bar
+      //    still holds the source page, which stops being true the moment a
+      //    modal is open — the address is then the *intercepted* URL and
+      //    re-matching it resolves through whichever group owns the canonical
+      //    page (TIM-1282).
+      //
+      // Neither is trusted: both are client-supplied, and satisfying the scope
+      // only selects which build-time rewrite applies. The rendered pathname is
+      // always the rewrite's own `interceptingPrefix`, the server re-derives the
+      // rendered chain from it below, and every access.ts runs regardless.
+      //
+      // They are handed over as two sets in that order rather than one union:
+      // each describes a single rendered chain, and only within one chain does
+      // "the deepest scope" name the innermost owner (TIM-1318). Unioned, a
+      // deeper scope from the address-implied canonical branch — which after
+      // (2) may be a route group the client never mounted — would outrank the
+      // owner actually on screen.
+      const resolveSourceScopes = () => {
+        const mounted = new Set(parseClientStateTree(req)?.treePaths ?? []);
+        const sourceRoute = config.matchRoute(validatedSourceUrl);
+        const addressed = new Set(sourceRoute ? computeSegmentTreePaths(sourceRoute.segments) : []);
+        const scopes = [mounted, addressed].filter((scope) => scope.size > 0);
+        // Neither channel produced a tree — no scope can contain anything, and
+        // an origin that matches no route is not a legitimate soft navigation.
+        return scopes.length > 0 ? scopes : null;
+      };
+      const rewrite = findInterceptionMatch(
+        canonicalPathname,
+        resolveSourceScopes,
+        config.interceptionRewrites
+      );
+      if (rewrite?.mode === 'children') {
+        // Sibling layout swap (TIM-1280). Nothing is re-matched: the resolver
+        // addresses the owner directory by tree path and returns the chain
+        // `[…owner ancestors, interceptingNode, …descendants]`, which renders
+        // as an ordinary route. `interception` stays unset — there is no slot
+        // to intercept into, and setting it would additionally arm the modal
+        // path for every slot in the tree we are about to render.
+        //
+        // A null here means the scope named nothing in this manifest, or no
+        // intercepting child matched the target. Both fall through to the
+        // canonical route, which is what a hard navigation renders.
+        const interceptedMatch = config.matchInterceptedRoute?.(
+          canonicalPathname,
+          rewrite.interceptingScope
+        );
+        if (interceptedMatch) match = interceptedMatch;
+      } else if (rewrite) {
+        const sourceMatch = config.matchRoute(rewrite.interceptingPrefix);
+        // The scope test above was about the route the user is LEAVING. The
+        // route we are about to render is a different one —
+        // `interceptingPrefix` is URL-derived, and route groups are
+        // URL-invisible, so `/` can resolve into a sibling group that does not
+        // own the slot. Rendering that would reproduce the TIM-1278 failure on
+        // a valid tree: the rewrite hijacks the navigation and no slot exists
+        // to render the intercepting page. Fall through to the canonical
+        // target route instead.
+        const rendersTheSlot =
+          sourceMatch !== null &&
+          computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope);
+        if (rendersTheSlot) {
+          match = sourceMatch;
+          interception = { targetPathname: canonicalPathname };
+        }
+      }
+    }
+  }
+
+  return { match, interception };
+}
+
+/**
+ * Validate and canonicalize the X-Timber-URL header value.
+ *
+ * Returns the canonical pathname if valid, or null if rejected:
+ * - Must start with '/' (relative pathname, no scheme/authority)
+ * - Must not contain control characters
+ * - Must pass canonicalization (no encoded separators, null bytes, etc.)
+ */
+function validateInterceptionHeader(raw: string, stripTrailingSlash: boolean): string | null {
+  if (!raw.startsWith('/')) return null;
+  if (raw.startsWith('//')) return null;
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) return null;
+  }
+  const result = canonicalize(raw, stripTrailingSlash);
+  if (!result.ok) return null;
+  return result.pathname;
+}