Files
ssw-mvp/nax
admin 41f460539d feat(zkp): 新增零知识证明算子,算子集市与 SSWFlow 目录对齐
- nax.crypto.zkp:真实 Schnorr 非交互身份证明(Fiat-Shamir)+ Pedersen 承诺与知识证明,基于 769-bit 安全素数群,纯标准库
- demo/zkp:交互式演示面板(L2),含两类证明的逐阶段推导 + 数据空间合规用例
- demo/server.py:注册 zkp_bp;index.html 新增卡片、算子计数 22→23
- SSWFlow 对齐(运行时生效,boot 子树下文件被 gitignore):catalog.json 增加 zkp.prove 算子(新分类 零知识证明);nax_adapter.py 增加 op_zkp 与 DISPATCH 条目

对齐诊断:此前 demo 与 SSWFlow catalog(18 算子)存在偏差——demo 多了 PIR/Paillier/OLE/DP/密文比较/策略审计等 nax 能力未作为 DAG 节点暴露,且缺失 source/prep.*/stat.iv/model.predict/sink.export/tee 等 SSWFlow 算子;本次 ZKP 在两侧同步新增。
2026-08-11 14:25:27 +08:00
..
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00
2026-08-05 18:29:12 +08:00

Nax

N-arty Arithmetic eXecution —— 多方算术执行

基于 Ray 的轻量隐私计算框架 —— 秘密分享、同态加密、隐私求交、联邦学习、密态 SQL。

Nax 想回答一个问题:几家机构手里各有一部分数据,谁都不肯把明文交出去, 怎么才能一起算出结果?

import numpy as np, nax

nax.init(["alice", "bob"], backend="local")
alice, bob = nax.site("alice"), nax.site("bob")
box = nax.vault([alice, bob])

x = box.share(alice.put(np.array([1.0, 2.0, 3.0])))   # alice 的数据,切成分片
y = box.share(bob.put(np.array([4.0, 5.0, 6.0])))     # bob 的数据,切成分片

z = (x * y + 1.0).sum()                               # 全程在密文上算

print(z.reveal(to=alice).fetch())                     # 33.0

整个过程里,alice 看不到 bob 的数字,bob 也看不到 alice 的, driver 进程更是什么都拿不到——除非你显式 reveal。


目录


装一下

git clone <this-repo> && cd nax
pip install -e ".[dev]"      # numpy + pandas + pytest + ray

只想单机跑的话,ray 是可选的:

pip install -e .             # 仅 numpy + pandas,用 local 后端

跑测试:

pytest -q                    # 278 个用例,约 30 秒

跑起来

examples/ 下有 11 个能直接执行的例子,从简到繁(另有一个 k8s 分布式部署示例 examples/12_k8s_two_party/,演示两个 Pod 各跑一个参与方的真实形态):

python examples/01_hello_mpc.py          # 密文四则运算、矩阵乘、sigmoid
python examples/02_psi_join.py           # ECDH-PSI 求交与样本对齐
python examples/03_vertical_lr.py        # 纵向联邦逻辑回归(全程密文训练)
python examples/04_horizontal_fedavg.py  # 横向 FedAvg + 两种安全聚合
python examples/05_policy_audit.py       # 出域策略守卫与审计日志
python examples/06_dp_fedavg.py          # 差分隐私联邦(RDP 记账,隐私预算 ε)
python examples/07_secure_mlp.py         # 密文域 MLP 训练 + 安全统计 + 存盘重载
python examples/08_pir.py                # 1-out-of-N 隐匿查询(Paillier)
python examples/09_scql.py               # 密态 SQL:跨方 JOIN + GROUP BY + k-匿名
python examples/10_hetero_binning.py      # 纵向联邦分箱 + WOE / IV
python examples/11_dry_run.py             # 双阶段执行:同一代码真实 MPC 与明文试跑

想验证真实分布式(两个 k8s Pod 各跑一个参与方,数据不出域),见 examples/12_k8s_two_party/(构建镜像 + kubectl apply 即可,详见其 README)。

想验证真实分布式,加个环境变量就换到 Ray:

NAX_BACKEND=ray python examples/03_vertical_lr.py

同一套代码,两种后端,不用改一行业务逻辑。


