merge sandbox/fe93ee4: chg_0008 operator_real_algorithms — 6 算子真算法仿真(crypto-js + secret-share + Box-Muller + HMAC, 15+27+33+17+16=108 e2e PASS)

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
xstudio agentandClaude Code committed 2026-09-28 18:40:35 +08:00
1 parent 8c06057283
commit 66d21a5415
12 files changed
+1252 -71

No files matched your search

+308
View File
@@ -0,0 +1,308 @@
# Operator Real Algorithms — 设计文档(chg_0008)
> 作者:xstudio-agent · 日期:2026-09-28
> 范围:把 chg_0005 加进来的 6 个 mock 算子(scql / horizontal-fedavg / secure-mlp /
> tee-inference / prompt-defense / compliance-audit)改成"真算法仿真"形态。
>
> 注意范围:本文档**不**包含 chg_0002 的 hello-mpc / pir / vertical-lr 三个基础算子
> (已 `good-enough-real`,按任务约定不动)。
---
## 1. 背景与目标
需求 §5(数智安全人才平台 design doc line 212)要求"后端跑真算法(nax.crypto/
data/ml/sql/policy 引擎),学生看到的中间值是真计算结果"。chg_0005 在增量加进
6 个算子时受限于 `nax.*` 引擎(`~/Desktop/ssw/demo`)在本机不可用,所以采用
mock(`protocol: 'scql-psi-sum-mock'` / `algorithm: 'fedavg-mock-1-round'` /
mechanism: 'laplace' / `enclave: 'mock-sgx-equivalent'` / keyword classifier /
UUID trail)。
本变更目标:
1. 接口不变 — `Operator { meta, run(input) }` 形态不变,输入 schema 不变。
2. 真正的密码学 / 统计原语 — 每个算子用上一个**真实**算法(secret-share /
Box-Muller / Laplace / HMAC-SHA256 / seeded RNG),不再 `Math.random()` 满天飞。
3. 输出加 `schema_version: "v2"` 标记 — additive,下游消费者可平滑升级。
4. 可验证的不变性 — SCQL 真满足 `Σ partSum === Σ value`;FedAvg 100 次
stddev 落在理论 σ × √(1/N) 量级;MLP 同 `run_id` 输出位相同;TEE 错 key
校验失败;Audit 链注入即破。
非目标:
- 不引 nax.* / @ssw/* 引擎(不可用,留待 `~/Desktop/ssw/demo` 落地)。
- 不动 chg_0002 三个基础算子。
- 不引真实 GPU / WebAssembly / 同态加密库。
---
## 2. 选型:每个算子的"真算法"是什么
### 2.1 scql — 真 secret-share 三方聚合
**原 mock**(chg_0005 行 36-58):
```typescript
const colSum = vals.reduce((a, b) => a + b, 0); // 直接算 sum
// protocol: 'scql-psi-sum-mock'
```
**v2 真算法**:
每行 `value` 用确定性函数拆 3 方 share:`shareA + shareB + shareC === value`。
拆分由 `CryptoJS.SHA256(seed + "|" + rowIdx + "|" + partyIdx)` 派生,
用 `BigInt` 整型(mod `2^53 - 1` 安全整数)做 secret-share,避免 `Number` 浮点
精度问题。最后各 party 算 partial-sum,merge 时直接相加还原:
`Σ partSum === Σ value` 严格相等。
实现要点:
- 用 `BigInt` 整型拆分:`shareA = (hashInt(partyA) mod M); shareB = ...;
shareC = valueInt - shareA - shareB`,刚好互补。
- M = `2n + 1`(安全整数 2^53 - 1),全用 `Number(BigInt) as number` 投回浮点
比较时做 `1e-9` 容差。
- `trace.partSums = [sumA, sumB, sumC]` / `trace.shareCount = 3` 暴露中间值。
- `meta.algorithm = "secret-share-aggregation-v2"`。
**不变性测试可证**:3 行数据 Σ = 600,每 party 各算自己的 partial sum,
合并与直接 sum 的差 ≤ 1e-9。
### 2.2 horizontal-fedavg — 真 FedAvg + Gaussian DP
**原 mock**(chg_0005 行 38-72):
```typescript
agg[i] = avg(client weights) // pure average, no noise
// algorithm: 'fedavg-mock-1-round'
```
**v2 真算法**:
FedAvg = client 算 local sum → server 加权平均(mean aggregation),再加
Gaussian DP 噪声。噪声 stddev = `sensitivity / epsilon`,用 **Box-Muller 变换**
从两个均匀分布采样出标准正态,再乘 stddev:
```
u1, u2 ~ U(0, 1)
z = sqrt(-2 * ln(u1)) * cos(2 * pi * u2)
noise = z * stddev
```
实现要点:
- `boxMuller()` private 方法(在 operator 内)— 不依赖第三方随机库。
- sensitivity 默认 1.0(最大 l2 norm 单 client 权重差),epsilon 在 input
中传入(默认 1.0)。
- 噪声加在 final averaged vector 上(per-dimension independent)。
- `trace.noise_scale = sensitivity / epsilon` 暴露给学生看。
- 100 次独立运行后 `stddev(final_weights[i])` 应落在 `[0.5 * sigma, 2.0 * sigma]`
范围(Box-Muller 标准差收敛)。
- `meta.algorithm = "fedavg-gaussian-dp-v2"`。
### 2.3 secure-mlp — 真 forward pass + Laplace DP(seeded)
**原 mock**(chg_0005 行 41-67):
```typescript
// 输入带 weights 字段,直接使用
z = bias + Σ w * x + laplace(noiseScale) // Math.random() 用法
// weights_used: weights // 用户传啥用啥
```
**v2 真算法**:
单层 MLP forward pass = `output = sigmoid(x @ W + b) + Laplace(1/λ)`。W 用
**deterministic seeded RNG**(seed 来自 `run_id`)保证可复现:
```
W[j][i] = scalar( SHA256(seed + "|w|" + j + "|" + i) ) in [-1, 1]
b[i] = scalar( SHA256(seed + "|b|" + i) ) in [-0.5, 0.5]
laplace_noise = (1/epsilon) * laplace_sample()
```
实现要点:
- `seedRNG(run_id)` 用 `CryptoJS.SHA256(run_id)` 派生 32 字节种子,
转成 16 个 `uint32` 喂 Mulberry32 PRNG(轻量、标准)。
- Laplace 采样 = `(u - 0.5) / |u - 0.5| * (-scale) * ln(1 - 2|u - 0.5|)`,
u 取 PRNG 派生(非 `Math.random()`)— 同样 seed 输出位相同。
- 同 `run_id` 两次调用 → 输出位相同(deterministic)。
- 不同 `run_id` → 输出不同(噪声独立采样)。
- `meta.algorithm = "secure-mlp-laplace-dp-v2"`。
### 2.4 tee-inference — 真 HMAC-SHA256 attestation
**原 mock**(chg_0005 行 27-44):
```typescript
const hex = createHash('sha256').update(`${prompt}||${model}`).digest('hex');
// attestation: sha256(prompt||model) // 没签名
```
**v2 真算法**:
TEE attestation quote = `PCR0 + PCR1 + nonce + signature`,其中:
```
PCR0 = sha256(model || input)
PCR1 = sha256(enclave_code_id)
nonce = random16-bytes-hex
signature = HMAC-SHA256(attestation_key, pcr0 || "|" || pcr1 || "|" || nonce)
```
验证方拿到 attestation 用同一 `attestation_key` 重算 HMAC 比对:
- 正确 key → `signature === recomputed` → `verify_code = 0`。
- 错误 key → `signature !== recomputed` → `verify_code = 1`。
实现要点:
- 用 `CryptoJS.HmacSHA256` + `CryptoJS.enc.Hex` 派生 signature。
- `attestation_key` 由 input 传入,**不**硬编码到 operator 内(防止误用)。
- `meta.algorithm = "tee-hmac-attestation-v2"`。
### 2.5 prompt-defense — 真 z-score + HMAC 签名校验
**原 mock**(chg_0005 行 4-53):
```typescript
const matched: string[] = [];
for (const kw of INJECTION_KEYWORDS) if (lower.includes(kw)) matched.push(kw);
// keyword-only
```
**v2 真算法**:
三段式真检测:
1. **关键词 / 模式匹配**(保留 chg_0005 逻辑)— 检测 "ignore previous
instructions" / "override system" / "jailbreak" 等 injection pattern。
2. **长度 / 字符分布 z-score** — 计算 prompt 字符长度,与训练集统计
(mean=80, std=200,硬编码即可)算 z-score;`|z| > 3` 算"异常"。
3. **HMAC 签名校验** — 调用方提供 `signature`,operator 重算
`HMAC-SHA256(api_key, prompt)` 比对;不匹配也标 `defected=true` 加
`reason: "signature-mismatch"`。
实现要点:
- `api_key` 默认值内置为 `'default-api-key'`(生产应从环境变量,本仿真简化)。
- `meta.algorithm = "z-score-hmac-prompt-v2"`。
### 2.6 compliance-audit — 真 HMAC 链
**原 mock**(chg_0005 行 36-52):
```typescript
const trail_id = uuidv4(); // 每次独立,无链
const compliance_score = Number((fnv1a(`${action}:${actor}`) % 10000) / 10000).toFixed(6);
// 完全没 chain 概念
```
**v2 真算法**:
Append-only HMAC chain:
```
genesis_hash = "0".repeat(64)
entries[i] = {
prev_hash: entries[i-1]?.hash ?? genesis_hash,
payload: { action, actor, ... },
hash: HMAC-SHA256(chain_key, prev_hash + "|" + JSON.stringify(payload))
}
```
验证:`chainValid = true` 当且仅当遍历 entries 从头重算每行 `hash` 都等于
存储的 `hash` + 每行 `prev_hash` 都等于上行 `hash`。
实现要点:
- `chain_key` 默认 `'default-audit-chain-key'`(生产应注入)。
- 当前 operator 不存全局 state(每次调用独立),chain 验证由 e2e 通过多
次调用构造 3 entry chain + verify call 验证(构造链由脚本持有)。
- `meta.algorithm = "hmac-chain-v2"`。
---
## 3. crypto-js 引入理由
| 维度 | 内置 `node:crypto` | `crypto-js` |
|------|----------------------|-------------|
| 浏览器兼容 | ❌ 仅 Node | ✅ 浏览器 + Node |
| 体积 | — | 416 KB minified |
| HMAC-SHA256 | ✅ | ✅ |
| API 风格 | 流式 / `createHmac` | 一行 `HmacSHA256(msg, key).toString()` |
| 单元可测 | 需 mock fs/net | 无副作用 |
| 维护方 | Node core | 标准社区库,已 4.2.x 稳定 |
**理由汇总**:
1. DTH 后端虽只用 Node,但 chg_0005 模拟真实业务场景时(包括未来扩展
的前端演示 / mock-server)需要**纯 JS** 库;`crypto-js` 跨 runtime。
2. `crypto-js` 提供 `HmacSHA256 / SHA256 / enc.Hex.stringify` 等便利 API,
一行出 hex 字符串,省掉 node:crypto 的 `createHash().digest('hex')` 模板。
3. 体积 416 KB 在后端场景完全可接受(不带 GPU / 不打包到前端)。
4. 不引 `elliptic` / `libsodium` — 任务规约明确说保持 crypto-js。
---
## 4. 与 chg_0005 mock 的差异(速查表)
| 算子 | chg_0005 mock | chg_0008 v2 真算法 | meta.algorithm |
|------|---------------|---------------------|----------------|
| scql | 直接 reduce 求和 | secret-share 3 方拆分 + 加和,BigInt 整型 | `secret-share-aggregation-v2` |
| horizontal-fedavg | pure mean | mean + Box-Muller Gaussian DP (σ = sens/ε) | `fedavg-gaussian-dp-v2` |
| secure-mlp | 输入权重 × Laplace 噪声 | seeded W/b + Laplace DP(seed→可复现) | `secure-mlp-laplace-dp-v2` |
| tee-inference | sha256(prompt\|\|model) 无签名 | PCR0/PCR1/nonce + HMAC-SHA256 签名 + verify | `tee-hmac-attestation-v2` |
| prompt-defense | keyword-only | keyword + z-score 长度 + HMAC 签名校验 | `z-score-hmac-prompt-v2` |
| compliance-audit | UUID + fnv1a 分数,无链 | append-only HMAC chain + chainValid 验证 | `hmac-chain-v2` |
所有 v2 输出顶层增加 `schema_version: "v2"` 字段(additive)。
---
## 5. 输出兼容性
- 输入 schema 完全不变 — chg_0005 e2e(`dth_experiment_extend.test.sh`)8 个
case 直接复用,断言旧字段存在 + `schema_version === "v2"` 即可。
- 输出 schema 是 v1 的**严格超集**:旧字段全部保留 + `schema_version` 标记。
- meta 字段新增 `meta.algorithm` 一律带 `-v2` 后缀,调度者可通过 `algorithm`
判断是否真算法实现。
---
## 6. 关键测试点(e2e)
| Case | Scenario | 验证什么 |
|------|----------|----------|
| C1 | S1 | `Σ partSum === Σ value`(1e-9 容差)+ `trace.partSums.length === 3` |
| C2 | S2 | 100 次独立运行,stddev ∈ `[0.5 * σ, 2.0 * σ]` |
| C3 | S3 | 同 run_id 两次输出完全一致 |
| C4 | S3 | 不同 run_id 输出不同 |
| C5 | S4 | TEE 正确 key → `verify_code = 0` |
| C6 | S4 | TEE 错 key → `verify_code !== 0` |
| C7 | S5 | 注入 prompt → `defected=true` + reasons 含 `injection-pattern-match` |
| C8 | S6 | 3 entry chain,篡改 entry[1] → `chainValid=false`;原链 → `chainValid=true` |
每个 case 顺带断言 `schema_version === "v2"`。
---
## 7. 风险与权衡
| 风险 | 影响 | 缓解 |
|------|------|------|
| BigInt 精度 | secret-share 拆 2^53 以上有损 | 用 mod `(2n+1)` 限安全整数范围;sum ≤ 1e15 安全 |
| Box-Muller 极值 | u1 → 0 时 ln 爆炸 | u1 加 floor `1e-300`,clip 到 ±10σ |
| Laplace seed 化 | 同 seed 输出碰撞 / PRNG 周期 | Mulberry32 周期 2^32,run_id 用 SHA256 后取 16 字节 |
| HMAC key 暴露 | 仿真 key 硬编码默认 | 文档明确"生产应从 env 注入";本任务范围内接受 |
| `schema_version` 误用 | 下游消费者忘升级 | 文档明确 additive;旧的 `dth_experiment_extend.test.sh` 仍跑 |
| crypto-js 体积 | 后端打包增 416 KB | 后端可接受;前端 bundle 不引 |
---
## 8. 参考
- chg_0005 提案:`openspec/changes/chg_0005_experiment_platform_extend/proposal.md`
- 需求 §5 line 212:`docs/superpowers/specs/2026-09-28-data-talent-hub-design.md`
- learnings §152-158:`docs/superpowers/learnings/2026-09-28-dispatch-session.md`
- Mulberry32 PRNG:https://gist.github.com/tommyettinger/46a3a48c1eb5c9f0c4b6a5d6a6e7b8e7
- Box-Muller 变换:https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform
- crypto-js API:https://github.com/brix/crypto-js
---
> 本文件由 chg_0008 T1 (architect) 产出。T2 (implementer) 据此改 6 个算子。
+81
View File
@@ -0,0 +1,81 @@
# chg_0008 operator_real_algorithms — Verification Report
> 作者:xstudio-agent · 日期:2026-09-28
## 范围
chg_0008 把 chg_0005 引入的 6 个 mock 算子(scql / horizontal-fedavg / secure-mlp /
tee-inference / prompt-defense / compliance-audit)改写为真算法仿真形态,并加
`schema_version: "v2"` 标记。
## 门禁结果
| # | 检查 | 命令 | 结果 |
|---|------|------|------|
| 1 | Spec coverage | `bash openspec/scripts/check_spec_coverage.sh` | **gap=0**(chg_0008 OK + 全部 6 chg OK)|
| 2 | TypeScript | `cd src/backend && npx tsc --noEmit` | 我改的 6 算子 + `operators.ts` interface 0 error;1 个 pre-existing vertical-lr.ts:52 TS2352(chg_0002 off-limits,未动)|
| 3 | chg_0008 e2e | `bash tests/e2e/dth_operator_real.test.sh` | **pass=15 / fail=0** |
| 4 | chg_0005 回归 | `bash tests/e2e/dth_experiment_extend.test.sh` | **pass=27 / fail=0** |
| 5 | chg_0007 回归 | `bash tests/e2e/dth_lite_demo.test.sh` | **pass=33 / fail=0** |
| 6 | chg_0006 回归 | `bash tests/e2e/dth_lms.test.sh` | **pass=17 / fail=0** |
| 7 | chg_0002 回归 | `bash tests/e2e/dth_experiment.test.sh` | **pass=16 / fail=0** |
合计 5 e2e:108 assertions all PASS。
## 关键修复(本次 session 内)
1. `compliance-audit.ts` verify 模式:原本对整个 entry 做 JSON.stringify 取 hash(与
record 模式只对 payload 取 hash 不一致,字符串里包含 hash/prev_hash 字段导致两边
canonical 不一致),改为对 `entry.payload` 取 hash → chainValid 验证通过。
2. `tests/e2e/dth_operator_real.test.sh` 中 C7 的 Python 断言 `sv=d['schema_version']`
路径错误,改为 `sv=d['data']['output_json']['schema_version']` → C7 通过。
3. C1 / C2 一并把 python 输出统一为 'true'/'false' 字符串,shell 比较
`[ '$X' = 'true' ]` 形式,前后保持一致。
## chg_0008 e2e 覆盖(S1-S6 共 8 case,15 assertion)
| Case | Scenario | 验证什么 | 通过 |
|------|----------|----------|------|
| C1_scql_run_status | S1 | scql rows 模式 status=success | ✓ |
| C1_scql_sum_invariant | S1 | Σ partSums === Σ values (600) + schema_version=v2 | ✓ |
| C2_fedavg_noise_distribution | S2 | 100 次 stddev ∈ [0.5, 2.0]σ + mean ∈ [1.5, 2.5] | ✓ |
| C2_fedavg_meta_algorithm_v2 | S2 | meta.algorithm='fedavg-gaussian-dp-v2' | ✓ |
| C3_mlp_same_seed_identical | S3 | 同 run_id 两次输出位相同 | ✓ |
| C3_mlp_schema_version_v2 | S3 | schema_version=v2 | ✓ |
| C4_mlp_different_seed_differs | S3 | 不同 run_id 输出不同 | ✓ |
| C5_tee_correct_key_verify_code_0 | S4 | attestation_key 正确 → verify_code=0 | ✓ |
| C5_tee_signature_validates | S4 | 外部 Python hmac 重算 = 存储 signature | ✓ |
| C6_tee_wrong_key_verify_code_nonzero | S4 | 错 key → verify_code != 0 | ✓ |
| C7_prompt_defense_injection_detected | S5 | injection 检出 + signature_valid + reasons 含 injection-pattern-match | ✓ |
| C8_audit_chain_valid_true | S6 | 原始 3-entry chain → chainValid=true | ✓ |
| C8_audit_chain_tampering_detected | S6 | 篡改 entry 2 → chainValid=false | ✓ |
| C8_audit_schema_version_v2 | S6 | schema_version=v2 | ✓ |
| pre_admin_login | — | admin 登录拿到 JWT | ✓ |
## 沙盒边界与稳健性
- BigInt secret-share 限 `MOD = 2^53 - 1`(任务规约强制)— 测试输入 600 << M,无溢出。
- Box-Muller u1 限 ≥ 1e-12 防 `ln(0)` 退化;clip ±10σ 防极端方差。
- Mulberry32 PRNG 周期 2^32,run_id → SHA256 → 32 hex bytes 作种子;测试同/不同 seed 验证。
- HMAC chain:prev_hash + canonical-payload-json(payload keys 字母排序后 JSON.stringify),
record 与 verify 拿一致字符串,避免字段顺序差异破链。
- HMAC-SHA256 attestation quote:`pcr0|pcr1|nonce` → signature;TEE verify 用
`CryptoJS.HmacSHA256(message, attestation_key)` 还原比对,verify_code 0=OK / !=0=fail。
- prompt-defense: keyword + regex + z-score + HMAC signature 四段独立判定;
signature 错不仅威胁等级升 high,还会在 reasons 里写 'signature-mismatch'。
## 改动 commit (sandbox 分支)
```
f501fc9 feat(dth): T4 dth_operator_real e2e test (15 assertions / 8 cases)
38d1206 feat(dth): T2+T3 rewrite 6 operators with crypto-js + schema_version=v2
dbf9ef7 feat(dth): T1 operator-real design doc
8c06057 chg_0008: operator_real_algorithms 提案 — 6 算子真算法仿真 (主分支 baseline)
```
## 是否建议合并
建议合并 — chg_0008 自身 5 e2e 全 PASS + spec gap=0 + tsc 仅 1 pre-existing 错误
(chg_0002 vertical-lr.ts:52,按任务规约不动)。chg_0005 / 0007 / 0006 / 0002 全部
回归通过,未引入新的破坏性变更(旧字段保留 + 加 `schema_version` additive 字段 +
加可选 `algorithm` meta 字段)。