qinglong/docs/adr/ADR-0502-bounded-cluster-api-credential-pepper-keyring.md

ADR-0502：有界 Cluster API Credential Pepper Keyring

• 状态：Accepted
• 日期：2026-08-26
• 决策：D-407
• 关联：ADR-0049、ADR-0050、ADR-0080、ADR-0083、ADR-0500、ADR-0501

背景

PostgreSQL API credential record 已保存 pepperKeyId，但 Cluster Control 运行时仍只装载一个 pepper，Security Administration 签发时也固定写入 legacy-v1。这意味着数据库虽然保留了密钥来源，却无法在不中断全部旧 credential 的情况下切换 pepper；如果认证端通过遍历所有历史 pepper 猜测摘要，又会扩大每个未认证请求的 CPU 成本和 timing surface。

QingLong 3.0 同时服务低配路由设备与集群节点。pepper rotation 只能进入 Cluster opt-in 路径，不能给 Edge/Standalone 增加 package、依赖、watcher、timer、连接池或常驻资源；Cluster 的认证热路径也必须保持一次精确摘要计算，而不是随历史 key 数线性增长。

决策

1. 运行时只接受最多两个显式 generation

runtime-core 提供 schema v1 keyring：一个 activePepperKeyId 和 1–2 个唯一 {pepperKeyId,pepper}。每个 ID 与 32-byte canonical base64url material 都使用既有 credential contract 校验，active ID 必须存在于 keys。原单 pepper 配置只通过显式 legacy-v1 singleton bridge 保持兼容，不允许自动发现、环境合并或第三代历史 key。

Cluster Control 可从 QL3_API_CREDENTIAL_PEPPER_KEYRING_FILE 读取不超过 2 KiB 的 canonical 私有 JSON；它与旧 QL3_API_CREDENTIAL_PEPPER 必须二选一。文件必须是 canonical absolute regular file、不可为 symlink、不可向 group/world 写入，并在稳定 inode/mtime/size 下读取。Kubernetes 的 kubelet Secret volume 使用 symlink-backed Atomic Writer，不能直接满足该运行时边界；部署因此只把投影挂给同 UID 的 hardened init container，由它固定解析一个 ..data generation，将 CA 与 keyring 以 no-replace 方式复制到 1 MiB memory-backed Pod-private volume 并收紧为 0400 普通文件。常驻容器只读挂载物化后的 volume，不可访问原始投影。运行时不安装 watcher；切换 keyring 后由部署系统执行受控滚动重启，新 Pod 在启动前重新物化。

2. 认证严格按 durable key ID 选择

认证先读取 credential record，再用其 pepperKeyId 精确选择一把 pepper，并只计算一次摘要。未知 key ID、缺失 material、畸形 keyring 或存储不可用都返回统一 unavailable；不得回退 active key、legacy key或遍历其他 key。未知 credential 的 timing dummy work 只使用 active key，不产生多 key 探测。

因此 overlap 期间旧 credential 继续使用旧 key，新 credential 使用新 key，但每个请求成本仍为常数。keyring 不进入日志、响应、审计详情或错误字段。

3. 新签发只绑定 active generation

Security Administration 使用 keyring 的 active key 计算新 token digest，并把 exact active ID 写入 credential record。credential.issue、credential.rotate 的 mutation/replay、私有 delivery 和同事务 audit 语义不变；旧 raw pepper 参数仍只映射成 legacy-v1 singleton bridge。

CLI 在 --pepper 与 --pepper-keyring 中必须精确选择一个。keyring 文件属于短生命周期 admin authority，不进入 command JSON，也不复制到输出或数据库。

4. 退休前只做有界引用检查

新增只读 pepper.references 管理操作，输入仅为 exact pepperKeyId 和 1–64 的 limit。PostgreSQL 使用 statement_timestamp()，只返回该 key 当前最新、active、未过期 credential ID、观察时间与 hasMore；结果行、时间、ID、重复项或空集表示发生漂移时全部失败关闭。

该查询用于人工轮换 ceremony 的退休前判断，不删除 credential、keyring material 或历史记录，也不修改 active key。结果大小有界，但当前查询仍可能检查历史 credential versions；大规模生产数据上的索引/查询计划证据是独立门禁，不能把输出上限解释为数据库成本已经完全有界。

轮换顺序

1. overlap：部署 {old,new}，active 仍为 old，滚动重启并确认旧 credential 可认证；
2. activate：把 active 切到 new，再滚动重启，之后的新 issue/rotate 都绑定 new；
3. converge：轮换或撤销 old credential，分页执行 pepper.references，直到得到同一稳定部署下的空引用结果；
4. contract：从 keyring 删除 old，滚动重启并确认 old credential 失败、new credential 成功。

