@opengeni/api-router 3.0.1 → 3.1.2

package/dist/http/deprecation.d.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareHandler } from "hono";
+/**
+ * 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 declare const DEPRECATED_ROUTES: readonly RouteDeprecation[];
+/** Validate one registry entry; the policy's 90-day minimum is enforced here. */
+export declare function assertValidRouteDeprecation(deprecation: RouteDeprecation): void;
+/** The response headers that advertise one deprecation. */
+export declare function deprecationHeaders(deprecation: RouteDeprecation): Record<string, string>;
+/**
+ * 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 declare function deprecationHeadersMiddleware(registry?: readonly RouteDeprecation[]): MiddlewareHandler;

package/dist/http/keyed-admission.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function createKeyedAdmission<Key extends string>(options?: {
+    capacity?: number;
+    refillPerSecond?: number;
+    now?: () => number;
+}): KeyedAdmission<Key>;

package/dist/http/local-browser-boundary.d.ts

@@ -0,0 +1,72 @@
+import { 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;
+};
+/** Mark a request the API dispatches to itself so the boundary admits it. */
+export declare function markLocalInternalDispatch(request: Request): Request;
+export declare function localBrowserBoundaryApplies(settings: Pick<Settings, "productAccessMode" | "environment">): boolean;
+/** Build the boundary, or null when the deployment is not the local dev product. */
+export declare function createLocalBrowserBoundary(settings: LocalBrowserBoundarySettings, options?: {
+    warn?: LocalBrowserBoundaryWarn;
+}): LocalBrowserBoundary | null;
+/** The standard API error envelope for a boundary rejection outside Hono. */
+export declare function localBrowserBoundaryResponse(rejection: LocalBrowserBoundaryRejection): Response;
+/** The `Host` the boundary checks: the header, else the request URL's authority. */
+export declare function localBrowserRequestHost(request: Request): string | null;

package/dist/http/metrics-listener.d.ts

@@ -0,0 +1,22 @@
+import type { Settings } from "@opengeni/config";
+import { Hono } from "hono";
+type PrometheusSource = {
+    prometheusMetrics(): Promise<string>;
+};
+/** Register the Prometheus exposition route on one Hono app. */
+export declare function registerPrometheusMetricsRoute(app: Hono, observability: PrometheusSource): void;
+/**
+ * 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 declare function publicListenerServesMetrics(settings: Pick<Settings, "apiMetricsPort">): boolean;
+/**
+ * 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 declare function createMetricsListenerApp(settings: Settings, observability: PrometheusSource): Hono;
+/** Start the dedicated listener when configured; returns undefined otherwise. */
+export declare function startApiMetricsListener(settings: Settings, observability: PrometheusSource): ReturnType<typeof Bun.serve> | undefined;
+export {};

package/dist/http/path-identifier.d.ts

@@ -0,0 +1,17 @@
+import { ApiHttpError } from "./api-error.js";
+/**
+ * A resource id taken verbatim from the URL path that is not a UUID cannot
+ * name any row. Routes pass such ids straight to PostgreSQL, which rejects the
+ * cast (SQLSTATE 22P02); that is a client addressing error, so answer 404
+ * instead of an unhandled 500.
+ *
+ * Deliberately narrow: only a uuid-syntax failure whose rejected text is
+ * exactly one of this request's own path segments qualifies. A malformed UUID
+ * produced by server code (a stored value, a derived subject, a body field)
+ * does not appear as a path segment and stays a genuine 500.
+ *
+ * Typical cause: a client built against a newer API calls a literal route
+ * (for example `.../scheduled-tasks/attention`) that an older server does not
+ * have, so the literal falls through to `.../scheduled-tasks/:taskId`.
+ */
+export declare function invalidPathIdentifierHttpError(error: unknown, pathname: string): ApiHttpError | null;

package/dist/http/registered-route-label.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from "hono";
+/**
+ * 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 declare function registeredHandlerRoutePath(context: Context): string | null;
+/** Normalize a registered template; drop catch-alls that would name nothing. */
+export declare function boundedRegisteredRouteLabel(path: string | null | undefined): string | null;

