@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/server/request-context.ts

@@ -1,5 +1,5 @@
 /**
- * Request Context — per-request ALS store for headers() and cookies().
+ * Request Context — per-request ALS store for getHeaders() and getCookies().
  *
  * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
  * instance, public accessor functions that throw outside request scope,
@@ -10,10 +10,10 @@
  * 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';
+import { _setGetSearchParamsFn } from '../search-params/define.js';
+import { _setGetSegmentParamsFn } from '../segment-params/define.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -22,30 +22,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 ───────────────────────────────────────────────────────────
 
 /**
@@ -54,15 +30,34 @@ export function setCookieSecrets(secrets: string[]): void {
  * Available in middleware, access checks, server components, and server actions.
  * Throws if called outside a request context (security principle #2: no global fallback).
  */
-export function headers(): ReadonlyHeaders {
+export function getHeaders(): Promise<ReadonlyHeaders> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] headers() called outside of a request context. ' +
+      '[timber] getHeaders() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.headers;
+  return Promise.resolve(store.headers);
+}
+
+/**
+ * Returns the value of a single request header, or undefined if absent.
+ *
+ * Thin wrapper over `(await getHeaders()).get(name)` for the common
+ * case where you need exactly one header.
+ *
+ * ```ts
+ * import { getHeader } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const auth = await getHeader('authorization');
+ * }
+ * ```
+ */
+export async function getHeader(name: string): Promise<string | undefined> {
+  const headers = await getHeaders();
+  return headers.get(name) ?? undefined;
 }
 
 /**
@@ -80,11 +75,11 @@ export function headers(): ReadonlyHeaders {
  *
  * See design/29-cookies.md
  */
-export function cookies(): RequestCookies {
+export function getCookies(): Promise<RequestCookies> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] cookies() called outside of a request context. ' +
+      '[timber] getCookies() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
@@ -95,7 +90,7 @@ export function cookies(): RequestCookies {
   }
 
   const map = store.parsedCookies;
-  return {
+  return Promise.resolve({
     get(name: string): string | undefined {
       return map.get(name);
     },
@@ -109,39 +104,45 @@ 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) {
         if (isDebug()) {
           console.warn(
-            `[timber] warn: cookies().set('${name}') called after response headers were committed.\n` +
+            `[timber] warn: getCookies().set('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
               `  or a route.ts handler.`
           );
         }
         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.`
-          );
+      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };
+      store.cookieJar.set(name, { name, value, options: opts });
+      // Read-your-own-writes: update the parsed cookies map
+      map.set(name, value);
+    },
+
+    setFromHeaders(headers: Headers): void {
+      assertMutable(store, 'setFromHeaders');
+      if (store.flushed) {
+        console.warn(
+          `[timber] warn: getCookies().setFromHeaders() called after response headers were committed.\n` +
+            `  The cookies will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
+            `  or a route.ts handler.`
+        );
+        return;
+      }
+      // Headers.getSetCookie() returns individual Set-Cookie strings,
+      // avoiding the fragile comma-splitting that raw .get() requires.
+      for (const raw of headers.getSetCookie()) {
+        const parsed = parseSetCookie(raw);
+        if (parsed) {
+          // Use setRaw to preserve the original header's attributes without
+          // merging DEFAULT_COOKIE_OPTIONS (parseSetCookie intentionally
+          // does not apply defaults — see its doc comment).
+          setRaw(store, map, parsed.name, parsed.value, parsed.options);
         }
-        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);
     },
 
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
@@ -149,7 +150,7 @@ export function cookies(): RequestCookies {
       if (store.flushed) {
         if (isDebug()) {
           console.warn(
-            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\n` +
+            `[timber] warn: getCookies().delete('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n` +
               `  or a route.ts handler.`
           );
@@ -186,45 +187,135 @@ export function cookies(): RequestCookies {
         .map(([name, value]) => `${name}=${value}`)
         .join('; ');
     },
-  };
+  });
+}
+
+/**
+ * Returns the value of a single cookie, or undefined if absent.
+ *
+ * Thin wrapper over `(await getCookies()).get(name)` for the common
+ * case where you need exactly one cookie.
+ *
+ * ```ts
+ * import { getCookie } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const session = await getCookie('session_id');
+ * }
+ * ```
+ */
+export async function getCookie(name: string): Promise<string | undefined> {
+  const cookies = await getCookies();
+  return cookies.get(name);
 }
 
 /**
- * Returns a Promise resolving to the current request's search params.
+ * Returns a Promise resolving to the current request's raw URLSearchParams.
  *
- * 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`.
+ * For typed, parsed search params, import the definition from params.ts
+ * and call `.load()` or `.parse()`:
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * ```ts
+ * import { searchParams } from './params'
+ * const parsed = await searchParams.get()
+ * ```
+ *
+ * Or explicitly:
+ *
+ * ```ts
+ * import { getSearchParams } from '@timber-js/app/server'
+ * import { searchParams } from './params'
+ * const parsed = searchParams.parse(await getSearchParams())
+ * ```
  *
  * 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 getSearchParams(): Promise<URLSearchParams> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] searchParams() called outside of a request context. ' +
+      '[timber] getSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
   return store.searchParamsPromise;
 }
 
+// Eagerly register getSearchParams with the search-params module so
+// searchParams.get() can call it synchronously without a dynamic import.
+// Dynamic imports lose ALS context in React's RSC Flight renderer,
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+_setGetSearchParamsFn(getSearchParams);
+
+// Eagerly register getSegmentParams with the segment-params module so
+// segmentParams.get() can call it synchronously without a dynamic import.
+// Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
+_setGetSegmentParamsFn(getSegmentParams);
+
 /**
- * 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.
+ * Returns a Promise resolving to the current request's coerced segment params.
+ *
+ * Segment params are set by the pipeline after route matching and param
+ * coercion (via params.ts codecs). When no params.ts exists, values are
+ * raw strings. When codecs are defined, values are already coerced
+ * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).
+ *
+ * This is the primary way page and layout components access route params:
+ *
+ * ```ts
+ * import { getSegmentParams } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const { slug } = await getSegmentParams()
+ *   // ...
+ * }
+ * ```
+ *
+ * Throws if called outside a request context.
  */
