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

package/src/server/route-module-loader.ts

@@ -0,0 +1,161 @@
+/**
+ * Route module loading — loads layout, page, and access.ts modules from
+ * a matched route's segment chain in a single pass.
+ *
+ * Extracted from `route-element-builder.ts` to keep that file focused on
+ * element-tree construction.
+ *
+ * See design/02-rendering-pipeline.md, design/07-routing.md.
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { Metadata } from './types.ts';
+import { loadModule } from './safe-load.ts';
+import { NoPageComponentError, type LayoutComponentEntry } from './route-element-builder.ts';
+
+/** Metadata export from a layout or page module, with its segment context. */
+export interface MetadataSource {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  segmentIndex: number;
+}
+
+/** Access function loaded from a segment's access.ts. */
+export type AccessFn = (() => unknown) | undefined;
+
+/** Result of the module-loading phase. */
+export interface LoadedRouteModules {
+  metadataSources: MetadataSource[];
+  layoutComponents: LayoutComponentEntry[];
+  PageComponent: (...args: unknown[]) => unknown;
+  deferSuspenseFor: number;
+  accessFns: Array<AccessFn>;
+}
+
+/**
+ * Reject the legacy `generateMetadata` export with a helpful migration message.
+ * Throws if the module exports `generateMetadata` instead of `metadata`.
+ */
+function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: string): void {
+  if ('generateMetadata' in mod) {
+    throw new Error(
+      `${filePath}: "generateMetadata" is not a valid export. ` +
+        `Export an async function named "metadata" instead.\n\n` +
+        `  // Before\n` +
+        `  export async function generateMetadata({ params }) { ... }\n\n` +
+        `  // After\n` +
+        `  export async function metadata() { ... }`
+    );
+  }
+}
+
+/**
+ * Extract `deferSuspenseFor` from a module and return the maximum
+ * of the current value and the module's value.
+ */
+function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
+  if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
+    return mod.deferSuspenseFor;
+  }
+  return current;
+}
+
+/**
+ * Collect metadata and deferSuspenseFor from a loaded module.
+ * Shared between layout and page loading paths.
+ */
+function collectModuleExports(
+  mod: Record<string, unknown>,
+  segment: ManifestSegmentNode,
+  segmentIndex: number,
+  isPage: boolean,
+  metadataSources: MetadataSource[],
+  currentDefer: number
+): number {
+  const filePath = (isPage ? segment.page?.filePath : segment.layout?.filePath) ?? segment.urlPath;
+  rejectLegacyGenerateMetadata(mod, filePath);
+  if (mod.metadata) {
+    metadataSources.push({
+      metadataExport: mod.metadata as Metadata | (() => Promise<Metadata>),
+      segmentName: segment.segmentName ?? segment.urlPath,
+      isPage,
+      segmentIndex,
+    });
+  }
+  return extractDeferSuspenseFor(mod, currentDefer);
+}
+
+/**
+ * Load all route modules (layouts, page, access functions) in a single pass.
+ *
+ * Access functions are loaded eagerly here so the wrapping loop does not need
+ * to await `loadModule(segment.access)` at each iteration.
+ */
+export async function loadRouteModules(
+  segments: ManifestSegmentNode[],
+  requestUrl: string
+): Promise<LoadedRouteModules> {
+  const metadataSources: MetadataSource[] = [];
+  const layoutComponents: LayoutComponentEntry[] = [];
+  const accessFns: Array<AccessFn> = [];
+  let PageComponent: ((...args: unknown[]) => unknown) | null = null;
+  let deferSuspenseFor = 0;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const isLeaf = i === segments.length - 1;
+
+    if (segment.layout) {
+      const mod = await loadModule(segment.layout);
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment,
+        });
+      }
+      deferSuspenseFor = collectModuleExports(
+        mod,
+        segment,
+        i,
+        false,
+        metadataSources,
+        deferSuspenseFor
+      );
+    }
+
+    if (isLeaf && segment.page) {
+      const mod = await loadModule(segment.page);
+      if (mod.default) {
+        PageComponent = mod.default as (...args: unknown[]) => unknown;
+      }
+      deferSuspenseFor = collectModuleExports(
+        mod,
+        segment,
+        i,
+        true,
+        metadataSources,
+        deferSuspenseFor
+      );
+    }
+
+    if (segment.access) {
+      const accessMod = await loadModule(segment.access);
+      accessFns[i] = accessMod.default as AccessFn;
+    }
+  }
+
+  if (!PageComponent) {
+    const segmentInfo = segments
+      .map(
+        (s, i) =>
+          `  [${i}] ${s.segmentName} (page: ${s.page ? 'yes' : 'no'}, layout: ${s.layout ? 'yes' : 'no'}, children: ${s.children?.length ?? 0})${i === segments.length - 1 ? ' ← leaf' : ''}`
+      )
+      .join('\n');
+    throw new NoPageComponentError(
+      `No page component found for route: ${new URL(requestUrl).pathname}\nMatched segments:\n${segmentInfo}`
+    );
+  }
+
+  return { metadataSources, layoutComponents, PageComponent, deferSuspenseFor, accessFns };
+}

