@opengeni/api-router 4.1.0 → 4.1.2-canary.36199476632001

package/src/http/local-browser-boundary.ts

@@ -0,0 +1,343 @@
+import {
+  localAllowedOriginEntries,
+  localSandboxApiRouteAllowed,
+  type Settings,
+} from "@opengeni/config";
+
+/**
+ * Browser boundary for the unauthenticated local product mode.
+ *
+ * In `local` access mode every request without credentials acts as the local
+ * `dev` user, and the default local sandbox runs agent commands on the host.
+ * Binding the API to loopback keeps other devices out, but a web page open in
+ * the developer's browser can still reach `http://127.0.0.1:<port>`:
+ *
+ * - any site can send cross-origin requests to it (CORS only hides the
+ *   response; a simple POST still runs), and
+ * - a DNS-rebinding site can make its own hostname resolve to 127.0.0.1 and
+ *   read responses as a same-origin page.
+ *
+ * The boundary therefore sorts the `Host` a request is addressed to into two
+ * classes:
+ *
+ * - Browser hosts: loopback, the hosts of the configured web, public, and
+ *   extra origins, the GitHub App callback tunnel, and a specific API bind
+ *   address. A present `Origin` must be this stack's web app, an explicitly
+ *   configured origin, or the API's own address on one of these hosts.
+ * - Sandbox hosts: names only sandboxes and the worker use to reach the API
+ *   (`host.docker.internal` with the Docker sandbox, and the hosts of
+ *   `OPENGENI_MCP_URL` and `OPENGENI_MCP_INTERNAL_URL`). They serve only the
+ *   sandbox routes (Codemode, first-party MCP, and the Git broker) and refuse
+ *   any request that carries browser metadata. A browser cannot tell a
+ *   sandbox name from an attacker's, so a rebinding page on one of these
+ *   names can neither send an accepted `Origin` nor reach the rest of the API.
+ *
+ * Every other `Host` is refused. Non-browser clients (the SDK, curl, sandbox
+ * callbacks, host-app servers) send no `Origin` and are unaffected. The `Host`
+ * port is not compared: a rebinding page controls only the hostname, while
+ * local proxies and forwarders legitimately present their own port.
+ *
+ * It applies only to `local` access mode in the `local` environment (the
+ * `bun run dev` stack and manual local runs). Managed and configured access
+ * modes, and deployments that set another `OPENGENI_ENVIRONMENT`, keep their
+ * existing CORS policy.
+ */
+export type LocalBrowserBoundarySettings = Pick<
+  Settings,
+  | "productAccessMode"
+  | "environment"
+  | "apiHost"
+  | "webBaseUrl"
+  | "publicBaseUrl"
+  | "opengeniMcpUrl"
+  | "opengeniMcpInternalUrl"
+  | "githubAppManifestBaseUrl"
+  | "localAllowedOrigins"
+  | "sandboxBackend"
+>;
+
+export type LocalBrowserBoundaryRejectionCode =
+  | "LOCAL_HOST_NOT_ALLOWED"
+  | "LOCAL_ORIGIN_NOT_ALLOWED"
+  | "LOCAL_SANDBOX_ROUTE_ONLY";
+
+export type LocalBrowserBoundaryRejection = {
+  status: 403;
+  code: LocalBrowserBoundaryRejectionCode;
+  message: string;
+  /** The refused `Host` or `Origin`, for the API log only; never sent back. */
+  refused: string;
+};
+
+/** Called once per distinct refused value, so an operator can see why. */
+export type LocalBrowserBoundaryWarn = (
+  message: string,
+  attributes: Record<string, string>,
+) => void;
+
+export type LocalBrowserBoundary = {
+  readonly allowedOrigins: ReadonlySet<string>;
+  /** Hostnames a browser may address. */
+  readonly browserHostnames: ReadonlySet<string>;
+  /** Hostnames only sandboxes and the worker use; sandbox routes only, no browsers. */
+  readonly sandboxHostnames: ReadonlySet<string>;
+  /** Whether a present `Origin` may call the API for a request with this `Host`. */
+  originAllowed(origin: string, host: string | null): boolean;
+  /** The rejection for this request, or null when the boundary admits it. */
+  rejection(request: Request): LocalBrowserBoundaryRejection | null;
+};
+
+const LOOPBACK_HOSTNAMES = ["127.0.0.1", "localhost", "[::1]"] as const;
+/** Docker Desktop's name for the host; Linux sandboxes use the configured bridge route. */
+const DOCKER_HOST_ALIAS = "host.docker.internal";
+/** `apps/web` dev server default when no web base URL is configured. */
+const DEFAULT_LOCAL_WEB_ORIGIN = "http://127.0.0.1:3000";
+const WILDCARD_BIND_HOSTS = new Set(["", "0.0.0.0", "::", "[::]"]);
+/**
+ * Only browsers send these. (Node's fetch sends `Sec-Fetch-Mode: cors`, so that
+ * header does not identify a browser.)
+ */
+const BROWSER_REQUEST_HEADERS = ["origin", "sec-fetch-site"];
+/** Distinct refused values logged per boundary, so a rebinding page cannot flood the log. */
+const MAX_REPORTED_REJECTIONS = 32;
+const MAX_REPORTED_VALUE_LENGTH = 200;
+
+const HOST_NOT_ALLOWED_MESSAGE =
+  "The local OpenGeni API only answers requests addressed to this computer. " +
+  "To use another address, set it in OPENGENI_WEB_BASE_URL, OPENGENI_PUBLIC_BASE_URL, " +
+  "or OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+const ORIGIN_NOT_ALLOWED_MESSAGE =
+  "The local OpenGeni API has no authentication, so browser requests are accepted only " +
+  "from this stack's web app. Add other trusted origins to OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+const SANDBOX_ROUTE_ONLY_MESSAGE =
+  "This address is the local OpenGeni API's sandbox route. It serves only sandbox calls " +
+  "(Codemode, first-party MCP, and the Git broker), never browsers. Open the web app at " +
+  "its own address, or list this address in OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+
+const WARNINGS: Record<LocalBrowserBoundaryRejectionCode, { message: string; setting: string }> = {
+  LOCAL_HOST_NOT_ALLOWED: {
+    message: "Local API refused a request addressed to a name that is not this computer's",
+    setting: "OPENGENI_WEB_BASE_URL, OPENGENI_PUBLIC_BASE_URL, or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+  LOCAL_ORIGIN_NOT_ALLOWED: {
+    message: "Local API refused a browser request from an origin that is not this stack's web app",
+    setting: "OPENGENI_WEB_BASE_URL or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+  LOCAL_SANDBOX_ROUTE_ONLY: {
+    message: "Local API refused a browser or non-sandbox request on an address only sandboxes use",
+    setting: "OPENGENI_WEB_BASE_URL or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+};
+
+/**
+ * Requests the API builds and dispatches to itself, such as the Codemode SDK
+ * proxy's re-dispatch. They never come from the network, and the request they
+ * were built from already passed the boundary.
+ */
+const internalDispatches = new WeakSet<Request>();
+
+/** Mark a request the API dispatches to itself so the boundary admits it. */
+export function markLocalInternalDispatch(request: Request): Request {
+  internalDispatches.add(request);
+  return request;
+}
+
+export function localBrowserBoundaryApplies(
+  settings: Pick<Settings, "productAccessMode" | "environment">,
+): boolean {
+  return settings.productAccessMode === "local" && settings.environment === "local";
+}
+
+/** Build the boundary, or null when the deployment is not the local dev product. */
+export function createLocalBrowserBoundary(
+  settings: LocalBrowserBoundarySettings,
+  options: { warn?: LocalBrowserBoundaryWarn } = {},
+): LocalBrowserBoundary | null {
+  if (!localBrowserBoundaryApplies(settings)) return null;
+
+  const webOrigins = [settings.webBaseUrl ?? DEFAULT_LOCAL_WEB_ORIGIN, settings.publicBaseUrl]
+    .map((value) => parseHttpUrl(value))
+    .filter((url): url is URL => url !== null);
+  const extraOrigins = localAllowedOriginEntries(settings.localAllowedOrigins).map(
+    (origin) => new URL(origin),
+  );
+
+  const allowedOrigins = new Set<string>();
+  for (const url of [...webOrigins, ...extraOrigins]) {
+    allowedOrigins.add(url.origin);
+    // 127.0.0.1, localhost, and [::1] are the same machine and port; the
+    // developer may open the printed URL under any of those names.
+    if (isLoopbackHostname(url.hostname)) {
+      for (const hostname of LOOPBACK_HOSTNAMES) {
+        const alias = new URL(url.origin);
+        alias.hostname = hostname;
+        allowedOrigins.add(alias.origin);
+      }
+    }
+  }
+
+  const browserHostnames = new Set<string>(LOOPBACK_HOSTNAMES);
+  for (const url of [...webOrigins, ...extraOrigins]) browserHostnames.add(url.hostname);
+  // A tunnel configured for GitHub App callbacks: GitHub redirects the browser there.
+  const githubAppTunnel = parseHttpUrl(settings.githubAppManifestBaseUrl);
+  if (githubAppTunnel) browserHostnames.add(githubAppTunnel.hostname);
+  const apiHost = settings.apiHost.trim().toLowerCase();
+  if (!WILDCARD_BIND_HOSTS.has(apiHost)) {
+    const url = parseHostHeader(
+      apiHost.includes(":") && !apiHost.startsWith("[") ? `[${apiHost}]` : apiHost,
+    );
+    if (url) browserHostnames.add(url.hostname);
+  }
+
+  // The sandbox-visible API route (Docker Desktop's host alias, the Linux
+  // Docker bridge address, or a tunnel for a remote sandbox) and the worker's
+  // internal route arrive with their own Host.
+  const sandboxHostnames = new Set<string>();
+  if (settings.sandboxBackend === "docker") sandboxHostnames.add(DOCKER_HOST_ALIAS);
+  for (const value of [settings.opengeniMcpUrl, settings.opengeniMcpInternalUrl]) {
+    const url = parseHttpUrl(value?.replaceAll("{workspaceId}", "workspace"));
+    if (url) sandboxHostnames.add(url.hostname);
+  }
+  // A name the developer also uses in the browser stays a browser host.
+  for (const hostname of browserHostnames) sandboxHostnames.delete(hostname);
+
+  const browserHost = (host: string | null): URL | null => {
+    const url = host === null ? null : parseHostHeader(host);
+    return url !== null && browserHostnames.has(url.hostname) ? url : null;
+  };
+
+  const originAllowed = (origin: string, host: string | null): boolean => {
+    const url = parseHttpUrl(origin);
+    if (!url || url.origin !== origin.toLowerCase().replace(/\/$/u, "")) return false;
+    if (allowedOrigins.has(url.origin)) return true;
+    // Pages served by the API itself (for example the MCP OAuth consent form)
+    // and same-origin dev proxies present the API's own address. Only a
+    // browser host qualifies: sandbox names and unknown names never do.
+    const requestHost = browserHost(host);
+    return requestHost !== null && requestHost.host === url.host;
+  };
+
+  const reported = new Set<string>();
+  const report = (rejection: LocalBrowserBoundaryRejection, host: string | null) => {
+    if (!options.warn) return;
+    const key = `${rejection.code}\u0000${rejection.refused}`;
+    if (reported.has(key) || reported.size >= MAX_REPORTED_REJECTIONS) return;
+    reported.add(key);
+    const warning = WARNINGS[rejection.code];
+    options.warn(warning.message, {
+      code: rejection.code,
+      refused: rejection.refused.slice(0, MAX_REPORTED_VALUE_LENGTH),
+      host: (host ?? "").slice(0, MAX_REPORTED_VALUE_LENGTH),
+      setting: warning.setting,
+    });
+  };
+
+  const refuse = (
+    code: LocalBrowserBoundaryRejectionCode,
+    refused: string,
+    host: string | null,
+  ): LocalBrowserBoundaryRejection => {
+    const message =
+      code === "LOCAL_HOST_NOT_ALLOWED"
+        ? HOST_NOT_ALLOWED_MESSAGE
+        : code === "LOCAL_ORIGIN_NOT_ALLOWED"
+          ? ORIGIN_NOT_ALLOWED_MESSAGE
+          : SANDBOX_ROUTE_ONLY_MESSAGE;
+    const rejection: LocalBrowserBoundaryRejection = { status: 403, code, message, refused };
+    report(rejection, host);
+    return rejection;
+  };
+
+  return {
+    allowedOrigins,
+    browserHostnames,
+    sandboxHostnames,
+    originAllowed,
+    rejection(request) {
+      if (internalDispatches.has(request)) return null;
+      const host = localBrowserRequestHost(request);
+      const origin = request.headers.get("origin");
+      if (browserHost(host)) {
+        if (origin !== null && !originAllowed(origin, host)) {
+          return refuse("LOCAL_ORIGIN_NOT_ALLOWED", origin, host);
+        }
+        return null;
+      }
+      const parsedHost = host === null ? null : parseHostHeader(host);
+      if (parsedHost === null || !sandboxHostnames.has(parsedHost.hostname)) {
+        return refuse("LOCAL_HOST_NOT_ALLOWED", host ?? "", host);
+      }
+      if (
+        BROWSER_REQUEST_HEADERS.some((name) => request.headers.has(name)) ||
+        !localSandboxApiRouteAllowed(requestPathname(request))
+      ) {
+        return refuse("LOCAL_SANDBOX_ROUTE_ONLY", host ?? "", host);
+      }
+      return null;
+    },
+  };
+}
+
+/** The standard API error envelope for a boundary rejection outside Hono. */
+export function localBrowserBoundaryResponse(rejection: LocalBrowserBoundaryRejection): Response {
+  return Response.json(
+    {
+      error: {
+        status: rejection.status,
+        code: "forbidden",
+        message: rejection.message,
+        retryable: false,
+        details: { code: rejection.code },
+      },
+    },
+    { status: rejection.status },
+  );
+}
+
+/** The `Host` the boundary checks: the header, else the request URL's authority. */
+export function localBrowserRequestHost(request: Request): string | null {
+  const header = request.headers.get("host");
+  if (header !== null) return header;
+  try {
+    return new URL(request.url).host || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The normalized path the router sees (URL parsing resolves dot segments). */
+function requestPathname(request: Request): string {
+  try {
+    return new URL(request.url).pathname;
+  } catch {
+    return "";
+  }
+}
+
+function parseHostHeader(value: string): URL | null {
+  const host = value.trim();
+  // A Host is exactly `hostname[:port]`; anything else is not an address.
+  if (!host || /[\s/?#@\\,]/u.test(host)) return null;
+  try {
+    const url = new URL(`http://${host}`);
+    return url.host === host.toLowerCase() || url.host === host.toLowerCase().replace(/:80$/u, "")
+      ? url
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseHttpUrl(value: string | undefined): URL | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (LOOPBACK_HOSTNAMES as readonly string[]).includes(hostname);
+}

package/src/http/metrics-listener.ts

@@ -0,0 +1,57 @@
+import type { Settings } from "@opengeni/config";
+import { Hono } from "hono";
+
+import { requireAccessKey } from "./auth";
+
+type PrometheusSource = { prometheusMetrics(): Promise<string> };
+
+/** Register the Prometheus exposition route on one Hono app. */
+export function registerPrometheusMetricsRoute(app: Hono, observability: PrometheusSource): void {
+  app.get("/metrics", async (c) =>
+    c.text(await observability.prometheusMetrics(), 200, {
+      "content-type": "text/plain; version=0.0.4; charset=utf-8",
+    }),
+  );
+}
+
+/**
+ * Whether the public API listener serves `GET /metrics`. A deployment that sets
+ * `OPENGENI_API_METRICS_PORT` moves the exposition to a dedicated internal
+ * listener, so an ingress that forwards every path to the API cannot publish it.
+ */
+export function publicListenerServesMetrics(settings: Pick<Settings, "apiMetricsPort">): boolean {
+  return settings.apiMetricsPort === undefined;
+}
+
+/**
+ * The dedicated metrics listener: only `GET /metrics`, behind the same
+ * deployment-key perimeter rules as the public listener. Nothing else is
+ * routed here, so exposing this port to a scraper exposes nothing else.
+ */
+export function createMetricsListenerApp(
+  settings: Settings,
+  observability: PrometheusSource,
+): Hono {
+  const app = new Hono();
+  app.use("*", requireAccessKey(settings));
+  registerPrometheusMetricsRoute(app, observability);
+  return app;
+}
+
+/** Start the dedicated listener when configured; returns undefined otherwise. */
+export function startApiMetricsListener(
+  settings: Settings,
+  observability: PrometheusSource,
+): ReturnType<typeof Bun.serve> | undefined {
+  const port = settings.apiMetricsPort;
+  if (port === undefined) return undefined;
+  if (port === settings.apiPort) {
+    throw new Error("OPENGENI_API_METRICS_PORT must differ from OPENGENI_API_PORT");
+  }
+  const app = createMetricsListenerApp(settings, observability);
+  return Bun.serve({
+    hostname: settings.apiHost,
+    port,
+    fetch: (request) => app.fetch(request),
+  });
+}

package/src/http/registered-route-label.ts

@@ -0,0 +1,34 @@
+import type { Context } from "hono";
+import { matchedRoutes } from "hono/route";
+
+/**
+ * The registered Hono path template of the handler that answers this request.
+ *
+ * Hono resolves every route matching a request before the first middleware
+ * runs, so the metrics middleware can read the exact code-owned template (for
+ * example `/v1/workspaces/:workspaceId/rigs/:rigId`) without re-implementing
+ * routing. Templates come only from route registrations, never from request
+ * data, so they are a closed and bounded metric/log label set.
+ *
+ * Middleware (arity two: `(context, next)`) and global catch-alls never name a
+ * route; the first matched terminal handler is the one Hono dispatches to.
+ */
+export function registeredHandlerRoutePath(context: Context): string | null {
+  try {
+    for (const route of matchedRoutes(context)) {
+      if (typeof route.handler !== "function" || route.handler.length >= 2) continue;
+      const label = boundedRegisteredRouteLabel(route.path);
+      if (label) return label;
+    }
+  } catch {
+    // Route labels are observational and must never affect request handling.
+  }
+  return null;
+}
+
+/** Normalize a registered template; drop catch-alls that would name nothing. */
+export function boundedRegisteredRouteLabel(path: string | null | undefined): string | null {
+  if (!path || !path.startsWith("/") || path === "/*") return null;
+  // `:param{regex}` constraints are routing detail, not part of the label.
+  return path.replace(/(:[A-Za-z0-9_]+)\{[^/]*\}/g, "$1");
+}

package/src/http/request-source.ts

@@ -1,11 +1,28 @@
+import { BlockList, isIP } from "node:net";
+import { trustedProxyCidrEntries, type Settings } from "@opengeni/config";
 import type { Context } from "hono";
 
 const TRANSPORT_PEER_ADDRESS_BINDING = "opengeniTransportPeerAddress";
 
+/** Returned when the runtime supplied no transport peer (for example an
+ * in-process test request). Callers treat it as one shared bucket. */
+export const UNKNOWN_REQUEST_SOURCE_ADDRESS = "unknown";
+
+/**
+ * App-owned request header carrying the server-resolved client address into
+ * Better Auth, which reads client addresses only from request headers. It is
+ * removed from every inbound request and re-stamped on managed-auth routes, so
+ * a caller-supplied value never reaches the auth rate limiter or session IP.
+ */
+export const TRUSTED_CLIENT_ADDRESS_HEADER = "x-opengeni-trusted-client-address";
+
 type ApiRequestBindings = {
   [TRANSPORT_PEER_ADDRESS_BINDING]?: string | null;
 };
 
+/** The deployment's declared proxy chain (`OPENGENI_API_TRUSTED_PROXY_*`). */
+export type RequestSourceTrust = Pick<Settings, "apiTrustedProxyHops" | "apiTrustedProxyCidrs">;
+
 export function apiRequestBindingsForTransportPeer(
   address: string | null | undefined,
 ): ApiRequestBindings {
@@ -15,23 +32,147 @@ export function apiRequestBindingsForTransportPeer(
 /**
  * Resolve a quota/audit source from the server-owned transport peer. Forwarded
  * values are considered only when the operator declares an exact trusted proxy
- * hop count; the chain is then walked from the server side so caller-prepended
- * values cannot replace the address inserted by the trusted edge.
+ * hop count (`OPENGENI_API_TRUSTED_PROXY_HOPS`) and, when
+ * `OPENGENI_API_TRUSTED_PROXY_CIDRS` is set, only for a transport peer inside
+ * those ranges. Each trusted proxy must append the address of the peer that
+ * connected to it, or overwrite the header with the original client address;
+ * the chain is then walked from the server side so caller-prepended values
+ * cannot replace the address observed by the trusted edge. A missing, short,
+ * or malformed chain falls back to the transport peer.
  */
-export function trustedRequestSourceAddress(c: Context, trustedProxyHops: number): string {
+export function trustedRequestSourceAddress(c: Context, trust: RequestSourceTrust): string {
   const bindings = c.env as ApiRequestBindings | undefined;
-  const peer = normalizedAddress(bindings?.[TRANSPORT_PEER_ADDRESS_BINDING]) ?? "unknown";
-  if (trustedProxyHops <= 0 || peer === "unknown") return peer;
-
-  const forwarded = (c.req.header("x-forwarded-for") ?? "")
-    .split(",")
-    .map(normalizedAddress)
-    .filter((value): value is string => value !== null);
+  const peer =
+    normalizedAddress(bindings?.[TRANSPORT_PEER_ADDRESS_BINDING]) ?? UNKNOWN_REQUEST_SOURCE_ADDRESS;
+  const trustedProxyHops = trust.apiTrustedProxyHops;
+  if (
+    !Number.isInteger(trustedProxyHops) ||
+    trustedProxyHops <= 0 ||
+    peer === UNKNOWN_REQUEST_SOURCE_ADDRESS ||
+    !peerIsTrustedProxy(peer, trust.apiTrustedProxyCidrs)
+  ) {
+    return peer;
+  }
+  const header = c.req.header("x-forwarded-for");
+  if (!header) return peer;
+  // Entries are never filtered: dropping a malformed value would shift the
+  // server-side position and could promote a caller-prepended value.
+  const forwarded = header.split(",");
   const sourceIndex = forwarded.length - trustedProxyHops;
-  return sourceIndex >= 0 ? forwarded[sourceIndex]! : peer;
+  if (sourceIndex < 0) return peer;
+  return normalizedAddress(forwarded[sourceIndex]) ?? peer;
+}
+
+/**
+ * Rate-limit key for a trusted source address. An IPv6 address keys on its
+ * /64, the block one subscriber normally holds and the granularity Better
+ * Auth applies to the same stamped address, so rotating addresses inside one
+ * /64 cannot mint fresh buckets. An IPv4-mapped IPv6 address (how a
+ * dual-stack listener reports an IPv4 peer) keys on the embedded IPv4 address
+ * instead of collapsing every IPv4 client into one /64. Anything else,
+ * including {@link UNKNOWN_REQUEST_SOURCE_ADDRESS}, is returned unchanged.
+ */
+export function requestSourceRateLimitKey(address: string): string {
+  if (isIP(address) !== 6) return address;
+  const groups = ipv6Groups(address);
+  if (!groups) return address;
+  if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) {
+    const high = groups[6]!;
+    const low = groups[7]!;
+    return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
+  }
+  return `${groups
+    .slice(0, 4)
+    .map((group) => group.toString(16))
+    .join(":")}::/64`;
+}
+
+/** {@link trustedRequestSourceAddress} as an application rate-limit key. */
+export function trustedRequestSourceRateLimitKey(c: Context, trust: RequestSourceTrust): string {
+  return requestSourceRateLimitKey(trustedRequestSourceAddress(c, trust));
 }
 
+/**
+ * Replace any caller-supplied {@link TRUSTED_CLIENT_ADDRESS_HEADER}. When
+ * `stamp` is true the header is set to the trusted source address, so every
+ * Better Auth request derived from this request (direct handler calls,
+ * isolated provider requests, and `auth.api.*` calls built from its headers)
+ * keys rate limits and session records on the real client.
+ */
+export function replaceTrustedClientAddressHeader(
+  c: Context,
+  trust: RequestSourceTrust,
+  stamp: boolean,
+): void {
+  const headers = c.req.raw.headers;
+  headers.delete(TRUSTED_CLIENT_ADDRESS_HEADER);
+  if (!stamp) return;
+  const address = trustedRequestSourceAddress(c, trust);
+  if (address !== UNKNOWN_REQUEST_SOURCE_ADDRESS) {
+    headers.set(TRUSTED_CLIENT_ADDRESS_HEADER, address);
+  }
+}
+
+const trustedProxyRanges = new Map<string, BlockList | null>();
+
+function peerIsTrustedProxy(peer: string, cidrs: string): boolean {
+  let ranges = trustedProxyRanges.get(cidrs);
+  if (ranges === undefined) {
+    // Settings validation already rejected malformed entries at boot.
+    const entries = trustedProxyCidrEntries(cidrs);
+    ranges = entries.length === 0 ? null : new BlockList();
+    for (const entry of entries) ranges?.addSubnet(entry.address, entry.prefix, entry.family);
+    trustedProxyRanges.set(cidrs, ranges);
+  }
+  if (!ranges) return true;
+  return ranges.check(peer, isIP(peer) === 6 ? "ipv6" : "ipv4");
+}
+
+/**
+ * Canonical IP text, or null. Accepts the `ipv4:port` and `[ipv6]:port` forms
+ * some load balancers write into X-Forwarded-For, and drops IPv6 zone ids.
+ */
 function normalizedAddress(value: string | null | undefined): string | null {
-  const normalized = value?.trim();
-  return normalized ? normalized.slice(0, 128) : null;
+  let candidate = value?.trim();
+  if (!candidate || candidate.length > 64) return null;
+  const bracketed = /^\[([^\]]+)\](?::\d{1,5})?$/u.exec(candidate);
+  if (bracketed) {
+    candidate = bracketed[1]!;
+  } else {
+    const ipv4WithPort = /^(\d{1,3}(?:\.\d{1,3}){3}):\d{1,5}$/u.exec(candidate);
+    if (ipv4WithPort) candidate = ipv4WithPort[1]!;
+  }
+  const zone = candidate.indexOf("%");
+  if (zone >= 0) candidate = candidate.slice(0, zone);
+  const family = isIP(candidate);
+  if (family === 4) return candidate;
+  if (family === 6) return candidate.toLowerCase();
+  return null;
+}
+
+/** The eight 16-bit groups of a valid IPv6 address, or null. */
+function ipv6Groups(address: string): number[] | null {
+  let text = address;
+  const tail: number[] = [];
+  const lastColon = text.lastIndexOf(":");
+  const last = text.slice(lastColon + 1);
+  if (last.includes(".")) {
+    const octets = last.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet))) return null;
+    tail.push((octets[0]! << 8) | octets[1]!, (octets[2]! << 8) | octets[3]!);
+    text = text.slice(0, lastColon + 1);
+    if (!text.endsWith("::")) text = text.slice(0, -1);
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const parse = (part: string): number[] =>
+    part ? part.split(":").map((group) => Number.parseInt(group, 16)) : [];
+  const head = parse(halves[0]!);
+  const rest = halves.length === 2 ? parse(halves[1]!) : [];
+  const fill = halves.length === 2 ? 8 - head.length - rest.length - tail.length : 0;
+  if (fill < 0) return null;
+  const groups = [...head, ...Array.from({ length: fill }, () => 0), ...rest, ...tail];
+  if (groups.length !== 8) return null;
+  if (groups.some((group) => !Number.isInteger(group) || group < 0 || group > 0xffff)) return null;
+  return groups;
 }