@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

package/src/server/pipeline.ts

@@ -13,7 +13,7 @@
 
 import { canonicalize } from './canonicalize.js';
 import { runProxy, type ProxyExport } from './proxy.js';
-import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
+import { runMiddlewareChain, type MiddlewareFn } from './middleware-runner.js';
 import { runWithTimingCollector, withTiming, getServerTimingHeader } from './server-timing.js';
 import {
   runWithRequestContext,
@@ -21,6 +21,7 @@ import {
   setMutableCookieContext,
   getSetCookieHeaders,
   markResponseFlushed,
+  setSegmentParams,
 } from './request-context.js';
 import {
   generateTraceId,
@@ -29,7 +30,7 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  traceId,
+  getTraceId,
 } from './tracing.js';
 import {
   logRequestReceived,
@@ -42,10 +43,35 @@ import {
 } from './logger.js';
 import { callOnRequestError } from './instrumentation.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
+import { ParamCoercionError } from './route-element-builder.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
+import { loadModule } from './safe-load.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
 import type { MiddlewareContext } from './types.js';
-import type { SegmentNode } from '#/routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
+
+// ─── Prototype-Pollution-Safe Merge ────────────────────────────────────────
+
+/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Shallow merge that skips prototype-polluting keys.
+ *
+ * Used instead of Object.assign when the source object comes from
+ * user-authored codec output (segmentParams.parse), which could
+ * contain __proto__, constructor, or prototype keys.
+ *
+ * See TIM-655, design/13-security.md
+ */
+export function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      target[key] = source[key];
+    }
+  }
+}
 
 // ─── Route Match Result ────────────────────────────────────────────────────
 
