@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/index.d.ts

@@ -1,12 +1,17 @@
-export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type ProcessHttpHost, type HttpHostAddress, type HttpHostOptions, type HttpHostTlsOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, type WsRouteOptions, } from './http-host.js';
-export { createHttpHostGroup, listHttpHostAddresses, } from './listener-group.js';
-export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type DynamicTokenConfig, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
+export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpRequestInfo, type HttpRouter, type HttpRouterOptions, type HttpRouteRegistration, type RouteContext, type WsConnection, type WsHandle, type WsRouteOptions, type WsTransport, type WsUpgradeDecision, type WsUpgradeRequest, type ListedWsRoute, } from './http-host.js';
+export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
+export { listHttpHostAddresses } from './addresses.js';
+export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type TokenRegistryConfig, } from './token-registry.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
+export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken, type ProtocolAuthRequest } from './protocol-auth.js';
+export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, type TrustProxyPredicate, type TrustProxySetting, } from './trust-proxy.js';
 export { createConsoleEventHub, consoleEventHubToken, type ConsoleEventHub, } from './console-events.js';
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, type BuildOpenApiOptions, type ListedRoute, type OpenApiParameter, type RouteMeta, } from './openapi.js';
-export { HttpBodyError, readJsonBody, } from './json-body.js';
-export { dispatchRuntimeConsoleRpc, isDemoHttpAllowed, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
-export { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
+export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, type HttpBodyReadOptions, } from './json-body.js';
+export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, type HttpResponseStream, type HttpResponseStreamOptions, } from '@zhin.js/host-http-contract';
+export { dispatchRuntimeConsoleRpc, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
+export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, type FileTreeNode, } from './project-files.js';
 export { registerConsoleRestPages, type ConsoleAgentIntrospection, type ConsoleAgentRuntime, type ConsoleAgentSessionTree, type ConsoleRestCtx, type ConsoleRestPagesOptions, } from './console-rest-pages.js';
 export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, } from './console-rpc-extended/index.js';

package/lib/index.js

@@ -1,12 +1,16 @@
-export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
-export { createHttpHostGroup, listHttpHostAddresses, } from './listener-group.js';
-export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
+export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
+export { listHttpHostAddresses } from './addresses.js';
+export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
+export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken } from './protocol-auth.js';
+export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, } from './trust-proxy.js';
 export { createConsoleEventHub, consoleEventHubToken, } from './console-events.js';
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, } from './openapi.js';
-export { HttpBodyError, readJsonBody, } from './json-body.js';
-export { dispatchRuntimeConsoleRpc, isDemoHttpAllowed, pickRpcReply, } from './console-rpc.js';
-export { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
+export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, } from './json-body.js';
+export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, } from '@zhin.js/host-http-contract';
+export { dispatchRuntimeConsoleRpc, pickRpcReply, } from './console-rpc.js';
+export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, } from './project-files.js';
 export { registerConsoleRestPages, } from './console-rest-pages.js';
 export { dispatchExtendedConsoleRpc, } from './console-rpc-extended/index.js';

package/lib/json-body.d.ts

@@ -1,2 +1 @@
-/** @deprecated Import from @zhin.js/host-http-contract in protocol hosts. */
-export { HttpBodyError, readJsonBody } from '@zhin.js/host-http-contract';
+export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, type HttpBodyReadOptions, } from '@zhin.js/host-http-contract';

package/lib/json-body.js

@@ -1,2 +1 @@
-/** @deprecated Import from @zhin.js/host-http-contract in protocol hosts. */
-export { HttpBodyError, readJsonBody } from '@zhin.js/host-http-contract';
+export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, } from '@zhin.js/host-http-contract';

package/lib/marketplace-registry.d.ts

@@ -10,3 +10,20 @@ export declare class MarketplaceRegistry {
     constructor(options: MarketplaceRegistryOptions);
     list(): Promise<readonly unknown[]>;
 }
