@zhin.js/host-http 1.1.8 → 1.1.10

package/lib/console-rpc.d.ts

@@ -1,6 +1,6 @@
 import type { AuthScope } from './token-registry.js';
 import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
-import { type ConsoleConfigSource, type ConsoleConfigExplanation, type ConsoleEndpointSummary } from '@zhin.js/console-protocol';
+import { type ConsoleConfigPatchRequest, type ConsoleConfigPatchResult, type ConsoleConfigSource, type ConsoleConfigExplanation, type ConsoleEndpointSummary } from '@zhin.js/console-protocol';
 import { type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
 /**
  * Console RPC 请求结构：未锚定 endpoint 的会话地址（结构对齐
@@ -96,7 +96,9 @@ export interface PluginVerificationResult {
     readonly status: 'passed' | 'failed' | 'not-configured';
     readonly scope: 'local' | 'platform' | null;
     readonly summary: string;
+    readonly summaryI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['summaryI18n'];
     readonly evidence: readonly string[];
+    readonly evidenceI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['evidenceI18n'];
 }
 export interface PluginManagementPort {
     explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
@@ -161,6 +163,11 @@ export type RuntimeConsoleRpcContext = {
     setConfigKey?(pluginName: string, data: unknown): Promise<{
         restartRequired: boolean;
     }>;
+    /**
+     * Full-scope, path-allowlisted and revision-checked write (`config:patch`).
+     * Scope and schema checks belong to the implementation; scope violations throw.
+     */
+    patchConfig?(request: ConsoleConfigPatchRequest): Promise<ConsoleConfigPatchResult>;
     /** Persist a declared child Plugin lifecycle state. Takes effect after restart. */
     setPluginEnabled?(instanceKey: string, enabled: boolean): Promise<Readonly<{
         disabled: readonly string[];

package/lib/console-rpc.js

@@ -212,6 +212,52 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
             }
             return payloads;
         }
