chg_0010: federated_risk_control 提案 — 3 银行联合反欺诈场景(5 件套,无新代码,纯算子组合)

场景:3 银行(BankA/BankB/BankC)联合反欺诈,不泄露 PII,6 步流程
  1. DID 建立 + TDS 合约匹配 (did-identity + tds-connector)
  2. PSI 黑名单交集 (psi)
  3. Paillier 跨行特征聚合 (paillier-he)
  4. Threshold 2-of-3 风险签名 (threshold-sig)
  5. ABAC 风险分析师访问控制 (abac-policy)
  6. 数据水印嵌入 (data-watermark) + 审计链 HMAC (compliance-audit)

12 case e2e (S1-S12) 覆盖 8/10 chg_0009 算子 + 1 chg_0008 算子
4 不变性断言:PSI 正确 / PSI 不泄露 / Paillier 同态 / 水印 roundtrip

约束:
- 不改 backend 代码(10 算子已齐备,0 新依赖,0 新接口)
- 不加前端(backend-only e2e)
- 复用既有 /experiment/runs 一个一个跑算子
- admin token 全程,per-bank 标签在 input 里传

gate: PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh → PASS (gap=0, 9 archived + 1 active)

handoff §2 优先级 2 闭环。
实施待 sandbox dispatch(T1 architect → T5 pm)。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
xstudio agentandClaude Code committed 2026-09-28 21:49:33 +08:00
1 parent 56e26dbe86
commit fadd9e46d0
5 files changed
+434

No files matched your search

@@ -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️⃣框架文档化待办)。
@@ -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)
@@ -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 脚本
@@ -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 (可恢复性)
@@ -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)