qinglong/docs/adr/ADR-0268-signed-external-prompt-output-key-custody-and-recovery-proof.md

# ADR-0268：签名的外部 Prompt 输出密钥托管与恢复证明

- 状态：Proposed
- 日期：2026-08-03
- 关联：RFC D-244、D-245、D-247、D-249；ADR-0261、ADR-0262、ADR-0266

## 背景

QingLong 已能用 Kubernetes Secret CAS 完成 Prompt 输出 key rotation/retirement，并以
PostgreSQL append-only preparation/completion 抵抗响应丢失和主库晋升。但 Kubernetes
Secret 不是最终 KMS/HSM，也不是灾难备份。`create Secret` 不能按 `resourceNames` 收紧，
因此 QingLong Job 不应为了首次 provision 或灾难恢复取得 namespace 范围的 create 权限；
常驻 control 更不能持有 KMS unwrap、HSM session 或对象存储删除 authority。

即使 key material 已安全退役，现有 durable fact 仍保留 `keyId + materialProof +
catalogDigest`。这允许一个外部托管系统恢复 32 字节 material 后，在不重新激活该 key、
不改写生产 Secret 的情况下，证明它与原始 rotation/retirement 事实相同，并实际打开一份
历史 Artifact。

## 决策

### 1. KMS/HSM 与 QingLong runtime 分权

首次生成、wrap/unwrap、HSM quorum、wrapped blob 存储、备份复制和外部 Secret create 均由
部署方的独立 authority 负责。QingLong runtime、cluster-control、AI Pool 和 migration role
不得取得云 SDK credential、KMS decrypt、HSM session、Secret create 或 backup delete。

### 2. 外部托管必须产生签名 receipt

新增 `qinglong/plugin-package-prompt-output-external-custody-receipt@v1`。receipt 只保存：

- custody/key identity、material proof、source generation/catalog digest；
- provider 名、wrapping key reference digest；
- wrapped material digest/bytes；
- Ed25519 signing public key digest、receipt digest 与 signature。

receipt 不包含 plaintext key、wrapped blob、KMS key ARN/path、credential、Artifact ciphertext
或模型输出。QingLong 只接受显式 pinned Ed25519 public key；换 key 必须是外部受审 ceremony，
不能由 receipt 自报信任根。

receipt 与 wrapped blob 必须装入单一
`qinglong/plugin-package-prompt-output-external-custody-bundle@v1`。bundle digest 使用独立 domain，
绑定 schema、custody ID、receipt digest、wrapped material digest/bytes；wrapped material 使用
canonical base64url。Verifier 不再接受两个独立文件，避免复制中断或跨 generation 拼接形成
“新 receipt + 旧 blob”的部分状态。bundle 是 provider-neutral contract，不包含 endpoint、KMS key
path、token 或 provider credential。

### 3. wrapped backup 与恢复 material 分别验证

`@qinglong/ai/plugin-package-prompt-output-external-custody` 提供两个纯 caller-driven gate：

1. 对 wrapped blob 复算 bytes/SHA-256，并验证 receipt digest、签名和 pinned key；
2. 对外部 unwrap 后的 32 字节 material 复算 domain-separated material proof，要求与
   rotation completion 或 retirement preparation 的 durable `keyId/materialProof/catalogDigest`
   完全一致，再使用正式 AES-256-GCM/AAD 逻辑打开 exact Artifact。

成功只返回 content-free recovery proof：custody/receipt/key/material proof、Artifact/content
digest、output bytes、request/recovery identity 和 verification time。不得返回 plaintext、
key、wrapped bytes、provider reference 或路径。

### 4. 恢复不等于重新激活

首版 recovery proof 不更新生产 Secret、不删除 retirement record、不改变 active key、
不写 ModelInvocation/Artifact，也不把恢复 material 挂给常驻 runtime。实际明文交付、
重建生产 keyring 或 re-encrypt 属于后续显式审批产品；不能因为一次验证成功就静默撤销
retirement 或绕过 `artifact.read`。

### 5. 资源与包边界