设计思路

1. 明文归明文,密文归密文——用类型分开

大多数隐私计算的事故,不是密码学被攻破,而是有人不小心把明文 print 了出来。 Nax 让「数据在哪、能不能动」变成类型系统里的事:

类型 含义 能 fetch 到 driver 吗
SiteRef 某一方本地的明文 ❌ 默认拒绝
SecretRef 秘密分享后的分片集合 ❌ 拒绝(分片本身也不行)
SiteRef(released 标签) 显式 reveal 出来的结果 ✅ 允许

你写不出「不小心泄露」的代码——因为它根本过不了守卫。

2. 三个关口,收敛所有数据流动

                   ┌──────────────┐
   run_at ────────▶│ check_exec   │  A 的任务能读 B 的数据吗?
                   ├──────────────┤
   transfer ──────▶│check_transfer│  数据能从 A 搬到 B 吗?
                   ├──────────────┤
   fetch ─────────▶│ check_fetch  │  数据能离开集群吗?
                   └──────────────┘
                          │
                          ▼
                     AuditLog(每一次都留痕)

协议内部(分片传递、Beaver 三元组、PSI 双盲)走 internal=True 豁免, 因为那些路径上流的是随机数,不是明文。

3. Ray 只是底座,不是耦合

nax/runtime/backend.py
    ├── LocalBackend   单进程字典,秒起,方便调试与 CI
    └── RayBackend     每个参与方一个 Ray Actor,可绑定到指定物理节点

Backend 是一个只有 4 个方法的抽象类(start / put / run / get)。 业务层完全不知道 Ray 的存在,将来接 gRPC / 真实多机部署也只是加一个后端。

生产部署时可以把参与方钉在各自机构的物理机上:

nax.init({
    "bank":  {"resources": {"bank_node": 1}},
    "insur": {"resources": {"insur_node": 1}},
}, backend="ray", address="ray://head:10001")

三种设备

Site —— 明文域

「某机构自己的机器」。上面跑的函数看到的是明文,但这些明文出不去。

alice = nax.site("alice")

df   = alice(pd.read_csv)("/data/alice.csv")   # 在 alice 机器上读文件
n    = alice(len)(df)                          # 继续在 alice 上算
stat = alice(lambda d: d.describe())(df)

n.fetch()          # ✗ PrivacyViolation:明文不得出域
alice(len)(df)     # ✓ 自己算自己的,随便
bob(len)(df)       # ✗ PrivacyViolation:bob 不能读 alice 的明文

Vault —— 安全域

多方共同构成的虚拟计算机。数据一进来就被切成加性分片, 之后所有运算都在 Z_{2^64} 上做定点算术。

box = nax.vault(["alice", "bob", "carol"])

x = box.share(alice.put(arr))     # 明文 → 分片
y = box.share(bob.put(arr2))

z = x * y                # Beaver 三元组,一轮交互
z = x @ m                # 密文矩阵乘(公开矩阵则是纯本地运算)
z = x.sum(axis=0)        # 线性算子,零通信
z = box.sigmoid(x, degree=7)      # 多项式逼近

z.reveal(to=alice)       # 唯一的出口

SecretRef —— 分片的逻辑引用

它自己不含任何数据,只记录「哪几方各持有一片」。 运算符全部重载过,写起来跟 numpy 差不多:

w = (x - y) * 0.5 + 1.0
loss = ((pred - label) * (pred - label)).mean()

密态 SQL(SCQL)

数据在两家,问题却是一句很普通的业务 SQL:

box = nax.vault(["bank", "shop"])
q = nax.sql.SecureSQL(box, reveal_to="bank", min_group_size=5)

q.register("bank", site="bank", data=bank_df, key="uid",
           categorical={"city": ["北京", "上海", "广州", "深圳"]})
q.register("shop", site="shop", data=shop_df, key="uid")

q("""SELECT bank.city, COUNT(*) AS n, AVG(shop.spend) AS avg_spend
     FROM bank JOIN shop ON bank.uid = shop.uid
     WHERE bank.age >= 30 AND shop.spend > 100
     GROUP BY bank.city ORDER BY avg_spend DESC""")
