@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/server/form-data.ts

@@ -29,6 +29,12 @@ 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);
 
@@ -82,18 +88,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 +124,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 ────────────────────────────────────────────────────
 
 /**
@@ -173,4 +193,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;
+    };
+  },
 };

package/src/server/html-injector-core.ts

@@ -0,0 +1,417 @@
+/**
+ * HTML injector core — pure stateful helpers for streaming HTML post-processing.
+ *
+ * These helpers contain the actual byte/string logic for the held-flush
+ * streaming pipeline (buffered transforms, suffix moving, head injection,
+ * RSC flight interleaving). They are stream-shape agnostic: they know
+ * nothing about Web `TransformStream` or Node.js `Transform` and contain
+ * no `setImmediate` scheduling or controller plumbing.
+ *
+ * The Web Stream wrapper (`html-injectors.ts`) and the Node Stream wrapper
+ * (`node-stream-transforms.ts`) compose these helpers behind whichever
+ * stream shape their target runtime needs:
+ *
+ *   - On Cloudflare/edge: Web `TransformStream` wraps the helpers.
+ *   - On Node.js/Bun: Node `Transform` wraps the helpers (faster — C++ streams).
+ *
+ * Keeping this module split per-shape (rather than one file exporting both)
+ * preserves the build-time tree-shake: Cloudflare bundles never import
+ * `node:stream` even transitively. Only the helpers below are shared.
+ *
+ * **Pure functions only.** Anything that touches a stream API, schedules
+ * a tick, or owns a controller belongs in the wrapper, not here.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Streaming Constraints", 18-build-system.md §"Entry Files"
+ */
+
+import { createMachine, type Machine } from '../utils/state-machine.js';
+import { flightChunkScript } from './flight-scripts.js';
+import {
+  flightInjectionTransitions,
+  isHtmlDone,
+  isPullDone,
+  type FlightInjectionState,
+  type FlightInjectionEvent,
+} from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+
+// ─── Encoders / Constants ────────────────────────────────────────────────────
+
+const encoder = new TextEncoder();
+
+/** Closing tags React Fizz emits inside the shell chunk. */
+export const SUFFIX = '</body></html>';
+/** UTF-8 bytes of {@link SUFFIX}. Cached so wrappers don't re-encode per request. */
+export const SUFFIX_BYTES: Uint8Array = encoder.encode(SUFFIX);
+
+/** Encode a UTF-8 string. Convenience for wrappers that need a single source of truth. */
+export function encodeUtf8(text: string): Uint8Array {
+  return encoder.encode(text);
+}
+
+// ─── Buffered Aggregator ─────────────────────────────────────────────────────
+
+/**
+ * Pure buffer state for the buffered transform.
+ *
+ * Both Web and Node wrappers want the same behaviour: collect chunks that
+ * arrive in the same event-loop tick, decide whether the buffer has grown
+ * beyond `maxBufferByteLength` and must flush synchronously, then emit a
+ * single concatenated chunk on the next tick.
+ *
+ * The only thing the two wrappers disagree on is *who schedules the tick*
+ * (`setImmediate` callback vs Promise-based) and *how to push the merged
+ * chunk* (`controller.enqueue` vs `transform.push`). This class owns
+ * everything else.
+ */
+export class BufferAggregator {
+  private chunks: Uint8Array[] = [];
+  private byteLength = 0;
+
+  constructor(private readonly maxBufferByteLength: number = Infinity) {}
+
+  /**
+   * Append a chunk. Returns `true` if the caller should flush synchronously
+   * right now (the buffer has reached the byte cap), `false` if a deferred
+   * tick-end flush is sufficient.
+   */
+  append(chunk: Uint8Array): boolean {
+    this.chunks.push(chunk);
+    this.byteLength += chunk.byteLength;
+    return this.byteLength >= this.maxBufferByteLength;
+  }
+
+  /** Drain the buffer into a single concatenated chunk, or `null` if empty. */
+  drain(): Uint8Array | null {
+    if (this.chunks.length === 0) return null;
+
+    const merged = new Uint8Array(this.byteLength);
+    let offset = 0;
+    for (const chunk of this.chunks) {
+      merged.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    this.chunks = [];
+    this.byteLength = 0;
+    return merged;
+  }
+
+  get bufferedByteLength(): number {
+    return this.byteLength;
+  }
+
+  get isEmpty(): boolean {
+    return this.chunks.length === 0;
+  }
+}
+
+// ─── Suffix Mover ────────────────────────────────────────────────────────────
+
+/**
+ * Result of feeding one chunk through the suffix-mover state.
+ *
+ * - `passthrough` — already found and removed the suffix on a previous chunk.
+ *   Caller emits the chunk unchanged.
+ * - `noSuffix` — current chunk does not contain the suffix. Caller emits unchanged.
+ * - `suffixFound` — caller emits `before` and `after` (skipping the suffix
+ *   itself). The suffix will be re-emitted later by {@link suffixFlush}.
+ */
+export type SuffixChunkResult =
+  | { kind: 'passthrough' }
+  | { kind: 'noSuffix' }
+  | { kind: 'suffixFound'; before: Uint8Array | null; after: Uint8Array | null };
+
+export interface SuffixState {
+  found: boolean;
+}
+
+export function createSuffixState(): SuffixState {
+  return { found: false };
+}
+
+/**
+ * Search a chunk for {@link SUFFIX}. If found, mark state and return the
+ * surrounding bytes (the caller emits them; the suffix is held for the
+ * end of the stream). The bytes-vs-text dance matches what both Web and
+ * Node implementations did before extraction — search via decoded UTF-8
+ * to avoid splitting multi-byte characters at the suffix boundary.
+ */
+export function processSuffixChunk(state: SuffixState, chunk: Uint8Array): SuffixChunkResult {
+  if (state.found) return { kind: 'passthrough' };
+
+  const text = new TextDecoder().decode(chunk, { stream: true });
+  const idx = text.indexOf(SUFFIX);
+  if (idx === -1) return { kind: 'noSuffix' };
+
+  state.found = true;
+
+  // Whole chunk was the suffix — nothing to emit before/after.
+  if (chunk.byteLength === SUFFIX_BYTES.byteLength) {
+    return { kind: 'suffixFound', before: null, after: null };
+  }
+
+  const beforeText = text.slice(0, idx);
+  const afterText = text.slice(idx + SUFFIX.length);
+  return {
+    kind: 'suffixFound',
+    before: beforeText ? encoder.encode(beforeText) : null,
+    after: afterText ? encoder.encode(afterText) : null,
+  };
+}
+
+/**
+ * Final emit for the suffix mover. Always returns the suffix bytes — even
+ * if no suffix was ever observed in the input — so output is well-formed.
+ */
+export function suffixFlush(_state: SuffixState): Uint8Array {
+  return SUFFIX_BYTES;
+}
+
+// ─── Tag Injector (head / body) ──────────────────────────────────────────────
+
+/**
+ * Pure state for `injectHead`-style transforms: scan for a target tag,
+ * inject `content` once at the matching position, then pass everything
+ * else through. We keep a small trailing string buffer (just under the
+ * length of the target tag) so the tag can be detected even when split
+ * across chunk boundaries.
+ *
+ * The `decoder` is a long-lived `TextDecoder` reused across every chunk
+ * with `{ stream: true }`. This is required so a UTF-8 codepoint that
+ * spans two chunks (e.g. the bytes of `é` arriving in two halves) is
+ * reassembled correctly. A fresh decoder per chunk would drop or
+ * replace the partial codepoint and corrupt streamed HTML.
+ */
+export interface InjectorState {
+  injected: boolean;
+  tail: string;
+  readonly content: string;
+  readonly targetTag: string;
+  readonly position: 'before' | 'after';
+  readonly tailLen: number;
+  readonly decoder: TextDecoder;
+}
+
+export interface InjectorOptions {
+  content: string;
+  targetTag: string;
+  position?: 'before' | 'after';
+}
+
+export function createInjectorState(options: InjectorOptions): InjectorState {
+  return {
+    injected: false,
+    tail: '',
+    content: options.content,
+    targetTag: options.targetTag,
+    position: options.position ?? 'before',
+    tailLen: options.targetTag.length - 1,
+    decoder: new TextDecoder('utf-8'),
+  };
+}
+
+/**
+ * Result of feeding one chunk through {@link processInjectorChunk}.
+ *
+ * - `passthrough` — already injected. Emit `chunk` unchanged.
+ * - `emit` — emit the returned bytes (or nothing if `null`).
+ *
+ * Note: when not yet injected and the target tag is not present, the
+ * helper still emits the *safe head* of the buffer — everything except
+ * the trailing `tailLen` characters that might be the start of the
+ * target tag spilled into the next chunk. The unsafe tail is held in
+ * `state.tail` for the next call.
+ */
+export type InjectorChunkResult =
+  | { kind: 'passthrough' }
+  | { kind: 'emit'; bytes: Uint8Array | null };
+
+export function processInjectorChunk(state: InjectorState, chunk: Uint8Array): InjectorChunkResult {
+  if (state.injected) return { kind: 'passthrough' };
+
+  // Reuse the long-lived decoder so split UTF-8 codepoints are preserved
+  // across chunk boundaries. See comment on InjectorState.decoder.
+  const decoded = state.decoder.decode(chunk, { stream: true });
+  const text = state.tail + decoded;
+  const tagIndex = text.indexOf(state.targetTag);
+
+  if (tagIndex !== -1) {
+    const splitPoint = state.position === 'before' ? tagIndex : tagIndex + state.targetTag.length;
+    const before = text.slice(0, splitPoint);
+    const after = text.slice(splitPoint);
+    state.injected = true;
+    state.tail = '';
+    return { kind: 'emit', bytes: encoder.encode(before + state.content + after) };
+  }
+
+  // Tag not yet seen — flush everything except the last tailLen chars,
+  // which might be the start of the target tag split across chunks.
+  const safeEnd = Math.max(0, text.length - state.tailLen);
+  const safe = safeEnd > 0 ? text.slice(0, safeEnd) : '';
+  state.tail = text.slice(safeEnd);
+  return { kind: 'emit', bytes: safe ? encoder.encode(safe) : null };
+}
+
+/**
+ * Final emit for the injector. If the target tag never appeared, the
+ * leftover tail bytes are returned so they aren't lost. (The injection
+ * itself is silently skipped — same behaviour as before extraction.)
+ */
+export function injectorFlush(state: InjectorState): Uint8Array | null {
+  if (!state.injected && state.tail) return encoder.encode(state.tail);
+  return null;
+}
+
+// ─── Flight Injection Core ───────────────────────────────────────────────────
+
+/**
+ * Pure async core of the RSC flight-injection transform.
+ *
+ * Both wrappers (Web `TransformStream` and Node `Transform`) implement the
+ * exact same protocol around an RSC reader:
+ *
+ *   1. On the first HTML chunk, send `FIRST_CHUNK` and start the pull loop.
+ *   2. The pull loop reads from `rscReader` (timeout-guarded), wraps each
+ *      chunk in a `<script>` via `flightChunkScript`, and pushes it onto a
+ *      pending queue. Between reads, it yields with a single-shot
+ *      `setImmediate` so HTML chunks get event-loop priority — and after
+ *      yielding, it drains the queue (via the wrapper's `onYieldDrain`)
+ *      so flight data reaches the client at shell-flush time.
+ *   3. After every emitted HTML chunk, the wrapper drains the queue.
+ *   4. On `flush()` the wrapper sends `HTML_DONE` and awaits `pullPromise`.
+ *      No polling — just `.then()`.
+ *
+ * The wrappers only differ in:
+ *   - How they push bytes (controller.enqueue vs transform.push).
+ *   - How they signal a terminal error (controller.error vs transform.destroy).
+ *
+ * This class owns the state machine, the pending queue, and the pull
+ * loop itself. The wrapper supplies the drain callback and consumes the
+ * pending queue + machine state to decide what to push.
+ *
+ * **No polling.** See design/02-rendering-pipeline.md §"No Polling".
+ * **Always timeout-guarded reads.** Per design/02 §"Streaming Constraints".
+ */
+export class FlightInjectorCore {
+  readonly machine: Machine<FlightInjectionState, FlightInjectionEvent>;
+  /** Script chunks waiting to be drained between HTML chunks. */
+  readonly pending: Uint8Array[] = [];
+
+  private readonly rscReader: ReadableStreamDefaultReader<Uint8Array>;
+  private readonly timeoutMs: number;
+  private readonly errorSignal?: AbortSignal;
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true });
+  private pullPromise: Promise<void> | null = null;
+
+  constructor(
+    rscStream: ReadableStream<Uint8Array>,
+    renderTimeoutMs?: number,
+    errorSignal?: AbortSignal
+  ) {
+    this.rscReader = rscStream.getReader();
+    this.timeoutMs = renderTimeoutMs ?? 30_000;
+    this.errorSignal = errorSignal;
+    this.machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
+      initial: { phase: 'init' },
+      transitions: flightInjectionTransitions,
+    });
+  }
+
+  /** Tell the machine the first HTML chunk has arrived. Idempotent-ish: caller checks. */
+  notifyFirstChunk(): void {
+    this.machine.send({ type: 'FIRST_CHUNK' });
+  }
+
+  /** Tell the machine HTML output is finished — pull loop will stop yielding. */
+  notifyHtmlDone(): void {
+    this.machine.send({ type: 'HTML_DONE' });
+  }
+
+  get isInit(): boolean {
+    return this.machine.state.phase === 'init';
+  }
+
+  get isPullDone(): boolean {
+    return isPullDone(this.machine.state);
+  }
+
+  get hasPullPromise(): boolean {
+    return this.pullPromise !== null;
+  }
+
+  /**
+   * Get (or start) the pull-loop promise. The wrapper calls this from
+   * `flush()` and chains `.then()` onto it — never `await` without an
+   * existing finish callback (we don't want to block transform()).
+   *
+   * `onYieldDrain` is invoked between RSC reads while HTML is still
+   * streaming. It must drain the pending queue into the output stream.
+   */
+  ensurePullLoop(onYieldDrain: () => void): Promise<void> {
+    if (!this.pullPromise) {
+      this.pullPromise = this.runPullLoop(onYieldDrain);
+    }
+    return this.pullPromise;
+  }
+
+  /**
+   * Get the current terminal error if the machine is in the error phase,
+   * else `null`. Wrappers use this after a drain to decide whether to
+   * `controller.error()` / `transform.destroy()`.
+   */
+  get terminalError(): unknown {
+    return this.machine.state.phase === 'error' ? this.machine.state.error : null;
+  }
+
+  private async runPullLoop(onYieldDrain: () => void): Promise<void> {
+    // Yield once so the first HTML shell chunk flows through the wrapper
+    // before we start reading RSC data.
+    await new Promise<void>((r) => setImmediate(r));
+
+    try {
+      for (;;) {
+        // Guard each read with a timeout so a permanently hung RSC stream
+        // eventually aborts. See design/02 §"Streaming Constraints".
+        const readPromise = this.rscReader.read();
+        const { done, value } =
+          this.timeoutMs > 0
+            ? await withTimeout(readPromise, this.timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
+
+        if (done) {
+          this.machine.send({ type: 'PULL_DONE' });
+          return;
+        }
+
+        // If an unhandled RSC error was detected, stop injecting Flight
+        // data. Continue reading (to prevent tee buffer divergence) but
+        // discard the chunks so corrupted data never reaches the client.
+        // See TIM-938.
+        if (this.errorSignal?.aborted) {
+          continue;
+        }
+
+        const decoded = this.decoder.decode(value, { stream: true });
+        this.pending.push(encoder.encode(flightChunkScript(decoded)));
+
+        // Yield between reads so HTML chunks get priority — but only while
+        // HTML is still streaming. Once flush() fires (HTML_DONE), drain
+        // without yielding so remaining RSC data doesn't stall.
+        if (!isHtmlDone(this.machine.state)) {
+          await new Promise<void>((r) => setImmediate(r));
+          // After yielding, drain. Without this, hydration blocks waiting
+          // for flight data stuck in pending[]. Safe because we're between
+          // event-loop ticks (no transform() call mid-execution → no
+          // mid-tag risk; the buffered transform upstream coalesced HTML
+          // chunks to coherent fragments).
+          if (this.pending.length > 0) onYieldDrain();
+        }
+      }
+    } catch (err) {
+      if (err instanceof RenderTimeoutError) {
+        this.rscReader.cancel(err).catch(() => {});
+      }
+      this.machine.send({ type: 'PULL_ERROR', error: err });
+    }
+  }
+}