@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/rsc-cache-key-guard.ts

@@ -0,0 +1,164 @@
+/**
+ * Origin-side binding of the `_rsc` cache key to the request that produced
+ * the response (TIM-1268).
+ *
+ * The key is deterministic, and deliberately so — that is what makes RSC
+ * payloads cacheable. But deterministic also means *predictable*: anyone can
+ * compute the key another client will request. Without this guard, a caller
+ * could request `/about?_rsc=<victim's key>` while sending its own
+ * `X-Timber-State-Tree`, and a shared cache that keys by URL — the exact
+ * environment this feature targets — would store that variant under the
+ * victim's key. Every subsequent legitimate navigation would then be served
+ * a payload rendered for someone else's segment tree or deployment.
+ *
+ * The guard is a *storability* rule, not a rejection: if the claimed key
+ * does not match the key derived from the received headers, the response
+ * loses its shared-cache directives. Mismatched requests are still served
+ * normally, they just cannot be stored for anyone else.
+ *
+ * Why not Next.js's 307 self-correction: a redirect is cacheable in its own
+ * right, costs a round trip on every legitimate miss, and would make the
+ * server's behaviour depend on a parameter it otherwise never reads. This
+ * rule closes the same hole by making the poisoned entry unstorable at the
+ * source, in the response the developer already has to opt into sharing.
+ *
+ * See design/19-client-navigation.md §"The `_rsc` cache key".
+ */
+
+import { rscCacheKey, isRscCacheKeyShape, RSC_KEY_PARAM } from '../shared/rsc-cache-key.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+
+/**
+ * Legacy shared-cache control fields that predate RFC 9213 and so do not
+ * follow the `<target>-Cache-Control` naming pattern — the one part of this
+ * rule that cannot be matched by shape. `X-Accel-Expires` is nginx
+ * `proxy_cache`, which gives it precedence over `Cache-Control`.
+ *
+ * A closed historical set, unlike the vendor `*-Cache-Control` names, which
+ * keep being minted and are handled by pattern below.
+ */
+const LEGACY_CDN_CACHE_HEADERS = ['Surrogate-Control', 'Edge-Control', 'X-Accel-Expires'];
+
+/**
+ * Whether a response header overrides `Cache-Control` at a shared cache.
+ *
+ * Matched by *shape*, not by vendor name. RFC 9213 defines targeted fields
+ * as `<target>-Cache-Control`, and every CDN spells its own: `CDN-`,
+ * `Cloudflare-CDN-`, `Netlify-CDN-`, `Vercel-CDN-`, and whichever ships
+ * next. A vendor list here is a denylist with an unbounded tail — it was
+ * extended twice during review, each time by one name, which is the signal
+ * that enumeration is the wrong shape. The suffix rule is total.
+ *
+ * `Cache-Control` itself does not match (no `-` prefix) and is replaced
+ * separately.
+ */
+function isSharedCacheOverride(name: string): boolean {
+  const lowered = name.toLowerCase();
+  return (
+    lowered.endsWith('-cache-control') ||
+    LEGACY_CDN_CACHE_HEADERS.some((legacy) => legacy.toLowerCase() === lowered)
+  );
+}
+
+/**
+ * Whether the request's `_rsc` parameter matches the key derived from its
+ * own headers.
+ *
+ * Requests without the parameter are not claiming a key at all, so they are
+ * left alone — the bare document URL is the developer's declared territory
+ * (see design/32-response-caching.md, TIM-1264). Neither is a parameter
+ * whose value could not be one of our digests: `_rsc` is not reserved, and
+ * an application that already uses it for its own search state
+ * (`/search?_rsc=foo`) must not have its cache policy silently revoked by a
+ * guard that mistook that for a forgery.
+ */
+export async function hasValidRscCacheKey(req: Request): Promise<boolean> {
+  // Fast path: this runs on every request, and the overwhelming majority
+  // (document requests) have no query string at all. Keyed on `?` and not
+  // on the literal `_rsc=`, because a substring test is not a parse: a
+  // request for `?%5Frsc=<key>` carries no literal `_rsc=`, yet
+  // `URLSearchParams` decodes it to one — and a cache that canonicalizes
+  // percent-encoded unreserved characters in its key while forwarding the
+  // original URL would store the response under the decoded, claimed key.
+  // The only sound fast path is one that cannot answer "no key" wrongly.
+  if (!req.url.includes('?')) return true;
+  let values: string[];
+  try {
+    values = new URL(req.url).searchParams.getAll(RSC_KEY_PARAM);
+  } catch {
+    // Unparseable URL — nothing to validate, and nothing safe to assume.
+    return false;
+  }
+  // Every value, not the first. An application that owns `_rsc` for its own
+  // search state makes the client emit `?_rsc=foo&_rsc=<key>` — reading only
+  // the first would see `foo`, exempt it as application data, and never
+  // check the real key sitting beside it.
+  const claims = values.filter(isRscCacheKeyShape);
+  if (claims.length === 0) return true;
+  const expected = await rscCacheKey((name) => req.headers.get(name));
+  // No digest available means the claim is unverifiable, which is not the
+  // same as verified. Every server runtime timber targets has
+  // `crypto.subtle`, so this is a guard against a future one that does not.
+  if (expected === null) return false;
+  // All of them, because at most one can be legitimate and a cache keys on
+  // the whole query string — a second, mismatched key would ride along
+  // inside an address that otherwise looks validated.
+  return claims.every((claim) => claim === expected);
+}
+
+/**
+ * Ensure a Flight payload can never be interpreted as a document.
+ *
+ * Applied here, at the pipeline's single exit, rather than where each
+ * payload response is built. Six places build one — the success path, three
+ * in `deny-renderer.ts`, the action paths — and hardening them one at a time
+ * is how you end up hardening five of six. The response is Flight if it says
+ * it is; that is the only test that covers every producer, including ones
+ * added later.
+ *
+ * Matters because the payload URL is observable and, on a shared-cache hit,
+ * the origin is never consulted — so a top-level navigation can be handed
+ * these bytes with no request-time check available. See design/13-security.md
+ * #36c.
+ */
+export function hardenRscPayloadResponse(response: Response): void {
+  const contentType = response.headers.get('content-type');
+  if (!contentType) return;
+  if (contentType.split(';')[0].trim().toLowerCase() !== RSC_CONTENT_TYPE) return;
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+}
+
+/**
+ * Make a response unstorable by any shared cache when its request claimed an
+ * `_rsc` key that does not match its own headers.
+ *
+ * The end state is unconditional and therefore statable: **a mismatched
+ * response is never stored by any cache.** Every targeted cache-control
+ * field is removed and `Cache-Control` is replaced outright, rather than
+ * downgrading only when a shared directive is spotted. Conditional variants
+ * of this were tried and were wrong twice over — they missed the CDN-
+ * specific headers, and leaving `Cache-Control` alone when it looked
+ * harmless lets a CDN apply heuristic caching to a response that has none.
+ *
+ * The cost is that a mismatched request loses developer-chosen *browser*
+ * caching too. That is a request no timber client ever makes.
+ *
+ * Purge tags (`Surrogate-Key`, `Cache-Tag`) are deliberately left alone:
+ * they address stored entries, and this response is not stored.
+ *
+ * Mutates `response.headers` in place; the pipeline guarantees mutable
+ * headers at this point (see TIM-866).
+ */
+export async function enforceRscCacheKey(req: Request, response: Response): Promise<void> {
+  if (await hasValidRscCacheKey(req)) return;
+  // Collected before deleting — mutating Headers while iterating its live
+  // key iterator can skip entries.
+  const overrides: string[] = [];
+  for (const name of response.headers.keys()) {
+    if (isSharedCacheOverride(name)) overrides.push(name);
+  }
+  for (const name of overrides) {
+    response.headers.delete(name);
+  }
+  response.headers.set('Cache-Control', 'private, no-store');
+}

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -0,0 +1,167 @@
+/**
+ * Middleware runner for revalidation — runs a route's `middleware.ts`
+ * chain inside its own `runWithRequestContext` scope and returns a
+ * `MiddlewareOutcome` value the caller can translate.
+ *
+ * Used by the revalidation renderer (TIM-996) to run the TARGET route's
+ * middleware before building the revalidated element tree, ensuring that
+ * `revalidatePath('/admin')` from a public action honors admin's auth.
+ *
+ * NOT used for action dispatch itself — per-segment middleware does not
+ * run on action POSTs (TIM-1134). Actions are dispatched by action ID,
+ * not route segment, so `proxy.ts` and `createActionClient({ middleware })`
+ * are the correct auth mechanisms.
+ *
+ * The function is intentionally a free function (not a closure over deps)
+ * so it can be unit-tested in isolation. Failure modes are encoded as
+ * outcome variants rather than thrown so the caller never has to wrap
+ * this in try/catch.
+ */
+
+import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.js';
+import {
+  applyRequestHeaderOverlay,
+  runWithRequestContext,
+  setMutableCookieContext,
+  setSegmentParams,
+} from '../request-context.js';
+import { runMiddlewareChain } from '../middleware-runner.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { ParamCoercionError } from '../route-element-builder.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { MiddlewareContext } from '../types.js';
+
+/** Coerce a matched route's segment params via its `params.ts` codecs. */
+export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;
+
+/**
+ * Outcome of running middleware on an action request, surfaced from the
+ * inner `runWithRequestContext` scope so the outer dispatcher can convert
+ * it to a Response (short-circuit) or continue to the action handler.
+ *
+ * Each variant carries the post-middleware Set-Cookie snapshot so the
+ * outer scope can apply cookies to whichever Response it ultimately
+ * returns. The middleware ALS scope ends before the action ALS scope
+ * begins, so cookie state must be threaded explicitly across the boundary
+ * via `seedRequestCookies` (cookie reads) and `setCookieHeaders` (cookie
+ * writes).
+ */
+export type MiddlewareOutcome =
+  | {
+      kind: 'continue';
+      overlay: Headers;
+      cookies: Map<string, string>;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'short-circuit';
+      response: Response;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'redirect';
+      signal: RedirectSignal;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'deny';
+      signal: DenySignal;
+      match: RouteMatch;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'param-coercion-error';
+    }
+  | {
+      kind: 'error';
+      error: unknown;
+    };
+
+/**
+ * Run the matched route's middleware chain inside a fresh request-context
+ * scope, captured as a `MiddlewareOutcome` value the outer dispatcher can
+ * translate to a Response or use as the seed for the action handler.
+ */
+export async function runMiddlewareForAction(
+  req: Request,
+  match: RouteMatch,
+  coerceSegmentParams: CoerceSegmentParamsFn
+): Promise<MiddlewareOutcome> {
+  return runWithRequestContext(req, async (): Promise<MiddlewareOutcome> => {
+    // ─── Coerce segment params (mirrors page pipeline) ──────────────
+    try {
+      await coerceSegmentParams(match);
+    } catch (err) {
+      if (err instanceof ParamCoercionError) {
+        return { kind: 'param-coercion-error' };
+      }
+      return { kind: 'error', error: err };
+    }
+    setSegmentParams(match.segmentParams);
+
+    // ─── Build the middleware context ───────────────────────────────
+    const responseHeaders = new Headers();
+    const requestHeaderOverlay = new Headers();
+    const ctx: MiddlewareContext = {
+      req,
+      requestHeaders: requestHeaderOverlay,
+      headers: responseHeaders,
+      segmentParams: match.segmentParams,
+      // 103 Early Hints are a page-render concern — server actions are
+      // RPC and never produce HTML, so there is nothing to hint about.
+      // Provide a no-op so user middleware can call `ctx.earlyHints()`
+      // unconditionally without branching on request kind.
+      earlyHints: () => {},
+    };
+
+    // ─── Run the chain ──────────────────────────────────────────────
+    setMutableCookieContext(true);
+    try {
+      let middlewareResponse: Response | undefined;
+      try {
+        middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+      } catch (err) {
+        if (err instanceof RedirectSignal) {
+          return {
+            kind: 'redirect',
+            signal: err,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        if (err instanceof DenySignal) {
+          return {
+            kind: 'deny',
+            signal: err,
+            match,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        return { kind: 'error', error: err };
+      }
+
+      if (middlewareResponse) {
+        return {
+          kind: 'short-circuit',
+          response: middlewareResponse,
+          setCookieHeaders: getSetCookieHeaders(),
+        };
+      }
+
+      // Middleware passed — apply the request-header overlay to the
+      // current scope so any code that might still read it within
+      // this scope sees the merged view. The overlay is also captured
+      // in the outcome so the caller can re-apply it inside the
+      // action's request-context scope (which is a separate ALS run).
+      applyRequestHeaderOverlay(requestHeaderOverlay);
+
+      return {
+        kind: 'continue',
+        overlay: requestHeaderOverlay,
+        cookies: getCookiesForSsr(),
+        setCookieHeaders: getSetCookieHeaders(),
+      };
+    } finally {
+      setMutableCookieContext(false);
+    }
+  });
+}

package/src/server/rsc-entry/api-handler.ts

@@ -6,17 +6,27 @@
  * See design/04-authorization.md §"Auth in API Routes".
  */
 
-import { withSpan, setSpanAttribute } from '#/server/tracing.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { handleRouteRequest } from '#/server/route-handler.js';
-import type { RouteModule } from '#/server/route-handler.js';
-import type { RouteContext } from '#/server/types.js';
+import { withSpan, setSpanAttribute } from '../tracing.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { loadModule } from '../safe-load.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { handleRouteRequest } from '../route-handler.js';
+import { stripHeadBody } from '../head-response.js';
+import type { RouteModule } from '../route-handler.js';
+import type { RouteContext } from '../types.js';
 
+/**
+ * Handle a `route.ts` request.
+ *
+ * Segment-param coercion has already run (in pipeline-phases.ts), and the
+ * coerced values + raw URLSearchParams are seeded into the request-context
+ * ALS — so `segmentParams.get()` / `searchParams.get()` work inside
+ * `middleware.ts`, `access.ts`, and the HTTP method handler. This function
+ * only runs the access chain and dispatches; it does not duplicate the
+ * coercion or ALS setup the pipeline already performed.
+ */
 export async function handleApiRoute(
   req: Request,
-  match: RouteMatch,
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
@@ -26,10 +36,8 @@ export async function handleApiRoute(
   // Each access.ts is independent — deny()/redirect() throws a signal.
   for (const segment of segments) {
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
         try {
           await withSpan(
@@ -37,7 +45,7 @@ export async function handleApiRoute(
             { 'timber.segment': segment.segmentName ?? 'unknown' },
             async () => {
               try {
-                await accessFn({ params: match.params, searchParams: {} });
+                await accessFn();
                 await setSpanAttribute('timber.result', 'pass');
               } catch (error) {
                 if (error instanceof DenySignal) {
@@ -54,28 +62,55 @@ export async function handleApiRoute(
             }
           );
         } catch (error) {
-          if (error instanceof DenySignal) {
-            return renderApiDeny(error, segments, responseHeaders);
-          }
-          if (error instanceof RedirectSignal) {
-            responseHeaders.set('Location', error.location);
-            return new Response(null, { status: error.status, headers: responseHeaders });
-          }
+          const signalResponse = await translateApiSignal(error, req, segments, responseHeaders);
+          if (signalResponse) return signalResponse;
           throw error;
         }
       }
     }
   }
 
-  // Load route.ts module and dispatch
-  const routeMod = (await leaf.route!.load()) as RouteModule;
-  const ctx: RouteContext = {
-    req,
-    params: match.params,
-    searchParams: new URL(req.url).searchParams,
-    headers: responseHeaders,
-  };
-  return handleRouteRequest(routeMod, ctx);
+  // Load route.ts module and dispatch.
+  // Segment params / query params are NOT on `ctx` — handlers read them
+  // through `segmentParams.get()` / `searchParams.get()`, which pull from
+  // the request-context ALS that the pipeline already populated.
+  const routeMod = await loadModule<RouteModule>(leaf.route!);
+  const ctx: RouteContext = { req, headers: responseHeaders };
+  try {
+    return await handleRouteRequest(routeMod, ctx);
+  } catch (error) {
+    const signalResponse = await translateApiSignal(error, req, segments, responseHeaders);
+    if (signalResponse) return signalResponse;
+    throw error;
+  }
+}
+
+/**
+ * Translate a control-flow signal thrown from access.ts or a route.ts
+ * method handler into the proper API response: DenySignal → JSON status-file
+ * chain via `renderApiDeny`, RedirectSignal → bare 3xx with Location header.
+ *
+ * For HEAD requests, strip the deny body to preserve HEAD semantics — signals
+ * bypass the HEAD path in `handleRouteRequest`, so this exit needs its own
+ * call. Shares `stripHeadBody` with that path and with the pipeline exit; the
+ * pipeline applying it again downstream is a no-op (TIM-1324).
+ *
+ * Returns `null` for non-signal errors so the caller knows to rethrow.
+ */
+async function translateApiSignal(
+  error: unknown,
+  req: Request,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers
+): Promise<Response | null> {
+  if (error instanceof DenySignal) {
+    return stripHeadBody(await renderApiDeny(error, segments, responseHeaders), req.method);
+  }
+  if (error instanceof RedirectSignal) {
+    responseHeaders.set('Location', error.location);
+    return new Response(null, { status: error.status, headers: responseHeaders });
+  }
+  return null;
 }
 
 /**
@@ -90,11 +125,11 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveManifestStatusFile } = await import('#/server/manifest-status-resolver.js');
+  const { resolveStatusFile } = await import('../status-code-resolver.js');
 
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
   if (resolution) {
-    const mod = (await resolution.file.load()) as Record<string, unknown>;
+    const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;
     responseHeaders.set('content-type', 'application/json; charset=utf-8');
     return new Response(JSON.stringify(jsonContent), {

package/src/server/rsc-entry/deny-fallback.ts

@@ -0,0 +1,93 @@
+/**
+ * Deny fallback renderer — renders the deny page (403.tsx, 404.tsx, etc.)
+ * for DenySignals that escape from middleware or the render phase.
+ *
+ * Extracted from index.ts (TIM-968) as a pure move. The factory captures
+ * the root segment and client bootstrap config once at handler creation;
+ * the returned function is wired into `PipelineConfig.renderDenyFallback`
+ * and reused by the action-dispatch wrapper.
+ *
+ * Design docs: 04-authorization.md, 10-error-handling.md
+ */
+
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { ClientBootstrapConfig } from '../html-injectors.js';
+import { logRenderError } from '../logger.js';
+import type { PipelineConfig, RouteMatch } from '../pipeline.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { loadModule } from '../safe-load.js';
+import { createDebugChannelSink } from './helpers.js';
+import { isRscRequest } from '../../shared/rsc-media-type.js';
+import { callSsr } from './ssr-bridge.js';
+
+/**
+ * Create the pipeline's deny fallback renderer.
+ *
+ * When the pipeline already matched a route (the common case — matching
+ * runs before middleware and rendering), resolve the status file against
+ * the matched chain so colocated files like a nested `403.tsx` or an API
+ * route's `401.json` are picked up. Fall back to the root chain when no
+ * match is available (e.g. proxy-stage deny before route matching).
+ * See TIM-822, design/04-authorization.md, design/10-error-handling.md.
+ */
+export function createDenyFallbackRenderer(options: {
+  rootSegment: ManifestSegmentNode;
+  clientBootstrap: ClientBootstrapConfig;
+}): NonNullable<PipelineConfig['renderDenyFallback']> {
+  const { rootSegment, clientBootstrap } = options;
+  return async (deny, req, responseHeaders, matchedRoute) => {
+    const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [rootSegment];
+    const layoutComponents: LayoutEntry[] = [];
+    try {
+      for (const segment of chain) {
+        if (!segment.layout) continue;
+        const mod = await loadModule(segment.layout);
+        if (mod.default) {
+          layoutComponents.push({
+            component: mod.default as (...args: unknown[]) => unknown,
+            segment,
+          });
+        }
+      }
+    } catch (layoutError) {
+      // Layout failed to load — proceed without it. Partial layout chains
+      // are acceptable; the deny renderer wraps in whatever loaded.
+      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
+    }
+    // Reuse the matched route's params/middleware metadata when present so
+    // downstream rendering sees the real route shape. Otherwise synthesise
+    // a root-only stub (no params, no middleware).
+    const match: RouteMatch = matchedRoute ?? {
+      segments: chain,
+      segmentParams: {},
+      middlewareChain: [],
+    };
+    // For client navigation (Accept: text/x-component), the timber router
+    // decodes the response as React Flight. Returning HTML to a Flight
+    // decoder breaks navigation, so dispatch to the RSC renderer when the
+    // request is an RSC payload request — mirroring the normal render path.
+    // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
+    if (isRscRequest(req)) {
+      return renderDenyPageAsRsc(
+        deny,
+        chain,
+        layoutComponents,
+        req,
+        responseHeaders,
+        createDebugChannelSink
+      );
+    }
+    return renderDenyPage(
+      deny,
+      chain,
+      layoutComponents,
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      createDebugChannelSink,
+      callSsr
+    );
+  };
+}