bank.city  n  avg_spend
       深圳 11 414.163441
       广州  6 387.522953
       北京  6 271.027065
       上海 11 268.141472

两张表从头到尾没有合并过。三条与明文数据库根本不同的执行语义:

明文 SQL 的做法 Nax 的做法 为什么
JOIN 物理合表 ECDH-PSI 对齐行序 双方只知交集,不知对方多出哪些人
WHERE 删掉不满足的行 求值成一列共享 0/1 位,聚合时当权重乘 剩下多少行本身就泄露选择率
GROUP BY 扫描出有哪些取值 取值域必须在 register() 里预先声明 「有哪些组、每组几个人」是一次泄露,得让人明示同意

方言是受限的(这是特性,不是坑)

支持:SELECT 聚合(COUNT / SUM / AVG / MIN / MAX)、单表或两表等值 JOIN、 WHERE(AND / OR / NOT / 比较 / IN)、GROUP BY、HAVING、ORDER BY、LIMIT、 聚合内外的四则运算。

直接拒绝(抛 SQLSyntaxError 或 PrivacyViolation):

SELECT * FROM bank                                  -- 星号 = 整表导出
SELECT bank.age FROM bank                           -- 裸机密列 = 逐行泄露
SELECT bank.age, COUNT(*) FROM bank GROUP BY bank.age  -- 分组列取值域未公开
SELECT ... FROM a LEFT JOIN b ON ...                -- 外连接泄露未匹配行
SELECT DISTINCT / 子查询 / UNION / LIKE / 窗口函数     -- 未实现,不做危险的降级

拒绝比支持更重要——一个悄悄把 SELECT balance 当查询执行的引擎, 才是真正的事故来源。

k-匿名

min_group_size=k 时,命中行数不足 k 的分组连 COUNT 都不解密, 结果表里显式标一列 suppressed=True:

bank.city  bank.risk   n         a  suppressed
       北京          1 NaN       NaN        True     ← 人太少,整组不出域
       上海          2 7.0 49.285522       False

抑制本身是可见的(这是 k-匿名的标准语义),但组内数据一个字节都没出来。

看清楚再执行

print(q.explain("SELECT bank.city, COUNT(*) AS n FROM bank JOIN shop ..."))
query : SELECT bank.city, COUNT(*) AS n FROM bank JOIN shop ON bank.uid = shop.uid ...
join  : PSI on bank.uid = shop.uid
where : ((bank.age >= 30) AND (shop.spend > 100))   → 密态 0/1 掩码,不做物理过滤
group : ['bank.city']
reveal: → bank

explain() 不执行、不出域,只告诉你这次查询会泄露什么。 每条真正执行的查询都会在审计日志里留下一条 sql 事件。


能力清单

密码学原语(nax/crypto/)

模块 内容
ring.py Z_{2^64} 定点算术:编解码、加减乘、矩阵乘、算术右移
share.py 加性秘密分享;Beaver 乘法/矩阵乘三元组;截断对;离线 Dealer
prg.py 配对种子伪随机数:成对掩码、零和分享
paillier.py Paillier 加法同态(纯 Python,CRT 加速解密)
ole.py 不经意线性求值(OLE),HE-Beaver 的底层原语
curve25519.py X25519 标量乘(RFC 7748),含 hash-to-point
psi.py ECDH-PSI 内核:盲化 / 双盲 / 匹配
pir.py 1-out-of-N 隐匿查询(PIR):客户端加密单位向量、服务端密文加权求和、客户端解密

安全比较(nax/device/vault.py)

用 edaBit + BitLT 做符号位提取,在线只打开一个被均匀随机数完全掩盖的值:

算子 说明
lt / le / gt / ge / eq / ne 密文比较,返回共享 0/1(定点尺度,可直接参与算术)
select(cond, x, y) 密态三元表达式 cond ? x : y
max / min 逐元素取大/取小
amax / amin(axis) 沿轴归约(密态锦标赛,⌈log₂n⌉ 轮)
argmax / argmin(axis) 返回(密文极值,明文下标)

