@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/cookies/define-cookie.ts

@@ -2,58 +2,154 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ * with sync .get(), .set(), .delete() isomorphic methods (server + client)
+ * and a .useCookie() client hook.
  *
- * Reuses the SearchParamCodec protocol via fromSchema() bridge.
- * Validation on read returns the codec default (never throws).
+ * Environment detection is call-time: on the server, getCookieJar() is
+ * used directly (ALS-backed). On the client, document.cookie helpers
+ * and the useCookie hook are used. No registration pattern — imports
+ * resolve via the shims plugin (client bundle gets a stub for
+ * @timber-js/app/server).
+ *
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in
+ * the codec option — no explicit fromSchema() wrapper needed.
  *
  * See design/29-cookies.md §"Typed Cookies with Schema Validation"
  */
 
-import { cookies } from '#/server/request-context.js';
-import type { CookieOptions } from '#/server/request-context.js';
-import { useCookie as useRawCookie } from '#/client/use-cookie.js';
-import type { ClientCookieOptions } from '#/client/use-cookie.js';
+import type { CookieOptions } from '../server/cookie-context.js';
+import type { ClientCookieOptions } from '../client/use-cookie.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
+import type { Codec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+import { resolveCodecOrSchema } from '../schema-bridge.js';
+
 /**
  * A codec that converts between string cookie values and typed values.
- * Intentionally identical to SearchParamCodec<T>.
+ * Type alias for the shared Codec<T> protocol.
  */
-export interface CookieCodec<T> {
-  parse(value: string | string[] | undefined): T;
-  serialize(value: T): string | null;
-}
+export type CookieCodec<T> = Codec<T>;
 
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
-  /** Codec for parsing/serializing the cookie value. */
-  codec: CookieCodec<T>;
-  /** Sign the cookie with HMAC-SHA256. */
-  signed?: boolean;
+export interface DefineCookieOptions<T, HttpOnly extends boolean = boolean> extends CookieOptions {
+  /**
+   * Codec for parsing/serializing the cookie value.
+   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)
+   * which is auto-wrapped via fromSchema.
+   */
+  codec: CookieCodec<T> | StandardSchemaV1<T>;
+  /**
+   * Prevent client-side JS access. Default: true.
+   * When true (or omitted), client methods (useCookie, get/set/delete on
+   * client) are omitted from the return type and throw at runtime.
+   */
+  httpOnly?: HttpOnly;
 }
 
-/** A fully typed cookie definition with server and client methods. */
-export interface CookieDefinition<T> {
-  /** The cookie name. */
+/**
+ * Server-only cookie definition. Returned when httpOnly is true or omitted.
+ * Client methods are absent from the type — accessing them is a TS error.
+ */
+export interface ServerOnlyCookieDefinition<T> {
   readonly name: string;
-  /** The resolved cookie options (without codec). */
   readonly options: CookieOptions;
-  /** The codec used for parsing/serializing. */
   readonly codec: CookieCodec<T>;
 
-  /** Server: read the typed value from the current request. */
+  /** Read the typed value. Sync, isomorphic (server + client). */
   get(): T;
-  /** Server: set the typed value on the response. */
+  /** Set the typed value. Sync, isomorphic (server + client). */
   set(value: T): void;
-  /** Server: delete the cookie. */
+  /** Delete the cookie. Sync, isomorphic (server + client). */
   delete(): void;
+}
 
+/**
+ * Full cookie definition with client methods. Returned when httpOnly: false.
+ */
+export interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {
   /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
   useCookie(): [T, (value: T) => void, () => void];
 }
 
+// ─── Direct Imports (no registration) ─────────────────────────────────────
+//
+// Server: getCookieJar is imported from @timber-js/app/server. In the client
+// bundle, the shims plugin replaces @timber-js/app/server with a stub module
+// where getCookieJar throws on call. We detect the environment at call time
+// by trying getCookieJar() — if it throws the stub error, we fall through
+// to the client path.
+//
+// Client: useCookie, getCookieValue, notifyCookieChange
+// are imported from use-cookie.ts. These are safe in all environments (no
+// node:async_hooks dependency).
+//
+// Schema: fromSchema is a pure function — safe in all environments.
+
+import { getCookieJar } from '@timber-js/app/server';
+import {
+  useCookie as useRawCookie,
+  notifyCookieChange,
+  getCookieValue,
+} from '../client/use-cookie.js';
+
+// ─── Environment Detection ────────────────────────────────────────────────
+
+/**
+ * Try to get the server cookie jar. Returns null if we're in the client
+ * environment (stub throws) or if there's no request context.
+ *
+ * On the server, getCookieJar() throws "outside of a request context" if
+ * called without an ALS store — this is a real error and is re-thrown.
+ * The client stub throws a different message — that's caught and returns null.
+ */
+function tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {
+  try {
+    return getCookieJar();
+  } catch (e) {
+    // Server-side "no request context" error — re-throw as a real bug.
+    if (e instanceof Error && e.message.includes('outside of a request context')) {
+      throw e;
+    }
+    // Client stub error or other — fall through to client path.
+    return null;
+  }
+}
+
+// ─── Client Cookie Helpers ────────────────────────────────────────────────
+
+/** Write a cookie via document.cookie and notify useCookie subscribers. */
+function setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {
+  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];
+  const path = options?.path ?? '/';
+  parts.push(`Path=${path}`);
+  if (options?.domain) parts.push(`Domain=${options.domain}`);
+  if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
+  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+  const sameSite = options?.sameSite ?? 'lax';
+  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+  if (options?.secure) parts.push('Secure');
+  document.cookie = parts.join('; ');
+  notifyCookieChange(name);
+}
+
+/** Delete a cookie via document.cookie and notify useCookie subscribers. */
+function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
+  const path = options?.path ?? '/';
+  const domain = options?.domain;
+  let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+  if (domain) cookieStr += `; Domain=${domain}`;
+  document.cookie = cookieStr;
+  notifyCookieChange(name);
+}
+
+// ─── Standard Schema Auto-Detection ───────────────────────────────────────
+
+function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
+  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;
+}
+
 // ─── Factory ──────────────────────────────────────────────────────────────
 
 /**
@@ -61,64 +157,130 @@ export interface CookieDefinition<T> {
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/search-params';
  * import { z } from 'zod/v4';
  *
+ * // httpOnly: false — client methods available
  * export const themeCookie = defineCookie('theme', {
- *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+ *   codec: z.enum(['light', 'dark', 'system']).default('system'),
  *   httpOnly: false,
  *   maxAge: 60 * 60 * 24 * 365,
  * });
+ *
+ * // Server or client
+ * const theme = themeCookie.get();
+ * themeCookie.set('dark');
+ *
+ * // Client hook
+ * const [theme, setTheme] = themeCookie.useCookie();
+ *
+ * // httpOnly: true (default) — server-only, no client methods
+ * export const sessionCookie = defineCookie('session', {
+ *   codec: z.string(),
+ * });
+ * sessionCookie.get();       // works on server
+ * sessionCookie.useCookie(); // TS error — httpOnly cookie
  * ```
  */
