Repository navigation
Conversation
Add platform-side conformance vectors for signed, mandate-bound AP2 Order receipts (ucp#1063, spec in ucp#1109 at 1d19291d): - ap2_receipt_verifier.py: verifier for the Order Receipts Platform Verification rules, reporting MUST outcomes, the per-seller SHOULD (receipt_exceeds_seller_total) as warnings, and adjustment reconciliation (reconciliation_adjustment_mismatch) separately. - fixtures/ap2_order_receipts/: 18 fixtures covering test-plan vectors 1-12, a pending refund that succeeds with a late network_ref, and a refund settled as a reversal without one. v02, v05 and v06 reuse the signed ucp#1109 Order example byte for byte. - ap2_receipt_fixtures.py: deterministic generator (TEST-ONLY keys, RFC 6979 ECDSA); the tests check the fixtures match it. - ap2_receipt_vectors_test.py: runs every vector, plus mutation tests. - ap2_order_receipts_test.py: verifies receipts a live business issues; skips unless it declares order_receipts. Adds cryptography as a dependency. Refs: Universal-Commerce-Protocol/ucp#1063
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Conformance checks for signed, mandate-bound AP2 Order receipts, the companion
to Universal-Commerce-Protocol/ucp#1109 (refs Universal-Commerce-Protocol/ucp#1063).
Field names, statuses and outcome codes are the ones in #1109 at
1d19291d.Opened as a draft while the open points in my review of #1109 (Universal-Commerce-Protocol/ucp#1109 (review)) are settled. I'll update the vectors to whatever wording lands there and mark this ready.
As agreed on #1063, the fixed vectors live in
common/payments/with a smallplatform-side verifier, plus a server test that the receipts a live business
issues verify.
What it adds
common/payments/ap2_receipt_verifier.py: a platform-side verifier for thePlatform Verification rules in #1109. Each check cites its section. It
reports three separate groups:
kidin thekeysofiss;iss/mandate binding;seq/prevcontinuity and both total invariantsper
(iss, mandate_ref)chain);receipt_exceeds_seller_total;reconciliation_adjustment_mismatch, which leaves thereceipt valid.
common/payments/fixtures/ap2_order_receipts/: 18 JSON fixtures. Each holdsthe Order (only the members verification reads) with its compact JWS
receipts in
ap2.receipts, the businesskeys, the Payment Mandates theplatform sent, a decoded copy of every receipt, the spec rules it exercises,
and the exact expected findings.
common/payments/ap2_receipt_fixtures.py: the generator for those fixtures.common/payments/ap2_receipt_vectors_test.py: runs every vector, checks thatthe committed fixtures match the generator byte for byte, checks that vectors
1–12 and every
receipt_verification_outcomevalue are covered, andrejects mutations of the #1109 chain (flipped bytes, reordered or repeated
receipts, unknown key, unknown mandate, mandate for another business, malformed
payload).
common/payments/ap2_order_receipts_test.py: completes an AP2 checkout,reads the Order and verifies its receipts against the
keysat/.well-known/ucp. A second test ships the order and checks that earlierreceipts are kept and the extended chain still verifies. Both skip unless the
business advertises
dev.ucp.common.payment.ap2_mandatewithorder_receiptsin its config. The test serves a platform profile thatdeclares
order_receiptstoo, because receipts are only required when bothsides declare it.
cryptography>=44.0.0as a dependency (ES256 verification; RFC 6979deterministic signing for the generator).
Vectors
Indexes are positions in
ap2.receipts.v01_single_capturev02_split_capturesv03_capture_exceeds_mandatereceipt_exceeds_mandate@1v04_increase_second_mandatev05_tampered_amountreceipt_invalid_signature@2v06_missing_seqreceipt_sequence_gap@1v07_refund_exceeds_capturereceipt_refund_exceeds_capture@2v08_rotated_retained_keyv08_key_not_retainedreceipt_invalid_signature@0,receipt_sequence_gap@1v09_two_sellersv09_duplicate_seller_capturereceipt_exceeds_seller_total@2v09_seller_refund_exceeds_capturesreceipt_exceeds_seller_total@2v10_two_merchants_of_recordv10_iss_mismatchreceipt_mandate_unknown@4v11_lodging_partial_refundv12_lodging_refund_mismatchreconciliation_adjustment_mismatch@2refund_delayed_network_refrefundedchanges only on the succeeded receipt, which carriesnetwork_refrefund_reversal_no_network_refnetwork_refSigning:
v02,v05andv06use the real ES256 chain from the #1109 Orderexample, byte for byte. They verify with the example key in the #1109
description.
v05changes one amount after signing, andv06dropsseq2.Vector 1 is a single capture of the full mandate, which that chain doesn't
contain (it has two split captures), so
v01is signed with a test key.labels in the generator. They are public by construction and labelled as
such in every fixture.
The reversal vector is processor-neutral. Its shape (pending, then succeeded
for the same
event.refwith no network reference) mirrors how cardprocessors report a refund that settles as a reversal.
How to run
To regenerate the fixtures, or check that they are current (the output is
deterministic):
Verification
the full suite runs 148 tests: 144 pass and 4 skip, 0 failures. On
mainitis 83 run, 81 pass and 2 skip. The two new server tests skip because the
sample server does not advertise AP2.
sample server that issues receipts. Both pass for valid receipts. Each of
these makes them fail: a tampered amount, a withheld
seq1, a wrongiss,and a
pendingreceipt that changes totals.ruff check,ruff format --check, prettier, codespell and cspell pass onthe changed files. Generated fixtures are added to cspell's
ignorePaths(base64), and
SECPandunpaddedare added to the word list.Notes
fixtures are regenerated from the generator.
line_items[].seller_id,seller_idandsellers. #1018 is still open. Following #1018, aseller_idthat does notresolve in
sellersis not checked per seller.item,quantity,fulfillmentand so on), so they are not complete Orders.webhooks are not checked yet.
docstrings: an unresolvable
kidisreceipt_invalid_signature; a receiptthat fails signature or mandate binding is left out of its chain; refunds
reconcile against the magnitude of the adjustment's
total; both totalinvariants are evaluated on the totals each receipt states. A signed receipt
that is not a Receipt Payload is listed separately (
malformed), since nooutcome covers it.
Thanks to @parag2507 for the proposal, the signed example chain and vectors
1–8, to @Flyingmiata-droid for
network_refand the reversal case, and to@ericestegassy-code for the lodging vectors 11–12.
Type of change
Is this a Breaking Change or Removal?
No. Nothing is removed; the change adds tests, fixtures and one dependency.
Checklist