@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/node/node-http.js

@@ -0,0 +1,272 @@
+import { WebSocket } from 'ws';
+const BODYLESS_METHODS = new Set(['GET', 'HEAD']);
+/** Headers of a Node request as a Web `Headers` (repeated headers preserved). */
+export function nodeRequestHeaders(request) {
+    const headers = new Headers();
+    const raw = request.rawHeaders;
+    for (let index = 0; index + 1 < raw.length; index += 2) {
+        const name = raw[index];
+        if (name.startsWith(':'))
+            continue;
+        try {
+            headers.append(name, raw[index + 1]);
+        }
+        catch { /* invalid for the Fetch API: skip */ }
+    }
+    return 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 function createNodeRequest(request, options) {
+    const method = (request.method ?? 'GET').toUpperCase();
+    const body = BODYLESS_METHODS.has(method) ? null : nodeBodyStream(request, options.highWaterMark ?? 65_536);
+    return new Request(options.url, {
+        method,
+        headers: nodeRequestHeaders(request),
+        ...(body ? { body, duplex: 'half' } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+function nodeBodyStream(request, highWaterMark) {
+    let settled = false;
+    let cancelled = false;
+    return new ReadableStream({
+        start(controller) {
+            request.on('data', (chunk) => {
+                if (cancelled)
+                    return;
+                const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+                controller.enqueue(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+                if ((controller.desiredSize ?? 0) <= 0)
+                    request.pause();
+            });
+            request.once('end', () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!cancelled)
+                    controller.close();
+            });
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!cancelled)
+                    controller.error(error);
+            };
+            request.once('error', fail);
+            request.once('close', () => {
+                if (!request.complete)
+                    fail(new Error('Request aborted'));
+            });
+            request.pause();
+        },
+        pull() {
+            request.resume();
+        },
+        cancel() {
+            // Discard the rest instead of destroying the socket.
+            cancelled = true;
+            request.resume();
+        },
+    }, new ByteLengthQueuingStrategy({ highWaterMark }));
+}
+/**
+ * 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 async function writeNodeResponse(target, response) {
+    target.statusCode = response.status;
+    if (response.statusText)
+        target.statusMessage = response.statusText;
+    const cookies = response.headers.getSetCookie();
+    for (const [name, value] of response.headers) {
+        if (name === 'set-cookie')
+            continue;
+        target.setHeader(name, value);
+    }
+    if (cookies.length > 0)
+        target.setHeader('set-cookie', cookies);
+    const body = response.body;
+    if (!body) {
+        target.end();
+        return;
+    }
+    const reader = body.getReader();
+    let disconnected = false;
+    let cancelled;
+    const onClose = () => {
+        if (target.writableFinished)
+            return;
+        disconnected = true;
+        cancelled = reader.cancel(new Error('Client disconnected')).catch(() => undefined);
+    };
+    target.once('close', onClose);
+    try {
+        let read = reader.read();
+        let first = await raceImmediate(read);
+        if (first === PENDING) {
+            // Nothing to send yet (SSE): commit the headers now.
+            target.flushHeaders();
+            first = await read;
+        }
+        if (first.done) {
+            target.end();
+            return;
+        }
+        let chunk = first.value;
+        read = reader.read();
+        const second = await raceImmediate(read);
+        if (second !== PENDING && second.done) {
+            target.end(chunk);
+            return;
+        }
+        for (;;) {
+            if (disconnected || target.destroyed)
+                return;
+            if (!target.write(chunk))
+                await waitForDrain(target);
+            if (disconnected || target.destroyed)
+                return;
+            const next = await read;
+            if (next.done)
+                break;
+            chunk = next.value;
+            read = reader.read();
+        }
+        if (!target.destroyed)
+            target.end();
+    }
+    catch (error) {
+        if (!disconnected && !target.destroyed)
+            target.destroy(error instanceof Error ? error : new Error(String(error)));
+    }
+    finally {
+        target.off('close', onClose);
+        // A disconnect cancels the body: let its source finish cleaning up first.
+        await cancelled;
+        try {
+            reader.releaseLock();
+        }
+        catch { /* read still pending after disconnect */ }
+    }
+}
+const PENDING = Symbol('pending');
+/** Settles with the promise's value if it is ready before the next macrotask, else PENDING. */
+function raceImmediate(promise) {
+    return new Promise((resolve, reject) => {
+        const timer = setImmediate(() => resolve(PENDING));
+        promise.then((value) => {
+            clearImmediate(timer);
+            resolve(value);
+        }, (error) => {
+            clearImmediate(timer);
+            reject(error);
+        });
+    });
+}
+function waitForDrain(target) {
+    return new Promise((resolve) => {
+        const done = () => {
+            target.off('drain', done);
+            target.off('close', done);
+            resolve();
+        };
+        target.once('drain', done);
+        target.once('close', done);
+    });
+}
+/** A {@link WsTransport} over a `ws` server socket. */
+export function wrapNodeWebSocket(socket, options = {}) {
+    const messageListeners = new Set();
+    const closeListeners = new Set();
+    let closedWith;
+    socket.on('message', (data, isBinary) => {
+        const value = isBinary ? rawBytes(data) : rawBytes(data).toString('utf8');
+        for (const listener of [...messageListeners]) {
+            try {
+                listener(value);
+            }
+            catch { /* isolate listener failures */ }
+        }
+    });
+    socket.on('error', () => { });
+    let alive = true;
+    const keepAliveMs = options.keepAliveMs ?? 30_000;
+    const timer = keepAliveMs > 0
+        ? setInterval(() => {
+            if (!alive) {
+                socket.terminate();
+                return;
+            }
+            alive = false;
+            try {
+                socket.ping();
+            }
+            catch { /* closing */ }
+        }, keepAliveMs)
+        : undefined;
+    timer?.unref?.();
+    socket.on('pong', () => { alive = true; });
+    socket.once('close', (code, reason) => {
+        if (timer)
+            clearInterval(timer);
+        closedWith = { code, reason: reason.toString('utf8') };
+        messageListeners.clear();
+        for (const listener of [...closeListeners]) {
+            try {
+                listener(closedWith.code, closedWith.reason);
+            }
+            catch { /* isolate listener failures */ }
+        }
+        closeListeners.clear();
+    });
+    return {
+        send(data) {
+            if (socket.readyState !== WebSocket.OPEN)
+                return;
+            socket.send(data);
+        },
+        close(code, reason) {
+            if (socket.readyState === WebSocket.CLOSING || socket.readyState === WebSocket.CLOSED)
+                return;
+            try {
+                socket.close(code, reason);
+            }
+            catch {
+                socket.terminate();
+            }
+        },
+        onMessage(listener) {
+            if (closedWith)
+                return () => undefined;
+            messageListeners.add(listener);
+            return () => { messageListeners.delete(listener); };
+        },
+        onClose(listener) {
+            if (closedWith) {
+                const { code, reason } = closedWith;
+                queueMicrotask(() => listener(code, reason));
+                return () => undefined;
+            }
+            closeListeners.add(listener);
+            return () => { closeListeners.delete(listener); };
+        },
+        get bufferedAmount() {
+            return socket.bufferedAmount;
+        },
+    };
+}
+function rawBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    return Buffer.from(data);
+}