@@ -53,10 +79,10 @@ import type { SegmentNode } from '#/routing/types.js';
 export interface RouteMatch {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Extracted route params (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** The leaf segment's middleware.ts export, if any. */
-  middleware?: MiddlewareFn;
+  /** Extracted segment params (catch-all segments produce string[]). */
+  segmentParams: Record<string, string | string[]>;
+  /** Middleware chain from the segment tree, ordered root-to-leaf. */
+  middlewareChain: MiddlewareFn[];
 }
 
 /** Function that matches a canonical pathname to a route. */
@@ -115,14 +141,25 @@ export interface PipelineConfig {
    * Generated at build time from intercepting route directories.
    * See design/07-routing.md §"Intercepting Routes"
    */
-  interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
+  interceptionRewrites?: import('../routing/interception.js').InterceptionRewrite[];
+  /**
+   * Control Server-Timing header output.
+   *
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render).
+   * - `'total'` — single `total;dur=N` entry (production-safe).
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'total'`.
+   */
+  serverTiming?: 'detailed' | 'total' | false;
   /**
-   * Emit Server-Timing header on responses for Chrome DevTools visibility.
-   * Only enable in dev mode — exposes internal timing data.
+   * Auto-generated sitemap handler. When provided, the pipeline intercepts
+   * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
+   * function. Returns a Response or null (pass-through to regular routing).
    *
-   * Default: false (production-safe).
+   * See design/16-metadata.md §"Auto-generated Sitemap"
    */
-  enableServerTiming?: boolean;
+  autoSitemapHandler?: (pathname: string) => Promise<Response | null>;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -149,6 +186,51 @@ export interface PipelineConfig {
   ) => Response | Promise<Response>;
 }
 
+// ─── Param Coercion ────────────────────────────────────────────────────────
+
+/**
+ * Run segment param coercion on the matched route's segments.
+ *
+ * Loads params.ts modules from segments that have them, extracts the
+ * segmentParams definition, and coerces raw string params through codecs.
+ * Throws ParamCoercionError if any codec fails (→ 404).
+ *
+ * This runs BEFORE middleware, so ctx.segmentParams is already typed.
+ * See design/07-routing.md §"Where Coercion Runs"
+ */
+export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  const segments = match.segments as unknown as import('./route-matcher.js').ManifestSegmentNode[];
+
+  for (const segment of segments) {
+    // Only process segments that have a params.ts convention file
+    if (!segment.params) continue;
+
+    let mod: Record<string, unknown>;
+    try {
+      mod = await loadModule(segment.params);
+    } catch (err) {
+      throw new ParamCoercionError(
+        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
+    const segmentParamsDef = mod.segmentParams as
+      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
+      | undefined;
+
+    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
+
+    try {
+      const coerced = segmentParamsDef.parse(match.segmentParams);
+      // Merge coerced values back — use safeMerge to prevent prototype pollution
+      // from malicious/buggy codec output. See TIM-655.
+      safeMerge(match.segmentParams, coerced as Record<string, unknown>);
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
 // ─── Pipeline ──────────────────────────────────────────────────────────────
 
 /**
@@ -165,7 +247,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     earlyHints,
     stripTrailingSlash = true,
     slowRequestMs = 3000,
-    enableServerTiming = false,
+    serverTiming = 'total',
     onPipelineError,
   } = config;
 
@@ -186,7 +268,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     const traceIdValue = generateTraceId();
 
     return runWithTraceId(traceIdValue, async () => {
-      // Establish request context ALS scope so headers() and cookies() work
+      // Establish request context ALS scope so getHeaders() and getCookies() work
       // throughout the entire request lifecycle (proxy, middleware, render).
       return runWithRequestContext(req, async () => {
         // In dev mode, wrap with timing collector for Server-Timing header.
@@ -216,25 +298,25 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Append Server-Timing header.
-              // In dev mode: detailed per-phase breakdown (proxy, middleware, render).
-              // In production: single total duration — safe to expose, no phase names.
+              // Append Server-Timing header based on configured mode.
               // Response.redirect() creates immutable headers, so we must
               // ensure mutability before writing Server-Timing.
-              if (enableServerTiming) {
-                const serverTiming = getServerTimingHeader();
-                if (serverTiming) {
+              if (serverTiming === 'detailed') {
+                // Detailed: per-phase breakdown (proxy, middleware, render).
+                const timingHeader = getServerTimingHeader();
+                if (timingHeader) {
                   result = ensureMutableResponse(result);
-                  result.headers.set('Server-Timing', serverTiming);
+                  result.headers.set('Server-Timing', timingHeader);
                 }
-              } else {
-                // Production: emit total request duration only.
-                // No phase breakdown — prevents information disclosure
-                // while giving browser DevTools useful timing data.
+              } else if (serverTiming === 'total') {
+                // Total only: single `total;dur=N` — no phase names.
+                // Prevents information disclosure while giving browser
+                // DevTools useful timing data.
                 const totalMs = Math.round(performance.now() - startTime);
                 result = ensureMutableResponse(result);
                 result.headers.set('Server-Timing', `total;dur=${totalMs}`);
               }
+              // serverTiming === false: no header at all
 
               return result;
             }
@@ -254,7 +336,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           return response;
         };
 
-        return enableServerTiming ? runWithTimingCollector(runRequest) : runRequest();
+        return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
       });
     });
   };
@@ -272,7 +354,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
       const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
       return await withSpan('timber.proxy', {}, () =>
-        enableServerTiming ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
+        serverTiming === 'detailed' ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
       );
     } catch (error) {
       // Uncaught proxy.ts error → bare HTTP 500
@@ -283,6 +365,24 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     }
   }
 
+  /**
+   * Build a redirect Response from a RedirectSignal.
+   *
+   * For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
+   * so the client router can perform a soft SPA redirect. A raw 302 would be
+   * turned into an opaque redirect by fetch({redirect:'manual'}), crashing
+   * createFromFetch. See design/19-client-navigation.md.
+   */
+  function buildRedirectResponse(signal: RedirectSignal, req: Request, headers: Headers): Response {
+    const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+    if (isRsc) {
+      headers.set('X-Timber-Redirect', signal.location);
+      return new Response(null, { status: 204, headers });
+    }
+    headers.set('Location', signal.location);
+    return new Response(null, { status: signal.status, headers });
+  }
+
   async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
     // Stage 1: URL canonicalization
     const url = new URL(req.url);
@@ -306,7 +406,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
             return await serveStaticMetadataFile(metaMatch);
           }
 
-          const mod = (await metaMatch.file.load()) as { default?: Function };
+          const mod = await loadModule<{ default?: Function }>(metaMatch.file);
           if (typeof mod.default !== 'function') {
             return new Response('Metadata route must export a default function', { status: 500 });
           }
@@ -339,6 +439,36 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // Stage 1b.2: Auto-generated sitemap — serves /sitemap.xml and /sitemap/N.xml
+    // when sitemap generation is enabled and no user-authored sitemap exists.
+    // Runs after metadata route matching so user sitemaps always take precedence.
+    // See design/16-metadata.md §"Auto-generated Sitemap"
+    if (config.autoSitemapHandler) {
+      try {
+        const sitemapResponse = await config.autoSitemapHandler(canonicalPathname);
+        if (sitemapResponse) return sitemapResponse;
+      } catch (error) {
+        logRenderError({ method, path, error });
+        if (onPipelineError && error instanceof Error) onPipelineError(error, 'auto-sitemap');
+        return new Response(null, { status: 500 });
+      }
+    }
+
+    // Stage 1c: Version skew detection (TIM-446).
+    // For RSC payload requests (client navigation), check if the client's
+    // deployment ID matches the current build. On mismatch, signal the
+    // client to do a full page reload instead of returning an RSC payload
+    // that references mismatched module IDs.
+    const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
+    if (isRscRequest) {
+      const skewCheck = checkVersionSkew(req);
+      if (!skewCheck.ok) {
+        const reloadHeaders = new Headers();
+        applyReloadHeaders(reloadHeaders);
+        return new Response(null, { status: 204, headers: reloadHeaders });
+      }
+    }
+
     // Stage 2: Route matching
     let match = matchRoute(canonicalPathname);
     let interception: InterceptionContext | undefined;
@@ -397,18 +527,57 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
-    // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
-    if (match.middleware) {
+    // Stage 2c: Param coercion (before middleware)
+    // Load params.ts modules from matched segments and coerce raw string
+    // params through defineSegmentParams codecs. Coercion failure → 404
+    // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
+    try {
+      await coerceSegmentParams(match);
+    } catch (error) {
+      if (error instanceof ParamCoercionError) {
+        // For API routes (route.ts), return a bare 404 — not an HTML page.
+        // API consumers expect JSON/empty responses, not rendered HTML.
+        const leafSegment = match.segments[match.segments.length - 1];
+        if (
+          (leafSegment as { route?: unknown }).route &&
+          !(leafSegment as { page?: unknown }).page
+        ) {
+          return new Response(null, { status: 404 });
+        }
+        // Route through the app's 404 page (404.tsx in root layout) instead of
+        // returning a bare empty 404 Response. Falls back to bare 404 only if
+        // no renderNoMatch renderer is configured.
+        if (config.renderNoMatch) {
+          return config.renderNoMatch(req, responseHeaders);
+        }
+        return new Response(null, { status: 404 });
+      }
+      throw error;
+    }
+
+    // Store coerced segment params in ALS so components can access them
+    // via getSegmentParams() instead of receiving them as a prop.
+    // See design/07-routing.md §"params.ts — Convention File for Typed Params"
+    setSegmentParams(match.segmentParams);
+
+    // Stage 3: Middleware chain (root-to-leaf, short-circuits on first Response)
+    if (match.middlewareChain.length > 0) {
       const ctx: MiddlewareContext = {
         req,
         requestHeaders: requestHeaderOverlay,
         headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
+        segmentParams: match.segmentParams,
         earlyHints: (hints) => {
           for (const hint of hints) {
-            let value = `<${hint.href}>; rel=${hint.rel}`;
-            if (hint.as !== undefined) value += `; as=${hint.as}`;
+            // Match Cloudflare's cached Early Hints attribute order: `as` before `rel`.
+            // Cloudflare caches Link headers and re-emits them on subsequent 200s.
+            // If our order differs, the browser sees duplicate preloads and warns.
+            let value: string;
+            if (hint.as !== undefined) {
+              value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
+            } else {
+              value = `<${hint.href}>; rel=${hint.rel}`;
+            }
             if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
             if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
             responseHeaders.append('Link', value);
@@ -419,9 +588,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       try {
         // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
         setMutableCookieContext(true);
-        const middlewareFn = () => runMiddleware(match.middleware!, ctx);
+        const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
         const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          enableServerTiming ? withTiming('mw', 'middleware.ts', middlewareFn) : middlewareFn()
+          serverTiming === 'detailed' ? withTiming('mw', 'middleware.ts', chainFn) : chainFn()
         );
         setMutableCookieContext(false);
         if (middlewareResponse) {
@@ -430,28 +599,30 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           // mutability before appending Set-Cookie entries.
           const finalResponse = ensureMutableResponse(middlewareResponse);
           applyCookieJar(finalResponse.headers);
+          // Merge parent-set responseHeaders onto the short-circuit response.
+          // Child-set headers take precedence — only add headers not already present.
+          // Snapshot existing keys first so multi-value headers (Set-Cookie, Link)
+          // from the parent are all appended when the child didn't set that key.
+          const existingKeys = new Set(
+            [...finalResponse.headers.keys()].map((k) => k.toLowerCase())
+          );
+          for (const [key, value] of responseHeaders.entries()) {
+            if (!existingKeys.has(key.toLowerCase())) {
+              finalResponse.headers.append(key, value);
+            }
+          }
           logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
           return finalResponse;
         }
-        // Middleware succeeded without short-circuiting — apply any
-        // injected request headers so headers() returns them downstream.
+        // Middleware chain completed without short-circuiting — apply any
+        // injected request headers so getHeaders() returns them downstream.
         applyRequestHeaderOverlay(requestHeaderOverlay);
       } catch (error) {
         setMutableCookieContext(false);
-        // RedirectSignal from middleware → HTTP redirect (not an error).
-        // For RSC payload requests (client navigation), return 204 + X-Timber-Redirect
-        // so the client router can perform a soft SPA redirect. A raw 302 would be
-        // turned into an opaque redirect by fetch({redirect:'manual'}), crashing
-        // createFromFetch. See design/19-client-navigation.md.
+        // RedirectSignal from middleware → HTTP redirect (not an error)
         if (error instanceof RedirectSignal) {
           applyCookieJar(responseHeaders);
-          const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-          if (isRsc) {
-            responseHeaders.set('X-Timber-Redirect', error.location);
-            return new Response(null, { status: 204, headers: responseHeaders });
-          }
-          responseHeaders.set('Location', error.location);
-          return new Response(null, { status: error.status, headers: responseHeaders });
+          return buildRedirectResponse(error, req, responseHeaders);
         }
         // DenySignal from middleware → HTTP deny status
         if (error instanceof DenySignal) {
@@ -476,7 +647,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       const renderFn = () =>
         render(req, match, responseHeaders, requestHeaderOverlay, interception);
       const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        enableServerTiming ? withTiming('render', 'RSC + SSR render', renderFn) : renderFn()
+        serverTiming === 'detailed'
+          ? withTiming('render', 'RSC + SSR render', renderFn)
+          : renderFn()
       );
       markResponseFlushed();
       return response;
@@ -486,17 +659,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       if (error instanceof DenySignal) {
         return new Response(null, { status: error.status });
       }
-      // RedirectSignal leaked from render — honour the redirect.
-      // For RSC payload requests, return 204 + X-Timber-Redirect so the
-      // client router can perform a soft SPA redirect (same as middleware path).
+      // RedirectSignal leaked from render — honour the redirect
       if (error instanceof RedirectSignal) {
-        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-        if (isRsc) {
-          responseHeaders.set('X-Timber-Redirect', error.location);
-          return new Response(null, { status: 204, headers: responseHeaders });
-        }
-        responseHeaders.set('Location', error.location);
-        return new Response(null, { status: error.status, headers: responseHeaders });
+        return buildRedirectResponse(error, req, responseHeaders);
       }
       logRenderError({ method, path, error });
       await fireOnRequestError(error, req, 'render');
@@ -532,7 +697,7 @@ async function fireOnRequestError(
   await callOnRequestError(
     error,
     { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: traceId() }
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
   );
 }
 

package/src/server/primitives.ts

@@ -6,6 +6,8 @@
 import type { JsonSerializable } from './types.js';
 import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
 import { isDebug } from './debug.js';
+import { getRequestSearchString } from './request-context.js';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -143,37 +145,65 @@ export class DenySignal extends Error {
   }
 }
 
+/** Options for deny() when using the object form. */
+export interface DenyOptions {
+  /** HTTP status code (4xx or 5xx). Default: 403. */
+  status?: number;
+  /** Human-readable message (logged server-side, not sent to client). */
+  message?: string;
+  /** JSON-serializable data passed as `dangerouslyPassData` prop to status-code files. */
+  data?: 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.
+ * Supports both positional and object signatures:
+ * ```ts
+ * deny()                                          // 403 (default)
+ * deny(404)                                       // 404
+ * deny(503, { retry: true })                      // 503 with data
+ * deny({ status: 503, message: 'Maintenance' })   // object form
+ * ```
+ *
+ * Accepts any 4xx or 5xx status code. This replaces the need for
+ * `throw new RenderError(...)` in user code — RenderError is now an
+ * internal pipeline detail.
+ *
+ * @param statusOrOptions - Status code (number) or options object. Default: 403.
+ * @param data - Optional JSON-serializable data (positional form only).
  */
-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.'
-    );
+export function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializable): never {
+  let status: number;
+  let resolvedData: JsonSerializable | undefined;
+
+  if (typeof statusOrOptions === 'object' && statusOrOptions !== null) {
+    status = statusOrOptions.status ?? 403;
+    resolvedData = statusOrOptions.data;
+  } else {
+    status = statusOrOptions ?? 403;
+    resolvedData = data;
   }
-  warnIfNotSerializable(data, 'deny()');
-  throw new DenySignal(status, data);
+
+  if (status < 400 || status > 599) {
+    throw new Error(`deny() requires a 4xx or 5xx status code, got ${status}.`);
+  }
+  warnIfNotSerializable(resolvedData, 'deny()');
+  throw new DenySignal(status, resolvedData);
 }
 
 /**
- * Convenience alias for `deny(404)`.
- *
- * 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.
+ * @deprecated Use `deny(404)` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
 export function notFound(): never {
-  throw new DenySignal(404);
+  deny(404);
 }
 
 /**
@@ -209,14 +239,63 @@ 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+\-.]*:|\/\/)/;
 
+/**
+ * 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}.`);
   }
@@ -226,19 +305,23 @@ export function redirect(path: string, status: number = 302): never {
         'Use redirectExternal(url, allowList) for external redirects.'
     );
   }
-  throw new RedirectSignal(path, status);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
+  }
+
+  throw new RedirectSignal(resolvedPath, 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')
+ * @deprecated Use `redirect(path, { permanent: true })` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
+  redirect(path, { permanent: true, ...options });
 }
 
 /**