@timber-js/app 0.2.0-alpha.98 → 0.2.0-alpha.99

package/src/cookies/define-cookie.ts

@@ -2,31 +2,27 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with async .getCookie(), .setCookie(), .deleteCookie() server methods
- * and a sync .useCookie() client hook.
+ * with sync .get(), .set(), .delete() isomorphic methods (server + client)
+ * and a .useCookie() client hook.
  *
- * Server methods are async to future-proof the API for v2 features
- * (signed cookies via crypto.subtle, encrypted cookies, external stores).
+ * Uses the registration pattern: server entry registers serverCookieImpl,
+ * client entry registers clientCookieImpl. This avoids top-level value
+ * imports from either environment and makes defineCookie isomorphic
+ * without `typeof window` checks.
  *
- * Reuses the SearchParamCodec protocol via fromSchema() bridge.
- * Validation on read returns the codec default (never throws).
- *
- * IMPORTANT: This module must NOT have top-level value imports from either
- * server or client modules. Server methods lazy-import request-context;
- * useCookie() lazy-imports use-cookie. This ensures:
- * - Client bundles don't pull in ALS/server code
- * - RSC bundles don't pull in useSyncExternalStore/client code
- * - Tree-shaking is not required for correctness
+ * 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 type { CookieOptions } from '../server/request-context.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';
 
 /**
  * A codec that converts between string cookie values and typed values.
@@ -35,46 +31,110 @@ import type { Codec } from '../codec.js';
 export type CookieCodec<T> = Codec<T>;
 
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends CookieOptions {
-  /** Codec for parsing/serializing the cookie value. */
-  codec: CookieCodec<T>;
+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. */
-  getCookie(): Promise<T>;
-  /** Server: set the typed value on the response. */
-  setCookie(value: T): Promise<void>;
-  /** Server: delete the cookie. */
-  deleteCookie(): Promise<void>;
+  /** Read the typed value. Sync, isomorphic (server + client). */
+  get(): T;
+  /** Set the typed value. Sync, isomorphic (server + client). */
+  set(value: T): void;
+  /** 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];
 }
 
-// ─── Lazy Module References ───────────────────────────────────────────────
+// ─── Registration Pattern ─────────────────────────────────────────────────
 //
-// These are resolved on first use, not at module load time. This prevents
-// the server module graph from pulling in client code and vice versa.
-// The dynamic import() in server methods is natural (they're async).
-// For useCookie() (sync), we cache the module reference after first load.
+// Server and client entries register their implementations at module load
+// time. This avoids dynamic imports (which lose ALS context) and typeof
+// window checks (which are fragile).
+
+/** Server-side cookie impl: reads from ALS-backed cookie jar. */
+export interface ServerCookieImpl {
+  getCookieJar(): {
+    get(name: string): string | undefined;
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+  };
+}
+
+/** Client-side cookie impl: reads/writes document.cookie via useCookie hook. */
+export interface ClientCookieImpl {
+  useCookie(
+    name: string,
+    options?: ClientCookieOptions
+  ): [string | undefined, (value: string, options?: ClientCookieOptions) => void, () => void];
+  getCookieValue(name: string): string | undefined;
+  setCookieValue(name: string, value: string, options?: ClientCookieOptions): void;
+  deleteCookieValue(name: string, options?: ClientCookieOptions): void;
+}
+
+let _serverImpl: ServerCookieImpl | undefined;
+let _clientImpl: ClientCookieImpl | undefined;
+let _fromSchemaFn: ((schema: StandardSchemaV1<unknown>) => CookieCodec<unknown>) | undefined;
+
+/**
+ * Register the server-side cookie implementation.
+ * Called by server entry at module load time.
+ * @internal
+ */
+export function _registerServerCookieImpl(impl: ServerCookieImpl): void {
+  _serverImpl = impl;
+}
 
