@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.98914650

package/src/rsc/origin-guard.ts

@@ -9,11 +9,31 @@
  * navigations, bookmarks, and non-browser clients don't send Origin.
  */
 
+import type { RequestPlan } from "../router/request-classification.js";
+
 /**
  * Request phase that triggered the origin check.
  */
 export type OriginCheckPhase = "action" | "loader" | "pe-form";
 
+// Exhaustive over RequestPlan modes so a new mode must be classified here (the
+// security gate) instead of silently falling through to no origin check.
+export const ORIGIN_CHECK_PHASE_BY_MODE: Record<
+  RequestPlan["mode"],
+  OriginCheckPhase | null
+> = {
+  action: "action",
+  loader: "loader",
+  "pe-render": "pe-form",
+  "full-render": null,
+  "partial-render": null,
+  response: null,
+  redirect: null,
+  "version-mismatch": null,
+  // Terminal: handled before the origin guard (emits X-RSC-Reload, no execution).
+  "app-switch": null,
+};
+
 /**
  * Context passed to the originCheck callback.
  */
@@ -49,11 +69,8 @@ export type OriginCheckConfig<TEnv = any> =
  * Returns true to allow, false to reject.
  */
 export function defaultOriginCheck(request: Request, url: URL): boolean {
-  // 1. Read Origin header (present on all cross-origin requests and
-  //    same-origin POST/PUT/PATCH/DELETE in modern browsers)
   let requestOrigin = request.headers.get("origin");
 
-  // 2. Fallback to Referer if Origin is absent (some proxies strip it)
   if (!requestOrigin) {
     const referer = request.headers.get("referer");
     if (referer) {
@@ -65,23 +82,20 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
     }
   }
 
-  // 3. No Origin or Referer — allow (can't be browser-initiated CSRF)
   if (!requestOrigin) return true;
 
-  // "null" origin comes from privacy-sensitive contexts (data: URLs,
-  // sandboxed iframes, cross-origin redirects). Reject it.
   if (requestOrigin === "null") return false;
 
-  // 4. Determine expected host from Host header or URL.
-  // X-Forwarded-Host/Proto are NOT used — they are client-controllable
-  // unless a trusted proxy strips them. On standard deployments (Cloudflare
-  // Workers, Node behind nginx/caddy) the Host header is already correct.
-  // For non-standard setups, use the custom function escape hatch.
-  const expectedHost = request.headers.get("host") || url.host;
-  const expectedProtocol = url.protocol;
+  // 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;
 
-  // 5. Build expected origin and compare (case-insensitive)
-  const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
+  const expectedOrigin = `${url.protocol}//${expectedHost}`;
 
   return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();
 }
@@ -116,14 +130,15 @@ export async function checkRequestOrigin<TEnv = any>(
   // Disabled by explicit opt-out
   if (config === false) return null;
 
-  // Default: built-in validation (config === true or undefined)
-  if (config === true || config === undefined) {
-    const allowed = defaultOriginCheck(request, url);
-    if (allowed) return null;
-    return createForbiddenResponse(request);
-  }
+  // Default (true/undefined) becomes a callback returning boolean, so the
+  // Response|true|reject resolution below is written once.
+  const check: (
+    ctx: OriginCheckContext<TEnv>,
+  ) => boolean | Response | Promise<boolean | Response> =
+    config === true || config === undefined
+      ? () => defaultOriginCheck(request, url)
+      : config;
 
-  // Custom function — build context and call
   const ctx: OriginCheckContext<TEnv> = {
     request,
     url,
@@ -133,9 +148,8 @@ export async function checkRequestOrigin<TEnv = any>(
     defaultCheck: () => defaultOriginCheck(request, url),
   };
 
-  const result = await config(ctx);
+  const result = await check(ctx);
 
   if (result instanceof Response) return result;
-  if (result === true) return null;
-  return createForbiddenResponse(request);
+  return result === true ? null : createForbiddenResponse(request);
 }

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 });
@@ -254,11 +262,11 @@ export async function handleProgressiveEnhancement<TEnv>(
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
         version: ctx.version,
+        stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
         warmupEnabled: ctx.router.warmupEnabled,
         initialTheme: requireRequestContext().theme,
       },
-      formState: actionResult,
     };
 
     const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
@@ -276,6 +284,8 @@ export async function handleProgressiveEnhancement<TEnv>(
       url,
       undefined,
     );
