@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/server/deny-boundary.ts

@@ -8,10 +8,14 @@
  *    `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.
+ * 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
@@ -36,7 +40,9 @@ 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';
 
@@ -56,27 +62,106 @@ export interface DenyPageEntry {
   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) — matches any 4xx
+ * 2. Category catch-alls (4xx.tsx, 5xx.tsx) — matches any in category
  * 3. 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.
+ * 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
+  startIndex: number,
+  segmentKeys: string[]
 ): Promise<DenyPageEntry[]> {
   const chain: DenyPageEntry[] = [];
 
@@ -93,13 +178,15 @@ export async function buildDenyPageChain(
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
-          const mod = await loadModule(file).catch(() => null);
-          if (mod?.default) {
+          const component = await loadChainComponent(file);
+          if (component) {
             chain.push({
               status,
-              component: mod.default as (...args: unknown[]) => unknown,
+              component,
               kind: 'status',
               isMdx: isMdxFilePath(file.filePath),
+              segmentIndex: i,
+              ownerKey: segmentKeys[i],
             });
           }
         }
@@ -109,14 +196,16 @@ export async function buildDenyPageChain(
     // 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 component = await loadChainComponent(file);
+        if (component) {
           const categoryStatus = key === '4xx' ? 400 : 500;
           chain.push({
             status: categoryStatus,
-            component: mod.default as (...args: unknown[]) => unknown,
+            component,
             kind: 'status',
             isMdx: isMdxFilePath(file.filePath),
+            segmentIndex: i,
+            ownerKey: segmentKeys[i],
           });
         }
       }
@@ -129,13 +218,15 @@ export async function buildDenyPageChain(
   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) {
+      const component = await loadChainComponent(segment.error);
+      if (component) {
         chain.push({
           status: null,
-          component: mod.default as (...args: unknown[]) => unknown,
+          component,
           kind: 'error',
           isMdx: isMdxFilePath(segment.error.filePath),
+          segmentIndex: i,
+          ownerKey: segmentKeys[i],
         });
       }
     }
@@ -147,31 +238,106 @@ export async function buildDenyPageChain(
 // ─── 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.
+ * 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 renderMatchingDenyPage(
-  chain: DenyPageEntry[],
-  status: number,
-  data: unknown
-): React.ReactElement | null {
+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 renderDenyEntry(entry, status, data);
-    }
-    if (entry.status === 400 && status >= 400 && status <= 499) {
-      return renderDenyEntry(entry, status, data);
+    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);
     }
-    if (entry.status === 500 && status >= 500 && status <= 599) {
-      return renderDenyEntry(entry, status, data);
+  }
+  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;
     }
-    if (entry.status === null) {
-      return renderDenyEntry(entry, status, data);
+    // 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:
@@ -184,7 +350,7 @@ export function renderMatchingDenyPage(
  * - error.mdx: plain { status } — server component, static content.
  */
 export function renderDenyEntry(
-  entry: DenyPageEntry,
+  entry: DenyEntryShape,
   status: number,
   data: unknown
 ): React.ReactElement {
@@ -216,6 +382,43 @@ export function renderDenyEntry(
   });
 }
 
+/**
+ * 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 ────────────────────────────────────────────────────────
 
 /**
@@ -236,6 +439,7 @@ export async function PageDenyBoundary({
   Page,
   route,
   denyPages,
+  segmentKey,
   onSettled,
 }: {
   /** The page server component function. */
@@ -244,6 +448,12 @@ export async function PageDenyBoundary({
   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> {
@@ -252,11 +462,7 @@ export async function PageDenyBoundary({
     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;
-      }
+      return handleCaughtDeny(denyPages, error, segmentKey);
     }
     throw error;
   } finally {
@@ -286,3 +492,25 @@ export function setDenyStatus(status: number): void {
 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;
+}