Prototype signed catalog fallback (T-101)

docs/tasks/T-101.md

@@ -0,0 +1,65 @@
+---
+id: T-101
+title: 签名 Catalog 验签与缓存回退原型
+phase: 1
+deps: [T-002]
+status: DONE
+created: 2026-07-16
+issue: null
+context_ref: 45c242ecec153aa2d409a46883da9845503f185c
+claim_branch: null
+work_branch: agent/codex/T-101
+write_paths:
+  - docs/tasks/T-101.md
+  - core/catalog/
+  - testdata/catalog/
+  - testdata/README.md
+  - docs/api.md
+  - docs/04-architecture.md
+  - docs/current-state.md
+---
+
+## 问题 / 背景
+
+Catalog 是后续下载与执行链路的信任根。当前协议只约定 Ed25519 和顶层 `signature`,尚未验证签名域、JSON 歧义处理、缓存替换与断网回退行为。若这里错误,篡改清单可能进入安装链路。
+
+## 方案
+
+1. 在 `core/catalog` 建立 Ed25519 verifier,签名域为“移除顶层 `signature` 后的受限规范 JSON”。
+2. 解析时拒绝重复字段、尾随 JSON、非对象根、非整数数字、缺失/非法长度签名,避免不同解析器对同一文档产生歧义。
+3. 建立 Fetcher/Cache 接口与 Loader:远端验签成功后才写缓存;远端获取或验签失败时只使用再次验签通过的缓存。
+4. 提供文件缓存原型,使用同目录临时文件 + current/backup 改名,并能读取中断后遗留的 backup。
+5. 在 `testdata/catalog` 放置假数据与恶意样例;测试使用明确标注的专用测试密钥,不提交生产私钥。
+6. 将签名域与原型结论同步到 `docs/api.md`、`docs/04-architecture.md`。
+
+## 验收要点
+
+- 合法测试清单验签通过。
+- 篡改内容复用合法签名、伪造签名、重复字段、浮点/指数数字均被拒绝。
+- 远端验签失败不会覆盖最后有效缓存;断网可返回再次验签通过的缓存。
+- 缓存自身被篡改时拒绝,不得当作离线可信数据。
+- 文件缓存更新与 backup 恢复测试通过。
+- `cd core && go vet ./... && go test -count=1 ./...` 通过,Phase 0 双目标闸门继续通过。
+
+## 边界（不改什么）
+
+- 不实现 HTTPS 客户端、Catalog 字段 Schema、OS/架构过滤或 UI 接入(T-201)。
+- 不定稿密钥轮换、撤销名单和 package 独立签名域。
+- 不引入第三方 JSON canonicalization 或加密依赖。
+- 不提交生产私钥、真实 URL 或真实签名。
+
+## 协作约束
+
+未启用 Gitea;本任务在 `agent/codex/T-101` 分支串行执行。签名格式结论标记为 Phase 1 原型,T-201 正式接入时再与发布端共同冻结。
+
+## 执行记录
+
+- 2026-07-16:在 `core/catalog` 建立受限 JSON 解析/规范化与 Ed25519 verifier;拒绝重复字段、尾随值、无效 UTF-8、非对象根、非整数数字和非法签名编码/长度。
+- 2026-07-16:签名域确定为移除顶层 `signature` 后的受限规范 JSON;对象键排序、数组保序、字符串标准 JSON 转义、数字仅允许整数。该结论已同步 `docs/api.md` 与 `docs/04-architecture.md`,并明确为 T-201 前的 Phase 1 原型。
+- 2026-07-16:建立 Fetcher/Cache/Loader;远端只有验签成功才写缓存,获取失败或验签失败时只返回再次验签成功的缓存;缓存写失败作为非致命 warning 暴露。
+- 2026-07-16:建立 FileCache 临时文件 + current/backup 切换原型,并支持 current 缺失时读取中断遗留 backup。
+- 2026-07-16:新增公开虚构的 Catalog testdata;测试密钥由测试代码中的明确测试 seed 运行时派生,仓库不含生产私钥。
+- 定向测试通过:合法、篡改、伪造、重复字段、浮点、指数、缺签名、尾随 JSON、无效 UTF-8、断网回退、坏缓存、缓存写失败与中断 backup 恢复。
+- 验证通过:Go 1.20.14 `go vet ./...`、`go test -count=1 ./...`。
+- 验证通过:`./scripts/verify_phase0.ps1`,包含 core 边界/版本检查和 modern/win7 双目标构建。
+- 验证通过:`python scripts/validate_harness_governance.py`。