Files
ssw-mpc/docs/OPT_PLAN.md
T
rong 471289fe55 feat: 按 SecretFlow 对比结论补齐六条优化 + PostgreSQL 数据接入
影响
- 传输层不再"知道端口就能冒充":PSK 挑战-应答,未配置时显式告警
- 参与方参数不一致可归因(逐字段对表,不再只说"指纹不同")
- 长跑不再整表进内存:CSV 真流式,PG 可直连
- 所有子命令支持 --report json,stdout 只出结构化结果,诊断走 stderr
- 作业支持 DAG 与落盘状态,失败/跳过/重来可追溯
- 计算域抽象落地,dry_run 开关第一次有消费者

改动
- nax-core: 新增 hmac(HMAC-SHA256 / ct_eq / derive_labeled);pg 的 HMAC 改为委托,删重复实现
- nax-node: 新增 auth(REQ/ACK/OK,ctx 绑定双方序号与双 nonce,双 label 防回打)、entropy(只读 /dev/urandom,不降级)
- nax-proto: 新增 Op::Manifest,显式拼字节避开长度前缀错位
- nax-vault: exchange_manifest 比对版本/参与方/fxp/键值清单,三种差异分别点名
- nax-data: 新增 source(TableSource/Batch/CsvSource,流式与整表逐位一致);新增 pg 客户端(自研 wire、trust/md5/SCRAM、零外部依赖)
- nax-orch: 新增 plan(文本计划 + 拓扑校验)、state(append-only JSONL)、run_jobs;协议加 SKIP,单作业模式逐字不变;每作业派生种子避免 Beaver 三元组复用
- nax-runtime: 新增 device(Value/Device/Plain/Secret);域是数据属性,单方搬不回明文;非线性算子在密态域显式拒绝而不是给出错掩码
- nax-cli: 新增 report 模块(Cell/table/kv/note!)、selfcheck(含 TEE 签名)、pg(列类型摊开)、orch run|status
- tools/pg-dev: PGlite + PG-wire 壳、两方种子库、e2e.sh 20 条断言

设计(明确拒绝的方案)
- 设备抽象不做 eval(op) 分发:线性算子对加性分片天然透明,多一层间接只多一个没人用的入口;非线性算子要换协议,不是换指针
- DAG 计划用文本不用 JSON:现场手改要能报"第 2 行:不认识的指令 retries",而 serde_json 与单二进制目标冲突
- 端到端用 PGlite 而非系统 PostgreSQL:同一份源码编成 WASM,无需常驻服务

回归
- cargo test --workspace --features secure → 338 通过 / 0 失败
- cargo build --workspace --all-targets --features secure → 零代码告警
- cargo build -p nax-core --no-default-features → no_std 守线通过
- tools/pg-dev/e2e.sh 两轮真 TCP + 真 PSI + 真密态聚合,两方输出逐字段一致
2026-10-31 21:08:21 +08:00

22 KiB
Raw Blame History

优化计划(源自 docs/COMPARE_SECRETFLOW.md 的缺口清单)

判定依据:COMPARE_SECRETFLOW.md §3 的三档分类。 排序原则:先补「不给客户看」的,再补「改一次就够」的,最后补「有客户才需要」的。 每条都必须独立可验收:cargo test --workspace 全绿 + 零 rustc 告警 + cargo build -p nax-core --no-default-features 通过。


顺序总表

# 事项 为什么排这个位置 依赖 规模
O1 传输认证(PSK 挑战-应答)+ 真随机源 现在任何知道端口的人都能冒充参与者;与任何其它工作都不冲突 — 中
O2 会话参数对表(manifest) 复用 O1 的握手通道;解决「两方参数不一致只报 open 长度不一致」 O1 小
O3 设备抽象(Device / Value::to) 架构分水岭:明文/MPC 不再靠 if 分叉;越晚改越贵 独立 原估中大,实做小(见 §O3 实施)
O4 数据接入接口(分批流 + 多源) 现在整表进内存,真实数据量下用不了 独立 中
O5 报告结构 + 产物自校验 交付形态:机读报告 + 二进制指纹 独立 小
O6 作业 DAG + 状态落盘 运维必需但可等,nax-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), nax-he 的素数、握手 nonce 都无处可取。安全上这是必须先解决的底层能力。

