@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

package/src/server/pipeline.ts

@@ -42,6 +42,8 @@ import {
 } from './logger.js';
 import { callOnRequestError } from './instrumentation.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
+import { ParamCoercionError } from './route-element-builder.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
 import type { MiddlewareContext } from './types.js';
@@ -152,6 +154,42 @@ export interface PipelineConfig {
   ) => Response | Promise<Response>;
 }
 
+// ─── Param Coercion ────────────────────────────────────────────────────────
+
+/**
+ * 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"
+ */
+async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  const segments = match.segments as unknown as import('./route-matcher.js').ManifestSegmentNode[];
+
+  for (const segment of segments) {
+    // Only process segments that have a params.ts convention file
+    if (!segment.params) continue;
+
+    const mod = (await segment.params.load()) as Record<string, unknown>;
+    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.params);
+      // Merge coerced values back into match.params
+      Object.assign(match.params, coerced);
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
 // ─── Pipeline ──────────────────────────────────────────────────────────────
 
 /**
@@ -286,6 +324,24 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     }
   }
 
+  /**
+   * 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.
+   */
+  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 });
+  }
+
   async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
     // Stage 1: URL canonicalization
     const url = new URL(req.url);
@@ -342,6 +398,21 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // Stage 1c: Version skew detection (TIM-446).
+    // For RSC payload requests (client navigation), check if the client's
+    // deployment ID matches the current build. On mismatch, signal the
+    // client to do a full page reload instead of returning an RSC payload
+    // that references mismatched module IDs.
+    const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
+    if (isRscRequest) {
+      const skewCheck = checkVersionSkew(req);
+      if (!skewCheck.ok) {
+        const reloadHeaders = new Headers();
+        applyReloadHeaders(reloadHeaders);
+        return new Response(null, { status: 204, headers: reloadHeaders });
+      }
+    }
+
     // Stage 2: Route matching
     let match = matchRoute(canonicalPathname);
     let interception: InterceptionContext | undefined;
