mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-23 20:15:19 +08:00
119 lines
7.1 KiB
Markdown
119 lines
7.1 KiB
Markdown
# ADR-0399：物理 Edge 证据的外部发布归档证明
|
||
|
||
- 状态：Accepted（协议、exact recorder 重建与本地离线验签已实现；18-package/backend/边界门通过，固定物理设备和真实 release ceremony 待执行）
|
||
- 日期：2026-08-14
|
||
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-86、D-196、D-307
|
||
- 关联 ADR：ADR-0088、ADR-0206、ADR-0363、ADR-0398
|
||
|
||
## 上下文
|
||
|
||
物理 Edge 聚合报告已经能绑定设备、数据文件系统、同 boot workload，以及最终
|
||
systemd/OpenRC unit 直接运行的 Node、production application artifact 和 startup
|
||
receipt；但它仍把 `release_archive_signature` 保留为发布 Gate。仅记录 Git revision
|
||
或归档 SHA-256 不足以证明归档、源码 revision、设备实际运行 artifact 与 Node 是同一
|
||
次发布决策；让 QingLong 自己生成并保存发布私钥，又会把构建、签发和验证 authority
|
||
混入低配设备工具。
|
||
|
||
基础 importer 还存在一个较窄的身份绑定缺口：Edge Executor、Node SQLite 和 Plugin
|
||
Package recovery 三个子 workload 虽在 recorder 中由同一进程启动，离线重建时没有逐项
|
||
复验其 platform/architecture。攻击者可以在重算外层摘要后把其他主机报告注入统一报告。
|
||
|
||
## 决策
|
||
|
||
新增非 workspace-package、无第三方依赖、无常驻进程的
|
||
`scripts/ql3-physical-edge-release-evidence.cjs`，根命令为
|
||
`evidence:physical-edge-release`。它只承担确定性载荷生成与验签，不持有或调用私钥。
|
||
|
||
协议分两阶段：
|
||
|
||
1. `prepare` 读取当前 UID 所有、`0600`、无 symlink 的统一物理报告，完整重建其 manifest、
|
||
三个基础 workload、全部 supplemental evidence、qualification 和 SHA-256；必须已有通过的
|
||
direct release service start evidence，并且 `release_archive_signature` 恰好仍缺一次。
|
||
2. 工具以稳定 descriptor 流式读取不超过 64 MiB、不可被 group/other 写入的 release archive，
|
||
生成不带换行的 canonical JSON signing payload。payload 精确绑定 repository、40 位小写
|
||
Git revision、物理报告摘要、设备/boot、归档摘要/字节数，以及实机 direct report 中的
|
||
artifact tree、metadata、entrypoint、Node digest/version。
|
||
3. 发布 operator 在工具之外通过 HSM、KMS、离线机或 OpenSSL 使用 Ed25519 私钥签署 payload
|
||
原始字节。私钥不进入 QingLong data path、配置、环境变量、报告或进程参数。
|
||
4. `finalize` 从调用方固定的 Ed25519 SPKI 公钥重新计算 SHA-256 fingerprint，重新读取并
|
||
计算全部输入，要求 payload 是 exact canonical bytes，再验证 64-byte detached signature。
|
||
source revision、archive 或物理报告任一漂移都失败关闭；输出以 `0600`、no-replace、fsync
|
||
发布。
|
||
|
||
通过的最终 envelope 只把 `release_archive_signature` 替换为
|
||
`release_archive_signature_or_attestation`。它永久保持 `supported:false`，保留原报告中的
|
||
firmware/bootloader、whole-device flash、migration、断电等所有未完成证据。
|
||
|
||
基础 recorder 同时收紧 workload identity：Edge report 的 `host.platform/architecture`、
|
||
SQLite report 的 `platform/arch`、Plugin Package report 的
|
||
`identity.platform/architecture` 必须全部等于统一物理观测值。该检查不增加设备工作量，
|
||
只拒绝跨主机拼接。
|
||
|
||
## Operator ceremony
|
||
|
||
```sh
|
||
pnpm evidence:physical-edge-release -- prepare \
|
||
--physical-report=/opt/qinglong/evidence/physical.json \
|
||
--release-archive=/opt/qinglong/releases/qinglong3-edge.tar.gz \
|
||
--repository=https://github.com/whyour/qinglong.git \
|
||
--revision=<40-lowercase-git-revision> \
|
||
--payload=/opt/qinglong/evidence/release-signing-payload.json \
|
||
--json
|
||
|
||
# 在 QingLong 工具之外签署 exact payload bytes；下面只是一种 operator 实现。
|
||
openssl pkeyutl -sign -rawin \
|
||
-inkey /offline/release-ed25519.key \
|
||
-in /opt/qinglong/evidence/release-signing-payload.json \
|
||
-out /opt/qinglong/evidence/release-signing-payload.sig
|
||
chmod 600 /opt/qinglong/evidence/release-signing-payload.sig
|
||
|
||
pnpm evidence:physical-edge-release -- finalize \
|
||
--physical-report=/opt/qinglong/evidence/physical.json \
|
||
--release-archive=/opt/qinglong/releases/qinglong3-edge.tar.gz \
|
||
--payload=/opt/qinglong/evidence/release-signing-payload.json \
|
||
--signature=/opt/qinglong/evidence/release-signing-payload.sig \
|
||
--trusted-public-key=/etc/qinglong/release-ed25519.pub \
|
||
--expected-repository=https://github.com/whyour/qinglong.git \
|
||
--expected-revision=<40-lowercase-git-revision> \
|
||
--output=/opt/qinglong/evidence/physical-release-evidence.json \
|
||
--json
|
||
```
|
||
|
||
public key 与 archive 必须是 canonical regular file、无 symlink，且 group/other 不可写；
|
||
physical report、payload、signature 必须为当前 UID 所有的 `0600` 文件。所有输入在读取前后
|
||
复验 device/inode/size/mtime/ctime，输出拒绝覆盖已有文件。
|
||
|
||
## 不证明的内容
|
||
|
||
- verifier 不展开 archive，也不自行复现 build；“archive、source 与 runtime artifact 属于同一
|
||
发布”的关系由被信任 operator 的签名证明。
|
||
- 公钥分发、轮换、撤销、透明日志和 signer 组织流程仍由 release authority 负责。
|
||
- 签名不证明固定设备已经采集、firmware/bootloader 起点、exclusive cold cache、整机 CPU
|
||
wakeup、NAND/FTL 写放大、突发断电、adopted migration 或 Cluster 容量。
|
||
- 本地生成的测试 key 和合成物理 fixture 只验证协议，不可作为正式 release evidence。
|
||
|
||
## 被否决的方案
|
||
|
||
1. **把私钥放入仓库或 recorder**：混合签发与验证 authority，并扩大低配设备 Secret 面，拒绝。
|
||
2. **只签 archive digest**：无法绑定 source revision、实机报告和实际运行 artifact，拒绝。
|
||
3. **只信任外层物理报告摘要**：无法阻止可重算摘要下的跨 platform workload 拼接，拒绝。
|
||
4. **验签成功即设置 `supported:true`**：签名只关闭一个 Gate，不能替代剩余物理证据，拒绝。
|
||
5. **为一次性工具新建 workspace package**：没有独立制品、依赖或常驻 authority，违反 package
|
||
边界原则，拒绝。
|
||
|
||
## 验收
|
||
|
||
- exact payload、Ed25519 成功验签、公钥 fingerprint、归档篡改、source mismatch、私有文件
|
||
mode、canonical path、no-replace 和 remaining evidence 由 backend contract test 覆盖。
|
||
- 跨 platform Plugin Package workload 必须使基础物理 candidate 失败。
|
||
- 工具不得新增 workspace package、production dependency、daemon、listener、timer、watcher、
|
||
数据库 migration 或 Edge 常驻导入。
|
||
- 阶段合并前必须通过相关定向测试、18-package clean build/test、完整 backend、package 边界、
|
||
dependency/import 审计和 GitNexus staged change 审计。
|
||
|
||
当前实现完成后，18-package clean build/test 退出 0；完整 backend 为 1,208 项、1,206
|
||
通过、2 条 Linux 条件跳过、0 失败。package boundary 仍为 18 个 package，
|
||
`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Cluster dependency、Edge import、
|
||
service bridge import 与 Cluster deployment 审计均无 finding。以上只验证协议和回归，
|
||
本地合成 fixture 与测试 key 不替代固定设备报告或正式 release signing ceremony。
|