@zhin.js/gateway 1.1.2 → 1.3.0

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

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

package/lib/http/console-rpc.js

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

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

@@ -1,7 +1,7 @@
 import { type ConsoleAuditEntry } from '@zhin.js/host-http';
 import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
 import { type ProjectDatabaseConfig } from '../database/config.js';
-import { ProjectDatabase } from '../database/project-database.js';
+import { type GatewayStore, type OpenGatewayStoreOptions } from '../database/gateway-store.js';
 import { type LocalConsoleAdmin } from '../iam/local-admin.js';
 import { ConsoleIamService } from '../iam/service.js';
 import { ConsoleSetupService } from '../iam/setup-service.js';
@@ -26,26 +26,33 @@ export interface GatewayConsoleOptions {
     readonly instance?: GatewayConsoleInstancePort;
     /** Restarts the instance after the setup wizard switched databases (ADR 0054 §7). */
     readonly restartInstance?: () => Promise<void>;
-    /** Overrides the project `database` block (tests). */
+    /** Overrides the project `database` block the old `console_*` tables are imported from (tests). */
     readonly database?: ProjectDatabaseConfig;
+    /** Gateway store overrides (tests; default `.zhin/gateway.db`). */
+    readonly store?: OpenGatewayStoreOptions;
     /** Overrides the project `console.terminal` block. */
     readonly terminal?: unknown;
     readonly onboarding?: OnboardingService;
-    /** Retry interval while the database cannot be opened. Default 10 s. */
+    /** Retry interval while gateway.db or the import of the old tables fails. Default 10 s. */
     readonly retryMs?: number;
 }
 export interface GatewayConsole {
-    /** Settles once the first database open attempt finished (never rejects). */
+    /** Settles once the first open attempt finished (never rejects). */
     readonly ready: Promise<void>;
-    /** The IAM service bound to the open database; undefined when the dialect cannot hold accounts. */
+    /** The IAM service; fails closed (`unavailableReason()`) until gateway.db is open and imported. */
     iam(): ConsoleIamService | undefined;
-    /** The gateway's database connection (undefined before the first open). */
-    database(): ProjectDatabase | undefined;
+    /** The gateway store `.zhin/gateway.db` (undefined before it opened). */
+    database(): GatewayStore | undefined;
     readonly setup: ConsoleSetupService;
     readonly onboarding: OnboardingService;
     readonly terminal: ConsoleTerminalHandle;
-    /** Closes the gateway's connection and opens the configured database again (setup wizard). */
+    /** Closes gateway.db and opens it again (and retries a pending import). */
     reopenDatabase(): Promise<void>;
+    /**
+     * Writes the store marker into the project database if it is missing (after the first owner was
+     * created and after the instance first reported ready: a first-run project file exists by then).
+     */
+    ensureStoreMarker(): Promise<void>;
     /** Socket-only `gateway.console.*` (`zhin console init` / `zhin console user` beside the gateway). */
     readonly localAdmin: LocalConsoleAdmin;
     close(): Promise<void>;

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
@@ -10,34 +12,46 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { ONBOARDING_RPC } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, IAM_RPC, ONBOARDING_RPC } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
 import { createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 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 () => {
@@ -247,6 +330,7 @@ const ONBOARDING_STEPS = new Set(['ai', 'adapters', 'finish']);
 export function createGatewayAccountRpc(options) {
     return Object.freeze({
         owns: (type) => isIamRpc(type) || type === ONBOARDING_RPC.UPDATE,
+        types: () => [...Object.values(IAM_RPC), ONBOARDING_RPC.UPDATE],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const requestId = message.requestId;
@@ -255,21 +339,21 @@ export function createGatewayAccountRpc(options) {
                 return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
             }
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${String(message.type ?? '')}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const result = isIamRpc(message.type)
@@ -278,7 +362,7 @@ export function createGatewayAccountRpc(options) {
             if (decision.write)
                 audit(result.status < 400 && result.body.success !== false ? 'ok' : 'error');
             else if (result.status === 403)
-                audit('denied');
+                audit('denied', CONSOLE_DENIAL_REASONS.HANDLER_DENIED);
             return jsonResponse(result.status, result.body, { ...noStore, ...result.headers });
         },
     });

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

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

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

@@ -17,7 +17,7 @@
  */
 import { join } from 'node:path';
 import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
-import { FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
 import { DEFAULT_ROOT_CONFIG_FILE_NAME, FEATURE_OVERRIDES_KEY } from '@zhin.js/plugin-runtime';
 import { collectFeatureOverrideWarnings, createConfigDocument } from '@zhin.js/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -39,6 +39,7 @@ export function createGatewayPluginSwitchRpc(options) {
     return Object.freeze({
         owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
         claims: isGatewayPluginSwitch,
+        types: () => [PLUGIN_RPC.SET_ENABLED, FEATURE_RPC.SET_ENABLED],
         async handle(message, context, registry) {
             const noStore = { 'cache-control': 'no-store' };
             const type = String(message.type ?? '');
@@ -49,27 +50,27 @@ export function createGatewayPluginSwitchRpc(options) {
             }
             // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
             const decision = authorizeConsoleRpc(principal, message);
-            const audit = (outcome) => {
+            const audit = (outcome, reason) => {
                 try {
                     registry.accessProvider?.audit?.({
                         actor: auditActor(principal),
                         action: `rpc:${type}`.slice(0, 256),
                         ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
                         outcome,
-                        detail: rpcAuditDetail(message),
+                        detail: reason ? { ...rpcAuditDetail(message), reason } : rpcAuditDetail(message),
                         ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
                     });
                 }
                 catch { /* audit never breaks a request */ }
             };
             if (!decision.allowed) {
-                audit('denied');
+                audit('denied', decision.reason);
                 return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
             }
             const reply = type === PLUGIN_RPC.SET_ENABLED
                 ? await setPluginEnabled(message, principal, options, readConfig)
                 : await setFeatureGlobal(message, principal, options, readConfig);
-            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error');
+            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error', reply.status === 403 ? CONSOLE_DENIAL_REASONS.HANDLER_DENIED : undefined);
             return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
         },
     });
@@ -197,7 +198,11 @@ 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 the plugin's own overrides (as the instance computed them). */
+/**
+ * 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;

package/lib/http/start-gateway.js

@@ -141,6 +141,15 @@ export async function startGateway(options) {
                 },
             });
             await settleWithin(gatewayConsole.ready, options.databaseWaitMs ?? 10_000);
+            // ADR 0059 §3: once the instance runs, a first-run SQLite project file exists; make sure the
+            // store marker is there (normally written at connect time already).
+            let markerChecked = false;
+            supervisor.on('state', (status) => {
+                if (markerChecked || status.state !== 'running')
+                    return;
+                markerChecked = true;
+                void gatewayConsole?.ensureStoreMarker();
+            });
         }
         assertNotOpenOnNetwork(http, server.tokenRegistry);
         // Settings for the first instance start, read before listening so it starts right away.