package/src/server/rsc-cache-key-guard.ts

@@ -0,0 +1,122 @@
+/**
+ * Origin-side binding of the `_rsc` cache key to the request that produced
+ * the response (TIM-1268).
+ *
+ * The key is deterministic, and deliberately so — that is what makes RSC
+ * payloads cacheable. But deterministic also means *predictable*: anyone can
+ * compute the key another client will request. Without this guard, a caller
+ * could request `/about?_rsc=<victim's key>` while sending its own
+ * `X-Timber-State-Tree`, and a shared cache that keys by URL — the exact
+ * environment this feature targets — would store that variant under the
+ * victim's key. Every subsequent legitimate navigation would then be served
+ * a payload rendered for someone else's segment tree or deployment.
+ *
+ * The guard is a *storability* rule, not a rejection: if the claimed key
+ * does not match the key derived from the received headers, the response
+ * loses its shared-cache directives. Mismatched requests are still served
+ * normally, they just cannot be stored for anyone else.
+ *
+ * Why not Next.js's 307 self-correction: a redirect is cacheable in its own
+ * right, costs a round trip on every legitimate miss, and would make the
+ * server's behaviour depend on a parameter it otherwise never reads. This
+ * rule closes the same hole by making the poisoned entry unstorable at the
+ * source, in the response the developer already has to opt into sharing.
+ *
+ * See design/19-client-navigation.md §"The `_rsc` cache key".
+ */
+
+import { rscCacheKey, isRscCacheKeyShape, RSC_KEY_PARAM } from '../shared/rsc-cache-key.ts';
+import { isRscContentType } from '../shared/rsc-media-type.ts';
+import { preventResponseCaching } from './response-cache-policy.ts';
+
+/**
+ * Whether the request's `_rsc` parameter matches the key derived from its
+ * own headers.
+ *
+ * Requests without the parameter are not claiming a key at all, so they are
+ * left alone — the bare document URL is the developer's declared territory
+ * (see design/32-response-caching.md, TIM-1264). Neither is a parameter
+ * whose value could not be one of our digests: `_rsc` is not reserved, and
+ * an application that already uses it for its own search state
+ * (`/search?_rsc=foo`) must not have its cache policy silently revoked by a
+ * guard that mistook that for a forgery.
+ */
+export async function hasValidRscCacheKey(req: Request): Promise<boolean> {
+  // Fast path: this runs on every request, and the overwhelming majority
+  // (document requests) have no query string at all. Keyed on `?` and not
+  // on the literal `_rsc=`, because a substring test is not a parse: a
+  // request for `?%5Frsc=<key>` carries no literal `_rsc=`, yet
+  // `URLSearchParams` decodes it to one — and a cache that canonicalizes
+  // percent-encoded unreserved characters in its key while forwarding the
+  // original URL would store the response under the decoded, claimed key.
+  // The only sound fast path is one that cannot answer "no key" wrongly.
+  if (!req.url.includes('?')) return true;
+  let values: string[];
+  try {
+    values = new URL(req.url).searchParams.getAll(RSC_KEY_PARAM);
+  } catch {
+    // Unparseable URL — nothing to validate, and nothing safe to assume.
+    return false;
+  }
+  // Every value, not the first. An application that owns `_rsc` for its own
+  // search state makes the client emit `?_rsc=foo&_rsc=<key>` — reading only
+  // the first would see `foo`, exempt it as application data, and never
+  // check the real key sitting beside it.
+  const claims = values.filter(isRscCacheKeyShape);
+  if (claims.length === 0) return true;
+  const expected = await rscCacheKey((name) => req.headers.get(name));
+  // No digest available means the claim is unverifiable, which is not the
+  // same as verified. Every server runtime timber targets has
+  // `crypto.subtle`, so this is a guard against a future one that does not.
+  if (expected === null) return false;
+  // All of them, because at most one can be legitimate and a cache keys on
+  // the whole query string — a second, mismatched key would ride along
+  // inside an address that otherwise looks validated.
+  return claims.every((claim) => claim === expected);
+}
+
+/**
+ * Ensure a Flight payload can never be interpreted as a document.
+ *
+ * Applied here, at the pipeline's single exit, rather than where each
+ * payload response is built. Six places build one — the success path, three
+ * in `deny-renderer.ts`, the action paths — and hardening them one at a time
+ * is how you end up hardening five of six. The response is Flight if it says
+ * it is; that is the only test that covers every producer, including ones
+ * added later.
+ *
+ * Matters because the payload URL is observable and, on a shared-cache hit,
+ * the origin is never consulted — so a top-level navigation can be handed
+ * these bytes with no request-time check available. See design/13-security.md
+ * #36c.
+ */
+export function hardenRscPayloadResponse(response: Response): void {
+  if (!isRscContentType(response.headers.get('content-type'))) return;
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+}
+
+/**
+ * Make a response unstorable by any shared cache when its request claimed an
+ * `_rsc` key that does not match its own headers.
+ *
+ * The end state is unconditional and therefore statable: **a mismatched
+ * response is never stored by any cache.** Every targeted cache-control
+ * field is removed and `Cache-Control` is replaced outright, rather than
+ * downgrading only when a shared directive is spotted. Conditional variants
+ * of this were tried and were wrong twice over — they missed the CDN-
+ * specific headers, and leaving `Cache-Control` alone when it looked
+ * harmless lets a CDN apply heuristic caching to a response that has none.
+ *
+ * The cost is that a mismatched request loses developer-chosen *browser*
+ * caching too. That is a request no timber client ever makes.
+ *
+ * Purge tags (`Surrogate-Key`, `Cache-Tag`) are deliberately left alone:
+ * they address stored entries, and this response is not stored.
+ *
+ * Mutates `response.headers` in place; the pipeline guarantees mutable
+ * headers at this point (see TIM-866).
+ */
+export async function enforceRscCacheKey(req: Request, response: Response): Promise<void> {
+  if (await hasValidRscCacheKey(req)) return;
+  preventResponseCaching(response.headers);
+}

