qinglong/docs/adr/ADR-0074-authorized-local-secret-administration-and-atomic-audit.md

# ADR-0074：授权的本机 Secret 管理与原子安全审计

- 状态：Proposed
- 日期：2026-07-20
- 关联 RFC：QL-RFC-0001 D-05、D-17、D-27、D-37、D-48、D-62、D-65、D-72、D-73
- 关联 ADR：ADR-0028、ADR-0029、ADR-0047、ADR-0049、ADR-0050、ADR-0063、ADR-0073

## 上下文

ADR-0073 已让全新本机 application 具备可达的加密 SecretStore，但只提供 envelope、keyring 和运行期解析能力。若直接把 plaintext 写入口放进常驻 application、数据库迁移 authority 或 legacy Controller，就会同时扩大 HTTP 漏洞、DDL 凭据和 Secret 明文的 blast radius；若只在 service 层先查权限、再单独写 envelope 和日志，RoleBinding 撤销及审计失败又会留下 TOCTOU 或“已写密文但没有授权事实”的崩溃窗口。

本机默认 Project 仍是 ownerless。迁移或首次启动自动授予 owner 虽然方便，却会绕过 D-27 的本机强认证 ceremony。目标用户还包括低性能路由设备，因此 Secret 管理不能增加常驻连接、timer、watcher、sidecar 或明文 cache。

## 决策

### 1. Secret 管理使用独立、短生命周期 authority

新增 `@qinglong/local-secret-admin`，生产只依赖 `@qinglong/local-secret` 与 `@qinglong/runtime-core`。它不得进入 `@qinglong/local-application`、edge/standalone application tarball 或任何常驻 Profile 组合根；依赖审计对所有其他 3.0 package 的反向导入 fail closed。

`local-admin` 继续只负责 SQLite migration/adoption，不能同时取得 Secret plaintext 管理 authority。数据库结构变更与业务密钥管理分离，避免一个运维入口同时拥有 DDL、keyring 和密文写入能力。

### 2. SQLite capability v5 提供最小 Policy 与审计事实

`0009-local-project-policy-audit` 新增：

- ownerless 的 `QingLong3Projects` 默认 Project；
- append-only、versioned 的 `QingLong3ProjectRoleBindings`；
- 低敏 `QingLong3SecurityAuditEvents`。

`0010-capability-v5` 声明 `local_project_policy`、`local_security_audit` 和 `local_secret_authorized_mutation`。migration、typed schema、manifest、readiness 与真实 catalog 必须 lockstep；默认 migration 不创建 owner，也不复用 legacy Sequelize 的 `0017/0018` bootstrap 表。

### 3. 认证和 Policy 必须先于 keyring/Secret 访问

管理请求只接受 exact-shape、UUIDv4 mutation/request identity、Project-bound Secret name、expected version、plaintext 和 `AuthenticatedPrincipal`。User 必须具备 `multi_factor`、`hardware` 或 `local_console` assurance；system/service 仍须是稳定 subject。弱认证先写 `authentication_rejected` 审计，且不得读取 keyring、查询 Secret 或执行密码学操作。

强认证主体经 `ProjectPolicyEngine` 检查 `secret.manage`。owner/admin 可允许，ownerless、operator/viewer、archived、损坏或依赖不可用均 fail closed。拒绝、需要审批和依赖不可用使用低敏审计，不记录 plaintext、密文、key material 或可还原值。

### 4. 最终授权、envelope 与 allowed audit 在一个事务裁决

service 层的 Policy 结果不是最终写权限。repository 在同一个 `BEGIN IMMEDIATE` transaction 中重新验证精确 Project version 与 RoleBinding subject/version/state/role fence，然后验证 Secret current version，最后同时追加 encrypted envelope 和 `allowed` 安全审计。

RoleBinding 在 Policy 判断后被撤销时，旧请求必须得到 `LocalSecretAuthorizationFenceConflictError`，不能写 envelope 或 allowed audit。audit insert 失败时整个 envelope mutation 回滚；不得以 best-effort 日志替代原子事实。实现复用唯一 `LocalSqliteRunRepository` 的 DatabaseSync、256 operation 队列和 close fence，不创建第二 SQLite authority。

