System Architecture
Agent-Pass implements a decentralized identity protocol using W3C standards, designed specifically for autonomous AI agent authentication with dual-signature verification.
Core Architecture
Identity Layer
W3C DID-based identity management for both controllers and agents
- DID generation using did:key method
- Ed25519 cryptographic keys
- Veramo agent framework
- Key management system integration
Credential Layer
Verifiable Credentials for capability delegation and authorization
- Agent Capability Credentials (ACC)
- Constraint-based permissions
- Expiration and validity checking
- Cryptographic proof attachment
Presentation Layer
Challenge-response authentication with Verifiable Presentations
- Challenge generation and validation
- Domain-bound presentations
- Dual signature verification
- Replay attack prevention
Integration Layer
Framework integrations and middleware for common platforms
- Express.js middleware
- TypeScript client libraries
- Configurable authentication flows
- Error handling and logging
Component Structure
Core Classes Architecture
// Main unified interface
export class AgentPass {
private sharedAgent: ReturnType<typeof createAgent>;
private identityManager: AgentIdentityManager;
private credentialManager: AgentCredentialManager;
private presentationManager: AgentPresentationManager;
}
// Specialized managers for different concerns
export class AgentIdentityManager {
async createAgentIdentity(options?: CreateAgentOptions): Promise<AgentIdentity>
async createControllerIdentity(options?: CreateAgentOptions): Promise<ControllerIdentity>
async resolveDID(did: string): Promise<any>
}
export class AgentCredentialManager {
async createAgentCapabilityCredential(
controller: ControllerIdentity,
agent: AgentIdentity,
options: CreateCredentialOptions
): Promise<AgentCapabilityCredential>
async verifyAgentCapabilityCredential(
credential: AgentCapabilityCredential
): Promise<VerificationResult>
}
export class AgentPresentationManager {
generateChallenge(domain: string, validityDuration?: number): Challenge
async createVerifiablePresentation(
agent: AgentIdentity,
credential: AgentCapabilityCredential,
challenge: string,
domain: string
): Promise<VerifiablePresentation>
async verifyVerifiablePresentation(
presentation: VerifiablePresentation,
expectedChallenge: string,
expectedDomain: string
): Promise<VerificationResult>
}Authentication Data Flow
1
Identity Creation
Controller and Agent generate DID identities with Ed25519 keys
2
Credential Issuance
Controller issues Agent Capability Credential with scope and constraints
3
Challenge Generation
Relying Party generates unique challenge with domain binding
4
Presentation Creation
Agent creates Verifiable Presentation with credential and challenge response
5
Dual Verification
Verify agent signature on presentation AND controller signature on credential
Security Model
Cryptographic Properties
Ed25519 signature verification
Challenge-response freshness
Domain binding protection
Replay attack prevention
Access Control
Scope-based permissions
Fine-grained constraints
Expiration checking
Context-aware validation
Implementation Pattern
Complete Authentication Flow
import { AgentPass } from '@agent-pass/core';
const agentPass = new AgentPass();
// 1. Create identities
const controller = await agentPass.createControllerIdentity({
alias: 'human-user'
});
const agent = await agentPass.createAgentIdentity({
alias: 'email-agent'
});
// 2. Issue capability credential
const credential = await agentPass.createAgentCapabilityCredential(
controller,
agent,
{
scope: ['read:emails', 'send:emails'],
constraints: {
allowedDomains: ['example.com'],
maxEmailsPerDay: 100
}
}
);
// 3. Authentication challenge-response
const challenge = agentPass.generateChallenge('api.service.com');
const presentation = await agentPass.createVerifiablePresentation(
agent,
credential,
challenge.challenge,
challenge.domain
);
// 4. Dual verification
const verification = await agentPass.verifyVerifiablePresentation(
presentation,
challenge.challenge,
challenge.domain
);
if (verification.verified) {
console.log('✅ Agent authenticated successfully');
console.log('Agent DID:', verification.agentDid);
console.log('Controller DID:', verification.controllerDid);
console.log('Granted scope:', verification.scope);
}