@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/csrf.ts

@@ -1,79 +1,272 @@
 /**
- * CSRF protection — Origin header validation.
+ * CSRF protection — Fetch Metadata first, Origin as the fallback.
  *
- * Auto-derived from the Host header for single-origin deployments.
- * Configurable via allowedOrigins for multi-origin setups.
- * Disable with csrf: false (not recommended outside local dev).
+ * CSRF needs a victim's browser to attach cookies, and browsers mark the
+ * requests they send: `Sec-Fetch-Site` on HTTPS (and localhost) pages in
+ * every current browser, `Origin` on cross-site POSTs everywhere else. So
+ * the check trusts those two headers in that order, and lets a request
+ * carrying neither through — a webhook, curl, or a server-to-server
+ * `fetch`. The residual risk is browsers old enough to send neither on a
+ * form POST (Firefox < 70, IE11); SameSite cookies are the defense there.
+ * See design/08-forms-and-actions.md §"CSRF Protection".
+ *
+ * Prior art: Go's `net/http.CrossOriginProtection` (Go 1.25) and the OWASP
+ * CSRF cheat sheet (Fetch Metadata as a primary defense).
+ *
+ * The per-route exemption (`export const csrf = false` in route.ts) is not
+ * decided here: the caller owns route matching and applies it to a
+ * rejection. Disable globally with csrf: false (not recommended).
  *
  * See design/08-forms-and-actions.md §"CSRF Protection"
  * See design/13-security.md §"Security Testing Checklist" #6
  */
 