package/dist/http/rejection-telemetry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Bounded, content-free classification of a rejected (4xx/5xx) API response,
+ * so a refused request can be diagnosed from logs and counted per route without
+ * copying the response message, identifiers, or user content into telemetry.
+ *
+ * - `code` is the public `ErrorEnvelope.code` (a closed enum).
+ * - `reason` is `permission:<name>` when the refusal names a missing permission
+ *   from the closed permission catalog, else the envelope's typed
+ *   `details.code` when it is a short identifier, else `control:<code>` for a
+ *   Connected Machine control failure, else `unclassified`.
+ * - `fingerprint` is a one-way hash of the message with identifiers and
+ *   numbers normalized away. It groups identical refusals in logs; resolve it
+ *   back to source text with `bun run scripts/resolve-rejection-fingerprint.ts`.
+ *   It never becomes a metric label.
+ */
+export type HttpRejectionFacts = {
+    code: string;
+    reason: string;
+    fingerprint?: string;
+};
+export declare const UNCLASSIFIED_REJECTION_REASON = "unclassified";
+export declare function rejectionFingerprint(message: string): string;
+/** Identifiers, quoted values, and numbers never distinguish two fingerprints. */
+export declare function normalizeRejectionMessage(message: string): string;
+export declare function rejectionReasonFromMessage(message: string | undefined): string | null;
+/** Classify a parsed `ErrorEnvelope`-shaped body. Unknown shapes still get a code. */
+export declare function httpRejectionFactsFromEnvelope(envelope: unknown, fallbackCode: string): HttpRejectionFacts;
+/** Classify a thrown error that escaped the central error handler. */
+export declare function httpRejectionFactsFromError(error: unknown, fallbackCode: string): HttpRejectionFacts;
+/**
+ * Read a small JSON error body without consuming the response that is sent to
+ * the client. Streams, non-JSON bodies, and large bodies are never read.
+ */
+export declare function readRejectionEnvelope(response: Response): Promise<unknown>;

package/dist/http/request-body.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import { ZodError } from "zod";
+import { ApiHttpError } from "./api-error.js";
+/** Parse an already-read request body against its public request schema. */
+export declare function parseRequestBody<Schema extends z.ZodType>(schema: Schema, body: unknown): z.output<Schema>;
+/**
+ * Read the request body as JSON. Malformed JSON is a client error (400), never
+ * an unhandled `SyntaxError` 500. Other failures (body limit, aborted stream)
+ * keep their own mapping.
+ */
+export declare function readRequestJson(c: Context): Promise<unknown>;
+/** Read and validate a JSON request body in one step. */
+export declare function parseRequestJson<Schema extends z.ZodType>(c: Context, schema: Schema): Promise<z.output<Schema>>;
+/**
+ * Tag malformed-JSON failures of `c.req.json()` for this request. The same
+ * `SyntaxError` instance is rethrown so routes that already catch it keep
+ * their own mapping; an uncaught one becomes a 400 in `app.onError` instead of
+ * a 500. A `SyntaxError` from parsing stored or upstream data is never tagged.
+ */
+export declare function tagRequestJsonParseErrors(c: Context): void;
+export declare function isRequestBodyValidationError(error: unknown): error is ZodError | SyntaxError;
+/**
+ * Public 400 for a registered request-body validation failure, naming every
+ * offending field (bounded) so API callers can correct the request.
+ */
+export declare function requestBodyValidationHttpError(error: unknown): ApiHttpError | null;

package/dist/http/request-source.d.ts

