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

package/src/server/utils/element-type.ts

@@ -0,0 +1,88 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+
+// Marker symbols React stamps onto exotic component types. Mirrors the
+// internal `isValidElementType` check in `react.development.js` — React
+// doesn't export it, and we don't want to add `react-is` just for this one
+// validation. `isClientReference` (below) also uses REACT_CLIENT_REFERENCE_TYPE.
+const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
+const REACT_MEMO_TYPE = Symbol.for('react.memo');
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
+const REACT_CONTEXT_TYPE = Symbol.for('react.context');
+const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
+const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
+const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
+
+const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
+  REACT_FORWARD_REF_TYPE,
+  REACT_MEMO_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONTEXT_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_SUSPENSE_LIST_TYPE,
+  REACT_CLIENT_REFERENCE_TYPE,
+]);
+
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+/**
+ * Detect whether a component is a React client reference.
+ * Client references have $$typeof set to Symbol.for('react.client.reference')
+ * by registerClientReference() in the React Flight server runtime.
+ *
+ * Used to skip OTEL tracing wrappers that would call the component as a
+ * function. Client components must go through createElement only — they are
+ * serialized as references in the RSC Flight stream, not executed on the server.
+ */
+export function isClientReference(component: unknown): boolean {
+  return (
+    component != null &&
+    typeof component === 'function' &&
+    (component as unknown as Record<string, unknown>).$$typeof === REACT_CLIENT_REFERENCE_TYPE
+  );
+}
+
+export function isValidElementType(value: unknown): value is LoadedComponent {
+  if (typeof value === 'function') return true;
+  if (typeof value !== 'object' || value === null) return false;
+  const marker = (value as { $$typeof?: unknown }).$$typeof;
+  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}

package/src/server/utils/escape-html.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared HTML escaping utility.
+ *
+ * Used by both dev-only paths (error pages, 404 page) and production
+ * paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+ * it's not dev-only.
+ */
+
+/**
+ * Escape a string for safe embedding in HTML content or attributes.
+ *
+ * Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/server/version-skew.ts

@@ -0,0 +1,104 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+
+// ─── Constants ───────────────────────────────────────────────────
+
+/** Header sent by the client with every RSC/action request. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/** Response header that signals the client to do a full page reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The current build's deployment ID. Set at startup from the runtime config
+ * (`virtual:timber-config`'s `deploymentId`). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup by the RSC
+ * entry's `createRequestHandler()`. In dev mode this is never called
+ * (deployment ID checks are skipped).
+ */
+export function setDeploymentId(id: string): void {
+  currentDeploymentId = id;
+}
+
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export function getDeploymentId(): string | null {
+  return currentDeploymentId;
+}
+
+// ─── Skew Detection ──────────────────────────────────────────────
+
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+  /** Whether the client's deployment ID matches the server's. */
+  ok: boolean;
+  /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+  clientId: string | null;
+}
+
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export function checkVersionSkew(req: Request): SkewCheckResult {
+  // Dev mode — no deployment ID checks (HMR handles updates)
+  if (!currentDeploymentId) {
+    return { ok: true, clientId: null };
+  }
+
+  const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+
+  // No header — initial page load or non-RSC request. Always OK.
+  if (!clientId) {
+    return { ok: true, clientId: null };
+  }
+
+  // Compare deployment IDs
+  if (clientId === currentDeploymentId) {
+    return { ok: true, clientId };
+  }
+
+  return { ok: false, clientId };
+}
+
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export function applyReloadHeaders(headers: Headers): void {
+  headers.set(RELOAD_HEADER, '1');
+}

package/src/server/waituntil-bridge.ts

@@ -10,7 +10,7 @@
  * Design doc: design/11-platform.md §"waitUntil()"
  */
 
