@opengeni/api-router 0.30.1 → 1.0.0

package/src/http/deprecation.ts

@@ -0,0 +1,118 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { registeredHandlerRoutePath } from "./registered-route-label";
+
+/**
+ * A public `/v1` route whose current behaviour is scheduled for removal.
+ *
+ * See docs/design/api-compatibility-policy.md: a breaking change to the public
+ * surface is announced, advertised on every affected response with the
+ * standard `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers plus a
+ * `Link: rel="deprecation"` to the migration notes, and the old behaviour is
+ * kept for at least 90 days on the managed service or until the next major,
+ * whichever is later. Published SDKs surface these headers to the integrator.
+ */
+export type RouteDeprecation = {
+  /** Upper-case HTTP method. */
+  method: string;
+  /** The exact registered Hono template, e.g. `/v1/workspaces/:workspaceId/packs`. */
+  path: string;
+  /** When the deprecation was announced (ISO 8601). */
+  deprecatedAt: string;
+  /** Earliest removal on the managed service (ISO 8601). */
+  sunset: string;
+  /** Public migration notes (changelog/docs URL). */
+  link: string;
+  /** Optional successor route or document. */
+  successor?: string;
+};
+
+/**
+ * Every currently deprecated public route. Adding an entry here is the
+ * server-side half of a deprecation; the breaking change itself still needs an
+ * entry in scripts/public-api-breaking-changes.json and a new major.
+ */
+export const DEPRECATED_ROUTES: readonly RouteDeprecation[] = [];
+
+const MINIMUM_NOTICE_MS = 90 * 24 * 60 * 60 * 1000;
+
+function isoMillis(value: string, field: string, deprecation: RouteDeprecation): number {
+  const millis = Date.parse(value);
+  if (Number.isNaN(millis)) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: ${field} is not an ISO date`,
+    );
+  }
+  return millis;
+}
+
+/** Validate one registry entry; the policy's 90-day minimum is enforced here. */
+export function assertValidRouteDeprecation(deprecation: RouteDeprecation): void {
+  if (!/^(GET|POST|PUT|PATCH|DELETE)$/.test(deprecation.method)) {
+    throw new Error(`deprecation method must be an upper-case HTTP verb: ${deprecation.method}`);
+  }
+  if (!deprecation.path.startsWith("/v1/")) {
+    throw new Error(`deprecation path must be a /v1 route template: ${deprecation.path}`);
+  }
+  const deprecatedAt = isoMillis(deprecation.deprecatedAt, "deprecatedAt", deprecation);
+  const sunset = isoMillis(deprecation.sunset, "sunset", deprecation);
+  if (sunset - deprecatedAt < MINIMUM_NOTICE_MS) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: sunset must be at least 90 days after deprecatedAt`,
+    );
+  }
+  if (!/^https:\/\//.test(deprecation.link)) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: link must be an https URL`,
+    );
+  }
+}
+
+/** The response headers that advertise one deprecation. */
+export function deprecationHeaders(deprecation: RouteDeprecation): Record<string, string> {
+  const deprecatedAt = Math.floor(Date.parse(deprecation.deprecatedAt) / 1000);
+  const links = [`<${deprecation.link}>; rel="deprecation"; type="text/html"`];
+  if (deprecation.successor) links.push(`<${deprecation.successor}>; rel="successor-version"`);
+  return {
+    // RFC 9745: a structured-field date, `@<unix seconds>`.
+    Deprecation: `@${deprecatedAt}`,
+    // RFC 8594: an HTTP-date.
+    Sunset: new Date(deprecation.sunset).toUTCString(),
+    Link: links.join(", "),
+  };
+}
+
+function appendHeader(context: Context, name: string, value: string): void {
+  const existing = context.res.headers.get(name);
+  context.res.headers.set(name, existing ? `${existing}, ${value}` : value);
+}
+
+/**
+ * Stamp deprecation headers on every response from a registered deprecated
+ * route, including error responses, so an integrator sees the notice whatever
+ * the call's outcome. Matching uses the registered route template, never
+ * request data.
+ */
+export function deprecationHeadersMiddleware(
+  registry: readonly RouteDeprecation[] = DEPRECATED_ROUTES,
+): MiddlewareHandler {
+  for (const deprecation of registry) assertValidRouteDeprecation(deprecation);
+  const byRoute = new Map(registry.map((entry) => [`${entry.method} ${entry.path}`, entry]));
+  return async (context, next) => {
+    await next();
+    if (byRoute.size === 0) return;
+    const path = registeredHandlerRoutePath(context);
+    if (!path) return;
+    const deprecation = byRoute.get(`${context.req.method} ${path}`);
+    if (!deprecation) return;
+    const headers = deprecationHeaders(deprecation);
+    try {
+      context.res.headers.set("Deprecation", headers.Deprecation!);
+    } catch {
+      // Immutable headers (a proxied or redirect response): copy once.
+      context.res = new Response(context.res.body, context.res);
+      context.res.headers.set("Deprecation", headers.Deprecation!);
+    }
+    context.res.headers.set("Sunset", headers.Sunset!);
+    appendHeader(context, "Link", headers.Link!);
+  };
+}

