@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/rsc/manifest-init.ts

@@ -0,0 +1,77 @@
+/**
+ * Router Manifest Initialization
+ *
+ * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
+ * where the manifest exists but the trie needs rebuilding.
+ */
+
+import {
+  getGlobalRouteMap,
+  hasCachedManifest,
+  setCachedManifest,
+  getRouteTrie,
+  setRouteTrie,
+  setRouterManifest,
+  setRouterTrie,
+  setRouterPrecomputedEntries,
+} from "../route-map-builder.js";
+
+/**
+ * Build a fresh route trie from router.urlpatterns and store it in the
+ * per-router cache. Also sets the per-router manifest and merges into
+ * the global manifest for reverse()/href().
+ *
+ * Called when manifest data may exist but the per-router trie is missing,
+ * which happens in dev mode after HMR: the virtual module sets the manifest
+ * from fresh gen files but skips the trie (which would be stale from initial
+ * discovery). The trie is essential for correct wildcard priority -- without
+ * it, the regex fallback matches catch-all patterns before specific routes.
+ */
+export async function buildRouterTrieFromUrlpatterns(
+  router: any,
+): Promise<void> {
+  const { generateManifestFull } =
+    await import("../build/generate-manifest.js");
+  const generated = generateManifestFull(
+    router.urlpatterns,
+    undefined,
+    router.basename ? { urlPrefix: router.basename } : undefined,
+  );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
+    setRouterTrie(router.id, trie);
+    // Set global trie only if not already set by another router
+    if (!getRouteTrie()) {
+      setRouteTrie(trie);
+    }
+  }
+  setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
+  // Merge into global manifest (needed for reverse/href across routers)
+  const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
+  setCachedManifest({ ...existing, ...generated.routeManifest });
+}

package/src/rsc/nonce.ts

@@ -2,6 +2,20 @@
  * Nonce generation for Content Security Policy (CSP)
  */
 
+import type { ContextVar } from "../context-var.js";
+import { createVar } from "../context-var.js";
+
+/**
+ * Typed ContextVar token for CSP nonce.
+ *
+ * Use this to access the nonce in middleware or handlers:
+ * ```ts
+ * import { nonce } from "@rangojs/router";
+ * const value = ctx.get(nonce); // string | undefined
+ * ```
+ */
+export const nonce: ContextVar<string> = createVar<string>();
+
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/src/rsc/origin-guard.ts

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+
+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.
+ */
+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 {
+  let requestOrigin = request.headers.get("origin");
+
+  if (!requestOrigin) {
+    const referer = request.headers.get("referer");
+    if (referer) {
+      try {
+        requestOrigin = new URL(referer).origin;
+      } catch {
+        // Malformed referer — treat as absent
+      }
+    }
+  }
+
+  if (!requestOrigin) return true;
+
+  if (requestOrigin === "null") return false;
+
+  // 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();
+}
+
+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 (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;
+
+  const ctx: OriginCheckContext<TEnv> = {
+    request,
+    url,
+    env,
+    routerId,
+    phase,
+    defaultCheck: () => defaultOriginCheck(request, url),
+  };
+
+  const result = await check(ctx);
+
+  if (result instanceof Response) return result;
+  return result === true ? null : createForbiddenResponse(request);
+}

package/src/rsc/progressive-enhancement.ts

@@ -0,0 +1,413 @@
+/**
+ * Progressive Enhancement Handler
+ *
+ * Handles no-JS form submissions. When JavaScript is disabled, React renders
+ * forms with hidden fields ($ACTION_REF_*, $ACTION_KEY) containing the action
+ * reference. We detect these and return HTML instead of RSC stream.
+ */
+
+import {
+  requireRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import { getSSRSetup } from "./ssr-setup.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import { executeMiddleware } from "../router/middleware.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import type { RscPayload, ReactFormState } from "./types.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>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  isAction: boolean,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  nonce: string | undefined,
+  routeMwInfo?: PeRouteMiddlewareInfo,
+): Promise<Response | null> {
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+
+  if (request.method !== "POST" || isAction || !isFormSubmission) {
+    return null;
+  }
+
+  // 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;
+  let isUseActionState = false;
+  let directActionId: string | null = null;
+
+  formData.forEach((_value, key) => {
+    if (key.startsWith("$ACTION_ID_")) {
+      isDirectAction = true;
+      directActionId = key.slice("$ACTION_ID_".length);
+    } else if (key.startsWith("$ACTION_REF_")) {
+      isUseActionState = true;
+    }
+  });
+
+  if (!isDirectAction && !isUseActionState) {
+    return null;
+  }
+
+  // Execute action and return HTML
+  let actionResult: unknown = undefined;
+  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;
+      // Meter the no-JS form action as the action phase, same as the JS path.
+      actionResult = await observePhase(
+        PHASES.action(useActionStateId ?? "useActionState"),
+        () => 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);
+    }
+  } 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 });
+    } catch {
+      args = [formData];
+    }
+
+    try {
+      const loadedAction = await ctx.loadServerAction(directActionId);
+      actionResult = await observePhase(PHASES.action(directActionId), () =>
+        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,
+        env,
+        actionId: directActionId,
+        handledByBoundary: false,
+      });
+      console.error("[RSC] Progressive enhancement action error:", error);
+    }
+  }
+
+  // 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);
+  } catch (error) {
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      handledByBoundary: false,
+    });
+    console.error("[RSC] Failed to decode form state:", error);
+  }
+
+  // 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,
+        routerId: ctx.router.id,
+        basename: ctx.router.basename,
+        segments: match.segments,
+        matched: match.matched,
+        diff: match.diff,
+        resolvedIds: match.resolvedIds,
+        params: match.params,
+        isPartial: false,
+        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,
+      },
+    };
+
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+    // metricsStore=undefined is safe: the handler already stashed the early
+    // SSR setup promise on request variables, so getSSRSetup returns it
+    // without falling back to a fresh startSSRSetup.
+    const [ssrModule, streamMode] = await getSSRSetup(
+      ctx,
+      request,
+      env,
+      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,
+      streamMode,
+    });
+
+    return createResponseWithMergedHeaders(htmlStream, {
+      headers: { "content-type": "text/html;charset=utf-8" },
+    });
+  };
+
+  // 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,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: errorResult.segments,
+      matched: errorResult.matched,
+      diff: errorResult.diff,
+      resolvedIds: errorResult.resolvedIds,
+      params: errorResult.params,
+      isPartial: false,
+      isError: true,
+      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,
+    },
+  };
+
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
+  // metricsStore=undefined is safe: the handler already stashed the early
+  // SSR setup promise on request variables, so getSSRSetup returns it
+  // without falling back to a fresh startSSRSetup.
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    undefined,
+  );
+  const htmlStream = await ssrModule.renderHTML(rscStream, {
+    nonce,
+    streamMode,
+  });
+
+  return createResponseWithMergedHeaders(htmlStream, {
+    status: 500,
+    headers: { "content-type": "text/html;charset=utf-8" },
+  });
+}