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.

Note: This replaces the previously closed PR #251. The branch on #251 was inadvertently broken during a local history-cleanup pass (the force-push lost the shared ancestor with upstream/main, so GitHub auto-closed the PR). The code below is identical to what #251 carried — three commits cherry-picked clean onto the current upstream/main tip. All Gemini high-priority feedback from the earlier closed PR #241 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.

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.

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.

[gemini-code-assist]

Code Review

This pull request implements a cart-to-payment mandate binding mechanism to ensure the integrity of the payment process by linking a PaymentMandate to a specific CartMandate. Key changes include the addition of cart_mandate_id and cart_mandate_hash fields to the PaymentMandateContents model, the introduction of a validation module using RFC 8785 (JCS) for canonicalization and SHA-256 for hashing, and updates to the AP2 specification documentation. I have no feedback to provide.

[chopmob-cloud]

Thanks @gemini-code-assist. Noted that the automated review found no issues. Flagging for @GarethCOliver or any AP2 maintainer when you have a cycle -- this is the cart-integrity binding gap from #211 and is independently useful alongside the Biome lint fix in #249.

[gemini-code-assist]

Thanks for the update, @chopmob-cloud. I've reviewed the implementation of the cart-to-payment mandate binding. The use of RFC 8785 for canonicalization is the correct approach to ensure cross-language consistency, and the model_dump(exclude_none=True) approach effectively aligns with Go's omitempty behavior. The documentation updates and the validation helper in code/samples/python/src/common/validation.py are clear and correctly implement the requirements specified in the PR description. This looks solid.