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

5.8 KiB
Raw Blame History

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 深链、静态资源照常。

cargo test --test spa_fallback

教训(下次同类任务直接照抄)

  1. 黑名单要按「类」判,不按「名字」判 ⇒ 扩展名规则 > 文件名规则。
  2. 大小写折叠用 Unicode 语义(to_uppercase),别用 ASCII 折叠。
  3. 「只认整份」的比对要连带分段一起想 —— 分段能拼回整份。
  4. 路径判定与文件系统的归一化必须同口径(Path::components() 会丢 CurDir)。
  5. 兜底要有根因修复兜底 —— 真正的控制是「DDL 不在 web root」,两道守卫只是防手滑。