Files
ssw-mpc/docs/OPT_PLAN.md
T
admin 535c63a690
ci / gate (push) Waiting to run
refactor(domain): 协议域分隔常量统一到 mpc-core::domain,nax → mpc
- 20 个 KDF/HMAC/PSI/TEE/分片/作业种子标签全量换 mpc 前缀,集中到 mpc-core::domain 唯一真相源,业务代码不再写裸字符串
- 等长替换,消息格式与长度不变;mpc-tee 的 COMMIT/EGRESS 消息长度改由 label.len() 计算,避免写死数字漂移
- 不兼容变更:会话密钥、TEE 封存 blob、PSI 盲化点、缓存指纹、分片流全部换钥,参与方须同步升级,旧 blob/缓存/离线物料作废;不提供旧 nax 标签兼容读取
- README/CLAUDE/OPT_PLAN 重写兼容约定与迁移清单;仍保留 refs/nax 路径与 Python 包名 import nax(独立只读仓库真实路径)
- golden 向量(ring/paillier/zkp)是纯数学、check_psi.py 只比语义,均不依赖这些标签,无需重生成
- CI 三条闸门全绿(全量测试 / -Dwarnings / mpc-core no_std)
2026-11-05 15:29:33 +08:00

602 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 优化计划(源自 docs/COMPARE_SECRETFLOW.md 的缺口清单)
> 判定依据:`COMPARE_SECRETFLOW.md` §3 的三档分类。
> 排序原则:**先补「不给客户看」的,再补「改一次就够」的,最后补「有客户才需要」的**。
> 每条都必须独立可验收:`cargo test --workspace` 全绿 + 零 rustc 告警 +
> `cargo build -p mpc-core --no-default-features` 通过。
---
## 顺序总表
| # | 事项 | 为什么排这个位置 | 依赖 | 规模 |
|---|---|---|---|---|
| O1 | 传输认证(PSK 挑战-应答)+ 真随机源 | 现在任何知道端口的人都能冒充参与者;与任何其它工作都不冲突 | — | 中 |
| O2 | 会话参数对表(manifest) | 复用 O1 的握手通道;解决「两方参数不一致只报 open 长度不一致」 | O1 | 小 |
| O3 | 设备抽象(Device / Value::to) | 架构分水岭:明文/MPC 不再靠 `if` 分叉;越晚改越贵 | 独立 | 原估中大,实做小(见 §O3 实施) |
| O4 | 数据接入接口(分批流 + 多源) | 现在整表进内存,真实数据量下用不了 | 独立 | 中 |
| O5 | 报告结构 + 产物自校验 | 交付形态:机读报告 + 二进制指纹 | 独立 | 小 |
| O6 | 作业 DAG + 状态落盘 | 运维必需但可等,`mpc-orch` 现在够跑 demo | 独立 | 中 |
**不排期**(见 COMPARE §3.3):XLA 编译栈、Arrow/Flight、K8s CRD、协议后端全插拔、
Python 算法层、BFIA 互操作(有对接需求才做)。
**当前状态**:O1–O6 **全部完成**(O3 收敛成「域边界 + 非线性显式拒绝」,
见 §O3 实施;原计划里的 `eval(op)` 分发被论证为负债,没有做)。
全量回归口径:`cargo test --workspace --features secure`。
---
## O1 传输认证 + 真随机源
### 问题
`TcpMesh::connect_mesh` 的握手只是 `write_party(me)` / `read_party()` ——
**对方说自己是谁就信谁**。任何人都能连上来充当第 j 方,并在 `open` 阶段拿到中间量。
另外会话主种子走 `--seed` argv,进程列表可见。
顺带发现:**整个 workspace 没有任何真随机源**(无 `getrandom`、无 `/dev/urandom`),
`mpc-he` 的素数、握手 nonce 都无处可取。安全上这是必须先解决的底层能力。
### 方案
1. `mpc-core` 新增 `hmac.rs`:`hmac_sha256(key, msg) -> [u8; 32]`,
固定数组实现、零分配、no_std 可用。(`mpc-data::pg::crypto` 里的那份改为委托,
消除重复实现,golden 仍走原测试。)
2. `mpc-node` 新增 `entropy` 模块:`fill_random(&mut [u8])` —— Unix 读 `/dev/urandom`,
**失败即报错不降级**(安全件不允许「拿时间凑」)。
3. `mpc-node` 握手升级为三步挑战-应答(`connect_mesh_with_psk`):
```
主动方 A → B : REQ{idx=A, nonce_a}
B → A : ACK{idx=B, nonce_b, tag_b = HMAC(psk, domain::SESSION_S2C ‖ A ‖ B ‖ na ‖ nb)}
A → B : OK {tag_a = HMAC(psk, domain::SESSION_C2S ‖ A ‖ B ‖ na ‖ nb)}
```
> label 见 `mpc_core::domain` 的 `SESSION_S2C` / `SESSION_C2S`,与 `mpc-node::auth` 的握手实现一致;
> 改任一标签都是协议 breaking change(见 README「命名沿革与兼容约定」)。
两个 tag 用不同 label,防「把对方 tag 原样打回来」。
`connect_mesh(...)` 保持原签名,内部转调 `psk = None`(存量测试不受影响);
有 PSK 时对端没有 PSK 会被拒(**不静默降级**)。
### 验收
- 错 PSK → 连不上,且错误信息说明是认证失败;
- 一方有 PSK、一方没有 → 拒绝(而不是「降级成明文握手」);
- nonce 重放(把收到的 ACK 原样回放)→ 拒绝;
- `hmac_sha256` 与 python3 `hmac` 的 golden 向量一致(新增 4 组:空 key、块长 key、超块长 key、常规);
- 现有两进程 `sql-join` 仍能跑通。
### 完成情况(2026-10-31)
| 落点 | 内容 | 测试 |
|---|---|---|
| `mpc-core::hmac` | `hmac_sha256` / `ct_eq`(定长不提前返回)/ `derive_labeled` | 8 组 python golden + 块长边界 + 域分离,4 测 |
| `mpc-node::entropy` | `/dev/urandom`,非 Unix 明确报错**不降级** | 非恒定 + 空缓冲,2 测 |
| `mpc-node::auth` | REQ/ACK/OK 三步,双 label 防回打,**失败即 shutdown** | 全流程/错 PSK/单边/两无/ctx 绑定/标签分离,7 测 |
| `mpc-node` | `connect_mesh_with_psk`、`TcpTransport::{connect,accept}_with_psk` | 存量 14 测未动 |
| `mpc-cli` | `--psk-file` > `--psk` > `MPC_PSK`,接进 sql-join / psi / node 三条路径 | — |
端到端实测(两个进程):
- 同一 PSK → 跑通,`COUNT=2 / SUM=70 / AVG=35`;
- 错 PSK → 两侧**立即**报 `认证失败: 对端 tag 校验失败`,不再等 120s 读超时;
- 无 PSK → 明确打印 `⚠ 未配置 PSK…不做身份认证`,功能仍可用。
**遗留(明确记录,不是忘了)**:只做了**认证**,没做**加密**。帧载荷仍是
明文分片与 `Open` 的掩码值 —— 半诚实模型下分片本身均匀随机,但 `Open`
的数值会暴露"这一轮传了多长、频率如何"。帧加密(用握手派生的会话密钥)
列为后续项,见 §O7。
---
## O2 会话参数对表(manifest)
### 问题
两方 `--sites` / `--schema` / `--fxp` / `--seed` 任意一项不一致,报的是
「open 长度不一致」或「分片长度不一致」——**看不出是谁配错了**。本轮已踩过两次。
### 方案
`mpc-vault` 新增 `SessionManifest`:参与方列表(排序后)、`fxp`、协议版本、
列归属清单的 SHA-256。`Vault::new` 之后调用一次 `exchange_manifest()`:
双方交换并**逐字段比对**,不一致时报「字段 X:本方 A,对端 B」。
不改任何算子语义,只在会话开始加一轮往返。
### 实际做法(与原方案的一处偏离)
原计划传「列结构摘要(32 字节哈希)」,实现时改成**键值清单**:
```rust
vault.exchange_manifest(&[
("schema", "balance,spend"),
("agg_col", "spend"),
("pred", "balance >= 250"),
("aligned_rows", "3"),
])
```
理由:哈希只能回答「不一样」,键值对能回答「`pred` 不一致,本方有对端没有」——
后者才是排障要的。同时**删掉了**原来的「差值分片求和为零」计划指纹
(`plan_fingerprint`):功能被完全覆盖且更弱,两套并存只会让人不知道该看哪个。
### 完成情况(2026-10-31)
- `mpc-proto`:新增 `Op::Manifest = 0x03` 与 `Frame::{manifest,read_manifest}`;
单字节字段显式拼字节(用 `Writer::bytes` 会多加 4 字节长度前缀,踩过一次)。
- `mpc-vault`:`exchange_manifest(&[(k,v)])`,比对 协议版本 / 参与方集合 / fxp / 键值清单
(本方有对端无、对端有本方无、值不同,三种都点名),4 测。
- `mpc-cli`:`sql_join` 用它替换旧指纹对表,同步更新「漏 --pred」的测试断言。
端到端实测:
- 一方漏 `--pred` → `计划参数 \`pred\` 不一致:本方 "balance >= 250",对端 bob 为 "<none>"`;
- `--fxp 18` vs `--fxp 12` → `定点位数不一致:本方 --fxp 18,对端 bob 为 12`;
- 参数一致 → 正常出结果(`COUNT=2 / SUM=70`)。
### 验收(对照原计划)
- fxp 不同 → 点名定点位数 ✅
- 列结构/参数不同 → 点名具体键(`schema` / `pred` / `agg_col`)✅
- 一致时通过,开销一轮往返(几百字节)✅
- 原计划中的「一轮 32 字节」估算偏小:现在是键值文本,几十到几百字节,仍可忽略。
---
## O3 设备抽象
### 问题
`mpc-runtime` 是一个线程局部 `bool`(`mode.rs`),算法里靠
`if is_dry_run() { 明文 } else { MPC }` 自己分叉。加一种域(HE / TEE)就要改所有算法。
### 方案
- `mpc-runtime` 增 `device` 模块:`trait Device { fn kind(&self) -> DeviceKind; }`
+ `Value`(新类型,包 列数据 + 归属方 + 所在设备)+ `Value::to(device)`;
- 首批两个实现:`Plain`(就是现在的 dry run 路径)、`Secret`(转给 `mpc-vault`);
- **不改现有算法**,先给 `mpc-sql` 里的一个算子做迁移示范(`where` 掩码),
其余保持原路径,避免一次性大改。
### 验收
- 同一表达式在 `Plain` 与 `Secret` 上结果一致(fxp 容差内);
- `mpc-core` 的 no_std 守线不受影响(device 只在 mpc-runtime,不进 core)。
### 复评(2026-10-31,动手前,结论:**降级**)
原计划把它排第三,理由是「越晚改越贵」。真正动手前复核,三条理由推翻这个排序:
1. **第三域还不存在。** 现在只有「明文试跑」和「MPC」两种。`to()` 抽象的收益要等到
有 3+ 种域、且同一个算子要在域间混搭时才显现(SecretFlow 有四域才值得)。
为两种域搭一套 trait,收益是负的 —— 多一层间接,少一个使用者。
2. **Rust 里不能照抄 Python 的形态。** `x.to(spu)` 依赖动态类型 + 运行时对象;
Rust 版必须做成 `trait Eval { fn eval(&mut self, op, args) -> … }` 的**算子分发**,
而这会改到 `mpc-sql`(3519 行) + `mpc-ml`(1688 行) 里每一个算子调用点。
这不是「加一个模块」,是一次跨 crate 重构,且会碰确定性算子的对齐基线。
3. **有一条更便宜的前置动作。** 把 `mpc-runtime` 的分叉从「每个算法自己写
`if is_dry_run()`」收敛成「一处 `mode()` 查询 + 两个具名内部函数」,
能把散落的判断点收拢,几乎零风险,也不阻塞任何东西。先做这个,
等第三域真出现时再抽 trait。
**排序变更**:O4 → O5 → O6 → O3。O3 从「阻塞产品化」移出,改为触发式
(出现第三种计算域,或 `is_dry_run()` 的调用点超过 10 处)。
> 这不是「挑软的做」:判断依据是**当前接入方的数量**,不是改动难度。
> 一个抽象在没有第二个实现者时是负债 —— SecretFlow 敢这么设计,是因为它已经有四个设备。
### 实施(2026-10-31,结论:做了,但只有原计划的 1/3)
动手时先核实了一件事:**`is_dry_run()` 全仓零调用点,`mpc-runtime` 没有任何使用者。**
也就是说 O3 描述的「算法里靠 `if is_dry_run()` 自己分叉」并不存在——
那个机制是有的,只是从来没被接上。真正缺的不是抽象,是**谁来用它**。
所以落地的是三件小事,不是一套 trait 分发:
1. **`Value` 自带域**(`mpc-runtime::device`)。域是**数据的属性**,不是线程全局变量:
`kind() / fxp() / site() / parties()` 跟着值走,值不会「莫名其妙在另一个域里」。
2. **`Value::to()` 只做跨域搬迁**:明文→分片(`mpc-core::share`,带标签派生随机);
分片→明文必须 `reconstruct` 且集齐全部分片——单方搬不回明文是 MPC 的定义,
不是本实现的限制,所以直接报错而不是「尽力而为」。
3. **非线性算子显式拒绝**:`lt_mask` 在密态域返回 `DeviceError::Unsupported`,
信息里点名 `mpc-sql::secure` 的 BitLT。这条是全部价值所在——
在分片上偷偷跑本地比较,会得到**看起来像掩码、其实毫无意义**的 0/1,
那是最坏的失败方式。
为什么不做 `eval(op)` 分发:把算子按「对分片是否透明」分两类,结论很硬——
| 算子 | 两域同一份代码? | 原因 |
|---|---|---|
| 逐元素加、求和、**公开**标量缩放/掩码 | **是** | 加性分片对加法同态 |
| 逐元素乘、比较、除法 | 否 | 密态域必须 Beaver / edaBit 交互 |
线性算子根本不需要分发(多一层间接,少一个使用者);非线性算子需要的是**换协议**,
不是换指针,trait 分发救不了它。
**验收**(12 条测试,`cargo test -p mpc-runtime`):
- `linear_expression_is_device_transparent`:同一表达式(公开掩码 + 求和)在明文域与
两方密态域上**逐位相同**(`to_bits()` 相等,不只是容差内),fxp=0 / fxp=18 各一组;
- `shares_are_not_the_secret`:分片 ≠ 明文,单方 `decode` 被拒;
- `reconstruct_needs_every_share_exactly_once`:少片 / 重号 / 跨域参数不一致都报错;
- `comparison_is_rejected_on_secret_device`:错误类型是 `Unsupported`,信息指路;
- `current_tracks_the_dry_run_switch`:`dry_run()` → 明文域、`real_run()` → 密态域,
guard drop 后回退——**那个开关第一次有了消费者**。
接到产品路径上:`mpc selftest` 增第 5 步「明文域 / 密态域一致性」,每次自检都会真跑一遍
(否则这套东西仍然只是躺在库里的注释)。
`mpc-core` 的 no_std 守线不受影响:device 在 `mpc-runtime`(本来就是 std-only,
用 `thread_local`),只**调用** core 的 `share`/`ring`,不进去。
**没做的**:HEU(同态域)与 TEEU(TEE 域)的实现。它们的 `to()` 语义与 MPC 完全不同
(HE 的密文可算、TEE 的密钥级授权),等真有接入方再加——现在的 `Device` trait 只有
`kind()` 与 `secret_params()`,加第三个域时**不需要改任何现有算子**。
---
## O4 数据接入接口
### 问题
`mpc-data::pg::load()` 与 CSV 读取都是**整表进内存**;数据源只有两种,
加一种就要改 `mpc-data` 源码。
### 方案
- `mpc-data` 引入 `trait TableSource`:`schema()` + `next_batch(&mut self, rows) -> Option<Batch>`;
- CSV / PostgreSQL 各实现一份,`Batch` 是「列名 + 若干列 × N 行」;
- 保留 `load()` 作为便捷包装(内部循环 batches),不破坏现有调用。
### 验收
- 分批读 100 万行 CSV,**峰值内存不随行数线性增长**(以「一次只驻留一个 batch」为断言);
- 现有 `sql-join` 行为不变。
### 完成情况(2026-10-31)
`mpc-data::source`:
| 东西 | 说明 |
|---|---|
| `TableSource` | `columns()` / `next_batch(max_rows)` / `rows_read()`,三方法 |
| `Batch` | 列名 + 行式 `Vec<Vec<f64>>`,不引 Arrow |
| `CsvSource` | **真流式**:`BufReader` 逐行,一次只驻留一个 batch |
| `load()` | 便捷包装:循环 batch 拼 `Frame`,等价改造前行为 |
7 个测试,其中两条是关键:
- `batched_load_matches_whole_file_parse`:流式与一次性解析**逐位相同**(含空行、负数、科学计数法),
否则「流式」就成了另一套语义;
- `streams_large_file_without_accumulating`:20 万行只数不存,单批不超过请求行数。
**没做(明确记录)**:PostgreSQL 仍是「一次物化」。`pg::ResultSet` 走 simple query,
协议一次返回全部 `DataRow`,要做真流式得换 extended query + `Execute` 分页,
属于另一件事。接口先立起来是为了让「下一个数据源」有落点,**不写假流式**。
---
## O5 报告结构 + 产物自校验
### 方案
- `mpc-cli` 加全局 `--report json`:所有子命令输出统一
`{"kind":"table","title":…,"header":[…],"rows":[[…]]}`;
- 加 `mpc selfcheck`:打印自身二进制的 SHA-256 与(可选)TEE 签名,
呼应 Kuscia `AppImage.ID` 的「启动前校验镜像未被替换」。
### 验收
- `mpc fl --report json | jq .` 结构合法;
- `mpc selfcheck` 输出的摘要与 `sha256sum $(which mpc)` 一致。
### 完成情况(2026-10-31)
`crates/mpc-cli/src/report.rs`(新)+ 各子命令接入:
| 东西 | 说明 |
|---|---|
| `report::Cell` | `Text` / `Num{v,prec}` / `Int` / `Bool` / `Null(说明)`;数字单独成类,文本按精度截、JSON 出原始值 |
| `report::table` | 文本模式画对齐表(CJK 按 2 列算宽),JSON 模式出 `{"kind":"table",…}` |
| `report::kv` | `header` 恒为 `key/value` 的简写,多一个 `kind` 让消费方不必猜 |
| `report::note` | **进度行统一出口**:文本→stdout,JSON→stderr |
`--report text|json` 是全局开关(`split_report_flag` 先摘掉再分发,放前后都认)。
已接入的子命令:`selftest`(4 步列表)、`selfcheck`、`node`、`agent`、`cluster`(各方结果表)、
`psi`(交集)、`lr`(权重)、`fl`(逐轮指标 + 权重两张表)、`sql`、`sql-join`(聚合结果)。
多张表就是多行 NDJSON,`jq` 照常吃。
`mpc selfcheck`:`--file` / `--expect` / `--out` / `--tee-sign`。
实测 `sha256` 与 `shasum -a 256` 逐字符一致;`--expect` 不符时退出码 1 并打印两侧摘要。
**顺带修的三处**:
1. **库往 stdout 打进度**。`mpc-node::log()` 和 `mpc-orch` 的 5 处 `println!` 改成 `eprintln!` ——
不然后面那些行会混进 JSON 流(实测 `mpc psi --report json` 的 stdout 里夹着「收到对端 5 个盲化点」)。
这是库的通用规矩:**诊断走 stderr,stdout 归调用方**。
2. `sql_join::print_result` → `result_cells`:打印和 JSON 共用一份格式化,
避免「屏幕上 3、JSON 里 3.0000000001」。
3. `mpc lr` 帮助里的示例本身是错的(`--data-y` 给了 6 个值而 `--n 3`),照抄必报错。
**发现一个回归漏洞**:`cargo test --workspace` 不带 `--features secure`,
于是 `mpc-cli` 的 `sql_join` / `report` 之外那些 secure 测试**一直没跑**。
其中 `tcp_join_plan_mismatch_is_diagnosed` 是坏的(两方 `agg_col` 也不同,
对表先揪出 `agg_col`,永远测不到「漏谓词」)。已修正为只让 `pred` 不同。
**今后的全量回归用 `cargo test --workspace --features secure`**(301 条,比默认的 265 条多 36 条)。
本机没有 `jq`,验收用 `python3 -m json.tool` / `json.loads` 逐行校验代替。
---
## O6 作业 DAG + 状态落盘
### 方案
- `mpc-orch` 的 plan 支持 `dependencies`(拓扑执行,前序未成功不调度);
- 状态写 append-only JSONL(`<state_dir>/<job>.jsonl`),支持
`mpc orch status <job>` 查看「谁在跑、谁失败、从哪重来」。
### 验收
- 三任务链 A→B→C,故意让 B 失败 → C 不执行,`status` 能看出 B 失败原因;
- 重启 orchestrator 后 `status` 仍可读(状态不只在内存)。
### 完成情况(2026-10-31)
三个新模块 / 新命令:
| 东西 | 说明 |
|---|---|
| `mpc-orch::plan` | 文本计划(`job` / `deps` / `expect` / `data`),`JobPlan::parse` + `topo()` |
| `mpc-orch::state` | append-only JSONL:`Event` / `StateLog` / `summarize` |
| `Orchestrator::run_jobs` | 按拓扑序跑,依赖没成功就 `skip`;`run()` 退化成单作业特例 |
| `mpc orch run / status` | 跑 DAG / 只读文件查状态 |
**计划为什么是文本而不是 JSON**:读 JSON 要解析器,为几个字段引 `serde_json` 是
200 KB 的依赖;而且这文件是给人在现场改的,行式格式报错能直接指到行号
(`第 2 行:不认识的指令 "retries"`)。状态那边用 JSONL 是因为消费方是 `jq`/看板,
方向相反 —— 一个面向人写,一个面向机器读。
**每个作业单独派生种子**(`derive2(master, b"mpc-job", job)`)。
不派生就是**重用 Beaver 三元组**:两个作业同一个 seed 起 PRG,拿到的 `(a,b,c)` 一样,
等于一次性掩码用两次,中间量一公开输入就露了。这条不写出来下一个人一定会踩。
失败判定三道关(`judge`):有一方报错 → 各方结果不一致 → 后置条件 `expect` 不符。
中间那道是并行/分片类 bug 的唯一兜底(协议内部不会报错)。
**协议只加了一条 `SKIP`**,结束仍用原来的 `BYE`:老 agent 不读最后那行也能跑,
新 agent 把 `BYE`/`DONE` 都当结束。`PLAN` 的 `job=`/`data=` 是可缺省字段,
缺省时这一行与改造前**逐字相同**,所以单作业模式没有行为变化(三方 demo 仍是 31)。
测试:
- `plan`:环、未知依赖、自依赖、重名、缺名字、空计划、声明序 vs 依赖序;
- `state`:往返、转义、残行跳过并计数、落盘后新实例只读文件恢复;
- `dag_stops_at_failed_job_and_persists_state`:**假 agent** 只走编排协议,
A 成功 / B 后置条件不符 / C 跳过,并核对 `C.jsonl` 里那条 `skip` 的原因点名了 B。
实测(两进程 × 两个真 agent,`/tmp/demo.plan`):`A=35 ok`、`B fail(期望 999 实际 2)`、
`C skip(依赖 B 未成功)`,退出码 1;`mpc orch status --state-dir` 只读文件就还原出同一结论。
**已知限制**:每方同一个 `--listen` 端口会被多个作业反复绑定。实测 macOS 上
「上一轮的接受连接全部关闭后立刻重绑」可行,Linux 上若撞到 `TIME_WAIT`
需要 `SO_REUSEADDR`(`TcpMesh` 目前没设)。真要长跑多作业,应改成
「绑一次 listener,各作业复用」——那要动 `TcpMesh` 的构造,不在本次范围。
---
## 支线:PG 接入(不在 O1–O6 内)
做对比时顺带发现「真实业务库接不进来」,于是有了一条自研 PG 协议客户端的支线。
它与优化计划的六条正交,单独收口:
- **协议客户端**(`crates/mpc-data/src/pg`):StartupMessage + trust/cleartext/md5/
SCRAM-SHA-256 + Simple Query,零外部依赖。手写理由与限制见 `docs/PG.md`。
- **三层验证**:golden 向量(`python3 hashlib` 独立算)→ 假服务端(真 TCP,
三种认证 + 错误注入)→ **真 Postgres**(PGlite)。
- **`tools/pg-dev/`**:PGlite(Postgres 编到 WASM)+ PG-wire TCP 外壳。
`e2e.sh` 起两个独立库跑完整两方密态聚合,20 条断言全绿。
- **`mpc pg`**:排障用子命令,把列类型(OID / 类型名 / 会不会进 `Frame`)摊开。
「我查了 5 列,怎么聚合只认 2 列」的答案永远在这张表里。
真正有价值的不是「客户端写完了」,而是**第一次有一个不靠自证的验证手段**:
假服务端是我们自己写的,拿它测客户端等于自证;PGlite 用的是同一份 PG 源码。
---
## 第二轮:闸门与链路(2026-11-01)
O1–O6 与 PG 支线收口后复看,又挖出五处。这轮按「先立闸门、再补漏洞、最后固数字」排序。
### R1 回归闸门(CI)
**问题**:`CLAUDE.md` 的铁律第一条写着「CI 守 `cargo build -p mpc-core --no-default-features`」,
但仓库里**没有任何 CI 配置**。上一轮就因此漏跑 36 条 `secure` 测试,其中一条是坏的。
**做法**:`tools/ci.sh` 把三条铁律写成脚本,`.gitea/workflows/ci.yml` 只负责调用它 ——
不在这里重写命令,否则 CI 与本地会慢慢分叉。镜像钉在 `rust:1.85`(= MSRV 声明),
顺带验证那个声明是真的。
**没做的**:缓存 `target`(自建 runner 的缓存行为依赖存储配置,加了可能随机失败)、
golden 重生成(依赖 `refs/nax`,CI 里取不到)。
### R2 链路加密(ChaCha20-Poly1305)
**问题**:O1 的 PSK 只解决「谁能连」。握手之后 `Op::Shares`(输入分片)、
`Op::Open`(掩码差值)仍是明文,帧头也没有 per-frame MAC。默认 `--listen 0.0.0.0`
+ 自动 `advertise` 出口 IP,说明设计意图就是跨机部署 —— 那链路大概率不可信。
**做法**:`mpc-core::aead` 自写 ChaCha20-Poly1305(复用 `prg` 已有的 ChaCha20 core,
不另起一套);`mpc-node::auth` 握手时派生**双向独立**会话密钥;`mpc-node::secure`
做帧封装,计数器兼做防重放。
**为什么自己写**:`chacha20poly1305` 会拖进 `cipher`/`aead`/`universal-hash`/`subtle`,
破坏「依赖树为空 → 能编进 TA」这条前提。约 500 行含测试。
**验证**(不只是「能跑」):
- 三条 RFC 8439 官方向量(block / Poly1305 / AEAD)+ 一条 OpenSSL 交叉向量;
- 翻遍每一个字节都必须被拒(`tampered_byte_is_rejected`)、重放被拒;
- 真实两进程加抓包代理对照:无 PSK 的同一会话 **176 个明文帧头 + 2 处 `balance`**,
有 PSK 时 55981 字节里 **0 个帧头、0 处明文字段**。
### R3 熵源统一
**问题**:四处各自读 `/dev/urandom`,其中 `mpc-zkp` 是 **`expect()` panic**,且非 Unix
回退到 `SystemTime`;而隔壁 `mpc-node` 的注释明确写「拒绝用时间戳降级」。同一个仓库两种
安全姿态,迟早有第三处选错边。
**做法**:`mpc-core::osrand`(`#[cfg(feature = "std")]`,no_std 下整模块不存在),
四处改为调用它,各自只翻译错误类型。`mpc-zkp::os_stream()` 改为返回 `Result`。
### R4 Paillier 密钥生成的熵责任
**问题**:`mpc-he::keygen` 的签名是 `keygen(bits, &mut Stream)`,把「必须用 OS 熵播种」
写在注释里 —— 靠文档担保的安全。而且它**全仓没有生产调用点**(只有 tests),
等于 HE 那条路从来没接上过。另外 `assert!(bits >= 16)` 在库函数里 panic。
**做法**:新增 `keygen_os(bits)`(自己取熵,生产入口);`keygen` 保留为确定性版本并在
文档里说明用途(golden / 测试 / 基准);`assert` 改 `Err(KeyTooSmall)`。
### R5 基准固化
**问题**:`docs` 和 memory 里那张 Python-vs-Rust 对照表是临时手测贴上去的 ——
别人复现不了,代码退化了也没人知道。
**做法**:`crates/mpc-core/tests/bench_core.rs`,`#[ignore]`(CI 不跑,runner 上的数字没意义):
```bash
cargo test -p mpc-core --release --test bench_core -- --ignored --nocapture
```
**本机实测(i5-5250U / 双核 / AVX2 已确认可用)**:
| 算子 | 规模 | 耗时 | 吞吐 |
|---|---|---|---|
| 逐元素 mul | 1M u64 | 2.4–4.4 ms | 0.24–0.44 G elem/s |
| 逐元素 add | 1M u64 | 2.6–3.0 ms | 0.35–0.40 G elem/s |
| matmul | 256³ | 30.4 ms | 0.55 G mul-add/s |
| matmul | 512³ | 352–384 ms | 0.35–0.38 G mul-add/s |
| split_into | 1M / 2 方 | 66.9 ms | — |
| reconstruct_into | 1M / 2 方 | 7.2 ms | — |
| ChaCha20 流 | 16 MiB | 71.9 ms | 222 MiB/s |
| AEAD seal | 16 MiB | 110.6 ms | 145 MiB/s |
| AEAD open | 16 MiB | 117.4 ms | 136 MiB/s |
| AEAD seal(小帧) | 1 KiB | 7.55 µs/帧 | — |
**注意**:`matmul 256³` 这次是 **30.4 ms**,与早前记录的 18.0 ms 不符。已确认
`is_x86_feature_detected!("avx2") == true`、走的是 AVX2 路径,差异更可能来自机器状态
(笔记本持续编译后降频 / 内存带宽)。**以后以这条命令的输出为准**,不再引用旧数字。
`split_into` 比 `reconstruct_into` 慢 9 倍,原因是它要先生成 8 MiB 的 PRG 流
(按 222 MiB/s ≈ 36 ms),属于设计使然而非异常。
### R6 PSI 建会话:跨会话盲化缓存
**问题**:`docs/IR.md` §3.4 指出端到端的第一大项是建会话(PSI 的 EC 运算),
1024 行时比整个训练还贵。原因很单纯:两方各做 `2|X|` 次 EC 标量乘,一次
0.1~0.6 ms(Montgomery ladder,逐比特双加),1024 行就是每方 0.2~1.2 s。
而**重复对账场景里,两场会话之间绝大多数 ID 根本没变**。
**做法**:`mpc_psi::cache::BlindCache` + `mpc_node::run_psi_session_accelerated`。
| 层 | 改了什么 | 为什么在这里 |
|---|---|---|
| `mpc-psi` | `blind_points` / `shuffle_perm` 从 `blind_with_domain` 拆出来 | 缓存按元素查、与顺序无关;洗牌只在协议层需要 |
| `mpc-psi` | `BlindCache`:`SHA256(salt‖ID) → k·H(ID,domain)` 与 `P → k·P` 两张表 | 对应协议里的两趟 EC,一个未命中 = 一次标量乘 |
| `mpc-psi` | `strict::relationship_id`:按排序后的名单派生稳定标识 | domain 必须 `全体一致 + 跨会话不变`,排序防止各方算出不同值 |
| `mpc-node` | `PsiAccel { cache, relation }` + `run_psi_session_accelerated` | 默认入口 `run_psi_session` 原样转发 `None`,行为不变 |
**两条设计上的硬约束**:
1. **换密钥或换 domain 必须整表作废**(`bind` 比指纹)。拿旧点算交集会
*恒为空且不报错* —— 本仓第 N 次遇到「静默算错」,所以这里强制断开。
2. **缓存不短路协议**。命中只跳过本方的标量乘;点照发、`strict` 校验照做、
交集照求。对端换集合、换密钥、塞低阶点都照常被发现。
**实测**(`crates/mpc-node/tests/bench_psi_cache.rs`,真 TCP + PSK,同机两线程,
一次运行内三档并排):
| 行数 | 不缓存 | 冷缓存 | 热缓存 | 热/冷 | 热缓存 EC 次数 |
|---|---|---|---|---|---|
| 1024 | 1263 ms | 1298 ms | **5.2 ms** | 250× | 0 |
| 10240 | 9260 ms | 11425 ms | **96.6 ms** | 118× | 0 |
「冷缓存」与「不缓存」同价:冷跑要多做一次哈希(索引)与一次插入,但表是空的、
没有收益,两者差的 0~23% 在本机漂移的噪声里(见 §R8)。
「热缓存」剩的 5.2 ms 是分块收发 + 排序求交 + 每元素一次 SHA-256。
**验收**(`crates/mpc-node/tests/psi_cache.rs`,5 条进 CI):
| 用例 | 守什么 |
|---|---|
| `cached_matches_uncached` | 结果对不对(冷/热两档都与不缓存版逐条相同) |
| `warm_session_needs_no_ec` | 快不快(冷会话 `2n` 次 EC,热会话**不新增**) |
| `incremental_add_costs_one_ec` | 增量真的是增量(多一条 ID = 多一次 EC) |
| `per_session_relation_means_no_cache_hits` | **反向守卫**:domain 改回每场一换,结果仍对但命中归零 |
| `n_way_cached_matches_uncached` | 三方环协议下同样成立(每方 `3n` 次,热归零) |
最后一条是刻意的:把 domain 改回会话级,前四条里的三条照样绿,只有它会红。
**代价(写清不美化)**:
* **跨会话可关联** —— 同一个 ID 在与同一对端的所有会话里是同一个点。这是
缓存的前提,也是 `strict::session_domain` 当初要挡的东西。默认不启用。
* **预计算表恢复可用** —— 表建一次、对这对端永久有效。前提是知道盲化密钥
(表输入是 `H(ID)`,线上是 `k·H(ID)`),所以主要威胁「密钥泄漏后翻历史流量」。
* **缓存内容不新增暴露面**:两张表存的都是本来就要发到线上的点。真正要小心的是
**索引**,所以索引用 `SHA256(salt‖ID)`、`salt` 由密钥派生,脱离密钥不可字典反查。
**没做的**:
* **落盘**。一次一进程的 `mpc psi` 用不上缓存,所以 CLI 没有开关;缓存目前只对
「同一进程反复开会话」的部署(常驻 node / 批处理)有意义。要落盘得先定文件
生命周期、权限与原子写 —— 那是安全决策,不塞进这一轮。
* **接进 `run_lr_vertical_session`**。纵向 LR 每场只跑一次 PSI,缓存对它没有收益。
### R7 换曲线表示:Ristretto(**量过了,值得做,未做**)
**问题**:R6 之后 EC 次数归零只在「热」的时候成立;**每个关系的第一场会话仍然要
全额付 EC**,而这一次是客人感知到的首屏延迟。
**量到的**(`crates/mpc-psi/tests/bench_ec.rs`,`--ignored`):
| 路径 | 乘 | 映射到点 | 压回 32 字节 | 合计 |
|---|---|---|---|---|
| 现状:Montgomery ladder | 0.088 ms | ~0.002(SHA-256) | 0(就是 u 坐标) | **0.090 ms** |
| Edwards 窗口法 | 0.040 ms | 0.0056(+约 50% 重试) | ~0.003 | 0.051 ms |
| Ristretto 窗口法 | 0.040 ms | 0.0122(Elligator) | 0.0059 | **0.058 ms** |
窗口法快 2.2×,映射/解压只吃掉其中一小部分 → **合计 1.55~1.75×**。
**注意这条推翻了一个预判**:动手前我判断「映射到点的钱会吃掉窗口法的收益,
所以不值」。实测不成立。这已是本仓第三次同类失误(前两次:「树形不省轮数」、
「逐项截断省 3 个往返」),共同点都是**只估了一边、没把两边都量出来**。
**为什么选 Ristretto 而不是更快的 Edwards**:
1. 素数阶群 —— 没有 cofactor / 扭曲线 / 8-torsion,`strict::SMALL_ORDER_U`
那张黑名单可以整张删掉;
2. `RistrettoPoint::from_bytes` 对非规范/低阶编码**直接失败**,于是「拒绝非法点」
从「枚举已知坏值」变成「解码即校验」,是完备的。
**为什么这一轮不做**:它是线格式变更(32 字节 Montgomery u → 32 字节 Ristretto
压缩点),新旧实现不能混跑,`strict` 的三道硬化要重写、所有钉住点值的测试要重跑。
值得单独一轮,不该塞在缓存后面。
### R8 基准结果的漂移(记录,不是待办)
同一份代码、同一台机、隔几小时:`bench_lr_tcp` 的 1024 行建会话
**466 ms → 990 ms**,每次迭代 **10.65 ms → 79.73 ms**。差 2~8×,且两个数字的
倍率不同(等待 2.3×、迭代 7.5×)—— 说明降的是本地算术的时钟,不是网络。
**约定**:本机毫秒数**只在同一次运行内横向比**;跨次、跨机一律引**比值**。
`docs/IR.md` §3.4 已加了两组读数的对照表,新的基准都把三档放在一次运行里跑。
---
## 执行约定
1. **一次只推一条**,每条做完即跑全量测试并记录;
2. 任何一条只要触碰 `mpc-core` 的确定性算子,必须重跑
`.venv/bin/python tools/gen_golden.py` + `cargo test`;
3. **不放宽断言让测试变绿**——先确认哪边对;
4. 每条完成后在 `.workbuddy/memory/YYYY-MM-DD.md` 记一行结论(不是过程)。