@@ -400,18 +471,37 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // Stage 2c: Param coercion (before middleware)
+    // Load params.ts modules from matched segments and coerce raw string
+    // params through defineSegmentParams codecs. Coercion failure → 404
+    // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
+    try {
+      await coerceSegmentParams(match);
+    } catch (error) {
+      if (error instanceof ParamCoercionError) {
+        return new Response(null, { status: 404 });
+      }
+      throw error;
+    }
+
     // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
     if (match.middleware) {
       const ctx: MiddlewareContext = {
         req,
         requestHeaders: requestHeaderOverlay,
         headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
+        segmentParams: match.params,
         earlyHints: (hints) => {
           for (const hint of hints) {
-            let value = `<${hint.href}>; rel=${hint.rel}`;
-            if (hint.as !== undefined) value += `; as=${hint.as}`;
+            // Match Cloudflare's cached Early Hints attribute order: `as` before `rel`.
+            // Cloudflare caches Link headers and re-emits them on subsequent 200s.
+            // If our order differs, the browser sees duplicate preloads and warns.
+            let value: string;
+            if (hint.as !== undefined) {
+              value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
+            } else {
+              value = `<${hint.href}>; rel=${hint.rel}`;
+            }
             if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
             if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
             responseHeaders.append('Link', value);
@@ -443,20 +533,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         applyRequestHeaderOverlay(requestHeaderOverlay);
       } catch (error) {
         setMutableCookieContext(false);
-        // RedirectSignal from middleware → HTTP redirect (not an error).
-        // For RSC payload requests (client navigation), return 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.
+        // RedirectSignal from middleware → HTTP redirect (not an error)
         if (error instanceof RedirectSignal) {
           applyCookieJar(responseHeaders);
-          const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-          if (isRsc) {
-            responseHeaders.set('X-Timber-Redirect', error.location);
-            return new Response(null, { status: 204, headers: responseHeaders });
-          }
-          responseHeaders.set('Location', error.location);
-          return new Response(null, { status: error.status, headers: responseHeaders });
+          return buildRedirectResponse(error, req, responseHeaders);
         }
         // DenySignal from middleware → HTTP deny status
         if (error instanceof DenySignal) {
@@ -493,17 +573,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       if (error instanceof DenySignal) {
         return new Response(null, { status: error.status });
       }
-      // RedirectSignal leaked from render — honour the redirect.
-      // For RSC payload requests, return 204 + X-Timber-Redirect so the
-      // client router can perform a soft SPA redirect (same as middleware path).
+      // RedirectSignal leaked from render — honour the redirect
       if (error instanceof RedirectSignal) {
-        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-        if (isRsc) {
-          responseHeaders.set('X-Timber-Redirect', error.location);
-          return new Response(null, { status: 204, headers: responseHeaders });
-        }
-        responseHeaders.set('Location', error.location);
-        return new Response(null, { status: error.status, headers: responseHeaders });
+        return buildRedirectResponse(error, req, responseHeaders);
       }
       logRenderError({ method, path, error });
       await fireOnRequestError(error, req, 'render');

package/src/server/request-context.ts

@@ -10,8 +10,6 @@
  * See design/29-cookies.md for cookie mutation semantics.
  */
 
-import { createHmac, timingSafeEqual } from 'node:crypto';
-import type { Routes } from '#/index.js';
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
 import { isDebug } from './debug.js';
 
@@ -22,30 +20,6 @@ export { requestContextAls };
 // the ALS context persists for the entire request lifecycle including
 // async stream consumption by React's renderToReadableStream.
 
-// ─── Cookie Signing Secrets ──────────────────────────────────────────────
-
-/**
- * Module-level cookie signing secrets. Index 0 is the newest (used for signing).
- * All entries are tried for verification (key rotation support).
- *
- * Set by the framework at startup via `setCookieSecrets()`.
- * See design/29-cookies.md §"Signed Cookies"
- */
-let _cookieSecrets: string[] = [];
-
-/**
- * Configure the cookie signing secrets.
- *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
- *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
- */
-export function setCookieSecrets(secrets: string[]): void {
-  _cookieSecrets = secrets.filter(Boolean);
-}
-
 // ─── Public API ───────────────────────────────────────────────────────────
 
 /**
@@ -109,12 +83,6 @@ export function cookies(): RequestCookies {
       return map.size;
     },
 
-    getSigned(name: string): string | undefined {
-      const raw = map.get(name);
-      if (!raw || _cookieSecrets.length === 0) return undefined;
-      return verifySignedCookie(raw, _cookieSecrets);
-    },
-
     set(name: string, value: string, options?: CookieOptions): void {
       assertMutable(store, 'set');
       if (store.flushed) {
@@ -127,21 +95,10 @@ export function cookies(): RequestCookies {
         }
         return;
       }
-      let storedValue = value;
-      if (options?.signed) {
-        if (_cookieSecrets.length === 0) {
-          throw new Error(
-            `[timber] cookies().set('${name}', ..., { signed: true }) requires ` +
-              `cookies.secret or cookies.secrets in timber.config.ts.`
-          );
-        }
-        storedValue = signCookieValue(value, _cookieSecrets[0]);
-      }
       const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };
-      store.cookieJar.set(name, { name, value: storedValue, options: opts });
-      // Read-your-own-writes: update the parsed cookies map with the signed value
-      // so getSigned() can verify it in the same request
-      map.set(name, storedValue);
+      store.cookieJar.set(name, { name, value, options: opts });
+      // Read-your-own-writes: update the parsed cookies map
+      map.set(name, value);
     },
 
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
@@ -190,43 +147,37 @@ export function cookies(): RequestCookies {
 }
 
 /**
- * Returns a Promise resolving to the current request's search params.
+ * Returns a Promise resolving to the current request's raw URLSearchParams.
+ *
+ * For typed, parsed search params, import the definition from params.ts
+ * and call `.load()` or `.parse()`:
  *
- * In `page.tsx`, `middleware.ts`, and `access.ts` the framework pre-parses the
- * route's `search-params.ts` definition and the Promise resolves to the typed
- * object. In all other server component contexts it resolves to raw
- * `URLSearchParams`.
+ * ```ts
+ * import { searchParams } from './params'
+ * const parsed = await searchParams.load()
+ * ```
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * Or explicitly:
+ *
+ * ```ts
+ * import { rawSearchParams } from '@timber-js/app/server'
+ * import { searchParams } from './params'
+ * const parsed = searchParams.parse(await rawSearchParams())
+ * ```
  *
  * Throws if called outside a request context.
  */
-export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>> {
+export function rawSearchParams(): Promise<URLSearchParams> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] searchParams() called outside of a request context. ' +
+      '[timber] rawSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
   return store.searchParamsPromise;
 }
 
-/**
- * Replace the search params Promise for the current request with one that
- * resolves to the typed parsed result from the route's search-params.ts.
- * Called by the framework before rendering the page — not for app code.
- */
-export function setParsedSearchParams(parsed: Record<string, unknown>): void {
-  const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
-  }
-}
-
 // ─── Types ────────────────────────────────────────────────────────────────
 
 /**
@@ -257,12 +208,6 @@ export interface CookieOptions {
   sameSite?: 'strict' | 'lax' | 'none';
   /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */
   partitioned?: boolean;
-  /**
-   * Sign the cookie value with HMAC-SHA256 for integrity verification.
-   * Requires `cookies.secret` or `cookies.secrets` in timber.config.ts.
-   * See design/29-cookies.md §"Signed Cookies".
-   */
-  signed?: boolean;
 }
 
 const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
@@ -287,14 +232,6 @@ export interface RequestCookies {
   getAll(): Array<{ name: string; value: string }>;
   /** Number of cookies. */
   readonly size: number;
-  /**
-   * Get a signed cookie value, verifying its HMAC-SHA256 signature.
-   * Returns undefined if the cookie is missing, the signature is invalid,
-   * or no secrets are configured. Never throws.
-   *
-   * See design/29-cookies.md §"Signed Cookies"
-   */
-  getSigned(name: string): string | undefined;
   /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
   set(name: string, value: string, options?: CookieOptions): void;
   /** Delete a cookie. Only available in mutable contexts. */
@@ -354,6 +291,35 @@ export function markResponseFlushed(): void {
   }
 }
 
+/**
+ * Build a Map of cookie name → value reflecting the current request's
+ * read-your-own-writes state. Includes incoming cookies plus any
+ * mutations from cookies().set() / cookies().delete() in the same request.
+ *
+ * Used by SSR renderers to populate NavContext.cookies so that
+ * useCookie()'s server snapshot matches the actual response state.
+ *
+ * See design/29-cookies.md §"Read-Your-Own-Writes"
+ * See design/triage/TIM-441-cookie-api-triage.md §4
+ */
+export function getCookiesForSsr(): Map<string, string> {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');
+  }
+
+  // Trigger lazy parsing if not yet done
+  if (!store.parsedCookies) {
+    store.parsedCookies = parseCookieHeader(store.cookieHeader);
+  }
+
+  // The parsedCookies map already reflects read-your-own-writes:
+  // - cookies().set() updates the map via map.set(name, value)
+  // - cookies().delete() removes from the map via map.delete(name)
+  // Return a copy so callers can't mutate the internal map.
+  return new Map(store.parsedCookies);
+}
+
 /**
  * Collect all Set-Cookie headers from the cookie jar.
  * Called by the framework at flush time to apply cookies to the response.
@@ -467,47 +433,6 @@ function parseCookieHeader(header: string): Map<string, string> {
   return map;
 }
 
-// ─── Cookie Signing ──────────────────────────────────────────────────────
-
-/**
- * Sign a cookie value with HMAC-SHA256.
- * Returns `value.hex_signature`.
- */
-function signCookieValue(value: string, secret: string): string {
-  const signature = createHmac('sha256', secret).update(value).digest('hex');
-  return `${value}.${signature}`;
-}
-
-/**
- * Verify a signed cookie value against an array of secrets.
- * Returns the original value if any secret produces a matching signature,
- * or undefined if none match. Uses timing-safe comparison.
- *
- * The signed format is `value.hex_signature` — split at the last `.`.
- */
-function verifySignedCookie(raw: string, secrets: string[]): string | undefined {
-  const lastDot = raw.lastIndexOf('.');
-  if (lastDot <= 0 || lastDot === raw.length - 1) return undefined;
-
-  const value = raw.slice(0, lastDot);
-  const signature = raw.slice(lastDot + 1);
-
-  // Hex-encoded SHA-256 is always 64 chars
-  if (signature.length !== 64) return undefined;
-
-  const signatureBuffer = Buffer.from(signature, 'hex');
-  // If the hex decode produced fewer bytes, the signature was not valid hex
-  if (signatureBuffer.length !== 32) return undefined;
-
-  for (const secret of secrets) {
-    const expected = createHmac('sha256', secret).update(value).digest();
-    if (timingSafeEqual(expected, signatureBuffer)) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
 /** Serialize a CookieEntry into a Set-Cookie header value. */
 function serializeCookieEntry(entry: CookieEntry): string {
   const parts = [`${entry.name}=${entry.value}`];