a2a/x402: add AP2 mandate foundation for agent payments

[asim]

Goal
Add an opt-in AP2 mandate foundation so agents can carry auditable payment authorization over A2A and settle over x402 without changing defaults.

Scope

• Define minimal Checkout Mandate and Payment Mandate data structures with signing/verification helpers.
• Attach verified mandate metadata to A2A/x402 payment flows behind explicit options.
• Preserve current public defaults and avoid broad API breakage.
• Include docs/example notes only where needed to make the flow discoverable.

Acceptance criteria

• Unit tests cover mandate creation, signing, verification failure, and x402 rail metadata.
• A focused integration or gateway test shows an A2A request carrying mandate metadata into a paid-tool path.
• go test ./... passes.

[AmitabhainArunachala]

Reviewed the existing ap2.go foundation — the Ed25519 signed mandate + task/context binding + x402 rail reference is a clean primitive. The VerifyAP2ForTask check covering signature, task binding, and rail reference hits the core cases.

A few gaps worth considering for the mandate verification surface, based on what we've seen running a live mandate verification endpoint (POST /mandate/verify, USDC on Base, x402):

1. Expiry / replay window
The current AP2Mandate has IssuedAt but no ExpiresAt. A signed mandate with no expiry is replayable indefinitely — the verifier has no grounds to reject a stale credential. Even an optional ExpiresAt *time.Time field (checked in VerifyAP2ForTask when non-nil) would close this without breaking defaults.

2. Nonce / one-time-use enforcement
No Nonce field. For payment mandates specifically, the same signed mandate could authorize multiple settlements on the same rail. A Nonce string + a caller-provided seen-nonce set (similar to how you'd handle DPoP jti) would let the gateway reject replays without baking in a store implementation. The function signature could take an optional seenNonces map[string]bool.

3. Spend cap vs. actual amount
Amount is a string with no explicit relationship to what the x402 challenge actually charges. A payment mandate for "10.00" USD doesn't prevent a 402 challenge for $100.00 from settling under it. A MaxAmount string field (or checking Amount >= challenge.price at settlement time) would enforce the cap.

4. Resource binding
The mandate binds to TaskID and ContextID but not to a specific paid resource (endpoint URL or route). Two different paid tools in the same task context could both settle under one mandate. An optional Resource string (resource URL or route key) checked against the actual x402 challenge's resource field would close this.

5. Receipt obligation
No flag for whether the mandate requires a settlement receipt to be produced and verified before the task is marked complete. A ReceiptRequired bool on the payment mandate would let the gateway hold task completion until a valid x402 receipt is attached.

These are all additive — each can be an optional field with nil-checks in the verifier, preserving the current defaults. Happy to run any signed AP2Mandate JSON through our live /mandate/verify endpoint (22-check matrix across authority, scope, spend cap, recipient, expiry, nonce, resource binding, and receipt obligations) and post the full verdict here. One mandate JSON is all I need.

Endpoint: POST /mandate/verify at https://x402.167-172-95-184.nip.io ($0.25/call, USDC on Base via x402) — but the first one is free if you paste the JSON inline.