Repository navigation
docs(signatures): make example signature values raw r||s as the spec requires - #590
Conversation
…requires
signatures.md mandates fixed-width raw r||s encoding for ECDSA signature
values ("MUST use fixed-width raw r||s encoding"), but the worked examples
showed values beginning ME[UQ]C... — the base64 of a DER SEQUENCE, the exact
encoding the normative text forbids. An implementer copying the examples'
shape produces signatures a conformant verifier rejects.
Replaces the seven example values in signatures.md, checkout-mcp.md,
checkout-rest.md, and order-rest.md with a genuine ES256 raw r||s value
(64 bytes, 88 base64 chars), preserving each instance's truncation style.
The instance in order.md is deliberately left to avoid overlapping Universal-Commerce-Protocol#568,
which edits the same example block.
Fixes Universal-Commerce-Protocol#569.
|
Thanks for this documentation fix @vishkaty ! I see there are others examples fix worthy, like
Can you take a look and add them in this PR? |
…alues Extends the sweep per review: the response-signing examples used a second DER shape (MFQCIH..., a 0x30-led SEQUENCE) that the first pass's pattern missed — now swept by decoding every example signature value's leading byte rather than pattern-matching. Fixes checkout-mcp.md, checkout-rest.md, and signatures.md's response-signing example, and aligns the stale keyid="merchant-2025" with the merchant-2026 used by every sibling example. order.md's instance remains deferred to avoid overlapping Universal-Commerce-Protocol#568.
|
Good catch — thank you! Both fixed, plus one more the first pass missed: those response-signing examples use a second DER shape ( The only DER-shaped value now remaining anywhere in docs/ is order.md's — left deliberately since #568 edits that same example block; it can pick up the value fix on whichever lands second. |
|
Thanks for the reviews here @damaz91 @jingyli 🙏 This one's approved by both of you and every check is green — the only thing left |
Corrects several places where documentation examples contradict the schemas or the normative signing requirements: - Replace nonexistent message paths: buyer.json has no shipping_address property and no schema defines selected_fulfillment_option. Point validation messages at the real fields (fulfillment.methods[].selected_destination_id and fulfillment.methods[].groups[].selected_option_id). - Order webhook example: the payload is the plain order snapshot per order.md itself and rest.openapi.json (no event_id/created_time fields); event identity travels in the Webhook-Id/Webhook-Timestamp headers, which the example now includes. Also cover ucp-agent in Signature-Input as signatures.md requires when UCP-Agent is present, and replace the last remaining DER-encoded ECDSA example signature with the raw r||s value used everywhere else (follow-up to Universal-Commerce-Protocol#590). - Playground: emit the webhook simulation as headers + order body instead of injecting event_id/created_time into the payload. - split-payments: capabilities is an object keyed by reverse-domain name (ucp.json), not an array; this was the only array-form example in the tree. - discount: totals is an array, so $.totals.shipping cannot address the shipping total (and 'shipping' is not a well-known total type); use a JSONPath filter on type=='fulfillment' in both the doc table and the allocation path description in discount.json. - checkout-rest signed request example: cover ucp-agent in Signature-Input, matching the canonical example in signatures.md and its coverage verification pseudocode. - checkout-a2a: use 'kind' consistently for A2A message parts; four examples mixed 'type' and 'kind' between adjacent parts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011MnLq8ZJ3uAvzoEWxBLuYM
… signing gate Addresses the review on Universal-Commerce-Protocol#659. Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in Universal-Commerce-Protocol#342 left them outside Content-Digest, so an order webhook's identity and freshness were unsigned. The first draft fixed that with a rule local to order/index.md. Per review, the rule belongs in the global covered-component gate instead, so one route-agnostic verifier handles REST requests and webhooks without endpoint branching. 1. overview/index.md IRA step 5 and signatures.md now carry webhook-id and webhook-timestamp in the closed sign-if-present set: a table row each, a footnote giving the reason, and both the sign_rest_request and verify_rest_request pseudocode. rest.openapi.json already marks both headers required: true on order_event_webhook, so the presence gate does the rest. 2. Webhook-Id deduplication is SHOULD, not MUST. An order webhook carries the full current state rather than a delta, and Webhook-Timestamp is now signed and immutable, so a platform applying highest-timestamp-wins, or reconciling through GET /orders/{id}, is already replay-safe without keeping delivery state. Deduplication still earns its place for retry short-circuiting and same-second events, which is a SHOULD. 3. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request Verification rather than listing components, which had read as if @method, @authority, @path, @query and content-type were optional. 4. The example Signature value matches Universal-Commerce-Protocol#590's form, and the playground.md comment points at shopping/order/index.md. BREAKING CHANGE: a signature covering only the baseline REST components is no longer valid for a delivery carrying Webhook-Id or Webhook-Timestamp. Businesses must add both to Signature-Input; platforms must reject deliveries that omit them. The headers are already required: true on the webhook operation, so this binds signatures to headers the delivery was already obliged to carry. Verified on this branch, rebased onto main b0e81ad: validate_examples 376 passed 0 failed; its unit tests 59 passed; ucp-schema lint 144 files all passed; DOCS_MODE=spec mkdocs build --strict exit 0 with 0 warnings, 102 pages and 52 social cards; check_links byte-identical to the control on unmodified main, the same three pre-existing missing anchors under documentation/, none in the files touched here. Both newly referenced anchors resolve in the built site.
Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in Universal-Commerce-Protocol#342 left them outside Content-Digest, so the identity and the freshness of an order event travelled unsigned. Per review on Universal-Commerce-Protocol#659 the rule belongs in the global covered component gate rather than in order/index.md, so one route agnostic verifier handles REST requests and webhooks with no endpoint branching. Both headers join the closed sign if present set in overview/index.md IRA step 5 and in signatures.md, as a row each in the Signed Components table with a footnote giving the reason, plus sign_rest_request and verify_rest_request. rest.openapi.json already marks both required: true on order_event_webhook, and they appear on no other operation in any of the four service documents, so the header presence gate does the rest. Deduplication on Webhook-Id is SHOULD rather than MUST. An order webhook carries the full current state of the order rather than a delta, which the order page states at three points, so a platform applying deliveries in Webhook-Timestamp order, or reconciling through GET /orders/{id}, converges without per delivery state. Deduplication still earns a SHOULD for retry short circuiting and for events that share a timestamp, whose resolution is one second. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request Verification instead of naming a subset of components, which had read as if @method, @authority, @path, @query and content-type were optional. The example Signature value takes the Universal-Commerce-Protocol#590 form, and the playground.md comment points at shopping/order/index.md. The Signed Components table is re-padded because the webhook-timestamp row is wider than the previous column width, which trips markdownlint MD060 under the version super-linter pins. BREAKING CHANGE: a signature covering only the baseline REST components is no longer valid for a delivery carrying Webhook-Id or Webhook-Timestamp. Businesses must add both to Signature-Input, and platforms must reject deliveries that omit them. Both headers are already required: true on order_event_webhook, so this binds signatures to headers the delivery was obliged to carry, and the blast radius is the order event webhook alone.
…te (#659) * fix(order)!: cover webhook-id and webhook-timestamp in the signing gate Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in #342 left them outside Content-Digest, so the identity and the freshness of an order event travelled unsigned. Per review on #659 the rule belongs in the global covered component gate rather than in order/index.md, so one route agnostic verifier handles REST requests and webhooks with no endpoint branching. Both headers join the closed sign if present set in overview/index.md IRA step 5 and in signatures.md, as a row each in the Signed Components table with a footnote giving the reason, plus sign_rest_request and verify_rest_request. rest.openapi.json already marks both required: true on order_event_webhook, and they appear on no other operation in any of the four service documents, so the header presence gate does the rest. Deduplication on Webhook-Id is SHOULD rather than MUST. An order webhook carries the full current state of the order rather than a delta, which the order page states at three points, so a platform applying deliveries in Webhook-Timestamp order, or reconciling through GET /orders/{id}, converges without per delivery state. Deduplication still earns a SHOULD for retry short circuiting and for events that share a timestamp, whose resolution is one second. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request Verification instead of naming a subset of components, which had read as if @method, @authority, @path, @query and content-type were optional. The example Signature value takes the #590 form, and the playground.md comment points at shopping/order/index.md. The Signed Components table is re-padded because the webhook-timestamp row is wider than the previous column width, which trips markdownlint MD060 under the version super-linter pins. BREAKING CHANGE: a signature covering only the baseline REST components is no longer valid for a delivery carrying Webhook-Id or Webhook-Timestamp. Businesses must add both to Signature-Input, and platforms must reject deliveries that omit them. Both headers are already required: true on order_event_webhook, so this binds signatures to headers the delivery was obliged to carry, and the blast radius is the order event webhook alone. * docs(signatures): name the webhook headers by what they identify Review feedback from @igrigorik on #659, applied as suggested. `Webhook-Id` identifies the event, not the delivery: it is identical on every retry, which is what makes the SHOULD-deduplicate rule work. `source/services/shopping/rest.openapi.json` calls it "The unique identifier of a webhook event" and `order/index.md:697` already said "Unique event identifier", so the covered-components table was the only place calling it a delivery identifier. The `****` footnote said `Idempotency-Key` is "Required for POST, PUT, DELETE, PATCH" two lines above a note saying webhook deliveries carry none, in the same table. IRA step 5 treats it as sign-if-present and carries the parenthetical that whether a request must carry the header at all is a binding-level rule, separate from the coverage check. The footnote now says that. The `‡` note described `Webhook-Timestamp` as a freshness value, which is the Standard Webhooks meaning: attempt time, re-stamped on retry, checked against a tolerance window. The UCP value is the immutable event time, so the note now says event identity and event time, and both headers are per-event rather than per-delivery. `order/index.md:748` said the verification section requires rejecting "a delivery that omits either". That section is sign-if-present and says nothing about absent headers; the absent case is `required: true` in the OpenAPI binding. The rule it does define is: header present, signature does not cover it, treat as unsigned. The text now says that. Swept each point across docs/specification, and across source/, scripts/ and the scaffolds, rather than editing the four cited lines. Line numbers below are as at the parent of this commit. Out of class and left alone, with reasons: `:754` per-delivery state means state held about each delivery; `:376` and `:868` use freshness for the WBA created/expires window, which is a freshness signal; `:452` already uses the signature-side framing; `:824` describes the replay-protection mechanism. `:436` "Idempotency header (state-changing)" is the one debatable exclusion: it keeps the method framing one column left of the footnote this commit corrects, and the column mixes conditions with descriptions, so it is raised on the PR rather than changed here. Gates: validate_examples 398 passed, 0 failed, 0 errors, 53 skipped, identical to the control; its unit tests 59 passed; ucp-schema lint source/ 145 files all passed; pre-commit on the changed files all Passed; markdownlint 0.47.0 and 0.49.0 both clean, and a planted table misalignment reds MD060 on 0.49.0. * docs(order): oblige retries to carry the original webhook id and timestamp Review feedback from @igrigorik on #659, applied as suggested. The platform-side rule said platforms SHOULD deduplicate on Webhook-Id and may apply deliveries in Webhook-Timestamp order. Both depend on a retry carrying the same two values, and nothing in the spec obliged a business to do that, so the guarantee rested on an assumption. Businesses MUST now send retries with the original Webhook-Id and Webhook-Timestamp, stated once in the Events prose and once in the Business guidelines next to the retry MUST it completes. The header table row for Webhook-Id reads "Event identifier; stable across retries", which is the same fact where a reader meets the header first. Swept the class: shopping/order is the only capability with a webhook retry rule today, so no sibling needs the same obligation. Left alone: the Webhook-Id parameter in source/services/shopping/rest.openapi.json reads "The unique identifier of a webhook event", which is consistent with stability across retries without stating it. That belongs in the separate follow-up @gsmith85 invited rather than in an approved PR. Gates: markdownlint 0.49.0, the version super-linter pins and the one that carries MD060, is clean, and the new Webhook-Id row keeps the header table at 70 characters. validate_examples 398 passed 0 failed 0 errors 53 skipped, test_validate_examples 66 passed, ucp-schema lint source/ 145 files all passed, test_schema_tables rc 0, each identical to main d9c18e0. None of those four can observe a prose edit in docs/, so they show the change breaks nothing rather than that it is right; the table width check is the one that earns its place, because the row came from the suggestion UI, which is how MD060 bit this branch before. --------- Co-authored-by: Vishal Katyal <vishal@katyal.ai> Co-authored-by: Ilya Grigorik <ilya@grigorik.com>
Fixes #569: signatures.md mandates fixed-width raw
r||sencoding for ECDSA signature values, but the worked examples show values beginningMEUC…/MEQC…— the base64 of a DERSEQUENCE, the exact encoding the normative text forbids (§ Signature value encoding). An implementer copying the examples' shape produces signatures a conformant verifier rejects.What changed
Replaces the seven example signature values across
signatures.md(4),checkout-mcp.md(1),checkout-rest.md(1), andorder-rest.md(1) with a genuine ES256 rawr||svalue (a real P-256 signature: 64 bytes → 88 base64 chars, decodes to no ASN.1 structure), preserving each instance's truncation style (…).The eighth instance, in
order.md, is deliberately not touched here — #568 edits the same example block (addingucp-agentto its covered components), and overlapping diffs would conflict; it can pick up the value fix on whichever lands second.Example values only; no normative text changes.