能力留在既有 `@qinglong/ai` subpath，不新增 workspace package、第三方依赖、数据库表、
timer、watcher、listener、Pool 或云 SDK。Edge/Standalone/Cluster 默认均不加载；只有外部
恢复 ceremony 显式调用时付费。

### 6. 恢复必须由两个独立强身份共同授权

新增 `qinglong/plugin-package-prompt-output-external-recovery-authorization@v1`。授权固定
`artifact.read` 与 `lost-key-recovery-verification`，并绑定 recovery/request、custody receipt、
key、Artifact、Policy digest、请求者身份和最长 15 分钟有效期。两个 approver 必须使用不同
User、authentication、Ed25519 signing key，且均不得是请求者；每个认证在批准时最多 5 分钟。
两份签名覆盖同一个 canonical authorization digest，不能分别批准不同 Artifact 或 key 后拼接。

trusted approver public key 由 verifier 的私有 workspace 显式 pin，authorization 不能自报信任根。
过期、self-approval、重复 User/auth/key、签名或 exact fact 漂移全部失败关闭。

### 7. Verifier 是无网络、无数据库的隔离产品入口

`ql3-prompt-output-key-recovery-verify` 只读一个私有 workspace：authorization、custody receipt、
wrapped blob、外部 unwrap 得到的 32 字节 material、durable fact、Artifact 及三个 pinned public
key。所有文件必须是稳定、单 hard-link、不可写/执行、不可跟随 symlink 的 regular file；私有
文件禁止 `other` 读取。CLI 完成后清零持有的 recovered/wrapped material buffer，stdout 只有
authorization-bound content-free proof。

Kubernetes reference Job 位于独立 `qinglong3-recovery` namespace，不属于默认 Cluster
Kustomization。它没有 Role/RoleBinding、ServiceAccount token、env/envFrom、数据库连接、Secret
API、KMS endpoint 或 ingress/egress，只读一个由外部部署 authority 预置的 PVC。这个 Job 不能
执行 unwrap；因此 KMS credential 也不会因“恢复验证”进入 QingLong Pod。

### 8. 首个具体 adapter 是外部 Vault Transit CLI

仓库提供 caller-driven `custody:vault-transit:ql3` wrap/unwrap adapter，但不把 Vault SDK、token、
socket 或 timer 装入任何 QL3 package/runtime。production 只允许 HTTPS + 显式 CA，token 只从私有
只读文件读取；HTTP 仅允许 `127.0.0.1` 测试 fixture。wrap 调用 Transit encrypt 后生成签名 receipt
和单一 `0400`、no-replace bundle；exact replay 只验证已有 bundle，不重打 Vault。unwrap 先验证
bundle、pinned signing key、Vault endpoint/mount/key/version 的摘要绑定，再调用 Transit decrypt，
仅在 32 字节 material proof 完全一致后创建 `0400`、no-replace 文件。错误和成功 stdout 均不包含
token、material、wrapped blob、endpoint、key name 或路径。

## 当前证据

- Ed25519 receipt digest/signature 和 signing-key digest 可复算；错误 key/signature 失败关闭；
- wrapped blob bytes/digest 漂移失败关闭；
- provider-neutral atomic bundle 已替代 receipt/blob 双文件输入；跨 bundle blob 替换、digest 漂移、
  extra field 与 signing authority drift 均失败关闭；
- recovered material 必须同时匹配 signed receipt 与 durable key fact；
- 使用正式 Artifact AES-256-GCM/AAD 路径打开历史密文，输出 proof 不含明文或 key；
- 两个不同强 User、authentication 和 Ed25519 key 对同一个 15 分钟 authorization 签名；请求者
  self-approval、重复身份/会话/key、过期、签名和 exact fact 漂移失败关闭；
- package CLI 已从只读私有 workspace 完成 exact recovery，并在退出时清零 material/wrapped
  buffer；输出不含明文、key 或 wrapped blob；
- 隔离 Kubernetes Job 可由 Kustomize 渲染；deployment auditor 证明零 RBAC/token/env/network/
  database/KMS authority、deny-all NetworkPolicy 和 read-only PVC；
