@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/rsc/loader-fetch.ts

@@ -14,9 +14,20 @@
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
 import { requireRequestContext } from "../server/request-context.js";
-import { createReverseFunction } from "../router/handler-context.js";
-import { getGlobalRouteMap } from "../route-map-builder.js";
-import { createResponseWithMergedHeaders } from "./helpers.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import {
+  getGlobalRouteMap,
+  getSearchSchema,
+  isRouteRootScoped,
+} from "../route-map-builder.js";
+import { parseSearchParams } from "../search-params.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+} from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
 export async function handleLoaderFetch<TEnv>(
@@ -44,6 +55,15 @@ export async function handleLoaderFetch<TEnv>(
     );
   }
 
+  // Non-fetchable loaders are registered for SSR ctx.use() only.
+  // They must not be callable through the standalone _rsc_loader endpoint.
+  if (!registeredLoader.fetchable) {
+    return createResponseWithMergedHeaders(
+      `Loader "${loaderId}" is not fetchable`,
+      { status: 403 },
+    );
+  }
+
   // Parse params, body, and formData based on request method and content type
   let loaderParams: Record<string, string> = {};
   let loaderBody: unknown = undefined;
@@ -90,51 +110,73 @@ export async function handleLoaderFetch<TEnv>(
     }
   }
 