协议来自 Escudero et al. CRYPTO'20(edaBit)与 Damgård et al. TCC'06(BitLT)。 Dealer 离线发一组随机环元素 r 的 64 个共享比特;在线打开 c = x + r, 由于 r 在 Z_{2^64} 上均匀,c 与 x 统计独立——信息论意义上零泄露。 符号位由 msb(x) = c₆₃ ⊕ r₆₃ ⊕ borrow 还原,borrow 用后缀积扫描(6 轮批量乘)算出。 单次比较约 8 次密文乘 + 1 次 open。

比较结果内部保持原始 0/1 环元素(不做定点缩放),所以 select、amax、 布尔代数全程不经过截断——零累积误差,argmax 遇到并列时稳定取最小下标。

SQL 层(nax/sql/)

  • parser.py —— 手写递归下降解析器,受限 SQL 方言;不支持的语法明确报错而非降级
  • engine.py —— SecureSQL 执行引擎:PSI-JOIN、掩码 WHERE、公开域 GROUP BY、 k-匿名抑制、CCL 列约束、explain() 查询计划
  • 唯一明文出口是最终结果表,每条查询留一条 sql 审计事件

差分隐私(nax/privacy/)

  • clip_l2 —— L2 范数裁剪(把单条/单方贡献压到上界 C 内)
  • gaussian_noise / laplace_noise —— 高斯 / 拉普拉斯机制
  • GaussianAccountant —— 基于 RDP 的隐私记账:step(σ, q) 累计、get_epsilon(δ) 出 ε
  • rdp_sampled_gaussian / rdp_to_dp —— 抽样高斯 RDP(Abadi et al. CCS'16)+ RDP→(ε,δ)(Mironov CSF'17)

数据层(nax/data/)

  • intersect() —— 两方 ECDH-PSI,返回行序对齐的两侧数据
  • VFrame —— 纵向分区表(行对齐、列分散),psi_align() 一步对齐多方
  • HFrame —— 横向分区表(列对齐、行分散),密文域 count / sum / mean / var
  • 安全统计:secure_mean / secure_var / secure_cov / secure_pearson / secure_correlation_matrix(密文协方差 / 皮尔逊,去中心化后 reveal 汇总量明文算)
  • 双阶段数据:Dataset(data/mock.py)—— 数据方注册真实数据同时提供合成 mock;dry_run() 下自动换成明文快路,同一份算法代码两阶段零改动

算法层(nax/ml/)

  • SecureAggregator —— 安全聚合,mask(成对掩码)与 paillier 两种模式
  • FedAvg —— 横向联邦逻辑回归,本地训练 + 安全加权平均;可接 DP-FedAvg(本地 L2 裁剪 + 聚合方加高斯噪声 + RDP 记账)
  • VerticalLogisticRegression —— 纵向联邦逻辑回归,梯度和权重全程密文
  • SecureMLP —— 密文域多层感知机([d→h→1] 等结构),前向/反向/梯度下降全程密文,sigmoid/tanh 隐藏层、输出层固定 sigmoid,支持密文 z-score 标准化与权重存盘重载
  • hetero_binning —— 纵向联邦特征分箱:切点本地算、只送箱指示矩阵进密文,产出 WOE / IV(小箱抑制)
  • Aggregator 链(ml/aggregators.py)—— TFF 风格可插拔聚合责任链:SecureSum → Clipping → Zeroing → Mean → GaussianNoise,与 SecureAggregator 的 mask / paillier 模式配合
  • metrics —— accuracy / auc / log_loss / mse

实测效果

项目 结果
密文加减乘、矩阵乘 与明文误差 < 2e-3(fxp=18)
sigmoid 逼近 3/5/7/9 次,最大误差 0.038 / 0.022 / 0.008 / 0.003
纵向 LR(400×7,40 轮) 与明文权重相关系数 0.999999,AUC 完全一致
横向 FedAvg(3 方 750 样本) AUC 0.9168 vs 集中式 0.9167
mask / paillier 聚合 权重逐位一致;Paillier 慢约 50×
PSI 交集正确,两侧行序对齐
DP-FedAvg σ=0.8→AUC 0.82/ε=30;σ=2.0→AUC 0.71/ε=9.8(噪声↔准确↔隐私三角权衡)
密文 MLP(300×7, [7→16→1], 150 轮) sigmoid AUC 0.9987、tanh AUC 0.9978;存盘重载概率最大偏差 3e-5
密文 PIR 所有 N 条查询精确命中,服务端不知查询下标
安全比较(edaBit+BitLT) 与明文逐位一致(含负数/相等/大数量级),无误差
密态 SQL 单表聚合 / PSI-JOIN / GROUP BY 与 pandas 对照误差 < 1e-3
双阶段执行(dry_run 明文快路) 纵向 LR ≈ 16×、FedAvg/Paillier ≈ 150× 加速,数值逐位一致;还能当场抓出密文路径静默出错

