qinglong/docs/adr/ADR-0025-encrypted-local-secret-store.md

ADR-0025：加密本地 SecretStore 与版本化密文

• 状态：Superseded
• 日期：2026-07-18
• 关联：QL-RFC-0001、ADR-0007、ADR-0022、ADR-0024
• 被取代：ADR-0073 将实现从 legacy back/runtime/Sequelize 迁入全新 QL3 package graph；本 ADR 的 SecretRef、envelope 和威胁模型仍作为历史决策保留

上下文

ADR-0024 已规定 Task revision/context recipe 只能保存 Secret 引用，明文只能在 Attempt 物化时短暂进入可信内存。但只有 provider port 不能满足 edge/standalone 部署：路由设备通常没有 KMS、Vault 或常驻 sidecar，仍需要低资源、断电可恢复的本地实现。另一方面，直接复用 Legacy Envs、把主密钥写进 database.sqlite，或允许 cluster Worker 读取控制面数据库，都会破坏 Project 隔离、备份边界和多副本语义。

本地实现需要同时处理随机密文的幂等写入、并发轮换、历史版本引用、密钥轮换、SQLite 损坏和错误信息泄漏。加密静态存储只能缩小磁盘/备份泄漏面，不能防御已控制 QingLong 进程、root、调试器、heap dump 或实际 Executor 环境的攻击者。

决策

1. SecretRef 是 opaque Project capability

内置本地 provider 使用 canonical qlsecret:v1:<base64url-json>：payload 只允许 projectId、name 和可选的正整数 version。省略版本解析当前版本，显式版本精确解析历史密文；未知字段、非 canonical base64url/JSON、超长值或非法版本 fail closed。

Task revision/context recipe 继续只保存完整 opaque ref，不解析或保存 Secret 明文。通用 SecretRef.version 仍是 provider contract；内置 v1 codec 将其收敛为单调递增整数。执行时 provider 必须在访问仓储或密钥前证明 ref 的 projectId 与 Run candidate 相同。

2. SQLite 只保存 append-only envelope

0014-local-secret-envelopes 新增 LocalSecretEnvelopes，复合主键为 (project_id, secret_name, version)，并为 (project_id, secret_name, mutation_id) 建立唯一索引。每个版本保存：

• key_id 与固定算法 aes-256-gcm；
• 96-bit 随机 nonce、ciphertext、128-bit authentication tag；
• mutation identity 和创建时间。

明文、主密钥、解密缓存、API actor token 和 Run identity 不进入该表。AES-GCM AAD 绑定 Project、Secret name、version、mutationId、keyId 和 algorithm，因此复制密文到另一个 Project/name/version 或篡改 metadata 都无法通过认证。

SQLite repository 只支持 append、按 mutation 查询和最多 64 项的有界批量解析；没有 update plaintext/delete current 接口。current 解析在单条查询中选择最大版本，显式版本精确匹配并保持输入位置。

3. CAS 与 mutation 分别解决轮换和请求重放

写命令同时携带：

• expectedCurrentVersion：创建为 0，轮换 N→N+1 时必须为 N；SQLite IMMEDIATE 事务串行检查并写入，过期 writer 得到稳定 version conflict；
• mutationId：同一 Project/name 下标识一次调用。AES-GCM 每次生成随机 nonce，所以 repository 不能用密文字节判断幂等；并发 winner 的 envelope 返回应用层后，必须使用对应历史 key 解密并与本次 plaintext 比较。版本和明文都相同才是 existing，否则是 mutation conflict。

错误对象只携带稳定错误码和通用摘要，不包含 Project、Secret name、ref、plaintext、ciphertext 或 key ID。

4. 主密钥与数据库分离

edge key provider 从独立 JSON keyring 文件按需加载：

{
  "version": 1,
  "activeKeyId": "edge-key-2026-07",
  "keys": {
    "edge-key-2026-07": "<canonical-base64url-32-bytes>"
  }
}

文件必须是绝对路径下的普通文件，拒绝 symlink，禁止 group/other 任意权限位，大小上限 16 KiB、密钥最多 16 个，每个 key 恰好 32 bytes。provider 每次调用重新读取，因此原子替换 keyring 后新写入可使用新的 active key；历史 key 必须保留到其所有 envelope 超过恢复/备份保留窗口。消费者获得独立 key copy，并在使用后尽力清零 Buffer。

keyring 不进入 database.sqlite、普通配置导出或 Artifact。备份必须把数据库与 keyring 当作两个独立敏感对象，并验证能够配对恢复。

5. 明文只在 Attempt 解析窗口存在

EncryptedLocalSecretService 同时提供版本写入服务和 LocalSecretEnvironmentProvider：

