agent-did

W3C-compliant DID and Verifiable Credential toolkit for AI agents.

Give your AI agents cryptographic identity. Issue ownership credentials, delegate capabilities with expiration, and prove authenticity using W3C standards.

npm install -g agent-did

Website · Why this matters

Features

• Create DIDs - did:key method with Ed25519 cryptography
• Issue Verifiable Credentials - Ownership and capability credentials (JWT with EdDSA)
• Verify credentials - Cryptographic signature verification
• Key rotation - Maintain identity continuity
• Privacy-preserving revocation - W3C Bitstring Status List
• Expiration warnings - Monitor credential lifecycle
• Encrypted storage - AES-256-GCM with PBKDF2 (600k iterations)

Standards:

• W3C DID Core 1.0
• W3C VC Data Model 2.0
• W3C Bitstring Status List

Quick Start

1. Install

npm install -g agent-did

# Or use without installing
npx agent-did --help

2. Set Passphrase (Choose One)

Option A: Role-specific environment variables (Recommended for automation)

# Used for owner/issuer key operations (create owner, vc issue ownership/capability)
export OWNER_DID_PASSPHRASE="owner-passphrase"

# Used for agent key operations (create agent, auth sign, vc issue profile)
export AGENT_DID_PASSPHRASE="agent-passphrase"

AGENT_DID_OWNER_PASSPHRASE is also accepted for owner operations. Legacy owner fallback from AGENT_DID_PASSPHRASE still works with a warning.

Option B: Interactive prompt (Best for manual use)

# Owner key prompt
agent-did create owner --name "Agent-DID XYZ"

# Agent key prompt (separate passphrase by default)
agent-did create agent --name "Support Bot" --owner did:key:z6MkhaXg...

Option C: No encryption (Development/testing only)

agent-did create owner --name "Agent-DID XYZ" --no-encryption

💡 For production, use environment variable or interactive prompt. Store passphrase in password manager.

3. Create Identities

# Create owner identity (you/your organization)
agent-did create owner --name "Agent-DID XYZ"
# prompts for owner passphrase (unless --owner-passphrase or OWNER_DID_PASSPHRASE is set)

# Create agent identity
agent-did create agent \
  --name "Support Bot" \
  --owner did:key:z6MkhaXg...
# prompts for AGENT passphrase by default (unless --agent-passphrase or AGENT_DID_PASSPHRASE is set)

4. Issue Credentials

# Prove ownership (auto-stored in keystore)
OWNER_DID_PASSPHRASE="owner-passphrase" agent-did vc issue ownership \
  --issuer did:key:z6MkhaXg... \
  --subject did:key:z6Mkj7yH...
# ✓ Stored metadata in keystore: ~/.agent-did/credentials/ownership-391f062c...json
# ✓ JWT file: ~/.agent-did/vc/agent-ownership-credential-z6mkj7yh...jwt

# Grant capabilities (auto-stored in keystore)
agent-did vc issue capability \
  --issuer did:key:z6MkhaXg... \
  --subject did:key:z6Mkj7yH... \
  --scopes "read,write,refund" \
  --expires "2025-12-31T23:59:59Z"
# ✓ Stored metadata in keystore: ~/.agent-did/credentials/capability-f9b4e891...json
# ✓ JWT file: ~/.agent-did/vc/agent-capability-credential-z6mkj7yh...jwt

# Optional: Also save to a custom file (still copied to ~/.agent-did/vc unless --no-store)
OWNER_DID_PASSPHRASE="owner-passphrase" agent-did vc issue ownership \
  --issuer ... \
  --subject ... \
  --out ownership.jwt

# Optional: Skip keystore metadata + default vc storage (for immediate API use)
agent-did vc issue capability --issuer ... --subject ... --no-store

5. Verify Credentials

agent-did vc verify --file capability.jwt

6. Agent Signs Challenge

