@zhin.js/gateway 1.1.1 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@
 Zhin.js 管理网关（[ADR 0054](../../../docs/adr/0054-management-gateway.md)）。网关负责宿主层面的事：Console 账号与权限、终端、
 项目配置与 `.env`、依赖事务、实例监管。它**不依赖 `zhin.js` 与 IM 层**，不加载插件代码（`pnpm check:architecture` 强制）。
 
-网关进程（`zhin start`；前台运行用 `zhin start --foreground`）自己打开项目数据库并持有 `console_*` 表：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
+网关进程（`zhin start`；前台运行用 `zhin start --foreground`）把 `console_*` 账号表放在自己的 `.zhin/gateway.db`（ADR 0059，与项目数据库方言无关；升级时自动从项目数据库迁入）：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
 都在网关里，没有实例时 Console 照样可用；受管实例只按转发的主体做授权。`--standalone`（开发 / 测试，无网关）的实例仍在进程内
 装配 `installConsoleIam` / `installHostConsoleTerminal`。
 
@@ -27,7 +27,7 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 
 | 子路径 | 内容 |
 |---|---|
-| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc` |
+| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc`、`importLegacyIamTables` / `revertLegacyIamImport` / `inspectLegacyIamImport`（旧版项目库账号表迁入 gateway.db 与回退，ADR 0059） |
 | `@zhin.js/gateway/terminal` | Console 终端（ADR 0051）：`TerminalService`、`installHostConsoleTerminal`、`parseTerminalConfig` |
 | `@zhin.js/gateway/config` | 原始配置文件与 `.env` 读写：`ConsoleConfigurationStore`、`readEnvFile` / `writeEnvFile`、配置路径与补丁、Console Schema |
 | `@zhin.js/gateway/plugin-management` | 项目级依赖事务：`PluginManagementWorkflow`、`PluginManagementActivity`、插件用例 |
@@ -36,8 +36,8 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 | `@zhin.js/gateway/usage` | 用量统计聚合 |
 | `@zhin.js/gateway/onboarding` | Console 引导（ADR 0053）：`.zhin/onboarding.json` 状态（`OnboardingStateStore`、自动识别已配置步骤）、`OnboardingService`、安装白名单与 `authorizeInstall`、流式 `installPackages` |
 | `@zhin.js/gateway/http` | HTML / SSE 响应工具（实例也导入，不加载 Node HTTP 栈） |
-| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（项目数据库、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
-| `@zhin.js/gateway/database` | 网关自己的项目数据库连接（ADR 0054 §7）：`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`） |
+| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（gateway.db、旧表迁移、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
+| `@zhin.js/gateway/database` | 网关自己的存储与临时项目库连接（ADR 0054 §7、ADR 0059）：`openGatewayStore`（`.zhin/gateway.db`，`0600`，`gateway_meta`）、`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则，含 `database.console`）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`；`tableExists` / `readSnapshot` / `dropTables` 供迁移使用）、`setupConsoleRole`（`zhin db console-role`：PostgreSQL / MySQL 的 Console SQL 受限账号） |
 | `@zhin.js/gateway` | 以上全部 |
 
 ```ts

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/database/config.js

@@ -53,6 +53,32 @@ function normalizeRedisDatabase(value) {
     }
     return normalized;
 }
+/** `database.console` (ADR 0059 §4; port of the instance's check): PostgreSQL / MySQL only. */
+function normalizeConsoleCredential(config) {
+    if (!('console' in config) || config.console === undefined)
+        return;
+    const value = config.console;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw configurationError('database.console', '必须是对象 { user, password }');
+    const block = { ...value };
+    // `${ZHIN_DB_CONSOLE_*}` not set (yet): no restricted account — raw SQL stays off, the rest works.
+    if ((block.user === undefined || block.user === '') && (block.password === undefined || block.password === '')) {
+        delete config.console;
+        return;
+    }
+    normalizeRequiredText(block, 'user', 'database.console.user', 'ZHIN_DB_CONSOLE_USER=zhin_console_xxxxxxxx');
+    if (typeof block.password !== 'string' || block.password === '') {
+        throw configurationError('database.console.password', '不能为空', 'ZHIN_DB_CONSOLE_PASSWORD=…（zhin db console-role 生成）');
+    }
+    if (String(block.user) === String(config.user ?? '')) {
+        throw configurationError('database.console.user', '不能与主账号 database.user 相同（原始 SQL 只在受限账号上执行）');
+    }
+    for (const key of Object.keys(block)) {
+        if (key !== 'user' && key !== 'password')
+            throw configurationError(`database.console.${key}`, '不支持（只有 user 与 password）');
+    }
+    config.console = Object.freeze({ user: block.user, password: block.password });
+}
 /** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
 export function normalizeProjectDatabaseConfig(input) {
     const dialect = input.dialect;
@@ -60,6 +86,9 @@ export function normalizeProjectDatabaseConfig(input) {
         throw new TypeError(`数据库配置 database.dialect 不支持 ${JSON.stringify(dialect)}；可选值为 sqlite、mysql、pg、mongodb、redis、memory。`);
     }
     const config = { ...input, dialect };
+    if (dialect !== 'pg' && dialect !== 'mysql')
+        delete config.console;
+    delete config.denyAttach;
     switch (dialect) {
         case 'mysql':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -69,6 +98,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=3306');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'pg':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -78,6 +108,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=5432');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'mongodb':
             normalizeRequiredText(config, 'url', 'database.url', 'DB_URL=mongodb://127.0.0.1:27017');

package/lib/database/console-role.d.ts

@@ -0,0 +1,35 @@
+import { type ConsoleCredentialDialect } from '@zhin.js/database';
+export declare const CONSOLE_ROLE_USER_ENV = "ZHIN_DB_CONSOLE_USER";
+export declare const CONSOLE_ROLE_PASSWORD_ENV = "ZHIN_DB_CONSOLE_PASSWORD";
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export declare const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = "<ZHIN_DB_CONSOLE_PASSWORD>";
+export declare class ConsoleRoleError extends Error {
+    readonly code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied';
+    constructor(code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied', message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SetupConsoleRoleOptions {
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `${…}` (default `development`). */
+    readonly environment?: string;
+    /** Role name (default `zhin_console_<hash of the project root>`). */
+    readonly role?: string;
+    /**
+     * Do not create the account: write the password to `.env` and the reference to the config,
+     * and return the statements for a DBA (password shown as {@link CONSOLE_ROLE_PASSWORD_PLACEHOLDER}).
+     */
+    readonly printSql?: boolean;
+}
+export interface SetupConsoleRoleResult {
+    readonly dialect: ConsoleCredentialDialect;
+    readonly user: string;
+    /** Created / rotated by this run (false with `printSql`). */
+    readonly provisioned: boolean;
+    /** The statements (password replaced by the placeholder). */
+    readonly statements: readonly string[];
+    readonly envFile: string;
+}
+export declare function setupConsoleRole(options: SetupConsoleRoleOptions): Promise<SetupConsoleRoleResult>;
+/** The default role name of a project (what `zhin db console-role` creates). */
+export declare function defaultConsoleRoleName(projectRoot: string): string;

package/lib/database/console-role.js

@@ -0,0 +1,108 @@
+/**
+ * `zhin db console-role` and `zhin doctor --fix` (ADR 0059 §4): create the restricted database
+ * account raw Console SQL runs on (PostgreSQL / MySQL), with the main account, store its password
+ * in `.env` and reference it from `database.console`. Never run at instance start: the instance
+ * only probes the account (and refreshes PostgreSQL grants).
+ */
+import { join } from 'node:path';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
+import { consoleRoleName, generateConsolePassword, planConsoleRole, provisionConsoleRole, scrubSecret, } from '@zhin.js/database';
+import { ConsoleConfigurationStore } from '../config/configuration.js';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { upsertDotenv } from '../iam/setup-service.js';
+import { IAM_TABLES } from '../iam/tables.js';
+import { findConfigFile } from '../project/config-file.js';
+import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from './config.js';
+import { ProjectDatabase } from './project-database.js';
+export const CONSOLE_ROLE_USER_ENV = 'ZHIN_DB_CONSOLE_USER';
+export const CONSOLE_ROLE_PASSWORD_ENV = 'ZHIN_DB_CONSOLE_PASSWORD';
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = `<${CONSOLE_ROLE_PASSWORD_ENV}>`;
+export class ConsoleRoleError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'ConsoleRoleError';
+    }
+}
+const ENV_REFERENCE = { user: `\${${CONSOLE_ROLE_USER_ENV}}`, password: `\${${CONSOLE_ROLE_PASSWORD_ENV}}` };
+export async function setupConsoleRole(options) {
+    const { projectRoot } = options;
+    const expanded = await loadExpandedProjectConfig(projectRoot, options.environment ?? 'development');
+    const config = await resolveProjectDatabaseConfig(projectRoot, expanded);
+    if (config.dialect !== 'pg' && config.dialect !== 'mysql') {
+        throw new ConsoleRoleError('unsupported', `项目数据库是 ${config.dialect}：只有 PostgreSQL / MySQL 需要受限账号（SQLite 的 Console 账号在另一个文件里，且实例连接拒绝 ATTACH）`);
+    }
+    const dialect = config.dialect;
+    const main = new ProjectDatabase(config);
+    try {
+        await main.start();
+    }
+    catch (error) {
+        throw new ConsoleRoleError('unavailable', `无法用主账号连接项目数据库：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const password = generateConsolePassword();
+    let statements;
+    let user;
+    try {
+        // The old console_* tables would be inside a MySQL database-wide grant: import them first.
+        const legacy = await main.tableExists(Object.values(IAM_TABLES));
+        if (legacy.length) {
+            throw new ConsoleRoleError('pending_migration', `项目数据库里还有旧版的 Console 账号表（${legacy.join(', ')}）：先运行 zhin start 或 zhin console migrate 完成迁移`);
+        }
+        const run = (sql, params) => main.query(sql, params);
+        const request = { dialect, projectKey: projectRoot, password, ...(options.role ? { role: options.role } : {}) };
+        if (options.printSql) {
+            const plan = await planConsoleRole(run, request);
+            statements = plan.statements;
+            user = plan.user;
+        }
+        else {
+            try {
+                const plan = await provisionConsoleRole(run, request);
+                statements = plan.statements;
+                user = plan.user;
+            }
+            catch (error) {
+                // The message never carries the new password (provisionConsoleRole scrubs; scrub again here).
+                throw new ConsoleRoleError('denied', scrubSecret(`主账号无法创建受限账号（${error instanceof Error ? error.message : String(error)}）；改用 zhin db console-role --print-sql 把 SQL 交给 DBA 执行`, [password]));
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ConsoleRoleError)
+            throw error;
+        throw new ConsoleRoleError('unavailable', scrubSecret(error instanceof Error ? error.message : String(error), [password]));
+    }
+    finally {
+        await main.stop().catch(() => undefined);
+    }
+    // The password lives only in .env (ADR 0057); the config references it.
+    await writeEnvFile(projectRoot, '.env', upsertDotenv(await readEnvFile(projectRoot, '.env'), {
+        [CONSOLE_ROLE_USER_ENV]: user,
+        [CONSOLE_ROLE_PASSWORD_ENV]: password,
+    }));
+    const store = new ConsoleConfigurationStore({
+        projectRoot,
+        document: createConfigDocument(join(projectRoot, findConfigFile(projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME)),
+    });
+    const document = await store.readDocument();
+    const block = document.database && typeof document.database === 'object' && !Array.isArray(document.database)
+        ? document.database
+        : { dialect };
+    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } });
+    return Object.freeze({
+        dialect,
+        user,
+        provisioned: !options.printSql,
+        // PostgreSQL statements carry a SCRAM verifier, never the password; MySQL's are shown with a placeholder.
+        statements: Object.freeze(statements.map(statement => scrubSecret(statement, [password]).split('[redacted]').join(CONSOLE_ROLE_PASSWORD_PLACEHOLDER))),
+        envFile: '.env',
+    });
+}
+/** The default role name of a project (what `zhin db console-role` creates). */
+export function defaultConsoleRoleName(projectRoot) {
+    return consoleRoleName(projectRoot);
+}