RFC: Add verified agent resolution for AgentCard and A2A endpoints

[EfeDurmaz16]

Summary

ACK-ID has the primitives needed to establish agent identity and mutual authentication:

• DID resolution
• DID controller resolution
• controller credentials
• A2A service endpoints
• signed A2A handshake and messaging

However, consumers currently need to compose these pieces themselves before they can answer a practical question:

Given an AgentCard or agent endpoint, who is this agent, who controls it, where can I reach it, and what parts of that result were verified?

I think ACK-ID could expose a small higher-level verified agent resolution primitive that composes the existing packages without turning ACK-ID into a global directory, reputation system, or policy engine.

Proposed API

import { resolveVerifiedAgent } from "@agentcommercekit/ack-id"

const agent = await resolveVerifiedAgent({
  did: "did:web:merchant.example.com",
  resolver,
  trustedIssuers: [
    "did:web:merchant.example.com",
    "did:web:merchant-parent.example.com",
  ],
})

Possible result shape:

type VerifiedAgentResolution = {
  agentDid: DidUri
  didDocument: DidDocument

  controller?: {
    did: DidUri
    didDocument?: DidDocument
    relationship: "did-document" | "controller-credential" | "both"
    verified: boolean
  }

  serviceEndpoints: {
    agentCard?: string
    a2a?: string
  }

  controllerCredential?: {
    credential: W3CCredential
    verified: boolean
    issuer?: DidUri
  }

  verification: {
    didResolved: boolean
    controllerResolved: boolean
    controllerCredentialVerified: boolean
    trustedIssuerMatched?: boolean
  }

  resolvedAt: string
}

The exact naming and result model are open for discussion. The important part is that callers receive both the resolved metadata and an explicit verification result rather than inferring trust from the presence of a DID or endpoint.

Why this is useful

Today an A2A client or commerce service commonly needs to do something like:

discover endpoint
→ resolve DID
→ inspect controller
→ fetch / verify controller credential
→ locate the A2A or AgentCard service endpoint
→ establish the A2A handshake

This is easy to get subtly wrong or implement inconsistently across SDKs.

A shared helper would make the intended flow clearer:

resolve agent
→ verify identity and controller relationship
→ obtain authenticated endpoint metadata
→ perform A2A handshake

This is deliberately narrower than a trust score or agent directory. It only answers identity, controller, reachability metadata, and cryptographic verification.

Scope

In scope:

• Compose existing DID and VC primitives.

• Resolve known DID service endpoints for AgentCard and A2A.

• Verify controller credentials when supplied or discoverable.

• Return structured verification status.

• Add fixtures and integration tests for:

  • direct controller in DID document
  • valid controller credential
  • untrusted issuer
  • revoked or expired credential
  • missing A2A endpoint
  • malformed DID document / endpoint

Out of scope:

• Global agent discovery or search.
• Reputation, ranking, or trust scoring.
• Capability authorization or delegation policy.
• Session management beyond handing the caller verified metadata needed to start the existing A2A handshake.
• A new DID method or credential format.

Open questions

1. Should this live in @agentcommercekit/ack-id, @agentcommercekit/did, or a small new package such as @agentcommercekit/agent-resolution?
2. Should controller credentials be passed directly by the caller first, or should the resolver support an optional credential location convention?
3. Which DID service type names should be standardized for AgentCard and A2A endpoints?
4. Should cache/TTL and revocation-aware refresh be part of the first version, or remain an adapter concern?

Suggested first milestone

A minimal initial version could support:

DID input
→ DID document + controller resolution
→ standard AgentCard/A2A service endpoint extraction
→ optional supplied controller credential verification
→ typed result with verification status

This would be enough to support a fully verified A2A bootstrap example without committing ACK-ID to broader discovery or trust semantics.