-import { waitUntilAls } from './als-registry.js';
+import { waitUntilAls } from './als-registry.ts';
 
 /**
  * Run a function with a per-request waitUntil handler installed.

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

@@ -0,0 +1,33 @@
+/**
+ * Per-request Workers Cache purge bridge — ALS bridge for Cloudflare adapter.
+ *
+ * The generated _worker.js wraps each request with `runWithWorkersCachePurge`,
+ * binding `ctx.cache` from the Cloudflare ExecutionContext. The
+ * `WorkersCachePurge` CDN purge handler reads from this ALS to call
+ * `ctx.cache.purge({ tags })` without needing an API token.
+ *
+ * Design doc: design/06-caching.md, design/25-production-deployments.md
+ */
+
+import { workersCachePurgeAls } from './als-registry.ts';
+import type { WorkersCachePurgeCtx } from './als-registry.ts';
+
+/**
+ * Run a function with Workers Cache purge context available.
+ *
+ * Called by the generated Cloudflare _worker.js entry to bind
+ * `ctx.cache` for the request duration.
+ */
+export function runWithWorkersCachePurge<T>(ctx: WorkersCachePurgeCtx, fn: () => T): T {
+  return workersCachePurgeAls.run(ctx, fn);
+}
+
+/**
+ * Get the current request's Workers Cache context, if available.
+ *
+ * Returns undefined outside a Cloudflare Workers request context
+ * or on platforms without Workers Cache support.
+ */
+export function getWorkersCachePurgeCtx(): WorkersCachePurgeCtx | undefined {
+  return workersCachePurgeAls.getStore();
+}

package/src/shared/als-slots.ts

@@ -0,0 +1,74 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+
+import type { CoercedParams } from './param-value.ts';
+
+interface AlsSlot<T> {
+  /** Register the server-side getter. Called once at module-init time. */
+  set(fn: () => T): void;
+  /** Read through to the registered getter, or throw the client-side message. */
+  get(): T;
+}
+
+function createAlsSlot<T>(message: string): AlsSlot<T> {
+  let fn: (() => T) | undefined;
+  return {
+    set(next) {
+      fn = next;
+    },
+    get() {
+      if (!fn) throw new Error(message);
+      return fn();
+    },
+  };
+}
+
+const searchParamsSlot = createAlsSlot<URLSearchParams>(
+  '[timber] searchParams.get() is only available on the server. ' +
+    'Use searchParams.useQueryStates() on the client.'
+);
+
+const segmentParamsSlot = createAlsSlot<CoercedParams>(
+  '[timber] segmentParams.get() is only available on the server. ' +
+    'Use segmentParams.useSegmentParams() on the client.'
+);
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSearchParamsFn = searchParamsSlot.set;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export const getSearchParamsFromAls = searchParamsSlot.get;
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSegmentParamsFn = segmentParamsSlot.set;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export const getSegmentParamsFromAls = segmentParamsSlot.get;

package/src/shared/base-path.ts