package/lib/node/server.d.ts

@@ -0,0 +1,13 @@
+import { type GenerationAdmissionBindable } from '@zhin.js/plugin-runtime';
+import { type HttpHost } from '../http-host.js';
+import type { HttpHostAddress, HttpHostOptions } from '../host-options.js';
+/** @internal Process-root lifecycle and generation admission surface. */
+export interface ProcessHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+}
+/**
+ * In-process Node listener for the transport-independent router: Node requests become
+ * Web `Request`s, `Response`s are streamed back, `ws` sockets become `WsConnection`s.
+ */
+export declare function createHttpHost(options?: HttpHostOptions): ProcessHttpHost;

package/lib/node/server.js

@@ -0,0 +1,64 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
+import { createHttpRouter } from '../http-host.js';
+import { createNodeHttpListener } from './listener.js';
+const logger = getLogger('http');
+/**
+ * In-process Node listener for the transport-independent router: Node requests become
+ * Web `Request`s, `Response`s are streamed back, `ws` sockets become `WsConnection`s.
+ */
+export function createHttpHost(options = {}) {
+    const secure = options.tls !== undefined;
+    let closeResult;
+    const router = createHttpRouter({
+        token: options.token,
+        corsOrigins: options.corsOrigins,
+        apiBase: options.apiBase,
+        authExemptPaths: options.authExemptPaths,
+        tokenRegistry: options.tokenRegistry,
+        secure,
+        address: () => listener.address,
+    });
+    const tokenRegistry = router.tokenRegistry;
+    const listener = createNodeHttpListener({
+        host: options.host,
+        port: options.port,
+        tls: options.tls,
+        trustProxy: options.trustProxy,
+        handle: (request, info) => router.handle(request, info),
+        upgrade: (request) => router.upgrade(request),
+        onListening(address) {
+            logger.info(`listening ${address.origin}`
+                + ` | routes: ${router.routeCount}`
+                + ` | token: ${tokenRegistry.hasAnyToken()
+                    ? tokenRegistry.primaryTokenPrefixForLog()
+                    : '(none)'}`);
+            logger.debug(`listen detail | cors: ${router.corsOrigins.join(',')}`
+                + ` | ws: ${router.wsPaths.join(',') || '(none)'}`);
+        },
+        onClosed() {
+            logger.debug(formatCompact({ op: 'http_host_closed' }));
+        },
+    });
+    const runtime = {
+        [generationAdmissionBinder]: (admission) => router[generationAdmissionBinder](admission),
+        ws: (pathname, wsOptions) => router.ws(pathname, wsOptions),
+        route: (method, path, handler, meta) => router.route(method, path, handler, meta),
+        listRoutes: () => router.listRoutes(),
+        get address() {
+            return listener.address;
+        },
+        get tokenRegistry() {
+            return tokenRegistry;
+        },
+        listen: () => listener.listen(),
+        close() {
+            if (closeResult)
+                return closeResult;
+            router.close();
+            closeResult = listener.close();
+            return closeResult;
+        },
+    };
+    return runtime;
+}

