@vess-id/ai-identity

TypeScript SDK for AI Identity Layer - Secure delegation system for AI agents accessing external services.

Installation

npm install @vess-id/ai-identity
# or
pnpm add @vess-id/ai-identity

Quick Start

import { AIdentityClient } from '@vess-id/ai-identity'

// Initialize client
const client = new AIdentityClient({
  proxyApi: {
    baseUrl: 'http://localhost:3000', // Your Identity API endpoint
  },
})

// Create agent
const agent = await client.setup()

// Issue permission VC
const vc = await client.issueToolPermission('slack', 'postMessage', {
  subjectDid: agent.did,
  resourceScope: { channel: 'C123456' },
  expiresIn: '1h',
})

// Use the permission
const result = await client.invokeTool(
  'slack',
  'postMessage',
  {
    channel: 'C123456',
    text: 'Hello from AI Agent!',
  },
  [vc]
)

Core Concepts

Agents

Agents are autonomous entities with their own DID (Decentralized Identifier). Each agent has:

• A unique did:jwk identifier
• Public/private key pair for signing
• Local encrypted key storage

Verifiable Credentials (VCs)

VCs represent permissions or capabilities:

• ToolPermissionVC: Permission to use a specific tool/action
• DataAccessVC: Permission to access data resources

Verifiable Presentations (VPs)

VPs are signed presentations of VCs that agents use to prove their permissions when accessing services.

API Reference

AIdentityClient

Constructor

new AIdentityClient(config?: AIdentityConfig, password?: string)

Methods

setup(did?: string): Promise<Agent>

Create or load an agent.

issueToolPermission(tool, action, options): Promise<string>

Issue a VC for tool permission.

issueDataAccess(resource, actions, options): Promise<string>

Issue a VC for data access.

invokeTool<T>(tool, action, params, vcs): Promise<ConnectorResponse<T>>

Invoke a tool with VC authorization.

writeMemory(content, namespace, vcs, metadata?)

Write to memory with VC authorization.

queryMemory(query, vcs, options?)

Query memory with VC authorization.

Supported Tools

Slack

• postMessage: Post messages to channels
• getChannels: List available channels
• getUserInfo: Get user information

GitHub

• createIssue: Create repository issues
• listIssues: List repository issues
• getRepo: Get repository information

Gmail

• readMail: Read email messages
• listMails: List email messages
• getLabels: Get available labels

Google Drive

• readFile: Read file content
• listFiles: List files in folder
• getFolders: List folders

Configuration

interface AIdentityConfig {
  didApi?: {
    baseUrl: string
    apiKey?: string
    bearerToken?: string
  }
  issuerApi?: {
    baseUrl: string
    apiKey?: string
    bearerToken?: string
  }
  verifierApi?: {
    baseUrl: string
    apiKey?: string
    bearerToken?: string
  }
  proxyApi?: {
    baseUrl: string
  }
  storage?: {
    keyStorePath?: string // Default: ~/.vess/keys
  }
}

Examples

See the examples/ directory for complete usage examples:

• basic-usage.ts: Basic SDK usage
• github-integration.ts: GitHub integration example

Security

• Private keys are stored locally and encrypted with optional password
• VCs have configurable expiration times
• VPs include nonce and domain binding to prevent replay attacks
• All tool invocations require proper VC authorization

License

MIT