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. |
2 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.