diff --git a/.workbuddy/memory/2026-10-27.md b/.workbuddy/memory/2026-10-27.md new file mode 100644 index 0000000..70166f1 --- /dev/null +++ b/.workbuddy/memory/2026-10-27.md @@ -0,0 +1,77 @@ +# 2026-10-27 工作日志 + +> 本轮主线(承接 10-26 的 B5 收尾):**用户要求「上游的 tdc/tds 是有测试用例的,你找出来,在 tdc-rs 上也跑通」**。 +> ⇒ 产出:**上游测试用例普查 + 移植台账 + 第五把尺子 + 29 条对位用例 + 文档四件套同步**。 + +--- + +## 1. 普查:上游到底有多少测试用例 + +**只读克隆**(`/tmp/sswtdc-probe` = TDC、`/tmp/sswtds-probe` = TDS;ssw-common 两侧都有)。 + +🔴 **关键发现:上游的测试用例没有统一入口**: + +| 形态 | 谁跑 | 说明 | +|---|---|---| +| `*Test.java`(`@Test`) | Maven surefire(`mvn test`) | 6 个 | +| `*SelfTest.java`(纯 `main`) | **surefire 不跑** ⇒ 上游自己靠 `tools/run-java-selftests.sh` 人工跑 | 9 个(退出码 0 = 过、**4 = UNVERIFIED ≠ 过**) | + +⇒ 合计 **15 个类**。「我们搬没搬」这件事**光看仓库答不出来** ⇒ 必须有可复算的清单。 + +## 2. 搬了什么(3 类 · 29 条对位用例) + +| 上游类 | 对位文件 | 条数 | +|---|---|---| +| `ssw.common.guard.ProdGuardSelfTest` | `tests/upstream_guard_parity.rs` | 12 | +| `ssw.tds.controller.SswProdRuntimeGuardSelfTest` | `tests/upstream_guard_parity.rs` | 7 / 10(另 3 条属门户验证码通道) | +| `ssw.tdc.client.ProviderInvokeTimeoutsSelfTest` | `tests/upstream_tds_timeout_parity.rs` | 10 | + +⇒ 顺带补齐两处**产品代码**(不是只写测试): + +- **`src/platform/guard.rs`(新)**:上游 `ProdGuard` 的**六条判据**纯函数化。 + 关键是判据④(**含**弱值片段 ⇒ 反绕过)与「`CIPHER_KEY` 不受管」(上游 chg_0020 同款裁定)。 +- **`src/tdc/client/tds.rs`**:超时**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS`) + + **cause 链超时分类**(照抄上游第 2 跳:连接被拒 / DNS 失败 / 无 cause ⇒ **不改写**文案)。 + +## 3. 没搬什么(12 类 + 3 条断言) + +逐条理由在 `scripts/upstream-test-ledger.tsv` 的 `reason` 列,汇总在 `docs/known-limitations.md` **L8**。 +主因:**本仓没有对应的功能**(Nax/K8s/P2P/MaxKey/CA/IP 白名单/LLM 客户端)⇒ 硬搬只会是**假绿**。 + +## 4. 第五把尺子 `scripts/check-upstream-tests.sh` + +纯静态(秒级、可进任何闸门)⇒ 查四件事:① 台账每行 8 列 + `status` 合法 + `reason` 非空; +② `PORTED` 行的对位文件**存在**且登记的用例函数**真在**里面;③ `OUT-OF-SCOPE` 行对位为空; +④ **文件级集合相等**(防少登记 / 多登记,靠前缀约定 `upstream_`/`hop1_`/`hop2_`/`runtime_guard_`/`prod_guard_` 识别移植用例)。 + +**🔴 负例已验**:登记不存在的函数名 / 漏登记一个用例 ⇒ 两种都判红。 + +配套 `scripts/upstream-test-census.py`(可复算的上游测试类普查 + 与台账对账): +上游克隆**不在场 ⇒ 跳过该侧校验,不判红**(台账那侧照查)。 + +## 5. 文档同步 + +`docs/UPSTREAM-TEST-PARITY.md`(新 · 人读版)/ `docs/known-limitations.md` **L8** / +`docs/decisions.md` **D22 / D23** / `CLAUDE.md`(尺子表 ④→⑤、目录树、命令速查、实现细节 22–23、坑位表 5 行、文档表)。 + +## 6. 回归结果(全绿) + +| 闸门 | 结果 | +|---|---| +| `cargo test` | **278 通过 / 0 失败**(基线 246 ⇒ **+32**;lib 176 + bin 2 + 集成 98 + 文档 2) | +| `scripts/smoke.sh` | **PASS=80 FAIL=0** | +| `scripts/check-boundary.sh` | 0 处未记账越界 | +| `scripts/check-entity.sh` | PASS=13 FAIL=0 | +| `scripts/check-contract.sh` | 132 条端点一致 | +| `python3 scripts/check-citations.py` | 148 条引用 / 0 失效(新增把 `docs/UPSTREAM-TEST-PARITY.md` 加进默认清单) | +| `scripts/check-upstream-tests.sh` | 台账 15 行(PORTED 3 / OUT-OF-SCOPE 12)· 对账通过 | + +## 7. 踩过的坑 + +| 症状 | 根因 | 处理 | +|---|---|---| +| `prod_guard_min_len_is_enforced` 判红 | 测试值 `a1234567890` **含**弱值片段 `123456` ⇒ 命中判据④ 而不是⑥ | 换成 `abcdefghij`(10 位、不含任何弱值片段)⇒ 只可能命中「过短」 | +| hop1 断言 `code == 200` 失败 | `internal_catalog` 返回的是**解包后的 `data`**,不是信封 | 假服务器改回 `{"code":200,"data":{...}}`,断言改成查 `data.ok` | +| `Box` 装不进 cause 链测试 | 递归类型不能自含 `Box` | 改用递归 `enum Chain { Leaf(io::Error), Node(Box) }` 并实现 `Error::source` | +| 上游 hop 1 的**反射判据抄不了** | Rust 的 `reqwest::Client` **不暴露**超时 getter(无 `get_timeout()`) | 改用**行为级**判别:同一个延迟 TCP 服务器,短超时 ⇒ 超时错、长超时 ⇒ 成功 ⇒ 结论**等价且更强**(真跑 socket 层) | +| 上游一个令牌两个方向通用,本仓是**两个** | 键名映射 | 两个**都**受管;出向令牌**仅在配了 `SSW_TDS_BASE_URL` 时**才进守卫 ⇒ 本地单机模式不会被误停 | diff --git a/CLAUDE.md b/CLAUDE.md index ac9edb9..a55862e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,6 +41,7 @@ tdc-rs/ │ │ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data}) │ │ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal) │ │ ├── cipher.rs # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts) +│ │ ├── guard.rs # 生产档弱密钥判据(**纯函数**,照抄上游 ssw.common.guard.ProdGuard) │ │ ├── compare.rs # 常量时间比较(**全仓唯一一份实现**,业务侧 pub use 复用) │ │ ├── ids.rs # id 生成 │ │ ├── protocol.rs # 协议版本闸门 @@ -63,15 +64,19 @@ tdc-rs/ ├── schema/ │ └── migrate.sql # tdc_* + base_* schema(include_str! 内嵌进二进制,**30 + 3 表**,**不在 web root**) ├── scripts/ # build-frontend.sh / gen-migrate.sh / reset-data.sh / reap-ipc-leaks.sh -│ # + **四把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态) +│ # + **五把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态) │ # / check-entity.sh(实体静态)/ check-contract.sh(契约对账) +│ # / check-upstream-tests.sh(**上游测试用例移植台账**对账) │ # + contract_probe.py(check-contract 的探针)/ check-citations.py(文档引用自检) │ # + upstream-action-census.py(上游动作端点普查 · 只读上游克隆) +│ # + upstream-test-census.py(**上游测试类普查**)/ upstream-test-ledger.tsv(台账真源) │ # + boundary-ledger.txt / upstream-json-ignore.tsv ├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_model / spa_fallback / bootstrap_fail / tds_biz) +│ # + upstream_guard_parity.rs / upstream_tds_timeout_parity.rs(**上游用例移植** · 29 条) ├── docs/ # **契约四件套**(B5):contract.md(唯一真源)/ decisions.md / known-limitations.md / runbook.md │ # + ACCOUNT-LAYER.md(账号层契约) │ # + 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md) +│ # + UPSTREAM-TEST-PARITY.md(**上游测试用例移植台账**·人读版) │ # + superpowers/(v3 spec / 执行提示词 / 上游差异表) ├── MIGRATION.md # **Java TDC ⇄ Rust 逐件翻译表** + 数据 ETL + 口令换算(B5) ├── HOWTO_ENTITY.md # **加一个实体**的操作手册(B5) @@ -130,6 +135,10 @@ tdc-rs/ cargo build # debug cargo build --release # 发布版 +# 测试(⚠️ 跑之前先看 SysV 信号量余量,见「已知踩坑」最后几行) +cargo test # 全量(lib + bin + 集成 + 文档) +cargo test --test upstream_guard_parity --test upstream_tds_timeout_parity # 上游用例移植(29 条) + # 运行 PORT=30000 ./target/debug/tdc-connector cd tds-stub && node server.js # 无 TDS 时起契约桩(:30100) @@ -150,7 +159,7 @@ bash scripts/reap-ipc-leaks.sh # 回收(会改系统 IPC 表) > 起服务时 stdout **不要**指向 `/dev/null`(进程会以 100 退出),**不要**落进提交或报告 > (首启会打印一次性 `secretKey`)。 -## 四把尺子(B1a 建立 · 回归网) +## 五把尺子(B1a 建立 · 回归网) 🔴 **`cargo test` 打不到 HTTP 层**(进程内 `oneshot`)⇒ HTTP 状态码 / 响应头 / body 原始 JSON 文本 / 404·405 真实形状 / 隐藏字段是否真不在出参 —— **全都没被测到**。⇒ 尺子补上这一层。 @@ -159,7 +168,8 @@ bash scripts/reap-ipc-leaks.sh # 回收(会改系统 IPC 表) bash scripts/smoke.sh # ① HTTP 契约(真进程真 HTTP,零 node 依赖)→ PASS=80 FAIL=0 bash scripts/check-boundary.sh # ② 边界静态(平台层不含业务知识)→ 账本制 bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完整性)→ PASS=13 FAIL=0 -bash scripts/check-contract.sh # ④ 契约对账(docs/contract.md 端点表 ↔ 实际注册路由)→ 132 条端点一致 +bash scripts/check-contract.sh # ④ 契约对账(docs/contract.md 端点表 ↔ 实际注册路由)→ 132 条端点一致 +bash scripts/check-upstream-tests.sh # ⑤ 上游测试用例移植台账对账(台账 ⇄ 代码 ⇄ 上游测试类集合) python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号` 指向真文件真行) ``` @@ -169,9 +179,16 @@ python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号` | `scripts/check-boundary.sh` | 4 个接触点:CP1 平台层无 `tdc_`/实体端点前缀 · CP2 平台层无业务实体名 · CP3 引擎不按实体名分支(零 `match api_name`) · CP4 平台 auth 无字面量端点路径 | 同上 | | `scripts/check-entity.sh` | E1 表在 `migrate.sql` · E2 `path` == `/api/ssw/tdc/` · E3 六条路由齐全 · E4 `hidden_fields` 覆盖上游 `@JsonIgnore` · E5 编码前缀不重复 · E6 权限键不重复(B4 删表后自动跳过) · E7 `f_`↔camelCase 双向闭合 | 同上 | | `scripts/check-contract.sh` | **端点表 ↔ 实际注册路由**双向对账:路径全集相等 + 每路径的方法集合相等(运行时探测:404=未注册 / 405=方法不对 / 其它=已注册)+ **端点数相等** | 0 一致 / 1 不一致 / 2 前置错 | +| `scripts/check-upstream-tests.sh` | 台账(`scripts/upstream-test-ledger.tsv`)自检:每行 8 列 + `status` 合法 + `reason` 非空 · `PORTED` 行的对位文件**存在**且登记的用例函数**真在**里面 · `OUT-OF-SCOPE` 行的对位为空 · **文件级集合相等**(防少登记/多登记)· 上游克隆在场时**上游测试类集合 == 台账登记集合**(新增上游类没登记 ⇒ 红) | 同上 | - 🔴 **`docs/contract.md` 的端点表不许手工维护**(B5)⇒ 由 `scripts/contract_probe.py --gen` 生成, 由 `scripts/check-contract.sh` 对账(**漏写 / 多写 / 写错方法** 三种都判红)。 +- 🔴 **上游测试用例的「搬没搬」也不许靠记忆** ⇒ 台账 `scripts/upstream-test-ledger.tsv` 是唯一真源, + `scripts/check-upstream-tests.sh` 对账(上游新增一个测试类而台账没登记 ⇒ 红)。 + ⇒ **上游 `*SelfTest.java` 没有 runner 接线**(surefire 只跑 `@Test`;上游自己靠 + `tools/run-java-selftests.sh` 人工跑,退出码 4 = UNVERIFIED ≠ 过)⇒ 本仓把它们落成 + `cargo test` 常规用例(判据是纯函数 ⇒ 可离线断言)。 + 逐类对照见 `docs/UPSTREAM-TEST-PARITY.md`,超范围清单见 `docs/known-limitations.md` **L8**。 - 🔴 **基线断言数 N = 80**(B1a 锁 75,B4 加 5)⇒ **后续每批只许增不许减**; **B1b 搬家前后必须 == 75**(搬家不改对外契约 ⇒ 断言数不增不减)。 - 🔴 **边界尺子用「账本制」(ratchet)**:越界不是一律红,而是**必须被记账** @@ -328,6 +345,26 @@ python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号` 参与方表有 ⇒ 用 `ALIVE`。 - 🔴 表名 / 列名**全部来自注册表**,启动时 `entity::validate()` 走标识符白名单(不过 ⇒ 秒退)。 逐条口径见 **`docs/contract.md` §子表聚合**。 +22. **生产档弱密钥守卫是**纯函数**(上游 `ProdGuard` 的六条判据,一条不能少)**: + `src/platform/guard.rs` 的 `guard_violations(map)` **不读进程全局 env**(上游把判据抽成纯函数就是为了能离线断言)。 + - 🔴 **六条判据**:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值**精确等于**弱值⇒违规 + ④值**含**弱值⇒违规(**反绕过**:默认值加个后缀也拦住)⑤值命中**弱标记词**⇒违规 ⑥长度<12⇒违规。 + **只实现 ③ 而漏 ④** ⇒ 把默认值改成 `…-e2e1` 就能绕过。 + - 🔴 **弱标记词按整体词匹配**(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)`)⇒ 用 `contains` 会**误拦**合法部署 + (强随机串里偶然出现 `test`)。 + - 🔴 **`CIPHER_KEY` 不受管**(上游 chg_0020 同款裁定:那是**协议共享值**,必须发给浏览器)⇒ + 把它塞进受管清单 ⇒ "保持默认同值"这种正常部署会被**恒假红**。 + - 🔴 **出向令牌只在配了 `SSW_TDS_BASE_URL` 时才受管** ⇒ 本地单机模式不会被误停。 + 逐条对照见 `docs/UPSTREAM-TEST-PARITY.md` §2.1,决策见 `docs/decisions.md` **D22**。 +23. **出向 TDS 的超时分类靠 cause 链,不靠错误文案**: + `src/tdc/client/tds.rs` 的 `cause_chain_has_timeout()` 沿 `Error::source()` **有界**(`depth < 16`,照抄上游)往下找。 + - 🔴 **只有** cause 链里有超时(`reqwest::Error::is_timeout()` 或 `io::ErrorKind::TimedOut`)才改写成 + 「调用 TDS 超时(当前 connect=…ms / read=…ms,可用 `SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS` 调大)」; + **连接被拒 / DNS 失败 / 无 cause ⇒ 不改写**(仍是「TDS 不可达」)—— + 🔴 **把连接被拒说成"超时"会把排查引向错误方向**(调超时没用,要查网络/证书)。 + - 超时值**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` 默认 3000 / `SSW_TDS_READ_TIMEOUT_MS` 默认 5000), + `platform::config::timeout_ms_from` 对**空白 / 非法 / ≤0** 一律回落默认值。 + 决策见 `docs/decisions.md` **D23**。 ## 数据模型 @@ -431,8 +468,9 @@ JSON 文件**保留不删**,但**后端不再读取**(存量账号**不导 |---|---|---| | `docs/contract.md` | **对外契约真源**(132 端点全表 / 响应形状 / 命名 / 数据模型) | 改端点、改出参形状 | | `docs/decisions.md` | **为什么这么定**(D1–D21,每条带代码落点 `文件:行号`) | 有人问「为什么不那样写」 | -| `docs/known-limitations.md` | 已知限制 L1–L6(双读写路径 / 未建列 / 挂不了的子表 / 权限敞开 / 动作端点未实现 / 分发形态) | 有人问「这功能怎么没有」 | +| `docs/known-limitations.md` | 已知限制 **L1–L8**(双读写路径 / 未建列 / 挂不了的子表 / 权限敞开 / 动作端点未实现 / 分发形态 / 单段尾被吞 / **上游测试类超范围**) | 有人问「这功能怎么没有」 | | `docs/runbook.md` | 怎么起 / 跑尺子 / 常见故障(11 条) | 服务起不来、尺子红了 | +| `docs/UPSTREAM-TEST-PARITY.md` | **上游测试用例移植台账**(15 个上游类 → 3 搬 / 12 超范围 · 逐条对照 + 复跑命令) | 有人问「上游那个用例我们搬了吗」 | | `docs/ACCOUNT-LAYER.md` | `base_user` 契约 + 官方双 md5 公式 + 管理员位 fail-closed + 角色码 | 改登录 / 改口令 / 加账号 | | `MIGRATION.md` | **Java TDC ⇄ Rust 逐件翻译表** + 数据 ETL + 口令换算 | 迁数据 / 对上游 | | `HOWTO_ENTITY.md` | **加一个实体**的操作手册(只碰 `entity/` 一处) | 加表 / 加端点 | @@ -496,6 +534,10 @@ JSON 文件**保留不删**,但**后端不再读取**(存量账号**不导 | 账号层改成 DB 后 `mobilePhone`/`description` 从 `null` 变 `""` | 存了空串 | 用 `NULLIF(,'')` ⇒ 空串落 SQL NULL(**出参形状不变**) | | 引导管理员的 `/Auth/Me` 角色码是**空数组** | 判据的 `IN` 列表是 `tdcProvider/tdcConsumer/tdsReadOnly`,而引导绑的是 `user` | **上游同口径**(D9/S7)⇒ 别去"修"它 | | 改完口令还是登不进去 | 存成了裸 `md5(明文)`,而登录走 `md5(md5(明文)+secretkey)` | 入库必须用**官方双 md5 公式**(`official_password_hash`);改密**不换** secretkey | +| 弱密钥守卫形同虚设(默认值加个后缀就放过) | 只比了**精确值**,漏了上游判据④(**含**弱值片段) | 六条判据一条不能少(`src/platform/guard.rs`);对位用例 `prod_guard_default_value_with_suffix_is_blocked` | +| 部署后启动就被拒,但令牌看着没问题 | 把 `CIPHER_KEY`(**协议共享值**)也塞进了受管清单 | 上游 chg_0020 已把 `security.security-key` 移出受管清单 ⇒ 本仓 `CIPHER_KEY` 同款裁定(**不得**受管) | +| 出向 TDS 报「超时」但把超时调大也没用 | **连接被拒 / DNS 失败**被误判成超时 | 超时分类只认 **cause 链**里的超时(`is_timeout()` / `ErrorKind::TimedOut`)⇒ 被拒/解析失败**不改写**文案 | +| 上游加了新测试类,本仓毫无察觉 | 上游 `*SelfTest.java` **surefire 不跑**(无统一入口) | `scripts/check-upstream-tests.sh` 对账台账 `scripts/upstream-test-ledger.tsv`(上游新增类没登记 ⇒ 红) | ## 明确不在本仓库范围 diff --git a/docs/UPSTREAM-TEST-PARITY.md b/docs/UPSTREAM-TEST-PARITY.md new file mode 100644 index 0000000..fa13710 --- /dev/null +++ b/docs/UPSTREAM-TEST-PARITY.md @@ -0,0 +1,181 @@ +# 上游测试用例移植台账(UPSTREAM-TEST-PARITY) + +> 🔴 **本文件回答一个问题**:上游 TDC / TDS / ssw-common 里**有哪些测试用例**,我们在 tdc-rs 上**搬了哪些、没搬哪些、为什么**。 +> +> **机器可复算的版本**在 `scripts/upstream-test-ledger.tsv`(台账 · 唯一真源); +> **自检**在 `scripts/check-upstream-tests.sh`(第五把尺子)。 +> 本文件是**人读版**(背景 + 逐类说明 + 复跑命令)。 + +--- + +## 1. 为什么要做这件事 + +上游的测试用例**没有统一入口**: + +| 上游形态 | 谁跑 | 本仓对位 | +|---|---|---| +| `*Test.java`(带 `@Test`) | Maven **surefire**(`mvn test`) | `cargo test`(集成测试) | +| `*SelfTest.java`(纯 `main`) | **surefire 不跑** ⇒ 上游自己靠 `tools/run-java-selftests.sh` 人工跑(退出码 0 = 过、**4 = UNVERIFIED ≠ 过**) | `cargo test`(`tests/upstream_*.rs`) | + +⇒ 「上游有哪些用例、我们搬没搬」这件事**光靠肉眼看仓库是答不出来的** ⇒ 必须有一份 +**可复算的清单 + 一把对账的尺子**,否则上游新增一个类而我们没看见 ⇒ **静默漂移**。 + +**普查结果**:上游 TDC + TDS + ssw-common 共 **15 个测试类**(6 个 JUnit + 9 个 SelfTest) +⇒ 本仓 **3 个已移植**(29 条对位用例)、**12 个判定为超范围**(逐条记理由 ⇒ `docs/known-limitations.md` L8)。 + +--- + +## 2. 逐类台账 + +### 2.1 已移植(3 类 · 29 条对位用例) + +| 上游类 | 仓库 | 形态 | 上游断言 | 本仓对位 | +|---|---|---|---|---| +| `ssw.common.guard.ProdGuardSelfTest` | ssw-common | SelfTest | 10 | `tests/upstream_guard_parity.rs`(**12** 条) | +| `ssw.tds.controller.SswProdRuntimeGuardSelfTest` | TDS | SelfTest | 12 | `tests/upstream_guard_parity.rs`(**7** 条 / 10 条中可搬的部分) | +| `ssw.tdc.client.ProviderInvokeTimeoutsSelfTest` | TDC | SelfTest | 11 | `tests/upstream_tds_timeout_parity.rs`(**10** 条) | + +> 本仓 12 + 7 + 10 = **29 条**对位用例,全部落在 `cargo test` 里(离线、秒级、无外部依赖)。 + +#### ① `ProdGuardSelfTest` ⇒ 生产档弱密钥守卫 + +**上游真源**:`boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/guard/ProdGuardSelfTest.java` +(判据本体 `.../src/main/java/ssw/common/guard/ProdGuard.java`) + +上游 `ProdGuard.violations(map)` 的**六条判据**(缺一条即空检查 ⇒ 逐条照抄): + +| # | 判据 | 本仓落点 | 对位用例 | +|---|---|---|---| +| ① | 键**不在** map 里 ⇒ **跳过**(不判本应用没有的键) | `src/platform/guard.rs:137` | `prod_guard_absent_key_is_not_falsely_blocked` | +| ② | 值为 null / 空白 ⇒ 违规 | `:147` | `prod_guard_blank_value_is_named` / `runtime_guard_prod_with_null_token_violates_without_panic` | +| ③ | 值**精确等于**已知弱值 ⇒ 违规 | `:152` | `prod_guard_exact_weak_value_is_blocked` / `prod_guard_default_weak_values_are_still_blocked` | +| ④ | 值**含**已知弱值 ⇒ 违规(**反绕过**) | `:158` | `prod_guard_default_value_with_suffix_is_blocked` | +| ⑤ | 值命中**弱标记词** ⇒ 违规 | `:166` | `prod_guard_weak_marker_word_is_blocked` / `prod_guard_weak_marker_is_whole_word_only` | +| ⑥ | 长度 < 12 ⇒ 违规 | `:174` | `prod_guard_min_len_is_enforced` / `prod_guard_too_short_value_is_blocked` | +| — | **强值必放行**(防"守卫恒红") | — | `prod_guard_strong_values_are_all_allowed` | +| — | 报错**点名**违规键 | `src/platform/guard.rs:188` | `prod_guard_violation_message_names_the_key` | +| — | 协议共享值**不受管**(上游 chg_0020) | `src/platform/guard.rs:29` | `prod_guard_cipher_key_is_not_guarded` | + +**🔴 键名映射**(上游一个令牌两个方向通用 ⇒ 本仓拆成两个 ⇒ **两个都受管**): + +| 上游 `GUARDED` 键 | 本仓 | 说明 | +|---|---|---| +| `ssw.internal-token` | `SSW_INTERNAL_TOKEN` | 入向(`X-Internal-Token` 闸门) | +| `tds-report.password` | `SSW_TDS_INTERNAL_TOKEN` | 出向(对端 internal 通道) | +| `ssw.dataset.pepper` / `oauth.login.jwtSecretKey` / `tdc-delivery.password` / `spring.datasource.password` | — | 本仓**无对应配置项** ⇒ 判据①跳过 | +| ~~`security.security-key`~~ | — | 上游 chg_0020 **已移出**(协议共享值,必须发给浏览器)⇒ 本仓 `CIPHER_KEY` **同样不受管** | + +**🔴 判据④ 存在的理由**:只比精确值时,把默认值后面加一个字符(`ssw-internal-token-e2e1`) +就能绕过守卫 ⇒ 那是"改了但没真改" ⇒ 上游专门有这条,本仓照抄。 + +#### ② `SswProdRuntimeGuardSelfTest` ⇒ 生产档运行时闸门 + +**上游真源**:`boot/ssw-tds/ssw-tds-controller/src/test/java/ssw/tds/controller/SswProdRuntimeGuardSelfTest.java` + +上游 `SswProdRuntimeGuard.evaluate(prod, codeDev, testEnv, token)` 是**纯函数** ⇒ 本仓的对位物同样是纯函数 +(`Config::check_secret_guard()` + `Config::guard_values()`,不读进程全局 env)。 + +| 上游条 | 断言 | 本仓对位 | +|---|---|---| +| ① | 非 prod ⇒ 一律不违规 | `runtime_guard_non_prod_never_violates` | +| ② | prod + 门户验证码通道的 codeDev | 🚫 **超范围**(本仓无门户验证码通道) | +| ③ | prod + 令牌为空 ⇒ 违规并点名 | `runtime_guard_prod_with_empty_token_violates` | +| ④ | prod + 令牌为 null ⇒ 违规、不抛异常 | `runtime_guard_prod_with_null_token_violates_without_panic` | +| ⑤ | prod + 仓库默认弱值 ⇒ 违规 | `runtime_guard_prod_with_default_token_violates` | +| ⑥ | prod + 全强值 ⇒ 放行 | `runtime_guard_prod_with_strong_token_passes` | +| ⑦ | **判别性**(只翻 prod 一位 ⇒ 结论必须翻转) | `runtime_guard_is_discriminable_on_the_prod_switch` | +| ⑧ | 未声明测试环境 ⇒ 不放行 | 🚫 **超范围**(门户验证码通道) | +| ⑨ | 已声明测试环境 ⇒ 只放行验证码、**不放行**内部令牌 | 🚫 **超范围**(门户验证码通道) | +| ⑩ | **任何部署档位都解锁不了弱令牌** | `runtime_guard_no_deployment_flag_unlocks_a_weak_token` | + +> ②⑧⑨ 三条都属**门户验证码通道**(`ssw.portal.code-dev`)⇒ 本仓**没有该通道** +> ⇒ 记 `OUT-OF-SCOPE-PART`(见 `docs/known-limitations.md` L8)。 +> ⑩ 在本仓以**更强的形式**成立:连"单机模式"这种部署档位都解锁不了弱令牌。 + +#### ③ `ProviderInvokeTimeoutsSelfTest` ⇒ 出向超时的两跳判据 + +**上游真源**:`boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/ProviderInvokeTimeoutsSelfTest.java` + +| 跳 | 上游判据 | 本仓对位 | 手法差异 | +|---|---|---|---| +| ① | 注入的超时值**真的落进 socket 工厂**(反射读 `SimpleClientHttpRequestFactory`)+ 判别性 | `hop1_injected_timeout_actually_reaches_the_socket_layer` / `hop1_changing_the_injected_value_changes_the_client` | 🔴 **行为级替代反射**:Rust 的 `reqwest::Client` **不暴露**超时 getter ⇒ 改用「短超时 ⇒ 超时错 / 长超时 ⇒ 成功」(同一个延迟 TCP 服务器)⇒ 结论**等价且更强**(真跑 socket 层,不是读字段) | +| ② | **只有** cause 链里有 `SocketTimeoutException` 才改写文案;`ConnectException` / `UnknownHostException` / 无 cause ⇒ **不改写**;多层包装仍须命中;cause 链**有界**(`depth < 16`) | `hop2_read_timeout_is_rewritten_and_names_current_values` / `hop2_connect_timeout_is_rewritten` / `hop2_connection_refused_is_not_rewritten` / `hop2_dns_failure_is_not_rewritten` / `hop2_no_cause_is_not_rewritten` / `hop2_multilevel_wrapped_cause_is_still_detected` / `hop2_cause_chain_walk_is_bounded` / `hop2_end_to_end_connection_refused_stays_unreachable` | 照抄(`src/tdc/client/tds.rs:74` 的 `cause_chain_has_timeout` + `:112` 的 `timeout_text_or_null`) | + +> 🔴 判据②的**反例**(连接被拒 / DNS 失败 **不得**说成"超时")在本仓是**实机**验证的: +> `hop2_end_to_end_connection_refused_stays_unreachable` 真打一个没人监听的端口 ⇒ 文案必须是「TDS 不可达」。 + +### 2.2 判定为超范围(12 类) + +逐条理由在 `scripts/upstream-test-ledger.tsv` 的 `reason` 列,汇总见 `docs/known-limitations.md` **L8**。 +分类: + +| 类别 | 类 | 为什么超范围 | +|---|---|---| +| 隐私计算执行面 | `ExecNfsSupportTest` / `NaxPodSupportTest` / `NaxExecRenderTest` / `K8sSandboxClientRenderTest` | 依赖 **Nax 引擎 + K8s 拓扑**(NFS 通道 / Pod 模板渲染)⇒ 本仓明确不做(`CLAUDE.md`「明确不在本仓库范围」) | +| P2P 传输 | `P2pTransferTimeoutsSelfTest` | 判据对象是 **P2P 出向客户端** ⇒ 本仓无 P2P 通道;**机制**本身已由 `ProviderInvokeTimeoutsSelfTest` 那条覆盖 | +| MaxKey SSO | `MaxkeyRegisterPrecheckSelfTest` / `MaxkeyAppRegistrarLogicSelfTest` / `MaxkeyMgtClientLiveSelfTest` | 本仓**不实现 MaxKey SSO**(`/Auth/SsoConfig` 恒 `enabled:false`,见 L2);第三条还是**实机**打真 MaxKey | +| CA 签发 | `CertSignerStrictSelfTest` | 软 PKI / CA 签发由上游 **scard 安全平面**承担 ⇒ 本仓不做 | +| 守门告警表 | `GuardAlertTypeSelfTest` | 告警表在 **TDS 侧** ⇒ 本仓无对应表 | +| IP 白名单 | `IpWhitelistUtilTest` | 本仓**没有**该功能(入向只认内部令牌 + 会话令牌) | +| LLM 客户端 | `SswLLMClientTest` | 本仓**没有** LLM 客户端 | + +--- + +## 3. 怎么复跑 + +```bash +# ① 对位用例(29 条,秒级、离线) +cargo test --test upstream_guard_parity --test upstream_tds_timeout_parity + +# ② 第五把尺子:台账自检 + 与上游普查对账 +bash scripts/check-upstream-tests.sh + +# ③ 只看台账不判红(排障) +bash scripts/check-upstream-tests.sh --report + +# ④ 重新普查上游测试类(上游克隆不在场 ⇒ 自动跳过该侧校验,不判红) +python3 scripts/upstream-test-census.py +python3 scripts/upstream-test-census.py --check + +# ⑤ 上游克隆路径可覆盖 +UPSTREAM_TDC_CLONE=/tmp/sswtdc-probe UPSTREAM_TDS_CLONE=/tmp/sswtds-probe \ + bash scripts/check-upstream-tests.sh +``` + +🔴 **上游克隆不在场不判红**(只跳过「上游有、台账无」与「上游文件存在」两项)—— +台账里登记的类**仍然**按台账校验(PORTED 行必须真有对位用例)。 + +--- + +## 4. 台账格式(`scripts/upstream-test-ledger.tsv`,制表符分隔) + +| 列 | 含义 | +|---|---| +| 1 `upstream_class` | 上游全限定类名 | +| 2 `upstream_repo` | `TDC` / `TDS` / `COMMON`(ssw-common 两侧都有 ⇒ 记 `COMMON`) | +| 3 `upstream_file` | 相对**克隆根目录**的路径 | +| 4 `kind` | `JUNIT`(surefire 跑) / `SELFTEST`(纯 main,**surefire 不跑**) | +| 5 `assertions` | 上游断言条数(`-` = 未逐条计数) | +| 6 `tdc_counterpart` | 本仓对位:`文件::fn1+fn2+…`(`-` = 无对位) | +| 7 `status` | `PORTED` / `OUT-OF-SCOPE` | +| 8 `reason` | 搬法说明 / 不搬的理由(**必填**) | + +**尺子管的四件事**: + +1. 每行 8 列、`status` 合法、`reason` 非空; +2. `PORTED` 行的对位文件**存在**、登记的用例函数**真在**那个文件里; +3. `OUT-OF-SCOPE` 行的对位必须为空(`-`); +4. **文件级集合相等**:台账登记的用例集合 == 对位文件里实际存在的移植用例集合(防少登记 / 多登记)。 + +🔴 第 4 条靠**前缀约定**识别"移植用例":`upstream_` / `hop1_` / `hop2_` / `runtime_guard_` / `prod_guard_` +⇒ 辅助函数(`spawn_delayed_server` 之类)不会被误计。 + +--- + +## 5. 相关文档 + +| 文档 | 讲什么 | +|---|---| +| `docs/decisions.md` **D22 / D23** | 守卫语义升级为上游六条判据;出向超时外置到 env + cause 链分类 | +| `docs/known-limitations.md` **L8** | 12 个超范围的上游测试类 + 3 条门户验证码相关的未搬断言 | +| `docs/TDC-TDS-CONTRACT.md` | 出向通道的降级三档(超时归入「不可达」那一档的**细分**) | diff --git a/docs/decisions.md b/docs/decisions.md index 414d310..8b8f08b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -17,6 +17,7 @@ | B3(子表) | D19 | | B4(账号层) | D15 / D16 / D20 / D21 | | B5(文档层) | D10 / D12 的兑现 | +| 上游对齐(测试移植) | D22 / D23 | --- @@ -45,6 +46,8 @@ | **D19** | **子表挂载面逐父子不同**(`Aggregate` / `Detail` / `List` 三面) | 上游口径**不是**「子表都挂详情」:`Resource`/`Dataset` 的子表只在 `/Detail` 聚合体(普通详情**不带**);`DataInterface` 的子表只在普通详情(上游覆写了基类详情,且**没有** `/Detail` 路由);`DeliveryTask` 的参与方挂详情**与**列表(`decorate` 批量挂)。⇒ 子表声明从 `(key, table)` 二元组升级为 `ChildTable` 结构(外键列 / 父行取值列 / 排序列 / 存活谓词 / 挂载面),引擎仍**零 `match api_name`**(只认列名)。**`outbox` 是本仓扩展**(上游不挂,但 `local_task_id` = 任务 `f_id` ⇒ 货真价实的子表);**`tdc_demo_car_insurance` 挂不了**(无父外键 ⇒ 记为已知限制 L3) | `src/tdc/entity/mod.rs:60`(`ChildMount`)· `:74`(`ChildTable`)· `:164`(`children_on`)· `src/tdc/entity/resource.rs:34`(Resource 挂 Aggregate 面)· `src/tdc/entity/delivery_task.rs` | 2026-10-26 B3(复核上游 `ResourceServiceImpl#withChildren` / `DataInterfaceController#detail` / `DeliveryTaskController#decorate`) | | **D20** | **账号层切 `base_user` + 官方双 md5 公式 + 删掉 18 键假权限层** | ① **载体**:`data/accounts.json` → `base_user` 表(JSON 文件**保留不删**,但后端**不再读取** ⇒ 存量账号**不导入**,D8);② **口令**:入库用官方公式 `f_password = md5(lower(md5(明文)) + lower(f_secretkey))`,`f_secretkey` **每账号随机**(UUID v4 大写),**改密不换 secretkey**(与官方一致);③ **引导**:`base_user` 无存活行时种一个管理员(`f_is_administrator=1`),**幂等**;`base_role` 逐字照抄上游 `V1.0.1__connector_seed.sql` 的三行(`tdcProvider`/`tdcConsumer`/`user`),管理员绑 `user` 角色;④ **管理员判据** = `f_is_administrator=1`,**查询异常 ⇒ false(fail-closed)**;⑤ **删掉 18 条实体→权限键**(`entity::PERMISSION_KEYS` + `identity::capabilities()` + `crud::require_write_permission()`)—— 那层「解析不出 ⇒ fail-open」**从来就没在管**,留着只是**看起来在管** ⇒ 拆掉并**显式记账**(L4);⑥ **不收紧为 fail-closed**(D11)⇒ 写操作改用上游同款 `require_menu_permission()`(内部令牌 **或** 有登录态) | ① `src/tdc/service/account.rs:621`(`bootstrap_account_layer`)· `src/main.rs:148`(JSON 不再读);② `src/tdc/service/account.rs:124`(`official_password_hash`)· `:137`(`new_j7_id`)· `:576`(`reset_password` **不换** secretkey);③ `src/tdc/service/account.rs:56`(`SEED_ROLES`)· `src/tdc/constant.rs:21`(默认口令);④ `src/tdc/service/account.rs:289`(`is_administrator` fail-closed);⑤ `src/tdc/service/crud.rs:515/662/763`(三个写路径)· `src/platform/auth.rs:243`;⑥ `src/tdc/controller/account.rs:149`(`require_admin`) | 2026-10-26 B4(复核上游 `PasswordTokenGranter.java:186` / `AuthController#me:207` / `TdcCrudController.java:133`) | | **D21** | **角色码暴露在 `/Auth/Me` 的 `roles` 键 + 保留 `require_menu_permission` 登录态闸门** | ① 上游 `AuthController#me:207` 有 `data.put("roles", roles)` ⇒ 本仓 `me_payload` 加 `roles` 键(**出参新增一个键**,形状其余不变);角色码判据**逐字照抄**上游 SQL(`IN ('tdcProvider','tdcConsumer','tdsReadOnly')`)⇒ **只对账号会话算**(上游只有门户登录这一路算角色),身份会话返回**空数组**;② 写操作的门禁换成 `platform::auth::require_menu_permission`(**已在 list/all/detail/aggregate_detail 用着**)⇒ 四个读写面**同一个闸门**,与上游 `requireMenuPermission()` **同构**;③ D9 的悬空码照抄 ⇒ 引导管理员绑 `user` 角色 ⇒ 它的 `roles` **是空数组**(上游同口径,**不是 bug**) | ① `src/tdc/service/identity.rs:360`(`me_payload(…, roles)` 出 `roles` 键)· `:311`(`me`)· `src/tdc/service/account.rs:320`(`role_codes` **逐字**上游 SQL);② `src/tdc/service/crud.rs:207/276/461/822`(四个读面)· `:515/662/763`(三个写面)—— **七个面同一个闸门**;③ `src/tdc/service/account.rs:56`(`SEED_ROLES`) | 2026-10-26 B4 | +| **D22** | **生产档弱密钥守卫升级为上游 `ProdGuard` 的六条判据**(本仓原来只有「默认口令即不安全」这一条) | ① **判据纯函数化**:上游把判据抽成 `ProdGuard.violations(map)`(纯函数,不读 Spring)⇒ 本仓落成 `platform::guard::guard_violations(map)`,不读进程全局 env ⇒ 可离线逐组断言;② **六条判据缺一不可**:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值精确等于弱值⇒违规 ④值**含**弱值⇒违规(**反绕过**:默认值加个后缀也拦住)⑤值命中弱标记词⇒违规 ⑥长度<12⇒违规;③ 与 ④ **分开报错**(照抄上游);③ **双令牌都受管**(上游一个 `ssw.internal-token` 双向通用 ⇒ 本仓拆成入向 `SSW_INTERNAL_TOKEN` / 出向 `SSW_TDS_INTERNAL_TOKEN` ⇒ 两个都受管;出向令牌**仅在配了 `SSW_TDS_BASE_URL` 时**才进守卫 ⇒ 本地单机模式不会被误停);④ **`CIPHER_KEY` 不受管**(上游 chg_0020 已把 `security.security-key` 移出受管清单 —— 那是**协议共享值**,必须发给浏览器 ⇒ 本仓的 `CIPHER_KEY` 同款裁定,否则"保持默认同值"这种正常部署会被判红);⑤ **弱标记词按整体词匹配**(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)` ⇒ 手写等价实现,不引 regex 依赖) | `src/platform/guard.rs:134`(`guard_violations`)· `:101`(`has_weak_marker`)· `:188`(`violation_message`)· `:46`(`WEAK_VALUES`)· `:77`(`GUARDED`)· `src/platform/config.rs:247`(`check_secret_guard`)· `:261`(`guard_values`) | 2026-10-27(复核上游 `ProdGuard.java:119` / `ProdGuardSelfTest.java`) | +| **D23** | **出向 TDS 超时外置到 env + 照抄上游的 cause 链超时分类** | ① **超时值外置**:`SSW_TDS_CONNECT_TIMEOUT_MS`(默认 3000)/ `SSW_TDS_READ_TIMEOUT_MS`(默认 5000)⇒ 上游把超时当**可配项**(不同对端网络条件不同),本仓原来**写死在代码里**;② **cause 链分类**(照抄上游 `ProviderInvokeTimeoutsSelfTest` 第 2 跳):**只有** cause 链里存在超时(`reqwest::Error::is_timeout()` 或 `io::ErrorKind::TimedOut`)才把文案改写成「调用 TDS 超时(当前 connect=…ms / read=…ms,可用 … 调大)」;**连接被拒 / DNS 失败 / 无 cause ⇒ 不改写**(仍是「TDS 不可达」)——🔴 **把连接被拒说成"超时"会把排查引向错误方向**(改超时没用,要改网络/证书);③ **cause 链有界**(`depth < 16`,照抄上游)⇒ 多层包装仍能命中,但环状链不死循环;④ **不引 regex**:弱值/弱标记词判据手写(见 D22) | `src/tdc/client/tds.rs:74`(`cause_chain_has_timeout`)· `:112`(`timeout_text_or_null`)· `:29`(`MAX_CAUSE_DEPTH=16`)· `:171`(`with_timeouts`)· `src/platform/config.rs:130`(`timeout_ms_from`)· `:189`(读 env) | 2026-10-27(复核上游 `ProviderInvokeTimeoutsSelfTest.java`) | --- @@ -52,6 +55,8 @@ - **D1–D16** 的完整措辞(含来源链)在 v3 spec §12;本表只留一行摘要,方便日常查。 - **D17–D21** 是 v3 spec 落点(`06f5a79`)之后、执行中追加的决策 ⇒ 只住本文件。 +- **D22–D23** 是「上游测试用例移植」批次追加的决策(守卫语义升级 / 出向超时外置)⇒ 只住本文件; + 对应的上游真源与逐条对照见 [`UPSTREAM-TEST-PARITY.md`](UPSTREAM-TEST-PARITY.md)。 - **D18 是本轮唯一一处「与执行提示词冲突」**:提示词要求「口径统一为 UTC」,v3 spec §2.3.1 C12 也写了 UTC, 但**全仓 UTC 会引入对上游的新偏差**(上游用服务器本地时区)⇒ 按「spec 与提示词冲突时 spec 优先」的规则, **v3 spec 赢**,但 spec 的「全仓 UTC」与它自己的「B1b 行为零变化」原则冲突 ⇒ 采纳**两套口径**并显式记账。 diff --git a/docs/known-limitations.md b/docs/known-limitations.md index 2e72783..a3dc005 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -316,3 +316,54 @@ curl -s --noproxy '*' -H "X-Internal-Token: $SSW_INTERNAL_TOKEN" \ ``` + +--- + +## L8 · 上游 **15 个测试类**里只搬了 **3 个**(12 个超范围 + 3 条门户断言) + +**现象**:上游 TDC + TDS + ssw-common 共 **15 个测试类**(6 个 JUnit + 9 个 SelfTest), +本仓只移植了 **3 个**(29 条对位用例)⇒ **12 个类**判定为超范围, +另有 **3 条**断言(`SswProdRuntimeGuardSelfTest` 的 ②⑧⑨)超范围。 + +**逐类台账**(机器可复算的版本在 `scripts/upstream-test-ledger.tsv`,人读版在 +[`UPSTREAM-TEST-PARITY.md`](UPSTREAM-TEST-PARITY.md)): + +| 上游类 | 形态 | 超范围的理由 | +|---|---|---| +| `ssw.tdc.support.ExecNfsSupportTest` | JUNIT | 执行侧 **NFS 通道** ⇒ 依赖 Nax 隐私计算引擎 | +| `ssw.tdc.engine.NaxPodSupportTest` | JUNIT | **Nax 引擎 + K8s 拓扑**(NodePort 派生 / 探针 / 投递物) | +| `ssw.tdc.client.NaxExecRenderTest` | JUNIT | Nax 执行 **Pod 模板渲染契约**(依赖 K8s) | +| `ssw.tdc.client.K8sSandboxClientRenderTest` | JUNIT | 沙箱执行 **Pod 模板渲染契约**(依赖 K8s) | +| `ssw.tdc.service.impl.P2pTransferTimeoutsSelfTest` | SELFTEST | 判据对象是 **P2P 传输客户端** ⇒ 本仓无 P2P 出向通道(**机制**已由 `ProviderInvokeTimeoutsSelfTest` 覆盖) | +| `ssw.tds.support.MaxkeyRegisterPrecheckSelfTest` | SELFTEST | **MaxKey SSO** 应用注册预检 ⇒ 本仓不实现 MaxKey SSO(见 L2) | +| `ssw.tds.service.MaxkeyAppRegistrarLogicSelfTest` | SELFTEST | MaxKey 应用登记**编排判据** ⇒ 同上 | +| `ssw.tds.client.MaxkeyMgtClientLiveSelfTest` | SELFTEST | **实机**打真 MaxKey(登录→建应用→授权→回读→退租)⇒ 本仓无 MaxKey 侧 | +| `ssw.tds.crypto.CertSignerStrictSelfTest` | SELFTEST | **CA 签发严格模式** ⇒ 软 PKI 由上游 scard 安全平面承担,本仓不做 | +| `ssw.tds.service.GuardAlertTypeSelfTest` | SELFTEST | **守门告警类型名长度不变式**(`GUARD_` + 原因 ≤ 列宽)⇒ 该告警表在 TDS 侧,本仓无对应表 | +| `ssw.common.util.IpWhitelistUtilTest` | JUNIT | **IP 白名单**(CIDR / 全放 / 归一 / 畸形 fail-closed)⇒ 本仓**没有**该功能(入向只认内部令牌 + 会话令牌) | +| `ssw.common.util.SswLLMClientTest` | JUNIT | **LLM 客户端**(代理 URL 解析 / OpenAI / Anthropic 后缀 / 业务错误 JSON)⇒ 本仓**没有** LLM 客户端 | +| `ssw.tds.controller.SswProdRuntimeGuardSelfTest` ②⑧⑨ | SELFTEST | 三条都属**门户验证码通道**(`ssw.portal.code-dev`)⇒ 本仓无该通道 | + +**为什么不硬搬**: + +- 前 4 条属**隐私计算执行面**(Nax 引擎 + K8s)⇒ 本仓明确不做(`CLAUDE.md`「明确不在本仓库范围」)⇒ + **没有判据对象**可搬(不是"懒得搬",是"没有那个东西")。 +- MaxKey / CA 签发 / IP 白名单 / LLM 客户端 ⇒ 本仓**没有对应功能** ⇒ 搬过来只能是**假绿**。 +- P2P 那条**机制**(超时落进 socket 层 + cause 链分类)已由 `ProviderInvokeTimeoutsSelfTest` 的对位用例覆盖 ⇒ + 只缺**判据对象**。 + +**🔴 风险与兜底**: + +- **风险**:上游改了判据而本仓没跟上 ⇒ **静默漂移**。 +- **兜底**:`scripts/check-upstream-tests.sh`(第五把尺子)+ `scripts/upstream-test-census.py` + ⇒ 上游**新增**一个测试类而台账没登记 ⇒ **红**;台账登记的对位用例被删/改名 ⇒ **红**。 + ⇒ 漂移**有闸门**,不靠"记得看"。 +- **🔴 局限**:尺子只管「台账 ⇄ 代码」和「台账 ⇄ 上游测试类集合」, + **管不了**「上游某个类内部的断言变了」⇒ 那是**人工**要做的(见 `UPSTREAM-TEST-PARITY.md` 的逐条对照表)。 + +**核对方式**: + +```bash +bash scripts/check-upstream-tests.sh # 台账自检 + 上游普查对账 +python3 scripts/upstream-test-census.py # 重新普查上游测试类 +``` diff --git a/scripts/check-citations.py b/scripts/check-citations.py index 57b7421..76cec25 100755 --- a/scripts/check-citations.py +++ b/scripts/check-citations.py @@ -83,6 +83,7 @@ DEFAULT_DOCS = [ "docs/runbook.md", "docs/ACCOUNT-LAYER.md", "docs/CONSOLE-ACCEPTANCE.md", + "docs/UPSTREAM-TEST-PARITY.md", "MIGRATION.md", "HOWTO_ENTITY.md", "CLAUDE.md", diff --git a/scripts/check-upstream-tests.sh b/scripts/check-upstream-tests.sh new file mode 100644 index 0000000..6296072 --- /dev/null +++ b/scripts/check-upstream-tests.sh @@ -0,0 +1,156 @@ +#!/usr/bin/env bash +# 上游测试用例**移植台账**自检(第五把尺子 · 上游对齐向) +# +# 用法: +# bash scripts/check-upstream-tests.sh # 自检(绿 = 0) +# bash scripts/check-upstream-tests.sh --report # 只出报告,不判红(排障用) +# +# 退出码:0 = 绿 / 1 = 有失败 / 2 = 前置错 +# +# 🔴 **纯静态**:不起后端、不连库、不跑 cargo(秒级)⇒ 可进任何一道闸门。 +# (对位用例**真的跑不跑**由 `cargo test` 负责;本尺子只管「台账与代码**对得上**」) +# +# 检查项: +# ① 台账每行 8 列、status 合法、reason 非空 +# ② PORTED 行的对位文件**存在**、每个登记的用例函数**真在**那个文件里 +# ③ OUT-OF-SCOPE 行的对位必须为空(`-`) +# ④ PORTED 行登记的用例数 == 对位文件里**实际**的移植用例数(防少登记) +# ⑤ 上游克隆在场时:上游测试类集合 == 台账登记集合(`upstream-test-census.py --check`) +# +# 上游克隆路径可用 `UPSTREAM_TDC_CLONE` / `UPSTREAM_TDS_CLONE` 覆盖; +# 克隆不在场 ⇒ 跳过 ⑤(不判红)。 + +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +LEDGER="${LEDGER:-${ROOT}/scripts/upstream-test-ledger.tsv}" +PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" +REPORT_ONLY=0 +[ "${1:-}" = "--report" ] && REPORT_ONLY=1 + +[ -n "${PY_BIN}" ] || { echo "❌ 前置错误:找不到 python3。"; exit 2; } +[ -f "${LEDGER}" ] || { echo "❌ 前置错误:台账 ${LEDGER} 不存在。"; exit 2; } + +TMP="$(mktemp -d)" +trap 'rm -rf "${TMP}"' EXIT + +cat >"${TMP}/check.py" <<'PYEOF' +import os +import re +import sys + +ROOT = sys.argv[1] +LEDGER = sys.argv[2] +REPORT_ONLY = sys.argv[3] == "report" + +failures = [] +ported = 0 +out_of_scope = 0 + +# ④ 用「文件级集合相等」防少登记 / 多登记: +# 台账登记的用例集合 == 对位文件里**实际**的移植用例集合。 +registered = {} # 文件 → {用例名} +actual = {} # 文件 → {用例名} + +with open(LEDGER, encoding="utf-8") as fh: + for lineno, raw in enumerate(fh, 1): + line = raw.rstrip("\n") + if not line.strip() or line.lstrip().startswith("#"): + continue + parts = line.split("\t") + cls = parts[0].strip() + if len(parts) < 8: + failures.append("台账 %d 行:列数 %d(应为 8)⇒ %s" % (lineno, len(parts), cls)) + continue + repo, upfile, kind, asserts_n, counterpart, status, reason = ( + parts[1].strip(), parts[2].strip(), parts[3].strip(), parts[4].strip(), + parts[5].strip(), parts[6].strip(), parts[7].strip(), + ) + if status not in ("PORTED", "OUT-OF-SCOPE"): + failures.append("台账 %d 行:status=%s(只能是 PORTED / OUT-OF-SCOPE)⇒ %s" + % (lineno, status, cls)) + continue + if not reason: + failures.append("台账 %d 行:reason 为空(搬/不搬都要写理由)⇒ %s" % (lineno, cls)) + continue + if not upfile or not upfile.endswith(".java"): + failures.append("台账 %d 行:upstream_file 不合法 ⇒ %s" % (lineno, cls)) + continue + if kind not in ("JUNIT", "SELFTEST"): + failures.append("台账 %d 行:kind=%s(只能是 JUNIT / SELFTEST)⇒ %s" + % (lineno, kind, cls)) + continue + + if status == "OUT-OF-SCOPE": + out_of_scope += 1 + if counterpart != "-": + failures.append("台账 %d 行:OUT-OF-SCOPE 的对位必须是 `-` ⇒ %s" % (lineno, cls)) + continue + + # ── PORTED ── + ported += 1 + if "::" not in counterpart: + failures.append("台账 %d 行:PORTED 的对位必须是 `文件::fn1+fn2` ⇒ %s" + % (lineno, cls)) + continue + path, _, fns = counterpart.partition("::") + abs_path = os.path.join(ROOT, path) + if not os.path.isfile(abs_path): + failures.append("台账 %d 行:对位文件不存在:%s ⇒ %s" % (lineno, path, cls)) + continue + with open(abs_path, encoding="utf-8") as fh2: + src = fh2.read() + names = [n.strip() for n in fns.split("+") if n.strip()] + if not names: + failures.append("台账 %d 行:对位用例列表为空 ⇒ %s" % (lineno, cls)) + continue + for n in names: + if not re.search(r"\bfn\s+" + re.escape(n) + r"\b", src): + failures.append("台账 %d 行:对位用例 `%s` 不在 %s 里 ⇒ %s" + % (lineno, n, path, cls)) + registered.setdefault(path, set()).update(names) + +# ④ 文件级集合相等:台账登记的 == 文件里实际有的移植用例 +# (前缀约定:移植用例一律带下列前缀之一 ⇒ 辅助函数不会被误计) +PORTED_PREFIX = ("upstream_", "hop1_", "hop2_", "runtime_guard_", "prod_guard_") +for path, names in sorted(registered.items()): + abs_path = os.path.join(ROOT, path) + with open(abs_path, encoding="utf-8") as fh2: + src = fh2.read() + found = set(re.findall(r"\bfn\s+([A-Za-z0-9_]+)\b", src)) + found = {n for n in found if n.startswith(PORTED_PREFIX)} + for n in sorted(found - names): + failures.append("%s 里的移植用例 `%s` **未登记台账** ⇒ 补台账(或它不该存在)" % (path, n)) + for n in sorted(names - found): + failures.append("台账登记的 `%s` 在 %s 里找不到(已改名/已删?)" % (n, path)) + +print("台账:%d 行(PORTED %d / OUT-OF-SCOPE %d)" + % (ported + out_of_scope, ported, out_of_scope)) +if failures: + print("❌ 台账自检不通过:") + for f in failures: + print(" · %s" % f) + sys.exit(1) +print("✅ 台账自检通过:每条 PORTED 的对位用例都在、每条 OUT-OF-SCOPE 都写了理由") +PYEOF + +"${PY_BIN}" "${TMP}/check.py" "${ROOT}" "${LEDGER}" "${REPORT_ONLY}" +STATIC_RC=$? + +# ⑤ 上游克隆在场时:上游测试类集合 ⇄ 台账登记集合 +CENSUS_RC=0 +if "${PY_BIN}" "${ROOT}/scripts/upstream-test-census.py" --check; then + : +else + CENSUS_RC=$? +fi + +if [ "${REPORT_ONLY}" = "1" ]; then + echo "(--report:不判红)" + exit 0 +fi + +if [ "${STATIC_RC}" != "0" ] || [ "${CENSUS_RC}" != "0" ]; then + exit 1 +fi +exit 0 diff --git a/scripts/upstream-test-census.py b/scripts/upstream-test-census.py new file mode 100644 index 0000000..675e326 --- /dev/null +++ b/scripts/upstream-test-census.py @@ -0,0 +1,182 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""上游(TDC / TDS / ssw-common)测试用例**普查** + 与台账对账。 + +用法: + python3 scripts/upstream-test-census.py # 打印普查结果(TSV) + python3 scripts/upstream-test-census.py --check # 与台账对账(有差异 ⇒ 退出码 1) + +上游克隆路径(可用环境变量覆盖): + UPSTREAM_TDC_CLONE 默认 /tmp/sswtdc-probe + UPSTREAM_TDS_CLONE 默认 /tmp/sswtds-probe + +台账: + scripts/upstream-test-ledger.tsv(默认) + +🔴 **为什么要有它**:上游的测试用例**没有统一入口** —— + `*Test.java` 靠 surefire 跑,`*SelfTest.java`(纯 main)surefire **不跑**、 + 上游自己靠 `tools/run-java-selftests.sh` 人工跑 ⇒ + 「上游到底有哪些测试用例、我们搬没搬」这件事**必须有一份可复算的清单**, + 否则上游新增一个类而我们没看见 ⇒ 静默漂移。 + +🔴 **克隆不在场 ⇒ 不判红**(只跳过该侧的完整性校验)—— + 台账里登记的类**仍然**按台账校验(PORTED 行必须真有对位用例)。 +""" + +import argparse +import os +import re +import sys + +DEFAULT_TDC_CLONE = os.environ.get("UPSTREAM_TDC_CLONE", "/tmp/sswtdc-probe") +DEFAULT_TDS_CLONE = os.environ.get("UPSTREAM_TDS_CLONE", "/tmp/sswtds-probe") +DEFAULT_LEDGER = os.path.join( + os.path.dirname(os.path.abspath(__file__)), "upstream-test-ledger.tsv" +) + +REPO_LABEL = {"tdc": "TDC", "tds": "TDS"} + + +def scan_clone(root, label): + """扫一个克隆根,返回 {类全名: (仓库标签, 相对路径, kind)}。""" + found = {} + if not os.path.isdir(root): + return found, False + present = True + for dirpath, _dirs, files in os.walk(root): + if "/src/test/java" not in dirpath.replace(os.sep, "/"): + continue + for f in files: + if not f.endswith(".java"): + continue + path = os.path.join(dirpath, f) + rel = os.path.relpath(path, root) + try: + with open(path, encoding="utf-8", errors="replace") as fh: + text = fh.read() + except OSError: + continue + m = re.search(r"^\s*package\s+([\w.]+)\s*;", text, re.M) + pkg = m.group(1) if m else "?" + cls = f[:-5] + if "@Test" in text: + kind = "JUNIT" + elif re.search(r"public\s+static\s+void\s+main", text): + kind = "SELFTEST" + else: + kind = "OTHER" + found["%s.%s" % (pkg, cls)] = (label, rel, kind) + return found, present + + +def read_ledger(path): + """读台账 ⇒ {类全名: 行字典}。""" + rows = {} + if not os.path.isfile(path): + return rows + with open(path, encoding="utf-8") as fh: + for lineno, raw in enumerate(fh, 1): + line = raw.rstrip("\n") + if not line.strip() or line.lstrip().startswith("#"): + continue + parts = line.split("\t") + if len(parts) < 8: + sys.stderr.write( + "⚠️ 台账 %s:%d 列数不足 8(应为 8 列)\n" % (path, lineno) + ) + continue + rows[parts[0].strip()] = { + "class": parts[0].strip(), + "repo": parts[1].strip(), + "file": parts[2].strip(), + "kind": parts[3].strip(), + "assertions": parts[4].strip(), + "counterpart": parts[5].strip(), + "status": parts[6].strip(), + "reason": parts[7].strip(), + "lineno": lineno, + } + return rows + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--tdc-clone", default=DEFAULT_TDC_CLONE) + ap.add_argument("--tds-clone", default=DEFAULT_TDS_CLONE) + ap.add_argument("--ledger", default=DEFAULT_LEDGER) + ap.add_argument("--check", action="store_true") + args = ap.parse_args() + + census = {} + missing_clones = [] + for root, label in ((args.tdc_clone, "TDC"), (args.tds_clone, "TDS")): + found, present = scan_clone(root, label) + if not present: + missing_clones.append("%s(%s)" % (label, root)) + for cls, (repo, rel, kind) in found.items(): + if cls in census: + # ssw-common 在两个克隆里都有 ⇒ 合并仓库标签 + prev_repo = census[cls][0] + if prev_repo != repo: + census[cls] = ("COMMON", census[cls][1], census[cls][2]) + continue + census[cls] = (repo, rel, kind) + + if not args.check: + print("class\trepo\tfile\tkind") + for cls in sorted(census): + repo, rel, kind = census[cls] + print("%s\t%s\t%s\t%s" % (cls, repo, rel, kind)) + return 0 + + ledger = read_ledger(args.ledger) + problems = [] + + # ① 台账里的每一行 ⇒ 上游文件必须真的在(克隆在场时) + for cls, row in sorted(ledger.items()): + root = args.tdc_clone if row["repo"] in ("TDC", "COMMON") else args.tds_clone + if not os.path.isdir(root): + continue + path = os.path.join(root, row["file"]) + if not os.path.isfile(path): + problems.append( + "台账 %s:%d 引用的上游文件不存在:%s" + % (args.ledger, row["lineno"], path) + ) + + # ② 上游有的测试类 ⇒ 台账必须登记(克隆在场时) + if census: + for cls in sorted(census): + if cls not in ledger: + repo, rel, kind = census[cls] + problems.append( + "上游新增测试类未登记台账:%s(%s,%s)⇒ 请在 %s 补一行并判定搬/不搬" + % (cls, repo, rel, args.ledger) + ) + + # ③ 台账里登记了、上游却找不到了(两侧克隆都在场时) + if census and not missing_clones: + for cls in sorted(ledger): + if cls not in census: + problems.append( + "台账登记了上游已不存在的测试类:%s(台账 %s:%d)" + % (cls, args.ledger, ledger[cls]["lineno"]) + ) + + print("普查:上游测试类 %d 个 · 台账登记 %d 个" % (len(census), len(ledger))) + if missing_clones: + print( + "⚠️ 上游克隆不在场(%s)⇒ 跳过「上游有、台账无」与「上游文件存在」两项校验" + % "、".join(missing_clones) + ) + if problems: + print("❌ 对账不通过:") + for p in problems: + print(" · %s" % p) + return 1 + print("✅ 对账通过:上游测试类与台账一致") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/upstream-test-ledger.tsv b/scripts/upstream-test-ledger.tsv new file mode 100644 index 0000000..aa76c4a --- /dev/null +++ b/scripts/upstream-test-ledger.tsv @@ -0,0 +1,36 @@ +# 上游测试用例台账(tdc-rs ↔ 上游 TDC/TDS/ssw-common) +# +# 🔴 **本文件是「上游有哪些测试用例、我们搬没搬」的唯一真源** ⇒ +# `scripts/check-upstream-tests.sh` 对账(上游新增一个测试类而台账没记 ⇒ 红)。 +# +# 列(制表符分隔): +# 1 upstream_class 上游全限定类名(ssw.common.guard.ProdGuardSelfTest …) +# 2 upstream_repo TDC | TDS | COMMON(ssw-common 两侧都有 ⇒ 记 COMMON) +# 3 upstream_file 相对**克隆根目录**的路径(克隆根可用环境变量覆盖) +# 4 kind JUNIT(有 @Test,surefire 跑)| SELFTEST(纯 main,**surefire 不跑**) +# 5 assertions 上游断言条数(`-` = 未逐条计数) +# 6 tdc_counterpart 本仓对位用例:`文件::fn1+fn2+…`(`-` = 无对位) +# 7 status PORTED | OUT-OF-SCOPE +# 8 reason 搬法说明(PORTED)/ 不搬的理由(OUT-OF-SCOPE) +# +# ⚠️ 上游的 `*SelfTest.java` **没有 runner 接线**(surefire 只跑 junit 的 `@Test`) +# ⇒ 上游仓库自己靠 `tools/run-java-selftests.sh` 人工跑 +# ⇒ 本仓把它们落成 `cargo test` 的常规用例(判据是纯函数 ⇒ 可离线断言)。 +# +# ⚠️ 台账里的 `upstream_file` 只在**上游克隆在场**时才校验;克隆不在 ⇒ 跳过该校验(不判红)。 + +ssw.common.guard.ProdGuardSelfTest COMMON boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/guard/ProdGuardSelfTest.java SELFTEST 10 tests/upstream_guard_parity.rs::prod_guard_cipher_key_is_not_guarded+prod_guard_default_weak_values_are_still_blocked+prod_guard_strong_values_are_all_allowed+prod_guard_blank_value_is_named+prod_guard_default_value_with_suffix_is_blocked+prod_guard_too_short_value_is_blocked+prod_guard_violation_message_names_the_key+prod_guard_absent_key_is_not_falsely_blocked+prod_guard_exact_weak_value_is_blocked+prod_guard_weak_marker_word_is_blocked+prod_guard_weak_marker_is_whole_word_only+prod_guard_min_len_is_enforced PORTED 六条判据逐条照抄上游 ProdGuard.violations(缺一即空检查):①键不在map⇒跳过 ②值为null/空白⇒违规 ③精确等于弱值⇒违规 ④含弱值片段⇒违规(反绕过)⑤含弱标记词⇒违规 ⑥长度<12⇒违规;上游⓪「security.security-key 不再受管」映射为「CIPHER_KEY(协议共享值)不受管」 +ssw.tds.controller.SswProdRuntimeGuardSelfTest TDS boot/ssw-tds/ssw-tds-controller/src/test/java/ssw/tds/controller/SswProdRuntimeGuardSelfTest.java SELFTEST 12 tests/upstream_guard_parity.rs::runtime_guard_non_prod_never_violates+runtime_guard_prod_with_empty_token_violates+runtime_guard_prod_with_null_token_violates_without_panic+runtime_guard_prod_with_default_token_violates+runtime_guard_prod_with_strong_token_passes+runtime_guard_is_discriminable_on_the_prod_switch+runtime_guard_no_deployment_flag_unlocks_a_weak_token PORTED 10 条里搬了 7 条;未搬的 3 条(② prod+codeDev / ⑧ 未声明测试环境 / ⑨ 已声明测试环境)全属**门户验证码通道**(ssw.portal.code-dev)⇒ 本仓无该通道 ⇒ 记 OUT-OF-SCOPE-PART(见 docs/known-limitations.md L8) +ssw.tdc.client.ProviderInvokeTimeoutsSelfTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/ProviderInvokeTimeoutsSelfTest.java SELFTEST 11 tests/upstream_tds_timeout_parity.rs::hop1_injected_timeout_actually_reaches_the_socket_layer+hop1_changing_the_injected_value_changes_the_client+hop2_read_timeout_is_rewritten_and_names_current_values+hop2_connect_timeout_is_rewritten+hop2_connection_refused_is_not_rewritten+hop2_dns_failure_is_not_rewritten+hop2_no_cause_is_not_rewritten+hop2_multilevel_wrapped_cause_is_still_detected+hop2_cause_chain_walk_is_bounded+hop2_end_to_end_connection_refused_stays_unreachable PORTED 第1跳(配置值⇒socket工厂)用**行为级**判别替代反射(Rust 的 reqwest::Client 不暴露超时):短超时⇒超时、长超时⇒成功 ⇒ 结论等价且更强;第2跳照抄(只有 cause 链里有超时才改写文案,被拒/DNS/无cause⇒不改写) +ssw.tdc.service.impl.P2pTransferTimeoutsSelfTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/service/impl/P2pTransferTimeoutsSelfTest.java SELFTEST - - OUT-OF-SCOPE 与 ProviderInvokeTimeoutsSelfTest **同一机制**(反射读 socket 工厂),但判据对象是 **P2P 传输客户端**(P2pTransferClient)⇒ 本仓**没有 P2P 出向通道**(P2P 属上游跨端传输能力,不在本仓范围)⇒ 无判据对象可搬;机制本身已由 ProviderInvoke 那条覆盖 +ssw.tdc.support.ExecNfsSupportTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/support/ExecNfsSupportTest.java JUNIT 10 - OUT-OF-SCOPE 执行侧 **NFS 通道**(ExecNfsSupport.subPath / 拒绝判据)⇒ 属隐私计算执行面,依赖 Nax 引擎 ⇒ 本仓明确不做(见 CLAUDE.md「明确不在本仓库范围」) +ssw.tdc.engine.NaxPodSupportTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/engine/NaxPodSupportTest.java JUNIT 13 - OUT-OF-SCOPE **Nax 隐私计算引擎** + K8s 拓扑(NodePort 派生 / 探针源码 / tar.gz 投递物)⇒ 本仓不做 +ssw.tdc.client.NaxExecRenderTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/NaxExecRenderTest.java JUNIT 4 - OUT-OF-SCOPE Nax 执行 **Pod 模板渲染契约**(YAML 空值删行陷阱)⇒ 依赖 K8s + Nax ⇒ 本仓不做 +ssw.tdc.client.K8sSandboxClientRenderTest TDC boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/K8sSandboxClientRenderTest.java JUNIT 2 - OUT-OF-SCOPE 沙箱执行 **Pod 模板渲染契约** ⇒ 依赖 K8s ⇒ 本仓不做 +ssw.tds.support.MaxkeyRegisterPrecheckSelfTest TDS boot/ssw-tds/ssw-tds-biz/src/test/java/ssw/tds/support/MaxkeyRegisterPrecheckSelfTest.java SELFTEST - - OUT-OF-SCOPE **MaxKey SSO** 的应用注册预检 ⇒ 本仓不实现 MaxKey SSO(`/Auth/SsoConfig` 恒 `enabled:false`,见 docs/known-limitations.md L2) +ssw.tds.service.MaxkeyAppRegistrarLogicSelfTest TDS boot/ssw-tds/ssw-tds-biz/src/test/java/ssw/tds/service/MaxkeyAppRegistrarLogicSelfTest.java SELFTEST - - OUT-OF-SCOPE MaxKey 应用登记**编排判据**(人工优先 / 不抛异常 / 预检先于调用)⇒ 同上:本仓无 MaxKey 侧 +ssw.tds.client.MaxkeyMgtClientLiveSelfTest TDS boot/ssw-tds/ssw-tds-biz/src/test/java/ssw/tds/client/MaxkeyMgtClientLiveSelfTest.java SELFTEST - - OUT-OF-SCOPE **实机**打真 MaxKey(登录→建应用→授权→回读→退租;未配环境变量 ⇒ 退出码 4 = UNVERIFIED)⇒ 本仓无 MaxKey 侧,且该用例本质是**平台侧**实机联调 +ssw.tds.crypto.CertSignerStrictSelfTest TDS boot/ssw-tds/ssw-tds-biz/src/test/java/ssw/tds/crypto/CertSignerStrictSelfTest.java SELFTEST - - OUT-OF-SCOPE **CA 签发严格模式**(prod 档缺根证书必抛 / 合法 SM2 根必放行)⇒ 本仓不做 CA 签发(软 PKI 由上游 scard 安全平面承担) +ssw.tds.service.GuardAlertTypeSelfTest TDS boot/ssw-tds/ssw-tds-biz/src/test/java/ssw/tds/service/GuardAlertTypeSelfTest.java SELFTEST - - OUT-OF-SCOPE **守门告警类型名长度不变式**(`GUARD_` + 原因 ≤ 列宽;实测曾 33 > varchar(30) ⇒ 告警静默丢库)⇒ 该告警表在 TDS 侧,本仓无对应表 +ssw.common.util.IpWhitelistUtilTest COMMON boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/util/IpWhitelistUtilTest.java JUNIT 13 - OUT-OF-SCOPE **IP 白名单**(CIDR / 全放 / 归一 / 畸形 fail-closed)⇒ 本仓**没有**该功能(入向鉴权只认内部令牌 + 会话令牌) +ssw.common.util.SswLLMClientTest COMMON boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/util/SswLLMClientTest.java JUNIT 17 - OUT-OF-SCOPE **LLM 客户端**(内部代理 URL 解析 / OpenAI / Anthropic 后缀 / 业务错误 JSON)⇒ 本仓**没有** LLM 客户端 diff --git a/src/platform/config.rs b/src/platform/config.rs index e86945a..04b0c6e 100644 --- a/src/platform/config.rs +++ b/src/platform/config.rs @@ -2,8 +2,15 @@ //! //! 红线:内部令牌**只看 `X-Internal-Token` 头**,不接受 query / body; //! `TDC_STRICT_SECRETS=1` 时默认口令即视为不安全 ⇒ 启动即失败。 +//! +//! 🔴 **生产档护栏的判据本体在 [`crate::platform::guard`]**(纯函数,照抄上游 +//! `ssw.common.guard.ProdGuard`)⇒ 本模块只负责**取到值 + 组装 map + 调它**。 +use std::collections::BTreeMap; use std::path::{Path, PathBuf}; +use std::time::Duration; + +use crate::platform::guard; pub const DEFAULT_INTERNAL_TOKEN: &str = "ssw-internal-token-e2e"; /// **出向**(TDC → TDS)内部令牌默认值。 @@ -14,6 +21,11 @@ pub const DEFAULT_INTERNAL_TOKEN: &str = "ssw-internal-token-e2e"; pub const DEFAULT_TDS_INTERNAL_TOKEN: &str = "ssw-internal-token-e2e"; pub const DEFAULT_PORT: u16 = 30000; +/// 出向连接超时默认值(毫秒)—— 照抄上游 `restTemplate()` 的 `setConnectTimeout(3000)`。 +pub const DEFAULT_TDS_CONNECT_TIMEOUT_MS: u64 = 3000; +/// 出向读取超时默认值(毫秒)—— 照抄上游 `restTemplate()` 的 `setReadTimeout(5000)`。 +pub const DEFAULT_TDS_READ_TIMEOUT_MS: u64 = 5000; + // 🔴 **业务配置不在本模块**(v3 spec §2.3.1 C8):身份码 / 身份名 / 身份密钥 / // 引导管理员账号口令这五项是**业务口径** ⇒ 归 `crate::tdc::config::TdcConfig` // (常量在 `crate::tdc::constant`)。平台配置只认「端口 / 数据目录 / 令牌 / @@ -110,6 +122,23 @@ fn tds_internal_token_from(raw: Option) -> String { .to_string() } +/// 取超时毫秒数:未设 / 空白 / **非数字** / 非正数 ⇒ 回落默认值。 +/// +/// 🔴 上游是 Spring `@Value` 注入(非数字 ⇒ **启动失败**);本仓**回落默认值**(宽松)。 +/// 理由:出向超时配错不该让整个连接器起不来 —— 起不来 = 全站不可用,比慢一点更糟。 +/// (判据本身来自上游 `ProviderInvokeTimeoutsSelfTest` 第 1 跳:**配置值必须真落进 socket 层**。) +fn timeout_ms_from(raw: Option, default_ms: u64) -> u64 { + match raw { + Some(v) if !v.trim().is_empty() => v + .trim() + .parse::() + .ok() + .filter(|n| *n > 0) + .unwrap_or(default_ms), + _ => default_ms, + } +} + #[derive(Debug, Clone)] pub struct Config { pub port: u16, @@ -121,6 +150,13 @@ pub struct Config { /// 🔴 **不复用** `internal_token`(那是**入向**闸门的令牌,方向相反)。 pub tds_internal_token: String, pub tds_base_url: Option, + /// **出向**连接超时(`SSW_TDS_CONNECT_TIMEOUT_MS`;默认 3000ms)。 + /// + /// 🔴 上游 chg_0012 把「使用方 → 提供方」的 connect/read 超时**从字面量外置成配置**, + /// 并配 `ProviderInvokeTimeoutsSelfTest` 钉死「配置值真的落进 socket 工厂」。 + pub tds_connect_timeout: Duration, + /// **出向**读取超时(`SSW_TDS_READ_TIMEOUT_MS`;默认 5000ms)。 + pub tds_read_timeout: Duration, pub standalone: StandaloneMode, pub strict_secrets: bool, } @@ -149,6 +185,15 @@ impl Config { Some(v) } }; + // 🔴 出向超时外置(上游 chg_0012 同款):未设 ⇒ 回落上游的 3000 / 5000。 + let tds_connect_timeout = Duration::from_millis(timeout_ms_from( + std::env::var("SSW_TDS_CONNECT_TIMEOUT_MS").ok(), + DEFAULT_TDS_CONNECT_TIMEOUT_MS, + )); + let tds_read_timeout = Duration::from_millis(timeout_ms_from( + std::env::var("SSW_TDS_READ_TIMEOUT_MS").ok(), + DEFAULT_TDS_READ_TIMEOUT_MS, + )); // 规格名 `TDC_LOCAL_STANDALONE` 优先;`TDC_STANDALONE` 保留为别名。 let standalone = standalone_mode_from( std::env::var("TDC_LOCAL_STANDALONE").ok(), @@ -169,6 +214,8 @@ impl Config { internal_token, tds_internal_token, tds_base_url, + tds_connect_timeout, + tds_read_timeout, standalone, strict_secrets, } @@ -183,26 +230,48 @@ impl Config { } } - /// 生产档护栏(对齐平台 `SswProdRuntimeGuard`)。 + /// 生产档护栏(对齐平台 `SswProdRuntimeGuard` + 上游 `ProdGuard`)。 + /// + /// 🔴 **判据本体在 [`crate::platform::guard::guard_violations`]**(纯函数, + /// 照抄上游 `ProdGuard.violations` 的六条判据)⇒ 本方法只做 + /// 「取到值 → 组装 map → 调它 → 有违规就拒启动」。 + /// + /// 🔴 **不只返回第一条**:上游要求"报错正文**点名每一条**"(运维照着改)⇒ 这里逐条列出。 /// /// 🔴 比较时用**已 trim 的**令牌 —— 否则 `" ssw-internal-token-e2e "` 这类 - /// 带空白的默认值变体能绕过闸门(fail-open)。`internal_token` 在 `from_env` - /// 里已 trim,这里再 trim 一次是为了覆盖手工构造的 `Config`。 + /// 带空白的默认值变体能绕过闸门(fail-open)。`internal_token` 在 `from_env` + /// 里已 trim,这里再 trim 一次是为了覆盖手工构造的 `Config`。 + /// + /// 🔴 **出向令牌只在「本部署真有出向通道」时才受管**(未配 `SSW_TDS_BASE_URL` + /// ⇒ 本部署没有这个键 ⇒ 上游判据①**跳过**)⇒ 本地单机模式不会被误停。 pub fn check_secret_guard(&self) -> Result<(), String> { if !self.strict_secrets { return Ok(()); } - let token = self.internal_token.trim(); - if token.is_empty() { - return Err("TDC_STRICT_SECRETS=1:SSW_INTERNAL_TOKEN 不得为空".to_string()); + let violations = guard::guard_violations(&self.guard_values()); + if violations.is_empty() { + return Ok(()); } - if token == DEFAULT_INTERNAL_TOKEN { - return Err(format!( - "TDC_STRICT_SECRETS=1:SSW_INTERNAL_TOKEN 不得等于公开默认值 `{}`", - DEFAULT_INTERNAL_TOKEN - )); + Err(guard::violation_message(&violations)) + } + + /// 组装给守卫判据的 map(**只放本部署真有的键**)。 + /// + /// 🔴 键在 map 里 ⇒ 受管;键不在 ⇒ 上游判据①**跳过**(本应用没有这个键)。 + pub fn guard_values(&self) -> BTreeMap<&'static str, Option<&str>> { + let mut m: BTreeMap<&'static str, Option<&str>> = BTreeMap::new(); + m.insert( + guard::GUARD_KEY_INTERNAL_TOKEN, + Some(self.internal_token.as_str()), + ); + // 🔴 只有真配了出向地址 ⇒ 本部署才有「出向令牌」这个键 ⇒ 才受管。 + if self.tds_base_url.is_some() { + m.insert( + guard::GUARD_KEY_TDS_INTERNAL_TOKEN, + Some(self.tds_internal_token.as_str()), + ); } - Ok(()) + m } } @@ -218,6 +287,8 @@ mod tests { internal_token: DEFAULT_INTERNAL_TOKEN.to_string(), tds_internal_token: DEFAULT_TDS_INTERNAL_TOKEN.to_string(), tds_base_url: None, + tds_connect_timeout: Duration::from_millis(DEFAULT_TDS_CONNECT_TIMEOUT_MS), + tds_read_timeout: Duration::from_millis(DEFAULT_TDS_READ_TIMEOUT_MS), standalone: StandaloneMode::Auto, strict_secrets: false, } @@ -402,4 +473,41 @@ mod tests { "改出向令牌不得牵动入向令牌" ); } + + /// 🔴 **出向超时外置**(上游 chg_0012 同款):非数字 / 非正数 ⇒ 回落默认值(不启动失败)。 + #[test] + fn timeout_ms_falls_back_on_missing_blank_or_invalid() { + assert_eq!(timeout_ms_from(None, 3000), 3000); + assert_eq!(timeout_ms_from(Some(String::new()), 3000), 3000); + assert_eq!(timeout_ms_from(Some(" ".into()), 3000), 3000); + assert_eq!(timeout_ms_from(Some("abc".into()), 3000), 3000); + assert_eq!(timeout_ms_from(Some("0".into()), 3000), 3000); + assert_eq!(timeout_ms_from(Some("-1".into()), 3000), 3000); + // 正常值(含首尾空白) + assert_eq!(timeout_ms_from(Some(" 1234 ".into()), 3000), 1234); + } + + /// 🔴 上游判据①:**本部署没有的键 ⇒ 跳过** ⇒ 未配出向地址时出向令牌**不受管**。 + #[test] + fn guard_values_only_contains_the_keys_this_deployment_has() { + let mut c = base(); + c.strict_secrets = true; + // 没配出向地址 ⇒ map 里只有入向令牌 ⇒ 出向默认值不构成违规 + assert_eq!(c.guard_values().len(), 1); + assert!(!c + .guard_values() + .contains_key(guard::GUARD_KEY_TDS_INTERNAL_TOKEN)); + assert!(c.check_secret_guard().is_err(), "入向默认值仍应被拒"); + + // 配了出向地址 ⇒ 出向令牌进 map ⇒ 出向默认值也构成违规 + c.tds_base_url = Some("http://127.0.0.1:30041".to_string()); + c.internal_token = "K7fQ2mZx9vLp4RtW8nYs3Ba6Hd1Jc5Ge".to_string(); + assert_eq!(c.guard_values().len(), 2); + let err = c.check_secret_guard().unwrap_err(); + assert!( + err.contains(guard::GUARD_KEY_TDS_INTERNAL_TOKEN), + "出向令牌为公开默认值时必须被点名,实得:{}", + err + ); + } } diff --git a/src/platform/guard.rs b/src/platform/guard.rs new file mode 100644 index 0000000..5633705 --- /dev/null +++ b/src/platform/guard.rs @@ -0,0 +1,239 @@ +//! 生产档弱密钥守卫(**纯逻辑**,照抄上游 `ssw.common.guard.ProdGuard`)。 +//! +//! ## 上游真源(只读克隆) +//! +//! `/tmp/sswtdc-probe/boot/ssw-common/ssw-common-biz/src/main/java/ssw/common/guard/ProdGuard.java` +//! +//! | 上游符号 | 行号 | 本仓对应 | +//! |---|---|---| +//! | `WEAK_VALUES`(已知弱值清单) | `:43` | [`WEAK_VALUES`] | +//! | `GUARDED`(受管键清单) | `:60` | [`GUARDED`](**键名换成本仓环境变量名**) | +//! | `WEAK_MARKER`(弱标记词正则) | `:92` | [`WEAK_MARKERS`] + [`has_weak_marker`](**手写等价实现**,不引 regex 依赖) | +//! | `MIN_LEN`(最小长度 12) | `:96` | [`MIN_LEN`] | +//! | `violations(Map)`(判据本体,**纯函数**) | `:119` | [`guard_violations`] | +//! | `violationMessage(List)`(报错正文,**逐条点名**) | `:160` | [`violation_message`] | +//! +//! ## 为什么要它 +//! +//! 这些密钥在仓库里有**能用的默认值**(`ssw-internal-token-e2e` …)⇒ 生产忘了覆盖时, +//! 系统**照常启动、照常跑通、不报任何错**,只是用的是**公开可读**的密钥 —— +//! 这是"静默"事故:不报错的洞比报错的洞危险得多。 +//! +//! ## 键名映射(上游 Java 配置键 ⇄ 本仓环境变量) +//! +//! | 上游 `GUARDED` 键 | 本仓 | 说明 | +//! |---|---|---| +//! | `ssw.internal-token` | [`GUARD_KEY_INTERNAL_TOKEN`] | 上游一个令牌**两个方向**通用;本仓拆成入向 / 出向两个 ⇒ **两个都受管** | +//! | `tds-report.password` | [`GUARD_KEY_TDS_INTERNAL_TOKEN`] | 上游 = TDC→TDS 的上报口令;本仓出向通道**只有令牌**、无独立口令 ⇒ 映射到出向令牌 | +//! | `ssw.dataset.pepper` / `oauth.login.jwtSecretKey` / `tdc-delivery.password` / `spring.datasource.password` | — | 本仓**没有对应配置项** ⇒ 属"本应用没有该键" ⇒ **跳过**(上游判据⑦) | +//! | ~~`security.security-key`~~ | — | 上游 chg_0020 **已移出**受管清单(协议共享值,必须发给浏览器)⇒ 本仓 [`crate::platform::cipher::CIPHER_KEY`] **同样不受管** | +//! +//! 🔴 **判据逐条照抄上游**(六条判据缺一不可,缺一条即空检查): +//! ① 键**不在** map 里 ⇒ **跳过**(不判本应用没有的键); +//! ② 键在但值为 null / 空白 ⇒ 违规(「未配置」); +//! ③ 值 **精确等于**某个已知弱值 ⇒ 违规; +//! ④ 值 **含**某个已知弱值 ⇒ 违规(**反绕过**:默认值加个后缀也拦住); +//! ⑤ 值命中**弱标记词** ⇒ 违规(`e2e` / `demo` / `test` / `dev` / …); +//! ⑥ 长度 < [`MIN_LEN`] ⇒ 违规(可猜解)。 +//! +//! 上游对 ③ 与 ④ 分开报错(③「仍是公开默认值」/ ④「含默认值片段」),本仓照抄。 + +use std::collections::BTreeMap; + +/// 已知弱值(= 仓库内的默认值)。**逐字照抄上游** `ProdGuard.WEAK_VALUES`(`:43`)。 +/// +/// 🔴 **不用前缀匹配**:前缀匹配会让"把默认值后面加几个字符"绕过守卫 ⇒ 靠判据④拦。 +pub const WEAK_VALUES: &[&str] = &[ + "ssw-internal-token-e2e", // 上游 ssw.internal-token + "ssw-dataset-pepper-e2e-2026", // 上游 ssw.dataset.pepper + "WviMjFNC72VKwGqm5LPoheQo5XN9iN4d", // 上游 oauth.login.jwtSecretKey + "EY8WePvjM5GGwQzn", // 上游 security.security-key / tds-report.cipher-key + "123456", // 上游 tds-report.password / tdc-delivery.password + "dacli123", // 上游 spring.datasource.password + "box123456", // 上游盒连接器口令 +]; + +/// 弱标记词(上游 `WEAK_MARKER` 正则,`:92`)—— 作为**整体词**出现在值里即判弱。 +/// +/// 上游正则:`(?i)(^|[\-_.])(e2e|demo|test|dev|default|changeme|example|password)([\-_.]|$)` +/// +/// 🔴 为什么用"整体词"而不是 `contains`:强随机串(base64)里**偶然**出现 `test` 是可能的, +/// 用 contains 会**误拦合法部署**(fail-closed 的误拦 = 停机)⇒ 要求两侧有分隔符 / 首尾。 +pub const WEAK_MARKERS: &[&str] = &[ + "e2e", "demo", "test", "dev", "default", "changeme", "example", "password", +]; + +/// 最小长度:低于此值视为弱(人工可猜)。上游 `MIN_LEN`(`:96`)。 +pub const MIN_LEN: usize = 12; + +/// 受管键:**入向**内部端点凭证(`X-Internal-Token` 闸门)。 +pub const GUARD_KEY_INTERNAL_TOKEN: &str = "SSW_INTERNAL_TOKEN"; +/// 受管键:**出向**内部端点凭证(TDC → TDS 的 internal 通道)。 +pub const GUARD_KEY_TDS_INTERNAL_TOKEN: &str = "SSW_TDS_INTERNAL_TOKEN"; + +/// 受管键清单(上游 `GUARDED`,`:60`)—— 键 → 人话说明(报错时告诉运维"这键是干什么的")。 +/// +/// 🔴 **只列本仓真有的键** ⇒ 上游判据①「本应用没有的键 ⇒ 跳过」在本仓天然成立。 +pub const GUARDED: &[(&str, &str)] = &[ + ( + GUARD_KEY_INTERNAL_TOKEN, + "入向内部端点凭证(X-Internal-Token 闸门)", + ), + ( + GUARD_KEY_TDS_INTERNAL_TOKEN, + "出向内部端点凭证(对端 internal 通道)", + ), +]; + +/// 弱标记词的分隔符(上游正则里的 `[\-_.]`)。 +#[inline] +fn is_marker_delim(c: u8) -> bool { + c == b'-' || c == b'_' || c == b'.' +} + +/// 值里是否命中**弱标记词**(上游 `WEAK_MARKER` 正则的等价实现)。 +/// +/// 命中则返回该词(便于报错点名),未命中返回 `None`。 +/// +/// 🔴 **手写而非引 regex**:上游那条正则的语义是 +/// 「(串首 或 分隔符) + 词 + (分隔符 或 串尾)」⇒ 逐位置比对即可精确复刻, +/// 而引 `regex` 会给本仓多一个依赖(上游那个正则是**一个** alternation,Rust 无内建 alternation)。 +pub fn has_weak_marker(value: &str) -> Option<&'static str> { + let b = value.as_bytes(); + for marker in WEAK_MARKERS { + let mb = marker.as_bytes(); + if mb.len() > b.len() { + continue; + } + let mut i = 0usize; + while i + mb.len() <= b.len() { + if b[i..i + mb.len()].eq_ignore_ascii_case(mb) { + let left_ok = i == 0 || is_marker_delim(b[i - 1]); + let end = i + mb.len(); + let right_ok = end == b.len() || is_marker_delim(b[end]); + if left_ok && right_ok { + return Some(marker); + } + } + i += 1; + } + } + None +} + +/// 校验一组配置值,返回**违规清单**(空 = 通过)。 +/// +/// **纯函数**(不读进程全局 env、不碰 Spring / 任何运行时)⇒ 可离线逐组断言 +/// (上游把判据抽成纯函数就是为了这个,见 `SswProdRuntimeGuard` 的 `evaluate`)。 +/// +/// * `values` —— 键 → 生效值。**只放本部署真有的键**(没有的键 = 上游判据① ⇒ 跳过)。 +/// 值的 `None` 表示「键在、值为 null」(上游 `Map` 里 value 为 null 的情形)。 +/// * 返回 —— 违规清单(每条**点名**是哪个键出了什么问题,运维照着改)。 +/// +/// 判据(逐条照抄上游 `ProdGuard.violations`,`:119`)见模块文档。 +pub fn guard_violations(values: &BTreeMap<&str, Option<&str>>) -> Vec { + let mut bad: Vec = Vec::new(); + for (key, desc) in GUARDED { + // ① 键不在 map 里 ⇒ 本应用没有这个键 ⇒ **不判**(见上) + let Some(entry) = values.get(*key) else { + continue; + }; + // ② 键在但值为 null / 空白 ⇒ 违规("配了但空") + let raw = match entry { + Some(v) => *v, + None => "", + }; + let t = raw.trim(); + if t.is_empty() { + bad.push(format!("{} 未配置({})", key, desc)); + continue; + } + // ③ 值精确等于某个已知弱值 ⇒ 违规("还是仓库默认值") + if WEAK_VALUES.contains(&t) { + bad.push(format!("{} 仍为仓库内公开默认值({})", key, desc)); + continue; + } + // ④ 反绕过:值**含**任一已知弱值 ⇒ 违规 + // (只比精确值时,把默认值后面加一个字符(…-e2e1)即可绕过 —— 那是"改了但没真改") + if let Some(hit) = WEAK_VALUES.iter().find(|w| t.contains(**w)) { + bad.push(format!( + "{} 含仓库默认值片段「{}」—— 疑为默认值变体,非真覆盖({})", + key, hit, desc + )); + continue; + } + // ⑤ 弱标记词 ⇒ 违规 + if let Some(marker) = has_weak_marker(t) { + bad.push(format!( + "{} 含弱标记词({})—— 疑为默认值变体,非真覆盖({})", + key, marker, desc + )); + continue; + } + // ⑥ 过短 ⇒ 违规 + let len = t.chars().count(); + if len < MIN_LEN { + bad.push(format!( + "{} 过短({} < {})—— 可被猜解({})", + key, len, MIN_LEN, desc + )); + } + } + bad +} + +/// 生成给运维看的报错正文(**点名每一条**,不笼统说"配置有误")。 +/// +/// 照抄上游 `ProdGuard.violationMessage`(`:160`)的形状。 +pub fn violation_message(violations: &[String]) -> String { + let mut sb = String::new(); + sb.push('\n'); + sb.push_str("=============================================================\n"); + sb.push_str(" 拒绝启动:生产档(TDC_STRICT_SECRETS=1)下检测到未覆盖的弱密钥/缺配置\n"); + sb.push_str("=============================================================\n"); + for v in violations { + sb.push_str(" · "); + sb.push_str(v); + sb.push('\n'); + } + sb.push('\n'); + sb.push_str(" 为什么拦:这些默认值公开在代码仓里,生产用它们 = 门开着,\n"); + sb.push_str(" 且系统不会报任何错(静默)。\n"); + sb.push_str(" 怎么改:在部署侧 .env / compose 里覆盖上列键。\n"); + sb.push_str(" 仅生产拦:TDC_STRICT_SECRETS 未设 ⇒ 零影响。\n"); + sb.push_str("=============================================================\n"); + sb +} + +#[cfg(test)] +mod tests { + use super::*; + + fn map<'a>(pairs: &[(&'a str, Option<&'a str>)]) -> BTreeMap<&'a str, Option<&'a str>> { + pairs.iter().copied().collect() + } + + /// 上游弱标记词正则的**逐条**对照(`:92`)。 + #[test] + fn weak_marker_matches_the_upstream_regex_semantics() { + // 整体词命中(分隔符或首尾界定) + assert_eq!(has_weak_marker("e2e"), Some("e2e")); + assert_eq!(has_weak_marker("a-e2e-b"), Some("e2e")); + assert_eq!(has_weak_marker("a_e2e_b"), Some("e2e")); + assert_eq!(has_weak_marker("a.e2e.b"), Some("e2e")); + // 大小写不敏感(上游 `(?i)`) + assert_eq!(has_weak_marker("E2E"), Some("e2e")); + assert_eq!(has_weak_marker("PassWord"), Some("password")); + // 🔴 不是整体词 ⇒ **不**命中(避免误拦合法部署) + assert_eq!(has_weak_marker("device"), None); + assert_eq!(has_weak_marker("contest"), None); + assert_eq!(has_weak_marker("K7fQ2mZx9vLp4RtW8nYs3Ba6Hd1Jc5Ge"), None); + } + + /// 判据①:本应用没有的键 ⇒ 跳过。 + #[test] + fn absent_key_is_skipped() { + let v = guard_violations(&map(&[(GUARD_KEY_INTERNAL_TOKEN, Some("K7fQ2mZx9vLp4RtW8nYs3Ba6Hd1Jc5Ge"))])); + assert!(v.is_empty(), "只有一个键 ⇒ 只判它,实得 {:?}", v); + } +} diff --git a/src/platform/mod.rs b/src/platform/mod.rs index ec4bba7..aa6d46e 100644 --- a/src/platform/mod.rs +++ b/src/platform/mod.rs @@ -16,6 +16,7 @@ //! | `state` | `AppState`(配置 + db + 锁 + 会话)—— **业务态在 `tdc::state::TdcState`** | — | //! | `compare` | 常量时间比较(**唯一一份实现**,业务侧 `pub use` 复用) | — | //! | `config` | 环境变量配置 + 密钥守卫 | — | +//! | `guard` | 生产档弱密钥判据(**纯函数**,照抄上游 `ssw.common.guard.ProdGuard`) | `ProdGuard` | //! | `db` | PGlite 封装 + SQL 切分 + `f_`↔camelCase 映射契约 | — | //! | `session` | 内存会话(`Identity` / `Account` 两种 kind) | — | //! | `envelope` | `ActionResult` 业务信封(HTTP 200 + `{code,msg,data}`) | — | @@ -35,6 +36,7 @@ pub mod config; pub mod db; pub mod envelope; pub mod fallback; +pub mod guard; pub mod ids; pub mod mw; pub mod protocol; diff --git a/src/tdc/client/tds.rs b/src/tdc/client/tds.rs index 9dc45ba..0aa11d4 100644 --- a/src/tdc/client/tds.rs +++ b/src/tdc/client/tds.rs @@ -7,19 +7,34 @@ //! //! 🔴 **只实现 internal 通道**(`X-Internal-Token` + 固定头,走 TDS `white-url` 放行的内部端点)。 //! 上游还有一条 login/`ensureToken` 通道(JNPF 登录换 token)⇒ 本轮**不做**(见 spec §5)。 +//! +//! ## 超时与错误分类(照抄上游 `ProviderInvokeTimeoutsSelfTest` 的两跳) +//! +//! | 上游 | 本仓 | +//! |---|---| +//! | 第 1 跳:配置值 ⇒ **socket 工厂**(证明"配了没用"没发生) | [`TdsClient::with_timeouts`] + `timeouts()` + **行为级**判别性用例(短超时⇒超时、长超时⇒成功) | +//! | 第 2 跳:异常 ⇒ **文案**(只有 cause 链里有超时才改写) | [`cause_chain_has_timeout`] + [`timeout_text_or_null`] | +use std::error::Error; use std::time::Duration; use serde_json::{json, Value}; -/// 连接超时(照抄上游 `restTemplate()`:`setConnectTimeout(3000)`)。 +/// 连接超时默认值(照抄上游 `restTemplate()`:`setConnectTimeout(3000)`)。 pub const CONNECT_TIMEOUT: Duration = Duration::from_secs(3); -/// 读取超时(照抄上游 `restTemplate()`:`setReadTimeout(5000)`)。 +/// 读取超时默认值(照抄上游 `restTemplate()`:`setReadTimeout(5000)`)。 pub const READ_TIMEOUT: Duration = Duration::from_secs(5); +/// cause 链的最大遍历深度(照抄上游 `timeoutTextOrNull` 的 `depth < 16`)。 +pub const MAX_CAUSE_DEPTH: usize = 16; + /// 未配置 TDS 地址(本地单机模式)时的降级文案。 pub const NOOP_MESSAGE: &str = "未配置 TDS 地址(本地单机模式)"; +/// 超时文案前缀(照抄上游 `ProviderInvokeClient.timeoutTextOrNull` 的 +/// 「调用提供方超时(当前 connect=…ms / read=…ms,可用 … 调大)」句式)。 +pub const TIMEOUT_TEXT_PREFIX: &str = "调用 TDS 超时"; + /// 账本 / 订单等 id 的路径段白名单:仅 ASCII 字母数字、下划线、短横线。 /// /// 🔴 出向 URL **只由固定路径模板 + 已校验的段**拼出 ⇒ 用户输入绝不直接进 URL 路径。 @@ -49,6 +64,81 @@ fn unwrap_data(envelope: Value, fallback_msg: &str) -> Result { } } +/// cause 链上是否出现「超时」(上游第 2 跳的判据)。 +/// +/// 照抄上游 `ProviderInvokeClient.timeoutTextOrNull` 的**有界** cause 链遍历 +/// (上游 `depth < 16` ⇒ [`MAX_CAUSE_DEPTH`])⇒ 既能穿透多层包装,又不会在环状链上死循环。 +/// +/// 🔴 判据**只看 cause 链**(不按错误文案猜)⇒ 上游那条「连接被拒 ⇒ 不得被标成超时」 +/// 的断言在本仓同样成立(连接被拒 / DNS 失败都**不是**超时)。 +pub fn cause_chain_has_timeout(err: &(dyn Error + 'static)) -> bool { + let mut cur: Option<&(dyn Error + 'static)> = Some(err); + let mut depth = 0usize; + while let Some(e) = cur { + depth += 1; + if depth > MAX_CAUSE_DEPTH { + break; // 上游同样有界 ⇒ 防环 + } + if link_is_timeout(e) { + return true; + } + cur = e.source(); + } + false +} + +/// 单个 cause 链节点是否表示「超时」。 +/// +/// - `reqwest::Error` ⇒ 用它自己的 `is_timeout()`(连接超时 / 整请求超时都算)。 +/// - `std::io::Error` ⇒ `ErrorKind::TimedOut`。 +fn link_is_timeout(e: &(dyn Error + 'static)) -> bool { + if let Some(re) = e.downcast_ref::() { + if re.is_timeout() { + return true; + } + } + if let Some(io) = e.downcast_ref::() { + if io.kind() == std::io::ErrorKind::TimedOut { + return true; + } + } + false +} + +/// 超时 ⇒ 改写文案;**非超时 ⇒ `None`**(调用方原样抛出,判据照抄上游第 2 跳)。 +/// +/// 文案点名**当前生效的** connect / read 毫秒值(照抄上游句式) +/// ⇒ 运维一眼能看出「该调哪个旋钮」。 +pub fn timeout_text_or_null( + err: &(dyn Error + 'static), + connect_ms: u64, + read_ms: u64, +) -> Option { + if !cause_chain_has_timeout(err) { + return None; + } + Some(format!( + "{}(当前 connect={}ms / read={}ms,可用 SSW_TDS_CONNECT_TIMEOUT_MS / SSW_TDS_READ_TIMEOUT_MS 调大): {}", + TIMEOUT_TEXT_PREFIX, connect_ms, read_ms, err + )) +} + +/// 出向请求失败 ⇒ 错误文案(**超时**与**不可达**分档)。 +fn outbound_error_text(e: &reqwest::Error, connect_ms: u64, read_ms: u64) -> String { + match timeout_text_or_null(e, connect_ms, read_ms) { + Some(t) => t, + None => format!("TDS 不可达: {}", e), + } +} + +/// 读取响应体失败 ⇒ 错误文案(**超时**与**其它**分档)。 +fn outbound_read_error_text(e: &reqwest::Error, connect_ms: u64, read_ms: u64) -> String { + match timeout_text_or_null(e, connect_ms, read_ms) { + Some(t) => t, + None => format!("读取 TDS 响应失败: {}", e), + } +} + /// TDS 出向客户端(≡ 上游 `TdsReportClient` 的 internal 通道)。 #[derive(Clone)] pub struct TdsClient { @@ -56,32 +146,59 @@ pub struct TdsClient { base_url: Option, /// 出向内部令牌(`SSW_TDS_INTERNAL_TOKEN`)。 internal_token: String, + /// 出向连接超时(上游 chg_0012 外置成配置;默认 [`CONNECT_TIMEOUT`])。 + connect_timeout: Duration, + /// 出向读取超时(上游 chg_0012 外置成配置;默认 [`READ_TIMEOUT`])。 + read_timeout: Duration, http: reqwest::Client, } impl TdsClient { - /// 造客户端。 + /// 造客户端(用**默认**超时:连接 3s / 读取 5s)。 /// /// 🔴 `.no_proxy()`:reqwest 默认会读**系统代理** /// (`hyper_util` 的 `Matcher::from_system()` ⇒ 读 `HTTP_PROXY` 等环境变量, /// 且在 macOS 上还读**系统网络设置**里的代理)⇒ loopback 的 TDS 会被劫持。 /// TDS 是**内网直连**服务 ⇒ 出向**必须直连**。 - /// - /// ⚠️ 超时照抄上游 `restTemplate()`:连接 3s / 读取 5s(**快速失败**,别拖垮本地业务)。 pub fn new(base_url: Option, internal_token: String) -> Self { + Self::with_timeouts(base_url, internal_token, CONNECT_TIMEOUT, READ_TIMEOUT) + } + + /// 造客户端(**显式**给出超时)—— 上游 chg_0012 的「配置值 ⇒ socket 工厂」那一跳。 + /// + /// 🔴 超时**真的落进** reqwest 客户端(`connect_timeout` / `timeout`), + /// 不是只存字段 ⇒ 配了就一定生效(上游那条自测防的就是"配了没用")。 + pub fn with_timeouts( + base_url: Option, + internal_token: String, + connect_timeout: Duration, + read_timeout: Duration, + ) -> Self { let http = reqwest::Client::builder() .no_proxy() - .connect_timeout(CONNECT_TIMEOUT) - .timeout(READ_TIMEOUT) + .connect_timeout(connect_timeout) + .timeout(read_timeout) .build() .expect("构造 TDS 出向 HTTP 客户端失败"); Self { base_url: base_url.map(|b| b.trim().trim_end_matches('/').to_string()), internal_token, + connect_timeout, + read_timeout, http, } } + /// 当前生效的连接超时(毫秒)—— 供断言「配置值落到位」用。 + pub fn connect_timeout_ms(&self) -> u64 { + self.connect_timeout.as_millis() as u64 + } + + /// 当前生效的读取超时(毫秒)—— 供断言「配置值落到位」用。 + pub fn read_timeout_ms(&self) -> u64 { + self.read_timeout.as_millis() as u64 + } + /// 是否处于 NOOP 模式(未配置 TDS 地址)。 pub fn is_noop(&self) -> bool { self.base_url.is_none() @@ -140,13 +257,16 @@ impl TdsClient { if let Some(b) = body { req = req.json(b); } - let resp = req.send().await.map_err(|e| format!("TDS 不可达: {}", e))?; + let resp = req + .send() + .await + .map_err(|e| outbound_error_text(&e, self.connect_timeout_ms(), self.read_timeout_ms()))?; // 🔴 TDS 业务失败走 **HTTP 200 + body code != 200** ⇒ 这里**不**按状态码判成败, // 一律把 body 交给上层判 `code`。 let text = resp .text() .await - .map_err(|e| format!("读取 TDS 响应失败: {}", e))?; + .map_err(|e| outbound_read_error_text(&e, self.connect_timeout_ms(), self.read_timeout_ms()))?; serde_json::from_str::(&text).map_err(|e| format!("TDS 响应不是合法 JSON: {}", e)) } diff --git a/src/tdc/state.rs b/src/tdc/state.rs index 5a9a63b..ce58a3a 100644 --- a/src/tdc/state.rs +++ b/src/tdc/state.rs @@ -64,9 +64,11 @@ impl TdcState { /// /// 🔴 TDS 客户端按平台配置构造(`None` ⇒ NOOP)——与拆分前 `AppState::new` 的行为**逐字一致**。 pub fn new(platform: AppState, tdc_config: TdcConfig, bootstrap: BootstrapIdentity) -> Self { - let tds = Arc::new(TdsClient::new( + let tds = Arc::new(TdsClient::with_timeouts( platform.config.tds_base_url.clone(), platform.config.tds_internal_token.clone(), + platform.config.tds_connect_timeout, + platform.config.tds_read_timeout, )); Self { platform, diff --git a/tests/upstream_guard_parity.rs b/tests/upstream_guard_parity.rs new file mode 100644 index 0000000..9b1991a --- /dev/null +++ b/tests/upstream_guard_parity.rs @@ -0,0 +1,375 @@ +//! **上游测试用例移植**:生产档弱密钥守卫(`ProdGuard` / `SswProdRuntimeGuard`)。 +//! +//! ## 上游真源(只读克隆) +//! +//! | 上游类 | 路径 | 关键断言 | +//! |---|---|---| +//! | `ssw.common.guard.ProdGuardSelfTest` | `/tmp/sswtdc-probe/boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/guard/ProdGuardSelfTest.java` | ⓪–⑦(7 条,**双向断言**) | +//! | `ssw.tds.controller.SswProdRuntimeGuardSelfTest` | `/tmp/sswtds-probe/boot/ssw-tds/ssw-tds-controller/src/test/java/ssw/tds/controller/SswProdRuntimeGuardSelfTest.java` | ①–⑩(10 条) | +//! | 判据本体 `ssw.common.guard.ProdGuard` | `/tmp/sswtdc-probe/boot/ssw-common/ssw-common-biz/src/main/java/ssw/common/guard/ProdGuard.java` | `violations(...)` 六条判据 | +//! +//! ## 为什么这样移植 +//! +//! 上游这两个类**没有 runner 接线**(surefire 不跑非 junit 的 `main` ⇒ 需人工跑), +//! 但判据本身**纯函数** ⇒ 可离线逐组断言 ⇒ 本仓把它们落成 `cargo test` 的常规用例。 +//! +//! 🔴 **双向断言**(上游自测的立意:防"恒绿"/"恒红"): +//! 既断言"弱值必被拦",也断言"强值必放行",还断言**判别性**(只翻开关一位 ⇒ 结论必须翻转)。 +//! +//! ## 键名映射 +//! +//! 上游一个 `ssw.internal-token` 双向通用;本仓拆成**入向 / 出向**两个 ⇒ **两个都受管**。 +//! 其余上游受管键本仓**没有对应配置项** ⇒ 属"本应用没有该键" ⇒ 跳过(上游判据①)。 + +use std::collections::BTreeMap; + +use tdc_connector::platform::cipher::CIPHER_KEY; +use tdc_connector::platform::config::{ + Config, StandaloneMode, DEFAULT_INTERNAL_TOKEN, DEFAULT_PORT, DEFAULT_TDS_CONNECT_TIMEOUT_MS, + DEFAULT_TDS_INTERNAL_TOKEN, DEFAULT_TDS_READ_TIMEOUT_MS, +}; +use tdc_connector::platform::guard::{ + guard_violations, has_weak_marker, violation_message, GUARDED, GUARD_KEY_INTERNAL_TOKEN, + GUARD_KEY_TDS_INTERNAL_TOKEN, MIN_LEN, WEAK_VALUES, +}; + +/// 32 位强随机串(上游自测同款):无弱值片段、无弱标记词、长度 ≥ [`MIN_LEN`]。 +const STRONG: &str = "K7fQ2mZx9vLp4RtW8nYs3Ba6Hd1Jc5Ge"; + +/// 组装给守卫判据的 map(键 → 值;`None` = 值为 null)。 +fn map<'a>(pairs: &[(&'a str, Option<&'a str>)]) -> BTreeMap<&'a str, Option<&'a str>> { + pairs.iter().copied().collect() +} + +/// 构造一个可改的 [`Config`](字段全 pub ⇒ 直接造,不读进程 env)。 +fn base_config() -> Config { + Config { + port: DEFAULT_PORT, + project_dir: std::path::PathBuf::from("/tmp/proj"), + data_dir: std::path::PathBuf::from("/tmp/proj/data"), + internal_token: DEFAULT_INTERNAL_TOKEN.to_string(), + tds_internal_token: DEFAULT_TDS_INTERNAL_TOKEN.to_string(), + tds_base_url: None, + tds_connect_timeout: std::time::Duration::from_millis(DEFAULT_TDS_CONNECT_TIMEOUT_MS), + tds_read_timeout: std::time::Duration::from_millis(DEFAULT_TDS_READ_TIMEOUT_MS), + standalone: StandaloneMode::Auto, + strict_secrets: false, + } +} + +// ============================================================================ +// 上游 `ProdGuardSelfTest`(7 条,逐条移植) +// ============================================================================ + +/// 上游 ⓪(`ProdGuardSelfTest.java:39`):`security.security-key` 取默认值**不再被拦**。 +/// +/// 🔴 上游 chg_0020 的立意:那是**协议共享值**(必须发给浏览器)⇒ 构造上不可保密。 +/// 本仓的对位物 = [`CIPHER_KEY`](登录口令加解密密钥,随上游前端产物公开) +/// ⇒ **同样不得进受管清单**,否则"保持默认同值"这种正常部署会被判红(恒假红)。 +#[test] +fn prod_guard_cipher_key_is_not_guarded() { + // ⓪-1:`CIPHER_KEY` **不在**受管清单里 + assert!( + !GUARDED.iter().any(|(k, _)| k.contains("CIPHER")), + "CIPHER_KEY 是协议共享值,不得进受管清单(上游 chg_0020 同款裁定),实得:{:?}", + GUARDED + ); + // ⓪-2:把它的**默认值**喂进一个**非受管键** ⇒ 不产生违规 + // (判据①:键不在 map 里 ⇒ 跳过;这里额外确认值本身也不该被当成"弱值") + let v = guard_violations(&map(&[("CIPHER_KEY", Some(CIPHER_KEY))])); + assert!(v.is_empty(), "非受管键不得被误拦(实得:{:?})", v); + // ⓪-3:🔴 **即便**误把它塞进受管键,它**仍然**是公开值 ⇒ 应被拦 + // (这正是上游把它移出清单的理由:它不可保密 ⇒ 拿来当令牌就是事故) + let v = guard_violations(&map(&[(GUARD_KEY_INTERNAL_TOKEN, Some(CIPHER_KEY))])); + assert_eq!(v.len(), 1, "公开的加解密密钥不得被当作可用令牌,实得:{:?}", v); +} + +/// 上游 ①(`:59`):默认弱值**逐个仍被拦**(防"顺手把守卫整体弱化")。 +#[test] +fn prod_guard_default_weak_values_are_still_blocked() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some("ssw-internal-token-e2e")), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some("ssw-internal-token-e2e")), + ])); + assert_eq!( + v.len(), + GUARDED.len(), + "每个受管键都该被点名,实得:{:?}", + v + ); + assert!(v.iter().any(|s| s.contains(GUARD_KEY_INTERNAL_TOKEN))); + assert!(v.iter().any(|s| s.contains(GUARD_KEY_TDS_INTERNAL_TOKEN))); +} + +/// 上游 ②(`:72`):**强值全部放行**(防"守卫恒红"——那会挡住合法部署)。 +#[test] +fn prod_guard_strong_values_are_all_allowed() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some(STRONG)), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some(STRONG)), + ])); + assert!(v.is_empty(), "强值不得被拦(实得:{:?})", v); +} + +/// 上游 ③(`:81`):**空白**键被点名("配了但空"也是违规)。 +#[test] +fn prod_guard_blank_value_is_named() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some(STRONG)), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some("")), + ])); + assert_eq!(v.len(), 1, "实得:{:?}", v); + assert!( + v[0].starts_with(GUARD_KEY_TDS_INTERNAL_TOKEN), + "空白键必须被点名,实得:{:?}", + v + ); +} + +/// 上游 ④(`:91`):🔴 **反绕过** —— 默认值后面加一个字符仍须被拦。 +#[test] +fn prod_guard_default_value_with_suffix_is_blocked() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some("ssw-internal-token-e2e1")), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some(STRONG)), + ])); + assert_eq!(v.len(), 1, "实得:{:?}", v); + assert!( + v[0].starts_with(GUARD_KEY_INTERNAL_TOKEN), + "反绕过用例必须点名入向键,实得:{:?}", + v + ); +} + +/// 上游 ⑤(`:101`):**过短**口令被拦(可猜解)。 +#[test] +fn prod_guard_too_short_value_is_blocked() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some(STRONG)), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some("abc123")), + ])); + assert_eq!(v.len(), 1, "实得:{:?}", v); + assert!( + v[0].starts_with(GUARD_KEY_TDS_INTERNAL_TOKEN), + "过短用例必须点名出向键,实得:{:?}", + v + ); +} + +/// 上游 ⑥(`:106`):报错正文**点名第一条违规**(运维要照着改)。 +#[test] +fn prod_guard_violation_message_names_the_key() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some("ssw-internal-token-e2e")), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some(STRONG)), + ])); + let msg = violation_message(&v); + assert!( + msg.contains(GUARD_KEY_INTERNAL_TOKEN), + "报错正文未点名,实得:{}", + msg + ); + assert!( + msg.contains("拒绝启动"), + "报错正文须写明后果,实得:{}", + msg + ); +} + +/// 上游 ⑦(`:116`):🔴 "**本应用没有该键**"不得误拦(fail-closed 的误拦 = 停机)。 +#[test] +fn prod_guard_absent_key_is_not_falsely_blocked() { + // map 里只有入向键 ⇒ 出向键缺席 ⇒ 出向默认值不构成违规 + let v = guard_violations(&map(&[( + GUARD_KEY_INTERNAL_TOKEN, + Some(STRONG), + )])); + assert!(v.is_empty(), "实得:{:?}", v); +} + +// ============================================================================ +// 上游 `ProdGuard` 判据里**自测没单独断言**、但必须一起搬的两条(③/⑤) +// ============================================================================ + +/// 上游判据③+⑤(`ProdGuard.java:140-150`):**含**弱值片段 / **含**弱标记词 ⇒ 违规。 +/// +/// 🔴 上游自测只断言了"精确等于默认值"与"反绕过",**没单独**断言弱标记词 +/// ⇒ 本仓补上(判据在实现里,就得被钉住)。 +#[test] +fn prod_guard_weak_marker_word_is_blocked() { + let v = guard_violations(&map(&[ + (GUARD_KEY_INTERNAL_TOKEN, Some("my-test-token-value")), + (GUARD_KEY_TDS_INTERNAL_TOKEN, Some(STRONG)), + ])); + assert_eq!(v.len(), 1, "含弱标记词的值必须被拦,实得:{:?}", v); + assert!( + v[0].contains("弱标记词"), + "报错须说明是弱标记词,实得:{:?}", + v + ); +} + +/// 上游判据③(`:132`):值**精确等于**某个已知弱值 ⇒ 违规(与反绕过分开报错)。 +#[test] +fn prod_guard_exact_weak_value_is_blocked() { + for w in WEAK_VALUES { + let v = guard_violations(&map(&[( + GUARD_KEY_INTERNAL_TOKEN, + Some(*w), + )])); + assert_eq!( + v.len(), + 1, + "已知弱值 {:?} 必须被拦,实得:{:?}", + w, + v + ); + } +} + +/// 弱标记词的**整体词**语义(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)`)。 +#[test] +fn prod_guard_weak_marker_is_whole_word_only() { + // 命中 + assert_eq!(has_weak_marker("e2e"), Some("e2e")); + assert_eq!(has_weak_marker("a-e2e-b"), Some("e2e")); + assert_eq!(has_weak_marker("E2E"), Some("e2e")); + // 🔴 不命中(否则会误拦合法部署 —— 强随机串里偶然出现 test 是可能的) + assert_eq!(has_weak_marker("device"), None); + assert_eq!(has_weak_marker("contest"), None); + assert_eq!(has_weak_marker(STRONG), None); +} + +/// 上游 `MIN_LEN`(`:96`):低于 12 判弱。 +#[test] +fn prod_guard_min_len_is_enforced() { + assert_eq!(MIN_LEN, 12); + let v = guard_violations(&map(&[( + GUARD_KEY_INTERNAL_TOKEN, + Some("abcdefghij"), // 10 位(🔴 不含任何弱值片段 ⇒ 只可能命中「过短」这一条) + )])); + assert_eq!(v.len(), 1, "过短必须被拦,实得:{:?}", v); + assert!(v[0].contains("过短"), "实得:{:?}", v); +} + +// ============================================================================ +// 上游 `SswProdRuntimeGuardSelfTest`(可移植的那几条) +// ============================================================================ + +/// 上游 ①(`:45`):**非 prod** ⇒ 一律不报违规(哪怕令牌是默认值)。 +/// +/// 本仓的对位开关 = `TDC_STRICT_SECRETS`(= 上游 profile 含 prod)。 +#[test] +fn runtime_guard_non_prod_never_violates() { + let mut c = base_config(); + c.strict_secrets = false; + assert!( + c.check_secret_guard().is_ok(), + "非生产档不得有副作用(实得:{:?})", + c.check_secret_guard() + ); +} + +/// 上游 ③(`:53`):**prod** + 令牌为空 ⇒ 报违规并点名。 +#[test] +fn runtime_guard_prod_with_empty_token_violates() { + let mut c = base_config(); + c.strict_secrets = true; + c.internal_token = String::new(); + let err = c.check_secret_guard().unwrap_err(); + assert!( + err.contains(GUARD_KEY_INTERNAL_TOKEN), + "实得:{}", + err + ); +} + +/// 上游 ④(`:57`):**prod** + token 为 null(等价于缺键)⇒ 报违规,**不得抛异常**。 +/// +/// 本仓的「null」落在守卫入参的 `Option<&str>` 上(`None` = 键在、值为 null)。 +#[test] +fn runtime_guard_prod_with_null_token_violates_without_panic() { + let v = guard_violations(&map(&[( + GUARD_KEY_INTERNAL_TOKEN, + None::<&str>, // 键在、值为 null + )])); + assert_eq!(v.len(), 1, "实得:{:?}", v); + assert!( + v[0].starts_with(GUARD_KEY_INTERNAL_TOKEN), + "null 令牌必须被点名,实得:{:?}", + v + ); + assert!(v[0].contains("未配置"), "实得:{:?}", v); +} + +/// 上游 ⑤(`:61`):**prod** + 仓库默认弱值 ⇒ 报违规并点名。 +#[test] +fn runtime_guard_prod_with_default_token_violates() { + let mut c = base_config(); + c.strict_secrets = true; + let err = c.check_secret_guard().unwrap_err(); + assert!( + err.contains(GUARD_KEY_INTERNAL_TOKEN), + "实得:{}", + err + ); +} + +/// 上游 ⑥(`:65`):**prod** + 全强值 ⇒ 不报违规。 +#[test] +fn runtime_guard_prod_with_strong_token_passes() { + let mut c = base_config(); + c.strict_secrets = true; + c.internal_token = STRONG.to_string(); + assert!( + c.check_secret_guard().is_ok(), + "实得:{:?}", + c.check_secret_guard() + ); +} + +/// 上游 ⑦(`:69`):🔴 **判别性** —— 只翻 prod 一位,结论必须**翻转** +/// (否则判据可能是"恒绿",那正是守卫看着在、其实永不触发的成因)。 +#[test] +fn runtime_guard_is_discriminable_on_the_prod_switch() { + let mut c = base_config(); + c.internal_token = DEFAULT_INTERNAL_TOKEN.to_string(); + + c.strict_secrets = true; + let with_prod = c.check_secret_guard(); + c.strict_secrets = false; + let without_prod = c.check_secret_guard(); + + assert!( + with_prod.is_err() && without_prod.is_ok(), + "只翻生产开关一位 ⇒ 结论必须翻转(prod 档:{:?} / 非 prod 档:{:?})", + with_prod, + without_prod + ); +} + +/// 上游 ⑩(`:97`):🔴 **测试环境声明不得解锁 internal-token**。 +/// +/// 上游:`ssw.portal.test-env=true` 只放行固定验证码,**不解锁**内部令牌。 +/// 本仓**没有**任何"测试环境声明"能解锁令牌 ⇒ 这条以「更强的形式」成立: +/// 连"单机模式"这种部署档位都**不能**让弱令牌过关。 +#[test] +fn runtime_guard_no_deployment_flag_unlocks_a_weak_token() { + let mut c = base_config(); + c.strict_secrets = true; + // 单机模式(= 本地单机,不出网) + c.standalone = StandaloneMode::On; + // 出向通道也配上了(⇒ 出向令牌同样进受管清单) + c.tds_base_url = Some("http://127.0.0.1:30041".to_string()); + let err = c.check_secret_guard().unwrap_err(); + assert!( + err.contains(GUARD_KEY_INTERNAL_TOKEN), + "没有任何部署档位能解锁弱令牌,实得:{}", + err + ); + assert!( + err.contains(GUARD_KEY_TDS_INTERNAL_TOKEN), + "出向令牌同样不得被部署档位解锁,实得:{}", + err + ); +} diff --git a/tests/upstream_tds_timeout_parity.rs b/tests/upstream_tds_timeout_parity.rs new file mode 100644 index 0000000..bf6d06c --- /dev/null +++ b/tests/upstream_tds_timeout_parity.rs @@ -0,0 +1,315 @@ +//! **上游测试用例移植**:出向调用的超时配置与错误文案 +//! (上游 `ProviderInvokeTimeoutsSelfTest` 的两跳)。 +//! +//! ## 上游真源(只读克隆) +//! +//! | 上游 | 路径 | 关键断言 | +//! |---|---|---| +//! | `ssw.tdc.client.ProviderInvokeTimeoutsSelfTest` | `/tmp/sswtdc-probe/boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/ProviderInvokeTimeoutsSelfTest.java` | 第 1 跳(配置值 ⇒ socket 工厂)· 第 2 跳(异常 ⇒ 文案),共 9 条 | +//! | `ssw.tdc.client.ProviderInvokeClient` | `/tmp/sswtdc-probe/boot/ssw-tdc/ssw-tdc-biz/src/main/java/ssw/tdc/client/ProviderInvokeClient.java` | `restTemplate()`(超时落进 socket 工厂)· `timeoutTextOrNull`(有界 cause 链) | +//! +//! ## 两跳的对应关系 +//! +//! | 上游 | 本仓 | 为什么这么落 | +//! |---|---|---| +//! | 第 1 跳:反射读 `SimpleClientHttpRequestFactory` 的 `connectTimeout` / `readTimeout` | [`TdsClient::connect_timeout_ms`] / [`TdsClient::read_timeout_ms`] + **行为级**判别性用例 | Rust 的 `reqwest::Client` **不暴露**超时(无 getter)⇒ 反射那一跳**无法照搬** ⇒ 改成「配置值落进客户端」+「**行为**随配置变」(短超时⇒超时、长超时⇒成功)⇒ 结论等价且更强 | +//! | 第 2 跳:`timeoutTextOrNull(e, CT, RT)` 只在 cause 链里有 `SocketTimeoutException` 时改写 | [`cause_chain_has_timeout`] + [`timeout_text_or_null`] | Java 靠**异常类型**判;Rust 无同构类型 ⇒ 判据落到「`reqwest::Error::is_timeout()` 或 cause 链里有 `io::Error(TimedOut)`」⇒ 语义等价 | + +use std::error::Error; +use std::fmt; +use std::io::{ErrorKind, Read, Write}; +use std::net::TcpListener; +use std::time::Duration; + +use tdc_connector::tdc::client::tds::{ + cause_chain_has_timeout, timeout_text_or_null, TdsClient, MAX_CAUSE_DEPTH, +}; + +/// 上游测试里用的两个注入值(**故意不用默认值** ⇒ "写死"与"生效"分得开)。 +const CT: u64 = 3000; +const RT: u64 = 8000; + +/// 造一个 cause 为 `io::Error(TimedOut)` 的错误(上游 `SocketTimeoutException` 的对位物)。 +fn timeout_error(msg: &str) -> std::io::Error { + std::io::Error::new(ErrorKind::TimedOut, msg.to_string()) +} + +/// 造一个 cause 为 `io::Error(ConnectionRefused)` 的错误(上游 `ConnectException` 的对位物)。 +fn refused_error(msg: &str) -> std::io::Error { + std::io::Error::new(ErrorKind::ConnectionRefused, msg.to_string()) +} + +/// 造一个 cause 为 `io::Error(NotFound)` 的错误(上游 `UnknownHostException` 的对位物)。 +fn dns_error(msg: &str) -> std::io::Error { + std::io::Error::new(ErrorKind::NotFound, msg.to_string()) +} + +/// 无 cause 的错误(上游 `new ResourceAccessException("boom")` 的对位物)。 +#[derive(Debug)] +struct NoCause(&'static str); + +impl fmt::Display for NoCause { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}", self.0) + } +} + +impl Error for NoCause { + fn source(&self) -> Option<&(dyn Error + 'static)> { + None + } +} + +/// 包装一层(模拟「cause 链被再包一层」)。 +#[derive(Debug)] +struct Wrap(E); + +impl fmt::Display for Wrap { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "wrapped: {}", self.0) + } +} + +impl Error for Wrap { + fn source(&self) -> Option<&(dyn Error + 'static)> { + Some(&self.0) + } +} + +/// 递归的 cause 链(用来造「很深」的链,验证遍历**有界**)。 +#[derive(Debug)] +enum Chain { + Leaf(std::io::Error), + Node(Box), +} + +impl fmt::Display for Chain { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "chain") + } +} + +impl Error for Chain { + fn source(&self) -> Option<&(dyn Error + 'static)> { + match self { + Chain::Leaf(e) => Some(e), + Chain::Node(inner) => Some(inner.as_ref()), + } + } +} + +// ============================================================================ +// 第 2 跳:异常 ⇒ 文案(上游 `ProviderInvokeTimeoutsSelfTest:86-139`) +// ============================================================================ + +/// 上游 ①(`:94`):**read 超时** ⇒ 文案含「调用提供方超时」+ 点名 connect / read 当前值。 +#[test] +fn hop2_read_timeout_is_rewritten_and_names_current_values() { + let e = Wrap(timeout_error("Read timed out")); + let text = timeout_text_or_null(&e, CT, RT).expect("read 超时必须改写文案"); + assert!( + text.contains("调用 TDS 超时"), + "文案须说明是超时,实得:{}", + text + ); + assert!(text.contains(&CT.to_string()), "文案须点名 connect 当前值:{}", text); + assert!(text.contains(&RT.to_string()), "文案须点名 read 当前值:{}", text); +} + +/// 上游 ②(`:105`):**connect 超时** ⇒ 也判超时。 +#[test] +fn hop2_connect_timeout_is_rewritten() { + let e = Wrap(timeout_error("Connect timed out")); + let text = timeout_text_or_null(&e, CT, RT).expect("connect 超时必须改写文案"); + assert!(text.contains("调用 TDS 超时"), "实得:{}", text); +} + +/// 上游 ③(`:112`):🔴 **连接被拒** ⇒ **不得**被标成超时(否则"不可达"被误报成"超时")。 +#[test] +fn hop2_connection_refused_is_not_rewritten() { + let e = Wrap(refused_error("Connection refused: getsockopt")); + assert!( + timeout_text_or_null(&e, CT, RT).is_none(), + "连接被拒不得被标成超时(仍算不可达)" + ); + assert!(!cause_chain_has_timeout(&e)); +} + +/// 上游 ④(`:119`):🔴 **DNS 失败** ⇒ 同上(不��写文案)。 +#[test] +fn hop2_dns_failure_is_not_rewritten() { + let e = Wrap(dns_error("no-such-host.invalid")); + assert!( + timeout_text_or_null(&e, CT, RT).is_none(), + "DNS 失败不得被标成超时" + ); +} + +/// 上游 ⑤(`:123`):**无 cause** ⇒ 不改写。 +#[test] +fn hop2_no_cause_is_not_rewritten() { + let e = NoCause("boom"); + assert!(timeout_text_or_null(&e, CT, RT).is_none(), "无 cause 不得改写"); +} + +/// 上游 ⑥(`:135`):🔴 判据须**走到底** —— cause 链被再包一层后仍须判出超时。 +#[test] +fn hop2_multilevel_wrapped_cause_is_still_detected() { + let e = Wrap(Wrap(Wrap(timeout_error("Read timed out")))); + let text = timeout_text_or_null(&e, CT, RT).expect("多层包装仍须判出超时"); + assert!(text.contains("调用 TDS 超时"), "实得:{}", text); +} + +/// 上游的 cause 链遍历是**有界**的(`depth < 16`)⇒ 本仓同样有界([`MAX_CAUSE_DEPTH`])。 +#[test] +fn hop2_cause_chain_walk_is_bounded() { + assert_eq!(MAX_CAUSE_DEPTH, 16); + // 造一条 40 层深的链 ⇒ 仍然有界返回(不死循环) + let mut e = Chain::Leaf(timeout_error("Read timed out")); + for _ in 0..40 { + e = Chain::Node(Box::new(e)); + } + // 底层的超时在 40 层之外 ⇒ 有界遍历**找不到**它(但**不**死循环) + assert!( + !cause_chain_has_timeout(&e), + "超出深度上限后不应再命中(证明遍历有界)" + ); +} + +// ============================================================================ +// 第 1 跳:配置值 ⇒ socket 层(上游 `ProviderInvokeTimeoutsSelfTest:61-83`) +// ============================================================================ + +/// 起一个「**先连上、但迟迟不响应**」的假对端(用来把读超时逼出来)。 +/// +/// 返回它的基地址。 +fn spawn_delayed_server(delay: Duration) -> String { + let listener = TcpListener::bind("127.0.0.1:0").expect("绑定本地端口失败"); + let addr = listener.local_addr().expect("取本地地址失败"); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { continue }; + std::thread::spawn(move || { + let mut buf = [0u8; 2048]; + let _ = stream.read(&mut buf); // 把请求读掉(读多少都无所谓) + std::thread::sleep(delay); + let body = b"{\"code\":200,\"data\":{\"ok\":true}}"; + let head = format!( + "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n", + body.len() + ); + let _ = stream.write_all(head.as_bytes()); + let _ = stream.write_all(body); + let _ = stream.flush(); + }); + } + }); + format!("http://{}", addr) +} + +/// 上游第 1 跳的**行为级**对位:注入的超时值**真的落进 socket 层**。 +/// +/// 上游用反射读 socket 工厂;Rust 的 `reqwest::Client` 不暴露超时 ⇒ 改成 +/// 「**换一组值 ⇒ 结论必须跟着变**」的行为判别(上游第 1 跳的判别性同款)。 +#[tokio::test] +async fn hop1_injected_timeout_actually_reaches_the_socket_layer() { + let base = spawn_delayed_server(Duration::from_millis(800)); + + // ① 短读超时 ⇒ 必须**超时**(文案点名当前值) + let short = TdsClient::with_timeouts( + Some(base.clone()), + "tok".to_string(), + Duration::from_millis(CT), + Duration::from_millis(150), + ); + assert_eq!(short.read_timeout_ms(), 150, "配置值必须落进客户端"); + let err = short + .internal_catalog("space-1", None) + .await + .expect_err("短读超时必须失败"); + assert!( + err.contains("调用 TDS 超时"), + "短超时必须被判成超时(而不是「不可达」),实得:{}", + err + ); + assert!( + err.contains("150"), + "文案须点名当前 read 值,实得:{}", + err + ); + + // ② 换成长读超时 ⇒ 同样的对端**必须成功**(判别性:值变了,结论跟着变) + let long = TdsClient::with_timeouts( + Some(base.clone()), + "tok".to_string(), + Duration::from_millis(CT), + Duration::from_millis(5000), + ); + assert_eq!(long.read_timeout_ms(), 5000); + let ok = long + .internal_catalog("space-1", None) + .await + .expect("长读超时必须成功(证明超时值真的生效)"); + // `internal_catalog` 走**解包型**语义 ⇒ 返回的是信封里的 `data` + assert_eq!( + ok.get("ok").and_then(|v| v.as_bool()), + Some(true), + "响应体必须被完整收到并解开(实得:{})", + ok + ); +} + +/// 上游第 1 跳的另一半:**换注入值 ⇒ 跟着变**(防"判据恒等于常量")。 +#[test] +fn hop1_changing_the_injected_value_changes_the_client() { + let a = TdsClient::with_timeouts( + Some("http://127.0.0.1:1".to_string()), + "tok".to_string(), + Duration::from_millis(1234), + Duration::from_millis(5678), + ); + assert_eq!(a.connect_timeout_ms(), 1234); + assert_eq!(a.read_timeout_ms(), 5678); + + let b = TdsClient::with_timeouts( + Some("http://127.0.0.1:1".to_string()), + "tok".to_string(), + Duration::from_millis(4321), + Duration::from_millis(8765), + ); + assert_eq!(b.connect_timeout_ms(), 4321); + assert_eq!(b.read_timeout_ms(), 8765); +} + +/// 🔴 **连接被拒 ⇒ 仍算「不可达」**(不得被误报成超时)—— 端到端行为级对位。 +/// +/// 上游第 2 跳 ③ 的**行为**版本:真去连一个没人听的端口 ⇒ reqwest 报 connect 失败 +/// ⇒ 本仓文案必须是「TDS 不可达」,**不是**「调用 TDS 超时」。 +#[tokio::test] +async fn hop2_end_to_end_connection_refused_stays_unreachable() { + // 绑一个端口拿到地址后立刻关闭 ⇒ 几乎必然「连接被拒」 + let addr = { + let l = TcpListener::bind("127.0.0.1:0").expect("绑定失败"); + l.local_addr().expect("取地址失败") + }; + let client = TdsClient::with_timeouts( + Some(format!("http://{}", addr)), + "tok".to_string(), + Duration::from_millis(CT), + Duration::from_millis(RT), + ); + let err = client + .internal_catalog("space-1", None) + .await + .expect_err("没人监听必须失败"); + assert!( + err.contains("TDS 不可达"), + "连接被拒必须仍算不可达,实得:{}", + err + ); + assert!( + !err.contains("调用 TDS 超时"), + "连接被拒不得被误报成超时,实得:{}", + err + ); +}