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

package/src/server/primitives.ts

@@ -1,11 +1,18 @@
-// Server-side primitives: deny, redirect, redirectExternal, RenderError, waitUntil, SsrStreamError
+// Server-side primitives: deny, redirect, redirectExternal, waitUntil
 //
 // These are the core runtime signals that components, middleware, and access gates
 // use to control request flow. See design/10-error-handling.md.
 
-import type { JsonSerializable } from './types.js';
-import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
-import { isDebug } from './debug.js';
+import type { JsonSerializable } from './types.ts';
+import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.ts';
+import { isDebug } from './debug.ts';
+import { getRequestSearchString } from './request-context.ts';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
+import { DENY_BRAND, REDIRECT_BRAND } from './signal-identity.ts';
+import {
+  assertRelativeRedirectPath,
+  validateExternalRedirectUrl,
+} from '../shared/href-validation.ts';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -91,7 +98,7 @@ function warnIfNotSerializable(data: unknown, callerName: string): void {
   if (issue) {
     console.warn(
       `[timber] ${callerName}: ${issue}. ` +
-        'Data passed to deny() or RenderError must be JSON-serializable because ' +
+        'Data passed to deny() must be JSON-serializable because ' +
         'the post-flush path uses JSON.stringify, not React Flight.'
     );
   }
@@ -102,11 +109,38 @@ function warnIfNotSerializable(data: unknown, callerName: string): void {
 /**
  * Render-phase signal thrown by `deny()`. Caught by the framework to produce
  * the correct HTTP status code (segment context) or graceful degradation (slot context).
+ *
+ * Detect with `isDenySignal()`, never `instanceof` — see "Signal branding" in signal-identity.ts.
  */
 export class DenySignal extends Error {
+  readonly [DENY_BRAND] = true;
   readonly status: number;
   readonly data: JsonSerializable | undefined;
 
+  /**
+   * Ordered list of segment keys that own matching deny pages for this
+   * signal, best match first. Present = addressed (a boundary should
+   * render it); absent = unplaced (the re-render fallback serves it).
+   *
+   * In-tree hoists stamp a single-element list (`[entry.ownerKey]`) —
+   * identical to the pre-TIM-1450 `ownerKey`. Late addressing (TIM-1450)
+   * stamps the full candidate list so the client can find the first
+   * *reachable* owner via its ancestry context, eliminating the
+   * owner-below-throw-site escape.
+   *
+   * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+   */
+  owners?: string[];
+
+  /**
+   * When true, the pipeline must respond with `rscErrorEnvelope` so the
+   * client hard-navigates instead of attempting to render a deny page
+   * from the RSC payload. Set by AccessGate when a skipped segment
+   * denies — rendering the deny page in-tree would appear inside the
+   * client's cached layout chrome (TIM-1074). See TIM-1363.
+   */
+  _hardNavigate?: boolean;
+
   constructor(status: number, data?: JsonSerializable) {
     super(`Access denied with status ${status}`);
     this.name = 'DenySignal';
@@ -143,58 +177,66 @@ export class DenySignal extends Error {
   }
 }
 
+/** Options for deny(). */
+export interface DenyOptions {
+  /** Human-readable message (logged server-side, not sent to client). */
+  message?: string;
+  /**
+   * JSON-serializable data forwarded as the `data` prop to status-code files
+   * and `denied.tsx`. Named `dangerouslyPassData` because this data crosses
+   * the RSC → client serialization boundary — do not pass sensitive server
+   * state (tokens, internal IDs, database rows).
+   */
+  dangerouslyPassData?: JsonSerializable;
+}
+
 /**
- * Universal denial primitive. Throws a `DenySignal` that the framework catches.
+ * Universal denial/error primitive. Throws a `DenySignal` that the framework catches.
  *
  * - In segment context (outside Suspense): produces HTTP status code
  * - In slot context: graceful degradation → denied.tsx → default.tsx → null
  * - Inside Suspense (hold window): promoted to pre-flush behavior
  * - Inside Suspense (after flush): error boundary + noindex meta
  *
- * @param status - Any 4xx HTTP status code. Defaults to 403.
- * @param data - Optional JSON-serializable data passed as `dangerouslyPassData` prop to status-code files.
- */
-export function deny(status: number = 403, data?: JsonSerializable): never {
-  if (status < 400 || status > 499) {
-    throw new Error(
-      `deny() requires a 4xx status code, got ${status}. ` +
-        'For 5xx errors, throw a RenderError instead.'
-    );
-  }
-  warnIfNotSerializable(data, 'deny()');
-  throw new DenySignal(status, data);
-}
-
-/**
- * Convenience alias for `deny(404)`.
+ * ```ts
+ * deny()                                                        // 403 (default)
+ * deny(404)                                                     // 404
+ * deny(503, { message: 'Maintenance' })                         // server-only log message
+ * deny(404, { dangerouslyPassData: { resourceId: params.id } }) // explicit client opt-in
+ * ```
+ *
+ * Accepts any 4xx or 5xx status code — it is also how a page renders a 5xx
+ * status file with data. An unplanned throw needs no primitive: it renders
+ * the error page with a 500.
  *
- * Provided for Next.js API compatibility — libraries and user code that
- * call `notFound()` from `next/navigation` get the same behavior as
- * `deny(404)` in timber.
+ * @param status - HTTP status code (4xx or 5xx). Default: 403.
+ * @param options - Optional message and/or data to pass to the client.
  */
-export function notFound(): never {
-  throw new DenySignal(404);
+export function deny(status?: number, options?: DenyOptions): never {
+  const resolvedStatus = status ?? 403;
+  const resolvedData = options?.dangerouslyPassData;
+
+  if (resolvedStatus < 400 || resolvedStatus > 599) {
+    throw new Error(`deny() requires a 4xx or 5xx status code, got ${resolvedStatus}.`);
+  }
+  warnIfNotSerializable(resolvedData, 'deny()');
+  throw new DenySignal(resolvedStatus, resolvedData);
 }
 
-/**
- * Next.js redirect type discriminator.
- *
- * Provided for API compatibility with libraries that import `RedirectType`
- * from `next/navigation`. In timber, `redirect()` always uses `replace`
- * semantics (no history entry for the redirect itself).
- */
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
+// Single source of truth shared with the client next/navigation shim —
+// see shared/redirect-type.ts.
+export { RedirectType } from '../shared/redirect-type.ts';
 
 // ─── RedirectSignal ─────────────────────────────────────────────────────────
 
 /**
  * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
  * Caught by the framework to produce a 3xx response or client-side navigation.
+ *
+ * Detect with `isRedirectSignal()`, never `instanceof` — see "Signal branding" in signal-identity.ts.
  */
 export class RedirectSignal extends Error {
+  readonly [REDIRECT_BRAND] = true;
   readonly location: string;
   readonly status: number;
 
@@ -206,46 +248,89 @@ export class RedirectSignal extends Error {
   }
 }
 
-/** Pattern matching absolute URLs: http(s):// or protocol-relative // */
-const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+// ─── Signal Detection ───────────────────────────────────────────────────────
+
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+  /** HTTP redirect status code (3xx). Defaults to 302 (or 308 when `permanent: true`). */
+  status?: number;
+  /**
+   * When true, defaults the status to 308 (Permanent Redirect, preserves HTTP method).
+   * If `status` is also provided, `status` takes precedence.
+   *
+   * @example
+   * redirect('/new-path', { permanent: true });       // 308
+   * redirect('/new-path', { permanent: true, status: 301 }); // 301
+   */
+  permanent?: boolean;
+  /**
+   * Preserve search params from the current request URL on the redirect target.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Target path's own query params always take precedence over preserved ones.
+   */
+  preserveSearchParams?: true | string[];
+}
 
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
+ *
+ * // With status code
+ * redirect('/login', 301);
+ *
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export function redirect(path: string, status: number = 302): never {
+export function redirect(path: string, statusOrOptions?: number | RedirectOptions): never {
+  let status: number;
+  let preserveSearchParams: true | string[] | undefined;
+
+  if (typeof statusOrOptions === 'number') {
+    status = statusOrOptions;
+  } else if (statusOrOptions) {
+    // Explicit status wins. Otherwise permanent: true → 308, default → 302.
+    status = statusOrOptions.status ?? (statusOrOptions.permanent ? 308 : 302);
+    preserveSearchParams = statusOrOptions.preserveSearchParams;
+  } else {
+    status = 302;
+  }
+
   if (status < 300 || status > 399) {
     throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
   }
-  if (ABSOLUTE_URL_RE.test(path)) {
-    throw new Error(
-      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
-        'Use redirectExternal(url, allowList) for external redirects.'
-    );
+  // Relative-only validation shared with the client next/navigation shim —
+  // strips C0 controls and normalizes backslashes before the scheme check.
+  assertRelativeRedirectPath(path);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
   }
-  throw new RedirectSignal(path, status);
-}
 
-/**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
- *
- * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
- * will replay POST requests to the new location. This matches Next.js behavior.
- *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
- */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+  throw new RedirectSignal(resolvedPath, status);
 }
 
 /**
- * Redirect to an external URL. The hostname must be in the provided allow-list.
+ * Redirect to an external URL. The origin must be in the provided allow-list.
+ *
+ * Only http: and https: schemes are permitted. The allow-list is matched
+ * against full origins (scheme + host + port), not bare hostnames.
  *
  * @param url - Absolute URL to redirect to.
- * @param allowList - Array of allowed hostnames (e.g. ['example.com', 'auth.example.com']).
+ * @param allowList - Array of allowed origins (e.g. ['https://example.com', 'https://auth.example.com']).
  * @param status - HTTP redirect status code (3xx). Defaults to 302.
  */
 export function redirectExternal(url: string, allowList: string[], status: number = 302): never {
@@ -253,82 +338,12 @@ export function redirectExternal(url: string, allowList: string[], status: numbe
     throw new Error(`redirectExternal() requires a 3xx status code, got ${status}.`);
   }
 
-  let hostname: string;
-  try {
-    hostname = new URL(url).hostname;
-  } catch {
-    throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
-  }
-
-  if (!allowList.includes(hostname)) {
-    throw new Error(
-      `redirectExternal() target "${hostname}" is not in the allow-list. ` +
-        `Allowed: [${allowList.join(', ')}]`
-    );
-  }
-
-  throw new RedirectSignal(url, status);
-}
-
-// ─── RenderError ────────────────────────────────────────────────────────────
-
-/**
- * Typed digest that crosses the RSC → client boundary.
- * The `code` identifies the error class; `data` carries JSON-serializable context.
- */
-export interface RenderErrorDigest<
-  TCode extends string = string,
-  TData extends JsonSerializable = JsonSerializable,
-> {
-  code: TCode;
-  data: TData;
-}
-
-/**
- * Typed throw for render-phase errors that carry structured context to error boundaries.
- *
- * The `digest` (code + data) is serialized into the RSC stream separately from the
- * Error instance — only the digest crosses the RSC → client boundary.
- *
- * @example
- * ```ts
- * throw new RenderError('PRODUCT_NOT_FOUND', {
- *   title: 'Product not found',
- *   resourceId: params.id,
- * })
- * ```
- */
-export class RenderError<
-  TCode extends string = string,
-  TData extends JsonSerializable = JsonSerializable,
-> extends Error {
-  readonly code: TCode;
-  readonly digest: RenderErrorDigest<TCode, TData>;
-  readonly status: number;
-
-  constructor(code: TCode, data: TData, options?: { status?: number }) {
-    super(`RenderError: ${code}`);
-    this.name = 'RenderError';
-    this.code = code;
-    this.digest = { code, data };
-
-    warnIfNotSerializable(data, 'RenderError');
-
-    const status = options?.status ?? 500;
-    if (status < 400 || status > 599) {
-      throw new Error(`RenderError status must be 4xx or 5xx, got ${status}.`);
-    }
-    this.status = status;
-  }
+  const canonicalUrl = validateExternalRedirectUrl(url, allowList);
+  throw new RedirectSignal(canonicalUrl, status);
 }
 
 // ─── waitUntil ──────────────────────────────────────────────────────────────
 
-/** Minimal interface for adapters that support background work. */
-export interface WaitUntilAdapter {
-  waitUntil?(promise: Promise<unknown>): void;
-}
-
 // Intentional per-app singleton — warn-once flag that persists for the
 // lifetime of the process/isolate. Not per-request; do not migrate to ALS.
 let _waitUntilWarned = false;
@@ -337,30 +352,20 @@ let _waitUntilWarned = false;
  * Register a promise to be kept alive after the response is sent.
  * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
  *
- * In production, the platform adapter installs a per-request waitUntil
- * function via ALS (see waituntil-bridge.ts). This function checks the
- * ALS bridge first, then falls back to the legacy adapter argument.
- *
- * If neither is available, a warning is logged once and the promise is
- * left to resolve (or reject) without being tracked.
+ * The platform adapter installs a per-request waitUntil function via ALS
+ * (see waituntil-bridge.ts). If no ALS handler is available, a warning
+ * is logged once and the promise is left to resolve (or reject) without
+ * being tracked.
  *
  * @param promise - The background work to keep alive.
- * @param adapter - Optional legacy adapter (prefer ALS bridge in production).
  */
-export function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter): void {
-  // Check ALS bridge first (installed by generated entry points)
+export function waitUntil(promise: Promise<unknown>): void {
   const alsFn = _getWaitUntil();
   if (alsFn) {
     alsFn(promise);
     return;
   }
 
-  // Fall back to legacy adapter argument
-  if (adapter && typeof adapter.waitUntil === 'function') {
-    adapter.waitUntil(promise);
-    return;
-  }
-
   if (!_waitUntilWarned) {
     _waitUntilWarned = true;
     console.warn(
@@ -377,26 +382,3 @@ export function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter)
 export function _resetWaitUntilWarning(): void {
   _waitUntilWarned = false;
 }
-
-// ─── SsrStreamError ─────────────────────────────────────────────────────────
-
-/**
- * Error thrown when SSR's renderToReadableStream fails due to an error
- * in the decoded RSC stream (e.g., uncontained slot errors).
- *
- * The RSC entry checks for this error type in its catch block to avoid
- * re-executing server components via renderDenyPage. Instead, it renders
- * a bare deny/error page without layout wrapping.
- *
- * Defined in primitives.ts (not ssr-entry.ts) because ssr-entry.ts imports
- * react-dom/server which cannot be loaded in the RSC environment.
- */
-export class SsrStreamError extends Error {
-  constructor(
-    message: string,
-    public readonly cause: unknown
-  ) {
-    super(message);
-    this.name = 'SsrStreamError';
-  }
-}

package/src/server/publish-params.ts

@@ -0,0 +1,42 @@
+/**
+ * Publishing the request's params onto the RSC payload.
+ *
+ * Every tree the server sends the browser goes through here: the ordinary
+ * route payload (`route-element-builder.ts`), both deny renderers
+ * (`deny-renderer.ts`) and the error renderer. One helper rather than a wrap
+ * at each site, because these previously *were* separate sites — a response
+ * header, an inline script, and a second copy of each on the deny path — and
+ * the deny path shipping empty params was the bug that came of it (TIM-1285).
+ *
+ * Reads the request store rather than taking params as an argument, so a
+ * caller cannot pass a different record than the one the request rendered
+ * with. See design/41-global-params.md §"Transport".
+ */
+
+import { toPlainRecord } from '../shared/param-value.ts';
+import type { RscPayloadRoot } from '../shared/payload-root.ts';
+import { getSegmentParamsForClient, getSlotParamsForClient } from './request-context.ts';
+
+/**
+ * Build the payload root: the tree, and the params it rendered with beside it.
+ *
+ * The params are a *sibling* of the tree, not a provider around it. A provider
+ * inside the payload is shadowed by the retained tree's own provider on a
+ * partial navigation, and its props are not readable at the instant the root
+ * row resolves — see `shared/payload-root.ts` for both, and TIM-1297. The
+ * client renders the one provider readers see, above the merge point.
+ *
+ * The records are flattened to plain objects on the way out. Every param
+ * record the framework builds is `Object.create(null)` (design/13-security.md
+ * #36b/#36c), and React Flight rejects a null prototype — "Classes or null
+ * prototypes are not supported". `ParamsProvider` restores the prototype on
+ * the other side, so what the app reads is unchanged; only the wire
+ * representation differs.
+ */
+export function withPublishedParams(element: React.ReactElement): RscPayloadRoot {
+  return {
+    tree: element,
+    params: toPlainRecord(getSegmentParamsForClient()),
+    slotParams: toPlainRecord(getSlotParamsForClient() ?? null),
+  };
+}

package/src/server/react-cache-bridge.ts

@@ -0,0 +1,124 @@
+/**
+ * React.cache bridge — one `React.cache` scope per request, shared by
+ * `proxy.ts`, `middleware.ts`, route handlers, and the render.
+ *
+ * `React.cache(fn)` stores its memo table in whatever Map
+ * `ReactSharedInternals.A.getCacheForType()` returns. `A` is Flight's
+ * `DefaultAsyncDispatcher`, whose `getCacheForType` returns the active Flight
+ * request's `cache` Map, or a throwaway `new Map()` outside a render. So
+ * without this bridge a `React.cache` call in middleware silently never
+ * dedupes with the same call in `access.ts` or a layout.
+ *
+ * The bridge wraps that one method on the existing dispatcher object:
+ *
+ * - When a timber scope is active (`reactCacheScopeAls`), it returns the
+ *   scope's Map — inside or outside a Flight render.
+ * - Otherwise it calls Flight's original method, so behaviour outside a
+ *   request (build-time capture, tests, isolated renders) is unchanged.
+ *
+ * Opening, resuming, and leaving scopes lives in `react-cache-scope.ts`,
+ * which does not import `react` so request-context and cookie code can use it.
+ *
+ * Constraints (TIM-1529, design/spike-TIM-1529-react-cache-bridge.md):
+ *
+ * - Never reassign `ReactSharedInternals.A`. Flight's `Request` constructor
+ *   throws "Currently React only supports one RSC renderer at a time" when
+ *   `A` is set to anything but its own dispatcher.
+ * - Never shim the `react` module's `cache` export and never patch the
+ *   vendored Flight bundle.
+ * - Flight installs `A` lazily, in the `Request` constructor, so it is
+ *   `null` until the first render. `installReactCacheBridge` takes a
+ *   `warmUp` callback that constructs one throwaway render to install it.
+ * - Idempotent: a program reload that re-evaluates this module but not
+ *   Flight finds the brand on the live method and does not wrap it twice.
+ *   A reload that re-evaluates Flight too hands back a fresh dispatcher,
+ *   which the re-evaluated RSC entry patches again. The wrapper closes over
+ *   nothing but the `globalThis`-anchored ALS, so an old wrapper that
+ *   survives a reload still reads the current scope.
+ */
+
+import * as React from 'react';
+import { reactCacheScopeAls } from './als-registry.ts';
+
+const INTERNALS_KEY = '__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';
+const BRIDGED = Symbol.for('timber:react-cache-bridge');
+
+type GetCacheForType = (resourceType: () => unknown) => unknown;
+
+interface AsyncDispatcher {
+  getCacheForType: GetCacheForType;
+}
+
+interface ServerInternals {
+  A: unknown;
+}
+
+function isServerInternals(value: unknown): value is ServerInternals {
+  return typeof value === 'object' && value !== null && 'A' in value;
+}
+
+function isAsyncDispatcher(value: unknown): value is AsyncDispatcher {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'getCacheForType' in value &&
+    typeof value.getCacheForType === 'function'
+  );
+}
+
+/** Result of `installReactCacheBridge`, for the boot log and the canary test. */
+export type ReactCacheBridgeStatus =
+  | { installed: true; alreadyBridged: boolean }
+  | { installed: false; reason: string };
+
+/**
+ * Patch Flight's dispatcher so `React.cache` resolves the active timber
+ * scope. Call once from the RSC entry, after the Flight server has loaded.
+ *
+ * `warmUp` must construct a Flight render (e.g. `renderToReadableStream(null)`
+ * and cancel it) — that is the only public way to make Flight install `A`.
+ *
+ * Never throws: if React's internals change shape the bridge is skipped,
+ * `React.cache` keeps its stock per-render behaviour, and the reason is
+ * returned. `tests/react-cache-bridge.test.ts` fails CI on that path.
+ */
+export function installReactCacheBridge(warmUp: () => void): ReactCacheBridgeStatus {
+  const internals: unknown = Reflect.get(React, INTERNALS_KEY);
+  if (!isServerInternals(internals)) {
+    return {
+      installed: false,
+      reason: `react does not export ${INTERNALS_KEY}`,
+    };
+  }
+  if (internals.A === null || internals.A === undefined) {
+    try {
+      warmUp();
+    } catch (error) {
+      return { installed: false, reason: `warm-up render threw: ${String(error)}` };
+    }
+  }
+  const dispatcher = internals.A;
+  if (!isAsyncDispatcher(dispatcher)) {
+    return {
+      installed: false,
+      reason: 'ReactSharedInternals.A has no getCacheForType()',
+    };
+  }
+
+  const original = dispatcher.getCacheForType;
+  if (BRIDGED in original) return { installed: true, alreadyBridged: true };
+
+  const bridged: GetCacheForType = function getCacheForType(resourceType) {
+    const scope = reactCacheScopeAls.getStore();
+    if (!scope) return original.call(dispatcher, resourceType);
+    let entry = scope.get(resourceType);
+    if (entry === undefined) {
+      entry = resourceType();
+      scope.set(resourceType, entry);
+    }
+    return entry;
+  };
+  Object.defineProperty(bridged, BRIDGED, { value: true });
+  dispatcher.getCacheForType = bridged;
+  return { installed: true, alreadyBridged: false };
+}