qinglong/docs/adr/ADR-0188-cluster-durable-publisher-trust-authority-and-approved-revocation.md

ADR-0188：Cluster 持久发布者 Trust Authority 与受批撤销

• 状态：Accepted
• 日期：2026-07-28
• 关联：RFC D-140、D-144、D-175、D-176、D-177、D-178； ADR-0141、ADR-0144、ADR-0145、ADR-0185、ADR-0186、ADR-0187

背景

ADR-0187 已能根据可信 receipt 生成 signer impact 并隔离能力，但 receipt producer 仍是 直接调用的短生命周期函数。若管理请求可以自报 previousTrustDigest、 currentTrustDigest 或 generation，就能把客户端声明误当成集群事实；若 management 持有 package-executor credential，又会让网络入口直接取得隔离与安装写权限。

另一方面，部署既可能是资源有限的单节点，也可能是多副本控制面。协议必须允许小批量、 少连接、无常驻 timer 的执行方式，同时在多副本下对信任代际、提案、审批消费和执行租约 提供数据库事实与精确重放。

决策

1. Project Policy 是撤销 ceremony 的全局管理权威

集群显式配置一个 trust-authority Project。发布者 key 撤销固定要求 package.manage；审批使用既有 approval.decide：

• dual_control 创建 separation_of_duty 审批，请求人和确认人必须是不同 User；
• break_glass 创建 human_confirmation 审批，提案与确认均要求 hardware assurance；
• 提案、决定、消费三个阶段分别重验 Project/RoleBinding fence；
• 管理 assertion keyset 只认证操作者，不能替代 OCI publisher trust。

2. control-core v38 保存信任快照、head 与提案

pg-0039-plugin-package-publisher-trust-authority 新增：

• plugin_package_publisher_trust_snapshots：只保存 publisher/key ID/public-key digest/ lifetime，不保存 PEM；
• plugin_package_publisher_trust_heads：每个 authority 保存 generation、base/effective snapshot digest 和 head digest；
• plugin_package_publisher_revocation_proposals：不可变绑定 Project、Policy fence、 assurance、generation、目标 key、前后 digest 与 action/preview digest。

只读 trust 文件用于观察 base snapshot。首次观察以 INSERT ... ON CONFLICT DO NOTHING 竞选 head；相同 base 精确重放，不同 base 失败关闭。 文件变化不能隐式推进 effective trust。

客户端只提交 publisher、key ID、ceremony 和 reason。previous/current digest 与 generation 必须从 durable head/effective snapshot 派生，transport 响应只返回低敏摘要。

3. manager 只提案，executor 才消费和执行

package-manager credential 只能观察 base、创建 proposal/approval、决定与检查，不得更新 trust head、创建 revocation receipt 或执行 quarantine。

package-executor credential 以 caller-driven bounded process：

1. 扫描最多 64 个已批准 publisher revocation；
2. 以当前 package.manage fence 再授权并原子 consume；
3. 创建/领取既有 Approved Action execution；
4. handler 重新绑定 durable proposal、dispatch 与 execution start time；
5. D-177 的 SERIALIZABLE 事务同时推进 trust generation、写 receipt/impact；
6. 有界物化 quarantine，未收敛返回 indeterminate，保留可恢复事实。

management 永远不接触 executor credential；executor 不开放 HTTP listener。

4. 并发与最小权限

proposal 和 revocation 对 canonical (publisher,keyId) 使用相同 domain-separated PostgreSQL advisory transaction lock。不可变 proposal/dispatch 使用普通一致性读取； 只有可变 trust head 由 executor FOR UPDATE。这避免为了行锁向 manager 或 executor 扩大无业务意义的 UPDATE 权限。

revocation receipt 的 mutationId 必须是 approved dispatch ID。旧的直接 receipt producer 不再能通过 repository authority 验证。相同 receipt 精确重放；旧 generation 或并发 winner 导致冲突。

5. 部署与资源梯度

• 低资源设备可由外部 cadence 调用一次性 executor CLI，默认 2 个连接、8 条审批/派发、 4 批、每页 16 个 quarantine target，全部可下调；
• Cluster 提供 opt-in、concurrencyPolicy: Forbid 的两分钟 CronJob，request 50m/64Mi、limit 500m/256Mi，无 Service、无 ingress、无 Kubernetes token；
• management 以只读 ConfigMap 挂载 publisher trust；
• CloudNativePG overlay 只注入各自的 manager/executor role、CA 和 writer endpoint；
• 两个操作均不进入默认 operations Kustomization。

包边界

本切片不新增 workspace package或第三方生产依赖：

• runtime-core 保存纯 trust/proposal contract；
• cluster-postgres 保存 v38 migration、ACL、readiness 与 repository；
• cluster-admin 保存 management transport、approval consumer、handler、executor process/CLI。

workspace 仍为 22 包。单独拆出 trust、proposal 或 executor package 不形成新的制品或第三方 依赖边界，只会增加低配设备的安装、lockfile 和供应链审计成本。

不采用方案

允许客户端提交 trust digest/generation

客户端无法证明它观察的是当前 authority head，会制造 stale 或伪造 trust transition。

给 package-manager UPDATE 权限以支持行锁

PostgreSQL 的 FOR SHARE/FOR UPDATE 会隐式要求 UPDATE。manager 不应因此取得推进 head 的 能力；唯一键竞选和 signer advisory lock可以在不扩权的情况下提供并发序列化。

management 同步执行撤销

网络入口会同时持有 manager/executor 两类 credential，长时间 quarantine 还会占用 HTTP 请求和数据库连接。

常驻高频 controller

路由设备不应为低频 key ceremony 维持额外常驻进程。caller-driven CLI/CronJob 与 durable queue 已能在失败和切主后恢复。

验收证据

• runtime trust/proposal、PostgreSQL repository、management transport/process、 Approved Action handler/executor process 单元门通过；
• cluster dependency audit 与 Kubernetes base/CloudNativePG Kustomize 渲染通过；
• deployment audit 精确验证只读 trust、manager/executor credential 隔离、CronJob 资源/网络/Token 边界；
• PostgreSQL 18.4 Debian arm64 physical HA：
  • 真库先发现并修复两处 mock 未暴露的 FOR SHARE 隐式 UPDATE 权限扩大；
  • proposal 经 owner + admin 双人审批，executor consume 并成功执行；
  • trust generation 1→2，proposal/receipt/impact 各 1，trust snapshot 共 2；
  • Run/Tool guard true→false，2 个 Task withdrawal、retained source 0；
  • quarantine COMMIT response loss exact-once；
  • remote_apply、timeline 1→2 promotion、旧主 fence、pg_rewind 与同步只读重加入后 上述事实持续；
  • 最终 gates.passed=true。

后续

1. 增加 executor backlog、blocked/indeterminate、trust generation 与 quarantine remaining 的指标和告警。
2. 为 publisher key overlap rotation/retirement 增加与撤销不同的受批 action。
3. 完成真实管理客户端/UI 与硬件 assurance issuer 的部署证据。
4. 将两个 signer lock 实现抽成共享 helper 前必须单独审计 CRITICAL blast radius。