@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.150

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/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.js';
+import { formatSsrError } from './error-formatter.js';
+import type { TimberLogger } from './logger.js';
+
+/**
+ * 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/deny-boundary.ts

@@ -0,0 +1,311 @@
+/**
+ * Deny boundary subsystem — the in-tree DenySignal flow.
+ *
+ * Three things live together here because they form a single flow:
+ *
+ * 1. **Chain construction** (`buildDenyPageChain`) — walks the matched
+ *    segment chain at element-tree build time and produces a list of
+ *    `DenyPageEntry` records ordered by specificity (specific status →
+ *    category catch-all → `error.tsx`).
+ *
+ * 2. **Runtime matching** (`renderMatchingDenyPage`) — picks the first
+ *    chain entry whose status filter matches the thrown DenySignal and
+ *    returns a React element for the matching component. Used by
+ *    `AccessGate` and `PageDenyBoundary` when they catch a deny.
+ *
+ * 3. **The page boundary itself** (`PageDenyBoundary`) — the async server
+ *    component that wraps a server-component page, calls it, and catches
+ *    `DenySignal` so the deny page renders in-tree (no throw reaches
+ *    React Flight, single render pass).
+ *
+ * Plus the ALS helpers (`setDenyStatus` / `getDenyStatus`) the boundary
+ * uses to thread the matched status code back to the pipeline so the
+ * HTTP status reflects the deny.
+ *
+ * Folded into one module from the former `deny-page-resolver.ts` and
+ * `page-deny-boundary.tsx` (TIM-853) — the names were misleading and the
+ * three pieces only made sense together.
+ *
+ * See design/04-authorization.md, design/10-error-handling.md, TIM-666.
+ */
+
+import { createElement } from 'react';
+
+import { ErrorReconstituter } from '../client/error-reconstituter.js';
+import type { SerializableError } from '../client/error-reconstituter.js';
+import { requestContextAls } from './als-registry.js';
+import { DenySignal } from './primitives.js';
+import { loadModule } from './safe-load.js';
+import { LEGACY_FILE_TO_STATUS } from './status-code-resolver.js';
+import { withSpan } from './tracing.js';
+import { isMdxFilePath } from './utils/mdx-file.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** A single entry in the deny page fallback chain. */
+export interface DenyPageEntry {
+  /** Status code filter: specific (403), category (400 = any 4xx), or null (catch-all). */
+  status: number | null;
+  /** The component to render (server or client — both work). */
+  component: (...args: unknown[]) => unknown;
+  /**
+   * How the entry matched: a status-code file (404.tsx/4xx.tsx), a legacy
+   * compat file (not-found.tsx/forbidden.tsx/unauthorized.tsx), or the
+   * error.tsx catch-all. error.tsx entries render with their documented
+   * { error, digest, reset } contract, not bare deny props. See TIM-1081.
+   */
+  kind: 'status' | 'legacy' | 'error';
+  /** MDX files are server components — rendered with plain props, never ErrorReconstituter. */
+  isMdx: boolean;
+}
+
+// ─── Chain Construction ──────────────────────────────────────────────────
+
+/**
+ * Build the deny page fallback chain from the segment chain.
+ *
+ * Walks segments from `startIndex` outward (toward root) and collects
+ * status-code file components in fallback order:
+ * 1. Specific status files (403.tsx, 404.tsx) — exact match
+ * 2. Category catch-alls (4xx.tsx) — matches any 4xx
+ * 3. Legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
+ *    unauthorized.tsx → 401) — exact match
+ * 4. error.tsx — catches everything
+ *
+ * Each segment is checked in this order. The chain is ordered so the
+ * FIRST match wins at catch time. This mirrors resolveStatusFile's 4xx
+ * component chain (status-code-resolver.ts) — the two walks must stay in
+ * sync or in-tree and re-render deny paths resolve different files.
+ */
+export async function buildDenyPageChain(
+  segments: ManifestSegmentNode[],
+  startIndex: number
+): Promise<DenyPageEntry[]> {
+  const chain: DenyPageEntry[] = [];
+
+  // Pass 1: Status files (specific + category) across ALL segments.
+  // These have higher priority than error.tsx — a root 4xx.tsx should
+  // match before a leaf error.tsx. Walking inner → outer ensures the
+  // nearest match wins within each priority tier.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.statusFiles) continue;
+
+    // Specific status files (403.tsx, 404.tsx, etc.)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key !== '4xx' && key !== '5xx') {
+        const status = parseInt(key, 10);
+        if (!isNaN(status)) {
+          const mod = await loadModule(file).catch(() => null);
+          if (mod?.default) {
+            chain.push({
+              status,
+              component: mod.default as (...args: unknown[]) => unknown,
+              kind: 'status',
+              isMdx: isMdxFilePath(file.filePath),
+            });
+          }
+        }
+      }
+    }
+
+    // Category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key === '4xx' || key === '5xx') {
+        const mod = await loadModule(file).catch(() => null);
+        if (mod?.default) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          chain.push({
+            status: categoryStatus,
+            component: mod.default as (...args: unknown[]) => unknown,
+            kind: 'status',
+            isMdx: isMdxFilePath(file.filePath),
+          });
+        }
+      }
+    }
+  }
+
+  // Pass 2: legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
+  // unauthorized.tsx → 401). Lower priority than status files (a root
+  // 4xx.tsx beats a leaf not-found.tsx) but higher than error.tsx — the
+  // same ordering as resolveStatusFile's resolve4xx. See TIM-1081.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.legacyStatusFiles) continue;
+    for (const [name, status] of Object.entries(LEGACY_FILE_TO_STATUS)) {
+      const file = segment.legacyStatusFiles[name];
+      if (!file) continue;
+      const mod = await loadModule(file).catch(() => null);
+      if (mod?.default) {
+        chain.push({
+          status,
+          component: mod.default as (...args: unknown[]) => unknown,
+          kind: 'legacy',
+          isMdx: isMdxFilePath(file.filePath),
+        });
+      }
+    }
+  }
+
+  // Pass 3: error.tsx files — lowest priority catch-all.
+  // Only added AFTER all status and legacy files so they never shadow a
+  // more specific file from an ancestor segment.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (segment.error) {
+      const mod = await loadModule(segment.error).catch(() => null);
+      if (mod?.default) {
+        chain.push({
+          status: null,
+          component: mod.default as (...args: unknown[]) => unknown,
+          kind: 'error',
+          isMdx: isMdxFilePath(segment.error.filePath),
+        });
+      }
+    }
+  }
+
+  return chain;
+}
+
+// ─── Runtime Matcher ──────────────────────────────────────────────────────
+
+/**
+ * Find the first deny page in the chain that matches the given status code.
+ * Returns a React element for the matching component, or null if no match.
+ */
+export function renderMatchingDenyPage(
+  chain: DenyPageEntry[],
+  status: number,
+  data: unknown
+): React.ReactElement | null {
+  for (const entry of chain) {
+    if (entry.status === status) {
+      return renderDenyEntry(entry, status, data);
+    }
+    if (entry.status === 400 && status >= 400 && status <= 499) {
+      return renderDenyEntry(entry, status, data);
+    }
+    if (entry.status === 500 && status >= 500 && status <= 599) {
+      return renderDenyEntry(entry, status, data);
+    }
+    if (entry.status === null) {
+      return renderDenyEntry(entry, status, data);
+    }
+  }
+  return null;
+}
+
+/**
+ * Build the element for a matched deny chain entry with the props contract
+ * the file's convention documents:
+ *
+ * - Status-code and legacy files: { status, dangerouslyPassData }
+ * - error.tsx (TSX): { error, digest, reset } via ErrorReconstituter, plus
+ *   { status, dangerouslyPassData } for dual-shape implementations. Without
+ *   the Error prop, any error.tsx written per the docs (reading
+ *   error.message) crashes — turning a clean deny(404) into a 500. TIM-1081.
+ * - error.mdx: plain { status } — server component, static content.
+ */
+export function renderDenyEntry(
+  entry: DenyPageEntry,
+  status: number,
+  data: unknown
+): React.ReactElement {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+  if (entry.kind !== 'error') {
+    return h(entry.component, { status, dangerouslyPassData: data });
+  }
+
+  // MDX error pages receive plain props — no Error serialization possible.
+  if (entry.isMdx) {
+    return h(entry.component, { status });
+  }
+
+  // The message is derived solely from the status code (already on the
+  // wire) — safe to cross the RSC→client boundary in production. No stack,
+  // no user data. See design/13-security.md §"Errors don't leak".
+  const serializableDeny: SerializableError = {
+    message: `Access denied with status ${status}`,
+    name: 'DenySignal',
+  };
+  return h(ErrorReconstituter, {
+    error: serializableDeny,
+    digest: null,
+    reset: undefined,
+    component: entry.component,
+    status,
+    dangerouslyPassData: data,
+  });
+}
+
+// ─── Page Boundary ────────────────────────────────────────────────────────
+
+/**
+ * Async server component that wraps a page call with DenySignal catching.
+ *
+ * Calls the page component as an async function (the same thing React
+ * Flight does internally), awaits it, and catches DenySignal. On catch,
+ * renders the matching deny page in-tree. On success, returns the page's
+ * rendered output normally.
+ *
+ * Client component pages ('use client') are NOT wrapped — they can't call
+ * deny() (server-only API) and must go through createElement normally.
+ *
+ * No error reaches React Flight — the Flight stream is clean, SSR succeeds,
+ * and the entire request uses a single renderToReadableStream call.
+ */
+export async function PageDenyBoundary({
+  Page,
+  route,
+  denyPages,
+}: {
+  /** The page server component function. */
+  Page: (...args: unknown[]) => unknown;
+  /** Route path for OTEL tracing. */
+  route: string;
+  /** Deny page fallback chain from the segment chain. */
+  denyPages: DenyPageEntry[];
+}): Promise<React.ReactElement> {
+  try {
+    // Call the page as an async function — same as React Flight does.
+    // Wrap in OTEL span for tracing (replaces the TracedPage wrapper).
+    const result = await withSpan('timber.page', { 'timber.route': route }, () => Page({}));
+    return result as React.ReactElement;
+  } catch (error: unknown) {
+    if (error instanceof DenySignal) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
+      }
+    }
+    // Non-deny errors (RedirectSignal, runtime errors) propagate normally.
+    throw error;
+  }
+}
+
+// ─── ALS Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Set the deny status in the request context ALS.
+ * Called from AccessGate / PageDenyBoundary when a DenySignal is caught.
+ * The pipeline reads this after render to set the HTTP status code.
+ */
+export function setDenyStatus(status: number): void {
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.denyStatus = status;
+  }
+}
+
+/**
+ * Read the deny status from the request context ALS.
+ * Returns undefined if no deny was caught during render.
+ */
+export function getDenyStatus(): number | undefined {
+  return requestContextAls.getStore()?.denyStatus;
+}