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

package/src/server/param-coercion.ts

@@ -0,0 +1,76 @@
+/**
+ * Segment param coercion — runs the matched route's `params.ts` codecs
+ * over the raw matcher output before middleware and rendering.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the coercer can be
+ * imported directly by other entry points (the action-dispatch wrapper,
+ * the revalidation renderer in `rsc-entry/index.ts`) without pulling
+ * the entire pipeline phase module along with it.
+ *
+ * The function throws `ParamCoercionError` from `route-element-builder.ts`
+ * on any codec failure; the pipeline catches that and dispatches to the
+ * 404 page. See design/07-routing.md §"Where Coercion Runs".
+ */
+
+import type { RouteMatch } from './pipeline.js';
+import { sanitizeParamValue } from './pipeline-helpers.js';
+import { loadModule } from './safe-load.js';
+import { ParamCoercionError } from './route-element-builder.js';
+
+/**
+ * Run segment param coercion on the matched route's segments.
+ *
+ * Loads params.ts modules from segments that have them, extracts the
+ * segmentParams definition, and coerces raw string params through codecs.
+ * Throws ParamCoercionError if any codec fails (→ 404).
+ *
+ * This runs BEFORE middleware, so ctx.segmentParams is already typed.
+ * See design/07-routing.md §"Where Coercion Runs"
+ */
+export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  // Unconditionally install a null-prototype target so the invariant
+  // "match.segmentParams is null-prototype" holds from the first line,
+  // regardless of whether any segment has a codec.
+  const mergeTarget: Record<string, unknown> = Object.create(null);
+  for (const key of Object.keys(match.segmentParams)) {
+    if (key !== '__proto__') {
+      mergeTarget[key] = match.segmentParams[key as keyof typeof match.segmentParams];
+    }
+  }
+  match.segmentParams = mergeTarget as RouteMatch['segmentParams'];
+
+  for (const segment of match.segments) {
+    // Only process segments that have a params.ts convention file
+    if (!segment.params) continue;
+
+    let mod: Record<string, unknown>;
+    try {
+      mod = await loadModule(segment.params);
+    } catch (err) {
+      throw new ParamCoercionError(
+        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
+    const segmentParamsDef = mod.segmentParams as
+      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
+      | undefined;
+
+    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
+
+    try {
+      const coerced = segmentParamsDef.parse(match.segmentParams);
+
+      // Deep-sanitize codec output: every nested plain object becomes
+      // null-prototype with dangerous keys stripped at every depth.
+      // See TIM-873, design/13-security.md
+      for (const key of Object.keys(coerced as Record<string, unknown>)) {
+        if (key !== '__proto__') {
+          mergeTarget[key] = sanitizeParamValue((coerced as Record<string, unknown>)[key]);
+        }
+      }
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
+}

package/src/server/pipeline-helpers.ts

@@ -0,0 +1,204 @@
+/**
+ * Pipeline helpers — small utility functions used by `pipeline.ts` and
+ * `pipeline-phases.ts`. Lifted out of `pipeline.ts` to keep that file
+ * focused on the request handler entry point.
+ *
+ * Each helper is intentionally a free function with no closure capture, so
+ * it can be unit-tested in isolation.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import type { ProxyExport } from './proxy.js';
+import { getSetCookieHeaders } from './cookie-context.js';
+import { callOnRequestError } from './instrumentation.js';
+import { getTraceId } from './tracing.js';
+import { RedirectSignal } from './primitives.js';
+import type { ProxyConfig } from './pipeline.js';
+
+// ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
+
+/**
+ * Only __proto__ needs stripping — it has a language-level setter that
+ * changes the prototype chain of spread copies. constructor and prototype
+ * are harmless own properties on null-prototype objects.
+ */
+const DANGEROUS_KEYS = new Set(['__proto__']);
+
+/**
+ * Deep-walk a value returned by a segment param codec, producing a
+ * sanitized copy where every plain object is null-prototype and
+ * dangerous keys (__proto__, constructor, prototype) are stripped at
+ * every depth.
+ *
+ * Non-plain objects (Date, Map, class instances, etc.) are returned
+ * as-is — they cannot be poisoned by `{...x}` spread and may carry
+ * author-intended prototype methods.
+ *
+ * Arrays are walked element-wise.
+ *
+ * Performance: URL params are bounded by URL length (~8 KB). Realistic
+ * trees are <1 KB. The recursive walk is sub-microsecond.
+ *
+ * See TIM-655, TIM-855, TIM-873, design/13-security.md
+ */
+export function sanitizeParamValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sanitizeParamValue);
+  }
+
+  // Only walk plain objects — anything with a custom prototype (Date, Map,
+  // class instances) is left untouched.
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+
+  const out: Record<string, unknown> = Object.create(null);
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      out[key] = sanitizeParamValue((value as Record<string, unknown>)[key]);
+    }
+  }
+  return out;
+}
+
+// ─── Proxy Resolver ────────────────────────────────────────────────────────
+
+/**
+ * Resolver closure produced once at pipeline construction. The lazy variant
+ * still calls `loader()` per-request (HMR relies on re-importing), but the
+ * choice of which branch to take is made once, not on every request.
+ */
+export type ProxyResolver = () => ProxyExport | Promise<ProxyExport>;
+
+/**
+ * Build a proxy resolver closure from the declared source. Called exactly
+ * once at `createPipeline` setup time, so the hot path sees only the branch
+ * that corresponds to this pipeline's configured variant.
+ *
+ * Returns `null` when the app has no proxy.ts — the hot path short-circuits
+ * around `runProxyPhase` entirely in that case.
+ *
+ * Accepts the sugar form (a bare `ProxyExport` — function or function array)
+ * and normalises it to the static variant. Functions and arrays are
+ * structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
+ * so discrimination is unambiguous.
+ */
+export function makeProxyResolver(
+  proxy: ProxyConfig | ProxyExport | undefined
+): ProxyResolver | null {
+  if (proxy === undefined) return null;
+  // Sugar: a bare ProxyExport (function or function array) — treat as static.
+  if (typeof proxy === 'function' || Array.isArray(proxy)) {
+    const exp = proxy;
+    return () => exp;
+  }
+  if (proxy.kind === 'static') {
+    const exp = proxy.export;
+    return () => exp;
+  }
+  const loader = proxy.loader;
+  return async () => (await loader()).default;
+}
+
+// ─── Cookie / Header Helpers ───────────────────────────────────────────────
+
+/**
+ * Apply all Set-Cookie headers from the cookie jar to a Headers object.
+ * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
+ */
+export function applyCookieJar(headers: Headers): void {
+  for (const value of getSetCookieHeaders()) {
+    headers.append('Set-Cookie', value);
+  }
+}
+
+/**
+ * Merge framework-managed response headers onto a terminal response without
+ * overwriting headers the terminal response already set itself.
+ */
+export function mergeMissingHeaders(target: Headers, source: Headers): void {
+  const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));
+  for (const [key, value] of source.entries()) {
+    if (!existingKeys.has(key.toLowerCase())) {
+      target.append(key, value);
+    }
+  }
+}
+
+// ─── Mutable Response Cloning ──────────────────────────────────────────────
+
+/**
+ * Clone a Response into a fresh one whose header bag is guaranteed mutable.
+ *
+ * `Response.redirect()` and some platform-level passthrough responses (notably
+ * on Cloudflare Workers) return objects with frozen header bags. Calling
+ * `.set()` or `.append()` on them throws `TypeError: immutable`, which the
+ * pipeline can hit when it appends Set-Cookie or Server-Timing entries.
+ *
+ * The pipeline calls this at the producer sites where user-controlled
+ * responses enter the framework — `outcomeToResponse` for all phase outcomes,
+ * and `handleRequest` for metadata-route and auto-sitemap user handlers — so
+ * downstream code can write headers without runtime feature-detection.
+ *
+ * The clone is unconditional. This is a deliberate trade: we avoid a
+ * try/catch + thrown `TypeError` on every request (the previous probe-based
+ * approach paid that cost on the hot path) and accept one cheap Response
+ * rewrap at the framework boundary instead.
+ */
+export function cloneWithMutableHeaders(response: Response): Response {
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: new Headers(response.headers),
+  });
+}
+
+// ─── Redirect Builder ──────────────────────────────────────────────────────
+
+/**
+ * Build a redirect Response from a RedirectSignal.
+ *
+ * For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
+ * so the client router can perform a soft SPA redirect. A raw 302 would be
+ * turned into an opaque redirect by fetch({redirect:'manual'}), crashing
+ * createFromFetch. See design/19-client-navigation.md.
+ */
+export function buildRedirectResponse(
+  signal: RedirectSignal,
+  req: Request,
+  headers: Headers
+): Response {
+  const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+  if (isRsc) {
+    headers.set('X-Timber-Redirect', signal.location);
+    return new Response(null, { status: 204, headers });
+  }
+  headers.set('Location', signal.location);
+  return new Response(null, { status: signal.status, headers });
+}
+
+// ─── Instrumentation ───────────────────────────────────────────────────────
+
+/**
+ * Fire the user's onRequestError hook with request context.
+ * Extracts request info from the Request object and calls the instrumentation hook.
+ */
+export async function fireOnRequestError(
+  error: unknown,
+  req: Request,
+  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
+): Promise<void> {
+  const url = new URL(req.url);
+  const headersObj: Record<string, string> = {};
+  req.headers.forEach((v, k) => {
+    headersObj[k] = v;
+  });
+
+  await callOnRequestError(
+    error,
+    { method: req.method, path: url.pathname, headers: headersObj },
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
+  );
+}

