yuqei
1d85329a6a
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 9m12s
Build and Test Quality Gate / Isolated Alibaba and Tencent KMS gateway (pull_request) Failing after 4m53s
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 24m55s
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 8m42s
101 lines
6.4 KiB
Markdown
101 lines
6.4 KiB
Markdown
# V2 P1-07.6 外部见证、多地域探针与人工接管闭环实施说明
|
||
|
||
> 实施日期：2026-08-25
|
||
> 状态：已实现，进入隔离 UAT 与发布门禁
|
||
> 适用角色：平台超级管理员、安全负责人、SRE、法务运营、内外部审计人员
|
||
|
||
> 2026-08-25 产品决策：双云外部可信能力调整为企业版可选能力。核心产品默认使用 `disabled` 模式，不再因缺少外部探针或见证目标阻断上线；隔离双云 UAT 覆盖文件显式使用 `required`，原验收标准保持不变。
|
||
|
||
## 1. 交付结论
|
||
|
||
P1-07.6 在 P1-07.5 平台内哈希链和单区域合成验签的基础上，补齐四个生产信任缺口：透明检查点可投递到多个外部不可变目标并验证独立见证签名；KMS 验签探针按地域和网关目标独立留痕；审计凭证的签发、轮换和撤销统一进入双人审批；SLO 多窗口告警自动生成、升级并关联人工复核工单。
|
||
|
||
本阶段不改变“可靠合同决策”的业务判定口径，不把合同正文、签名私钥、审计 Bearer 凭证、外部见证凭据或原始客户端地址写入运营账本。
|
||
|
||
## 2. 外部锚定与见证
|
||
|
||
- 只有 `chain_valid=true` 且树大小大于零的检查点允许投递；
|
||
- 每个目标独立配置名称、地域、HTTPS 端点、凭据文件、CA、见证公钥文件和算法；
|
||
- 请求携带规范化检查点及 SHA-256 摘要；响应必须包含外部引用、回执和见证签名；
|
||
- 平台使用预置见证公钥验证回执签名，只保存回执摘要、公钥指纹、外部引用和脱敏错误码；
|
||
- 检查点公开返回 `verified_witnesses`、`required_witnesses`、`witness_quorum_met` 和最近锚定时间；
|
||
- 同一目标、树大小和链头具有数据库唯一约束，重试不会重复制造锚定记录；
|
||
- 外部见证记录不回写同一条透明链，避免“记录锚定事件导致链头立即变化”的自追赶问题。
|
||
|
||
本实现不是 RFC 6962 Certificate Transparency；它是面向业务证据链头的多目标不可变存储与签名见证适配层。
|
||
|
||
## 3. 多地域 KMS 验签探针
|
||
|
||
- `CONTRACT_API_RELIABLE_EVIDENCE_PROBE_TARGETS_JSON` 配置多个 KMS 网关地域；
|
||
- 每个地域使用独立端点、凭据文件和 CA，调用相同不可变密钥版本签名随机合成摘要；
|
||
- 平台用已固化的证书公钥本地验签，并保存地域、目标、耗时、算法、指纹和脱敏错误码；
|
||
- SLO 继续按每一次地域探针结果计算，单地域故障不会被其他地域成功覆盖；
|
||
- 未配置地域目标时运行内部 `primary` 自检探针；只有外部可信模式为 `required` 时才触发发布阻断；
|
||
- 探针不读取合同、租户业务字段或真实证据包。
|
||
|
||
## 4. 审计凭证双人审批与轮换
|
||
|
||
直接签发和直接撤销接口保留为兼容占位，但始终返回 `409 audit_client_dual_control_required`。统一状态机如下：
|
||
|
||
```text
|
||
issue / rotate / revoke proposal
|
||
│
|
||
├── proposer self-review ──> 409
|
||
├── reject ────────────────> terminal, no credential mutation
|
||
└── independent approve
|
||
├── issue -> create v1 credential
|
||
├── rotate -> atomically replace hash/prefix, version +1
|
||
└── revoke -> terminal revocation
|
||
```
|
||
|
||
- 完整 Bearer 值只在批准 `issue` 或 `rotate` 的响应中返回一次；
|
||
- 数据库继续只保存 PBKDF2-SHA-256 慢哈希；
|
||
- 轮换批准后旧前缀和旧秘密立即失效，不存在双密钥宽限窗口；
|
||
- 撤销不可恢复；需要重新授权时必须发起新的签发申请；
|
||
- 申请和审批均进入透明事件链，但秘密、哈希值和原始审批备注不进入事件元数据；
|
||
- 每个活动客户端最多一项待审批轮换或撤销申请，由部分唯一索引强制。
|
||
|
||
## 5. SLO 自动升级与人工接管
|
||
|
||
- 扫描成功率、通知终态成功率和多地域验签成功率继续使用快速、中速、长周期燃烧率；
|
||
- warning/critical/exhausted 告警自动创建或升级 `manual_review` 队列工单；
|
||
- 工单与告警通过 `handoff_case_id` 关联，并保存最小化 SLO 快照；
|
||
- 工单进入现有工作日历 SLA、值班轮换、换班/请假例外、外部升级通知和事件账本；
|
||
- 自动路由不计作人工首次响应；只有管理员确认、分派、开始处理等动作写入首响；
|
||
- SLO 恢复时告警关闭，关联工单自动解决并留下 `slo_recovered` 事件；
|
||
- 每次异常扫描会把仍开放的 SLO 告警视为活动来源，避免工单被错误自动关闭。
|
||
|
||
## 6. 接口与迁移
|
||
|
||
新增管理接口：
|
||
|
||
- `GET|POST /api/v1/admin/pilot-operations/evidence-audit/change-requests`
|
||
- `POST /api/v1/admin/pilot-operations/evidence-audit/change-requests/{change_id}/review`
|
||
- `GET /api/v1/admin/pilot-operations/evidence-transparency/anchors`
|
||
- `POST /api/v1/admin/pilot-operations/evidence-transparency/anchors/run`
|
||
- `POST /api/v1/admin/pilot-operations/evidence-probes/regions/run`
|
||
|
||
升级接口：
|
||
|
||
- `GET /api/v1/public/reliable-decision/transparency-checkpoint` 增加见证法定数；
|
||
- `GET|PUT /api/v1/admin/pilot-operations/policy` 增加锚定开关、间隔和最少见证数；
|
||
- `GET /api/v1/admin/pilot-operations/insights` 的 SLO 告警增加人工接管工单关联；
|
||
- 探针记录增加 `region` 与 `target_name`。
|
||
|
||
迁移版本为 `20260825_0072`，新增审计凭证变更申请表、透明锚定回执表，并扩展运营策略、探针、审计客户端和 SLO 告警字段。
|
||
|
||
## 7. 发布门禁
|
||
|
||
- 空库升级及 `0072 -> 0071 -> 0072` 往返成功；
|
||
- PostgreSQL 生产形态数据库升级至 `0072`；
|
||
- 双人签发、自审拒绝、轮换旧凭证失效、双人撤销自动化测试通过；
|
||
- 两个地域探针均独立留痕，单地域失败进入 SLO；
|
||
- 两个独立见证回执验证通过且法定数计算正确；
|
||
- SLO 告警自动创建人工复核工单，恢复后自动关闭；
|
||
- Contract API 全量测试、Web 测试、TypeScript、OpenAPI 引用检查和生产构建通过；
|
||
- staging 使用真实阿里云/腾讯云 KMS 网关和真实不可变对象存储/见证服务完成正常、超时、无效签名和恢复演练。
|
||
|
||
## 8. 后续边界
|
||
|
||
建议下一阶段进入 P1-07.7：见证者密钥轮换与交叉签名、对象锁/WORM 保留策略证明、跨云探针调度隔离、自动事件指挥官与复盘证据包，以及审计凭证到期前自动轮换申请。
|