@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/csp-nonce.ts

@@ -0,0 +1,70 @@
+/**
+ * CSP nonce — per-request, generated on demand.
+ *
+ * timber emits several inline `<script>` tags per HTML response — React's
+ * bootstrap script and Fizz runtime, the Flight init/chunk scripts, the
+ * segment-tree script, and the post-flush noindex script. Under a strict
+ * `Content-Security-Policy` (`script-src 'nonce-…' 'strict-dynamic'`) every
+ * one of them needs the request's nonce or the browser refuses to run it.
+ *
+ * The app opts in by reading `ctx.nonce` in `middleware.ts` and putting it
+ * in the CSP header it sets through `ctx.headers`. The first read generates
+ * the value and stores it on the request context; the render pipeline reads
+ * it back with `getCspNonce()` and stamps it on every inline script. A
+ * request whose middleware never reads `ctx.nonce` has no nonce, and its
+ * markup is byte-identical to a render without this feature. timber does
+ * not parse the CSP header — the app owns the policy, timber owns the
+ * markup, and `ctx.nonce` is the one value both are built from.
+ *
+ * `proxy.ts` cannot participate: it only sees the finished response from
+ * `next()`, after the markup exists.
+ *
+ * See design/13-security.md §"Content Security Policy" (TIM-1414).
+ */
+
+import { requestContextAls } from './als-registry.ts';
+
+/**
+ * Generate a CSP nonce: 128 random bits, base64. Matches CSP's
+ * `base64-value` grammar, so it is valid in the header verbatim and safe
+ * inside a double-quoted HTML attribute without escaping.
+ */
+function generateNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+/**
+ * The request's CSP nonce, creating it on first call. Backs the
+ * `ctx.nonce` getter on `MiddlewareContext`. Outside a request context
+ * (tests, build-time rendering) a fresh value is returned but not
+ * retained, since there is no request for it to belong to.
+ */
+export function requestCspNonce(): string {
+  const store = requestContextAls.getStore();
+  if (!store) return generateNonce();
+  store.cspNonce ??= generateNonce();
+  return store.cspNonce;
+}
+
+/**
+ * The request's CSP nonce if middleware asked for one, else `undefined` —
+ * in which case the pipeline emits bare `<script>` tags.
+ */
+export function getCspNonce(): string | undefined {
+  return requestContextAls.getStore()?.cspNonce;
+}
+
+/**
+ * The ` nonce="…"` attribute fragment for a timber-generated `<script>` tag,
+ * or `''` when the request has no nonce. Callers interpolate it directly
+ * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.
+ *
+ * The value comes from `generateNonce` and is base64, so no attribute
+ * escaping is required.
+ */
+export function nonceAttr(nonce: string | undefined): string {
+  return nonce ? ` nonce="${nonce}"` : '';
+}

package/src/server/csrf.ts

@@ -28,12 +28,36 @@ const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 // ─── Implementation ───────────────────────────────────────────────────────
 
 /**
- * Validate the Origin header against the request's Host.
+ * Derive the request's scheme from trusted sources.
+ *
+ * Priority:
+ * 1. X-Forwarded-Proto (set by reverse proxies / load balancers)
+ * 2. Request URL protocol
+ *
+ * Falls back to 'https' (fail closed) if neither is available.
+ */
+function deriveRequestScheme(req: Request): string {
+  const forwarded = req.headers.get('X-Forwarded-Proto');
+  if (forwarded) {
+    const proto = forwarded.split(',')[0].trim().toLowerCase();
+    if (proto === 'http' || proto === 'https') return proto;
+  }
+
+  try {
+    return new URL(req.url).protocol.replace(':', '');
+  } catch {
+    return 'https';
+  }
+}
+
+/**
+ * Validate the Origin header against the request's full origin
+ * (scheme + host + port).
  *
  * For mutation methods (POST, PUT, PATCH, DELETE):
  * - If `csrf: false`, skip validation.
  * - If `allowedOrigins` is set, Origin must match one exactly (no wildcards).
- * - Otherwise, Origin's host must match the request's Host header.
+ * - Otherwise, Origin must match the derived request origin.
  *
  * Safe methods (GET, HEAD, OPTIONS) always pass.
  */
