Repository navigation
feat(signatures): publish RFC 9421 test vectors and sign every example in the spec - #1008
sakinaroufid wants to merge 3 commits into
Conversation
…rpus Every example signature in the Message Signatures specification is a placeholder, so implementers have had nothing to run a signer or verifier against. Add worked, reproducible test vectors for each signing shape the spec defines: REST request with and without a body, REST response, Web Bot Auth-shaped request (Ed25519 with Dictionary-member selection, thumbprint keyid, created/expires/nonce/tag), order webhook delivery, and an MCP tools/call over streamable HTTP. The vectors sign with the RFC 9421 Appendix B.1.3 and B.1.4 test keys, whose Ed25519 thumbprint is the kid the spec already uses. ECDSA signatures use RFC 6979 deterministic nonces and raw r||s encoding so a deterministic ES256 signer reproduces them byte for byte. The corpus is published next to the spec as specification/signatures/test-vectors.json and quoted verbatim in a new non-normative Test Vectors section. scripts/signature_vectors.py generates it; scripts/test_signature_vectors.py proves the builder against RFC 9421's own Appendix B vectors, re-verifies every published vector from first principles, rejects tampered bodies, headers, signatures, keys and DER-encoded ECDSA, and fails if the page or the corpus drifts from the generator. The check runs in pre-commit and in the docs CI lint job. cryptography is added to the dev dependency group.
… example The spec's GET Request Example carries no UCP-Agent header, so a default UCP verifier cannot resolve its key. The rest-get-es256 vector adds the header and covers it; say so instead of claiming it mirrors the example.
The capability pages and the signatures page show 15 signed requests and responses, and every one carried placeholder values: the same `6G4i8TS6oUkGrx8KnCFUpsSPwd74...` pasted eleven times, digests like `X48E9q...`, and four Lodging examples whose signatures start with `MEUC`/`MFQC`, which is DER, the encoding the page forbids. Nothing could verify them, so an example and the rule it illustrates could disagree until someone read both (Universal-Commerce-Protocol#342, Universal-Commerce-Protocol#370, Universal-Commerce-Protocol#590, Universal-Commerce-Protocol#659, Universal-Commerce-Protocol#795, Universal-Commerce-Protocol#963). Add `verify-docs` and `sign-docs` to scripts/signature_vectors.py. verify-docs finds every fenced block with a complete Signature-Input, rebuilds the message from the block (request or status line, headers in wire order, body as the exact bytes after the blank line, no trailing newline), checks Content-Digest against the body, checks the covered components against the spec's coverage gate, and verifies the signature with the published test keys. sign-docs writes the digest, keyid and signature into the block and leaves everything else as written, so what an example says it covers never changes under it. A block whose Signature-Input is truncated with "..." is a fragment and is skipped; a "..." in a digest or signature is a placeholder and fails. Sign the 15 examples. Elided bodies become short complete payloads, since a digest over `{...}` is not something an implementer can reproduce. The GET example gains the UCP-Agent header the coverage gate requires, and the Lodging REST request now covers ucp-agent like every other request. The GET example ends up byte-identical to the rest-get-es256 vector. verify-docs runs in the docs lint job and from pre-commit on changed spec pages. test_signature_vectors.py covers the page examples: all verify, sign-docs is a no-op on the committed pages, a placeholder is rejected until signed, a tampered body or covered header is reported, a missing required component is reported, and a DER value is named as such. Verified: test_signature_vectors 100 passed; verify-docs 20 passed; validate_examples 407 passed; full draft build and check_links clean.
|
Review guide, since this is a large PR:
The three commits are independent and each builds and passes tests on its own, so they can be reviewed one at a time from the Commits tab. |
|
I'm anticipating this qn from tech council (since this is quite a large PR by LOC) ; Why this PR has its own signing code instead of a library. so answering it below;
It is checked against the RFC's own test vectors every time it runs: No Python library I found covers both |
Description
Summary: the specification’s signed examples carried placeholder digest and signature values that could not be verified. This change publishes RFC 9421 test vectors for the UCP signing profile, replaces every inline example with a message signed over the exact bytes shown using the RFC’s published test keys, and adds a CI check that rebuilds and verifies each example on every change. An example that is edited without being re-signed fails the build.
1. Test vectors. signatures.md profiles RFC 9421 for UCP but every signature on it was a placeholder, so there was nothing to run a signer or verifier against. This adds
scripts/signature_vectors.py, a small RFC 9421 implementation scoped to what the UCP profile uses (derived components@method@authority@path@query@status, fields,;keydictionary member selection,created/expires/nonce/keyid/tag), proven against the RFC's own Appendix B vectors. It generatesdocs/specification/signatures/test-vectors.json: six vectors covering each signing shape the spec defines (REST request, GET, response, WBA-shape request with Ed25519, order webhook, MCP request), signed with the RFC 9421 B.1.3 and B.1.4 test keys so a suite that already has those keys needs nothing new. ECDSA uses RFC 6979 nonces, so a deterministic ES256 signer reproduces the values byte for byte. A new Test Vectors section on signatures.md quotes the corpus andtest_signature_vectors.pychecks the corpus verifies, matches the generator, and is quoted verbatim.2. The inline examples. The checkout, order, booking and signatures pages show 15 signed requests/responses. All of them were placeholders:
6G4i8TS6oUkGrx8KnCFUpsSPwd74...pasted eleven times,X48E9q...digests, and the four Lodging ones start withMEUC/MFQC, i.e. DER, which the page itself forbids. That's how #342, #370, #590, #659, #795 and #963 happened: an example and the rule next to it could disagree and nothing noticed.signature_vectors.py verify-docsnow finds every fenced block with a completeSignature-Input, rebuilds the message from the block (request/status line, headers in wire order, body = exact bytes after the blank line, no trailing newline), checksContent-Digestagainst the body, checks the covered components against the coverage gate, and verifies the signature with the test keys.sign-docswrites real digest/keyid/signature values into a block and leaves everything else alone, so what an example claims to cover never changes under it. Blocks with a truncatedSignature-Input(...in the component list) are fragments and are skipped;...in a digest or signature value is a placeholder and fails.All 15 are now signed. Elided bodies became short complete payloads (a digest over
{...}isn't reproducible). Two content changes beyond that, both things the coverage gate requires: the GET example on signatures.md gainsUCP-Agentand covers it, and the Lodging REST request now coversucp-agentlike every other request does. The GET example ends up byte-identical to therest-get-es256vector.verify-docs runs in the docs lint job and from pre-commit on changed spec pages. Edit a signed example and the hook tells you to re-sign it.
Not in this PR: the webhook delivery contract and the
ready_for_completedefinition that were on the same branch earlier. Those are normative changes and will come separately.Category (Required)
Related Issues
#342 #370 #590 #659 #795 #963
Checklist
!for breaking changes).Screenshots / Logs (if applicable)
verify-docs against the pages on main, two of the fourteen placeholder blocks (the key check comes first, so that is what a placeholder fails on):
The one example on main that already used a test key id (the WBA example on signatures.md) fails on its content instead:
this branch:
Before/after on the Lodging REST page, complete request: