@actiondock/core 2.19.0 → 2.21.0

package/dist/runtime/standalone-commands.js

@@ -1,8 +1,9 @@
 import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../utils/intent.js";
-import { resolveExecutionHint } from "../errors.js";
-import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
+import { ActionDockError, INVALID_ARGUMENT, resolveExecutionHint } from "../errors.js";
+import { resolveInput, resolveValueInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
 import { validateActionInputValue } from "../value-validator.js";
+import { assertConcreteConfigKey } from "../project/config-declarations.js";
 import { parseDuration } from "../utils/index.js";
 import { ExitCode } from "./standalone.js";
 export async function handleList(ctx, subArgs) {
@@ -148,7 +149,7 @@ export async function handleRun(ctx, subArgs, actionArgs, signal) {
     }
     let input;
     try {
-        input = await resolveActionInput({
+        input = await resolveInput({
             input: inputStr,
             inputFile,
             stdinField,
@@ -273,7 +274,57 @@ function isServiceCapabilityError(err) {
     return (code === "CAPABILITY_UNAVAILABLE" ||
         code === "TARGET_CAPABILITY_UNAVAILABLE");
 }
-export async function handleConfig(ctx, subArgs) {
+function parseSetInput(subArgs, isState) {
+    const positional = [];
+    const input = {};
+    let namespace;
+    let ttl;
+    for (let i = 1; i < subArgs.length; i++) {
+        const arg = subArgs[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--stdin") {
+            if (input.fromStdin)
+                throw new ActionDockError(INVALID_ARGUMENT, "Duplicate --stdin option");
+            input.fromStdin = true;
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const option = equals < 0 ? arg : arg.slice(0, equals);
+        if (option === "--stdin-field" || (isState && ["-n", "--namespace", "--ttl"].includes(option))) {
+            const value = equals < 0 ? subArgs[++i] : arg.slice(equals + 1);
+            if (value === undefined) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Option '${option}' requires a value`);
+            }
+            if (option === "--stdin-field") {
+                if (input.stdinField !== undefined) {
+                    throw new ActionDockError(INVALID_ARGUMENT, "Duplicate --stdin-field option");
+                }
+                input.stdinField = value;
+            }
+            else if (option === "--ttl") {
+                ttl = parseInt(value, 10);
+            }
+            else {
+                namespace = value;
+            }
+        }
+        else if (arg.startsWith("-") && !/^-\d/.test(arg)) {
+            throw new ActionDockError(INVALID_ARGUMENT, "Unknown set option");
+        }
+        else {
+            positional.push(arg);
+            if (positional.length > 2) {
+                throw new ActionDockError(INVALID_ARGUMENT, "Only one complete positional value is allowed");
+            }
+        }
+    }
+    if (!positional[0])
+        throw new ActionDockError(INVALID_ARGUMENT, "Key is required");
+    input.value = positional[1];
+    return { key: positional[0], input, namespace, ttl };
+}
+export async function handleConfig(ctx, subArgs, flatArgs, signal, stdin) {
     const sub = subArgs[0] || "list";
     if (!ctx.service.management) {
         ctx.writeErr("Error: management port is not enabled on this service");
@@ -281,10 +332,15 @@ export async function handleConfig(ctx, subArgs) {
     }
     if (sub === "list") {
         const views = await ctx.service.management.config.list(ctx.options.packageId);
-        const dict = {};
+        const dict = Object.create(null);
         for (const v of views) {
-            if (v.configured && v.value !== undefined) {
-                dict[v.key] = v.value;
+            if (v.configured) {
+                if (v.secret && v.value === undefined) {
+                    dict[v.key] = "********";
+                }
+                else if (v.value !== undefined) {
+                    dict[v.key] = v.value;
+                }
             }
         }
         ctx.writeOut(JSON.stringify(dict, null, 2));
@@ -298,7 +354,15 @@ export async function handleConfig(ctx, subArgs) {
         }
         try {
             const item = await ctx.service.management.config.get(ctx.options.packageId, key);
-            ctx.writeOut(item.configured ? JSON.stringify(item.value) : "undefined");
+            if (item.redactedPaths.includes("") || (item.configured && item.value === undefined)) {
+                ctx.writeOut("<hidden>");
+            }
+            else if (item.value === undefined) {
+                ctx.writeOut("<not configured>");
+            }
+            else {
+                ctx.writeOut(JSON.stringify(item.value));
+            }
             return ExitCode.SUCCESS;
         }
         catch (err) {
@@ -311,21 +375,27 @@ export async function handleConfig(ctx, subArgs) {
         }
     }
     if (sub === "set") {
-        const key = subArgs[1];
-        const rawVal = subArgs[2];
-        if (!key || rawVal === undefined) {
-            ctx.writeErr("Error: key and value required");
-            return ExitCode.INVALID_ARGUMENT;
-        }
-        let parsed = rawVal;
+        let parsed;
+        let value;
         try {
-            parsed = JSON.parse(rawVal);
+            parsed = parseSetInput(subArgs, false);
+            assertConcreteConfigKey(parsed.key);
+            value = await resolveValueInput({
+                ...parsed.input,
+                flatArgs,
+                signal,
+                stdin,
+                policy: { sanitizeInputErrors: true },
+            });
+            signal?.throwIfAborted();
         }
-        catch {
-            parsed = rawVal;
+        catch (err) {
+            return ctx.emitError(subArgs.includes("--json"), err?.code || "INVALID_ARGUMENT", err?.message || String(err), ExitCode.INVALID_ARGUMENT, {
+                details: err?.details,
+            });
         }
-        await ctx.service.management.config.set(ctx.options.packageId, key, parsed);
-        ctx.writeOut(`Config '${key}' updated`);
+        await ctx.service.management.config.set(ctx.options.packageId, parsed.key, value);
+        ctx.writeOut(`Config '${parsed.key}' updated`);
         return ExitCode.SUCCESS;
     }
     if (sub === "delete") {
@@ -349,7 +419,7 @@ function decodeStateKeyArg(key) {
         return { namespace: "", key };
     }
 }
-export async function handleState(ctx, subArgs) {
+export async function handleState(ctx, subArgs, flatArgs, signal, stdin) {
     const sub = subArgs[0] || "list";
     let namespace;
     let isAll = false;
@@ -405,36 +475,32 @@ export async function handleState(ctx, subArgs) {
         return ExitCode.SUCCESS;
     }
     if (sub === "set") {
-        const key = subArgs[1];
-        const rawVal = subArgs[2];
-        if (!key || rawVal === undefined) {
-            ctx.writeErr("Error: key and value required");
-            return ExitCode.INVALID_ARGUMENT;
-        }
-        let ns = namespace || "";
-        let actualKey = key;
-        if (namespace === undefined) {
-            const decoded = decodeStateKeyArg(key);
-            ns = decoded.namespace;
-            actualKey = decoded.key;
-        }
-        let parsed = rawVal;
+        let parsed;
+        let value;
         try {
-            parsed = JSON.parse(rawVal);
+            parsed = parseSetInput(subArgs, true);
+            value = await resolveValueInput({
+                ...parsed.input,
+                flatArgs,
+                signal,
+                stdin,
+                policy: { sanitizeInputErrors: true },
+            });
+            signal?.throwIfAborted();
         }
-        catch {
-            parsed = rawVal;
+        catch (err) {
+            return ctx.emitError(isJson, err?.code || "INVALID_ARGUMENT", err?.message || String(err), ExitCode.INVALID_ARGUMENT, {
+                details: err?.details,
+            });
         }
-        let ttl;
-        for (let i = 3; i < subArgs.length; i++) {
-            if (subArgs[i] === "--ttl" && i + 1 < subArgs.length) {
-                ttl = parseInt(subArgs[++i], 10);
-            }
-            else if (subArgs[i].startsWith("--ttl=")) {
-                ttl = parseInt(subArgs[i].slice(6), 10);
-            }
+        let ns = parsed.namespace || "";
+        let actualKey = parsed.key;
+        if (parsed.namespace === undefined) {
+            const decoded = decodeStateKeyArg(parsed.key);
+            ns = decoded.namespace;
+            actualKey = decoded.key;
         }
-        await ctx.service.management.state.set(ctx.options.packageId, "", actualKey, parsed, { namespace: ns, ttl });
+        await ctx.service.management.state.set(ctx.options.packageId, "", actualKey, value, { namespace: ns, ttl: parsed.ttl });
         const displayKey = ns ? `${ns}:${actualKey}` : actualKey;
         ctx.writeOut(`State '${displayKey}' updated`);
         return ExitCode.SUCCESS;

package/dist/runtime/standalone-help.d.ts

@@ -1,3 +1,4 @@
+export { parseConfigOverrideAssignment } from "../input/config-override.js";
 export interface ParsedArgs {
     controlArgs: string[];
     actionArgs: string[];

package/dist/runtime/standalone-help.js

@@ -1,3 +1,5 @@
+import { parseConfigOverrideAssignment } from "../input/config-override.js";
+export { parseConfigOverrideAssignment } from "../input/config-override.js";
 export function parseStandaloneArgs(argv) {
     const separator = argv.indexOf("--");
     const controlArgs = separator >= 0 ? argv.slice(0, separator) : argv;
@@ -13,17 +15,15 @@ export function parseStandaloneArgs(argv) {
         else if (arg.startsWith("--data-dir=")) {
             dataDir = arg.slice(11);
         }
-        else if (arg === "--config" && i + 1 < controlArgs.length) {
-            const pair = controlArgs[++i];
-            const [k, ...v] = pair.split("=");
-            if (k)
-                configOverrides[k] = v.join("=");
+        else if (arg === "--config" || arg === "-c") {
+            const pair = controlArgs[++i] ?? "";
+            const { key, value } = parseConfigOverrideAssignment(pair);
+            Object.defineProperty(configOverrides, key, { value, enumerable: true, writable: true, configurable: true });
         }
         else if (arg.startsWith("--config=")) {
             const pair = arg.slice(9);
-            const [k, ...v] = pair.split("=");
-            if (k)
-                configOverrides[k] = v.join("=");
+            const { key, value } = parseConfigOverrideAssignment(pair);
+            Object.defineProperty(configOverrides, key, { value, enumerable: true, writable: true, configurable: true });
         }
         else {
             filteredArgs.push(arg);
@@ -45,10 +45,16 @@ export function printHelp(writeOut, options) {
     writeOut("  <cmd> run <id> [--stdin-field <field>] [-- <assignments...>]");
     writeOut("                                             Bind raw stdin text to an input field");
     writeOut("  <cmd> config list/get/set/delete            Manage package configuration");
+    writeOut("  <cmd> config set <key> [<value> | --stdin]");
+    writeOut("  <cmd> config set <key> [--stdin-field <field>] [-- <assignments...>]");
     writeOut("  <cmd> state list/get/set/delete             Manage shared state store");
+    writeOut("  <cmd> state set <key> [<value> | --stdin] [-n <namespace>] [--ttl <seconds>]");
+    writeOut("  <cmd> state set <key> [--stdin-field <field>] [-n <namespace>] [--ttl <seconds>] [-- <assignments...>]");
+    writeOut("                                             set 整键替换；完整值、--stdin 与结构化输入互斥");
+    writeOut("                                             扁平赋值：field=text 或 field:=json；--stdin-field 保留原始正文");
     writeOut("\nGlobal options:");
     writeOut("  --data-dir <path>                           Custom runtime database directory");
-    writeOut("  --config <KEY=val>                          Temporary config override");
+    writeOut("  --config <KEY=val|KEY:=json>                Temporary config override");
 }
 export function emitError(writeOut, writeErr, isJson, code, message, exitCode, options) {
     if (isJson) {

package/dist/runtime/standalone.js

@@ -149,10 +149,10 @@ export class StandaloneDispatcher {
                     code = await handleRun(ctx, subArgs, actionArgs, control?.signal);
                     break;
                 case "config":
-                    code = await handleConfig(ctx, subArgs);
+                    code = await handleConfig(ctx, subArgs, argv.includes("--") ? actionArgs : undefined, control?.signal);
                     break;
                 case "state":
-                    code = await handleState(ctx, subArgs);
+                    code = await handleState(ctx, subArgs, argv.includes("--") ? actionArgs : undefined, control?.signal);
                     break;
                 default:
                     this.writeErr(`Unknown command: '${command}'`);

package/dist/security/config-cipher.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 配置加密密钥材料。
+ *
+ * key 为 32 字节 AES-256 原始密钥；id 为密钥的稳定非敏感指纹
+ * （由 configKeyId 计算），随密文信封持久化，用于存储域密钥身份校验。
+ */
+export interface ConfigEncryptionKey {
+    /** 32 字节 AES-256 原始密钥材料 */
+    key: Uint8Array;
+    /** 密钥的 SHA-256 十六进制指纹（非敏感，可持久化） */
+    id: string;
+}
+/**
+ * 配置加密密钥提供器。
+ *
+ * create 为 true 时允许在缺失时生成并持久化本地密钥与身份标记；
+ * 为 false 时绝不生成任何密钥或标记，缺失即抛出 CONFIG_ENCRYPTION_ERROR。
+ * 同一提供器实例在首次成功加载后缓存材料，后续调用不再读取环境或文件。
+ */
+export type ConfigKeyProvider = (create: boolean) => ConfigEncryptionKey;
+/**
+ * 计算加密密钥的稳定非敏感指纹。
+ *
+ * 输出为密钥字节 SHA-256 摘要的 64 位小写十六进制字符串（256 位熵的指纹），
+ * 可安全持久化与打印，不会泄露密钥材料本身。
+ */
+export declare function configKeyId(key: Uint8Array): string;
+/**
+ * 判定存储值是否为加密信封。
+ *
+ * 识别任何 adenc: 前缀（含未知版本），调用方必须将命中值交给
+ * decryptConfigValue 严格解密；未知版本会在解密时明确报错，绝不降级为明文。
+ */
+export declare function isEncryptedConfigValue(raw: string): boolean;
+/**
+ * 加密单个配置值并返回规范密文信封。
+ *
+ * 信封格式：adenc:v1:<keyId>:<base64url(iv|ciphertext|authTag)>。
+ * 使用 AES-256-GCM 与随机 12 字节初始向量，认证数据无歧义绑定
+ * 格式版本、密钥指纹、配置域 scope 与配置键 key。
+ * 值必须严格 canonical JSON 可序列化（复用 validateJsonValue 单一事实源），
+ * 任何不可精确往返的输入都会抛出 CONFIG_ENCRYPTION_ERROR，错误信息与
+ * details 不包含值本身、校验器 reason/path 或密钥材料。
+ */
+export declare function encryptConfigValue(value: unknown, scope: string, key: string, material: ConfigEncryptionKey): string;
+/**
+ * 严格解密 encryptConfigValue 产生的密文信封并返回原始值。
+ *
+ * 拒绝一切不规范输入：未知版本、非规范指纹、非规范或非未填充的
+ * base64url、负载截断、密钥身份不符、认证校验失败与非法 JSON 负载，
+ * 全部抛出 CONFIG_DECRYPT_FAILED，绝不将密文降级当作明文返回。
+ * 错误信息不包含明文片段、密文负载或密钥材料。
+ */
+export declare function decryptConfigValue(ciphertext: string, scope: string, key: string, material: ConfigEncryptionKey): unknown;

package/dist/security/config-cipher.js

@@ -0,0 +1,190 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ActionDockError, CONFIG_DECRYPT_FAILED, CONFIG_ENCRYPTION_ERROR } from "../errors.js";
+import { parseJsonWithoutDuplicates } from "../project/digest.js";
+import { validateJsonValue } from "../value-validator.js";
+/** 密文信封统一前缀，任何以该前缀起始的存储值都按密文处理 */
+const ENVELOPE_PREFIX = "adenc:";
+/** 当前支持的密文格式版本 */
+const CURRENT_VERSION = "v1";
+/** AES-256-GCM 密钥字节长度 */
+const KEY_BYTES = 32;
+/** AES-GCM 随机初始向量字节长度 */
+const IV_BYTES = 12;
+/** AES-GCM 认证标签字节长度 */
+const AUTH_TAG_BYTES = 16;
+/** 密钥指纹的规范形式：64 位十六进制字符（SHA-256 摘要） */
+const KEY_ID_PATTERN = /^[0-9a-f]{64}$/;
+/** 密文信封整体规范形式：版本段、指纹段与未填充 base64url 负载段 */
+const ENVELOPE_PATTERN = /^adenc:(v[0-9]+):([0-9a-f]{64}):([A-Za-z0-9_-]+)$/;
+/** 未填充 base64url 字符集（RFC 4648 第 5 节） */
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** 序列化递归深度上限，与 canonical JSON 校验单一事实源的最大深度保持一致 */
+const MAX_SERIALIZE_DEPTH = 512;
+/**
+ * 计算加密密钥的稳定非敏感指纹。
+ *
+ * 输出为密钥字节 SHA-256 摘要的 64 位小写十六进制字符串（256 位熵的指纹），
+ * 可安全持久化与打印，不会泄露密钥材料本身。
+ */
+export function configKeyId(key) {
+    if (!(key instanceof Uint8Array) || key.byteLength === 0) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Cannot compute config key id: key material must be a non-empty Uint8Array");
+    }
+    return createHash("sha256").update(key).digest("hex");
+}
+/**
+ * 判定存储值是否为加密信封。
+ *
+ * 识别任何 adenc: 前缀（含未知版本），调用方必须将命中值交给
+ * decryptConfigValue 严格解密；未知版本会在解密时明确报错，绝不降级为明文。
+ */
+export function isEncryptedConfigValue(raw) {
+    return typeof raw === "string" && raw.startsWith(ENVELOPE_PREFIX);
+}
+/**
+ * 构造 AES-GCM 附加认证数据。
+ *
+ * 以 JSON 数组序列化无歧义绑定格式版本、密钥指纹、配置域与配置键，
+ * 防止 scope 或 key 含分隔符时的拼接歧义，阻止跨域跨键的密文挪用。
+ */
+function buildAdditionalAuthenticatedData(version, id, scope, key) {
+    return Buffer.from(JSON.stringify([`${ENVELOPE_PREFIX}${version}`, id, scope, key]), "utf8");
+}
+/**
+ * 校验并规范化密钥材料。
+ *
+ * 要求 key 恰为 32 字节，id 为规范指纹且与 key 实际指纹一致，
+ * 身份不符时立即拒绝，防止用错误身份写出无法解密的密文。
+ */
+function normalizeMaterial(material) {
+    if (material === null || typeof material !== "object") {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Invalid config encryption material: expected ConfigEncryptionKey object");
+    }
+    const { key, id } = material;
+    if (!(key instanceof Uint8Array) || key.byteLength !== KEY_BYTES) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Invalid config encryption key: expected ${KEY_BYTES} bytes, got ${key instanceof Uint8Array ? key.byteLength : typeof key}`);
+    }
+    if (typeof id !== "string" || !KEY_ID_PATTERN.test(id)) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Invalid config encryption key id: expected 64 lowercase hex characters");
+    }
+    if (configKeyId(key) !== id) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Config encryption key id does not match key material fingerprint");
+    }
+    return { keyBytes: Buffer.from(key.buffer, key.byteOffset, key.byteLength), id };
+}
+/**
+ * 校验配置域与配置键参数。
+ */
+function assertBindingFields(scope, key) {
+    if (typeof scope !== "string" || scope.length === 0) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Config encryption scope must be a non-empty string");
+    }
+    if (typeof key !== "string" || key.length === 0) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, "Config encryption key name must be a non-empty string");
+    }
+}
+/**
+ * 严格校验并序列化配置值。
+ *
+ * 复用 validateJsonValue 作为 canonical JSON 规则的单一事实源：拒绝
+ * undefined、函数、符号、BigInt、非有限数值、访问器属性（仅检查描述符，
+ * 绝不执行 getter）、非枚举属性、Symbol 键、稀疏数组、非 plain 对象
+ * （Date、Map 等）、循环引用与超深嵌套，保证密文解密后能够精确还原。
+ * 校验失败只携带固定文案与机器可读的校验错误码，不携带 validator 的
+ * reason/path（两者可能嵌入用户对象抛出的异常内容），杜绝秘密外带。
+ */
+function serializeConfigValue(value, scope, key) {
+    const validation = validateJsonValue(value, { maxDepth: MAX_SERIALIZE_DEPTH });
+    if (!validation.valid) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config value for key '${key}' in scope '${scope}' is not strictly JSON serializable`, { scope, key, code: validation.code });
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config value for key '${key}' in scope '${scope}' is not strictly JSON serializable`, { scope, key });
+    }
+}
+/**
+ * 加密单个配置值并返回规范密文信封。
+ *
+ * 信封格式：adenc:v1:<keyId>:<base64url(iv|ciphertext|authTag)>。
+ * 使用 AES-256-GCM 与随机 12 字节初始向量，认证数据无歧义绑定
+ * 格式版本、密钥指纹、配置域 scope 与配置键 key。
+ * 值必须严格 canonical JSON 可序列化（复用 validateJsonValue 单一事实源），
+ * 任何不可精确往返的输入都会抛出 CONFIG_ENCRYPTION_ERROR，错误信息与
+ * details 不包含值本身、校验器 reason/path 或密钥材料。
+ */
+export function encryptConfigValue(value, scope, key, material) {
+    assertBindingFields(scope, key);
+    const { keyBytes, id } = normalizeMaterial(material);
+    const plaintext = serializeConfigValue(value, scope, key);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", keyBytes, iv, { authTagLength: AUTH_TAG_BYTES });
+    cipher.setAAD(buildAdditionalAuthenticatedData(CURRENT_VERSION, id, scope, key));
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const payload = Buffer.concat([iv, ciphertext, authTag]).toString("base64url");
+    return `${ENVELOPE_PREFIX}${CURRENT_VERSION}:${id}:${payload}`;
+}
+/**
+ * 严格解密 encryptConfigValue 产生的密文信封并返回原始值。
+ *
+ * 拒绝一切不规范输入：未知版本、非规范指纹、非规范或非未填充的
+ * base64url、负载截断、密钥身份不符、认证校验失败与非法 JSON 负载，
+ * 全部抛出 CONFIG_DECRYPT_FAILED，绝不将密文降级当作明文返回。
+ * 错误信息不包含明文片段、密文负载或密钥材料。
+ */
+export function decryptConfigValue(ciphertext, scope, key, material) {
+    assertBindingFields(scope, key);
+    const { keyBytes, id } = normalizeMaterial(material);
+    if (typeof ciphertext !== "string" || !ciphertext.startsWith(ENVELOPE_PREFIX)) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Stored config value for key '${key}' in scope '${scope}' is not an encrypted envelope`, { scope, key });
+    }
+    const match = ciphertext.match(ENVELOPE_PATTERN);
+    if (!match) {
+        const rest = ciphertext.slice(ENVELOPE_PREFIX.length);
+        const colon = rest.indexOf(":");
+        const version = colon === -1 ? rest : rest.slice(0, colon);
+        if (/^v[0-9]+$/.test(version) && version !== CURRENT_VERSION) {
+            throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope version '${version}' is not supported (expected '${CURRENT_VERSION}')`, { scope, key, version });
+        }
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope for key '${key}' in scope '${scope}' is malformed`, { scope, key });
+    }
+    const [, version, envelopeId, payload] = match;
+    if (version !== CURRENT_VERSION) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope version '${version}' is not supported (expected '${CURRENT_VERSION}')`, { scope, key, version });
+    }
+    if (envelopeId !== id) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope for key '${key}' in scope '${scope}' was written with a different key identity`, { scope, key, envelopeKeyId: envelopeId });
+    }
+    if (!BASE64URL_PATTERN.test(payload)) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope payload for key '${key}' in scope '${scope}' is not canonical base64url`, { scope, key });
+    }
+    const raw = Buffer.from(payload, "base64url");
+    if (raw.byteLength < IV_BYTES + AUTH_TAG_BYTES + 1) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope payload for key '${key}' in scope '${scope}' is truncated`, { scope, key });
+    }
+    if (raw.toString("base64url") !== payload) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Encrypted config envelope payload for key '${key}' in scope '${scope}' is not canonical base64url`, { scope, key });
+    }
+    const iv = raw.subarray(0, IV_BYTES);
+    const authTag = raw.subarray(raw.byteLength - AUTH_TAG_BYTES);
+    const encrypted = raw.subarray(IV_BYTES, raw.byteLength - AUTH_TAG_BYTES);
+    let plaintext;
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", keyBytes, iv, { authTagLength: AUTH_TAG_BYTES });
+        decipher.setAAD(buildAdditionalAuthenticatedData(version, envelopeId, scope, key));
+        decipher.setAuthTag(authTag);
+        plaintext = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    }
+    catch {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decryption of config value for key '${key}' in scope '${scope}' failed authentication`, { scope, key });
+    }
+    try {
+        return parseJsonWithoutDuplicates(plaintext.toString("utf8"));
+    }
+    catch {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decrypted config payload for key '${key}' in scope '${scope}' is not valid JSON`, { scope, key });
+    }
+}

