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

package/src/server/fallback-error.ts

@@ -10,10 +10,15 @@
  * exposed to the client (design/13-security.md principle 4).
  */
 
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
+import type { RouteMatch } from './pipeline.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { ClientBootstrapConfig } from './html-injectors.js';
+import type { LayoutEntry } from './deny-renderer.js';
+import type { GlobalErrorFile } from './rsc-entry/error-renderer.js';
+import { swallow } from './logger.js';
+import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
+import { sourceMapError } from './dev-source-map.js';
 
 /**
  * Render a fallback error page when the render pipeline throws.
@@ -27,25 +32,43 @@ export async function renderFallbackError(
   responseHeaders: Headers,
   isDev: boolean,
   rootSegment: ManifestSegmentNode,
-  clientBootstrap: ClientBootstrapConfig
+  clientBootstrap: ClientBootstrapConfig,
+  globalError?: GlobalErrorFile,
+  projectRoot?: string,
+  hmrOptions?: import('../dev-tools/dev-page-shell.js').DevErrorHmrOptions
 ): Promise<Response> {
+  // Source-map the error's stack trace in dev mode so the error page
+  // shows original source positions. See TIM-811.
+  sourceMapError(error);
+
   if (isDev) {
-    return renderDevErrorPage(error);
+    return renderDevErrorPage(error, projectRoot, hmrOptions);
   }
   // Lazy import to avoid loading error-renderer in the pipeline module
-  const { renderErrorPage } = await import('#/server/rsc-entry/error-renderer.js');
+  const { renderErrorPage } = await import('./rsc-entry/error-renderer.js');
   const segments = [rootSegment];
   const layoutComponents: LayoutEntry[] = [];
-  if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
-    if (mod.default) {
-      layoutComponents.push({
-        component: mod.default as (...args: unknown[]) => unknown,
-        segment: rootSegment,
-      });
+  // Wrap layout loading in try/catch — if the root layout module itself
+  // crashes (evaluation failure, syntax error, etc.), we still want to
+  // reach renderErrorPage so it can fall through to global-error.tsx
+  // (Tier 2), which renders without any layout wrapping.
+  try {
+    if (rootSegment.layout) {
+      const mod = await loadModule(rootSegment.layout);
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment: rootSegment,
+        });
+      }
     }
+  } catch (layoutError) {
+    // Layout failed to load — proceed without it. renderErrorPage will
+    // attempt segment-level error pages (without layout wrapping) and
+    // then fall through to global-error.tsx if those also fail.
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
   return renderErrorPage(
     error,
     500,
@@ -54,94 +77,44 @@ export async function renderFallbackError(
     req,
     match,
     responseHeaders,
-    clientBootstrap
+    clientBootstrap,
+    globalError
   );
 }
 
 /**
- * Render a dev-mode 500 error page with error message and stack trace.
+ * Render a dev-mode 500 error page with error details, source context,
+ * classified stack trace, and copy button.
+ *
+ * Dynamically imports the shared template from `plugins/dev-error-page.ts`
+ * so it is NOT pulled into production server bundles. The Vite client script
+ * is injected so the error overlay fires when the HMR WebSocket connects.
  *
- * Returns an HTML Response that displays the error in a styled page.
- * The Vite HMR client script is included so the error overlay still fires.
+ * Dev-only — the dynamic import has zero production cost.
  */
