@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/dist/_chunks/use-segment-params-D1CzlgBo.js

@@ -0,0 +1,151 @@
+import { a as _setCurrentParams, l as currentParams, n as getSsrData } from "./ssr-data-BOWsq18U.js";
+import React, { createElement } from "react";
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useSegmentParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in usePendingNavigation (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*
+* NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an
+* internal helper — the public hook is `usePendingNavigation()` in
+* use-pending-navigation.ts.
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useSegmentParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		params: {},
+		pathname: "/",
+		search: ""
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+//#endregion
+//#region src/client/use-segment-params.ts
+/**
+* Set the current route params in the module-level store.
+*
+* Called by the router on each navigation. This updates the fallback
+* snapshot used by tests and by the hook when called outside a React
+* component (no NavigationContext available).
+*
+* On the client, the primary reactivity path is NavigationContext —
+* the router calls setNavigationState() then renderRoot() which wraps
+* the element in NavigationProvider. setCurrentParams is still called
+* for the module-level fallback.
+*
+* During SSR, params are also available via getSsrData().params
+* (ALS-backed).
+*/
+function setCurrentParams(params) {
+	_setCurrentParams(params);
+}
+function useSegmentParams(_segmentPath) {
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return navContext.params;
+	} catch {}
+	return getSsrData()?.params ?? currentParams;
+}
+//#endregion
+export { setNavigationState as a, getNavigationState as i, useSegmentParams as n, useNavigationContext as o, NavigationProvider as r, setCurrentParams as t };
+
+//# sourceMappingURL=use-segment-params-D1CzlgBo.js.map