安全模型

半诚实(semi-honest)+ 不合谋。 说人话就是:

  • 每一方都会老老实实按协议执行,但会努力从收到的消息里推测别人的隐私;
  • 参与方之间不串通。

在这个前提下:

  • 加性分享:n 方各持一片,任意 n-1 片在环上是均匀随机的, 信息论安全,跟对手算力无关。
  • Beaver 三元组:乘法时公开的是 x-a 和 y-b,其中 a, b 是一次性随机数, 所以公开值本身也是均匀随机的。
  • ECDH-PSI:对方拿到的是曲线上的点,反推 ID 等价于解 X25519 上的离散对数。
  • Paillier:安全性归约到判定合数剩余问题(DCRA)。默认 1024 位, 生产建议 ≥ 2048。

不防的:恶意参与方(发假消息、中途退出)、合谋、侧信道、 以及从最终结果反推输入(那是差分隐私的活儿)。


已知限制

写清楚比藏着好:

  1. 安全比较很贵。一次 lt ≈ 8 次密文乘 + 1 次 open,比一次加法贵两个数量级。 所以训练链路里的 sigmoid 仍用多项式逼近,而不是用比较拼精确 ReLU—— 前者一次密文乘就够。比较适合用在低频、决定性的地方(SQL 谓词、max/argmax、 树分裂),不适合塞进内层循环。

  2. 多项式 sigmoid 在拟合区间外会发散。这不是精度问题——明文复现同样会炸。 实践中要标准化特征、把学习率放小。VerticalLogisticRegression.fit(monitor=...) 可以打开发散监控(代价是泄露 max|z| 这一个标量)。

  3. Beaver 三元组可去掉可信发牌方。三元组与截断对改用 Paillier 同态加密在各方之间非交互地生成(见 device/offline.py,由 Vault(triples="he") 启用),消除了 "可信第三方发牌" 这一假设; 代价是 Paillier 的纯 Python 实现偏慢(见下条),且仍是半诚实模型。 默认仍是 triples="dealer"(最快,但需要一个可信发牌方)。

  4. Paillier 是纯 Python。1024 位 keygen 约 1~2 秒,加密约 1ms/元素。 够跑通流程,不够跑生产。真上量得换 gmpy2 或 C 扩展。

  5. 定点数会溢出。fxp=18 时可用整数范围约 ±3.5e13。 连乘很多次或数值量级很大时要注意,必要时调小 fxp。

  6. LocalBackend 不是真的隔离。它在同一个进程里模拟多方, 用来开发和 CI 很方便,但别拿它论证安全性。

  7. SCQL 的 GROUP BY 需要预先声明取值域,且分组数会走笛卡尔积—— 多个高基数分组键会让查询开销线性膨胀。这是刻意的:要支持任意基数的分组, 就得做密态排序/去重,那既贵又会泄露分组数量本身。


示例

纵向联邦:特征在两家,标签在一家

vf = VFrame({"hospital": h_ref, "insurer": i_ref})
aligned = vf.psi_align("uid")                     # 先 PSI 对齐样本

box = nax.vault(["hospital", "insurer"])
x = aligned.to_secret(box, drop={"hospital": ["uid"], "insurer": ["uid", "y"]})
y = aligned.secret_column(box, "insurer", "y")    # 标签也进密文

model = VerticalLogisticRegression(box, lr=0.5, epochs=40).fit(x, y)
w = model.weights(to="insurer").fetch()           # 唯一一次显式出域

横向联邦:样本分散在三家分行

fed = FedAvg(["branch_a", "branch_b", "branch_c"],
             aggregator="server", secure="paillier", key_site="branch_a")