• 一次最多解析 64 个去重 ref，保持位置对齐；任一 ref 跨 Project、密文损坏、key 缺失或 authentication 失败均 fail closed；
• missing envelope 返回 unavailable plan，不用空字符串代替；
• 同批次相同 keyId 只加载一个 key copy，结束时统一清零；
• plaintext Buffer 在 UTF-8 解码后立即尽力清零，不写入 revision、recipe、RunEvent、Artifact metadata 或异常消息。

JavaScript string、Executor 环境和子进程内存无法可靠擦除。因此禁止在诊断对象、结构化日志、Trace、heap dump 上传和错误 cause 中附带解析结果；日志脱敏仍是附加防线，不是存储边界。

6. edge 与 cluster 复用端口，不复用密钥实现

• edge/standalone：SQLite envelope repository + 私有文件 keyring，零常驻 sidecar、无轮询 timer；
• cluster-control：PostgreSQL envelope/metadata repository + KMS/Vault/云 Secret Manager adapter，必须实现相同 Project、exact/current、batch、CAS 和错误 contract；
• worker：只接收授权后、Attempt-scoped 的临时值或 capability，不读取控制面的 SQLite/keyring。

共享挂载 keyring 或 database.sqlite 不是 cluster SecretStore。外部 Secret Manager 的 provider-specific version 可以在其 adapter 内映射，不能放宽内置 qlsecret:v1 codec。

7. 当前保持 production unreachable

本 ADR 的 migration、crypto、repository、keyring provider 和 environment provider 已实现，但没有接入默认 bootstrap、API/UI、Task 管理或 Dispatcher lifecycle。启用前还必须完成：

• 首次安装的 CSPRNG key 生成、原子写入和权限校验；
• keyring 独立备份/恢复演练、丢失告警和灾难恢复文档；
• active key 轮换管理入口、历史 key 使用审计、全量 rekey/退役证明；
• secret.manage/secret.use 权限、actor 审计和不回显 API；
• ADR-0026 quota/retention 的受控 lifecycle、日志脱敏、heap dump 策略和真实 edge 磁盘耗尽测试；
• PostgreSQL/KMS contract suite 与多副本并发验证。

因此 migration 被注册不等于 SecretStore 已对生产调用可达，Legacy Envs 也不会自动迁移为 3.0 Secret。

影响

正面影响：

• 数据库、WAL 和常规数据库备份中没有 Secret 明文或主密钥；
• edge 无需额外进程即可获得 authenticated encryption、历史版本和并发安全轮换；
• key provider/repository 可独立替换，cluster 不需要在领域服务中增加 Profile 分支；
• 随机 nonce 与请求幂等不再冲突，损坏和错误路径默认不泄漏身份或内容。

代价与风险：

• 数据库和 keyring 任一丢失都会导致不可恢复，备份复杂度高于单文件 SQLite；
• 只切换 active key 不会重加密历史数据，删除历史 key 前必须有可验证的 rekey/保留证明；
• AES-GCM nonce 安全依赖 CSPRNG，测试注入的固定 nonce 绝不能进入生产装配；
• 进程内 plaintext string 无法可靠擦除，运行时与日志治理仍是强制门禁。

未选择的方案

1. 复用 Legacy Envs 明文表：权限、版本和备份边界不足，拒绝。
2. 把主密钥放进同一 SQLite：数据库泄漏即可解密，拒绝。
3. 用 Secret name 作为环境全局键：跨 Project 混淆且不可复现，拒绝。
4. 覆盖当前值而不保留版本：历史 Run/重试不可解释，拒绝。
5. 比较随机密文判断 mutation 幂等：相同 plaintext 的 nonce 不同，语义错误，拒绝。
6. 允许 keyring 宽权限或 symlink：扩大本地用户读取和路径替换攻击面，拒绝。
7. 将固定测试 key/nonce 作为默认值：破坏机密性，拒绝。
8. cluster 共享本地 keyring/SQLite：没有多副本一致性、KMS 审计和节点隔离，拒绝。

验证要求

• canonical SecretRef current/exact vectors，拒绝未知字段、非 canonical 编码和非法版本；
• AES-256-GCM 固定 vector，metadata/AAD 篡改、错误 key/tag 均 fail closed；
• 创建/轮换 CAS、mutation replay/conflict、双连接并发轮换恰好一个 winner；
• current/exact/missing 有界批量解析保持位置，跨 Project 在 repository 前拒绝；
• 原始 SQLite row 只有密文 BLOB，不出现测试 plaintext；
• keyring mode、symlink、大小、schema、key 长度、active key reload 测试；
• 所有 corruption/unavailable 错误不包含 Secret identity 或 plaintext；
• SQLite adapter 拒绝 cluster dialect，默认生产启动链保持不可达；
• Node 22、Node 24 全量回归通过。