@zhin.js/host-http 1.0.15 → 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.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);
@@ -504,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;
@@ -612,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",

package/src/console-events.ts

@@ -7,6 +7,7 @@ import type {
   ConsoleEventPayloadMap,
   KnownConsoleEventType,
 } from '@zhin.js/console-protocol';
+import { createToken } from '@zhin.js/plugin-runtime';
 
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
@@ -27,12 +28,17 @@ export interface ConsoleEventHub {
     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 const consoleEventHubToken = createToken<ConsoleEventHub>('zhin.host.console-events');
+
 export interface ConsoleEventHubOptions {
   readonly runtimeId?: string;
   readonly historyLimit?: number;
@@ -65,6 +71,7 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
   const journal: JournalEntry[] = [];
   let journalBytes = 0;
   const subscribers = new Set<ServerResponse>();
+  const listeners = new Set<(event: ConsoleEventEnvelope) => void>();
 
   const remove = (response: ServerResponse): void => {
     subscribers.delete(response);
@@ -120,6 +127,9 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
           remove(response);
         }
       }
+      for (const listener of [...listeners]) {
+        try { listener(event); } catch { /* isolate trusted bridge failures */ }
+      }
       return event as ConsoleEventEnvelope<
         Type,
         Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
@@ -158,6 +168,10 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
         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/src/console-rpc-extended.ts

@@ -217,6 +217,8 @@ export async function dispatchExtendedConsoleRpc(
       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':
@@ -719,6 +721,51 @@ async function listInboxMessages(
   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: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  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: Record<string, unknown>): Record<string, unknown> {
   const actorId = row.actor_id;
   const actorName = row.actor_name ?? undefined;
@@ -836,6 +883,12 @@ async function actOnRequest(
       ? 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/src/console-rpc.ts

@@ -81,6 +81,11 @@ export type RuntimeConsoleRpcContext = {
    * Returns whether a process restart is required (always true without ConfigFeature).
    */
   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>>;
@@ -754,6 +759,41 @@ export async function dispatchRuntimeConsoleRpc(
       }
       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/src/http-host.ts

@@ -1,9 +1,14 @@
 import {
-  createServer,
+  createServer as createHttpServer,
   type IncomingMessage,
-  type Server,
+  type Server as HttpServer,
   type ServerResponse,
 } from 'node:http';
+import {
+  createServer as createHttpsServer,
+  type Server as HttpsServer,
+  type ServerOptions as HttpsServerOptions,
+} from 'node:https';
 import type { Socket } from 'node:net';
 import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -46,9 +51,29 @@ export interface WsHandle {
   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 {
@@ -67,6 +92,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 = (
@@ -83,7 +110,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,
@@ -117,6 +144,7 @@ interface AdmissionBoundHttpHost extends HttpHost, GenerationAdmissionBindable<H
 interface WsRoute {
   readonly listener: (connection: WsConnection) => void;
   readonly admission?: GenerationAdmissionGate;
+  readonly options: WsRouteOptions;
 }
 
 /** @public Stable Plugin Runtime HTTP Host token. */
@@ -143,9 +171,13 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   let closed = false;
   let closeResult: Promise<void> | undefined;
 
-  const server: Server = createServer((request, response) => {
+  const secure = options.tls !== undefined;
+  const handleRequest = (request: IncomingMessage, response: ServerResponse): void => {
     void dispatchHttp(request, response);
-  });
+  };
+  const server: HttpServer | HttpsServer = 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().
@@ -184,7 +216,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
     handler: (request: IncomingMessage, response: ServerResponse) => {
       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}`,
@@ -210,7 +242,10 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
       socket.destroy();
       return;
     }
-    const auth = authenticateUpgrade(request, pathname);
+    const protocolAuthenticated = admitted.every(({ entry }) => entry.options.auth === 'protocol');
+    const auth = protocolAuthenticated
+      ? { ok: true as const, scope: 'full' as const }
+      : authenticateUpgrade(request, pathname);
     if (!auth.ok) {
       socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
       socket.destroy();
@@ -406,6 +441,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   function registerWs(
     pathname: string,
     admission?: GenerationAdmissionGate,
+    options: WsRouteOptions = {},
   ): WsHandle {
     const normalized = normalizePath(pathname);
     let listeners = wsRoutes.get(normalized);
@@ -416,7 +452,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     const owned = new Set<WsRoute>();
     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 () => {
@@ -463,7 +499,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   ): AdmissionBoundHttpHost {
     const bound: AdmissionBoundHttpHost = {
       [generationAdmissionBinder]: (next) => createBoundHost(next),
-      ws: (path) => registerWs(path, admission),
+      ws: (path, options) => registerWs(path, admission, options),
       route: (method, path, handler, meta) => registerRoute(
         method,
         path,
@@ -481,7 +517,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   const runtime: ProcessHttpHost = {
     [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),
 
@@ -506,9 +542,14 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
           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 });
+          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 http://${publicHost}:${listenPort}`
+            `listening ${address.origin}`
             + ` | routes: ${httpRoutes.length}`
             + ` | token: ${tokenRegistry.hasAnyToken()
               ? `${tokenRegistry.primaryTokenPrefixForLog()}…`

package/src/index.ts

@@ -7,22 +7,30 @@ export {
   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,
+  consoleEventHubToken,
   type ConsoleEventHub,
 } from './console-events.js';
 export {

package/src/listener-group.ts

@@ -0,0 +1,108 @@
+import {
+  bindGenerationAdmission,
+  generationAdmissionBinder,
+  type GenerationAdmissionBindable,
+  type GenerationAdmissionGate,
+} from '@zhin.js/plugin-runtime';
+import {
+  createHttpHost,
+  type HttpHost,
+  type HttpHostAddress,
+  type HttpHostOptions,
+  type HttpRouteRegistration,
+  type ProcessHttpHost,
+  type WsHandle,
+  type WsRouteOptions,
+} from './http-host.js';
+
+const addressProvider = Symbol('HttpHostAddressProvider');
+
+interface AddressAwareHttpHost {
+  readonly [addressProvider]: () => readonly HttpHostAddress[];
+}
+
+type BoundHttpHost = HttpHost & GenerationAdmissionBindable<HttpHost> & AddressAwareHttpHost;
+
+/**
+ * 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: readonly HttpHostOptions[],
+): ProcessHttpHost {
+  if (options.length === 0) throw new Error('HttpHostGroup requires at least one listener');
+  const listeners = options.map((entry) => createHttpHost(entry));
+
+  const createSurface = (hosts: readonly HttpHost[]): BoundHttpHost => {
+    const primary = hosts[0]!;
+    const surface: BoundHttpHost = {
+      [generationAdmissionBinder](admission: GenerationAdmissionGate): HttpHost {
+        return createSurface(hosts.map((host) => bindGenerationAdmission(host, admission)));
+      },
+      [addressProvider]: () => listeners.flatMap((host) => host.address ? [host.address] : []),
+      ws(path: string, wsOptions?: WsRouteOptions): WsHandle {
+        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): HttpRouteRegistration {
+        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: Promise<void> | undefined;
+  const runtime: ProcessHttpHost & AddressAwareHttpHost = {
+    [generationAdmissionBinder](admission: GenerationAdmissionGate): HttpHost {
+      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(): Promise<HttpHostAddress> {
+      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(): Promise<void> {
+      closeResult ??= closeListeners(listeners);
+      return closeResult;
+    },
+  };
+  return Object.freeze(runtime);
+}
+
+/** Returns every bound listener, ordered primary/local first. */
+export function listHttpHostAddresses(host: HttpHost): readonly HttpHostAddress[] {
+  const provider = (host as Partial<AddressAwareHttpHost>)[addressProvider];
+  if (typeof provider === 'function') return Object.freeze([...provider.call(host)]);
+  return Object.freeze(host.address ? [host.address] : []);
+}
+
+async function closeListeners(listeners: readonly ProcessHttpHost[]): Promise<void> {
+  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/src/token-registry.ts

@@ -20,17 +20,35 @@ export type TokenRegistryConfig = {
   readonly scopedTokens?: readonly ScopedTokenConfig[];
 };
 
+export type DynamicTokenConfig = ScopedTokenConfig & {
+  /** Unix epoch milliseconds; omitted credentials remain valid until explicitly revoked. */
+  readonly expiresAt?: number;
+};
+
+type TokenBinding = Readonly<{
+  scope: AuthScope;
+  principalId?: string;
+  expiresAt?: number;
+  dynamic: boolean;
+}>;
+
 export class TokenRegistry {
-  readonly #entries = new Map<string, Readonly<{ scope: AuthScope; principalId?: string }>>();
+  readonly #entries = new Map<string, TokenBinding>();
 
   constructor(config: TokenRegistryConfig = {}) {
-    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');
@@ -42,7 +60,9 @@ export class TokenRegistry {
   resolve(token: string): AuthScope | null {
     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;
   }
@@ -51,6 +71,7 @@ export class TokenRegistry {
     if (!token) 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;
@@ -60,7 +81,43 @@ export class TokenRegistry {
   }
 
   hasAnyToken(): boolean {
-    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: DynamicTokenConfig): () => void {
+    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: TokenBinding = 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: string): boolean {
+    const binding = this.#entries.get(token);
+    return binding?.dynamic === true && this.#entries.delete(token);
   }
 
   primaryTokenPrefixForLog(): string {
@@ -70,6 +127,12 @@ export class TokenRegistry {
     const first = this.#entries.keys().next().value;
     return first ? first.slice(0, 6) : '';
   }
+
+  #expired(token: string, binding: TokenBinding): boolean {
+    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. */