# ADR-0189：Cluster Effective Publisher Trust Material Binding

- 状态：Accepted
- 日期：2026-07-28
- 关联：RFC D-175、D-177、D-178、D-179；
  ADR-0185、ADR-0187、ADR-0188

## 背景

ADR-0188 已将 Cluster publisher trust 的有效代际保存在 PostgreSQL，并明确挂载文件只用于
初始化 base snapshot。但 recovery 进程仍直接用挂载文件中的全部 PEM 构造
`PluginPackagePublisherTrustRegistry`。这会形成控制面与执行面的 authority 分裂：

- operator 为 overlap rotation 预先分发 old+new ConfigMap 时，new key 会在 Approved
  Action 推进 effective head 前被 recovery 信任；
- 数据库已经撤销或退役 key 后，旧 Pod/旧挂载仍可能继续把该 key 当作 verifier material；
- 管理面比较 base snapshot 不能约束独立使用 Package-executor credential 的 recovery Job。

必须先关闭这个缺口，才能安全实现正常 overlap-add 与 retirement。

## 决策

### 1. 文件是 material，PostgreSQL head 是 authority

publisher trust 文件继续保存公开的 Ed25519 PEM、publisher、key ID 和 lifetime。读取器对
文件大小、regular-file、只读权限、exact JSON shape 和全部 key 定义执行既有严格验证。

运行时新增纯绑定函数：

1. 从全部文件定义构造 canonical low-sensitive material snapshot；
2. 规范化 PostgreSQL 返回的 effective snapshot；
3. 对每个 effective key 精确匹配 publisher、key ID、public-key digest、not-before 和
   not-after；
4. 只用匹配成功的定义构造 verifier registry；
5. effective key 缺材料、PEM 被替换、lifetime 漂移或 effective set 为空时失败关闭。

文件可以是 effective set 的真超集，因此允许先分发候选 key；额外 key 不进入 verifier。

### 2. stage authority 在数据库就绪后创建

`recoverClusterPluginPackages` 支持二选一：

- 调用方提供已构造的 `stageAuthority`；
- 调用方提供 `stageAuthorityFactory(pool)`。

两者必须且只能存在一个。factory 只在 Package-executor 数据库资源完成 schema/readiness
检查后调用；返回值立即执行同一 stage/verify contract 检查，并只在本次 recovery 周期内
使用。数据库仍由既有 one-shot composition 统一关闭，factory 不建立第二个 pool，也不让
repository 或 stage authority 逃逸。

生产 recovery 使用 factory：

1. 读取显式 `QL3_PLUGIN_PACKAGE_TRUST_AUTHORITY_ID`，默认 reviewed `cluster`；
2. 用现有只读 trust repository 查询 head 与 effective snapshot；
3. 将挂载 material 绑定为 effective registry；
4. 再构造 OCI stage authority。

因此 trust 查询、provenance recovery、stage 和 activation 共享一个最多 1 连接的
Package-executor pool，适合低资源单节点，也适合 HA writer endpoint。

### 3. 失败边界

以下状态必须在 OCI fetch、签名验证、Kubernetes 写入前失败：

- authority head 不存在；
- effective snapshot 在文件中缺少 exact material；
- public-key digest 或 lifetime 与 durable snapshot 不一致；
- 文件权限、大小、shape 或 key 类型不合法；
- database-bound factory 返回不完整 authority。

显式测试注入的 registry/stage authority 保留，用于无网络、无数据库的确定性测试；产品
部署不能通过环境变量选择绕过 durable head 的 registry。

### 4. 与 rotation/retirement 的关系

本 ADR 不新增 trust transition：

- overlap-add 后续采用 `old+new material` 预分发，再由受批 executor 推进 effective
  `old → old+new`；
- retirement 后续采用 durable impact proof 与 generation fence 推进
  `old+new → new`，随后才允许从文件清理 old material；
- emergency revoke 继续使用 ADR-0188 的 receipt/impact/quarantine 链。

正常 retirement 不能仅靠本次 recovery 启动时的 snapshot；后续 transition 必须在
provenance 写入和 head 推进处增加并发 fence。

## 包与资源边界

不新增 workspace package、migration 或生产依赖：

- `runtime-core` 保存纯 material/effective 绑定；
- `cluster-postgres` 复用现有 Package-executor 可读 trust repository；
- `cluster-admin` 在现有 recovery composition 内延迟构造 stage authority。

workspace 保持 22 包。没有新增 listener、timer、watcher、Service 或常驻 Pod；recovery
仍是显式 one-shot Job，数据库 pool 仍为 1 个连接。

## 不采用方案

### 文件 digest 必须等于 effective digest

这会禁止 old+new 候选材料预分发，并迫使 ConfigMap 更新与数据库审批形成不可实现的跨介质
原子提交。

### management 把 effective registry 推送给 executor

会把短生命周期 executor 依赖于管理进程可用性，并增加新的网络协议、身份和缓存一致性问题。

### recovery 启动前单独打开第二个数据库 pool

会增加低配设备连接开销，并让 trust 读取与实际 recovery 使用不同资源生命周期。

### 为 material binding 新拆 package

没有独立 Profile、credential、制品或第三方依赖边界，会违反 ADR-0185 的 package
收敛原则。

## 验收

- runtime-core 测试证明候选 key 被排除、exact durable key 可用、同 identity 替换 PEM
  失败关闭；
- recovery composition 测试证明 factory 只在 readiness 后接收同一 pool，且数据库仍精确
  关闭一次；
- Package recovery 配置与 base/CloudNativePG manifest 显式绑定 authority ID；
- 两套 Kustomize 渲染、deployment audit 与 dependency audit 无 finding；
- runtime-core 359/359；cluster-admin 111 pass、1 条真实 Kubernetes 条件 skip；
- PostgreSQL 18.4 arm64 physical HA 总门重跑 `gates.passed=true`，v38 Approved
  Action、trust generation `1→2`、quarantine exact-once、timeline `1→2`、旧主
  fence、`pg_rewind` 与同步只读重加入均无回归；
- workspace 仍为 22 包，无 migration、依赖或常驻资源增长。

## 后续

1. D-180 实现单 key overlap-add 与 safe-retire proposal/action。
2. retirement 在 signer provenance commit 与 trust-head transition 间增加 generation fence。
3. HA 门增加 old+new material 预分发、批准前拒绝、批准后接受和旧 key 安全退役证据。