- Vault Transit concrete adapter 的 8 项 protocol test 已覆盖 immutable wrap、exact replay、
  unwrap、wrong material、key authority drift、非 HTTPS production transport、unsafe authority
  file、bounded response 和 content-free CLI；
- opt-in live contract 已在 digest-pinned 官方 Vault 1.21.4 arm64 容器实际完成 TLS 1.3 + 显式
  私有 CA、错误 CA 拒绝、3-share/2-threshold init/unseal、persistent file barrier、Transit key
  create/encrypt、atomic bundle、整个容器替换、sealed 状态观察、re-unseal、同一 Transit key 存续、
  decrypt、无 Vault exact replay、双 User authorization 与正式 Artifact open，最终
  `gates.passed=true`。容器显式当前非 root UID/GID、read-only rootfs、no-new-privileges、capability
  仅 IPC_LOCK、随机 loopback 端口且成功/失败均零临时容器/私有目录残留；该证据仍是单宿主 file
  storage 和短期本地 CA/root token，不是 HA integrated storage、HSM auto-unseal、enterprise PKI
  或外部 IdP/CNPG restore；
- 独立 PostgreSQL 18 arm64 opt-in live contract 已用 digest-pinned 官方镜像和随机 loopback-only
  端口运行完整 QL3 core/AI migration，以 production repository 写入 materialized revision、automation
  publication、Prompt admission/start/completion/finalization、正式加密 Artifact 和 key-rotation
  preparation/completion，再生成 734,708-byte custom-format backup。backup 不含明文或 raw key；
  删除整个源容器及匿名卷后，不同容器/匿名卷恢复出相同 52 条 core、16 条 AI migration history
  digest，八类 lineage 行各 1，并由恢复后的 Artifact/rotation repository 重新读取 exact fact 与
  Artifact，交给既有双 User authorization + offline verifier 实际打开，最终 `gates.passed=true`。
  成功/失败都清理随机容器、匿名卷和私有目录。该门已证明 production schema lineage 的逻辑
  PostgreSQL backup→restore→recovery composition，但不替代 CloudNativePG Barman WAL/PITR；
- workspace 仍为 19，package consumer graph 和依赖树不变。

## 接受门

本 ADR 保持 Proposed，直到：

1. 在 production-grade 外部 KMS/HSM/Vault HA storage + HSM/受控 unseal authority 下完成
   generate→wrap→immutable backup→unwrap，并证明 QingLong Pod 无 KMS credential；当前 TLS 1.3/
   persistent single-host Vault live contract 已关闭 transport、barrier restart 和 seal threshold 的
   实现风险，但不替代外部 HA/HSM 门；
2. 把当前 pinned Ed25519 双人 authorization 接到真实外部 IdP/审批 ceremony，取得非 fixture
   的不同 User/authentication 证据；
3. 在隔离恢复环境中从 production schema lineage 的 PostgreSQL/CNPG backup 取得 exact Artifact
   和 durable key fact，完成 content-free recovery proof；当前独立 PostgreSQL logical backup 门
   已关闭完整 production tables、migration history、backup 序列化、源销毁、隔离 restore、
   production repository reopen 和 verifier composition 风险，但尚未替代 CloudNativePG Barman
   WAL/PITR；
4. 覆盖 receipt/backup 丢失、错误 KMS key version、签名轮换、material drift、Artifact
   篡改、COMMIT response-loss 和主库 promotion；
5. 明确实际 plaintext 导出、生产 keyring 重建或 bulk re-encrypt 的独立授权与审计策略。

## 不采用方案

### 在 cluster-control 内集成所有云 KMS SDK

拒绝。会把 provider 重依赖、长期 decrypt credential 和网络故障域带入全部控制面副本。

### 让 rotation Job 同时负责首次 Secret create

拒绝。Kubernetes RBAC 无法把 create 收紧到一个未来对象名。

### 只备份 Kubernetes Secret 或只保存 material hash

拒绝。前者没有独立外部 custody，后者无法恢复；两者都不能证明 wrapped blob 与原 key、
durable fact 和历史 Artifact 同时一致。

### 恢复后自动把旧 key 重新加入生产 keyring

拒绝。会绕过 retirement、审批、运行时 reload 和后续再次安全退役的状态机。