AGENT_DID_PASSPHRASE="agent-passphrase" agent-did auth sign \
  --did did:key:z6Mkj7yH... \
  --challenge "$NONCE" \
  --audience "agent-did.xyz" \
  --domain "agent-did.xyz" \
  --json

Core Concepts

DID (Decentralized Identifier)

Self-sovereign cryptographic identity you control.

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
│    │   └─ Base58btc-encoded Ed25519 public key
│    └───── Method (derived from key)
└────────── Scheme

Verifiable Credential

Cryptographically signed claim about a subject.

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "AgentCapabilityCredential"],
  "issuer": "did:key:z6Mk...",
  "validFrom": "2024-01-15T10:30:00Z",
  "validUntil": "2025-12-31T23:59:59Z",
  "credentialSubject": {
    "id": "did:key:z6Mk...",
    "scopes": ["read", "write"]
  }
}

Learn more about the vision →

Command Reference

Identity Management

# Create owner
agent-did create owner --name <name> [--owner-passphrase <passphrase>]

# Create agent
agent-did create agent --name <name> --owner <did> [--agent-passphrase <passphrase>]

# List identities
agent-did list

# Inspect identity
agent-did inspect --did <did>

# Delete identity
agent-did delete --did <did> --yes

Verifiable Credentials

# Issue ownership VC (auto-stored in keystore)
agent-did vc issue ownership \
  --issuer <did> --subject <did> \
  [--owner-passphrase <passphrase>]

# Issue capability VC (auto-stored in keystore)
agent-did vc issue capability \
  --issuer <did> --subject <did> \
  --scopes <scopes> \
  [--owner-passphrase <passphrase>] \
  --expires <iso-date>

# Optional flags:
#   --out <file>     Write JWT file there and also store in ~/.agent-did/vc (unless --no-store)
#   --no-store       Skip keystore metadata storage and skip ~/.agent-did/vc storage

# List local VCs (scans ~/.agent-did/vc and legacy ~/.agent-did/credentials/*.jwt)
agent-did vc list [--verify]

# Verify VC
agent-did vc verify --file <file>

# Revoke VC
agent-did vc revoke --file <file> --reason <reason>

# Check revocation
agent-did vc check-revocation --file <file>

# Inspect VC (decode without verifying)
agent-did vc inspect --file <file>

Authentication

# Sign challenge
agent-did auth sign \
  --did <did> \
  --challenge <nonce> \
  [--agent-passphrase <passphrase>] \
  --audience <service> \
  --json

# Verify signature
agent-did auth verify \
  --did <did> \
  --payload <base64url> \
  --signature <base64url>

Key Rotation

# Rotate key
agent-did rotate-key --did <did> --reason <reason>

# View rotation history
agent-did rotation-history

Status Lists

# Create status list
agent-did vc create-status-list --issuer <did>

# View statistics
agent-did vc status-list-stats --issuer <did>

Expiration Management

# Check expiring credentials
agent-did vc check-expiring --days 30

# Get summary
agent-did vc expiration-summary

# Check specific credential
agent-did vc check-credential-expiry --file <file>

Keystore Operations

# Check keystore health
agent-did keystore doctor

# Include migration from legacy credentials/*.jwt to vc/
agent-did keystore doctor --migrate-vc --yes

# Backup keystore
agent-did keystore backup --out backup.json --encrypt

# Restore keystore
agent-did keystore restore --file backup.json

Default Storage Layout

• AGENT_DID_HOME overrides home path; default is ~/.agent-did
• ~/.agent-did/keys/ - encrypted/decrypted key material files
• ~/.agent-did/vc/ - canonical VC JWT storage (*.jwt)
• ~/.agent-did/credentials/ - legacy/internal metadata storage (still scanned for *.jwt)
• ~/.agent-did/backups/ - backup destination directory

Example Outputs

agent-did vc list with zero credentials

No credentials found.
Scanned: /Users/you/.agent-did/vc
Scanned (legacy): /Users/you/.agent-did/credentials

agent-did vc list with two credentials

Found 2 credential(s):

