@reckona/mreact-router 0.0.201 → 0.0.203

package/src/request-header-tracking.ts

@@ -0,0 +1,161 @@
+/**
+ * Observes request inputs read by application code during a render.
+ *
+ * The shared route cache is keyed on the app directory, route path, pathname
+ * and query only. A render that reads a request header therefore produces HTML
+ * that is only correct for that header value, and storing it would serve one
+ * visitor's variant to the next: `accept-language` mixes locales, `user-agent`
+ * mixes mobile and desktop shells, and `cf-connecting-ip` or `referer` disclose
+ * one visitor's data to another. Reads are observed rather than inferred from
+ * the source so that headers read through helper modules are covered too.
+ *
+ * Only the request handed to application code is tracked. Router internals keep
+ * using the original request, so their own header reads never mark a route as
+ * header dependent.
+ *
+ * Reconstructing the request with `new Request(request)` copies headers from
+ * internal slots that no interception can reach. Application contexts therefore
+ * mark access when their lazy `request` property is retrieved, before opaque
+ * helpers can reconstruct it. `render.ts` also uses conservative source closure
+ * analysis so a previously stored entry cannot bypass the runtime observation.
+ */
+export interface TrackedHeaderRequest {
+  /** Marks application access to the Request before it can escape tracking. */
+  markRequestAccess(): void;
+  /** Returns true once application code has observed request-specific input. */
+  requestDependent(): boolean;
+  /** The request to hand to loaders, metadata functions and components. */
+  request: Request;
+}
+
+const HEADER_READ_METHODS = new Set<string | symbol>([
+  "entries",
+  "forEach",
+  "get",
+  "getSetCookie",
+  "has",
+  "keys",
+  "values",
+  Symbol.iterator,
+]);
+
+/**
+ * Wraps a request so that header reads performed through it are recorded.
+ *
+ * Falls back to reporting every request as header dependent when the request
+ * cannot be cloned, so an unexpected runtime never silently enables sharing.
+ */
+export function trackRequestHeaderReads(request: Request): TrackedHeaderRequest {
+  let readAny = false;
+
+  let tracked: Request;
+  try {
+    // Cloning a request that carries a body would tee its stream and buffer
+    // whichever half goes unread. Only bodyless requests are worth tracking:
+    // a request with a body is reported as header dependent so that its
+    // response is never shared.
+    if (request.body !== null) {
+      return {
+        markRequestAccess() {},
+        requestDependent: () => true,
+        request,
+      };
+    }
+
+    tracked = request.clone();
+  } catch {
+    return {
+      markRequestAccess() {},
+      requestDependent: () => true,
+      request,
+    };
+  }
+
+  const originalHeaders = tracked.headers;
+  const originalUrl = tracked.url;
+  const headers = new Proxy(originalHeaders, {
+    get(target, property) {
+      const value = Reflect.get(target, property, target);
+
+      if (typeof value !== "function" || !HEADER_READ_METHODS.has(property)) {
+        return value;
+      }
+
+      return (...args: unknown[]): unknown => {
+        readAny = true;
+        return Reflect.apply(value as (...callArgs: unknown[]) => unknown, target, args);
+      };
+    },
+  });
+
+  // Origin/host are not part of the route cache key. Treat any URL observation
+  // as request dependence so a multi-host process cannot replay one tenant's
+  // absolute URLs to another. Path and query reads are conservatively included.
+  Object.defineProperty(tracked, "url", {
+    configurable: true,
+    get: () => {
+      readAny = true;
+      return originalUrl;
+    },
+  });
+
+  // Shadow the prototype getter on a real Request so that `fetch(request)`,
+  // `request.json()` and instanceof checks keep working in every runtime.
+  // Taking a reference counts as a read on its own: a caller that reached for
+  // the headers is assumed to depend on them, which keeps the decision closed
+  // when the reference escapes into code this module cannot observe.
+  Object.defineProperty(tracked, "headers", {
+    configurable: true,
+    get: () => {
+      readAny = true;
+      return headers;
+    },
+  });
+
+  // `clone()` copies headers from internal slots rather than through the
+  // property above, so an unshadowed clone would hand back untracked headers.
+  Object.defineProperty(tracked, "clone", {
+    configurable: true,
+    value: (): Request => {
+      readAny = true;
+      return Request.prototype.clone.call(tracked);
+    },
+    writable: true,
+  });
+
+  return {
+    markRequestAccess: () => {
+      readAny = true;
+    },
+    requestDependent: () => readAny,
+    request: tracked,
+  };
+}
+
+/**
+ * Adds an enumerable Request property that records application access before
+ * opaque code can copy native Request internal slots.
+ */
+export function withTrackedRequest<T extends object>(
+  values: T,
+  request: Request,
+  tracked: TrackedHeaderRequest | undefined,
+): T & { request: Request } {
+  const context = values as T & { request: Request };
+  let currentRequest = request;
+
+  Object.defineProperty(context, "request", {
+    configurable: true,
+    enumerable: true,
+    get() {
+      tracked?.markRequestAccess();
+      return currentRequest;
+    },
+    set(value: Request) {
+      tracked?.markRequestAccess();
+      currentRequest = value;
+    },
+  });
+
+  return context;
+}

