fix: implement JCS cart-to-payment mandate binding per RFC 8785

[chopmob-cloud]

Summary

Closes the CartMandate ↔ PaymentMandate binding gap raised in #211.

The core problem: without a cryptographic link from CartMandate to PaymentMandate, a malicious or misconfigured agent can substitute a different cart after the user has expressed intent. The fix uses RFC 8785 (JSON Canonicalization Scheme) to produce a deterministic hash that is consistent across Python, Go, and TypeScript implementations.

Spec (docs/ap2/specification.md)

New normative section Cart-to-Payment Mandate Binding under §Payment Mandate with three requirements:

1. PaymentMandateContents MUST include cart_mandate_id and cart_mandate_hash = hex(sha256(JCS(CartMandate))).
2. JCS serialisation MUST exclude null/None optional fields so Python and Go (omitempty) produce identical canonical bytes.
3. Verifiers (CP, Merchant, MPP) MUST recompute the hash and MUST reject on mismatch before releasing credentials or initiating payment.

Types (code/sdk/python/ap2/models/mandate.py)

Added two Optional fields to PaymentMandateContents:

• cart_mandate_id — reference to the bound CartMandate.
• cart_mandate_hash — hex(sha256(JCS(CartMandate))).

Both are Optional for backward compatibility; new mandates SHOULD populate both.

Sample validation (code/samples/python/src/common/validation.py)

New helper module containing:

• validate_payment_mandate_signature() — placeholder for sd-jwt-vc key-binding.
• validate_cart_mandate_hash() — recomputes and compares the JCS hash. Uses model_dump(exclude_none=True) for cross-language consistency (matches Go omitempty); raises ValueError on mismatch; skips with a warning if cart_mandate_hash is absent (backward-compatible rollout).

Dependency (code/samples/python/pyproject.toml)

Added rfc8785>=0.1.2.

---

Note: This replaces the previously closed PR #241. All high-priority Gemini feedback from that review has been incorporated upfront: model_dump(exclude_none=True) for cross-language hash consistency, f-strings throughout, and import path updated from ap2.types.mandate → ap2.models.mandate.

Test plan

• validate_cart_mandate_hash() returns without error when hash matches.
• validate_cart_mandate_hash() raises ValueError when the hash does not match.
• validate_cart_mandate_hash() logs a warning and returns cleanly when cart_mandate_hash is None (backward compat).
• PaymentMandateContents with both new fields round-trips through Pydantic serialisation without error.

[google-cla]

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]

Code Review

This pull request implements the cart-to-payment mandate binding as specified in AP2 section 4.1.3.1. It introduces the rfc8785 dependency, updates the PaymentMandateContents model to include cart_mandate_id and cart_mandate_hash fields, adds validation logic in a new utility module, and updates the specification documentation. I have no feedback to provide.

[chopmob-cloud]

I have read and signed the Google CLA. @googlebot please re-check.

[chopmob-cloud]

Reopening this work as #253 — the branch on this PR was inadvertently broken during a local history-cleanup pass and GitHub auto-closed it. The replacement carries the identical code, cherry-picked clean onto current main. Apologies for the noise.