package/dist/_chunks/use-segment-params-D1CzlgBo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segment-params-D1CzlgBo.js","names":[],"sources":["../../src/client/navigation-context.ts","../../src/client/use-segment-params.ts"],"sourcesContent":["'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current route params and pathname, updated atomically\n * with the RSC tree on each navigation. This replaces the previous\n * useSyncExternalStore approach for useSegmentParams() and usePathname(),\n * which suffered from a timing gap: the new tree could commit before\n * the external store re-renders fired, causing a frame where both\n * old and new active states were visible simultaneously.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (useParams, usePathname) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, no NavigationProvider is mounted. Hooks fall back to\n * the ALS-backed getSsrData() for per-request isolation.\n *\n * IMPORTANT: createContext and useContext are NOT available in the RSC\n * environment (React Server Components use a stripped-down React).\n * The context is lazily initialized on first access, and all functions\n * that depend on these APIs are safe to call from any environment —\n * they return null or no-op when the APIs aren't available.\n *\n * SINGLETON GUARANTEE: All shared mutable state uses globalThis via\n * Symbol.for keys. The RSC client bundler can duplicate this module\n * across chunks (browser-entry graph + client-reference graph). With\n * ESM output, each chunk gets its own module scope — module-level\n * variables would create separate singleton instances per chunk.\n * globalThis guarantees a single instance regardless of duplication.\n *\n * This workaround will be removed when Rolldown ships `format: 'app'`\n * (module registry format that deduplicates like webpack/Turbopack).\n * See design/27-chunking-strategy.md.\n *\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport React, { createElement, type ReactNode } from 'react';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\nexport interface NavigationState {\n  params: Record<string, string | string[]>;\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * The context is created lazily to avoid calling createContext at module\n * level. In the RSC environment, React.createContext doesn't exist —\n * calling it at import time would crash the server.\n *\n * Context instances are stored on globalThis (NOT in module-level\n * variables) because the ESM bundler can duplicate this module across\n * chunks. Module-level variables would create separate instances per\n * chunk — the provider in NavigationRoot (index chunk) would use\n * context A while the consumer in usePendingNavigation (shared chunk)\n * reads from context B. globalThis guarantees a single instance.\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n *\n * NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an\n * internal helper — the public hook is `usePendingNavigation()` in\n * use-pending-navigation.ts.\n */\n\n// Symbol keys for globalThis storage — prevents collisions with user code\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\nconst PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');\n\nfunction getOrCreateContext(): React.Context<NavigationState | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | React.Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  // createContext may not exist in the RSC environment\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<NavigationState | null>(null);\n    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the navigation context. Returns null during SSR (no provider)\n * or in the RSC environment (no context available).\n * Internal — used by useSegmentParams() and usePathname().\n */\nexport function useNavigationContext(): NavigationState | null {\n  const ctx = getOrCreateContext();\n  if (!ctx) return null;\n  // useContext may not exist in the RSC environment — caller wraps in try/catch\n  if (typeof React.useContext !== 'function') return null;\n  // eslint-disable-next-line rules-of-hooks -- conditional on environment, not render path\n  return React.useContext(ctx);\n}\n\n// ---------------------------------------------------------------------------\n// Provider component\n// ---------------------------------------------------------------------------\n\nexport interface NavigationProviderProps {\n  value: NavigationState;\n  children?: ReactNode;\n}\n\n/**\n * Wraps children with NavigationContext.Provider.\n *\n * Used in browser-entry.ts renderRoot to wrap the RSC payload element\n * so that navigation state updates atomically with the tree render.\n */\nexport function NavigationProvider({\n  value,\n  children,\n}: NavigationProviderProps): React.ReactElement {\n  const ctx = getOrCreateContext();\n  if (!ctx) {\n    // RSC environment — no context available. Return children as-is.\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending Navigation Context (same module for singleton guarantee)\n// ---------------------------------------------------------------------------\n\n/**\n * Separate context for the in-flight navigation URL. Provided by\n * NavigationRoot (urgent useState), consumed by usePendingNavigation\n * and TopLoader. Per-link pending state uses useOptimistic instead\n * (see link-pending-store.ts).\n *\n * Uses globalThis via Symbol.for for the same reason as NavigationContext\n * above — the bundler may duplicate this module across chunks, and module-\n * level variables would create separate context instances.\n */\n\nfunction getOrCreatePendingContext(): React.Context<string | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as\n    | React.Context<string | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<string | null>(null);\n    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the pending navigation URL from context.\n * Returns null during SSR (no provider) or in the RSC environment.\n */\nexport function usePendingNavigationUrl(): string | null {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) return null;\n  if (typeof React.useContext !== 'function') return null;\n  // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n  return React.useContext(ctx);\n}\n\n/**\n * Provider for the pending navigation URL. Wraps children with\n * the pending context Provider.\n */\nexport function PendingNavigationProvider({\n  value,\n  children,\n}: {\n  value: string | null;\n  children?: ReactNode;\n}): React.ReactElement {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) {\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Navigation API transition state (optional progressive enhancement)\n// ---------------------------------------------------------------------------\n\n/**\n * Check if the browser's Navigation API has an active transition.\n *\n * When the Navigation API is available and a navigation has been intercepted\n * via event.intercept(), `navigation.transition` is non-null until the\n * handler resolves. This provides browser-native progress tracking that\n * can be used alongside the existing pendingUrl mechanism.\n *\n * Returns false when Navigation API is unavailable or no transition is active.\n */\nexport function hasNativeNavigationTransition(): boolean {\n  if (typeof window === 'undefined') return false;\n  const nav = (window as unknown as { navigation?: { transition?: unknown } }).navigation;\n  return nav?.transition != null;\n}\n","/**\n * useParams() — client-side hook for accessing route params.\n *\n * Returns the dynamic route parameters for the current URL.\n * When called with a route pattern argument, TypeScript narrows\n * the return type to the exact params shape for that route.\n *\n * Two layers of type narrowing work together:\n * 1. The generic overload here uses the Routes interface directly —\n *    `useParams<R>()` returns `Routes[R]['segmentParams']`.\n * 2. Build-time codegen generates per-route string-literal overloads\n *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).\n *\n * When the Routes interface is empty (no codegen yet), the generic\n * overload has `keyof Routes = never`, so only the fallback matches.\n *\n * During SSR, params are read from the ALS-backed SSR data context\n * (populated by ssr-entry.ts) to ensure correct per-request isolation\n * across concurrent requests with streaming Suspense.\n *\n * Reactivity: On the client, useParams() reads from NavigationContext\n * which is updated atomically with the RSC tree render. This replaces\n * the previous useSyncExternalStore approach that suffered from a\n * timing gap between tree render and store notification — causing\n * preserved layout components to briefly show stale active state.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n *\n * Design doc: design/09-typescript.md §\"Typed Routes\"\n */\n\nimport type { Routes } from '../index.js';\nimport { getSsrData } from './ssr-data.js';\nimport { currentParams, _setCurrentParams, paramsListeners } from './state.js';\nimport { useNavigationContext } from './navigation-context.js';\n\n// ---------------------------------------------------------------------------\n// Module-level subscribe/notify pattern — kept for backward compat and tests\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribe to params changes.\n * Retained for backward compatibility with tests that verify the\n * subscribe/notify contract. On the client, useParams() reads from\n * NavigationContext instead.\n */\nexport function subscribe(callback: () => void): () => void {\n  paramsListeners.add(callback);\n  return () => paramsListeners.delete(callback);\n}\n\n/**\n * Get the current params snapshot (module-level fallback).\n * Used by tests and by the hook when called outside a React component.\n */\nexport function getSnapshot(): Record<string, string | string[]> {\n  return currentParams;\n}\n\n// ---------------------------------------------------------------------------\n// Framework API — called by the segment router on each navigation\n// ---------------------------------------------------------------------------\n\n/**\n * Set the current route params in the module-level store.\n *\n * Called by the router on each navigation. This updates the fallback\n * snapshot used by tests and by the hook when called outside a React\n * component (no NavigationContext available).\n *\n * On the client, the primary reactivity path is NavigationContext —\n * the router calls setNavigationState() then renderRoot() which wraps\n * the element in NavigationProvider. setCurrentParams is still called\n * for the module-level fallback.\n *\n * During SSR, params are also available via getSsrData().params\n * (ALS-backed).\n */\nexport function setCurrentParams(params: Record<string, string | string[]>): void {\n  _setCurrentParams(params);\n}\n\n/**\n * Notify all legacy subscribers that params have changed.\n *\n * Retained for backward compatibility with tests. On the client,\n * the NavigationContext + renderRoot pattern replaces this — params\n * update atomically with the tree render, so explicit notification\n * is no longer needed.\n */\nexport function notifyParamsListeners(): void {\n  for (const listener of paramsListeners) {\n    listener();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public hook\n// ---------------------------------------------------------------------------\n\n/**\n * Read the current route's dynamic params.\n *\n * The optional `_route` argument exists only for TypeScript narrowing —\n * it does not affect the runtime return value.\n *\n * On the client, reads from NavigationContext (provided by\n * NavigationProvider in renderRoot). This ensures params update\n * atomically with the RSC tree — no timing gap.\n *\n * During SSR, reads from the ALS-backed SSR data context to ensure\n * per-request isolation across concurrent requests with streaming Suspense.\n *\n * When called outside a React component (e.g., in test assertions),\n * falls back to the module-level snapshot.\n *\n * @overload Typed — when a known segment path is passed, returns the\n *   exact params shape from the generated Routes interface.\n * @overload Fallback — returns the generic params record.\n */\nexport function useSegmentParams<R extends keyof Routes>(\n  segmentPath: R\n): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;\nexport function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;\nexport function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {\n  // Try reading from NavigationContext (client-side, inside React tree).\n  // During SSR, no NavigationProvider is mounted, so this returns null.\n  // When called outside a React component, useContext throws — caught below.\n  try {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n    const navContext = useNavigationContext();\n    if (navContext !== null) {\n      return navContext.params;\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n    // Fall through to module-level snapshot below.\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  // Falls back to module-level currentParams for tests.\n  return getSsrData()?.params ?? currentParams;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAM,cAAc,OAAO,IAAI,kBAAkB;AAGjD,SAAS,qBAAwE;CAC/E,MAAM,WAAY,WAAuC;CAGzD,IAAI,aAAa,KAAA,GAAW,OAAO;CAEnC,IAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAAsC,IAAI;EAC5D,WAAwC,eAAe;EACvD,OAAO;CACT;AAEF;;;;;;AAOA,SAAgB,uBAA+C;CAC7D,MAAM,MAAM,mBAAmB;CAC/B,IAAI,CAAC,KAAK,OAAO;CAEjB,IAAI,OAAO,MAAM,eAAe,YAAY,OAAO;CAEnD,OAAO,MAAM,WAAW,GAAG;AAC7B;;;;;;;AAiBA,SAAgB,mBAAmB,EACjC,OACA,YAC8C;CAC9C,MAAM,MAAM,mBAAmB;CAC/B,IAAI,CAAC,KAEH,OAAO;CAET,OAAO,cAAc,IAAI,UAAU,EAAE,MAAM,GAAG,QAAQ;AACxD;;;;;;;;;;;;;;AAmBA,IAAM,gBAAgB,OAAO,IAAI,oBAAoB;AAErD,SAAS,oBAAkD;CACzD,MAAM,IAAI;CACV,IAAI,CAAC,EAAE,gBACL,EAAE,iBAAiB,EAAE,SAAS;EAAE,QAAQ,CAAC;EAAG,UAAU;EAAK,QAAQ;CAAG,EAAE;CAE1E,OAAO,EAAE;AACX;AAEA,SAAgB,mBAAmB,OAA8B;CAC/D,kBAAkB,EAAE,UAAU;AAChC;AAEA,SAAgB,qBAAsC;CACpD,OAAO,kBAAkB,EAAE;AAC7B;;;;;;;;;;;;;;;;;;ACzFA,SAAgB,iBAAiB,QAAiD;CAChF,kBAAkB,MAAM;AAC1B;AA4CA,SAAgB,iBAAiB,cAA0D;CAIzF,IAAI;EAEF,MAAM,aAAa,qBAAqB;EACxC,IAAI,eAAe,MACjB,OAAO,WAAW;CAEtB,QAAQ,CAGR;CAIA,OAAO,WAAW,GAAG,UAAU;AACjC"}

