@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

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,134 @@
+/**
+ * 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.
+ */
+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.`
+      );
+    }
+  }
+}

package/src/dev-tools/404-page.ts

@@ -0,0 +1,387 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+
+import type { SegmentNode } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface RouteInfo {
+  /** URL path pattern (e.g., "/dashboard/[id]") */
+  path: string;
+  /** Whether this is a page route or API route handler */
+  type: 'page' | 'route';
+}
+
+// ─── Route Collection ───────────────────────────────────────────────────────
+
+/**
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
+ *
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
+ */
+export function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[] {
+  const leaves = collectLeafRoutes(root, { includeSlots: true });
+  const routes: RouteInfo[] = [];
+  for (const leaf of leaves) {
+    if (leaf.page) routes.push({ path: leaf.urlPath, type: 'page' });
+    if (leaf.route) routes.push({ path: leaf.urlPath, type: 'route' });
+  }
+  return routes;
+}
+
+// ─── String Similarity ──────────────────────────────────────────────────────
+
+/**
+ * Compute Levenshtein distance between two strings.
+ *
+ * Used for "did you mean?" suggestions. Simple O(n*m) implementation
+ * — fine for short URL paths.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // Optimization: use single-row DP
+  const row = Array.from({ length: n + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= m; i++) {
+    let prev = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j]! + 1, // deletion
+        prev + 1, // insertion
+        row[j - 1]! + cost // substitution
+      );
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[n] = prev;
+  }
+
+  return row[n]!;
+}
+
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[] {
+  if (routes.length === 0) return [];
+
+  const scored = routes
+    .map((route) => ({
+      route,
+      distance: levenshtein(requestedPath.toLowerCase(), route.path.toLowerCase()),
+    }))
+    .filter((s) => {
+      const maxLen = Math.max(requestedPath.length, s.route.path.length);
+      return s.distance <= maxLen * 0.4;
+    })
+    .sort((a, b) => a.distance - b.distance);
+
+  return scored.slice(0, 3).map((s) => s.route);
+}
+
+// ─── HTML Escaping ──────────────────────────────────────────────────────────
+
+const esc = escapeHtml;
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page.
+ */
+export function generateDev404Page(requestedPath: string, routes: RouteInfo[]): string {
+  const suggestions = findSimilarRoutes(requestedPath, routes);
+  const isEmpty = routes.length === 0;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>404 — ${esc(requestedPath)} | timber.js</title>
+  <style>${CSS}</style>
+</head>
+<body>
+  <div class="container">
+    <header class="header">
+      <div class="badge">404 Not Found</div>
+      <h1 class="message">No route matches <code>${esc(requestedPath)}</code></h1>
+    </header>
+
+    ${
+      isEmpty
+        ? `<div class="welcome">
+        <h2>Welcome to timber.js</h2>
+        <p>Your app has no pages yet. Create your first page to get started:</p>
+        <div class="code-block">
+          <div class="code-header">app/page.tsx</div>
+          <pre><code>export default function Home() {
+  return &lt;h1&gt;Hello, timber.js!&lt;/h1&gt;;
+}</code></pre>
+        </div>
+        <p class="hint">Save the file and this page will reload automatically.</p>
+      </div>`
+        : ''
+    }
+
+    ${
+      suggestions.length > 0
+        ? `<div class="section">
+        <div class="section-header">Did you mean?</div>
+        <ul class="route-list suggestions">
+          ${suggestions.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    ${
+      routes.length > 0
+        ? `<div class="section">
+        <div class="section-header">Available Routes (${routes.length})</div>
+        <ul class="route-list">
+          ${routes.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">Add or edit routes and this page will reload automatically.</span>
+    </footer>
+  </div>
+
+  <script>
+    // Auto-reload when Vite HMR fires (route added, file changed, etc.)
+    (function() {
+      try {
+        const ws = new WebSocket('ws://' + location.host, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            const data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch {}
+        });
+      } catch {}
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// ─── CSS ────────────────────────────────────────────────────────────────────
+
+const CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --badge-bg: #fefce8;
+    --badge-fg: #854d0e;
+    --badge-border: #fde68a;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --route-type-bg: #e0f2fe;
+    --route-type-fg: #0369a1;
+    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0a0a0a;
+      --fg: #f5f5f5;
+      --fg-dim: #9ca3af;
+      --border: #27272a;
+      --badge-bg: #422006;
+      --badge-fg: #fde68a;
+      --badge-border: #854d0e;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --route-type-bg: #0c4a6e;
+      --route-type-fg: #bae6fd;
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.6;
+    padding: 2rem;
+  }
+
+  .container { max-width: 56rem; margin: 0 auto; }
+  .header { margin-bottom: 1.5rem; }
+
+  .badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.25rem 0.625rem;
+    border-radius: 0.375rem;
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: 1px solid var(--badge-border);
+    margin-bottom: 0.75rem;
+  }
+
+  .message {
+    font-size: 1.375rem;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+
+  .message code {
+    font-family: var(--code-font);
+    background: var(--code-bg);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    font-size: 1.125rem;
+  }
+
+  .welcome {
+    margin-bottom: 1.5rem;
+    padding: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    background: var(--source-bg);
+  }
+
+  .welcome h2 {
+    font-size: 1.125rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .welcome p { color: var(--fg-dim); margin-bottom: 1rem; }
+
+  .code-block {
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+    margin-bottom: 1rem;
+  }
+
+  .code-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    padding: 0.5rem 0.75rem;
+    background: var(--code-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+    font-family: var(--code-font);
+  }
+
+  .code-block pre {
+    padding: 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    overflow-x: auto;
+    margin: 0;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .section-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+  }
+
+  .route-list {
+    list-style: none;
+    padding: 0.5rem 0;
+  }
+
+  .route-list li {
+    padding: 0.375rem 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .route-list li:hover { background: var(--source-bg); }
+
+  .route-list a {
+    color: var(--link);
+    text-decoration: none;
+  }
+
+  .route-list a:hover { text-decoration: underline; }
+
+  .route-type {
+    font-size: 0.625rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    background: var(--route-type-bg);
+    color: var(--route-type-fg);
+  }
+
+  .suggestions { background: var(--source-bg); }
+
+  .hint { font-size: 0.875rem; color: var(--fg-dim); }
+
+  .footer {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+    font-size: 0.75rem;
+    color: var(--fg-dim);
+  }
+
+  .timber-logo { font-weight: 600; white-space: nowrap; }
+`;