@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/server/rsc-entry/render-route.ts

@@ -0,0 +1,315 @@
+/**
+ * Route renderer — turns a matched route into a Response.
+ *
+ * Extracted from `rsc-entry/index.ts` so the entry can stay focused on
+ * pipeline construction. This module owns the steps that happen *after*
+ * the pipeline has matched a route and before it commits a response:
+ * element-tree build, RSC Flight render, and dispatch to either the SSR
+ * HTML path or the RSC payload path. It also handles the
+ * synchronous-signal escape hatches (deny / redirect / render error
+ * thrown during stream creation) so the entry doesn't carry that logic.
+ *
+ * The function is parameterized over its dependencies — `clientBootstrap`,
+ * `clientJsDisabled`, `rootSegment`, `globalError` — so the entry passes
+ * them in once at handler-construction time and they ride along on every
+ * call. No globals, no closures over the entry's createRequestHandler
+ * scope.
+ *
+ * Design docs: 02-rendering-pipeline.md, 19-client-navigation.md.
+ */
+
+import type { BuildManifest } from '../build-manifest.ts';
+import {
+  buildCssLinkTags,
+  buildFontPreloadTags,
+  buildModulepreloadTags,
+  collectRouteCss,
+  collectRouteFonts,
+  collectRouteModulepreloads,
+} from '../build-manifest.ts';
+import type { LayoutEntry } from '../deny-renderer.ts';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import type { InterceptionContext, RouteMatch } from '../pipeline.ts';
+import { buildRouteElement, NoPageComponentError } from '../route-element-builder.ts';
+import { ParamCoercionError } from '../param-coercion.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { recordTiming } from '../server-timing.ts';
+import { requestContextAls } from '../als-registry.ts';
+import { parseClientStateTree } from '../state-tree-diff.ts';
+
+import { getFirstDeniedSegmentIndex } from '../deny-boundary.ts';
+import { handleApiRoute } from './api-handler.ts';
+import { renderErrorPage, renderNoMatchPage } from './error-renderer.ts';
+import { buildRedirectResponse, createDebugChannelSink } from './helpers.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { buildRscPayloadResponse } from './rsc-payload.ts';
+import { renderRscStream } from './rsc-stream.ts';
+import { renderSsrResponse } from './ssr-renderer.ts';
+import { callSsr } from './ssr-bridge.ts';
+
+/**
+ * Static-per-handler dependencies for `renderRoute` — captured once at
+ * handler construction so each per-request call site only has to pass
+ * the request-specific arguments.
+ */
+export interface RenderRouteDeps {
+  clientBootstrap: ClientBootstrapConfig;
+  clientJsDisabled: boolean;
+  clientSegmentCache: boolean;
+  rootSegment: ManifestSegmentNode;
+  buildManifest: BuildManifest;
+  globalError?: { load: () => Promise<unknown>; filePath: string };
+  devDebugRegistry?: import('../../dev-tools/debug-channel.ts').DebugChannelRegistry;
+}
+
+/**
+ * Render a matched route to an HTML Response via RSC → SSR pipeline,
+ * or return a raw RSC Flight stream for client-side navigation requests.
+ *
+ * 1. Load page/layout components from the segment chain
+ * 2. Resolve metadata
+ * 3. Render to RSC Flight stream (serializes "use client" as references)
+ * 4. If Accept: text/x-component → return RSC stream directly
+ *    Otherwise → pass RSC stream to SSR entry for HTML rendering
+ */
+export async function renderRoute(
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  deps: RenderRouteDeps,
+  interception?: InterceptionContext
+): Promise<Response> {
+  const { clientBootstrap, clientJsDisabled, rootSegment, buildManifest, globalError } = deps;
+  const segments = match.segments;
+  const leaf = segments[segments.length - 1];
+
+  // API routes (route.ts) — run access.ts standalone then dispatch to handler.
+  // No React render pass — AccessGate is not used, React.cache is not active.
+  // See design/04-authorization.md §"Auth in API Routes".
+  if (leaf.route && !leaf.page) {
+    return handleApiRoute(req, segments, responseHeaders);
+  }
+
+  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
+  // The state tree lists sync segments the client has cached — the server
+  // skips re-rendering those layouts for a smaller, faster RSC payload.
+  // Only used for RSC requests — HTML requests always get a full render.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const clientStateTree =
+    deps.clientSegmentCache && isRscRequest(req) ? parseClientStateTree(req) : null;
+
+  // Build the React element tree — runs access checks eagerly to gate
+  // metadata resolution (TIM-1027), then loads modules and resolves
+  // metadata for non-denied segments. Denied segments' verdicts are
+  // passed to AccessGate for in-tree replay. Passing segments' access
+  // re-runs during render for React.cache population (TIM-662).
+  let routeResult;
+  const _buildStart = performance.now();
+  try {
+    routeResult = await buildRouteElement(
+      req,
+      match,
+      interception,
+      clientStateTree,
+      buildManifest.metadataRouteHashes
+    );
+  } catch (error) {
+    // Param coercion failed — render the custom 404 page via status files.
+    // Previously returned a bare Response(null, { status: 404 }) which bypassed
+    // custom 404 pages. Now routes through renderNoMatchPage so apps with
+    // 404.tsx render their custom page.
+    if (error instanceof ParamCoercionError) {
+      return renderNoMatchPage(req, rootSegment, responseHeaders, clientBootstrap);
+    }
+    // No PageComponent found — same treatment as param coercion: render custom 404.
+    if (error instanceof NoPageComponentError) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[timber] ${error.message}`);
+      }
+      return renderNoMatchPage(req, rootSegment, responseHeaders, clientBootstrap);
+    }
+    throw error;
+  }
+
+  const _buildEnd = performance.now();
+  recordTiming({
+    name: 'build',
+    dur: Math.round(_buildEnd - _buildStart),
+    desc: 'build element tree',
+  });
+
+  const {
+    payload,
+    layoutComponents,
+    deferSuspenseFor,
+    skippedSegments,
+    slotSkipInfo,
+    leafDenyChain,
+  } = routeResult;
+
+  // Build head HTML for injection into the SSR output.
+  // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
+  // In dev mode the manifest is empty — Vite HMR handles CSS/JS.
+  //
+  // Link headers (for 103 Early Hints) are emitted by the earlyHints pipeline
+  // stage before middleware runs. Here we only emit the <head> HTML fallback tags
+  // — these ensure resources load even on platforms without Early Hints support.
+  let headHtml = '';
+
+  // Font CSS is NOT inlined here anymore (TIM-828). The transform hook
+  // injects a side-effect `import 'virtual:timber-font-css/<hash>.css'`
+  // into each file that calls a font function. @vitejs/plugin-rsc's
+  // `collectCss` walks the RSC module graph, finds the virtual CSS
+  // module, and React Float `preinit()`s it as
+  // `<link rel="stylesheet" data-rsc-css-href=...>` — the same path
+  // component CSS rides on. Dev and production share a single path,
+  // with no `globalThis` channel and no dev/prod skew.
+  //
+  // Font preload hints (distinct from the @font-face CSS) still flow
+  // through `BuildManifest.fonts[importer]` and are emitted below plus
+  // as 103 Early Hints via `buildEarlyHintsHeaders()`.
+  const fontEntries = collectRouteFonts(segments, buildManifest);
+  if (fontEntries.length > 0) {
+    headHtml += buildFontPreloadTags(fontEntries);
+  }
+
+  // Emit <link rel="stylesheet"> tags for per-route CSS (TIM-1014).
+  // React Float also emits stylesheet links via preinit() during Fizz
+  // rendering, but those arrive too late — after the RSC stream starts.
+  // These <head> tags ensure CSS is discovered during HTML parsing.
+  // Float deduplicates, so no double-fetch.
+  const cssUrls = collectRouteCss(segments, buildManifest);
+  if (cssUrls.length > 0) {
+    headHtml += buildCssLinkTags(cssUrls);
+  }
+
+  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
+  if (!clientJsDisabled) {
+    const preloadUrls = collectRouteModulepreloads(segments, buildManifest);
+    if (preloadUrls.length > 0) {
+      headHtml += buildModulepreloadTags(preloadUrls);
+    }
+  }
+
+  // Metadata tags (<title>, <meta>, <link>) are now rendered as React
+  // elements in the route element tree — React 19 Float hoists them into
+  // <head> during SSR and manages them during client rendering. No string
+  // splice needed. See TIM-1151.
+
+  // Render to RSC Flight stream with signal tracking.
+  const _rscStart = performance.now();
+  // Only wire the HMR debug transport for HTML requests. RSC payload
+  // requests (client navigations) don't serve HTML with __timber_debug_id,
+  // so the browser can't subscribe — skip to avoid orphaned sessions.
+  const debugRegistry = isRscRequest(req) || clientJsDisabled ? undefined : deps.devDebugRegistry;
+  const { rscStream, signals, getDebugComponents, debugRequestId } = renderRscStream(
+    payload,
+    req,
+    leafDenyChain,
+    debugRegistry
+  );
+
+  // Store the debug components getter in ALS so onPipelineError can
+  // include component tree context for render-phase errors (dev mode only).
+  // Per-request via ALS — no cross-request race. See TIM-557.
+  const alsStore = requestContextAls.getStore();
+  if (alsStore) {
+    alsStore.debugComponentsGetter = getDebugComponents;
+  }
+  recordTiming({
+    name: 'rsc-init',
+    dur: Math.round(performance.now() - _rscStart),
+    desc: 'RSC stream init',
+  });
+
+  // Synchronous redirect — redirect() in access.ts or a non-async component
+  // throws during renderToReadableStream creation. Return HTTP redirect.
+  if (signals.redirectSignal) {
+    return buildRedirectResponse(signals.redirectSignal, req, responseHeaders);
+  }
+
+  // Synchronous deny — deny() in a non-async component throws during
+  // renderToReadableStream creation, caught in the try/catch above.
+  if (signals.denySignal) {
+    if (isRscRequest(req)) {
+      return renderDenyPageAsRsc(
+        signals.denySignal,
+        segments,
+        layoutComponents as LayoutEntry[],
+        req,
+        responseHeaders,
+        createDebugChannelSink,
+        getFirstDeniedSegmentIndex()
+      );
+    }
+    return renderDenyPage(
+      signals.denySignal,
+      segments,
+      layoutComponents as LayoutEntry[],
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      createDebugChannelSink,
+      callSsr,
+      undefined,
+      getFirstDeniedSegmentIndex()
+    );
+  }
+
+  // Synchronous render error — renderToReadableStream threw before
+  // creating the stream. Render the error page with correct 5xx status.
+  // (Async render errors are tracked in onError and handled after SSR.)
+  // An RSC payload request gets the hard-navigate envelope rather than an
+  // error page — `renderErrorPage` owns that branch, so every one of its call
+  // sites is covered rather than this one alone (TIM-1322).
+  if (signals.renderError && !rscStream) {
+    return renderErrorPage(
+      signals.renderError.error,
+      signals.renderError.status,
+      segments,
+      layoutComponents as LayoutEntry[],
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      globalError,
+      getFirstDeniedSegmentIndex()
+    );
+  }
+
+  // For RSC payload requests (client navigation), return the RSC Flight
+  // stream directly — skip SSR HTML rendering entirely.
+  // See design/19-client-navigation.md §"RSC Payload Handling"
+  if (isRscRequest(req)) {
+    return buildRscPayloadResponse(
+      req,
+      rscStream!,
+      signals,
+      segments,
+      layoutComponents,
+      responseHeaders,
+      skippedSegments,
+      slotSkipInfo
+    );
+  }
+
+  // Pipe through SSR for HTML rendering with streaming Suspense support.
+  return renderSsrResponse({
+    req,
+    rscStream: rscStream!,
+    signals,
+    segments,
+    layoutComponents,
+    match,
+    responseHeaders,
+    clientBootstrap,
+    clientJsDisabled,
+    headHtml,
+    deferSuspenseFor,
+    globalError,
+    slotSkipInfo,
+    debugRequestId,
+  });
+}

package/src/server/rsc-entry/revalidate-renderer.ts

@@ -0,0 +1,350 @@
+/**
+ * Revalidation renderer — builds the React element tree for the target
+ * path requested by `revalidatePath()` from inside a server action, with
+ * the same security guarantees as a normal route render.
+ *
+ * Before this module existed, `revalidatePath()` matched the route, coerced
+ * params, and called `buildRouteElement()` directly. That bypassed the
+ * target route's `middleware.ts` chain entirely. An action that revalidated
+ * a higher-privilege or user-controlled path could leak an authenticated
+ * RSC tree to the action submitter even when middleware on that path
+ * would have denied them.
+ *
+ * The fix (TIM-996) is to run the target route's middleware chain inside
+ * a fresh `runWithRequestContext` scope BEFORE building the element tree,
+ * propagate `DenySignal` and `RedirectSignal` to `executeAction`, drop the
+ * revalidation when middleware returns a short-circuit `Response`, and
+ * lift the request-header overlay onto the action's ALS store so the
+ * revalidated component render sees middleware-injected headers via
+ * `getHeaders()`.
+ *
+ * The input `path` is also validated as a local root-relative pathname so
+ * `revalidatePath('//evil.com/admin')` and similar scheme/authority
+ * injections cannot smuggle a foreign host through `new URL(path, base)`.
+ *
+ * See design/08-forms-and-actions.md §"revalidatePath()" and
+ * design/13-security.md §"Server actions silently bypass middleware".
+ */
+
+import { stringifyCookie } from 'cookie';
+
+import type { BuildManifest } from '../build-manifest.ts';
+import { canonicalize } from '../canonicalize.ts';
+import { getCookiesForSsr, seedRequestCookies } from '../cookie-context.ts';
+import { logRenderError } from '../logger.ts';
+import type { RouteMatch, RouteMatcher } from '../pipeline.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { applyRequestHeaderOverlay, setSegmentParams } from '../request-context.ts';
+import { requestContextAls } from '../als-registry.ts';
+import { buildRouteElement } from '../route-element-builder.ts';
+import type { RevalidateRenderer, RevalidationResult } from '../actions.ts';
+
+import { runMiddlewareForAction, type CoerceSegmentParamsFn } from './action-middleware-runner.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+
+/**
+ * Sentinel thrown when revalidation cannot proceed because middleware
+ * returned a short-circuit `Response` (a non-redirect HTTP response that
+ * we cannot translate back to an element tree). `executeAction` catches
+ * this and drops the revalidation — the action result is still delivered,
+ * but no `_tree` is piggybacked onto the response. The matching name
+ * `RevalidationDropped` is exported so callers can identify it via
+ * `instanceof` without leaking the message text to clients.
+ */
+export class RevalidationDropped extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RevalidationDropped';
+  }
+}
+
+/** Result of validating a `revalidatePath()` argument. */
+type PathValidation =
+  | { ok: true; pathname: string; search: string }
+  | { ok: false; reason: string };
+
+/**
+ * Validate a `revalidatePath()` argument.
+ *
+ * Accepts local root-relative pathnames only. Rejects anything that
+ * `new URL(path, base)` would resolve to a different host or scheme:
+ *
+ *   - Empty / non-string input
+ *   - Anything not starting with `/` (relative, scheme-bearing, etc.)
+ *   - Protocol-relative `//evil.com/admin` — resolves to scheme://evil.com
+ *   - Backslash-prefixed `/\evil.com` — some clients fold `\` into `/`
+ *   - Control characters and null bytes
+ *   - Paths that fail canonicalization (encoded separators, `..` escaping
+ *     root, malformed percent-encoding)
+ *
+ * The pathname is canonicalized so the rest of the renderer matches the
+ * same shape the page pipeline matches.
+ */
+export function validateRevalidatePath(path: unknown): PathValidation {
+  if (typeof path !== 'string' || path.length === 0) {
+    return { ok: false, reason: 'must be a non-empty string' };
+  }
+  if (!path.startsWith('/')) {
+    return { ok: false, reason: 'must start with "/" (root-relative path)' };
+  }
+  if (path.startsWith('//')) {
+    return { ok: false, reason: 'must not start with "//" (protocol-relative URL)' };
+  }
+  if (path.startsWith('/\\')) {
+    return { ok: false, reason: 'must not start with "/\\" (backslash injection)' };
+  }
+  for (let i = 0; i < path.length; i++) {
+    const code = path.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) {
+      return { ok: false, reason: 'must not contain control characters' };
+    }
+  }
+  const hashIndex = path.indexOf('#');
+  // Fragments are meaningless server-side and would not be sent back to
+  // the client on revalidation anyway. Drop them silently before splitting
+  // the query so a `#` cannot smuggle additional path content past the
+  // canonicalizer.
+  const noFragment = hashIndex >= 0 ? path.slice(0, hashIndex) : path;
+  const queryIndex = noFragment.indexOf('?');
+  const pathnameOnly = queryIndex >= 0 ? noFragment.slice(0, queryIndex) : noFragment;
+  const search = queryIndex >= 0 ? noFragment.slice(queryIndex) : '';
+  const canonical = canonicalize(pathnameOnly, true);
+  if (!canonical.ok) {
+    return { ok: false, reason: `failed URL canonicalization (status ${canonical.status})` };
+  }
+  return { ok: true, pathname: canonical.pathname, search };
+}
+
+/**
+ * Serialize a cookie map into a `Cookie:` request header value
+ * (`name1=value1; name2=value2`).
+ *
+ * The RYW map holds decoded logical values (decodeURIComponent has
+ * already run), so we use the default encode (encodeURIComponent) to
+ * re-encode for the wire — mirroring getCookieJar().toString().
+ *
+ * Total — never throws. Malformed inbound cookie names (e.g. spaces)
+ * survive parseCookie but make stringifyCookie throw, so we fall back
+ * to a manual join to stay total over arbitrary request headers.
+ */
+function serializeCookieMap(cookies: Map<string, string>): string {
+  try {
+    return stringifyCookie(Object.fromEntries(cookies));
+  } catch {
+    return Array.from(cookies.entries())
+      .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+      .join('; ');
+  }
+}
+
+/** Dependencies for the revalidate renderer factory. */
+export interface RevalidateRendererDeps {
+  matchRoute: RouteMatcher;
+  coerceSegmentParams: CoerceSegmentParamsFn;
+  buildManifest: BuildManifest;
+}
+
+/**
+ * Build a per-request `RevalidateRenderer`.
+ *
+ * The returned renderer:
+ *   1. Validates the requested path.
+ *   2. Matches the canonicalized path against the route tree.
+ *   3. Coerces segment params via the matched chain's `params.ts` codecs.
+ *   4. Runs the matched route's `middleware.ts` chain inside a fresh
+ *      `runWithRequestContext` scope (via `runMiddlewareForAction`).
+ *      Deny/redirect signals are re-thrown so `executeAction` can apply
+ *      its existing redirect handling and the new deny-drop behavior.
+ *      A short-circuit `Response` becomes `RevalidationDropped`.
+ *   5. Lifts the request-header overlay onto the OUTER action's ALS store
+ *      so the revalidated component render (which happens later inside
+ *      `renderToReadableStream` in the action's scope) observes
+ *      middleware-injected headers via `getHeaders()`. Acceptable because
+ *      revalidation runs after the action body has returned — the only
+ *      remaining ALS readers are render-phase code that should see the
+ *      same overlay a normal page render would see.
+ *   6. Builds and returns the route element tree, ready for the action
+ *      handler to serialize alongside the action result.
+ *
+ * Cookies set inside the revalidation middleware are intentionally NOT
+ * propagated to the action response. The middleware on a *different* path
+ * setting cookies via the action's response is surprising semantics; the
+ * scoped cookie jar on the inner ALS run is discarded with the scope.
+ * The primary security boundary closed here is auth — `deny()` from the
+ * target's middleware now prevents the revalidated tree from leaking.
+ */
+export function createRevalidateRendererFactory(
+  deps: RevalidateRendererDeps
+): (req: Request) => RevalidateRenderer {
+  return (req: Request): RevalidateRenderer => {
+    return async (path: string): Promise<RevalidationResult> => {
+      // ── 1. Validate the path ────────────────────────────────────────
+      const validation = validateRevalidatePath(path);
+      if (!validation.ok) {
+        // Throwing a typed error here drops the revalidation. We do not
+        // surface the message to the client (logRenderError sinks it).
+        const err = new RevalidationDropped(
+          `revalidatePath(${JSON.stringify(path)}) rejected: ${validation.reason}`
+        );
+        logRenderError({ method: req.method, path: new URL(req.url).pathname, error: err });
+        throw err;
+      }
+
+      // ── 2. Build the revalidation Request on the canonical pathname ─
+      //
+      // Use the canonical pathname (not the raw input) so the rebuilt
+      // URL cannot carry a hostile authority — `new URL('//evil.com/x',
+      // base)` would otherwise resolve to scheme://evil.com/x. Forward
+      // the original action request's headers (session IDs, accept-
+      // language, etc.) so middleware on the target route sees the same
+      // identity the action did.
+      //
+      // The `Cookie:` header is REBUILT from the action's
+      // read-your-own-writes cookie state rather than copied from the
+      // inbound request. An action that rotates the session via
+      // `getCookieJar().set('session', newToken)` and then calls
+      // `revalidatePath('/dashboard')` should have the target route's
+      // middleware see the NEW session — otherwise a session-rotation
+      // action would succeed only to have the piggybacked revalidation
+      // redirect to /login. `getCookieJar()` writes only update the ALS
+      // jar, not the immutable `Request.headers`, so without this step
+      // middleware reading `ctx.req.headers.get('cookie')` sees stale
+      // values. Codex P2.
+      const baseUrl = new URL(req.url);
+      const revalidateUrl = new URL(baseUrl.origin);
+      revalidateUrl.pathname = validation.pathname;
+      revalidateUrl.search = validation.search;
+      const revalidateHeaders = new Headers(req.headers);
+      revalidateHeaders.set('Accept', RSC_CONTENT_TYPE);
+      // Snapshot the action's post-mutation cookie map (deletions
+      // included) and serialize it into a `Cookie:` header value the
+      // target middleware can read off `ctx.req.headers.get('cookie')`.
+      // Only attempt this inside a request context — `getCookiesForSsr`
+      // throws otherwise — and bail out gracefully if no context is
+      // active (the legacy call-site contract permitted this).
+      const inRequestContext = Boolean(requestContextAls.getStore());
+      const ryw = inRequestContext ? getCookiesForSsr() : new Map<string, string>();
+      if (inRequestContext) {
+        if (ryw.size === 0) {
+          revalidateHeaders.delete('cookie');
+        } else {
+          revalidateHeaders.set('cookie', serializeCookieMap(ryw));
+        }
+      }
+      const revalidateReq = new Request(revalidateUrl.toString(), {
+        headers: revalidateHeaders,
+      });
+      // Seed the parsed map directly so the child `runWithRequestContext`
+      // inside `runMiddlewareForAction` skips `parseCookieHeader` — the
+      // same H-3 smuggling primitive mitigated by TIM-868. The Cookie
+      // header above remains in place for code that reads
+      // `ctx.req.headers.get('cookie')` directly.
+      if (inRequestContext) {
+        seedRequestCookies(revalidateReq, new Map(ryw));
+      }
+
+      // ── 3. Match the canonical path ─────────────────────────────────
+      const match = deps.matchRoute(validation.pathname);
+      if (!match) {
+        throw new Error(`revalidatePath('${path}') — no matching route`);
+      }
+
+      // ── 4. Run middleware in a fresh ALS scope ──────────────────────
+      //
+      // We only run middleware when the matched chain has at least one
+      // entry. Routes with no middleware skip this step (no scope, no
+      // overlay) — matching the page pipeline's behavior in
+      // `handleRequest` where `runMiddlewarePhase` is gated on
+      // `middlewareChain.length > 0`.
+      let overlay: Headers | undefined;
+      if (match.middlewareChain.length > 0) {
+        const outcome = await runMiddlewareForAction(
+          revalidateReq,
+          match,
+          deps.coerceSegmentParams
+        );
+
+        if (outcome.kind === 'param-coercion-error') {
+          // Bad params on the target path — drop revalidation. The
+          // action's own response still goes back to the client.
+          throw new RevalidationDropped(
+            `revalidatePath('${path}') — segment param coercion failed`
+          );
+        }
+        if (outcome.kind === 'error') {
+          // Re-throw unhandled middleware errors so `executeAction`'s
+          // existing `console.error` fallback logs them. Not surfaced
+          // to the action client (revalidation is best-effort).
+          throw outcome.error;
+        }
+        if (outcome.kind === 'redirect') {
+          // Propagate the redirect — `executeAction` catches
+          // RedirectSignal and converts it to an action-level redirect.
+          // See actions.ts §"Process path revalidation".
+          throw outcome.signal;
+        }
+        if (outcome.kind === 'deny') {
+          // Propagate the deny — `executeAction` catches DenySignal
+          // (added in this PR) and drops the revalidation.
+          throw outcome.signal;
+        }
+        if (outcome.kind === 'short-circuit') {
+          // Middleware returned a Response directly. A redirect Response
+          // (`return Response.redirect('/login')` or a 3xx + Location)
+          // is the same outcome as throwing `redirect()` — common for
+          // session-expiry / feature-flag gates — and the action client
+          // should follow it. Translate to a `RedirectSignal` so
+          // `executeAction` surfaces it as the action redirect, matching
+          // the normal page-pipeline behavior promised in
+          // design/08-forms-and-actions.md §"revalidatePath()". Codex P2.
+          const status = outcome.response.status;
+          const location = outcome.response.headers.get('location');
+          if (status >= 300 && status < 400 && location) {
+            throw new RedirectSignal(location, status);
+          }
+          // Any other short-circuit Response (200/403/418/etc.) cannot
+          // be translated to a piggy-backed element tree. Drop the
+          // revalidation; the action result still ships.
+          throw new RevalidationDropped(
+            `revalidatePath('${path}') — middleware returned a short-circuit Response (status ${status})`
+          );
+        }
+
+        // `continue` — capture the overlay so we can apply it to the
+        // action's request-context store below. We deliberately do NOT
+        // forward `outcome.cookies` or `outcome.setCookieHeaders` here;
+        // see the module docstring for why.
+        overlay = outcome.overlay;
+      } else {
+        // No middleware on the target — still coerce params so segment
+        // params reach `setSegmentParams` typed. `runMiddlewareForAction`
+        // would have done this for us; do it manually on the bypass path.
+        await deps.coerceSegmentParams(match);
+      }
+
+      // ── 5. Lift state onto the action's ALS store ───────────────────
+      //
+      // Segment params are set unconditionally so `getSegmentParams()`
+      // inside the revalidated tree returns the target path's coerced
+      // params, not the action route's. The overlay is applied only
+      // when middleware ran and produced headers — otherwise we leave
+      // the action's `headers()` view untouched.
+      setSegmentParams(match.segmentParams);
+      if (overlay) {
+        applyRequestHeaderOverlay(overlay);
+      }
+
+      // ── 6. Build the route element tree ─────────────────────────────
+      const routeResult = await buildRouteElement(
+        revalidateReq,
+        match,
+        undefined,
+        null,
+        deps.buildManifest.metadataRouteHashes
+      );
+      return {
+        payload: routeResult.payload,
+      };
+    };
+  };
+}