@zhin.js/gateway 1.1.1 → 1.2.0

package/lib/iam/rpc.js

@@ -18,7 +18,7 @@ export async function dispatchIamRpc(message, service, principal) {
     const ok = (data) => ({ status: 200, body: { success: true, data, type, requestId } });
     try {
         if (!service?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+            throw new IamError('unavailable', service?.publicUnavailable()?.message ?? 'Console 访问控制尚未就绪');
         const id = (key = 'id') => {
             const value = payload[key];
             if (typeof value !== 'string' || !value)

package/lib/iam/service.d.ts

@@ -83,7 +83,24 @@ export interface ConsoleIamServiceOptions {
      * Without it, levels are inferred from the permission suffix.
      */
     readonly pluginPermissions?: () => readonly ConsolePluginPermissionInfo[];
+    /**
+     * Why access control is closed right now (gateway.db not open, the import of the old project
+     * database tables not finished, ADR 0059 §3), or undefined. While closed the service fails
+     * closed: {@link ConsoleIamService.initialized} is true (the bootstrap token is refused),
+     * nothing authenticates and `/auth/*` answers 503 — an empty store never reads as "no owner".
+     */
+    readonly unavailable?: () => string | undefined;
+    /**
+     * Category of `unavailable` (`starting`, `store`, `migration`, `store_lost`, …). Anonymous HTTP
+     * callers only ever see this code and a generic message; the detail (paths, driver messages)
+     * goes to the logs and to the local owner (`zhin doctor`, `zhin console migrate`).
+     */
+    readonly unavailableCode?: () => string | undefined;
+    /** Called after the first owner was created (the gateway then makes sure its store marker exists). */
+    readonly onOwnerCreated?: () => void;
 }
+/** What anonymous callers learn while access control is closed (no paths or driver messages). */
+export declare const IAM_UNAVAILABLE_PUBLIC_MESSAGE = "Console \u8BBF\u95EE\u63A7\u5236\u6682\u4E0D\u53EF\u7528\uFF1A\u8BF7\u5728\u670D\u52A1\u5668\u4E0A\u8FD0\u884C zhin doctor \u67E5\u770B\u539F\u56E0";
 /**
  * What is wrong with a new account's username / password, or null — the rules
  * {@link ConsoleIamService.createUser} / `createOwner` enforce, for callers that must check before
@@ -104,6 +121,13 @@ export declare class ConsoleIamService implements ConsoleAccessProvider {
     #private;
     constructor(options: ConsoleIamServiceOptions);
     get ready(): boolean;
+    /** See {@link ConsoleIamServiceOptions.unavailable} (detail: logs and the local owner only). */
+    unavailableReason(): string | undefined;
+    /** `{ code, message }` safe for any HTTP caller while closed, or undefined. */
+    publicUnavailable(): {
+        readonly code: string;
+        readonly message: string;
+    } | undefined;
     /** Seeds built-in roles and loads the owner state; call after the database started. */
     start(options?: Readonly<{
         timers?: boolean;
@@ -201,3 +225,10 @@ export declare class ConsoleIamService implements ConsoleAccessProvider {
     /** Daily: audit older than the retention window and expired sessions. */
     cleanup(): Promise<void>;
 }
+/** Longest stored audit `detail` (characters of JSON). */
+export declare const AUDIT_DETAIL_MAX_LENGTH = 4096;
+/**
+ * Audit detail as JSON that always parses back: a detail longer than the column budget is
+ * replaced by `{ truncated, length, preview }` instead of being cut mid-string.
+ */
+export declare function auditDetailJson(detail: unknown): string;

package/lib/iam/service.js

@@ -21,6 +21,8 @@ export class IamError extends Error {
         this.status = STATUS[code];
     }
 }
+/** What anonymous callers learn while access control is closed (no paths or driver messages). */
+export const IAM_UNAVAILABLE_PUBLIC_MESSAGE = 'Console 访问控制暂不可用：请在服务器上运行 zhin doctor 查看原因';
 const USERNAME = /^[a-z0-9][a-z0-9._-]{1,63}$/u;
 /**
  * What is wrong with a new account's username / password, or null — the rules
@@ -48,6 +50,9 @@ export class ConsoleIamService {
     #limiter;
     #onError;
     #pluginPermissions;
+    #unavailable;
+    #unavailableCode;
+    #onOwnerCreated;
     #ready = false;
     #initialized;
     #cleanupTimer;
@@ -64,9 +69,22 @@ export class ConsoleIamService {
         this.#limiter = options.rateLimiter ?? new LoginRateLimiter({ now: this.#now });
         this.#onError = options.onError ?? (() => undefined);
         this.#pluginPermissions = options.pluginPermissions ?? (() => []);
+        this.#unavailable = options.unavailable ?? (() => undefined);
+        this.#unavailableCode = options.unavailableCode ?? (() => undefined);
+        this.#onOwnerCreated = options.onOwnerCreated;
     }
     get ready() {
-        return this.#ready;
+        return this.#ready && this.#unavailable() === undefined;
+    }
+    /** See {@link ConsoleIamServiceOptions.unavailable} (detail: logs and the local owner only). */
+    unavailableReason() {
+        return this.#unavailable();
+    }
+    /** `{ code, message }` safe for any HTTP caller while closed, or undefined. */
+    publicUnavailable() {
+        if (this.#unavailable() === undefined)
+            return undefined;
+        return Object.freeze({ code: this.#unavailableCode() ?? 'unavailable', message: IAM_UNAVAILABLE_PUBLIC_MESSAGE });
     }
     /** Seeds built-in roles and loads the owner state; call after the database started. */
     async start(options = {}) {
@@ -115,6 +133,8 @@ export class ConsoleIamService {
         clearInterval(this.#refreshTimer);
     }
     initialized() {
+        if (this.#unavailable() !== undefined)
+            return true;
         if (this.#initialized === true)
             return true;
         // Database not up yet, or another process (`zhin console init` beside a running gateway)
@@ -156,7 +176,7 @@ export class ConsoleIamService {
     }
     // ------------------------------------------------------------------ authentication
     async authenticate(token, meta = {}) {
-        if (!this.#ready || !token || token.length > 256)
+        if (!this.ready || !token || token.length > 256)
             return null;
         const hash = sha256(token);
         const now = this.#now();
@@ -199,7 +219,7 @@ export class ConsoleIamService {
             action: entry.action.slice(0, 256),
             target: entry.target?.slice(0, 256) ?? null,
             outcome: entry.outcome,
-            detail: entry.detail ? JSON.stringify(entry.detail).slice(0, 4096) : null,
+            detail: entry.detail ? auditDetailJson(entry.detail) : null,
             ip: entry.ip?.slice(0, 64) ?? null,
         }).catch(this.#onError);
     }
@@ -312,7 +332,14 @@ export class ConsoleIamService {
             this.#requireReady();
             if ((await this.#activeOwnerIds()).size > 0)
                 throw new IamError('conflict', '已初始化：所有者已存在');
-            return this.#createUser({ ...input, bindings: [{ role: 'owner', scopeKind: 'global' }] });
+            const owner = await this.#createUser({ ...input, bindings: [{ role: 'owner', scopeKind: 'global' }] });
+            try {
+                this.#onOwnerCreated?.();
+            }
+            catch (error) {
+                this.#onError(error);
+            }
+            return owner;
         });
     }
     /** Issues a session for a user (setup returns one for the new owner). */
@@ -782,3 +809,21 @@ function auditView(row) {
         ip: row.ip === null || row.ip === undefined ? null : String(row.ip),
     });
 }
+/** Longest stored audit `detail` (characters of JSON). */
+export const AUDIT_DETAIL_MAX_LENGTH = 4096;
+/**
+ * Audit detail as JSON that always parses back: a detail longer than the column budget is
+ * replaced by `{ truncated, length, preview }` instead of being cut mid-string.
+ */
+export function auditDetailJson(detail) {
+    const json = JSON.stringify(detail) ?? 'null';
+    if (json.length <= AUDIT_DETAIL_MAX_LENGTH)
+        return json;
+    let keep = AUDIT_DETAIL_MAX_LENGTH - 64;
+    for (;;) {
+        const replacement = JSON.stringify({ truncated: true, length: json.length, preview: json.slice(0, Math.max(0, keep)) });
+        if (replacement.length <= AUDIT_DETAIL_MAX_LENGTH || keep <= 0)
+            return replacement;
+        keep -= replacement.length - AUDIT_DETAIL_MAX_LENGTH;
+    }
+}

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

@@ -55,6 +55,8 @@ export interface ConsoleSetupServiceOptions {
     readonly driverAvailable?: (dialect: SetupDialect) => Promise<boolean>;
 }
 export declare const SETUP_NO_MIGRATION_NOTICE = "\u5207\u6362\u6570\u636E\u5E93\u4E0D\u4F1A\u8FC1\u79FB\u65E7\u5E93\u6570\u636E\uFF1A\u63D2\u4EF6\u6570\u636E\u4ECD\u7559\u5728\u539F\u6570\u636E\u5E93\u3002";
+/** PostgreSQL / MySQL: raw Console SQL needs the restricted account (ADR 0059 §4). */
+export declare const SETUP_CONSOLE_ROLE_NOTICE = "PostgreSQL / MySQL \u4E0A Console \u7684\u539F\u59CB SQL \u53EA\u7528\u53D7\u9650\u8D26\u53F7\u6267\u884C\uFF1A\u8FD0\u884C zhin db console-role \u521B\u5EFA\uFF08\u65E0\u5EFA\u53F7\u6743\u9650\u65F6\u52A0 --print-sql \u4EA4\u7ED9 DBA\uFF09\u3002";
 /**
  * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
  * Database changes are written to the config file / `.env`; restarting is the caller's job.

package/lib/iam/setup-service.js

@@ -3,7 +3,6 @@ import { isDatabaseDriverAvailable, probeDatabaseConnection, } from '@zhin.js/da
 import { expandEnvironmentValue } from '@zhin.js/plugin-runtime';
 import { DATABASE_DIALECT_DEFINITIONS, validateDatabaseConfig, } from '@zhin.js/scaffold-wizard';
 import { IamError } from './service.js';
-import { IAM_DIALECTS } from './tables.js';
 const DEFAULT_SQLITE_FILE = '.zhin/data.sqlite';
 const SECRET_FIELDS = new Set(['password']);
 const ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/u;
@@ -34,7 +33,14 @@ function fieldsOf(definition) {
             })];
     }));
 }
-const SETUP_DEFINITIONS = DATABASE_DIALECT_DEFINITIONS.filter(definition => IAM_DIALECTS.has(definition.dialect));
+/**
+ * Dialects the wizard can test a connection for. Console accounts no longer depend on it: they
+ * live in `.zhin/gateway.db` (ADR 0059); a redis / memory project keeps its database block.
+ */
+const SETUP_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
+const SETUP_DEFINITIONS = DATABASE_DIALECT_DEFINITIONS.filter(definition => SETUP_DIALECTS.has(definition.dialect));
+/** PostgreSQL / MySQL: raw Console SQL needs the restricted account (ADR 0059 §4). */
+export const SETUP_CONSOLE_ROLE_NOTICE = 'PostgreSQL / MySQL 上 Console 的原始 SQL 只用受限账号执行：运行 zhin db console-role 创建（无建号权限时加 --print-sql 交给 DBA）。';
 /**
  * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
  * Database changes are written to the config file / `.env`; restarting is the caller's job.
@@ -96,12 +102,13 @@ export class ConsoleSetupService {
             await this.#options.envFile.write(upsertDotenv(await this.#options.envFile.read(), envUpdates));
         }
         await this.#options.config.setKey('database', block);
-        return Object.freeze({ restartRequired: true, notice: SETUP_NO_MIGRATION_NOTICE });
+        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 });
     }
     async createOwner(input) {
         const iam = this.#options.iam();
         if (!iam?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+            throw new IamError('unavailable', iam?.publicUnavailable()?.message ?? 'Console 访问控制尚未就绪');
         if (iam.initialized())
             throw new IamError('conflict', '已初始化：请改用 zhin console user 管理用户');
         return { user: await iam.createOwner(input) };

package/lib/iam/tables.d.ts

@@ -1,4 +1,7 @@
-/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+/**
+ * Console access-control tables (ADR 0049 §2). Since ADR 0059 they live in the gateway's own store
+ * `.zhin/gateway.db` (SQLite), whatever the project database is.
+ */
 export declare const IAM_TABLES: Readonly<{
     readonly users: "console_users";
     readonly roles: "console_roles";
@@ -8,13 +11,10 @@ export declare const IAM_TABLES: Readonly<{
     readonly audit: "console_audit_log";
 }>;
 export declare const IAM_TABLE_DEFINITIONS: Readonly<Record<string, Record<string, unknown>>>;
-/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
-export declare const IAM_DIALECTS: ReadonlySet<string>;
 export interface IamTableHost {
-    readonly dialect: string;
     readonly started: boolean;
     define(name: string, definition: Record<string, unknown>): void;
     tables(): readonly string[];
 }
-/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
-export declare function defineConsoleIamTables(host: IamTableHost): boolean;
+/** Idempotent; must run before the database starts. */
+export declare function defineConsoleIamTables(host: IamTableHost): void;

package/lib/iam/tables.js

@@ -1,4 +1,7 @@
-/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+/**
+ * Console access-control tables (ADR 0049 §2). Since ADR 0059 they live in the gateway's own store
+ * `.zhin/gateway.db` (SQLite), whatever the project database is.
+ */
 export const IAM_TABLES = Object.freeze({
     users: 'console_users',
     roles: 'console_roles',
@@ -65,18 +68,13 @@ export const IAM_TABLE_DEFINITIONS = Object.freeze({
         ip: text(true),
     },
 });
-/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
-export const IAM_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
-/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
+/** Idempotent; must run before the database starts. */
 export function defineConsoleIamTables(host) {
-    if (!IAM_DIALECTS.has(host.dialect))
-        return false;
     if (host.started)
-        return true;
+        return;
     const existing = new Set(host.tables());
     for (const [name, definition] of Object.entries(IAM_TABLE_DEFINITIONS)) {
         if (!existing.has(name))
             host.define(name, definition);
     }
-    return true;
 }

package/lib/local/handler.js

@@ -53,7 +53,7 @@ async function handleHttp(options, data) {
     const result = { status: response.status, headers, body: text };
     return { ok: true, data: result };
 }
-const STREAMED = new Set([GATEWAY_RPC.INSTALL, GATEWAY_RPC.UNINSTALL, GATEWAY_RPC.UPDATE, GATEWAY_RPC.DECLARE]);
+const STREAMED = new Set([GATEWAY_RPC.INSTALL, GATEWAY_RPC.UNINSTALL, GATEWAY_RPC.UPDATE, GATEWAY_RPC.DECLARE, GATEWAY_RPC.ENABLE, GATEWAY_RPC.DISABLE]);
 export function createLocalRpcHandler(options) {
     return async (request, emit) => {
         if (request.type === LOCAL_GATEWAY_RPC.INFO)

package/lib/local/protocol.d.ts

@@ -33,6 +33,12 @@ export declare const LOCAL_GATEWAY_RPC: Readonly<{
     readonly CONSOLE_USER_PASSWD: "gateway.console.user.passwd";
     /** `{ username, disabled }`. */
     readonly CONSOLE_USER_DISABLE: "gateway.console.user.disable";
+    /**
+     * `zhin console migrate` / `zhin doctor` beside a running gateway (ADR 0059 §3): the state of the
+     * import of the old `console_*` tables (`{ record, pending?, reappeared?, problem? }`), read by
+     * the gateway, the only process that opens `.zhin/gateway.db` while it runs.
+     */
+    readonly CONSOLE_MIGRATION_STATUS: "gateway.console.migration.status";
     /**
      * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
      * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no

package/lib/local/protocol.js

@@ -39,6 +39,12 @@ export const LOCAL_GATEWAY_RPC = Object.freeze({
     CONSOLE_USER_PASSWD: 'gateway.console.user.passwd',
     /** `{ username, disabled }`. */
     CONSOLE_USER_DISABLE: 'gateway.console.user.disable',
+    /**
+     * `zhin console migrate` / `zhin doctor` beside a running gateway (ADR 0059 §3): the state of the
+     * import of the old `console_*` tables (`{ record, pending?, reappeared?, problem? }`), read by
+     * the gateway, the only process that opens `.zhin/gateway.db` while it runs.
+     */
+    CONSOLE_MIGRATION_STATUS: 'gateway.console.migration.status',
     /**
      * `{base}/…` request on behalf of the local owner ({@link LocalGatewayHttpRequest}): what
      * `zhin config` / `schedule` / `send` / `watch` use while a gateway runs, so they need no

package/lib/packages/authorization.d.ts

@@ -18,6 +18,7 @@ export declare function gatewayPrincipalAllows(principal: GatewayPrincipal | und
  * - bootstrap token: `install` of allowlisted database drivers only, before the first owner (ADR 0053 §3);
  * - `plugin.manage` without a global owner binding: allowlisted packages only (ADR 0053 §3);
  * - owners and the local socket: any npm package by name, with the same strict spec rules.
- * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`;
+ * `enable` / `disable` take the declared package (a bare name, or a `./` local plugin for owners).
  */
 export declare function authorizePackages(principal: GatewayPrincipal | undefined, operation: GatewayTransactionOperation, requests: readonly unknown[] | 'all', options: AuthorizePackagesOptions): readonly GatewayAuthorizedPackage[];

package/lib/packages/authorization.js

@@ -3,6 +3,8 @@ import { authorizeInstall, parseInstallRequest } from '../onboarding/allowlist.j
 import { OnboardingError } from '../onboarding/errors.js';
 import { GatewayError } from './errors.js';
 const MAX_PACKAGES = 32;
+/** A project-local plugin package reference as declared in `plugins.<instanceKey>`. */
+const LOCAL_PACKAGE = /^\.\/[A-Za-z0-9._@-]+(?:\/[A-Za-z0-9._@-]+)*$/u;
 const EXACT_VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}(?:-[0-9A-Za-z][0-9A-Za-z.-]{0,63})?$/u;
 /** A global `owner` binding, or the local control socket. */
 export function isGatewayOwner(principal) {
@@ -32,7 +34,8 @@ function rethrow(error) {
  * - bootstrap token: `install` of allowlisted database drivers only, before the first owner (ADR 0053 §3);
  * - `plugin.manage` without a global owner binding: allowlisted packages only (ADR 0053 §3);
  * - owners and the local socket: any npm package by name, with the same strict spec rules.
- * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`;
+ * `enable` / `disable` take the declared package (a bare name, or a `./` local plugin for owners).
  */
 export function authorizePackages(principal, operation, requests, options) {
     if (!principal)
@@ -73,7 +76,21 @@ export function authorizePackages(principal, operation, requests, options) {
     }
     const seen = new Set();
     const authorized = [];
+    const toggle = operation === 'enable' || operation === 'disable';
     for (const request of requests) {
+        // enable / disable name the declared package, which may be a project-local plugin directory.
+        if (toggle && typeof request === 'string' && request.startsWith('./')) {
+            if (!LOCAL_PACKAGE.test(request) || request.split('/').slice(1).some(part => part === '.' || part === '..')) {
+                throw new GatewayError('invalid_input', `本地插件路径无效：${request.slice(0, 64)}`);
+            }
+            if (!owner)
+                throw new GatewayError('forbidden', '只有所有者可以启停本地插件');
+            if (seen.has(request))
+                throw new GatewayError('invalid_input', `重复的包：${request}`);
+            seen.add(request);
+            authorized.push(Object.freeze({ name: request, spec: request, source: 'local' }));
+            continue;
+        }
         let parsed;
         try {
             parsed = parseInstallRequest(request);
@@ -93,6 +110,8 @@ export function authorizePackages(principal, operation, requests, options) {
             throw new GatewayError('invalid_input', `卸载 ${name} 时不能指定版本`);
         if (operation === 'declare' && version !== undefined)
             throw new GatewayError('invalid_input', `声明 ${name} 时不能指定版本`);
+        if (toggle && version !== undefined)
+            throw new GatewayError('invalid_input', `启停 ${name} 时不能指定版本`);
         if (operation === 'update' && version !== undefined && !EXACT_VERSION.test(version)) {
             throw new GatewayError('invalid_input', `${name} 的更新版本必须是精确 semver 版本`);
         }

package/lib/packages/rpc.js

@@ -64,6 +64,11 @@ async function handle(type, data, principal, deps) {
                 principal, ...optionalBoolean(data, 'startInstance'),
             });
         }
+        case 'gateway.plugins.enable':
+        case 'gateway.plugins.disable':
+            return packagesOf(deps).setEnabled({ plugin: data.plugin }, type === 'gateway.plugins.enable', {
+                principal, ...optionalBoolean(data, 'startInstance'),
+            });
         case 'gateway.instance.status': return instanceStatus(instanceOf(deps).status());
         case 'gateway.instance.logs': {
             const lines = data.lines === undefined ? DEFAULT_LOG_LINES : data.lines;

package/lib/packages/service.d.ts

@@ -36,6 +36,13 @@ export interface PackageWorkflowPort {
     declare?(request: string, config?: unknown, options?: {
         readonly instanceKey?: string;
     }): Promise<unknown>;
+    /** Validates an enable / disable without writing (throws `PluginEnablementError`). */
+    planSetEnabled?(request: string, enabled: boolean): Promise<{
+        readonly packageName: string;
+        readonly instanceKey: string;
+        readonly changed: boolean;
+    }>;
+    setEnabled?(request: string, enabled: boolean): Promise<unknown>;
 }
 /**
  * Runs the package manager with pnpm-style args (`add|remove|update|install …`), streaming output.
@@ -88,6 +95,10 @@ export interface GatewayDeclareRequest {
     readonly instanceKey?: unknown;
     readonly config?: unknown;
 }
+export interface GatewaySetEnabledRequest {
+    /** A declared instance key, or the package name of a package declared exactly once. */
+    readonly plugin: unknown;
+}
 export declare const DEFAULT_PACKAGE_READY_TIMEOUT_MS = 60000;
 export declare const DEFAULT_PACKAGE_STABLE_MS = 5000;
 export declare class GatewayPackageService {
@@ -111,6 +122,13 @@ export declare class GatewayPackageService {
      * the configuration file back and starts the previous instance again.
      */
     declare(request: GatewayDeclareRequest, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
+    /**
+     * `gateway.plugins.enable` / `gateway.plugins.disable`: rewrites `disable_plugins` for one
+     * declared instance, then restarts the instance (a failed start restores the configuration file
+     * and starts the previous instance again). Validation runs before the instance is touched; an
+     * instance already in the requested state succeeds without stopping anything or writing.
+     */
+    setEnabled(request: GatewaySetEnabledRequest, enabled: boolean, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
     uninstall(packages: readonly unknown[], options: GatewayUninstallOptions): Promise<GatewayPackageTransactionResult>;
     /** Exact versions go through the workflow (verified); bare names / `'all'` run the manager's update. */
     update(packages: readonly unknown[] | 'all', options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;

package/lib/packages/service.js

@@ -10,7 +10,7 @@ import { CONSOLE_PERMISSIONS } from '@zhin.js/console-protocol';
 import { createInstallAllowlist } from '../onboarding/allowlist.js';
 import { InstallOutputRelay, streamEvents } from '../onboarding/install.js';
 import { createStreamingPackageManager, detectPackageManager } from '../onboarding/package-manager.js';
-import { PluginDeclarationError, PluginManagementOperationError, PluginManagementWorkflow } from '../plugin-management/workflow.js';
+import { PluginDeclarationError, PluginEnablementError, PluginManagementOperationError, PluginManagementWorkflow } from '../plugin-management/workflow.js';
 import { InstanceStartError } from '../supervisor/instance-supervisor.js';
 import { authorizePackages, gatewayPrincipalAllows } from './authorization.js';
 import { GatewayError } from './errors.js';
@@ -20,6 +20,8 @@ export const DEFAULT_PACKAGE_STABLE_MS = 5_000;
 const LOCK_FILE = 'gateway-packages.lock';
 const LOG_TAIL_LINES = 50;
 const RUNNING_STATES = new Set(['running', 'starting', 'backoff']);
+/** Transactions that only write the configuration file: no package manager, no reinstall on rollback. */
+const CONFIG_ONLY_OPERATIONS = new Set(['declare', 'enable', 'disable']);
 /** Thrown inside a transaction when the instance does not come up; carries its log tail. */
 class InstanceStartFailure extends Error {
     logTail;
@@ -145,6 +147,60 @@ export class GatewayPackageService {
             await ctx.workflow.declare(authorized[0].name, config, declareOptions);
         });
     }
+    /**
+     * `gateway.plugins.enable` / `gateway.plugins.disable`: rewrites `disable_plugins` for one
+     * declared instance, then restarts the instance (a failed start restores the configuration file
+     * and starts the previous instance again). Validation runs before the instance is touched; an
+     * instance already in the requested state succeeds without stopping anything or writing.
+     */
+    async setEnabled(request, enabled, options) {
+        const workflow = this.#workflow;
+        if (!workflow.planSetEnabled || !workflow.setEnabled)
+            throw new GatewayError('unavailable', '插件启停不可用');
+        const operation = enabled ? 'enable' : 'disable';
+        // Permission before anything about the project is read.
+        if (!options.principal || options.principal !== 'local' && options.principal.kind === 'bootstrap'
+            || !gatewayPrincipalAllows(options.principal, CONSOLE_PERMISSIONS.PLUGIN_MANAGE)) {
+            throw new GatewayError('forbidden', `需要 ${CONSOLE_PERMISSIONS.PLUGIN_MANAGE} 权限`);
+        }
+        if (typeof request.plugin !== 'string' || !request.plugin.trim() || request.plugin.length > 256) {
+            throw new GatewayError('invalid_input', 'plugin 必须是插件包名或 instanceKey');
+        }
+        let plan;
+        try {
+            plan = await workflow.planSetEnabled(request.plugin, enabled);
+        }
+        catch (error) {
+            throw enablementError(error);
+        }
+        const plugin = Object.freeze({ instanceKey: plan.instanceKey, packageName: plan.packageName, enabled, changed: plan.changed });
+        if (!plan.changed)
+            return this.#unchanged(operation, await this.authorize(options.principal, operation, [plan.packageName]), plugin, options);
+        return this.#transaction(operation, [plan.packageName], options, async (ctx) => {
+            // The exact instance key: the declaration may not be re-resolved to another instance.
+            await ctx.workflow.setEnabled(plan.instanceKey, enabled);
+            return { plugin };
+        });
+    }
+    /** The result of an enable / disable that found nothing to change (instance untouched). */
+    #unchanged(operation, authorized, plugin, options) {
+        const now = (this.#options.now ?? Date.now)();
+        const id = randomUUID();
+        const state = this.#instanceState();
+        const result = Object.freeze({
+            id, operation, packages: authorized, ok: true, status: 'succeeded', plugin,
+            instance: Object.freeze({ before: state, after: state }), startedAt: now, finishedAt: now,
+        });
+        for (const event of [{ type: 'start', id, operation, packages: authorized }, { type: 'phase', id, phase: 'done' }, { type: 'result', id, result }]) {
+            for (const listener of [options.onEvent, ...this.#listeners]) {
+                try {
+                    listener?.(event);
+                }
+                catch { /* listeners never break a request */ }
+            }
+        }
+        return result;
+    }
     uninstall(packages, options) {
         return this.#transaction('uninstall', packages, options, async (ctx, authorized) => {
             for (const item of authorized) {
@@ -229,7 +285,7 @@ export class GatewayPackageService {
         // Rollback log tails only show what this transaction's instances printed.
         const logMark = instance?.logs?.tail(1).at(-1)?.seq ?? -1;
         // A declaration only writes the configuration file: no package manager, no reinstall on rollback.
-        const configOnly = operation === 'declare';
+        const configOnly = CONFIG_ONLY_OPERATIONS.has(operation);
         let extras = undefined;
         let snapshot;
         let mutated = false;
@@ -296,6 +352,7 @@ export class GatewayPackageService {
                 ...(rollbackFailure === undefined ? {} : { rollbackError: failureMessage(rollbackFailure) }),
                 ...(logTail?.length ? { logTail } : {}),
                 ...(status === 'succeeded' && extras?.needsConfiguration?.length ? { needsConfiguration: extras.needsConfiguration } : {}),
+                ...(status === 'succeeded' && extras?.plugin ? { plugin: extras.plugin } : {}),
                 instance: Object.freeze({ before, after: this.#instanceState() }),
                 startedAt,
                 finishedAt: now(),
@@ -424,10 +481,16 @@ function declarationError(error) {
         ? new GatewayError('invalid_input', error.message, { cause: error, details: { errors: error.errors, missingEnv: error.missingEnv } })
         : error;
 }
+/** A refused enable / disable is the caller's input problem; anything else stays internal. */
+function enablementError(error) {
+    return error instanceof PluginEnablementError
+        ? new GatewayError('invalid_input', error.message, { cause: error, details: { errors: error.errors, missingEnv: error.missingEnv } })
+        : error;
+}
 /** Structured feedback of a declaration refused inside the transaction (config changed after preflight). */
 function declarationDetails(error) {
     const cause = error instanceof PluginManagementOperationError ? error.cause : error;
-    if (!(cause instanceof PluginDeclarationError))
+    if (!(cause instanceof PluginDeclarationError) && !(cause instanceof PluginEnablementError))
         return {};
     return {
         ...(cause.errors?.length ? { errors: cause.errors } : {}),

package/lib/plugin-management/config-explanation.js

@@ -1,5 +1,5 @@
 import { isDeepStrictEqual } from 'node:util';
-import { parsePluginConfigSchema } from '@zhin.js/runtime';
+import { isSecretConfigSchema, parsePluginConfigSchema } from '@zhin.js/runtime';
 import { readStringLiteralOptions } from '../config/console-schema.js';
 const complexKeywords = ['$ref', '$dynamicRef', 'anyOf', 'oneOf', 'allOf', 'not', 'if', 'then', 'else', 'dependentSchemas', 'dependentRequired', 'patternProperties', 'prefixItems', 'unevaluatedProperties'];
 const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
@@ -28,7 +28,7 @@ export function explainConfigFields(schema, input, current, committedInput) {
             return;
         }
         const metadata = record(node['x-zhin-config']) ? node['x-zhin-config'] : {};
-        const secret = inheritedSecret || node.writeOnly === true || metadata.secret === true || metadata.hidden === true || metadata.component === 'password';
+        const secret = inheritedSecret || isSecretConfigSchema(node) || metadata.hidden === true;
         if (node.type === 'object') {
             if (node.properties !== undefined && !record(node.properties)) {
                 issue = 'complex-schema';
@@ -54,7 +54,7 @@ export function explainConfigFields(schema, input, current, committedInput) {
         }
         const items = list && record(node.items) ? node.items : {};
         const itemMetadata = record(items['x-zhin-config']) ? items['x-zhin-config'] : {};
-        const itemSecret = items.writeOnly === true || itemMetadata.secret === true || itemMetadata.hidden === true || itemMetadata.component === 'password';
+        const itemSecret = isSecretConfigSchema(items) || itemMetadata.hidden === true;
         fields.push({ path: Object.freeze([...path]), secret: secret || itemSecret, list });
     };
     visit(schema, [], false);

package/lib/plugin-management/workflow.d.ts

@@ -33,6 +33,36 @@ export declare class PluginDeclarationError extends Error {
         message: string;
     }[], missingEnv?: readonly string[]);
 }
+/** Why an enable / disable request was refused before anything was written. */
+export type PluginEnablementErrorCode = 'invalid-request' | 'reserved' | 'root' | 'not-declared' | 'not-installed' | 'invalid-config';
+/** An enable / disable refused before anything was written (invalid target or configuration). */
+export declare class PluginEnablementError extends Error {
+    readonly code: PluginEnablementErrorCode;
+    readonly errors: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+    readonly missingEnv: readonly string[];
+    constructor(code: PluginEnablementErrorCode, message: string, errors?: readonly {
+        path: string;
+        message: string;
+    }[], missingEnv?: readonly string[]);
+}
+/** What `setEnabled` would write to `disable_plugins`; changes nothing. */
+export interface PluginEnablementPlan {
+    readonly packageName: string;
+    readonly instanceKey: string;
+    /** The requested state. */
+    readonly enabled: boolean;
+    /** False when the instance already is in the requested state: nothing would be written. */
+    readonly changed: boolean;
+    /** `disable_plugins` after the change. */
+    readonly disabled: readonly string[];
+    readonly projectRevision: string;
+    readonly configurationRevision: string;
+    /** A running instance must restart to reflect the (current or requested) state. */
+    readonly restartRequired: boolean;
+}
 /** One installation authority for CLI and Console. No generation or package parser of its own. */
 export declare class PluginManagementWorkflow implements PluginManagementPort {
     #private;
@@ -64,6 +94,20 @@ export declare class PluginManagementWorkflow implements PluginManagementPort {
         restartRequired: boolean;
         state: PluginManagementState;
     }>>;
+    /**
+     * Validates enabling / disabling one declared instance (an instance key, or a package name
+     * declared exactly once) without writing. Enabling needs an installed plugin package whose
+     * dependencies and configuration pass; disabling also accepts a declared package that is no
+     * longer installed, so a broken instance can be taken out of the next generation.
+     */
+    planSetEnabled(request: string, enabled: boolean): Promise<PluginEnablementPlan>;
+    /** Writes `disable_plugins` in one atomic config write; already in the requested state → nothing written. */
+    setEnabled(request: string, enabled: boolean, expectedRevision?: string, expectedProjectRevision?: string): Promise<Readonly<{
+        plan: PluginEnablementPlan;
+        changed: boolean;
+        restartRequired: boolean;
+        state: PluginManagementState;
+    }>>;
     planUninstall(request: string): Promise<PluginUninstallPlan>;
     uninstall(request: string, expectedRevision?: string, expectedProjectRevision?: string, options?: {
         removeDependency?: boolean;