Agent identity for the A2A protocol
A2A-IDF is the identity-framework layer of the A2A protocol stack. Verification levels 0/1/2, dual-shape keyid resolution, attestation envelopes, and delegation chains. Composes with Envoys wire signatures, CTEF identity claims, and APS delegation envelopes without re-keying or re-signing.
Verify a signed request
import { verify, resolveKeyid, ReplayCache } from "@opena2a/a2a-idf";
const { publicKey } = await resolveKeyid(headers["signature-input-keyid"]);
const replay = new ReplayCache();
const result = verify({
method: req.method,
path: req.url,
body: req.body,
headers: {
"content-digest": req.headers["content-digest"],
"signature-input": req.headers["signature-input"],
signature: req.headers["signature"],
},
publicKey,
checkNonce: replay.check.bind(replay),
});
if (!result.ok) reject(result.reason); // signature-invalid, timestamp-too-old, etc.The same fixture set runs against a2a-idf-conformance using its built-in Node and Python verifiers, which depend only on platform cryptography primitives.
Four-layer A2A identity stack
The A2A identity stack split into four orthogonal layers, with each layer owned by a separate specification. A2A-IDF occupies layer two. Implementations can adopt one layer at a time.
| Layer | Concern | Specification | Layer owner |
|---|---|---|---|
| Wire signature | Per-message RFC 9421 + Ed25519. Survives proxies and intermediaries. Point-in-time integrity. | #1829 (Envoys signature/v1) | External |
| Identity framework | Verification levels 0/1/2, attestation envelopes, trust signals, delegation chain structure, revocation hooks. | #1496 (A2A-IDF) | OpenA2A |
| Identity claims | CTEF claim envelopes covering identity, transport, authority, and continuity categories. | #1786 (CTEF) | External |
| Delegation and continuity | APS bilateral receipts, delegation chains, commerce preflight, task-scoped identity. | #1575 (APS) | External |
Verification levels
A2A-IDF defines three levels of identity verification. Verifiers report the highest level the evidence supports, plus any warnings the evidence carries (stale DNS TTL, untrusted attestation issuer, expired keyid).
The AgentCard ships a valid Ed25519 signature against the declared keyid. Sufficient when downstream trust is granted by separate mechanisms.
Evidence: RFC 9421 + Ed25519 signature verifies against the resolved key.
Level 0 plus a DNS TXT record at _a2a-identity.<domain> advertising the keyid. Binds the agent to a domain operator.
Evidence: DNS TXT lookup returns the expected token. TTL above 300 seconds produces a stale-key warning.
Level 1 plus a trusted attestation that binds the agent to an organization (domain control, employer of record, or third-party audit).
Evidence: At least one attestation in the array is signed by an issuer the verifier trusts.
Reference artifacts
Three artifacts ship with the specification. The SDK is the consumer library; the conformance suite is the independent oracle; AIM is the production-grade reference implementation.
@opena2a/a2a-idf SDK
Reference TypeScript SDK. Sign and verify per RFC 9421 + Ed25519, resolve keyids in both shapes, validate verification levels, parse attestation arrays, walk delegation chains.
- Runtime dependencies: @noble/ed25519 and @noble/hashes only
- Apache 2.0, Node 24+
- Byte-matches Envoys signature/v1 §13 Vectors 1, 2, 3
Canonical conformance suite
Pinned vectors and composition fixtures. Independent Node and Python reference verifiers. No dependency on any A2A-IDF implementation library.
- Node verifier uses node:crypto only
- Python verifier uses the cryptography library only
- Cross-suite byte-match assertions against the Envoys §13 vectors
AIM reference implementation
OpenA2A Identity Manager. Production agent identity server with Ed25519 message signing, JCS canonicalization, and W3C DID Document resolution.
- Ships the same primitives the spec describes
- Validates fixtures from the conformance suite end-to-end
- No privileged position in the specification
Run the conformance suite
git clone https://github.com/opena2a-org/a2a-idf-conformance.git
cd a2a-idf-conformance
node scripts/verify.mjs fixtures/composition/aim-did-rfc9421/signature-alone.json
# PASS fixtures/composition/aim-did-rfc9421/signature-alone.jsonThe same fixture passes in both the Node and Python reference verifiers, and its expected signature byte-matches Envoys signature/v1 §13 Vector 1 by construction. Substituting the Envoys §6 compact-form key document for the W3C DID Document at the keyid URL leaves the wire signature unchanged.
Layered split endorsed across implementers
The four-layer A2A identity stack with A2A-IDF as the identity-framework layer is the consensus of the active implementer chain on a2aproject/A2A.
Crystallized the four-layer split on 2026-05-11 with three peer endorsements.
Owns the wire-signature layer. Published the §13 reproducible test vectors A2A-IDF byte-matches against.
Coordinates the cross-thread release cadence for the four-layer stack.
Ships the reference Ed25519 library against #1829. Contributed the tag parameter and SHA-512 acceptance to A2A-IDF §6.
Specification trajectory
Public roadmap so implementers can plan around the timeline. Versions follow the A2A protocol release cadence.
Verification levels 0/1/2, dual-shape keyid resolution, attestation array shape, delegation chain envelopes, RFC 9421 + Ed25519 wire signatures.
Formalize issuer / vouchee / scope / expiry shape for cross-issuer attestation chains.
Append-only revocation registry design with CT-style transparency. Subset of issuers operate as log witnesses.
Algorithm agility framework. Hybrid Ed25519 plus ML-DSA-65 keying and migration story.
Get involved
@opena2a/a2a-idf follows the composition fixture set landing in the conformance suite and this page going live. See the #1829 coordination thread for the latest cycle status.