@@ -67,13 +91,22 @@ export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
     return { ok: false, status: 403 };
   }
 
-  // Extract hostname from Origin URL and compare to Host header
-  let originHost: string;
+  // Compare full origins (scheme + host + port) using URL.origin for
+  // canonical port normalization (e.g. https://x:443 → https://x).
+  let originOrigin: string;
+  try {
+    originOrigin = new URL(origin).origin;
+  } catch {
+    return { ok: false, status: 403 };
+  }
+
+  const scheme = deriveRequestScheme(req);
+  let expectedOrigin: string;
   try {
-    originHost = new URL(origin).host;
+    expectedOrigin = new URL(`${scheme}://${host}`).origin;
   } catch {
     return { ok: false, status: 403 };
   }
 
-  return originHost === host ? { ok: true } : { ok: false, status: 403 };
+  return originOrigin === expectedOrigin ? { ok: true } : { ok: false, status: 403 };
 }

package/src/server/debug.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime debug flag for timber.js.
+ *
+ * Two distinct functions for two distinct security levels:
+ *
+ * ## `isDebug()` — server-side logging only
+ *
+ * Returns true when timber's debug/warning messages should be written to
+ * stderr / the server console. This NEVER affects what is sent to the
+ * client (no error details, no timing headers, no stack traces).
+ *
+ * Active when any of:
+ * - `NODE_ENV !== 'production'` (standard dev mode)
+ * - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+ * - `timber.config.ts` has `debug: true`
+ *
+ * ## `isDevMode()` — client-visible dev behavior
+ *
+ * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+ * that changes what clients can observe:
+ * - Dev error pages with stack traces (fallback-error.ts)
+ * - Detailed Server-Timing headers (pipeline.ts)
+ * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * `isDevMode()` is statically replaced in production builds → the guarded
+ * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+ *
+ * Usage:
+ *   In Cloudflare Workers wrangler.toml:
+ *     [vars]
+ *     TIMBER_DEBUG = "1"
+ *
+ *   In Node.js:
+ *     TIMBER_DEBUG=1 node server.js
+ *
+ *   In timber.config.ts:
+ *     export default { debug: true }
+ *
+ * See design/13-security.md for the security taxonomy.
+ * See design/18-build-system.md for build pipeline details.
+ */
+
+// ─── Dev Mode (client-visible) ──────────────────────────────────────────────
+
+/**
+ * Check if the application is running in development mode.
+ *
+ * This is the ONLY function that should gate client-visible dev behavior:
+ * - Dev error pages with stack traces
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+ * - Error messages in action `INTERNAL_ERROR` payloads
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * Returns `process.env.NODE_ENV !== 'production'`, which is statically
+ * replaced by the bundler in production builds. Code guarded by this
+ * function is tree-shaken to zero bytes in production.
+ *
+ * TIMBER_DEBUG does NOT enable this — that would leak server internals
+ * to clients. Use `isDebug()` for server-side-only logging.
+ */
+export function isDevMode(): boolean {
+  return process.env.NODE_ENV !== 'production';
+}
+
+// ─── Debug Flag (server-side logging only) ──────────────────────────────────
+
+/**
+ * Config-level debug override. Set via `setDebugFromConfig()` during
+ * initialization when timber.config.ts has `debug: true`.
+ */
+let _configDebug = false;
+
+/**
+ * Set the debug flag from timber.config.ts.
+ * Called during handler initialization.
+ */
+export function setDebugFromConfig(debug: boolean): void {
+  _configDebug = debug;
+}
+
+/**
+ * Check if timber debug logging is active (server-side only).
+ *
+ * Returns true if ANY of these conditions hold:
+ * - NODE_ENV is not 'production' (standard dev mode)
+ * - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+ * - timber.config.ts has `debug: true`
+ *
+ * This function controls ONLY server-side logging — messages written to
+ * stderr or the server console. It NEVER affects client-visible behavior
+ * (error pages, response headers, action payloads). For client-visible
+ * behavior, use `isDevMode()`.
+ *
+ * The TIMBER_DEBUG check is deliberately written as a dynamic property
+ * access so bundlers cannot statically replace it.
+ */
+export function isDebug(): boolean {
+  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)
+  if (process.env.NODE_ENV !== 'production') return true;
+
+  // Config override
+  if (_configDebug) return true;
+
+  // Runtime env var check — uses dynamic access to prevent static replacement.
+  // In production builds, process.env.NODE_ENV is statically replaced, but
+  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access
+  // pattern ensures the bundler treats this as opaque.
+  return _readTimberDebugEnv();
+}
+
+/**
+ * Read TIMBER_DEBUG from the environment at runtime.
+ *
+ * Extracted to a separate function to:
+ * 1. Prevent bundler inlining (cross-module function calls are not inlined)
+ * 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+ * 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+ */
+function _readTimberDebugEnv(): boolean {
+  // globalThis override — useful for programmatic control and testing
+  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;
+
+  // process.env — works in Node.js and platforms that polyfill process
+  try {
+    const key = 'TIMBER_DEBUG';
+    const val =
+      typeof process !== 'undefined' && process.env
+        ? (process.env as Record<string, string | undefined>)[key]
+        : undefined;
+    if (val && val !== '0' && val !== 'false') return true;
+  } catch {
+    // process may not exist or env may throw — safe to ignore
+  }
+
+  return false;
+}

