feat(ap2): add experimental AP2 mandate verification

[Revinand]

Summary

Add experimental, opt-in support for AP2 v0.2.0 Direct Checkout Mandate verification on paid resources.

The gateway verifies that a trusted issuer authorized the exact resource, input, price, and payment rail before allowing settlement. Mandates use static operator-configured trust and durable replay
protection. The package also exports a merchant checkout JWT signing helper through the optional ./ap2 entry point.

What changed

• Add generic authorization contracts, requirements, receipt records, events, error codes, and wire carriers without coupling the core pipeline to AP2.
• Add AP2 configuration, disabled by default, with separate trust lists for mandate issuers and merchant checkout issuers.
• Verify closed mandate.checkout.1 SD-JWTs for the AP2 v0.2.0 Direct, Human-Present flow.
• Require ES256 signatures with P-256 keys and reject private or remotely resolved key material.
• Bind each mandate to a merchant-signed checkout JWT covering the resolved resource, validated input, amount, currency, payment method, destination, network, and asset.
• Compute input digests with RFC 8785 JSON Canonicalization Scheme so signers in different languages produce the same binding.
• Add a dedicated SQLite replay store that reserves both the signed mandate and checkout jti, then consumes, releases, or marks the reservation uncertain based on settlement.
• Enforce authorization after payment proof verification and before payment replay reservation and settlement. Payment challenges advertise the authorization requirement before the buyer pays.
• Accept the same { method, payload } envelope through the Agent-Authorization HTTP header and the reserved _authorization field for MCP and A2A.
• Persist only a digest and safe authorization metadata in receipts. Raw mandates, disclosures, checkout JWTs, and authorization headers are not stored or logged.
• Wire AP2 into gateway startup, readiness, configuration validation, and agent-commerce doctor.
• Export createCheckoutJwt from @devlab.group/agent-commerce/ap2 for merchants that need to mint purchase-bound checkout documents.
• Add unit, integration, conformance, and end-to-end coverage for trust validation, purchase binding, replay handling, transport carriers, settlement outcomes, and x402 authorization flows.
• Document the supported profile, trust model, configuration, security properties, failure behavior, and operational limits.

Supported scope

This initial implementation supports:

• AP2 v0.2.0
• Direct, Human-Present mode
• Closed Checkout Mandates with vct: mandate.checkout.1
• SD-JWT mandate presentations
• ES256 signatures over P-256
• Static public keys configured separately for mandate and checkout issuers
• The frozen agent-commerce/ap2/checkout/v1 purchase-binding profile
• Durable single-use enforcement for mandates and checkout documents
• HTTP, MCP, and A2A authorization carriers
• Purchase binding against resolved payment requirements, including x402
• Merchant checkout JWT creation through the optional ./ap2 package entry point

The gateway verifies mandates but does not issue them, act as a full AP2 Merchant, or produce signed Checkout Receipts. It does not implement autonomous mode, open Checkout Mandates, intent or cart
mandates, Payment Mandate verification, spending constraints, key-bound presentations, delegation chains, remote key discovery, remote revocation, algorithms other than ES256, an AP2 transport, or AP2
over the ACP adapter.

Replay protection favors preventing duplicate settlement. If settlement was broadcast but its outcome is unknown, the mandate remains unavailable and is marked uncertain. A process failure between
settlement and the local replay-store update can leave a reservation unusable until an operator resolves it.

Compatibility

AP2 remains disabled unless explicitly enabled. Existing HTTP, MCP, A2A, ACP, and payment configurations continue to work, and resources without an authorization policy follow the existing execution path.

Authorization can only be required on paid resources because it gates settlement rather than access by itself. Configuration and runtime checks reject authorization policies on free resources.

The AP2 implementation and its exact-version peers, jose, @sd-jwt/core, and canonicalize, live behind the optional ./ap2 entry point. Deployments that do not use AP2 do not need to install them.