qinglong/docs/adr/ADR-0266-externally-staged-cluster-prompt-output-active-key-rotation.md

ADR-0266：Externally staged、resourceVersion-fenced 的 Cluster Prompt Output Active Key Rotation

• 状态：Accepted
• 日期：2026-08-03
• 关联：QL-RFC-0001 D-207/D-244/D-245/D-247、ADR-0261、ADR-0262

上下文

ADR-0262 已让 Cluster 使用固定 Kubernetes Secret 作为 Prompt output keyring material authority， 并以一次性 Job 完成 inactive key retirement；后续运行时同源投影也已证明同一 Pod/进程可观察 generation 更新，并继续解密历史 Artifact。尚未关闭的是首次 provision 与 active key rotation。

Kubernetes RBAC 的 create 不能由 resourceNames 限定。若 QingLong 自带 Job 创建目标 Secret， 它将取得 namespace 内创建任意同类对象的权限，超出一次 rotation 的最小 authority。另一方面，若 Job 在内存中随机生成新 key 后再替换目标 Secret，更新响应丢失时无法重新构造完全相同的 material； 盲目重试会产生另一个 key，无法判断首次写入是否已成为 durable winner。

因此，本阶段需要把 material custody、目标 Secret CAS 与 PostgreSQL 审计拆成三个明确边界：外部 部署 Secret manager/KMS 负责首次 provision 和 staged material，caller-driven Job 只消费一次不可变 投影并更新固定目标，PostgreSQL 只保存 content-free prepare/complete facts。

决策

1. 首次 provision 保持外部责任

QingLong 不内置对目标 Secret 的宽泛 create。首次创建 ql3-prompt-output-keyring、encryption-at-rest、备份、KMS wrapping/HSM custody 和 lost-key recovery 继续由部署者选择的 Secret manager/KMS ceremony 负责。首次对象必须满足 ADR-0262 的固定 identity、 canonical manifest、label/annotation 和唯一 data key 约束；rotation Job 只接受预先观察到的 UID， 不能把删除重建后的同名 Secret 当作原对象。

2. 新 material 由外部不可变 staging Secret 投影

每次 rotation 由外部 authority 创建固定名 ql3-prompt-output-key-rotation-material 的 immutable Secret，只含一个原始、恰好 32-byte 的 material.bin。kubelet 将该项以 0440、read-only、单文件 subPath 投影给 Job；Job 没有对 staging Secret 的 get/list/watch/create/update/patch/delete API 权限，也不把 material 放进 command、ConfigMap、 环境变量、stdout、日志或 PostgreSQL。

命令只包含 expected target UID、active key ID、catalog digest、新 key ID 和低敏 operation identity。 material reader 使用 O_NOFOLLOW、regular-file、single-link、exact-size、mode 和 pre/post stat 围栏； 读取后复制到受控内存，并在完成或失败时清零。

3. 目标 Secret 使用三重预期与 resourceVersion CAS

rotation 必须同时匹配：

• 预观察的 Secret UID；
• expected active key ID 与完整 expected catalog digest；
• 当前读取所得 resourceVersion。

成功 successor 只追加唯一的新 key、把它设为 active、将 generation 加一，并保留全部旧 key 供历史 Artifact 解密。adapter 只能对固定 ql3-prompt-output-keyring 执行 get/update；不同 UID、active/catalog 漂移、key ID 复用、material 改写、manifest 非 canonical 或并发不同命令都失败关闭。

相同命令和相同 staged material 的重放必须得到完全相同 successor。Kubernetes update 响应丢失或连接 中断时，adapter 重新读取目标：只有 UID、generation、active key、catalog 和 material proof 都与预期 successor 一致时才返回 existing；不能以 HTTP 状态缺失直接宣告失败或盲写第二次。

4. PostgreSQL 采用 content-free prepare/complete protocol

在 target Secret mutation 前，专用 maintenance authority 必须追加 immutable preparation，绑定 rotation/request/mutation identity、expected UID/active/catalog、新 key ID和 staged material proof，但 不得保存 material、base64、Secret body、token、DSN 或文件路径。Secret CAS 成功后再追加 completion， 绑定 successor generation/catalog 与 preparation digest。

崩溃恢复由 durable facts 和同一 staged material 裁决：

1. 没有 preparation 时创建 preparation；
2. 有 preparation、无 completion 时重读/必要时 CAS 同一个 successor；
3. Secret 已是 exact successor 时只补 completion；
4. preparation 或 Secret 与命令/material proof 不一致时失败关闭；
5. completion 已存在时返回 exact existing，不再更新 Secret。

PostgreSQL append-only protocol、最小权限 ACL、COMMIT-response-loss convergence、physical HA promotion survival 与真实 K3s Job 纵切面均已由下述证据关闭。CLI stdout 始终只能视为低敏操作结果， 不能冒充 durable audit。