-export function setParsedSearchParams(parsed: Record<string, unknown>): void {
+export function getSegmentParams(): Promise<Record<string, string | string[]>> {
   const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
+  if (!store) {
+    throw new Error(
+      '[timber] getSegmentParams() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
   }
+  if (!store.segmentParamsPromise) {
+    throw new Error(
+      '[timber] getSegmentParams() called before route matching completed. ' +
+        'Segment params are not available until after the route is matched.'
+    );
+  }
+  return store.segmentParamsPromise;
+}
+
+/**
+ * Set the segment params promise on the current request context.
+ * Called by the pipeline after route matching and param coercion.
+ *
+ * @internal — framework use only
+ */
+export function setSegmentParams(params: Record<string, string | string[]>): void {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] setSegmentParams() called outside of a request context.');
+  }
+  store.segmentParamsPromise = Promise.resolve(params);
+}
+
+/**
+ * Returns the raw search string from the current request URL (e.g. "?foo=bar").
+ * Synchronous — safe for use in `redirect()` which throws synchronously.
+ *
+ * Returns empty string if called outside a request context (non-throwing for
+ * use in redirect's optional preserveSearchParams path).
+ *
+ * @internal — used by redirect() for preserveSearchParams support.
+ */
+export function getRequestSearchString(): string {
+  const store = requestContextAls.getStore();
+  return store?.searchString ?? '';
 }
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -257,12 +348,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 = {
@@ -273,7 +358,89 @@ const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
 };
 
 /**
- * Cookie accessor returned by `cookies()`.
+ * Write a cookie to the jar WITHOUT merging DEFAULT_COOKIE_OPTIONS.
+ * Used by setFromHeaders to preserve the original header's attributes exactly.
+ *
+ * For deletion cookies (maxAge=0), the jar entry is still created so the
+ * Set-Cookie header is emitted, but the cookie is NOT added to the read map
+ * (it would be misleading — the cookie is being deleted).
+ */
+function setRaw(
+  store: RequestContextStore,
+  readMap: Map<string, string>,
+  name: string,
+  value: string,
+  options: CookieOptions
+): void {
+  store.cookieJar.set(name, { name, value, options });
+  // Deletion cookies (Max-Age=0) should not appear in the read map
+  if (options.maxAge === 0) {
+    readMap.delete(name);
+  } else {
+    readMap.set(name, value);
+  }
+}
+
+/**
+ * Parse a raw `Set-Cookie` header string into name, value, and options.
+ * Handles all standard attributes: Path, Domain, Max-Age, Expires,
+ * SameSite, Secure, HttpOnly, Partitioned.
+ *
+ * Does NOT apply DEFAULT_COOKIE_OPTIONS — the caller decides whether
+ * to merge defaults (e.g. `set()` does, but `setRaw()` should preserve
+ * the original header's intent).
+ */
+function parseSetCookie(
+  header: string
+): { name: string; value: string; options: CookieOptions } | null {
+  const segments = header.split(';');
+  const nameValue = segments[0];
+  const eqIdx = nameValue.indexOf('=');
+  if (eqIdx <= 0) return null;
+
+  const name = nameValue.slice(0, eqIdx).trim();
+  const value = nameValue.slice(eqIdx + 1).trim();
+  const options: CookieOptions = {};
+
+  for (let i = 1; i < segments.length; i++) {
+    const seg = segments[i].trim();
+    if (!seg) continue;
+    const [attrName, ...rest] = seg.split('=');
+    const key = attrName.trim().toLowerCase();
+    const val = rest.join('=').trim();
+    switch (key) {
+      case 'path':
+        options.path = val || '/';
+        break;
+      case 'domain':
+        options.domain = val;
+        break;
+      case 'max-age':
+        options.maxAge = Number(val);
+        break;
+      case 'expires':
+        options.expires = new Date(val);
+        break;
+      case 'samesite':
+        options.sameSite = val.toLowerCase() as 'strict' | 'lax' | 'none';
+        break;
+      case 'secure':
+        options.secure = true;
+        break;
+      case 'httponly':
+        options.httpOnly = true;
+        break;
+      case 'partitioned':
+        options.partitioned = true;
+        break;
+    }
+  }
+
+  return { name, value, options };
+}
+
+/**
+ * Cookie accessor returned by `getCookies()`.
  *
  * Read methods are always available. Mutation methods throw in read-only
  * contexts (access.ts, server components).
@@ -287,16 +454,20 @@ export interface RequestCookies {
   getAll(): Array<{ name: string; value: string }>;
   /** Number of cookies. */
   readonly size: number;
