@timber-js/app 0.2.0-alpha.96 → 0.2.0-alpha.98

package/src/server/rsc-entry/wrap-action-dispatch.ts

@@ -0,0 +1,156 @@
+/**
+ * Action-dispatch wrapper around the route pipeline.
+ *
+ * Extracted from rsc-entry/index.ts so the wiring can be unit-tested in
+ * isolation from Vite's virtual modules. The wrapper is responsible for
+ * three things, in order:
+ *
+ *   1. **Pipeline-boundary CSRF validation** — runs on EVERY unsafe-method
+ *      request, before any dispatch decision. This is the only line of
+ *      defense for `route.ts` API handlers, which never see the action
+ *      handler. See LOCAL-773.
+ *
+ *   2. **Server action interception** — POST requests carrying an
+ *      `x-rsc-action` header or React's `$ACTION_REF` form fields are
+ *      handed to `handleActionRequest`, which executes the action and
+ *      returns either an RSC response or a no-JS rerender signal.
+ *
+ *   3. **No-JS validation rerender** — when an action returns flash data
+ *      instead of a redirect, the wrapper re-runs the page render via the
+ *      pipeline with the post-action cookie state and `runWithFormFlash`
+ *      so server components can read the flash. See TIM-836 / TIM-837.
+ *
+ * Anything else falls through to `pipeline(req)` for normal route handling.
+ *
+ * The wrapper takes its dependencies as parameters (no module-level
+ * imports of virtual modules) so tests can construct it with stub
+ * pipelines and stub revalidate renderers.
+ */
+
+import type { FormRerender } from '../action-handler.js';
+import { handleActionRequest, isActionRequest } from '../action-handler.js';
+import type { BodyLimitsConfig } from '../body-limits.js';
+import { validateCsrf, type CsrfConfig } from '../csrf.js';
+import { runWithFormFlash } from '../form-flash.js';
+import type { SensitiveFieldsOption } from '../sensitive-fields.js';
+import type { RevalidateRenderer } from '../actions.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a `RevalidateRenderer` for a specific request.
+ *
+ * The renderer needs to forward cookies/headers from the originating
+ * request when fetching the revalidated route. We pass the request in
+ * via a builder so the wrapper doesn't need to know about route matching,
+ * segment param coercion, or element building — those concerns stay in
+ * `rsc-entry/index.ts`.
+ */
+export type RevalidateRendererFactory = (req: Request) => RevalidateRenderer;
+
+/** Dependencies for the action-dispatch wrapper. */
+export interface ActionDispatchDeps {
+  /** CSRF configuration (Origin allow-list, on/off switch). */
+  csrfConfig: CsrfConfig;
+  /** Body size limits forwarded to `handleActionRequest`. */
+  bodyLimits?: BodyLimitsConfig['limits'];
+  /** Sensitive-field deny-list forwarded to `handleActionRequest`. */
+  sensitiveFields?: SensitiveFieldsOption;
+  /** Per-request factory that builds a `RevalidateRenderer`. */
+  buildRevalidateRenderer: RevalidateRendererFactory;
+}
+
+// ─── Implementation ───────────────────────────────────────────────────────
+
+/**
+ * Wrap a pipeline function with CSRF validation and server-action dispatch.
+ *
+ * The returned handler is the framework's outermost request entry point.
+ * Its responsibilities, in order:
+ *
+ *   1. CSRF (Origin/Host) validation on every unsafe-method request.
+ *      Safe methods (GET/HEAD/OPTIONS) short-circuit inside `validateCsrf`,
+ *      so this is a no-op for reads.
+ *   2. Server-action interception for POSTs that match `isActionRequest`.
+ *   3. No-JS validation rerender when an action returns a `FormRerender`
+ *      signal instead of a redirect.
+ *   4. Otherwise, delegate to `pipeline(req)`.
+ *
+ * The duplicate `validateCsrf` call inside `handleActionRequest` is left in
+ * place as defense-in-depth (no-op on the happy path) so the action handler
+ * remains safe to call from any future entry point that bypasses this
+ * wrapper. See LOCAL-773.
+ */
+export function wrapPipelineWithActionDispatch(
+  pipeline: (req: Request) => Promise<Response>,
+  deps: ActionDispatchDeps
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    // ─── 1. Pipeline-boundary CSRF validation (LOCAL-773) ─────────────
+    //
+    // Runs on EVERY unsafe-method request, before any dispatch decision.
+    // Without this, `route.ts` PUT/PATCH/DELETE handlers and POSTs with
+    // `Content-Type: application/json` or `text/plain` would reach the
+    // route handler with no Origin check at all — `isActionRequest` only
+    // matches POST + form/multipart/x-rsc-action.
+    //
+    // `text/plain` POST is a CORS-simple request, so a cross-site
+    // `<form enctype="text/plain">` submission carries `SameSite=Lax`
+    // cookies (the framework's own default).
+    const csrfResult = validateCsrf(req, deps.csrfConfig);
+    if (!csrfResult.ok) {
+      return new Response(null, { status: csrfResult.status });
+    }
+
+    // ─── 2. Server action interception ────────────────────────────────
+    if (isActionRequest(req)) {
+      const actionResponse = await handleActionRequest(req, {
+        csrf: deps.csrfConfig,
+        bodyLimits: { limits: deps.bodyLimits },
+        sensitiveFields: deps.sensitiveFields,
+        revalidateRenderer: deps.buildRevalidateRenderer(req),
+      });
+
+      if (actionResponse) {
+        // ─── 3. No-JS validation rerender ─────────────────────────────
+        if ('rerender' in actionResponse) {
+          const formRerender = actionResponse as FormRerender;
+          // Build a synthetic GET request for the rerender pipeline:
+          //   - Same URL (so route matching lands on the same page)
+          //   - Cookie header replaced with the post-action RYW snapshot
+          //     so server components see the action's writes (TIM-837)
+          //   - Method GET because the rerender is conceptually a page
+          //     render, not a re-POST. The pipeline doesn't branch on
+          //     method for page rendering, and constructing a POST without
+          //     a body is awkward across Request implementations.
+          const rerenderHeaders = new Headers(req.headers);
+          if (formRerender.cookieHeader) {
+            rerenderHeaders.set('cookie', formRerender.cookieHeader);
+          } else {
+            rerenderHeaders.delete('cookie');
+          }
+          const rerenderReq = new Request(req.url, {
+            method: 'GET',
+            headers: rerenderHeaders,
+          });
+          const response = await runWithFormFlash(formRerender.rerender, () =>
+            pipeline(rerenderReq)
+          );
+          // Apply Set-Cookie headers snapshotted from the action's ALS scope.
+          // The pipeline above runs in its own request context with a fresh
+          // cookie jar, so cookies set inside the action would otherwise be
+          // silently dropped on the no-JS rerender path. See TIM-836
+          // (LOCAL-740).
+          for (const value of formRerender.setCookieHeaders) {
+            response.headers.append('Set-Cookie', value);
+          }
+          return response;
+        }
+        return actionResponse;
+      }
+    }
+
+    // ─── 4. Normal route dispatch ─────────────────────────────────────
+    return pipeline(req);
+  };
+}