方案

  1. nax-core 新增 hmac.rs:hmac_sha256(key, msg) -> [u8; 32], 固定数组实现、零分配、no_std 可用。(nax-data::pg::crypto 里的那份改为委托, 消除重复实现,golden 仍走原测试。)

  2. nax-node 新增 entropy 模块:fill_random(&mut [u8]) —— Unix 读 /dev/urandom, 失败即报错不降级(安全件不允许「拿时间凑」)。

  3. nax-node 握手升级为三步挑战-应答(connect_mesh_with_psk):

    主动方 A → B : REQ{idx=A, nonce_a}
    B → A        : ACK{idx=B, nonce_b, tag_b = HMAC(psk, "nax/v1/server" ‖ A ‖ B ‖ na ‖ nb)}
    A → B        : OK {tag_a = HMAC(psk, "nax/v1/client" ‖ A ‖ B ‖ na ‖ nb)}
    

    两个 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)

落点 内容 测试
nax-core::hmac hmac_sha256 / ct_eq(定长不提前返回)/ derive_labeled 8 组 python golden + 块长边界 + 域分离,4 测
nax-node::entropy /dev/urandom,非 Unix 明确报错不降级 非恒定 + 空缓冲,2 测
nax-node::auth REQ/ACK/OK 三步,双 label 防回打,失败即 shutdown 全流程/错 PSK/单边/两无/ctx 绑定/标签分离,7 测
nax-node connect_mesh_with_psk、TcpTransport::{connect,accept}_with_psk 存量 14 测未动
nax-cli --psk-file > --psk > NAX_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 长度不一致」或「分片长度不一致」——看不出是谁配错了。本轮已踩过两次。

方案

nax-vault 新增 SessionManifest:参与方列表(排序后)、fxp、协议版本、 列归属清单的 SHA-256。Vault::new 之后调用一次 exchange_manifest(): 双方交换并逐字段比对,不一致时报「字段 X:本方 A,对端 B」。 不改任何算子语义,只在会话开始加一轮往返。

实际做法(与原方案的一处偏离)

原计划传「列结构摘要(32 字节哈希)」,实现时改成键值清单:

vault.exchange_manifest(&[
    ("schema",       "balance,spend"),
    ("agg_col",      "spend"),
    ("pred",         "balance >= 250"),
    ("aligned_rows", "3"),
])

理由:哈希只能回答「不一样」,键值对能回答「pred 不一致,本方有对端没有」—— 后者才是排障要的。同时删掉了原来的「差值分片求和为零」计划指纹 (plan_fingerprint):功能被完全覆盖且更弱,两套并存只会让人不知道该看哪个。

完成情况(2026-10-31)

  • nax-proto:新增 Op::Manifest = 0x03 与 Frame::{manifest,read_manifest}; 单字节字段显式拼字节(用 Writer::bytes 会多加 4 字节长度前缀,踩过一次)。
  • nax-vault:exchange_manifest(&[(k,v)]),比对 协议版本 / 参与方集合 / fxp / 键值清单 (本方有对端无、对端有本方无、值不同,三种都点名),4 测。
  • nax-cli:sql_join 用它替换旧指纹对表,同步更新「漏 --pred」的测试断言。

端到端实测:

  • 一方漏 --pred → 计划参数 \pred` 不一致:本方 "balance >= 250",对端 bob 为 ""`;
  • --fxp 18 vs --fxp 12 → 定点位数不一致:本方 --fxp 18,对端 bob 为 12;
  • 参数一致 → 正常出结果(COUNT=2 / SUM=70)。

验收(对照原计划)

  • fxp 不同 → 点名定点位数 ✅
  • 列结构/参数不同 → 点名具体键(schema / pred / agg_col)✅
  • 一致时通过,开销一轮往返(几百字节)✅
  • 原计划中的「一轮 32 字节」估算偏小:现在是键值文本,几十到几百字节,仍可忽略。

