@zhin.js/gateway 1.1.1 → 1.2.0

package/lib/http/gateway-console.js

@@ -1,8 +1,10 @@
 /**
- * Console access control in the gateway (ADR 0054 §3 / §7, ADR 0049, ADR 0053 §4): the gateway
- * opens the project database itself, owns the `console_*` tables, authenticates sessions / API
- * tokens / the bootstrap token locally, and serves `/auth/*`, `iam.*`, `onboarding.update`, the
- * setup wizard, the terminal and the audit log — all without an instance.
+ * Console access control in the gateway (ADR 0054 §3 / §7, ADR 0049, ADR 0053 §4, ADR 0059): the
+ * gateway keeps the access-control tables in its own store `.zhin/gateway.db`, authenticates
+ * sessions / API tokens / the bootstrap token locally, and serves `/auth/*`, `iam.*`,
+ * `onboarding.update`, the setup wizard, the terminal and the audit log — all without an
+ * instance. It holds no connection to the project database: it connects only to import the
+ * tables an earlier version left there (and the setup wizard tests a connection).
  *
  * The instance contributes what only it knows over the bridge: the plugin permission catalog
  * (`catalog`) and its own audit entries (`audit`); the gateway tells it when a user's credentials
@@ -17,27 +19,39 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { ConsoleConfigurationStore } from '../config/configuration.js';
 import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
 import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from '../database/config.js';
-import { ProjectDatabase } from '../database/project-database.js';
+import { openGatewayStore } from '../database/gateway-store.js';
 import { projectEnvironment } from '../iam/install.js';
 import { createLocalConsoleAdmin } from '../iam/local-admin.js';
 import { registerConsoleAuthRoutes } from '../iam/routes.js';
 import { dispatchIamRpc, isIamRpc } from '../iam/rpc.js';
+import { ensureGatewayStoreMarker, importLegacyIamTables, inspectLegacyIamImport, isTransientLegacyImportError, LegacyImportError, readLegacyImportRecord } from '../iam/legacy-import.js';
 import { ConsoleIamService } from '../iam/service.js';
 import { ConsoleSetupService } from '../iam/setup-service.js';
-import { defineConsoleIamTables } from '../iam/tables.js';
 import { OnboardingError } from '../onboarding/errors.js';
 import { OnboardingService } from '../onboarding/service.js';
 import { findConfigFile } from '../project/config-file.js';
 import { installHostConsoleTerminal } from '../terminal/host.js';
 const logger = getLogger('gateway');
 const DEFAULT_RETRY_MS = 10_000;
-/** A database that never starts: the IAM service then fails closed on its setup marker. */
+/** Cap of the retry backoff while the project database stays unreachable. */
+const MAX_RETRY_MS = 5 * 60_000;
+/** A database that never starts: the IAM service then fails closed. */
 const UNAVAILABLE_DATABASE = Object.freeze({ started: false, models: Object.freeze({ get: () => undefined }) });
 export async function startGatewayConsole(options) {
     const { server, projectRoot } = options;
+    /** Why access control is closed (undefined once gateway.db is open and the import settled). */
+    let pending = 'Console 访问控制正在启动';
+    /** Category of `pending` shown to anonymous callers (never the detail). */
+    let pendingCode = 'starting';
+    /** Consecutive transient failures (backoff exponent). */
+    let failures = 0;
     const failClosed = () => ({
-        service: new ConsoleIamService({ database: UNAVAILABLE_DATABASE, projectRoot }),
-        supported: true,
+        service: new ConsoleIamService({
+            database: UNAVAILABLE_DATABASE,
+            projectRoot,
+            unavailable: () => pending ?? 'Console 访问控制正在重新连接',
+            unavailableCode: () => (pending === undefined ? 'starting' : pendingCode),
+        }),
         dispose: [],
     });
     const environment = options.environment ?? 'development';
@@ -52,12 +66,12 @@ export async function startGatewayConsole(options) {
     let closed = false;
     let retryTimer;
     let opening;
-    const iam = () => (connection.supported ? connection.service : undefined);
+    const iam = () => connection.service;
     const disposers = [];
     // Level grants need the catalog of the instance's loaded plugins (kept across restarts).
     disposers.push(registry.usePluginPermissions(() => options.instance?.pluginPermissions?.() ?? []));
     const access = Object.freeze({
-        initialized: () => connection.service?.initialized() ?? false,
+        initialized: () => connection.service.initialized(),
         authenticate: async (token, meta) => (await iam()?.authenticate(token, meta)) ?? null,
         audit: (entry) => { iam()?.audit(entry); },
     });
@@ -79,68 +93,134 @@ export async function startGatewayConsole(options) {
         }
         catch { /* bridge gone */ }
     };
+    const projectDatabase = async () => options.database
+        ?? resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
     async function connect() {
-        let config;
+        let store;
         try {
-            config = options.database ?? await resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
+            store = await openGatewayStore(projectRoot, options.store ?? {});
         }
         catch (error) {
-            logger.warn(formatCompact({ op: 'gateway_database_config_invalid', error: errorText(error) }));
-            connection = failClosed();
+            pending = `无法打开 .zhin/gateway.db：${errorText(error)}`;
+            pendingCode = 'store';
+            logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
+            scheduleRetry();
             return;
         }
-        let database;
+        connection = { database: store, service: connection.service, dispose: [] };
+        // ADR 0059 §3: the old console_* tables of the project database come over before anything
+        // reads gateway.db; until then access control stays closed (an empty store is not "no owner").
         try {
-            database = new ProjectDatabase(config);
+            const record = await importLegacyIamTables({
+                store,
+                projectRoot,
+                projectDatabase,
+                logger: { info: (message) => logger.info(message), warn: (message) => logger.warn(message) },
+            });
+            if (record.status === 'done' && record.changed) {
+                logger.warn(formatCompact({ op: 'gateway_legacy_import_changed', export: record.changedExport }));
+            }
         }
         catch (error) {
-            logger.warn(formatCompact({ op: 'gateway_database_driver_failed', dialect: config.dialect, error: errorText(error) }));
-            connection = failClosed();
-            return;
-        }
-        const supported = defineConsoleIamTables(database);
-        if (!supported) {
-            logger.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
-            connection = { database, supported: false, dispose: [] };
+            const code = error instanceof LegacyImportError ? error.code : 'error';
+            const transient = isTransientLegacyImportError(error);
+            pending = code === 'store_lost' || code === 'store_mismatch'
+                ? errorText(error)
+                : transient
+                    ? `正在等待项目数据库，以迁移旧版的 Console 账号表：${errorText(error)}`
+                    : `迁移旧版 Console 账号表失败，需要处理后重启网关（zhin stop && zhin start）：${errorText(error)}`;
+            pendingCode = code === 'store_lost' || code === 'store_mismatch' ? code : transient ? 'migration_pending' : 'migration_failed';
+            logger.warn(formatCompact({ op: 'gateway_legacy_import_failed', code, transient, error: errorText(error) }));
+            // Retrying cannot fix a conflict, a mismatch or a lost store: stay closed until the operator acts.
+            if (transient)
+                scheduleRetry();
             return;
         }
         const service = new ConsoleIamService({
-            database,
+            database: store,
             projectRoot,
             onError: (error) => logger.warn(`console iam: ${errorText(error)}`),
             pluginPermissions: () => registry.pluginPermissions(),
+            onOwnerCreated: () => { void ensureStoreMarker(); },
         });
-        const dispose = [service.onCredentialsRevoked(({ userId, reason }) => revoke(userId, reason))];
-        connection = { database, service, supported: true, dispose };
         try {
-            await database.start();
             await service.start();
-            logger.info(formatCompact({ op: 'gateway_database_open', dialect: config.dialect }));
         }
         catch (error) {
-            // Not ready: `/auth/*` answers 503 and the owner state comes from the setup marker.
-            logger.warn(formatCompact({ op: 'gateway_database_open_failed', dialect: config.dialect, error: errorText(error) }));
+            pending = `Console 访问控制无法启动：${errorText(error)}`;
+            pendingCode = 'store';
+            logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
+            service.stop();
             scheduleRetry();
+            return;
         }
+        const dispose = [service.onCredentialsRevoked(({ userId, reason }) => revoke(userId, reason))];
+        connection = { database: store, service, dispose };
+        pending = undefined;
+        failures = 0;
+        logger.info(formatCompact({ op: 'gateway_store_open', file: store.filename }));
     }
+    /** Writes the project database's store marker if missing; a foreign marker closes the Console. */
+    async function ensureStoreMarker() {
+        const store = connection.database;
+        if (!store || pending !== undefined)
+            return;
+        try {
+            await ensureGatewayStoreMarker({ store, projectRoot, projectDatabase, logger: { warn: (message) => logger.warn(message) } });
+        }
+        catch (error) {
+            if (error instanceof LegacyImportError && (error.code === 'store_mismatch' || error.code === 'store_lost')) {
+                // The project database belongs to another gateway.db (found after the start, e.g. once the
+                // project database became reachable): the same fail-closed state as at connect — Console
+                // closed, no retry, until the operator acts (`zhin console init --reset-store`).
+                logger.warn(formatCompact({ op: 'gateway_legacy_import_failed', code: error.code, transient: false, error: errorText(error) }));
+                opening = (opening ?? Promise.resolve()).then(async () => {
+                    const current = connection;
+                    if (closed || current.database !== store)
+                        return;
+                    pending = errorText(error);
+                    pendingCode = error.code;
+                    const users = await current.service.listUsers().catch(() => []);
+                    // gateway.db stays open (the local owner can inspect it, `--reset-store` can run).
+                    connection = { database: store, service: failClosed().service, dispose: [] };
+                    for (const dispose of current.dispose.splice(0))
+                        dispose();
+                    current.service.stop();
+                    // Sessions and API tokens no longer authenticate (the service is closed); what is already
+                    // open ends too: terminals and the instance's sockets of every user, as on a revocation.
+                    for (const user of users)
+                        revoke(user.id, error.code);
+                    for (const session of terminal.sessions())
+                        terminal.terminatePrincipal(session.principalId, 'revoked');
+                });
+                await opening;
+                return;
+            }
+            logger.warn(formatCompact({ op: 'gateway_store_marker_failed', error: errorText(error) }));
+        }
+    }
+    /** Transient failure: retry with a growing delay (retryMs, 2×, 4×, … at most MAX_RETRY_MS). */
     function scheduleRetry() {
         if (closed || retryTimer)
             return;
+        const delay = Math.min(retryMs * 2 ** failures, Math.max(retryMs, MAX_RETRY_MS));
+        failures += 1;
         retryTimer = setTimeout(() => {
             retryTimer = undefined;
             if (closed)
                 return;
             void reopen();
-        }, retryMs);
+        }, delay);
         retryTimer.unref?.();
     }
     async function disconnect() {
         const current = connection;
+        pending ??= 'Console 访问控制正在重新连接';
         connection = failClosed();
         for (const dispose of current.dispose.splice(0))
             dispose();
-        current.service?.stop();
-        await current.database?.stop().catch((error) => {
+        current.service.stop();
+        await current.database?.close().catch((error) => {
             logger.warn(formatCompact({ op: 'gateway_database_close_failed', error: errorText(error) }));
         });
     }
@@ -169,7 +249,7 @@ export async function startGatewayConsole(options) {
     });
     const onboarding = options.onboarding ?? new OnboardingService({
         projectRoot,
-        hasOwner: () => connection.service?.initialized() ?? false,
+        hasOwner: () => connection.service.initialized(),
     });
     const restartInstance = () => {
         void options.restartInstance?.().catch((error) => {
@@ -179,12 +259,18 @@ export async function startGatewayConsole(options) {
     const localAdmin = createLocalConsoleAdmin({
         setup,
         iam,
-        // ADR 0054 §7, as for the web wizard: the gateway uses the new database before it answers.
+        // The accounts stay in gateway.db (ADR 0059): only the instance uses the new database.
         switchDatabase: async () => {
-            await reopen();
             restartInstance();
             return { restarting: options.restartInstance !== undefined };
         },
+        migration: async () => {
+            const store = connection.database;
+            if (!store)
+                return { pending };
+            const inspection = await inspectLegacyIamImport({ store, projectRoot, projectDatabase });
+            return { ...inspection, record: inspection.record ?? await readLegacyImportRecord(store), ...(pending !== undefined ? { pending, pendingCode } : {}) };
+        },
     });
     disposers.push(...registerConsoleAuthRoutes({
         http: server,
@@ -192,18 +278,14 @@ export async function startGatewayConsole(options) {
         iam,
         setup,
         onboarding: () => onboarding.status(),
-        // ADR 0054 §7: close the gateway's connection, open the new database, restart the instance.
-        requestRestart: () => {
-            void reopen()
-                .then(() => options.restartInstance?.())
-                .catch((error) => logger.warn(formatCompact({ op: 'gateway_database_switch_failed', error: errorText(error) })));
-        },
+        // The instance restarts on the new project database; the accounts stay in gateway.db (ADR 0059).
+        requestRestart: () => { restartInstance(); },
     }));
     // `/auth/*` belongs to the gateway alone: nothing under it is forwarded to the instance.
     disposers.push(server.route('ALL', `${server.apiBase}/auth/*`, () => jsonResponse(404, { success: false, code: 'not_found', error: 'Not found' }), { summary: 'Unknown /auth route', tags: ['auth'] }));
     disposers.push(server.useConsoleRpc(createGatewayAccountRpc({ iam, onboarding })));
     const ready = reopen().catch((error) => {
-        logger.warn(formatCompact({ op: 'gateway_database_open_failed', error: errorText(error) }));
+        logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
     });
     let closeResult;
     return Object.freeze({
@@ -214,6 +296,7 @@ export async function startGatewayConsole(options) {
         onboarding,
         terminal,
         reopenDatabase: reopen,
+        ensureStoreMarker,
         localAdmin,
         close() {
             closeResult ??= (async () => {

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

@@ -10,10 +10,15 @@
  *   Console reconnects to the merged stream. `GET {base}/events/history` then answers an empty
  *   page that keeps the caller's cursor.
  *
+ * A succeeded plugin enable / disable that changed `disable_plugins` also sends
+ * `plugin:lifecycle-updated` on `{base}/events` (the Console reloads its entries on it).
+ *
  * `GET {base}/gateway/packages/progress` serves the progress frames alone.
  */
 import type { GatewayPackageEvent } from '@zhin.js/console-protocol';
 import type { GatewayHttpServer } from './gateway-http-server.js';
+/** Console event the client reloads its entries on (`CONSOLE_ENTRY_LIFECYCLE_EVENTS`). */
+export declare const PLUGIN_LIFECYCLE_UPDATED = "plugin:lifecycle-updated";
 export interface GatewayEventSource {
     /** Package transaction events (`GatewayPackageService.subscribe`). */
     subscribe(listener: (event: GatewayPackageEvent) => void): () => void;

package/lib/http/gateway-events.js

@@ -1,6 +1,8 @@
 import { GATEWAY_PACKAGES_PROGRESS, GATEWAY_PACKAGES_PROGRESS_PATH } from '@zhin.js/console-protocol';
 import { jsonResponse } from '@zhin.js/host-http';
 const KEEPALIVE_MS = 15_000;
+/** Console event the client reloads its entries on (`CONSOLE_ENTRY_LIFECYCLE_EVENTS`). */
+export const PLUGIN_LIFECYCLE_UPDATED = 'plugin:lifecycle-updated';
 /** Gateway frames held while an instance frame is half written. */
 const MAX_PENDING_FRAMES = 1_024;
 /** Chunks queued for a client that does not read; beyond it the stream ends (the client resumes). */
@@ -63,7 +65,18 @@ export function registerGatewayEventRoutes(options) {
         cleanups.push(() => clearInterval(timer));
         return { stream, write, finish, cleanups, get finished() { return finished; } };
     };
-    const subscribeProgress = (deliver) => options.packages?.subscribe((event) => deliver(gatewayEventFrame(GATEWAY_PACKAGES_PROGRESS, event)));
+    /**
+     * Progress frames; on the Console event stream (`lifecycle`) a succeeded enable / disable that
+     * changed `disable_plugins` is followed by `plugin:lifecycle-updated` `{ instanceKey, enabled }`,
+     * the event the instance used to publish for the Console switch (the Console reloads its entries).
+     */
+    const subscribeProgress = (deliver, lifecycle = false) => options.packages?.subscribe((event) => {
+        deliver(gatewayEventFrame(GATEWAY_PACKAGES_PROGRESS, event));
+        const plugin = event.type === 'result' && event.result.ok ? event.result.plugin : undefined;
+        if (lifecycle && plugin?.changed) {
+            deliver(gatewayEventFrame(PLUGIN_LIFECYCLE_UPDATED, { instanceKey: plugin.instanceKey, enabled: plugin.enabled }));
+        }
+    });
     const events = async (request, context) => {
         if (!server.instanceReady)
             return offlineStream(request);
@@ -95,7 +108,7 @@ export function registerGatewayEventRoutes(options) {
                 return;
             }
             client.write(frame);
-        });
+        }, true);
         if (stop)
             client.cleanups.push(stop);
         void (async () => {
@@ -121,7 +134,7 @@ export function registerGatewayEventRoutes(options) {
     const offlineStream = (request) => {
         const client = open(request);
         client.write(': gateway\n\n');
-        const stop = subscribeProgress((frame) => client.write(frame));
+        const stop = subscribeProgress((frame) => client.write(frame), true);
         if (stop)
             client.cleanups.push(stop);
         // Reconnect to the merged stream once the instance is back.

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

@@ -279,13 +279,17 @@ export class GatewayHttpServer {
             catch {
                 return jsonResponse(400, { success: false, code: 'invalid_body', error: 'Invalid JSON body' });
             }
-            try {
-                return await owner.handle(message, context, this.tokenRegistry);
-            }
-            catch (error) {
-                if (isDatabaseBusyError(error))
-                    return databaseBusyResponse({ requestId: message.requestId });
-                throw error;
+            const claimed = typeof message === 'object' && message !== null && !Array.isArray(message)
+                && (!('claims' in owner) || typeof owner.claims !== 'function' || owner.claims(message));
+            if (claimed) {
+                try {
+                    return await owner.handle(message, context, this.tokenRegistry);
+                }
+                catch (error) {
+                    if (isDatabaseBusyError(error))
+                        return databaseBusyResponse({ requestId: message.requestId });
+                    throw error;
+                }
             }
         }
         const headers = new Headers(request.headers);

package/lib/http/plugin-switch-rpc.d.ts

@@ -0,0 +1,19 @@
+import type { GatewayPackageService } from '../packages/service.js';
+import type { GatewayRpcHandler } from './console-rpc.js';
+/** What the switch needs from the package service. */
+export type GatewayPluginSwitchPackages = Pick<GatewayPackageService, 'setEnabled'>;
+/** The root configuration as written after the transaction. */
+export interface GatewayPluginSwitchConfigRead {
+    readonly revision: string;
+    readonly document: Readonly<Record<string, unknown>>;
+}
+export interface GatewayPluginSwitchRpcOptions {
+    readonly projectRoot: string;
+    /** Undefined when the gateway manages no packages: the switch then answers 503 (never forwarded). */
+    readonly packages: GatewayPluginSwitchPackages | undefined;
+    /** Reads the root configuration (revision and document). Defaults to the project's config file. */
+    readonly readConfig?: () => Promise<GatewayPluginSwitchConfigRead>;
+}
+/** Whether the gateway answers this Console RPC message itself (the global plugin switch). */
+export declare function isGatewayPluginSwitch(message: Readonly<Record<string, unknown>>): boolean;
+export declare function createGatewayPluginSwitchRpc(options: GatewayPluginSwitchRpcOptions): GatewayRpcHandler;

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

@@ -0,0 +1,218 @@
+/**
+ * The Console's global plugin switch, answered by the gateway (ADR 0054 §4, ADR 0050 §4):
+ * `plugin:set-enabled` and `feature.set-enabled` with `level: 'global'` both write
+ * `disable_plugins`, which is plugin lifecycle rather than a feature switch. The gateway
+ * intercepts them on `POST {base}/console/request` before anything is forwarded, authorizes them
+ * with `plugin.manage` (the shared permission map refines `feature.set-enabled` by level), and
+ * runs the enable / disable transaction of {@link GatewayPackageService.setEnabled}: stop the
+ * instance → write `disable_plugins` → start it, restoring the file and the old instance on
+ * failure. `feature.set-enabled` below the global level is forwarded to the instance untouched.
+ *
+ * Replies keep the shapes the instance used to send, so a published Console keeps working:
+ * - `plugin:set-enabled`: `{ success, instanceKey, enabled, disabled, restartRequired, message }`;
+ * - `feature.set-enabled`: `ConsoleFeatureWriteResult` (`saved` / `unchanged`) with the
+ *   configuration revision after the write and the override warnings of the new state.
+ * Both add `transaction` (the gateway transaction result). A failed or rolled-back transaction
+ * answers the RPC's error envelope (`success: false`, `code`, `error`) with `transaction`.
+ */
+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 { 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';
+import { GatewayError } from '../packages/errors.js';
+import { findConfigFile } from '../project/config-file.js';
+const logger = getLogger('gateway');
+/** Top-level plugin instance alias (the global switch only applies to top-level instances). */
+const INSTANCE_KEY = /^[a-z0-9][a-z0-9-]*$/u;
+/** Whether the gateway answers this Console RPC message itself (the global plugin switch). */
+export function isGatewayPluginSwitch(message) {
+    return message.type === PLUGIN_RPC.SET_ENABLED || isGlobalFeatureSwitch(message);
+}
+export function createGatewayPluginSwitchRpc(options) {
+    const readConfig = options.readConfig ?? (async () => {
+        const file = join(options.projectRoot, findConfigFile(options.projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME);
+        const { revision, document } = await createConfigDocument(file).read();
+        return { revision, document: document };
+    });
+    return Object.freeze({
+        owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
+        claims: isGatewayPluginSwitch,
+        async handle(message, context, registry) {
+            const noStore = { 'cache-control': 'no-store' };
+            const type = String(message.type ?? '');
+            const requestId = message.requestId;
+            const principal = context.principal;
+            if (!principal) {
+                return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
+            }
+            // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
+            const decision = authorizeConsoleRpc(principal, message);
+            const audit = (outcome) => {
+                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),
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            };
+            if (!decision.allowed) {
+                audit('denied');
+                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');
+            return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
+        },
+    });
+}
+/** `plugin:set-enabled` `{ instanceKey, enabled }` (top-level fields, as the Console sends them). */
+async function setPluginEnabled(message, principal, options, readConfig) {
+    const type = PLUGIN_RPC.SET_ENABLED;
+    const instanceKey = typeof message.instanceKey === 'string' ? message.instanceKey.trim() : '';
+    const enabled = message.enabled;
+    if (!instanceKey || typeof enabled !== 'boolean')
+        return error(400, 'invalid_input', 'instanceKey and boolean enabled are required', type);
+    const outcome = await runSwitch(instanceKey, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch(() => undefined);
+    const key = result.plugin?.instanceKey ?? instanceKey;
+    const changed = result.plugin?.changed === true;
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: {
+                success: true,
+                instanceKey: key,
+                enabled,
+                disabled: disabledPlugins(config?.document),
+                // The gateway restarted the instance for a change (it already is back): the Console re-syncs.
+                restartRequired: changed,
+                message: switchMessage(key, enabled, changed),
+                transaction: result,
+            },
+        },
+    };
+}
+/** `feature.set-enabled` with `level: 'global'`, payload in `data` (or on the message). */
+async function setFeatureGlobal(message, principal, options, readConfig) {
+    const type = FEATURE_RPC.SET_ENABLED;
+    const data = message.data;
+    const input = (data && typeof data === 'object' && !Array.isArray(data) ? data : message);
+    const plugin = input.plugin;
+    if (typeof plugin !== 'string' || !plugin)
+        return error(400, undefined, '缺少 plugin', type);
+    if (input.key !== undefined && input.key !== '')
+        return error(400, undefined, 'global 层不需要 key', type);
+    if (!INSTANCE_KEY.test(plugin)) {
+        return error(400, undefined, plugin.includes('/') ? '全局开关只适用于顶层插件实例' : 'plugin 必须是插件实例别名', type);
+    }
+    if (typeof input.enabled !== 'boolean')
+        return error(400, undefined, 'enabled 必须是布尔值', type);
+    const enabled = input.enabled;
+    const outcome = await runSwitch(plugin, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch((failure) => {
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_config_read_failed', error: failure instanceof Error ? failure.message : String(failure) }));
+        return undefined;
+    });
+    const revision = config?.revision ?? '';
+    const changed = result.plugin?.changed === true;
+    if (!changed) {
+        return { status: 200, body: { success: true, type, data: Object.freeze({ status: 'unchanged', revision, warnings: Object.freeze([]), transaction: result }) } };
+    }
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: Object.freeze({
+                status: 'saved',
+                revision,
+                // The instance was restarted by the gateway transaction (it already is back).
+                restartRequired: true,
+                warnings: config ? overrideWarnings(config.document, plugin) : Object.freeze([]),
+                message: switchMessage(plugin, enabled, true),
+                transaction: result,
+            }),
+        },
+    };
+}
+/** Runs the transaction; a refusal or a failed / rolled-back transaction becomes an error reply. */
+async function runSwitch(plugin, enabled, principal, options, type) {
+    if (!options.packages)
+        return { reply: error(503, 'unavailable', '插件启停不可用：网关未管理依赖', type) };
+    let result;
+    try {
+        result = await options.packages.setEnabled({ plugin }, enabled, { principal });
+    }
+    catch (failure) {
+        if (failure instanceof GatewayError) {
+            return {
+                reply: error(failure.status, failure.code, failure.message, type, {
+                    ...(failure.details?.errors ? { errors: failure.details.errors } : {}),
+                    ...(failure.details?.missingEnv ? { missingEnv: failure.details.missingEnv } : {}),
+                }),
+            };
+        }
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_failed', plugin, error: failure instanceof Error ? failure.message : String(failure) }));
+        return { reply: error(500, 'internal', '插件启停失败', type) };
+    }
+    if (result.ok)
+        return { result };
+    const action = enabled ? '启用' : '停用';
+    const text = result.status === 'rollbackFailed'
+        ? `${action} ${plugin} 失败，且回滚未完成：${result.rollbackError ?? '未知错误'}（原因：${result.error ?? '未知错误'}）`
+        : `${action} ${plugin} 失败，已回滚：${result.error ?? '未知错误'}`;
+    return {
+        reply: error(500, result.status === 'rollbackFailed' ? 'rollback_failed' : 'transaction_failed', text, type, {
+            transaction: result,
+            ...(result.errors?.length ? { errors: result.errors } : {}),
+            ...(result.missingEnv?.length ? { missingEnv: result.missingEnv } : {}),
+        }),
+    };
+}
+function error(status, code, message, type, extra = {}) {
+    return { status, body: { success: false, ...(code ? { code } : {}), error: message, type, ...extra } };
+}
+function switchMessage(plugin, enabled, changed) {
+    const action = enabled ? '启用' : '停用';
+    return changed ? `${plugin} 已${action}，实例已由管理网关重启` : `${plugin} 已处于${action}状态`;
+}
+function disabledPlugins(document) {
+    const list = document?.disable_plugins;
+    return Object.freeze(Array.isArray(list) ? list.filter((item) => typeof item === 'string') : []);
+}
+/**
+ * The global plugin switch's warnings about a legacy `overrides` block still in the file (as the
+ * instance computed them). Since ADR 0057 §2 adapter / account overrides live in the instance's
+ * database, which the gateway does not read, so this only reports a block waiting for its import.
+ */
+function overrideWarnings(document, plugin) {
+    const block = document[plugin];
+    const overrides = block && typeof block === 'object' && !Array.isArray(block) ? block[FEATURE_OVERRIDES_KEY] : undefined;
+    if (overrides === undefined)
+        return Object.freeze([]);
+    try {
+        const enabled = !disabledPlugins(document).includes(plugin);
+        return Object.freeze(collectFeatureOverrideWarnings(document, plugin, overrides, enabled)
+            .map(({ code, path, message }) => Object.freeze({ code, path, message })));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}