package/lib/protocol-auth.d.ts

@@ -0,0 +1,24 @@
+/** What a protocol credential check needs from an HTTP request or a {@link WsConnection}. */
+export interface ProtocolAuthRequest {
+    readonly headers: Headers;
+    readonly url: URL | string;
+    readonly remoteAddress?: string;
+}
+/** IPv4 / IPv6 / IPv4-mapped loopback peer. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Whether a listen address (`http.host`) only accepts connections from this machine:
+ * `localhost`, `127.0.0.0/8`, `::1` (bracketed or not). `0.0.0.0`, `::` and any other address are
+ * reachable from the network.
+ */
+export declare function isLoopbackHost(host: string | undefined): boolean;
+/**
+ * Access check for a plugin socket mounted with `ws(path, { auth: 'protocol' })` (adapter
+ * reverse WebSockets: OneBot, NapCat, Milky…) or a protocol webhook. With an access token the
+ * peer must present it as `Authorization: Bearer <token>` or `?access_token=<token>`
+ * (constant-time compare); without one only loopback peers are admitted, so an unconfigured
+ * socket is never public. Proxied traffic (`X-Forwarded-For` / `Forwarded` present) never counts
+ * as loopback: a same-host reverse proxy would otherwise make every client local. A {@link WsConnection} can be passed directly; for an HTTP route pass
+ * `{ headers: request.headers, url: context.url, remoteAddress: context.remoteAddress }`.
+ */
+export declare function verifyProtocolAccessToken(accessToken: string | undefined, request: ProtocolAuthRequest): boolean;

package/lib/protocol-auth.js