-  // Execute the loader with middleware
+  // Execute the loader with middleware.
+  // finalizeResponse drains onResponse callbacks that middleware short-circuits
+  // may leave behind (executeLoaderMiddleware does not finalize them itself).
   try {
     const { fn, middleware } = registeredLoader;
 
-    return await executeLoaderMiddleware(
-      middleware,
-      request,
-      env,
-      loaderParams,
-      variables,
-      async () => {
-        const reqCtx = requireRequestContext();
-        // Merge route params (from previewMatch) with explicit loader params.
-        // Explicit params take precedence over route-matched params.
-        const mergedParams = {
-          ...(routeParams ?? {}),
-          ...loaderParams,
-        };
-        const loaderCtx: any = {
-          ...reqCtx,
-          params: mergedParams,
-          body: loaderBody,
-          method: request.method,
-          reverse: createReverseFunction(
-            getGlobalRouteMap(),
-            reqCtx._routeName,
-            mergedParams,
-          ),
-          ...(loaderFormData ? { formData: loaderFormData } : {}),
-        };
+    return finalizeResponse(
+      await executeLoaderMiddleware(
+        middleware,
+        request,
+        env,
+        loaderParams,
+        variables,
+        async () => {
+          const reqCtx = requireRequestContext();
+          // Merge route params (from previewMatch) with explicit loader params.
+          // Explicit params take precedence over route-matched params.
+          const resolvedRouteParams = routeParams ?? {};
+          const mergedParams = {
+            ...resolvedRouteParams,
+            ...loaderParams,
+          };
+          // Strip _rsc_* transport params so loaders see the same
+          // url/searchParams as during SSR/navigation.
+          const cleanUrl = stripInternalParams(url);
+          const cleanSearchParams = cleanUrl.searchParams;
+          const searchSchema = reqCtx._routeName
+            ? getSearchSchema(reqCtx._routeName)
+            : undefined;
+          const loaderCtx: any = {
+            ...reqCtx,
+            url: cleanUrl,
+            pathname: cleanUrl.pathname,
+            searchParams: cleanSearchParams,
+            search: searchSchema
+              ? parseSearchParams(cleanSearchParams, searchSchema)
+              : {},
+            params: mergedParams,
+            routeParams: resolvedRouteParams,
+            body: loaderBody,
+            method: request.method,
+            reverse: createReverseFunction(
+              getGlobalRouteMap(),
+              reqCtx._routeName,
+              mergedParams,
+              reqCtx._routeName
+                ? isRouteRootScoped(reqCtx._routeName)
+                : undefined,
+            ),
+            ...(loaderFormData ? { formData: loaderFormData } : {}),
+          };
 
-        const result = await fn(loaderCtx);
+          const result = await fn(loaderCtx);
 
-        interface LoaderPayload {
-          loaderResult: unknown;
-        }
-        const loaderPayload: LoaderPayload = { loaderResult: result };
-        const rscStream =
-          ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          interface LoaderPayload {
+            loaderResult: unknown;
+          }
+          const loaderPayload: LoaderPayload = { loaderResult: result };
+          const rscStream =
+            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
 
-        return createResponseWithMergedHeaders(rscStream, {
-          headers: { "content-type": "text/x-component;charset=utf-8" },
-        });
-      },
-      createReverseFunction(ctx.getRequiredRouteMap()),
+          return createResponseWithMergedHeaders(rscStream, {
+            headers: { "content-type": "text/x-component;charset=utf-8" },
+          });
+        },
+        createReverseFunction(ctx.getRequiredRouteMap()),
+      ),
     );
   } catch (error) {
     const err = error instanceof Error ? error : new Error(String(error));

package/src/rsc/origin-guard.ts

@@ -0,0 +1,141 @@
+/**
+ * Origin Guard
+ *
+ * Cross-origin request protection for server actions, loader fetches, and
+ * progressive enhancement form submissions. Validates that the Origin header
+ * (or Referer fallback) matches the request Host before executing.
+ *
+ * Requests without an Origin or Referer header are allowed — same-origin
+ * navigations, bookmarks, and non-browser clients don't send Origin.
+ */
+
+/**
+ * Request phase that triggered the origin check.
+ */
+export type OriginCheckPhase = "action" | "loader" | "pe-form";
+
+/**
+ * Context passed to the originCheck callback.
+ */
+export interface OriginCheckContext<TEnv = any> {
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routerId: string;
+  phase: OriginCheckPhase;
+  /** Run the built-in conservative check (Origin/Referer vs Host + url.protocol). */
+  defaultCheck: () => boolean;
+}
+
+/**
+ * Configuration for the origin check.
+ *
+ * - `true` (default) — built-in conservative check
+ * - `false` — disabled
+ * - function — custom control; return true to allow, false to reject with
+ *   default 403, or a Response for custom rejection
+ */
+export type OriginCheckConfig<TEnv = any> =
+  | boolean
+  | ((
+      ctx: OriginCheckContext<TEnv>,
+    ) => boolean | Response | Promise<boolean | Response>);
+
+/**
+ * Built-in conservative origin check.
+ * Compares Origin (or Referer fallback) against Host + url.protocol.
+ * Does NOT trust X-Forwarded-Host/Proto headers.
+ *
+ * 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) {
+      try {
+        requestOrigin = new URL(referer).origin;
+      } catch {
+        // Malformed referer — treat as absent
+      }
+    }
+  }
+
+  // 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;
+
+  // 5. Build expected origin and compare (case-insensitive)
+  const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
+
+  return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();
+}
+
+function createForbiddenResponse(request: Request): Response {
+  const isDev = process.env.NODE_ENV !== "production";
+  const body = isDev
+    ? "Forbidden: Origin mismatch. The request origin does not match the server host. " +
+      `Set originCheck: false in createRouter() to disable this check. ` +
+      `(Origin: ${request.headers.get("origin") ?? "none"}, ` +
+      `Host: ${request.headers.get("host") ?? "none"})`
+    : "Forbidden";
+
+  return new Response(body, {
+    status: 403,
+    headers: { "X-Rango-Origin-Check": "failed" },
+  });
+}
+
+/**
+ * Configuration-aware origin check dispatcher.
+ * Builds the OriginCheckContext and delegates to the configured check.
+ */
+export async function checkRequestOrigin<TEnv = any>(
+  request: Request,
+  url: URL,
+  config: OriginCheckConfig<TEnv> | undefined,
+  env: TEnv,
+  routerId: string,
+  phase: OriginCheckPhase,
+): Promise<Response | null> {
+  // 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);
+  }
+
+  // Custom function — build context and call
+  const ctx: OriginCheckContext<TEnv> = {
+    request,
+    url,
+    env,
+    routerId,
+    phase,
+    defaultCheck: () => defaultOriginCheck(request, url),
+  };
+
+  const result = await config(ctx);
+
+  if (result instanceof Response) return result;
+  if (result === true) return null;
+  return createForbiddenResponse(request);
+}

package/src/rsc/progressive-enhancement.ts

@@ -10,9 +10,32 @@ import {
   requireRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import { executeMiddleware } from "../router/middleware.js";
 import type { RscPayload, ReactFormState } from "./types.js";
-import { createResponseWithMergedHeaders } from "./helpers.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+  buildRouteMiddlewareEntries,
+} from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
+import {
+  extractRedirectResponse,
+  warnNonRedirectPeResponse,
+} from "./runtime-warnings.js";
+
+export interface PeRouteMiddlewareInfo {
+  routeMiddleware?: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>;
+  variables: Record<string, any>;
+  routeReverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string;
+}
 
 export async function handleProgressiveEnhancement<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -22,6 +45,7 @@ export async function handleProgressiveEnhancement<TEnv>(
   isAction: boolean,
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
   nonce: string | undefined,
+  routeMwInfo?: PeRouteMiddlewareInfo,
 ): Promise<Response | null> {
   const contentType = request.headers.get("content-type") || "";
   const isFormSubmission =
@@ -32,8 +56,42 @@ export async function handleProgressiveEnhancement<TEnv>(
     return null;
   }
 
-  // Clone the request to read FormData without consuming it
-  const formData = await request.clone().formData();
+  // Clone the request to read FormData without consuming it.
+  // Wrap in try-catch so malformed POST bodies are reported as action
+  // errors, not routing errors from the outer catch in handler.ts.
+  let formData: FormData;
+  try {
+    formData = await request.clone().formData();
+  } catch (error) {
+    // Attempt error boundary rendering so the user sees a meaningful page.
+    const errorHtml = await renderPeErrorBoundary(
+      ctx,
+      request,
+      env,
+      url,
+      error,
+      handleStore,
+      nonce,
+    );
+    if (errorHtml) {
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        handledByBoundary: true,
+      });
+      return errorHtml;
+    }
+
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      handledByBoundary: false,
+    });
+    console.error("[RSC] Progressive enhancement form parse error:", error);
+    return createResponseWithMergedHeaders(null, { status: 400 });
+  }
 
   // Look for React's progressive enhancement hidden fields
   let isDirectAction = false;
