feat(ql3): add owner-confirmed package secret binding

2026-09-21 01:32:44 +08:00 · 2026-08-13 11:28:06 +08:00
parent d72631a2b0
commit 8ba27dc148
21 changed files with 1503 additions and 40 deletions
@@ -28,6 +28,7 @@
 - D-304/ADR-0392（已接受）：Plugin Package 进入安全 quarantine 时，Workflow/Prompt automation publication 不再仅依赖运行时 start guard 间接拒绝，而是与 quarantine event、Package-owned Task disabled revisions、Project Tool snapshot 和 withdrawal receipt 在同一 SQLite/PostgreSQL 事务中收敛为 `withdrawn`。原先仅能引用普通 lifecycle event 的外键升级为 append-only disposition-event 联合引用，历史 migration 与 publication digest schema 保持不变；SQLite edge/standalone 崩溃矩阵覆盖 automation publication insert 后、event/task/receipt/COMMIT 前后，PostgreSQL 通过触发器在既有 `SECURITY DEFINER` quarantine commit 内登记 disposition，再由同一外层 SERIALIZABLE transaction CAS publication head。能力位为 `plugin_package_automation_security_withdrawal@1`；不新增 package、daemon、timer、连接或常驻缓存，适用于低配路由设备和集群节点。SQLite 全量 228/228；PostgreSQL package 311 pass/1 条外部 URL 条件 skip；完整 18-package build/test 退出 0，backend 1,188 pass/2 skip，package/dependency boundary 零 finding；PostgreSQL 18.4 arm64 HA 125 项 gate 全绿、timeline `1→2`，报告 SHA-256 为 `ab156901b9c96ec5a62259c44d83d24ded011e0616dc827d928f3e13efd11786`。
 - D-305/ADR-0393（已接受）：Plugin Package Manifest 的逻辑 Secret requirement 获得按 resource generation 固定的不可变 binding。binding 精确覆盖 Manifest requirements，只保存同 Project、显式 version 的 `qlsecret://` 引用与 `approved-action-execution|local-owner-confirmation` authority evidence digest，不保存 Secret 明文；required 不可为空，optional 可显式为 `null`。发布由当前 active installation head、lock、generation 与 Manifest digest 联合 fencing，相同事实幂等、不同事实冲突；domain-separated digest、最多 64 项和 64 KiB 单行预算同时约束 Local 与 Cluster。SQLite 追加 `0091` ledger 与 capability v46，PostgreSQL 追加 `pg-0059`、capability v58，并只向 package executor 授予 `SELECT, INSERT`。不新增 package、daemon、timer、watcher、连接、缓存或集群 workload，低配路由设备只承担一个有界表和三个索引。D-305 不冒充 Secret 已进入执行路径：现有 materialization 拒绝仍保留，D-306 再完成用户授权、Secret resolution、runtime consumption 与 lifecycle/rebinding 语义。core 509/509、SQLite 232/232、PostgreSQL 316 pass/1 条件 skip；完整 18-package clean build/test 退出 0，backend 1,188 pass/2 skip，五项边界审计零 finding，workspace 仍无 single-source/shallow-source package。PostgreSQL 18.4 arm64 HA 125 项 gate 全绿、timeline `1→2`，报告 SHA-256 为 `acf0fea7ca7699989dfe70f5dd0061cdf5fb1968c691094331fea06ce01b96dc`。
 - D-306A/ADR-0394（已接受）：Package Task source 以 `package-secret` placeholder 引用逻辑 requirement，materialization 只用当前 generation 的 D-305 binding 编译为已有、固定 version 的 Task `SecretRef`；Package source 直接携带 SecretRef、缺失 binding、未批准 `secret.use`、跨 binding 引用和 optional/required 漂移全部失败关闭。binding 快照不含明文并进入 materialized revision digest，Local/Cluster 启动发布复用既有 repository/pool，Task dispatch、Local 短时解密和 Cluster offer/lease-fenced delivery 不另造协议。SQLite/PostgreSQL INSERT trigger 同时防止直接写库绕过；Local 只读 readiness 继续不加载 DDL。Local contract v47、Cluster v59；不新增 package、表、索引、连接、daemon、watcher、timer、cache 或 workload。完整 18-package clean build/test 退出 0；backend 1,188 pass/2 条件 skip/0 fail；五项 package/dependency/edge/service-manager/local-image 审计零 finding，workspace 仍无 single-source/shallow-source package，两个有序 migration ledger 精确为 PostgreSQL 61、SQLite 95 个 source；PostgreSQL 18.4 arm64 HA 125 项 gate 全绿、timeline `1→2`，报告 SHA-256 为 `f9107e8e54892a788779758f0573ac8d6a80f6d086516a1f5f5bbacb59bbb4be`。D-306A 不冒充产品闭环：Local bind/rebind 命令、Cluster Approved Action/API 与新 generation rotation/revocation 编排属于 D-306B。