+export declare function isValidNpmPackageName(name: string): boolean;
+export interface MarketplaceDetailCacheOptions<T> {
+    readonly load: (name: string) => Promise<T>;
+    readonly ttlMs: number;
+    readonly maxEntries: number;
+    readonly now?: () => number;
+}
+/**
+ * Per-package detail cache: TTL, bounded size (oldest entry evicted first) and
+ * coalescing of concurrent loads. Failures are not cached.
+ */
+export declare class MarketplaceDetailCache<T> {
+    #private;
+    constructor(options: MarketplaceDetailCacheOptions<T>);
+    get size(): number;
+    get(name: string): Promise<T>;
+}

package/lib/marketplace-registry.js

@@ -43,3 +43,55 @@ export class MarketplaceRegistry {
         return plugins;
     }
 }
+/** npm package name grammar (optionally scoped, lower-case, URL-safe, at most 214 chars). */
+const NPM_PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
+export function isValidNpmPackageName(name) {
+    return name.length > 0 && name.length <= 214 && NPM_PACKAGE_NAME.test(name);
+}
+/**
+ * Per-package detail cache: TTL, bounded size (oldest entry evicted first) and
+ * coalescing of concurrent loads. Failures are not cached.
+ */
+export class MarketplaceDetailCache {
+    #load;
+    #ttlMs;
+    #maxEntries;
+    #now;
+    #entries = new Map();
+    #inflight = new Map();
+    constructor(options) {
+        this.#load = options.load;
+        this.#ttlMs = options.ttlMs;
+        this.#maxEntries = Math.max(1, options.maxEntries);
+        this.#now = options.now ?? Date.now;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get(name) {
+        const cached = this.#entries.get(name);
+        if (cached && this.#now() < cached.expiresAt)
+            return Promise.resolve(cached.value);
+        const pending = this.#inflight.get(name);
+        if (pending)
+            return pending;
+        const request = this.#load(name).then((value) => {
+            this.#entries.delete(name);
+            this.#entries.set(name, { value, expiresAt: this.#now() + this.#ttlMs });
+            while (this.#entries.size > this.#maxEntries) {
+                const oldest = this.#entries.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.#entries.delete(oldest);
+            }
+            return value;
+        });
+        this.#inflight.set(name, request);
+        const clear = () => {
+            if (this.#inflight.get(name) === request)
+                this.#inflight.delete(name);
+        };
+        void request.then(clear, clear);
+        return request;
+    }
+}

package/lib/node/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Node transport for the HTTP Host (`@zhin.js/host-http/node`): the in-process listener
+ * and the Node `http` / `ws` ↔ Web standard conversion. The only entry of this package
+ * that loads `node:http`, `node:https` or `ws`.
+ * @module @zhin.js/host-http/node
+ */
+export { createHttpHost, type ProcessHttpHost } from './server.js';
+export { createHttpHostGroup } from './listener-group.js';
+export { createNodeHttpListener, type NodeHttpListener, type NodeHttpListenerOptions, } from './listener.js';
+export { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket, type NodeRequestOptions, type NodeWebSocketOptions, } from './node-http.js';

package/lib/node/index.js

@@ -0,0 +1,10 @@
+/**
+ * Node transport for the HTTP Host (`@zhin.js/host-http/node`): the in-process listener
+ * and the Node `http` / `ws` ↔ Web standard conversion. The only entry of this package
+ * that loads `node:http`, `node:https` or `ws`.
+ * @module @zhin.js/host-http/node
+ */
+export { createHttpHost } from './server.js';
+export { createHttpHostGroup } from './listener-group.js';
+export { createNodeHttpListener, } from './listener.js';
+export { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket, } from './node-http.js';

package/lib/{listener-group.d.ts → node/listener-group.d.ts}

@@ -1,9 +1,8 @@
-import { type HttpHost, type HttpHostAddress, type HttpHostOptions, type ProcessHttpHost } from './http-host.js';
+import type { HttpHostOptions } from '../host-options.js';
+import { type ProcessHttpHost } from './server.js';
 /**
  * Runs one logical Host surface on multiple network listeners. Route and WS
  * registration stays generation-owned and is mirrored to every listener,
  * while `address` intentionally remains the primary/local listener.
  */
 export declare function createHttpHostGroup(options: readonly HttpHostOptions[]): ProcessHttpHost;