O3 设备抽象

问题

nax-runtime 是一个线程局部 bool(mode.rs),算法里靠 if is_dry_run() { 明文 } else { MPC } 自己分叉。加一种域(HE / TEE)就要改所有算法。

方案

  • nax-runtime 增 device 模块:trait Device { fn kind(&self) -> DeviceKind; }
    • Value(新类型,包 列数据 + 归属方 + 所在设备)+ Value::to(device);
  • 首批两个实现:Plain(就是现在的 dry run 路径)、Secret(转给 nax-vault);
  • 不改现有算法,先给 nax-sql 里的一个算子做迁移示范(where 掩码), 其余保持原路径,避免一次性大改。

验收

  • 同一表达式在 Plain 与 Secret 上结果一致(fxp 容差内);
  • nax-core 的 no_std 守线不受影响(device 只在 nax-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) -> … } 的算子分发, 而这会改到 nax-sql(3519 行) + nax-ml(1688 行) 里每一个算子调用点。 这不是「加一个模块」,是一次跨 crate 重构,且会碰确定性算子的对齐基线。
  3. 有一条更便宜的前置动作。 把 nax-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() 全仓零调用点,nax-runtime 没有任何使用者。 也就是说 O3 描述的「算法里靠 if is_dry_run() 自己分叉」并不存在—— 那个机制是有的,只是从来没被接上。真正缺的不是抽象,是谁来用它。

所以落地的是三件小事,不是一套 trait 分发:

  1. Value 自带域(nax-runtime::device)。域是数据的属性,不是线程全局变量: kind() / fxp() / site() / parties() 跟着值走,值不会「莫名其妙在另一个域里」。
  2. Value::to() 只做跨域搬迁:明文→分片(nax-core::share,带标签派生随机); 分片→明文必须 reconstruct 且集齐全部分片——单方搬不回明文是 MPC 的定义, 不是本实现的限制,所以直接报错而不是「尽力而为」。
  3. 非线性算子显式拒绝:lt_mask 在密态域返回 DeviceError::Unsupported, 信息里点名 nax-sql::secure 的 BitLT。这条是全部价值所在—— 在分片上偷偷跑本地比较,会得到看起来像掩码、其实毫无意义的 0/1, 那是最坏的失败方式。

为什么不做 eval(op) 分发:把算子按「对分片是否透明」分两类,结论很硬——

算子 两域同一份代码? 原因
逐元素加、求和、公开标量缩放/掩码 是 加性分片对加法同态
逐元素乘、比较、除法 否 密态域必须 Beaver / edaBit 交互

线性算子根本不需要分发(多一层间接,少一个使用者);非线性算子需要的是换协议, 不是换指针,trait 分发救不了它。

验收(12 条测试,cargo test -p nax-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 后回退——那个开关第一次有了消费者。

接到产品路径上:nax selftest 增第 5 步「明文域 / 密态域一致性」,每次自检都会真跑一遍 (否则这套东西仍然只是躺在库里的注释)。

nax-core 的 no_std 守线不受影响:device 在 nax-runtime(本来就是 std-only, 用 thread_local),只调用 core 的 share/ring,不进去。

没做的:HEU(同态域)与 TEEU(TEE 域)的实现。它们的 to() 语义与 MPC 完全不同 (HE 的密文可算、TEE 的密钥级授权),等真有接入方再加——现在的 Device trait 只有 kind() 与 secret_params(),加第三个域时不需要改任何现有算子。


O4 数据接入接口

问题

nax-data::pg::load() 与 CSV 读取都是整表进内存;数据源只有两种, 加一种就要改 nax-data 源码。

方案

  • nax-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)

nax-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 报告结构 + 产物自校验

方案

  • nax-cli 加全局 --report json:所有子命令输出统一 {"kind":"table","title":…,"header":[…],"rows":[[…]]};
  • 加 nax selfcheck:打印自身二进制的 SHA-256 与(可选)TEE 签名, 呼应 Kuscia AppImage.ID 的「启动前校验镜像未被替换」。