+        case CONFIG_RPC.PATCH: {
+            if (ctx.authScope !== 'full') {
+                emit({ requestId, error: 'Full scope required' });
+                return payloads;
+            }
+            const { instanceKey, expectedRevision, patches } = message;
+            if (instanceKey !== undefined && (typeof instanceKey !== 'string' || !instanceKey || instanceKey.length > 128)) {
+                emit({ requestId, error: 'instanceKey 必须是插件实例名，或省略以使用 Host 白名单' });
+                return payloads;
+            }
+            if (typeof expectedRevision !== 'string' || !/^[a-f0-9]{64}$/u.test(expectedRevision)) {
+                emit({ requestId, error: 'expectedRevision is required' });
+                return payloads;
+            }
+            if (!Array.isArray(patches)) {
+                emit({ requestId, error: 'patches 必须是数组' });
+                return payloads;
+            }
+            if (!ctx.patchConfig) {
+                emit({ requestId, error: 'Config patch is not configured' });
+                return payloads;
+            }
+            try {
+                const result = await ctx.patchConfig({
+                    ...(instanceKey === undefined ? {} : { instanceKey }),
+                    expectedRevision,
+                    patches,
+                });
+                if (result.status === 'saved') {
+                    ctx.publishEvent?.('config:updated', {
+                        pluginName: instanceKey ?? null,
+                        keys: [...new Set(result.paths.map(path => path[0]))],
+                        paths: result.paths,
+                        revision: result.revision,
+                    });
+                }
+                emit({ requestId, data: result });
+            }
+            catch (error) {
+                emit({
+                    requestId,
+                    error: `Failed to patch config: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            return payloads;
+        }
         case CONFIG_RPC.SET: {
             try {
                 const pluginName = message.pluginName;

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 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 { TokenRegistry, extractBearerToken, isDemoWebSocketPath, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, 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 { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, type BuildOpenApiOptions, type ListedRoute, type OpenApiParameter, type RouteMeta, } from './openapi.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 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 { TokenRegistry, extractBearerToken, isDemoWebSocketPath, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { createConsoleEventHub, consoleEventHubToken, } from './console-events.js';
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, } from './openapi.js';

package/lib/token-registry.d.ts

@@ -2,10 +2,32 @@
 export type AuthScope = 'full' | 'demo';
 export type ScopedTokenConfig = {
     readonly token: string;
-    readonly scope: AuthScope;
+    /**
+     * `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[];
 };
+/**
+ * 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.
+ */
+export interface ConsoleAccess {
+    readonly unrestricted: boolean;
+    readonly permissions: readonly string[];
+    readonly roles: readonly string[];
+}
+export declare const publicConsoleAccess: ConsoleAccess;
+export declare const unrestrictedConsoleAccess: ConsoleAccess;
 export interface AuthenticatedTokenPrincipal {
     readonly principalId: string;
     readonly scope: AuthScope;
@@ -23,6 +45,11 @@ export declare class TokenRegistry {
     constructor(config?: TokenRegistryConfig);
     resolve(token: string): AuthScope | null;
     resolvePrincipal(token: string): AuthenticatedTokenPrincipal | null;
+    /**
+     * 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.
+     */
+    resolveAccess(token: string): ConsoleAccess;
     hasAnyToken(): boolean;
     /** Registers a runtime-issued credential and returns an idempotent revoker. */
     register(config: DynamicTokenConfig): () => void;

package/lib/token-registry.js

@@ -1,23 +1,37 @@
 import { timingSafeEqualString } from './timing-safe-equal.js';
+export const publicConsoleAccess = Object.freeze({
+    unrestricted: false,
+    permissions: Object.freeze([]),
+    roles: Object.freeze([]),
+});
+export const unrestrictedConsoleAccess = Object.freeze({
+    unrestricted: true,
+    permissions: Object.freeze([]),
+    roles: Object.freeze([]),
+});
 export class TokenRegistry {
     #entries = new Map();
     constructor(config = {}) {
         if (config.primaryToken) {
-            this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', dynamic: false }));
+            this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', permissions: [], roles: [], dynamic: false }));
         }
-        for (const { token, scope, principalId } of config.scopedTokens ?? []) {
+        for (const { token, scope, principalId, permissions, roles } 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,
+                scope: scope === 'full' ? 'full' : 'demo',
                 ...(principalId === undefined ? {} : { principalId }),
+                permissions: accessList(permissions, 'permissions'),
+                roles: accessList(roles, 'roles'),
                 dynamic: false,
             });
             const existing = this.#entries.get(token);
-            if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId)) {
+            if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId
+                || existing.permissions.join('\n') !== candidate.permissions.join('\n')
+                || existing.roles.join('\n') !== candidate.roles.join('\n'))) {
                 throw new Error('HTTP token has conflicting authority bindings');
             }
             this.#entries.set(token, candidate);
@@ -49,6 +63,26 @@ export class TokenRegistry {
         }
         return null;
     }
+    /**
+     * 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.
+     */
+    resolveAccess(token) {
+        if (!this.hasAnyToken())
+            return unrestrictedConsoleAccess;
+        if (!token)
+            return publicConsoleAccess;
+        for (const [known, binding] of this.#entries) {
+            if (!timingSafeEqualString(known, token))
+                continue;
+            if (this.#expired(known, binding))
+                return publicConsoleAccess;
+            if (binding.scope === 'full')
+                return unrestrictedConsoleAccess;
+            return Object.freeze({ unrestricted: false, permissions: binding.permissions, roles: binding.roles });
+        }
+        return publicConsoleAccess;
+    }
     hasAnyToken() {
         for (const [token, binding] of this.#entries) {
             if (!this.#expired(token, binding))
@@ -69,8 +103,10 @@ export class TokenRegistry {
             throw new Error('Dynamic HTTP token expiresAt must be a future epoch millisecond');
         }
         const candidate = Object.freeze({
-            scope: config.scope,
+            scope: config.scope === 'full' ? 'full' : 'demo',
             ...(config.principalId === undefined ? {} : { principalId: config.principalId }),
+            permissions: accessList(config.permissions, 'permissions'),
+            roles: accessList(config.roles, 'roles'),
             ...(config.expiresAt === undefined ? {} : { expiresAt: config.expiresAt }),
             dynamic: true,
         });
@@ -107,6 +143,14 @@ export class TokenRegistry {
         return true;
     }
 }
+function accessList(value, label) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0 && item.trim() === item)) {
+        throw new Error(`HTTP token ${label} must be non-empty trimmed strings`);
+    }
+    return Object.freeze([...new Set(value)].sort());
+}
 /** WebSocket upgrade paths allowed for demo scope. */
 export function isDemoWebSocketPath(pathname) {
     return pathname === '/sandbox';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,11 +17,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.11",
+    "@zhin.js/console-protocol": "1.1.12",
     "@zhin.js/host-http-contract": "1.1.1",
     "@zhin.js/logger": "1.1.2",
     "@zhin.js/schedule": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.1.15"
+    "@zhin.js/plugin-runtime": "1.1.17"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/console-rpc.ts

@@ -3,6 +3,8 @@ import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
 import {
   CONFIG_RPC,
   ENDPOINT_RPC,
+  type ConsoleConfigPatchRequest,
+  type ConsoleConfigPatchResult,
   type ConsoleConfigSource,
   type ConsoleConfigExplanation,
   type ConsoleEndpointSummary,
@@ -133,7 +135,9 @@ export interface PluginVerificationResult {
   readonly status: 'passed' | 'failed' | 'not-configured';
   readonly scope: 'local' | 'platform' | null;
   readonly summary: string;
+  readonly summaryI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['summaryI18n'];
   readonly evidence: readonly string[];
+  readonly evidenceI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['evidenceI18n'];
 }
 
 export interface PluginManagementPort {
@@ -194,6 +198,11 @@ export type RuntimeConsoleRpcContext = {
    * Returns whether a process restart is required.
    */
   setConfigKey?(pluginName: string, data: unknown): Promise<{ restartRequired: boolean }>;
+  /**
+   * Full-scope, path-allowlisted and revision-checked write (`config:patch`).
+   * Scope and schema checks belong to the implementation; scope violations throw.
+   */
+  patchConfig?(request: ConsoleConfigPatchRequest): Promise<ConsoleConfigPatchResult>;
   /** Persist a declared child Plugin lifecycle state. Takes effect after restart. */
   setPluginEnabled?(
     instanceKey: string,
@@ -454,6 +463,48 @@ export async function dispatchRuntimeConsoleRpc(
       }
       return payloads;
     }
+    case CONFIG_RPC.PATCH: {
+      if (ctx.authScope !== 'full') { emit({ requestId, error: 'Full scope required' }); return payloads; }
+      const { instanceKey, expectedRevision, patches } = message;
+      if (instanceKey !== undefined && (typeof instanceKey !== 'string' || !instanceKey || instanceKey.length > 128)) {
+        emit({ requestId, error: 'instanceKey 必须是插件实例名，或省略以使用 Host 白名单' });
+        return payloads;
+      }
+      if (typeof expectedRevision !== 'string' || !/^[a-f0-9]{64}$/u.test(expectedRevision)) {
+        emit({ requestId, error: 'expectedRevision is required' });
+        return payloads;
+      }
+      if (!Array.isArray(patches)) {
+        emit({ requestId, error: 'patches 必须是数组' });
+        return payloads;
+      }
+      if (!ctx.patchConfig) {
+        emit({ requestId, error: 'Config patch is not configured' });
+        return payloads;
+      }
+      try {
+        const result = await ctx.patchConfig({
+          ...(instanceKey === undefined ? {} : { instanceKey }),
+          expectedRevision,
+          patches,
+        });
+        if (result.status === 'saved') {
+          ctx.publishEvent?.('config:updated', {
+            pluginName: instanceKey ?? null,
+            keys: [...new Set(result.paths.map(path => path[0]))],
+            paths: result.paths,
+            revision: result.revision,
+          });
+        }
+        emit({ requestId, data: result });
+      } catch (error) {
+        emit({
+          requestId,
+          error: `Failed to patch config: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+      return payloads;
+    }
     case CONFIG_RPC.SET: {
       try {
         const pluginName = message.pluginName;

package/src/index.ts

@@ -21,7 +21,10 @@ export {
   TokenRegistry,
   extractBearerToken,
   isDemoWebSocketPath,
+  publicConsoleAccess,
+  unrestrictedConsoleAccess,
   type AuthenticatedTokenPrincipal,
+  type ConsoleAccess,
   type AuthScope,
   type DynamicTokenConfig,
   type ScopedTokenConfig,

package/src/token-registry.ts

@@ -5,11 +5,44 @@ export type AuthScope = 'full' | 'demo';
 
 export type ScopedTokenConfig = {
   readonly token: string;
-  readonly scope: AuthScope;
+  /**
+   * `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[];
 };
 
+/**
+ * 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.
+ */
+export interface ConsoleAccess {
+  readonly unrestricted: boolean;
+  readonly permissions: readonly string[];
+  readonly roles: readonly string[];
+}
+
+export const publicConsoleAccess: ConsoleAccess = Object.freeze({
+  unrestricted: false,
+  permissions: Object.freeze([]) as readonly string[],
+  roles: Object.freeze([]) as readonly string[],
+});
+
+export const unrestrictedConsoleAccess: ConsoleAccess = Object.freeze({
+  unrestricted: true,
+  permissions: Object.freeze([]) as readonly string[],
+  roles: Object.freeze([]) as readonly string[],
+});
+
 export interface AuthenticatedTokenPrincipal {
   readonly principalId: string;
   readonly scope: AuthScope;
@@ -28,6 +61,8 @@ export type DynamicTokenConfig = ScopedTokenConfig & {
 type TokenBinding = Readonly<{
   scope: AuthScope;
   principalId?: string;
+  permissions: readonly string[];
+  roles: readonly string[];
   expiresAt?: number;
   dynamic: boolean;
 }>;
@@ -37,20 +72,24 @@ export class TokenRegistry {
 
   constructor(config: TokenRegistryConfig = {}) {
     if (config.primaryToken) {
-      this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', dynamic: false }));
+      this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', permissions: [], roles: [], dynamic: false }));
     }
-    for (const { token, scope, principalId } of config.scopedTokens ?? []) {
+    for (const { token, scope, principalId, permissions, roles } 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,
+      const candidate: TokenBinding = Object.freeze({
+        scope: scope === 'full' ? 'full' : 'demo',
         ...(principalId === undefined ? {} : { principalId }),
+        permissions: accessList(permissions, 'permissions'),
+        roles: accessList(roles, 'roles'),
         dynamic: false,
       });
       const existing = this.#entries.get(token);
-      if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId)) {
+      if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId
+        || existing.permissions.join('\n') !== candidate.permissions.join('\n')
+        || existing.roles.join('\n') !== candidate.roles.join('\n'))) {
         throw new Error('HTTP token has conflicting authority bindings');
       }
       this.#entries.set(token, candidate);
@@ -80,6 +119,22 @@ export class TokenRegistry {
     return null;
   }
 
+  /**
+   * 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.
+   */
+  resolveAccess(token: string): ConsoleAccess {
+    if (!this.hasAnyToken()) return unrestrictedConsoleAccess;
+    if (!token) return publicConsoleAccess;
+    for (const [known, binding] of this.#entries) {
+      if (!timingSafeEqualString(known, token)) continue;
+      if (this.#expired(known, binding)) return publicConsoleAccess;
+      if (binding.scope === 'full') return unrestrictedConsoleAccess;
+      return Object.freeze({ unrestricted: false, permissions: binding.permissions, roles: binding.roles });
+    }
+    return publicConsoleAccess;
+  }
+
   hasAnyToken(): boolean {
     for (const [token, binding] of this.#entries) {
       if (!this.#expired(token, binding)) return true;
@@ -99,8 +154,10 @@ export class TokenRegistry {
       throw new Error('Dynamic HTTP token expiresAt must be a future epoch millisecond');
     }
     const candidate: TokenBinding = Object.freeze({
-      scope: config.scope,
+      scope: config.scope === 'full' ? 'full' : 'demo',
       ...(config.principalId === undefined ? {} : { principalId: config.principalId }),
+      permissions: accessList(config.permissions, 'permissions'),
+      roles: accessList(config.roles, 'roles'),
       ...(config.expiresAt === undefined ? {} : { expiresAt: config.expiresAt }),
       dynamic: true,
     });
@@ -135,6 +192,14 @@ export class TokenRegistry {
   }
 }
 
+function accessList(value: readonly string[] | undefined, label: string): readonly string[] {
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0 && item.trim() === item)) {
+    throw new Error(`HTTP token ${label} must be non-empty trimmed strings`);
+  }
+  return Object.freeze([...new Set(value)].sort());
+}
+
 /** WebSocket upgrade paths allowed for demo scope. */
 export function isDemoWebSocketPath(pathname: string): boolean {
   return pathname === '/sandbox';