package/src/server/rsc-entry/action-dispatcher.ts

@@ -0,0 +1,142 @@
+/**
+ * Server action dispatcher — the `dispatchAction` callback for
+ * `PipelineConfig`.
+ *
+ * Extracted from rsc-entry/index.ts so the wiring can be unit-tested in
+ * isolation from Vite's virtual modules.
+ *
+ * `createPipeline` calls it after proxy.ts runs (TIM-1213), so proxy.ts
+ * sees action POSTs — "proxy.ts runs on every request, no exclusions." It
+ * encapsulates action detection, the route-type check, action handler
+ * dispatch, and the no-JS validation rerender path.
+ *
+ * The CSRF gate is not here: it runs in `createPipeline` before proxy.ts
+ * (`csrfGate` in pipeline-helpers.ts). The action handler repeats the
+ * check as defense-in-depth, with no per-route exemption.
+ *
+ * Per-segment `middleware.ts` does NOT run on action POSTs (TIM-1134).
+ * Actions are dispatched by action ID, not by route segment. Per-action
+ * auth/validation belongs in `createActionClient({ middleware })`.
+ */
+
+import type { FormRerender } from '../action-handler.ts';
+import { handleActionRequest, isActionRequest } from '../action-handler.ts';
+import type { BodyLimitsConfig } from '../body-limits.ts';
+import type { CsrfConfig } from '../csrf.ts';
+import { runWithFormFlash } from '../form-flash.ts';
+import type { RouteMatcher } from '../pipeline.ts';
+import { isApiRouteChain } from '../route-matcher.ts';
+import type { SensitiveFieldsOption } from '../sensitive-fields.ts';
+import type { RevalidateRenderer } from '../actions.ts';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a `RevalidateRenderer` for a specific request.
+ *
+ * The renderer needs to forward cookies/headers from the originating
+ * request when fetching the revalidated route. We pass the request in
+ * via a builder so the wrapper doesn't need to know about route matching,
+ * segment param coercion, or element building — those concerns stay in
+ * `rsc-entry/index.ts`.
+ */
+export type RevalidateRendererFactory = (req: Request) => RevalidateRenderer;
+
+/** Dependencies for the action dispatcher (used inside the pipeline). */
+export interface ActionDispatcherDeps {
+  /** CSRF configuration — defense-in-depth check inside the action handler. */
+  csrfConfig: CsrfConfig;
+  /** Body size limits forwarded to `handleActionRequest`. */
+  bodyLimits?: BodyLimitsConfig['limits'];
+  /** Sensitive-field deny-list forwarded to `handleActionRequest`. */
+  sensitiveFields?: SensitiveFieldsOption;
+  /** Per-request factory that builds a `RevalidateRenderer`. */
+  buildRevalidateRenderer: RevalidateRendererFactory;
+  /**
+   * Route matcher — used for the route-type check that skips action
+   * detection on `route.ts` API handlers (TIM-870). Required: without it,
+   * every form POST to a route.ts would enter the action handler, whose
+   * CSRF check has no per-route exemption, and a `csrf = false` route
+   * would 403 its cross-site callbacks.
+   */
+  matchRoute: RouteMatcher;
+}
+
+// ─── Action Dispatcher ────────────────────────────────────────────────────
+
+/**
+ * Build the `dispatchAction` callback for `PipelineConfig`.
+ *
+ * Called after proxy.ts runs (inside the pipeline) for every request.
+ * Checks if the request is a server action POST, handles the route-type
+ * check (TIM-870), dispatches to the action handler, and handles the
+ * no-JS validation rerender path.
+ *
+ * Returns `Response` if the request was handled as an action, `null` to
+ * fall through to normal routing.
+ */
+export function buildActionDispatcher(
+  deps: ActionDispatcherDeps
+): (
+  req: Request,
+  canonicalPath: string,
+  reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>
+) => Promise<Response | null> {
+  return async (
+    req: Request,
+    canonicalPath: string,
+    reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>
+  ): Promise<Response | null> => {
+    if (!isActionRequest(req)) return null;
+
+    // Route-type check (TIM-870): match the route BEFORE any body parsing.
+    // If the matched route is an API route (route.ts), skip action detection
+    // entirely — server actions only live on page routes; POSTs to route.ts
+    // are API requests whose body must reach the handler untouched.
+    //
+    // Use `canonicalPath` from the pipeline — NOT `new URL(req.url).pathname`,
+    // which re-encodes the path. The matcher expects the decoded canonical form.
+    const match = deps.matchRoute(canonicalPath);
+    if (match && isApiRouteChain(match.segments)) {
+      return null;
+    }
+
+    // Action handler dispatch
+    const actionResponse = await handleActionRequest(req, {
+      csrf: deps.csrfConfig,
+      bodyLimits: { limits: deps.bodyLimits },
+      sensitiveFields: deps.sensitiveFields,
+      revalidateRenderer: deps.buildRevalidateRenderer(req),
+    });
+
+    if (actionResponse) {
+      // No-JS validation rerender
+      if ('rerender' in actionResponse) {
+        const formRerender = actionResponse as FormRerender;
+        // Build a synthetic GET request for the rerender pipeline:
+        //   - Same URL (so route matching lands on the same page)
+        //   - Cookie header DROPPED entirely. The post-action RYW state
+        //     is handed to `reenter` as a parsed `Map<string, string>`,
+        //     which becomes the rerender request context's cookies.
+        //   - Method GET because the rerender is conceptually a page render.
+        const rerenderHeaders = new Headers(req.headers);
+        rerenderHeaders.delete('cookie');
+        const rerenderReq = new Request(req.url, {
+          method: 'GET',
+          headers: rerenderHeaders,
+        });
+        const response = await runWithFormFlash(formRerender.rerender, () =>
+          reenter(rerenderReq, formRerender.cookies)
+        );
+        // Apply Set-Cookie headers snapshotted from the action's ALS scope.
+        for (const value of formRerender.setCookieHeaders) {
+          response.headers.append('Set-Cookie', value);
+        }
+        return response;
+      }
+      return actionResponse;
+    }
+
+    return null;
+  };
+}

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -0,0 +1,130 @@
+/**
+ * Middleware runner for revalidation — runs a route's `middleware.ts`
+ * chain inside its own `runWithRequestContext` scope and returns a
+ * `MiddlewareOutcome` value the caller can translate.
+ *
+ * Used by the revalidation renderer (TIM-996) to run the TARGET route's
+ * middleware before building the revalidated element tree, ensuring that
+ * `revalidatePath('/admin')` from a public action honors admin's auth.
+ *
+ * NOT used for action dispatch itself — per-segment middleware does not
+ * run on action POSTs (TIM-1134). Actions are dispatched by action ID,
+ * not route segment, so `proxy.ts` and `createActionClient({ middleware })`
+ * are the correct auth mechanisms.
+ *
+ * The function is intentionally a free function (not a closure over deps)
+ * so it can be unit-tested in isolation. Failure modes are encoded as
+ * outcome variants rather than thrown so the caller never has to wrap
+ * this in try/catch.
+ */
+
+import {
+  applyRequestHeaderOverlay,
+  runWithRequestContext,
+  setMutableCookieContext,
+  setSegmentParams,
+} from '../request-context.ts';
+import { runMiddlewareChain } from '../middleware-runner.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
+import type { RouteMatch } from '../pipeline.ts';
+import type { MiddlewareContext } from '../types.ts';
+import { requestCspNonce } from '../csp-nonce.ts';
+import type { ReactCacheScope } from '../react-cache-scope.ts';
+
+/**
+ * Outcome of running a route's middleware chain, surfaced from the inner
+ * `runWithRequestContext` scope as a value. Its one consumer is the
+ * revalidation renderer, which turns every variant but `continue` into
+ * a thrown signal or a dropped revalidation.
+ *
+ * Only `continue` carries state out of the scope: the request-header
+ * overlay, which the renderer applies to the action's scope so the
+ * revalidated tree sees middleware-injected headers. Cookies the chain sets
+ * stay in the inner scope and are discarded with it; see the renderer's
+ * docstring for why.
+ */
+export type MiddlewareOutcome =
+  | { kind: 'continue'; overlay: Headers }
+  | { kind: 'short-circuit'; response: Response }
+  | { kind: 'redirect'; signal: RedirectSignal }
+  | { kind: 'deny'; signal: DenySignal }
+  | { kind: 'error'; error: unknown };
+
+/** The inner request scope's inputs, besides the request itself. */
+export interface MiddlewareScope {
+  /** The `React.cache` scope the revalidated tree will render in. */
+  reactCacheScope: ReactCacheScope;
+  /** The action's post-mutation cookies, as the inner scope's cookies. */
+  cookies?: Map<string, string>;
+}
+
+/**
+ * Run the matched route's middleware chain inside a fresh request-context
+ * scope, captured as a `MiddlewareOutcome` value.
+ *
+ * `match` must already carry coerced segment params: coercion runs before
+ * middleware, in the caller, as it does in the page pipeline.
+ */
+export async function runMiddlewareForAction(
+  req: Request,
+  match: RouteMatch,
+  { reactCacheScope, cookies }: MiddlewareScope
+): Promise<MiddlewareOutcome> {
+  return runWithRequestContext(
+    req,
+    async (): Promise<MiddlewareOutcome> => {
+      setSegmentParams(match.segmentParams);
+
+      // ─── Build the middleware context ───────────────────────────────
+      const responseHeaders = new Headers();
+      const requestHeaderOverlay = new Headers();
+      const ctx: MiddlewareContext = {
+        req,
+        requestHeaders: requestHeaderOverlay,
+        headers: responseHeaders,
+        segmentParams: match.segmentParams,
+        // 103 Early Hints are a page-render concern — server actions are
+        // RPC and never produce HTML, so there is nothing to hint about.
+        // Provide a no-op so user middleware can call `ctx.earlyHints()`
+        // unconditionally without branching on request kind.
+        earlyHints: () => {},
+        // Same reasoning: an action response carries no inline scripts, so a
+        // nonce has nothing to stamp. Still a real value so middleware that
+        // builds its CSP header unconditionally keeps working.
+        get nonce() {
+          return requestCspNonce();
+        },
+      };
+
+      // ─── Run the chain ──────────────────────────────────────────────
+      setMutableCookieContext(true);
+      try {
+        let middlewareResponse: Response | undefined;
+        try {
+          middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+        } catch (err) {
+          if (isRedirectSignal(err)) return { kind: 'redirect', signal: err };
+          if (isDenySignal(err)) return { kind: 'deny', signal: err };
+          return { kind: 'error', error: err };
+        }
+
+        if (middlewareResponse) {
+          return { kind: 'short-circuit', response: middlewareResponse };
+        }
+
+        // Middleware passed — apply the request-header overlay to the
+        // current scope so any code that might still read it within
+        // this scope sees the merged view. The overlay is also captured
+        // in the outcome so the caller can re-apply it inside the
+        // action's request-context scope (which is a separate ALS run).
+        applyRequestHeaderOverlay(requestHeaderOverlay);
+
+        return { kind: 'continue', overlay: requestHeaderOverlay };
+      } finally {
+        setMutableCookieContext(false);
+      }
+    },
+    { reactCacheScope, cookies }
+  );
+}