Files
tdc-rs/docs/DDL-GUARD.md
T
adminandClaude Code 4a5b7ecb2b docs: 补齐鉴权/权限键说明 + 目录树同步 + DDL 守卫踩坑记录
- README: 新增「鉴权三道门」表与「写操作的权限键」说明块;「已实现范围」
  补 JNPF 兼容登录 + 本地账号管理一条;目录树同步到当前模块拆分
  (src/lib.rs、src/{account,auth,cipher,…}、src/domain、src/routes 全量、
  tests/、data/accounts.json)。
- docs/DDL-GUARD.md: 新增。记录 DDL 不可下载这条红线的四轮踩坑(路径级
  Unicode 大写折叠 1536/1536、内容级 Range 同偏移比对、fail-closed)、
  已知边界与回归测试入口。
- docs/TDC-TDS-CONTRACT.md: 加现状横幅 —— 旧代理网关已随 Task 10 下线
  (请求 /api/ssw/tdc/tds/* 现为 404),SSW_TDS_BASE_URL 仅用于健康检查
  回显与单机模式判定;本文改为 P4 出向客户端的输入契约。

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 11:28:34 +08:00

106 lines
5.7 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/routes/fallback.rs` 的注释里,本文只讲「为什么」)。
## 为什么要防
`schema/migrate.sql` 是**编译期内嵌**进二进制的上游 `tdc_*` 全量 DDL(3017 行 / 30 表)。
它一旦能从 HTTP 下载 ⇒ 攻击者直接拿到**全库结构**(表名、列名、索引、约束、注释里的业务语义)。
**根因修复只有一条**:`schema/migrate.sql` **不在 web root**。
`static/` 会被 `ServeDir` 挂到 HTTP 上 ⇒ DDL 必须住在 `schema/`(`include_str!` 相对 `src/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」,两道守卫只是防手滑。