@@ -0,0 +1,48 @@
+import { timingSafeEqualString } from './timing-safe-equal.js';
+import { hasForwardingHeaders } from './trust-proxy.js';
+/** IPv4 / IPv6 / IPv4-mapped loopback peer. */
+export function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    if (address === '::1')
+        return true;
+    const v4 = address.startsWith('::ffff:') ? address.slice(7) : address;
+    return /^127(?:\.\d{1,3}){3}$/u.test(v4);
+}
+/**
+ * Whether a listen address (`http.host`) only accepts connections from this machine:
+ * `localhost`, `127.0.0.0/8`, `::1` (bracketed or not). `0.0.0.0`, `::` and any other address are
+ * reachable from the network.
+ */
+export function isLoopbackHost(host) {
+    if (host === undefined || host === '')
+        return true; // the listener default is 127.0.0.1
+    const bare = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    return bare.toLowerCase() === 'localhost' || isLoopbackAddress(bare);
+}
+/**
+ * Access check for a plugin socket mounted with `ws(path, { auth: 'protocol' })` (adapter
+ * reverse WebSockets: OneBot, NapCat, Milky…) or a protocol webhook. With an access token the
+ * peer must present it as `Authorization: Bearer <token>` or `?access_token=<token>`
+ * (constant-time compare); without one only loopback peers are admitted, so an unconfigured
+ * socket is never public. Proxied traffic (`X-Forwarded-For` / `Forwarded` present) never counts
+ * as loopback: a same-host reverse proxy would otherwise make every client local. A {@link WsConnection} can be passed directly; for an HTTP route pass
+ * `{ headers: request.headers, url: context.url, remoteAddress: context.remoteAddress }`.
+ */
+export function verifyProtocolAccessToken(accessToken, request) {
+    if (!accessToken)
+        return isLoopbackAddress(request.remoteAddress) && !hasForwardingHeaders(request.headers);
+    const header = request.headers.get('authorization');
+    if (typeof header === 'string' && header.startsWith('Bearer ')
+        && timingSafeEqualString(header.slice(7).trim(), accessToken))
+        return true;
+    let presented = null;
+    try {
+        const url = typeof request.url === 'string' ? new URL(request.url, 'http://localhost') : request.url;
+        presented = url.searchParams.get('access_token');
+    }
+    catch {
+        presented = null;
+    }
+    return presented !== null && timingSafeEqualString(presented, accessToken);
+}

package/lib/public-api.d.ts

@@ -2,6 +2,6 @@
  * Plugin-facing HTTP Host contract exposed from `@zhin.js/host-http`.
  * @module @zhin.js/host-http
  */
