@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.126

package/src/rsc/helpers.ts

@@ -11,6 +11,11 @@ import {
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isRedirectResponse } from "../response-utils.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
 import type { RscPayload } from "./types.js";
@@ -41,6 +46,10 @@ function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
 function applyStubHeaders(target: Headers, stub: Headers): void {
   stub.forEach((value, name) => {
     try {
+      // The reserved external-redirect marker is internal and never a trust
+      // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+      // browser-facing response. The opt-in is the out-of-band brand.
+      if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
       if (name.toLowerCase() === "set-cookie") {
         target.append(name, value);
       } else if (!target.has(name)) {
@@ -64,10 +73,19 @@ function drainOnResponseCallbacks(
   const callbacks = ctx._onResponseCallbacks;
   if (callbacks.length === 0) return response;
   ctx._onResponseCallbacks = [];
+  // An onResponse callback may return a NEW Response (e.g. to add a header),
+  // which drops the out-of-band external-redirect brand (brand is keyed on
+  // Response object identity). Preserve a redirect(url, { external: true })
+  // opt-in across that rebuild so a callback can't silently neutralize the
+  // off-host redirect at the guard chokepoint.
+  const wasExternal = isExternalRedirect(response);
   let result = response;
   for (const callback of callbacks) {
     result = callback(result) ?? result;
   }
+  if (wasExternal && !isExternalRedirect(result)) {
+    markExternalRedirect(result);
+  }
   return result;
 }
 
@@ -135,8 +153,20 @@ export function createSimpleRedirectResponse(redirectUrl: string): Response {
 
 /**
  * Carry over headers from a source redirect Response to a wrapper Response.
- * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper)
- * and appends Set-Cookie to avoid clobbering multiple cookie headers.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper) and
+ * appends Set-Cookie to avoid clobbering multiple cookie headers.
+ *
+ * This is a GENERIC copier used by every redirect-rebuild path (PE
+ * extractRedirectResponse, the SPA intercept below, the guard's neutralize
+ * rebuild), so it has two redirect-specific jobs:
+ *
+ * 1. NEVER copy the reserved external-redirect header: it is no longer a trust
+ *    signal (the opt-in is the out-of-band brand), and a forged value from a
+ *    proxied upstream must not ride a rebuilt response to the browser.
+ * 2. Transfer the out-of-band external brand: a rebuilt document-native redirect
+ *    has to carry the opt-in to the guard chokepoint, which reads and clears it.
+ *    Without this transfer, redirect(url, { external: true }) would be silently
+ *    neutralized on any rebuild path (fail-closed, but a feature regression).
  */
 export function carryOverRedirectHeaders(
   source: Response,
@@ -145,12 +175,16 @@ export function carryOverRedirectHeaders(
   source.headers.forEach((value, name) => {
     const lower = name.toLowerCase();
     if (lower === "location" || lower === "x-rsc-redirect") return;
+    if (lower === EXTERNAL_REDIRECT_MARKER) return;
     if (lower === "set-cookie") {
       target.headers.append(name, value);
     } else if (!target.headers.has(name)) {
       target.headers.set(name, value);
     }
   });
+  if (isExternalRedirect(source)) {
+    markExternalRedirect(target);
+  }
 }
 
 /**
@@ -164,24 +198,44 @@ export function interceptRedirectForPartial(
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response,
 ): Response | null {
   if (!isRedirectResponse(response)) {
     return null;
   }
   const redirectUrl = response.headers.get("Location")!;
+  // redirect(url, { external: true }) marks an explicit off-host redirect via
+  // the out-of-band brand (not a wire header). On the SPA/action channel the
+  // intent must travel as a Flight payload (metadata.redirect.external) so the
+  // client does a scheme-validated hard navigation (location.assign) rather than
+  // a partial fetch. The client re-validates the scheme; see partial-update.ts.
+  const external = isExternalRedirect(response);
   const locationState = getLocationState();
   let intercepted: Response;
   if (locationState) {
     intercepted = createRedirectFlightResponse(
       redirectUrl,
       resolveLocationStateEntries(locationState),
+      external,
     );
+  } else if (external) {
+    intercepted = createRedirectFlightResponse(redirectUrl, undefined, true);
   } else {
     intercepted = createSimpleRedirectResponse(redirectUrl);
   }
 
   carryOverRedirectHeaders(response, intercepted);
+  // Defense-in-depth at the SPA browser-facing exit: carryOverRedirectHeaders
+  // already refuses to copy the reserved marker, but strip any value that might
+  // exist on `intercepted` so a forged header can never ride the 200/204 to the
+  // browser. The external intent travels in metadata.redirect.external (Flight),
+  // where the client re-validates the scheme.
+  try {
+    intercepted.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Immutable headers: the marker was never copied here, so this is inert.
+  }
 
   return intercepted;
 }
@@ -226,7 +280,6 @@ export function buildRouteMiddlewareEntries<TEnv>(
       regex: null,
       paramNames: [],
       handler: mw.handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params: mw.params,
   }));

package/src/rsc/json-route-result.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+
+import { RouterError } from "../errors.js";
+
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export function stringifyJsonRouteResult(result: unknown): string {
+  return JSON.stringify(result, (_key, value) => {
+    if (
+      value != null &&
+      typeof (value as { then?: unknown }).then === "function"
+    ) {
+      throw new RouterError(
+        "RESPONSE_NOT_SERIALIZABLE",
+        "A json() response route returned a Promise (likely a forgotten " +
+          "await). Await async values before returning so they serialize, " +
+          "instead of emitting an empty {}.",
+      );
+    }
+    return value;
+  });
+}

package/src/rsc/origin-guard.ts

@@ -86,10 +86,16 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
 
   if (requestOrigin === "null") return false;
 
-  const expectedHost = request.headers.get("host") || url.host;
-  const expectedProtocol = url.protocol;
-
-  const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
+  // An Origin/Referer is present, so this is a browser request worth checking.
+  // Establish the expected origin from the Host header only -- browsers always
+  // send Host alongside Origin (runtimes synthesize it from the HTTP/2
+  // :authority), so a missing Host here is anomalous. Fail closed rather than
+  // fall back to url.host (derived from the request line) when the trusted Host
+  // cannot be established.
+  const expectedHost = request.headers.get("host");
+  if (!expectedHost) return false;
+
+  const expectedOrigin = `${url.protocol}//${expectedHost}`;
 
   return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();
 }

package/src/rsc/progressive-enhancement.ts

@@ -155,6 +155,14 @@ export async function handleProgressiveEnhancement<TEnv>(
   } else if (isDirectAction && directActionId) {
     const temporaryReferences = ctx.createTemporaryReferenceSet();
 
+    // INTENTIONAL JS/PE divergence (do NOT "fix" to match the JS reject path).
+    // On the JS path React Flight-encodes the action args, so decodeReply
+    // succeeds or a failure means a malformed body (rejected). On the no-JS PE
+    // path the browser submits a raw <form action={fn}> POST with NO encoded
+    // args, so decodeReply throws by design and the raw FormData IS the action
+    // argument (the React form-action convention: fn(formData)). Removing this
+    // fallback breaks every unbound no-JS form action (verified: it fails the
+    // progressive-enhancement dev+prod e2e suite). See #572 (decided: keep).
     let args: unknown[] = [];
     try {
       args = await ctx.decodeReply(formData, { temporaryReferences });

package/src/rsc/redirect-guard.ts

@@ -0,0 +1,99 @@
+/**
+ * Server-side open-redirect guard.
+ *
+ * Applied to the FINAL handler response (the single top-level return in
+ * `handler.ts`) so every browser-followed redirect honors the same same-origin
+ * rule the client enforces (`browser/validate-redirect-origin.ts`), via the one
+ * shared resolver in `redirect-origin.ts`. This is the server half of the
+ * client's existing guard: the client can only validate redirects its own JS
+ * navigates to (the SPA/fetch channel), so document-native redirects -- a no-JS
+ * PE form POST, a full-page GET `match.redirect`, a middleware `redirect()`
+ * short-circuit, a response-route 3xx -- reach the browser with no client in the
+ * loop. They all funnel through one handler return, so guarding there covers
+ * every one and any future redirect exit.
+ *
+ * Soft (SPA/Flight) redirects are 200/204 responses (`X-RSC-Redirect` header or
+ * `metadata.redirect` payload) and are NOT redirect Responses, so they never
+ * reach this guard -- they stay validated client-side.
+ *
+ * Behavior on a `Location` header:
+ * - same-origin / relative  -> passes through unchanged
+ * - `redirect(url, { external: true })` (out-of-band brand present) and an
+ *   http(s) target -> allowed (explicit, auditable, unforgeable opt-in)
+ * - branded but a non-http(s) target (e.g. `javascript:`) -> neutralized: the
+ *   opt-in waives the same-origin rule, NOT scheme safety
+ * - cross-origin without the brand -> Location rewritten to the basename root
+ *   (a safe same-origin landing, the document analog of the client's "stay put");
+ *   dev logs the blocked target and points to `{ external: true }`.
+ *
+ * The opt-in is an out-of-band brand on the Response object (isExternalRedirect),
+ * never a wire header: a header is forgeable by an attacker-controlled upstream
+ * response a proxy-style response route copies through, which would defeat the
+ * guard without app code ever opting in. The reserved header name is stripped
+ * defensively so a forged value can never reach the browser.
+ */
+
+import { isRedirectResponse } from "../response-utils.js";
+import {
+  resolveSameOriginRedirect,
+  resolveExternalRedirect,
+  isExternalRedirect,
+  EXTERNAL_REDIRECT_MARKER,
+} from "../redirect-origin.js";
+import { carryOverRedirectHeaders } from "./helpers.js";
+
+export function guardOutgoingRedirect(
+  response: Response,
+  requestOrigin: string,
+  basename: string | undefined,
+): Response {
+  // Only 3xx + Location responses (document-native redirects) are guarded.
+  if (!isRedirectResponse(response)) {
+    return response;
+  }
+
+  // The reserved marker is never a trust signal. Strip any value -- forged by a
+  // proxied upstream or otherwise -- so it can never reach the browser. Trust
+  // comes solely from the out-of-band brand below.
+  try {
+    response.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Some platform responses carry immutable headers; the header is inert on
+    // the browser, so a failed strip is harmless.
+  }
+
+  // isRedirectResponse guarantees a truthy Location.
+  const location = response.headers.get("Location")!;
+
+  // Explicit opt-in via redirect(url, { external: true }): allow an off-host
+  // target, but only an http(s) one. external waives the same-origin rule, not
+  // scheme safety -- a branded javascript:/data: target falls through to be
+  // neutralized so it can never become a scriptable navigation downstream.
+  if (isExternalRedirect(response)) {
+    if (resolveExternalRedirect(location, requestOrigin) !== null) {
+      return response;
+    }
+  } else if (resolveSameOriginRedirect(location, requestOrigin) !== null) {
+    return response;
+  }
+
+  // Cross-origin (or unsafe-scheme external): neutralize to a safe same-origin
+  // landing.
+  const safeTarget = basename && basename !== "/" ? basename : "/";
+  if (process.env.NODE_ENV !== "production") {
+    console.error(
+      `[rango] Blocked cross-origin redirect to "${location}"; sent to ` +
+        `"${safeTarget}" instead. To redirect off-host on purpose, use ` +
+        `redirect(url, { external: true }).`,
+    );
+  }
+
+  const blocked = new Response(null, {
+    status: response.status,
+    headers: { Location: safeTarget },
+  });
+  // Preserve cookies and any other headers (Set-Cookie, Server-Timing, ...);
+  // carryOverRedirectHeaders intentionally skips Location.
+  carryOverRedirectHeaders(response, blocked);
+  return blocked;
+}

package/src/rsc/response-route-handler.ts

@@ -30,6 +30,12 @@ import {
   mergeStubHeadersAndFinalize,
 } from "./helpers.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { stringifyJsonRouteResult } from "./json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -110,16 +116,29 @@ export async function handleResponseRoute<TEnv>(
       }
       const headers = new Headers();
       result.headers.forEach((value, key) => {
+        // Never copy the reserved external-redirect marker off a handler result.
+        // It is not a trust signal -- the opt-in is the out-of-band brand below
+        // -- and a proxy-style route returning an attacker-controlled upstream
+        // response must not let a forged value ride through to the browser.
+        if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
         if (key.toLowerCase() === "set-cookie") {
           headers.append(key, value);
         } else {
           headers.set(key, value);
         }
       });
-      return createResponseWithMergedHeaders(result.body, {
+      const rewrapped = createResponseWithMergedHeaders(result.body, {
         status: result.status,
         headers,
       });
+      // Transfer the out-of-band external brand only when the handler result is
+      // genuinely branded (a real redirect(url, { external: true })). A proxied
+      // upstream Response is never branded, so an attacker cannot opt a response
+      // route's redirect out of the same-origin guard by injecting the header.
+      if (isExternalRedirect(result)) {
+        markExternalRedirect(rewrapped);
+      }
+      return rewrapped;
     };
 
     try {
@@ -133,23 +152,9 @@ export async function handleResponseRoute<TEnv>(
       if (preview.responseType === "json") {
         // Runtime guard: the json() return type rejects nested Promises at
         // compile time, but an `as`-cast or untyped (JS) handler can still slip
-        // one through. JSON.stringify would silently emit {} for it (the
-        // forgotten-await footgun — the RSC pipeline awaits nested promises, this
-        // path does not). Throw a clear error instead of shipping empty data.
-        const body = JSON.stringify(result, (_key, value) => {
-          if (
-            value != null &&
-            typeof (value as { then?: unknown }).then === "function"
-          ) {
-            throw new RouterError(
-              "RESPONSE_NOT_SERIALIZABLE",
-              "A json() response route returned a Promise (likely a forgotten " +
-                "await). Await async values before returning so they serialize, " +
-                "instead of emitting an empty {}.",
-            );
-          }
-          return value;
-        });
+        // one through. stringifyJsonRouteResult throws a clear error instead of
+        // shipping empty data (shared with dispatch() so the two cannot drift).
+        const body = stringifyJsonRouteResult(result);
         return createResponseWithMergedHeaders(body, {
           status: 200,
           headers: { "content-type": "application/json;charset=utf-8" },

package/src/rsc/server-action.ts

@@ -85,7 +85,10 @@ export async function executeServerAction<TEnv>(
       args = await ctx.decodeReply(body, { temporaryReferences });
     }
   } catch (error) {
-    throw new Error(`Failed to decode action arguments: ${error}`, {
+    // Keep the original error as `cause` for server-side logging, but do not
+    // interpolate it into the message: that string can surface to the client
+    // and may leak decode internals.
+    throw new Error("Failed to decode action arguments", {
       cause: error,
     });
   }

package/src/rsc/types.ts

@@ -53,8 +53,12 @@ export interface RscPayload {
     basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
-    /** Server-side redirect with optional state (for partial requests) */
-    redirect?: { url: string };
+    /**
+     * Server-side redirect with optional state (for partial requests).
+     * `external: true` (from redirect(url, { external: true })) tells the client
+     * to hard-navigate to an off-host target instead of validating same-origin.
+     */
+    redirect?: { url: string; external?: boolean };
     /** Server-set location state to include in history.pushState */
     locationState?: Record<string, unknown>;
   };

package/src/server/request-context.ts

@@ -40,6 +40,7 @@ import {
   type HandleData,
 } from "./handle-store.js";
 import { isHandle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
@@ -476,6 +477,7 @@ export function _getRequestContext<TEnv = DefaultEnv>():
 export function setRequestContextParams(
   params: Record<string, string>,
   routeName?: string,
+  routeMap?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
   if (ctx) {
@@ -488,9 +490,13 @@ export function setRequestContextParams(
           : undefined
       ) as DefaultRouteName | undefined;
     }
-    // Update reverse with scoped resolution now that route is known
+    // Update reverse with scoped resolution now that route is known. Production
+    // omits routeMap and uses the global map (routes are registered globally);
+    // the testing primitives (renderToFlightString/renderServerTree) pass a
+    // scoped routeMap so `ctx.reverse` is not order-dependent on whatever router
+    // registered last.
     ctx.reverse = createReverseFunction(
-      getGlobalRouteMap(),
+      routeMap ?? getGlobalRouteMap(),
       routeName,
       params,
       routeName ? isRouteRootScoped(routeName) : undefined,
@@ -968,7 +974,10 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   return result;
 }
 
-function parseCookiesFromHeader(
+// Exported for unit tests; the canonical cookie parse/serialize lives here
+// (a duplicate copy in middleware-cookies.ts was removed). Not part of the
+// public export surface.
+export function parseCookiesFromHeader(
   cookieHeader: string | null,
 ): Record<string, string> {
   if (!cookieHeader) return {};
@@ -992,7 +1001,7 @@ function parseCookiesFromHeader(
   return cookies;
 }
 
-function serializeCookieValue(
+export function serializeCookieValue(
   name: string,
   value: string,
   options: CookieOptions = {},
@@ -1037,16 +1046,16 @@ export function createUseFunction<TEnv>(
         );
       }
 
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          const valueOrPromise =
+            typeof dataOrFn === "function"
+              ? (dataOrFn as () => Promise<unknown>)()
+              : dataOrFn;
 
-        handleStore.push(handle.$$id, segmentId, valueOrPromise);
-      };
+          handleStore.push(handle.$$id, segmentId, valueOrPromise);
+        },
+      );
     }
 
     const loader = item as LoaderDefinition<any, any>;

package/src/testing/cache-status.ts

@@ -12,7 +12,14 @@
  * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
  *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
  *    production surface: no header, just structured `cache.decision` events
- *    (which carry the same coarse `segments` cache signal).
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
  *
  * v1 cache status is COARSE (route-level): the router reports a single entry
  * keyed by the route key (the route NAME), not per individual segment.
@@ -117,3 +124,39 @@ export function filterCacheDecisions(
     (e): e is CacheDecisionEvent => e.type === "cache.decision",
   );
 }
+
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export function assertCacheDecision(
+  events: readonly TelemetryEvent[],
+  routeKey: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const segments = filterCacheDecisions(events).flatMap(
+    (d) => d.segments ?? [],
+  );
+  const seg = segments.find((s) => s.id === routeKey);
+  if (seg === undefined) {
+    const known = segments.map((s) => s.id);
+    throw new Error(
+      `assertCacheDecision: no cache.decision segment for routeKey "${routeKey}". ` +
+        `Seen: ${known.length > 0 ? known.join(", ") : "(none)"}. Wire ` +
+        `createRouter({ telemetry: createCacheSink().sink }) and drive an RSC request.`,
+    );
+  }
+  if (seg.cacheStatus !== expected) {
+    throw new Error(
+      `assertCacheDecision: routeKey "${routeKey}" expected "${expected}" but got "${seg.cacheStatus}".`,
+    );
+  }
+}

package/src/testing/dispatch.ts

@@ -37,6 +37,10 @@
  *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
  *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
  *   identical to production's no-location-state path.
+ * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
+ *   redirects: a cross-origin Location is rewritten to the basename root unless
+ *   redirect(url, { external: true }) opted out, mirroring production's single
+ *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -91,6 +95,13 @@ import {
   interceptRedirectForPartial,
   mergeStubHeadersAndFinalize,
 } from "../rsc/helpers.js";
+import { guardOutgoingRedirect } from "../rsc/redirect-guard.js";
+import { stringifyJsonRouteResult } from "../rsc/json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import type { Rango } from "../router/router-interfaces.js";
 
@@ -154,7 +165,8 @@ function toRequest(request: Request | string): Request {
 /**
  * Serialize a NON-Response response-route handler result, mirroring the
  * router's handleResponseRoute() contract:
- * - "json" serializes the value verbatim (bare) with application/json,
+ * - "json" serializes the value (bare) with application/json, rejecting a nested
+ *   unresolved Promise via the shared stringifyJsonRouteResult guard,
  * - text/html/xml/md stringify with the mapped MIME type.
  *
  * A handler-returned Response is NOT routed here — callHandler re-wraps it via
@@ -167,7 +179,12 @@ function serializeResponseRouteResult(
   responseType: string,
 ): Response {
   if (responseType === "json") {
-    return new Response(JSON.stringify(result), {
+    // Serialize through the SAME guard production uses: a nested unresolved
+    // Promise (forgotten await) throws RESPONSE_NOT_SERIALIZABLE here, caught by
+    // callHandler's catch and mapped to the identical typed 500 production
+    // returns -- so a dispatch json test fails exactly where production would,
+    // instead of silently emitting {} and passing.
+    return new Response(stringifyJsonRouteResult(result), {
       status: 200,
       headers: { "content-type": "application/json;charset=utf-8" },
     });
@@ -252,16 +269,27 @@ function rewrapHandlerResponse(result: Response): Response {
   }
   const headers = new Headers();
   result.headers.forEach((value, key) => {
+    // Mirror production: never copy the reserved external-redirect marker off a
+    // handler result (it is not a trust signal; the opt-in is the out-of-band
+    // brand transferred below).
+    if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (key.toLowerCase() === "set-cookie") {
       headers.append(key, value);
     } else {
       headers.set(key, value);
     }
   });
-  return createResponseWithMergedHeaders(result.body, {
+  const rewrapped = createResponseWithMergedHeaders(result.body, {
     status: result.status,
     headers,
   });
+  // Mirror production's rewrapResponse: transfer the out-of-band external brand
+  // only from a genuinely branded result (a real redirect(url, { external:
+  // true })), never from a proxied upstream's forged header.
+  if (isExternalRedirect(result)) {
+    markExternalRedirect(rewrapped);
+  }
+  return rewrapped;
 }
 
 /**
@@ -506,7 +534,6 @@ export async function dispatch<TEnv = any>(
             regex: null,
             paramNames: [],
             handler: mw.handler,
-            mountPrefix: null,
           } as MiddlewareEntry<TEnv>,
           params: mw.params,
         }),
@@ -569,13 +596,23 @@ export async function dispatch<TEnv = any>(
     // callbacks via finalizeResponse. dispatch is RSC-free, so the
     // createRedirectFlightResponse stand-in falls back to the no-state
     // 204 + X-RSC-Redirect (see the location-state divergence in the header).
+    let finalResponse: Response;
     if (isPartial || isAction) {
       const intercepted = interceptRedirectForPartial(
         mwResponse,
         (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
       );
-      return finalizeResponse(intercepted ?? mwResponse);
+      finalResponse = finalizeResponse(intercepted ?? mwResponse);
+    } else {
+      finalResponse = finalizeResponse(mwResponse);
     }
-    return finalizeResponse(mwResponse);
+
+    // Mirror production's single open-redirect chokepoint (handler.ts): every
+    // browser-followed (3xx + Location) redirect is same-origin guarded before
+    // it leaves -- a cross-origin Location is rewritten to the basename root
+    // unless redirect(url, { external: true }) opted out. Soft partial/action
+    // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
+    // validates them), so this is a no-op for them.
+    return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
   });
 }

package/src/testing/e2e/index.ts

@@ -32,6 +32,7 @@ import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 
 export {
   assertCacheStatus,
+  assertCacheDecision,
   parseCacheHeader,
   createCacheSink,
   filterCacheDecisions,