package/src/server/pipeline-outcome.ts

@@ -0,0 +1,167 @@
+/**
+ * Pipeline outcome translator — converts a `PhaseOutcome` (the value
+ * each phase function returns) into a final `Response`.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the per-phase try /
+ * catch logic and the terminal Response-building logic each live in
+ * their own file. The phases produce values; this module is the single
+ * source of truth for how those values become wire responses.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import {
+  applyCookieJar,
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  fireOnRequestError,
+  mergeMissingHeaders,
+} from './pipeline-helpers.js';
+import {
+  logProxyError,
+  logMiddlewareError,
+  logMiddlewareShortCircuit,
+  logRenderError,
+} from './logger.js';
+import { markResponseFlushed } from './request-context.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
+import type { PipelineConfig, RouteMatch } from './pipeline.js';
+
+// ─── Phase Outcome ─────────────────────────────────────────────────────────
+
+export type PhaseName = 'proxy' | 'middleware' | 'render';
+
+export type PhaseOutcome =
+  | { kind: 'response'; phase: PhaseName; response: Response }
+  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
+  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
+  | { kind: 'error'; phase: PhaseName; error: unknown };
+
+export interface OutcomeContext {
+  req: Request;
+  method: string;
+  path: string;
+  responseHeaders?: Headers;
+  match?: RouteMatch;
+}
+
+// ─── Translator ────────────────────────────────────────────────────────────
+
+/**
+ * Terminal outcome handler — converts a `PhaseOutcome` into a final
+ * `Response`, applying cookies, building redirects, rendering deny pages
+ * and fallback error pages, and firing instrumentation hooks.
+ *
+ * This is the single source of truth for how phase outputs become wire
+ * responses; the per-phase try/catch blocks now produce values, not
+ * Responses, so the conversion logic lives in exactly one place.
+ */
+export async function outcomeToResponse(
+  config: PipelineConfig,
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext
+): Promise<Response> {
+  switch (outcome.kind) {
+    case 'response': {
+      // Clone unconditionally so downstream code (cookie/header merge,
+      // Server-Timing in createPipeline) can write headers without paying
+      // for a try/catch immutability probe per request. User middleware,
+      // proxy, and route code may all return `Response.redirect()` or
+      // platform-level responses with frozen header bags. See TIM-866.
+      const finalResponse = cloneWithMutableHeaders(outcome.response);
+
+      if (outcome.phase === 'proxy') return finalResponse;
+
+      if (outcome.phase === 'middleware' && ctx.responseHeaders) {
+        applyCookieJar(finalResponse.headers);
+        mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
+        logMiddlewareShortCircuit({
+          method: ctx.method,
+          path: ctx.path,
+          status: finalResponse.status,
+        });
+      }
+
+      if (outcome.phase === 'render') {
+        markResponseFlushed();
+      }
+
+      return finalResponse;
+    }
+
+    case 'redirect': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      return buildRedirectResponse(outcome.signal, ctx.req, headers);
+    }
+
+    case 'deny': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      if (config.renderDenyFallback) {
+        try {
+          // Clone user-supplied deny-page responses so downstream
+          // Server-Timing writes are safe against frozen header bags
+          // (e.g. user returned Response.redirect from the hook).
+          return cloneWithMutableHeaders(
+            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
+          );
+        } catch (denyRenderError) {
+          // Deny page rendering failed — log before falling through to bare response.
+          // Without this, a crashing deny page produces a blank response with zero
+          // server-side signal. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: denyRenderError });
+          await fireOnRequestError(denyRenderError, ctx.req, 'render');
+          if (config.onPipelineError && denyRenderError instanceof Error)
+            config.onPipelineError(denyRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      if (outcome.phase === 'proxy') {
+        logProxyError({ error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'proxy');
+        if (config.onPipelineError && outcome.error instanceof Error)
+          config.onPipelineError(outcome.error, 'proxy');
+        return new Response(null, { status: 500 });
+      }
+
+      if (outcome.phase === 'middleware') {
+        logMiddlewareError({ method: ctx.method, path: ctx.path, error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'handler');
+        if (config.onPipelineError && outcome.error instanceof Error) {
+          config.onPipelineError(outcome.error, 'middleware');
+        }
+        return new Response(null, { status: 500 });
+      }
+
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      logRenderError({ method: ctx.method, path: ctx.path, error: outcome.error });
+      await fireOnRequestError(outcome.error, ctx.req, 'render');
+      if (config.onPipelineError && outcome.error instanceof Error)
+        config.onPipelineError(outcome.error, 'render');
+      if (config.renderFallbackError) {
+        try {
+          // Clone user-supplied fallback error responses so downstream
+          // Server-Timing writes are safe against frozen header bags.
+          return cloneWithMutableHeaders(
+            await config.renderFallbackError(outcome.error, ctx.req, headers)
+          );
+        } catch (fallbackRenderError) {
+          // Fallback rendering itself failed — log the secondary error before
+          // falling through to bare 500. The original render error was already
+          // logged above; this captures the fallback renderer's own crash so it
+          // doesn't vanish silently. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: fallbackRenderError });
+          await fireOnRequestError(fallbackRenderError, ctx.req, 'render');
+          if (config.onPipelineError && fallbackRenderError instanceof Error)
+            config.onPipelineError(fallbackRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: 500 });
+    }
+  }
+}