@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/http-host.d.ts

@@ -1,14 +1,40 @@
-import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type ServerOptions as HttpsServerOptions } from 'node:https';
-import { WebSocket } from 'ws';
 import { type GenerationAdmissionBindable } from '@zhin.js/plugin-runtime';
-import { TokenRegistry, type AuthenticatedTokenPrincipal, type AuthScope, type ScopedTokenConfig } from './token-registry.js';
+import { type HttpRouteContext } from '@zhin.js/host-http-contract';
+import { TokenRegistry } from './token-registry.js';
 import { type ListedRoute, type RouteMeta } from './openapi.js';
+import { type ConsolePrincipal } from './access-control.js';
+import type { HttpHostAddress } from './host-options.js';
+export type { HttpHostAddress } from './host-options.js';
 export declare const REMOTE_CONSOLE_ORIGIN = "https://console.zhin.dev";
+/** Per-request data resolved by the Host before a route runs. */
+export interface RouteContext extends HttpRouteContext {
+    readonly url: URL;
+    readonly params: Readonly<Record<string, string>>;
+    /**
+     * Console principal the Host authenticated. Set for `{apiBase}` routes and for public
+     * routes that presented a valid credential; absent otherwise.
+     */
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+}
+export type HttpHandler = (request: Request, context: RouteContext) => Response | Promise<Response>;
+export interface HttpRouteRegistration {
+    (): void;
+}
+/** An accepted WebSocket, independent of the transport that carries it. */
 export interface WsConnection {
-    readonly socket: WebSocket;
-    readonly request: IncomingMessage;
-    readonly authScope: AuthScope;
+    readonly url: URL;
+    readonly headers: Headers;
+    /** Authenticated principal (absent for `auth: 'protocol'` routes, which authenticate themselves). */
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+    /** Text frames as strings, binary frames as bytes. Dropped once the socket is closing. */
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onMessage(listener: (data: string | Uint8Array) => void): () => void;
+    onClose(listener: (code: number, reason: string) => void): () => void;
+    /** Bytes queued but not yet sent (backpressure). */
+    readonly bufferedAmount: number;
 }
 export interface WsHandle {
     onConnection(listener: (connection: WsConnection) => void): () => void;
@@ -21,28 +47,20 @@ export interface WsRouteOptions {
      */
     readonly auth?: 'host' | 'protocol';
 }
-export interface HttpHostAddress {
-    readonly host: string;
-    readonly port: number;
-    readonly protocol: 'http' | 'https';
-    readonly secure: boolean;
-    readonly origin: string;
-}
-export interface HttpHostTlsOptions {
-    readonly key: NonNullable<HttpsServerOptions['key']>;
-    readonly cert: NonNullable<HttpsServerOptions['cert']>;
-    readonly ca?: HttpsServerOptions['ca'];
-    readonly passphrase?: string;
-    readonly minVersion?: HttpsServerOptions['minVersion'];
-    readonly ciphers?: string;
+/** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
+export interface HttpHost {
+    ws(path: string, options?: WsRouteOptions): WsHandle;
+    route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
+    listRoutes(): readonly ListedRoute[];
+    get address(): HttpHostAddress | undefined;
+    /** @internal Console authentication registry owned by the process Host. */
+    get tokenRegistry(): TokenRegistry;
 }
-export interface HttpHostOptions {
-    readonly host?: string;
-    readonly port?: number;
-    /** Primary full-scope Bearer token (`http.token`). */
+/** @public Stable Plugin Runtime HTTP Host token. */
+export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
+export interface HttpRouterOptions {
+    /** Bootstrap Bearer token (`http.token`), accepted only until the first owner exists. */
     readonly token?: string;
-    /** Additional scoped tokens (`http.tokens`). */
-    readonly tokens?: readonly ScopedTokenConfig[];
     /** CORS allowlist; always merged with Remote Console origin. */
     readonly corsOrigins?: readonly string[];
     /**
@@ -52,28 +70,86 @@ export interface HttpHostOptions {
     readonly apiBase?: string;
     /** Extra HTTP path prefixes that skip auth even under `apiBase`. */
     readonly authExemptPaths?: readonly string[];
-    /** Enables HTTPS and WSS on this listener. Certificate lifecycle belongs to the process composition root. */
-    readonly tls?: HttpHostTlsOptions;
+    /** Shared registry for listener groups; `token` is ignored when set. */
+    readonly tokenRegistry?: TokenRegistry;
+    /** Whether the carrying transport is TLS (OpenAPI server URL default). */
+    readonly secure?: boolean;
+    /** Bound listener address as reported by the transport. */
+    readonly address?: () => HttpHostAddress | undefined;
+    /**
+     * Who authenticates requests (ADR 0054 §3):
+     * - `credentials` (default): the router resolves the Bearer / `?token=` credential through
+     *   {@link TokenRegistry}. A `principal` passed by the transport is ignored.
+     * - `forwarded`: the carrying transport already authenticated the request (the gateway, over
+     *   the bridge) and passes the principal in {@link HttpRequestInfo.principal} /
+     *   {@link WsUpgradeRequest.principal}. The router never parses credentials itself but still
+     *   authorizes every `{apiBase}` route and host-authenticated socket against the Console
+     *   permission map, exactly as in `credentials` mode. A missing principal is anonymous.
+     */
+    readonly authentication?: 'credentials' | 'forwarded';
+    /**
+     * Register the built-in `/pub/health` and `/pub/openapi.json` routes (default true). The
+     * gateway turns them off: it owns its own health probe and forwards the instance's catalog.
+     */
+    readonly builtinRoutes?: boolean;
 }
-export type HttpHandler = (request: IncomingMessage, response: ServerResponse, url: URL, authScope: AuthScope, authenticatedPrincipal?: AuthenticatedTokenPrincipal) => void | Promise<void>;
-export interface HttpRouteRegistration {
-    (): void;
+export interface HttpRequestInfo {
+    readonly remoteAddress?: string;
+    /**
+     * An in-process caller with no network peer (tests, embedding). Only such an explicit caller is
+     * admitted to an open Host without a loopback `remoteAddress`.
+     */
+    readonly inProcess?: boolean;
+    /** Pre-authenticated principal; honoured only by a `forwarded` router. */
+    readonly principal?: ConsolePrincipal;
 }
-/** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
-export interface HttpHost {
-    ws(path: string, options?: WsRouteOptions): WsHandle;
-    route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
-    listRoutes(): readonly ListedRoute[];
-    get address(): HttpHostAddress | undefined;
-    /** @internal Console authentication registry owned by the process Host. */
-    get tokenRegistry(): TokenRegistry;
+export interface WsUpgradeRequest {
+    readonly url: URL;
+    readonly headers: Headers;
+    readonly remoteAddress?: string;
+    /** Pre-authenticated principal; honoured only by a `forwarded` router. */
+    readonly principal?: ConsolePrincipal;
 }
-/** @internal Process-root lifecycle and generation admission surface. */
-export interface ProcessHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {
-    listen(): Promise<HttpHostAddress>;
-    close(): Promise<void>;
+/** A registered WebSocket path and how it authenticates (admission-active only). */
+export interface ListedWsRoute {
+    readonly path: string;
+    readonly auth: 'host' | 'protocol';
 }
-/** @public Stable Plugin Runtime HTTP Host token. */
-export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
-/** @internal CLI composition-root factory. */
-export declare function createHttpHost(options?: HttpHostOptions): ProcessHttpHost;
+/** The transport half of a {@link WsConnection}. */
+export interface WsTransport {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onMessage(listener: (data: string | Uint8Array) => void): () => void;
+    onClose(listener: (code: number, reason: string) => void): () => void;
+    readonly bufferedAmount: number;
+}
+export type WsUpgradeDecision = Readonly<{
+    accepted: false;
+    /** 404 drops the socket silently; other statuses are written as a bare HTTP response. */
+    status: 401 | 404 | 503;
+    /** Extra response headers for the refusal (e.g. `Retry-After`). */
+    headers?: Readonly<Record<string, string>>;
+}> | Readonly<{
+    accepted: true;
+    /** Hand the established socket to the route listeners. */
+    accept(transport: WsTransport): void;
+    /** The transport failed to complete the handshake. */
+    reject(): void;
+}>;
+/** @internal Transport-facing router; `createHttpHost` (node) and the gateway bridge drive it. */
+export interface HttpRouter extends HttpHost, GenerationAdmissionBindable<HttpHost> {
+    handle(request: Request, info?: HttpRequestInfo): Promise<Response>;
+    upgrade(request: WsUpgradeRequest): Promise<WsUpgradeDecision>;
+    readonly routeCount: number;
+    readonly wsPaths: readonly string[];
+    /** Admission-active WebSocket routes (`protocol` only when every listener uses it). */
+    listWsRoutes(): readonly ListedWsRoute[];
+    /** Called after any route or socket registration changes (not on admission changes). */
+    onRoutesChanged(listener: () => void): () => void;
+    readonly apiBase: string;
+    readonly corsOrigins: readonly string[];
+    /** Terminal: routes are dropped and every later request gets 503. */
+    close(): void;
+}
+export declare function createHttpRouter(options?: HttpRouterOptions): HttpRouter;
+export declare function normalizePath(pathname: string): string;