Skip to content

test(payments): add AP2 order receipt conformance vectors - #136

Draft
ynachiket wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
ynachiket:feat/ap2-receipt-vectors-1063
Draft

ynachiket wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
ynachiket:feat/ap2-receipt-vectors-1063

Conversation

@ynachiket

Copy link
Copy Markdown

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 small
platform-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 the
    Platform Verification rules in #1109. Each check cites its section. It
    reports three separate groups:
    • outcomes: the MUSTs (signature and kid in the keys of iss;
      iss/mandate binding; seq/prev continuity and both total invariants
      per (iss, mandate_ref) chain);
    • warnings: the per-seller SHOULD, receipt_exceeds_seller_total;
    • reconciliation: reconciliation_adjustment_mismatch, which leaves the
      receipt valid.
  • common/payments/fixtures/ap2_order_receipts/: 18 JSON fixtures. Each holds
    the Order (only the members verification reads) with its compact JWS
    receipts in ap2.receipts, the business keys, the Payment Mandates the
    platform 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 that
    the committed fixtures match the generator byte for byte, checks that vectors
    1–12 and every receipt_verification_outcome value are covered, and
    rejects 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 keys at
    /.well-known/ucp. A second test ships the order and checks that earlier
    receipts are kept and the extended chain still verifies. Both skip unless the
    business advertises dev.ucp.common.payment.ap2_mandate with
    order_receipts in its config. The test serves a platform profile that
    declares order_receipts too, because receipts are only required when both
    sides declare it.
  • cryptography>=44.0.0 as a dependency (ES256 verification; RFC 6979
    deterministic signing for the generator).

Vectors

Indexes are positions in ap2.receipts.

Fixture #1063 test plan Rule (#1109) Expected
v01_single_capture 1 Platform Verification 1–2 valid
v02_split_captures 2 Platform Verification 1–2, Split shipments valid
v03_capture_exceeds_mandate 3 Platform Verification 2, Business Requirements 3 receipt_exceeds_mandate @1
v04_increase_second_mandate 4 Business Requirements 3 (new mandate, own chain) valid
v05_tampered_amount 5 Platform Verification 1 receipt_invalid_signature @2
v06_missing_seq 6 Platform Verification 2 receipt_sequence_gap @1
v07_refund_exceeds_capture 7 Platform Verification 2 receipt_refund_exceeds_capture @2
v08_rotated_retained_key 8 Business Requirements 6 valid
v08_key_not_retained (8, negative) Platform Verification 1 receipt_invalid_signature @0, receipt_sequence_gap @1
v09_two_sellers 9 Platform Verification 3, Marketplace as merchant of record valid
v09_duplicate_seller_capture 9 Platform Verification 3 warning receipt_exceeds_seller_total @2
v09_seller_refund_exceeds_captures (9, refund half) Platform Verification 3 warning receipt_exceeds_seller_total @2
v10_two_merchants_of_record 10 Several merchants of record valid
v10_iss_mismatch 10 Platform Verification 1 receipt_mandate_unknown @4
v11_lodging_partial_refund 11 Platform Verification 4, Partial refunds valid, reconciles
v12_lodging_refund_mismatch 12 Platform Verification 4 valid; reconciliation reconciliation_adjustment_mismatch @2
refund_delayed_network_ref – Pending movements, Late network references valid; refunded changes only on the succeeded receipt, which carries network_ref
refund_reversal_no_network_ref – Pending movements, Late network references valid; the succeeded receipt has no network_ref

Signing:

  • v02, v05 and v06 use the real ES256 chain from the #1109 Order
    example, byte for byte. They verify with the example key in the #1109
    description. v05 changes one amount after signing, and v06 drops seq 2.
    Vector 1 is a single capture of the full mandate, which that chain doesn't
    contain (it has two split captures), so v01 is signed with a test key.
  • All other receipts are signed with TEST-ONLY P-256 keys derived from fixed
    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.ref with no network reference) mirrors how card
processors report a refund that settles as a reversal.

How to run

uv sync
# Vectors only; no server needed
uv run pytest common/payments/ap2_receipt_vectors_test.py
# Everything, against a server
uv run ucp-conformance --server_url=... --suite=common

To regenerate the fixtures, or check that they are current (the output is
deterministic):

uv run python -m common.payments.ap2_receipt_fixtures
uv run python -m common.payments.ap2_receipt_fixtures --check

Verification

  • 63 new vector tests pass without a server. Against the Python sample server
    the full suite runs 148 tests: 144 pass and 4 skip, 0 failures. On main it
    is 83 run, 81 pass and 2 skip. The two new server tests skip because the
    sample server does not advertise AP2.
  • The server tests were also run against a local, uncommitted patch of the
    sample server that issues receipts. Both pass for valid receipts. Each of
    these makes them fail: a tampered amount, a withheld seq 1, a wrong iss,
    and a pending receipt that changes totals.
  • ruff check, ruff format --check, prettier, codespell and cspell pass on
    the changed files. Generated fixtures are added to cspell's ignorePaths
    (base64), and SECP and unpadded are added to the word list.

Notes

  • Depends on ucp#1109 and should land after it. If #1109's names change, the
    fixtures are regenerated from the generator.
  • Vectors 9–10 use #1018's line_items[].seller_id, seller_id and
    sellers. #1018 is still open. Following #1018, a seller_id that does not
    resolve in sellers is not checked per seller.
  • Fixture Orders carry only the members verification reads (no item,
    quantity, fulfillment and so on), so they are not complete Orders.
  • Only REST is covered; the test plan also names MCP. Receipts on order
    webhooks are not checked yet.
  • Where #1109 leaves a choice open, the verifier's choice is stated in its
    docstrings: an unresolvable kid is receipt_invalid_signature; a receipt
    that fails signature or mandate binding is left out of its chain; refunds
    reconcile against the magnitude of the adjustment's total; both total
    invariants are evaluated on the totals each receipt states. A signed receipt
    that is not a Receipt Payload is listed separately (malformed), since no
    outcome covers it.

Thanks to @parag2507 for the proposal, the signed example chain and vectors
1–8, to @Flyingmiata-droid for network_ref and the reversal case, and to
@ericestegassy-code for the lodging vectors 11–12.

Type of change

  • New feature (non-breaking change which adds functionality)

Is this a Breaking Change or Removal?

No. Nothing is removed; the change adds tests, fixtures and one dependency.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules (ucp#1109 is open)

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
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