任何阶段都不得在仍有引用时删除 material。当前切片不实现 material destructive GC、持久 active-generation catalog、自动轮换调度或 Kubernetes Secret CAS；这些能力必须使用独立 ADR 和 live gate。

被拒绝的替代方案

认证时遍历所有 pepper

拒绝。它让未认证请求的成本随历史线性增长，扩大 timing surface，也掩盖 record 的 durable provenance 漂移。

无界 keyring 或永久保留所有历史 key

拒绝。Cluster 常驻 secret footprint、审计范围和错误配置 blast radius 会持续增长。3.0 首个轮换只允许 old/new 双代 overlap。

在进程内 watcher 自动热切换

拒绝。它增加后台 I/O、竞态和跨副本不可观察状态。初始产品基线使用显式配置更新和部署系统滚动重启。

同时给 Edge/Standalone 增加该 keyring

拒绝。D-407 只关闭 Cluster API credential 的结构缺口；本机 Owner credential 已有独立 catalog/keyring/GC ceremony，不能混合 authority。

验证

• keyring contract 覆盖 exact shape、1–2 key 上限、active membership、duplicate、invalid ID/material 和 singleton bridge；
• Cluster Control 覆盖 old/new overlap、stored key exact selection、unknown stored key fail-closed、旧环境变量 bridge、私有 keyring 文件与双来源拒绝；
• Security Administration 覆盖新 credential 绑定 active key、keyring CLI、引用查询 exact command/result 与旧单 pepper bridge；
• PostgreSQL repository 覆盖数据库时间、latest active/unexpired 过滤、limit+1、空引用与畸形行 fail-closed；
• Kubernetes Security Administration 只投影 pepper-keyring.json，stager 以 2 KiB 边界私有化到 memory-backed 0700/0600 目录；常驻 Cluster Control 通过 init materializer 把 symlink-backed Secret generation 收敛成 Pod-private 0400 CA/keyring 普通文件，不再从 Secret 注入旧单值环境变量，也不向主容器暴露原始投影；
• overlap-old-active、activate-new、旧代引用 1→0 与 contract-new 已由远程 run 32893754795 在 source beb490c48c7d8ee4aee629924b5003fd8c73e9cb 上完成受审 live 验收：K3s v1.34.3+k3s1 为 1 control-plane + 2 worker，CloudNativePG 1.30.0 管理 3 个 ready PostgreSQL 18.4 实例；三次 rollout 始终保持两个反亲和 Cluster Control 副本。五个真实 /api/v3 probe 证明 old/new 在 overlap 期间认证成功但因无 Project role 返回 403，contract 后 old 返回 401、new 仍返回 403；数据库事实为两个 credential、四个 version、1 个旧代与 3 个新代 version、四次 authorization denied 与一次 authentication rejected。报告还证明 response-loss exact replay、RWO PVC 三个 no-replace delivery、网络/RBAC 拒绝与完整清理；content-free 离线复审为 compatible=true/findings=[]，报告 SHA-256 为 d9e9fd1395adcef60f7f360959fcad27a9b2f0b132869bc1c75043dedd400ff6；
• 当前 cluster-admin 完整回归为 459 total / 456 pass / 3 conditional skip / 0 fail，cluster-control 为 281 total / 279 pass / 2 conditional skip / 0 fail；3.0.0-alpha.1 身份下 18-package clean build/test 已完成（Worker Runtime 3 个 loopback 用例在沙箱外复验为 135/135）。物化修复后的治理/部署聚焦测试为 88/88，完整 backend 为 1599 total / 1597 pass / 2 conditional skip / 0 fail；source f8934b401d724378fe5a6ea9dbe63e696b5480b9 的远程 CI run 32898407637 为 40/40，独立 Kubernetes deployment run 32898407590 也已通过。

影响与剩余门禁

D-407 关闭了“数据库记录 key ID、运行时却只能使用一个固定 pepper”的结构性缺口。Edge/Standalone package、依赖和常驻路径零变化；Cluster 每个认证请求仍只解析 record 并计算一个摘要，管理引用检查只在显式短命令中打开一个 admin connection。

D-406 Kubernetes stager/Job 与常驻 Cluster Control manifest 已收敛为 keyring-only；旧单 pepper 只存在于通用 CLI/进程配置兼容桥。D-407 的真实 K3s/CNPG overlap→activate→contract 产品命令、运行时认证与权限边界门已经关闭，但这只是单 Docker host 上的应用合同证据，不是生产 control-plane HA、跨主机 STONITH/DR、加密 CSI 或外部 ingress TLS 证据。远程管理 API/UI、双人复核/break-glass、material GC、audit retention/export/alert 和大规模引用查询计划也仍未完成。