@zhin.js/host-http 1.1.17 → 1.2.0

package/lib/bridge/protocol.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Gateway ↔ instance control channel protocol (ADR 0054 §3).
+ *
+ * The channel is the Node child-process IPC channel opened by the gateway with
+ * `serialization: 'advanced'` (structured clone: `Uint8Array` travels as is). Every message is
+ * `{ type, id?, payload }`. Both sides import this module so the message shapes, limits and the
+ * protocol version stay in one place.
+ *
+ * Streams
+ * - HTTP exchanges and WebSocket connections are identified by a gateway-assigned `id`.
+ * - Bodies travel in chunks of at most {@link BridgeLimits.maxChunkBytes}. Flow control is
+ *   credit based: each direction of a stream starts with {@link BridgeLimits.initialCreditBytes}
+ *   of credit; the receiver grants more (`http.request.credit` / `http.response.credit`) as its
+ *   consumer reads. A sender never has more than the window in flight, so memory per stream is
+ *   bounded on both ends. A receiver that gets more than it granted fails the stream.
+ * - WebSocket frames are whole messages (at most {@link BridgeLimits.maxWsMessageBytes}); the
+ *   receiver acknowledges delivered bytes with `ws.drain`, which drives `bufferedAmount`.
+ * - Either side cancels: `http.request.abort` (gateway: client went away / timeout),
+ *   `http.response.error` (instance: handler or body failed), `ws.close` (both).
+ *
+ * This module must not import `node:http` / `ws`: the instance loads it.
+ */
+import type { ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import type { ConsoleAuditEntry, ConsolePrincipal } from '../access-control.js';
+import type { HttpHostAddress } from '../host-options.js';
+import type { RouteMeta } from '../openapi.js';
+/**
+ * Bumped on any incompatible change to the control channel messages.
+ * - 1: `ready` / `restart-request` / `shutdown` (B1.1).
+ * - 2: route table, HTTP streams, WebSocket frames, forwarded principal (B1.2); interim delegated
+ *   credential resolution (`auth.*`).
+ * - 3: Console accounts live in the gateway (B1.4): `auth.*` removed; `catalog` (plugin permission
+ *   catalog) and `audit` (instance-side audit entries) from the instance; `principal-revoked`
+ *   from the gateway.
+ */
+export declare const INSTANCE_BRIDGE_PROTOCOL_VERSION = 3;
+/** Protocol versions this build can talk to. */
+export declare const SUPPORTED_BRIDGE_PROTOCOL_VERSIONS: readonly number[];
+export declare function isBridgeProtocolCompatible(version: number): boolean;
+/**
+ * Set by the gateway on the instance child process; marks the process as a supervised instance.
+ * Its value is the gateway's {@link INSTANCE_BRIDGE_PROTOCOL_VERSION}, so the instance can
+ * refuse an incompatible gateway before it starts anything.
+ */
+export declare const INSTANCE_CHILD_ENV = "ZHIN_RUNTIME_CHILD";
+/**
+ * Set by the gateway on the instance child process: the gateway's local control endpoint (socket
+ * path — including the `os.tmpdir()` fallback for deep project roots — or named pipe). Whoever
+ * connects to it is the local owner (ADR 0054 §6), so the instance keeps the Agent's file and
+ * shell tools away from it. Absent when the gateway runs without a local socket.
+ */
+export declare const GATEWAY_SOCKET_ENV = "ZHIN_GATEWAY_SOCKET";
+export declare class BridgeProtocolMismatchError extends Error {
+    readonly peerVersion: number;
+    readonly side: 'gateway' | 'instance';
+    readonly code = "ZHIN_BRIDGE_PROTOCOL_MISMATCH";
+    constructor(peerVersion: number, side: 'gateway' | 'instance');
+}
+/** Per-frame size limits and stream windows. Both ends use the same defaults. */
+export interface BridgeLimits {
+    /** Largest body chunk in one message. */
+    readonly maxChunkBytes: number;
+    /** Credit each stream direction starts with (also the most a receiver buffers). */
+    readonly initialCreditBytes: number;
+    /** Request line + headers (names and values) of one request or response head. */
+    readonly maxHeadBytes: number;
+    /** Largest WebSocket message (text is measured as UTF-16 length × 3 upper bound). */
+    readonly maxWsMessageBytes: number;
+    /** Unacknowledged WebSocket bytes a sender queues before closing with 1013. */
+    readonly maxWsBufferedBytes: number;
+    /** Concurrent HTTP exchanges + WebSocket connections per instance. */
+    readonly maxStreams: number;
+    /** Entries in a route table. */
+    readonly maxRoutes: number;
+}
+export declare const DEFAULT_BRIDGE_LIMITS: BridgeLimits;
+/** Gateway: time to wait for a response head before failing with `timeout`. */
+export declare const DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS = 120000;
+/** Gateway: time to wait for `ws.accepted` / `ws.rejected`. */
+export declare const DEFAULT_BRIDGE_WS_OPEN_TIMEOUT_MS = 30000;
+export interface BridgeMessage<Type extends string, Payload> {
+    readonly type: Type;
+    readonly id?: string;
+    readonly payload: Payload;
+}
+/** A message that belongs to one stream (`id` is required). */
+export interface BridgeStreamMessage<Type extends string, Payload> extends BridgeMessage<Type, Payload> {
+    readonly id: string;
+}
+/** Header list; repeated names (e.g. `set-cookie`) stay separate. */
+export type BridgeHeaders = readonly (readonly [string, string])[];
+export interface BridgeHttpRoute {
+    readonly method: string;
+    /** `/path` or `/prefix/*`. */
+    readonly pattern: string;
+    readonly meta?: RouteMeta;
+}
+export interface BridgeWsRoute {
+    readonly path: string;
+    /** `host`: the gateway authenticates before upgrade; `protocol`: the route authenticates itself. */
+    readonly auth: 'host' | 'protocol';
+}
+/**
+ * Routes the instance currently serves. The gateway authenticates `{apiBase}` routes and
+ * `auth: 'host'` sockets and forwards the rest unauthenticated (ADR 0054 §3).
+ */
+export interface BridgeRouteTable {
+    /** Increases with every table the instance sends. */
+    readonly revision: number;
+    /** Committed Runtime generation, when known. */
+    readonly generation?: number;
+    readonly apiBase: string;
+    readonly http: readonly BridgeHttpRoute[];
+    readonly ws: readonly BridgeWsRoute[];
+}
+export declare const EMPTY_ROUTE_TABLE: BridgeRouteTable;
+export interface InstanceReadyPayload {
+    /** {@link INSTANCE_BRIDGE_PROTOCOL_VERSION} the instance was built with. */
+    readonly version: number;
+    /** Committed Runtime generation at the time the instance became ready. */
+    readonly generation?: number;
+    readonly pid: number;
+    /** Route table at ready time (also sent earlier with `routes`). */
+    readonly routes?: BridgeRouteTable;
+}
+export interface InstanceRestartRequestPayload {
+    /** Short machine-readable reason, e.g. `console`, `dependencies`, `self-change`. */
+    readonly reason: string;
+}
+export interface HttpResponseHeadPayload {
+    readonly status: number;
+    readonly statusText?: string;
+    readonly headers: BridgeHeaders;
+    /** False for a bodiless response: no `http.response.body` follows, `http.response.end` does. */
+    readonly body: boolean;
+}
+export interface BodyChunkPayload {
+    readonly chunk: Uint8Array;
+}
+export interface CreditPayload {
+    readonly bytes: number;
+}
+export interface StreamErrorPayload {
+    readonly message: string;
+}
+export interface WsRejectedPayload {
+    readonly status: 401 | 403 | 404 | 503;
+}
+export interface WsMessagePayload {
+    readonly data: string | Uint8Array;
+}
+export interface WsClosePayload {
+    readonly code: number;
+    readonly reason: string;
+}
+export type InstanceReadyMessage = BridgeMessage<'ready', InstanceReadyPayload>;
+export type InstanceRestartRequestMessage = BridgeMessage<'restart-request', InstanceRestartRequestPayload>;
+export type InstanceRoutesMessage = BridgeMessage<'routes', {
+    readonly table: BridgeRouteTable;
+}>;
+export type HttpResponseHeadMessage = BridgeStreamMessage<'http.response.head', HttpResponseHeadPayload>;
+export type HttpResponseBodyMessage = BridgeStreamMessage<'http.response.body', BodyChunkPayload>;
+export type HttpResponseEndMessage = BridgeStreamMessage<'http.response.end', Record<string, never>>;
+export type HttpResponseErrorMessage = BridgeStreamMessage<'http.response.error', StreamErrorPayload>;
+export type HttpRequestCreditMessage = BridgeStreamMessage<'http.request.credit', CreditPayload>;
+export type WsAcceptedMessage = BridgeStreamMessage<'ws.accepted', Record<string, never>>;
+export type WsRejectedMessage = BridgeStreamMessage<'ws.rejected', WsRejectedPayload>;
+export type WsMessageMessage = BridgeStreamMessage<'ws.message', WsMessagePayload>;
+export type WsCloseMessage = BridgeStreamMessage<'ws.close', WsClosePayload>;
+export type WsDrainMessage = BridgeStreamMessage<'ws.drain', CreditPayload>;
+/**
+ * Plugin permission catalog of the instance's current generation (ADR 0049 amendment): the
+ * gateway uses it for level grants in `/auth/me`, `iam.roles.list` and its own authorization.
+ * Sent on listen and whenever it changes (generation commit).
+ */
+export interface InstanceCatalogPayload {
+    readonly pluginPermissions: readonly ConsolePluginPermissionInfo[];
+}
+/** An audit entry written by the instance (its RPC dispatcher); the gateway owns the audit log. */
+export interface InstanceAuditPayload {
+    readonly entry: ConsoleAuditEntry;
+}
+export type InstanceCatalogMessage = BridgeMessage<'catalog', InstanceCatalogPayload>;
+export type InstanceAuditMessage = BridgeMessage<'audit', InstanceAuditPayload>;
+export type InstanceToGatewayMessage = InstanceReadyMessage | InstanceCatalogMessage | InstanceAuditMessage | InstanceRestartRequestMessage | InstanceRoutesMessage | HttpResponseHeadMessage | HttpResponseBodyMessage | HttpResponseEndMessage | HttpResponseErrorMessage | HttpRequestCreditMessage | WsAcceptedMessage | WsRejectedMessage | WsMessageMessage | WsCloseMessage | WsDrainMessage;
+export interface GatewayShutdownPayload {
+    /** Why the gateway stops the instance, e.g. `stop`, `restart`, `protocol-mismatch`. */
+    readonly reason: string;
+    /** Graceful stop budget; the gateway escalates to SIGTERM / SIGKILL after it. */
+    readonly budgetMs: number;
+}
+export interface HttpRequestPayload {
+    readonly method: string;
+    /** Absolute URL as the gateway received it. */
+    readonly url: string;
+    readonly headers: BridgeHeaders;
+    /** True when `http.request.body` chunks (then `http.request.end`) follow. */
+    readonly body: boolean;
+    /** Principal the gateway authenticated (ADR 0054 §3); authorization happens in the instance. */
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+}
+export interface WsOpenPayload {
+    readonly url: string;
+    readonly headers: BridgeHeaders;
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+}
+/**
+ * A user's credentials were revoked or narrowed (disabled, deleted, password changed, bindings
+ * changed): the instance closes that principal's live connections (SSE, WebSocket).
+ */
+export interface PrincipalRevokedPayload {
+    /** `ConsoleUserPrincipal.userId`. */
+    readonly principalId: string;
+    readonly reason?: string;
+}
+export type GatewayShutdownMessage = BridgeMessage<'shutdown', GatewayShutdownPayload>;
+export type GatewayPrincipalRevokedMessage = BridgeMessage<'principal-revoked', PrincipalRevokedPayload>;
+export type GatewayAddressesMessage = BridgeMessage<'host.addresses', {
+    readonly addresses: readonly HttpHostAddress[];
+}>;
+export type HttpRequestMessage = BridgeStreamMessage<'http.request', HttpRequestPayload>;
+export type HttpRequestBodyMessage = BridgeStreamMessage<'http.request.body', BodyChunkPayload>;
+export type HttpRequestEndMessage = BridgeStreamMessage<'http.request.end', Record<string, never>>;
+export type HttpRequestAbortMessage = BridgeStreamMessage<'http.request.abort', StreamErrorPayload>;
+export type HttpResponseCreditMessage = BridgeStreamMessage<'http.response.credit', CreditPayload>;
+export type WsOpenMessage = BridgeStreamMessage<'ws.open', WsOpenPayload>;
+export type GatewayToInstanceMessage = GatewayShutdownMessage | GatewayPrincipalRevokedMessage | GatewayAddressesMessage | HttpRequestMessage | HttpRequestBodyMessage | HttpRequestEndMessage | HttpRequestAbortMessage | HttpResponseCreditMessage | WsOpenMessage | WsMessageMessage | WsCloseMessage | WsDrainMessage;
+/** Bytes a head occupies (UTF-16 length; ASCII headers are exact). */
+export declare function headSize(url: string, headers: BridgeHeaders): number;
+/** Upper bound of the UTF-8 size of a text frame. */
+export declare function wsMessageSize(data: string | Uint8Array): number;
+/** Validates a principal forwarded by the gateway; `undefined` when malformed. */
+export declare function parseBridgePrincipal(value: unknown): ConsolePrincipal | undefined;
+/** Validates an untrusted message received from the instance. */
+export declare function parseInstanceMessage(value: unknown, limits?: BridgeLimits): InstanceToGatewayMessage | undefined;
+/** Validates an untrusted message received from the gateway. */
+export declare function parseGatewayMessage(value: unknown, limits?: BridgeLimits): GatewayToInstanceMessage | undefined;
+/** Headers as a bridge header list (repeated `set-cookie` stays separate). */
+export declare function toBridgeHeaders(headers: Headers): BridgeHeaders;
+export declare function fromBridgeHeaders(list: BridgeHeaders): Headers;

package/lib/bridge/protocol.js

@@ -0,0 +1,369 @@
+/**
+ * Bumped on any incompatible change to the control channel messages.
+ * - 1: `ready` / `restart-request` / `shutdown` (B1.1).
+ * - 2: route table, HTTP streams, WebSocket frames, forwarded principal (B1.2); interim delegated
+ *   credential resolution (`auth.*`).
+ * - 3: Console accounts live in the gateway (B1.4): `auth.*` removed; `catalog` (plugin permission
+ *   catalog) and `audit` (instance-side audit entries) from the instance; `principal-revoked`
+ *   from the gateway.
+ */
+export const INSTANCE_BRIDGE_PROTOCOL_VERSION = 3;
+/** Protocol versions this build can talk to. */
+export const SUPPORTED_BRIDGE_PROTOCOL_VERSIONS = Object.freeze([INSTANCE_BRIDGE_PROTOCOL_VERSION]);
+export function isBridgeProtocolCompatible(version) {
+    return SUPPORTED_BRIDGE_PROTOCOL_VERSIONS.includes(version);
+}
+/**
+ * Set by the gateway on the instance child process; marks the process as a supervised instance.
+ * Its value is the gateway's {@link INSTANCE_BRIDGE_PROTOCOL_VERSION}, so the instance can
+ * refuse an incompatible gateway before it starts anything.
+ */
+export const INSTANCE_CHILD_ENV = 'ZHIN_RUNTIME_CHILD';
+/**
+ * Set by the gateway on the instance child process: the gateway's local control endpoint (socket
+ * path — including the `os.tmpdir()` fallback for deep project roots — or named pipe). Whoever
+ * connects to it is the local owner (ADR 0054 §6), so the instance keeps the Agent's file and
+ * shell tools away from it. Absent when the gateway runs without a local socket.
+ */
+export const GATEWAY_SOCKET_ENV = 'ZHIN_GATEWAY_SOCKET';
+export class BridgeProtocolMismatchError extends Error {
+    peerVersion;
+    side;
+    code = 'ZHIN_BRIDGE_PROTOCOL_MISMATCH';
+    constructor(peerVersion, side) {
+        super(`${side === 'gateway' ? 'Gateway' : 'Instance'} control channel protocol ${peerVersion} is not supported `
+            + `(this build speaks ${SUPPORTED_BRIDGE_PROTOCOL_VERSIONS.join(', ')}); upgrade zhin.js and @zhin.js/gateway together`);
+        this.peerVersion = peerVersion;
+        this.side = side;
+        this.name = 'BridgeProtocolMismatchError';
+    }
+}
+export const DEFAULT_BRIDGE_LIMITS = Object.freeze({
+    maxChunkBytes: 64 * 1024,
+    initialCreditBytes: 256 * 1024,
+    maxHeadBytes: 64 * 1024,
+    maxWsMessageBytes: 16 * 1024 * 1024,
+    maxWsBufferedBytes: 32 * 1024 * 1024,
+    maxStreams: 4096,
+    maxRoutes: 4096,
+});
+/** Gateway: time to wait for a response head before failing with `timeout`. */
+export const DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS = 120_000;
+/** Gateway: time to wait for `ws.accepted` / `ws.rejected`. */
+export const DEFAULT_BRIDGE_WS_OPEN_TIMEOUT_MS = 30_000;
+const MAX_ID_LENGTH = 64;
+const MAX_TEXT_LENGTH = 1024;
+export const EMPTY_ROUTE_TABLE = Object.freeze({
+    revision: 0,
+    apiBase: '/api',
+    http: Object.freeze([]),
+    ws: Object.freeze([]),
+});
+// ---- validation (messages are untrusted on both ends)
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFiniteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isText(value, max = MAX_TEXT_LENGTH) {
+    return typeof value === 'string' && value.length <= max;
+}
+function hasValidId(message) {
+    return message.id === undefined || (typeof message.id === 'string' && message.id.length > 0 && message.id.length <= MAX_ID_LENGTH);
+}
+function hasStreamId(message) {
+    return typeof message.id === 'string' && message.id.length > 0 && message.id.length <= MAX_ID_LENGTH;
+}
+/** Bytes a head occupies (UTF-16 length; ASCII headers are exact). */
+export function headSize(url, headers) {
+    let size = url.length;
+    for (const [name, value] of headers)
+        size += name.length + value.length + 4;
+    return size;
+}
+function isHeaders(value, limits, extra = 0) {
+    if (!Array.isArray(value))
+        return false;
+    let size = extra;
+    for (const entry of value) {
+        if (!Array.isArray(entry) || entry.length !== 2)
+            return false;
+        if (typeof entry[0] !== 'string' || typeof entry[1] !== 'string')
+            return false;
+        size += entry[0].length + entry[1].length + 4;
+        if (size > limits.maxHeadBytes)
+            return false;
+    }
+    return true;
+}
+function isChunk(value, limits) {
+    return value instanceof Uint8Array && value.byteLength <= limits.maxChunkBytes;
+}
+function isCredit(payload) {
+    return Number.isSafeInteger(payload.bytes) && payload.bytes > 0;
+}
+/** Upper bound of the UTF-8 size of a text frame. */
+export function wsMessageSize(data) {
+    return typeof data === 'string' ? data.length * 3 : data.byteLength;
+}
+function isWsData(value, limits) {
+    if (typeof value === 'string')
+        return value.length <= limits.maxWsMessageBytes;
+    return value instanceof Uint8Array && value.byteLength <= limits.maxWsMessageBytes;
+}
+function isWsClose(payload) {
+    return Number.isSafeInteger(payload.code) && payload.code >= 1000 && payload.code <= 4999
+        && isText(payload.reason, 123);
+}
+function isAddress(value) {
+    if (!isRecord(value))
+        return false;
+    return isText(value.host) && Number.isSafeInteger(value.port) && (value.protocol === 'http' || value.protocol === 'https')
+        && typeof value.secure === 'boolean' && isText(value.origin);
+}
+/** Validates a principal forwarded by the gateway; `undefined` when malformed. */
+export function parseBridgePrincipal(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.kind === 'bootstrap') {
+        return typeof value.open === 'boolean' ? Object.freeze({ kind: 'bootstrap', open: value.open }) : undefined;
+    }
+    if (value.kind !== 'user' && value.kind !== 'api-token')
+        return undefined;
+    if (!isText(value.userId) || !isText(value.username) || !isText(value.displayName) || !isText(value.credentialId))
+        return undefined;
+    if (!Array.isArray(value.roles) || !value.roles.every((role) => isText(role)))
+        return undefined;
+    if (!Array.isArray(value.grants) || value.grants.length > 1024)
+        return undefined;
+    const grants = [];
+    for (const grant of value.grants) {
+        if (!isRecord(grant) || !isRecord(grant.scope))
+            return undefined;
+        if (grant.role !== undefined && !isText(grant.role))
+            return undefined;
+        const scope = grant.scope;
+        let parsedScope;
+        if (scope.kind === 'global')
+            parsedScope = Object.freeze({ kind: 'global' });
+        else if ((scope.kind === 'adapter' || scope.kind === 'endpoint') && isText(scope.key)) {
+            parsedScope = Object.freeze({ kind: scope.kind, key: scope.key });
+        }
+        else
+            return undefined;
+        if (!Array.isArray(grant.permissions) || !grant.permissions.every((permission) => isText(permission)))
+            return undefined;
+        grants.push(Object.freeze({
+            ...(grant.role !== undefined ? { role: grant.role } : {}),
+            scope: parsedScope,
+            permissions: Object.freeze([...grant.permissions]),
+        }));
+    }
+    return Object.freeze({
+        kind: value.kind,
+        userId: value.userId,
+        username: value.username,
+        displayName: value.displayName,
+        credentialId: value.credentialId,
+        grants: Object.freeze(grants),
+        roles: Object.freeze([...value.roles]),
+    });
+}
+function isRouteTable(value, limits) {
+    if (!isRecord(value))
+        return false;
+    if (!Number.isSafeInteger(value.revision) || value.revision < 0)
+        return false;
+    if (value.generation !== undefined && !isFiniteNonNegative(value.generation))
+        return false;
+    if (!isText(value.apiBase))
+        return false;
+    if (!Array.isArray(value.http) || !Array.isArray(value.ws))
+        return false;
+    if (value.http.length + value.ws.length > limits.maxRoutes)
+        return false;
+    for (const route of value.http) {
+        if (!isRecord(route) || !isText(route.method, 16) || !isText(route.pattern, 2048))
+            return false;
+        if (route.meta !== undefined && !isRecord(route.meta))
+            return false;
+    }
+    for (const route of value.ws) {
+        if (!isRecord(route) || !isText(route.path, 2048) || (route.auth !== 'host' && route.auth !== 'protocol'))
+            return false;
+    }
+    return true;
+}
+const MAX_CATALOG_ENTRIES = 4096;
+const PLUGIN_PERMISSION_LEVELS = new Set(['read', 'operate', 'manage']);
+function isCatalogEntry(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isText(value.id, 256) || !PLUGIN_PERMISSION_LEVELS.has(value.level) || typeof value.declared !== 'boolean')
+        return false;
+    if (value.description !== undefined && !isText(value.description))
+        return false;
+    return Array.isArray(value.owners) && value.owners.length <= 256 && value.owners.every((owner) => isText(owner, 256));
+}
+function isAuditEntry(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isText(value.actor, 256) || !isText(value.action, 512))
+        return false;
+    if (value.outcome !== 'ok' && value.outcome !== 'denied' && value.outcome !== 'error')
+        return false;
+    if (value.target !== undefined && !isText(value.target, 512))
+        return false;
+    if (value.ip !== undefined && !isText(value.ip, 256))
+        return false;
+    if (value.detail !== undefined && !isRecord(value.detail))
+        return false;
+    return true;
+}
+function isOptionalPrincipal(value) {
+    return value === undefined || parseBridgePrincipal(value) !== undefined;
+}
+function isOptionalRemote(value) {
+    return value === undefined || isText(value, 256);
+}
+/** Validates an untrusted message received from the instance. */
+export function parseInstanceMessage(value, limits = DEFAULT_BRIDGE_LIMITS) {
+    if (!isRecord(value) || !hasValidId(value) || !isRecord(value.payload))
+        return undefined;
+    const payload = value.payload;
+    switch (value.type) {
+        case 'ready':
+            if (!Number.isSafeInteger(payload.version))
+                return undefined;
+            if (!Number.isSafeInteger(payload.pid))
+                return undefined;
+            if (payload.generation !== undefined && !isFiniteNonNegative(payload.generation))
+                return undefined;
+            if (payload.routes !== undefined && !isRouteTable(payload.routes, limits))
+                return undefined;
+            return value;
+        case 'restart-request':
+            if (typeof payload.reason !== 'string')
+                return undefined;
+            return value;
+        case 'routes':
+            return isRouteTable(payload.table, limits) ? value : undefined;
+        case 'catalog': {
+            const list = payload.pluginPermissions;
+            if (!Array.isArray(list) || list.length > MAX_CATALOG_ENTRIES || !list.every(isCatalogEntry))
+                return undefined;
+            return value;
+        }
+        case 'audit':
+            return isAuditEntry(payload.entry) ? value : undefined;
+        default:
+            break;
+    }
+    if (!hasStreamId(value))
+        return undefined;
+    switch (value.type) {
+        case 'http.response.head':
+            if (!Number.isSafeInteger(payload.status) || payload.status < 200 || payload.status > 599)
+                return undefined;
+            if (payload.statusText !== undefined && !isText(payload.statusText))
+                return undefined;
+            if (typeof payload.body !== 'boolean' || !isHeaders(payload.headers, limits))
+                return undefined;
+            return value;
+        case 'http.response.body':
+            return isChunk(payload.chunk, limits) ? value : undefined;
+        case 'http.response.end':
+        case 'ws.accepted':
+            return value;
+        case 'http.response.error':
+            return isText(payload.message) ? value : undefined;
+        case 'http.request.credit':
+        case 'ws.drain':
+            return isCredit(payload) ? value : undefined;
+        case 'ws.rejected':
+            return [401, 403, 404, 503].includes(payload.status) ? value : undefined;
+        case 'ws.message':
+            return isWsData(payload.data, limits) ? value : undefined;
+        case 'ws.close':
+            return isWsClose(payload) ? value : undefined;
+        default:
+            return undefined;
+    }
+}
+/** Validates an untrusted message received from the gateway. */
+export function parseGatewayMessage(value, limits = DEFAULT_BRIDGE_LIMITS) {
+    if (!isRecord(value) || !hasValidId(value) || !isRecord(value.payload))
+        return undefined;
+    const payload = value.payload;
+    switch (value.type) {
+        case 'shutdown':
+            if (typeof payload.reason !== 'string' || !isFiniteNonNegative(payload.budgetMs))
+                return undefined;
+            return value;
+        case 'host.addresses':
+            if (!Array.isArray(payload.addresses) || payload.addresses.length > 64 || !payload.addresses.every(isAddress))
+                return undefined;
+            return value;
+        case 'principal-revoked':
+            if (!isText(payload.principalId) || payload.principalId.length === 0)
+                return undefined;
+            if (payload.reason !== undefined && !isText(payload.reason, 64))
+                return undefined;
+            return value;
+        default:
+            break;
+    }
+    if (!hasStreamId(value))
+        return undefined;
+    switch (value.type) {
+        case 'http.request':
+            if (!isText(payload.method, 16) || !/^[A-Za-z]+$/u.test(payload.method))
+                return undefined;
+            if (!isText(payload.url, limits.maxHeadBytes) || typeof payload.body !== 'boolean')
+                return undefined;
+            if (!isHeaders(payload.headers, limits, payload.url.length))
+                return undefined;
+            if (!isOptionalPrincipal(payload.principal) || !isOptionalRemote(payload.remoteAddress))
+                return undefined;
+            return value;
+        case 'ws.open':
+            if (!isText(payload.url, limits.maxHeadBytes) || !isHeaders(payload.headers, limits, payload.url.length))
+                return undefined;
+            if (!isOptionalPrincipal(payload.principal) || !isOptionalRemote(payload.remoteAddress))
+                return undefined;
+            return value;
+        case 'http.request.body':
+            return isChunk(payload.chunk, limits) ? value : undefined;
+        case 'http.request.end':
+            return value;
+        case 'http.request.abort':
+            return isText(payload.message) ? value : undefined;
+        case 'http.response.credit':
+        case 'ws.drain':
+            return isCredit(payload) ? value : undefined;
+        case 'ws.message':
+            return isWsData(payload.data, limits) ? value : undefined;
+        case 'ws.close':
+            return isWsClose(payload) ? value : undefined;
+        default:
+            return undefined;
+    }
+}
+/** Headers as a bridge header list (repeated `set-cookie` stays separate). */
+export function toBridgeHeaders(headers) {
+    const list = [];
+    for (const [name, value] of headers)
+        list.push([name, value]);
+    return list;
+}
+export function fromBridgeHeaders(list) {
+    const headers = new Headers();
+    for (const [name, value] of list) {
+        try {
+            headers.append(name, value);
+        }
+        catch { /* not a valid Fetch header: skip */ }
+    }
+    return headers;
+}

