docs: add production payment binding guidance#107
Conversation
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the project documentation to point to version 0.2 of the x402 extension specification and introduces a new section on production payment binding requirements. These requirements define mandatory behaviors for task binding, atomic payment claims, settlement finality, receipt history, and secure HTTP transport handling. The review feedback suggests clarifying the comparison target for the resource field and explicitly using the term idempotency to improve the technical clarity of the specification.
|
|
||
| Implementations that grant paid service results, mutate account state, or trigger downstream commerce workflows MUST bind payment verification to the exact task and paid resource being fulfilled: | ||
|
|
||
| * **Task and requirement binding**: Merchant Agents MUST validate that the submitted `PaymentPayload` matches a `PaymentRequirements` option that was previously issued for the same `taskId`. If the accepted requirements include a `resource` field, the Merchant Agent MUST compare it exactly before settlement. If the flow is embedded in a higher-level protocol, the implementation MUST also verify that the enclosing order or mandate identity matches the task being fulfilled. |
There was a problem hiding this comment.
The requirement to "compare it exactly" is slightly ambiguous. It should specify what the resource field is being compared against (e.g., the identifier of the resource the client is attempting to access). Consider clarifying this to ensure developers understand the binding target.
Suggested change:
- Task and requirement binding: Merchant Agents MUST validate that the submitted
PaymentPayloadmatches aPaymentRequirementsoption that was previously issued for the sametaskId. If the accepted requirements include aresourcefield, the Merchant Agent MUST compare it exactly against the resource identifier being fulfilled before settlement. If the flow is embedded in a higher-level protocol, the implementation MUST also verify that the enclosing order or mandate identity matches the task being fulfilled.
| Implementations that grant paid service results, mutate account state, or trigger downstream commerce workflows MUST bind payment verification to the exact task and paid resource being fulfilled: | ||
|
|
||
| * **Task and requirement binding**: Merchant Agents MUST validate that the submitted `PaymentPayload` matches a `PaymentRequirements` option that was previously issued for the same `taskId`. If the accepted requirements include a `resource` field, the Merchant Agent MUST compare it exactly before settlement. If the flow is embedded in a higher-level protocol, the implementation MUST also verify that the enclosing order or mandate identity matches the task being fulfilled. | ||
| * **Atomic claim before grant**: Merchant Agents MUST atomically record the accepted payment claim, such as the nonce, transaction authorization, or scheme-specific payment identifier, before returning paid artifacts or performing paid side effects. Duplicate submissions for an already claimed payment MUST NOT produce another paid result; implementations SHOULD return the existing receipt or fail with `DUPLICATE_NONCE`. |
There was a problem hiding this comment.
This section describes idempotency. Explicitly mentioning that the implementation should be idempotent for a given payment claim would improve clarity for developers familiar with this pattern.
Suggested change:
- Atomic claim before grant: Merchant Agents MUST atomically record the accepted payment claim, such as the nonce, transaction authorization, or scheme-specific payment identifier, before returning paid artifacts or performing paid side effects. To ensure idempotency, duplicate submissions for an already claimed payment MUST NOT produce another paid result; implementations SHOULD return the existing receipt or fail with
DUPLICATE_NONCE.
|
Addressed the review suggestions in 5587b6f: clarified what the resource field is compared against and made the duplicate-claim requirement explicitly idempotent. passes locally. |
1 participant
Description
Adds production security guidance to the v0.2 x402 A2A spec for payment-to-task/resource binding, atomic claim-before-grant behavior, settlement finality, receipt history, scheme field checks, and HTTP cache/header handling.
Also updates the root README to point new readers at
spec/v0.2/spec.mdas the current specification.CONTRIBUTINGGuide.git diff --check.Fixes #<issue_number_goes_here>