@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/server/tree-match.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared URL-matching tree walker for segment trees.
+ *
+ * Both the main route matcher (`route-matcher.ts`) and slot resolver
+ * (`slot-resolver.ts`) need to walk a SegmentNode tree, matching URL
+ * parts against children with the same priority semantics:
+ *
+ *   static > dynamic > catch-all > optional-catch-all
+ *
+ * Before this module, each had its own walker with subtle divergences
+ * (different group handling, missing backtracking, incomplete
+ * optional-catch-all support). This shared walker is the single
+ * source of truth for URL-to-segment matching.
+ *
+ * See design/07-routing.md §"Request Lifecycle" and TIM-940.
+ */
+
+import type { SegmentNode } from '../routing/types.js';
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/** Result of matching URL parts against a segment tree. */
+export interface TreeMatchResult<TFile> {
+  /** Matched segment chain from root to leaf, inclusive. */
+  chain: SegmentNode<TFile>[];
+  /** Collected params, keyed by param name. Catch-all params are string[]. */
+  params: Record<string, string | string[]>;
+}
+
+export interface TreeMatchOptions {
+  /**
+   * When true (default), only match if the leaf node has a page or route
+   * handler. Set to false for metadata route matching, where we just need
+   * to find the owning segment regardless of whether it has a page.
+   */
+  requireTerminal?: boolean;
+}
+
+/**
+ * Match URL path parts against a segment tree.
+ *
+ * Walks the tree depth-first with backtracking, applying priority
+ * ordering globally across group boundaries. Returns the matched
+ * segment chain and collected params, or null if no route matches.
+ *
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
+ *
+ * @param root  The root segment node to start matching from.
+ * @param parts URL path parts (e.g. ['blog', 'hello-world']).
+ *              Empty array matches the root itself (if terminal).
+ */
+export function matchUrlParts<TFile>(
+  root: SegmentNode<TFile>,
+  parts: string[],
+  options?: TreeMatchOptions
+): TreeMatchResult<TFile> | null {
+  const chain: SegmentNode<TFile>[] = [];
+  const params: Record<string, string | string[]> = {};
+  const requireTerminal = options?.requireTerminal ?? true;
+
+  if (matchNode(root, parts, 0, chain, params, requireTerminal)) {
+    return { chain, params };
+  }
+  return null;
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────
+
+/**
+ * A child node flattened through group segments, along with the
+ * chain of group nodes that must appear in the segment chain
+ * before the child to preserve the tree path.
+ */
+interface EffectiveChild<TFile> {
+  child: SegmentNode<TFile>;
+  groupChain: SegmentNode<TFile>[];
+}
+
+/**
+ * Flatten children through group segments.
+ *
+ * Groups are transparent for URL matching — their non-group descendants
+ * are returned with the chain of group nodes leading to them. This lets
+ * the caller apply priority ordering (static > dynamic > catch-all >
+ * optional-catch-all) across all groups uniformly instead of per-group.
+ */
+function collectEffectiveChildren<TFile>(
+  node: SegmentNode<TFile>,
+  groupChain: SegmentNode<TFile>[] = []
+): EffectiveChild<TFile>[] {
+  const result: EffectiveChild<TFile>[] = [];
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      const nested = collectEffectiveChildren(child, [...groupChain, child]);
+      result.push(...nested);
+    } else {
+      result.push({ child, groupChain });
+    }
+  }
+  return result;
+}
+
+/** A node is terminal if it can serve a response (has a page or route handler). */
+function isTerminal<TFile>(node: SegmentNode<TFile>): boolean {
+  return !!(node.page || node.route);
+}
+
+/**
+ * Recursive depth-first matcher with backtracking.
+ *
+ * Mutates `chain` and `params` in place for performance; backtracks
+ * (restores previous state) when a candidate doesn't lead to a match.
+ */
+function matchNode<TFile>(
+  node: SegmentNode<TFile>,
+  parts: string[],
+  index: number,
+  chain: SegmentNode<TFile>[],
+  params: Record<string, string | string[]>,
+  requireTerminal: boolean
+): boolean {
+  chain.push(node);
+
+  // All parts consumed — check if this node is terminal (or any node if !requireTerminal)
+  if (index >= parts.length) {
+    if (!requireTerminal || isTerminal(node)) return true;
+
+    // Groups don't consume URL segments, so a group child's page can
+    // match at the same URL depth. Recurse into groups transparently.
+    for (const child of node.children) {
+      if (child.segmentType === 'group') {
+        if (matchNode(child, parts, index, chain, params, requireTerminal)) {
+          return true;
+        }
+      }
+    }
+
+    // Optional catch-all with zero segments (direct and through groups).
+    // The param is NOT set — matching Next.js semantics for [[...slug]]
+    // with no path segments.
+    const effective = collectEffectiveChildren(node);
+    for (const { child, groupChain } of effective) {
+      if (child.segmentType === 'optional-catch-all' && (!requireTerminal || isTerminal(child))) {
+        chain.push(...groupChain, child);
+        return true;
+      }
+    }
+
+    chain.pop();
+    return false;
+  }
+
+  const part = parts[index];
+
+  // Flatten children through groups so priority ordering applies globally.
+  const effective = collectEffectiveChildren(node);
+
+  // 1. Static segments (exact name match)
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'static' && child.segmentName === part) {
+      chain.push(...groupChain);
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      chain.length -= groupChain.length;
+    }
+  }
+
+  // 2. Dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'dynamic' && child.paramName) {
+      chain.push(...groupChain);
+      const prev = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName] = prev;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 3. Catch-all segments ([...param]) — must be terminal unless the
+  // caller passed requireTerminal:false (metadata route matching needs to
+  // find the owning segment even when it has no page).
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  // 4. Optional catch-all segments ([[...param]]) — same terminal rule
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'optional-catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  chain.pop();
+  return false;
+}