-/** Returns every bound listener, ordered primary/local first. */
-export declare function listHttpHostAddresses(host: HttpHost): readonly HttpHostAddress[];

package/lib/{listener-group.js → node/listener-group.js}

@@ -1,6 +1,7 @@
 import { bindGenerationAdmission, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
-import { createHttpHost, } from './http-host.js';
-const addressProvider = Symbol('HttpHostAddressProvider');
+import { TokenRegistry } from '../token-registry.js';
+import { httpHostAddressProvider as addressProvider } from '../addresses.js';
+import { createHttpHost } from './server.js';
 /**
  * Runs one logical Host surface on multiple network listeners. Route and WS
  * registration stays generation-owned and is mirrored to every listener,
@@ -9,7 +10,9 @@ const addressProvider = Symbol('HttpHostAddressProvider');
 export function createHttpHostGroup(options) {
     if (options.length === 0)
         throw new Error('HttpHostGroup requires at least one listener');
-    const listeners = options.map((entry) => createHttpHost(entry));
+    // One authentication state for the whole surface: every listener sees the same sessions.
+    const tokenRegistry = options[0].tokenRegistry ?? new TokenRegistry({ primaryToken: options[0].token });
+    const listeners = options.map((entry) => createHttpHost({ ...entry, tokenRegistry }));
     const createSurface = (hosts) => {
         const primary = hosts[0];
         const surface = {
@@ -71,13 +74,6 @@ export function createHttpHostGroup(options) {
     };
     return Object.freeze(runtime);
 }
-/** Returns every bound listener, ordered primary/local first. */
-export function listHttpHostAddresses(host) {
-    const provider = host[addressProvider];
-    if (typeof provider === 'function')
-        return Object.freeze([...provider.call(host)]);
-    return Object.freeze(host.address ? [host.address] : []);
-}
 async function closeListeners(listeners) {
     const results = await Promise.allSettled([...listeners].reverse().map((listener) => listener.close()));
     const errors = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);

package/lib/node/listener.d.ts

@@ -0,0 +1,26 @@
+import type { HttpRequestInfo, WsUpgradeDecision, WsUpgradeRequest } from '../http-host.js';
+import type { HttpHostAddress, HttpHostTlsOptions } from '../host-options.js';
+import { type TrustProxySetting } from '../trust-proxy.js';
+export interface NodeHttpListenerOptions {
+    readonly host?: string;
+    readonly port?: number;
+    /** Enables HTTPS / WSS on this listener. */
+    readonly tls?: HttpHostTlsOptions;
+    /** `http.trustProxy`: derive `remoteAddress` from forwarding headers sent by trusted peers. */
+    readonly trustProxy?: TrustProxySetting;
+    handle(request: Request, info: HttpRequestInfo): Promise<Response>;
+    upgrade(request: WsUpgradeRequest): Promise<WsUpgradeDecision>;
+    /** Called once the listener is bound, before `listen()` resolves. */
+    onListening?(address: HttpHostAddress): void;
+    /** Called after the listener closed. */
+    onClosed?(): void;
+}
+export interface NodeHttpListener {
+    listen(): Promise<HttpHostAddress>;
+    /** Destroys open connections (SSE, keep-alive, WebSocket) and stops listening. */
+    close(): Promise<void>;
+    readonly address: HttpHostAddress | undefined;
+    readonly secure: boolean;
+}
+/** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
+export declare function createNodeHttpListener(options: NodeHttpListenerOptions): NodeHttpListener;

package/lib/node/listener.js

@@ -0,0 +1,231 @@
+/**
+ * One Node `http` / `https` listener that feeds a transport-independent request handler and
+ * WebSocket upgrade handler (ADR 0054 §2). The in-process Host and the management gateway
+ * both run on it.
+ */
+import { createServer as createHttpServer, STATUS_CODES, } from 'node:http';
+import { createServer as createHttpsServer, } from 'node:https';
+import { WebSocketServer } from 'ws';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { compileTrustProxy, resolveClientAddress } from '../trust-proxy.js';
+import { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket } from './node-http.js';
+const logger = getLogger('http');
+/** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
+export function createNodeHttpListener(options) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 8086;
+    const secure = options.tls !== undefined;
+    let address;
+    let closed = false;
+    let closeResult;
+    let listenResult;
+    const trust = compileTrustProxy(options.trustProxy);
+    const clientAddress = (request) => resolveClientAddress(request.socket?.remoteAddress, request.headers, trust);
+    const handleRequest = (request, response) => {
+        void dispatch(request, response).catch((error) => {
+            logger.warn(formatCompact({
+                op: 'http_dispatch_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            if (!response.headersSent) {
+                response.writeHead(500);
+                response.end();
+            }
+            else {
+                response.destroy();
+            }
+        });
+    };
+    const server = secure
+        ? createHttpsServer(options.tls, handleRequest)
+        : createHttpServer(handleRequest);
+    // Track live TCP sockets so close() can destroy long-lived connections
+    // (SSE, keep-alive) that would otherwise block server.close().
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => {
+            sockets.delete(socket);
+        });
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    async function dispatch(request, response) {
+        if (closed) {
+            response.writeHead(503);
+            response.end();
+            return;
+        }
+        let url;
+        try {
+            url = new URL(request.url ?? '/', 'http://localhost');
+        }
+        catch {
+            response.writeHead(400);
+            response.end();
+            return;
+        }
+        const abort = new AbortController();
+        response.once('close', () => {
+            if (!response.writableFinished)
+                abort.abort(new Error('Client disconnected'));
+        });
+        let webRequest;
+        try {
+            webRequest = createNodeRequest(request, { url, signal: abort.signal });
+        }
+        catch {
+            response.writeHead(400);
+            response.end();
+            return;
+        }
+        const remoteAddress = clientAddress(request);
+        const webResponse = await options.handle(webRequest, {
+            ...(remoteAddress ? { remoteAddress } : {}),
+        });
+        await writeNodeResponse(response, webResponse);
+    }
+    server.on('upgrade', (request, socket, head) => {
+        if (closed) {
+            socket.destroy();
+            return;
+        }
+        let url;
+        try {
+            url = new URL(request.url ?? '/', 'http://localhost');
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const remoteAddress = clientAddress(request);
+        void options.upgrade({
+            url,
+            headers: nodeRequestHeaders(request),
+            ...(remoteAddress ? { remoteAddress } : {}),
+        }).then((decision) => {
+            if (!decision.accepted) {
+                if (decision.status !== 404)
+                    writeUpgradeRefusal(socket, decision.status, decision.headers);
+                socket.destroy();
+                return;
+            }
+            if (closed || socket.destroyed) {
+                decision.reject();
+                writeUpgradeRefusal(socket, 401);
+                socket.destroy();
+                return;
+            }
+            let accepted = false;
+            socket.once('close', () => { if (!accepted)
+                decision.reject(); });
+            try {
+                wss.handleUpgrade(request, socket, head, (ws) => {
+                    accepted = true;
+                    decision.accept(wrapNodeWebSocket(ws));
+                });
+            }
+            catch (err) {
+                decision.reject();
+                logger.warn(formatCompact({
+                    op: 'ws_upgrade_failed',
+                    path: url.pathname,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* already destroyed */
+                }
+            }
+        }, () => socket.destroy());
+    });
+    return {
+        get address() { return address; },
+        secure,
+        listen() {
+            if (closed)
+                return Promise.reject(new Error('HTTP Host is closed'));
+            if (listenResult)
+                return listenResult;
+            if (address)
+                return Promise.resolve(address);
+            listenResult = new Promise((resolve, reject) => {
+                const onError = (error) => {
+                    listenResult = undefined;
+                    reject(error);
+                };
+                server.once('error', onError);
+                server.listen({ host, port }, () => {
+                    server.off('error', onError);
+                    if (closed) {
+                        reject(new Error('HTTP Host closed before listen completed'));
+                        return;
+                    }
+                    const bound = server.address();
+                    const listenPort = typeof bound === 'object' && bound ? bound.port : port;
+                    const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+                    const protocol = secure ? 'https' : 'http';
+                    const originHost = publicHost.includes(':') ? `[${publicHost}]` : publicHost;
+                    address = Object.freeze({
+                        host: publicHost, port: listenPort, protocol, secure,
+                        origin: `${protocol}://${originHost}:${listenPort}`,
+                    });
+                    options.onListening?.(address);
+                    resolve(address);
+                });
+            });
+            return listenResult;
+        },
+        close() {
+            if (closeResult)
+                return closeResult;
+            closed = true;
+            closeResult = (async () => {
+                // A pending listen must settle before deciding whether there is a
+                // listener to close. Otherwise it can bind after close has resolved.
+                await listenResult?.catch(() => undefined);
+                if (!server.listening) {
+                    address = undefined;
+                    return;
+                }
+                await new Promise((resolve, reject) => {
+                    // Long-lived connections (SSE, keep-alive, WS) never end on their own:
+                    // destroy tracked sockets and terminate WS clients before close(),
+                    // otherwise the close callbacks would never fire.
+                    for (const socket of sockets)
+                        socket.destroy();
+                    sockets.clear();
+                    for (const client of wss.clients)
+                        client.terminate();
+                    wss.close((wssError) => {
+                        if (wssError) {
+                            reject(wssError);
+                            return;
+                        }
+                        server.close((serverError) => {
+                            if (serverError) {
+                                reject(serverError);
+                                return;
+                            }
+                            address = undefined;
+                            options.onClosed?.();
+                            resolve();
+                        });
+                    });
+                });
+            })();
+            return closeResult;
+        },
+    };
+}
+function writeUpgradeRefusal(socket, status, headers) {
+    if (socket.destroyed)
+        return;
+    const lines = [`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? ''}`.trimEnd()];
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (/^[!#$%&'*+.^_`|~0-9a-z-]+$/iu.test(name) && !/[\r\n]/u.test(value))
+            lines.push(`${name}: ${value}`);
+    }
+    socket.write(`${lines.join('\r\n')}\r\n\r\n`);
+}

package/lib/node/node-http.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Node `http` / `ws` ↔ Web standard conversion (ADR 0054 §2). This module and the
+ * server built on it are the only places in `@zhin.js/host-http` that load
+ * `node:http` or `ws`; the gateway reuses them for its listener.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { WebSocket } from 'ws';
+import type { WsTransport } from '../http-host.js';
+export interface NodeRequestOptions {
+    /** Absolute request URL. */
+    readonly url: URL;
+    /** Aborted when the client goes away before the response finished. */
+    readonly signal?: AbortSignal;
+    /** Bytes buffered from the socket before reading pauses (default 64 KiB). */
+    readonly highWaterMark?: number;
+}
+/** Headers of a Node request as a Web `Headers` (repeated headers preserved). */
+export declare function nodeRequestHeaders(request: IncomingMessage): Headers;
+/**
+ * A Web `Request` over a Node request. The body streams from the socket with
+ * backpressure; cancelling it (or reading it to the end) never destroys the
+ * socket, so the response can still be written on the same connection.
+ */
+export declare function createNodeRequest(request: IncomingMessage, options: NodeRequestOptions): Request;
+/**
+ * Writes a Web `Response` to a Node response: status, headers (`set-cookie`
+ * kept separate) and the body, honouring `drain` backpressure. A body that is
+ * immediately complete is sent with `Content-Length`; otherwise headers are
+ * flushed at once (SSE) and the body is chunked. A body stream error destroys
+ * the connection; a client disconnect cancels the body.
+ */
+export declare function writeNodeResponse(target: ServerResponse, response: Response): Promise<void>;
+export interface NodeWebSocketOptions {
+    /** Protocol ping interval; a peer that misses one pong is terminated. 0 disables. Default 30 s. */
+    readonly keepAliveMs?: number;
+}
+/** A {@link WsTransport} over a `ws` server socket. */
+export declare function wrapNodeWebSocket(socket: WebSocket, options?: NodeWebSocketOptions): WsTransport;