Freeze catalog signature vectors (T-614)

2026-07-18 16:46:17 +08:00
parent 9e5f3f4840
commit 0c1b7662c6
11 changed files with 370 additions and 32 deletions
@@ -7,3 +7,11 @@
 - 恶意样例用于证明解析器和安全边界会拒绝输入,不得被发布流程消费。
 - `catalog/manifest-valid-payload.json` 同时作为 manifest v1 强类型解析与目标过滤的公开虚构样例;包哈希与签名只保证格式合法,不对应真实下载物。
 - `download/`:T-301 在运行时生成 HTTPS Range、断连、并发和恢复样例,不保存真实下载包。
+
+## Catalog canonicalization vectors
+
+`catalog/canonical-vectors.json` is the versioned, cross-implementation signing corpus for the Catalog signature domain. It contains only a public RFC 8032 test key and fixed synthetic documents, canonical signing bytes and Ed25519 signatures; it never contains a production private key, real Catalog URL or release signature.
+
+Each `document` is the raw UTF-8 JSON text passed to the verifier. A successful vector provides the exact `signed_payload_base64` and top-level `signature`; a rejecting vector provides `want_error` (`invalid_document`, `unsupported_number` or `signature_invalid`). Both the client and the external `softbox-catalog` publisher must consume these static values verbatim. They must not recreate expected bytes or signatures by calling their own canonicalizer or signing helper.
+
+The corpus freezes Unicode key sorting/escaping, U+2028/U+2029, valid and invalid surrogate behavior, `-0` and large integers, nested `signature`, canonical padded Base64 and semantic-equivalent JSON representations. Extending it is a protocol change: increment `schema_version` when its interpretation changes and update `docs/api.md` together with client and publisher tests.