package/src/server/default-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * DefaultLogger — human-readable stderr logging when no custom logger is configured.
+ *
+ * Ships as the fallback so production deployments always have error visibility,
+ * even without an `instrumentation.ts` logger export. Output is one line per
+ * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+ *
+ * Format:
+ *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+ *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+ *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+ *
+ * Behavior:
+ * - Suppressed entirely in dev mode (dev logging handles all output)
+ * - `debug` suppressed unless TIMBER_DEBUG is set
+ * - Replaced entirely when a custom logger is set via `setLogger()`
+ *
+ * See design/17-logging.md §"DefaultLogger"
+ */
+
+import { isDevMode, isDebug } from './debug.ts';
+import { formatSsrError } from './error-formatter.ts';
+import type { TimberLogger } from './logger.ts';
+
+/**
+ * Format data fields as `key=value` pairs for human-readable output.
+ * - `error` key is serialized via formatSsrError for stack trace cleanup
+ * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+ * - Other values are stringified inline
+ */
+function formatDataFields(data?: Record<string, unknown>): string {
+  if (!data) return '';
+
+  const parts: string[] = [];
+  let traceId: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'trace_id') {
+      // Defer trace_id to the end
+      traceId = typeof value === 'string' ? value : String(value);
+      continue;
+    }
+    if (key === 'error') {
+      // Serialize errors with formatSsrError for clean output
+      parts.push(`error=${formatSsrError(value)}`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${value}`);
+  }
+
+  // trace_id always last, truncated to 8 chars for readability
+  if (traceId) {
+    parts.push(`trace_id=${traceId.slice(0, 8)}`);
+  }
+
+  return parts.length > 0 ? '  ' + parts.join('  ') : '';
+}
+
+/** Pad level string to fixed width for alignment. */
+function padLevel(level: string): string {
+  return level.padEnd(5);
+}
+
+export function createDefaultLogger(): TimberLogger {
+  return {
+    error(msg: string, data?: Record<string, unknown>): void {
+      // Errors are ALWAYS logged, including dev mode. Suppressing errors
+      // in dev causes silent 500s with no stack trace, making route.ts
+      // and render errors impossible to debug. See TIM-555.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      // Warnings are always logged — same rationale as errors.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\n`);
+    },
+
+    info(msg: string, data?: Record<string, unknown>): void {
+      // info is suppressed by default — per-request lines are too noisy
+      // without a custom logger. Enable with TIMBER_DEBUG.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\n`);
+    },
+
+    debug(msg: string, data?: Record<string, unknown>): void {
+      // debug is suppressed in dev (dev logger handles it) and in
+      // production unless TIMBER_DEBUG is explicitly set.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\n`);
+    },
+  };
+}