+- D-306B1/ADR-0395（进行中）：先完成当前 active、尚未绑定 Package generation 的首次 Secret binding，不允许原地 rebind。共享 content-free plan 由服务端从 installation/proposal/lock/Manifest/generation 重建，调用方不能注入 generation 或 digest。Local 已复用短生命周期 `ql3-package` 私有 command-file 和单 SQLite authority：强 `local-console` User 必须同时具备 `secret.manage` 与当前 Project Owner，human confirmation 后在一个 `BEGIN IMMEDIATE` transaction 内复验 Owner fence、Package provenance、精确 Secret version、content-free audit 与 immutable binding；plan 后撤权原子回滚，exact replay 收敛，不同 audit identity 或当前代重复绑定失败关闭。未新增 package、migration、表、索引、依赖、进程、连接、listener、timer、watcher 或 cache。针对包粒度复审确认 18 个 workspace package 不按 LOC 机械合并；D-306 contract/plan 与 SQLite repository/administration 分别收敛为 owning-domain 两文件目录，公开 subpath 不变、无 wrapper。Cluster separation-of-duty Approved Action、PostgreSQL durable plan/proposal 与 HA 证据仍未完成，所以 ADR 保持 Proposed；rebind/rotation/revocation 继续属于必须创建新 generation 的 D-306B2。
 - D-302/ADR-0390（已接受）
  Cluster operator context 增加无网络、无 mutation 的内建 `ql3-cluster-admin context validate` 预检。它先复用 owner-private context
  reader，再让每个 entry 经过与真实请求相同的 production HTTPS/Kubernetes configuration preparation，验证精确 route、hostname、CA、
