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

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/{plugins/dev-404-page.ts → dev-tools/404-page.ts}

@@ -15,6 +15,7 @@
 
 import type { SegmentNode } from '../routing/types.js';
 import { collectLeafRoutes } from '../routing/walkers.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -104,13 +105,7 @@ export function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): R
 
 // ─── HTML Escaping ──────────────────────────────────────────────────────────
 
-function esc(str: string): string {
-  return str
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+const esc = escapeHtml;
 
 // ─── HTML Generation ────────────────────────────────────────────────────────
 

package/src/{plugins/dev-error-page.ts → dev-tools/error-page.ts}

@@ -15,19 +15,12 @@
  */
 
 import {
-  classifyFrame,
   extractComponentStack,
   parseFirstAppFrame,
   type ErrorPhase,
-  type FrameType,
-} from './dev-error-overlay.js';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-interface ClassifiedFrame {
-  raw: string;
-  type: FrameType;
-}
+} from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
 
 // ─── Phase Labels ───────────────────────────────────────────────────────────
 
@@ -52,19 +45,6 @@ const PHASE_HINTS: Record<ErrorPhase, string> = {
   'handler': 'This error occurred in a route handler (route.ts). Check the handler function.',
 };
 
-// ─── Stack Trace Processing ─────────────────────────────────────────────────
-
-function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
-  return stack
-    .split('\n')
-    .slice(1) // skip first line (error message)
-    .filter((line) => line.trim().startsWith('at '))
-    .map((line) => ({
-      raw: line,
-      type: classifyFrame(line, projectRoot),
-    }));
-}
-
 // ─── Source Context ─────────────────────────────────────────────────────────
 
 /**
@@ -97,15 +77,8 @@ function readSourceContext(
   }
 }
 
-// ─── HTML Escaping ──────────────────────────────────────────────────────────
-
-function esc(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// HTML escaping provided by server/utils/escape-html.ts
+const esc = escapeHtml;
 
 /**
  * Escape a JSON string for safe embedding in an HTML `<script>` block.

package/src/dev-tools/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Dev tools barrel — re-exports all dev-only modules.
+ *
+ * Organized by concern, not by Vite plugin vs server module:
+ * - stack-classifier: frame classification for error display
+ * - overlay: Vite browser error overlay integration
+ * - error-page: self-contained HTML 500 page
+ * - 404-page: self-contained HTML 404 page
+ * - terminal: boxed terminal error output
+ * - logger: structured request tree logger
+ * - warnings: dev-mode footgun warnings
+ * - browser-logs: forward browser console to server
+ * - logs: forward server console to browser
+ * - holding-server: startup holding server
+ * - instrumentation: fetch tracing + OTEL span processor
+ *
+ * Dev-only: all modules in this subtree are only active during `vite dev`.
+ * They are never included in production builds.
+ */
+
+// Stack trace classification
+export {
+  classifyFrame,
+  classifyStack,
+  type FrameType,
+  type ClassifiedFrame,
+} from './stack-classifier.js';
+
+// Error overlay (Vite integration)
+export {
+  sendErrorToOverlay,
+  fixErrorStacktrace,
+  classifyErrorPhase,
+  extractComponentStack,
+  parseFirstAppFrame,
+  calculateModuleRunnerOffset,
+  formatRscDebugContext,
+  formatTerminalError,
+  PHASE_LABELS,
+  type ErrorPhase,
+  type RscDebugComponentInfo,
+} from './overlay.js';
+
+// HTML error pages
+export { generateDevErrorPage, extractHmrOptions, type DevErrorHmrOptions } from './error-page.js';
+export { generateDev404Page, collectRoutes, findSimilarRoutes } from './404-page.js';
+
+// Terminal error formatting
+export { formatTerminalError as formatTerminalErrorDirect } from './terminal.js';
+
+// Request tree logger
+export {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  resolveLogMode,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.js';
+
+// Dev-mode warnings
+export {
+  warnSuspenseWrappingChildren,
+  warnDenyInSuspense,
+  warnRedirectInSuspense,
+  warnRedirectInAccess,
+  warnStaticRequestApi,
+  warnSlowSlotWithoutSuspense,
+  setViteServer,
+  WarningId,
+  type DevWarningConfig,
+  _resetWarnings,
+  _getEmitted,
+} from './warnings.js';
+
+// Browser log forwarding
+export {
+  timberDevBrowserLogs,
+  type BrowserLogLevel,
+  type DevBrowserLogsConfig,
+} from './browser-logs.js';
+
+// Server log forwarding
+export { timberDevLogs } from './logs.js';
+
+// Holding server
+export { createHoldingServer, type HoldingServer } from './holding-server.js';
+
+// OTEL instrumentation
+export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.js';

package/src/dev-tools/instrumentation.ts

@@ -0,0 +1,176 @@
+/**
+ * Dev-mode OTEL instrumentation — fetch tracing and span processing.
+ *
+ * Combines two concerns:
+ * 1. Fetch instrumentation: patches globalThis.fetch to create OTEL spans
+ *    for every fetch call, giving visibility into async data fetching in
+ *    the dev request log tree.
+ * 2. Span processing: collects completed spans per-request and drives
+ *    dev log output when the root span ends.
+ *
+ * Only activated in dev mode — zero overhead in production.
+ *
+ * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+
+import * as api from '@opentelemetry/api';
+import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Span, Context } from '@opentelemetry/api';
+import {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.js';
+
+// ─── Fetch Instrumentation ──────────────────────────────────────────────────
+
+export type DevFetchCleanup = () => void;
+
+/**
+ * Patch globalThis.fetch to wrap every call in an OTEL span.
+ *
+ * Returns a cleanup function that restores the original fetch.
+ * Only call this in dev mode.
+ */
+export function instrumentDevFetch(): DevFetchCleanup {
+  const originalFetch = globalThis.fetch;
+  const tracer = api.trace.getTracer('timber.js');
+
+  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const { method, url } = extractFetchInfo(input, init);
+
+    return tracer.startActiveSpan(
+      'timber.fetch',
+      {
+        attributes: {
+          'http.request.method': method,
+          'http.url': url,
+        },
+      },
+      async (span) => {
+        try {
+          const response = await originalFetch(input, init);
+
+          span.setAttribute('http.response.status_code', response.status);
+
+          // Surface cache status from standard headers
+          const cacheStatus =
+            response.headers.get('X-Cache') ?? response.headers.get('CF-Cache-Status');
+          if (cacheStatus) {
+            span.setAttribute('timber.cache_status', cacheStatus);
+          }
+
+          span.setStatus({ code: api.SpanStatusCode.OK });
+          span.end();
+          return response;
+        } catch (error) {
+          span.setStatus({ code: api.SpanStatusCode.ERROR });
+          if (error instanceof Error) {
+            span.setAttribute('timber.fetch_error', error.message);
+            span.recordException(error);
+          }
+          span.end();
+          throw error;
+        }
+      }
+    );
+  };
+
+  return () => {
+    globalThis.fetch = originalFetch;
+  };
+}
+
+/**
+ * Extract method and URL from the various fetch() call signatures.
+ */
+function extractFetchInfo(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): { method: string; url: string } {
+  let method = init?.method ?? 'GET';
+  let url: string;
+
+  if (input instanceof Request) {
+    url = input.url;
+    if (!init?.method) {
+      method = input.method;
+    }
+  } else if (input instanceof URL) {
+    url = input.toString();
+  } else {
+    url = input;
+  }
+
+  return { method: method.toUpperCase(), url };
+}
+
+// ─── Span Processor ─────────────────────────────────────────────────────────
+
+/**
+ * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
+ *
+ * Collects completed spans per-request (correlated by trace ID). When the
+ * root span (http.server.request) ends, all child spans are already collected
+ * (child spans end before parent in OTEL). The processor formats the span
+ * tree and writes it to stderr.
+ *
+ * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
+ * now the single source of truth for dev logging — no more parallel event
+ * systems that can drift.
+ */
+export class DevSpanProcessor implements SpanProcessor {
+  private spansByTrace = new Map<string, ReadableSpan[]>();
+  private mode: DevLogMode;
+  private config: DevLoggerConfig;
+
+  constructor(config: DevLoggerConfig) {
+    this.config = config;
+    this.mode = config.mode ?? 'tree';
+  }
+
+  onStart(_span: Span, _context: Context): void {
+    // No action needed on span start — we collect on end.
+  }
+
+  onEnd(span: ReadableSpan): void {
+    const traceId = span.spanContext().traceId;
+
+    let spans = this.spansByTrace.get(traceId);
+    if (!spans) {
+      spans = [];
+      this.spansByTrace.set(traceId, spans);
+    }
+    spans.push(span);
+
+    // Root span signals request completion — all child spans are already
+    // collected because OTEL ends child spans before parent spans.
+    if (span.name === 'http.server.request') {
+      const output = this.format(spans);
+      if (output) {
+        process.stderr.write(output);
+      }
+      this.spansByTrace.delete(traceId);
+    }
+  }
+
+  private format(spans: ReadableSpan[]): string {
+    if (this.mode === 'quiet') return '';
+    if (this.mode === 'json') return formatJson(spans);
+    if (this.mode === 'summary') return formatSpanSummary(spans, this.config);
+    // Both 'tree' and 'verbose' use the tree formatter.
+    // verbose will show additional detail (every component render) once
+    // component-level spans are wired.
+    return formatSpanTree(spans, this.config);
+  }
+
+  async shutdown(): Promise<void> {
+    this.spansByTrace.clear();
+  }
+
+  async forceFlush(): Promise<void> {
+    // Nothing to flush — output happens synchronously in onEnd.
+  }
+}

