- 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]>
5.7 KiB
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 深链、静态资源照常。
cargo test --test spa_fallback
教训(下次同类任务直接照抄)
- 黑名单要按「类」判,不按「名字」判 ⇒ 扩展名规则 > 文件名规则。
- 大小写折叠用 Unicode 语义(
to_uppercase),别用 ASCII 折叠。 - 「只认整份」的比对要连带分段一起想 —— 分段能拼回整份。
- 路径判定与文件系统的归一化必须同口径(
Path::components()会丢CurDir)。 - 兜底要有根因修复兜底 —— 真正的控制是「DDL 不在 web root」,两道守卫只是防手滑。