package/src/route-source.ts

@@ -1,5 +1,6 @@
 import { dirname, isAbsolute, join } from "node:path";
 import {
+  collectIdentifierReferenceNames,
   collectFormActionExpressionReferences,
   collectTopLevelValueExportNames,
   collectJsxComponentRootNames,
@@ -203,6 +204,76 @@ export function routeClosureMayUseAwaitBoundary(options: {
   }
 }
 
+const REQUEST_INPUT_IDENTIFIERS = new Set(["fetch", "request", "Request"]);
+
+/**
+ * Conservatively detects route closures that may consume Request inputs which
+ * are not represented by the shared route cache key.
+ *
+ * This deliberately over-approximates: a false positive disables shared HTML
+ * reuse, while a false negative can disclose one request's rendered values to
+ * another. Local server imports are traversed so helpers that reconstruct a
+ * Request from its internal slots are covered before cache lookup.
+ */
+export function routeClosureMayUseRequestInput(options: {
+  filename: string;
+  files: RouteSourceLookup;
+  projectRoot: string;
+  seen?: Set<string> | undefined;
+  source: string;
+}): boolean {
+  const seen = options.seen ?? new Set<string>();
+  if (seen.has(options.filename)) {
+    return false;
+  }
+
+  seen.add(options.filename);
+
+  try {
+    if (hasModuleDirective({ code: options.source, directive: "use client" })) {
+      return false;
+    }
+
+    const sourceFilename = sourceFilenameForCompiler(options.projectRoot, options.filename);
+    if (
+      collectIdentifierReferenceNames({
+        code: options.source,
+        filename: sourceFilename,
+      }).some((name) => REQUEST_INPUT_IDENTIFIERS.has(name))
+    ) {
+      return true;
+    }
+
+    for (const reference of collectStaticImportReferences({
+      code: options.source,
+      filename: sourceFilename,
+    })) {
+      const resolved = resolveLocalSourceImport(options.files, options.filename, reference.source);
+
+      if (
+        resolved !== undefined &&
+        routeClosureMayUseRequestInput({
+          filename: resolved.filename,
+          files: options.files,
+          projectRoot: options.projectRoot,
+          seen,
+          source: resolved.source,
+        })
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  } catch {
+    // An analysis parser mismatch must not turn an unknown route into a shared
+    // cache candidate. The normal compiler still reports actual source errors.
+    return true;
+  } finally {
+    seen.delete(options.filename);
+  }
+}
+
 export function hasPrerenderExport(code: string, filename?: string | undefined): boolean {
   return hasTopLevelExportDeclaration({ code, filename, names: ["prerender"] });
 }

package/src/security-headers.ts

@@ -58,6 +58,47 @@ export function routeSecurityHeaders(options: {
   return headers;
 }
 
+/**
+ * Returns the configured Strict-Transport-Security value regardless of scheme.
+ *
+ * `routeSecurityHeaders` only emits the header for secure requests, so callers
+ * that persist a response across requests need the configured value on its own:
+ * the scheme of the request that happened to produce the response must not
+ * decide what later requests receive.
+ *
+ * An invalid value yields `undefined` rather than throwing. This runs on every
+ * render that may be cached, including plain ones that would never emit the
+ * header, and reporting the configuration error is `routeSecurityHeaders`'s
+ * job on the request that actually emits it.
+ */
+export function configuredHstsHeader(
+  security: RouteSecurityHeaders | undefined,
+): string | undefined {
+  if (security?.hsts === undefined || security.hsts === false || security.hsts === null) {
+    return undefined;
+  }
+
+  try {
+    return serializeHsts(security.hsts);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Returns whether HSTS is configured but cannot be serialized safely. */
+export function hasInvalidConfiguredHsts(security: RouteSecurityHeaders | undefined): boolean {
+  if (security?.hsts === undefined || security.hsts === false || security.hsts === null) {
+    return false;
+  }
+
+  try {
+    serializeHsts(security.hsts);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
 function serializeHsts(hsts: NonNullable<RouteSecurityHeaders["hsts"]>): string {
   if (hsts === false) {
     throw new TypeError("Invalid security header value for hsts.");

package/src/serve.ts

@@ -1,4 +1,5 @@
 import type { Server } from "node:http";
+import type { DehydrateOptions } from "@reckona/mreact-query";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { BuiltPrerenderedRoute } from "./build.js";
@@ -57,6 +58,13 @@ import { startNodeRequestServer } from "./node-server.js";
 import { builtAppRuntimePreloadPlan } from "./preload-policy.js";
 import { normalizeRoutePath } from "./route-path.js";
 import type { HttpUpgradeHandler } from "./upgrade.js";
+import {
+  isCurrentPrerenderedRoute,
+  isVisitorDependentResponse,
+  PRERENDERED_ROUTE_SCHEMA_VERSION,
+  replayedPrerenderedRouteHeaders,
+  storedPrerenderedRouteHeaders,
+} from "./prerender-entry.js";
 
 interface BuiltRuntimeCacheEntry {
   clientManifestText: string;
@@ -94,6 +102,7 @@ let warnedImplicitHostTrust = false;
  * Configures rendering a request against a built app-router output directory.
  */
 export interface RenderBuiltAppRequestOptions {
+  dehydrateOptions?: DehydrateOptions | undefined;
   outDir: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   instrumentation?: RouterInstrumentation | undefined;
@@ -151,6 +160,7 @@ export interface BuiltAppRuntimePreloadStrategy {
  * Configures the Node HTTP server used to serve a built app-router output.
  */
 export interface StartServerOptions {
+  dehydrateOptions?: DehydrateOptions | undefined;
   outDir: string;
   port: number;
   hostname?: string;
@@ -176,6 +186,13 @@ export interface StartServerOptions {
   serverActions?: AppRouterServerActionOptions | undefined;
   sinkStrategy?: ResponseSinkStrategy;
   onUpgrade?: HttpUpgradeHandler | undefined;
+  /**
+   * Trusts the first `X-Forwarded-Proto` value when the socket is not TLS.
+   *
+   * Defaults to `false`. Enable only behind a proxy that overwrites the header
+   * and prevents untrusted clients from reaching the Node listener directly.
+   */
+  trustForwardedProto?: boolean | undefined;
 }
 
 export function resolveRequestHost(options: {
@@ -449,7 +466,14 @@ async function renderBuiltAppRequestWithRuntime(
   let normalizedPath = normalizeRoutePath(url.pathname);
   let matched = options.runtime.routeMatcher.match(normalizedPath);
 
-  if (options.request.method === "GET" || options.request.method === "HEAD") {
+  // Prerendered HTML may only be served ahead of middleware when the app has
+  // no middleware at all. Otherwise a middleware that gates access (auth,
+  // geo blocking, maintenance mode) would be bypassed for exactly the routes
+  // it is most often used to protect.
+  if (
+    !options.runtime.hasMiddleware &&
+    (request.method === "GET" || request.method === "HEAD")
+  ) {
     // Sync fast path when no external prerender store is configured (the
     // common case): skip the Promise wrap that `readPrerenderedRoute`
     // would otherwise introduce just to satisfy the async signature.
@@ -461,18 +485,10 @@ async function renderBuiltAppRequestWithRuntime(
             normalizedPath,
             options.prerenderStore,
           );
+    const prerenderedResponse = prerenderedRouteResponse(prerendered, request);
 
-    if (prerendered !== undefined) {
-      if (options.request.method === "HEAD") {
-        return new Response(null, {
-          headers: prerendered.headers,
-          status: prerendered.status,
-        });
-      }
-      return htmlResponse(prerendered.html, {
-        headers: prerendered.headers,
-        status: prerendered.status,
-      });
+    if (prerenderedResponse !== undefined) {
+      return prerenderedResponse;
     }
   }
 
@@ -489,6 +505,29 @@ async function renderBuiltAppRequestWithRuntime(
     matched = options.runtime.routeMatcher.match(normalizedPath);
   }
 
+  // Middleware apps resolve prerendered HTML here instead, so that a
+  // middleware response or rewrite is honoured before the stored HTML is
+  // served. The lookup uses the post-middleware path.
+  if (
+    options.runtime.hasMiddleware &&
+    (request.method === "GET" || request.method === "HEAD")
+  ) {
+    const prerendered =
+      options.prerenderStore === undefined
+        ? options.runtime.prerenderedRoutes.get(normalizedPath)
+        : await readPrerenderedRoute(
+            options.runtime,
+            normalizedPath,
+            options.prerenderStore,
+          );
+    const prerenderedResponse = prerenderedRouteResponse(prerendered, request);
+
+    if (prerenderedResponse !== undefined) {
+      emitBuiltRenderTiming(options, request, timing, prerenderedResponse.status);
+      return prerenderedResponse;
+    }
+  }
+
   if (request.method === "GET" && options.runtime.prerenderableRoutes.has(normalizedPath)) {
     await loadBuiltServerModuleArtifactsForRequest(options.runtime, matched?.route.file, {
       includeRender: false,
@@ -517,6 +556,33 @@ async function renderBuiltAppRequestWithRuntime(
     : response;
 }
 
+function prerenderedRouteResponse(
+  prerendered: BuiltPrerenderedRoute | undefined,
+  request: Request,
+): Response | undefined {
+  if (!isCurrentPrerenderedRoute(prerendered)) {
+    return undefined;
+  }
+
+  const navigation = request.headers.get("x-mreact-navigation") === "1";
+  const html = navigation ? prerendered.navigationHtml : prerendered.html;
+  if (html === undefined) {
+    return undefined;
+  }
+
+  if (request.method === "HEAD") {
+    return new Response(null, {
+      headers: replayedPrerenderedRouteHeaders(prerendered, request),
+      status: prerendered.status,
+    });
+  }
+
+  return htmlResponse(html, {
+    headers: replayedPrerenderedRouteHeaders(prerendered, request),
+    status: prerendered.status,
+  });
+}
+
 async function resolveBuiltMiddleware(
   options: RenderBuiltAppRequestOptions & {
     runtime: BuiltRuntime;
@@ -651,8 +717,10 @@ export async function startServer(
     onUpgrade: options.onUpgrade,
     port: options.port,
     resolveHost: resolveRequestHost,
+    trustForwardedProto: options.trustForwardedProto,
     render: (request) =>
       runtime.render(request, {
+        dehydrateOptions: options.dehydrateOptions,
         instrumentation: options.instrumentation,
         logger: options.logger,
         onResponse: options.onResponse,
@@ -815,13 +883,22 @@ async function readPrerenderedRoute(
   const stored = await store?.get(path);
 
   if (stored !== undefined) {
-    runtime.prerenderedRoutes.set(path, stored);
-    return stored;
+    if (isCurrentPrerenderedRoute(stored)) {
+      runtime.prerenderedRoutes.set(path, stored);
+      return stored;
+    }
+
+    await store?.delete(path);
   }
 
   const manifestEntry = runtime.prerenderedRoutes.get(path);
 
-  if (manifestEntry !== undefined && store !== undefined) {
+  if (!isCurrentPrerenderedRoute(manifestEntry)) {
+    runtime.prerenderedRoutes.delete(path);
+    return undefined;
+  }
+
+  if (store !== undefined) {
     await store.set(path, manifestEntry);
   }
 
@@ -831,11 +908,15 @@ async function readPrerenderedRoute(
 function renderBuiltDynamicResponse(
   options: RenderBuiltAppRequestOptions & {
     matchedRoute?: MatchedRoute | undefined;
+    renderSignals?: { headerDependent: () => boolean } | undefined;
     requestUrl?: URL | undefined;
     runtime: BuiltRuntime;
   },
 ): Promise<Response> {
-  return renderAppRequest(builtRenderAppRequestOptions(options));
+  return renderAppRequest({
+    ...builtRenderAppRequestOptions(options),
+    ...(options.renderSignals === undefined ? {} : { renderSignals: options.renderSignals }),
+  });
 }
 
 function builtRenderAppRequestOptions(
@@ -858,6 +939,7 @@ function builtRenderAppRequestOptions(
     clientScripts: options.runtime.clientScripts,
     clientStylesByFile: options.runtime.clientStylesByFile,
     clientStyles: options.runtime.clientStyles,
+    dehydrateOptions: options.dehydrateOptions,
     importPolicy: {
       ...options.importPolicy,
       allowedSourceDirs: options.runtime.allowedSourceDirs,
@@ -907,51 +989,106 @@ async function renderAndCachePrerenderWithLock(
   options: RenderBuiltAppRequestOptions & { runtime: BuiltRuntime },
   path: string,
 ): Promise<Response> {
-  const existing = options.runtime.prerenderLocks.get(path);
+  const lockKey =
+    options.request.headers.get("x-mreact-navigation") === "1"
+      ? `${path}\0navigation`
+      : path;
+  const existing = options.runtime.prerenderLocks.get(lockKey);
 
   if (existing !== undefined) {
-    return cloneResponse(await existing);
+    const result = await existing;
+    if (result.shareable) {
+      return cloneResponse(result.response);
+    }
+
+    return (await runPrerenderRegeneration(options, path)).response;
   }
 
   const task = runPrerenderRegeneration(options, path);
-  options.runtime.prerenderLocks.set(path, task);
+  options.runtime.prerenderLocks.set(lockKey, task);
 
   try {
-    return cloneResponse(await task);
+    return cloneResponse((await task).response);
   } finally {
-    options.runtime.prerenderLocks.delete(path);
+    options.runtime.prerenderLocks.delete(lockKey);
   }
 }
 
 async function runPrerenderRegeneration(
   options: RenderBuiltAppRequestOptions & { runtime: BuiltRuntime },
   path: string,
-): Promise<Response> {
+): Promise<{ response: Response; shareable: boolean }> {
+  const lockKey =
+    options.request.headers.get("x-mreact-navigation") === "1"
+      ? `${path}\0navigation`
+      : path;
   const regenerate = async () => {
     const stored = await readPrerenderedRoute(options.runtime, path, options.prerenderStore);
+    const storedResponse = prerenderedRouteResponse(stored, options.request);
 
-    if (stored !== undefined) {
-      return htmlResponse(stored.html, {
-        headers: stored.headers,
-        status: stored.status,
-      });
+    if (storedResponse !== undefined) {
+      return {
+        response: storedResponse,
+        shareable: true,
+      };
+    }
+
+    // A prerendered entry is replayed to every visitor by path alone, so a
+    // render that depended on this visitor's request headers must not become
+    // one; it is returned to the caller without being stored. The signal starts
+    // closed so that a render which never reports back is not stored either.
+    const renderSignals = {
+      headerDependent: () => true,
+      strictTransportSecurity: () => undefined as string | undefined,
+    };
+    const response = await renderBuiltDynamicResponse({ ...options, renderSignals });
+
+    if (!response.ok) {
+      return { response, shareable: false };
     }
 
-    const response = await renderBuiltDynamicResponse(options);
+    // Draining the body finishes a streamed render, so the signal is only
+    // final once the whole response has been read.
+    const body = await response.text();
+
+    if (renderSignals.headerDependent() || isVisitorDependentResponse(response)) {
+      return {
+        response: htmlResponse(body, {
+          headers: response.headers,
+          status: response.status,
+        }),
+        shareable: false,
+      };
+    }
 
-    return response.ok
-      ? await cacheRegeneratedPrerenderedRoute(
-          options.runtime,
-          path,
-          response,
-          options.prerenderStore,
-        )
-      : response;
+    const navigation = options.request.headers.get("x-mreact-navigation") === "1";
+    if (navigation && stored === undefined) {
+      return {
+        response: htmlResponse(body, {
+          headers: response.headers,
+          status: response.status,
+        }),
+        shareable: false,
+      };
+    }
+
+    return {
+      response: await cacheRegeneratedPrerenderedRoute(
+        options.runtime,
+        path,
+        body,
+        response,
+        renderSignals.strictTransportSecurity(),
+        options.prerenderStore,
+        navigation ? stored : undefined,
+      ),
+      shareable: true,
+    };
   };
 
   return options.prerenderStore?.withLock === undefined
     ? await regenerate()
-    : await options.prerenderStore.withLock(path, regenerate);
+    : await options.prerenderStore.withLock(lockKey, regenerate);
 }
 
 async function applyBuiltPrerenderInvalidations(
@@ -975,20 +1112,23 @@ async function applyBuiltPrerenderInvalidations(
 async function cacheRegeneratedPrerenderedRoute(
   runtime: BuiltRuntime,
   path: string,
+  body: string,
   response: Response,
+  strictTransportSecurity: string | undefined,
   store: AppRouterPrerenderStore | undefined,
+  existing?: BuiltPrerenderedRoute | undefined,
 ): Promise<Response> {
-  const body = await response.text();
-  const headers: Record<string, string> = {};
-
-  response.headers.forEach((value, key) => {
-    headers[key] = value;
-  });
-  const entry = {
-    headers,
-    html: body,
-    status: response.status,
-  };
+  const headers = storedPrerenderedRouteHeaders(response.headers);
+  const entry: BuiltPrerenderedRoute =
+    existing === undefined
+      ? {
+          headers,
+          html: body,
+          schemaVersion: PRERENDERED_ROUTE_SCHEMA_VERSION,
+          status: response.status,
+          ...(strictTransportSecurity === undefined ? {} : { strictTransportSecurity }),
+        }
+      : { ...existing, navigationHtml: body };
   runtime.prerenderedRoutes.set(path, entry);
   await store?.set(path, entry);