@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/server/pipeline-phases.ts

@@ -30,6 +30,8 @@ import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
 import { loadModule } from './safe-load.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
+import { computeSegmentTreePaths } from '../routing/segment-keys.js';
+import { parseClientStateTree } from './state-tree-diff.js';
 import { applyCookieJar, cloneWithMutableHeaders, type ProxyResolver } from './pipeline-helpers.js';
 import { coerceSegmentParams } from './param-coercion.js';
 import { outcomeToResponse, type PhaseOutcome } from './pipeline-outcome.js';
@@ -37,6 +39,7 @@ import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline
 import type { MetadataHandler, MetadataRoute, MiddlewareContext } from './types.js';
 import { swallow } from './logger.js';
 import { isDebug } from './debug.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 
 interface RenderContext {
   canonicalPathname: string;
@@ -293,17 +296,6 @@ export async function handleRequest(
         // outer Server-Timing writer can append without hitting an
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
-          if (method === 'HEAD') {
-            const headHeaders = new Headers(handlerResult.headers);
-            if (handlerResult.ok && !headHeaders.has('Cache-Control')) {
-              headHeaders.set('Cache-Control', 'public, max-age=14400, must-revalidate');
-            }
-            return new Response(null, {
-              status: handlerResult.status,
-              statusText: handlerResult.statusText,
-              headers: headHeaders,
-            });
-          }
           const res = cloneWithMutableHeaders(handlerResult);
           if (res.ok && !res.headers.has('Cache-Control')) {
             res.headers.set('Cache-Control', 'public, max-age=14400, must-revalidate');
@@ -376,8 +368,8 @@ export async function handleRequest(
   // deployment ID matches the current build. On mismatch, signal the
   // client to do a full page reload instead of returning an RSC payload
   // that references mismatched module IDs.
-  const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
-  if (isRscRequest) {
+  const isRsc = isRscRequest(req);
+  if (isRsc) {
     const skewCheck = checkVersionSkew(req);
     if (!skewCheck.ok) {
       const reloadHeaders = new Headers();
@@ -395,20 +387,81 @@ export async function handleRequest(
   // 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 && config.interceptionRewrites?.length) {
+  if (isRsc && config.interceptionRewrites?.length) {
     const rawSourceUrl = req.headers.get('X-Timber-URL');
     const validatedSourceUrl = rawSourceUrl
       ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
       : null;
     if (validatedSourceUrl) {
-      const intercepted = findInterceptionMatch(
+      // 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,
-        validatedSourceUrl,
+        resolveSourceScopes,
         config.interceptionRewrites
       );
-      if (intercepted) {
-        const sourceMatch = config.matchRoute(intercepted.sourcePathname);
-        if (sourceMatch) {
+      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 };
         }
@@ -459,7 +512,7 @@ export async function handleRequest(
     | { route?: unknown; page?: unknown }
     | undefined;
   const isApiRoute = leafSegment?.route && !leafSegment?.page;
-  if (config.earlyHints && !isRscRequest && !isApiRoute) {
+  if (config.earlyHints && !isRsc && !isApiRoute) {
     try {
       await config.earlyHints(match, req, responseHeaders);
     } catch (err) {
@@ -468,8 +521,8 @@ export async function handleRequest(
   }
 
   // Stage 2c: Param coercion (before middleware)
-  // Load params.ts modules from matched segments and coerce raw string
-  // params through defineSegmentParams codecs. Coercion failure → 404
+  // Coerce raw string params through the app/schema.ts codecs.
+  // Coercion failure → 404
   // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
   //
   // Snapshot raw params before coercion — slot resolution needs the
@@ -488,9 +541,8 @@ export async function handleRequest(
           `[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n` +
             `  Matched segments: ${segmentChain}\n` +
             `  Error: ${error.message}\n` +
-            `  This usually means a params.ts codec rejected the URL params.\n` +
-            `  Check that all fields in defineSegmentParams() are optional for params\n` +
-            `  that don't appear at every route depth (e.g. year, month, day).`
+            `  This usually means a codec in app/schema.ts rejected the URL value.\n` +
+            `  Check the codec for the bracket key of the segment named above.`
         );
       }
       // For API routes (route.ts), return a bare 404 — not an HTML page.

package/src/server/pipeline.ts

@@ -35,6 +35,9 @@ import { makeProxyResolver } from './pipeline-helpers.js';
 import { handleRequest, runProxyPhase } from './pipeline-phases.js';
 import { outcomeToResponse } from './pipeline-outcome.js';
 import { canonicalize } from './canonicalize.js';
+import { enforceRscCacheKey, hardenRscPayloadResponse } from './rsc-cache-key-guard.js';
+import { stripHeadBody } from './head-response.js';
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
 import { isDebug } from './debug.js';
 
 // ─── Route Match Result ────────────────────────────────────────────────────
@@ -142,6 +145,17 @@ export interface PipelineConfig {
    * See design/07-routing.md §"Intercepting Routes"
    */
   interceptionRewrites?: import('../routing/interception.js').InterceptionRewrite[];
+  /**
+   * Resolver for children-path interceptions — the sibling layout swap.
+   *
+   * Separate from `matchRoute` because it addresses the owner directory by
+   * tree path rather than by pathname, which needs the manifest tree itself.
+   * Omitting it disables the `'children'` interception shape and leaves the
+   * canonical route rendering, which is the fail-safe outcome.
+   *
+   * See design/07-routing.md §"Intercepting Routes"
+   */
+  matchInterceptedRoute?: import('./children-interception.js').InterceptedRouteMatcher;
   /**
    * Control Server-Timing header output.
    *
@@ -393,17 +407,30 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Vary: Accept — CDNs must cache HTML and RSC payload responses
-              // separately for the same URL. Without this, a shared cache may
-              // serve an RSC Flight payload to a browser expecting HTML (or
-              // vice versa). See GHSA-wfc6-r584-vfw7, design/13-security.md.
+              // Vary on exactly the headers the `_rsc` cache key hashes.
               //
-              // Vary: X-Timber-URL — intercepting route responses depend on
-              // the source URL, so caches must store them separately.
-              const varyTokens = ['Accept'];
-              if (config.interceptionRewrites?.length) {
-                varyTokens.push('X-Timber-URL');
-              }
+              // Those two mechanisms answer the same question — which request
+              // headers change this response — so they are the same list, not
+              // two lists that happen to agree. A separate hand-written list
+              // here drifted from `RSC_KEY_HEADERS` the moment the key set
+              // grew, and the drift is invisible: `Vary` is the *fallback*
+              // layer, used only when a cache omits the query from its key,
+              // which is precisely when nobody is watching (TIM-1268).
+              //
+              // Why any of it: without `Vary: Accept` a shared cache may serve
+              // an RSC Flight payload to a browser expecting HTML, or the
+              // reverse (GHSA-wfc6-r584-vfw7, design/13-security.md). The
+              // `_rsc` param puts that distinction in the URL, so correctness
+              // no longer *depends* on `Vary` — which is opt-in configuration
+              // on Cloudflare and CloudFront. `Vary` covers the requests that
+              // arrive without the param: a stripped query, a hand-rolled
+              // client.
+              //
+              // It costs no hit rate. Document requests send no `X-Timber-*`
+              // header at all, so they collapse to a single cache key; payload
+              // requests are already fragmented by these same values via the
+              // URL.
+              const varyTokens = [...RSC_KEY_HEADERS];
               const existingVary = result.headers.get('Vary');
               const existingTokens = existingVary
                 ? existingVary
@@ -419,6 +446,26 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
                 );
               }
 
+              // A request may only claim an `_rsc` cache key that matches its
+              // own headers. The key is predictable by design, so without this
+              // a caller could render its own variant under another client's
+              // key and have a shared cache store it there (TIM-1268).
+              await enforceRscCacheKey(canonicalReq, result);
+
+              // Flight payloads must never be sniffable into a renderable
+              // type — applied at this single exit so every producer is
+              // covered, not just the success path (TIM-1268).
+              hardenRscPayloadResponse(result);
+
+              // A HEAD response carries the headers its GET would produce and
+              // no content (RFC 9110 §9.3.2). Applied at this single exit so
+              // every response shape is covered — page render, API route,
+              // metadata route, deny page, error page, proxy short-circuit —
+              // rather than per-renderer, where it was missing for page
+              // renders entirely (TIM-1324). The render still runs: the
+              // headers have to be the ones a GET would have sent.
+              result = stripHeadBody(result, method);
+
               // Append Server-Timing header based on configured mode.
               // Header mutability is guaranteed by the producer-side clone
               // in `outcomeToResponse` and the metadata-route / auto-sitemap

package/src/server/prebuilt-runtime.ts

@@ -173,17 +173,17 @@ const registry = new Map<string, PrebuiltRegistration>();
  */
 function resolveKeyParams(store: {
   segmentParams?: Record<string, string | string[]>;
-  slotParamsMap?: Map<string, Record<string, string | string[]>>;
+  slotParams?: Record<string, Record<string, string | string[]>>;
 }): Record<string, string | string[]> | null {
   const main = store.segmentParams ?? {};
-  const map = store.slotParamsMap;
-  if (!map || map.size === 0) return main;
+  const slots = store.slotParams;
+  if (!slots || Object.keys(slots).length === 0) return main;
   // Spread before canonicalizing: param records are framework-produced
   // Object.create(null) objects (prototype-pollution defense) — normalize
   // the records themselves, let nested values face the full allowlist.
   const mainCanonical = tryCanonicalize({ ...main });
   if (mainCanonical === null) return null;
-  for (const slotParams of map.values()) {
+  for (const slotParams of Object.values(slots)) {
     const merged = tryCanonicalize({ ...main, ...slotParams });
     if (merged === null || merged !== mainCanonical) return null;
   }

package/src/server/primitives.ts

@@ -113,6 +113,31 @@ export class DenySignal extends Error {
   readonly status: number;
   readonly data: JsonSerializable | undefined;
 
+  /**
+   * Segment key of the segment that owns the deny page matched for this
+   * signal — set by a framework catch site that matched an entry it may not
+   * render at its own position, and re-threw so the boundary at the owning
+   * segment renders it instead.
+   *
+   * Written only by the three in-tree catch sites (`PageDenyBoundary`,
+   * `TracedLayout`, `AccessGate`), never by user code. Two readers depend on
+   * it: `TimberErrorBoundary`, which declines any deny whose `ownerKey` is
+   * not its own `segmentKey`, and `buildRscPayloadResponse`, which keeps
+   * streaming instead of re-rendering when it is set.
+   *
+   * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+   */
+  ownerKey?: string;
+
+  /**
+   * When true, the pipeline must respond with `rscErrorEnvelope` so the
+   * client hard-navigates instead of attempting to render a deny page
+   * from the RSC payload. Set by AccessGate when a skipped segment
+   * denies — rendering the deny page in-tree would appear inside the
+   * client's cached layout chrome (TIM-1074). See TIM-1363.
+   */
+  _hardNavigate?: boolean;
+
   constructor(status: number, data?: JsonSerializable) {
     super(`Access denied with status ${status}`);
     this.name = 'DenySignal';

package/src/server/publish-params.ts

@@ -0,0 +1,42 @@
+/**
+ * Publishing the request's params onto the RSC payload.
+ *
+ * Every tree the server sends the browser goes through here: the ordinary
+ * route payload (`route-element-builder.ts`), both deny renderers
+ * (`deny-renderer.ts`) and the error renderer. One helper rather than a wrap
+ * at each site, because these previously *were* separate sites — a response
+ * header, an inline script, and a second copy of each on the deny path — and
+ * the deny path shipping empty params was the bug that came of it (TIM-1285).
+ *
+ * Reads the request store rather than taking params as an argument, so a
+ * caller cannot pass a different record than the one the request rendered
+ * with. See design/41-global-params.md §"Transport".
+ */
+
+import { toPlainRecord } from '../shared/param-value.js';
+import type { RscPayloadRoot } from '../shared/payload-root.js';
+import { getSegmentParamsForClient, getSlotParamsForClient } from './request-context.js';
+
+/**
+ * Build the payload root: the tree, and the params it rendered with beside it.
+ *
+ * The params are a *sibling* of the tree, not a provider around it. A provider
+ * inside the payload is shadowed by the retained tree's own provider on a
+ * partial navigation, and its props are not readable at the instant the root
+ * row resolves — see `shared/payload-root.ts` for both, and TIM-1297. The
+ * client renders the one provider readers see, above the merge point.
+ *
+ * The records are flattened to plain objects on the way out. Every param
+ * record the framework builds is `Object.create(null)` (design/13-security.md
+ * #36b/#36c), and React Flight rejects a null prototype — "Classes or null
+ * prototypes are not supported". `ParamsProvider` restores the prototype on
+ * the other side, so what the app reads is unchanged; only the wire
+ * representation differs.
+ */
+export function withPublishedParams(element: React.ReactElement): RscPayloadRoot {
+  return {
+    tree: element,
+    params: toPlainRecord(getSegmentParamsForClient()),
+    slotParams: toPlainRecord(getSlotParamsForClient() ?? null),
+  };
+}

package/src/server/request-context.ts

@@ -15,9 +15,14 @@
  */
 
 import { requestContextAls, type RequestContextStore } from './als-registry.js';
-import { _setGetSearchParamsFn } from '../search-params/define.js';
-import { _setGetSegmentParamsFn } from '../segment-params/define.js';
+import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.js';
 import { consumeSeededCookies } from './cookie-context.js';
+import { appVisibleSearch } from '../shared/rsc-cache-key.js';
+import {
+  mergeSlotParams,
+  resolveSegmentParams,
+  type SlotParamsRecord,
+} from '../shared/slot-params.js';
 import { isDebug } from './debug.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
@@ -111,17 +116,13 @@ export function getSegmentParams(segmentPath?: string): Record<string, string |
     );
   }
 
-  // Check slot params map first — parallel slots may have different param
-  // types than the main route (e.g. catch-all [..year] → string[] vs
-  // dynamic [year] → string). If the requested segment path matches a
-  // stored slot, return its params merged with the main route's.
-  if (segmentPath && store.slotParamsMap?.has(segmentPath)) {
-    const slotParams = store.slotParamsMap.get(segmentPath)!;
-    // Merge: main params as base, slot-specific params override.
-    // This ensures params from segments above the slot (that the slot
-    // doesn't re-derive) are still available.
-    return { ...store.segmentParams, ...slotParams };
-  }
+  // Parallel slots may derive a param the main route never had, or the same
+  // name with a different type (catch-all [...year] → string[] vs dynamic
+  // [year] → string). `resolveSegmentParams` is the shared definition the
+  // client's useSegmentParams() also reads, so the two halves of one
+  // documented API cannot drift (TIM-1285).
+  const slotResolved = resolveSegmentParams(store.segmentParams, store.slotParams, segmentPath);
+  if (slotResolved !== store.segmentParams) return slotResolved;
 
   // Dev-mode validation: warn when the segment path expects dynamic
   // segments that don't exist on the actual matched segment. This catches
@@ -173,8 +174,82 @@ export function setSlotParams(
 ): void {
   const store = requestContextAls.getStore();
   if (!store) return; // non-throwing — optional diagnostic
-  if (!store.slotParamsMap) store.slotParamsMap = new Map();
-  store.slotParamsMap.set(segmentPath, params);
+  if (!store.slotParams) store.slotParams = Object.create(null) as SlotParamsRecord;
+  store.slotParams[segmentPath] = params;
+}
+
+/**
+ * Run `fn` with the segment params a parallel slot's own chain produced, so
+ * a no-arg `getSegmentParams()` inside that slot returns the slot's params
+ * rather than the main route's.
+ *
+ * ALS is the only channel available: the slot's page and layouts are plain
+ * components that receive no params prop and cannot know their own tree
+ * path, so they have no way to ask for the keyed overload. The slot resolver
+ * invokes each of them itself (page through `SafeSlotPage`, layouts and
+ * access functions through their wrappers), and this scopes those calls.
+ *
+ * The store is wrapped in a Proxy rather than cloned. Everything a slot
+ * renders can write to the *live* request store — `setDenyStatus` from an
+ * access gate, cookie writes, the flush flag — and a clone would silently
+ * strand those writes in a copy the pipeline never reads. Only the two
+ * params fields are shadowed; every other read and every write passes
+ * straight through to the real store.
+ *
+ * Returns `fn()`'s result unchanged, and no-ops outside a request context or
+ * before route matching has set the main params. See TIM-1283.
+ *
+ * @internal — framework use only
+ */
+export function runWithSlotSegmentParams<T>(
+  slotSegmentPath: string | undefined,
+  slotParams: Record<string, string | string[]>,
+  fn: () => T
+): T {
+  const store = requestContextAls.getStore();
+  if (!store?.segmentParams) return fn();
+
+  const merged = mergeSlotParams(store.segmentParams, slotParams);
+  const matchedSegmentPath = slotSegmentPath ?? store.matchedSegmentPath;
+  const scoped = new Proxy(store, {
+    get(target, prop, receiver) {
+      if (prop === 'segmentParams') return merged;
+      if (prop === 'matchedSegmentPath') return matchedSegmentPath;
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  return requestContextAls.run(scoped, fn);
+}
+
+/**
+ * The main route's coerced params, or an empty record before route matching.
+ *
+ * Non-throwing, unlike `getSegmentParams()`: the deny payload path publishes
+ * params from wherever the pipeline happened to fail, which may be before
+ * matching completed.
+ *
+ * @internal — framework use only. See TIM-1285.
+ */
+export function getSegmentParamsForClient(): Record<string, string | string[]> {
+  return requestContextAls.getStore()?.segmentParams ?? {};
+}
+
+/**
+ * The per-slot params to publish to the client, or `undefined` when the
+ * request rendered no slot with params of its own.
+ *
+ * The client cannot derive these: a slot matches the URL through its own
+ * sub-tree, and the browser only ever sees the main route's record. Reading
+ * the map here — rather than threading it back out of the element builder —
+ * keeps one producer, since `setSlotParams` already writes it during slot
+ * resolution and every serialization site runs after that completes.
+ *
+ * @internal — framework use only. See TIM-1285.
+ */
+export function getSlotParamsForClient(): SlotParamsRecord | undefined {
+  const store = requestContextAls.getStore();
+  if (!store?.slotParams) return undefined;
+  return Object.keys(store.slotParams).length > 0 ? store.slotParams : undefined;
 }
 
 /**
@@ -247,7 +322,7 @@ export type ReadonlyHeaders = Pick<
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
-  const parsedUrl = new URL(req.url);
+  const appVisible = appVisibleSearch(new URL(req.url));
   const seed = consumeSeededCookies(req);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
@@ -257,8 +332,12 @@ export function runWithRequestContext<T>(req: Request, fn: () => T): T {
     // gated on `parsedCookies` being undefined.
     cookieHeader: seed ? '' : (req.headers.get('cookie') ?? ''),
     parsedCookies: seed,
-    searchParams: parsedUrl.searchParams,
-    searchString: parsedUrl.search,
+    // Not `parsedUrl.searchParams` / `parsedUrl.search`: this store is what
+    // `getSearchParams()` and `redirect({ preserveSearchParams })` read, and
+    // the RSC payload URL carries the framework's `_rsc` cache key that no
+    // other request has (TIM-1272).
+    searchParams: appVisible.params,
+    searchString: appVisible.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,