@@ -58,14 +116,37 @@ export async function handleProgressiveEnhancement<TEnv>(
   let reactFormState: ReactFormState | null = null;
 
   if (isUseActionState) {
+    // Decode and extract action identity before execution so error
+    // handlers can report actionId even when the action throws.
+    let useActionStateId: string | undefined;
     try {
       const boundAction = await ctx.decodeAction(formData);
+      // React's custom .bind() preserves $$id on server references.
+      useActionStateId = (boundAction as { $$id?: string }).$$id ?? undefined;
       actionResult = await boundAction();
     } catch (error) {
+      // Handle thrown redirect (e.g., throw redirect('/path'))
+      const redirectResponse = extractRedirectResponse(error);
+      if (redirectResponse) return redirectResponse;
+
+      // Attempt error boundary rendering for the PE path
+      const errorHtml = await renderPeErrorBoundary(
+        ctx,
+        request,
+        env,
+        url,
+        error,
+        handleStore,
+        nonce,
+        useActionStateId,
+      );
+      if (errorHtml) return errorHtml;
+
       ctx.callOnError(error, "action", {
         request,
         url,
         env,
+        actionId: useActionStateId,
         handledByBoundary: false,
       });
       console.error("[RSC] Progressive enhancement action error:", error);
@@ -84,6 +165,23 @@ export async function handleProgressiveEnhancement<TEnv>(
       const loadedAction = await ctx.loadServerAction(directActionId);
       actionResult = await loadedAction.apply(null, args);
     } catch (error) {
+      // Handle thrown redirect (e.g., throw redirect('/path'))
+      const redirectResponse = extractRedirectResponse(error);
+      if (redirectResponse) return redirectResponse;
+
+      // Attempt error boundary rendering for the PE path
+      const errorHtml = await renderPeErrorBoundary(
+        ctx,
+        request,
+        env,
+        url,
+        error,
+        handleStore,
+        nonce,
+        directActionId,
+      );
+      if (errorHtml) return errorHtml;
+
       ctx.callOnError(error, "action", {
         request,
         url,
@@ -95,6 +193,20 @@ export async function handleProgressiveEnhancement<TEnv>(
     }
   }
 
+  // Handle Response returned from action during PE.
+  // In the JS path, executeServerAction intercepts redirect Responses and
+  // short-circuits. The PE path must handle them too.
+  if (actionResult instanceof Response) {
+    const redirectResponse = extractRedirectResponse(actionResult);
+    if (redirectResponse) return redirectResponse;
+    // W3: Non-redirect Response — discard it so it doesn't flow into
+    // decodeFormState or the re-render payload.
+    if (process.env.NODE_ENV !== "production") {
+      warnNonRedirectPeResponse();
+    }
+    actionResult = undefined;
+  }
+
   // Decode form state for useActionState progressive enhancement
   try {
     reactFormState = await ctx.decodeFormState(actionResult, formData);
@@ -108,28 +220,126 @@ export async function handleProgressiveEnhancement<TEnv>(
     console.error("[RSC] Failed to decode form state:", error);
   }
 
-  // Re-render the page and return HTML
-  const renderRequest = new Request(url.toString(), {
-    method: "GET",
-    headers: new Headers({ accept: "text/html" }),
-  });
+  // Re-render the page and return HTML.
+  // Route middleware wraps the render so context variables, headers, and
+  // cookies set by route middleware are available during re-render — matching
+  // the behavior of JS-enabled requests.
+  const renderPage = async (): Promise<Response> => {
+    const renderRequest = new Request(url.toString(), {
+      method: "GET",
+      headers: new Headers({ accept: "text/html" }),
+    });
+
+    const match = await ctx.router.match(renderRequest, { env });
+
+    if (match.redirect) {
+      return createResponseWithMergedHeaders(null, {
+        status: 308,
+        headers: { Location: match.redirect },
+      });
+    }
+
+    const payload: RscPayload = {
+      metadata: {
+        pathname: url.pathname,
+        segments: match.segments,
+        matched: match.matched,
+        diff: match.diff,
+        isPartial: false,
+        rootLayout: ctx.router.rootLayout,
+        handles: handleStore.stream(),
+        version: ctx.version,
+        themeConfig: ctx.router.themeConfig,
+        warmupEnabled: ctx.router.warmupEnabled,
+        initialTheme: requireRequestContext().theme,
+      },
+      formState: actionResult,
+    };
+
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    const [ssrModule, streamMode] = await Promise.all([
+      ctx.loadSSRModule(),
+      ctx.resolveStreamMode(request, env, url),
+    ]);
+    const htmlStream = await ssrModule.renderHTML(rscStream, {
+      formState: reactFormState,
+      nonce,
+      streamMode,
+    });
 
-  const match = await ctx.router.match(renderRequest, { env });
+    return createResponseWithMergedHeaders(htmlStream, {
+      headers: { "content-type": "text/html;charset=utf-8" },
+    });
+  };
 
-  if (match.redirect) {
-    return createResponseWithMergedHeaders(null, {
-      status: 308,
-      headers: { Location: match.redirect },
+  // Execute route middleware wrapping the render, if any.
+  // finalizeResponse drains onResponse callbacks that middleware short-circuits
+  // may leave behind (executeMiddleware does not finalize them itself).
+  if (routeMwInfo?.routeMiddleware && routeMwInfo.routeMiddleware.length > 0) {
+    return finalizeResponse(
+      await executeMiddleware(
+        buildRouteMiddlewareEntries(routeMwInfo.routeMiddleware),
+        request,
+        env,
+        routeMwInfo.variables,
+        renderPage,
+        routeMwInfo.routeReverse,
+      ),
+    );
+  }
+
+  return renderPage();
+}
+
+/**
+ * Attempt to render an error boundary as full HTML for the PE path.
+ * Returns null if no error boundary is found (caller falls through to
+ * normal page re-render).
+ */
+async function renderPeErrorBoundary<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  error: unknown,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  nonce: string | undefined,
+  actionId?: string | null,
+): Promise<Response | null> {
+  let errorResult;
+  try {
+    errorResult = await ctx.router.matchError(request, { env }, error, "route");
+  } catch (matchErr) {
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      actionId: actionId ?? undefined,
+      handledByBoundary: false,
     });
+    throw matchErr;
   }
 
+  if (!errorResult) return null;
+
+  ctx.callOnError(error, "action", {
+    request,
+    url,
+    env,
+    actionId: actionId ?? undefined,
+    handledByBoundary: true,
+  });
+
+  setRequestContextParams(errorResult.params, errorResult.routeName);
+
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
-      segments: match.segments,
-      matched: match.matched,
-      diff: match.diff,
+      segments: errorResult.segments,
+      matched: errorResult.matched,
+      diff: errorResult.diff,
       isPartial: false,
+      isError: true,
       rootLayout: ctx.router.rootLayout,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -137,17 +347,20 @@ export async function handleProgressiveEnhancement<TEnv>(
       warmupEnabled: ctx.router.warmupEnabled,
       initialTheme: requireRequestContext().theme,
     },
-    formState: actionResult,
   };
 
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-  const ssrModule = await ctx.loadSSRModule();
+  const [ssrModule, streamMode] = await Promise.all([
+    ctx.loadSSRModule(),
+    ctx.resolveStreamMode(request, env, url),
+  ]);
   const htmlStream = await ssrModule.renderHTML(rscStream, {
-    formState: reactFormState,
     nonce,
+    streamMode,
   });
 
   return createResponseWithMergedHeaders(htmlStream, {
+    status: 500,
     headers: { "content-type": "text/html;charset=utf-8" },
   });
 }