diff --git a/Cargo.lock b/Cargo.lock index 04ec11a..a485110 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -85,6 +85,7 @@ name = "nax-fl" version = "0.1.0" dependencies = [ "nax-core", + "nax-vault", ] [[package]] diff --git a/README.md b/README.md index 2ced390..b0aa761 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ | `nax-node` TCP 会话 | ✅ 网状 n 方 + 两方便捷路径,5 单测(真实 TCP,含三方端到端、10 万元素粘包、PSI) | | `nax-psi` 隐私求交 | ✅ X25519 ECDH-PSI,10 单测(含 RFC 7748 向量、1 万条求交) | | `nax-zkp` 零知识证明 | ✅ Schnorr 身份证明 + Pedersen 承诺/表示证明,逐位 golden(5 测,含篡改必败) | -| `nax-fl` 联邦聚合 + DP + FedAvg | ✅ 安全聚合责任链(Clip/Zero/SecureSum/Mean/GaussianNoise)+ 差分隐私(RDP 记账)+ 横向 FedAvg(local_train/metrics/加权均值/收敛轨迹),12 测含 4 逐位 golden | +| `nax-fl` 联邦聚合 + DP + FedAvg | ✅ 安全聚合责任链(Clip/Zero/SecureSum/Mean/GaussianNoise)+ 差分隐私(RDP 记账)+ 横向 FedAvg(local_train/metrics/加权均值/收敛轨迹),12 测含 4 逐位 golden;`--features secure` 另有 2 方 Vault 密态加权均值端到端 1 测 | | `nax-ml` 纵向 LR + MLP + 分箱 | ✅ sigmoid 奇多项式 + Beaver SGD(明文对照 >0.95);MLP 前向/反向/二分类 4 测;异构分箱 + WOE/IV + 互补抑制 6 测 | | `nax-data` 数据层 | ✅ Frame(选择/矩阵/列和)+ 明文统计(均值/方差/协方差/相关)+ mock(确定性主键/schema 合成/DP)+ CSV,16 测 | | `nax-sql` SCQL 引擎 | ✅ 手写解析器 + 掩码式 WHERE + 聚合/GROUP BY/k-匿名/投影约束/JOIN/HAVING/ORDER BY,15 测 | diff --git a/crates/nax-fl/Cargo.toml b/crates/nax-fl/Cargo.toml index 25fbb3c..fa55630 100644 --- a/crates/nax-fl/Cargo.toml +++ b/crates/nax-fl/Cargo.toml @@ -8,3 +8,9 @@ rust-version.workspace = true [dependencies] nax-core = { workspace = true } +# 可选:把安全聚合接到真实的 Vault 密态算子上(2 方/多方 Beaver 乘 + 截断)。 +# 默认关闭,保持 nax-fl 明文层零密码学依赖。 +nax-vault = { path = "../nax-vault", optional = true } + +[features] +secure = ["dep:nax-vault"] diff --git a/crates/nax-fl/src/lib.rs b/crates/nax-fl/src/lib.rs index b9c1d06..647e3ac 100644 --- a/crates/nax-fl/src/lib.rs +++ b/crates/nax-fl/src/lib.rs @@ -26,6 +26,9 @@ use nax_core::prg::Stream; pub mod fedavg; pub mod linear; pub mod metrics; +/// 把加权均值接到真实 Vault 密态算子(`feature = "secure"`)。 +#[cfg(feature = "secure")] +pub mod secure; // ─────────────────────────── 基础向量运算 ─────────────────────────── diff --git a/crates/nax-fl/src/secure.rs b/crates/nax-fl/src/secure.rs new file mode 100644 index 0000000..0700608 --- /dev/null +++ b/crates/nax-fl/src/secure.rs @@ -0,0 +1,157 @@ +//! 安全聚合:把 FedAvg 的加权均值接到真实的 [`nax_vault::Vault`] 密态算子上。 +//! +//! 这是 nax-fl 明文聚合链([`crate::weighted_mean`])的**密态对应**。聚合按样本数加权: +//! +//! ```text +//! Δ̄ = Σ nᵢ·Δᵢ / Σ nᵢ +//! ``` +//! +//! 全程只用 Vault 已有原语:`mul_trunc`(Beaver 乘 + 定点截断)、`add_local`(本地加)、 +//! `reveal`(打开总样本数,公开量)、`scale_public`(乘 1/Σn)、`truncate`。 +//! **不需要安全比较**——这正是 FedAvg 比 SQL/分箱更容易先密态化的原因。 +//! +//! 输入是**本方持有的分片**(对方的 `Δᵢ`、`nᵢ` 分片在网络另一侧)。调用方负责: +//! 1. 用 `vault.split` 把明文编码后的 `Δᵢ`/`nᵢ` 切成平铺分片; +//! 2. 本方取自己那一片、发对方那一片; +//! 3. 两方各自调用本函数,最后 `reveal` 结果并 `ring::decode`。 +//! +//! 只在 `feature = "secure"` 下编译,默认构建不引入 `nax-vault`。 + +use nax_core::ring; +use nax_vault::{Transport, Vault, VaultError}; + +/// 用本方分片计算「按样本数加权平均」`Σ nᵢ·Δᵢ / Σ nᵢ`。 +/// +/// * `delta_shares[i]`:第 i 个客户端的 `Δᵢ` 分片(fxp 尺度,长度 d); +/// * `count_shares[i]`:第 i 个客户端的样本数 `nᵢ` 分片(标量,长度 1)。 +/// +/// 返回结果分片(fxp 尺度)。总样本数是非负公开量,会被 `reveal` 一次。 +pub fn weighted_mean_shares( + vault: &mut Vault, + delta_shares: &[Vec], + count_shares: &[Vec], +) -> Result, VaultError> { + if delta_shares.is_empty() { + return Err(VaultError::Protocol("没有客户端更新".into())); + } + if delta_shares.len() != count_shares.len() { + return Err(VaultError::Protocol(format!( + "delta 与 count 的客户端数不一致:{} vs {}", + delta_shares.len(), + count_shares.len() + ))); + } + let d = delta_shares[0].len(); + if d == 0 { + return Err(VaultError::Protocol("delta 维数为 0".into())); + } + if count_shares.iter().any(|c| c.len() != 1) { + return Err(VaultError::Protocol("count 分片必须是标量(长度 1)".into())); + } + let fxp = vault.fxp(); + + let mut acc_delta = vec![0u64; d]; + let mut acc_count = vec![0u64; 1]; + for (ds, cs) in delta_shares.iter().zip(count_shares) { + if ds.len() != d { + return Err(VaultError::Protocol("各客户端 delta 维数不一致".into())); + } + // 把样本数的共享标量广播成 len d,逐元素 Beaver 乘 nᵢ·Δᵢ(结果仍在 fxp 尺度) + let c_rep = vec![cs[0]; d]; + let contrib = vault.mul_trunc(&c_rep, ds)?; + acc_delta = vault.add_local(&acc_delta, &contrib)?; + acc_count = vault.add_local(&acc_count, cs)?; + } + + // 总样本数是公开量:打开后当标量用(这也是 k-匿名/审计里已出域的量) + let total_raw = vault.reveal(&acc_count)?[0]; + let total = ring::decode(total_raw, fxp); + if !(total > 0.0) { + return Err(VaultError::Protocol(format!("总样本数非正: {total}"))); + } + + // × (1/Σn) 得到 2·fxp 尺度的分片,再截回 fxp + let scaled = vault.scale_public(&acc_delta, 1.0 / total)?; + vault.truncate(&scaled) +} + +#[cfg(test)] +mod tests { + use super::*; + use nax_vault::Pipe; + use std::thread; + + /// 2 方 in-process 端到端:密文加权均值必须等于明文 `weighted_mean`。 + #[test] + fn secure_weighted_mean_matches_plaintext() { + let (pa, pb) = Pipe::pair(); + let sites = ["alice", "bob"]; + let fxp = 18u32; + let seed = [7u8; 32]; + + let mut va = Vault::new(pa, "alice", &sites, seed, fxp).unwrap(); + let mut vb = Vault::new(pb, "bob", &sites, seed, fxp).unwrap(); + + // 两个客户端的更新量与样本数 + let deltas = [vec![0.5f64, 1.0], vec![-0.25, 0.5]]; + let counts = [10.0f64, 30.0]; + + // 由 alice 侧 split 出平铺分片,手工切给两方(同一次 split 才互补) + let mut d0 = Vec::new(); + let mut d1 = Vec::new(); + let mut c0 = Vec::new(); + let mut c1 = Vec::new(); + for (dv, &n) in deltas.iter().zip(&counts) { + let enc_d: Vec = dv.iter().map(|v| ring::encode(*v, fxp).unwrap()).collect(); + let dl = enc_d.len(); + let all = va.split(&enc_d).unwrap(); + d0.push(all[0..dl].to_vec()); + d1.push(all[dl..2 * dl].to_vec()); + + let enc_c = vec![ring::encode(n, fxp).unwrap()]; + let allc = va.split(&enc_c).unwrap(); + c0.push(allc[0..1].to_vec()); + c1.push(allc[1..2].to_vec()); + } + + let ha = thread::spawn(move || { + let res = weighted_mean_shares(&mut va, &d0, &c0).unwrap(); + va.reveal(&res).unwrap() + }); + let hb = thread::spawn(move || { + let res = weighted_mean_shares(&mut vb, &d1, &c1).unwrap(); + let _ = vb.reveal(&res).unwrap(); + }); + let got = ha.join().unwrap(); + hb.join().unwrap(); + + let want = crate::weighted_mean(&[(deltas[0].clone(), counts[0]), (deltas[1].clone(), counts[1])]); + // want = (10*[0.5,1] + 30*[-0.25,0.5]) / 40 = [-0.0625, 0.625] + assert!((want[0] + 0.0625).abs() < 1e-12); + assert!((want[1] - 0.625).abs() < 1e-12); + // 定点误差上界:`scale_public(·, 1/Σn)` 把系数编码到 fxp 时四舍五入, + // 误差被分子 |Σn·Δ| 放大到 ~|ΣnΔ|·2^-fxp 量级;mul_trunc/truncate 再各加 1 单位。 + // 按 (|ΣnΔ|+1)·2^-fxp 取容差,是理论界而非随手放宽。 + let d = want.len(); + let num_max = (0..d) + .map(|i| { + deltas + .iter() + .zip(&counts) + .map(|(dv, c)| dv[i] * c) + .sum::() + .abs() + }) + .fold(0.0, f64::max); + let tol = (num_max + 1.0) * 2f64.powi(-(fxp as i32)); + for (i, &g) in got.iter().enumerate() { + let v = ring::decode(g, fxp); + assert!( + (v - want[i]).abs() < tol, + "第 {i} 项: 密文 {v:.8} vs 明文 {:.8}(差 {:.2e},容差 {tol:.2e})", + want[i], + (v - want[i]).abs() + ); + } + } +} diff --git a/docs/GAP_PLAN.md b/docs/GAP_PLAN.md index 5a99e24..5326faa 100644 --- a/docs/GAP_PLAN.md +++ b/docs/GAP_PLAN.md @@ -68,3 +68,12 @@ Python 参考版 `nax/` 共 **8,963 行**。此前约 **4,150 行(≈46%)未 - **#8 策略/审计/守卫(✅ 完成)**:新建 `nax-policy` crate,对齐 `policy/{audit,guard}.py`。`Label` 六档(plain/share/cipher/masked/public/released)+ MOVABLE/FETCHABLE 集合;`AuditEvent`/`AuditLog`(record/filter/summary/dump/clear,超上限裁半);`Guard` 三关口(check_exec / check_transfer / check_fetch,协议内部 `internal` 豁免,拒绝即记 denied 事件并返回 `PrivacyViolation`)。9 测全绿。 - **#9 dry_run 模式(✅ 完成)**:新建 `nax-runtime` crate,对齐 `runtime/mode.py`。线程局部 `DRY_RUN`/`DRY_HOST`/`DRY_FXP` + RAII guard(`dry_run(host, emulate_fixed_point)` / `real_run()`),drop 恢复上一层状态,支持嵌套与并发隔离。4 测全绿(默认、进入/退出、嵌套恢复、real_run 临时覆盖)。 - **9 个优先块全部完成**:Python 参考里约 46% 未 port 的算法层已补齐,`cargo test --workspace` 212 测全绿。 + +## 集成层(第一刀:安全 FedAvg) + +明文层验证的是**语义正确性**;集成层验证它确实能跑在密态算子上。先挑依赖最少的一块: + +- **`nax-fl` 加可选 `secure` feature**(拉 `nax-vault`,默认关闭,保持明文层零密码学依赖):`secure::weighted_mean_shares` 用 `mul_trunc`(Beaver 乘 + 定点截断)+ `add_local` + `reveal`(打开公开的总样本数)+ `scale_public`(1/Σn) + `truncate` 计算 `ΣnᵢΔᵢ/Σnᵢ`,**不需要安全比较**。 +- 2 方 in-process 端到端测试(`Pipe::pair()` 双线程)对着明文 `weighted_mean` 验证,`cargo test -p nax-fl --features secure` 13 测全绿。误差落在定点精度理论上界 `(|ΣnΔ|+1)·2^-fxp` 内。 +- 为什么先做 FedAvg 而不是 SQL/分箱:后两者依赖 `_bit_lt`/`_bit_eq`(交互式 BitLT),`nax-vault` 目前**没有**安全比较,`nax-core::compare` 只给了本地步骤。补 BitLT 是独立的大块密码学工作,不混在这次集成里。 +- 集成层后续:给 `nax-vault` 补 `bit_lt`/`bit_eq`/`bit_mask`(驱动 `nax-core::compare` 的 edaBit + 后缀积 + msb 组合),再把 `nax-sql`/`nax-ml::binning` 接上去。