@vorim/sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,31 @@
 # @vorim/sdk
 
-Official TypeScript SDK for **Vorim AI** — the AI Agent Identity & Trust Layer.
+**The identity and trust layer for AI agents.**
 
-Register agents with cryptographic identities, enforce fine-grained permissions, emit immutable audit trails, and verify trust scores.
+Register agents with cryptographic Ed25519 identities, enforce scoped permissions in under 5ms, emit tamper-evident audit trails, and verify trust scores — all in a few lines of code.
+
+[![npm version](https://img.shields.io/npm/v/@vorim/sdk.svg)](https://www.npmjs.com/package/@vorim/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)]()
+
+---
+
+## Why Vorim?
+
+AI agents are shipping into production without identity, permissions, or audit trails. This is a problem:
+
+- **No identity** — agents share API keys. You can't tell which agent did what.
+- **No permissions** — agents get all-or-nothing access. No scoped, time-bounded controls.
+- **No audit trail** — no tamper-evident record of agent actions. Compliance teams are blind.
+- **No trust signal** — third parties can't verify an agent before interacting with it.
+
+Vorim solves all four. One SDK. One protocol. Ships in minutes.
+
+> **EU AI Act** (enforced Aug 2025) mandates traceability and audit trails for high-risk AI systems. Vorim makes your agents compliant out of the box.
+
+---
 
 ## Install
 
@@ -10,92 +33,377 @@ Register agents with cryptographic identities, enforce fine-grained permissions,
 npm install @vorim/sdk
 ```
 
+```bash
+# or
+yarn add @vorim/sdk
+# or
+pnpm add @vorim/sdk
+```
+
+---
+
 ## Quick Start
 
 ```typescript
-import createVorim from '@vorim/sdk';
+import createVorim from "@vorim/sdk";
 
 const vorim = createVorim({
-  apiKey: 'agid_sk_live_your_api_key_here',
+  apiKey: "agid_sk_live_...",
 });
 
-// Register an agent with Ed25519 keypair
+// 1. Register an agent — Ed25519 keypair generated, private key shown once
 const { agent, private_key } = await vorim.register({
-  name: 'InvoiceBot',
-  capabilities: ['api_access', 'email_send'],
-  scopes: ['agent:read', 'agent:write'],
+  name: "invoice-processor",
+  capabilities: ["read_documents", "extract_data"],
+  scopes: ["agent:read", "agent:execute"],
+});
+
+console.log(agent.agent_id);    // agid_acme_a1b2c3d4
+console.log(agent.trust_score); // 50 (initial)
+
+// 2. Check permissions before acting (<5ms via Redis)
+const { allowed } = await vorim.check(agent.agent_id, "agent:execute");
+
+if (allowed) {
+  // 3. Perform the action, then emit an audit event
+  await vorim.emit({
+    agent_id: agent.agent_id,
+    event_type: "tool_call",
+    action: "process_invoice",
+    resource: "INV-2026-0042",
+    result: "success",
+    latency_ms: 142,
+  });
+}
+
+// 4. Verify any agent's trust (public endpoint, no auth required)
+const trust = await vorim.verify(agent.agent_id);
+console.log(trust.trust_score);  // 0–100
+console.log(trust.active_scopes); // ['agent:read', 'agent:execute']
+```
+
+---
+
+## Framework Integration
+
+### LangChain
+
+```typescript
+import createVorim from "@vorim/sdk";
+import { ChatOpenAI } from "@langchain/openai";
+import { AgentExecutor } from "langchain/agents";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+
+// Register your LangChain agent with Vorim
+const { agent: identity } = await vorim.register({
+  name: "langchain-research-agent",
+  capabilities: ["web_browsing", "api_calls"],
+  scopes: ["agent:read", "agent:execute", "agent:communicate"],
+});
+
+// Check permissions before every tool call
+async function guardedToolCall(toolName: string, input: any) {
+  const { allowed } = await vorim.check(identity.agent_id, "agent:execute");
+  if (!allowed) throw new Error("Permission denied by Vorim");
+
+  const result = await executeTool(toolName, input);
+
+  // Audit every action
+  await vorim.emit({
+    agent_id: identity.agent_id,
+    event_type: "tool_call",
+    action: `${toolName}: ${JSON.stringify(input)}`,
+    result: "success",
+  });
+
+  return result;
+}
+```
+
+### CrewAI
+
+```typescript
+import createVorim from "@vorim/sdk";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+
+// Register each crew member as a Vorim agent
+const researcher = await vorim.register({
+  name: "crew-researcher",
+  capabilities: ["web_browsing"],
+  scopes: ["agent:read"],
 });
 
-// Check permissions (sub-5ms via Redis cache)
-const { allowed } = await vorim.check(agent.agent_id, 'agent:write');
+const writer = await vorim.register({
+  name: "crew-writer",
+  capabilities: ["file_access"],
+  scopes: ["agent:read", "agent:write"],
+});
 
-// Emit audit event
+// Verify permissions before delegation
+const { allowed } = await vorim.check(writer.agent.agent_id, "agent:write");
+```
+
+### OpenAI Agents SDK
+
+```typescript
+import createVorim from "@vorim/sdk";
+import OpenAI from "openai";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+const openai = new OpenAI();
+
+// Register your OpenAI agent
+const { agent: identity } = await vorim.register({
+  name: "openai-assistant",
+  capabilities: ["api_calls", "code_execution"],
+  scopes: ["agent:read", "agent:execute"],
+});
+
+// Wrap function calls with Vorim permission checks
+async function handleFunctionCall(call: any) {
+  const { allowed } = await vorim.check(identity.agent_id, "agent:execute");
+  if (!allowed) return { error: "Blocked by Vorim trust layer" };
+
+  const result = await executeFunction(call);
+
+  await vorim.emit({
+    agent_id: identity.agent_id,
+    event_type: "tool_call",
+    action: call.name,
+    resource: JSON.stringify(call.arguments),
+    result: "success",
+  });
+
+  return result;
+}
+```
+
+---
+
+## API Reference
+
+### Identity
+
+```typescript
+// Register a new agent (private key returned once — store it securely)
+const { agent, private_key } = await vorim.register({
+  name: "my-agent",
+  description: "Processes invoices",
+  capabilities: ["read_documents"],
+  scopes: ["agent:read", "agent:execute"],
+});
+
+// Get agent details
+const agent = await vorim.getAgent("agid_acme_a1b2c3d4");
+
+// List all agents in your organisation
+const { agents, meta } = await vorim.listAgents({ page: 1, per_page: 20 });
+
+// Permanently revoke an agent
+await vorim.revoke("agid_acme_a1b2c3d4");
+```
+
+### Permissions
+
+```typescript
+// Check if an agent has a specific permission (<5ms)
+const { allowed, remaining_quota } = await vorim.check(
+  "agid_acme_a1b2c3d4",
+  "agent:execute"
+);
+
+// Grant a time-bounded, rate-limited permission
+await vorim.grant("agid_acme_a1b2c3d4", "agent:transact", {
+  valid_until: "2026-06-01T00:00:00Z",
+  rate_limit: { max: 100, window: "1h" },
+});
+```
+
+#### Permission Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `agent:read` | Read data and resources |
+| `agent:write` | Create or modify resources |
+| `agent:execute` | Execute tools and functions |
+| `agent:transact` | Perform financial transactions |
+| `agent:communicate` | Send messages and notifications |
+| `agent:delegate` | Delegate tasks to other agents |
+| `agent:elevate` | Request elevated privileges |
+
+### Audit
+
+```typescript
+// Emit a single audit event
 await vorim.emit({
-  agent_id: agent.agent_id,
-  event_type: 'api_request',
-  action: 'POST /invoices',
-  result: 'success',
+  agent_id: "agid_acme_a1b2c3d4",
+  event_type: "tool_call",
+  action: "send_email",
+  resource: "user@example.com",
+  result: "success",
+  latency_ms: 230,
+  metadata: { template: "invoice_reminder" },
 });
 
-// Verify trust (public API, no auth needed)
-const trust = await vorim.verify(agent.agent_id);
-console.log(trust.trust_score); // 0-100
+// Batch emit up to 1,000 events
+await vorim.emitBatch([
+  { agent_id: "agid_acme_a1b2c3d4", event_type: "api_request", action: "GET /users", result: "success" },
+  { agent_id: "agid_acme_a1b2c3d4", event_type: "api_request", action: "POST /orders", result: "denied" },
+]);
 ```
 
-## Features
+### Trust Verification
+
+```typescript
+// Public endpoint — no API key required
+const trust = await vorim.verify("agid_acme_a1b2c3d4");
+
+trust.verified;          // true
+trust.trust_score;       // 82
+trust.status;            // 'active'
+trust.owner.org_name;    // 'Acme Corp'
+trust.active_scopes;     // ['agent:read', 'agent:execute']
+trust.key_fingerprint;   // 'a1b2c3d4...'
+trust.revocation_status; // false
+```
+
+**Trust score factors:**
+- Agent status (active, suspended, revoked)
+- Account age (older = more trusted)
+- Success rate over last 30 days
+- Denial ratio (high denials = lower trust)
+- Scope breadth (too many scopes = higher risk)
 
-- **Cryptographic Identity** — Ed25519 keypairs, SHA-256 fingerprints
-- **7 Permission Scopes** — `agent:read`, `write`, `execute`, `transact`, `communicate`, `delegate`, `elevate`
-- **Immutable Audit Trail** — ULID-ordered events with content hashes
-- **Trust Scoring** — Multi-factor algorithm (0-100)
-- **Payload Signing** — Client-side Ed25519 signatures via Web Crypto or Node.js crypto
-- **Dual Runtime** — Works in Node.js 18+ and modern browsers
-
-## API
-
-| Method | Description |
-|---|---|
-| `vorim.register(input)` | Register agent with keypair |
-| `vorim.getAgent(agentId)` | Get agent details |
-| `vorim.listAgents(params?)` | List organisation agents |
-| `vorim.revoke(agentId)` | Permanently revoke agent |
-| `vorim.check(agentId, scope)` | Check permission |
-| `vorim.grant(agentId, scope, options?)` | Grant permission |
-| `vorim.emit(event)` | Emit single audit event |
-| `vorim.emitBatch(events)` | Emit up to 1,000 events |
-| `vorim.verify(agentId)` | Public trust verification |
-| `vorim.sign(payload, privateKey)` | Ed25519 payload signing |
+### Payload Signing
+
+```typescript
+// Sign a payload with the agent's Ed25519 private key (client-side)
+const signature = await vorim.sign(
+  JSON.stringify({ action: "transfer", amount: 500 }),
+  privateKeyPem
+);
+// Returns: "ed25519:base64signature..."
+
+// Include signature in audit events for non-repudiation
+await vorim.emit({
+  agent_id: "agid_acme_a1b2c3d4",
+  event_type: "tool_call",
+  action: "transfer_funds",
+  result: "success",
+  signature,
+});
+```
+
+### Embeddable Trust Badge
+
+Every registered agent gets a public SVG trust badge you can embed anywhere:
+
+```html
+<!-- Embed in your docs, landing page, or agent marketplace listing -->
+<img src="https://api.vorim.ai/v1/trust/badge/agid_acme_a1b2c3d4.svg" alt="Vorim Trust Badge" />
+```
+
+The badge displays the agent's current trust score and updates in real-time. Use it to signal trust to end users, partners, and other agents.
+
+---
 
 ## Configuration
 
 ```typescript
+import createVorim from "@vorim/sdk";
+
 const vorim = createVorim({
-  apiKey: 'agid_sk_live_...',     // Required — your API key
-  baseUrl: 'https://api.vorim.ai', // Optional — API base URL
-  timeout: 10000,                   // Optional — request timeout (ms)
+  apiKey: "agid_sk_live_...",         // Required — your Vorim API key
+  baseUrl: "https://api.vorim.ai",   // Optional (default)
+  timeout: 10000,                     // Optional — request timeout in ms (default: 10000)
 });
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | Your Vorim API key (`agid_sk_live_...` or `agid_sk_test_...`) |
+| `baseUrl` | `string` | `https://api.vorim.ai` | API base URL (override for self-hosted) |
+| `timeout` | `number` | `10000` | Request timeout in milliseconds |
+
+---
+
 ## Error Handling
 
+All errors throw `VorimError` with structured fields:
+
 ```typescript
-import { VorimError } from '@vorim/sdk';
+import createVorim, { VorimError } from "@vorim/sdk";
 
 try {
-  await vorim.check('invalid_id', 'agent:read');
+  await vorim.check("invalid_id", "agent:read");
 } catch (err) {
   if (err instanceof VorimError) {
-    console.log(err.status);  // 404
-    console.log(err.code);    // 'AGENT_NOT_FOUND'
-    console.log(err.message); // 'Agent not found'
+    err.status;   // 404
+    err.code;     // 'AGENT_NOT_FOUND'
+    err.message;  // 'Agent invalid_id not found in the trust registry'
+    err.details;  // Additional context (optional)
   }
 }
 ```
 
-## Documentation
+| Error Code | Status | Meaning |
+|-----------|--------|---------|
+| `INVALID_CREDENTIALS` | 401 | Bad or expired API key |
+| `AGENT_NOT_FOUND` | 404 | Agent ID doesn't exist |
+| `PERMISSION_DENIED` | 403 | Agent lacks required scope |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `VALIDATION_ERROR` | 400 | Invalid request payload |
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| **Cryptographic Identity** | Ed25519 keypairs with SHA-256 fingerprints |
+| **7 Permission Scopes** | `read`, `write`, `execute`, `transact`, `communicate`, `delegate`, `elevate` |
+| **Immutable Audit Trail** | Append-only events with content hashing |
+| **Trust Scoring** | 5-factor algorithm producing a 0–100 score |
+| **Payload Signing** | Client-side Ed25519 via Web Crypto or Node.js crypto |
+| **Dual Runtime** | Node.js 18+ and modern browsers |
+| **Zero Dependencies** | Types bundled — nothing extra to install |
+| **ESM + CJS** | Dual module output for any bundler or runtime |
+
+---
+
+## Protocol
+
+This SDK implements the **[Vorim Agent Identity Protocol (VAIP)](https://github.com/Kzino/vorim-protocol)** — an open standard for AI agent identity, permissions, and cryptographic audit trails.
+
+VAIP defines 5 conformance levels, from basic identity to full cryptographic signing. The protocol is open-source under Apache 2.0 — anyone can implement it.
+
+Read the full specification: **[SPEC.md](https://github.com/Kzino/vorim-protocol/blob/main/SPEC.md)**
+
+---
 
-Full documentation at [vorim.dev/docs](https://vorim.dev/docs)
+## Requirements
+
+- **Node.js** 18+ or modern browser with Web Crypto API
+- **TypeScript** 5.0+ (optional but recommended)
+
+---
+
+## Links
+
+- **Website:** [vorim.ai](https://vorim.ai)
+- **Protocol Spec:** [github.com/Kzino/vorim-protocol](https://github.com/Kzino/vorim-protocol)
+- **npm:** [@vorim/sdk](https://www.npmjs.com/package/@vorim/sdk)
+- **X:** [@vorim_ai_x](https://x.com/vorim_ai_x)
+- **Issues:** [GitHub Issues](https://github.com/Kzino/vorim-protocol/issues)
+
+---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+Built by **[Vorim AI](https://vorim.ai)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vorim/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Official TypeScript SDK for Vorim AI — AI Agent Identity, Permissions & Audit",
   "type": "module",
   "main": "dist/index.cjs",