@@ -1,14 +1,52 @@
+import { type Settings } from "@opengeni/config";
 import type { Context } from "hono";
 declare 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 declare 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 declare 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 declare function apiRequestBindingsForTransportPeer(address: string | null | undefined): ApiRequestBindings;
 /**
  * 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 declare function trustedRequestSourceAddress(c: Context, trust: RequestSourceTrust): string;
+/**
+ * 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 declare function requestSourceRateLimitKey(address: string): string;
+/** {@link trustedRequestSourceAddress} as an application rate-limit key. */
+export declare function trustedRequestSourceRateLimitKey(c: Context, trust: RequestSourceTrust): string;
+/**
+ * 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 declare function trustedRequestSourceAddress(c: Context, trustedProxyHops: number): string;
+export declare function replaceTrustedClientAddressHeader(c: Context, trust: RequestSourceTrust, stamp: boolean): void;
 export {};

package/dist/http/sse.d.ts

@@ -59,6 +59,17 @@ export type LatestWinsDelivery<T extends {
 export declare function createLatestWinsDelivery<T extends {
     sequence: number;
 }>(send: (event: T) => Promise<void>, onError: (error: unknown) => void): LatestWinsDelivery<T>;
+/**
+ * Durable coverage for each projected frame. Storage may omit sequences on
+ * purpose (an archived session keeps only its readable timeline), and clients
+ * treat an uncovered jump as a gap to backfill. Within a page the next stored
+ * row bounds the gap; after the last row, `gapEnd` (when given) reads the
+ * race-free bound from storage.
+ */
+export declare function coverStorageGaps(projection: {
+    events: SessionEvent[];
+    coveredThroughBySequence: ReadonlyMap<number, number>;
+}, gapEnd: ((through: number) => Promise<number>) | null): Promise<Map<number, number>>;
 export declare function sseSessionStream(db: Database, bus: EventBus, workspaceId: string, sessionId: string, after: number, signal: AbortSignal, options?: SessionSseDeliveryOptions): Promise<Response>;
 export declare function replaySessionEvents(loadPage: (after: number, limit: number) => Promise<SessionEvent[]>, send: (event: SessionEvent) => Promise<void>, after: number, pageSize?: number): Promise<void>;
 export declare function sseWorkspaceControlStream(db: Database, bus: EventBus, workspaceId: string, after: number, signal: AbortSignal, options?: SseDeliveryOptions): Promise<Response>;
@@ -67,7 +78,7 @@ export type WorkspaceInteractionSseOptions = SseDeliveryOptions & {
 };
 /**
  * One HTTP connection for the two workspace-wide invalidation domains used by
- * every visible OpenGeni surface. Keeping these as separate HTTP/1 streams
+ * every visible Opengeni surface. Keeping these as separate HTTP/1 streams
  * consumes all six per-origin browser connections with only two windows and
  * starves ordinary mutations/terminal grants. The durable cursors remain
  * independent; this function only multiplexes their already-bounded SSE frames.

package/dist/http/unmatched-route.d.ts

@@ -0,0 +1,18 @@
+import type { Context, Hono } from "hono";
+export type UnmatchedRoute = {
+    status: 404;
+} | {
+    status: 405;
+    allow: string[];
+};
+/**
+ * Classify a request no registered handler can answer, BEFORE authentication
+ * or authorization middleware runs. Those layers otherwise turn a request for a
+ * route that does not exist into an authorization-shaped failure (for example
+ * the fail-closed session operation classifier answering a retryable 503), so
+ * a client probing an unknown method or path would be told to retry forever.
+ *
+ * Returns null when the request has a handler, or when classification itself
+ * fails (fail open: the request keeps its previous routing behavior).
+ */
+export declare function unmatchedRoute(app: Hono, c: Context): UnmatchedRoute | null;

package/dist/http/user-content.d.ts

@@ -0,0 +1,36 @@
+export declare const USER_CONTENT_SECURITY_POLICY = "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox";
+/** Media players only; scripts stay disabled (see the module comment). */
+export declare const USER_MEDIA_CONTENT_SECURITY_POLICY = "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox allow-same-origin";
+export declare const USER_CONTENT_SECURITY_HEADERS: Readonly<{
+    readonly "Content-Security-Policy": "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox";
+    readonly "Cross-Origin-Resource-Policy": "same-origin";
+    readonly "X-Content-Type-Options": "nosniff";
+}>;
+/**
+ * True when a browser would render this type as an active document (HTML,
+ * XHTML, SVG, any XML dialect, or multipart replacement streams). Anything that
+ * is not a clean `type/subtype` token is treated as active too.
+ */
+export declare function isActiveUserContentType(contentType: string): boolean;
+/** `Content-Disposition: attachment` for active markup; inline types are unchanged. */
+export declare function userContentDispositionHeaders(contentType: string, filename?: string | null): {
+    "Content-Disposition": string;
+} | Record<string, never>;
+/**
+ * Signed object-storage GET options for one stored object: active markup gets
+ * a signed `attachment` response override, so a browser that opens the URL
+ * downloads the bytes instead of rendering them with their stored type. The
+ * storage endpoint is not always a separate site (local development serves it
+ * from loopback, and a preview may route the bucket path on the app origin),
+ * so a signed URL follows the same rule as the API routes. Spread into
+ * `createGetUrl`; inline types add nothing.
+ */
+export declare function userContentSignedGetUrlOptions(contentType: string, filename?: string | null): {
+    responseContentDisposition: string;
+} | Record<string, never>;
+/** True for audio and video types the browser plays in a synthesized media document. */
+export declare function isPlayableMediaUserContentType(contentType: string): boolean;
+/** Sandbox policy for one response; only playable media keeps its origin. */
+export declare function userContentSecurityPolicy(contentType: string): string;
+/** Full header set for one user-content response with the given content type. */
+export declare function userContentResponseHeaders(contentType: string, filename?: string | null): Record<string, string>;

