Skip to content

docs(signatures): make example signature values raw r||s as the spec requires - #590

Merged
damaz91 merged 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/raw-rs-example-signatures
Jul 24, 2026
Merged

damaz91 merged 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/raw-rs-example-signatures

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

Fixes #569: signatures.md mandates fixed-width raw r||s encoding for ECDSA signature values, but the worked examples show values beginning MEUC…/MEQC… — the base64 of a DER SEQUENCE, 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), and order-rest.md (1) with a genuine ES256 raw r||s value (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 (adding ucp-agent to 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.

…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.
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Jul 16, 2026
@damaz91

damaz91 commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

@damaz91
damaz91 self-requested a review July 16, 2026 09:13
…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.
@vishkaty

Copy link
Copy Markdown
Contributor Author

Good catch — thank you! Both fixed, plus one more the first pass missed: those response-signing examples use a second DER shape (MFQCIH…), so I re-swept by decoding every example signature value's leading byte (DER always starts 0x30) instead of pattern-matching, and fixed signatures.md's response-signing example too. Also aligned the stale keyid="merchant-2025" in checkout-rest.md with the merchant-2026 its sibling examples use.

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.

@vishkaty

Copy link
Copy Markdown
Contributor Author

Thanks for the reviews here @damaz91 @jingyli 🙏

This one's approved by both of you and every check is green — the only thing left
is the Governance / Approvals gate, which still reports "Pending required
approvals."
Since it's a small docs fix (and it closes #569), is there a specific
domain/area approver the governance rule is still waiting on? Happy to get it in
front of the right person if that helps move it along — just let me know.

@damaz91
damaz91 merged commit e1b4917 into Universal-Commerce-Protocol:main Jul 24, 2026
19 checks passed
sakinaroufid pushed a commit to sakinaroufid/pr-test that referenced this pull request Jul 31, 2026
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
vishkaty pushed a commit to vishkaty/ucp that referenced this pull request Oct 3, 2026
… 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.
vishkaty pushed a commit to vishkaty/ucp that referenced this pull request Oct 3, 2026
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.
damaz91 pushed a commit that referenced this pull request Oct 16, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

signatures.md: example Signature values are ASN.1/DER, but the spec requires raw r||s encoding

4 participants