package/src/{plugins/dev-logs.ts → dev-tools/logs.ts}

@@ -149,7 +149,7 @@ function extractCallerLocation(projectRoot: string): string | null {
   for (let i = 1; i < lines.length; i++) {
     const line = lines[i].trim();
     // Skip our own patching frames
-    if (line.includes('dev-logs')) continue;
+    if (line.includes('dev-tools/logs')) continue;
     // Skip node internals
     if (line.includes('node:') || line.includes('node_modules')) continue;
 
@@ -189,7 +189,7 @@ export function isFrameworkInternalCaller(): boolean {
   for (let i = 1; i < lines.length; i++) {
     const line = lines[i].trim();
     // Skip our own patching frames
-    if (line.includes('dev-logs')) continue;
+    if (line.includes('dev-tools/logs')) continue;
     // Skip node internals (but NOT node_modules — we need to inspect those)
     if (line.includes('node:')) continue;
 

package/src/{plugins/dev-error-overlay.ts → dev-tools/overlay.ts}

@@ -18,6 +18,7 @@
 import type { ViteDevServer, DevEnvironment } from 'vite';
 import { createRequire } from 'node:module';
 import { resolve, dirname } from 'node:path';
+import { classifyFrame, type FrameType } from './stack-classifier.js';
 
 // ─── Trace Mapping (lazy-loaded) ─────────────────────────────────────────────
 
@@ -70,28 +71,9 @@ export const PHASE_LABELS: Record<ErrorPhase, string> = {
   'handler': 'Route Handler',
 };
 
-// ─── Frame Classification ───────────────────────────────────────────────────
+// ─── Frame Classification (re-exported from stack-classifier) ───────────────
 
-export type FrameType = 'app' | 'framework' | 'internal';
-
-/**
- * Classify a stack frame line by origin.
- *
- * - 'app': user application code (in project root, not node_modules)
- * - 'framework': timber-app internal code
- * - 'internal': node_modules, Node.js internals
- */
-export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
-  // Strip leading whitespace and "at "
-  const trimmed = frameLine.trim();
-
-  if (trimmed.includes('packages/timber-app/')) return 'framework';
-  if (trimmed.includes('node_modules/')) return 'internal';
-  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
-  if (trimmed.includes(projectRoot)) return 'app';
-
-  return 'internal';
-}
+export { classifyFrame, classifyStack, type FrameType, type ClassifiedFrame } from './stack-classifier.js';
 
 // ─── Component Stack Extraction ─────────────────────────────────────────────
 
@@ -172,9 +154,9 @@ export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhas
 // ─── Terminal Formatting ────────────────────────────────────────────────────
 
 // formatTerminalError is implemented in the dedicated terminal formatter module
-// (dev-terminal-error.ts) to keep this file under 500 lines.
+// (terminal.ts) to keep this file under 500 lines.
 // Import for use in sendErrorToOverlay, and re-export for external consumers.
-import { formatTerminalError as _formatTerminalError } from './dev-terminal-error.js';
+import { formatTerminalError as _formatTerminalError } from './terminal.js';
 export const formatTerminalError = _formatTerminalError;
 
 // ─── RSC Debug Context ──────────────────────────────────────────────────────

package/src/dev-tools/stack-classifier.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack trace frame classifier — categorizes stack frames by origin.
+ *
+ * Provides `classifyFrame` (single frame) and `classifyStack` (full stack
+ * string) as the shared primitives used by the error page, terminal
+ * formatter, and overlay.
+ *
+ * Dev-only: this module is only imported by other dev-tools modules.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type FrameType = 'app' | 'framework' | 'internal';
+
+export interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+// ─── Frame Parsing ──────────────────────────────────────────────────────────
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+// ─── Classification ─────────────────────────────────────────────────────────
+
+/**
+ * Classify a single stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
+  const trimmed = frameLine.trim();
+
+  if (trimmed.includes('packages/timber-app/')) return 'framework';
+  if (trimmed.includes('node_modules/')) return 'internal';
+  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
+  if (trimmed.includes(projectRoot)) return 'app';
+
+  return 'internal';
+}
+
+/**
+ * Classify all frames in a full stack trace string.
+ *
+ * Parses the stack, skips the first line (error message), filters to
+ * lines starting with "at ", and returns classified frames with optional
+ * file/line/col metadata.
+ */
+export function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1) // skip first line (error message)
+    .filter((line) => line.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}