@zhin.js/gateway 1.1.2 → 1.2.0

package/lib/iam/rpc.js

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

package/lib/iam/service.d.ts

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

package/lib/iam/service.js

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

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

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

package/lib/iam/setup-service.js

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

package/lib/iam/tables.d.ts

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

package/lib/iam/tables.js

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

package/lib/local/protocol.d.ts

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

package/lib/local/protocol.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/gateway",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Zhin.js management gateway: Console access control, terminal, project configuration and instance supervision (ADR 0054)",
   "type": "module",
   "main": "./lib/index.js",
@@ -72,13 +72,13 @@
     "fs-extra": "^11.4.0",
     "tsx": "^4.23.1",
     "yaml": "^2.9.0",
-    "@zhin.js/console-protocol": "1.2.1",
-    "@zhin.js/database": "1.1.8",
-    "@zhin.js/host-http": "1.2.1",
+    "@zhin.js/console-protocol": "1.2.2",
+    "@zhin.js/database": "1.2.0",
+    "@zhin.js/host-http": "1.2.2",
     "@zhin.js/logger": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.2.0",
-    "@zhin.js/runtime": "1.2.1",
-    "@zhin.js/scaffold-wizard": "1.1.20"
+    "@zhin.js/plugin-runtime": "1.2.1",
+    "@zhin.js/runtime": "1.2.2",
+    "@zhin.js/scaffold-wizard": "1.1.21"
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",