@reckona/mreact-router 0.0.201 → 0.0.203

package/src/build.ts

@@ -46,6 +46,7 @@ import {
   buildNavigationRuntimeBundle,
   clientScriptForPath,
   routeIdForPath,
+  routeMarkerParts,
   type BuildClientRouteOutputOptions,
 } from "./navigation-runtime.js";
 import {
@@ -70,7 +71,12 @@ import {
 import type { ModuleMetadata } from "@reckona/mreact-compiler";
 import type { RouteCachePolicy } from "./cache.js";
 import { routeCachePolicyFromSource } from "./cache.js";
-import { bundleMiddlewareModuleCode, renderAppRequest } from "./render.js";
+import {
+  bundleMiddlewareModuleCode,
+  prerenderVariantMarkerParts,
+  renderAppRequest,
+  type RenderAppRequestRuntimeOptions,
+} from "./render.js";
 import { createAppRouterImportPolicyPlugin, type AppRouterImportPolicy } from "./import-policy.js";
 import {
   hasGenerateStaticParamsExport,
@@ -78,6 +84,7 @@ import {
   hasPrerenderExport,
   isStreamRouteSource,
   routeClosureMayUseAwaitBoundary,
+  routeClosureMayUseRequestInput,
   stripRouteBuildExports,
   stripRouteClientOnlyExports,
   stripRouteClientSource,
@@ -97,6 +104,11 @@ import { collectRouteCssFilesFromSources, collectSpecialBoundaryFiles } from "./
 import { existingRouteShellCandidates } from "./route-shells.js";
 import { sourceModuleCandidates } from "./source-modules.js";
 import { collectBuildInferredServerActions } from "./server-action-inference.js";
+import {
+  isVisitorDependentResponse,
+  PRERENDERED_ROUTE_SCHEMA_VERSION,
+  storedPrerenderedRouteHeaders,
+} from "./prerender-entry.js";
 import { prepareRouteServerActionPlaceholders } from "./actions.js";
 import { viteDefineCacheKey, vitePluginsCacheKey } from "./vite-plugin-cache-key.js";
 import { workspacePackageFile } from "./workspace-packages.js";
@@ -368,6 +380,7 @@ export interface BuiltRouteSourceAnalysisSummary {
   routePath: string;
   sourceHash: string;
   streamRoute: boolean;
+  usesRequestInput?: boolean | undefined;
   usesRuntimeCacheControl: boolean;
 }
 
@@ -393,6 +406,7 @@ interface BuildRouteSourceAnalysis extends BuildSourceAnalysis {
   route: AppRoute & { kind: "page" };
   routeCode: string;
   streamRoute: boolean;
+  usesRequestInput: boolean;
 }
 
 interface BuildSourceAnalysisScope {
@@ -412,7 +426,11 @@ export interface BuiltServerModuleOutput {
 export interface BuiltPrerenderedRoute {
   headers: Record<string, string>;
   html: string;
+  navigationHtml?: string | undefined;
+  /** Identifies entries that satisfy the complete current prerender contract. */
+  schemaVersion?: 4 | undefined;
   status: number;
+  strictTransportSecurity?: string | undefined;
 }
 
 type StaticParams = Record<string, string | number | boolean | readonly string[]>;
@@ -1384,6 +1402,14 @@ async function analyzeBuildRouteSources(options: {
             projectRoot: options.projectRoot,
             source,
           }),
+          usesRequestInput: await buildRouteUsesRequestInput({
+            file,
+            files: options.files,
+            project: options.project,
+            projectRoot: options.projectRoot,
+            routeFile: route.file,
+            source,
+          }),
         },
       ] as const;
     },
@@ -1411,6 +1437,39 @@ async function analyzeBuildRouteSources(options: {
   };
 }
 
+async function buildRouteUsesRequestInput(options: {
+  file: string;
+  files: Record<string, string>;
+  project: ResolvedAppRouterProject;
+  projectRoot: string;
+  routeFile: string;
+  source: string;
+}): Promise<boolean> {
+  const shells = await existingRouteShellCandidates(
+    options.project.routesDir,
+    options.routeFile,
+    async (shellFile) =>
+      options.files[relative(options.projectRoot, shellFile).split(sep).join("/")] !== undefined,
+  );
+  const sources = [
+    { file: options.file, source: options.source },
+    ...shells.flatMap((shell) => {
+      const file = relative(options.projectRoot, shell.file).split(sep).join("/");
+      const source = options.files[file];
+      return source === undefined ? [] : [{ file, source }];
+    }),
+  ];
+
+  return sources.some((entry) =>
+    routeClosureMayUseRequestInput({
+      filename: entry.file,
+      files: options.files,
+      projectRoot: options.projectRoot,
+      source: entry.source,
+    })
+  );
+}
+
 function analyzeBuildSource(source: string, filename: string): BuildSourceAnalysis {
   const cachePolicy = routeCachePolicyFromSource(source);
   const sourceHash = hashText(source);
@@ -2564,7 +2623,11 @@ async function prerenderStaticRoutes(options: {
 
       const entries: Array<[string, BuiltPrerenderedRoute]> = [];
       for (const pathname of await prerenderPathsForRoute(route, analysis, options.vitePlugins)) {
-        const response = await renderAppRequest({
+        const renderSignals = {
+          headerDependent: () => true,
+          strictTransportSecurity: () => undefined as string | undefined,
+        };
+        const renderOptions = {
           appDir: options.appDir,
           assetBaseUrl: options.assetBaseUrl,
           clientScripts,
@@ -2572,22 +2635,52 @@ async function prerenderStaticRoutes(options: {
           define: options.define,
           importPolicy,
           navigationScripts,
-          request: new Request(`http://mreact.local${pathname}`),
+          request: new Request(
+            `http://mreact.local${pathname}`,
+            analysis.clientRoute
+              ? undefined
+              : { headers: { "x-mreact-prerender-variant-capture": "1" } },
+          ),
+          renderSignals,
           serverModuleCacheVersion,
           serverModules: serverModuleMap,
           vitePlugins: options.vitePlugins,
-        });
-        const headers: Record<string, string> = {};
+        } satisfies RenderAppRequestRuntimeOptions;
+        const response = await renderAppRequest(renderOptions);
+        const renderedHtml = await response.text();
 
-        response.headers.forEach((value, key) => {
-          headers[key] = value;
-        });
+        if (renderSignals.headerDependent() || isVisitorDependentResponse(response)) {
+          continue;
+        }
+
+        let html = renderedHtml;
+        let navigationHtml = renderedHtml;
+        if (!analysis.clientRoute) {
+          const capture = prerenderVariantMarkerParts(route.path);
+          const start = renderedHtml.indexOf(capture.prefix);
+          const end = renderedHtml.lastIndexOf(capture.suffix);
+          if (start === -1 || end < start + capture.prefix.length) {
+            throw new Error(`Failed to capture prerender response variants for ${pathname}.`);
+          }
+          const before = renderedHtml.slice(0, start);
+          const content = renderedHtml.slice(start + capture.prefix.length, end);
+          const after = renderedHtml.slice(end + capture.suffix.length);
+          const navigationMarker = routeMarkerParts(route.path);
+          html = `${before}${content}${after}`;
+          navigationHtml = `${before}${navigationMarker.prefix}${content}${navigationMarker.suffix}${after}`;
+        }
+
+        const headers = storedPrerenderedRouteHeaders(response.headers);
+        const strictTransportSecurity = renderSignals.strictTransportSecurity();
         entries.push([
           pathname,
           {
             headers,
-            html: await response.text(),
+            html,
+            navigationHtml,
+            schemaVersion: PRERENDERED_ROUTE_SCHEMA_VERSION,
             status: response.status,
+            ...(strictTransportSecurity === undefined ? {} : { strictTransportSecurity }),
           },
         ]);
       }
@@ -3141,6 +3234,7 @@ function builtRouteSourceAnalysisSummary(options: {
     routePath: options.analysis.route.path,
     sourceHash: options.analysis.sourceHash,
     streamRoute: options.analysis.streamRoute,
+    usesRequestInput: options.analysis.usesRequestInput,
     usesRuntimeCacheControl: options.analysis.usesRuntimeCacheControl,
   };
 }
@@ -3887,6 +3981,7 @@ function cloudflarePageRouteFacadeModuleSource(componentImport: string): string
 const componentSlots = readComponentModuleExport(componentModule, "slots");
 const componentGenerateMetadata = readComponentModuleExport(componentModule, "generateMetadata");
 const componentMetadata = readComponentModuleExport(componentModule, "metadata");
+const componentSecurityHeadersApplied = readComponentModuleExport(componentModule, "__mreactSecurityHeadersApplied");
 
 export function App(props) {
   return renderCloudflareRouteComponent(props);
@@ -3901,6 +3996,7 @@ export const slots = componentSlots === undefined ? undefined : { ...componentSl
 export const generateMetadata =
   typeof componentGenerateMetadata === "function" ? componentGenerateMetadata : undefined;
 export const metadata = componentMetadata;
+export const __mreactSecurityHeadersApplied = componentSecurityHeadersApplied === true;
 
 function renderCloudflareRouteComponent(props) {
   const routeComponent = resolveCloudflareRouteComponent();
@@ -4647,7 +4743,9 @@ ${cloudflareShellRuntimeSource()}`;
 }
 
 function cloudflareShellRuntimeSource(): string {
-  return `async function renderLayoutShells(shells, props, namedSlots) {
+  return `export const __mreactSecurityHeadersApplied = true;
+
+async function renderLayoutShells(shells, props, namedSlots) {
   const slotContext = { consumedSlots: new Set(), namedSlots };
   const rendered = [];
   for (const shell of shells) {
@@ -4726,7 +4824,7 @@ function cloudflareHydrationMarkerParts(props) {
   const escapedRouteId = escapeHtmlAttribute(routeId);
   const propsJson = escapeScriptJson(JSON.stringify({
     params: props.params,
-    request: { url: props.request.url },
+    request: { url: new URL(props.request.url).pathname },
     data: props.data,
   }));
   const clientReferencesJson = route.clientReferenceManifest === undefined || route.clientReferenceManifest.length === 0
@@ -5149,17 +5247,63 @@ function routeSecurityHeaders(security, request) {
   } else {
     headers["referrer-policy"] = validateHeaderValue(security?.referrerPolicy ?? "strict-origin-when-cross-origin");
   }
+  if (security?.permissionsPolicy === null) {
+    delete headers["permissions-policy"];
+  } else {
+    const permissionsPolicy = serializePermissionsPolicy(security?.permissionsPolicy);
+    if (permissionsPolicy === undefined) {
+      delete headers["permissions-policy"];
+    } else {
+      headers["permissions-policy"] = permissionsPolicy;
+    }
+  }
   if (security?.frameOptions === null) {
     delete headers["x-frame-options"];
   } else if (security?.frameOptions !== undefined) {
     headers["x-frame-options"] = validateHeaderValue(security.frameOptions);
   }
   if (request.url.startsWith("https://") && security?.hsts !== undefined && security.hsts !== false && security.hsts !== null) {
-    headers["strict-transport-security"] = \`max-age=\${Math.trunc(security.hsts.maxAge)}\${security.hsts.includeSubDomains === true ? "; includeSubDomains" : ""}\${security.hsts.preload === true ? "; preload" : ""}\`;
+    headers["strict-transport-security"] = serializeHsts(security.hsts);
   }
   return headers;
 }
 
+function serializeHsts(hsts) {
+  if (hsts === false) {
+    throw new TypeError("Invalid security header value for hsts.");
+  }
+  const maxAge = Math.trunc(hsts.maxAge);
+  if (!Number.isFinite(maxAge) || maxAge < 0) {
+    throw new TypeError("Invalid security header value for hsts.maxAge.");
+  }
+  const parts = [\`max-age=\${maxAge}\`];
+  if (hsts.includeSubDomains === true) {
+    parts.push("includeSubDomains");
+  }
+  if (hsts.preload === true) {
+    parts.push("preload");
+  }
+  return parts.join("; ");
+}
+
+function serializePermissionsPolicy(policy) {
+  if (policy === undefined) {
+    return "camera=(), microphone=(), geolocation=()";
+  }
+  const directives = [];
+  for (const [directive, allowlist] of Object.entries(policy)) {
+    if (allowlist === null || allowlist === undefined) {
+      continue;
+    }
+    validateToken(directive, "permissionsPolicy directive");
+    for (const value of allowlist) {
+      validatePermissionAllowlistValue(value);
+    }
+    directives.push(\`\${directive}=(\${allowlist.join(" ")})\`);
+  }
+  return directives.length === 0 ? undefined : directives.join(", ");
+}
+
 function validateHeaderValue(value) {
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);
@@ -5170,6 +5314,22 @@ function validateHeaderValue(value) {
   return value;
 }
 
+function validateToken(value, label) {
+  if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(value)) {
+    throw new TypeError(\`Invalid security header value for \${label}: \${JSON.stringify(value)}\`);
+  }
+}
+
+function validatePermissionAllowlistValue(value) {
+  if (value === "self" || value === "*" || /^[A-Za-z][A-Za-z0-9+.-]*:$/.test(value)) {
+    return;
+  }
+  if (/^https:\\/\\/[A-Za-z0-9.-]+(?::[0-9]+)?$/.test(value)) {
+    return;
+  }
+  throw new TypeError(\`Invalid security header value for permissionsPolicy allowlist: \${JSON.stringify(value)}\`);
+}
+
 function mergeRouteMetadata(metadata) {
   if (metadata.length === 0) {
     return undefined;
@@ -6149,6 +6309,10 @@ async function writeClientRouteBundles(options: {
             options.sourceAnalysis.byRouteFile.get(
               relative(options.projectRoot, route.file).split(sep).join("/"),
             )?.streamRoute === true,
+          restoreRequestUrl:
+            options.sourceAnalysis.byRouteFile.get(
+              relative(options.projectRoot, route.file).split(sep).join("/"),
+            )?.usesRequestInput === true,
           cacheDir: options.cacheDir,
           dropConsoleFunctions: options.clientConsolePureFunctions,
           filename: route.file,

package/src/built-runtime.ts

@@ -25,7 +25,7 @@ export interface BuiltRuntime extends BuiltServerModuleArtifactRuntime {
   projectRoot: string;
   publicAssetBaseUrl?: string | undefined;
   prerenderableRoutes: ReadonlySet<string>;
-  prerenderLocks: Map<string, Promise<Response>>;
+  prerenderLocks: Map<string, Promise<{ response: Response; shareable: boolean }>>;
   prerenderedRoutes: Map<string, BuiltPrerenderedRoute>;
   routeMatcher: RouteMatcher;
   routes: readonly AppRoute[];
@@ -78,7 +78,7 @@ export async function materializeBuiltRuntime(options: {
   }));
   const prerenderedRoutes = new Map(Object.entries(serverManifest.prerenderedRoutes ?? {}));
   const prerenderableRoutes = new Set(prerenderedRoutes.keys());
-  const prerenderLocks = new Map<string, Promise<Response>>();
+  const prerenderLocks = new Map<string, Promise<{ response: Response; shareable: boolean }>>();
   const serverModules = new Map<string, BuiltServerModuleArtifact>(
     Object.entries(serverManifest.serverModules ?? {}).map(([file, artifact]) => [
       join(appDir, file),

package/src/cache.ts

@@ -24,8 +24,31 @@ export interface AppRouterCacheEntry {
   body: string;
   cacheControl: string;
   expiresAt: number;
+  /**
+   * Response headers to replay on a cache hit.
+   *
+   * Metadata-derived security headers such as `content-security-policy`,
+   * `x-frame-options` and `x-content-type-options` live here, so that turning a
+   * route into a cached one does not quietly drop them.
+   */
+  headers?: Record<string, string> | undefined;
   path: string;
+  /**
+   * Identifies entries that preserve the complete current cache contract.
+   *
+   * Missing markers are treated as cache misses so HTML written by older
+   * runtimes, or custom serializers that drop new security fields, is never
+   * replayed under the current security rules.
+   */
+  schemaVersion?: 2 | undefined;
   status: number;
+  /**
+   * Strict-Transport-Security value to replay to secure requests only.
+   *
+   * It is kept out of `headers` because it depends on the scheme of the
+   * request that produced the entry, which the cache key does not cover.
+   */
+  strictTransportSecurity?: string | undefined;
 }
 
 /**
@@ -277,16 +300,29 @@ export function cachedRouteResponse(options: {
     const now = options.now ?? Date.now();
     const cached = await cache.get(options.key, now);
 
-    if (cached === undefined || cached.expiresAt <= now) {
+    if (
+      cached === undefined ||
+      cached.expiresAt <= now ||
+      cached.schemaVersion !== ROUTE_CACHE_ENTRY_SCHEMA_VERSION ||
+      !isStringRecord(cached.headers)
+    ) {
       return undefined;
     }
 
+    const headers = new Headers(cached.headers ?? {});
+    headers.set("cache-control", cached.cacheControl);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "text/html; charset=utf-8");
+    }
+    headers.set("x-mreact-cache", "HIT");
+    // Replayed against the scheme of the request being served, not the one
+    // that produced the entry.
+    if (cached.strictTransportSecurity !== undefined && isSecureRequest(options.request)) {
+      headers.set(HSTS_HEADER, cached.strictTransportSecurity);
+    }
+
     return new Response(cached.body, {
-      headers: {
-        "cache-control": cached.cacheControl,
-        "content-type": "text/html; charset=utf-8",
-        "x-mreact-cache": "HIT",
-      },
+      headers,
       status: cached.status,
     });
   });
@@ -294,18 +330,35 @@ export function cachedRouteResponse(options: {
 
 export async function cacheRouteResponse(options: {
   cache?: AppRouterCache | undefined;
+  headerDependent?: boolean | undefined;
   key: string;
   now?: number;
   path: string;
   policy: RouteCachePolicy | undefined;
   request?: Request | undefined;
   response: Response;
+  /** Configured Strict-Transport-Security value, independent of this request's scheme. */
+  strictTransportSecurity?: string | undefined;
 }): Promise<Response> {
   if (options.policy === undefined) {
     return options.response;
   }
 
   if (options.policy.revalidateSeconds === 0) {
+    // No entry is stored here, but cacheControl({ maxAge }) still emits a bare
+    // max-age that a shared cache may store, so a header dependent render has
+    // to opt out of that too. Directives that already keep the response out of
+    // shared caches are left exactly as the application asked for them.
+    const sharedCacheMayStore = !/(^|,)\s*(private|no-store)\s*(,|$)/.test(
+      options.policy.cacheControl,
+    );
+
+    if (options.headerDependent === true && sharedCacheMayStore) {
+      options.response.headers.set("cache-control", "private, no-store");
+      options.response.headers.set("x-mreact-cache", "DYNAMIC");
+      return options.response;
+    }
+
     options.response.headers.set("cache-control", options.policy.cacheControl);
     return options.response;
   }
@@ -315,7 +368,12 @@ export async function cacheRouteResponse(options: {
   const status = options.response.status;
   const contentType = options.response.headers.get("content-type") ?? "text/html; charset=utf-8";
 
+  // A render that read a request header only produced HTML that is correct for
+  // that header value. The cache key covers the path and query alone, so the
+  // entry cannot be shared; the response is marked uncacheable for downstream
+  // shared caches too, which are keyed the same way.
   if (
+    options.headerDependent === true ||
     requestCarriesCredentials(options.request) ||
     options.response.headers.has("set-cookie")
   ) {
@@ -324,6 +382,9 @@ export async function cacheRouteResponse(options: {
     if (!headers.has("content-type")) {
       headers.set("content-type", contentType);
     }
+    if (options.headerDependent === true) {
+      headers.set("x-mreact-cache", "DYNAMIC");
+    }
 
     return new Response(body, {
       headers,
@@ -331,24 +392,69 @@ export async function cacheRouteResponse(options: {
     });
   }
 
+  // Metadata-derived security headers are part of the rendered response, so
+  // they are stored with it and replayed on a hit rather than dropped by the
+  // rebuilt cache response. Strict-Transport-Security is kept apart because it
+  // is derived from the scheme of whichever request missed and the key does not
+  // cover the scheme: it is replayed only to requests that are themselves
+  // secure, instead of pinning one visitor's scheme onto the entry.
+  const storedHeaders: Record<string, string> = {};
+  options.response.headers.forEach((value, key) => {
+    if (key !== "cache-control" && key !== "x-mreact-cache" && key !== HSTS_HEADER) {
+      storedHeaders[key] = value;
+    }
+  });
+  // Taken from the route's configuration rather than from this response, whose
+  // HSTS header is present only when this particular request was secure. Using
+  // the response would let one plain request pin an entry that withholds HSTS
+  // from every later secure visitor.
+  const hsts = options.strictTransportSecurity;
+
   await (options.cache ?? cacheState.memoryCache).set(options.key, {
     body,
     cacheControl,
     expiresAt: (options.now ?? Date.now()) + options.policy.revalidateSeconds * 1000,
+    headers: storedHeaders,
+    ...(hsts === undefined ? {} : { strictTransportSecurity: hsts }),
     path: normalizeRevalidationPath(options.path),
+    schemaVersion: ROUTE_CACHE_ENTRY_SCHEMA_VERSION,
     status,
   });
 
+  const headers = new Headers(storedHeaders);
+  headers.set("cache-control", cacheControl);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", contentType);
+  }
+  headers.set("x-mreact-cache", "MISS");
+  if (hsts !== undefined && isSecureRequest(options.request)) {
+    headers.set(HSTS_HEADER, hsts);
+  }
+
   return new Response(body, {
-    headers: {
-      "cache-control": cacheControl,
-      "content-type": contentType,
-      "x-mreact-cache": "MISS",
-    },
+    headers,
     status,
   });
 }
 
+const HSTS_HEADER = "strict-transport-security";
+const ROUTE_CACHE_ENTRY_SCHEMA_VERSION = 2;
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function isSecureRequest(request: Request | undefined): boolean {
+  // `Request.url` is always absolute, so this avoids parsing a URL on the
+  // cache-hit hot path.
+  return request?.url.startsWith("https://") === true;
+}
+
 function requestCarriesCredentials(request: Request | undefined): boolean {
   if (request === undefined) {
     return false;
@@ -544,10 +650,16 @@ export function activeRouteCacheContext(): RouteCacheContext | undefined {
 
 // Host is excluded from the cache key to prevent attacker-supplied Host
 // headers from fragmenting / poisoning the cache (Issue 068). The Vary
-// dimension is the request path + query; same-origin reverse proxies are
-// expected to handle vhost separation at their layer.
-export function routeCacheKey(appDir: string, routePath: string, url: URL): string {
-  return `${appDir}\0${normalizeRevalidationPath(routePath)}\0${url.pathname}${url.search}`;
+// dimensions are the request path + query and the document/navigation HTML
+// shape; same-origin reverse proxies are expected to handle vhost separation
+// at their layer.
+export function routeCacheKey(
+  appDir: string,
+  routePath: string,
+  url: URL,
+  responseVariant: "document" | "navigation" = "document",
+): string {
+  return `${appDir}\0${normalizeRevalidationPath(routePath)}\0${url.pathname}${url.search}\0${responseVariant}`;
 }
 
 export function stripRevalidateExport(code: string): string {

package/src/cli-options.ts

@@ -28,6 +28,7 @@ export interface ParsedCliArguments {
   routeArg?: string | undefined;
   skipRuntimeDependencyCheck?: boolean | undefined;
   target?: CliBuildTarget | undefined;
+  trustForwardedProto?: boolean | undefined;
   worker?: string | undefined;
 }
 
@@ -103,6 +104,14 @@ export function parseCliArguments(argv: readonly string[]): ParsedCliArguments {
       continue;
     }
 
+    if (value === "--trust-forwarded-proto") {
+      if (command !== "start") {
+        throw new Error("--trust-forwarded-proto is only supported by the start command");
+      }
+      parsed.trustForwardedProto = true;
+      continue;
+    }
+
     if (value.startsWith("--allowed-hosts=")) {
       parsed.allowedHosts = parseCliAllowedHosts(value.slice("--allowed-hosts=".length));
       continue;
@@ -326,10 +335,13 @@ export function formatCliHelp(command?: string | undefined): string {
       "",
       "Options:",
       "  --host <host>  Bind address. Default: 127.0.0.1. Use 0.0.0.0 inside containers behind explicit port publishing or a reverse proxy.",
+      "  --port <port>  TCP port. Overrides PORT. Default: 3001.",
       "  --host-policy=strict|trusted-proxy",
       "      Control Host header trust for request origin reconstruction.",
       "  --allowed-hosts <host[,host...]>",
       "      Exact Host header allow-list for public deployments.",
+      "  --trust-forwarded-proto",
+      "      Trust the first X-Forwarded-Proto value. Enable only when a trusted proxy overwrites the header and the Node port is not publicly reachable.",
       "  --log=requests  Print request summaries.",
       "  -h, --help      Show this help message.",
       "",
@@ -339,6 +351,8 @@ export function formatCliHelp(command?: string | undefined): string {
       "                  Host header trust policy when --host-policy is not set.",
       "  MREACT_ROUTER_ALLOWED_HOSTS",
       "                  Comma-separated Host header allow-list when --allowed-hosts is not set.",
+      "  MREACT_ROUTER_TRUST_FORWARDED_PROTO",
+      "                  Set to 1 to trust X-Forwarded-Proto when the flag is not set.",
       "  PORT            TCP port. Default: 3001.",
     ].join("\n");
   }
@@ -456,6 +470,18 @@ export function resolveCliDevPort(
   return envValue === undefined || envValue === "" ? viteConfigPort : parseCliPort(envValue);
 }
 
+export function resolveCliStartPort(
+  flagValue: number | undefined,
+  env: { PORT?: string | undefined },
+): number {
+  if (flagValue !== undefined) {
+    return flagValue;
+  }
+
+  const envValue = env.PORT;
+  return envValue === undefined || envValue === "" ? 3001 : parseCliPort(envValue, "PORT");
+}
+
 export function resolveCliHostPolicy(
   flagValue: RequestHostPolicy | undefined,
   env: { MREACT_ROUTER_HOST_POLICY?: string | undefined },
@@ -480,6 +506,17 @@ export function resolveCliAllowedHosts(
   return envValue === undefined || envValue === "" ? undefined : parseCliAllowedHosts(envValue);
 }
 
+export function resolveCliTrustForwardedProto(
+  flagValue: boolean | undefined,
+  env: { MREACT_ROUTER_TRUST_FORWARDED_PROTO?: string | undefined },
+): boolean {
+  if (flagValue !== undefined) {
+    return flagValue;
+  }
+
+  return env.MREACT_ROUTER_TRUST_FORWARDED_PROTO === "1";
+}
+
 export function createCliRequestLogger(): AppRouterLogger {
   return {
     error(event) {
@@ -503,7 +540,7 @@ function parseCliRequestLogMode(value: string): CliRequestLogMode {
   throw new Error(`Unsupported log mode ${JSON.stringify(value)}. Expected "requests".`);
 }
 
-function parseCliPort(value: string): number {
+function parseCliPort(value: string, source = "port"): number {
   const port = Number(value);
 
   if (Number.isInteger(port) && port >= 0 && port <= 65535) {
@@ -511,7 +548,7 @@ function parseCliPort(value: string): number {
   }
 
   throw new Error(
-    `Unsupported port ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`,
+    `Unsupported ${source} ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`,
   );
 }