@zhin.js/gateway 1.2.0 → 1.4.0

package/lib/config/validation-messages.d.ts

@@ -0,0 +1,15 @@
+import { type Locale } from '@zhin.js/plugin-runtime';
+/** The parts of an Ajv `ErrorObject` a configuration message needs. */
+export interface SchemaIssue {
+    readonly keyword: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly message?: string;
+}
+/** Schema `pattern` of a value that may be a string only as one whole `${VAR}` reference. */
+export declare const ENVIRONMENT_REFERENCE_SCHEMA_PATTERN = "^\\$\\{[A-Za-z_][A-Za-z0-9_]*(?::[-=][^}]*)?\\}$";
+/**
+ * Localized text for one Ajv issue of a Plugin configuration, in the project `locale`
+ * (`zh-CN` by default). `location` is the field path inside the configuration block; it is named in
+ * the message so a reader sees which field is wrong without matching it to the separate path.
+ */
+export declare function formatSchemaIssue(issue: SchemaIssue, location: readonly string[], locale: Locale | unknown): string;

package/lib/config/validation-messages.js

@@ -0,0 +1,66 @@
+import { createMessages, resolveLocale } from '@zhin.js/plugin-runtime';
+const messages = createMessages({
+    type: { 'zh-CN': '{field}类型应为 {type}', en: '{field}must be of type {type}' },
+    maximum: { 'zh-CN': '{field}不能大于 {limit}', en: '{field}must be at most {limit}' },
+    minimum: { 'zh-CN': '{field}不能小于 {limit}', en: '{field}must be at least {limit}' },
+    exclusiveMaximum: { 'zh-CN': '{field}必须小于 {limit}', en: '{field}must be less than {limit}' },
+    exclusiveMinimum: { 'zh-CN': '{field}必须大于 {limit}', en: '{field}must be greater than {limit}' },
+    minLength: { 'zh-CN': '{field}长度不能少于 {limit} 个字符', en: '{field}must be at least {limit} characters long' },
+    maxLength: { 'zh-CN': '{field}长度不能超过 {limit} 个字符', en: '{field}must be at most {limit} characters long' },
+    enum: { 'zh-CN': '{field}必须是以下值之一：{values}', en: '{field}must be one of: {values}' },
+    const: { 'zh-CN': '{field}必须等于 {value}', en: '{field}must equal {value}' },
+    pattern: { 'zh-CN': '{field}格式不符合 {pattern}', en: '{field}must match the pattern {pattern}' },
+    environmentReference: { 'zh-CN': '{field}只接受数值或 {reference} 形式的环境变量引用', en: '{field}accepts only a number or a {reference} environment reference' },
+    required: { 'zh-CN': '缺少必填字段 {property}', en: 'missing required field {property}' },
+    additionalProperties: { 'zh-CN': '不支持的字段 {property}', en: 'unknown field {property}' },
+    format: { 'zh-CN': '{field}应为有效的 {format}', en: '{field}must be a valid {format}' },
+    minItems: { 'zh-CN': '{field}至少需要 {limit} 项', en: '{field}must have at least {limit} items' },
+    maxItems: { 'zh-CN': '{field}最多只能有 {limit} 项', en: '{field}must have at most {limit} items' },
+    fallback: { 'zh-CN': '{field}不满足 {keyword} 约束（{detail}）', en: '{field}does not satisfy {keyword} ({detail})' },
+    field: { 'zh-CN': '字段 {path} ', en: 'Field {path} ' },
+});
+/** Schema `pattern` of a value that may be a string only as one whole `${VAR}` reference. */
+export const ENVIRONMENT_REFERENCE_SCHEMA_PATTERN = '^\\$\\{[A-Za-z_][A-Za-z0-9_]*(?::[-=][^}]*)?\\}$';
+const NUMERIC_LIMITS = new Set(['maximum', 'minimum', 'exclusiveMaximum', 'exclusiveMinimum', 'minLength', 'maxLength', 'minItems', 'maxItems']);
+function display(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * Localized text for one Ajv issue of a Plugin configuration, in the project `locale`
+ * (`zh-CN` by default). `location` is the field path inside the configuration block; it is named in
+ * the message so a reader sees which field is wrong without matching it to the separate path.
+ */
+export function formatSchemaIssue(issue, location, locale) {
+    const lang = resolveLocale(locale);
+    const field = location.length > 0 ? messages(lang, 'field', { path: location.join('.') }) : '';
+    const params = issue.params;
+    switch (issue.keyword) {
+        case 'type': {
+            const type = Array.isArray(params.type) ? params.type.join(' | ') : String(params.type);
+            return messages(lang, 'type', { field, type: type === 'array' ? 'list' : type });
+        }
+        case 'enum': {
+            const allowed = Array.isArray(params.allowedValues) ? params.allowedValues.map(display).join(', ') : display(params.allowedValues);
+            return messages(lang, 'enum', { field, values: allowed });
+        }
+        case 'const':
+            return messages(lang, 'const', { field, value: display(params.allowedValue) });
+        case 'pattern':
+            // A string allowed only as a whole `${VAR}` reference (e.g. `http.port`): say so plainly.
+            if (String(params.pattern) === ENVIRONMENT_REFERENCE_SCHEMA_PATTERN) {
+                return messages(lang, 'environmentReference', { field, reference: '${VAR}' });
+            }
+            return messages(lang, 'pattern', { field, pattern: String(params.pattern) });
+        case 'format':
+            return messages(lang, 'format', { field, format: String(params.format) });
+        case 'required':
+            return messages(lang, 'required', { property: [...location, String(params.missingProperty)].join('.') });
+        case 'additionalProperties':
+            return messages(lang, 'additionalProperties', { property: [...location, String(params.additionalProperty)].join('.') });
+        default:
+            if (NUMERIC_LIMITS.has(issue.keyword) && (typeof params.limit === 'number' || typeof params.limit === 'string')) {
+                return messages(lang, issue.keyword, { field, limit: params.limit });
+            }
+            return messages(lang, 'fallback', { field, keyword: issue.keyword, detail: issue.message ?? issue.keyword });
+    }
+}

package/lib/config.d.ts

@@ -11,3 +11,4 @@ export * from './config/environment-files.js';
 export * from './config/literal-secrets.js';
 export * from './config/plugin-package-map.js';
 export * from './config/plugin-schema-catalog.js';
+export { SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError } from './config/secret-storage.js';

package/lib/config.js

@@ -11,3 +11,4 @@ export * from './config/environment-files.js';
 export * from './config/literal-secrets.js';
 export * from './config/plugin-package-map.js';
 export * from './config/plugin-schema-catalog.js';
+export { SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError } from './config/secret-storage.js';

package/lib/database/console-role.js

@@ -92,7 +92,8 @@ export async function setupConsoleRole(options) {
     const block = document.database && typeof document.database === 'object' && !Array.isArray(document.database)
         ? document.database
         : { dialect };
-    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } });
+    // Local owner CLI (`zhin db console-role`): may write `.env`.
+    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } }, { environmentWrite: true });
     return Object.freeze({
         dialect,
         user,

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

@@ -6,7 +6,7 @@
  * type is forwarded to the instance by the HTTP server.
  */
 import { type RouteContext, type TokenRegistry } from '@zhin.js/host-http';
-import type { GatewayRpcDispatcher } from '../packages/rpc.js';
+import { type GatewayRpcDispatcher } from '../packages/rpc.js';
 /** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
 export declare const GATEWAY_RPC_PREFIX = "gateway.";
 export interface GatewayConsoleRpc {
@@ -23,5 +23,7 @@ export interface GatewayRpcHandler extends GatewayConsoleRpc {
      * is forwarded to the instance untouched (e.g. `feature.set-enabled` below the global level).
      */
     claims?(message: Readonly<Record<string, unknown>>): boolean;
+    /** RPC types this handler answers, for `GET {base}/console/capabilities`. */
+    types?(): readonly string[];
 }
 export declare function createGatewayConsoleRpc(dispatch: GatewayRpcDispatcher): GatewayConsoleRpc;

package/lib/http/console-rpc.js

@@ -5,31 +5,58 @@
  * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
  * type is forwarded to the instance by the HTTP server.
  */
-import { auditActor, jsonResponse, } from '@zhin.js/host-http';
-import { GATEWAY_RPC } from '@zhin.js/console-protocol';
+import { auditActor, jsonResponse, unknownRpcLog, } from '@zhin.js/host-http';
+import { CONSOLE_DENIAL_REASONS, GATEWAY_RPC, GATEWAY_RPC_PERMISSIONS, } from '@zhin.js/console-protocol';
+import { isGatewayRpcType } from '../packages/rpc.js';
+import { gatewayPrincipalAllows } from '../packages/authorization.js';
+import { LOCAL_GATEWAY_RPC } from '../local/protocol.js';
 /** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
 export const GATEWAY_RPC_PREFIX = 'gateway.';
+/**
+ * Socket-only RPC types ({@link LOCAL_GATEWAY_RPC}): they exist, but never over HTTP. Refused
+ * with 403 (`forbidden`, audit reason `socket_only`) rather than `unknown_rpc`, so an attempt to
+ * reach Console administration over HTTP stays visible in the audit log.
+ */
+const SOCKET_ONLY_TYPES = new Set(Object.values(LOCAL_GATEWAY_RPC));
 const READ_ONLY_TYPES = new Set([
     GATEWAY_RPC.LIST,
     GATEWAY_RPC.PLAN,
     GATEWAY_RPC.STATUS,
     GATEWAY_RPC.LOGS,
 ]);
+/** Why the gateway dispatcher refused `type` (`forbidden`). */
+function gatewayDenialReason(type, principal) {
+    if (!principal)
+        return CONSOLE_DENIAL_REASONS.NOT_AUTHENTICATED;
+    if (isGatewayRpcType(type) && !gatewayPrincipalAllows(principal, GATEWAY_RPC_PERMISSIONS[type])) {
+        return principal.kind === 'bootstrap' ? CONSOLE_DENIAL_REASONS.SETUP_REQUIRED : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+    }
+    // The permission map admitted it; the service's own rule refused (e.g. bootstrap package limits).
+    return CONSOLE_DENIAL_REASONS.HANDLER_DENIED;
+}
 export function createGatewayConsoleRpc(dispatch) {
     return Object.freeze({
         async handle(message, context, tokenRegistry) {
             const type = typeof message.type === 'string' ? message.type : '';
             const requestId = message.requestId;
             const principal = context.principal;
-            const result = await dispatch({ type, data: message.data }, principal);
+            const socketOnly = SOCKET_ONLY_TYPES.has(type);
+            const result = socketOnly
+                ? { ok: false, error: { code: 'forbidden', status: 403, message: `RPC "${type.slice(0, 64)}" 只能通过本机网关套接字调用（zhin console …）` } }
+                : await dispatch({ type, data: message.data }, principal);
             const write = !READ_ONLY_TYPES.has(type);
+            const unknown = !result.ok && result.error.code === 'unknown_rpc';
             const outcome = result.ok ? 'ok' : result.error.code === 'forbidden' ? 'denied' : 'error';
-            if (write || outcome === 'denied') {
+            // zhinjs/zhin#1250: an unknown `gateway.*` type ran nothing and is not a refusal: not audited.
+            if (unknown)
+                unknownRpcLog.note(type);
+            else if (write || outcome === 'denied') {
                 try {
                     tokenRegistry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${type}`.slice(0, 256),
                         outcome,
+                        ...(outcome === 'denied' ? { detail: { type: type.slice(0, 256), reason: socketOnly ? CONSOLE_DENIAL_REASONS.SOCKET_ONLY : gatewayDenialReason(type, principal) } } : {}),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }

package/lib/http/gateway-console.d.ts

@@ -1,5 +1,6 @@
 import { type ConsoleAuditEntry } from '@zhin.js/host-http';
 import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import type { BridgeRouteTable } from '@zhin.js/host-http/bridge';
 import { type ProjectDatabaseConfig } from '../database/config.js';
 import { type GatewayStore, type OpenGatewayStoreOptions } from '../database/gateway-store.js';
 import { type LocalConsoleAdmin } from '../iam/local-admin.js';
@@ -15,6 +16,10 @@ export interface GatewayConsoleInstancePort {
     pluginPermissions?(): readonly ConsolePluginPermissionInfo[];
     /** Sends `principal-revoked` (the instance closes that user's live connections). */
     revokePrincipal?(principalId: string, reason?: string): void;
+    /** Whether an instance is attached and answering (a message sent now is delivered). */
+    readonly ready?: boolean;
+    /** Runs on every route table change (an instance's first `ready` included; empty when it goes away). */
+    onRoutes?(listener: (table: BridgeRouteTable) => void): () => void;
     /** Audit entries written by the instance. */
     onAudit?(listener: (entry: ConsoleAuditEntry) => void): () => void;
 }

package/lib/http/gateway-console.js

@@ -12,7 +12,7 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { ONBOARDING_RPC } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, IAM_RPC, ONBOARDING_RPC } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
 import { createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -86,13 +86,38 @@ export async function startGatewayConsole(options) {
         iam,
         logger: { warn: (message) => logger.warn(message), info: (message) => logger.info(message) },
     });
+    // ADR 0060 §2.4: a deleted / disabled Console user's chat person link is removed by the
+    // instance on `principal-revoked`. Those two reasons are kept while no instance is attached
+    // and sent once one reports ready, so a link never outlives its user because the instance was
+    // down (bounded; in memory only: a gateway restart forgets them).
+    const undelivered = new Map();
     const revoke = (userId, reason) => {
         terminal.terminatePrincipal(`user:${userId}`, 'revoked');
+        const ending = reason === 'deleted' || reason === 'disabled';
+        if (ending && options.instance?.ready === false) {
+            undelivered.delete(userId);
+            undelivered.set(userId, reason);
+            if (undelivered.size > 1024)
+                undelivered.delete(undelivered.keys().next().value);
+        }
         try {
             options.instance?.revokePrincipal?.(userId, reason);
         }
         catch { /* bridge gone */ }
     };
+    const stopUndelivered = options.instance?.onRoutes?.(() => {
+        if (options.instance?.ready !== true)
+            return;
+        for (const [userId, reason] of [...undelivered]) {
+            undelivered.delete(userId);
+            try {
+                options.instance?.revokePrincipal?.(userId, reason);
+            }
+            catch { /* bridge gone */ }
+        }
+    });
+    if (stopUndelivered)
+        disposers.push(stopUndelivered);
     const projectDatabase = async () => options.database
         ?? resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
     async function connect() {
@@ -330,6 +355,7 @@ const ONBOARDING_STEPS = new Set(['ai', 'adapters', 'finish']);
 export function createGatewayAccountRpc(options) {
     return Object.freeze({
         owns: (type) => isIamRpc(type) || type === ONBOARDING_RPC.UPDATE,
+        types: () => [...Object.values(IAM_RPC), ONBOARDING_RPC.UPDATE],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const requestId = message.requestId;
@@ -338,21 +364,21 @@ export function createGatewayAccountRpc(options) {
                 return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
             }
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${String(message.type ?? '')}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const result = isIamRpc(message.type)
@@ -361,7 +387,7 @@ export function createGatewayAccountRpc(options) {
             if (decision.write)
                 audit(result.status < 400 && result.body.success !== false ? 'ok' : 'error');
             else if (result.status === 403)
-                audit('denied');
+                audit('denied', CONSOLE_DENIAL_REASONS.HANDLER_DENIED);
             return jsonResponse(result.status, result.body, { ...noStore, ...result.headers });
         },
     });

package/lib/http/gateway-http-server.d.ts

@@ -43,6 +43,8 @@ export interface GatewayHttpServerOptions {
      * RPC type on that route is forwarded to the instance unchanged.
      */
     readonly consoleRpc?: GatewayConsoleRpc;
+    /** Reported on `/pub/health` as `project.id` (`projectIdentity(projectRoot)`). */
+    readonly projectId?: string;
 }
 /** One router, many listeners: every listener serves the same surface. */
 export declare class GatewayHttpServer {

package/lib/http/gateway-http-server.js

@@ -14,9 +14,10 @@
  * answer in time gives `504 { code: 'instance_timeout' }`, any other bridge failure
  * `502 { code: 'instance_error' }` (mapped from {@link InstanceTransportError}).
  */
-import { authorizeConsoleWebSocket, auditActor, createHttpRouter, extractBearerToken, jsonResponse, normalizePath, requestMeta, TokenRegistry, } from '@zhin.js/host-http';
+import { authorizeConsoleWebSocket, auditActor, createHttpRouter, extractBearerToken, jsonResponse, normalizePath, requestMeta, TokenRegistry, webSocketDenialReason, } from '@zhin.js/host-http';
 import { InstanceTransportError, } from '@zhin.js/host-http/bridge';
 import { createNodeHttpListener } from '@zhin.js/host-http/node';
+import { CONSOLE_CAPABILITIES_PATH, CONSOLE_FEATURES, GATEWAY_RPC, createConsoleCapabilities, mergeConsoleCapabilities, parseConsoleCapabilities, } from '@zhin.js/console-protocol';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { databaseBusyResponse, isDatabaseBusyError } from '../database/project-database.js';
 import { GATEWAY_RPC_PREFIX } from './console-rpc.js';
@@ -55,6 +56,9 @@ export class GatewayHttpServer {
     #retryAfter;
     #maxBody;
     #consoleRpc;
+    /** The instance connection (and route table) that has no capability route: asked once. */
+    #capabilitiesMissing;
+    #projectId;
     #rpcHandlers = new Set();
     #closed = false;
     #closeResult;
@@ -65,6 +69,7 @@ export class GatewayHttpServer {
         this.#retryAfter = String(Math.max(1, Math.round(options.retryAfterSeconds ?? DEFAULT_GATEWAY_RETRY_AFTER_SECONDS)));
         this.#maxBody = options.maxRequestBodyBytes ?? DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES;
         this.#consoleRpc = options.consoleRpc;
+        this.#projectId = options.projectId;
         this.tokenRegistry = options.tokenRegistry ?? new TokenRegistry({ primaryToken: primary.token });
         this.apiBase = normalizePath(primary.apiBase ?? '/api');
         const routerOptions = {
@@ -84,6 +89,10 @@ export class GatewayHttpServer {
                 summary: 'Console RPC (gateway-owned types answered by the gateway, the rest forwarded)',
                 tags: ['console'],
             });
+            router.route('GET', `${this.apiBase}${CONSOLE_CAPABILITIES_PATH}`, (request, context) => this.#capabilities(request, context), {
+                summary: 'Console capabilities (gateway-owned RPC types merged with the instance\'s)',
+                tags: ['console'],
+            });
             // Lowest precedence: every path no gateway route claims goes to the instance.
             router.route('ALL', '/*', (request, context) => this.#forward(request, context));
         }
@@ -178,6 +187,7 @@ export class GatewayHttpServer {
             status: 'ok',
             timestamp: new Date().toISOString(),
             instance: { state: this.#instance.state(), ready: this.#readyTransport() !== undefined },
+            ...(this.#projectId ? { project: { id: this.#projectId } } : {}),
         };
         // Polled by the Console's instance banner: never cached.
         return jsonResponse(200, body, { 'cache-control': 'no-store' });
@@ -243,6 +253,36 @@ export class GatewayHttpServer {
         }));
         return this.#instanceError(502, 'instance_error', 'unknown', 'The instance failed to answer', false);
     }
+    /**
+     * `GET {base}/console/capabilities` (zhinjs/zhin#1250): the RPC types the gateway answers itself,
+     * merged with the instance's reply. While the instance is not answering (or predates the route)
+     * the reply says `complete: false`, so the Console reads it again later.
+     */
+    async #capabilities(request, context) {
+        const own = [...this.#rpcHandlers].flatMap(handler => handler.types?.() ?? []);
+        const gateway = createConsoleCapabilities({
+            rpc: [...(this.#consoleRpc ? Object.values(GATEWAY_RPC) : []), ...own],
+            features: [CONSOLE_FEATURES.UNKNOWN_RPC_CODE, CONSOLE_FEATURES.DENIAL_REASONS, CONSOLE_FEATURES.GATEWAY],
+        });
+        let instance = createConsoleCapabilities({ rpc: [], complete: false });
+        const transport = this.#readyTransport();
+        // An instance that predates the route refuses it (and audits that): ask it once per route table.
+        const revision = transport?.routes().revision;
+        const missing = this.#capabilitiesMissing;
+        if (transport && !(missing?.transport === transport && missing.revision === revision)) {
+            try {
+                const response = await this.#forward(request, context);
+                const body = response.ok ? await response.json().catch(() => null) : null;
+                const parsed = parseConsoleCapabilities(body?.data);
+                if (parsed)
+                    instance = parsed;
+                else if (response.status === 403 || response.status === 404)
+                    this.#capabilitiesMissing = { transport, revision };
+            }
+            catch { /* the instance part stays unknown */ }
+        }
+        return jsonResponse(200, { success: true, data: mergeConsoleCapabilities(gateway, instance) }, { 'cache-control': 'no-store' });
+    }
     /**
      * `POST {base}/console/request`: the router authenticated and authorized the route; `gateway.*`
      * types are dispatched here (the dispatcher checks the per-RPC permission), the rest are
@@ -392,6 +432,7 @@ export class GatewayHttpServer {
                     actor: auditActor(principal),
                     action: `ws:${pathname}`,
                     outcome: 'denied',
+                    detail: { reason: webSocketDenialReason(principal, pathname) },
                     ...(request.remoteAddress ? { ip: request.remoteAddress } : {}),
                 });
             }

package/lib/http/local-principal.d.ts

@@ -1,2 +1,2 @@
-import type { ConsoleUserPrincipal } from '@zhin.js/host-http';
+import { type ConsoleUserPrincipal } from '@zhin.js/host-http';
 export declare const LOCAL_OWNER_PRINCIPAL: ConsoleUserPrincipal;

package/lib/http/local-principal.js

@@ -5,12 +5,13 @@
  * entries name it `user:local`.
  */
 import { CONSOLE_PERMISSION_LIST } from '@zhin.js/console-protocol';
+import { LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID } from '@zhin.js/host-http';
 export const LOCAL_OWNER_PRINCIPAL = Object.freeze({
     kind: 'user',
-    userId: 'local',
+    userId: LOCAL_SOCKET_USER_ID,
     username: 'local',
     displayName: '本机 CLI（网关控制套接字）',
-    credentialId: 'local-socket',
+    credentialId: LOCAL_SOCKET_CREDENTIAL_ID,
     grants: Object.freeze([Object.freeze({ role: 'owner', scope: Object.freeze({ kind: 'global' }), permissions: CONSOLE_PERMISSION_LIST })]),
     roles: Object.freeze(['owner']),
 });

package/lib/http/plugin-switch-rpc.js

@@ -17,7 +17,7 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME, FEATURE_OVERRIDES_KEY } from '@zhin.js/plugin-runtime';
 import { collectFeatureOverrideWarnings, createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -39,6 +39,7 @@ export function createGatewayPluginSwitchRpc(options) {
     return Object.freeze({
         owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
         claims: isGatewayPluginSwitch,
+        types: () => [PLUGIN_RPC.SET_ENABLED, FEATURE_RPC.SET_ENABLED],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const type = String(message.type ?? '');
@@ -49,27 +50,27 @@ export function createGatewayPluginSwitchRpc(options) {
             }
             // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${type}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const reply = type === PLUGIN_RPC.SET_ENABLED
                 ? await setPluginEnabled(message, principal, options, readConfig)
                 : await setFeatureGlobal(message, principal, options, readConfig);
-            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error');
+            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error', reply.status === 403 ? CONSOLE_DENIAL_REASONS.HANDLER_DENIED : undefined);
             return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
         },
     });
@@ -176,7 +177,7 @@ async function runSwitch(plugin, enabled, principal, options, type) {
         return { result };
     const action = enabled ? '启用' : '停用';
     const text = result.status === 'rollbackFailed'
-        ? `${action} ${plugin} 失败，且回滚未完成：${result.rollbackError ?? '未知错误'}（原因：${result.error ?? '未知错误'}）`
+        ? `${action} ${plugin} 失败，且回滚未完成：${[result.rollbackError, result.restartError ? `重新启动实例失败：${result.restartError}` : undefined].filter(Boolean).join('；') || '未知错误'}（原因：${result.error ?? '未知错误'}）`
         : `${action} ${plugin} 失败，已回滚：${result.error ?? '未知错误'}`;
     return {
         reply: error(500, result.status === 'rollbackFailed' ? 'rollback_failed' : 'transaction_failed', text, type, {

package/lib/http/start-gateway.d.ts

@@ -14,7 +14,7 @@ import { GatewayHttpServer } from './gateway-http-server.js';
  * optional {@link GatewayConsoleInstancePort} methods (plugin catalog, instance audit,
  * `principal-revoked`) when the transport has them (`IpcInstanceTransport` does).
  */
-export interface GatewayInstanceTransport extends InstanceTransport, GatewayConsoleInstancePort {
+export interface GatewayInstanceTransport extends InstanceTransport, Omit<GatewayConsoleInstancePort, 'ready' | 'onRoutes'> {
     dispose?(): void | Promise<void>;
     /** Told the bound listener addresses after listen (the instance's `HttpHost.address`). */
     setAddresses?(addresses: readonly import('@zhin.js/host-http').HttpHostAddress[]): void;

package/lib/http/start-gateway.js

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createConfigDocument } from '@zhin.js/runtime';
 import { findConfigFile } from '../project/config-file.js';
+import { projectIdentity } from '../project/identity.js';
 import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
 import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
 import { GatewayPackageService } from '../packages/service.js';
@@ -113,6 +114,7 @@ export async function startGateway(options) {
         ...(options.retryAfterSeconds !== undefined ? { retryAfterSeconds: options.retryAfterSeconds } : {}),
         ...(options.maxRequestBodyBytes !== undefined ? { maxRequestBodyBytes: options.maxRequestBodyBytes } : {}),
         consoleRpc: createGatewayConsoleRpc(rpc),
+        projectId: projectIdentity(options.projectRoot),
     });
     registry = server.tokenRegistry;
     // The Console's global plugin switch is a gateway transaction (stop → write → start, rollback);

package/lib/iam/service.js

@@ -460,9 +460,18 @@ export class ConsoleIamService {
                 row.permissions = JSON.stringify(permissionList(patch.permissions));
             if (Object.keys(row).length)
                 await this.#model('roles').update(row).where({ id });
+            // Grants of every holder may have shrunk: their long-lived connections and anything the
+            // instance derived from their grants (open chat bind codes) re-authorize from scratch.
+            if (patch.permissions !== undefined)
+                for (const userId of await this.#usersBoundTo(id))
+                    this.#emitRevocation(userId, 'bindings');
             return withPluginPermissions((await this.#role(id)), this.pluginPermissionCatalog());
         });
     }
+    async #usersBoundTo(roleId) {
+        const rows = await this.#model('bindings').select('user_id').where({ role_id: roleId });
+        return [...new Set(rows.map(row => String(row.user_id)))];
+    }
     deleteRole(id) {
         return this.#serialize(async () => {
             const role = await this.#role(id);
@@ -470,8 +479,11 @@ export class ConsoleIamService {
                 throw new IamError('not_found', '角色不存在');
             if (role.builtin)
                 throw new IamError('forbidden', '内置角色不可删除');
+            const holders = await this.#usersBoundTo(id);
             await this.#model('bindings').delete().where({ role_id: id });
             await this.#model('roles').delete().where({ id });
+            for (const userId of holders)
+                this.#emitRevocation(userId, 'bindings');
         });
     }
     /** Replaces all bindings of a user. */

package/lib/iam/setup-service.d.ts

@@ -37,7 +37,9 @@ export interface SetupDatabaseInput {
 /** Config-file and dotenv access the setup flow needs (ConsoleConfigurationStore satisfies `config`). */
 export interface SetupConfigPort {
     readDocument(): Promise<Record<string, unknown>>;
-    setKey(key: string, value: unknown): Promise<unknown>;
+    setKey(key: string, value: unknown, options?: {
+        readonly environmentWrite?: boolean;
+    }): Promise<unknown>;
 }
 export interface SetupEnvFilePort {
     read(): Promise<string>;

package/lib/iam/setup-service.js

@@ -101,7 +101,8 @@ export class ConsoleSetupService {
         if (Object.keys(envUpdates).length) {
             await this.#options.envFile.write(upsertDotenv(await this.#options.envFile.read(), envUpdates));
         }
-        await this.#options.config.setKey('database', block);
+        // The setup flow writes `.env` itself (bootstrap / owner): secret literals may go there too.
+        await this.#options.config.setKey('database', block, { environmentWrite: true });
         const notice = prepared.dialect === 'pg' || prepared.dialect === 'mysql' ? `${SETUP_NO_MIGRATION_NOTICE}${SETUP_CONSOLE_ROLE_NOTICE}` : SETUP_NO_MIGRATION_NOTICE;
         return Object.freeze({ restartRequired: true, notice });
     }

package/lib/onboarding/ignored-builds.d.ts

@@ -0,0 +1,18 @@
+export declare const PNPM_IGNORED_BUILDS_CODE = "ERR_PNPM_IGNORED_BUILDS";
+/** Cap on the package-manager output kept to recognise the error (its summary comes last). */
+export declare const IGNORED_BUILDS_OUTPUT_LIMIT: number;
+/**
+ * The packages pnpm reports in `Ignored build scripts: a@1.0.0, @scope/b@2.0.0.`; `undefined` when
+ * the output does not carry `ERR_PNPM_IGNORED_BUILDS` (an empty list when the list is unreadable).
+ */
+export declare function parseIgnoredBuilds(output: string): readonly string[] | undefined;
+/** Package names named by an `add` invocation (`add [-w] [-D] <spec>…`); empty for other commands. */
+export declare function addedPackageNames(args: readonly string[]): readonly string[];
+/**
+ * Whether the dependencies of `args` are in place after pnpm reported ignored builds: pnpm wrote
+ * `node_modules/.modules.yaml` (it does so after linking) and every package an `add` named is in
+ * `node_modules`. Only then is the exit treated as a warning.
+ */
+export declare function dependenciesInPlace(projectRoot: string, args: readonly string[]): Promise<boolean>;
+/** The hint printed for ignored builds: same allowance the scaffold writes for native packages. */
+export declare function ignoredBuildsHint(names: readonly string[]): string;