@actiondock/core 2.19.0 → 2.21.0

package/dist/storage/config-value.js

@@ -0,0 +1,102 @@
+import { ActionDockError, CONFIG_DECRYPT_FAILED } from "../errors.js";
+import { decryptConfigValue, encryptConfigValue, } from "../security/config-cipher.js";
+import { isSecretConfigKey } from "./mask.js";
+/**
+ * 对保护声明递归剥离脱敏无关信息。
+ *
+ * 仅保留结构（properties/additionalProperties/items）、类型与 secret
+ * 标记；严禁把 default、enum、env、description 等可能携带值的内容
+ * 写入保护元数据，即使信封整体已加密也保持最小化。
+ */
+function sanitizeProtectionSchema(schema) {
+    const copy = {};
+    if (schema.type !== undefined)
+        copy.type = schema.type;
+    if (schema.secret !== undefined)
+        copy.secret = schema.secret;
+    if (schema.properties) {
+        copy.properties = Object.fromEntries(Object.entries(schema.properties).map(([name, child]) => [
+            name,
+            sanitizeProtectionSchema(child),
+        ]));
+    }
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties === "object") {
+        copy.additionalProperties = sanitizeProtectionSchema(schema.additionalProperties);
+    }
+    if (schema.items !== undefined && typeof schema.items === "object") {
+        copy.items = sanitizeProtectionSchema(schema.items);
+    }
+    return copy;
+}
+/** 对单条保护声明剥离脱敏无关字段（保留 secret/type/schema 结构信息）。 */
+function sanitizeProtectionDeclaration(item) {
+    const copy = {};
+    if (item.secret !== undefined)
+        copy.secret = item.secret;
+    if (item.type !== undefined)
+        copy.type = item.type;
+    if (item.schema)
+        copy.schema = sanitizeProtectionSchema(item.schema);
+    return copy;
+}
+/**
+ * 合并历史保护声明与当前敏感声明，绝不弱化保护强度。
+ *
+ * - 以规范化 JSON 作为去重标识，防止重复写入导致保护数组无界增长；
+ * - 当前声明中仅并入判定敏感的条目（非敏感声明不产生历史保护义务）；
+ * - 合并结果为空时保守回退为整项敏感，保证密文行始终有脱敏依据。
+ */
+export function mergeProtectionDeclarations(stored, current, key) {
+    const merged = [];
+    const seen = new Set();
+    const push = (item) => {
+        const sanitized = sanitizeProtectionDeclaration(item);
+        const identity = JSON.stringify(sanitized);
+        if (!seen.has(identity)) {
+            seen.add(identity);
+            merged.push(sanitized);
+        }
+    };
+    for (const item of stored ?? []) {
+        push(item);
+    }
+    for (const item of current) {
+        if (isSecretConfigKey(key, item)) {
+            push(item);
+        }
+    }
+    if (merged.length === 0) {
+        merged.push({ secret: true });
+    }
+    return merged;
+}
+/** 加密业务值与保护声明构成的完整信封，返回规范密文信封字符串。 */
+export function encryptConfigEnvelope(value, protection, scope, key, material) {
+    const envelope = { value, protection: [...protection] };
+    return encryptConfigValue(envelope, scope, key, material);
+}
+/**
+ * 严格解密密文信封并校验负载形态。
+ *
+ * 信封负载必须为含 value 属性的对象；protection 省略或为声明对象数组。
+ * 任何不合规输入抛 CONFIG_DECRYPT_FAILED，绝不把密文降级当作明文返回。
+ */
+export function decryptConfigEnvelope(ciphertext, scope, key, material) {
+    const payload = decryptConfigValue(ciphertext, scope, key, material);
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload) ||
+        !Object.prototype.hasOwnProperty.call(payload, "value")) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decrypted config payload for key '${key}' in scope '${scope}' is not a valid protection envelope`, { scope, key });
+    }
+    const envelope = payload;
+    if (envelope.protection !== undefined &&
+        (!Array.isArray(envelope.protection) ||
+            envelope.protection.some((item) => item === null || typeof item !== "object"))) {
+        throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decrypted protection metadata for config key '${key}' in scope '${scope}' is malformed`, { scope, key });
+    }
+    return {
+        value: envelope.value,
+        protection: envelope.protection ?? [],
+    };
+}

package/dist/storage/file-lock.js

@@ -292,6 +292,10 @@ function* acquireLockMachine(lockPath, options, isAsync) {
                             isDir = s.isDirectory();
                         }
                         catch { }