package/dist/http/variable-sets-removed.d.ts

@@ -0,0 +1,41 @@
+import type { Context } from "hono";
+/** The RM-1 answer for legacy Variable Set routes (410) and fields (422). */
+export declare function variableSetsRemovedResponse(c: Context, status: 410 | 422, fields?: readonly string[]): Response;
+/** Thrown where a route cannot return directly; `app.onError` renders it. */
+export declare class VariableSetsRemovedError extends Error {
+    readonly fields: readonly string[];
+    readonly name = "VariableSetsRemovedError";
+    constructor(fields: readonly string[]);
+}
+/**
+ * The RM-1 body for a removed-field error from a route or from core's
+ * `variableSetsRemovedError`, or null for any other error.
+ */
+export declare function variableSetsRemovedErrorResponse(c: Context, error: unknown): Response | null;
+/**
+ * Legacy selection fields that still carry a choice. Empty arrays and null
+ * mean "no Variable Sets" and stay accepted so old clients keep working.
+ */
+export declare function legacyVariableSetFields(payload: unknown): string[];
+/** True when the body explicitly clears a legacy selection (`null` or `[]`). */
+export declare function clearsLegacyVariableSet(payload: unknown): boolean;
+/**
+ * Drops every (empty) legacy Variable Set field so nothing downstream can act
+ * on one. Call after {@link legacyVariableSetFields} found none set.
+ */
+export declare function withoutLegacyVariableSetFields(payload: unknown): unknown;
+/**
+ * The RM-1 boundary for one JSON body: a 422 `variable_sets_removed` response
+ * when a legacy field still carries a choice, otherwise the body without them.
+ */
+export declare function rejectLegacyVariableSetFields(c: Context, payload: unknown): {
+    response: Response;
+} | {
+    payload: unknown;
+};
+/**
+ * Old clients send `variableSetId: null` / `environmentId: null` to mean "no
+ * Variable Sets". The create schema only takes the array form, so translate the
+ * accepted empty legacy fields to it. Call after {@link legacyVariableSetFields}.
+ */
+export declare function withoutEmptyLegacyVariableSetFields(payload: unknown): unknown;

package/dist/http/websocket-upgrade-dispatch.d.ts

@@ -0,0 +1,18 @@
+import { type LocalBrowserBoundary } from "./local-browser-boundary.js";
+export type ApiWebSocketUpgradeRoute<Server> = {
+    handles(request: Request): boolean;
+    upgrade(request: Request, server: Server): Response | undefined;
+};
+export type ApiWebSocketUpgradeDispatch = {
+    handled: false;
+} | {
+    handled: true;
+    response: Response | undefined;
+};
+/**
+ * WebSocket upgrades bypass the Hono app, so the local-mode browser boundary
+ * (./local-browser-boundary.ts) is applied here before a transport upgrades.
+ * Returns `{ handled: false }` when no transport claims the request, so the
+ * caller dispatches it to the app, where the boundary runs as middleware.
+ */
+export declare function dispatchApiWebSocketUpgrade<Server>(request: Request, server: Server, routes: ReadonlyArray<ApiWebSocketUpgradeRoute<Server>>, localBrowserBoundary: LocalBrowserBoundary | null): ApiWebSocketUpgradeDispatch;