-export function defineCookie<T>(
+export function defineCookie<T, HttpOnly extends boolean = true>(
   name: string,
-  options: DefineCookieOptions<T>
-): CookieDefinition<T> {
-  const { codec, ...cookieOpts } = options;
+  options: DefineCookieOptions<T, HttpOnly>
+): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {
+  const { codec: codecOrSchema, ...cookieOpts } = options;
+  const codec = resolveCodec(codecOrSchema);
   const resolvedOptions: CookieOptions = { ...cookieOpts };
+  const isHttpOnly = options.httpOnly !== false; // default true
 
-  return {
+  function getClientOpts(): ClientCookieOptions {
+    return {
+      path: resolvedOptions.path,
+      domain: resolvedOptions.domain,
+      maxAge: resolvedOptions.maxAge,
+      expires: resolvedOptions.expires,
+      sameSite: resolvedOptions.sameSite,
+      secure: resolvedOptions.secure,
+    };
+  }
+
+  const base: ServerOnlyCookieDefinition<T> = {
     name,
     options: resolvedOptions,
     codec,
 
     get(): T {
-      const jar = cookies();
-      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        return codec.parse(serverJar.get(name));
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
+      const raw = getCookieValue(name);
       return codec.parse(raw);
     },
 
     set(value: T): void {
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        const serialized = codec.serialize(value);
+        if (serialized === null) {
+          serverJar.delete(name, {
+            path: resolvedOptions.path,
+            domain: resolvedOptions.domain,
+          });
+        } else {
+          serverJar.set(name, serialized, resolvedOptions);
+        }
+        return;
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
       const serialized = codec.serialize(value);
       if (serialized === null) {
-        cookies().delete(name, {
-          path: resolvedOptions.path,
-          domain: resolvedOptions.domain,
-        });
+        deleteClientCookie(name, getClientOpts());
       } else {
-        cookies().set(name, serialized, resolvedOptions);
+        setClientCookie(name, serialized, getClientOpts());
       }
     },
 
     delete(): void {
-      cookies().delete(name, {
-        path: resolvedOptions.path,
-        domain: resolvedOptions.domain,
-      });
+      const serverJar = tryGetServerCookieJar();
+      if (serverJar) {
+        serverJar.delete(name, {
+          path: resolvedOptions.path,
+          domain: resolvedOptions.domain,
+        });
+        return;
+      }
+      // Client path
+      if (isHttpOnly) {
+        throw new Error(
+          `[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — ` +
+            `the browser cannot access them. Set httpOnly: false to enable client access.`
+        );
+      }
+      deleteClientCookie(name, getClientOpts());
     },
+  };
 
-    useCookie(): [T, (value: T) => void, () => void] {
-      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)
-      const clientOpts: ClientCookieOptions = {
-        path: resolvedOptions.path,
-        domain: resolvedOptions.domain,
-        maxAge: resolvedOptions.maxAge,
-        expires: resolvedOptions.expires,
-        sameSite: resolvedOptions.sameSite,
-        secure: resolvedOptions.secure,
-      };
+  if (isHttpOnly) {
+    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;
+  }
 
+  // httpOnly: false — add useCookie client hook
+  const full: CookieDefinition<T> = {
+    ...base,
+
+    useCookie(): [T, (value: T) => void, () => void] {
+      const clientOpts = getClientOpts();
       const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);
       const parsed = codec.parse(raw);
 
@@ -134,4 +296,6 @@ export function defineCookie<T>(
       return [parsed, setTyped, deleteRaw];
     },
   };
+
+  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;
 }

package/src/cookies/index.ts

@@ -2,4 +2,15 @@
 // See design/29-cookies.md §"Typed Cookies with Schema Validation"
 
 export { defineCookie } from './define-cookie.js';
-export type { CookieDefinition, CookieCodec, DefineCookieOptions } from './define-cookie.js';
+export type {
+  CookieDefinition,
+  ServerOnlyCookieDefinition,
+  CookieCodec,
+  DefineCookieOptions,
+} from './define-cookie.js';
+
+// JSON-in-cookie helper. Wraps any JSON-serializable value with URL-encoding
+// so the stored form satisfies RFC 6265 §4.1.1 cookie-octet (the rule that
+// the framework now enforces in `getCookieJar().set()` to close TIM-868).
+// See ONGOING_SECURITY.md H-3 and design/29-cookies.md.
+export { jsonCookieCodec } from './json-cookie.js';

package/src/cookies/json-cookie.ts

@@ -0,0 +1,105 @@
+/**
+ * jsonCookieCodec — Codec helper for storing JSON-serializable values in
+ * cookies.
+ *
+ * The codec is intentionally minimal: `JSON.stringify` on serialize,
+ * `JSON.parse` on parse. The framework handles the URL encoding /
+ * decoding around it (see design/29-cookies.md §"Encoding Contract"):
+ *
+ *     defineCookie.setCookie(value)
+ *       → codec.serialize: JSON.stringify       → '{"a":1}'
+ *       → cookies().set: encodeURIComponent     → '%7B%22a%22%3A1%7D'
+ *       → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D
+ *
+ *     defineCookie.getCookie()
+ *       → wire: Cookie: prefs=%7B%22a%22%3A1%7D
+ *       → parseCookieHeader: decodeURIComponent → '{"a":1}'
+ *       → codec.parse: JSON.parse               → { a: 1 }
+ *
+ * The same chain works on the client: `useCookie` auto-encodes on writes
+ * and auto-decodes on reads, so `jsonCookieCodec` composes with both the
+ * server `defineCookie` methods and the client `useCookie` hook with no
+ * environment-specific branches.
+ *
+ * Parsing is total: any non-JSON value (or `undefined`) returns the
+ * supplied default. This matches the "never crash on user-controlled
+ * cookie input" semantics that `fromSchema` uses for typed search params.
+ *
+ * ```ts
+ * import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';
+ *
+ * interface Prefs { lang: string; fontSize: number }
+ *
+ * export const prefsCookie = defineCookie('prefs', {
+ *   codec: jsonCookieCodec<Prefs>({ lang: 'en', fontSize: 16 }),
+ *   httpOnly: false,
+ *   maxAge: 60 * 60 * 24 * 365,
+ * });
+ *
+ * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });
+ * ```
+ */
+
+import type { Codec } from '../codec.js';
+
+/**
+ * Build a CookieCodec that JSON-encodes the value. The framework's
+ * cookie write path then URL-encodes the JSON string into a valid
+ * `cookie-octet` form, and the read path reverses both transforms.
+ *
+ * @param defaultValue - Returned by `parse` when the cookie is missing
+ *   or the stored value cannot be JSON-parsed. Optional — if omitted,
+ *   `parse` returns `undefined` on missing/malformed input.
+ *
+ *   The default is **deep-cloned** on every fallback return via
+ *   `structuredClone`, so mutating the parsed result in one request
+ *   cannot leak into later requests that fall back to the same
+ *   default. This matters for long-lived server processes where a
+ *   codec is defined once at module load and shared across all
+ *   requests — without the clone, a user doing
+ *   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing
+ *   cookie would mutate the module-level default and poison every
+ *   later fallback. See the "shared mutable default" regression test
+ *   in `tests/define-cookie.test.ts`.
+ */
+export function jsonCookieCodec<T>(defaultValue?: T): Codec<T> {
+  // Resolve the fallback at call time, not capture time, so every
+  // fallback return produces a fresh deep copy. structuredClone handles
+  // nested objects, arrays, dates, maps, sets — everything
+  // JSON-serializable plus more. For primitives and undefined,
+  // structuredClone is effectively a no-op.
+  const cloneDefault = (): T => {
+    if (defaultValue === undefined || defaultValue === null) {
+      return defaultValue as T;
+    }
+    // structuredClone is a Node built-in since Node 17, available in
+    // all supported runtimes.
+    return structuredClone(defaultValue);
+  };
+
+  return {
+    parse(value: string | string[] | undefined): T {
+      if (value === undefined || value === '') {
+        return cloneDefault();
+      }
+      // Cookies are single-valued by name; defensively pick the last
+      // entry if a Codec consumer somehow passes an array.
+      const raw = Array.isArray(value) ? value[value.length - 1] : value;
+      if (raw === undefined || raw === '') {
+        return cloneDefault();
+      }
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return cloneDefault();
+      }
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      return JSON.stringify(value);
+    },
+  };
+}

package/src/cookies/validation.ts

@@ -0,0 +1,192 @@
+/**
+ * Cookie name and value validation per RFC 6265 §4.1.1.
+ *
+ * This module is pure — no server or client imports — so it can be loaded
+ * by both `server/request-context.ts` (which guards `getCookies().set()`)
+ * and `client/use-cookie.ts` (which guards `useCookie()`'s setter). The
+ * shared validator gives both sides identical encoding contracts:
+ * **the framework never silently encodes — callers emit `cookie-octet`
+ * bytes or get a developer-facing error.**
+ *
+ * Why this matters: see ONGOING_SECURITY.md H-3 (TIM-868) and
+ * design/29-cookies.md §"Cookie Name and Value Validation".
+ */
+
+// ─── RFC 6265 cookie-octet ────────────────────────────────────────────────
+//
+//   cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+//
+// Equivalently: US-ASCII printable bytes excluding whitespace, `"` (0x22),
+// `,` (0x2C), `;` (0x3B), `\` (0x5C), and DEL (0x7F).
+
+/**
+ * RFC 7230 §3.2.6 token characters used as the cookie-name production in
+ * RFC 6265 §4.1.1. Anchored, non-empty match.
+ *
+ * Allowed: US-ASCII letters, digits, and `!#$%&'*+-.^_` `` ` `` `|~`.
+ * Disallowed: whitespace, controls, delimiters
+ * (`(` `)` `<` `>` `@` `,` `;` `:` `\` `"` `/` `[` `]` `?` `=` `{` `}`).
+ */
+const COOKIE_NAME_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+
+/**
+ * Format a single byte for a clear error message — escape control bytes
+ * and non-ASCII as `0x..` and quote printables.
+ */
+function describeChar(value: string, index: number): string {
+  const code = value.charCodeAt(index);
+  if (code < 0x20 || code === 0x7f || code > 0x7e) {
+    return `0x${code.toString(16).padStart(2, '0')}`;
+  }
+  return JSON.stringify(value[index]);
+}
+
+/**
+ * Validate a cookie name against RFC 6265 §4.1.1 / RFC 7230 token rules.
+ * Throws a developer-facing error naming the offending byte and its index.
+ */
+export function assertValidCookieName(name: string): void {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('[timber] cookie name must be a non-empty string.');
+  }
+  if (!COOKIE_NAME_RE.test(name)) {
+    for (let i = 0; i < name.length; i++) {
+      if (!COOKIE_NAME_RE.test(name[i])) {
+        throw new Error(
+          `[timber] invalid cookie name ${JSON.stringify(name)} — ` +
+            `disallowed character ${describeChar(name, i)} at index ${i}. ` +
+            `Cookie names must match the RFC 6265 §4.1.1 token grammar (US-ASCII letters, digits, ` +
+            `and \`!#$%&'*+-.^_\`|~\`; no whitespace, controls, or delimiters).`
+        );
+      }
+    }
+    throw new Error(
+      `[timber] invalid cookie name ${JSON.stringify(name)} — ` +
+        `must match RFC 6265 §4.1.1 token grammar.`
+    );
+  }
+}
+
+/** Single-byte test for RFC 6265 §4.1.1 cookie-octet. */
+function isCookieOctet(code: number): boolean {
+  return (
+    code === 0x21 ||
+    (code >= 0x23 && code <= 0x2b) ||
+    (code >= 0x2d && code <= 0x3a) ||
+    (code >= 0x3c && code <= 0x5b) ||
+    (code >= 0x5d && code <= 0x7e)
+  );
+}
+
+/**
+ * Validate a cookie value against the RFC 6265 §4.1.1 `cookie-value`
+ * production:
+ *
+ *     cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
+ *     cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+ *
+ * Both the bare `*cookie-octet` form and the DQUOTE-wrapped form are
+ * valid. The wrapped form is common in upstream `Set-Cookie` headers
+ * (e.g. `sid="abc"; Path=/`) and must be forwardable through
+ * `setFromHeaders` verbatim — stripping or rejecting the surrounding
+ * quotes would corrupt the on-the-wire bytes and break value semantics
+ * for the upstream service.
+ *
+ * Excluded bytes (in either form): CTL, whitespace (CR/LF/TAB/SP),
+ * interior DQUOTE, comma, semicolon, backslash, DEL, and anything
+ * non-ASCII. The smuggling primitive (`;`) is rejected regardless of
+ * wrapping.
+ *
+ * Throws a developer-facing error naming the offending byte and its
+ * index. Callers passing user-controlled data through the default
+ * `set()` path don't need to call this — `set()` auto-encodes via
+ * `encodeURIComponent`, whose output is always valid cookie-octet.
+ * This validator is for the `{ raw: true }` opt-out and for
+ * `setFromHeaders` forwarding.
+ */
+// ─── Cookie attribute validation ──────────────────────────────────────────
+
+/**
+ * Characters that must not appear in path or domain cookie attributes.
+ * Semicolons delimit cookie attributes on the wire, so allowing `;` in
+ * path or domain would inject extra attributes. CR/LF enable HTTP header
+ * injection.
+ */
+const ATTR_INJECTION_RE = /[;\r\n]/;
+
+const VALID_SAME_SITE = new Set(['strict', 'lax', 'none']);
+
+/**
+ * Validate cookie option attributes at runtime to prevent Set-Cookie
+ * header injection through unsanitized option values.
+ *
+ * TypeScript types enforce correct shapes at compile time, but at runtime
+ * (e.g. from untyped libraries or user-controlled config) invalid values
+ * could inject additional Set-Cookie attributes.
+ */
+export function assertValidCookieOptions(options: {
+  sameSite?: string;
+  path?: string;
+  domain?: string;
+  maxAge?: number;
+}): void {
+  if (options.sameSite !== undefined) {
+    const lower = options.sameSite.toLowerCase();
+    if (!VALID_SAME_SITE.has(lower)) {
+      throw new Error(
+        `[timber] invalid cookie sameSite value ${JSON.stringify(options.sameSite)} — ` +
+          `must be 'strict', 'lax', or 'none'.`
+      );
+    }
+  }
+  if (options.path !== undefined && ATTR_INJECTION_RE.test(options.path)) {
+    throw new Error(
+      `[timber] invalid cookie path ${JSON.stringify(options.path)} — ` +
+        `path must not contain ';', CR, or LF (Set-Cookie header injection).`
+    );
+  }
+  if (options.domain !== undefined && ATTR_INJECTION_RE.test(options.domain)) {
+    throw new Error(
+      `[timber] invalid cookie domain ${JSON.stringify(options.domain)} — ` +
+        `domain must not contain ';', CR, or LF (Set-Cookie header injection).`
+    );
+  }
+  if (
+    options.maxAge !== undefined &&
+    (typeof options.maxAge !== 'number' || !Number.isFinite(options.maxAge))
+  ) {
+    throw new Error(
+      `[timber] invalid cookie maxAge ${JSON.stringify(options.maxAge)} — ` +
+        `maxAge must be a finite number.`
+    );
+  }
+}
+
+export function assertValidCookieValue(name: string, value: string): void {
+  if (typeof value !== 'string') {
+    throw new Error(`[timber] cookie ${JSON.stringify(name)}: cookie value must be a string.`);
+  }
+  // Detect the DQUOTE-wrapped form: at least two characters and both
+  // endpoints are `"`. The interior must be pure cookie-octet (no
+  // interior DQUOTEs allowed — the grammar says *cookie-octet, and
+  // cookie-octet excludes 0x22).
+  const wrapped =
+    value.length >= 2 &&
+    value.charCodeAt(0) === 0x22 &&
+    value.charCodeAt(value.length - 1) === 0x22;
+  const start = wrapped ? 1 : 0;
+  const end = wrapped ? value.length - 1 : value.length;
+  for (let i = start; i < end; i++) {
+    const code = value.charCodeAt(i);
+    if (!isCookieOctet(code)) {
+      throw new Error(
+        `[timber] cookie ${JSON.stringify(name)}: invalid cookie value — ` +
+          `disallowed character ${describeChar(value, i)} at index ${i}. ` +
+          `Cookie values must contain only RFC 6265 §4.1.1 cookie-octet bytes ` +
+          `(US-ASCII printable, excluding whitespace, \`"\`, \`,\`, \`;\`, and \`\\\`), ` +
+          `optionally enclosed in a single DQUOTE pair. ` +
+          `Encode the value (e.g. encodeURIComponent or jsonCookieCodec) before storing it.`
+      );
+    }
+  }
+}