@actiondock/core 2.19.0 → 2.21.0

package/dist/storage/sqlite.d.ts

@@ -1,5 +1,6 @@
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, type Logger, type RuntimeError, type RunRecord } from "@actiondock/sdk";
-import { type IdempotencyCheckResult, type IdempotencyRecord, type RunsQueryFilterOptions, type RunsRetentionPolicy, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
+import { type ConfigSnapshot, type ConfigWriteOptions, type IdempotencyCheckResult, type IdempotencyRecord, type RunsQueryFilterOptions, type RunsRetentionPolicy, type RuntimeStorage, type StateEntry, type StorageOptions, type TerminalRunStatus } from "./types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
 export interface SqliteStorageOptions extends StorageOptions {
     logger?: Logger;
@@ -13,6 +14,8 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     private dbPath;
     private recoverOrphans;
     private retentionPolicy?;
+    private configKeyProvider?;
+    private configDeclarations?;
     private runsStore;
     private stateStore;
     private configStore;
@@ -27,8 +30,10 @@ export declare class SqliteRuntimeStorage implements RuntimeStorage {
     }): number;
     getConfig<T = unknown>(key: string): T | undefined;
     listConfig(): Record<string, unknown>;
-    setConfig(key: string, value: unknown): void;
+    setConfig(key: string, value: unknown, options?: ConfigWriteOptions): void;
     deleteConfig(key: string): boolean;
+    getConfigSnapshot(key: string): ConfigSnapshot | undefined;
+    getConfigProtection(key: string): readonly ConfigItemDefinition[] | undefined;
     getState<T = unknown>(namespace: string, key: string): Promise<T | undefined>;
     findState<T = unknown>(targetKey: string, namespace?: string): Promise<StateEntry | undefined>;
     setState<T = unknown>(namespace: string, key: string, value: T, ttl?: number): Promise<void>;

package/dist/storage/sqlite.js

@@ -1,14 +1,32 @@
 import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, } from "@actiondock/sdk";
 import { SystemClock } from "./clock.js";
 import { NodeSqliteDriver } from "./sqlite-driver.js";
-import { initSchema } from "./sqlite-schema.js";
+import { ensureStorageSchema } from "./migrations/index.js";
 import { SqliteRunsStore } from "./sqlite-runs.js";
 import { SqliteStateStore } from "./sqlite-state.js";
 import { SqliteConfigStore } from "./sqlite-config.js";
 import { SqliteEventsStore } from "./sqlite-events.js";
+import { createConfigKeyProvider } from "../security/config-key.js";
 export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, };
