@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

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

@@ -0,0 +1,449 @@
+/**
+ * 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
+ * four 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. **Middleware-on-actions execution** — when the request is a server
+ *      action POST and `actions.runMiddleware !== false`, the matched
+ *      route's `middleware.ts` chain runs BEFORE the action body. This
+ *      closes the Next.js CVE-2025-29927 class of bug, where developers
+ *      reasonably believe `middleware.ts` runs on every request and find
+ *      out (the hard way) that actions silently bypass it. Middleware can
+ *      short-circuit with a `Response`, `redirect()`, or `deny()`; can
+ *      mutate cookies; and can inject request headers visible to the
+ *      action body via `getHeaders()`. See TIM-871.
+ *
+ *   3. **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.
+ *
+ *   4. **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. The synthetic GET is
+ *      marked via `markRequestBypassMiddleware` so the pipeline does not
+ *      double-execute middleware on it. See TIM-836 / TIM-837 / TIM-871.
+ *
+ * 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, stub revalidate renderers, and stub route matchers.
+ */
+
+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 { seedRequestCookies } from '../cookie-context.js';
+import { markRequestBypassMiddleware } from '../middleware-runner.js';
+import { DenySignal } from '../primitives.js';
+import { canonicalize } from '../canonicalize.js';
+import {
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  fireOnRequestError,
+} from '../pipeline-helpers.js';
+import { logRenderError } from '../logger.js';
+import type { RouteMatch, RouteMatcher } from '../pipeline.js';
+import type { SensitiveFieldsOption } from '../sensitive-fields.js';
+import type { RevalidateRenderer } from '../actions.js';
+import { runMiddlewareForAction, type CoerceSegmentParamsFn } from './action-middleware-runner.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;
+
+/** Optional renderer for fallback deny pages — mirrors `PipelineConfig.renderDenyFallback`. */
+export type RenderDenyFallbackFn = (
+  deny: DenySignal,
+  req: Request,
+  responseHeaders: Headers,
+  match?: RouteMatch
+) => Response | Promise<Response>;
+
+/** 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;
+  /**
+   * Route matcher — when present, enables middleware-on-actions execution.
+   * Mirrors `PipelineConfig.matchRoute`. Tests that don't exercise the
+   * middleware path may omit this; the wrapper falls back to the legacy
+   * "actions skip middleware" behavior.
+   */
+  matchRoute?: RouteMatcher;
+  /**
+   * Segment-param coercer — runs the matched route's `params.ts` codecs
+   * so the middleware context sees typed `segmentParams`. Required when
+   * `matchRoute` is provided.
+   */
+  coerceSegmentParams?: CoerceSegmentParamsFn;
+  /**
+   * Renderer for fallback deny pages — used when middleware throws a
+   * `DenySignal` and the framework wants to render `403.tsx` / `404.tsx`
+   * instead of returning a bare empty Response. Optional — when omitted
+   * the wrapper falls back to a bare status response.
+   */
+  renderDenyFallback?: RenderDenyFallbackFn;
+  /**
+   * Whether to run `middleware.ts` on server action requests. Defaults
+   * to `true` (the safe default). Controlled by
+   * `actions.runMiddleware` in `timber.config.ts`. See TIM-871.
+   */
+  runMiddleware?: boolean;
+  /**
+   * Whether to strip trailing slashes during pathname canonicalization
+   * for route matching. Mirrors `PipelineConfig.stripTrailingSlash`;
+   * defaults to `true` when omitted, matching the page pipeline. The
+   * wrapper MUST canonicalize before matching so non-canonical action
+   * POSTs (`/admin/`, `/admin//`, encoded separators) cannot bypass the
+   * middleware gate by missing the route match and falling through to
+   * the legacy path. See TIM-871 / codex review.
+   */
+  stripTrailingSlash?: boolean;
+}
+
+// ─── 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 are documented in the file header.
+ *
+ * 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> {
+  const middlewareEnabled = deps.runMiddleware !== false;
+  const stripTrailingSlash = deps.stripTrailingSlash ?? true;
+
+  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)) {
+      // ─── 2a. Route-type check + canonicalize (TIM-870) ──────────────
+      //
+      // Canonicalize and match the route BEFORE any body parsing. If the
+      // matched route is an API route (route.ts), skip action detection
+      // entirely and dispatch straight to the pipeline. Server actions
+      // only live on page routes; POSTs to route.ts are API requests
+      // whose body must reach the handler untouched — not pre-parsed
+      // looking for $ACTION_REF fields.
+      //
+      // This also avoids allocating a full formData() parse over large
+      // multipart uploads (e.g. 50 MB file uploads to /api/upload) that
+      // would otherwise be buffered and discarded by handleFormAction.
+      //
+      // The same canonicalized match is reused for the middleware-on-
+      // actions path below, avoiding a redundant match.
+      let match: RouteMatch | null = null;
+
+      if (deps.matchRoute) {
+        // Canonicalize the pathname BEFORE matching, with the exact same
+        // rules the page pipeline uses (`canonicalize()` in
+        // `pipeline-phases.ts` stage 1). Without this, an attacker could
+        // POST to a non-canonical variant of an authenticated route —
+        // `/admin/` with a trailing slash, `/admin//` with a doubled
+        // slash, `/adm%69n` with percent-escapes, `/admin%2fnested` with
+        // an encoded separator — fail the match here, fall through to
+        // the legacy "no middleware" path, and still reach the action
+        // handler. The canonicalization step closes that bypass and
+        // guarantees the wrapper matches EXACTLY the same route the page
+        // pipeline would match. A canonicalize failure (encoded
+        // separator, null byte, malformed escape, `..` escaping root)
+        // returns the canonicalizer's status directly — the request is
+        // malformed, never dispatched. See TIM-871 (codex review).
+        const url = new URL(req.url);
+        const canonical = canonicalize(url.pathname, stripTrailingSlash);
+        if (!canonical.ok) {
+          return new Response(null, { status: canonical.status });
+        }
+        match = deps.matchRoute(canonical.pathname);
+
+        // Skip action detection for route.ts API handlers (TIM-870).
+        // Server actions only target page routes. A POST to a route.ts
+        // path is an API request — the full body should reach the route
+        // handler without being pre-parsed by handleFormAction.
+        if (match) {
+          const leaf = match.segments[match.segments.length - 1];
+          if (leaf?.route) {
+            return pipeline(req);
+          }
+        }
+      }
+
+      // ─── 2b. Middleware-on-actions (TIM-871) ────────────────────────
+      //
+      // When middleware execution is enabled and the request matches a
+      // known route, run the matched chain BEFORE the action handler.
+      // The middleware run happens inside its own `runWithRequestContext`
+      // scope so middleware can read/write cookies and inject request
+      // headers via the standard ALS APIs. Mutations are captured at the
+      // end of the scope and threaded into the action handler's own ALS
+      // scope via `seedRequestCookies` + a request rebuilt with overlay
+      // headers merged in.
+      let downstreamReq = req;
+      let middlewareSetCookieHeaders: string[] = [];
+
+      if (
+        middlewareEnabled &&
+        deps.coerceSegmentParams &&
+        match &&
+        match.middlewareChain.length > 0
+      ) {
+        const outcome = await runMiddlewareForAction(req, match, deps.coerceSegmentParams);
+
+        // ─── Translate middleware outcome ─────────────────────────
+        if (outcome.kind === 'param-coercion-error') {
+          // Bad segment params → 404. Matches the page pipeline.
+          return new Response(null, { status: 404 });
+        }
+        if (outcome.kind === 'error') {
+          // Unhandled middleware error → 500.
+          return new Response(null, { status: 500 });
+        }
+        if (outcome.kind === 'short-circuit') {
+          // Middleware returned a Response. Apply its Set-Cookie
+          // snapshot before returning. Clone unconditionally so the
+          // header bag is mutable.
+          const finalResponse = cloneWithMutableHeaders(outcome.response);
+          for (const value of outcome.setCookieHeaders) {
+            finalResponse.headers.append('Set-Cookie', value);
+          }
+          return finalResponse;
+        }
+        if (outcome.kind === 'redirect') {
+          // RedirectSignal from middleware → standard redirect Response.
+          // Use `buildRedirectResponse` so the with-JS path produces a
+          // 204 + X-Timber-Redirect (SPA navigation) and the no-JS path
+          // produces a real HTTP 30x — exactly the same translation
+          // the page pipeline applies in `outcomeToResponse`.
+          const headers = new Headers();
+          for (const value of outcome.setCookieHeaders) {
+            headers.append('Set-Cookie', value);
+          }
+          return buildRedirectResponse(outcome.signal, req, headers);
+        }
+        if (outcome.kind === 'deny') {
+          // DenySignal from middleware → render the matched route's
+          // colocated deny page if available, otherwise a bare empty
+          // status response. Mirrors the page pipeline's deny handling.
+          const headers = new Headers();
+          for (const value of outcome.setCookieHeaders) {
+            headers.append('Set-Cookie', value);
+          }
+          if (deps.renderDenyFallback) {
+            try {
+              return cloneWithMutableHeaders(
+                await deps.renderDenyFallback(outcome.signal, req, headers, outcome.match)
+              );
+            } catch (denyRenderError) {
+              // Deny page rendering failed — log before falling through to bare
+              // response. Without this, a crashing deny page on the action path
+              // produces a blank response with zero server-side signal. See TIM-876.
+              const url = new URL(req.url);
+              logRenderError({ method: req.method, path: url.pathname, error: denyRenderError });
+              await fireOnRequestError(denyRenderError, req, 'render');
+            }
+          }
+          return new Response(null, { status: outcome.signal.status, headers });
+        }
+
+        // ─── Continue: middleware passed ──────────────────────────
+        //
+        // Build a downstream Request that the action handler will see:
+        //   - Original headers + middleware's request-header overlay
+        //     merged on top, so `getHeaders()` inside the action body
+        //     observes the injected values.
+        //   - Cookie header dropped; the post-middleware RYW cookie
+        //     state is threaded directly into the action handler's
+        //     request context via `seedRequestCookies`. This avoids
+        //     a Cookie-header round-trip that would re-parse via
+        //     `parseCookieHeader` — the same H-3 smuggling primitive
+        //     mitigated by TIM-868. The action's own cookie reads
+        //     therefore observe both the original cookies and any
+        //     middleware mutations, with no cleartext encoding step
+        //     in between.
+        //   - Body forwarded as-is so the action handler can decode it.
+        //   - Method preserved (POST).
+        //
+        // We hold the middleware Set-Cookie snapshot to prepend to the
+        // final response below — middleware writes precede action
+        // writes in the response order so the browser's last-wins
+        // resolution lets the action override middleware on conflict.
+        const mergedHeaders = new Headers(req.headers);
+        outcome.overlay.forEach((value, key) => {
+          mergedHeaders.set(key, value);
+        });
+        mergedHeaders.delete('cookie');
+        downstreamReq = new Request(req.url, {
+          method: req.method,
+          headers: mergedHeaders,
+          body: req.body,
+          // Required by undici when constructing a Request with a
+          // streaming body — `req.body` is a ReadableStream and the
+          // fetch spec needs an explicit half-duplex declaration.
+          // @ts-expect-error — `duplex` is not in the standard Request init type yet.
+          duplex: 'half',
+        });
+        seedRequestCookies(downstreamReq, outcome.cookies);
+        middlewareSetCookieHeaders = outcome.setCookieHeaders;
+      }
+
+      // ─── 2c. Action handler dispatch ────────────────────────────────
+      //
+      // The revalidate renderer is built from the ORIGINAL request, not
+      // `downstreamReq`. The downstream request had its `cookie` header
+      // stripped (the post-middleware RYW cookie state is threaded
+      // through ALS via `seedRequestCookies` instead, to preserve the
+      // H-3 smuggling invariant from TIM-868). But the revalidate
+      // renderer in `rsc-entry/index.ts` forwards `req.headers` onto the
+      // synthetic revalidation Request it builds for the target path —
+      // if we passed `downstreamReq` here, that synthetic request would
+      // carry no cookies, and an action that calls `revalidatePath()`
+      // would re-render the target route with no session / tenant / auth
+      // context. Using `req` (the unmodified inbound request) preserves
+      // the original cookie header for the revalidation side channel
+      // while `seedRequestCookies` handles the middleware RYW state for
+      // the action body itself. See TIM-871 (codex review).
+      const actionResponse = await handleActionRequest(downstreamReq, {
+        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 DROPPED entirely. The post-action RYW state
+          //     is threaded into the rerender request context as a parsed
+          //     `Map<string, string>` via `seedRequestCookies` below, so
+          //     `parseCookieHeader` is never called for this request.
+          //     This eliminates the value-smuggling primitive that the
+          //     previous string round-trip exposed: a `;`-laden cookie
+          //     value would otherwise split into sibling cookies during
+          //     re-parse and let an attacker inject `role=admin` /
+          //     forged session cookies into the rerender response. See
+          //     ONGOING_SECURITY.md H-3 (TIM-868) and 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.
+          //   - Marked via `markRequestBypassMiddleware` so the pipeline
+          //     skips its middleware phase on this synthetic request.
+          //     Middleware already ran once on the inbound POST (above);
+          //     letting the pipeline run it again would double-execute
+          //     auth, rate limiting, and request-header injection. See
+          //     TIM-871.
+          const rerenderHeaders = new Headers(req.headers);
+          rerenderHeaders.delete('cookie');
+          const rerenderReq = new Request(req.url, {
+            method: 'GET',
+            headers: rerenderHeaders,
+          });
+          // Seed BEFORE pipeline() runs — runWithRequestContext consumes
+          // the seed when it constructs the per-request store.
+          seedRequestCookies(rerenderReq, formRerender.cookies);
+          markRequestBypassMiddleware(rerenderReq);
+          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). Middleware-set cookies are prepended first so
+          // browser last-wins still lets action writes override.
+          for (const value of middlewareSetCookieHeaders) {
+            response.headers.append('Set-Cookie', value);
+          }
+          for (const value of formRerender.setCookieHeaders) {
+            response.headers.append('Set-Cookie', value);
+          }
+          return response;
+        }
+        // Apply middleware Set-Cookie snapshot to the action's RSC
+        // response. Action's own cookies were already appended inside
+        // `handleActionRequest` via `getSetCookieHeaders()` before the
+        // action ALS scope exited; we prepend middleware writes so
+        // browser last-wins lets action writes take precedence on
+        // conflicting names.
+        if (middlewareSetCookieHeaders.length > 0) {
+          // Middleware writes go FIRST in the response order, so we
+          // build a fresh Headers and rebuild the Response. Cloning the
+          // Response keeps the body stream intact.
+          const mergedHeaders = new Headers();
+          for (const value of middlewareSetCookieHeaders) {
+            mergedHeaders.append('Set-Cookie', value);
+          }
+          actionResponse.headers.forEach((value, key) => {
+            if (key.toLowerCase() === 'set-cookie') {
+              mergedHeaders.append('Set-Cookie', value);
+            } else {
+              mergedHeaders.set(key, value);
+            }
+          });
+          return new Response(actionResponse.body, {
+            status: actionResponse.status,
+            statusText: actionResponse.statusText,
+            headers: mergedHeaders,
+          });
+        }
+        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/ssr-entry.ts

@@ -37,7 +37,7 @@ import { SsrStreamError } from './primitives.js';
 import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.js';
 import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
-import { setCurrentParams } from '../client/use-params.js';
+import { setCurrentParams } from '../client/use-segment-params.js';
 import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.js';
 
 // Pre-import Node.js stream modules at module load time — not per-request.

package/src/server/state-tree-diff.ts

@@ -14,6 +14,8 @@
  * See design/13-security.md §"State tree manipulation"
  */
 
+import { swallow } from './logger.js';
+
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
@@ -33,7 +35,8 @@ export function parseClientStateTree(req: Request): Set<string> | null {
       return null;
     }
     return new Set(parsed.segments as string[]);
-  } catch {
+  } catch (err) {
+    swallow(err, 'malformed X-Timber-State-Tree header');
     return null;
   }
 }