fed.fit(x_refs, y_refs, n_features=6, rounds=15, lr=1.0, local_epochs=3)
print(fed.history.last())     # {'acc': ..., 'auc': ..., 'loss': ...}

注意 key_site != aggregator——否则聚合方既能收密文又能解密, 安全聚合就形同虚设。框架会直接报错拦住这种配置。

只做统计,不做建模

hf = HFrame({"a": ref_a, "b": ref_b, "c": ref_c})
hf.count()                       # 三方总行数
hf.mean(columns=["amount"])      # 全局均值,但谁都不知道别人的和
hf.var(columns=["amount"])       # 全局方差

与 SecretFlow 的差距对照

Nax 是对照 SecretFlow 做的「轻量 clean-room 实现」,目标是覆盖其算法能力里能用纯 Python + 秘密分享/同态加密复现的部分,而不是复刻它的工业基础设施。下面这张表是诚实的差距盘点(截至本版)。

已补齐 / 对齐的能力

SecretFlow 能力 在 Nax 中的落点 说明
SPU 上的密文训练(纵向 LR) VerticalLogisticRegression 前向/反向/梯度下降链路等价;底座是加性分享而非 SPU 编译器
SPU 上的神经网络训练 SecureMLP [d→h→1] 等结构,密文前向/反向/sigmoid/tanh,权重全程分片
安全聚合(FedAvg) FedAvg + SecureAggregator mask / paillier 两种模式
差分隐私(DP-SGD / DP-FedAvg) privacy/ + FedAvg(dp_*) L2 裁剪 + 高斯加噪 + RDP 记账(Abadi'16 / Mironov'17)
PSI(隐私求交) crypto/psi.py + data.intersect ECDH-PSI,X25519
隐匿查询(PIR,secretflow/psi 同族) crypto/pir.py Paillier 1-out-of-N,服务端不知查询下标
HEU(同态加密算子) paillier.py(加法同态) 纯 Python,缺少 SIMD/乘法深度优化
YACL 级密码原语 ring / share / prg / curve25519 环算术、Beaver、PRG、X25519
SCQL(隐私 SQL 引擎) nax/sql/(SecureSQL) 受限方言:聚合 / PSI-JOIN / 掩码 WHERE / GROUP BY / HAVING / ORDER BY / k-匿名 / CCL 列约束
SPU 的安全比较(less/max/argmax) vault.lt/gt/select/amax/argmax edaBit + BitLT,信息论零泄露、零定点误差
安全统计(相关性分析) secure_mean/var/cov/pearson 密文协方差 / 皮尔逊
安全求交外的多方统计 HFrame 密文 count/sum/mean/var 横向分区表的全局聚合
Beaver 三元组(去可信发牌方) device/vault.py(triples="he") Paillier 同态 OLE 非交互生成三元组,消除可信第三方假设
纵向联邦分箱 + WOE / IV ml/binning.py(hetero_binning) 切点本地算、只送箱指示矩阵进密文、唯一一次矩阵乘出箱级统计;小箱抑制
聚合责任链(TFF 风格 aggregators) ml/aggregators.py 可链式组合的 Aggregator:SecureSum → Clipping → Zeroing → Mean → GaussianNoise,与 SecureAggregator 的 mask/paillier 两种模式配合
双阶段执行(dry_run 明文快路) runtime/mode.py + device/plain.py + data/mock.py dry_run() 上下文里 vault 自动换成明文 PlainVault、数据自动换成 Dataset mock;同一份算法代码两阶段零改动,试跑秒级且能当场抓密文静默出错

明确选择不做(超出「简易框架」范畴)

SecretFlow 组件 为什么不在 Nax 范围
KUSCIA / K8s 调度 部署编排层,与算法无关;Nax 用 Ray 当底座
SPU C++ 编译器 + 协议栈 需要 MPC 编译器(ABY3 / SecureNN),C++ 量级工程
TEEU(可信执行环境) 依赖 SGX / 硬件 enclave,非纯软件可复现
密态决策树 / GBDT / 深度学习编译器 比较原语已具备,但树的密态分裂点搜索是独立工程量
SCQL 的完整 SQL 方言(子查询 / 窗口 / 密态排序去重) 需要密态排序网络;且 DISTINCT、任意 GROUP BY 的组数本身就是泄露
SecretPad / SecretNote 产品层 前端与编排,非算法框架
serving(模型密文服务) 部署与推理服务化,是另一类工程
恶意安全(malicious security) 当前是半诚实模型;需 MAC/零知识证明加固