package/src/server/types.ts

@@ -22,23 +22,40 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: Record<string, string | string[]>;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
 
+/**
+ * Context passed to `route.ts` HTTP method handlers (GET/POST/etc.).
+ *
+ * `req` is the original incoming Request; `headers` is the response-headers
+ * container the framework will apply to the final Response.
+ *
+ * Segment params and query parameters are NOT on this context — they are
+ * accessed via the same ALS-backed `.get()` accessors pages use:
+ *
+ * ```ts
+ * // app/api/users/[id]/params.ts
+ * export const segmentParams = defineSegmentParams({ id: z.coerce.number() });
+ * // app/api/users/[id]/route.ts
+ * import { segmentParams } from './params';
+ * export async function GET() {
+ *   const { id } = segmentParams.get(); // typed number — 404 on bad input
+ * }
+ * ```
+ *
+ * See design/07-routing.md §"RouteContext", design/23-search-params.md,
+ * design/40-segment-params.md.
+ */
 export interface RouteContext {
   req: Request;
-  params: Record<string, string | string[]>;
-  searchParams: URLSearchParams;
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };
@@ -146,7 +163,7 @@ export interface Metadata {
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace MetadataRoute {
-  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
   export interface Sitemap extends Array<SitemapEntry> {}
   export interface SitemapEntry {
     url: string;
@@ -163,4 +180,56 @@ export namespace MetadataRoute {
     sitemap?: string | string[];
     host?: string;
   }
+  /**
+   * PWA Web App Manifest — serialized as `application/manifest+json`.
+   *
+   * Intentionally permissive: the manifest spec is large and evolving
+   * (W3C + browser-specific extensions). Users that want stricter typing
+   * can augment the return type with a library like `web-app-manifest`.
+   */
+  export type Manifest = Record<string, unknown>;
 }
+
+/**
+ * The value a dynamic metadata route handler may return.
+ *
+ * This is a structural union — the pipeline dispatches on the shape at
+ * request time (see `pipeline-phases.ts`):
+ *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
+ *     Used by `icon.tsx`, `opengraph-image.tsx`,
+ *     `apple-icon.tsx`.
+ *   - `string` → written as the response body verbatim. Used by `robots.ts`
+ *     and by any handler that wants to emit a pre-serialized payload.
+ *   - `MetadataRoute.Sitemap` → serialized via the sitemap XML writer. Used
+ *     by `sitemap.ts`.
+ *   - `MetadataRoute.Manifest` → serialized via `JSON.stringify`. Used by
+ *     `manifest.ts`.
+ *
+ * See design/16-metadata.md §"Metadata Routes".
+ */
+export type MetadataResult = Response | string | MetadataRoute.Sitemap | MetadataRoute.Manifest;
+
+/**
+ * Default export signature for a dynamic metadata route file
+ * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
+ * `opengraph-image.tsx`, `apple-icon.tsx`).
+ *
+ * Parameterize `TResult` to narrow the return type for a specific route:
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import type { MetadataHandler, MetadataRoute } from '@timber-js/app/server';
+ *
+ * const sitemap: MetadataHandler<MetadataRoute.Sitemap> = async () => [
+ *   { url: 'https://example.com/', changeFrequency: 'weekly', priority: 1 },
+ * ];
+ * export default sitemap;
+ * ```
+ *
+ * The handler is currently invoked with no arguments. Per-request context
+ * (`params`, `searchParams`, `Request`) is not yet wired through to metadata
+ * route handlers; when it is, this signature will grow a context parameter.
+ */
+export type MetadataHandler<TResult extends MetadataResult = MetadataResult> = () =>
+  | TResult
+  | Promise<TResult>;

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/utils/mdx-file.ts

@@ -0,0 +1,22 @@
+/**
+ * MDX file-path detection shared by error/deny rendering paths.
+ *
+ * MDX status and error files are server components — they cannot be passed
+ * as function props across the RSC→client boundary (e.g. to
+ * TimberErrorBoundary or ErrorReconstituter) and must be pre-rendered as
+ * elements with plain props instead.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
+ */
+
+/** MDX/markdown extensions — server components by default. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
+
+/**
+ * Check if a file path ends with an MDX/markdown extension.
+ */
+export function isMdxFilePath(filePath: string): boolean {
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) return false;
+  return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}

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 manifest init
+ * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. 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/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.js';
+import type { WorkersCachePurgeCtx } from './als-registry.js';
+
+/**
+ * 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/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;
+}