Files
tdc-rs/docs/DDL-GUARD.md
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

107 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DDL 不可下载:守卫设计与踩坑记录
> 这条「schema DDL 绝不能从 HTTP 下载」的红线,踩了**四轮**才收干净。
> 本文是那四轮的**决策记录 + 坑位清单**(真值仍在 `src/platform/fallback.rs` 的注释里,本文只讲「为什么」)。
## 为什么要防
`schema/migrate.sql` 是**编译期内嵌**进二进制的上游 `tdc_*` 全量 DDL(3249 行 / 30 张 `tdc_*` + 3 张 `base_*`)。
它一旦能从 HTTP 下载 ⇒ 攻击者直接拿到**全库结构**(表名、列名、索引、约束、注释里的业务语义)。
**根因修复只有一条**:`schema/migrate.sql` **不在 web root**。
`static/` 会被 `ServeDir` 挂到 HTTP 上 ⇒ DDL 必须住在 `schema/`
(`include_str!` 相对 `src/platform/db.rs` 写 `../../schema/migrate.sql`)。
下面两道都只是**兜底**(防「有人不小心把 DDL 复制回 `static/`」)。
## 兜底 1 · 路径级(`ddl_guard`,跑在 `ServeDir` **之前**)
判据:**路径中任意一段的扩展名**,去尾部空白与尾部 `.` 后,**Unicode 大写折叠**后等于 `SQL` ⇒ 404 + JSON。
### 坑 1:只看「最后一段」会被 `.` 结尾绕过
`tower-http-0.6.11` 的 `ServeDir` 用 `Path::components()` 归一化并**丢弃 `CurDir`(`.`)**
⇒ `/migrate.sql/.` 被它解析成「文件 `migrate.sql`」。
⇒ 判据必须是「**任意一段**」,不是「末段」。
### 坑 2:ASCII 不区分大小写会漏 1/3 的拼法
macOS APFS 的文件名比较用的是 **Unicode casefold**,不是 ASCII 折叠:
`ſ`(U+017F,长 s)casefold 到 `s` ⇒ 磁盘上叫 `migrate.sql` 的文件,用 `migrate.ſql` **也能打开**(本机实测)。
`migrate.sql` 的逐字符 casefold 等价拼法是**有限集**:
```
migrate 7 个字母各 2 种(m/M…e/E) ⇒ 2⁷
. 1 种
s 3 种(s / S / ſ)
q 2 种
l 2 种
合计 2⁷×1×3×2×2 = 1536 种
```
**本机实测**:这 1536 种在磁盘上全部命中同一个文件。
旧的 `eq_ignore_ascii_case` 只覆盖 **1024 / 1536** ⇒ 漏掉含 `ſ` 的那 512 种。
⇒ 改用 **`to_uppercase`**(`ſ` 大写为 `S`)后,12 种扩展名拼法
(`s∈{s,S,ſ} × q∈{q,Q} × l∈{l,L}`)**全部**折叠成 `SQL`
⇒ 覆盖 **1536 / 1536**。
⚠️ **不能用 `to_lowercase`** —— `ſ` 的小写还是 `ſ` ⇒ 会漏。
### 坑 3:守卫必须挂在 `ServeDir` 之前
axum 0.8.9 的 `Router::layer` 会**同时**包住 `fallback_router` 与 `catch_all_fallback`
⇒ 前置中间件先于 `ServeDir` 执行。
⚠️ 用 axum 自己的 `any(handler)` 兜底,**不要**用 `tower::service_fn`(`tower` 只是 dev-dependency,lib 里不许用)。
### 坑 4:percent-decode 的层数是**契约**
守卫与 SPA 决策层必须用**同一口径**(都先 decode)。只 decode 一层是刻意的:
两层会让 `%252F` 变成 `/`,与 `ServeDir`(`tower-http` 也只 decode 一层)对不上;零层又认不出 `%2F`。
## 兜底 2 · 内容级(`ddl_content_guard`,跑在 `ServeDir` **之后**)
判据:响应体**与内嵌 DDL 逐字节相同** ⇒ 404 + JSON。这条**只认内容**,
文件名怎么拼、怎么折叠、怎么规范化**全都无关** ⇒ 兜住「改了名、内容还是那份 DDL」的副本。
### 坑 5(**本项目最重的一个洞**):`Range` 分段能拼回整份
`Range: bytes=0-1000` 的响应体只有 1001 字节(`Content-Length` ≠ DDL 长度)
⇒ 若只按「整份长度」比对 ⇒ **放行** ⇒ 而**逐段请求能把整份 DDL 拼回来**
⇒ 那不是「片段泄露」,是**完整泄露**。
⇒ 改成按 `Content-Range` 的**同偏移**片段比:`Content-Range: bytes <start>-<end>/<total>`
⇒ 取 `DDL[start..=end]` 逐字节比。
`total` 段**一律忽略**(顺带兜住「DDL + 一段尾巴」这类副本:它的前 N 字节就是 DDL 的前 N 字节)。
### 坑 6:长度说谎要 fail-closed
`to_bytes(body, expected.len())` 报错(实际比声明的长)⇒ **当命中处理**(404),
不因为「读不出来」就放行。
## 已知边界(记录在案,不改)
| 边界 | 说明 | 后果 |
|---|---|---|
| 改过一个字节的副本 | 整份响应不拦(内容不再逐字节相同) | 只泄露「几乎一样的 DDL」,不泄露原件;且该副本的 `Range` 片段里**不含**那个改动字节的片段**仍会被拦** |
| `HEAD` 请求改名副本 | 仍 **200**(带 `Content-Length`,**无体**) | 只泄露**长度**,不泄露内容(内容判据要有体可比) |
| `/migrate.sql%00`(尾部 NUL) | 不命中路径级守卫(扩展名不是 `SQL`) | 交 `ServeDir` ⇒ 该文件名不存在 ⇒ 落 SPA 层(200 + `text/html`);**不泄露 DDL**(不是同一个文件名),但**响应形状**与守卫表不同 |
| 尾部带点/带空格的名字 | APFS 上 `migrate.sql.` / `migrate.sql ` **打不开**;HFS+ 会把尾部点从磁盘名里去掉 | 两种文件系统行为不一致 ⇒ 判据**保守**处理(多拦不错放) |
## 回归测试
`tests/spa_fallback.rs`(10 个用例)覆盖:路径级(含 Unicode casefold 变体)、内容级(改名副本)、
`Range` 分段(整份/首段/中段)、`/api/**` 404 JSON、SPA 深链、静态资源照常。
```bash
cargo test --test spa_fallback
```
## 教训(下次同类任务直接照抄)
1. **黑名单要按「类」判,不按「名字」判** ⇒ 扩展名规则 > 文件名规则。
2. **大小写折叠用 Unicode 语义**(`to_uppercase`),别用 ASCII 折叠。
3. **「只认整份」的比对要连带分段一起想** —— 分段能拼回整份。
4. **路径判定与文件系统的归一化必须同口径**(`Path::components()` 会丢 `CurDir`)。
5. **兜底要有根因修复兜底** —— 真正的控制是「DDL 不在 web root」,两道守卫只是防手滑。