package/dist/_chunks/validation-taUkvA4Q.js

@@ -0,0 +1,113 @@
+//#region src/cookies/validation.ts
+/**
+* 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 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
+* (`(` `)` `<` `>` `@` `,` `;` `:` `\` `"` `/` `[` `]` `?` `=` `{` `}`).
+*/
+var 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, index) {
+	const code = value.charCodeAt(index);
+	if (code < 32 || code === 127 || code > 126) 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.
+*/
+function assertValidCookieName(name) {
+	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) {
+	return code === 33 || code >= 35 && code <= 43 || code >= 45 && code <= 58 || code >= 60 && code <= 91 || code >= 93 && code <= 126;
+}
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+var ATTR_INJECTION_RE = /[;\r\n]/;
+var 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.
+*/
+function assertValidCookieOptions(options) {
+	if (options.sameSite !== void 0) {
+		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 !== void 0 && 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 !== void 0 && 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 !== void 0 && (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.`);
+}
+function assertValidCookieValue(name, value) {
+	if (typeof value !== "string") throw new Error(`[timber] cookie ${JSON.stringify(name)}: cookie value must be a string.`);
+	const wrapped = value.length >= 2 && value.charCodeAt(0) === 34 && value.charCodeAt(value.length - 1) === 34;
+	const start = wrapped ? 1 : 0;
+	const end = wrapped ? value.length - 1 : value.length;
+	for (let i = start; i < end; i++) if (!isCookieOctet(value.charCodeAt(i))) 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.`);
+}
+//#endregion
+export { assertValidCookieOptions as n, assertValidCookieValue as r, assertValidCookieName as t };
+
+//# sourceMappingURL=validation-taUkvA4Q.js.map

package/dist/_chunks/validation-taUkvA4Q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-taUkvA4Q.js","names":[],"sources":["../../src/cookies/validation.ts"],"sourcesContent":["/**\n * Cookie name and value validation per RFC 6265 §4.1.1.\n *\n * This module is pure — no server or client imports — so it can be loaded\n * by both `server/request-context.ts` (which guards `getCookies().set()`)\n * and `client/use-cookie.ts` (which guards `useCookie()`'s setter). The\n * shared validator gives both sides identical encoding contracts:\n * **the framework never silently encodes — callers emit `cookie-octet`\n * bytes or get a developer-facing error.**\n *\n * Why this matters: see ONGOING_SECURITY.md H-3 (TIM-868) and\n * design/29-cookies.md §\"Cookie Name and Value Validation\".\n */\n\n// ─── RFC 6265 cookie-octet ────────────────────────────────────────────────\n//\n//   cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E\n//\n// Equivalently: US-ASCII printable bytes excluding whitespace, `\"` (0x22),\n// `,` (0x2C), `;` (0x3B), `\\` (0x5C), and DEL (0x7F).\n\n/**\n * RFC 7230 §3.2.6 token characters used as the cookie-name production in\n * RFC 6265 §4.1.1. Anchored, non-empty match.\n *\n * Allowed: US-ASCII letters, digits, and `!#$%&'*+-.^_` `` ` `` `|~`.\n * Disallowed: whitespace, controls, delimiters\n * (`(` `)` `<` `>` `@` `,` `;` `:` `\\` `\"` `/` `[` `]` `?` `=` `{` `}`).\n */\nconst COOKIE_NAME_RE = /^[!#$%&'*+\\-.0-9A-Z^_`a-z|~]+$/;\n\n/**\n * Format a single byte for a clear error message — escape control bytes\n * and non-ASCII as `0x..` and quote printables.\n */\nfunction describeChar(value: string, index: number): string {\n  const code = value.charCodeAt(index);\n  if (code < 0x20 || code === 0x7f || code > 0x7e) {\n    return `0x${code.toString(16).padStart(2, '0')}`;\n  }\n  return JSON.stringify(value[index]);\n}\n\n/**\n * Validate a cookie name against RFC 6265 §4.1.1 / RFC 7230 token rules.\n * Throws a developer-facing error naming the offending byte and its index.\n */\nexport function assertValidCookieName(name: string): void {\n  if (typeof name !== 'string' || name.length === 0) {\n    throw new Error('[timber] cookie name must be a non-empty string.');\n  }\n  if (!COOKIE_NAME_RE.test(name)) {\n    for (let i = 0; i < name.length; i++) {\n      if (!COOKIE_NAME_RE.test(name[i])) {\n        throw new Error(\n          `[timber] invalid cookie name ${JSON.stringify(name)} — ` +\n            `disallowed character ${describeChar(name, i)} at index ${i}. ` +\n            `Cookie names must match the RFC 6265 §4.1.1 token grammar (US-ASCII letters, digits, ` +\n            `and \\`!#$%&'*+-.^_\\`|~\\`; no whitespace, controls, or delimiters).`\n        );\n      }\n    }\n    throw new Error(\n      `[timber] invalid cookie name ${JSON.stringify(name)} — ` +\n        `must match RFC 6265 §4.1.1 token grammar.`\n    );\n  }\n}\n\n/** Single-byte test for RFC 6265 §4.1.1 cookie-octet. */\nfunction isCookieOctet(code: number): boolean {\n  return (\n    code === 0x21 ||\n    (code >= 0x23 && code <= 0x2b) ||\n    (code >= 0x2d && code <= 0x3a) ||\n    (code >= 0x3c && code <= 0x5b) ||\n    (code >= 0x5d && code <= 0x7e)\n  );\n}\n\n/**\n * Validate a cookie value against the RFC 6265 §4.1.1 `cookie-value`\n * production:\n *\n *     cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )\n *     cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E\n *\n * Both the bare `*cookie-octet` form and the DQUOTE-wrapped form are\n * valid. The wrapped form is common in upstream `Set-Cookie` headers\n * (e.g. `sid=\"abc\"; Path=/`) and must be forwardable through\n * `setFromHeaders` verbatim — stripping or rejecting the surrounding\n * quotes would corrupt the on-the-wire bytes and break value semantics\n * for the upstream service.\n *\n * Excluded bytes (in either form): CTL, whitespace (CR/LF/TAB/SP),\n * interior DQUOTE, comma, semicolon, backslash, DEL, and anything\n * non-ASCII. The smuggling primitive (`;`) is rejected regardless of\n * wrapping.\n *\n * Throws a developer-facing error naming the offending byte and its\n * index. Callers passing user-controlled data through the default\n * `set()` path don't need to call this — `set()` auto-encodes via\n * `encodeURIComponent`, whose output is always valid cookie-octet.\n * This validator is for the `{ raw: true }` opt-out and for\n * `setFromHeaders` forwarding.\n */\n// ─── Cookie attribute validation ──────────────────────────────────────────\n\n/**\n * Characters that must not appear in path or domain cookie attributes.\n * Semicolons delimit cookie attributes on the wire, so allowing `;` in\n * path or domain would inject extra attributes. CR/LF enable HTTP header\n * injection.\n */\nconst ATTR_INJECTION_RE = /[;\\r\\n]/;\n\nconst VALID_SAME_SITE = new Set(['strict', 'lax', 'none']);\n\n/**\n * Validate cookie option attributes at runtime to prevent Set-Cookie\n * header injection through unsanitized option values.\n *\n * TypeScript types enforce correct shapes at compile time, but at runtime\n * (e.g. from untyped libraries or user-controlled config) invalid values\n * could inject additional Set-Cookie attributes.\n */\nexport function assertValidCookieOptions(options: {\n  sameSite?: string;\n  path?: string;\n  domain?: string;\n  maxAge?: number;\n}): void {\n  if (options.sameSite !== undefined) {\n    const lower = options.sameSite.toLowerCase();\n    if (!VALID_SAME_SITE.has(lower)) {\n      throw new Error(\n        `[timber] invalid cookie sameSite value ${JSON.stringify(options.sameSite)} — ` +\n          `must be 'strict', 'lax', or 'none'.`\n      );\n    }\n  }\n  if (options.path !== undefined && ATTR_INJECTION_RE.test(options.path)) {\n    throw new Error(\n      `[timber] invalid cookie path ${JSON.stringify(options.path)} — ` +\n        `path must not contain ';', CR, or LF (Set-Cookie header injection).`\n    );\n  }\n  if (options.domain !== undefined && ATTR_INJECTION_RE.test(options.domain)) {\n    throw new Error(\n      `[timber] invalid cookie domain ${JSON.stringify(options.domain)} — ` +\n        `domain must not contain ';', CR, or LF (Set-Cookie header injection).`\n    );\n  }\n  if (\n    options.maxAge !== undefined &&\n    (typeof options.maxAge !== 'number' || !Number.isFinite(options.maxAge))\n  ) {\n    throw new Error(\n      `[timber] invalid cookie maxAge ${JSON.stringify(options.maxAge)} — ` +\n        `maxAge must be a finite number.`\n    );\n  }\n}\n\nexport function assertValidCookieValue(name: string, value: string): void {\n  if (typeof value !== 'string') {\n    throw new Error(`[timber] cookie ${JSON.stringify(name)}: cookie value must be a string.`);\n  }\n  // Detect the DQUOTE-wrapped form: at least two characters and both\n  // endpoints are `\"`. The interior must be pure cookie-octet (no\n  // interior DQUOTEs allowed — the grammar says *cookie-octet, and\n  // cookie-octet excludes 0x22).\n  const wrapped =\n    value.length >= 2 &&\n    value.charCodeAt(0) === 0x22 &&\n    value.charCodeAt(value.length - 1) === 0x22;\n  const start = wrapped ? 1 : 0;\n  const end = wrapped ? value.length - 1 : value.length;\n  for (let i = start; i < end; i++) {\n    const code = value.charCodeAt(i);\n    if (!isCookieOctet(code)) {\n      throw new Error(\n        `[timber] cookie ${JSON.stringify(name)}: invalid cookie value — ` +\n          `disallowed character ${describeChar(value, i)} at index ${i}. ` +\n          `Cookie values must contain only RFC 6265 §4.1.1 cookie-octet bytes ` +\n          `(US-ASCII printable, excluding whitespace, \\`\"\\`, \\`,\\`, \\`;\\`, and \\`\\\\\\`), ` +\n          `optionally enclosed in a single DQUOTE pair. ` +\n          `Encode the value (e.g. encodeURIComponent or jsonCookieCodec) before storing it.`\n      );\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAM,iBAAiB;;;;;AAMvB,SAAS,aAAa,OAAe,OAAuB;CAC1D,MAAM,OAAO,MAAM,WAAW,KAAK;CACnC,IAAI,OAAO,MAAQ,SAAS,OAAQ,OAAO,KACzC,OAAO,KAAK,KAAK,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;CAE/C,OAAO,KAAK,UAAU,MAAM,MAAM;AACpC;;;;;AAMA,SAAgB,sBAAsB,MAAoB;CACxD,IAAI,OAAO,SAAS,YAAY,KAAK,WAAW,GAC9C,MAAM,IAAI,MAAM,kDAAkD;CAEpE,IAAI,CAAC,eAAe,KAAK,IAAI,GAAG;EAC9B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAC/B,IAAI,CAAC,eAAe,KAAK,KAAK,EAAE,GAC9B,MAAM,IAAI,MACR,gCAAgC,KAAK,UAAU,IAAI,EAAE,0BAC3B,aAAa,MAAM,CAAC,EAAE,YAAY,EAAE,0JAGhE;EAGJ,MAAM,IAAI,MACR,gCAAgC,KAAK,UAAU,IAAI,EAAE,6CAEvD;CACF;AACF;;AAGA,SAAS,cAAc,MAAuB;CAC5C,OACE,SAAS,MACR,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ,MACxB,QAAQ,MAAQ,QAAQ;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,oBAAoB;AAE1B,IAAM,kBAAkB,IAAI,IAAI;CAAC;CAAU;CAAO;AAAM,CAAC;;;;;;;;;AAUzD,SAAgB,yBAAyB,SAKhC;CACP,IAAI,QAAQ,aAAa,KAAA,GAAW;EAClC,MAAM,QAAQ,QAAQ,SAAS,YAAY;EAC3C,IAAI,CAAC,gBAAgB,IAAI,KAAK,GAC5B,MAAM,IAAI,MACR,0CAA0C,KAAK,UAAU,QAAQ,QAAQ,EAAE,uCAE7E;CAEJ;CACA,IAAI,QAAQ,SAAS,KAAA,KAAa,kBAAkB,KAAK,QAAQ,IAAI,GACnE,MAAM,IAAI,MACR,gCAAgC,KAAK,UAAU,QAAQ,IAAI,EAAE,uEAE/D;CAEF,IAAI,QAAQ,WAAW,KAAA,KAAa,kBAAkB,KAAK,QAAQ,MAAM,GACvE,MAAM,IAAI,MACR,kCAAkC,KAAK,UAAU,QAAQ,MAAM,EAAE,yEAEnE;CAEF,IACE,QAAQ,WAAW,KAAA,MAClB,OAAO,QAAQ,WAAW,YAAY,CAAC,OAAO,SAAS,QAAQ,MAAM,IAEtE,MAAM,IAAI,MACR,kCAAkC,KAAK,UAAU,QAAQ,MAAM,EAAE,mCAEnE;AAEJ;AAEA,SAAgB,uBAAuB,MAAc,OAAqB;CACxE,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MAAM,mBAAmB,KAAK,UAAU,IAAI,EAAE,iCAAiC;CAM3F,MAAM,UACJ,MAAM,UAAU,KAChB,MAAM,WAAW,CAAC,MAAM,MACxB,MAAM,WAAW,MAAM,SAAS,CAAC,MAAM;CACzC,MAAM,QAAQ,UAAU,IAAI;CAC5B,MAAM,MAAM,UAAU,MAAM,SAAS,IAAI,MAAM;CAC/C,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,KAE3B,IAAI,CAAC,cADQ,MAAM,WAAW,CACX,CAAI,GACrB,MAAM,IAAI,MACR,mBAAmB,KAAK,UAAU,IAAI,EAAE,gDACd,aAAa,OAAO,CAAC,EAAE,YAAY,EAAE,gRAKjE;AAGN"}