diff --git a/openspec/changes/chg_0011_vehicle_cloud_compliance/proposal.md b/openspec/changes/chg_0011_vehicle_cloud_compliance/proposal.md new file mode 100644 index 0000000..83420ad --- /dev/null +++ b/openspec/changes/chg_0011_vehicle_cloud_compliance/proposal.md @@ -0,0 +1,92 @@ +--- +change_id: chg_0011 +status: proposed +owner: pm@team +stakeholders: [pd, tm, qa, dev] +priority: P1 +target_release: v0.7 +created: 2026-09-29 +skip_coverage: false +--- + +# chg_0011 vehicle_cloud_data_compliance — 车云数据合规场景 + +## Why + +chg_0010 金融联合风控覆盖了"数据不出域"的多方计算场景,但**车云数据流通**是反向场景—— +**数据必须出域**(车端 → 云端聚合),出域前必须:合约授权 + 字段脱敏 + 水印嵌入 + 审计追溯。 + +需求 §5 提到三个候选场景(金融联合风控 / 医疗隐私查询 / 车云数据合规)。chg_0010 已落地金融 +联合风控(侧重"多方不出域");chg_0011 选 **车云数据合规**(侧重"数据出域可追溯"),覆盖 +互补威胁模型。 + +**算子互补性**(与 chg_0010 比): +- chg_0010 重用 8/10 chg_0009 算子:did-identity / psi / tds-connector / paillier-he / + threshold-sig / abac-policy / data-watermark / compliance-audit +- chg_0011 重用 6 算子,其中 2 个与 chg_0010 互补(chg_0010 几乎没用): + - **data-masking**(chg_0011 重度使用)—— GPS / 车牌 / 车主 ID 脱敏 + - **horizontal-fedavg**(chg_0010 没用到)—— 车云 fleet 均值聚合 +- chg_0011 不重用:mpc-beaver / model-watermark / psi / paillier-he / threshold-sig / + did-identity / secure-mlp / model-watermark + +**约束**(与 chg_0010 一致): +- 不改 backend 代码(19 算子已齐备,0 新依赖,0 新接口) +- 不加前端(backend-only e2e) +- 复用 chg_0006 LMS 的多实体建模思路:admin token + per-vehicle 标签模拟车队 + +## Scope + +**做**: + +1. **场景设计文档** `docs/dth/vc/scenario.md`:定义 VC 场景的 6 步流程图 + 数据流图 + + 不变性约束 + 与既有算子的映射表 + 出域 PII 清单。 + +2. **集成 e2e 测试** `tests/e2e/dth_vc.test.sh`:10 case 串起 6 个算子,覆盖: + - S1: 车云 TDS 合约匹配(tds-connector: match=true + JWT) + - S2: 车云 TDS 合约 hash 不匹配 → 流程拒绝(tds-connector error="contract-mismatch") + - S3: GPS / 车牌 / 车主 ID 字段脱敏 + 业务字段保留(data-masking) + - S4: 脱敏后 SHA256 hash 可逆(data-masking hash 字段 → 还原原始值) + - S5: 聚合报告零宽水印嵌入 + 提取 roundtrip(data-watermark) + - S6: 聚合报告可见长度不变(data-watermark 零宽字符不变可见长度) + - S7: Fleet-wide 均值聚合(horizontal-fedavg: 50 车均值 + σ) + - S8: ABAC 合规分析师通过 + 工程师拒绝(abac-policy) + - S9: 审计链 HMAC 完整(compliance-audit: 6 步 chainValid=true) + - S10: E2E 端到端(S1→S9 全程跑通 + 总耗时 < 60s) + +3. **5 件套 + map.yaml**:spec.md / tasks.md / testcases.md / testcases.map.yaml + +**不做**: + +- ❌ 新建 VC 专属 endpoint(直接复用 `POST /experiment/runs`) +- ❌ 新加 operator(19 算子全够用) +- ❌ 新加依赖(纯 shell + python3 + curl) +- ❌ 改 abac / auth(admin token 全程,per-vehicle 标签在 input 里传) +- ❌ 真车端模拟器(用 admin token + JSON payload 模拟 50 辆车 telemetry) +- ❌ 真云端聚合引擎(horizontal-fedavg 已实现 mock + Gaussian DP 噪声,无需新代码) + +## Acceptance + +- 10 case e2e 全 PASS(chg_0011 自身) +- 7 回归 e2e 全 PASS(chg_0002/0005/0006/0007/0008/0009/0010) +- gate `PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh` gap=0 +- `tsc --noEmit` 0 error(除预存 chg_0002 vertical-lr.ts:52) +- 文档 `docs/dth/vc/scenario.md` 包含:mermaid 流程图 + 数据流表 + 算子映射表 + 不变性清单 + + **出域 PII 清单**(明确每字段是否出域 + 脱敏方式) + +## 与 handoff / chg_0010 的对应 + +- handoff §4 优先级 2(chg_0011 设计候选 B):本 chg 闭环 +- 与 chg_0010 互补:chg_0010 = 数据不出域(多方计算),chg_0011 = 数据出域可追溯 +- 算子复用矩阵:chg_0010 用 8 算子(psi/paillier/threshold/did/tds/abac/watsonmark/audit), + chg_0011 用 6 算子(tds/data-masking/watermark/fedavg/abac/audit),**重叠 4**(tds/abac/watermark/audit), + **互补 2**(masking/fedavg vs psi/paillier/threshold/did) +- 跑完 chg_0010 + chg_0011 = 14/19 算子(74%),剩余 5(mpc-beaver / model-watermark / secure-mlp + 仍待场景) + +## 后续候选 + +- **chg_0012 候选**: + - A. 医疗隐私查询(PSI + paillier + secure-mlp)—— 复用 chg_0010 同款算子 + - B. chg_0010 F2B 扩展(ABAC region 细分 + watermark capacity 升级) + - C. 多方安全聚合(3+ 方 psi + mpc-beaver + threshold-sig) +- chg_0012 决策在 chg_0011 合并后做,避免一次设计太多场景导致饱和 \ No newline at end of file diff --git a/openspec/changes/chg_0011_vehicle_cloud_compliance/spec.md b/openspec/changes/chg_0011_vehicle_cloud_compliance/spec.md new file mode 100644 index 0000000..a3a688e --- /dev/null +++ b/openspec/changes/chg_0011_vehicle_cloud_compliance/spec.md @@ -0,0 +1,103 @@ +# Spec: experiment_platform + +## Requirement + +THE SYSTEM SHALL provide a vehicle-to-cloud data compliance (VC) scenario that composes +6 existing operators (tds-connector / data-masking / data-watermark / horizontal-fedavg / +abac-policy / compliance-audit) into a 6-step end-to-end telemetry egress flow for a 50-vehicle +fleet, proving that **vehicle PII never leaves the OEM boundary in clear text** and **all +downstream cloud consumption is traceable + access-controlled + auditable**, WITHOUT any new +operator / endpoint / dependency, so that 业务方能用现有算子验证"数据出域可追溯"的车云合规场景。 + +## ADDED Scenarios + +### S1 车云 TDS 合约匹配 + +- **WHEN** OEM cloud operator calls tds-connector.match() with matching `contract_hash` + (车端合约 = 云端合约) +- **THEN** output `{match: true, token: <3-part JWT>}` (Bearer for downstream auth) +- **AND** schema_version = "v2" +- **AND** token is non-empty + has 3-part JWT structure + +### S2 车云 TDS 合约 hash 不匹配 → 流程拒绝 + +- **WHEN** tds-connector.match() is called with `contract_hash_oem ≠ contract_hash_cloud` +- **THEN** output `{match: false, error: "contract-mismatch"}` +- **AND** the VC flow is aborted at step 1 (no masking / aggregation runs) + +### S3 GPS / 车牌 / 车主 ID 字段脱敏 + 业务字段保留 + +- **WHEN** vehicle telemetry `{v1: "京A12345", gps: "39.9,116.4", owner_id: "13800138000", + speed_kmh: 65, energy_kwh: 18.5, anomaly_code: 0}` is passed through data-masking +- **THEN** output: + - `v1` → masked (e.g., "京A*****5") + - `gps` → masked (e.g., "39.9****" or hash-based) + - `owner_id` → masked (e.g., "138****8000") + - `speed_kmh` → unchanged (业务字段保留) + - `energy_kwh` → unchanged + - `anomaly_code` → unchanged +- **AND** masked fields are NEVER the same as original (except for empty) +- **AND** schema_version = "v2" + +### S4 脱敏后 SHA256 hash 可逆 + +- **WHEN** data-masking outputs a `{field, mask_type, hash}` triple for owner_id +- **THEN** `mask_type === "sha256-truncate"` or `"sha256-reversible"` +- **AND** the hash field, when reversed via the operator's inverse (lookup), yields the + original value +- **AND** the masking is deterministic (same input → same hash) + +### S5 聚合报告零宽水印嵌入 + 提取 roundtrip + +- **WHEN** the cloud aggregator embeds `payload = "VC|2026-09-29|oem-id-OEM123"` into a + fleet-wide report via data-watermark +- **THEN** the report's visible length is **unchanged** (zero-width chars U+200B/200C/200D/FEFF) +- **AND** data-watermark.extract(report) recovers the **exact** payload string +- **AND** schema_version = "v2" + +### S6 聚合报告可见长度不变(不可见字符纯隐身) + +- **WHEN** S5 watermark is embedded +- **THEN** the visible (non-zero-width) character count of the report equals the pre-embed count +- **AND** the byte/char delta is entirely zero-width (U+200B/200C/200D/FEFF) +- **AND** the report renders identically in a non-ZW-aware viewer + +### S7 Fleet-wide 均值聚合(horizontal-fedavg) + +- **WHEN** 50 simulated vehicles submit `energy_kwh` values +- **THEN** `final_weights` is a single averaged value (mean across 50 vehicles) +- **AND** Gaussian DP noise is added (trace `noise_scale` exposed) +- **AND** running the same fleet 100 times, stddev of final_weights is in range + `[0.5*σ, 2.0*σ]` +- **AND** schema_version = "v2" + +### S8 ABAC 合规分析师通过 + 工程师拒绝 + +- **WHEN** ABAC policy requires `subject.role === "compliance-analyst"` AND + `subject.region in ["BJ","SH","GZ"]` AND `env.timewindow 09:00-18:00` AND + `resource.classification in ["public","internal"]` +- **THEN** request from `{role: "compliance-analyst", region: "BJ", time: "10:00", + resource: "internal"}` returns `{allow: true}` +- **AND** request from `{role: "engineer", region: "BJ", time: "10:00", + resource: "internal"}` returns `{allow: false, reason: "role-deny"}` +- **AND** request from `{role: "compliance-analyst", region: "NY", time: "10:00", + resource: "internal"}` returns `{allow: false, reason: "region-deny"}` +- **AND** request from `{role: "compliance-analyst", region: "BJ", time: "20:00", + resource: "internal"}` returns `{allow: false, reason: "timewindow-deny"}` + +### S9 审计链 HMAC 完整(6 步) + +- **WHEN** the full VC flow runs through steps S1→S8 +- **THEN** compliance-audit chain contains ≥ 6 entries (one per VC step: + tds-match / masking / watermark / fedavg / abac / auth) +- **AND** each entry has HMAC-SHA256 chain linkage (`prev_hash` references the prior entry) +- **AND** `chainValid === true` on full replay +- **AND** any tampered entry triggers `chainValid === false` + +### S10 E2E 端到端 6 步不变性 + +- **WHEN** a single shell run executes S1→S9 in order with the canonical 50-vehicle fixture +- **THEN** every intermediate assertion in S1..S9 passes +- **AND** the final output reports `e2e dth_vc: pass=N fail=0` (N = 10 main cases + sub-assertions) +- **AND** total wall-clock time for the e2e is < 60s +- **AND** NO cleartext GPS / 车牌 / 车主 ID appears in any cloud-side output (privacy invariant) \ No newline at end of file diff --git a/openspec/changes/chg_0011_vehicle_cloud_compliance/tasks.md b/openspec/changes/chg_0011_vehicle_cloud_compliance/tasks.md new file mode 100644 index 0000000..28ed4be --- /dev/null +++ b/openspec/changes/chg_0011_vehicle_cloud_compliance/tasks.md @@ -0,0 +1,77 @@ +# Tasks (DAG) + +- id: T1 + type: architect + depends_on: [] + output: docs/dth/vc/scenario.md + verification: + - mermaid 流程图(6 步:合约 → 脱敏 → 水印 → 聚合 → ABAC → 审计) + - 数据流表(每步:输入 → 算子 → 输出 → 不变性) + - 算子映射表(每算子:何时被调用 / 输入 schema / 输出 schema) + - 不变性清单(S1-S10 → 对应算子 + 测试断言) + - **出域 PII 清单**(明确每字段:是否出域 + 脱敏方式 + 反向验证手段) + - 复用矩阵(既有 19 算子的复用率 ≥ 30%,新增 chg_0010+0011 复用 ≥ 70%) + +- id: T2 + type: implementer + depends_on: [T1] + output: | + tests/e2e/dth_vc.test.sh (10 case e2e shell 脚本) + verification: + - 脚本无 set -e(每条 assertion 独立计数) + - 使用 DTH_BASE=${DTH_BASE:-http://127.0.0.1:30000} + - 每条 assert 用 python3 json_get(与 chg_0008/0009/0010 一致) + - 包含 admin token login (pre_admin_login) + - 10 case 覆盖 S1..S10 + - 总耗时 < 60s + - 复用既有 helpers(不要重写 json_get / assert / login) + - 含 4 不变性断言(脱敏可逆 / 水印 roundtrip / 水印长度不变 / 审计链 valid) + - 含 1 拒绝路径(TDS mismatch → 流程拒绝) + - 含 1 跨车 E2E 串联(S10 = S1→S9 一气呵成) + +- id: T3 + type: tester + depends_on: [T2] + output: | + 1 次完整 e2e 跑通(bash tests/e2e/dth_vc.test.sh 10/0) + verification: + - pass=10 fail=0 + - 含 4 不变性断言(脱敏可逆 / 水印 roundtrip / 水印长度不变 / 审计链 valid) + - 含 1 篡改检测(audit chain 篡改 → chainValid=false) + - 含 1 拒绝路径(TDS mismatch → 流程拒绝) + - 含 1 跨车 E2E 串联(S10 = S1→S9 一气呵成) + - 含 1 隐私不变性(NO cleartext GPS/车牌/车主ID 出域) + +- id: T4 + type: qa + depends_on: [T3] + output: | + PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh + 7 e2e 套件全跑(chg_0002/0005/0006/0007/0008/0009/0010/0011 = 8 套) + verification: + - gate gap = 0 + - tsc --noEmit 0 error(除预存 chg_0002 vertical-lr.ts:52) + - 7 回归 + 1 新 = 8 e2e 套件全 PASS + - 总断言数 ≥ 157(147 旧 + 10 新 = 157) + - 报告落 /tmp/chg_0011-qa.log + +- id: T5 + type: pm + depends_on: [T4] + output: | + openspec/changes/chg_0011_vehicle_cloud_compliance/.xstudio-report.md + chg_0011 实施说明(取舍 + 与 chg_0010 算子复用对比 + 后续 chg_0012 候选) + verification: + - 报告含 改动文件清单 + 门禁结果 + 算子复用率(与 chg_0010 互补矩阵)+ 是否建议合并 + - 报告大小 ≥ 30 行 + - chg_0011 任务全部完成 + +# Notes + +- 无 backend 代码改动(19 算子已齐备) +- 无 frontend 代码改动(业务场景 e2e only) +- 无新依赖 +- 测试端口 30000(与既有 e2e 一致;DTH_BASE env 可覆盖) +- 提交顺序建议:T1 (docs) → T2 (test script) → T3 (test PASS) → T4 (gate + regressions) → T5 (report) +- 与 chg_0009/0010 的边界:不动 OperatorsService / ExperimentModule 注册,仅新增 test 脚本 + 文档 +- 与 chg_0010 互补:chg_0010 = "数据不出域",chg_0011 = "数据出域可追溯",两者复用不同算子子集 \ No newline at end of file diff --git a/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.map.yaml b/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.map.yaml new file mode 100644 index 0000000..5e7630e --- /dev/null +++ b/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.map.yaml @@ -0,0 +1,50 @@ +# spec: experiment_platform@chg_0011 +scenarios: + - id: S1 + cases: [C1_vc_tds_contract_match] + - id: S2 + cases: [C2_vc_tds_mismatch_abort] + - id: S3 + cases: [C3_vc_field_aware_masking] + - id: S4 + cases: [C4_vc_masking_reversible] + - id: S5 + cases: [C5_vc_watermark_embed_extract_roundtrip] + - id: S6 + cases: [C6_vc_watermark_invisible_length_invariant] + - id: S7 + cases: [C7_vc_fleet_fedavg_aggregation] + - id: S8 + cases: [C8_vc_abac_compliance_analyst] + - id: S9 + cases: [C9_vc_audit_chain_hmac] + - id: S10 + cases: [C10_vc_e2e_full_flow_6_steps] +gate: + blocking_gap_tolerance: 0 + implementation_files: + - tests/e2e/dth_vc.test.sh + - docs/dth/vc/scenario.md + test_files: + - tests/e2e/dth_vc.test.sh +notes: + reuses_operators_no_new_code: true + operator_coverage: "6 of 19 existing operators (32%) + 2 complementary to chg_0010" + operators_used: + - tds-connector (S1, S2) + - data-masking (S3, S4) + - data-watermark (S5, S6) + - horizontal-fedavg (S7, chg_0008) + - abac-policy (S8) + - compliance-audit (S9) + invariant_assertions: 4 + - C4 vc_masking_reversible (可逆) + - C5 vc_watermark_roundtrip (roundtrip) + - C6 vc_watermark_invisible_length (不可见) + - C9 vc_audit_chain_valid (审计链) + privacy_invariant: C10 NO cleartext GPS/车牌/车主ID in cloud-side output + complements_chg_0010: true + complementary_operators_vs_chg_0010: + - chg_0011 exclusive: data-masking, horizontal-fedavg + - chg_0010 exclusive: psi, paillier-he, threshold-sig, did-identity + - shared: tds-connector, abac-policy, data-watermark, compliance-aaudit \ No newline at end of file diff --git a/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.md b/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.md new file mode 100644 index 0000000..ea8e31b --- /dev/null +++ b/openspec/changes/chg_0011_vehicle_cloud_compliance/testcases.md @@ -0,0 +1,117 @@ +### C1_vc_tds_contract_match +- Scenario: S1 +- Type: e2e +- Priority: P0 +- Given: backend running on 30000, admin token, matching contract_hash +- When: POST /experiment/runs with operator=tds-connector +- Then: response.match=true + token non-empty (3-part JWT) +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C2_vc_tds_mismatch_abort +- Scenario: S2 +- Type: e2e +- Priority: P1 +- Given: contract_hash_oem ≠ contract_hash_cloud +- When: POST with operator=tds-connector +- Then: response.match=false, error="contract-mismatch" +- And: VC flow stops at step 1 (no masking/aggregation runs) +- Automated: true +- Bound Task: T2 + +### C3_vc_field_aware_masking +- Scenario: S3 +- Type: e2e +- Priority: P0 +- Given: telemetry {v1, gps, owner_id, speed_kmh, energy_kwh, anomaly_code} +- When: POST with operator=data-masking +- Then: PII fields (v1/gps/owner_id) masked, business fields (speed_kmh/energy_kwh/anomaly_code) unchanged +- And: masked values ≠ original values +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C4_vc_masking_reversible +- Scenario: S4 +- Type: e2e +- Priority: P0 (privacy invariant) +- Given: masked owner_id with hash field +- When: data-masking inverse lookup via hash +- Then: recovered value === original owner_id +- And: same input → same hash (deterministic) +- Automated: true +- Bound Task: T2 + +### C5_vc_watermark_embed_extract_roundtrip +- Scenario: S5 +- Type: e2e +- Priority: P0 +- Given: fleet-wide report text, watermark payload="VC|2026-09-29|oem-id-OEM123" +- When: POST data-watermark (embed), then POST same text (extract) +- Then: report visible length unchanged (zero-width chars) +- And: extract returns exact payload string +- And: schema_version=v2 +- Automated: true +- Bound Task: T2 + +### C6_vc_watermark_invisible_length_invariant +- Scenario: S6 +- Type: e2e +- Priority: P0 (visibility invariant) +- Given: original report (no watermark) +- When: embed payload, then count visible chars (filter out U+200B/200C/200D/FEFF) +- Then: visible_char_count_after === visible_char_count_before +- And: byte_delta > 0 (watermark chars present) but visible_delta = 0 +- Automated: true +- Bound Task: T2 + +### C7_vc_fleet_fedavg_aggregation +- Scenario: S7 +- Type: e2e +- Priority: P0 +- Given: 50 vehicle energy_kwh values +- When: POST with operator=horizontal-fedavg 100 times +- Then: final_weights is single averaged value (~mean) +- And: trace.noise_scale exposed +- And: across 100 runs, stddev of final_weights ∈ [0.5*σ, 2.0*σ] +- Automated: true +- Bound Task: T2 + +### C8_vc_abac_compliance_analyst +- Scenario: S8 +- Type: e2e +- Priority: P0 +- Given: ABAC policy role=compliance-analyst AND region∈[BJ,SH,GZ] AND time∈[09:00,18:00] AND resource.classification∈[public,internal] +- When: 4 POSTs with combinations (allow / 3× deny) +- Then: allow for {role:compliance-analyst, region:BJ, time:10:00, resource:internal} +- And: deny "role-deny" for {role:engineer} +- And: deny "region-deny" for {region:NY} +- And: deny "timewindow-deny" for {time:20:00} +- Automated: true +- Bound Task: T2 + +### C9_vc_audit_chain_hmac +- Scenario: S9 +- Type: e2e +- Priority: P0 +- Given: 6 VC step entries (tds-match / masking / watermark / fedavg / abac / audit-read) +- When: POST with operator=compliance-audit, action=verify_chain +- Then: chain length ≥ 6 +- And: each entry has prev_hash link +- And: chainValid=true +- And: tampered entry → chainValid=false +- Automated: true +- Bound Task: T2 + +### C10_vc_e2e_full_flow_6_steps +- Scenario: S10 +- Type: e2e +- Priority: P0 +- Given: canonical 50-vehicle fixture (telemetry + masked hashes + watermark + fedavg outputs + ABAC subjects) +- When: 1 shell run executes all 9 steps in sequence (C1-C9 in order) +- Then: pass=10 fail=0 (10 main cases) +- And: total wall-clock < 60s +- And: NO cleartext GPS/车牌/车主ID in any cloud-side output (privacy invariant) +- Automated: true +- Bound Task: T3 (E2E orchestration test) \ No newline at end of file