+  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
+  set(name: string, value: string, options?: CookieOptions): void;
   /**
-   * 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.
+   * Copy all `Set-Cookie` headers from a `Headers` object.
+   * Parses each header and forwards name, value, and all attributes
+   * (path, domain, max-age, expires, sameSite, secure, httpOnly, partitioned).
    *
-   * See design/29-cookies.md §"Signed Cookies"
+   * Useful when forwarding cookies from an internal `fetch()` or auth handler:
+   * ```ts
+   * const response = await auth.handler(req);
+   * getCookies().then(c => c.setFromHeaders(response.headers));
+   * ```
    */
-  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;
+  setFromHeaders(headers: Headers): void;
   /** Delete a cookie. Only available in mutable contexts. */
   delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
   /** Delete all cookies. Only available in mutable contexts. */
@@ -309,18 +480,20 @@ export interface RequestCookies {
 
 /**
  * Run a callback within a request context. Used by the pipeline to establish
- * per-request ALS scope so that `headers()` and `cookies()` work.
+ * per-request ALS scope so that `getHeaders()` and `getCookies()` work.
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
+  const parsedUrl = new URL(req.url);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
     cookieHeader: req.headers.get('cookie') ?? '',
-    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),
+    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),
+    searchString: parsedUrl.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,
@@ -354,6 +527,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 getCookies().set() / getCookies().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:
+  // - getCookies().set() updates the map via map.set(name, value)
+  // - getCookies().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.
@@ -371,7 +573,7 @@ export function getSetCookieHeaders(): string[] {
  *
  * Called by the pipeline after middleware.ts runs. Merges overlay headers
  * on top of the original request headers so downstream code (access.ts,
- * server components, server actions) sees them via `headers()`.
+ * server components, server actions) sees them via `getHeaders()`.
  *
  * The original request headers are never mutated — a new frozen Headers
  * object is created with the overlay applied on top.
@@ -418,7 +620,7 @@ function freezeHeaders(source: Headers): Headers {
       if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {
         return () => {
           throw new Error(
-            `[timber] headers() returns a read-only Headers object. ` +
+            `[timber] getHeaders() returns a read-only Headers object. ` +
               `Calling .${prop}() is not allowed. ` +
               `Use ctx.requestHeaders in middleware to inject headers for downstream components.`
           );
@@ -440,7 +642,7 @@ function freezeHeaders(source: Headers): Headers {
 function assertMutable(store: RequestContextStore, method: string): void {
   if (!store.mutableContext) {
     throw new Error(
-      `[timber] cookies().${method}() cannot be called in this context.\n` +
+      `(timber] getCookies().${method}() cannot be called in this context.\n` +
         `  Set cookies in middleware.ts, server actions, or route.ts handlers.`
     );
   }
@@ -467,47 +669,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}`];