- File: agent-ownership-credential-z6mkj7yh-20260206T220153Z-a1b2c3.jwt
  Types: VerifiableCredential, AgentOwnershipCredential
  Issuer: did:key:z6MkhaXg...
  Subject: did:key:z6Mkj7yH...
  Issued: 2/6/2026, 10:01:53 PM

- File: agent-capability-credential-z6mkj7yh-20260206T220245Z-d4e5f6.jwt
  Types: VerifiableCredential, AgentCapabilityCredential
  Issuer: did:key:z6MkhaXg...
  Subject: did:key:z6Mkj7yH...
  Issued: 2/6/2026, 10:02:45 PM
  Expires: 12/31/2026, 11:59:59 PM

agent-did keystore doctor healthy

Keystore Doctor
Home: /Users/you/.agent-did
Home source: default

Directories:
- keys: exists, writable, permissions OK (/Users/you/.agent-did/keys)
- vc: exists, writable, permissions OK (/Users/you/.agent-did/vc)
- backups: exists, writable, permissions OK (/Users/you/.agent-did/backups)

Counts:
- Identities: 2
- Key files: 2
- VC files: 2 (canonical: 2, legacy: 0)

✓ Healthy keystore

agent-did keystore doctor broken permissions

Keystore Doctor
Home: /Users/you/.agent-did
Home source: default

Errors:
- [error] weak-directory-permissions: Directory permissions allow group/other write access (/Users/you/.agent-did/keys)

✗ Keystore health check failed

Complete command reference →

Integration Examples

Authentication Flow

💡 Quick Start: For production use, check out agent-did-server - a ready-to-use authentication server that handles the entire flow below.

Manual Implementation - Server generates challenge:

const challenge = crypto.randomUUID();
await redis.setex(`auth:${challenge}`, 120, 'pending');
res.json({ challenge });

Client signs challenge:

AGENT_DID_PASSPHRASE="agent-passphrase" agent-did auth sign \
  --did did:key:z6Mkj7yH... \
  --challenge "$CHALLENGE" \
  --audience "agent-did.xyz" \
  --json > auth.json

Server verifies:

import { didKeyToPublicKey } from 'agent-did/did';
import { verify } from 'agent-did/crypto';

const { did, payloadEncoded, signature } = req.body;

// 1. Extract public key from DID
const publicKey = didKeyToPublicKey(did);

// 2. Verify Ed25519 signature
const isValid = await verify(
  Buffer.from(payloadEncoded),
  Buffer.from(signature, 'base64url'),
  publicKey
);

// 3. Check payload (nonce, expiration, audience)
const payload = JSON.parse(
  Buffer.from(payloadEncoded, 'base64url').toString()
);

More examples →

Security

• Encryption: AES-256-GCM with PBKDF2 (600k iterations - OWASP 2024)
• Signatures: Ed25519 (EdDSA)
• Key Storage: Encrypted at rest, file permissions 0o600
• Randomness: Cryptographically secure (crypto.randomBytes)
• Passphrase Options: Environment variable, interactive prompt, or no encryption

Best Practices:

1. Production: Use encrypted keystore with strong passphrase (16+ chars)
2. Development: Interactive prompt or --no-encryption for testing
3. CI/CD: Set both OWNER_DID_PASSPHRASE and AGENT_DID_PASSPHRASE (or pass command flags)
4. Rotate keys quarterly or after compromise
5. Set expiration on all capability credentials
6. Backup keystore regularly with encryption
7. Use Bitstring Status List for production revocation

Security details →

Documentation

• VISION.md - Why decentralized identity for AI agents matters
• GUIDE.md - Complete usage guide with tutorials
• examples/ - Integration examples

Development

# Clone
git clone https://github.com/dantber/agent-did.git
cd agent-did

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Smoke test
npm run smoke

Requirements:

• Node.js 20+
• TypeScript 5+

Contributing →

License

MIT - see LICENSE

Community

• Website: agent-did.xyz
• Issues: Report bugs
• npm: agent-did

Built with ❤️ for the agentic future