Skip to content

docs(checkout-rest): cover ucp-agent in the example signed request - #795

Merged
damaz91 merged 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:docs/rest-signed-example-covers-ucp-agent
Oct 14, 2026
Merged

damaz91 merged 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:docs/rest-signed-example-covers-ucp-agent

Conversation

@vishkaty

@vishkaty vishkaty commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #794

What this changes

Adds "ucp-agent" to the covered components of the Example Signed Request in the checkout REST binding, docs/specification/shopping/checkout/rest.md line 1430.

Before:

("@method" "@authority" "@path" "idempotency-key" "content-digest" "content-type")

After:

("@method" "@authority" "@path" "ucp-agent" "idempotency-key" "content-digest" "content-type")

The example already prints a UCP-Agent header. signatures.md makes ucp-agent a conditionally required covered component at line 434, with the footnote at line 442 reading "Required if UCP-Agent header is present", and the verifier pseudocode at lines 715 to 721 reaches coverage_insufficient and skips a signature that omits it. overview/index.md line 1662 carries the same closed set. So the example as shipped models a request a conformant verifier will not authenticate.

The resulting covered set is identical to the canonical REST request example at signatures.md line 515, which is the document this section links to for the complete signing algorithm. The two examples still differ elsewhere, for instance in their keyid.

Scope

One line. No normative text changes, no schema changes, no new prose.

Rebased onto main ad9950ba on 2026-10-11; the branch was 28 commits behind and the hunk is unchanged by the rebase apart from its line number.

Corrected since this was opened. The body previously cited line 1440 for the change and overview/index.md line 2435 for the requirement; both have drifted and line 2435 is now blank. It also carried the sweep from the linked issue, 13 fenced blocks with 2 violations, and said this PR and #659 closed the class between them. That is no longer the count. On main today, of the 9 signed example blocks under docs/specification that print a UCP-Agent header, 3 omit the component: this one, shopping/order/index.md line 751 in open PR #659, and lodging/booking/rest.md line 1589 in open PR #934. The third arrived with #780 in September, after the issue was written. The class reaches zero when all three land, and the three merge clean with each other and with main.

Test plan

  • scripts/validate_examples.py --schema-base source/schemas/: 398 passed, 0 failed, 0 errors, 53 skipped.
  • scripts/test_validate_examples.py: 59 passed.
  • ucp-schema lint source/: 145 files, all passed.
  • pre-commit on the changed file: all hooks Passed.

All measured on the rebased branch, and all unchanged against unmodified main as the control. That is expected rather than reassuring: the example is a ```http fence, which validate_examples.py skips by language, so no CI job here inspects a covered set. The mechanical check that does catch it compares, per fenced block, the headers the block carries against the components its own Signature-Input names; it flags this block before the change and not after, and reverting the one line makes it flag again.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Sep 2, 2026
@carolinerg1 carolinerg1 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Sep 3, 2026
@damaz91 damaz91 added the documentation Improvements or additions to documentation label Sep 10, 2026
@vishkaty
vishkaty force-pushed the docs/rest-signed-example-covers-ucp-agent branch from efea311 to 1b5119f Compare September 11, 2026 04:26
@damaz91
damaz91 requested review from mmohades and removed request for niranjanmanjunath September 21, 2026 10:42
@damaz91 damaz91 added area:shopping Issues and pull requests related to the Shopping vertical status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Sep 24, 2026
@damaz91

damaz91 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

Can a maintainer take a look at this simple change? @mmohades @knightlin-shopify

The Example Signed Request in the checkout REST binding carries a
UCP-Agent header, but its Signature-Input covers only "@method"
"@authority" "@path" "idempotency-key" "content-digest" "content-type".

The identity resolution gate in overview/index.md states that a
signature MUST cover ucp-agent, signature-agent and idempotency-key
when those headers are present, and that a verifier MUST skip a
signature whose covered set omits any of them, since a header the
signature does not cover is treated as unsigned. The example therefore
shows a request whose signature a conformant verifier is required to
skip, in the one place an implementer copies from.

Adds "ucp-agent" to the covered set, which makes its covered set
identical to the canonical REST request example in signatures.md
line 515, the document this section links to for the complete signing
algorithm. The two examples still differ elsewhere, for instance in
their keyid.

No normative text changes. validate_examples.py 343 passed, 0 failed,
50 skipped and test_validate_examples.py 52 passed on a test merge into
main 1d39948 on 2026-09-01, both unchanged by this commit, because the
example is an unannotated http fence that no CI job inspects. cspell
clean on the changed file.
@vishkaty
vishkaty force-pushed the docs/rest-signed-example-covers-ucp-agent branch from 1b5119f to cc37629 Compare October 11, 2026 23:58
@damaz91
damaz91 requested review from karangoel16 and xiaoxuanz-hub and removed request for knightlin-shopify and mmohades October 12, 2026 07:36
@damaz91 damaz91 added status:under-review and removed status:stale-review Applied if a PR is waiting on a reviewer for too long labels Oct 12, 2026
@damaz91
damaz91 merged commit d9c18e0 into Universal-Commerce-Protocol:main Oct 14, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:shopping Issues and pull requests related to the Shopping vertical documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Example Signed Request in the checkout REST binding omits ucp-agent from its covered components

6 participants