diff --git a/README.md b/README.md index b54e383..649572f 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,22 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC > **HTTP 401/403 + `{"success":false,"code":401,"msg":"…"}`**(**无 `data` 键**)。 > 内部库为单 in-process backend,所有 DB 访问由 `tokio::Mutex` 串行化。 +**鉴权三道门**(顺序与文案与上游一致): + +| 门 | 载体 | 失败文案 | +|---|---|---| +| ① 协议版本 | `X-Protocol-Version` | 401「跨端协议版本不兼容,请升级对端」 | +| ② 内部令牌 | `X-Internal-Token`(**只看头**,不收 query/body) | 401「内部接口凭证无效」 | +| ③ 会话令牌 | `X-Auth-Token` 或 `Authorization: bearer ` | 401「内部接口凭证无效」 | + +**写操作的权限键**(`src/registry.rs` 的 `PERMISSION_KEYS`,18 条「实体 → 权限键」): + +- 权限键来自 `tdc_identity.f_capability`(`domain::identity::capabilities()`)。 +- 能力集**解析不出** ⇒ **fail-open**(本地单机模式没有能力集,不该把写操作全锁死); + **解析出来** ⇒ 按键判定,`*` / `all` 通配放行。 +- 无凭证 ⇒ 403;内部令牌 ⇒ 放行;**本地账号 ⇒ 放行**(⚠️ 已知边界,见 `.superpowers/sdd/` ledger)。 +- 🔴 `TDC_STRICT_SECRETS=1` ⇒ 默认口令视为不安全 ⇒ **启动即失败**。 + ## 已实现范围 **30 张表**(上游 `tdc_*` schema 的生成产物):其中 **24 张**带齐 **10 个系统列** @@ -134,6 +150,9 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC `DestroyLog` / `PolicyCheckLog` / `Contract` / `ApiConsumeLog` 带写保护,详见 `src/registry.rs` - 2 个聚合详情:`/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` - 4 个 `Auth` 端点:`Auth/Login`、`Auth/Me`、`Auth/Spaces`、`Auth/SsoConfig` +- **JNPF 兼容登录 + 本地账号管理**(上游完整控制台的真登录链): + `POST /api/oauth/Login` + `/api/permission/Users*` 6 个端点(**仅管理员**), + 账号库存本机 `data/accounts.json`(**不进数据库** ⇒ 30 表口径不变) - `GET /api/health` > 🔴 **上游那 100+ 个「动作端点」(发布 / 下架 / 提交审核 / 通过 / 驳回 / 签署 / 生效 / 终止 / @@ -157,13 +176,19 @@ Quality* / HostingJob` 等控制器依赖 **Nax 隐私计算引擎**与 **scard tdc-rs/ ├── Cargo.toml # 含 pglite-rs = "0.2" ├── src/ -│ ├── main.rs # axum:内嵌 PGlite + 路由装配 + 中间件 -│ └── routes/ # 按域装配:health / auth / crud / mw(405 改写)/ fallback(404 + SPA 兜底) +│ ├── main.rs # 启动装配:内嵌 PGlite + 引导身份 + 账号库 + 路由 + 中间件 + 静态兜底 +│ ├── lib.rs # 模块声明(业务逻辑都在 lib,bin 只做装配) +│ ├── auth.rs / session.rs # 鉴权中间件 + 三道门 / 会话存储(身份会话 / 账号会话) +│ ├── registry.rs / crud.rs # 18 实体注册表 + 权限键 / CRUD 引擎(写操作二次校验) +│ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data}) +│ ├── account.rs / cipher.rs# 本地账号库(JSON 文件)/ 登录口令加解密(对齐上游 cipher.ts) +│ └── routes/ # 按域装配:health / auth / account / crud / body / mw(405 改写)/ fallback(404 + SPA 兜底 + DDL 守卫) ├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/) ├── schema/ -│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制;**不在 web root**) +│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制;**不在 web root**;30 表) ├── scripts/ # build-frontend.sh(前端产物)/ gen-migrate.sh(schema 生成)/ reset-data.sh -├── docs/ # 补充文档 +├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail) +├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md) ├── tds-stub/ # 本地 TDS 契约桩(零依赖,仅供端到端调试) -└── data/ # 运行期数据(tdc.pg/,已 gitignore) +└── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore) ``` diff --git a/docs/DDL-GUARD.md b/docs/DDL-GUARD.md new file mode 100644 index 0000000..3195acd --- /dev/null +++ b/docs/DDL-GUARD.md @@ -0,0 +1,105 @@ +# 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 -/` +⇒ 取 `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」,两道守卫只是防手滑。 diff --git a/docs/TDC-TDS-CONTRACT.md b/docs/TDC-TDS-CONTRACT.md index b81d613..dc40859 100644 --- a/docs/TDC-TDS-CONTRACT.md +++ b/docs/TDC-TDS-CONTRACT.md @@ -1,7 +1,11 @@ # TDC ↔ TDS 跨方契约参考 -本仓库 `/api/ssw/tdc/tds/*` 代理网关所还原的原始契约,真源在 -`~/Desktop/workspace/ssw-mvp/boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/client/`。 +> 🔴 **现状(P0+P1)**:本仓**没有** TDS 出向通道。 +> 旧版的 `/api/ssw/tdc/tds/*` 代理网关**已随 Task 10 下线**(现在请求该路径 ⇒ **404**)。 +> `SSW_TDS_BASE_URL` 目前只用于**健康检查回显**与「本地单机模式」的判定,不产生任何出向请求。 +> +> **本文现在的角色 = P4(TDS 出向客户端)的输入契约**,不是本仓现状的描述。 +> 出向客户端落地时,本文列的路径/请求头/错误口径**逐条照抄**即可。 ## 原 Java 侧结构 @@ -49,9 +53,9 @@ POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void `POST /api/ssw/tds/NodeReport` 可直连(200);`GET /NodeReport/Categories` 需登录态。 → 本仓库 heartbeat 在配 base-url 时一并上报 `NodeReport`,失败仅告警不影响本地。 -## 代理行为约定(`src/main.rs` → `tds_proxy`) +## 代理行为约定(**旧代理已下线**;下表是 P4 重做时的行为约定) -| 行为 | 实现 | +| 行为 | 约定 | |---|---| | 路径映射 | `/api/ssw/tdc/tds/{rest}` → `{base}/api/ssw/tds/{rest}`(query 透传) | | 逐跳头剥离 | `host` / `content-length` / `connection` / `transfer-encoding` / `upgrade` / `keep-alive` / `te` / `trailer` | @@ -61,7 +65,10 @@ POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void | 未配 base-url | 返回 501 `NOOP mode`(对应原 `NoopTdcTdsClient`) | | 响应回传 | 透传上游状态码与 `Content-Type`,body 原样字节回传 | -## 实测验证记录(真实 TDS,2026-10-23) +> ⚠️ 「未配 base-url ⇒ 501 NOOP」「失败即降级、绝不拖垮本地 TDC 业务」是**原 Java 侧的核心原则** +> (`TdcTdsClient` → `NoopTdcTdsClient`),P4 重做时必须保留。 + +## 实测验证记录(真实 TDS,2026-10-23,**旧代理时代**) | 调用 | 结果 | |---|---| @@ -70,3 +77,6 @@ POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void | `Bridge/DataProduct/855039616187633989` | 「测评目录产品-iws2k」,`DRAFT` | 经本仓库连接器代理调用返回**完全相同**的数据,与 `tds` 库一致。 + +> ⚠️ 这份记录是**旧代理时代**(2026-10-23)留下的,**旧代理现已下线**。 +> P4 落地出向客户端时,**重新做一遍**这组实测并更新本表。