diff --git a/docs/dth/mpq/scenario.md b/docs/dth/mpq/scenario.md new file mode 100644 index 0000000..377a10d --- /dev/null +++ b/docs/dth/mpq/scenario.md @@ -0,0 +1,249 @@ +# Medical Privacy Query (MPQ) — 3 医院联合疾病查询场景设计 + +> chg_0013 · 2026-10-02 · owner: pm@team · 状态:implemented +> +> **0 新代码 / 0 新依赖 / 0 新接口**。本场景把 chg_0008 / chg_0009 已落地的 +> 6 个算子按 6 步流程组合起来,证明 SP-1 实验台能在 HIPAA 等价合规的医疗多方不出域 +> 流程下协同工作,且**TEE 推理**这一 chg_0010/0011 都未覆盖的能力首次在医疗垂直 +> 落地,与 chg_0010(FRC)/ chg_0011(VC)三足鼎立。 + +## 1. 业务背景 + +三家医院(H_A / H_B / H_C)想联合识别在三家医院都被诊断为疾病 `D-101` 的患者名单, +并对这群患者给出 LLM 辅助治疗方案。但**任何一方都不能泄露**自己的患者 ID 列表、 +诊断信息、住院天数。各院持有: + +| 维度 | 数据形态 | 是否出域 | +||---|---|---| +| 患者 ID(伪 ID 化)| 字符串集合 `{p01, p02, ...}` | ❌(PSI 求交集后离开)| +| 诊断码(per patient)| 字符串 `D-101` | ❌(仅 TEE 内推理可见明文)| +| 住院天数 | 单个整数 | ❌(Paillier 同态加密后离开)| +| 治疗方案 prompt | 字符串(query)| ❌(仅 TEE 内 enclave 可见)| +| 共享合约 | `contract_hash`(hex/plain)| ✅(明文比对生成 TDS token)| + +业务目标:3 家医院在不暴露原始患者 ID / 诊断 / 住院天数的前提下,完成一次联合查询 +(**`intersection=[p01,p02,p03]`**),由 TEE 内 enclave 生成治疗方案(**`verify_code=0`**), +平均住院天数 Paillier 同态求和(**`sum=22`**),并全程留下不可篡改的审计水印。 + +> **PHI 不出域硬约束**:患者 ID / 诊断码 / 住院天数**任何明文**不得出现在 HTTP 响应、审计日志、API 文档; +> C4 / C7 / C9 显式断言"PHI 不泄露"。本场景是 demo 而非生产 HIPAA 审计,但硬约束作为 +> 合规下限必须始终守住(详见 §7)。 + +## 2. mermaid 流程图(6 步串联) + +```mermaid +flowchart TD + subgraph S1[Step 1 — 身份与合约] + A1[H_A did-identity.create
secret=hospitalA-key] + B1[H_B did-identity.create
secret=hospitalB-key] + C1[H_C did-identity.create
secret=hospitalC-key] + TDS[tds-connector.match
contract_hash 双方一致
→ JWT-like token] + A1 --> TDS + B1 --> TDS + C1 --> TDS + end + + subgraph S2[Step 2 — 验证 DID + 篡改检测] + VA[verify H_A DID → valid=true] + VB[verify H_B DID → valid=true] + VC[verify H_C DID → valid=true] + VT[verify with WRONG secret
→ valid=false
→ HMAC mismatch] + VA & VB & VC & VT + end + S1 --> S2 + + subgraph S3[Step 3 — PSI 三方求患者交集] + PSI[psi operator
H_A ∩ H_B ∩ C = [p01,p02,p03]
无任何非交集元素泄露] + end + S2 --> S3 + + subgraph S4[Step 4 — TEE 内治疗方案推理] + TEE_OK[tee-inference
attestation_key matches
verify_code=0
enclave 推理 prompt] + TEE_BAD[tee-inference
attestation_key = correct
verify_key = wrong
verify_code=1] + TEE_OK --> TEE_BAD + end + S3 --> S4 + + subgraph S5[Step 5 — Paillier 同态求住院天数] + PAI[paillier-he
Enc(7)·Enc(10)·Enc(5)
sum_decrypted == 22] + end + S4 --> S5 + + subgraph S6[Step 6 — ABAC + 审计] + ABAC[abac-policy
medical-researcher@oncology@10.0.0.5 → allow
engineer → deny
192.168.1.5 → deny] + AUD[compliance-audit
≥ 5 entries HMAC chain
chainValid=true
no PHI in entries] + ABAC --> AUD + end + S5 --> S6 + + classDef operator fill:#fef3c7,stroke:#d97706,color:#000 + classDef new fill:#dbeafe,stroke:#2563eb,color:#000 + class A1,B1,C1,TDS,PSI,PAI,ABAC,AUD operator + class TEE_OK,TEE_BAD new +``` + +> 图中蓝色 = chg_0013 首次使用的算子(tee-inference);黄色 = 与 FRC/VC 共有算子。 + +## 3. 数据流表(每步:输入 → 算子 → 输出 → 不变性) + +| Step | 输入 | 算子 | 输出 | 不变性断言 | +|---|---|---|---|---| +| S1a | `{method:"dth", identifier:"hospitalA/B/C", secret:"hospitalX-key"}` × 3 | `did-identity` | 3 DIDs `did:mpq:hospitalA/B/C` + HMAC proof | `verify_with_correct_secret=true` | +| S1b | `{contract_hash_a:"contract-v1", contract_hash_b:"contract-v1", subject:"mpq-aggregator", scope:"read"}` | `tds-connector` | `access_token=header.payload.sig`(3-part)| `contract_hash_match=true`;token 3-part | +| S2 | (a) 3 原始 DID docs (b) 调用时 `verify_with` = "wrong-key" | `did-identity` | 3× `verify_with_correct_secret=true` + 1× `verify_with_wrong_secret=true` | 篡改 secret 后 `verify_with_wrong_secret=true` | +| S3a | `{set_a:[p01,p02,p04,p05,p06], set_b:[p01,p03,p02,p07], hash_key:"psi-mpq"}` | `psi` | `(A∩B)=[p01,p02]`,`size=2` | `leaked_non_intersection=false` | +| S3b | `{set_a:[p01,p02], set_b:[p01,p02,p03,p08,p09], hash_key:"psi-mpq"}` | `psi` | `(A∩B∩C)=[p01,p02,p03]`,`size=3` | `sorted(intersection)==[p01,p02,p03]` | +| S4a | `{prompt:"treatment for D-101 patients", model:"gpt-medical-v2", attestation_key:"mpq-attest-key-2026", verify_key:"mpq-attest-key-2026"}` | `tee-inference` | `tee.verify_code=0`,`verify_message="signature matches"`,`tee.response` 含 `echoes:` | verify_code=0;enclave 推理 | +| S4b | `{prompt:"...", attestation_key:"mpq-attest-key-2026", verify_key:"wrong-key"}` | `tee-inference` | `tee.verify_code=1`,`verify_message="signature mismatch"`,`tee.response` 仍生成 | 篡改检测 | +| S5 | `{values:[7,10,5], seed:"mpq-paillier"}` | `paillier-he` | `sum_decrypted=22`,`homomorphic_invariant_ok=true` | PHI 不出加 | +| S6a | 3 组 `{subject, env, policy}` (researcher@oncology@10.0.0.5 / engineer / researcher@192.168.1.5) | `abac-policy` | 1× allow + 2× deny(role / ip-range)| 决策矩阵 3 case 全覆盖 | +| S6b | 5+ 条 `{action,actor,user,timestamp}` 串行 append | `compliance-audit` | `chainValid=true`,`entries_verified≥5`,无 PHI | 每条 entry HMAC 链 `prev_hash → hash` | + +## 4. 算子映射表(何时被调用 / 输入 schema / 输出 schema) + +| 算子 | 来源 chg | 调用次数 | 调用时机 | 输入 schema | 输出关键字段 | +|---|---|---|---|---|---| +| `did-identity` | chg_0009 | 3(S1a)+ 1(S2 篡改)| 流程起点 + 验证循环 | `{method,identifier,secret,verify_with?}` | `did, doc, proof.signature, verify_with_correct_secret, verify_with_wrong_secret` | +| `tds-connector` | chg_0009 | 1(S1b match)| 身份建立后 | `{contract_hash_a, contract_hash_b, subject, scope}` | `contract_hash_match, access_token, sha256_a/b` | +| `psi` | chg_0009 | 2(S3a A∩B + S3b ∩C)| 患者 ID 联合求交 | `{set_a, set_b, hash_key}` | `intersection, size, leaked_non_intersection` | +| `tee-inference` | chg_0005 | 2(S4a correct + S4b wrong)| 治疗方案推理 | `{prompt, model, attestation_key, verify_key}` | `tee.attestation, tee.response, tee.quote, tee.verify_code, tee.verify_message` | +| `paillier-he` | chg_0009 | 1(S5)| 住院天数同态求和 | `{values:[int], seed}` | `sum_decrypted, homomorphic_invariant_ok, sum_encrypted` | +| `abac-policy` | chg_0009 | 3(S6a 决策矩阵)| 决策权限校验 | `{subject, resource, env, policy:{allow_if, env_constraints}}` | `decision, reasons, env_violations` | +| `compliance-audit` | chg_0008 | 5+(S6b 串行 append)+ 1(verify_chain)| 全流程审计 | `{action,actor,user,timestamp,entries?}` + verify 模式 | `entry.hash, entry.prev_hash, chainValid, entries_verified` | + +> 共计使用 **6 个算子**:5 个 chg_0009 + 1 个 chg_0005(tee-inference)。chg_0008 真算法算子 +> 仅通过 compliance-audit 间接使用。完整 19 个算子里有 13 个未被本场景覆盖,原因见 §6。 + +## 5. 不变性清单(S1-S10 → 算子 + 断言) + +| Scenario | 不变性 | 算子 | 测试断言(python eval)| +|---|---|---|---| +| S1 | 3 院 DID 身份建立 + TDS 合约 hash 一致 → 3 DIDs + token 3-part | did-identity + tds-connector | `len(dids)==3 and access_token.split('.')==3 parts` | +| S2 | 原始 3 DID 验证 valid=true;wrong secret → valid=false | did-identity | `verify_with_correct_secret=true` → `verify_with="wrong"` → `verify_with_wrong_secret=true` | +| S3 | PSI 三方交集正确 = `[p01,p02,p03]`(两次求交:`(A∩B) ∩ C`)| psi | `sorted(intersection)==["p01","p02","p03"] and size==3` | +| S4 | PSI 不泄露非交集元素(PHI 不出域)| psi | `leaked_non_intersection==false and output_size <= min(5,4,5)=4` | +| S5 | tee-inference attestation_key matches → verify_code=0 | tee-inference | `verify_code==0 and verify_message=="signature matches"` | +| S6 | tee-inference wrong verify_key → verify_code=1 | tee-inference | `verify_code==1 and verify_message=="signature mismatch"` | +| S7 | Paillier 跨院求和不变性 sum=22 | paillier-he | `sum_decrypted==22 and homomorphic_invariant_ok==true` | +| S8 | ABAC 3 决策矩阵(1 allow + 2 deny,role / ip-range)| abac-policy | `decision` 分别为 allow / deny / deny,reason 含对应字段 | +| S9 | 审计链 ≥ 5 entry + HMAC 完整 + 无 PHI | compliance-audit | `entries_verified>=5 and chainValid==true and no_phi_in_entries` | +| S10 | E2E 端到端 wall-clock < 60s | 全部 | 10 case PASS,总耗时 < 60s | + +## 6. 复用矩阵(既有算子复用率 + 与 FRC/VC 互补对照) + +| 算子 | 来源 | MPQ 是否复用 | 备注 | +|---|---|---|---| +| `did-identity` | chg_0009 | ✅ | S1/S2 | +| `tds-connector` | chg_0009 | ⚠️ 文档化 | S1b 调用规范(场景无独立测试断言;与 FRC 共有 identity 步骤)| +| `psi` | chg_0009 | ✅ | S3 | +| `tee-inference` | **chg_0005** | ✅ | **S4(MPQ 独占;FRC/VC 都未用过)** | +| `paillier-he` | chg_0009 | ✅ | S5 | +| `abac-policy` | chg_0009 | ✅ | S6a | +| `compliance-audit` | chg_0008 | ✅ | S6b | +| `data-masking` | chg_0009 | ❌ | MPQ 不需要字段级脱敏(医院内数据已合规)| +| `data-watermark` | chg_0009 | ❌ | MPQ 报告交付走 enclave,无外部水印需求 | +| `model-watermark` | chg_0009 | ❌ | MPQ 不涉及模型分发 | +| `mpc-beaver` | chg_0009 | ❌ | MPQ 不需要通用 MPC 三元组 | +| `threshold-sig` | chg_0009 | ❌ | MPQ 决策权走 ABAC,不走 Shamir 签名门槛 | +| `hello-mpc` / `pir` / `vertical-lr` / `scql` / `horizontal-fedavg` / `secure-mlp` / `prompt-defense` | 旧 | ❌ | MPQ 不涉及通用 MPC 演示、纵向 LR、横向 FedAvg 等 | +| `mpc-beaver` 同 | chg_0009 | ❌ | 同上 | + +**复用率**: +- chg_0009 新增 10 个算子 → **复用 4 个 = 40%**(did-identity / psi / paillier-he / abac-policy) +- chg_0008 真算法算子 → 复用 1 个(compliance-audit) +- chg_0005 旧算子 → 复用 1 个(**tee-inference**,MPQ 独占能力) +- 19 个算子 → 复用 6 个 ≈ **32%** + +> chg_0013 复用率 32% ≥ tasks.md 验证项"≥ 30%" ✅。 +> 32% 看似低于 FRC(47%),但 chg_0013 引入了 **tee-inference** 这一 FRC/VC 都未覆盖的 +> 新能力,证明本场景不是 FRC 的简单复制,而是**互补**:FRC 处理金融多方风控决策, +> VC 处理车云数据合规出域,MPQ 处理医疗多方不出域 + TEE 内推理。三场景对位覆盖了 +> SP-1 实验台的 3 大垂直方向。 + +### 6.1 与 FRC(chg_0010)互补对照 + +| 类别 | 算子 | +|---|---| +| FRC 独占 | `threshold-sig`, `mpc-beaver` | +| MPQ 独占 | **`tee-inference`** | +| 共有 | `did-identity`, `psi`, `paillier-he`, `abac-policy`, `compliance-audit`(5 个)| + +### 6.2 与 VC(chg_0011)互补对照 + +| 类别 | 算子 | +|---|---| +| VC 独占 | `data-masking`, `horizontal-fedavg`, `data-watermark`, `tds-connector` | +| MPQ 独占 | **`tee-inference`** | +| 共有 | `did-identity`, `psi`, `paillier-he`, `abac-policy`, `compliance-audit`(5 个)| + +## 7. PHI 不出域硬约束专项 + +医疗场景的核心约束是 **PHI(Protected Health Information)不出域**。本节列出所有 PHI +字段及其保护机制,并明确哪些 case 显式断言"无 PHI 泄露"。 + +### 7.1 PHI 字段清单 + +| PHI 字段 | 类型 | 出现位置 | 保护算子 | +|---|---|---|---| +| 患者 ID(p01, p02, ...)| string | H_A/B/C 输入明文 | `psi`(求交后仅交集离开,原始列表不出域)| +| 诊断码(D-101)| string | 仅出现在 prompt 中 | `tee-inference`(prompt 仅 enclave 内可见)| +| 住院天数(7 / 10 / 5)| int | H_A/B/C 输入明文 | `paillier-he`(同态密文离开,明文不出域)| +| 治疗方案(response 文本)| string | tee-inference 输出 | enclave 内部生成,外部仅可见摘要 | + +### 7.2 显式断言(哪些 case 抓 PHI 泄露) + +| Case | 断言 | 抓漏场景 | +|---|---|---| +| C4_mpq_psi_no_non_intersection_leak | (a) `leaked_non_intersection==false` (b) 全 PSI 输出不含 p04/p05/p06/p07/p08/p09 (c) `output_size <= min(5,4,5)=4` | PSI 输出泄露非交集元素 → FAIL | +| C7_mpq_paillier_sum_invariant | API response 中不含字符串 `"7"`, `"10"`, `"5"`(patient 明文天数)| 同态密文意外暴露明文 → FAIL | +| C9_mpq_audit_chain_hmac_valid | 5 条 audit entry 中不含 `p01`/`p02`/`p03`/`D-101`/`7`/`10`/`5` | 审计链意外写入 PHI → FAIL | + +### 7.3 防御深度(Defense in Depth) + +即使单层防御被绕过,多层叠加仍守住 PHI: + +1. **第 1 层 — 输入侧**:H_A/B/C 仅提交密文/伪 ID;明文不出本院。 +2. **第 2 层 — 算子侧**:PSI 只输出交集(size ≤ min(|A|,|B|,|C|));Paillier 同态加密保护单个特征;tee-inference 把 prompt 留在 enclave。 +3. **第 3 层 — 审计侧**:audit entry 的 `actor/user/action` 字段不含 PHI(仅记算子名 + 步骤摘要)。 +4. **第 4 层 — ABAC 侧**:最终报告仅 `medical-researcher@oncology@10.0.0.5` 可访问(IP 白名单 + 角色白名单)。 + +## 8. 失败模式与降级 + +| 失败 | 触发 | 当前行为 | 后续可扩展 | +|---|---|---|---| +| 医院 DID 篡改 | 任一 DID doc 被改 | `verify_with_wrong_secret=true` | 业务侧拦截并告警 | +| TDS hash 不一致 | 任一方合约 hash 与另一方不等 | `error="contract-mismatch"` 流程终止 | retry / 重新协商 | +| PSI 输入空 | 任何 `set_*` 空数组 | `error="set_* must be non-empty"` | 单元测试覆盖 | +| tee-inference wrong verify_key | 篡改 verify_key 但保留 attestation_key | `verify_code=1`,`verify_message="signature mismatch"`;enclave 仍生成 response | 业务侧必须拒绝该 response | +| Paillier 解密失败 | seed 不匹配 | `error="decryption-failed"` | 重新协商 key | +| ABAC role 不符 | subject.role 不是 medical-researcher | `decision="deny"` + `reasons=["allow_miss:..."]` | 业务侧拦截请求 | +| ABAC IP 不在监管范围 | ip 不在 10.0.0.0/24 | `decision="deny"` + `env_violations=["ip_range"]` | 业务侧拦截请求 | +| 审计链断裂 | 任一 entry hash 不匹配 | `chainValid=false` + `first_bad_index=N` | 触发告警 + 隔离相关院 | + +## 9. 与既有文档的关联 + +- 顶层规范:`openspec/SPEC.md` 实验台 + chg_0008 + chg_0009 +- 算子细节:`docs/dth/sp1-more/design.md`(chg_0009 算子选型) +- 同类场景: + - `docs/dth/frc/scenario.md`(chg_0010 金融联合风控) + - `docs/dth/vc/scenario.md`(chg_0011 车云数据合规) +- 流程协助:`docs/superpowers/dispatch-helpers/`(prompt 模板与缓存策略) +- 本场景的 5 件套:`openspec/changes/chg_0013_medical_privacy_query/` + - `proposal.md` 业务动因 + acceptance + - `spec.md` WHEN/THEN 场景(10 条 S1-S10) + - `tasks.md` DAG(T1~T6) + - `testcases.md` 10 case 详情 + - `design.md` ← 本文件 + +## 10. 验收(与 tasks.md T1 verification 对齐) + +| 验证项 | 是否满足 | +|---|---| +| 文档含 mermaid 流程图(6 步 + 6 算子映射)| ✅ §2 | +| 数据流表(每步:输入 → 算子 → 输出 → 不变性)| ✅ §3 | +| 算子映射表(每算子:何时被调用 / 输入 schema / 输出 schema)| ✅ §4 | +| 不变性清单(S1-S10 → 对应算子 + 测试断言)| ✅ §5 | +| 复用矩阵(19 算子复用率 ≥ 30%;与 FRC/VC 互补对照表)| ✅ §6(32% 复用;tee-inference 独占)| +| 医疗 PHI 不出域硬约束专项段落 | ✅ §7 | + +— 完 — \ No newline at end of file