package/lib/console-events.d.ts

@@ -1,10 +1,12 @@
-import type { ServerResponse } from 'node:http';
+import type { HttpResponseStream } from '@zhin.js/host-http-contract';
 import type { ConsoleEventEnvelope, ConsoleEventHistoryPage, ConsoleEventHistoryQuery, ConsoleEventPayloadMap, KnownConsoleEventType } from '@zhin.js/console-protocol';
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
- * 单进程内 fan-out：`publish` 向所有已订阅的 SSE response 写帧；
+ * 单进程内 fan-out：`publish` 向所有已订阅的 SSE 响应流写帧；
  * write 失败或连接断开自动摘除订阅。
  */
+/** The SSE response body a subscriber reads from (`createResponseStream()`). */
+export type ConsoleEventSink = Pick<HttpResponseStream, 'write' | 'onDrain' | 'onClose' | 'error'>;
 export interface ConsoleEventSubscriptionOptions {
     readonly runtimeId?: string;
     readonly after?: number;
@@ -15,7 +17,7 @@ export interface ConsoleEventHub {
     /** In-process delivery for trusted Host bridges such as Device Protocol. */
     listen(listener: (event: ConsoleEventEnvelope) => void): () => void;
     /** Atomically replay the resumable suffix, then join live fan-out. */
-    subscribe(response: ServerResponse, options?: ConsoleEventSubscriptionOptions): () => void;
+    subscribe(sink: ConsoleEventSink, options?: ConsoleEventSubscriptionOptions): () => void;
     readonly runtimeId: string;
     readonly subscriberCount: number;
 }