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

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

@@ -3,28 +3,40 @@
  *
  * 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:
+ * 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. **Server action interception** — POST requests carrying an
+ *   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.
  *
- *   3. **No-JS validation rerender** — when an action returns flash data
+ *   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. See TIM-836 / TIM-837.
+ *      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 and stub revalidate renderers.
+ * pipelines, stub revalidate renderers, and stub route matchers.
  */
 
 import type { FormRerender } from '../action-handler.js';
@@ -32,8 +44,20 @@ 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 ────────────────────────────────────────────────────────────────
 
@@ -48,6 +72,14 @@ import type { RevalidateRenderer } from '../actions.js';
  */
 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). */
@@ -58,6 +90,42 @@ export interface ActionDispatchDeps {
   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 ───────────────────────────────────────────────────────
@@ -66,15 +134,7 @@ export interface ActionDispatchDeps {
  * 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)`.
+ * 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
@@ -85,6 +145,9 @@ 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) ─────────────
     //
@@ -104,7 +167,192 @@ export function wrapPipelineWithActionDispatch(
 
     // ─── 2. Server action interception ────────────────────────────────
     if (isActionRequest(req)) {
-      const actionResponse = await handleActionRequest(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,
@@ -117,22 +365,36 @@ export function wrapPipelineWithActionDispatch(
           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)
+          //   - 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);
-          if (formRerender.cookieHeader) {
-            rerenderHeaders.set('cookie', formRerender.cookieHeader);
-          } else {
-            rerenderHeaders.delete('cookie');
-          }
+          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)
           );
@@ -140,12 +402,43 @@ export function wrapPipelineWithActionDispatch(
           // 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).
+          // (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;
       }
     }

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;
   }
 }

package/src/server/tracing.ts

@@ -105,17 +105,17 @@ export function getTraceStore(): TraceStore | undefined {
  * Only called in dev mode — zero overhead in production.
  */
 export async function initDevTracing(
-  config: import('./dev-logger.js').DevLoggerConfig
+  config: import('../dev-tools/logger.js').DevLoggerConfig
 ): Promise<void> {
   const api = await getOtelApi();
   if (!api) return;
 
-  let DevSpanProcessor: typeof import('./dev-span-processor.js').DevSpanProcessor;
+  let DevSpanProcessor: typeof import('../dev-tools/instrumentation.js').DevSpanProcessor;
   let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;
   let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;
 
   try {
-    ({ DevSpanProcessor } = await import('./dev-span-processor.js'));
+    ({ DevSpanProcessor } = await import('../dev-tools/instrumentation.js'));
     ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));
     ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));
   } catch (err) {