@zhin.js/host-http 1.0.14 → 1.0.16

package/lib/console-events.d.ts

@@ -12,11 +12,15 @@ export interface ConsoleEventSubscriptionOptions {
 export interface ConsoleEventHub {
     publish<Type extends string>(type: Type, data: Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown): ConsoleEventEnvelope<Type, Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown>;
     history(query?: ConsoleEventHistoryQuery): ConsoleEventHistoryPage;
+    /** 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;
     readonly runtimeId: string;
     readonly subscriberCount: number;
 }
+/** Shared Console event authority installed by the Plugin Runtime composition root. */
+export declare const consoleEventHubToken: import("@zhin.js/plugin-runtime").Token<ConsoleEventHub>;
 export interface ConsoleEventHubOptions {
     readonly runtimeId?: string;
     readonly historyLimit?: number;

package/lib/console-events.js

@@ -1,4 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import { createToken } from '@zhin.js/plugin-runtime';
+/** Shared Console event authority installed by the Plugin Runtime composition root. */
+export const consoleEventHubToken = createToken('zhin.host.console-events');
 const DEFAULT_HISTORY_LIMIT = 256;
 const DEFAULT_PAGE_LIMIT = 200;
 const MAX_PAGE_LIMIT = 500;
@@ -14,6 +17,7 @@ export function createConsoleEventHub(options = {}) {
     const journal = [];
     let journalBytes = 0;
     const subscribers = new Set();
+    const listeners = new Set();
     const remove = (response) => {
         subscribers.delete(response);
     };
@@ -62,6 +66,12 @@ export function createConsoleEventHub(options = {}) {
                     remove(response);
                 }
             }
+            for (const listener of [...listeners]) {
+                try {
+                    listener(event);
+                }
+                catch { /* isolate trusted bridge failures */ }
+            }
             return event;
         },
         history(query = {}) {
@@ -99,6 +109,10 @@ export function createConsoleEventHub(options = {}) {
                 gap,
             });
         },
+        listen(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
         subscribe(response, options = {}) {
             // Replay and subscription are synchronous relative to publish(), closing
             // the race between HTTP recovery and the live stream hand-off.

package/lib/console-rpc-extended.d.ts

@@ -55,6 +55,18 @@ export interface ConsoleRpcExtendedCtx {
     workroomKnowledgeControl?: ConsoleWorkroomKnowledgeControlPort;
 }
 export interface ConsoleWorkroomProfileControlPort {
+    getPlanningStatus(projectId: string, authenticatedPrincipal?: Readonly<{
+        principalId: string;
+    }>): Promise<unknown>;
+    bootstrapPlanning(command: Readonly<{
+        operationId: string;
+        projectId: string;
+        expectedRegistryRevision: number;
+        includeTools?: readonly string[];
+        includeSkills?: readonly string[];
+    }>, authenticatedPrincipal: Readonly<{
+        principalId: string;
+    }>): Promise<unknown>;
     publishPack(command: Readonly<{
         operationId: string;
         pack: unknown;

package/lib/console-rpc-extended.js

@@ -51,6 +51,8 @@ export async function dispatchExtendedConsoleRpc(type, data, ctx) {
             return listInbox(d, ctx, TABLE_NOTICE, 'notices', mapNoticeRow);
         case 'inbox.messages':
             return listInboxMessages(d, ctx);
+        case 'inbox.recent':
+            return listRecentInboxMessages(d, ctx);
         case 'request.approve':
         case 'request.reject':
             return actOnRequest(type, d, ctx);
@@ -95,6 +97,8 @@ export async function dispatchExtendedConsoleRpc(type, data, ctx) {
             });
         case 'endpoint.delete_friend':
             return deleteFriend(d, ctx);
+        case 'workroom.profile.status':
+        case 'workroom.profile.bootstrap':
         case 'workroom.profile.pack.publish':
         case 'workroom.profile.publish':
         case 'workroom.profile.rollback':
@@ -118,11 +122,31 @@ async function mutateWorkroomProfile(type, data, ctx) {
         if (forbidden in data)
             return { error: `Console Workroom Profile request cannot carry ${forbidden}` };
     }
+    if (type === 'workroom.profile.status') {
+        try {
+            return { data: await control.getPlanningStatus(requiredRpcText(data.projectId, 'projectId'), ctx.authenticatedPrincipal) };
+        }
+        catch (error) {
+            return { error: errorMessage(error) };
+        }
+    }
     const principal = ctx.authenticatedPrincipal;
     if (!principal)
         return { error: 'Workroom Profile control requires an authenticated principal' };
     try {
         const operationId = requiredRpcText(data.operationId, 'operationId');
+        if (type === 'workroom.profile.bootstrap') {
+            const projectId = requiredRpcText(data.projectId, 'projectId');
+            const includeTools = optionalRpcTextArray(data.includeTools, 'includeTools');
+            const includeSkills = optionalRpcTextArray(data.includeSkills, 'includeSkills');
+            return { data: await control.bootstrapPlanning(Object.freeze({
+                    operationId,
+                    projectId,
+                    expectedRegistryRevision: requiredRpcInteger(data.expectedRegistryRevision, 'expectedRegistryRevision', -1),
+                    ...(includeTools ? { includeTools } : {}),
+                    ...(includeSkills ? { includeSkills } : {}),
+                }), principal) };
+        }
         if (type === 'workroom.profile.pack.publish') {
             return { data: await control.publishPack(Object.freeze({ operationId, pack: requiredRpcValue(data.pack, 'pack') }), principal) };
         }
@@ -205,6 +229,16 @@ function requiredRpcText(value, name) {
 function optionalRpcText(value, name) {
     return value === undefined ? undefined : requiredRpcText(value, name);
 }
+function optionalRpcTextArray(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error(`${name} is invalid`);
+    const result = value.map((item, index) => requiredRpcText(item, `${name}.${index}`));
+    if (new Set(result).size !== result.length)
+        throw new Error(`${name} contains duplicates`);
+    return Object.freeze(result);
+}
 function requiredRpcInteger(value, name, minimum = 1) {
     if (!Number.isSafeInteger(value) || Number(value) < minimum)
         throw new Error(`${name} is invalid`);
@@ -472,6 +506,47 @@ async function listInboxMessages(d, ctx) {
     }));
     return { data: { messages, inboxEnabled: enabled } };
 }
+/**
+ * Cross-endpoint recent inbox used by paired Mobile Console clients.
+ * Unlike endpoint-detail `inbox.messages`, every row carries its complete
+ * routable address so selecting a conversation can safely call
+ * `endpoint.send_message` through the Device Protocol write allowlist.
+ */
+async function listRecentInboxMessages(d, ctx) {
+    const limit = boundedIntegerField(d, 50, 1, 100, '$limit', 'limit');
+    const [messagePage, requestPage] = await Promise.all([
+        readInboxRows(ctx, TABLE_MESSAGE, {}, {
+            orderBy: { field: 'created_at', direction: 'DESC' }, limit,
+        }),
+        readInboxRows(ctx, TABLE_REQUEST, { resolved: 0 }, {
+            orderBy: { field: 'created_at', direction: 'DESC' }, limit,
+        }),
+    ]);
+    const messages = messagePage.rows
+        .slice()
+        .sort((left, right) => Number(right.created_at ?? 0) - Number(left.created_at ?? 0))
+        .slice(0, limit)
+        .map(row => ({
+        id: row.id,
+        adapter: row.adapter,
+        endpoint_id: row.endpoint_id,
+        platform_message_id: row.platform_message_id,
+        sender_id: row.sender_id,
+        sender_name: row.sender_name,
+        content: row.content,
+        raw: row.raw,
+        created_at: row.created_at,
+        channel: channelFromStoredRow(row),
+        parent: parentFromStoredRow(row),
+    }));
+    const requests = requestPage.rows
+        .filter(row => Number(row.resolved ?? 0) === 0)
+        .slice()
+        .sort((left, right) => Number(right.created_at ?? 0) - Number(left.created_at ?? 0))
+        .slice(0, limit)
+        .map(row => ({ ...mapRequestRow(row), adapter: row.adapter, endpoint_id: row.endpoint_id }));
+    return { data: { messages, requests, inboxEnabled: messagePage.enabled || requestPage.enabled } };
+}
 function mapRequestRow(row) {
     const actorId = row.actor_id;
     const actorName = row.actor_name ?? undefined;
@@ -580,6 +655,12 @@ async function actOnRequest(type, d, ctx) {
             ? strField(d, '$remark', 'remark')
             : strField(d, '$reason', 'reason');
         await method.call(management, requestId, extra || undefined);
+        const model = getInboxModel(ctx, TABLE_REQUEST);
+        if (model && typeof model.update === 'function') {
+            await model.update({ resolved: 1, resolved_at: Date.now() }).where({
+                adapter, endpoint_id: endpointKey, platform_request_id: requestId,
+            });
+        }
         return { data: { success: true } };
     });
 }

package/lib/console-rpc.d.ts

@@ -50,6 +50,10 @@ export type RuntimeConsoleRpcContext = {
     setConfigKey?(pluginName: string, data: unknown): Promise<{
         restartRequired: boolean;
     }>;
+    /** Persist a declared child Plugin lifecycle state. Takes effect after restart. */
+    setPluginEnabled?(instanceKey: string, enabled: boolean): Promise<Readonly<{
+        disabled: readonly string[];
+    }>>;
     /** Atomic, revision-checked runtime Workroom Catalog read/write. */
     readWorkroomCatalog?(): Promise<Readonly<{
         agents: Readonly<Record<string, unknown>>;

package/lib/console-rpc.js

@@ -661,6 +661,42 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
             }
             return payloads;
         }
+        case 'plugin:set-enabled': {
+            try {
+                const instanceKey = typeof message.instanceKey === 'string' ? message.instanceKey : '';
+                const enabled = message.enabled;
+                if (!instanceKey || typeof enabled !== 'boolean') {
+                    emit({ requestId, error: 'instanceKey and boolean enabled are required' });
+                    return payloads;
+                }
+                if (!ctx.setPluginEnabled) {
+                    emit({ requestId, error: 'Plugin lifecycle management is not configured' });
+                    return payloads;
+                }
+                const lifecycle = await ctx.setPluginEnabled(instanceKey, enabled);
+                ctx.publishEvent?.('plugin:lifecycle-updated', { instanceKey, enabled });
+                emit({
+                    requestId,
+                    data: {
+                        success: true,
+                        instanceKey,
+                        enabled,
+                        disabled: lifecycle.disabled,
+                        restartRequired: true,
+                        message: `${instanceKey} 已${enabled ? '启用' : '停用'}，Host 正在重启`,
+                    },
+                });
+                if (ctx.requestRestart) {
+                    setTimeout(() => {
+                        void Promise.resolve(ctx.requestRestart?.()).catch(() => undefined);
+                    }, 500);
+                }
+            }
+            catch (error) {
+                emit({ requestId, error: error instanceof Error ? error.message : String(error) });
+            }
+            return payloads;
+        }
         default:
             if (type.startsWith('db:')) {
                 emit({

package/lib/http-host.d.ts

@@ -1,4 +1,5 @@
 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';
@@ -13,9 +14,27 @@ export interface WsHandle {
     onConnection(listener: (connection: WsConnection) => void): () => void;
     close(): void;
 }
+export interface WsRouteOptions {
+    /**
+     * `host` applies the Host Bearer-token registry before upgrade. `protocol`
+     * leaves upgrade authentication to the registered application protocol.
+     */
+    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;
 }
 export interface HttpHostOptions {
     readonly host?: string;
@@ -33,6 +52,8 @@ 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;
 }
 export type HttpHandler = (request: IncomingMessage, response: ServerResponse, url: URL, authScope: AuthScope, authenticatedPrincipal?: AuthenticatedTokenPrincipal) => void | Promise<void>;
 export interface HttpRouteRegistration {
@@ -40,7 +61,7 @@ export interface HttpRouteRegistration {
 }
 /** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
 export interface HttpHost {
-    ws(path: string): WsHandle;
+    ws(path: string, options?: WsRouteOptions): WsHandle;
     route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
     listRoutes(): readonly ListedRoute[];
     get address(): HttpHostAddress | undefined;

package/lib/http-host.js

@@ -1,4 +1,5 @@
-import { createServer, } from 'node:http';
+import { createServer as createHttpServer, } from 'node:http';
+import { createServer as createHttpsServer, } from 'node:https';
 import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
@@ -29,9 +30,13 @@ export function createHttpHost(options = {}) {
     let address;
     let closed = false;
     let closeResult;
-    const server = createServer((request, response) => {
+    const secure = options.tls !== undefined;
+    const handleRequest = (request, response) => {
         void dispatchHttp(request, response);
-    });
+    };
+    const server = secure
+        ? createHttpsServer(options.tls, handleRequest)
+        : createHttpServer(handleRequest);
     // Track live TCP sockets so close() can destroy long-lived connections
     // (SSE /api/events, keep-alive) that would otherwise block server.close().
     const sockets = new Set();
@@ -66,7 +71,7 @@ export function createHttpHost(options = {}) {
         meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
         handler: (request, response) => {
             const hostHeader = headerValue(request.headers.host) ?? 'localhost';
-            const proto = headerValue(request.headers['x-forwarded-proto']) ?? 'http';
+            const proto = headerValue(request.headers['x-forwarded-proto']) ?? (secure ? 'https' : 'http');
             writeJson(response, 200, buildOpenApiDocument(listListedRoutes(), {
                 apiBase,
                 serverUrl: `${proto}://${hostHeader}`,
@@ -92,7 +97,10 @@ export function createHttpHost(options = {}) {
             socket.destroy();
             return;
         }
-        const auth = authenticateUpgrade(request, pathname);
+        const protocolAuthenticated = admitted.every(({ entry }) => entry.options.auth === 'protocol');
+        const auth = protocolAuthenticated
+            ? { ok: true, scope: 'full' }
+            : authenticateUpgrade(request, pathname);
         if (!auth.ok) {
             socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
             socket.destroy();
@@ -286,7 +294,7 @@ export function createHttpHost(options = {}) {
             meta: route.meta,
         })));
     }
-    function registerWs(pathname, admission) {
+    function registerWs(pathname, admission, options = {}) {
         const normalized = normalizePath(pathname);
         let listeners = wsRoutes.get(normalized);
         if (!listeners) {
@@ -296,7 +304,7 @@ export function createHttpHost(options = {}) {
         const owned = new Set();
         return {
             onConnection(listener) {
-                const entry = Object.freeze({ listener, admission });
+                const entry = Object.freeze({ listener, admission, options: Object.freeze({ ...options }) });
                 listeners.add(entry);
                 owned.add(entry);
                 return () => {
@@ -335,7 +343,7 @@ export function createHttpHost(options = {}) {
     function createBoundHost(admission) {
         const bound = {
             [generationAdmissionBinder]: (next) => createBoundHost(next),
-            ws: (path) => registerWs(path, admission),
+            ws: (path, options) => registerWs(path, admission, options),
             route: (method, path, handler, meta) => registerRoute(method, path, handler, meta, admission),
             listRoutes: () => listListedRoutes(),
             get address() { return runtime.address; },
@@ -345,7 +353,7 @@ export function createHttpHost(options = {}) {
     }
     const runtime = {
         [generationAdmissionBinder]: (admission) => createBoundHost(admission),
-        ws: (pathname) => registerWs(pathname),
+        ws: (pathname, options) => registerWs(pathname, undefined, options),
         route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
         listRoutes() {
             return listListedRoutes();
@@ -366,8 +374,13 @@ export function createHttpHost(options = {}) {
                     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;
-                    address = Object.freeze({ host: publicHost, port: listenPort });
-                    logger.info(`listening http://${publicHost}:${listenPort}`
+                    const protocol = secure ? 'https' : 'http';
+                    const originHost = publicHost.includes(':') ? `[${publicHost}]` : publicHost;
+                    address = Object.freeze({
+                        host: publicHost, port: listenPort, protocol, secure,
+                        origin: `${protocol}://${originHost}:${listenPort}`,
+                    });
+                    logger.info(`listening ${address.origin}`
                         + ` | routes: ${httpRoutes.length}`
                         + ` | token: ${tokenRegistry.hasAnyToken()
                             ? `${tokenRegistry.primaryTokenPrefixForLog()}…`

package/lib/index.d.ts

@@ -1,7 +1,8 @@
-export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type ProcessHttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
-export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, type AuthenticatedTokenPrincipal, type AuthScope, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
+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, type AuthenticatedTokenPrincipal, type AuthScope, type DynamicTokenConfig, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
-export { createConsoleEventHub, type ConsoleEventHub, } from './console-events.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 RuntimeEndpointSummary, } from './console-rpc.js';

package/lib/index.js

@@ -1,7 +1,8 @@
 export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
+export { createHttpHostGroup, listHttpHostAddresses, } from './listener-group.js';
 export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
-export { createConsoleEventHub, } from './console-events.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';

package/lib/listener-group.d.ts

@@ -0,0 +1,9 @@
+import { type HttpHost, type HttpHostAddress, type HttpHostOptions, type ProcessHttpHost } from './http-host.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

@@ -0,0 +1,88 @@
+import { bindGenerationAdmission, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
+import { createHttpHost, } from './http-host.js';
+const addressProvider = Symbol('HttpHostAddressProvider');
+/**
+ * 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 function createHttpHostGroup(options) {
+    if (options.length === 0)
+        throw new Error('HttpHostGroup requires at least one listener');
+    const listeners = options.map((entry) => createHttpHost(entry));
+    const createSurface = (hosts) => {
+        const primary = hosts[0];
+        const surface = {
+            [generationAdmissionBinder](admission) {
+                return createSurface(hosts.map((host) => bindGenerationAdmission(host, admission)));
+            },
+            [addressProvider]: () => listeners.flatMap((host) => host.address ? [host.address] : []),
+            ws(path, wsOptions) {
+                const handles = hosts.map((host) => host.ws(path, wsOptions));
+                return {
+                    onConnection(listener) {
+                        const disposers = handles.map((handle) => handle.onConnection(listener));
+                        return () => { for (const dispose of disposers.reverse())
+                            dispose(); };
+                    },
+                    close() { for (const handle of handles)
+                        handle.close(); },
+                };
+            },
+            route(method, path, handler, meta) {
+                const disposers = hosts.map((host) => host.route(method, path, handler, meta));
+                return () => { for (const dispose of disposers.reverse())
+                    dispose(); };
+            },
+            listRoutes: () => primary.listRoutes(),
+            get address() { return primary.address; },
+            get tokenRegistry() { return primary.tokenRegistry; },
+        };
+        return Object.freeze(surface);
+    };
+    const surface = createSurface(listeners);
+    let closeResult;
+    const runtime = {
+        [generationAdmissionBinder](admission) {
+            return surface[generationAdmissionBinder](admission);
+        },
+        [addressProvider]: surface[addressProvider],
+        ws: (path, wsOptions) => surface.ws(path, wsOptions),
+        route: (method, path, handler, meta) => surface.route(method, path, handler, meta),
+        listRoutes: () => surface.listRoutes(),
+        get address() { return surface.address; },
+        get tokenRegistry() { return surface.tokenRegistry; },
+        async listen() {
+            try {
+                for (const listener of listeners) {
+                    await listener.listen();
+                }
+            }
+            catch (error) {
+                await Promise.allSettled([...listeners].reverse().map((listener) => listener.close()));
+                throw error;
+            }
+            return listeners[0].address;
+        },
+        close() {
+            closeResult ??= closeListeners(listeners);
+            return closeResult;
+        },
+    };
+    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] : []);
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, 'multiple HTTP listeners failed to close');
+}

package/lib/token-registry.d.ts

@@ -14,12 +14,19 @@ export type TokenRegistryConfig = {
     readonly primaryToken?: string;
     readonly scopedTokens?: readonly ScopedTokenConfig[];
 };
+export type DynamicTokenConfig = ScopedTokenConfig & {
+    /** Unix epoch milliseconds; omitted credentials remain valid until explicitly revoked. */
+    readonly expiresAt?: number;
+};
 export declare class TokenRegistry {
     #private;
     constructor(config?: TokenRegistryConfig);
     resolve(token: string): AuthScope | null;
     resolvePrincipal(token: string): AuthenticatedTokenPrincipal | null;
     hasAnyToken(): boolean;
+    /** Registers a runtime-issued credential and returns an idempotent revoker. */
+    register(config: DynamicTokenConfig): () => void;
+    revoke(token: string): boolean;
     primaryTokenPrefixForLog(): string;
 }
 /** WebSocket upgrade paths allowed for demo scope. */

package/lib/token-registry.js

@@ -2,15 +2,20 @@ import { timingSafeEqualString } from './timing-safe-equal.js';
 export class TokenRegistry {
     #entries = new Map();
     constructor(config = {}) {
-        if (config.primaryToken)
-            this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full' }));
+        if (config.primaryToken) {
+            this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', dynamic: false }));
+        }
         for (const { token, scope, principalId } of config.scopedTokens ?? []) {
             if (!token)
                 continue;
             if (principalId !== undefined && (!principalId.trim() || principalId !== principalId.trim())) {
                 throw new Error('HTTP token principalId is invalid');
             }
-            const candidate = Object.freeze({ scope, ...(principalId === undefined ? {} : { principalId }) });
+            const candidate = Object.freeze({
+                scope,
+                ...(principalId === undefined ? {} : { principalId }),
+                dynamic: false,
+            });
             const existing = this.#entries.get(token);
             if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId)) {
                 throw new Error('HTTP token has conflicting authority bindings');
@@ -22,8 +27,11 @@ export class TokenRegistry {
         if (!token)
             return null;
         for (const [known, binding] of this.#entries) {
-            if (timingSafeEqualString(known, token))
-                return binding.scope;
+            if (!timingSafeEqualString(known, token))
+                continue;
+            if (this.#expired(known, binding))
+                return null;
+            return binding.scope;
         }
         return null;
     }
@@ -32,6 +40,8 @@ export class TokenRegistry {
             return null;
         for (const [known, binding] of this.#entries) {
             if (timingSafeEqualString(known, token)) {
+                if (this.#expired(known, binding))
+                    return null;
                 return binding.principalId
                     ? Object.freeze({ principalId: binding.principalId, scope: binding.scope })
                     : null;
@@ -40,7 +50,46 @@ export class TokenRegistry {
         return null;
     }
     hasAnyToken() {
-        return this.#entries.size > 0;
+        for (const [token, binding] of this.#entries) {
+            if (!this.#expired(token, binding))
+                return true;
+        }
+        return false;
+    }
+    /** Registers a runtime-issued credential and returns an idempotent revoker. */
+    register(config) {
+        if (!config.token)
+            throw new Error('Dynamic HTTP token is required');
+        if (config.principalId !== undefined
+            && (!config.principalId.trim() || config.principalId !== config.principalId.trim())) {
+            throw new Error('Dynamic HTTP token principalId is invalid');
+        }
+        if (config.expiresAt !== undefined
+            && (!Number.isSafeInteger(config.expiresAt) || config.expiresAt <= Date.now())) {
+            throw new Error('Dynamic HTTP token expiresAt must be a future epoch millisecond');
+        }
+        const candidate = Object.freeze({
+            scope: config.scope,
+            ...(config.principalId === undefined ? {} : { principalId: config.principalId }),
+            ...(config.expiresAt === undefined ? {} : { expiresAt: config.expiresAt }),
+            dynamic: true,
+        });
+        const existing = this.#entries.get(config.token);
+        if (existing)
+            throw new Error('Dynamic HTTP token conflicts with an existing credential');
+        this.#entries.set(config.token, candidate);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            if (this.#entries.get(config.token) === candidate)
+                this.#entries.delete(config.token);
+        };
+    }
+    revoke(token) {
+        const binding = this.#entries.get(token);
+        return binding?.dynamic === true && this.#entries.delete(token);
     }
     primaryTokenPrefixForLog() {
         for (const [tok, binding] of this.#entries) {
@@ -50,6 +99,13 @@ export class TokenRegistry {
         const first = this.#entries.keys().next().value;
         return first ? first.slice(0, 6) : '';
     }
+    #expired(token, binding) {
+        if (binding.expiresAt === undefined || binding.expiresAt > Date.now())
+            return false;
+        if (binding.dynamic)
+            this.#entries.delete(token);
+        return true;
+    }
 }
 /** WebSocket upgrade paths allowed for demo scope. */
 export function isDemoWebSocketPath(pathname) {