+                        // 所有权仲裁：陈旧目录在守卫独占保护下不可能被他人新建，可直接接管；
+                        // 陈旧单文件被 unlink 后存在创建间隙，仅当本回收者亲自 mkdir 成功才可宣称所有权，
+                        // 否则主锁已被他人在守卫外真实创建，严禁覆盖现存元数据或删除赢家
+                        let mainLockClaimable = isDir;
                         if (!isDir) {
                             try {
                                 yield (d) => d.unlink(lockPath);
@@ -299,35 +303,45 @@ function* acquireLockMachine(lockPath, options, isAsync) {
                             catch { }
                             try {
                                 yield (d) => d.mkdir(lockPath, { mode: 0o700 });
+                                mainLockClaimable = true;
                             }
                             catch (err) {
                                 if (err.code !== "EEXIST")
                                     throw err;
                             }
+                            if (!mainLockClaimable && !isAsync) {
+                                // 同步语义：主锁已被他人真实创建，当轮快速失败，不得向调用方泄露原始 EEXIST
+                                if (options?.createLockError) {
+                                    throw options.createLockError(`Lock '${lockPath}' is currently held by another active process`);
+                                }
+                                throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently held by another active process`);
+                            }
                         }
-                        // 在接管守卫独占保护下写入并核验元数据，杜绝外部并发读取到残余陈旧元数据
-                        token = randomUUID();
-                        metadata = {
-                            pid: process.pid,
-                            createdAt: clock.now().toISOString(),
-                            ...options?.metadata,
-                            token,
-                        };
-                        const metaPath = join(lockPath, LOCK_METADATA_FILE);
-                        const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
-                        yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-                        yield (d) => d.rename(tmpPath, metaPath);
-                        const raw = yield (d) => d.readFile(metaPath, "utf-8");
-                        const verify = JSON.parse(raw);
-                        if (verify?.token !== token) {
-                            if (options?.createLockError) {
-                                throw options.createLockError(`Failed to verify acquired lock ownership in '${lockPath}'`);
+                        if (mainLockClaimable) {
+                            // 在接管守卫独占保护下写入并核验元数据，杜绝外部并发读取到残余陈旧元数据
+                            token = randomUUID();
+                            metadata = {
+                                pid: process.pid,
+                                createdAt: clock.now().toISOString(),
+                                ...options?.metadata,
+                                token,
+                            };
+                            const metaPath = join(lockPath, LOCK_METADATA_FILE);
+                            const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
+                            yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+                            yield (d) => d.rename(tmpPath, metaPath);
+                            const raw = yield (d) => d.readFile(metaPath, "utf-8");
+                            const verify = JSON.parse(raw);
+                            if (verify?.token !== token) {
+                                if (options?.createLockError) {
+                                    throw options.createLockError(`Failed to verify acquired lock ownership in '${lockPath}'`);
+                                }
+                                throw new ActionDockError(STORAGE_BUSY, `Failed to verify acquired lock ownership in '${lockPath}'`);
                             }
-                            throw new ActionDockError(STORAGE_BUSY, `Failed to verify acquired lock ownership in '${lockPath}'`);
+                            activeLockPaths.add(resolvedPath);
+                            acquired = true;
+                            reclaimMetadataWritten = true;
                         }
-                        activeLockPaths.add(resolvedPath);
-                        acquired = true;
-                        reclaimMetadataWritten = true;
                     }
                     finally {
                         try {

package/dist/storage/index.d.ts

@@ -1,4 +1,6 @@
-import type { RuntimeStorage } from "./types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
+import { type RedactResult } from "./mask.js";
+import type { ConfigSnapshot, RuntimeStorage } from "./types.js";
 export { DataDirLock, type DataDirLockInfo, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export { NodeSqliteDriver } from "./sqlite-driver.js";
@@ -34,7 +36,7 @@ export declare function resolveDatabasePath(packageId: string, options?: {
  * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
  *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans, configDeclarations）
  */
 export declare function createStorage(packageId: string, options?: {
     projectRoot?: string;
@@ -43,6 +45,7 @@ export declare function createStorage(packageId: string, options?: {
     customHome?: string;
     recoverOrphans?: boolean;
     retentionPolicy?: import("./types.js").RunsRetentionPolicy;
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }): RuntimeStorage;
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。
@@ -70,4 +73,23 @@ export declare function createGlobalStorage(customHomeOrOptions?: string | {
     customHome?: string;
     dataDir?: string;
     inMemory?: boolean;
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }, dataDirArg?: string): RuntimeStorage;
+/**
+ * 读取配置值与配套历史保护声明的原子快照。
+ *
+ * 优先使用存储的 getConfigSnapshot 单次 SELECT 配对读取值与保护规则，
+ * 消除先读值后读保护之间行被并发删除或改写造成的错配竞态；
+ * 存储未提供快照能力（如 MemoryStorage 或外部旧实现）时回退为
+ * 原值读取加可选保护读取的既有配对行为。
+ */
+export declare function readConfigWithProtection(storage: RuntimeStorage, key: string): ConfigSnapshot | undefined;
+/**
+ * 依据当前声明与历史保护声明合并脱敏管理视图配置值。
+ *
+ * 仅在存在历史保护声明（值曾按敏感声明加密写入）时使用：当前声明与历史
+ * 保护声明合并后取脱敏并集；合并后仍未产生任何脱敏结果时保守隐藏整项，
+ * 杜绝加密值因声明变更或跨宿主加载差异重新外泄明文。
+ * 无历史保护时由调用方沿用各自既有脱敏原语，保持行为不变。
+ */
+export declare function redactConfigValueWithProtection(value: unknown, items: readonly ConfigItemDefinition[], protection: readonly ConfigItemDefinition[] | undefined): RedactResult;

package/dist/storage/index.js

@@ -1,7 +1,9 @@
 import { join, relative, resolve } from "node:path";
 import { assertValidPackageId, getActionDockHome, isPathOutsideBoundary } from "../utils/index.js";
 import { ActionDockError, PATH_TRAVERSAL } from "../errors.js";
+import { createConfigKeyProvider } from "../security/config-key.js";
 import { SqliteRuntimeStorage } from "./sqlite.js";
+import { redactConfigValueForDeclarations } from "./mask.js";
 export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export { NodeSqliteDriver } from "./sqlite-driver.js";
@@ -56,7 +58,7 @@ export function resolveDatabasePath(packageId, options = {}) {
  * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
  *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans, configDeclarations）
  */
 export function createStorage(packageId, options = {}) {
     const dbPath = resolveDatabasePath(packageId, options);
@@ -65,6 +67,17 @@ export function createStorage(packageId, options = {}) {
         packageId,
         recoverOrphans: options.recoverOrphans,
         retentionPolicy: options.retentionPolicy,
+        ...(options.configDeclarations?.length ? { configDeclarations: options.configDeclarations } : {}),
+        // 持久化库统一注入懒加载密钥提供器：密钥与数据库共享同一有效 dataDir/customHome 域；
+        // 内存库不注入，由存储内部使用随机内存密钥，确保内存运行不触碰宿主密钥源
+        ...(dbPath !== ":memory:"
+            ? {
+                configKeyProvider: createConfigKeyProvider({
+                    customHome: options.customHome,
+                    dataDir: options.dataDir,
+                }),
+            }
+            : {}),
     });
 }
 /**
@@ -94,10 +107,12 @@ export function createGlobalStorage(customHomeOrOptions, dataDirArg) {
     let customHome;
     let dataDir;
     let inMemory = false;
+    let configDeclarations;
     if (typeof customHomeOrOptions === "object" && customHomeOrOptions !== null) {
         customHome = customHomeOrOptions.customHome;
         dataDir = customHomeOrOptions.dataDir;
         inMemory = Boolean(customHomeOrOptions.inMemory);
+        configDeclarations = customHomeOrOptions.configDeclarations;
     }
     else {
         customHome = customHomeOrOptions;
@@ -107,5 +122,53 @@ export function createGlobalStorage(customHomeOrOptions, dataDirArg) {
         return new SqliteRuntimeStorage({ dbPath: ":memory:", packageId: "__global__" });
     }
     const dbPath = resolveGlobalDatabasePath({ dataDir, customHome });
-    return new SqliteRuntimeStorage({ dbPath, packageId: "__global__" });
+    return new SqliteRuntimeStorage({
+        dbPath,
+        packageId: "__global__",
+        configKeyProvider: createConfigKeyProvider({ customHome, dataDir }),
+        ...(configDeclarations?.length ? { configDeclarations } : {}),
+    });
+}
+/**
+ * 读取配置值与配套历史保护声明的原子快照。
+ *
+ * 优先使用存储的 getConfigSnapshot 单次 SELECT 配对读取值与保护规则，
+ * 消除先读值后读保护之间行被并发删除或改写造成的错配竞态；
+ * 存储未提供快照能力（如 MemoryStorage 或外部旧实现）时回退为
+ * 原值读取加可选保护读取的既有配对行为。
+ */
+export function readConfigWithProtection(storage, key) {
+    if (typeof storage.getConfigSnapshot === "function") {
+        return storage.getConfigSnapshot(key);
+    }
+    const value = storage.getConfig(key);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof storage.getConfigProtection === "function") {
+        const protection = storage.getConfigProtection(key);
+        return protection !== undefined ? { value, protection } : { value };
+    }
+    return { value };
+}
+/**
+ * 依据当前声明与历史保护声明合并脱敏管理视图配置值。
+ *
+ * 仅在存在历史保护声明（值曾按敏感声明加密写入）时使用：当前声明与历史
+ * 保护声明合并后取脱敏并集；合并后仍未产生任何脱敏结果时保守隐藏整项，
+ * 杜绝加密值因声明变更或跨宿主加载差异重新外泄明文。
+ * 无历史保护时由调用方沿用各自既有脱敏原语，保持行为不变。
+ */
+export function redactConfigValueWithProtection(value, items, protection) {
+    if (protection === undefined) {
+        return redactConfigValueForDeclarations(value, [...items]);
+    }
+    const merged = [...items, ...protection];
+    const result = redactConfigValueForDeclarations(value, merged);
+    if (!result.secret) {
+        return value === undefined
+            ? { value: undefined, secret: true, redactedPaths: [] }
+            : { value: undefined, secret: true, redactedPaths: [""] };
+    }
+    return result;
 }

package/dist/storage/mask.d.ts

@@ -1,10 +1,8 @@
+import type { JsonValue } from "@actiondock/sdk";
 import type { ConfigItemDefinition } from "../project/types.js";
 /**
- * 检查指定配置项是否为敏感数据（密码、私钥、Token、密钥等）。
- *
- * 判定逻辑：
- * 严格依据配置项元数据属性判定：若声明了 `secret: true`，直接判定为敏感数据；否则不视为敏感数据。
- * 不进行基于正则或键名的自动探测，由开发者显式配置驱动。
+ * 检查指定配置项是否为敏感数据（顶层 secret: true 或模式中嵌套 secret: true）。
+ * 不进行基于正则或键名的自动探测，调用方若涉及模板应先解析具体声明项。
  *
  * @param _key 配置键名（保留入参以兼容契约）
  * @param declaredItem 项目中声明的配置元数据（可选）
@@ -17,9 +15,38 @@ export declare function isSecretConfigKey(_key?: string, declaredItem?: ConfigIt
  * @returns 掩码脱敏后的安全展示字符串
  */
 export declare function maskSecretValue(value: unknown): string;
+/**
+ * 配置值脱敏安全视图产物。
+ */
+export interface RedactResult {
+    /** 脱敏后的数据值（顶层敏感时为 undefined） */
+    value: JsonValue | undefined;
+    /** 是否包含敏感信息或发生了保守脱敏 */
+    secret: boolean;
+    /** 发生脱敏替换的字段路径集合（标准 JSON Pointer 格式） */
+    redactedPaths: string[];
+}
+/**
+ * 依据单项配置声明对配置值执行纯函数脱敏处理。
+ *
+ * @param value 待脱敏的配置原始数据值
+ * @param item 对应的单项配置定义元数据
+ */
+export declare function redactConfigValue(value: unknown, item?: ConfigItemDefinition): RedactResult;
+/** 根据可信隐藏路径应用幂等掩码，绝不把远端提供的路径本身当成已脱敏的证据。 */
+export declare function redactConfigValueAtPaths(value: unknown, paths: string[]): RedactResult;
+/**
+ * 依据跨包多重声明对配置值执行合并脱敏处理（取脱敏路径并集，祖先路径覆盖子路径）。
+ *
+ * @param value 待脱敏的配置原始数据值
+ * @param items 各相关包分别解析得到的配置声明集合
+ */
+export declare function redactConfigValueForDeclarations(value: unknown, items: ConfigItemDefinition[]): RedactResult;
 /**
  * 对配置定义字典进行脱敏处理：
- * 针对声明为 secret: true 的项，剥离其 default 默认值，不返回敏感默认值。
+ * - 针对外层 secret: true 或嵌套包含敏感字段的项，剥离其 default 默认值，避免敏感默认值泄露或误用于执行；
+ * - 针对模式中敏感节点的 enum 约束列表进行清洗，杜绝约束文本泄露秘密；
+ * - 仅返回安全副本，严禁修改清单原始数据。
  *
  * @param config 声明的配置定义字典
  */