-export { httpHostToken, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
+export { httpHostToken, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpRouteRegistration, type RouteContext, type WsConnection, type WsHandle, type WsRouteOptions, } from './http-host.js';
 export type { AuthenticatedTokenPrincipal, AuthScope } from './token-registry.js';
 export type { ListedRoute, OpenApiParameter, RouteMeta } from './openapi.js';

package/lib/token-registry.d.ts

@@ -1,25 +1,13 @@
-/** Demo Host token scope (ADR 0016 subset for Plugin Runtime Host). */
-export type AuthScope = 'full' | 'demo';
-export type ScopedTokenConfig = {
-    readonly token: string;
-    /**
-     * `full` is the operator. `user` is an alias of `demo`: an ordinary Console user who sees and
-     * calls only what its `permissions` / `roles` allow. Stored and reported as `demo`.
-     */
-    readonly scope: AuthScope | 'user';
-    /** Root-configured subject binding; never accepted from an HTTP payload. */
-    readonly principalId?: string;
-    /**
-     * Console permissions held by this token (matched against Page `requiredPermissions`).
-     * Ignored for `full` scope, which already holds every Console permission.
-     */
-    readonly permissions?: readonly string[];
-    /** Console roles held by this token (matched against Page `requiredRoles`). */
-    readonly roles?: readonly string[];
-};
+import { type ConsolePluginPermissionInfo, type ConsolePluginPermissionLevelResolver } from '@zhin.js/console-protocol';
+import { type ConsoleAccessProvider, type ConsolePrincipal, type ConsoleRequestMeta } from './access-control.js';
 /**
- * What a Console caller may see. `unrestricted` is the operator (full scope, or a Host with no
- * tokens configured); otherwise only the listed permissions and roles count.
+ * Scope a Host handler runs with. Every admitted request is `full`: authorization happens
+ * before dispatch against the request's `ConsolePrincipal` (ADR 0049).
+ */
+export type AuthScope = 'full';
+/**
+ * What a Console caller may see. `unrestricted` is an open Host before setup; otherwise only
+ * the listed permissions and roles count.
  */
 export interface ConsoleAccess {
     readonly unrestricted: boolean;
@@ -33,29 +21,59 @@ export interface AuthenticatedTokenPrincipal {
     readonly scope: AuthScope;
 }
 export type TokenRegistryConfig = {
+    /** `http.token`: the bootstrap credential, valid only until the first owner exists. */
     readonly primaryToken?: string;
-    readonly scopedTokens?: readonly ScopedTokenConfig[];
-};
-export type DynamicTokenConfig = ScopedTokenConfig & {
-    /** Unix epoch milliseconds; omitted credentials remain valid until explicitly revoked. */
-    readonly expiresAt?: number;
 };
+/**
+ * Bearer authentication for the Host (ADR 0049).
+ * - Before setup: no credential configured → open; `http.token` → bootstrap (setup only).
+ * - After setup (an enabled global owner exists): only user sessions and API tokens from the
+ *   {@link ConsoleAccessProvider}; `http.token` is rejected everywhere.
+ */
 export declare class TokenRegistry {
     #private;
     constructor(config?: TokenRegistryConfig);
-    resolve(token: string): AuthScope | null;
-    resolvePrincipal(token: string): AuthenticatedTokenPrincipal | null;
+    /** Installs the user/session backend; returns an idempotent uninstaller. */
+    useAccessProvider(provider: ConsoleAccessProvider): () => void;
+    get accessProvider(): ConsoleAccessProvider | undefined;
     /**
-     * Console access for a bearer token. With no tokens configured the Host is local and open,
-     * so every caller is the operator. An unknown or missing token gets public access only.
+     * Installs the plugin permission catalog source (the runtime composition root reads it from
+     * the current generation); returns an idempotent uninstaller.
      */
-    resolveAccess(token: string): ConsoleAccess;
+    usePluginPermissions(source: () => readonly ConsolePluginPermissionInfo[]): () => void;
+    /** Plugin permissions the loaded plugins use or declare, with their levels (empty when none). */
+    pluginPermissions(): readonly ConsolePluginPermissionInfo[];
+    /** Declared-or-inferred level lookup over {@link pluginPermissions}. */
+    pluginPermissionLevels(): ConsolePluginPermissionLevelResolver;
+    /** An enabled global owner exists. */
+    initialized(): boolean;
+    /** Whether `/api` requires a credential (a bootstrap token is configured, or setup is done). */
     hasAnyToken(): boolean;
-    /** Registers a runtime-issued credential and returns an idempotent revoker. */
-    register(config: DynamicTokenConfig): () => void;
-    revoke(token: string): boolean;
+    /** Whether `token` is the bootstrap token and still accepted (setup not done). */
+    isBootstrapToken(token: string): boolean;
+    /** Resolves a bearer to a principal; null when it is not (or no longer) valid. */
+    authenticate(token: string, meta?: ConsoleRequestMeta): Promise<ConsolePrincipal | null>;
+    /**
+     * Bearer check for non-Console protocol surfaces (MCP, A2A): the bootstrap token before
+     * setup, or a user credential holding `permission` globally. An open Host yields false so
+     * the surface keeps its own unauthenticated (loopback) policy.
+     */
+    authorizeBearer(token: string, permission: string, meta?: ConsoleRequestMeta): Promise<boolean>;
+    /**
+     * {@link authorizeBearer} for a principal already resolved from the request's bearer (by this
+     * registry, or by the gateway that forwarded the request): the bootstrap token before setup,
+     * or a user credential holding `permission` globally. An open Host yields false.
+     */
+    authorizePrincipal(principal: ConsolePrincipal | null | undefined, permission: string): boolean;
+    /**
+     * Synchronous explicit-credential check: `full` only for the still-valid bootstrap token.
+     * User credentials need {@link authenticate} (or the request's bound principal).
+     */
+    resolve(token: string): AuthScope | null;
+    /** Console access for a resolved principal. */
+    accessFor(principal: ConsolePrincipal | null | undefined): ConsoleAccess;
+    /** Synchronous legacy access: only an open Host is unrestricted. */
+    resolveAccess(_token: string): ConsoleAccess;
     primaryTokenPrefixForLog(): string;
 }
-/** WebSocket upgrade paths allowed for demo scope. */
-export declare function isDemoWebSocketPath(pathname: string): boolean;
 export declare function extractBearerToken(authorization: string | undefined, queryToken: string | null): string;