验收

  • nax fl --report json | jq . 结构合法;
  • nax selfcheck 输出的摘要与 sha256sum $(which nax) 一致。

完成情况(2026-10-31)

crates/nax-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 照常吃。

nax selfcheck:--file / --expect / --out / --tee-sign。 实测 sha256 与 shasum -a 256 逐字符一致;--expect 不符时退出码 1 并打印两侧摘要。

顺带修的三处:

  1. 库往 stdout 打进度。nax-node::log() 和 nax-orch 的 5 处 println! 改成 eprintln! —— 不然后面那些行会混进 JSON 流(实测 nax psi --report json 的 stdout 里夹着「收到对端 5 个盲化点」)。 这是库的通用规矩:诊断走 stderr,stdout 归调用方。
  2. sql_join::print_result → result_cells:打印和 JSON 共用一份格式化, 避免「屏幕上 3、JSON 里 3.0000000001」。
  3. nax lr 帮助里的示例本身是错的(--data-y 给了 6 个值而 --n 3),照抄必报错。

发现一个回归漏洞:cargo test --workspace 不带 --features secure, 于是 nax-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 + 状态落盘

方案

  • nax-orch 的 plan 支持 dependencies(拓扑执行,前序未成功不调度);
  • 状态写 append-only JSONL(<state_dir>/<job>.jsonl),支持 nax orch status <job> 查看「谁在跑、谁失败、从哪重来」。

验收

  • 三任务链 A→B→C,故意让 B 失败 → C 不执行,status 能看出 B 失败原因;
  • 重启 orchestrator 后 status 仍可读(状态不只在内存)。

完成情况(2026-10-31)

三个新模块 / 新命令:

东西 说明
nax-orch::plan 文本计划(job / deps / expect / data),JobPlan::parse + topo()
nax-orch::state append-only JSONL:Event / StateLog / summarize
Orchestrator::run_jobs 按拓扑序跑,依赖没成功就 skip;run() 退化成单作业特例
nax orch run / status 跑 DAG / 只读文件查状态

计划为什么是文本而不是 JSON:读 JSON 要解析器,为几个字段引 serde_json 是 200 KB 的依赖;而且这文件是给人在现场改的,行式格式报错能直接指到行号 (第 2 行:不认识的指令 "retries")。状态那边用 JSONL 是因为消费方是 jq/看板, 方向相反 —— 一个面向人写,一个面向机器读。

每个作业单独派生种子(derive2(master, b"nax-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;nax orch status --state-dir 只读文件就还原出同一结论。

已知限制:每方同一个 --listen 端口会被多个作业反复绑定。实测 macOS 上 「上一轮的接受连接全部关闭后立刻重绑」可行,Linux 上若撞到 TIME_WAIT 需要 SO_REUSEADDR(TcpMesh 目前没设)。真要长跑多作业,应改成 「绑一次 listener,各作业复用」——那要动 TcpMesh 的构造,不在本次范围。


支线:PG 接入(不在 O1–O6 内)

做对比时顺带发现「真实业务库接不进来」,于是有了一条自研 PG 协议客户端的支线。 它与优化计划的六条正交,单独收口:

  • 协议客户端(crates/nax-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 条断言全绿。
  • nax pg:排障用子命令,把列类型(OID / 类型名 / 会不会进 Frame)摊开。 「我查了 5 列,怎么聚合只认 2 列」的答案永远在这张表里。

真正有价值的不是「客户端写完了」,而是第一次有一个不靠自证的验证手段: 假服务端是我们自己写的,拿它测客户端等于自证;PGlite 用的是同一份 PG 源码。


执行约定

  1. 一次只推一条,每条做完即跑全量测试并记录;
  2. 任何一条只要触碰 nax-core 的确定性算子,必须重跑 .venv/bin/python tools/gen_golden.py + cargo test;
  3. 不放宽断言让测试变绿——先确认哪边对;
  4. 每条完成后在 .workbuddy/memory/YYYY-MM-DD.md 记一行结论(不是过程)。