简言之:算法层能对的都对了,基础设施层的工业复杂度明确让给 SecretFlow。 Nax 的价值在于「一个下午能读懂、改得动、跑得通」的可教学/可验证实现。


关于代码来源

这是一份从零开始的独立实现(clean-room implementation)。

  • 本项目没有复制、改写或参考任何第三方隐私计算框架的源代码。
  • 所实现的算法均为公开发表的学术成果或公开标准:
    • 加性秘密分享 —— 密码学教科书内容
    • Beaver 三元组 —— Beaver, CRYPTO'91
    • 定点数截断 —— Catrina & Saxena, FC'10
    • Paillier —— Paillier, EUROCRYPT'99
    • X25519 —— RFC 7748
    • ECDH-PSI —— Meadows, S&P'86 起的经典构造
    • FedAvg —— McMahan et al., AISTATS'17
    • sigmoid 多项式逼近 —— 本项目用 numpy.linalg.lstsq 自行拟合, 拟合脚本是 tools/fit_sigmoid.py,跑一遍即可原样复现 SIGMOID_FITS 里的所有系数
  • API 命名与分层是围绕 Ray 的 Actor 模型自行设计的。 隐私计算领域「参与方 / 明文域 / 安全域」这套划分是行业通用概念, 就像所有深度学习框架都有 Tensor 一样,属于领域术语而非专有表达。
  • 依赖仅 numpy / pandas / ray,均为 Apache-2.0 / BSD 许可。

本项目以 Apache-2.0 发布。


目录结构

nax/
├── runtime/          执行层
│   ├── backend.py      Local / Ray 双后端
│   ├── cluster.py      会话管理、任务调度、传输与取回
│   ├── handle.py       数据句柄与敏感度标签
│   └── mode.py         dry_run / real_run 模式开关(contextvars)
├── policy/           策略层
│   ├── guard.py        三个出域关口
│   └── audit.py        审计日志
├── crypto/           密码学原语
│   ├── ring.py  share.py  prg.py
│   ├── paillier.py  ole.py  curve25519.py  psi.py
│   └── pir.py          Paillier 隐匿查询(PIR)
├── privacy/          差分隐私
│   └── dp.py          L2 裁剪 / 高斯·拉普拉斯机制 / RDP 记账
├── device/           设备抽象
│   ├── site.py         明文域
│   ├── secret.py       分片引用
│   ├── vault.py        安全域(核心算子 + edaBit/BitLT 安全比较)
│   ├── offline.py      HE-Beaver:Paillier OLE 非交互物料生成(triples="he")
│   └── plain.py        PlainVault:dry_run 明文替身
├── data/             联邦数据结构
│   ├── psi.py          PSI 驱动
│   ├── frame.py        VFrame / HFrame
│   ├── mock.py         Dataset:真实数据 + mock 双绑定
│   └── stats.py        密文安全统计(均值/方差/协方差/皮尔逊)
├── sql/              密态 SQL(SCQL)
│   ├── ast.py          语法树节点
│   ├── parser.py       递归下降解析器(受限方言)
│   └── engine.py       执行引擎:PSI-JOIN / 掩码 WHERE / GROUP BY / k-匿名
└── ml/               算法
    ├── aggregate.py    安全聚合(SecureAggregator:mask / paillier)
    ├── aggregators.py  聚合责任链(TFF 风格可插拔 aggregator)
    ├── binning.py      纵向联邦分箱 + WOE / IV
    ├── fedavg.py       横向联邦(含 DP-FedAvg)
    ├── vertical.py     纵向联邦
    ├── mlp.py          密文域 MLP(SecureMLP)
    └── metrics.py

tests/       278 个用例
examples/    11 个可运行示例 + 1 个 k8s 分布式部署示例 (12_k8s_two_party/)

约 8500 行核心代码,没有 C 扩展,读完一个周末。