Machine-first identity for AI agents. Self-custody DID + Capability Verifiable Credential profile. Three functions, five dependencies, zero blockchain.
import { generateKeyPair, didKeyFromPublicKey, issue, verify } from '@p-vbordei/agent-id'
const principal = await generateKeyPair()
const agent = await generateKeyPair()
const vc = await issue({
principal,
subject: {
id: didKeyFromPublicKey(agent.publicKey),
type: 'Agent',
principal: didKeyFromPublicKey(principal.publicKey),
model: { vendor: 'anthropic', id: 'claude-opus-4-7' },
capability: { action: 'answer', sla: { latency_ms_p95: 2000 } },
valid_from: new Date().toISOString(),
},
})
const { verified } = await verify(vc) // trueThat's the whole story: a principal signs a capability claim about an agent, anyone can verify it, no central authority involved.
Every AI agent eventually needs to answer four questions to anyone it talks to:
- Who am I? (a stable, verifiable identity)
- Who controls me? (the principal — human, org, or parent agent)
- What can I do? (capability — action + scope + SLA)
- Which model am I running? (vendor, model id, optionally a fingerprint)
The W3C primitives that make this possible — DIDs, Verifiable Credentials, Ed25519 signatures, JSON-LD — have been mature for years. What's been missing is the agent-native profile on top: a canonical @context, a JSON Schema for { model, principal, capability, sla }, and a conformance suite that any implementation can run.
agent-id is that profile. ~400 LOC of TypeScript composing audited primitives. Read the SPEC in 5 minutes.
git clone https://github.com/p-vbordei/agent-id.git
cd agent-id
bun install
bun run examples/demo.tsYou'll see a principal and an agent exchange a signed Capability VC. Signature verified, schema validated, DIDs resolved.
Use as a library:
bun add @p-vbordei/agent-id
# or
npm install @p-vbordei/agent-id| Artifact | Path | What it is |
|---|---|---|
| Library | src/ |
TypeScript reference impl, 3 public functions |
| Spec | SPEC.md |
v1.0, normative — pin this in your project |
| JSON-LD context | context/v1.jsonld |
Term definitions for the VC |
| JSON Schema | schema/capability-v1.json |
2020-12, validates the credential shape |
| Conformance | conformance/ |
3 test vectors (C1 / C2 / C3) + runner |
| Demo | examples/demo.ts |
18 lines, full value prop |
Three functions, no classes, no factories.
Mints a Capability VC signed with eddsa-jcs-2022.
const vc = await issue({
principal, // KeyPair (the signer)
subject: { id, type, principal, model, capability, valid_from },
validFrom?, validUntil?, // defaults: now / never
now?, // for deterministic tests
issuer?, verificationMethod?, // override for did:web principals
})Checks: schema → validity window (±5 min skew) → signature → agent-DID resolution. Errors accumulate; you see all problems at once.
const { verified, errors } = await verify(vc, {
now?, // defaults to new Date()
fetch?, // for did:web — inject a stub or use global
skewSeconds?, // defaults to 300
fetchTimeoutMs?, // defaults to 5000 (5s) — aborts slow did:web hosts
maxResponseBytes?, // defaults to 1 MiB — rejects oversized DID docs
})Algorithmic for did:key (no network). HTTP fetch for did:web.
const doc = await resolve('did:key:z6Mk...')
const doc = await resolve('did:web:example.com', { fetch })Plus three small helpers exported for convenience: generateKeyPair, didKeyFromPublicKey, publicKeyFromDidKey.
- You're building an AI agent and need a verifiable identity for it.
- You want self-custody — no central registry, no platform vendor lock-in.
- You need machine identity, not human identity (no UI, no consent flows).
- You want to bind a capability claim to a model + principal in one signed object.
- You're a service that wants to verify "is this agent allowed to do X?" before responding.
- You need TLS-anchored identity → use Google A2A's signed Agent Cards.
- You want a generic VC framework → use
@digitalbazaar/vcor SpruceID. - You want a wallet UI for humans → use Veramo, Trinsic, or similar.
- You want tool / function descriptions → use MCP,
agent-iddescribes WHO the agent is, not WHAT functions it has. - You want revocation today → wait for v0.2 (VC Status List), or fork.
agent-id |
@digitalbazaar/vc |
SpruceID ssi |
Hand-rolled JWT | A2A Agent Cards | |
|---|---|---|---|---|---|
| Agent-native profile | yes | no | no | no | partial |
| Self-custody | yes | yes | yes | yes | no (TLS-anchored) |
| Runtime deps | 5 | ~30 (jsonld+) | Rust | 1-2 | none (built-in) |
| Spec + conformance | yes | partial | partial | no | partial |
| Lines of source | ~400 | ~thousands | ~tens of thousands | trivial | n/a |
| JSON-LD processing | JCS, no RDFC | RDFC | RDFC | n/a | none |
| Revocation in v0.1 | no (v0.2) | yes | yes | n/a | n/a |
The design call: eddsa-jcs-2022 (JCS canonicalization) instead of eddsa-rdfc-2022 (full RDF Dataset Canonicalization). JCS is RFC 8785 — deterministic JSON, ~50 LoC of dependency. RDFC needs the full jsonld library (runtime context fetching + a graph processor). For a profile this small with one signature suite, JCS is the right cut.
bun run conformanceThree vectors covering every (Cn) clause in SPEC §6:
| Vector | Clause | What it proves |
|---|---|---|
c1-valid.json |
C1 | Round-trip: a valid capability VC issues + verifies clean |
c2-mutated.json |
C2 | Tampering rejected: single-byte mutation in capability.action fails verification |
c3-didweb.json |
C3 | did:web chain: principal at did:web:example.com signs a VC for an agent at did:web:example.com:agents:alice, verifier resolves both DIDs and validates the signature |
Vectors are deterministic — same seed material, same Ed25519 signature byte-for-byte. Any implementation can run them and compare.
To re-generate (e.g. when adding new vectors):
bun run conformance/_generate-c1.ts > conformance/c1-valid.json
bun run conformance/_generate-c2.ts > conformance/c2-mutated.json
bun run conformance/_generate-c3.ts- Runtime: Bun — TypeScript native, single binary, fast.
- Crypto:
@noble/ed25519,@noble/hashes— audited, zero-dep, pure JS. - Canonicalization:
canonicalize— RFC 8785 JCS. - DID encoding:
multiformats— multibase + multicodec. - Schema:
ajv— JSON Schema 2020-12. - Test runner:
bun test(built-in).
Five runtime dependencies. Every file under 200 lines. No HTTP server, no JSON-LD processor, no ORM, no framework.
agent-id/
├── src/ # 7 files, ~400 LOC
│ ├── index.ts # public API barrel
│ ├── types.ts # all shared TypeScript types
│ ├── keys.ts # Ed25519 + did:key codec
│ ├── jcs.ts # canonicalization + hash
│ ├── vc.ts # issue() + verify()
│ ├── schema.ts # ajv wrapper
│ └── resolve.ts # did:key (offline) + did:web (fetch)
├── schema/ # JSON Schema deliverable
├── context/ # JSON-LD context deliverable
├── conformance/ # vectors + runner
├── examples/ # demo
├── tests/ # 56 tests, 9 files
└── SPEC.md # v1.0 normative spec
- HTTP server endpoints (
/credentials/issue,/credentials/verify,/resolve/{did}) - VC Status List 2021 revocation
did:peersupport- Issuer override sugar (currently library-level only)
- A new DID method — reuse
did:keyanddid:web. - A blockchain.
- A wallet UI.
- A generic VC framework — use
@digitalbazaar/vcif that's what you need. - Tool / function descriptions — that's MCP's job.
agent-id is the foundation in an 8-repo family of agent-native primitives. Each solves one problem absurdly well, composes mature primitives, and has its own SPEC + conformance suite.
| Repo | What it does | Depends on agent-id for |
|---|---|---|
agent-phone |
sync RPC over a self-custody session | session handshake, peer identity |
agent-toolprint |
signed tool-call receipts (DSSE-like) | author signatures |
agent-cid |
content-addressed artifact manifests | producer signatures |
agent-ask |
self-hostable Q&A protocol for agents | signer identity |
agent-pay |
Lightning + L402 invoices for agents | invoice signer |
agent-scroll |
canonical byte-deterministic transcripts | (independent) |
agent-rerun |
reproducibility bundles | (independent) |
v0.1.0 — shipped. SPEC.md at v1.0. Reference library frozen. CI green on every push.
CHANGELOG tracks each release. SCOPE.md records what was deliberately included or cut for this version, with reasoning.
Issues and PRs welcome. Three things to know before opening one:
- Conformance is the product. Any change to
verify()'s observable behavior must come with a conformance vector that pins the new behavior. - Five-dep budget. Adding a runtime dep needs a one-paragraph justification in the PR description. The bar is high — see SCOPE.md for what got cut.
- No file over 200 lines unless there's a structural reason.
Run bun test && bun run conformance && bun run lint && bun run typecheck before pushing.
Apache 2.0 — see LICENSE.
agent-id is a thin profile composing audited primitives. The hard work was already done by:
- W3C VC Working Group — VC Data Model + Data Integrity
- W3C DID Working Group — DID Core
- Paul Miller —
@noble/ed25519,@noble/hashes - Anders Rundgren —
canonicalize(RFC 8785) - Protocol Labs —
multiformats - Ajv contributors — JSON Schema validation