Skip to content

docs: add normative verifier obligation for checkout_hash#243

Open
chopmob-cloud wants to merge 8 commits intogoogle-agentic-commerce:mainfrom
chopmob-cloud:docs/verifier-checkout-hash-obligation
Open

docs: add normative verifier obligation for checkout_hash#243
chopmob-cloud wants to merge 8 commits intogoogle-agentic-commerce:mainfrom
chopmob-cloud:docs/verifier-checkout-hash-obligation

Conversation

@chopmob-cloud
Copy link
Copy Markdown

Summary

The checkout_hash field definition in checkout_mandate.md specifies what
the field IS (base64url SHA-256 of checkout_jwt) but contains no normative
obligation telling verifiers they MUST check it.

This adds a MUST/MUST NOT gate immediately after the field description:

Before releasing credentials or initiating payment, the Credential Provider,
Merchant, and Merchant Payment Processor each MUST independently recompute
checkout_hash by applying the _sd_alg algorithm (or sha-256 if absent)
to the raw bytes of the checkout_jwt value and comparing the result to the
checkout_hash field. If the values do not match, the verifier MUST reject
the mandate and MUST NOT proceed with the transaction.

Motivation

Without this text, a conformant implementation can accept a Checkout Mandate
where checkout_jwt has been substituted (e.g. amount altered) while
checkout_hash still matches the original. The field provides no security
guarantee until checking it is normatively required.

This follows the pattern already established in the payment.reference
constraint evaluation ("MUST contain an open Checkout Mandate with a matching
hash") — the same MUST language applied to the Checkout Mandate's internal
integrity gate.

Related: issue #211 (cart-to-payment binding discussion).

Verifiers (Credential Provider, Merchant, MPP) are required to
recompute checkout_hash from the raw checkout_jwt bytes and reject
the mandate on mismatch. This obligation was implicit in the field
definition but absent as normative MUST text, leaving implementations
free to skip the integrity check before releasing credentials or
initiating payment.
@chopmob-cloud chopmob-cloud requested a review from a team as a code owner April 29, 2026 16:22
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation for the Checkout Mandate to include a mandatory verification step for the checkout_hash. The reviewer suggested rephrasing the new requirement for improved readability and clarity, which has been accepted as a valid improvement opportunity.

Comment thread docs/ap2/checkout_mandate.md Outdated
Comment on lines +30 to +35
Before releasing credentials or initiating payment, the Credential Provider,
Merchant, and Merchant Payment Processor each MUST independently recompute
`checkout_hash` by applying the `_sd_alg` algorithm (or `sha-256` if absent)
to the raw bytes of the `checkout_jwt` value and comparing the result to the
`checkout_hash` field. If the values do not match, the verifier MUST reject
the mandate and MUST NOT proceed with the transaction.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

For improved readability, consider rephrasing this paragraph to more clearly separate the primary requirement from the implementation details. Breaking the first long sentence into two can make the instruction easier to parse.

Suggested change
Before releasing credentials or initiating payment, the Credential Provider,
Merchant, and Merchant Payment Processor each MUST independently recompute
`checkout_hash` by applying the `_sd_alg` algorithm (or `sha-256` if absent)
to the raw bytes of the `checkout_jwt` value and comparing the result to the
`checkout_hash` field. If the values do not match, the verifier MUST reject
the mandate and MUST NOT proceed with the transaction.
Before releasing credentials or initiating payment, the Credential Provider,
Merchant, and Merchant Payment Processor each MUST verify that the `checkout_hash`
field's value matches a computed hash of the `checkout_jwt` value. The hash
MUST be computed by applying the `_sd_alg` algorithm (or `sha-256` if absent)
to the raw bytes of the `checkout_jwt` value. If the values do not match, the
verifier MUST reject the mandate and MUST NOT proceed with the transaction.

MD030: normalize list-marker spacing (-   -> -)
MD036: replace bold-as-heading with proper ##### heading
MD031: add blank lines around fenced code blocks
MD007/MD032: remove indentation from inline example lists and add
  surrounding blank lines
MD040: add 'text' language tag to encoded-token code blocks
MD012: remove consecutive blank lines
MD026: remove trailing period from section heading
spellcheck: disable cspell around base64-encoded token examples
Replace three scattered inline cspell:disable comments with one
block wrapping the entire Examples section, which contains all
base64 nonces, encoded tokens, and example product identifiers
that the spellchecker flags.
MD001: downgrade Example headings from h5 to h4 to maintain
  heading-level increments under h3 section headings
MD030: normalize ordered list marker spacing (1.  -> 1.)
gitleaks: add .gitleaks.toml allowlist for docs/ to suppress
  false positives on example SD-JWT tokens
…ath)

Super-linter reads gitleaks config from .github/linters/.gitleaks.toml,
not the repo root. Move the allowlist there so example SD-JWT tokens
in docs/ are correctly suppressed.
Split the single long sentence into two shorter sentences to more
clearly separate the primary requirement (verify the hash matches)
from the implementation detail (how to compute the hash).

Addresses Gemini code-review feedback on PR google-agentic-commerce#243.
@chopmob-cloud
Copy link
Copy Markdown
Author

Thanks for the suggestion @gemini-code-assist — applied in the latest commit. The paragraph now opens with the primary obligation ("verify that the checkout_hash field's value matches a computed hash") before introducing the implementation detail (how to compute the hash), which makes the intent clear on first read.

@gemini-code-assist
Copy link
Copy Markdown
Contributor

That sounds great. Thank you for confirming the update, and I'm glad the phrasing now clearly emphasizes the normative obligation for verifiers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant