@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/server/deny-boundary.ts

@@ -0,0 +1,516 @@
+/**
+ * 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 and placement** (`matchDenyEntry`, `placeDenyPage`,
+ *    `handleCaughtDeny`) — picks the first chain entry whose status filter
+ *    matches the thrown DenySignal, then decides whether the catch site may
+ *    render it where it stands. A chain spans the catcher outward to root,
+ *    so a match may belong to an ancestor segment; rendering it in place
+ *    would wrap it in every layout in between. Ancestor-owned matches are
+ *    re-thrown with `ownerKey` stamped on the signal so the error boundary
+ *    at the owning segment renders it. See TIM-1356.
+ *
+ * 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 type { ManifestLoader } from './safe-load.js';
+import { withSpan } from './tracing.js';
+import { isValidElementType, type LoadedComponent } from './utils/element-type.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) 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' | 'error';
+  /** MDX files are server components — rendered with plain props, never ErrorReconstituter. */
+  isMdx: boolean;
+  /**
+   * Position in the segment chain (0 = root, ascending toward leaf).
+   * Used by `matchDenyEntry` to reconstruct per-segment ordering for 5xx
+   * statuses — `resolve5xx` walks per-segment (status files then error.tsx
+   * at each segment before moving outward), while the chain is stored in
+   * the 4xx two-pass order. Without this, `deny(503)` resolves to a
+   * different file depending on which path serves it. See TIM-1360.
+   */
+  segmentIndex: number;
+  /**
+   * Segment key of the segment whose directory holds this file — where the
+   * deny page must render, which is not necessarily where it was caught.
+   *
+   * A chain flattens every segment from the catcher outward to root, so
+   * without this a catcher cannot tell a file it owns from an ancestor's,
+   * and renders both at its own position — wrapping the deny page in every
+   * layout in between (TIM-1356).
+   *
+   * A **key**, not an index: `computeSegmentKeys` produces the identity the
+   * client segment cache already navigates by, and it survives the trip
+   * through the Flight digest to a boundary the client mounted on an
+   * earlier navigation. A chain position would not — depth varies with
+   * route groups and interception.
+   *
+   * It inherits that key's known collision rather than fixing it: keys reset
+   * to `urlPath` at each URL-visible segment, so `(browse)/feed` and
+   * `(landing)/feed` are both `/feed` (see `routing/segment-keys.ts`). Two
+   * such branches are already indistinguishable to the skip decision and the
+   * client cache, so a deny addressed across them can land in the wrong
+   * branch's layout. Fixing that means fixing the key for every reader, not
+   * minting a second identity here.
+   */
+  ownerKey: string;
+}
+
+/**
+ * What `renderDenyEntry` needs to build the element: which component, and
+ * which props contract it expects. Deliberately excludes `ownerKey` — the
+ * re-render fallback path builds an entry from a `resolveStatusFile`
+ * resolution that already carries the position, and would otherwise have to
+ * invent an owner it never reads.
+ */
+export type DenyEntryShape = Pick<DenyPageEntry, 'component' | 'kind' | 'isMdx'>;
+
+/**
+ * Where a matched deny page must render, relative to the catcher that
+ * matched it.
+ *
+ * `render` — the catcher owns the file and is already at the right
+ * position. `hoist` — an ancestor owns it; the catcher must re-throw so the
+ * boundary at `ownerKey` renders it, outside the layouts in between.
+ */
+export type DenyPlacement =
+  | { kind: 'render'; element: React.ReactElement }
+  | { kind: 'hoist'; ownerKey: string };
+
+// ─── Chain Construction ──────────────────────────────────────────────────
+
+/**
+ * Load a candidate's default export, or null if it cannot be a component.
+ *
+ * Gated on `isValidElementType` — the same predicate `error-boundary-wrapper.ts`
+ * uses to decide whether to create a boundary at all, and deliberately not a
+ * second expression of it. A file this walk accepts but that one rejects
+ * yields a chain entry whose owner has no boundary, so a deny addressed to it
+ * passes every boundary and escapes with nothing to catch it. (Before the two
+ * agreed, such an entry instead crashed inside `createElement` when rendered
+ * in place.)
+ *
+ * Agreement is per-file, which is not the same as per-segment: this walk runs
+ * over every segment in the chain, while the boundary walk is skipped for a
+ * segment the client already has cached. See the skip branch in
+ * `route-element-builder.ts` for why that case still lands.
+ *
+ * See TIM-1356.
+ */
+async function loadChainComponent(file: ManifestLoader): Promise<LoadedComponent | null> {
+  const mod = await loadModule(file).catch(() => null);
+  return isValidElementType(mod?.default) ? mod.default : null;
+}
+
+/**
+ * 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, 5xx.tsx) — matches any in category
+ * 3. error.tsx — catches everything
+ *
+ * The chain is stored in the 4xx two-pass order (all status files across
+ * segments, then all error.tsx), which mirrors `resolve4xx`. For 5xx,
+ * `matchDenyEntry` reconstructs the per-segment walk from each entry's
+ * `segmentIndex` — matching `resolve5xx`'s single-pass ordering where a
+ * leaf `error.tsx` beats a root `5xx.tsx`. See TIM-1360.
+ */
+export async function buildDenyPageChain(
+  segments: ManifestSegmentNode[],
+  startIndex: number,
+  segmentKeys: string[]
+): 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 component = await loadChainComponent(file);
+          if (component) {
+            chain.push({
+              status,
+              component,
+              kind: 'status',
+              isMdx: isMdxFilePath(file.filePath),
+              segmentIndex: i,
+              ownerKey: segmentKeys[i],
+            });
+          }
+        }
+      }
+    }
+
+    // Category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key === '4xx' || key === '5xx') {
+        const component = await loadChainComponent(file);
+        if (component) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          chain.push({
+            status: categoryStatus,
+            component,
+            kind: 'status',
+            isMdx: isMdxFilePath(file.filePath),
+            segmentIndex: i,
+            ownerKey: segmentKeys[i],
+          });
+        }
+      }
+    }
+  }
+
+  // Pass 2: 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 component = await loadChainComponent(segment.error);
+      if (component) {
+        chain.push({
+          status: null,
+          component,
+          kind: 'error',
+          isMdx: isMdxFilePath(segment.error.filePath),
+          segmentIndex: i,
+          ownerKey: segmentKeys[i],
+        });
+      }
+    }
+  }
+
+  return chain;
+}
+
+// ─── Runtime Matcher ──────────────────────────────────────────────────────
+
+/**
+ * Find the first deny page in the chain whose status filter matches.
+ * Returns null when nothing in the chain accepts this status.
+ *
+ * For 4xx statuses, the chain's stored order is correct: every status file
+ * across all segments (inner→outer) before any error.tsx — so a root
+ * `404.tsx` beats a leaf `error.tsx`. This matches `resolve4xx`.
+ *
+ * For 5xx statuses, the match walks per-segment (inner→outer): at each
+ * segment, status files (`503.tsx` → `5xx.tsx`) then `error.tsx`, before
+ * moving to the next segment outward. A leaf `error.tsx` therefore beats a
+ * root `5xx.tsx` — the intentional inverse of the 4xx chain, matching
+ * `resolve5xx`. See TIM-1360.
+ */
+export function matchDenyEntry(chain: DenyPageEntry[], status: number): DenyPageEntry | null {
+  if (status >= 500) return matchDenyEntry5xx(chain, status);
+
+  for (const entry of chain) {
+    if (entry.status === status) return entry;
+    if (entry.status === 400 && status >= 400 && status <= 499) return entry;
+    if (entry.status === null) return entry;
+  }
+  return null;
+}
+
+/**
+ * 5xx per-segment walk: at each segment (inner→outer), check status files
+ * then error.tsx before moving outward. Mirrors `resolve5xx`.
+ */
+function matchDenyEntry5xx(chain: DenyPageEntry[], status: number): DenyPageEntry | null {
+  // Collect unique segment indices, sorted descending (inner→outer).
+  const segmentIndices: number[] = [];
+  for (const entry of chain) {
+    if (!segmentIndices.includes(entry.segmentIndex)) {
+      segmentIndices.push(entry.segmentIndex);
+    }
+  }
+  segmentIndices.sort((a, b) => b - a);
+
+  for (const seg of segmentIndices) {
+    // Status files at this segment (exact then category).
+    for (const entry of chain) {
+      if (entry.segmentIndex !== seg || entry.kind === 'error') continue;
+      if (entry.status === status) return entry;
+      if (entry.status === 500 && status >= 500 && status <= 599) return entry;
+    }
+    // error.tsx at this segment.
+    for (const entry of chain) {
+      if (entry.segmentIndex !== seg || entry.kind !== 'error') continue;
+      return entry;
+    }
+  }
+  return null;
+}
+
+/**
+ * Decide where the deny page for `status` renders, from the perspective of
+ * the catch site at `selfKey`.
+ *
+ * The match itself is unchanged — first entry in fallback order wins, so
+ * every path picks the same file. What this adds is the position: a chain
+ * built at segment i spans i outward to root, so a matched entry is owned
+ * either by the catcher or by one of its ancestors.
+ *
+ * - Owned by the catcher → `render`. The catcher already sits at the
+ *   owning segment's position.
+ * - Owned by an ancestor → `hoist`. Rendering here would wrap the deny page
+ *   in every layout between the owner and the catcher. The caller re-throws
+ *   with `ownerKey` stamped on the signal so the boundary at that segment
+ *   renders it instead — inside the owner's layout, outside the rest.
+ *
+ * Returns null when no entry matches; the caller re-throws unannotated and
+ * the re-render fallback resolves it.
+ *
+ * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+ */
+export function placeDenyPage(
+  chain: DenyPageEntry[],
+  status: number,
+  data: unknown,
+  selfKey: string | undefined
+): DenyPlacement | null {
+  const entry = matchDenyEntry(chain, status);
+  if (!entry) return null;
+
+  if (entry.ownerKey !== selfKey) {
+    // An MDX owner cannot be addressed. Its boundary holds a `fallbackElement`
+    // pre-rendered at tree-build time — before this status or its data
+    // existed — so hoisting to it would render a page that never learns what
+    // was denied (a category `4xx.mdx` gets no `status` prop at all). Leave it
+    // unaddressed so the re-render fallback serves it, which is the documented
+    // MDX path and resolves the position correctly on its own. See TIM-503.
+    if (entry.isMdx) return null;
+    return { kind: 'hoist', ownerKey: entry.ownerKey };
+  }
+
+  // Rendering in place is unaffected: `renderDenyEntry` builds the MDX element
+  // here, at catch time, with the real status.
+  return { kind: 'render', element: renderDenyEntry(entry, status, data) };
+}
+
+/**
+ * Build the element for a matched deny chain entry with the props contract
+ * the file's convention documents:
+ *
+ * - Status-code 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: DenyEntryShape,
+  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,
+  });
+}
+
+/**
+ * The whole of what an in-tree catch site does with a `DenySignal`, shared
+ * by all three of them (`PageDenyBoundary`, `TracedLayout`, `AccessGate`).
+ *
+ * Returns the deny page element when this catch site owns the matched file.
+ * Otherwise it throws — annotated with `ownerKey` when an ancestor owns the
+ * file, bare when nothing matched at all.
+ *
+ * `setDenyStatus` runs on the hoist path too, and must run *before* the
+ * throw: on the RSC payload path no boundary executes server-side, so the
+ * ALS status is the only thing standing between the response and a 200
+ * (`rsc-payload.ts` reads it after the stream settles).
+ *
+ * Either branch leaves part of the matched chain unmounted — hoisting sends
+ * the render to a boundary that discards everything below it, and a layout
+ * that denies returns the deny page instead of its own child outlet. What the
+ * response then says about the tree is decided from the deny status alone in
+ * `rsc-payload.ts`, not tracked here; see the note there for why.
+ */
+export function handleCaughtDeny(
+  chain: DenyPageEntry[] | undefined,
+  error: DenySignal,
+  selfKey: string | undefined
+): React.ReactElement {
+  const placement = chain ? placeDenyPage(chain, error.status, error.data, selfKey) : null;
+
+  if (placement?.kind === 'render') {
+    setDenyStatus(error.status);
+    return placement.element;
+  }
+  if (placement?.kind === 'hoist') {
+    setDenyStatus(error.status);
+    error.ownerKey = placement.ownerKey;
+  }
+  throw error;
+}
+
+// ─── 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,
+  segmentKey,
+  onSettled,
+}: {
+  /** 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[];
+  /**
+   * Segment key of the leaf. The page renders inside the leaf's layout, so
+   * a leaf-owned deny page is already at the right position; anything the
+   * chain matched further up is hoisted to its owner.
+   */
+  segmentKey: string;
+  /** Called when the page component finishes (success or deny). See TIM-1045. */
+  onSettled?: () => void;
+}): Promise<React.ReactElement> {
+  try {
+    const result = await withSpan('timber.page', { 'timber.route': route }, () => Page({}));
+    return result as React.ReactElement;
+  } catch (error: unknown) {
+    if (error instanceof DenySignal) {
+      return handleCaughtDeny(denyPages, error, segmentKey);
+    }
+    throw error;
+  } finally {
+    onSettled?.();
+  }
+}
+
+// ─── 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;
+    store.onDenyStatus?.();
+  }
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Record the first denied segment index in the request context ALS.
+ * Called from AccessGate when a DenySignal is caught during render.
+ * Only the first (shallowest) denial is recorded — deeper denials are
+ * unreachable because the gate short-circuits the subtree.
+ * See TIM-1363.
+ */
+export function setFirstDeniedSegmentIndex(index: number): void {
+  const store = requestContextAls.getStore();
+  if (store && store._firstDeniedSegmentIndex === undefined) {
+    store._firstDeniedSegmentIndex = index;
+  }
+}
+
+/**
+ * Read the first denied segment index from the request context ALS.
+ * Returns Infinity if no segment denied during render.
+ */
+export function getFirstDeniedSegmentIndex(): number {
+  return requestContextAls.getStore()?._firstDeniedSegmentIndex ?? Infinity;
+}