@@ -0,0 +1,80 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+
+/** `https://cdn.example.com/`, `//cdn.example.com/` — a base pointing off-origin. */
+function isAbsoluteUrlBase(base: string): boolean {
+  return base.startsWith('//') || /^[a-z][a-z0-9+.-]*:\/\//i.test(base);
+}
+
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export function isRelativeBase(base: string | undefined): boolean {
+  if (!base) return false;
+  return !base.startsWith('/') && !isAbsoluteUrlBase(base);
+}
+
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export function normalizeBasePath(base: string | undefined): string {
+  if (!base) return '/';
+  if (isAbsoluteUrlBase(base) || isRelativeBase(base)) return '/';
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function stripBasePath(base: string, pathname: string): string {
+  if (base === '/') return pathname;
+  const withoutTrailingSlash = base.slice(0, -1);
+  if (pathname === withoutTrailingSlash) return '/';
+  if (!pathname.startsWith(base)) return pathname;
+  return pathname.slice(withoutTrailingSlash.length);
+}
+
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function withBasePath(base: string, path: string): string {
+  if (base === '/') return path;
+  return path.startsWith('/') ? base.slice(0, -1) + path : `${base}${path}`;
+}

package/src/shared/csrf-reject.ts

@@ -0,0 +1,15 @@
+/**
+ * Marker header on CSRF rejections.
+ *
+ * A CSRF rejection is a 403, the same status as an access-control denial.
+ * The server stamps this header on every CSRF 403 so callers — the browser
+ * action runtime, a same-origin `fetch` in user code, a curl session — can
+ * tell the two apart without parsing the body. A cross-origin `fetch` cannot
+ * read it: the rejection returns before proxy.ts, so no CORS headers are set
+ * and the browser reports a network error instead. Shared so the server writer and the client
+ * reader cannot drift.
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection" (TIM-1459).
+ */
+export const CSRF_REJECT_HEADER = 'X-Timber-Reject';
+export const CSRF_REJECT_VALUE = 'csrf';

package/src/shared/error-digest.ts

@@ -0,0 +1,46 @@
+/**
+ * The digest an unhandled render error carries across Flight, and the
+ * correlation ID error pages read back out of it.
+ *
+ * Flight's `onError` (server/rsc-entry/rsc-stream.ts) returns this string for
+ * any error that is not a deny or redirect, and React sets it as `digest` on
+ * the Error it revives for that row, in SSR and on the client alike. The
+ * `errorId` is the one the server logged the error with, so an error page
+ * that shows it gives the reader something to quote that an operator can
+ * find. It is the `digest` prop every TSX error page receives.
+ *
+ * `message` is the real message only in dev; production sends a fixed string
+ * (design/13-security.md §"Errors don't leak").
+ */
+
+interface ErrorRowDigest {
+  type: 'error';
+  message: string;
+  errorId: string;
+}
+
+export function encodeErrorDigest(digest: Omit<ErrorRowDigest, 'type'>): string {
+  const row: ErrorRowDigest = { type: 'error', ...digest };
+  return JSON.stringify(row);
+}
+
+/**
+ * The correlation ID in an error's Flight digest, or `null` when the error
+ * carries none — a deny or redirect row, an error that never crossed Flight,
+ * or anything that is not an object.
+ */
+export function errorDigestId(error: unknown): string | null {
+  if (typeof error !== 'object' || error === null) return null;
+  const digest: unknown = Reflect.get(error, 'digest');
+  if (typeof digest !== 'string') return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(digest);
+  } catch {
+    // A digest someone else set (a library's own error): not ours to read.
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null;
+  const errorId: unknown = Reflect.get(parsed, 'errorId');
+  return Reflect.get(parsed, 'type') === 'error' && typeof errorId === 'string' ? errorId : null;
+}

package/src/shared/href-validation.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared href/URL validation for all navigation sinks.
+ *
+ * Used by <Link>, useRouter().push/replace, and redirectExternal().
+ * Single source of truth for dangerous-scheme detection — prevents
+ * control-character smuggling that bypasses naive regex checks.
+ *
+ * See design/13-security.md §"Link scheme injection" (test #9)
+ * and design/07-routing.md §"<Link> Scheme Validation".
+ */
+
+/**
+ * All C0 control characters (U+0000–U+001F) that browsers strip during
+ * URL preprocessing. Browsers and `new URL()` strip the full C0 range,
+ * not just tab/LF/CR — so we must match that behavior to prevent
+ * bypass vectors like `\x00javascript:alert(1)`.
+ */
+// eslint-disable-next-line no-control-regex -- intentional: must match all C0 controls to prevent bypass
+const CONTROL_CHARS_RE = /[\x00-\x1f]/g;
+
+const DANGEROUS_SCHEMES = new Set(['javascript:', 'data:', 'vbscript:']);
+
+/**
+ * Strip C0 control chars and leading whitespace, then extract the scheme.
+ * Returns the lowercase scheme (e.g. "javascript:") or null if no scheme.
+ */
+function extractScheme(href: string): string | null {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart();
+  const match = /^([a-z][a-z0-9+.-]*:)/i.exec(cleaned);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Validate an href for navigation sinks (<Link>, useRouter, etc.).
+ *
+ * Rejects dangerous schemes (javascript:, data:, vbscript:) even when
+ * control characters are embedded to bypass naive regex checks.
+ * Also rejects protocol-relative URLs (//evil.com).
+ *
+ * Throws on rejection. Safe hrefs pass through silently.
+ */
+export function validateNavigationHref(href: string): void {
+  // Normalize for validation: strip C0 controls, trim, then replace backslashes
+  // with forward slashes. Browsers normalize \ → / during URL resolution, so
+  // "/\evil.com" becomes "//evil.com" (protocol-relative open redirect).
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  // Protocol-relative URLs can redirect to attacker-controlled origins
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `Navigation received a protocol-relative or backslash-prefixed URL: "${href}". ` +
+        'Use an absolute URL with an explicit scheme or a relative path.'
+    );
+  }
+
+  const scheme = extractScheme(href);
+  if (scheme && DANGEROUS_SCHEMES.has(scheme)) {
+    throw new Error(
+      `Navigation received a dangerous href: "${href}". ` +
+        'javascript:, data:, and vbscript: URLs are not allowed.'
+    );
+  }
+}
+
+/**
+ * Check if an href is internal (same-origin navigation) or external.
+ *
+ * Strips control characters before checking so that "java\tscript:" is
+ * correctly identified as having a scheme (and thus not internal).
+ */
+export function isInternalHref(href: string): boolean {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (cleaned.startsWith('//')) return false;
+  if (cleaned.startsWith('/') || cleaned.startsWith('#') || cleaned.startsWith('?')) return true;
+
+  const scheme = extractScheme(href);
+  if (scheme) return false;
+
+  return true;
+}
+
+/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */
+const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+
+/**
+ * Assert that a redirect target is a relative path — rejects absolute and
+ * protocol-relative URLs. Used by both the server `redirect()` primitive and
+ * the client next/navigation shim so they enforce identical semantics.
+ *
+ * Normalizes for validation only: strips C0 controls, trims, then replaces
+ * backslashes with forward slashes. Browsers normalize \ → / during URL
+ * resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+ * redirect). See design/13-security.md tests #8, #8a–#8c.
+ */
+export function assertRelativeRedirectPath(path: string): void {
+  const cleaned = path.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (ABSOLUTE_URL_RE.test(cleaned)) {
+    throw new Error(
+      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
+        'Use redirectExternal(url, allowList) for external redirects.'
+    );
+  }
+
+  // eslint-disable-next-line no-control-regex -- intentional: must match C0 controls
+  if (/[\x00-\x1f]/.test(path)) {
+    throw new Error(
+      `redirect() received a path containing control characters (U+0000–U+001F). ` +
+        'Sanitize user input before passing it to redirect().'
+    );
+  }
+}
+
+const SAFE_REDIRECT_SCHEMES = new Set(['http:', 'https:']);
+
+/**
+ * Validate and canonicalize an external redirect URL.
+ *
+ * Requires http: or https: scheme and checks origin against an allow-list.
+ * Returns the parsed canonical URL string (from URL.href) to prevent
+ * raw user input from reaching the Location header.
+ *
+ * @throws On invalid URL, dangerous scheme, or origin not in allow-list.
+ */
+export function validateExternalRedirectUrl(url: string, allowList: string[]): string {
+  // Strip control chars before parsing to prevent scheme smuggling
+  const cleaned = url.replace(CONTROL_CHARS_RE, '').trimStart();
+
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `redirectExternal() received a protocol-relative URL: "${url}". ` +
+        'Use an absolute URL with http: or https: scheme.'
+    );
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(cleaned);
+  } catch {
+    throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
+  }
+
+  if (!SAFE_REDIRECT_SCHEMES.has(parsed.protocol)) {
+    throw new Error(
+      `redirectExternal() received a non-http(s) URL: "${url}". ` +
+        'Only http: and https: schemes are allowed for external redirects.'
+    );
+  }
+
+  if (!allowList.includes(parsed.origin)) {
+    throw new Error(
+      `redirectExternal() target "${parsed.origin}" is not in the allow-list. ` +
+        `Allowed: [${allowList.join(', ')}]`
+    );
+  }
+
+  return parsed.href;
+}