@vess-id/ai-identity 0.0.1

package/README.md

@@ -0,0 +1,153 @@
+# @vesslabs/ai-identity
+
+TypeScript SDK for AI Identity Layer - Secure delegation system for AI agents accessing external services.
+
+## Installation
+
+```bash
+npm install @vesslabs/ai-identity
+# or
+pnpm add @vesslabs/ai-identity
+```
+
+## Quick Start
+
+```typescript
+import { AIdentityClient } from '@vesslabs/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
+```typescript
+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
+
+```typescript
+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