@actiondock/core 2.20.0 → 2.21.0

package/dist/runtime/context.d.ts

@@ -1,5 +1,6 @@
 import type { ActionContext, ActionInvokeOptions, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
 import type { ProjectConfig } from "../project/types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
 import type { RuntimeStorage } from "../storage/types.js";
 import { ProcessManager, type ProcessOwner } from "../process/index.js";
 import type { ConfigSource } from "../service/types.js";
@@ -22,11 +23,15 @@ export declare class RuntimeConfig implements Config {
     get<T = unknown>(key: string): T | undefined;
     get<T = unknown>(key: string, defaultValue: T): T;
     has(key: string): boolean;
+    /**
+     * 含历史保护声明的配置解析结果视图。
+     */
+    describeWithProtection<T = unknown>(key: string): ConfigResolutionWithProtection<T>;
     /**
      * 结构化解析指定配置项的来源与取值视图。
      *
-     * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
-     * 避免重复实现解析链导致行为漂移。
+     * 委托 describeWithProtection 五层优先级链单一事实源，剥出既有公开契约视图，
+     * 避免双实现漂移；历史保护声明仅由管理视图消费。
      * source 仅表达实际生效值来源；undefined 统一视为未命中并继续向低优先级解析，
      * null/false/0/空串均为真实值；整链未命中时 source 为 null。
      */
@@ -35,6 +40,20 @@ export declare class RuntimeConfig implements Config {
         value: T | undefined;
     };
 }
+/**
+ * 含历史保护声明的配置解析结果视图。
+ */
+export interface ConfigResolutionWithProtection<T = unknown> {
+    /** 实际生效值来源；整链未命中为 null */
+    source: ConfigSource | null;
+    /** 实际生效值 */
+    value: T | undefined;
+    /**
+     * 值来源存储持久化的历史保护声明（仅 package/global 来源可能存在）。
+     * 与值取自同一次原子读取，避免并发删除造成值与规则错配。
+     */
+    protection?: readonly ConfigItemDefinition[];
+}
 /**
  * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
  *

package/dist/runtime/context.js

@@ -1,8 +1,9 @@
 import { assertConcreteConfigKey, assertValidConfigDeclarations, resolveConfigDeclaration, validateConfigValue } from "../project/config-declarations.js";
+import { readConfigWithProtection } from "../storage/index.js";
 import { MemoryProcessDriver, ProcessManager } from "../process/index.js";
 import { createDefaultProcessOwner } from "../invocation/types.js";
 import { resolveEnvValue } from "./env.js";
-import { ActionDockError, INVALID_ACTION_REF, INVALID_ARGUMENT, INVALID_STATE } from "../errors.js";
+import { ActionDockError, isConfigEncryptionError, INVALID_ACTION_REF, INVALID_ARGUMENT, INVALID_STATE, } from "../errors.js";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
@@ -41,14 +42,9 @@ export class RuntimeConfig {
         return !(resolved.source === null && resolved.value === undefined);
     }
     /**
-     * 结构化解析指定配置项的来源与取值视图。
-     *
-     * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
-     * 避免重复实现解析链导致行为漂移。
-     * source 仅表达实际生效值来源；undefined 统一视为未命中并继续向低优先级解析，
-     * null/false/0/空串均为真实值；整链未命中时 source 为 null。
+     * 含历史保护声明的配置解析结果视图。
      */
-    describe(key) {
+    describeWithProtection(key) {
         assertConcreteConfigKey(key);
         // 1. 运行时固定覆盖与单次调用覆盖（值为 undefined 视为未命中，继续解析链）
         if (this.overrides.has(key)) {
@@ -57,25 +53,42 @@ export class RuntimeConfig {
                 return { source: "override", value: overrideValue };
             }
         }
-        // 2. 包级持久化存储
-        const stored = this.storage.getConfig(key);
-        if (stored !== undefined) {
-            return { source: "package", value: stored };
+        // 2. 包级持久化存储：原子快照配对读取值与历史保护声明；
+        //    加密错误直接透传，绝不降级继续解析链（旧版库已在打开时自动迁移）
+        const resolvedDecl = resolveConfigDeclaration(this.projectConfig?.config, key);
+        const packageSnapshot = readConfigWithProtection(this.storage, key);
+        if (packageSnapshot !== undefined) {
+            return {
+                source: "package",
+                value: packageSnapshot.value,
+                ...(packageSnapshot.protection !== undefined
+                    ? { protection: packageSnapshot.protection }
+                    : {}),
+            };
         }
-        // 3. 全局持久化存储（读取异常时降级继续解析链，但记录警告确保不静默吞没）
+        // 3. 全局持久化存储（一般读取异常降级继续解析链并告警；
+        //    加密错误严禁回退，必须原样透传）
         if (this.globalStorage) {
             try {
-                const globalStored = this.globalStorage.getConfig(key);
-                if (globalStored !== undefined) {
-                    return { source: "global", value: globalStored };
+                const globalSnapshot = readConfigWithProtection(this.globalStorage, key);
+                if (globalSnapshot !== undefined) {
+                    return {
+                        source: "global",
+                        value: globalSnapshot.value,
+                        ...(globalSnapshot.protection !== undefined
+                            ? { protection: globalSnapshot.protection }
+                            : {}),
+                    };
                 }
             }
             catch (err) {
+                if (isConfigEncryptionError(err)) {
+                    throw err;
+                }
                 console.warn(`[actiondock] global config read failed for ${key}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         // 4. 环境变量
-        const resolvedDecl = resolveConfigDeclaration(this.projectConfig?.config, key);
         const itemDef = resolvedDecl?.item;
         const envResolved = resolveEnvValue(key, itemDef, this.projectConfig?.id);
         if (envResolved !== undefined) {
@@ -87,6 +100,18 @@ export class RuntimeConfig {
         }
         return { source: null, value: undefined };
     }
+    /**
+     * 结构化解析指定配置项的来源与取值视图。
+     *
+     * 委托 describeWithProtection 五层优先级链单一事实源，剥出既有公开契约视图，
+     * 避免双实现漂移；历史保护声明仅由管理视图消费。
+     * source 仅表达实际生效值来源；undefined 统一视为未命中并继续向低优先级解析，
+     * null/false/0/空串均为真实值；整链未命中时 source 为 null。
+     */
+    describe(key) {
+        const resolved = this.describeWithProtection(key);
+        return { source: resolved.source, value: resolved.value };
+    }
 }
 /**
  * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。

package/dist/runtime/run-persistence.d.ts

@@ -63,7 +63,7 @@ export interface RunFinalizer {
     /** 竞态监听句柄注销函数列表（finalize 时统一清理，覆盖成功路径） */
     raceListenerRemovers: Array<() => void>;
     /** 绑定取消控制器并启动超时定时器 */
-    startTimeout(controller: AbortController, timeoutMs: number): void;
+    startTimeout(controller: AbortController, timeoutMs: number, displayTimeoutMs?: number): void;
     /** 写入终态（幂等，自动清理超时定时器与全部监听句柄） */
     finalize(status: TerminalRunStatus, output?: unknown, error?: RuntimeError): void;
 }

package/dist/runtime/run-persistence.js

@@ -1,4 +1,4 @@
-import { ActionDockError, RUN_PERSISTENCE_FAILED, RUN_REPOSITORY_UNAVAILABLE } from "../errors.js";
+import { ActionDockError, ACTION_TIMEOUT, RUN_PERSISTENCE_FAILED, RUN_REPOSITORY_UNAVAILABLE } from "../errors.js";
 import { snapshotRunOrigin } from "./run-origin.js";
 /**
  * 构建运行初始记录（RunRecord 组装单一事实源）。
@@ -79,11 +79,12 @@ export function createRunFinalizer(storage, runId) {
         signal: undefined,
         onAbort: undefined,
         raceListenerRemovers: [],
-        startTimeout: (controller, timeoutMs) => {
+        startTimeout: (controller, timeoutMs, displayTimeoutMs) => {
             finalizer.controller = controller;
+            const display = displayTimeoutMs ?? timeoutMs;
             finalizer.timeoutTimer = setTimeout(() => {
                 finalizer.isTimeout = true;
-                finalizer.controller?.abort(new Error(`Action exceeded timeout of ${timeoutMs}ms`));
+                finalizer.controller?.abort(new ActionDockError(ACTION_TIMEOUT, `Action exceeded timeout of ${display}ms`, { timeoutMs: display }));
             }, timeoutMs);
         },
         finalize: (status, output, error) => {

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;