@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.171

package/src/server/param-coercion.ts

@@ -0,0 +1,207 @@
+/**
+ * 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 { Codec } from '../codec.js';
+import { toBracketKey } from '../params/resolve-schema.js';
+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';
+import { isDebug } from './debug.js';
+
+// ---------------------------------------------------------------------------
+// Module-level global codec store (TIM-931)
+// ---------------------------------------------------------------------------
+
+/** Global schema codecs, set once at startup from virtual:timber-schema. */
+let _globalCodecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the global schema codecs. Called once from the RSC entry
+ * at server startup when app/schema.ts provides segment param codecs.
+ * @internal
+ */
+export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _globalCodecs = codecs;
+}
+
+/**
+ * Coerce raw slot params through global schema codecs.
+ *
+ * Each slot segment that has a paramName is looked up in the global codec
+ * map by its bracket key (e.g. '[...year]' for catch-all). If a codec
+ * exists, the raw value is parsed through it. If no codec exists or no
+ * global codecs are registered, the raw value passes through unchanged.
+ *
+ * Unlike main route coercion, this does NOT throw ParamCoercionError on
+ * failure — slots degrade gracefully. A failed coercion logs a warning
+ * in dev mode and keeps the raw value.
+ *
+ * @internal — framework use only
+ */
+export function coerceSlotParams(
+  slotChain: Array<{ segmentType: string; paramName?: string }>,
+  rawParams: Record<string, string | string[]>
+): Record<string, string | string[]> {
+  const globalCodecs = _globalCodecs;
+  if (!globalCodecs) return rawParams;
+
+  const result: Record<string, string | string[]> = Object.create(null);
+  for (const key of Object.keys(rawParams)) {
+    result[key] = rawParams[key];
+  }
+
+  for (const segment of slotChain) {
+    if (!segment.paramName) continue;
+    const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+    const codec = globalCodecs[bracketKey];
+    if (!codec) continue;
+
+    const key = segment.paramName;
+    if (!(key in result)) continue;
+
+    try {
+      result[key] = sanitizeParamValue(codec.parse(result[key] as string | string[])) as
+        | string
+        | string[];
+    } catch (err) {
+      // Slot param coercion failures are non-fatal — keep the raw value.
+      // The main route already validated the URL; the slot just interprets
+      // the same parts differently.
+      if (isDebug()) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[timber] Slot param coercion failed for "${key}" (codec: ${bracketKey})\n` +
+            `  Error: ${message}\n` +
+            `  Raw value: ${JSON.stringify(result[key])}\n` +
+            `  Keeping raw value.`
+        );
+      }
+    }
+  }
+
+  return result as Record<string, string | string[]>;
+}
+
+/**
+ * Run segment param coercion on the matched route's segments.
+ *
+ * When `globalCodecs` is provided (from app/schema.ts), uses the global
+ * codec map keyed by bare param name. Otherwise falls back to loading
+ * per-segment params.ts modules.
+ *
+ * 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"
+ * See design/41-global-params.md §"Pipeline Integration"
+ */
+export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  const globalCodecs = _globalCodecs;
+  // 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'];
+
+  // TIM-931/TIM-936: When a global schema is available, use it for coercion
+  // instead of per-segment params.ts files. The global codec map is keyed
+  // by bracket name (e.g. '[id]', '[...slug]') to avoid collisions between
+  // distinct segment types that share a param name.
+  if (globalCodecs) {
+    for (const segment of match.segments) {
+      if (!segment.paramName) continue;
+      const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+      const codec = globalCodecs[bracketKey];
+      if (!codec) continue; // no codec in schema → keep raw string
+
+      const key = segment.paramName;
+      if (!(key in mergeTarget)) continue;
+      try {
+        mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key] as string | string[]));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isDebug()) {
+          console.warn(
+            `[timber] Global schema codec rejected value for param "${key}"\n` +
+              `  Error: ${message}\n` +
+              `  Raw value: ${JSON.stringify(mergeTarget[key])}\n` +
+              `  Hint: check the codec in app/schema.ts for key '${bracketKey}'.`
+          );
+        }
+        throw new ParamCoercionError(message);
+      }
+    }
+    return;
+  }
+
+  // Legacy path: per-segment params.ts coercion
+  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) {
+      const message = `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`;
+      if (isDebug()) {
+        console.warn(
+          `[timber] Param coercion error: ${message}\n` +
+            `  Segment: ${segment.segmentName}\n` +
+            `  Params file: ${segment.params}`
+        );
+      }
+      throw new ParamCoercionError(message);
+    }
+
+    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) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (isDebug()) {
+        const rawKeys = Object.keys(match.segmentParams).join(', ');
+        console.warn(
+          `[timber] Param codec rejected values for segment "${segment.segmentName}"\n` +
+            `  Error: ${message}\n` +
+            `  Available raw params: { ${rawKeys} }\n` +
+            `  Params file: ${segment.params}\n` +
+            `  Hint: this usually means a codec threw for the raw URL value.\n` +
+            `  Check that the regex/schema accepts the actual path segment string.`
+        );
+      }
+      throw new ParamCoercionError(message);
+    }
+  }
+}

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-interception.ts

@@ -9,12 +9,26 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
+import { classifyUrlSegment } from '../routing/segment-classify.js';
+
 /** Result of a successful interception match. */
 export interface InterceptionMatchResult {
   /** The pathname to re-match (the source/intercepting route's parent). */
   sourcePathname: string;
 }
 
+/**
+ * Check if a pathname starts with a prefix on a segment boundary.
+ *
+ * Prevents /feed from matching /feed-private — the prefix must be
+ * followed by '/' or be an exact match.
+ */
+function hasSegmentPrefix(pathname: string, prefix: string): boolean {
+  if (prefix === '/') return true;
+  if (!pathname.startsWith(prefix)) return false;
+  return pathname.length === prefix.length || pathname[prefix.length] === '/';
+}
+
 /**
  * Check if an intercepting route applies for this soft navigation.
  *
@@ -26,11 +40,12 @@ export interface InterceptionMatchResult {
 export function findInterceptionMatch(
   targetPathname: string,
   sourceUrl: string,
-  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
+  rewrites: import('../routing/interception.js').InterceptionRewrite[]
 ): InterceptionMatchResult | null {
   for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix
-    if (!sourceUrl.startsWith(rewrite.interceptingPrefix)) continue;
+    // Check if the source URL starts with the intercepting prefix,
+    // enforcing segment boundary to prevent /feed matching /feed-private.
+    if (!hasSegmentPrefix(sourceUrl, rewrite.interceptingPrefix)) continue;
 
     // Check if the target URL matches the intercepted pattern.
     // Dynamic segments in the pattern match any single URL segment.
@@ -53,23 +68,35 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   let pi = 0;
   for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
-
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
-    }
+    const seg = classifyUrlSegment(patternParts[i]);
 
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) return false;
-      pi++;
-      continue;
+    switch (seg.kind) {
+      case 'catch-all':
+        return pi < pathParts.length;
+      case 'optional-catch-all':
+        return true;
+      case 'dynamic': {
+        if (pi >= pathParts.length) return false;
+        const prefix = seg.prefix ?? '';
+        const suffix = seg.suffix ?? '';
+        const pathPart = pathParts[pi];
+        if (prefix || suffix) {
+          if (
+            pathPart.length <= prefix.length + suffix.length ||
+            (prefix && !pathPart.startsWith(prefix)) ||
+            (suffix && !pathPart.endsWith(suffix))
+          ) {
+            return false;
+          }
+        }
+        pi++;
+        continue;
+      }
+      case 'static':
+        if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
+        pi++;
+        continue;
     }
-
-    // Static — must match exactly
-    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
-    pi++;
   }
 
   return pi === pathParts.length;

package/src/server/pipeline-metadata.ts

@@ -41,6 +41,7 @@ export async function serveStaticMetadataFile(
   const headers: Record<string, string> = {
     'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
     'Content-Length': String(body.byteLength),
+    'Cache-Control': 'public, max-age=14400, must-revalidate',
   };
 
   return new Response(body, { status: 200, headers });
@@ -79,6 +80,19 @@ export function serializeSitemap(
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
 }
 
+/**
+ * Serialize a sitemap index (list of sub-sitemap URLs) to XML.
+ * Used for pagination when the total URL count exceeds 50,000.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export function serializeSitemapIndex(sitemapUrls: string[]): string {
+  const sitemaps = sitemapUrls
+    .map((url) => `  <sitemap>\n    <loc>${escapeXml(url)}</loc>\n  </sitemap>`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemaps}\n</sitemapindex>`;
+}
+
 /** Escape special XML characters. */
 export function escapeXml(str: string): string {
   return str