### 5. 管理结果不回显明文

成功只返回 canonical SecretRef、version 和 `created|existing`。mutation replay 必须解密既有 envelope 后做 timing-safe 语义比较：同一 plaintext 返回 `existing`，不同 plaintext 作为 mutation identity collision 失败；任何响应、错误和审计都不返回输入 plaintext。

同一 mutation identity 一旦用于 authentication/policy 拒绝，不得随后被复用为 allowed mutation；调用方必须生成新的 mutation，以保留每次安全决策的唯一审计身份。

### 6. 首 owner 与产品入口继续保持不可达

当前 package 是可测试的领域/存储核心，不是可发布管理入口。首次 owner bootstrap 必须由后续本机控制台 ceremony 使用新的 Node 24 SQLite authority 原子建立，不能自动授予、复用默认密码或把 legacy session 直接当强认证。

CLI/HTTP/UI、独立速率限制、Secret 创建/轮换审批、keyring provision/rotation 编排、备份/rekey/retirement 和恢复流程完成前，默认部署不得暴露 Secret mutation。

## 被否决的替代方案

1. **把 Secret 写入口放入常驻 local-application**：扩大长期 plaintext 与远程攻击面，拒绝。
2. **把 Secret 管理并入 migration local-admin**：让 DDL authority 同时持有 keyring 和业务 mutation，拒绝。
3. **只在 service 层检查权限**：无法关闭撤权与写入之间的 TOCTOU，拒绝。
4. **先写 envelope、再 best-effort audit**：崩溃或审计故障会产生无授权事实的密文，拒绝。
5. **migration 自动建立默认 owner**：绕过首 owner 强认证 ceremony，拒绝。
6. **为管理请求增加专属连接、队列或 watcher**：给 edge 增加常驻成本并产生第二 SQLite authority，拒绝。

## 影响与未完成项

已完成：

- runtime-core 的本机 Secret 管理 repository/fence contract；
- Node 24 SQLite v5 migration/schema/readiness、ownerless Project、RoleBinding 与安全审计；
- 强 Principal、`secret.manage` Policy、拒绝先审计且 key-access-after-allow；
- Project/RoleBinding fence、Secret version、envelope 和 allowed audit 的单事务提交；
- 撤权竞态、审计回滚、语义 replay 与不回显测试；
- 二十二个 3.0 importer 的依赖/source/lock/advisory 注册，管理包不进入 application 产物。

仍未完成：

- Node 24 SQLite 首 owner bootstrap、可信 local-console issuer 与 production authentication wiring；
- 不回显 CLI/HTTP/UI、独立 rate limit、审批与 break-glass 流程；
- Project/RoleBinding 正式管理入口、审计 query/retention/export/alert；
- 数据库/keyring 配对备份、历史 envelope rekey、key retirement proof 和 crash-resume journal；
- `secret.use` 对 Task/Workflow/Agent 的完整 Policy/Approval 装配与已知值日志治理；
- PostgreSQL/KMS/Vault 管理 authority、Remote Worker 临时 Secret delivery 与多副本契约。

因此本 ADR 只关闭本机 Secret mutation 的授权、撤权竞态和原子审计断层；它不使 ownerless 默认部署获得管理能力，也不表示 QingLong 3.0 Secret 产品链已完成。

## 验证

1. owner 可以在一个事务中写 encrypted envelope 和 allowed audit，原始 row/响应均无 plaintext。
2. ownerless Project 被拒绝并审计，且 key provider 未被访问。
3. 弱认证被审计，Policy、Secret repository 与 key provider 均未被访问。
4. Policy 判断后撤销 RoleBinding 会触发 fence conflict，envelope/audit 均不写入。
5. 强制 audit insert 失败会回滚 envelope。
6. 同 mutation/same plaintext 返回 `existing`，不同 plaintext 冲突。
7. capability v5 的十条 migration、十四张 owned table、schema/readiness/manifest 与真实 catalog 一致。
8. application tarball 仍为十二个 package，且不包含 `@qinglong/local-secret-admin`。