5. 一次性权限与网络边界保持显式

operation 使用独立 tokenless ServiceAccount、backoffLimit: 0、短 deadline、只读 root、non-root、 drop ALL。只有主容器取得 600 秒 projected token；tokenless init 先证明 exact API allow 与 deny-canary 不可达。RBAC 仅允许对固定目标 Secret get/update 和创建 SelfSubjectAccessReview；staging Secret 不在 API authority 中。base NetworkPolicy 只允许 DNS，Kubernetes API 必须由私有 overlay 以 exact /32 + TCP port 放行；接入 PostgreSQL 后，CloudNativePG overlay 也只能放行数据库 Pods 的 5432。

低配与 package 影响

• Edge/Standalone 不装配 Kubernetes client、staging Secret、Job、listener、Pool、timer 或 watcher；
• runtime Cluster Pod 仍只读同源投影，没有 ServiceAccount token、Secret API 或 mutation authority；
• 实现留在既有 @qinglong/ai manifest subpath、@qinglong/cluster-admin one-shot process 和 @qinglong/cluster-postgres maintenance adapter，不新增 workspace package；
• workspace 保持 19 个 QL3 package，低配设备不会因 Cluster rotation 文件数增加 importer/SBOM 闭包；
• 每次 ceremony 最多读取一个 32-byte staged material 和一个有界 keyring Secret，无 list/watch/cache。

当前实现与接受门

已完成：

• shared manifest rotation：exact 32-byte、新 identity、generation+1、保留历史 key、exact replay；
• Kubernetes Secret adapter：UID/resourceVersion CAS、并发单赢家、状态缺失的 update-response-loss 重读；
• command-file-only CLI 与 hardened staged-material reader；
• 独立 Job/RBAC/ServiceAccount/NetworkPolicy、命令/material/token 三种分离挂载及 deployment mutation audit；
• pg-9016 append-only preparation/completion、source CAS fence、content-free digest、专用 maintenance SELECT/INSERT-only ACL、readiness 与 COMMIT-response-loss durable re-read；
• one-shot process 的 Kubernetes authority/readiness → PostgreSQL prepare → Secret CAS → PostgreSQL complete 顺序，以及 prepare 后恢复、Secret update 响应丢失和 completion 响应丢失 exact convergence；
• AI 183 项中 180 pass/3 条件 skip、Cluster Admin 252 项中 250 pass/2 条件 skip，dependency/deployment audit 43/43、两套 Kustomize render 与构建全绿；
• 2026-08-03 PostgreSQL 18.4 arm64 physical HA 门包含本 ADR 的 rotation facts 后重跑全绿： remote_apply、timeline 1→2、一次 Secret durable write、材料 authority 两次调用、response-loss convergence、historical Artifact decrypt、content-free facts、promotion survival、旧主 pg_rewind 只读同步重入与总 gates.passed=true；ql3-ha-* 零残留，受保护 evidence control-plane 未被操作。
• 2026-08-03 真实三节点 K3s/Flannel + CloudNativePG 1.30.0/PostgreSQL 18.4 arm64 纵切面通过： 3/3 database Ready、52/16 migration、两次 one-shot Job 形成 completed/existing、Secret generation 1→2 且 resourceVersion 只改变一次、preparation/completion 各一条并保持 content-free；staged material 为 immutable Secret 的 0440 单文件投影，Job 对它无 API read authority；同一 tokenless runtime Pod 观察新 active key 并用保留的旧 key 解密历史 Artifact。exact RBAC/API/PG/DNS egress、同 Pod deny barrier、600 秒 token 与全部 gate 为 true；随机 K3s 资源和临时镜像零残留，受保护 control-plane 未触碰。

Accepted 后仍保留的独立发布门：

1. 生产 KMS/HSM/backup/lost-key ceremony 继续作为独立发布门，不由本 ADR 的 Kubernetes Secret 证据替代。

被拒绝方案

1. Job 创建目标 Secret：Kubernetes create 无法按 resourceNames 收紧，会扩大 namespace authority。
2. Job 内随机生成 key：响应丢失后无法 exact replay，可能产生两个不同 successor。
3. 把 material 放入 command/ConfigMap/PostgreSQL：扩大日志、etcd、备份和审计泄漏面。
4. 给 Job staging Secret API read：kubelet 投影已足够，额外 API authority 允许枚举或旁路读取。
5. rotation 删除旧 key：会破坏历史 Artifact decrypt；删除只属于独立、已证明零引用的 retirement。
6. 自动重试 Job/controller：不确定结果必须由 durable facts 裁决，后台重试会掩盖冲突并扩大常驻面。
7. 为 rotation 新拆 package：没有独立制品或依赖反转价值，只会重新引入 D-207 的碎片化。