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

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -0,0 +1,167 @@
+/**
+ * Middleware-on-actions runner — runs the matched route's `middleware.ts`
+ * chain for an action POST inside its own `runWithRequestContext` scope
+ * and returns a `MiddlewareOutcome` value the dispatcher can translate.
+ *
+ * Lifted out of `wrap-action-dispatch.ts` (TIM-853) so the dispatcher
+ * can be read top-to-bottom without scrolling past the chain runner. The
+ * function is intentionally a free function (not a closure over deps)
+ * so it can be unit-tested in isolation. It does not import virtual
+ * modules and does not call into the action handler — it owns exactly
+ * the "run middleware once" step and nothing else.
+ *
+ * Failure modes are encoded as outcome variants rather than thrown so the
+ * caller never has to wrap this in try/catch. The only thrown errors are
+ * truly unexpected (programmer bugs) and propagate naturally.
+ *
+ * See TIM-871 for the full design rationale (closing the
+ * CVE-2025-29927-class bug where actions silently bypass middleware).
+ */
+
+import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.js';
+import {
+  applyRequestHeaderOverlay,
+  runWithRequestContext,
+  setMutableCookieContext,
+  setSegmentParams,
+} from '../request-context.js';
+import { runMiddlewareChain } from '../middleware-runner.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { ParamCoercionError } from '../route-element-builder.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { MiddlewareContext } from '../types.js';
+
+/** Coerce a matched route's segment params via its `params.ts` codecs. */
+export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;
+
+/**
+ * Outcome of running middleware on an action request, surfaced from the
+ * inner `runWithRequestContext` scope so the outer dispatcher can convert
+ * it to a Response (short-circuit) or continue to the action handler.
+ *
+ * Each variant carries the post-middleware Set-Cookie snapshot so the
+ * outer scope can apply cookies to whichever Response it ultimately
+ * returns. The middleware ALS scope ends before the action ALS scope
+ * begins, so cookie state must be threaded explicitly across the boundary
+ * via `seedRequestCookies` (cookie reads) and `setCookieHeaders` (cookie
+ * writes).
+ */
+export type MiddlewareOutcome =
+  | {
+      kind: 'continue';
+      overlay: Headers;
+      cookies: Map<string, string>;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'short-circuit';
+      response: Response;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'redirect';
+      signal: RedirectSignal;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'deny';
+      signal: DenySignal;
+      match: RouteMatch;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'param-coercion-error';
+    }
+  | {
+      kind: 'error';
+      error: unknown;
+    };
+
+/**
+ * Run the matched route's middleware chain inside a fresh request-context
+ * scope, captured as a `MiddlewareOutcome` value the outer dispatcher can
+ * translate to a Response or use as the seed for the action handler.
+ */
+export async function runMiddlewareForAction(
+  req: Request,
+  match: RouteMatch,
+  coerceSegmentParams: CoerceSegmentParamsFn
+): Promise<MiddlewareOutcome> {
+  return runWithRequestContext(req, async (): Promise<MiddlewareOutcome> => {
+    // ─── Coerce segment params (mirrors page pipeline) ──────────────
+    try {
+      await coerceSegmentParams(match);
+    } catch (err) {
+      if (err instanceof ParamCoercionError) {
+        return { kind: 'param-coercion-error' };
+      }
+      return { kind: 'error', error: err };
+    }
+    setSegmentParams(match.segmentParams);
+
+    // ─── Build the middleware context ───────────────────────────────
+    const responseHeaders = new Headers();
+    const requestHeaderOverlay = new Headers();
+    const ctx: MiddlewareContext = {
+      req,
+      requestHeaders: requestHeaderOverlay,
+      headers: responseHeaders,
+      segmentParams: match.segmentParams,
+      // 103 Early Hints are a page-render concern — server actions are
+      // RPC and never produce HTML, so there is nothing to hint about.
+      // Provide a no-op so user middleware can call `ctx.earlyHints()`
+      // unconditionally without branching on request kind.
+      earlyHints: () => {},
+    };
+
+    // ─── Run the chain ──────────────────────────────────────────────
+    setMutableCookieContext(true);
+    try {
+      let middlewareResponse: Response | undefined;
+      try {
+        middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+      } catch (err) {
+        if (err instanceof RedirectSignal) {
+          return {
+            kind: 'redirect',
+            signal: err,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        if (err instanceof DenySignal) {
+          return {
+            kind: 'deny',
+            signal: err,
+            match,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        return { kind: 'error', error: err };
+      }
+
+      if (middlewareResponse) {
+        return {
+          kind: 'short-circuit',
+          response: middlewareResponse,
+          setCookieHeaders: getSetCookieHeaders(),
+        };
+      }
+
+      // Middleware passed — apply the request-header overlay to the
+      // current scope so any code that might still read it within
+      // this scope sees the merged view. The overlay is also captured
+      // in the outcome so the caller can re-apply it inside the
+      // action's request-context scope (which is a separate ALS run).
+      applyRequestHeaderOverlay(requestHeaderOverlay);
+
+      return {
+        kind: 'continue',
+        overlay: requestHeaderOverlay,
+        cookies: getCookiesForSsr(),
+        setCookieHeaders: getSetCookieHeaders(),
+      };
+    } finally {
+      setMutableCookieContext(false);
+    }
+  });
+}

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

@@ -25,7 +25,7 @@ import { renderDenyPage } from '../deny-renderer.js';
 import type { LayoutEntry } from '../deny-renderer.js';
 import type { NavContext } from '../ssr-entry.js';
 import { createDebugChannelSink } from './helpers.js';
-import { getCookiesForSsr } from '../request-context.js';
+import { getCookiesForSsr } from '../cookie-context.js';
 import { callSsr } from './ssr-bridge.js';
 import { teeWithErrorPropagation } from '../stream-utils.js';
 import { isDevMode } from '../debug.js';

package/src/server/rsc-entry/helpers.ts

@@ -250,13 +250,8 @@ export function isAbortError(error: unknown): boolean {
   return false;
 }
 
-export function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// escapeHtml is now imported from server/utils/escape-html.ts
+export { escapeHtml } from '../utils/escape-html.js';
 
 /**
  * Parse a Cookie header string into a name→value Map.

package/src/server/rsc-entry/index.ts

@@ -34,23 +34,17 @@ import loadCacheHandler from 'virtual:timber-cache-handler';
 import { wrapPipelineWithActionDispatch } from './wrap-action-dispatch.js';
 import type { BodyLimitsConfig } from '../body-limits.js';
 import type { BuildManifest } from '../build-manifest.js';
-import {
-  buildFontPreloadTags,
-  buildModulepreloadTags,
-  collectRouteFonts,
-  collectRouteModulepreloads,
-} from '../build-manifest.js';
 import type { LayoutEntry } from '../deny-renderer.js';
 import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
-import { resolveLogMode } from '../dev-logger.js';
+import { resolveLogMode } from '../../dev-tools/logger.js';
 import { sendEarlyHints103 } from '../early-hints-sender.js';
 import { collectEarlyHintHeaders } from '../early-hints.js';
-import type { ClientBootstrapConfig } from '../html-injectors.js';
 import { buildClientScripts } from '../html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.js';
-import { createPipeline, coerceSegmentParams } from '../pipeline.js';
+import { createPipeline } from '../pipeline.js';
+import { coerceSegmentParams } from '../param-coercion.js';
 import { setSegmentParams } from '../request-context.js';
-import { buildRouteElement, ParamCoercionError } from '../route-element-builder.js';
+import { buildRouteElement } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
 import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
 import { initDevTracing } from '../tracing.js';
@@ -59,23 +53,16 @@ import { renderFallbackError as renderFallback } from '../fallback-error.js';
 import { loadInstrumentation } from '../instrumentation.js';
 import { loadModule } from '../safe-load.js';
 import { logRenderError } from '../logger.js';
-import { handleApiRoute } from './api-handler.js';
-import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
+import { renderNoMatchPage } from './error-renderer.js';
 import {
-  buildRedirectResponse,
   createDebugChannelSink,
-  escapeHtml,
   isRscPayloadRequest,
   type DebugComponentEntry,
 } from './helpers.js';
-import { parseClientStateTree } from '../state-tree-diff.js';
-import { buildRscPayloadResponse } from './rsc-payload.js';
-import { renderRscStream } from './rsc-stream.js';
-import { renderSsrResponse } from './ssr-renderer.js';
+import { renderRoute } from './render-route.js';
 import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
 import { setSourceMapCallback } from '../dev-source-map.js';
-import { recordTiming } from '../server-timing.js';
 import { requestContextAls } from '../als-registry.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
 
@@ -230,7 +217,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
       // Patch globalThis.fetch to create OTEL spans for fetch calls.
       // Spans appear as children of the active component span in the dev log tree.
-      const { instrumentDevFetch } = await import('../dev-fetch-instrumentation.js');
+      const { instrumentDevFetch } = await import('../../dev-tools/instrumentation.js');
       instrumentDevFetch();
     }
   }
@@ -274,11 +261,14 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         req,
         match,
         responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
-        interception,
-        manifest.root,
-        manifest.globalError
+        {
+          clientBootstrap,
+          clientJsDisabled,
+          rootSegment: manifest.root,
+          buildManifest: typedBuildManifest,
+          globalError: manifest.globalError,
+        },
+        interception
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
@@ -296,7 +286,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // should receive the bare 404 without an HTML body (TIM-793).
       const acceptsHtml = (req.headers.get('accept') ?? '').includes('text/html');
       if (isDev && !response.body && req.method === 'GET' && acceptsHtml) {
-        const { generateDev404Page, collectRoutes } = await import('../../plugins/dev-404-page.js');
+        const { generateDev404Page, collectRoutes } = await import('../../dev-tools/404-page.js');
         const routes = collectRoutes(manifest.root);
         const pathname = new URL(req.url).pathname;
         const html = generateDev404Page(pathname, routes);
@@ -420,8 +410,10 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   const pipeline = createPipeline(pipelineConfig);
 
   // Wrap the pipeline to enforce CSRF at the request boundary and intercept
-  // server action requests before rendering. Actions bypass the normal
-  // pipeline (no route matching, no middleware) per
+  // server action requests. By default, the wrapper also runs the matched
+  // route's `middleware.ts` chain on action POSTs, so authentication, rate
+  // limiting, tenant isolation, and request-header injection apply to
+  // actions just like they do to page renders. See TIM-871 and
   // design/08-forms-and-actions.md §"Middleware for Server Actions".
   //
   // CSRF validation lives in the wrapper (not inside the action handler) so
@@ -433,10 +425,23 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       | undefined,
   };
 
+  const actionsConfig = (runtimeConfig as Record<string, unknown>).actions as
+    | { runMiddleware?: boolean }
+    | undefined;
+
   return wrapPipelineWithActionDispatch(pipeline, {
     csrfConfig,
     bodyLimits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
     sensitiveFields: formsConfig?.stripSensitiveFields,
+    matchRoute,
+    coerceSegmentParams,
+    renderDenyFallback: pipelineConfig.renderDenyFallback,
+    runMiddleware: actionsConfig?.runMiddleware,
+    // Thread the pipeline's `stripTrailingSlash` setting into the wrapper
+    // so its canonicalization step (applied before `matchRoute` for
+    // action POSTs) matches the page pipeline exactly. Defaults to `true`
+    // both here and inside the wrapper.
+    stripTrailingSlash: pipelineConfig.stripTrailingSlash,
     buildRevalidateRenderer: (req) => async (path: string) => {
       // Build the React element tree for the route at `path`.
       // Returns the element tree (not serialized) so the action handler can
@@ -456,7 +461,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       await coerceSegmentParams(revalidateMatch);
       // Set coerced params in ALS so getSegmentParams() works during the
       // revalidation render (AccessGate reads params via ALS). Without this,
-      // AccessGate → getSegmentParams() throws because segmentParamsPromise
+      // AccessGate → getSegmentParams() throws because segmentParams
       // is never set. See TIM-667.
       setSegmentParams(revalidateMatch.segmentParams);
       const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
@@ -468,250 +473,6 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   });
 }
 
-/**
- * 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
- */
-async function renderRoute(
-  _req: Request,
-  match: RouteMatch,
-  responseHeaders: Headers,
-  clientBootstrap: ClientBootstrapConfig,
-  clientJsDisabled: boolean,
-  interception?: InterceptionContext,
-  rootSegment?: ManifestSegmentNode,
-  globalError?: { load: () => Promise<unknown>; filePath: string }
-): Promise<Response> {
-  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, match, 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 = isRscPayloadRequest(_req) ? parseClientStateTree(_req) : null;
-
-  // Build the React element tree — loads modules, collects access checks,
-  // resolves metadata. Access checks are NOT run here — they run inside
-  // AccessPreRunner during renderToReadableStream so that access.ts and
-  // render components share the same React.cache scope (TIM-662).
-  //
-  // DenySignal/RedirectSignal from access checks are caught by onError
-  // during stream consumption and handled by renderSsrResponse /
-  // buildRscPayloadResponse.
-  let routeResult;
-  const _buildStart = performance.now();
-  try {
-    routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
-  } catch (error) {
-    // Param coercion failed — render the custom 404 page (status files / not-found).
-    // Previously returned a bare Response(null, { status: 404 }) which bypassed
-    // custom not-found pages. Now routes through renderNoMatchPage so apps with
-    // 404.tsx / not-found status files 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 Error && error.message.startsWith('No page component')) {
-      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 { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
-    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.
-  const typedManifest = buildManifest as BuildManifest;
-  let headHtml = '';
-
-  // CSS is handled by the RSC plugin via ReactDOM.preinit() with
-  // data-precedence attributes. This injects <link rel="stylesheet">
-  // tags during the RSC render phase — before our headHtml injection.
-  // We do NOT emit additional <link rel="stylesheet"> tags here because:
-  // 1. React's Float system deduplicates them, making ours redundant
-  // 2. The duplicate reference confuses React's client-side preload
-  //    deduplication, causing "preload ignored" browser warnings
-  //
-  // CSS URLs are still collected for Early Hints (Link headers) in
-  // buildEarlyHintsHeaders() — those are HTTP headers, not DOM elements,
-  // so they don't conflict with Float.
-
-  // 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, typedManifest);
-  if (fontEntries.length > 0) {
-    headHtml += buildFontPreloadTags(fontEntries);
-  }
-
-  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
-  if (!clientJsDisabled) {
-    const preloadUrls = collectRouteModulepreloads(segments, typedManifest);
-    if (preloadUrls.length > 0) {
-      headHtml += buildModulepreloadTags(preloadUrls);
-    }
-  }
-
-  for (const el of headElements) {
-    if (el.tag === 'title' && el.content) {
-      headHtml += `<title>${escapeHtml(el.content)}</title>`;
-    } else if (el.attrs) {
-      const attrs = Object.entries(el.attrs)
-        .filter(([, v]) => v != null)
-        .map(([k, v]) => `${k}="${escapeHtml(v as string)}"`)
-        .join(' ');
-      headHtml += `<${el.tag} ${attrs}>`;
-    }
-  }
-
-  // In dev mode, inject the browser log forwarding script so console
-  // errors/warnings from the browser appear in the server terminal.
-  // Set by timber-dev-browser-logs plugin via globalThis (TIM-575).
-  if (isDevMode()) {
-    const devLogScript = (globalThis as Record<string, unknown>).__timber_dev_browser_log_script as
-      | string
-      | undefined;
-    if (devLogScript) {
-      headHtml += devLogScript;
-    }
-  }
-
-  // Render to RSC Flight stream with signal tracking.
-  const _rscStart = performance.now();
-  const { rscStream, signals, getDebugComponents } = renderRscStream(element, _req);
-
-  // 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(_req, signals.redirectSignal, responseHeaders);
-  }
-
-  // Synchronous deny — deny() in a non-async component throws during
-  // renderToReadableStream creation, caught in the try/catch above.
-  if (signals.denySignal) {
-    if (isRscPayloadRequest(_req)) {
-      return renderDenyPageAsRsc(
-        signals.denySignal,
-        segments,
-        layoutComponents as LayoutEntry[],
-        responseHeaders,
-        createDebugChannelSink
-      );
-    }
-    return renderDenyPage(
-      signals.denySignal,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap,
-      createDebugChannelSink,
-      callSsr
-    );
-  }
-
-  // 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.)
-  if (signals.renderError && !rscStream) {
-    return renderErrorPage(
-      signals.renderError.error,
-      signals.renderError.status,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap,
-      globalError
-    );
-  }
-
-  // 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 (isRscPayloadRequest(_req)) {
-    return buildRscPayloadResponse(
-      _req,
-      rscStream!,
-      signals,
-      segments,
-      layoutComponents,
-      headElements,
-      match,
-      responseHeaders,
-      skippedSegments
-    );
-  }
-
-  // Pipe through SSR for HTML rendering with streaming Suspense support.
-  return renderSsrResponse({
-    req: _req,
-    rscStream: rscStream!,
-    signals,
-    segments,
-    layoutComponents,
-    match,
-    responseHeaders,
-    clientBootstrap,
-    clientJsDisabled,
-    headHtml,
-    deferSuspenseFor,
-    globalError,
-  });
-}
-
 // Re-export for generated entry points (e.g., Nitro node-server/bun) to wrap
 // the handler with per-request 103 Early Hints sender via ALS.
 export { runWithEarlyHintsSender } from '../early-hints-sender.js';