+/**
+ * 内存库默认密钥提供器：一次性随机内存密钥。
+ *
+ * 通过 createConfigKeyProvider({ key }) 注入纯内存材料，懒加载缓存，
+ * 绝不读取环境变量，也绝不访问或创建任何密钥文件；同一存储实例
+ * 生命周期内密钥恒定，进程退出即失效。
+ */
+function createMemoryConfigKeyProvider() {
+    return createConfigKeyProvider({ key: randomBytes(32) });
+}
+/** 解析存储级密钥提供器：显式注入优先，否则按库类型选择默认。 */
+function resolveConfigKeyProvider(dbPath, injected) {
+    if (injected)
+        return injected;
+    return dbPath === ":memory:" ? createMemoryConfigKeyProvider() : createConfigKeyProvider();
+}
 export class SqliteRuntimeStorage {
     driver;
     packageId;
@@ -18,6 +36,8 @@ export class SqliteRuntimeStorage {
     dbPath;
     recoverOrphans;
     retentionPolicy;
+    configKeyProvider;
+    configDeclarations;
     runsStore;
     stateStore;
     configStore;
@@ -44,6 +64,8 @@ export class SqliteRuntimeStorage {
         this.dbPath = dbPath;
         this.recoverOrphans = options.recoverOrphans === true;
         this.retentionPolicy = options.retentionPolicy;
+        this.configKeyProvider = options.configKeyProvider;
+        this.configDeclarations = options.configDeclarations;
         if (dbPath !== ":memory:") {
             const dir = dirname(dbPath);
             if (!existsSync(dir)) {
@@ -57,23 +79,46 @@ export class SqliteRuntimeStorage {
             }
         }
         this.driver = options.driver ?? new NodeSqliteDriver(dbPath);
-        if (dbPath !== ":memory:" && existsSync(dbPath)) {
-            try {
-                chmodSync(dbPath, 0o600);
-            }
-            catch {
-                // 忽略文件权限设置异常
+        try {
+            this.init();
+        }
+        catch (err) {
+            // 构造失败回收自建连接，避免数据库文件锁泄漏：注入的 driver 归调用方管理，
+            // 自建的 driver 生命周期归本实例，初始化失败时必须立即关闭
+            if (options.driver === undefined) {
+                try {
+                    this.driver.close();
+                }
+                catch {
+                    // 回收失败不得掩盖导致构造失败的原始异常
+                }
             }
+            throw err;
         }
-        this.init();
     }
     init() {
-        // 延迟初始化子存储以便它们可以访问 driver 等，但把初始化本身移到了 schema
-        this.configStore = new SqliteConfigStore(this.driver, this.packageId, this.dbPath, this.clock);
+        const keyProvider = resolveConfigKeyProvider(this.dbPath, this.configKeyProvider);
+        // 版本就绪：新库建当前版本、旧库迁移、当前库校验。
+        // 迁移先于任何正常子存储构造（当前版本实现始终假定库已是当前版本），
+        // 也先于运行记录恢复（恢复依赖子存储）。
+        ensureStorageSchema({
+            driver: this.driver,
+            dbPath: this.dbPath,
+            packageId: this.packageId,
+            declarations: this.configDeclarations ?? [],
+            keyProvider,
+            clock: this.clock,
+        });
+        // 构造正常子存储
+        this.configStore = new SqliteConfigStore(this.driver, this.packageId, this.dbPath, this.clock, keyProvider);
         this.stateStore = new SqliteStateStore(this.driver, this.packageId, this.dbPath, this.clock, this.logger, (msg) => this.logWarn(msg));
         this.runsStore = new SqliteRunsStore(this.driver, this.packageId, this.dbPath, this.clock, this.retentionPolicy, (k) => this.getConfig(k), this.logger, (msg) => this.logWarn(msg));
         this.eventsStore = new SqliteEventsStore(this.driver, this.packageId, this.clock);
-        initSchema(this.driver, this.dbPath, this.recoverOrphans, () => this.recoverDeadSessionRuns(), () => this.cleanExpiredRuns());
+        // 数据目录持有者语义下的遗留运行收割（与迁移无关，依赖子存储就绪）
+        if (this.recoverOrphans) {
+            this.recoverDeadSessionRuns();
+            this.cleanExpiredRuns();
+        }
         if (this.dbPath !== ":memory:" && existsSync(this.dbPath)) {
             try {
                 chmodSync(this.dbPath, 0o600);
@@ -93,12 +138,18 @@ export class SqliteRuntimeStorage {
     listConfig() {
         return this.configStore.listConfig();
     }
-    setConfig(key, value) {
-        this.configStore.setConfig(key, value);
+    setConfig(key, value, options) {
+        this.configStore.setConfig(key, value, options);
     }
     deleteConfig(key) {
         return this.configStore.deleteConfig(key);
     }
+    getConfigSnapshot(key) {
+        return this.configStore.getConfigSnapshot(key);
+    }
+    getConfigProtection(key) {
+        return this.configStore.getConfigProtection(key);
+    }
     // --- State 状态管理 ---
     async getState(namespace, key) {
         return this.stateStore.getState(namespace, key);

package/dist/storage/types.d.ts

@@ -1,9 +1,16 @@
 import type { RuntimeError, RunRecord, RunStatus } from "@actiondock/sdk";
+import type { ConfigItemDefinition } from "../project/types.js";
+import type { ConfigKeyProvider } from "../security/config-cipher.js";
 import type { Clock } from "./clock.js";
 /**
- * 固定的存储 Schema 目标版本常量。
+ * 固定的存储 Schema 当前版本常量。
+ *
+ * 当前版本（3）数据库总是携带 config_encryption 密钥元数据表（无敏感
+ * 写入时表保持空置），config 表允许普通 JSON 明文行与 adenc: 密文行
+ * 共存。旧版本数据库在存储打开前由 migrations/ 通用版本调度完成升级，
+ * 当前版本读写代码不感知历史版本。
  */
-export declare const STORAGE_SCHEMA_VERSION = 2;
+export declare const STORAGE_SCHEMA_VERSION = 3;
 /**
  * 幂等去重记录保留窗口（24 小时），与 ActionDockService.info()
  * 中的 idempotencyPolicy.retentionMs 保持单一事实源。
@@ -78,6 +85,14 @@ export interface SqliteStatement {
     get<T>(...params: any[]): T | undefined;
     all<T>(...params: any[]): T[];
 }
+/**
+ * 事务开启模式。
+ *
+ * deferred 为历史默认；读后写升级场景（如先读旧行再决定加密写入）
+ * 必须使用 immediate，在事务开始即取得写锁，避免并发提交下的
+ * 快照升级 SQLITE_BUSY；exclusive 供离线维护取得持续排他锁。
+ */
+export type SqliteTransactionMode = "deferred" | "immediate" | "exclusive";
 /**
  * 统一 SQLite 驱动层接口（严格同步契约）。
  *
@@ -90,7 +105,7 @@ export interface SqliteStatement {
 export interface SqliteDriver {
     exec(sql: string): void;
     prepare(sql: string): SqliteStatement;
-    transaction<T>(fn: () => T extends PromiseLike<unknown> ? never : T): T;
+    transaction<T>(fn: () => T extends PromiseLike<unknown> ? never : T, mode?: SqliteTransactionMode): T;
     close(): void;
 }
 /**
@@ -125,6 +140,29 @@ export interface StateEntry {
     /** 自动过期时间戳（ISO 8601 格式，null/undefined 表示不过期） */
     expiresAt?: string;
 }
+/**
+ * 配置写入选项。
+ *
+ * declarations 为写入时目标键的有效声明集合（跨包并集），存储层据此
+ * 判定敏感性、执行整键加密并合并历史保护声明；缺省视为无敏感声明。
+ */
+export interface ConfigWriteOptions {
+    /** 写入时目标键的有效配置声明集合 */
+    declarations?: readonly ConfigItemDefinition[];
+}
+/**
+ * 单键配置原子读取快照。
+ *
+ * 单次 SELECT 同时解出业务值与历史保护声明，避免管理视图分两次读取
+ * 时因其他进程恰好删除行而出现「旧秘密值 + 空保护」的组合泄漏。
+ * 明文行的快照仅含 value；密文行同时携带解密验证后的保护声明。
+ */
+export interface ConfigSnapshot {
+    /** 业务配置值（密文行经透明解密还原） */
+    value: unknown;
+    /** 历史保护声明（仅密文行存在；用于当前声明弱化后的脱敏兜底） */
+    protection?: readonly ConfigItemDefinition[];
+}
 /**
  * 初始化存储引擎所需的选项。
  */
@@ -147,6 +185,21 @@ export interface StorageOptions {
     recoverOrphans?: boolean;
     /** 运行记录保留策略配置 */
     retentionPolicy?: RunsRetentionPolicy;
+    /**
+     * 配置加密密钥提供器。
+     *
+     * 缺省时文件库懒使用本地默认密钥定位（createConfigKeyProvider），
+     * 内存库使用一次性随机内存密钥（不读取环境变量或密钥文件）。
+     */
+    configKeyProvider?: ConfigKeyProvider;
+    /**
+     * 打开存储时用于版本迁移判定的配置声明字典集合。
+     *
+     * 包级存储传当前包声明；全局存储传所有已加载包的声明字典（跨包并集
+     * 判定敏感性）。声明解析遵循各字典内具体键优先于模板、跨字典取并集。
+     * 仅在旧版本数据库需要迁移时被读取；版本迁移只在首次打开执行。
+     */
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }
 /**
  * 数据库中存储的幂等请求去重记录实体。
@@ -202,8 +255,23 @@ export interface RuntimeStorage {
     readonly closed?: boolean;
     getConfig<T = unknown>(key: string): T | undefined;
     listConfig(): Record<string, unknown>;
-    setConfig(key: string, value: unknown): void | Promise<void>;
+    setConfig(key: string, value: unknown, options?: ConfigWriteOptions): void | Promise<void>;
     deleteConfig(key: string): boolean | Promise<boolean>;
+    /**
+     * 单次读取同时解出业务值与历史保护声明的原子快照。
+     *
+     * 键不存在返回 undefined；明文行仅含 value；密文行经严格解密验证后
+     * 同时携带 protection。管理视图优先使用本方法，避免分离读取的
+     * 并发窗口泄漏无保护的秘密值。
+     */
+    getConfigSnapshot?(key: string): ConfigSnapshot | undefined;
+    /**
+     * 读取目标键的历史保护声明（密文行解密验证后返回；明文行或不存在返回 undefined）。
+     *
+     * 用于当前声明弱化（如移除 secret 标记）后的脱敏兜底，防止已加密的
+     * 历史敏感值在管理视图重新明文展示。
+     */
+    getConfigProtection?(key: string): readonly ConfigItemDefinition[] | undefined;
     getState<T = unknown>(namespace: string, key: string): Promise<T | undefined>;
     findState<T = unknown>(targetKey: string, namespace?: string): Promise<StateEntry | undefined>;
     setState<T = unknown>(namespace: string, key: string, value: T, ttl?: number): Promise<void>;

package/dist/storage/types.js

@@ -1,8 +1,13 @@
 import { ACTION_CANCELLED, ACTION_TIMEOUT } from "../errors.js";
 /**
- * 固定的存储 Schema 目标版本常量。
+ * 固定的存储 Schema 当前版本常量。
+ *
+ * 当前版本（3）数据库总是携带 config_encryption 密钥元数据表（无敏感
+ * 写入时表保持空置），config 表允许普通 JSON 明文行与 adenc: 密文行
+ * 共存。旧版本数据库在存储打开前由 migrations/ 通用版本调度完成升级，
+ * 当前版本读写代码不感知历史版本。
  */
-export const STORAGE_SCHEMA_VERSION = 2;
+export const STORAGE_SCHEMA_VERSION = 3;
 /**
  * 幂等去重记录保留窗口（24 小时），与 ActionDockService.info()
  * 中的 idempotencyPolicy.retentionMs 保持单一事实源。

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export declare const ACTIONDOCK_VERSION = "2.19.0";
+export declare const ACTIONDOCK_VERSION = "2.21.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export const ACTIONDOCK_VERSION = "2.19.0";
+export const ACTIONDOCK_VERSION = "2.21.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,7 +59,7 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/sdk": "^2.19.0",
+    "@actiondock/sdk": "^2.21.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "undici": "^7.29.1"