package/src/server/default-status-page.ts

@@ -0,0 +1,88 @@
+/**
+ * Framework default status page — the terminal fallback of the deny chain.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every 4xx/5xx chain in a
+ * "framework default page". Before TIM-1258 that terminal did not exist: an app
+ * with no `404.tsx` / `4xx.tsx` / `error.tsx` got `Response(null, { status })` —
+ * a correct status code with an empty body. Browsers render that as a blank
+ * page, and static generation had nothing to write to `404.html`.
+ *
+ * This page is a plain HTML string rather than a React component on purpose:
+ * it is the *last* fallback, so it must not depend on the RSC → SSR pipeline
+ * (the machinery that may already have failed by the time we get here), and it
+ * must be renderable from the static build where no render environment exists.
+ * One builder is the single source of truth for both surfaces.
+ *
+ * Security: the page interpolates nothing but the status code, and the code is
+ * clamped to a plain integer before it reaches the markup. No request URL, no
+ * error message, no stack — see design/13-security.md principle 4.
+ */
+
+import { displayStatus, statusReasonPhrase } from '../shared/status-reason-phrase.ts';
+
+// The phrase table and status clamp live in `shared/status-reason-phrase.ts`:
+// the client-form terminal (`client/deny-last-resort.tsx`) renders the same
+// words for a deny that streamed past every boundary, and one table keeps the
+// two surfaces from drifting.
+export { statusReasonPhrase };
+
+/** HTML content type used for every framework default page response. */
+export const DEFAULT_STATUS_PAGE_CONTENT_TYPE = 'text/html; charset=utf-8';
+
+/**
+ * Build the framework default page for a status code as a full HTML document.
+ *
+ * The document is self-contained: no scripts, no external resources, no client
+ * JavaScript. It renders identically in `server` mode, in `static` mode's
+ * generated `404.html`, and with `clientJavascript: false`.
+ */
+export function defaultStatusPageHtml(status: number): string {
+  const code = displayStatus(status);
+  const phrase = statusReasonPhrase(code);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${code} ${phrase}</title>
+<style>
+:root { color-scheme: light dark; --fg: #1a1a1a; --muted: #6b6b76; --bg: #ffffff; }
+@media (prefers-color-scheme: dark) { :root { --fg: #ededf1; --muted: #9b9baa; --bg: #111114; } }
+html, body { height: 100%; margin: 0; }
+body {
+  display: flex; align-items: center; justify-content: center;
+  background: var(--bg); color: var(--fg);
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  text-align: center; padding: 2rem;
+  box-sizing: border-box;
+}
+h1 { font-size: 3rem; font-weight: 600; margin: 0; letter-spacing: -0.02em; }
+p { margin: 0.5rem 0 0; color: var(--muted); font-size: 1rem; }
+</style>
+</head>
+<body>
+<main>
+<h1>${code}</h1>
+<p>${phrase}</p>
+</main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Build the framework default page as an HTTP `Response`.
+ *
+ * `responseHeaders` carries whatever middleware/proxy already set (cookies,
+ * cache directives); the content type is overwritten because the body is
+ * always HTML regardless of what the route would have produced.
+ *
+ * The body is unconditional. HEAD is not this function's problem: the pipeline
+ * strips HEAD bodies at its single exit for every response shape, so a
+ * `method` parameter here would be one renderer's private copy of a rule that
+ * now holds framework-wide (TIM-1324).
+ */
+export function defaultStatusPageResponse(status: number, responseHeaders: Headers): Response {
+  responseHeaders.set('content-type', DEFAULT_STATUS_PAGE_CONTENT_TYPE);
+  return new Response(defaultStatusPageHtml(status), { status, headers: responseHeaders });
+}