diff --git a/openspec/changes/chg_0010_federated_risk_control/proposal.md b/openspec/changes/chg_0010_federated_risk_control/proposal.md new file mode 100644 index 0000000..57b80e4 --- /dev/null +++ b/openspec/changes/chg_0010_federated_risk_control/proposal.md @@ -0,0 +1,74 @@ +--- +change_id: chg_0010 +status: proposed +owner: pm@team +stakeholders: [pd, tm, qa, dev] +priority: P1 +target_release: v0.6 +created: 2026-09-28 +skip_coverage: false +--- + +# chg_0010 federated_risk_control — 3 银行联合反欺诈场景 + +## Why + +chg_0009 已落地 10 个真算法算子(paillier-he / threshold-sig / psi / did-identity / tds-connector / +data-masking / data-watermark / abac-policy / model-watermark / mpc-beaver),但缺少**真实业务场景** +把它们组合起来跑通。 + +需求 §5(数智安全人才平台 design doc line 212)要求"业务场景测试:模拟 N 机构联合数据流通场景 +(金融联合风控 / 医疗联合诊断 / 车云数据合规),证明算子在真实多方流程下能协同工作"。 + +金融联合风控是三个候选中**算子覆盖率最高**的场景(直接命中 8/10 chg_0009 算子 + 1 chg_0008 算子), +也是 SP-1 实验台最典型的"多方数据不出域"用例。 + +**约束**: +- 不改 backend 代码(10 算子已齐备,0 新依赖,0 新接口) +- 不加前端(场景测试目标是 backend e2e 协同,不是 UI) +- 复用 chg_0006 LMS 的多实体建模思路:用 admin token + per-bank 标签模拟 3 银行(避免改 auth) + +## Scope + +**做**: + +1. **场景设计文档** `docs/dth/frc/scenario.md`:定义 FRC 场景的 6 步流程图 + 数据流图 + + 不变性约束 + 与既有算子的映射表。 + +2. **集成 e2e 测试** `tests/e2e/dth_frc.test.sh`:12 case 串起 8 个算子,覆盖: + - S1: 3 银行 DID 建立 + TDS 合约 hash 匹配(did-identity + tds-connector) + - S2: DID 验证循环 + 篡改检测(did-identity) + - S3: TDS 合约 hash 不匹配 → 流程拒绝(tds-connector) + - S4: PSI 黑名单交集正确(psi:仅输出共享欺诈 ID,不泄露非交集) + - S5: PSI 不泄露非交集(psi:交集元素计数 ≤ min(各银行黑名单大小)) + - S6: Paillier 跨行特征求和不变性(paillier-he:Enc(bankA)·Enc(bankB)·Enc(bankC) = Enc(sum)) + - S7: Threshold 2-of-3 风险签名重构(threshold-sig:2 share → verify_code=0) + - S8: Threshold 1 share 签名失败(threshold-sig:1 share → verify_code≠0) + - S9: ABAC 风险分析师通过 + 游客拒绝(abac-policy) + - S10: 数据水印嵌入提取 roundtrip(data-watermark:聚合报告含零宽水印) + - S11: 审计链 HMAC 完整(compliance-audit:完整 8 步流程链 chainValid=true) + - S12: E2E 端到端(依次跑 S1→S11 全程,每步 invariant 通过) + +3. **门禁更新** `openspec/scripts/check_spec_coverage.sh`:无需改动(5 件套天然 cover)。 +5. **端口**:仍 30000(DTH_BASE 默认;不冲突 LMS / SP-1 实验台)。 + +**不做**: + +- ❌ 新建 FRC 专属 endpoint(直接复用 `POST /experiment/runs` 一个一个跑算子) +- ❌ 新加前端(backend-only e2e) +- ❌ 新加 operator(10 算子全够用) +- ❌ 新加依赖(纯 shell + python3 + jq,已在 chg_0002 启用) +- ❌ 改 abac / auth(admin token 全程够用,per-bank 标签在 input 里传) + +## Acceptance + +- 12 case e2e 全 PASS(chg_0010 自身) +- 5 回归 e2e 全 PASS(chg_0002/0005/0006/0007/0008/0009) +- gate `PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh` gap=0 +- `tsc --noEmit` 0 error(除预存 chg_0002 vertical-lr.ts:52) +- 文档 `docs/dth/frc/scenario.md` 包含:流程图(mermaid)+ 数据流 + 算子映射表 + 不变性清单 + +## 与 handoff §2 的对应 + +handoff §2 优先级 2 = "chg_0010 真实业务场景测试设计" → 本 chg 闭环。 +本 chg 完成 = handoff §2 全部三条都关闭(1️⃣chg_0009 重派 ✅ 2️⃣chg_0010 设计 ✅ 3️⃣框架文档化待办)。 \ No newline at end of file diff --git a/openspec/changes/chg_0010_federated_risk_control/spec.md b/openspec/changes/chg_0010_federated_risk_control/spec.md new file mode 100644 index 0000000..90377e6 --- /dev/null +++ b/openspec/changes/chg_0010_federated_risk_control/spec.md @@ -0,0 +1,100 @@ +# Spec: experiment_platform + +## Requirement + +THE SYSTEM SHALL provide a multi-bank federated risk control (FRC) scenario that composes +8 existing operators (did-identity / tds-connector / psi / paillier-he / threshold-sig / +abac-policy / data-watermark / compliance-audit) into a 6-step end-to-end fraud detection +flow across 3 simulated banks (BankA / BankB / BankC), proving that **multi-party, no-PII-leak, +audit-traceable** risk decisions can be made WITHOUT any new operator / endpoint / dependency, +so that 业务方能用现有算子验证"数据不出域"的多方金融场景。 + +## ADDED Scenarios + +### S1 3 银行 DID 建立 + TDS 合约匹配 + +- **WHEN** BankA / BankB / BankC each call did-identity.create() with their private keys +- **THEN** output 3 distinct DIDs (`did:frc:bankA/...`, `did:frc:bankB/...`, `did:frc:bankC/...`) +- **AND** tds-connector.match() with matching `contract_hash` returns `{match: true, token: <3-part JWT>}` +- **AND** output `schema_version === "v2"` + +### S2 DID 验证循环 + 篡改检测 + +- **WHEN** each of the 3 DIDs from S1 is verified with did-identity.verify() +- **THEN** all 3 return `{valid: true}` +- **AND** if any DID document is tampered (e.g., swap `publicKey`), verify() returns `{valid: false}` + +### S3 TDS 合约 hash 不匹配 → 流程拒绝 + +- **WHEN** tds-connector.match() is called with `contract_hash_a === contract_hash_b` +- **THEN** output `{match: false, error: "contract-mismatch"}` +- **AND** the FRC flow is aborted at step 1 (no PSI / aggregation runs) + +### S4 PSI 黑名单交集正确 + +- **WHEN** 3 banks submit private blacklists: + - BankA = `[f01, f02, f03, f04]` + - BankB = `[f02, f03, f05]` + - BankC = `[f01, f03, f06, f07]` +- **THEN** PSI intersection output = `[f01, f02, f03]` (sorted, no duplicates, no extras) +- **AND** output `intersection_size === 3` +- **AND** schema_version = "v2" + +### S5 PSI 不泄露非交集(隐私不变性) + +- **WHEN** S4 PSI is run +- **THEN** the output NEVER contains elements outside `[f01, f02, f03]` +- **AND** the output size is **at most** `min(len(A), len(B), len(C))` (here min=3) +- **AND** no per-bank blacklist sizes are revealed in the output (`{intersection: [...], intersection_size: N}` only) + +### S6 Paillier 跨行特征求和不变性 + +- **WHEN** 3 banks submit encrypted average-risk features: + - BankA: Enc(100) + - BankB: Enc(200) + - BankC: Enc(300) +- **THEN** `sumProduct = Enc(100) · Enc(200) · Enc(300) mod n² === Enc(600)` +- **AND** Decrypt(Enc(600)) === 600 (mod n) +- **AND** schema_version = "v2" + +### S7 Threshold 2-of-3 风险签名重构 + +- **WHEN** the aggregator (TDS) computes a risk decision and requests 3 banks to sign via threshold-sig +- **THEN** with **2 of 3 shares** (any 2 banks), Lagrange interpolation reconstructs the secret +- **AND** verify_code === 0 (signature valid) +- **AND** output `recovered === original_payload` + +### S8 Threshold 1 share 签名失败 + +- **WHEN** only **1 share** is provided to threshold-sig.reconstruct() +- **THEN** verify_code !== 0 (signature fails — needs ≥ 2 shares) +- **AND** error code reflects "insufficient-shares" + +### S9 ABAC 风险分析师通过 + 游客拒绝 + +- **WHEN** an ABAC policy requires `subject.role === "risk-analyst"` AND `subject.region in ["BJ","SH","GZ"]` AND `env.timewindow 09:00-18:00` +- **THEN** request from `{role: "risk-analyst", region: "BJ", time: "10:00"}` returns `{allow: true}` +- **AND** request from `{role: "guest", region: "BJ", time: "10:00"}` returns `{allow: false, reason: "role-deny"}` +- **AND** request from `{role: "risk-analyst", region: "NY", time: "10:00"}` returns `{allow: false, reason: "region-deny"}` +- **AND** request from `{role: "risk-analyst", region: "BJ", time: "20:00"}` returns `{allow: false, reason: "timewindow-deny"}` + +### S10 数据水印嵌入提取 roundtrip + +- **WHEN** the aggregator embeds `payload = "FRC|2026-09-28|bankA,bankB,bankC"` into a report via data-watermark +- **THEN** the report's visible length is unchanged (zero-width chars) +- **AND** data-watermark.extract(report) recovers the **exact** payload string +- **AND** schema_version = "v2" + +### S11 审计链 HMAC 完整 + +- **WHEN** the full FRC flow runs through steps S1→S10 (or as many as allowed by input) +- **THEN** compliance-audit chain contains ≥ 8 entries (one per FRC step) +- **AND** each entry has HMAC-SHA256 chain linkage (`prev_hash` references the prior entry) +- **AND** chainValid === true on full replay + +### S12 E2E 端到端 8 步不变性 + +- **WHEN** a single shell run executes S1→S11 in order with the canonical 3-bank input fixture +- **THEN** every intermediate assertion in S1..S11 passes +- **AND** the final output reports `e2e dth_frc: pass=N fail=0` (N = total sub-assertions, expected 12+) +- **AND** total wall-clock time for the e2e is < 60s (operators are local Python/TS, no external I/O) \ No newline at end of file diff --git a/openspec/changes/chg_0010_federated_risk_control/tasks.md b/openspec/changes/chg_0010_federated_risk_control/tasks.md new file mode 100644 index 0000000..04a5233 --- /dev/null +++ b/openspec/changes/chg_0010_federated_risk_control/tasks.md @@ -0,0 +1,71 @@ +# Tasks (DAG) + +- id: T1 + type: architect + depends_on: [] + output: docs/dth/frc/scenario.md + verification: + - 文档含 mermaid 流程图(6 步 + 8 算子映射) + - 数据流表(每步:输入 → 算子 → 输出 → 不变性) + - 算子映射表(每算子:何时被调用 / 输入 schema / 输出 schema) + - 不变性清单(S1-S12 → 对应算子 + 测试断言) + - 复用矩阵(既有 10 算子的复用率 ≥ 80%) + +- id: T2 + type: implementer + depends_on: [T1] + output: | + tests/e2e/dth_frc.test.sh (12 case e2e shell 脚本) + verification: + - 脚本无 set -e(每条 assertion 独立计数) + - 使用 DTH_BASE=${DTH_BASE:-http://127.0.0.1:30000} + - 每条 assert 用 python3 json_get (与 chg_0008/0009 一致) + - 包含 admin token login (pre_admin_login) + - 12 case 覆盖 S1..S12 + - 总耗时 < 60s + - 复用既有 helpers(不要重写 json_get / assert / login) + +- id: T3 + type: tester + depends_on: [T2] + output: | + 1 次完整 e2e 跑通(bash tests/e2e/dth_frc.test.sh 12/0) + verification: + - pass=12 fail=0 + - 含 4+ 不变性断言(PSI 交集正确 / PSI 不泄露 / Paillier sum / 水印 roundtrip) + - 含 1 篡改检测(did-identity 篡改 verify 失败) + - 含 1 拒绝路径(TDS mismatch → 流程拒绝) + - 含 1 跨银行 E2E 串联(S12 = S1→S11 一气呵成) + +- id: T4 + type: qa + depends_on: [T3] + output: | + PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh + 6 e2e 套件全跑(chg_0002/0005/0006/0007/0008/0009/0010 = 7 套) + verification: + - gate gap = 0 + - tsc --noEmit 0 error(除预存 chg_0002 vertical-lr.ts:52) + - 5 回归 + 1 新 = 6 e2e 套件全 PASS + - 总断言数 ≥ 144(135 旧 + 12 新 = 147) + - 报告落 /tmp/chg_0010-qa.log + +- id: T5 + type: pm + depends_on: [T4] + output: | + openspec/changes/chg_0010_federated_risk_control/.xstudio-report.md + chg_0010 实施说明(取舍 + 与 chg_0009 复用率 + 后续 chg_0011 候选) + verification: + - 报告含 改动文件清单 + 门禁结果 + 算子复用率 + 是否建议合并 + - 报告大小 ≥ 30 行 + - chg_0010 任务全部完成 + +# Notes + +- 无 backend 代码改动(10 算子已齐备) +- 无 frontend 代码改动(业务场景 e2e only) +- 无新依赖 +- 测试端口 30000(与既有 e2e 一致;DTH_BASE env 可覆盖) +- 提交顺序建议:T1 (docs) → T2 (test script) → T3 (test PASS) → T4 (gate + regressions) → T5 (report) +- 与 chg_0009 的边界:不动 OperatorsService / ExperimentModule 注册(10 算子已注册),仅新增 test 脚本 \ No newline at end of file diff --git a/openspec/changes/chg_0010_federated_risk_control/testcases.map.yaml b/openspec/changes/chg_0010_federated_risk_control/testcases.map.yaml new file mode 100644 index 0000000..a983afc --- /dev/null +++ b/openspec/changes/chg_0010_federated_risk_control/testcases.map.yaml @@ -0,0 +1,50 @@ +# spec: experiment_platform@chg_0010 +scenarios: + - id: S1 + cases: [C1_3bank_did_setup_tds_match] + - id: S2 + cases: [C2_did_verify_loop_tamper_detect] + - id: S3 + cases: [C3_tds_mismatch_abort] + - id: S4 + cases: [C4_psi_intersection_correct] + - id: S5 + cases: [C5_psi_no_leak_non_intersection] + - id: S6 + cases: [C6_paillier_cross_bank_sum_invariant] + - id: S7 + cases: [C7_threshold_sig_2shares_reconstruct] + - id: S8 + cases: [C8_threshold_sig_1share_fails] + - id: S9 + cases: [C9_abac_policy_decision_matrix] + - id: S10 + cases: [C10_data_watermark_roundtrip] + - id: S11 + cases: [C11_audit_chain_hmac_valid] + - id: S12 + cases: [C12_e2e_full_flow_8_steps] +gate: + blocking_gap_tolerance: 0 + implementation_files: + - tests/e2e/dth_frc.test.sh + - docs/dth/frc/scenario.md + test_files: + - tests/e2e/dth_frc.test.sh +notes: + reuses_operators_no_new_code: true + operator_coverage: "8 of 10 chg_0009 operators + 1 chg_0008 operator" + operators_used: + - did-identity (S1, S2) + - tds-connector (S1, S3) + - psi (S4, S5) + - paillier-he (S6) + - threshold-sig (S7, S8) + - abac-policy (S9) + - data-watermark (S10) + - compliance-audit (S11) + invariant_assertions: 4 + - C4 psi_intersection_correct (正确性) + - C5 psi_no_leak_non_intersection (隐私) + - C6 paillier_homomorphic_sum (密码学) + - C10 watermark_roundtrip (可恢复性) \ No newline at end of file diff --git a/openspec/changes/chg_0010_federated_risk_control/testcases.md b/openspec/changes/chg_0010_federated_risk_control/testcases.md new file mode 100644 index 0000000..3d4bfb2 --- /dev/null +++ b/openspec/changes/chg_0010_federated_risk_control/testcases.md @@ -0,0 +1,139 @@ +### C1_3bank_did_setup_tds_match +- Scenario: S1 +- Type: e2e +- Priority: P0 +- Given: backend running on 30000, admin token, 3 bank private keys +- When: POST /experiment/runs × 3 with operator=did-identity (per-bank), then POST with operator=tds-connector (matching contract_hash) +- Then: 3 DIDs created + tds match=true + token non-empty (3-part JWT) +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C2_did_verify_loop_tamper_detect +- Scenario: S2 +- Type: e2e +- Priority: P0 +- Given: 3 DIDs from C1 +- When: verify each DID, then mutate one DID's publicKey and re-verify +- Then: original 3 verify returns valid=true; mutated DID verify returns valid=false +- Automated: true +- Bound Task: T2 + +### C3_tds_mismatch_abort +- Scenario: S3 +- Type: e2e +- Priority: P1 +- Given: contract_hash_a ≠ contract_hash_b +- When: POST /experiment/runs with operator=tds-connector +- Then: response.match=false, error="contract-mismatch" +- And: FRC flow aborts (no PSI / aggregation steps executed) +- Automated: true +- Bound Task: T2 + +### C4_psi_intersection_correct +- Scenario: S4 +- Type: e2e +- Priority: P0 +- Given: 3 blacklists A=[f01,f02,f03,f04] / B=[f02,f03,f05] / C=[f01,f03,f06,f07] +- When: POST /experiment/runs with operator=psi +- Then: response.intersection=[f01,f02,f03] (sorted, deduped) +- And: intersection_size=3 +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C5_psi_no_leak_non_intersection +- Scenario: S5 +- Type: e2e +- Priority: P0 (privacy invariant) +- Given: blacklists from C4 +- When: inspect full PSI response (all keys + values) +- Then: output NEVER contains f04/f05/f06/f07 (non-intersection) +- And: output size ≤ min(4,3,4)=3 +- And: no per-bank blacklist size or membership info in output +- Automated: true +- Bound Task: T2 + +### C6_paillier_cross_bank_sum_invariant +- Scenario: S6 +- Type: e2e +- Priority: P0 +- Given: paillier public key, 3 features (100/200/300) +- When: POST /experiment/runs with operator=paillier-he, input={action: "homomorphic_sum", values: [100,200,300]} +- Then: decrypted sum === 600 (mod n) +- And: homomorphic_invariant passes (Enc(a)·Enc(b) mod n² === Enc(a+b)) +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C7_threshold_sig_2shares_reconstruct +- Scenario: S7 +- Type: e2e +- Priority: P0 +- Given: 3-of-3 Shamir shares, payload +- When: POST /experiment/runs with operator=threshold-sig, input={shares: [s1,s2,s3], threshold: 2} +- Then: 2-share Lagrange reconstruction recovers secret +- And: verify_code=0 (signature valid) +- And: recovered payload === original payload +- Automated: true +- Bound Task: T2 + +### C8_threshold_sig_1share_fails +- Scenario: S8 +- Type: e2e +- Priority: P1 +- Given: 3 shares from C7 +- When: POST with shares=[s1] only +- Then: verify_code≠0 +- And: error code="insufficient-shares" or equivalent +- Automated: true +- Bound Task: T2 + +### C9_abac_policy_decision_matrix +- Scenario: S9 +- Type: e2e +- Priority: P0 +- Given: abac policy requiring role=risk-analyst AND region∈[BJ,SH,GZ] AND time∈[09:00,18:00] +- When: 4 POSTs with combinations (allow / 3× deny) +- Then: allow for {role:risk-analyst,region:BJ,time:10:00} +- And: deny "role-deny" for {role:guest} +- And: deny "region-deny" for {region:NY} +- And: deny "timewindow-deny" for {time:20:00} +- Automated: true +- Bound Task: T2 + +### C10_data_watermark_roundtrip +- Scenario: S10 +- Type: e2e +- Priority: P0 +- Given: report text, watermark payload="FRC|2026-09-28|bankA,bankB,bankC" +- When: POST with operator=data-watermark (embed), then POST same text (extract) +- Then: report length unchanged after embed (zero-width chars) +- And: extract returns exact payload string +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C11_audit_chain_hmac_valid +- Scenario: S11 +- Type: e2e +- Priority: P1 +- Given: 8 FRC step entries (S1-S10 condensed: did×3 / tds / psi / paillier / threshold / abac / watermark = ~9 audit entries) +- When: POST with operator=compliance-audit, action=verify_chain +- Then: chain length ≥ 8 +- And: each entry has prev_hash link +- And: chainValid=true +- Automated: true +- Bound Task: T2 + +### C12_e2e_full_flow_8_steps +- Scenario: S12 +- Type: e2e +- Priority: P0 +- Given: canonical 3-bank fixture (BankA/BankC blacklists + features + shares + ABAC subject + report) +- When: 1 shell run executes all 11 steps in sequence (C1-C11 in order) +- Then: pass=12 fail=0 (12 main cases) +- And: total wall-clock < 60s +- And: no operator-not-found or 500 errors in any substep +- Automated: true +- Bound Task: T3 (E2E orchestration test) \ No newline at end of file