+/**
+ * Register the client-side cookie implementation.
+ * Called by client entry at module load time.
+ * @internal
+ */
+export function _registerClientCookieImpl(impl: ClientCookieImpl): void {
+  _clientImpl = impl;
+}
+
+/**
+ * Register the fromSchema bridge function.
+ * Called by server/client entry at module load time.
+ * @internal
+ */
+export function _registerFromSchema(
+  fn: (schema: StandardSchemaV1<unknown>) => CookieCodec<unknown>
+): void {
+  _fromSchemaFn = fn;
+}
+
+// Legacy registration for useCookie module — still used by client/index.ts
 let _useCookieModule: typeof import('../client/use-cookie.js') | undefined;
 
 function getUseCookieModule(): typeof import('../client/use-cookie.js') {
   if (!_useCookieModule) {
-    // In the client/SSR environment, this module is already in the module
-    // graph (imported by the client entry). The throw is a safeguard —
-    // if useCookie() is somehow called before the module is available,
-    // the developer gets a clear error instead of a silent failure.
     throw new Error(
       '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +
         'This hook can only be used in client components.'
@@ -91,6 +151,68 @@ function getUseCookieModule(): typeof import('../client/use-cookie.js') {
  */
 export function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void {
   _useCookieModule = mod;
+  // Also register the client impl from the module
+  _clientImpl = {
+    useCookie: mod.useCookie,
+    getCookieValue: (name: string) => {
+      if (typeof document === 'undefined') return undefined;
+      const match = document.cookie.match(
+        new RegExp('(?:^|;\\s*)' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*=\\s*([^;]*)')
+      );
+      return match ? decodeURIComponent(match[1]) : undefined;
+    },
+    setCookieValue: (name: string, value: string, options?: ClientCookieOptions) => {
+      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('; ');
+      // Notify useCookie subscribers so mounted hooks re-render
+      mod.notifyCookieChange(name);
+    },
+    deleteCookieValue: (name: string, options?: ClientCookieOptions) => {
+      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;
+      mod.notifyCookieChange(name);
+    },
+  };
+}
+
+// ─── Standard Schema Auto-Detection ───────────────────────────────────────
+
+function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
+  // If it has parse + serialize, it's already a Codec
+  if (
+    typeof (codecOrSchema as Codec<T>).parse === 'function' &&
+    typeof (codecOrSchema as Codec<T>).serialize === 'function'
+  ) {
+    return codecOrSchema as CookieCodec<T>;
+  }
+
+  // Auto-detect Standard Schema
+  if (typeof codecOrSchema === 'object' && codecOrSchema !== null && '~standard' in codecOrSchema) {
+    if (!_fromSchemaFn) {
+      throw new Error(
+        '[timber] defineCookie: Standard Schema auto-detection requires @timber-js/app/server or ' +
+          '@timber-js/app/client to be loaded. Pass an explicit Codec<T> with parse/serialize methods, ' +
+          'or ensure the framework entry module is imported.'
+      );
+    }
+    return _fromSchemaFn(codecOrSchema as StandardSchemaV1<unknown>) as CookieCodec<T>;
+  }
+
+  throw new Error(
+    '[timber] defineCookie: codec must be a Codec<T> (with parse/serialize methods) ' +
+      'or a Standard Schema object (Zod, Valibot, ArkType).'
+  );
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────
@@ -100,78 +222,147 @@ export function _registerUseCookieModule(mod: typeof import('../client/use-cooki
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/codec';
  * 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
- * const theme = await themeCookie.getCookie();
- * await themeCookie.setCookie('dark');
+ * // Server or client
+ * const theme = themeCookie.get();
+ * themeCookie.set('dark');
  *
- * // Client
+ * // 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
+
+  function getClientOpts(): ClientCookieOptions {
+    return {
+      path: resolvedOptions.path,
+      domain: resolvedOptions.domain,
+      maxAge: resolvedOptions.maxAge,
+      expires: resolvedOptions.expires,
+      sameSite: resolvedOptions.sameSite,
+      secure: resolvedOptions.secure,
+    };
+  }
+
+  function assertNotHttpOnlyClient(method: string): void {
+    if (isHttpOnly && !_serverImpl) {
+      throw new Error(
+        `[timber] defineCookie('${name}').${method}() cannot be used with httpOnly cookies — ` +
+          `the browser cannot access them. Set httpOnly: false to enable client access.`
+      );
+    }
+  }
 
-  return {
+  const base: ServerOnlyCookieDefinition<T> = {
     name,
     options: resolvedOptions,
     codec,
 
-    async getCookie(): Promise<T> {
-      const { getCookies } = await import('../server/request-context.js');
-      const jar = await getCookies();
-      const raw = jar.get(name);
-      return codec.parse(raw);
+    get(): T {
+      if (_serverImpl) {
+        const jar = _serverImpl.getCookieJar();
+        const raw = jar.get(name);
+        return codec.parse(raw);
+      }
+      // Client path
+      assertNotHttpOnlyClient('get');
+      if (_clientImpl) {
+        const raw = _clientImpl.getCookieValue(name);
+        return codec.parse(raw);
+      }
+      throw new Error(
+        `[timber] defineCookie('${name}').get() — no environment registered. ` +
+          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'
+      );
     },
 
-    async setCookie(value: T): Promise<void> {
-      const { getCookies } = await import('../server/request-context.js');
-      const jar = await getCookies();
-      const serialized = codec.serialize(value);
-      if (serialized === null) {
+    set(value: T): void {
+      if (_serverImpl) {
+        const jar = _serverImpl.getCookieJar();
+        const serialized = codec.serialize(value);
+        if (serialized === null) {
+          jar.delete(name, {
+            path: resolvedOptions.path,
+            domain: resolvedOptions.domain,
+          });
+        } else {
+          jar.set(name, serialized, resolvedOptions);
+        }
+        return;
+      }
+      // Client path
+      assertNotHttpOnlyClient('set');
+      if (_clientImpl) {
+        const serialized = codec.serialize(value);
+        if (serialized === null) {
+          _clientImpl.deleteCookieValue(name, getClientOpts());
+        } else {
+          _clientImpl.setCookieValue(name, serialized, getClientOpts());
+        }
+        return;
+      }
+      throw new Error(
+        `[timber] defineCookie('${name}').set() — no environment registered. ` +
+          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'
+      );
+    },
+
+    delete(): void {
+      if (_serverImpl) {
+        const jar = _serverImpl.getCookieJar();
         jar.delete(name, {
           path: resolvedOptions.path,
           domain: resolvedOptions.domain,
         });
-      } else {
-        jar.set(name, serialized, resolvedOptions);
+        return;
+      }
+      // Client path
+      assertNotHttpOnlyClient('delete');
+      if (_clientImpl) {
+        _clientImpl.deleteCookieValue(name, getClientOpts());
+        return;
       }
+      throw new Error(
+        `[timber] defineCookie('${name}').delete() — no environment registered. ` +
+          'Ensure @timber-js/app/server or @timber-js/app/client is imported.'
+      );
     },
+  };
 
-    async deleteCookie(): Promise<void> {
-      const { getCookies } = await import('../server/request-context.js');
-      const jar = await getCookies();
-      jar.delete(name, {
-        path: resolvedOptions.path,
-        domain: resolvedOptions.domain,
-      });
-    },
+  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 { useCookie: useRawCookie } = getUseCookieModule();
 
-      // 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,
-      };
-
+      const clientOpts = getClientOpts();
       const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);
       const parsed = codec.parse(raw);
 
@@ -187,4 +378,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,12 +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';
 
-// Codec is the canonical home for the Codec type — import from
-// @timber-js/app/codec. Re-export removed per TIM-721.
-
-// cookies() is a server-only function (requires AsyncLocalStorage) and is
-// exported from @timber-js/app/server. It is intentionally NOT re-exported
-// here so that client-side code importing defineCookie doesn't pull in
-// server ALS code. See TIM-704.
+// 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);
+    },
+  };
+}