-export function renderDevErrorPage(error: unknown): Response {
+export async function renderDevErrorPage(
+  error: unknown,
+  projectRoot?: string,
+  hmrOptions?: import('../dev-tools/dev-page-shell.js').DevErrorHmrOptions
+): Promise<Response> {
   const err = error instanceof Error ? error : new Error(String(error));
-  const title = err.name || 'Error';
-  const message = escapeHtml(err.message);
-  const stack = err.stack ? escapeHtml(err.stack) : '';
+  const root = projectRoot ?? process.cwd();
 
-  const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>500 — ${escapeHtml(title)}</title>
-  <script type="module" src="/@vite/client"></script>
-  <style>
-    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-      background: #1a1a2e;
-      color: #e0e0e0;
-      padding: 2rem;
-      line-height: 1.6;
-    }
-    .container { max-width: 800px; margin: 0 auto; }
-    .badge {
-      display: inline-block;
-      background: #e74c3c;
-      color: white;
-      font-size: 0.75rem;
-      font-weight: 700;
-      padding: 0.2rem 0.6rem;
-      border-radius: 4px;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
-      margin-bottom: 1rem;
-    }
-    h1 {
-      font-size: 1.5rem;
-      color: #ff6b6b;
-      margin-bottom: 0.5rem;
-      word-break: break-word;
-    }
-    .message {
-      font-size: 1.1rem;
-      color: #ccc;
-      margin-bottom: 1.5rem;
-      word-break: break-word;
-    }
-    .stack-container {
-      background: #16213e;
-      border: 1px solid #2a2a4a;
-      border-radius: 8px;
-      padding: 1rem;
-      overflow-x: auto;
-    }
-    .stack {
-      font-family: 'SF Mono', 'Fira Code', 'Fira Mono', Menlo, Consolas, monospace;
-      font-size: 0.8rem;
-      color: #a0a0c0;
-      white-space: pre-wrap;
-      word-break: break-all;
-    }
-    .hint {
-      margin-top: 1.5rem;
-      font-size: 0.85rem;
-      color: #666;
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <span class="badge">500 Internal Server Error</span>
-    <h1>${escapeHtml(title)}</h1>
-    <p class="message">${message}</p>
-    ${stack ? `<div class="stack-container"><pre class="stack">${stack}</pre></div>` : ''}
-    <p class="hint">This error page is only shown in development.</p>
-  </div>
-</body>
-</html>`;
+  let html: string;
+  try {
+    // Dynamic import — keeps dev-error-page.ts and its transitive deps
+    // (dev-error-overlay.ts, @jridgewell/trace-mapping) out of production bundles.
+    const { generateDevErrorPage } = await import('../dev-tools/error-page.js');
+    html = generateDevErrorPage(err, 'render', root, hmrOptions);
+    // Inject Vite client script so the error overlay fires when HMR connects.
+    html = html.replace(
+      '</head>',
+      '  <script type="module" src="/@vite/client"></script>\n</head>'
+    );
+  } catch (e) {
+    swallow(e, 'dev error page template failed, using minimal fallback');
+    html = minimalErrorPage(err);
+  }
 
   return new Response(html, {
     status: 500,
@@ -149,11 +122,15 @@ export function renderDevErrorPage(error: unknown): Response {
   });
 }
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#x27;');
+/**
+ * Minimal fallback error page — used only if the shared template fails to load.
+ */
+function minimalErrorPage(err: Error): string {
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>500</title>
+<script type="module" src="/@vite/client"></script></head>
+<body style="font-family:system-ui;padding:2rem;background:#1a1a2e;color:#e0e0e0">
+<h1 style="color:#ff6b6b">500 Internal Server Error</h1>
+<pre style="color:#a0a0c0;white-space:pre-wrap">${esc(err.stack ?? err.message)}</pre>
+</body></html>`;
 }

package/src/server/flight-injection-state.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared state machine types and transitions for RSC Flight injection.
+ *
+ * Both html-injectors.ts (Web Streams) and node-stream-transforms.ts
+ * (Node.js streams) implement identical state transitions — only the
+ * I/O primitives differ. This module defines the discriminated union
+ * states and the transition map once.
+ *
+ * Valid state flow:
+ *   init → streaming → flushing → done
+ *   (any) → error
+ *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
+ * Design doc: 02-rendering-pipeline.md
+ */
+
+import type { TransitionMap } from '../utils/state-machine.js';
+
+// ─── States ──────────────────────────────────────────────────────────────────
+
+/** Waiting for first HTML chunk. Pull loop not started. */
+export interface InitState {
+  phase: 'init';
+}
+
+/** HTML chunks flowing, pull loop running. */
+export interface StreamingState {
+  phase: 'streaming';
+}
+
+/** HTML stream done (flush fired). Draining remaining RSC chunks. */
+export interface FlushingState {
+  phase: 'flushing';
+}
+
+/** All streams consumed. Terminal state. */
+export interface DoneState {
+  phase: 'done';
+}
+
+/** Pull loop failed. Terminal state with captured error. */
+export interface ErrorState {
+  phase: 'error';
+  error: unknown;
+}
+
+export type FlightInjectionState =
+  | InitState
+  | StreamingState
+  | FlushingState
+  | DoneState
+  | ErrorState;
+
+// ─── Events ──────────────────────────────────────────────────────────────────
+
+/** First HTML chunk arrived — start the pull loop. */
+export interface FirstChunkEvent {
+  type: 'FIRST_CHUNK';
+}
+
+/** HTML stream finished (flush/end). */
+export interface HtmlDoneEvent {
+  type: 'HTML_DONE';
+}
+
+/** RSC pull loop completed (all chunks read or stream closed). */
+export interface PullDoneEvent {
+  type: 'PULL_DONE';
+}
+
+/** RSC pull loop encountered an error. */
+export interface PullErrorEvent {
+  type: 'PULL_ERROR';
+  error: unknown;
+}
+
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
+
+// ─── Transitions ─────────────────────────────────────────────────────────────
+
+export const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent> =
+  {
+    init: {
+      FIRST_CHUNK: (): StreamingState => ({ phase: 'streaming' }),
+      // Edge case: HTML stream ends immediately (empty body)
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+    },
+    streaming: {
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+      PULL_DONE: (): StreamingState => ({ phase: 'streaming' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+    flushing: {
+      PULL_DONE: (): DoneState => ({ phase: 'done' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+  };
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Whether the HTML stream has finished (flush/end fired). */
+export function isHtmlDone(state: FlightInjectionState): boolean {
+  return state.phase === 'flushing' || state.phase === 'done';
+}
+
+/** Whether the RSC pull loop has completed. */
+export function isPullDone(state: FlightInjectionState): boolean {
+  return state.phase === 'done' || state.phase === 'error';
+}

package/src/server/flight-scripts.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared Flight data script generation.
+ *
+ * Both html-injectors.ts (Web Streams / dev) and node-stream-transforms.ts
+ * (Node streams / production) use this module to generate inline `<script>`
+ * tags for RSC Flight data injection.
+ *
+ * The init script goes in `<head>` as part of the HTML shell (guaranteed
+ * to execute before any streaming chunk scripts). Push scripts are emitted
+ * as RSC chunks arrive during streaming.
+ *
+ * See design/02-rendering-pipeline.md, LOCAL-415
+ */
+
+// ─── JSON Escaping ────────────────────────────────────────────────────────
+
+/**
+ * Escape a JSON string for safe embedding inside an HTML `<script>` tag.
+ *
+ * Prevents XSS via `</script>` injection and handles Unicode line/paragraph
+ * separators that are valid JSON but invalid in JS string literals (pre-ES2019).
+ */
+export function htmlEscapeJsonString(str: string): string {
+  return str
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+// ─── Script Generation ────────────────────────────────────────────────────
+
+/** The global variable name used for Flight data on the client. */
+const FLIGHT_VAR = 'self.__timber_f';
+
+/**
+ * Generate the init script that creates the Flight data array.
+ *
+ * This MUST be included in `<head>` (via headHtml) so it executes before
+ * any streaming chunk scripts arrive in `<body>`. The array is created
+ * unconditionally — no `||[]` guard needed in push scripts.
+ *
+ * Also emits the bootstrap signal [0] which tells the client that
+ * Flight data is active for this page.
+ */
+export function flightInitScript(): string {
+  return `<script>${FLIGHT_VAR}=[${htmlEscapeJsonString(JSON.stringify([0]))}]</script>`;
+}
+
+/**
+ * Generate a push script for a Flight data chunk.
+ *
+ * Normally the init script runs first (it's in `<head>`), so
+ * `self.__timber_f` already exists. However, shell-less status pages
+ * (e.g. standalone error pages) may have no `<head>` tag, so the init script
+ * never runs. The `||[]` guard ensures the array is created on first
+ * push if needed, preventing a TypeError. See TIM-559.
+ */
+export function flightChunkScript(data: string): string {
+  const escaped = htmlEscapeJsonString(JSON.stringify([1, data]));
+  return `<script>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
+}

package/src/server/form-data.ts

@@ -29,14 +29,21 @@ export function parseFormData(formData: FormData): Record<string, unknown> {
     // Skip React internal fields
     if (key.startsWith('$ACTION_')) continue;
 
+    // Skip prototype-pollution keys at the top level — assigning to
+    // `flat['__proto__']` invokes the prototype setter and can splice
+    // attacker-controlled data into `flat`'s prototype chain.
+    // The dot-path case is filtered separately in `expandDotPaths`.
+    if (DANGEROUS_KEYS.has(key)) continue;
+
     const values = formData.getAll(key);
     const processed = values.map(normalizeValue);
 
     if (processed.length === 1) {
       flat[key] = processed[0];
     } else {
-      // Filter out undefined entries from multi-value fields
-      flat[key] = processed.filter((v) => v !== undefined);
+      // Filter out undefined (empty Files) and empty strings from multi-value fields.
+      // Multi-value fields (e.g. tags=js&tags=&tags=ts) should not include blanks.
+      flat[key] = processed.filter((v) => v !== undefined && v !== '');
     }
   }
 
@@ -46,15 +53,13 @@ export function parseFormData(formData: FormData): Record<string, unknown> {
 
 /**
  * Normalize a single FormData entry value.
- * - Empty strings → undefined (enables .optional() semantics)
  * - Empty File objects (no selection) → undefined
+ * - Strings pass through as-is (empty strings stay as empty strings so
+ *   schema validators like `z.string().min(1, 'Required')` can produce
+ *   their custom error messages instead of a generic type mismatch)
  * - Everything else passes through as-is
  */
 function normalizeValue(value: FormDataEntryValue): unknown {
-  if (typeof value === 'string') {
-    return value === '' ? undefined : value;
-  }
-
   // File input with no selection: browsers submit a File with name="" and size=0
   if (value instanceof File && value.size === 0 && value.name === '') {
     return undefined;
@@ -82,18 +87,23 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
     }
   }
 
-  // Fast path: no dot-notation keys, return as-is
+  // Fast path: no dot-notation keys, return as-is.
+  // Top-level dangerous keys are already filtered in `parseFormData` above.
   if (!hasDotPaths) return flat;
 
   for (const [key, value] of Object.entries(flat)) {
-    if (!key.includes('.')) {
-      result[key] = value;
+    // Reject any path that contains __proto__ / constructor / prototype.
+    // Without this, `__proto__.x=1` writes to Object.prototype because
+    // `result['__proto__']` resolves to the prototype object itself.
+    const parts = key.split('.');
+    if (parts.some((p) => DANGEROUS_KEYS.has(p))) continue;
+
+    if (parts.length === 1) {
+      result[parts[0]] = value;
       continue;
     }
 
-    const parts = key.split('.');
     let current: Record<string, unknown> = result;
-
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i];
       if (current[part] === undefined || current[part] === null) {
@@ -113,6 +123,15 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
   return result;
 }
 
+// `__proto__` is the only key in this parser that escapes the dot-path
+// walk's `typeof !== 'object'` reset: accessing `obj['__proto__']` returns
+// `Object.prototype` (itself an object), so the walk steps into the global
+// prototype and the leaf write mutates it. `constructor` resolves to a
+// function (reset fires) and `prototype` is undefined on fresh objects
+// (reset fires), so neither escapes the walk — they parse as legit nested
+// keys and do not mutate anything global.
+const DANGEROUS_KEYS = new Set(['__proto__']);
+
 // ─── Coercion Helpers ────────────────────────────────────────────────────
 
 /**
@@ -129,6 +148,23 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
  * ```
  */
 export const coerce = {
+  /**
+   * Coerce an empty string to undefined for optional text fields.
+   * Use with `.optional()` schemas where an empty input means "not provided".
+   *
+   * ```ts
+   * // Zod
+   * z.unknown().transform(coerce.text).pipe(z.string().optional())
+   * // Valibot
+   * v.pipe(v.unknown(), v.transform(coerce.text), v.optional(v.string()))
+   * ```
+   */
+  text(value: unknown): string | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value === 'string') return value;
+    return undefined;
+  },
+
   /**
    * Coerce a string to a number.
    * - `"42"` → `42`
@@ -173,4 +209,80 @@ export const coerce = {
       return undefined;
     }
   },
+
+  /**
+   * Coerce a date string to a Date object.
+   * Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
+   * (`"2024-01-15T10:30"`), and full ISO 8601 strings.
+   * - Valid date string → `Date`
+   * - `""` / `undefined` / `null` → `undefined`
+   * - Invalid date strings → `undefined` (schema validation will catch this)
+   * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
+   */
+  date(value: unknown): Date | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (value instanceof Date) return value;
+    if (typeof value !== 'string') return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return undefined;
+
+    // Overflow detection: extract Y/M/D from the input string and verify
+    // they match the parsed Date components. new Date('2024-02-31') silently
+    // normalizes to March 2nd — we reject such inputs.
+    const ymdMatch = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (ymdMatch) {
+      const inputYear = Number(ymdMatch[1]);
+      const inputMonth = Number(ymdMatch[2]);
+      const inputDay = Number(ymdMatch[3]);
+
+      // Use UTC methods for date-only and Z-suffixed strings to avoid
+      // timezone offset shifting the day. For datetime-local (no Z suffix),
+      // the Date constructor parses in local time, so use local methods.
+      const isUTC = value.length === 10 || value.endsWith('Z');
+      const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();
+      const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;
+      const parsedDay = isUTC ? date.getUTCDate() : date.getDate();
+
+      if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) {
+        return undefined;
+      }
+    }
+
+    return date;
+  },
+
+  /**
+   * Create a File coercion function with optional size and mime type validation.
+   * Returns the File if valid, `undefined` otherwise.
+   *
+   * ```ts
+   * // Basic — just checks it's a real File
+   * z.preprocess(coerce.file(), z.instanceof(File))
+   *
+   * // With constraints
+   * z.preprocess(
+   *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+   *   z.instanceof(File)
+   * )
+   * ```
+   */
+  file(options?: { maxSize?: number; accept?: string[] }): (value: unknown) => File | undefined {
+    return (value: unknown): File | undefined => {
+      if (value === undefined || value === null || value === '') return undefined;
+      if (!(value instanceof File)) return undefined;
+
+      // Empty file input (no selection): browsers submit File with name="" and size=0
+      if (value.size === 0 && value.name === '') return undefined;
+
+      if (options?.maxSize !== undefined && value.size > options.maxSize) {
+        return undefined;
+      }
+
+      if (options?.accept !== undefined && !options.accept.includes(value.type)) {
+        return undefined;
+      }
+
+      return value;
+    };
+  },
 };