@@ -0,0 +1,42 @@
+# ADR-0395：Owner 确认的 Plugin Package Secret 首次绑定
+
+- 状态：Proposed
+- 日期：2026-08-13
+- 关联 RFC：QL-RFC-0001 D-306B1
+- 关联 ADR：ADR-0364、ADR-0393、ADR-0394
+
+## 问题
+
+D-305 已提供按 Package generation 不可变的 Secret binding ledger，D-306A 已让 materialization 消费该 binding，但部署者仍缺少受支持的产品入口。直接开放 repository 会绕过 User、Project Policy、Owner confirmation、Secret version existence 与当前 generation fence；让既有 generation 原地改绑则会使同一 materialized revision 在不同时间指向不同 Secret。
+
+QingLong 3.0 同时面向低配路由设备和集群节点。本机产品入口不能引入常驻进程、第二条 SQLite 连接、watcher、timer 或 cache；Cluster 后续入口必须复用 separation-of-duty Approved Action，而不是复制 Local Owner authority。
+
+## 决策
+
+1. D-306B 拆成两个可独立验证的阶段：B1 只允许当前 active、尚未绑定 generation 的首次 binding；B2 才通过新 Package generation 完成 rebind、rotation 与 revocation。任何阶段都不得更新或删除历史 binding。
+2. B1 使用共享、content-free 的 `qinglong/plugin-package-secret-binding-plan@v1`。服务端从当前 installation、admission proposal、lock、Manifest 与 resource generation 重建目标和 canonical entries，调用方不能提交 generation、Manifest digest、lock digest 或 binding digest。
+3. Local 入口复用短生命周期 `ql3-package` 私有 command-file 链路。plan 与 execute 都要求强 `local-console` User、`secret.manage` 和当前 Project `owner`；execute 在 human confirmation 后进入既有单 SQLite operation authority，并在同一 `BEGIN IMMEDIATE` transaction 内重新验证 Owner fence、当前 generation、Package provenance、精确 Secret version existence、content-free audit 与 binding publish。
+4. plan 只包含 SecretRef 元数据，不包含 Secret 明文；响应只返回目标摘要、canonical entry、plan/binding digest 与 created/existing 状态。required requirement 不能为 `null`，optional requirement 可以显式为 `null`，所有非空引用必须同 Project且固定 version。
+5. plan 后撤销 Owner 必须使 execute 回滚且不留下 audit/binding。完全相同的 plan 与 audit identity 可以 exact replay；同一当前 generation 的第二次 bind/rebind、不同 audit identity 或任何 provenance drift 必须失败关闭，并提示通过新 generation 执行 B2。
+6. workspace package 继续按部署制品、authority、依赖隔离、adapter 与多消费者裁决，不按文件数合并。D-306 的 Runtime contract/plan 归入同包 `plugin-package/secret-binding/{binding,plan}`，SQLite repository/administration 归入同包 `plugin-package/secret-binding/{repository,administration}`；稳定公开 subpath 不变，不保留旧物理路径 wrapper，也不为单个 plan 新增微型 package。
+7. Local 实现不新增 package、migration、表、索引、依赖、进程、listener、连接、timer、watcher 或 cache。Cluster B1 仍须以 Approved Action、package-manager/package-executor 最小权限和 PostgreSQL HA 证据完成后，本 ADR 才能进入 Accepted。
+
+## 明确不在 B1 中完成
+
+- 不允许对已经绑定的 generation 原地 rebind、rotate 或 revoke。
+- 不读取、解密、输出或复制 Secret value。
+- 不让常驻 Local application、Cluster Control 或 Worker 获得管理 authority。
+- 不以 Local Owner confirmation 替代 Cluster separation-of-duty Approved Action。
+
+## 验证
+
+- Runtime contract：plan canonicalization、digest/shape drift、Local/Cluster authority 派生与稳定 package subpath。
+- Local 产品纵切面：真实 Package proposal/approval/activation，缺失 Secret version 拒绝，plan 后撤权原子回滚，恢复 Owner 后首次 publish、exact replay、重复 bind 与 audit identity drift 拒绝。
+- 完整 18-package clean build/test；需要本机 TLS listener 的 Worker 测试在允许回环监听的等价环境复跑。
+- package/dependency/edge/service-manager/local-image 审计与 GitNexus compare-to-`develop` 变更影响检查。
+
+## 当前证据
+
+- Runtime Core、Local SQLite、Local Owner CLI closure type-check 已通过；Local 产品定向纵切面 3/3。
+- 18-package clean build/test 中除受限沙箱禁止绑定 `127.0.0.1` 导致的 Worker TLS 三项外，其余已执行测试均为 0 fail；同一 Worker 完整包在允许回环监听的环境为 133/133。
+- Cluster Approved Action、PostgreSQL proposal/plan ledger、最小权限、真库与 physical HA 证据仍待 B1 后半段完成，因此本 ADR 保持 Proposed。
@@ -398,6 +398,7 @@
 | [ADR-0392](./ADR-0392-atomic-plugin-package-automation-security-withdrawal.md)                                | Plugin Package Automation 安全隔离原子撤回                                                                                           | Accepted |
 | [ADR-0393](./ADR-0393-generation-bound-plugin-package-secret-binding-ledger.md)                              | 按 Generation 固定的 Plugin Package Secret 绑定账本                                                                                  | Accepted |
 | [ADR-0394](./ADR-0394-generation-bound-plugin-package-secret-materialization.md)                             | 按 Generation 固定的 Plugin Package Secret Materialization                                                                           | Accepted |
+| [ADR-0395](./ADR-0395-owner-confirmed-plugin-package-secret-binding.md)                                      | Owner 确认的 Plugin Package Secret 首次绑定                                                                                           | Proposed |

 ## 规则