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

docs(signatures): make example signature values raw r||s as the spec requires#590
damaz91 merged 3 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/raw-rs-example-signatures

Conversation

@vishkaty

@vishkaty vishkaty commented Jul 16, 2026

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.

@vishkaty
docs(signatures): make example signature values raw r||s as the spec …
d10d010 
…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

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?

@damaz91
damaz91 self-requested a review July 16, 2026 09:13
@vishkaty
docs(signatures): fix remaining DER-shaped response-signing example v…
2da4cfd 
…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

vishkaty commented Jul 16, 2026

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

vishkaty commented Jul 24, 2026

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
@claude
fix: align spec examples with schema definitions and signing rules
de7ea3d 
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jingyli jingyli jingyli approved these changes
@yanheChen yanheChen yanheChen approved these changes
@damaz91 damaz91 damaz91 approved these changes
@DanielFalconGuedes DanielFalconGuedes Awaiting requested review from DanielFalconGuedes

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation status:under-review

Projects

None yet

Milestone

No milestone

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

@vishkaty @damaz91 @jingyli @yanheChen