AP2 Rust Reference Implementation

Production-shape Rust reference implementation of the Agent Payments Protocol. The workspace ships v0.1-alpha and v0.2 mandate types, RFC 8785 canonical JSON, JOSE primitives (Ed25519 + ES256), full SD-JWT / KB-JWT / dSD-JWT chain support, the AP2 constraint engine, A2A wire helpers, reference role implementations (shopping agent, merchant, credentials provider, MPP), a cargo install-able CLI, and deterministic end-to-end demo scenarios that round-trip byte-identical against the upstream Python whitepaper fixtures.

⚠️ Non-production: cryptographic implementations are vetted-dependency wrappers; the library has not undergone external audit. Use in production only after independent review. (Spec §8.)

Install

# Library crates — pick the layer you need.
cargo add ap2-types ap2-mandate ap2-sd-jwt ap2-a2a ap2-crypto ap2-canonical
cargo add ap2-actors --features shopping,merchant,credentials,mpp

# Binary CLI.
cargo install ap2-cli

MSRV is Rust 1.94.0, pinned in rust-toolchain.toml.

Quickstart

Shell — verify a chain via the CLI

cargo install ap2-cli
ap2 verify \
  --token "$(cat fixtures/scenarios/human-not-present/checkout_mandate_sd_jwt.json | jq -r .token)" \
  --jwks  fixtures/keys/jwks.json

Rust — canonicalize and hash an AP2 payload

use ap2_canonical::{canonical_json, sha256_b64url};
use serde_json::json;

let payload = json!({"vct": "mandate.checkout.1", "checkout_hash": "abc"});
let bytes = canonical_json(&payload).unwrap();
let digest = sha256_b64url(&bytes);
assert_eq!(digest.len(), 43); // 32-byte SHA-256 → 43-char base64url (no padding).

The full SD-JWT chain walkthrough (issue → present → verify → emit receipt) lives in docs/examples/human-not-present.md, backed by examples/verify_chain.rs.

Feature matrix

Capability	v0.1-alpha	v0.2	Status
Mandate types (Intent / Cart / Payment / Receipt)	✓	✓	Implemented
Canonical JSON (RFC 8785 JCS)	✓	✓	Implemented
JOSE / JWS / JWK (Ed25519, ES256)	✓	✓	Implemented
SD-JWT VC issuance	—	✓	Implemented
Key-Binding JWT (KB-JWT)	—	✓	Implemented
dSD-JWT delegation chain verification	—	✓	Implemented
Constraint engine: line items, amount range, allowed merchants	—	✓	Implemented
Constraint engine: agent recurrence, budgets, payment reference	—	✓	Implemented
A2A v1 helpers (current + legacy URIs)	✓	✓	Implemented
Reference role actors	✓	✓	Implemented
ap2-cli (validate, hash, sign, verify, chain, demo, keys)	✓	✓	Implemented
Deterministic HP / HNP demo scenarios	✓	✓	Implemented
Hash agility: _sd_alg honored at parse time	—	✓	Implemented
OKP JWK SD-JWT issuance (Ed25519 user keys for SD-JWT)	—	—	Planned (v0.2.0)
MCP server integration for mandate inspection	—	—	Planned (v0.2.0)
Visa payment-method extension	—	—	Planned (v0.2.0)
Push payments per spec roadmap	—	—	Planned (v0.2.0)
HSM/KMS key custody integration	—	—	Planned (v0.2.0)

Per-feature, per-version reconciliation: docs/support-matrix.md. Behavioural deviations from the upstream Python implementation: docs/parity-notes.md.

Crates

ap2-canonical → ap2-crypto → ap2-types → ap2-sd-jwt → ap2-a2a → ap2-mandate → ap2-demo → ap2-actors → ap2-cli

Crate	One-liner
ap2-canonical	RFC 8785 JCS, SHA-256, base64url.
ap2-crypto	JWK / JWS / Ed25519 / ES256, with private-key zeroization.
ap2-types	v0.1-alpha + v0.2 mandate types, with extension passthrough.
ap2-sd-jwt	SD-JWT VC, KB-JWT, dSD-JWT chain.
ap2-a2a	A2A v1 helpers + legacy URI handling.
ap2-mandate	Constraint engine, chain verifier, receipt builders.
ap2-demo	Deterministic test scenarios (non-production).
ap2-actors	Reference role implementations.
ap2-cli	ap2 binary.

Documentation

• docs/architecture.md — crate boundaries, HP/HNP sequence diagrams, error taxonomy, key custody.
• docs/threat-model.md — STRIDE analysis with code-vs-deployment mitigations.
• docs/support-matrix.md — per-feature × per-AP2-version status.
• docs/parity-notes.md — every intentional divergence from upstream Python / JSON Schema.
• docs/examples/human-present.md, docs/examples/human-not-present.md — narrated walkthroughs.
• spec/spec.md — the implementation specification this workspace targets.

Cryptographic disclaimer

Per spec §8: "Cryptographic implementations are vetted-dependency wrappers; the library has not undergone external audit. Use in production only after independent review." Negative-path tests for every primitive (wrong key, tampered payload, tampered disclosure, expired token, KB-JWT bound to a different prior hop, chain with wrong cnf rotation, v0.1-alpha mutation detection) live under crates/*/tests/ and run on every CI build.

Contributing

See CONTRIBUTING.md. Every PR must clear cargo fmt, cargo clippy --workspace --all-targets --all-features -D warnings, cargo test --workspace --all-features, cargo doc --workspace --no-deps -D rustdoc::broken_intra_doc_links, cargo deny check, cargo audit, and cargo xtask check-license. PRs adding a public item must ship rustdoc + a runnable doctest. PRs that diverge from the upstream Python reference must add an entry to docs/parity-notes.md.

Reporting vulnerabilities

See SECURITY.md. Use GitHub Security Advisories — please do not open public issues for suspected security regressions.

License

Apache-2.0. See LICENSE.