---
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`。