+    // reactFormState carries the useActionState payload via the SSR-option path
+    // (renderToReadableStream({ formState })); it does NOT travel on RscPayload.
     const htmlStream = await ssrModule.renderHTML(rscStream, {
       formState: reactFormState,
       nonce,
@@ -362,6 +372,7 @@ async function renderPeErrorBoundary<TEnv>(
       rootLayout: ctx.router.rootLayout,
       handles: handleStore.stream(),
       version: ctx.version,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       initialTheme: requireRequestContext().theme,

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-error.ts

@@ -1,37 +1,104 @@
 /**
- * Response Error Payload Builder
+ * Problem Details (RFC 9457) Builder
  *
- * Builds a ResponseError object from a caught error, controlling
- * what information is exposed based on error type and environment.
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
  */
 
 import { RouterError } from "../errors.js";
-import type { ResponseError } from "../urls.js";
+import type { ProblemDetails } from "../urls.js";
 
 /**
- * Build a ResponseError payload from a caught error.
- * RouterError messages are always exposed (developer-crafted).
+ * HTTP reason phrases for the problem `title` member. Inlined because the
+ * router targets edge/worker runtimes without node's `http.STATUS_CODES`;
+ * covers the full standard 4xx/5xx range, with a generic fallback for any
+ * non-standard status a handler might set.
+ */
+const STATUS_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function statusPhrase(status: number): string {
+  return STATUS_PHRASES[status] ?? "Error";
+}
+
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
  * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
  */
-export function createResponseErrorPayload(
+export function createProblemDetails(
   error: unknown,
+  status: number,
   isDev: boolean,
-): ResponseError {
+): ProblemDetails {
   if (error instanceof RouterError) {
     return {
-      message: error.message,
+      title: statusPhrase(status),
+      status,
+      detail: error.message,
       code: error.code,
-      ...(error.type ? { type: error.type } : {}),
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   if (error instanceof Error) {
     return {
-      message: isDev ? error.message : "Internal Server Error",
+      title: statusPhrase(status),
+      status,
+      detail: isDev ? error.message : "Internal Server Error",
+      code: "INTERNAL",
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   return {
-    message: isDev ? String(error) : "Internal Server Error",
+    title: statusPhrase(status),
+    status,
+    detail: isDev ? String(error) : "Internal Server Error",
+    code: "INTERNAL",
   };
 }

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

@@ -11,7 +11,8 @@ import { requireRequestContext } from "../server/request-context.js";
 import { contextGet } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { traverseBack } from "../router/pattern-matching.js";
-import { createCacheScope } from "../cache/cache-scope.js";
+import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
   createReverseFunction,
@@ -20,7 +21,7 @@ import {
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { EntryData } from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
-import { createResponseErrorPayload } from "./response-error.js";
+import { createProblemDetails } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
   finalizeResponse,
@@ -29,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;
@@ -109,49 +116,31 @@ 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,
       });
-    };
-
-    // JSON response routes: wrap in { data } / { error } envelope
-    if (preview.responseType === "json") {
-      try {
-        const result = await (preview.handler as Function)(responseHandlerCtx);
-        if (result instanceof Response) {
-          return rewrapResponse(result);
-        }
-        return createResponseWithMergedHeaders(
-          JSON.stringify({ data: result }),
-          {
-            status: 200,
-            headers: { "content-type": "application/json;charset=utf-8" },
-          },
-        );
-      } catch (error) {
-        handlerCtx.callOnError(error, "handler", errorCtx);
-        const isDev = process.env.NODE_ENV !== "production";
-        const status = error instanceof RouterError ? error.status : 500;
-        return createResponseWithMergedHeaders(
-          JSON.stringify({
-            error: createResponseErrorPayload(error, isDev),
-          }),
-          {
-            status,
-            headers: { "content-type": "application/json;charset=utf-8" },
-          },
-        );
+      // 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;
+    };
 
-    // Non-JSON response routes: catch errors and return plain Response
     try {
       const result = await (preview.handler as Function)(responseHandlerCtx);
 
@@ -159,38 +148,56 @@ export async function handleResponseRoute<TEnv>(
         return rewrapResponse(result);
       }
 
-      // Auto-wrap based on response type tag
-      switch (preview.responseType) {
-        case "text":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/plain;charset=utf-8" },
-          });
-        case "html":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/html;charset=utf-8" },
-          });
-        case "xml":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "application/xml;charset=utf-8" },
-          });
-        case "md":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/markdown;charset=utf-8" },
-          });
-        default:
-          // image, stream, any -- must return Response
-          throw new Error(
-            `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
-          );
+      // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
+      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. 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" },
+        });
+      }
+
+      // Object.hasOwn (not truthiness) so prototype names like "toString" are not
+      // matched; image/stream/any are absent and fall through to the throw.
+      if (Object.hasOwn(RESPONSE_TYPE_MIME, preview.responseType)) {
+        return createResponseWithMergedHeaders(String(result), {
+          status: 200,
+          headers: {
+            "content-type": `${RESPONSE_TYPE_MIME[preview.responseType]};charset=utf-8`,
+          },
+        });
       }
+
+      throw new Error(
+        `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
+      );
     } catch (error) {
       handlerCtx.callOnError(error, "handler", errorCtx);
       const isDev = process.env.NODE_ENV !== "production";
-      const status = error instanceof RouterError ? error.status : 500;
+      const derivedStatus = error instanceof RouterError ? error.status : 500;
+      // Resolve the effective status the same way createResponseWithMergedHeaders
+      // will (ctx.res.status override) so the problem body's status/title match
+      // the actual HTTP status — e.g. when a handler called ctx.setStatus()
+      // before throwing.
+      const status =
+        reqCtx.res.status !== 200 ? reqCtx.res.status : derivedStatus;
+
+      if (preview.responseType === "json") {
+        return createResponseWithMergedHeaders(
+          JSON.stringify(createProblemDetails(error, status, isDev)),
+          {
+            status,
+            headers: {
+              "content-type": "application/problem+json;charset=utf-8",
+            },
+          },
+        );
+      }
+
       const message =
         error instanceof RouterError
           ? error.message
@@ -275,6 +282,11 @@ export async function handleResponseRoute<TEnv>(
           }
         }
 
+        // Resolve cache tags for this document entry (static or dynamic),
+        // while request context is available. Passed to putResponse so the
+        // entry is tag-invalidatable.
+        const responseTags = resolveCacheTags(cacheScope.config, reqCtx);
+
         // Save pre-handler callbacks (registered by app-level middleware
         // before we reach the cache block) and clear the live array.
         // createResponseWithMergedHeaders (inside the handler) eagerly
@@ -316,6 +328,7 @@ export async function handleResponseRoute<TEnv>(
                     fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
+                    responseTags,
                   );
                 }
               } catch (error) {
@@ -344,6 +357,7 @@ export async function handleResponseRoute<TEnv>(
                 response.clone(),
                 cacheScope!.ttl,
                 cacheScope!.swr,
+                responseTags,
               );
             } catch (error) {
               console.error(`[ResponseCache] Cache write failed:`, error);