package/src/server/sitemap-generator.ts

@@ -334,5 +334,5 @@ export async function generateSitemap(
  */
 export function hasUserSitemap(root: SegmentNode): boolean {
   if (!root.metadataRoutes) return false;
-  return root.metadataRoutes.has('sitemap');
+  return 'sitemap' in root.metadataRoutes;
 }

package/src/server/slot-resolver.ts

@@ -352,7 +352,7 @@ interface SlotMatchResult {
  * to find the deepest matching page.
  */
 function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMatchResult | null {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
   // Find the parent segment that owns this slot by comparing urlPaths.
   // The slot's urlPath matches its parent's urlPath (slots don't add URL depth).

package/src/server/status-code-resolver.ts

@@ -5,6 +5,12 @@
  * correct file to render by walking the fallback chain described in
  * design/10-error-handling.md §"Status-Code Files".
  *
+ * **Generic over `TFile`** (TIM-848). Walks `SegmentNode<TFile>` trees
+ * regardless of whether `TFile` is the build-time `RouteFile` or the
+ * runtime `ManifestFile`. Before TIM-848 there were two near-identical
+ * resolvers — one for the Map-based scanner output and one for the
+ * object-based runtime manifest. Now there is one.
+ *
  * Supports two format families:
  * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
  * - 'json': .json status files → raw JSON response, no React
@@ -17,17 +23,16 @@
  *   Pass 3 — error.tsx (leaf → root)
  *   Pass 4 — framework default (returns null)
  *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ * **JSON chain (4xx and 5xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
  *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
  *
- * **5xx (component only):**
+ * **5xx component:**
  *   Per-segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- *   Then global-error.tsx (future)
  *   Then framework default (returns null)
  */
 
-import type { SegmentNode, RouteFile } from '../routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -42,9 +47,9 @@ export type StatusFileKind =
 export type StatusFileFormat = 'component' | 'json';
 
 /** Result of resolving a status-code file for a segment chain. */
-export interface StatusFileResolution {
+export interface StatusFileResolution<TFile> {
   /** The matched route file. */
-  file: RouteFile;
+  file: TFile;
   /** The HTTP status code (always the original status, not the file's code). */
   status: number;
   /** How the file was matched. */
@@ -57,9 +62,9 @@ export interface StatusFileResolution {
 export type SlotDeniedKind = 'denied' | 'default';
 
 /** Result of resolving a slot denied file. */
-export interface SlotDeniedResolution {
+export interface SlotDeniedResolution<TFile> {
   /** The matched route file (denied.tsx or default.tsx). */
-  file: RouteFile;
+  file: TFile;
   /** Slot name without @ prefix. */
   slotName: string;
   /** How the file was matched. */
@@ -78,6 +83,52 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
   'unauthorized': 401,
 };
 
+/** Reverse index: status code → legacy file name. Built once at module load. */
+const STATUS_TO_LEGACY_FILE: Record<number, string> = Object.fromEntries(
+  Object.entries(LEGACY_FILE_TO_STATUS).map(([name, status]) => [status, name])
+);
+
+// ─── Lookup Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Look up `{statusStr}` then `{categoryKey}` (e.g. "4xx" / "5xx") in a
+ * status-file group on a single segment. Shared by all three fallback
+ * chains — the only structural difference between component 4xx,
+ * component 5xx, and JSON resolution is *which* group is searched and
+ * how the per-segment loop is layered around it.
+ */
+function lookupInGroup<TFile>(
+  group: Record<string, TFile> | undefined,
+  statusStr: string,
+  categoryKey: string,
+  segmentIndex: number,
+  status: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const exact = group[statusStr];
+  if (exact) return { file: exact, status, kind: 'exact', segmentIndex };
+  const category = group[categoryKey];
+  if (category) return { file: category, status, kind: 'category', segmentIndex };
+  return null;
+}
+
+/**
+ * Look up the legacy convention file (`not-found.tsx` / `forbidden.tsx` /
+ * `unauthorized.tsx`) for `status` on a single segment. Returns null if
+ * `status` has no legacy mapping or the file isn't present.
+ */
+function lookupLegacy<TFile>(
+  group: Record<string, TFile> | undefined,
+  status: number,
+  segmentIndex: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const name = STATUS_TO_LEGACY_FILE[status];
+  if (!name) return null;
+  const file = group[name];
+  return file ? { file, status, kind: 'legacy', segmentIndex } : null;
+}
+
 // ─── Resolver ────────────────────────────────────────────────────────────────
 
 /**
@@ -91,101 +142,50 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
  */
-export function resolveStatusFile(
+export function resolveStatusFile<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>,
+  segments: ReadonlyArray<SegmentNode<TFile>>,
   format: StatusFileFormat = 'component'
-): StatusFileResolution | null {
-  if (status >= 400 && status <= 499) {
-    return format === 'json' ? resolve4xxJson(status, segments) : resolve4xx(status, segments);
-  }
-  if (status >= 500 && status <= 599) {
-    // JSON format for 5xx uses the same json chain pattern
-    return format === 'json' ? resolve5xxJson(status, segments) : resolve5xx(status, segments);
-  }
-  return null;
+): StatusFileResolution<TFile> | null {
+  if (status < 400 || status > 599) return null;
+  if (format === 'json') return resolveJson(status, segments);
+  if (status <= 499) return resolve4xx(status, segments);
+  return resolve5xx(status, segments);
 }
 
 /**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
+ * 4xx component fallback chain — three separate full passes leaf→root.
+ *
+ * The passes must be separate (not interleaved per-segment) so that a
+ * root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
+ * inverts this and is per-segment: a leaf's `error.tsx` beats a root's
+ * `5xx.tsx`. This asymmetry is the only reason these two functions exist
+ * separately.
+ *
+ *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
+ *   Pass 2 — not-found / forbidden / unauthorized (legacyStatusFiles)
+ *   Pass 3 — error.tsx                         (error)
  */
-function resolve4xx(
+function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  // Pass 2: legacy compat files (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles.get(name);
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
+    const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
+    if (r) return r;
   }
 
-  // Pass 3: error.tsx (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
-    }
+    const r = lookupLegacy(segments[i].legacyStatusFiles, status, i);
+    if (r) return r;
   }
 
-  return null;
-}
-
-/**
- * 4xx JSON fallback chain (single pass):
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolve4xxJson(
-  status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
-  const statusStr = String(status);
-
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    // Exact match first
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.jsonStatusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
+    const errorFile = segments[i].error;
+    if (errorFile) {
+      return { file: errorFile, status, kind: 'error', segmentIndex: i };
     }
   }
 
@@ -193,33 +193,22 @@ function resolve4xxJson(
 }
 
 /**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ * 5xx component fallback chain — single pass, per-segment leaf→root.
+ *
+ * At each segment: {status}.tsx → 5xx.tsx → error.tsx. A leaf's
+ * `error.tsx` therefore beats a root's `5xx.tsx`, which is the
+ * intentional inverse of the 4xx chain.
  */
-function resolve5xx(
+function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
-
-    // Exact status file
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles.get(statusStr);
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      // Category catch-all
-      const category = segment.statusFiles.get('5xx');
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    // error.tsx at this segment level (for 5xx, checked per-segment)
+    const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
+    if (r) return r;
     if (segment.error) {
       return { file: segment.error, status, kind: 'error', segmentIndex: i };
     }
@@ -229,29 +218,22 @@ function resolve5xx(
 }
 
 /**
- * 5xx JSON fallback chain (single pass):
- *   At each segment (leaf → root): {status}.json → 5xx.json
- *   No error.tsx equivalent — JSON chain terminates at category catch-all.
+ * JSON fallback chain (for both 4xx and 5xx) — single pass leaf→root.
+ *
+ * At each segment: {status}.json → {category}.json. No legacy compat,
+ * no error.tsx — the JSON chain terminates at the category catch-all
+ * and the caller falls back to a bare-JSON framework default.
  */
-function resolve5xxJson(
+function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const categoryKey = status >= 500 ? '5xx' : '4xx';
 
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles.get('5xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
+    const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
+    if (r) return r;
   }
 
   return null;
@@ -267,7 +249,9 @@ function resolve5xxJson(
  *
  * @param slotNode - The segment node for the slot (segmentType === 'slot').
  */
-export function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null {
+export function resolveSlotDenied<TFile>(
+  slotNode: SegmentNode<TFile>
+): SlotDeniedResolution<TFile> | null {
   const slotName = slotNode.segmentName.replace(/^@/, '');
 
   if (slotNode.denied) {

package/src/server/tree-builder.ts

@@ -213,8 +213,10 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       if (LayoutComponent) {
         // Resolve parallel slots for this layout
         const slotProps: Record<string, ReactElement> = {};
-        if (segment.slots.size > 0) {
-          for (const [slotName, slotNode] of segment.slots) {
+        const slotNames = Object.keys(segment.slots);
+        if (slotNames.length > 0) {
+          for (const slotName of slotNames) {
+            const slotNode = segment.slots[slotName]!;
             slotProps[slotName] = await buildSlotElement(
               slotNode,
               loadModule,
@@ -344,7 +346,7 @@ async function wrapWithErrorBoundaries(
 
   if (segment.statusFiles) {
     // Wrap with specific status files (innermost — highest priority at runtime)
-    for (const [key, file] of segment.statusFiles) {
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
@@ -369,7 +371,7 @@ async function wrapWithErrorBoundaries(
     }
 
     // Wrap with category catch-alls (4xx.tsx, 5xx.tsx)
-    for (const [key, file] of segment.statusFiles) {
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key === '4xx' || key === '5xx') {
         const mod = await loadModule(file);
         const Component = mod.default;