+import { logCsrfRejected } from './logger.ts';
+import { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../shared/csrf-reject.ts';
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 export interface CsrfConfig {
-  /** Explicit list of allowed origins. Replaces Host-based auto-derivation. */
+  /**
+   * Origins trusted in addition to the request's own. Canonical origins
+   * only (`new URL(x).origin === x`); `validateConfig` enforces that.
+   */
   allowedOrigins?: string[];
   /** Set to false to disable CSRF validation entirely. */
   csrf?: boolean;
 }
 
-export type CsrfResult = { ok: true } | { ok: false; status: 403 };
+/** Why a request failed the check — one value per rejection path. */
+export type CsrfRejectReason =
+  | 'cross-origin'
+  | 'missing-host'
+  | 'invalid-host'
+  | 'invalid-origin'
+  | 'origin-mismatch';
+
+/**
+ * A failed check. `origin` is the request's Origin header and `fetchSite`
+ * its Sec-Fetch-Site header (null when absent); `expected` is the origin(s)
+ * `origin` was compared against: the `allowedOrigins` list, preceded on
+ * `origin-mismatch` by the origin derived from the Host header. All three are for
+ * the server log only — never the response.
+ */
+export interface CsrfRejection {
+  ok: false;
+  status: 403;
+  reason: CsrfRejectReason;
+  origin: string | null;
+  fetchSite: string | null;
+  expected: readonly string[];
+}
+
+export type CsrfResult = { ok: true } | CsrfRejection;
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
 /** HTTP methods that are considered safe (no mutation). */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 
+/**
+ * `Sec-Fetch-Site` values that mean the browser itself vouches for the
+ * request: `same-origin`, or `none` (user-initiated — typed URL, bookmark).
+ * Every other value, including ones no browser sends, is not same-origin.
+ * The header is forbidden to page scripts, so a page cannot forge it.
+ */
+const TRUSTED_FETCH_SITES = new Set(['same-origin', 'none']);
+
 // ─── Implementation ───────────────────────────────────────────────────────
 
 /**
- * Validate the Origin header against the request's Host.
+ * Derive the request's scheme from trusted sources.
  *
- * 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.
+ * Priority:
+ * 1. X-Forwarded-Proto (set by reverse proxies / load balancers)
+ * 2. Request URL protocol
  *
- * Safe methods (GET, HEAD, OPTIONS) always pass.
+ * Falls back to 'https' (fail closed) if neither is available.
  */
-export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
-  // Safe methods don't need CSRF protection
-  if (SAFE_METHODS.has(req.method)) {
-    return { ok: true };
+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;
   }
 
-  // Explicitly disabled
-  if (config.csrf === false) {
-    return { ok: true };
+  try {
+    return new URL(req.url).protocol.replace(':', '');
+  } catch {
+    return 'https';
   }
+}
+
+/**
+ * Decide whether an unsafe-method request may proceed.
+ *
+ * In order:
+ * 1. `Sec-Fetch-Site` is `same-origin` or `none` → allow.
+ * 2. `Sec-Fetch-Site` has any other value → allow only if `Origin` is in
+ *    `allowedOrigins`.
+ * 3. No `Sec-Fetch-Site`, `Origin` present (a plain-HTTP page, or an
+ *    older browser) → `Origin` must be in `allowedOrigins` or equal the
+ *    origin derived from the scheme and `Host`.
+ * 4. Neither header → allow: not a browser, so no ambient cookies to abuse.
+ *
+ * Safe methods (GET, HEAD, OPTIONS) and `csrf: false` always pass.
+ */
+export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
+  if (SAFE_METHODS.has(req.method)) return { ok: true };
+  if (config.csrf === false) return { ok: true };
 
+  const fetchSite = req.headers.get('Sec-Fetch-Site');
   const origin = req.headers.get('Origin');
+  const rejection = (reason: CsrfRejectReason, expected: readonly string[]): CsrfRejection => ({
+    ok: false,
+    status: 403,
+    reason,
+    origin,
+    fetchSite,
+    expected,
+  });
 
-  // No Origin header on a mutation → reject
-  if (!origin) {
-    return { ok: false, status: 403 };
+  // Steps 1–2: the browser told us where the request came from.
+  if (fetchSite !== null) {
+    if (TRUSTED_FETCH_SITES.has(fetchSite)) return { ok: true };
+    if (origin !== null && config.allowedOrigins?.includes(origin)) return { ok: true };
+    return rejection('cross-origin', config.allowedOrigins ?? []);
   }
 
-  // If allowedOrigins is configured, use that instead of Host-based derivation
-  if (config.allowedOrigins) {
-    const allowed = config.allowedOrigins.includes(origin);
-    return allowed ? { ok: true } : { ok: false, status: 403 };
-  }
+  // Step 4: no browser marker at all.
+  if (origin === null) return { ok: true };
+
+  // Step 3: Origin only. The request's own origin, or a listed one — the
+  // same two sources step 2 trusts, so a same-origin POST from a page that
+  // gets no Fetch Metadata (plain HTTP) never needs listing (Go's
+  // CrossOriginProtection makes the same union).
+  const allowed = config.allowedOrigins ?? [];
+  if (allowed.includes(origin)) return { ok: true };
 
-  // Auto-derive from Host header
   const host = req.headers.get('Host');
-  if (!host) {
-    return { ok: false, status: 403 };
+  if (!host) return rejection('missing-host', allowed);
+
+  // 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 rejection('invalid-origin', allowed);
   }
 
-  // Extract hostname from Origin URL and compare to Host header
-  let originHost: string;
+  let expectedOrigin: string;
   try {
-    originHost = new URL(origin).host;
+    expectedOrigin = new URL(`${deriveRequestScheme(req)}://${host}`).origin;
   } catch {
-    return { ok: false, status: 403 };
+    return rejection('invalid-host', allowed);
+  }
+
+  return originOrigin === expectedOrigin
+    ? { ok: true }
+    : rejection('origin-mismatch', [expectedOrigin, ...allowed]);
+}
+
+// ─── Rejection Response ───────────────────────────────────────────────────
+
+/**
+ * Longest request-derived value echoed into the server log. Origin, Host,
+ * Sec-Fetch-Site, and the path are attacker-controlled; a request can carry
+ * kilobytes in each, and every rejection writes a log line. Real values are
+ * far shorter.
+ */
+const MAX_LOGGED_VALUE = 200;
+
+function clip(value: string): string {
+  return value.length > MAX_LOGGED_VALUE ? `${value.slice(0, MAX_LOGGED_VALUE)}…` : value;
+}
+
+/**
+ * Clip and quote a request-derived value for the log. JSON quoting escapes
+ * quotes and control characters, so a crafted header cannot close the quote
+ * and forge `key=value` fields or a second line.
+ */
+function quote(value: string): string {
+  return JSON.stringify(clip(value));
+}
+
+const PROXY_HINT =
+  'If the app runs behind a proxy that rewrites Host or terminates TLS, forward the ' +
+  'original Host and X-Forwarded-Proto, or list the public origin in allowedOrigins ' +
+  'in timber.config.ts.';
+
+const EXEMPTION_HINT =
+  'If this route.ts must accept cross-site browser requests (OIDC form_post, SAML, ' +
+  '3-D Secure returns), add `export const csrf = false` to it.';
+
+/**
+ * Browsers send `Origin: null` from opaque contexts: sandboxed iframes, a POST
+ * redirected across origins, file: pages. Every such context shares the one
+ * value — an attacker's `<iframe sandbox>` included — so config validation
+ * refuses it in `allowedOrigins` and the hint points at the exemption instead.
+ */
+const OPAQUE_ORIGIN_DETAIL =
+  'origin "null" is an opaque origin (sandboxed iframe, a POST redirected across ' +
+  'origins, or a file: page). allowedOrigins cannot admit it: every opaque context ' +
+  `sends "null", including an attacker's sandboxed iframe. ${EXEMPTION_HINT}`;
+
+/** One sentence per rejection path: what was observed, and what to change. */
+function describeRejection(r: CsrfRejection, host: string | null): string {
+  const opaque = r.origin === 'null';
+  const origin = quote(r.origin ?? '');
+  const expected = r.expected.map(quote).join(', ');
+  switch (r.reason) {
+    // The opaque-origin note replaces only the reasons where the origin
+    // itself is the fault. A null-origin request that fails for another
+    // reason (no Host, a bad Host) keeps that reason's diagnosis and hint.
+    case 'cross-origin': {
+      if (opaque) return OPAQUE_ORIGIN_DETAIL;
+      const from = r.origin === null ? 'with no Origin header' : `from origin ${origin}`;
+      const allowed = r.expected.length > 0 ? ` and is not in allowedOrigins [${expected}]` : '';
+      return (
+        `Sec-Fetch-Site ${quote(r.fetchSite ?? '')} request ${from}: the browser reports ` +
+        `it is not same-origin${allowed}. If this origin is legitimate, add it to ` +
+        `allowedOrigins in timber.config.ts. ${EXEMPTION_HINT}`
+      );
+    }
+    case 'missing-host':
+      return `origin ${origin} could not be checked: request has no Host header. ${PROXY_HINT}`;
+    case 'invalid-host':
+      return `origin ${origin} could not be checked: Host header ${quote(host ?? '')} is not a valid host. ${PROXY_HINT}`;
+    case 'invalid-origin':
+      if (opaque) return OPAQUE_ORIGIN_DETAIL;
+      return `Origin header ${origin} is not a valid origin.`;
+    case 'origin-mismatch': {
+      const [own, ...listed] = r.expected.map(quote);
+      const list = listed.length > 0 ? ` or allowedOrigins [${listed.join(', ')}]` : '';
+      return `origin ${origin} does not match the request origin ${own}${list}. ${PROXY_HINT}`;
+    }
   }
+}
 
-  return originHost === host ? { ok: true } : { ok: false, status: 403 };
+/**
+ * Turn a failed check into the response the client sees, and log why.
+ *
+ * The response is a 403 marked as a CSRF rejection (header + plain-text
+ * body) so it cannot be mistaken for an access-control 403. It never
+ * carries the observed or expected origins — `allowedOrigins` is server
+ * configuration, and a Host-derived origin can be an internal hostname
+ * behind a proxy. The server log gets the full diagnosis.
+ */
+export function csrfRejectionResponse(req: Request, rejection: CsrfRejection): Response {
+  logCsrfRejected(describeRejection(rejection, req.headers.get('Host')), {
+    method: req.method,
+    path: clip(new URL(req.url).pathname),
+    reason: rejection.reason,
+  });
+  return new Response('Forbidden: CSRF origin check failed\n', {
+    status: rejection.status,
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+      [CSRF_REJECT_HEADER]: CSRF_REJECT_VALUE,
+    },
+  });
 }

package/src/server/debug.ts

@@ -48,7 +48,6 @@
  *
  * 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)
  *

package/src/server/default-logger.ts

@@ -0,0 +1,100 @@
+/**
+ * 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:
+ * - `info` and `debug` suppressed in dev mode (dev logging handles them);
+ *   `warn` and `error` are always written (TIM-555)
+ * - `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 });
+}