fix: align mandate types with spec for HNP security

[gautammanak1]

• Add IntentMandate id, user_authorization, and Pydantic validation for unsigned vs cart-confirmation rules
• Add PaymentMandateContents intent_mandate_id, TransactionModality enum, and HNP validation requiring intent reference
• Bind payment signing to intent mandate hash when present; populate modality and intent_mandate_id from shopping agent state
• Sync Go sample structs; clarify Cart Mandate dual-signature wording in specification; fix IntentMandate JSON example in a2a-extension

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
• Ensure the tests and linter pass
• Appropriate docs were updated (if necessary)

Fixes 150🦕

[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 introduces support for 'Human Not Present' (HNP) transaction flows by updating mandate specifications and sample implementations. Key changes include adding unique identifiers and user authorization fields to IntentMandate, introducing a TransactionModality enum, and ensuring payment mandates are cryptographically bound to pre-authorized intent mandates. Feedback focuses on refining the logic for including intent hashes in signatures, improving consistency in placeholder hash generation, and correcting multiline string formatting in Pydantic models.

[gautammanak1]

Hello @holtskinner @jorellis

I’m Gautam Manak (@gautammanak1). This contribution aligns the AP2 reference implementation with the specification for mandate security, with a focus on Human Not Present (HNP) flows.

What problem this addresses
The specification describes Intent Mandates as user-signed where HNP applies, and Payment Mandates as bound to both Cart and Intent so the payments ecosystem can reason over agentic, HNP transactions. The codebase did not fully reflect that: key fields and binding logic were missing or incomplete, which could mislead anyone using this repo as the source of truth.

What I changed

IntentMandate: Added a stable id, optional user_authorization (JWT in real deployments; a dev placeholder in samples), and Pydantic validation so an unsigned intent cannot be combined with “no per-cart confirmation” in an invalid way.
PaymentMandateContents: Added intent_mandate_id and TransactionModality (human_present / human_not_present), with validation so human_not_present requires an intent_mandate_id.
Shopping agent sample: When an intent is present and user-signed, the payment mandate carries the right modality and intent reference; sign_mandates_on_user_device only appends an intent mandate hash when intent_mandate.user_authorization is set, and the placeholder hash uses intent_mandate.id for consistency with the other fake hashes.
Go sample types, documentation (clearer Cart Mandate signing story), spellcheck / markdown hygiene, and CI: pointed super-linter at the repo’s real markdownlint config so Lint Code Base matches the project’s intended rules.
How it behaves

Human-present flows: signing is driven by cart + payment hashes; an unsigned intent in state does not add an intent hash to the authorization string.
HNP with a signed intent: the payment side can reference the intent (intent_mandate_id, human_not_present), and the user authorization string includes the intent binding only when the intent is actually signed, matching the spec’s security story.

Thank you to the Google team and AP2 maintainers for maintaining this project and for reviewing this change.

Best regards,
Gautam