@zhin.js/gateway 1.3.0 → 1.4.0

package/lib/config/configuration.d.ts

@@ -20,6 +20,14 @@ export declare class ConfigChatRequestRejectedError extends Error {
     constructor();
 }
 /** Owns one project's Console configuration projection over the Root config authority. */
+/**
+ * What the caller of a configuration write may do besides `ops.config.write`. Set by the Console
+ * RPC context from the principal's grants, and by trusted in-process / local-owner callers.
+ */
+export interface ConfigWriteAuthority {
+    /** The caller may write `.env` (`ops.env.write`): secret literals may be moved there. Default false. */
+    readonly environmentWrite?: boolean;
+}
 export declare class ConsoleConfigurationStore {
     #private;
     constructor(options: {
@@ -43,7 +51,12 @@ export declare class ConsoleConfigurationStore {
         readonly revision: string;
         readonly restartRequired: boolean;
     } & ConsoleConfigApplicationStatus>;
-    setKey(pluginName: string, data: unknown): Promise<{
+    /**
+     * `options.environmentWrite`: the caller holds `ops.env.write` (or is a trusted in-process / local
+     * owner caller). Without it a block whose secret fields hold literals is refused
+     * ({@link SecretEnvironmentWriteRequiredError}): those values would be written into `.env`.
+     */
+    setKey(pluginName: string, data: unknown, options?: ConfigWriteAuthority): Promise<{
         restartRequired: boolean;
     } & ConsoleConfigApplicationStatus>;
     removeKey(pluginName: string): Promise<{
@@ -54,14 +67,14 @@ export declare class ConsoleConfigurationStore {
      * allowlist are rejected before reading values; a stale revision returns the latest
      * values instead of overwriting; every touched section is validated by its schema.
      */
-    patch(request: ConsoleConfigPatchRequest): Promise<ConsoleConfigPatchResult>;
+    patch(request: ConsoleConfigPatchRequest, options?: ConfigWriteAuthority): Promise<ConsoleConfigPatchResult>;
     /**
      * Trusted project administration (`config:patch-project`, full scope only). Same
      * single-CAS core as {@link patch}, without the page allowlist; it does not widen
      * `config:patch` / `HOST_CONFIG_PATCH_PATHS`. Declaration writes are rejected as
      * `invalid`, conflict values are masked, and a thrown commit is `unconfirmed`.
      */
-    patchProject(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigProjectPatchResult>;
+    patchProject(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>, options?: ConfigWriteAuthority): Promise<ConsoleConfigProjectPatchResult>;
     /** Host-authenticated owner chat. Policy checks share the mutation's CAS boundary. */
     patchChat(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigPatchResult>;
     /**

package/lib/config/configuration.js

@@ -7,7 +7,9 @@ import { readPluginPackageMap } from './plugin-package-map.js';
 import { assertUnambiguousConfigKey, configKeyPatch, configKeyRemovePatch, flattenConfigDocument } from './configuration-projection.js';
 import { readEnvFile, readEnvFileView, replaceEnvFileContent, revealEnvVariable, updateEnvVariables, writeEnvFile, } from './environment-files.js';
 import { PluginSchemaCatalog } from './plugin-schema-catalog.js';
+import { declarationKeyMessage, describeArrayPathProblem, unknownConfigKeyMessage } from './patch-path-messages.js';
 import { findProjectLiteralSecrets } from './literal-secrets.js';
+import { planSecretExternalization, SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError, secretEnvironmentWriteRequiredMessage, writeSecretAssignments, } from './secret-storage.js';
 import { hostModelOwnerId } from '@zhin.js/plugin-runtime';
 import { assertChatConfigurationAccess, assertChatConfigurationScope, assertChatValueHasNoEnvironmentReference, assertChatOptionalLeaf, chatConfigurationLeaves, chatHostRoots, chatLeafTypes, ConfigChatAccessError, } from './configuration-chat-policy.js';
 import { isForbiddenConfigurationPathSegment } from './configuration-path.js';
@@ -49,7 +51,6 @@ function chatApplication(application) {
             dependsOn: Object.freeze([]),
         }))) });
 }
-/** Owns one project's Console configuration projection over the Root config authority. */
 export class ConsoleConfigurationStore {
     #projectRoot;
     #document;
@@ -121,16 +122,36 @@ export class ConsoleConfigurationStore {
             });
         });
     }
-    setKey(pluginName, data) {
+    /**
+     * `options.environmentWrite`: the caller holds `ops.env.write` (or is a trusted in-process / local
+     * owner caller). Without it a block whose secret fields hold literals is refused
+     * ({@link SecretEnvironmentWriteRequiredError}): those values would be written into `.env`.
+     */
+    setKey(pluginName, data, options = {}) {
         return this.#serialize(async () => {
             const current = await this.#document.read();
             await this.#assertUnambiguousKey(current.document, pluginName);
-            const prepared = await this.#document.prepare(current, [
-                configKeyPatch(current.document, pluginName, data),
-            ]);
-            readApplicationPluginDeclaration(prepared.document);
-            await this.#validatePrepared(prepared);
-            const committed = await prepared.commit();
+            const patches = [configKeyPatch(current.document, pluginName, data)];
+            // Literal values of secret fields go to `.env`; the block keeps `${VAR}` references (#1250).
+            const plan = await planSecretExternalization(this.#projectRoot, this.#environmentName(), current.document, applyConfigPatches(current.document, patches), patches.map(patch => patch.path));
+            if (plan.assignments.length > 0 && options.environmentWrite !== true) {
+                throw new SecretEnvironmentWriteRequiredError(plan.assignments.map(item => item.path));
+            }
+            if (plan.errors.length > 0)
+                throw new Error(plan.errors.map(error => error.message).join('；'));
+            patches.push(...plan.patches);
+            const restoreEnvironment = await writeSecretAssignments(this.#projectRoot, this.#environmentName(), plan.assignments);
+            let committed;
+            try {
+                const prepared = await this.#document.prepare(current, patches);
+                readApplicationPluginDeclaration(prepared.document);
+                await this.#validatePrepared(prepared);
+                committed = await prepared.commit();
+            }
+            catch (error) {
+                await restoreEnvironment();
+                throw error;
+            }
             return this.#applySaved(HOST_CONFIG_KEYS.includes(pluginName), committed.revision);
         });
     }
@@ -152,8 +173,8 @@ export class ConsoleConfigurationStore {
      * allowlist are rejected before reading values; a stale revision returns the latest
      * values instead of overwriting; every touched section is validated by its schema.
      */
-    patch(request) {
-        return this.#serialize(() => this.#patchCore(request, 'scoped'));
+    patch(request, options = {}) {
+        return this.#serialize(() => this.#patchCore(request, 'scoped', options));
     }
     /**
      * Trusted project administration (`config:patch-project`, full scope only). Same
@@ -161,10 +182,11 @@ export class ConsoleConfigurationStore {
      * `config:patch` / `HOST_CONFIG_PATCH_PATHS`. Declaration writes are rejected as
      * `invalid`, conflict values are masked, and a thrown commit is `unconfirmed`.
      */
-    patchProject(request) {
+    patchProject(request, options = {}) {
         return this.#serialize(async () => {
             try {
-                return await this.#patchCore({ expectedRevision: request.expectedRevision, patches: request.patches }, 'project');
+                return await this.#patchCore({ expectedRevision: request.expectedRevision, patches: request.patches,
+                    ...(request.secretStorage === undefined ? {} : { secretStorage: request.secretStorage }) }, 'project', options);
             }
             catch (error) {
                 if (!(error instanceof ConfigCommitUnconfirmedError))
@@ -196,11 +218,13 @@ export class ConsoleConfigurationStore {
         });
     }
     /** Shared single-CAS write: `scoped` keeps the page allowlist; `project` is the trusted full path. */
-    async #patchCore(request, mode) {
+    async #patchCore(request, mode, authority = {}) {
         let phase = 'prepare';
+        // Restores `.env` when secrets were moved there but the config write does not happen.
+        let restoreEnvironment;
         try {
             const instanceKey = request.instanceKey;
-            const patches = normalizeConfigPatchOperations(request.patches);
+            let patches = normalizeConfigPatchOperations(request.patches);
             const current = await this.#document.read();
             if (mode === 'scoped') {
                 const declared = instanceKey === undefined
@@ -213,8 +237,9 @@ export class ConsoleConfigurationStore {
             if (mode !== 'scoped') {
                 const rejected = projectDeclarationErrors(current.document, paths);
                 if (rejected.length > 0) {
+                    const declarationWrite = paths.some(path => PROJECT_PATCH_DECLARATION_KEYS.has(path[0]));
                     return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(rejected),
-                        missingEnv: Object.freeze([]), message: '插件声明不能通过项目补丁修改，未保存' });
+                        missingEnv: Object.freeze([]), message: declarationWrite ? '插件声明不能通过项目补丁修改，未保存' : '没有这个配置项，未保存' });
                 }
             }
             const conflict = async (snapshot) => Object.freeze({
@@ -226,7 +251,44 @@ export class ConsoleConfigurationStore {
             });
             if (current.revision !== request.expectedRevision)
                 return await conflict(current);
-            const candidate = applyConfigPatches(current.document, patches);
+            // Array indexes outside the array (or a key where an index belongs) are a usage problem:
+            // answer with an explanation instead of the document layer's internal exception.
+            const arrayProblems = patches.flatMap(patch => {
+                const message = describeArrayPathProblem(current.document, patch.path, patch.op);
+                return message ? [{ path: `$.${patch.path.join('.')}`, message }] : [];
+            });
+            if (arrayProblems.length > 0) {
+                return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(arrayProblems),
+                    missingEnv: Object.freeze([]), message: '配置路径无效，未保存' });
+            }
+            let candidate = applyConfigPatches(current.document, patches);
+            // Secret fields keep `${VAR}` references: a literal written here goes to `.env` (#1250),
+            // unless the caller explicitly asked for plain storage. Chat writes never carry literals
+            // into secret fields (they are refused by the chat policy).
+            let envSecrets = [];
+            let secretAssignments = [];
+            if (mode !== 'chat' && request.secretStorage !== 'plain') {
+                const plan = await planSecretExternalization(this.#projectRoot, this.#environmentName(), current.document, candidate, patches.filter(patch => patch.op === 'set').map(patch => patch.path));
+                if (plan.errors.length > 0) {
+                    return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(plan.errors),
+                        missingEnv: Object.freeze([]), message: '配置校验失败，未保存' });
+                }
+                // Moving a value into `.env` is an `.env` write: it needs `ops.env.write` (#1250). Without
+                // it the write is refused, never stored as plain text behind the caller's back.
+                if (plan.assignments.length > 0 && authority.environmentWrite !== true) {
+                    const paths = plan.assignments.map(item => item.path);
+                    return Object.freeze({ status: 'invalid', revision: current.revision, code: SECRET_ENVIRONMENT_WRITE_REQUIRED,
+                        errors: Object.freeze(paths.map(path => Object.freeze({ path: `$.${path.join('.')}`,
+                            message: '敏感字段的值要写入 .env，需要 ops.env.write 权限' }))),
+                        missingEnv: Object.freeze([]), message: secretEnvironmentWriteRequiredMessage(paths) });
+                }
+                if (plan.patches.length > 0) {
+                    patches = Object.freeze([...patches, ...plan.patches]);
+                    candidate = applyConfigPatches(current.document, patches);
+                    secretAssignments = plan.assignments;
+                    envSecrets = Object.freeze(plan.assignments.map(item => Object.freeze({ path: item.path, variable: item.variable })));
+                }
+            }
             // Chat writes exactly one leaf (C1/C4); scope and leaf shape are proven before values.
             if (mode === 'chat' && patches.length !== 1)
                 throw new ConfigChatAccessError('leaf');
@@ -267,6 +329,8 @@ export class ConsoleConfigurationStore {
                 for (const name of validation.missingEnv)
                     missingEnv.add(name);
             }
+            for (const { variable } of envSecrets)
+                missingEnv.delete(variable);
             if (errors.length > 0) {
                 return Object.freeze({
                     status: 'invalid',
@@ -277,6 +341,7 @@ export class ConsoleConfigurationStore {
                 });
             }
             let committed;
+            restoreEnvironment = await writeSecretAssignments(this.#projectRoot, this.#environmentName(), secretAssignments);
             try {
                 const prepared = await this.#document.prepare(current, patches);
                 readApplicationPluginDeclaration(prepared.document);
@@ -289,6 +354,7 @@ export class ConsoleConfigurationStore {
                     // Runtime validation may report cross-field constraints without a
                     // structured path. Preserve the invalid contract at the document
                     // boundary; arbitrary issue strings can contain private values.
+                    await restoreEnvironment();
                     return Object.freeze({ status: 'invalid', revision: current.revision,
                         errors: Object.freeze([Object.freeze({ path: '$', message: '完整配置未通过运行校验' })]),
                         missingEnv: Object.freeze([...missingEnv].sort()), message: '配置校验失败，未保存' });
@@ -310,6 +376,8 @@ export class ConsoleConfigurationStore {
                 }
             }
             catch (error) {
+                if (phase === 'prepare')
+                    await restoreEnvironment();
                 if (error instanceof ConfigDocumentConflictError)
                     return await conflict(await this.#document.read());
                 throw error;
@@ -322,6 +390,7 @@ export class ConsoleConfigurationStore {
                 ...applied,
                 paths,
                 missingEnv: Object.freeze([...missingEnv].sort()),
+                ...(envSecrets.length > 0 ? { envSecrets } : {}),
                 message: applied.applicationError === 'superseded' ? '配置已保存，但该次生效申请已被替代'
                     : applied.applicationError === 'invalid' ? '配置已保存，但配置校验失败，未生效'
                         : applied.applicationError ? '配置已保存，生效结果未确认' : applied.restartRequired
@@ -688,10 +757,11 @@ function projectDeclarationErrors(document, paths) {
     const errors = [];
     for (const section of new Set(paths.map(path => path[0]))) {
         if (PROJECT_PATCH_DECLARATION_KEYS.has(section)) {
-            errors.push({ path: `$.${section}`, message: '插件声明与根插件配置请用 gateway.plugins.declare、配置源码或插件管理修改' });
+            errors.push({ path: `$.${section}`, message: declarationKeyMessage(section) });
         }
         else if (!HOST_CONFIG_KEYS.includes(section) && !declared.has(section)) {
-            errors.push({ path: `$.${section}`, message: '未声明的插件实例；请先用 gateway.plugins.declare 声明' });
+            const known = [...HOST_CONFIG_KEYS, ...declared].filter(key => !PROJECT_PATCH_DECLARATION_KEYS.has(key));
+            errors.push({ path: `$.${section}`, message: unknownConfigKeyMessage(section, known) });
         }
     }
     return errors;

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

@@ -32,3 +32,6 @@ export interface LiteralSecretFixResult {
  * variables already written, so the operation is idempotent.
  */
 export declare function moveLiteralSecretsToEnv(projectRoot: string, configFile: string): Promise<LiteralSecretFixResult>;
+/** A `NAME=value` dotenv line that parses back to exactly `value`, or undefined when none does. */
+export declare function dotenvLine(name: string, value: string): string | undefined;
+export declare function readDocumentPath(document: unknown, path: readonly string[]): unknown;

package/lib/config/literal-secrets.js

@@ -100,7 +100,7 @@ export async function moveLiteralSecretsToEnv(projectRoot, configFile) {
     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) {
+export function dotenvLine(name, value) {
     if (/[\r\n]/u.test(value))
         return undefined;
     for (const quote of ["'", '`', '"']) {
@@ -112,6 +112,9 @@ function dotenvLine(name, value) {
     }
     return undefined;
 }
+export function readDocumentPath(document, path) {
+    return readPath(document, path);
+}
 function readPath(document, path) {
     let current = document;
     for (const segment of path) {

package/lib/config/patch-path-messages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Chinese explanations for project config patches that cannot apply (#1250): unknown top-level
+ * keys (with close candidates), declaration keys, and array indexes outside the array. Shown by
+ * `zhin config set|unset` and the Console; they never name RPCs or revisions.
+ */
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** Up to three known keys close to `key` (edit distance, prefix or substring). */
+export declare function closeConfigKeys(key: string, known: Iterable<string>): string[];
+export declare function unknownConfigKeyMessage(section: string, known: Iterable<string>): string;
+export declare function declarationKeyMessage(section: string): string;
+/**
+ * Why `path` cannot be written in `document` because of an array segment, or undefined. `set`
+ * cannot append: an index equal to the length is out of range too.
+ */
+export declare function describeArrayPathProblem(document: RuntimeConfigDocument, path: readonly string[], op: 'set' | 'remove'): string | undefined;

package/lib/config/patch-path-messages.js

@@ -0,0 +1,71 @@
+function displayPath(path) {
+    return path.join('.');
+}
+/** Damerau-free Levenshtein distance, enough for "did you mean" suggestions. */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+/** Up to three known keys close to `key` (edit distance, prefix or substring). */
+export function closeConfigKeys(key, known) {
+    const lower = key.toLowerCase();
+    return [...new Set(known)]
+        .map(candidate => ({ candidate, score: distance(lower, candidate.toLowerCase()) }))
+        .filter(({ candidate, score }) => score <= Math.max(2, Math.floor(key.length / 3))
+        || candidate.toLowerCase().startsWith(lower) || lower.startsWith(candidate.toLowerCase())
+        || (lower.length >= 3 && candidate.toLowerCase().includes(lower)))
+        .sort((left, right) => left.score - right.score || left.candidate.localeCompare(right.candidate))
+        .slice(0, 3)
+        .map(({ candidate }) => candidate);
+}
+export function unknownConfigKeyMessage(section, known) {
+    const close = closeConfigKeys(section, known);
+    return `没有这个配置项：${section}（不是 Host 配置，也不是已声明的插件实例）`
+        + (close.length > 0 ? `。你是不是想写：${close.join('、')}？` : '。')
+        + '要给新插件写配置，先在 Console「插件」页或用 zhin install <包名> 安装并声明它';
+}
+export function declarationKeyMessage(section) {
+    return `${section} 是插件声明，不能用配置补丁修改；请在 Console「插件」页管理插件，或直接编辑配置文件`;
+}
+/**
+ * Why `path` cannot be written in `document` because of an array segment, or undefined. `set`
+ * cannot append: an index equal to the length is out of range too.
+ */
+export function describeArrayPathProblem(document, path, op) {
+    let current = document;
+    for (let index = 0; index < path.length; index++) {
+        const segment = path[index];
+        const here = path.slice(0, index + 1);
+        if (Array.isArray(current)) {
+            const parent = displayPath(path.slice(0, index));
+            if (!/^(0|[1-9]\d*)$/u.test(segment)) {
+                return `${parent} 是数组，${displayPath(here)} 里的 "${segment}" 应为数组下标（0–${Math.max(current.length - 1, 0)}）`;
+            }
+            const position = Number(segment);
+            if (position >= current.length) {
+                const range = current.length === 0 ? '当前是空数组' : `当前有 ${current.length} 项，下标 0–${current.length - 1}`;
+                const append = op === 'set'
+                    ? `。要追加一项：先用 zhin config get ${parent} 读出整个数组，加上新项后用 zhin config set ${parent} '<JSON 数组>' 整体写回`
+                    : '';
+                return `${displayPath(here)} 超出数组范围（${range}）${append}`;
+            }
+            current = current[position];
+            continue;
+        }
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = Object.hasOwn(current, segment) ? current[segment] : undefined;
+        if (current === undefined)
+            return undefined;
+    }
+    return undefined;
+}

package/lib/config/secret-storage.d.ts

@@ -0,0 +1,42 @@
+import type { ConfigPatch, RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** How a patch stores secret values: `env` (default) or `plain` (explicit opt-out, e.g. `zhin config set --plain`). */
+export type ConfigSecretStorage = 'env' | 'plain';
+/** Result / error code when a write would store secret values in `.env` without `ops.env.write`. */
+export declare const SECRET_ENVIRONMENT_WRITE_REQUIRED = "env-write-required";
+/** Refusal message for {@link SECRET_ENVIRONMENT_WRITE_REQUIRED}; names the fields, never values. */
+export declare function secretEnvironmentWriteRequiredMessage(paths: readonly (readonly string[])[]): string;
+/** `setKey` refusal: the block holds secret literals but the caller may not write `.env`. */
+export declare class SecretEnvironmentWriteRequiredError extends Error {
+    readonly paths: readonly (readonly string[])[];
+    readonly code = "env-write-required";
+    constructor(paths: readonly (readonly string[])[]);
+}
+export interface SecretAssignment {
+    readonly path: readonly string[];
+    readonly variable: string;
+    /** Never serialized into results. */
+    readonly value: string;
+}
+export interface SecretExternalizationPlan {
+    /** `set path → ${VAR}` patches applied after the caller's patches. */
+    readonly patches: readonly ConfigPatch[];
+    readonly assignments: readonly SecretAssignment[];
+    /** Secret values `.env` cannot hold (line breaks): the write is refused for these paths. */
+    readonly errors: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+}
+/** `http.token` → `HTTP_TOKEN` (the `${…}` name the scaffold uses), `qq.endpoints.0.appSecret` → `QQ_ENDPOINTS_0_APP_SECRET`. */
+export declare function canonicalSecretVariable(path: readonly string[]): string;
+/**
+ * Plans moving the literal secrets that `candidate` newly holds under `touched` paths (values that
+ * differ from `current`) into `.env`.
+ */
+export declare function planSecretExternalization(projectRoot: string, environmentName: string, current: RuntimeConfigDocument, candidate: RuntimeConfigDocument, touched: readonly (readonly string[])[]): Promise<SecretExternalizationPlan>;
+/**
+ * Writes the assignments: into `.env.<environment>` when that file already defines the variable
+ * (it overrides `.env`), and into `.env` otherwise. Returns a function that restores the previous
+ * contents (used when the config write does not happen after all).
+ */
+export declare function writeSecretAssignments(projectRoot: string, environmentName: string, assignments: readonly SecretAssignment[]): Promise<() => Promise<void>>;

package/lib/config/secret-storage.js

@@ -0,0 +1,140 @@
+/**
+ * Secret values written through a config patch go to `.env`, not into the config file (#1250).
+ *
+ * A `set` that writes a literal into a schema-marked secret field (`x-zhin-secret`, `writeOnly`,
+ * `format: password`, `x-zhin-config.secret`, or the secret field-name fallback) is rewritten:
+ * the value is stored as a `.env` variable and the config keeps (or gets) the `${VAR}` reference.
+ * The variable is the field's canonical name derived from its path (`http.token` → `HTTP_TOKEN`,
+ * with a numeric suffix when another value already holds that name). A `${VAR}` the field merely
+ * references is never overwritten unless it is that canonical name: otherwise a config write could
+ * replace any `.env` variable (e.g. point `http.token` at `${OPENAI_API_KEY}`, then set a literal).
+ * Writing into `.env` at all needs the caller's `ops.env.write` ({@link SecretEnvironmentWriteRequiredError}).
+ * Values are never returned or logged.
+ */
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseDotenv } from 'dotenv';
+import { updateDotenvFile } from '@zhin.js/runtime';
+import { dotenvLine, findProjectLiteralSecrets, literalSecretEnvironmentName, readDocumentPath as readPath } from './literal-secrets.js';
+const WHOLE_REFERENCE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/u;
+/** Result / error code when a write would store secret values in `.env` without `ops.env.write`. */
+export const SECRET_ENVIRONMENT_WRITE_REQUIRED = 'env-write-required';
+/** Refusal message for {@link SECRET_ENVIRONMENT_WRITE_REQUIRED}; names the fields, never values. */
+export function secretEnvironmentWriteRequiredMessage(paths) {
+    return `敏感字段 ${paths.map(path => path.join('.')).join('、')} 的值要写入 .env，需要 ops.env.write 权限；未保存。`
+        + '请让有该权限的管理员设置，或在 .env 中设置变量后写入 ${VAR} 引用';
+}
+/** `setKey` refusal: the block holds secret literals but the caller may not write `.env`. */
+export class SecretEnvironmentWriteRequiredError extends Error {
+    paths;
+    code = SECRET_ENVIRONMENT_WRITE_REQUIRED;
+    constructor(paths) {
+        super(secretEnvironmentWriteRequiredMessage(paths));
+        this.paths = paths;
+        this.name = 'SecretEnvironmentWriteRequiredError';
+    }
+}
+/** `http.token` → `HTTP_TOKEN` (the `${…}` name the scaffold uses), `qq.endpoints.0.appSecret` → `QQ_ENDPOINTS_0_APP_SECRET`. */
+export function canonicalSecretVariable(path) {
+    return literalSecretEnvironmentName(path).replace(/^ZHIN_/u, '');
+}
+function startsWith(path, prefix) {
+    return prefix.length <= path.length && prefix.every((segment, index) => path[index] === segment);
+}
+async function readOptional(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Plans moving the literal secrets that `candidate` newly holds under `touched` paths (values that
+ * differ from `current`) into `.env`.
+ */
+export async function planSecretExternalization(projectRoot, environmentName, current, candidate, touched) {
+    const literals = (await findProjectLiteralSecrets(projectRoot, candidate))
+        .filter(secret => touched.some(path => startsWith(secret.path, path)));
+    if (literals.length === 0)
+        return { patches: [], assignments: [], errors: [] };
+    const layers = await Promise.all(['.env', `.env.${environmentName}`].map(async (name) => parseDotenv((await readOptional(join(projectRoot, name))) ?? '')));
+    const taken = new Map();
+    for (const layer of layers)
+        for (const [name, value] of Object.entries(layer))
+            taken.set(name, value);
+    const patches = [];
+    const assignments = [];
+    const errors = [];
+    for (const secret of literals) {
+        const value = readPath(candidate, secret.path);
+        if (typeof value !== 'string' || value === '' || value === readPath(current, secret.path))
+            continue;
+        const label = secret.path.join('.');
+        const canonical = canonicalSecretVariable(secret.path);
+        const reference = WHOLE_REFERENCE.exec(String(readPath(current, secret.path) ?? ''))?.[1];
+        // Only the field's own canonical variable is updated in place. Any other `${VAR}` the field
+        // references may belong to something else (#1250): a fresh name is written instead.
+        let variable = canonical;
+        if (reference !== canonical) {
+            for (let suffix = 2; (taken.has(variable) && taken.get(variable) !== value) || variable === reference; suffix += 1) {
+                variable = `${canonical}_${suffix}`;
+            }
+        }
+        if (!dotenvLine(variable, value)) {
+            errors.push({ path: `$.${label}`, message: `${label} 是敏感字段，值含换行等字符，无法写入 .env；请手动在 .env 设置后引用 \${${variable}}，或明确用明文保存（zhin config set --plain）` });
+            continue;
+        }
+        taken.set(variable, value);
+        assignments.push({ path: secret.path, variable, value });
+        patches.push({ op: 'set', path: secret.path, value: `\${${variable}}` });
+    }
+    return { patches, assignments, errors };
+}
+function assign(content, variable, line) {
+    const pattern = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${variable}[ \\t]*=.*$`, 'mu');
+    if (pattern.test(content))
+        return content.replace(pattern, line);
+    const separator = content === '' || content.endsWith('\n') ? '' : '\n';
+    return `${content}${separator}${line}\n`;
+}
+/**
+ * Writes the assignments: into `.env.<environment>` when that file already defines the variable
+ * (it overrides `.env`), and into `.env` otherwise. Returns a function that restores the previous
+ * contents (used when the config write does not happen after all).
+ */
+export async function writeSecretAssignments(projectRoot, environmentName, assignments) {
+    if (assignments.length === 0)
+        return async () => { };
+    const files = ['.env', `.env.${environmentName}`].map(name => join(projectRoot, name));
+    const originals = await Promise.all(files.map(readOptional));
+    const overlay = parseDotenv(originals[1] ?? '');
+    const byFile = new Map();
+    for (const item of assignments) {
+        const file = Object.hasOwn(overlay, item.variable) ? files[1] : files[0];
+        byFile.set(file, [...(byFile.get(file) ?? []), item]);
+    }
+    const written = [];
+    try {
+        for (const [file, items] of byFile) {
+            await updateDotenvFile(file, content => items.reduce((text, item) => assign(text, item.variable, dotenvLine(item.variable, item.value)), content));
+            written.push(file);
+        }
+    }
+    catch (error) {
+        await restore(written);
+        throw error;
+    }
+    async function restore(targets) {
+        for (const file of targets) {
+            const original = originals[files.indexOf(file)];
+            if (original === undefined)
+                await rm(file, { force: true });
+            else
+                await updateDotenvFile(file, () => original);
+        }
+    }
+    return () => restore(written);
+}

package/lib/config/validation-messages.d.ts

@@ -5,6 +5,8 @@ export interface SchemaIssue {
     readonly params: Readonly<Record<string, unknown>>;
     readonly message?: string;
 }
+/** Schema `pattern` of a value that may be a string only as one whole `${VAR}` reference. */
+export declare const ENVIRONMENT_REFERENCE_SCHEMA_PATTERN = "^\\$\\{[A-Za-z_][A-Za-z0-9_]*(?::[-=][^}]*)?\\}$";
 /**
  * Localized text for one Ajv issue of a Plugin configuration, in the project `locale`
  * (`zh-CN` by default). `location` is the field path inside the configuration block; it is named in

package/lib/config/validation-messages.js

@@ -10,6 +10,7 @@ const messages = createMessages({
     enum: { 'zh-CN': '{field}必须是以下值之一：{values}', en: '{field}must be one of: {values}' },
     const: { 'zh-CN': '{field}必须等于 {value}', en: '{field}must equal {value}' },
     pattern: { 'zh-CN': '{field}格式不符合 {pattern}', en: '{field}must match the pattern {pattern}' },
+    environmentReference: { 'zh-CN': '{field}只接受数值或 {reference} 形式的环境变量引用', en: '{field}accepts only a number or a {reference} environment reference' },
     required: { 'zh-CN': '缺少必填字段 {property}', en: 'missing required field {property}' },
     additionalProperties: { 'zh-CN': '不支持的字段 {property}', en: 'unknown field {property}' },
     format: { 'zh-CN': '{field}应为有效的 {format}', en: '{field}must be a valid {format}' },
@@ -18,6 +19,8 @@ const messages = createMessages({
     fallback: { 'zh-CN': '{field}不满足 {keyword} 约束（{detail}）', en: '{field}does not satisfy {keyword} ({detail})' },
     field: { 'zh-CN': '字段 {path} ', en: 'Field {path} ' },
 });
+/** Schema `pattern` of a value that may be a string only as one whole `${VAR}` reference. */
+export const ENVIRONMENT_REFERENCE_SCHEMA_PATTERN = '^\\$\\{[A-Za-z_][A-Za-z0-9_]*(?::[-=][^}]*)?\\}$';
 const NUMERIC_LIMITS = new Set(['maximum', 'minimum', 'exclusiveMaximum', 'exclusiveMinimum', 'minLength', 'maxLength', 'minItems', 'maxItems']);
 function display(value) {
     return typeof value === 'string' ? value : JSON.stringify(value);
@@ -43,6 +46,10 @@ export function formatSchemaIssue(issue, location, locale) {
         case 'const':
             return messages(lang, 'const', { field, value: display(params.allowedValue) });
         case 'pattern':
+            // A string allowed only as a whole `${VAR}` reference (e.g. `http.port`): say so plainly.
+            if (String(params.pattern) === ENVIRONMENT_REFERENCE_SCHEMA_PATTERN) {
+                return messages(lang, 'environmentReference', { field, reference: '${VAR}' });
+            }
             return messages(lang, 'pattern', { field, pattern: String(params.pattern) });
         case 'format':
             return messages(lang, 'format', { field, format: String(params.format) });

package/lib/config.d.ts

@@ -11,3 +11,4 @@ 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';
+export { SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError } from './config/secret-storage.js';

package/lib/config.js

@@ -11,3 +11,4 @@ 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';
+export { SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError } from './config/secret-storage.js';

package/lib/database/console-role.js

@@ -92,7 +92,8 @@ export async function setupConsoleRole(options) {
     const block = document.database && typeof document.database === 'object' && !Array.isArray(document.database)
         ? document.database
         : { dialect };
-    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } });
+    // Local owner CLI (`zhin db console-role`): may write `.env`.
+    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } }, { environmentWrite: true });
     return Object.freeze({
         dialect,
         user,

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

@@ -1,5 +1,6 @@
 import { type ConsoleAuditEntry } from '@zhin.js/host-http';
 import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import type { BridgeRouteTable } from '@zhin.js/host-http/bridge';
 import { type ProjectDatabaseConfig } from '../database/config.js';
 import { type GatewayStore, type OpenGatewayStoreOptions } from '../database/gateway-store.js';
 import { type LocalConsoleAdmin } from '../iam/local-admin.js';
@@ -15,6 +16,10 @@ export interface GatewayConsoleInstancePort {
     pluginPermissions?(): readonly ConsolePluginPermissionInfo[];
     /** Sends `principal-revoked` (the instance closes that user's live connections). */
     revokePrincipal?(principalId: string, reason?: string): void;
+    /** Whether an instance is attached and answering (a message sent now is delivered). */
+    readonly ready?: boolean;
+    /** Runs on every route table change (an instance's first `ready` included; empty when it goes away). */
+    onRoutes?(listener: (table: BridgeRouteTable) => void): () => void;
     /** Audit entries written by the instance. */
     onAudit?(listener: (entry: ConsoleAuditEntry) => void): () => void;
 }