@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/server/request-context.ts

@@ -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 { _setRawSearchParamsFn } from '../search-params/define.js';
+import { _setRawSegmentParamsFn } 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 ───────────────────────────────────────────────────────────
 
 /**
@@ -109,12 +85,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 +97,33 @@ 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.`
-          );
+      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: cookies().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 {
@@ -190,41 +172,112 @@ 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;
 }
 
+// Eagerly register rawSearchParams with the search-params module so
+// searchParams.load() can call it synchronously without a dynamic import.
+// Dynamic imports lose ALS context in React's RSC Flight renderer,
+// breaking rawSearchParams() in parallel slot pages. See TIM-523.
+_setRawSearchParamsFn(rawSearchParams);
+
+// Eagerly register rawSegmentParams with the segment-params module so
+// segmentParams.load() can call it synchronously without a dynamic import.
+// Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
+_setRawSegmentParamsFn(rawSegmentParams);
+
+/**
+ * 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 { rawSegmentParams } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const { slug } = await rawSegmentParams()
+ *   // ...
+ * }
+ * ```
+ *
+ * Throws if called outside a request context.
+ */
+export function rawSegmentParams(): Promise<Record<string, string | string[]>> {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error(
+      '[timber] rawSegmentParams() 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] rawSegmentParams() called before route matching completed. ' +
+        'Segment params are not available until after the route is matched.'
+    );
+  }
+  return store.segmentParamsPromise;
+}
+
 /**
- * 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.
+ * 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 setParsedSearchParams(parsed: Record<string, unknown>): void {
+export function setSegmentParams(params: Record<string, string | string[]>): void {
   const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
+  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 +310,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 = {
@@ -272,6 +319,88 @@ const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
   sameSite: 'lax',
 };
 
+/**
+ * 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 `cookies()`.
  *
@@ -287,16 +416,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);
+   * cookies().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. */
@@ -316,11 +449,13 @@ export interface RequestCookies {
  */
 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 +489,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 +631,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}`];