Imported from ar-agents/ar-agents (packages/ap2/AGENTS.md). Install upstream with npx skills add ar-agents/ar-agents --skill ap2. Copyright stays with the author.

AGENTS.md — @ar-agents/ap2

This file is for AI agents and code-generation tools integrating @ar-agents/ap2 at runtime or build time. Conforms to the agents.md convention.

What this package does

@ar-agents/ap2 is the first faithful TypeScript implementation of the Agent Payments Protocol (AP2) v0.2. It implements:

• The four mandate types (Open + Closed × Checkout + Payment) as Zod schemas
• All ten constraint types with deterministic evaluators (max-flow for checkout.line_items)
• ES256 (P-256 ECDSA) sign/verify on top of jose
• SD-JWT VC primitives (RFC 9901): disclosures, _sd digests, sd_hash, compact serialization parser, KB-JWT build/verify
• The inner checkout_jwt with rainbow-table-defense (Ed25519 forbidden)
• Issuer factories + verifiers for each mandate type
• CheckoutReceipt + PaymentReceipt build/verify (plain JWTs)

When to use

• A merchant facilitator needs to verify an AP2 Closed Checkout Mandate before completing a checkout. Use verifyClosedCheckoutMandate with the agent's public JWK as issuerKey and the merchant's own public JWK as checkoutJwtKey.
• A Credential Provider / MPP / network needs to verify an AP2 Closed Payment Mandate before authorizing a payment. Use verifyClosedPaymentMandate with expectedTransactionId set to the linked Closed Checkout Mandate's checkout_hash.
• An agent or Trusted Surface needs to issue mandates for direct flows. Use issueOpenCheckoutMandate / issueClosedCheckoutMandate / issueOpenPaymentMandate / issueClosedPaymentMandate.
• Anyone needs to issue or verify a CheckoutReceipt / PaymentReceipt after a successful (or failed) completion. The receipt's reference field is the sd_hash of the closed mandate it confirms — always pass the value returned in verificationOutcome.sdHash.

When NOT to use

• The host needs multi-hop delegated chains (Trusted Agent Provider model with ~~-separated SD-JWT presentations + per-hop cnf.jwk PoP binding). Wait for Phase 2.2.
• The host needs the inner checkout_jwt to use Ed25519 — it cannot, per spec. ES256 is the canonical choice. ES384, ES512, and RS256 are also accepted (all are non-deterministic).
• The host wants stateful budget tracking for payment.budget / payment.agent_recurrence. Phase 2.1 ships the interface but the default in-memory tracker lands in Phase 2.2.

Tool selection guidance

When wiring AP2 into a host that already uses @ar-agents/*:

host
 ├── @ar-agents/ap2                    ← THIS package
 ├── @ar-agents/agentic-commerce-bridge ← ACP merchant facilitator (optional)
 ├── @ar-agents/mercadopago            ← MP toolkit (issues PaymentReceipts)
 ├── @ar-agents/identity               ← CUIT + ARCA padrón (AR fiscal context)
 └── @ar-agents/facturacion            ← AFIP factura electronica (post-receipt)

The recommended pattern for an Argentine-fiscal-compliant AP2 merchant:

1. Verify the AP2 Closed Checkout Mandate via this package.
2. Bridge converts the verified payload into ACP CheckoutSession shape.
3. On complete, the bridge's onOrderConfirmed hook (powered by @ar-agents/facturacion) issues a Factura A/B/C/E.
4. After successful payment, this package builds the PaymentReceipt with reference = sdHash of the closed Payment Mandate. Optionally include the AFIP CAE in psp_confirmation_id for evidentiary use in future disputes.

Result schemas worth memorizing

Verification outcome

Every verify* function returns this shape:

type VerificationOutcome<T> =
  | { ok: true; mandate: T; sdHash: string }
  | {
      ok: false;
      code: "invalid_credential" | "invalid_mandate" | "unresolved_constraint" | "mandates_not_supported";
      reason: string;
    };

The sdHash is what you put in the receipt's reference. The code maps directly to AP2's canonical error codes per spec §G.

Mandate vct strings (exact-match)

Don't invent your own — match these character-for-character:

• mandate.checkout.open.1
• mandate.checkout.1
• mandate.payment.open.1
• mandate.payment.1

If a future v0.3 introduces mandate.checkout.2, treat it as a different schema (downgrade-attack defense).

transaction_id ↔ checkout_hash rule

The Closed Payment Mandate's transaction_id MUST equal the Closed Checkout Mandate's checkout_hash. The verifier checks this via expectedTransactionId. You — the host — must pass it. It's how AP2 binds payments to checkouts.

Latency expectations

Constraints

• checkout_jwt MUST use ECDSA. Passing alg: "EdDSA" to signCheckoutJwt throws CheckoutJwtAlgError. Default is ES256.
• exp is RECOMMENDED for autonomous flows — set iat + (minutes the agent needs to complete the task) and let the default 30s clock tolerance handle drift.
• Always supply nonce + audience for KB-JWTs. The verifier checks exact equality. Don't reuse nonces across requests.
• generateSalt() returns >=16 bytes of base64url entropy. Don't use a deterministic salt — it defeats RFC 9901's selective-disclosure privacy goal.
• _sd_alg is sha-256 in v0.1. sha-384 / sha-512 ship in Phase 2.2.

Side effects

This package is pure crypto. There are NO network calls. NO state persistence. The BudgetTracker interface IS stateful but the v0.1 default is a no-op pass-through.

Reasoning hints for agents writing host code

• Use generateAp2KeyPair("ES256") once at app startup. Persist private keys via your secret manager (Vercel KMS, AWS KMS, etc.). The public JWK is what you publish at your JWKS endpoint or pass as cnf.jwk.
• For CRITICAL paths (real money), wire clockTolerance: 0 in production to reject any future-iat / past-exp mandates.
• For receipt-signing keys, rotate every 90 days per CSA STRIDE recommendations (docs/ap2/security_and_privacy_considerations.md).
• The sdHash returned by verifyClosedCheckoutMandate is the canonical receipt-reference. Compute it once, store it, link your DB row to it.
• When integrating with @ar-agents/agentic-commerce-bridge, expose mandate.checkout.1 via a custom payment_data.instrument.credential with type: "ap2_mandate" and the closed mandate's compact SD-JWT presentation as token. Phase 2.2 will ship a built-in createAp2PaymentProvider for this; for now wire it manually.

See also

• README.md — full quickstart + spec deviations
• CHANGELOG.md — Phase 2.1 → 2.2 → 2.3 roadmap
• AP2 spec (Google + FIDO)
• agents.md convention