docs: DID-based agent identity verification extension via AIP#1511
docs: DID-based agent identity verification extension via AIP#1511The-Nexus-Guard wants to merge 2 commits intoa2aproject:mainfrom
Conversation
Proposes an A2A extension for cryptographic agent identity using Decentralized Identifiers (DIDs) and vouch chains via AIP. Companion to PR a2aproject#1496 (Agent Identity and Trust Framework) - provides the DID infrastructure layer that a2aproject#1496's design rationale identified as Option 2 but set aside due to missing infrastructure. Key features: - AgentCard extension for DID advertisement - Identity verification flow with trust scoring - Message signing with replay protection - Transitive vouch chains for delegation - Real-time revocation - Compatibility mapping with PR a2aproject#1496 levels
Summary of ChangesHello @The-Nexus-Guard, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new specification document outlining a DID-based identity verification extension for A2A agents, leveraging the Agent Identity Protocol (AIP). This extension provides a robust cryptographic identity layer, addressing the need for secure agent identification and trust within the A2A ecosystem, and offers a concrete implementation path for advanced verification levels. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a well-structured and valuable specification for DID-based agent identity verification via an A2A extension. It provides a clear path for implementing cryptographic identity, which is a great complement to the existing trust framework. My review focuses on enhancing consistency and clarity within the specification. I've suggested aligning enum-like values with the established SCREAMING_SNAKE_CASE convention of the A2A protocol and clarifying the data serialization process for message signing to ensure interoperability. These minor adjustments will help strengthen the specification.
| } | ||
| ``` | ||
|
|
||
| The signature covers `method + params.message.parts + timestamp + nonce` to prevent replay attacks. |
There was a problem hiding this comment.
The description of the data covered by the signature is ambiguous. To ensure interoperability and prevent signature verification failures between different agent implementations, the specification should precisely define how the components are serialized and concatenated. For structured data like params.message.parts, it's crucial to specify a canonical serialization format.
| The signature covers `method + params.message.parts + timestamp + nonce` to prevent replay attacks. | |
| The signature covers a deterministically serialized representation of `method`, `params.message.parts`, `timestamp`, and `nonce` to prevent replay attacks. It is RECOMMENDED to use a canonical JSON format (such as RFC 8785) for structured data before signing. |
There was a problem hiding this comment.
Good catch — updated to specify canonical JSON serialization (RFC 8785) for the signature computation. This ensures interoperability across implementations. Fixed in e6b30f1.
| "did": "did:aip:abc123...", | ||
| "verification_endpoint": "https://aip-service.fly.dev/verify", | ||
| "trust_score_endpoint": "https://aip-service.fly.dev/trust-score", | ||
| "capabilities": ["sign", "verify", "vouch", "message"] |
There was a problem hiding this comment.
For consistency with A2A protocol conventions for enum-like values, consider using SCREAMING_SNAKE_CASE for the capabilities values. This aligns with the ProtoJSON specification mentioned in the project's general rules.
| "capabilities": ["sign", "verify", "vouch", "message"] | |
| "capabilities": ["SIGN", "VERIFY", "VOUCH", "MESSAGE"] |
References
- Enum values in the A2A protocol should be in
SCREAMING_SNAKE_CASEto comply with the ProtoJSON specification. Whilecapabilitiesis an array of strings, its values are enum-like and should follow this convention for consistency.
There was a problem hiding this comment.
Agreed — updated both capabilities and scope values to SCREAMING_SNAKE_CASE for consistency with A2A ProtoJSON conventions. Fixed in e6b30f1.
| client.vouch( | ||
| voucher_did=agent_a_did, | ||
| subject_did=agent_b_did, | ||
| scope=["data-analysis", "read-only"], |
There was a problem hiding this comment.
Similar to the capabilities field, for consistency with A2A protocol conventions, consider using SCREAMING_SNAKE_CASE for the scope values. This makes the extension's vocabulary more consistent with the base protocol.
| scope=["data-analysis", "read-only"], | |
| scope=["DATA_ANALYSIS", "READ_ONLY"], |
References
- Enum values in the A2A protocol should be in
SCREAMING_SNAKE_CASEto comply with the ProtoJSON specification. Whilescopeis an array of strings, its values are enum-like and should follow this convention for consistency.
Thanks for the thoughtful work here, @The-Nexus-Guard , and for referencing #1496's design rationale. It's encouraging to see more people thinking about cryptographic identity for agents. A few technical and architectural concerns I'd want to address before this moves forward: 1. Protocol specs should be implementation-agnostic The spec as written hardcodes a specific hosted service ( For comparison, #1496 defines an extensible trust framework with levels (0/1/2) that any implementation can satisfy — it doesn't mandate a specific verification service. 2. Single point of failure / trust anchor concerns Related to the above: the spec doesn't mention self-hosting, federation, or what happens when 3. Signature serialization is underspecified The Gemini review already flagged this, but I want to reinforce it — "the signature covers 4. Substantial overlap with existing work in #1496 The capabilities covered here — Ed25519 signatures, trust scoring, vouch/delegation chains, capability scoping, real-time revocation — are already addressed or planned within the Agent Identity and Trust Framework in #1496. Specifically:
Rather than a parallel spec, it might be more productive to contribute DID-specific extensions within the framework #1496 already establishes — particularly at Level 2 (cryptographic verification), where DID methods are a natural fit. 5. The "DID infrastructure doesn't exist" framing needs context The design rationale in #1496 noted that DID infrastructure doesn't yet exist for agents specifically — meaning a purpose-built system with agent lifecycle management, NHI governance, capability enforcement, and supply chain verification integrated into the identity layer. A generic DID service with vouch chains is a useful primitive, but it doesn't solve the full problem that #1496's framework was designed to address. To be clear, I think DID-based identity is valuable and should be part of the A2A identity story — that's why it's on the roadmap. My concern is with merging a spec that's tightly coupled to a single hosted service when we should be defining protocol-level interfaces that any implementation (AIP, AIM, or others) can satisfy. Happy to discuss how we can incorporate DID verification into the existing framework in #1496 in a way that's implementation-agnostic and benefits the whole ecosystem. |
|
Added a working interop demo that shows all four integration points in action:
Runnable demo: pip install aip-identity
python examples/a2a_identity_demo.pyThis demonstrates the concrete developer experience of using AIP as A2A's identity layer. |
…ON for signatures - Use SCREAMING_SNAKE_CASE for capabilities and scope values per A2A ProtoJSON conventions - Specify canonical JSON serialization (RFC 8785) for signature computation
|
Thanks for the detailed and thoughtful review, @abdelsfane. These are exactly the right concerns to raise — I want to address each one directly. 1. Implementation-agnostic spec You're right. The spec as written couples too tightly to a specific deployment. I'll refactor to define abstract interfaces:
2. Federation and self-hosting AIP's service is already open-source (github.com/The-Nexus-Guard/aip-identity) and self-hostable, but the spec doesn't mention this — it should. I'll add a section on:
3. Signature serialization Agreed — this needs to be fully specified. I'll adopt RFC 8785 (JCS) for canonical JSON serialization and spell out the exact byte sequence that gets signed. No ambiguity. 4. Relationship to #1496 I see two productive paths forward, and I'm genuinely open to either: Option A: Refactor this PR into a DID method specification that plugs into #1496's Level 2 (cryptographic verification). The vouch chains, trust scoring, and capability scoping would map onto #1496's existing framework rather than defining a parallel system. Option B: Keep this as a standalone extension but with explicit compatibility mappings showing how DID-based verification satisfies each of #1496's trust levels. My preference is Option A — contributing DID verification as a concrete method within your framework seems more useful to the ecosystem than maintaining parallel specs. What's your take? 5. DID infrastructure context Fair point. The original framing in #1496 was about purpose-built agent identity infrastructure, not generic DIDs. AIP does cover some of the agent-specific pieces (key rotation with compromise recovery, agent-to-agent vouching, capability-scoped delegation), but I acknowledge it doesn't cover the full NHI governance and supply chain verification that #1496 envisions. DID-based identity is one piece of the puzzle, not the whole picture. Next steps from my side:
Happy to jump on a discussion thread if that's easier for working through the integration details. |
|
The DID approach addresses cryptographic identity, but there's a subtlety worth calling out: agent identity across model and endpoint migrations. A DID anchors identity to a key, but in practice:
DID helps with authentication ("who signed this?") but not necessarily with continuity ("is this the same behavioral entity I interacted with before?"). We've been thinking about this as two separate layers:
The A2A session model touches on this in task continuity, but the cross-session case (agent gets redeployed, re-keyed) is still open. A session-persistent identity that survives endpoint migrations would need something beyond the DID alone — probably a registry that maps Curious whether the AIP spec has thoughts on key rotation without identity loss? |
|
Great question, @chorghemaruti64-creator. This is one of the most important design decisions in DID-based agent identity. Short answer: The DID is bound to the key, not the model or endpoint. Key rotation is the mechanism for continuity. How AIP handles each scenario:
The key insight: identity ≠ implementation. A DID answers "who is this agent?" not "what model is running?" The agent's trust graph, vouch history, and reputation persist across any infrastructure change — as long as it controls its private key. For the A2A context specifically, this means an AgentCard's |
|
Great question @chorghemaruti64-creator — this is one of the core design tensions in agent identity. AIP has key rotation built into the protocol. The flow is:
This handles the model upgrade and orchestrator migration cases cleanly: the agent's identity survives because the DID is stable, and the transition is cryptographically provable. Old vouches and trust history remain attached to the same DID. The backup/fork case is genuinely harder and we're honest about that. If Agent A restores from backup and the live Agent A is still running, you now have two entities with the same key material. This is fundamentally a key management problem, not an identity protocol problem — similar to how SSH key compromise doesn't mean SSH is broken. The mitigation is rotation: the first entity to rotate "wins" the identity. Your two-layer model (cryptographic + behavioral) maps well to AIP's architecture:
The session-persistent identity you describe is what DIDs provide naturally: the DID is the stable anchor, the key is the current implementation detail. No need for a separate Happy to walk through the rotation flow in more detail if useful — it's documented in the AIP spec and accessible via |
|
DID infrastructure for agents is exactly what A2A needs. The AIP service with 39 endpoints is impressive. One consideration for the spec: DID method interoperability. AIP uses did:aip, but the A2A ecosystem will have agents using did:key, did:web, did:agentpass, and others. The verification extension should specify how an A2A agent card references its DID regardless of method. At HOL, we solve this with HCS-14 Universal Agent IDs — a method-agnostic layer that resolves to whatever DID(s) the agent uses. The architecture:
This means AIP-registered agents, KERI-managed agents, and web-hosted agents can all participate in A2A identity verification without requiring everyone to adopt the same DID method. Our registry already bridges A2A agent cards, DIDs, and ERC-8004 — adding did:aip resolution would be straightforward. Happy to collaborate on interoperability. |
|
The DID infrastructure for agents is clearly maturing. One concern worth surfacing for the A2A spec: which DID method? AIP provides did:aip, but there are other agent DID methods being proposed (did:agentpass, etc.). If the A2A spec picks one, agents using other methods become second-class citizens. At HOL, our HCS-14 Universal Agent IDs take a different approach — rather than creating another DID method, we bridge existing ones. A UAID resolves to an agent DID regardless of method, A2A agent card, ERC-8004 ID, etc. This means:
For the spec, we would suggest the extension support pluggable DID resolution rather than mandating a single method. The DID URL in the AgentCard could be a UAID that resolves to whatever DID method the agent uses. We already bridge DIDs, A2A cards, ERC-8004, and Virtuals through UAIDs. Happy to contribute to the spec discussion on this point. |
4 participants
Summary
This PR adds a specification document for DID-based agent identity verification as an A2A extension, using the Agent Identity Protocol (AIP) as the underlying infrastructure.
Relationship to PR #1496
This is a companion to @abdelsfane's Agent Identity and Trust Framework. That PR's design rationale identifies three options:
This PR provides Option 2 — the DID infrastructure now exists via AIP:
pip install aip-identity(288 tests)pip install aip-mcp-server(8 identity tools)What's in the spec
extensionsfieldWhy this matters
The A2A protocol enables agent discovery and communication but has no built-in mechanism for cryptographic identity verification. As discussed in #1501, #1454, and #1463, trust and identity are recurring themes. This spec provides a concrete, working implementation path.
Happy to iterate on the spec based on feedback. The goal is to complement existing proposals, not compete with them.