package/src/http/interaction-control-error.ts

@@ -0,0 +1,164 @@
+import { ErrorCode as AgentErrorCode } from "@opengeni/agent-proto";
+import {
+  InteractionControlFailureDetails,
+  type ErrorCode,
+  type InteractionControlFailureCode,
+} from "@opengeni/contracts";
+import { SelfhostedControlError } from "@opengeni/runtime/sandbox";
+import { HTTPException } from "hono/http-exception";
+import { ApiHttpError } from "./api-error";
+
+export type InteractionControlSurface = "browser" | "computer";
+
+/**
+ * Projects an internal connected-machine control fault into the public API
+ * vocabulary. This is deliberately an allowlist: the agent's free-form message
+ * and detail map may contain paths, process output, or provider diagnostics and
+ * never cross this boundary. The exact inner request id is safe opaque
+ * correlation and links API logs back to the machine operation.
+ */
+export function interactionControlApiError(
+  error: unknown,
+  surface: InteractionControlSurface,
+): ApiHttpError | null {
+  const controlError =
+    error instanceof SelfhostedControlError
+      ? error
+      : error instanceof HTTPException && error.cause instanceof SelfhostedControlError
+        ? error.cause
+        : null;
+  if (!controlError) return null;
+  const controlFailureCode = publicControlFailureCode(controlError.code);
+  const details = InteractionControlFailureDetails.parse({
+    interactionLayer: "connected_machine",
+    interactionSurface: surface,
+    controlFailureCode,
+    ...(safeControlRequestId(controlError.controlRequestId)
+      ? { controlRequestId: controlError.controlRequestId }
+      : {}),
+  });
+  const ruling = publicControlFailureRuling(controlError, surface, controlFailureCode);
+  return new ApiHttpError(ruling.status, {
+    code: ruling.code,
+    message: ruling.message,
+    retryable: controlError.retryable,
+    outcomeUnknown:
+      controlError.code === AgentErrorCode.ERROR_CODE_TIMEOUT && !controlError.neverSent,
+    details,
+  });
+}
+
+export function publicControlFailureCode(code: AgentErrorCode): InteractionControlFailureCode {
+  switch (code) {
+    case AgentErrorCode.ERROR_CODE_UNSUPPORTED:
+      return "unsupported";
+    case AgentErrorCode.ERROR_CODE_OS:
+      return "os";
+    case AgentErrorCode.ERROR_CODE_NOT_FOUND:
+      return "not_found";
+    case AgentErrorCode.ERROR_CODE_CONSENT_REQUIRED:
+      return "consent_required";
+    case AgentErrorCode.ERROR_CODE_TIMEOUT:
+      return "timeout";
+    case AgentErrorCode.ERROR_CODE_DRAINING:
+      return "draining";
+    case AgentErrorCode.ERROR_CODE_PROTOCOL:
+      return "protocol";
+    case AgentErrorCode.ERROR_CODE_STREAM:
+      return "stream";
+    case AgentErrorCode.ERROR_CODE_AGENT_OFFLINE:
+      return "agent_offline";
+    case AgentErrorCode.ERROR_CODE_FENCED:
+      return "fenced";
+    case AgentErrorCode.ERROR_CODE_PAYLOAD_TOO_LARGE:
+      return "payload_too_large";
+    default:
+      return "unknown";
+  }
+}
+
+function publicControlFailureRuling(
+  error: SelfhostedControlError,
+  surface: InteractionControlSurface,
+  code: InteractionControlFailureCode,
+): { status: number; code: ErrorCode; message: string } {
+  const liveView = surface === "browser" ? "browser live view" : "computer live view";
+  switch (code) {
+    case "consent_required":
+      return {
+        status: 403,
+        code: "forbidden",
+        message: `Screen access is not enabled for this connected machine's ${liveView}.`,
+      };
+    case "unsupported":
+      return {
+        status: 409,
+        code: "conflict",
+        message: `This connected machine does not support the ${liveView}.`,
+      };
+    case "not_found":
+      return {
+        status: 404,
+        code: "not_found",
+        message: `The connected-machine resource for this ${liveView} no longer exists.`,
+      };
+    case "fenced":
+      return {
+        status: 409,
+        code: "conflict",
+        message: `The connected-machine ${liveView} changed while it was opening.`,
+      };
+    case "agent_offline":
+      return {
+        status: 503,
+        code: "upstream_unavailable",
+        message: `The connected machine is offline, so its ${liveView} is unavailable.`,
+      };
+    case "draining":
+      return {
+        status: 503,
+        code: "upstream_unavailable",
+        message: `The connected machine is busy and could not open the ${liveView}.`,
+      };
+    case "timeout":
+      return {
+        status: 504,
+        code: "upstream_unavailable",
+        message: `The connected machine did not finish opening the ${liveView} in time.`,
+      };
+    case "payload_too_large":
+      return {
+        status: 502,
+        code: "upstream_unavailable",
+        message: `The connected machine could not deliver the ${liveView} within its transport limit.`,
+      };
+    case "stream":
+      return {
+        status: error.retryable ? 503 : 502,
+        code: "upstream_unavailable",
+        message: `The connected machine could not open the ${liveView} stream.`,
+      };
+    case "protocol":
+      return {
+        status: 502,
+        code: "upstream_unavailable",
+        message: `The connected machine returned an invalid ${liveView} response.`,
+      };
+    case "os":
+      return {
+        status: 502,
+        code: "upstream_unavailable",
+        message: `The connected machine could not prepare the ${liveView}.`,
+      };
+    case "unknown":
+      return {
+        status: 502,
+        code: "upstream_unavailable",
+        message: `The connected machine could not open the ${liveView}.`,
+      };
+  }
+}
+
+function safeControlRequestId(value: string | null): value is string {
+  return value !== null && value.length <= 128 && /^[A-Za-z0-9._:-]+$/u.test(value);
+}

package/src/http/keyed-admission.ts

@@ -0,0 +1,29 @@
+/**
+ * One token bucket per closed key, for anonymous beacon routes. It bounds
+ * counter inflation and log volume from any caller without per-client state.
+ */
+export type KeyedAdmission<Key extends string> = { admit(key: Key): boolean };
+
+export function createKeyedAdmission<Key extends string>(
+  options: { capacity?: number; refillPerSecond?: number; now?: () => number } = {},
+): KeyedAdmission<Key> {
+  const capacity = options.capacity ?? 30;
+  const refillPerMs = (options.refillPerSecond ?? 0.5) / 1_000;
+  const now = options.now ?? Date.now;
+  const buckets = new Map<Key, { tokens: number; updatedAt: number }>();
+  return {
+    admit(key) {
+      const at = now();
+      const bucket = buckets.get(key) ?? { tokens: capacity, updatedAt: at };
+      bucket.tokens = Math.min(
+        capacity,
+        bucket.tokens + Math.max(0, at - bucket.updatedAt) * refillPerMs,
+      );
+      bucket.updatedAt = at;
+      buckets.set(key, bucket);
+      if (bucket.tokens < 1) return false;
+      bucket.tokens -= 1;
+      return true;
+    },
+  };
+}

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);
+}