package/dist/security/config-key.d.ts

@@ -0,0 +1,35 @@
+import { type ConfigKeyProvider } from "./config-cipher.js";
+/**
+ * 配置加密密钥提供器构造选项。
+ */
+export interface ConfigKeyProviderOptions {
+    /** 覆盖用户主目录定位（与 getActionDockHome 的 customHome 语义一致） */
+    customHome?: string;
+    /** 数据目录定位：密钥落盘为 <dataDir>/keys/config.key，优先于主目录定位 */
+    dataDir?: string;
+    /** 显式注入密钥材料：纯内存使用，不读取环境变量，也不访问或创建任何真实目录 */
+    key?: Uint8Array;
+    /** 环境变量快照来源（缺省读取 process.env），至少须支持 ACTIONDOCK_ENCRYPTION_KEY */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * 创建配置加密密钥提供器。
+ *
+ * 来源优先级：
+ * - 显式注入 key：纯内存材料，绝不读取环境变量或真实用户目录，也无需钉住持久身份；
+ * - 环境变量 ACTIONDOCK_ENCRYPTION_KEY：必须为恰好 64 位十六进制字符，
+ *   只要被设置（含空串或空白）就必须严格合法，非法取值立即报错，
+ *   绝不静默回退到本地密钥；
+ * - 本地密钥文件：dataDir 有值时为 <dataDir>/keys/config.key，
+ *   否则为 getActionDockHome(customHome)/.actiondock/keys/config.key。
+ *
+ * 构造时不发生任何环境读取、文件访问或目录创建；全部定位与加载在
+ * 首次调用时完成并缓存，此后同一提供器实例不再感知环境变化（宿主快照）。
+ * 若首次调用以 create 为 false 加载了未钉住身份的材料，后续 create 为 true
+ * 的调用会先原子创建或校验身份标记再返回缓存材料，保证允许写入前
+ * 持久域身份一定已经落盘。
+ *
+ * 身份保护：标记存在而密钥材料丢失时直接报错，绝不为同一存储域重新
+ * 生成新密钥；提供密钥与标记指纹不符时同样拒绝。
+ */
+export declare function createConfigKeyProvider(options?: ConfigKeyProviderOptions): ConfigKeyProvider;