@zhin.js/gateway 1.1.1 → 1.1.2

package/lib/config/configuration-chat-policy.js

@@ -1,4 +1,5 @@
 import { expandEnvironmentValue } from '@zhin.js/runtime';
+import { isSecretConfigSchema } from '@zhin.js/runtime';
 import { isUnknownConfigurationSchemaBoundary, sensitiveConfigKey as sensitiveKey } from './configuration-redaction.js';
 const accessMessages = Object.freeze({
     sensitive: '敏感配置不能通过聊天读取或修改，请使用 CLI 或 Console。',
@@ -88,8 +89,7 @@ function record(value) {
 }
 function own(value, key) { return Object.hasOwn(value, key); }
 function sensitive(schema) {
-    return schema.writeOnly === true || schema.secret === true || schema.format === 'password' || schema.component === 'password'
-        || record(schema['x-zhin-config']) && (schema['x-zhin-config'].secret === true || schema['x-zhin-config'].component === 'password');
+    return isSecretConfigSchema(schema);
 }
 function unknown() { throw new ConfigChatAccessError('unknown'); }
 function assertSafe(nodes) {

package/lib/config/configuration-redaction.d.ts

@@ -1,14 +1,8 @@
-/**
- * Masks stored configuration values before they leave the store in a response that the
- * caller did not ask to read (e.g. a trusted project patch conflict). Conservative: a
- * schema secret/writeOnly/password/hidden annotation, a secret-like key, or an unexpanded
- * environment reference (`${…}`, `env://…`) is replaced as a whole and never echoed.
- */
 type Schema = Readonly<Record<string, unknown>>;
 /** Shared proof limit: these branches/resources need a resolver we do not provide. */
 export declare function isUnknownConfigurationSchemaBoundary(schema: Schema, root: Schema): boolean;
-/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit. */
-export declare function sensitiveConfigKey(key: string): boolean;
+/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit (the ADR 0057 predicate). */
+export declare const sensitiveConfigKey: (key: string) => boolean;
 export declare const REDACTED_CONFIG_VALUE = "[redacted]";
 /**
  * Masks `value`, stored at `path` (first segment is the section) under `sectionSchema`.

package/lib/config/configuration-redaction.js

@@ -1,3 +1,10 @@
+/**
+ * Masks stored configuration values before they leave the store in a response that the
+ * caller did not ask to read (e.g. a trusted project patch conflict). Conservative: a
+ * schema secret/writeOnly/password/hidden annotation, a secret-like key, or an unexpanded
+ * environment reference (`${…}`, `env://…`) is replaced as a whole and never echoed.
+ */
+import { UNRESOLVED_CONFIG_SCHEMA, configSchemaChildren, expandConfigSchema, isConfigEnvironmentReference, isSecretConfigKey, isSecretConfigSchema, } from '@zhin.js/runtime';
 const unsupportedApplicators = Object.freeze([
     'if', 'then', 'else', 'not', 'contains', 'dependencies', 'dependentSchemas',
     '$dynamicRef', '$recursiveRef', '$dynamicAnchor', 'unevaluatedProperties', 'unevaluatedItems',
@@ -8,88 +15,28 @@ export function isUnknownConfigurationSchemaBoundary(schema, root) {
         || unsupportedApplicators.some(keyword => Object.hasOwn(schema, keyword))
         || schema.$ref !== undefined && (typeof schema.$ref !== 'string' || !schema.$ref.startsWith('#/') || /~(?![01])/u.test(schema.$ref));
 }
-/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit. */
-export function sensitiveConfigKey(key) {
-    const normalized = key.replace(/[^a-z0-9]/giu, '').toLowerCase();
-    return /(?:password|passwd|secret|apikey|accesskey|privatekey|encrypt(?:ion)?key|encodingaeskey|credential|authorization|cookie)/u.test(normalized)
-        || normalized === 'pwd' || /(?:^|api|access|refresh|auth|bearer|bot|oauth|session|private|client|app|verify|verification)tokens?(?:v[0-9]+)?$/u.test(normalized);
-}
+/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit (the ADR 0057 predicate). */
+export const sensitiveConfigKey = isSecretConfigKey;
 export const REDACTED_CONFIG_VALUE = '[redacted]';
 const MAX_DEPTH = 32;
 // Retain uncertainty without changing the non-strict masker's best-effort behavior.
-const unresolvedSchema = Object.freeze({});
+const unresolvedSchema = UNRESOLVED_CONFIG_SCHEMA;
+const expand = expandConfigSchema;
+const children = configSchemaChildren;
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 function sensitiveSchema(schema) {
     const metadata = schema['x-zhin-config'];
     // `hidden` mirrors the configuration explanation contract: hidden fields are never echoed.
-    return schema.writeOnly === true || schema.secret === true || schema.hidden === true
-        || schema.format === 'password' || schema.component === 'password'
-        || record(metadata) && (metadata.secret === true || metadata.hidden === true || metadata.component === 'password');
-}
-/** Expands local `$ref` and every combinator branch; any branch's annotation applies. */
-function expand(node, root, seen = new Set()) {
-    if (!record(node) || seen.has(node) || seen.size > MAX_DEPTH)
-        return [unresolvedSchema];
-    const nextSeen = new Set([...seen, node]);
-    const nodes = [node];
-    if (typeof node.$ref === 'string' && node.$ref.startsWith('#/')) {
-        let referenced = root;
-        for (const raw of node.$ref.slice(2).split('/')) {
-            const key = raw.replaceAll('~1', '/').replaceAll('~0', '~');
-            referenced = record(referenced) && Object.hasOwn(referenced, key) ? referenced[key] : undefined;
-        }
-        nodes.push(...expand(referenced, root, nextSeen));
-    }
-    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
-        const branches = node[keyword];
-        if (Array.isArray(branches))
-            for (const branch of branches)
-                nodes.push(...expand(branch, root, nextSeen));
-    }
-    return nodes;
-}
-function children(nodes, key, root) {
-    const next = [];
-    for (const node of nodes) {
-        let matched = false;
-        if (record(node.properties) && Object.hasOwn(node.properties, key)) {
-            next.push(...expand(node.properties[key], root));
-            matched = true;
-        }
-        if (record(node.patternProperties)) {
-            for (const [pattern, child] of Object.entries(node.patternProperties)) {
-                let test = false;
-                try {
-                    test = new RegExp(pattern, 'u').test(key);
-                }
-                catch {
-                    test = false;
-                }
-                if (test) {
-                    next.push(...expand(child, root));
-                    matched = true;
-                }
-            }
-        }
-        if (!matched && record(node.additionalProperties))
-            next.push(...expand(node.additionalProperties, root));
-        if (/^(?:0|[1-9][0-9]*)$/u.test(key)) {
-            const index = Number(key);
-            if (Array.isArray(node.prefixItems) && index < node.prefixItems.length)
-                next.push(...expand(node.prefixItems[index], root));
-            else if (record(node.items))
-                next.push(...expand(node.items, root));
-        }
-    }
-    return next;
+    return isSecretConfigSchema(schema) || schema.hidden === true
+        || record(metadata) && metadata.hidden === true;
 }
 function maskTree(value, nodes, root, depth, hidden) {
     if (nodes.some(hidden))
         return REDACTED_CONFIG_VALUE;
     if (typeof value === 'string')
-        return /\$\{|^env:\/\//u.test(value) ? REDACTED_CONFIG_VALUE : value;
+        return isConfigEnvironmentReference(value) ? REDACTED_CONFIG_VALUE : value;
     if (value === null || typeof value !== 'object')
         return value;
     if (depth >= MAX_DEPTH)

package/lib/config/console-schema.js

@@ -1,3 +1,4 @@
+import { isSecretConfigSchema } from '@zhin.js/runtime';
 const record = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
 const own = (value, key) => Object.hasOwn(value, key);
 const jsonTypes = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
@@ -7,7 +8,7 @@ export function readStringLiteralOptions(input) {
     if (!Array.isArray(input.anyOf) || input.anyOf.length === 0 || input.anyOf.length > 64)
         return null;
     const annotations = ['title', 'description', 'x-descriptionZh', 'x-i18n', '$comment'];
-    const parentKeys = ['anyOf', 'type', 'default', 'writeOnly', 'readOnly', 'deprecated', 'x-zhin-config', ...annotations];
+    const parentKeys = ['anyOf', 'type', 'default', 'writeOnly', 'readOnly', 'deprecated', 'x-zhin-config', 'x-zhin-secret', ...annotations];
     if (Object.keys(input).some(key => !parentKeys.includes(key))
         || (input.type !== undefined && input.type !== 'string'))
         return null;
@@ -148,7 +149,7 @@ function convert(input, key, context) {
     const inferred = type ?? (Array.isArray(schema.enum) && schema.enum.length ? (schema.enum[0] === null ? 'null' : typeof schema.enum[0]) : 'any');
     return finish({ type: inferred === 'integer' ? 'number' : jsonTypes.has(inferred) ? inferred : 'any', ...(inferred === 'integer' ? { integer: true } : {}) });
 }
-const annotationKeys = new Set(['title', 'description', 'x-descriptionZh', 'x-i18n', 'default', 'readOnly', 'writeOnly', 'examples', 'deprecated', 'x-zhin-config', 'key', 'hidden', 'component', 'options', 'effect', 'secret']);
+const annotationKeys = new Set(['title', 'description', 'x-descriptionZh', 'x-i18n', 'default', 'readOnly', 'writeOnly', 'examples', 'deprecated', 'x-zhin-config', 'x-zhin-secret', 'key', 'hidden', 'component', 'options', 'effect', 'secret']);
 function annotate(result, schema, key) {
     const output = { ...result };
     if (record(schema['x-i18n']))
@@ -180,7 +181,7 @@ function annotate(result, schema, key) {
             output[name] = metadata[name];
     if (output.secret !== true && typeof schema.secret === 'boolean')
         output.secret = schema.secret;
-    if (output.secret === true || schema.writeOnly === true || schema.secret === true || metadata.secret === true) {
+    if (output.secret === true || isSecretConfigSchema(schema)) {
         output.secret = true;
         if (output.component !== 'textarea')
             output.component = 'password';

package/lib/config/environment-files.d.ts

@@ -1,2 +1,3 @@
 export declare function readEnvFile(projectRoot: string, filename: string): Promise<string>;
+/** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
 export declare function writeEnvFile(projectRoot: string, filename: string, content: string): Promise<void>;

package/lib/config/environment-files.js

@@ -1,21 +1,14 @@
-import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readDotenvFile, writeDotenvFile } from '@zhin.js/runtime';
 const ENV_FILES = new Set(['.env', '.env.development', '.env.production']);
 export async function readEnvFile(projectRoot, filename) {
     if (!ENV_FILES.has(filename))
         throw new Error(`Invalid env file: ${filename}`);
-    const file = join(projectRoot, filename);
-    try {
-        return await readFile(file, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return '';
-        throw error;
-    }
+    return readDotenvFile(join(projectRoot, filename));
 }
+/** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
 export async function writeEnvFile(projectRoot, filename, content) {
     if (!ENV_FILES.has(filename))
         throw new Error(`Invalid env file: ${filename}`);
-    await writeFile(join(projectRoot, filename), content, 'utf8');
+    await writeDotenvFile(join(projectRoot, filename), content);
 }

package/lib/config/literal-secrets.d.ts

@@ -0,0 +1,34 @@
+import { type LiteralConfigSecret } from '@zhin.js/runtime';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/**
+ * Secret paths holding literals in `document`, using the Host schema, the root `schema.json`
+ * and each declared instance's `schema.json` (annotations), plus the field-name fallback.
+ * Plugins whose schema is only inline (`definePlugin({ config })`) use the name fallback here.
+ */
+export declare function findProjectLiteralSecrets(projectRoot: string, document: RuntimeConfigDocument): Promise<readonly LiteralConfigSecret[]>;
+/** `ZHIN_<PATH_UPPER_SNAKE>`: `http.token` → `ZHIN_HTTP_TOKEN`, `qq.endpoints[0].appSecret` → `ZHIN_QQ_ENDPOINTS_0_APP_SECRET`. */
+export declare function literalSecretEnvironmentName(path: readonly string[]): string;
+export interface LiteralSecretMove {
+    readonly path: readonly string[];
+    readonly variable: string;
+    /** The variable already held this exact value; `.env` was not changed for it. */
+    readonly reused: boolean;
+}
+export interface LiteralSecretSkip {
+    readonly path: readonly string[];
+    readonly reason: string;
+}
+export interface LiteralSecretFixResult {
+    readonly moved: readonly LiteralSecretMove[];
+    readonly skipped: readonly LiteralSecretSkip[];
+}
+/**
+ * Moves every literal secret of `configFile` into `<projectRoot>/.env`.
+ *
+ * Order: `.env` first (locked, atomic; a variable that already holds the same value is reused,
+ * a name taken by another value gets `_2`, `_3`, …), then the config file through
+ * ConfigFileDocument (revision check, lock, atomic). If the config changed in between, the
+ * write is refused with a conflict and nothing in the config changes; the next run reuses the
+ * variables already written, so the operation is idempotent.
+ */
+export declare function moveLiteralSecretsToEnv(projectRoot: string, configFile: string): Promise<LiteralSecretFixResult>;

package/lib/config/literal-secrets.js

@@ -0,0 +1,136 @@
+/**
+ * ADR 0057 §4: literal secrets in the YAML/JSON config move to `.env`.
+ * `zhin doctor` reports them; `zhin doctor --fix` writes each literal into `.env` as
+ * `ZHIN_<PATH>` and replaces the config value with `${ZHIN_<PATH>}`.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseDotenv } from 'dotenv';
+import { HOST_CONFIG_SCHEMA, createConfigDocument, findLiteralConfigSecrets, readApplicationPluginDeclaration, updateDotenvFile, } from '@zhin.js/runtime';
+import { PluginSchemaCatalog } from './plugin-schema-catalog.js';
+/**
+ * Secret paths holding literals in `document`, using the Host schema, the root `schema.json`
+ * and each declared instance's `schema.json` (annotations), plus the field-name fallback.
+ * Plugins whose schema is only inline (`definePlugin({ config })`) use the name fallback here.
+ */
+export async function findProjectLiteralSecrets(projectRoot, document) {
+    let instanceKeys = [];
+    try {
+        instanceKeys = readApplicationPluginDeclaration(document).instances.map(item => item.instanceKey);
+    }
+    catch { /* Invalid declarations are reported elsewhere; still scan with the name fallback. */ }
+    const schemas = await new PluginSchemaCatalog(projectRoot).readJsonMany(['plugin', ...instanceKeys], document);
+    const plugins = [];
+    for (const [key, schema] of schemas) {
+        if (schema && !(schema instanceof Error))
+            plugins.push([[key], schema]);
+    }
+    return findLiteralConfigSecrets(document, { host: HOST_CONFIG_SCHEMA, plugins });
+}
+/** `ZHIN_<PATH_UPPER_SNAKE>`: `http.token` → `ZHIN_HTTP_TOKEN`, `qq.endpoints[0].appSecret` → `ZHIN_QQ_ENDPOINTS_0_APP_SECRET`. */
+export function literalSecretEnvironmentName(path) {
+    const body = path
+        .map(segment => segment.replace(/([a-z0-9])([A-Z])/gu, '$1_$2'))
+        .join('_')
+        .replace(/[^A-Za-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '')
+        .toUpperCase();
+    return `ZHIN_${body || 'SECRET'}`;
+}
+/**
+ * Moves every literal secret of `configFile` into `<projectRoot>/.env`.
+ *
+ * Order: `.env` first (locked, atomic; a variable that already holds the same value is reused,
+ * a name taken by another value gets `_2`, `_3`, …), then the config file through
+ * ConfigFileDocument (revision check, lock, atomic). If the config changed in between, the
+ * write is refused with a conflict and nothing in the config changes; the next run reuses the
+ * variables already written, so the operation is idempotent.
+ */
+export async function moveLiteralSecretsToEnv(projectRoot, configFile) {
+    const config = createConfigDocument(configFile);
+    const snapshot = await config.read();
+    const secrets = await findProjectLiteralSecrets(projectRoot, snapshot.document);
+    if (secrets.length === 0)
+        return Object.freeze({ moved: Object.freeze([]), skipped: Object.freeze([]) });
+    // `.env.<environment>` overrides `.env`: a name used there with another value is taken.
+    const overlays = await Promise.all(['.env.development', '.env.production'].map(name => readOptional(join(projectRoot, name))));
+    const shadowing = overlays.map(source => parseDotenv(source));
+    const moved = [];
+    const skipped = [];
+    await updateDotenvFile(join(projectRoot, '.env'), current => {
+        moved.length = 0;
+        skipped.length = 0;
+        const existing = { ...parseDotenv(current) };
+        const lines = [];
+        for (const secret of secrets) {
+            const value = readPath(snapshot.document, secret.path);
+            if (typeof value !== 'string')
+                continue;
+            const line = (name) => dotenvLine(name, value);
+            if (!line('ZHIN_PROBE')) {
+                skipped.push(Object.freeze({ path: secret.path, reason: '值含换行或无法安全写入 .env，请手动迁移' }));
+                continue;
+            }
+            const base = literalSecretEnvironmentName(secret.path);
+            let variable = base;
+            for (let suffix = 2;; suffix += 1) {
+                const taken = existing[variable] !== undefined && existing[variable] !== value
+                    || shadowing.some(layer => layer[variable] !== undefined && layer[variable] !== value);
+                if (!taken)
+                    break;
+                variable = `${base}_${suffix}`;
+            }
+            const reused = existing[variable] === value;
+            if (!reused) {
+                lines.push(line(variable));
+                existing[variable] = value;
+            }
+            moved.push(Object.freeze({ path: secret.path, variable, reused }));
+        }
+        if (lines.length === 0)
+            return undefined;
+        const separator = current === '' || current.endsWith('\n') ? '' : '\n';
+        return `${current}${separator}${current.trim() ? '\n' : ''}# zhin doctor --fix：从 ${configFileLabel(configFile)} 移入的密钥（ADR 0057）\n${lines.join('\n')}\n`;
+    });
+    if (moved.length) {
+        const patches = moved.map(item => ({ op: 'set', path: item.path, value: `\${${item.variable}}` }));
+        const prepared = await config.prepare(snapshot, patches);
+        await prepared.commit();
+    }
+    return Object.freeze({ moved: Object.freeze(moved), skipped: Object.freeze(skipped) });
+}
+/** A `NAME=value` dotenv line that parses back to exactly `value`, or undefined when none does. */
+function dotenvLine(name, value) {
+    if (/[\r\n]/u.test(value))
+        return undefined;
+    for (const quote of ["'", '`', '"']) {
+        if (value.includes(quote))
+            continue;
+        const line = `${name}=${quote}${value}${quote}`;
+        if (parseDotenv(line)[name] === value)
+            return line;
+    }
+    return undefined;
+}
+function readPath(document, path) {
+    let current = document;
+    for (const segment of path) {
+        if (!current || typeof current !== 'object' || !Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function configFileLabel(file) {
+    return file.split(/[\\/]/u).pop() ?? file;
+}
+async function readOptional(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}

package/lib/config.d.ts

@@ -8,5 +8,6 @@ export * from './config/configuration-projection.js';
 export * from './config/configuration-redaction.js';
 export * from './config/console-schema.js';
 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';

package/lib/config.js

@@ -8,5 +8,6 @@ export * from './config/configuration-projection.js';
 export * from './config/configuration-redaction.js';
 export * from './config/console-schema.js';
 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';

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

@@ -12,8 +12,16 @@ export declare const GATEWAY_RPC_PREFIX = "gateway.";
 export interface GatewayConsoleRpc {
     handle(message: Readonly<Record<string, unknown>>, context: RouteContext, tokenRegistry: TokenRegistry): Promise<Response>;
 }
-/** Further gateway-owned RPC types (`iam.*`, `onboarding.update`), see `GatewayHttpServer.useConsoleRpc`. */
+/**
+ * Further gateway-owned RPC types (`iam.*`, `onboarding.update`, the global plugin switch), see
+ * `GatewayHttpServer.useConsoleRpc`.
+ */
 export interface GatewayRpcHandler extends GatewayConsoleRpc {
     owns(type: string): boolean;
+    /**
+     * Narrows {@link owns} by payload: when present and false for the parsed message, the request
+     * is forwarded to the instance untouched (e.g. `feature.set-enabled` below the global level).
+     */
+    claims?(message: Readonly<Record<string, unknown>>): boolean;
 }
 export declare function createGatewayConsoleRpc(dispatch: GatewayRpcDispatcher): GatewayConsoleRpc;

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;