aira-sdk 0.1.3 → 0.3.0

package/README.md

@@ -1,171 +1,346 @@
 # Aira TypeScript SDK
 
-**Legal infrastructure for AI agents.** Cryptographic proof for every action your AI agent takes.
+**AI compliance infrastructure for AI agents.**
 
-Aira provides the accountability layer that autonomous AI agents need to operate in regulated environments. Every action is notarized with Ed25519 signatures and RFC 3161 timestamps — producing court-admissible proof that an action happened, who authorized it, and what decision was made.
+[![npm version](https://img.shields.io/npm/v/aira-sdk.svg)](https://www.npmjs.com/package/aira-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**What you get:**
-- **Notarize actions** — cryptographic receipts for every agent decision, email, transaction
-- **Register agents** — verifiable identity with versioned configs and public profiles
-- **Multi-model consensus** — run the same decision through multiple AI models, flag disagreements
-- **Evidence packages** — sealed, tamper-proof bundles for legal discovery and audit
-- **Agent lifecycle** — wills, succession plans, death certificates, compliance snapshots
-- **Liability commitments** — record accountability commitments with cryptographic proof
-- **Human authorization** — require human co-signatures on high-stakes actions
-- **Public verification** — anyone can verify a receipt without an account
+Aira produces cryptographic receipts for every action your AI agent takes. Ed25519 signatures and RFC 3161 timestamps create tamper-proof, court-admissible proof of what happened, who authorized it, and which model made the decision. Built for EU AI Act, SR 11-7, and GDPR compliance.
 
-Built for EU AI Act, SR 11-7, and GDPR compliance. Self-hostable. Open-source SDK.
+---
 
-[![npm version](https://img.shields.io/npm/v/aira-sdk.svg)](https://www.npmjs.com/package/aira-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+## Integration Matrix
+
+Drop Aira into your existing agent framework with one import:
+
+| Framework | Import | Integration |
+|---|---|---|
+| **LangChain.js** | `import { AiraCallbackHandler } from "aira-sdk/extras/langchain"` | Callback handler |
+| **Vercel AI** | `import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai"` | Middleware |
+| **OpenAI Agents** | `import { AiraGuardrail } from "aira-sdk/extras/openai-agents"` | Guardrail |
+| **MCP** | `import { createServer } from "aira-sdk/extras/mcp"` | MCP Server |
+| **Webhooks** | `import { verifySignature } from "aira-sdk/extras/webhooks"` | Verification |
+
+Or install the core SDK alone:
 
 ```bash
 npm install aira-sdk
 ```
 
+---
+
 ## Quick Start
 
+Every call to `notarize()` returns a cryptographic receipt -- Ed25519-signed, timestamped, tamper-proof.
+
 ```typescript
 import { Aira } from "aira-sdk";
 
 const aira = new Aira({ apiKey: "aira_live_xxx" });
 
-// Notarize an agent action
 const receipt = await aira.notarize({
   actionType: "email_sent",
   details: "Sent onboarding email to customer@example.com",
   agentId: "support-agent",
   modelId: "claude-sonnet-4-6",
+  instructionHash: "sha256:a1b2c3...",
 });
 
-console.log(receipt.signature);  // ed25519:base64url...
-console.log(receipt.action_id);  // uuid
+console.log(receipt.payload_hash);   // sha256:e5f6a7b8...
+console.log(receipt.signature);       // ed25519:base64url...
+console.log(receipt.action_id);       // uuid — publicly verifiable
 ```
 
-## Agent Registry
+---
+
+## Framework Integrations
+
+### LangChain.js
+
+`AiraCallbackHandler` notarizes every tool call, chain completion, and LLM invocation with a cryptographic receipt. No changes to your chain logic.
 
 ```typescript
-const agent = await aira.registerAgent({
-  agentSlug: "lending-agent",
-  displayName: "Loan Decision Engine",
-  capabilities: ["credit_scoring", "risk_assessment"],
-  public: true,
-});
+import { Aira } from "aira-sdk";
+import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
 
-await aira.publishVersion("lending-agent", {
-  version: "1.0.0",
-  modelId: "claude-sonnet-4-6",
-  changelog: "Initial release",
-});
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const handler = new AiraCallbackHandler({ client: aira, agentId: "research-agent", modelId: "gpt-4o" });
 
-const agents = await aira.listAgents();
-console.log(agents.total);  // 5
+// Every tool call and chain completion gets a signed receipt
+const result = await chain.invoke({ input: "Analyze Q1 revenue" }, { callbacks: [handler] });
 ```
 
-## Action Notarization
+### Vercel AI
+
+`AiraVercelMiddleware` wraps your Vercel AI `streamText` / `generateText` calls so every model invocation is notarized with a tamper-proof receipt.
 
 ```typescript
-// Notarize with chain of custody
-const decision = await aira.notarize({
-  actionType: "loan_approved",
-  details: "Approved loan #4521 for €25,000",
-  agentId: "lending-agent",
-  modelId: "claude-sonnet-4-6",
-  idempotencyKey: "loan-4521",
-});
+import { Aira } from "aira-sdk";
+import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
 
-// Chain a follow-up action
-const email = await aira.notarize({
-  actionType: "email_sent",
-  details: "Sent approval notification",
-  agentId: "lending-agent",
-  parentActionId: decision.action_id,
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const middleware = new AiraVercelMiddleware({ client: aira, agentId: "assistant-agent" });
+
+// Wrap your Vercel AI calls — receipts at invocation and completion
+const result = await middleware.wrapGenerateText({
+  model: openai("gpt-4o"),
+  prompt: "Summarize the contract terms",
 });
+```
+
+### OpenAI Agents SDK
+
+`AiraGuardrail` wraps any tool function to automatically notarize both invocation and result with cryptographic proof.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
+
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const guardrail = new AiraGuardrail({ client: aira, agentId: "assistant-agent" });
+
+// Wrap tools — every call and result gets a signed receipt
+const search = guardrail.wrapTool(searchTool, { toolName: "web_search" });
+const execute = guardrail.wrapTool(codeExecutor, { toolName: "code_exec" });
+```
+
+---
+
+## MCP Server
+
+Expose Aira as an MCP tool server. Any MCP-compatible AI agent can notarize actions and verify receipts without SDK integration.
 
-// Get chain of custody
-const chain = await aira.getActionChain(decision.action_id);
+```typescript
+import { createServer } from "aira-sdk/extras/mcp";
+
+const server = createServer({ apiKey: "aira_live_xxx" });
+server.listen(); // stdio transport
+```
 
-// Human co-signature
-await aira.authorizeAction(decision.action_id);
+The server exposes three tools: `notarize_action`, `verify_action`, and `get_receipt` -- each producing cryptographically signed results.
 
-// Legal hold
-await aira.setLegalHold(decision.action_id);
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "aira": {
+      "command": "npx",
+      "args": ["aira-sdk", "mcp"],
+      "env": { "AIRA_API_KEY": "aira_live_xxx" }
+    }
+  }
+}
 ```
 
-## Multi-Model Consensus
+---
+
+## Session
+
+Pre-fill defaults for a block of related actions. Every `notarize()` call within the session inherits the agent identity, producing receipts that share a common provenance chain.
 
 ```typescript
-const result = await aira.runCase(
-  "Should we approve loan #4521?",
-  ["claude-sonnet-4-6", "gpt-4o", "gemini-2.0-flash"],
-);
+const sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
 
-console.log(result.consensus.decision);     // "APPROVE"
-console.log(result.consensus.confidence);   // 0.92
+await sess.notarize({ actionType: "identity_verified", details: "Verified customer ID #4521" });
+await sess.notarize({ actionType: "account_created", details: "Created account for customer #4521" });
+await sess.notarize({ actionType: "welcome_sent", details: "Sent welcome email to customer #4521" });
 ```
 
-## Evidence Packages
+---
+
+## Offline Mode
+
+Queue notarizations locally when connectivity is unavailable. Cryptographic receipts are generated server-side when you sync -- nothing is lost.
 
 ```typescript
-const pkg = await aira.createEvidencePackage({
-  title: "Q1 2026 Lending Audit",
-  actionIds: [decision.action_id, email.action_id],
-  description: "All lending decisions for regulatory review",
-});
+const aira = new Aira({ apiKey: "aira_live_xxx", offline: true });
+
+// These queue locally — no network calls
+await aira.notarize({ actionType: "scan_completed", details: "Scanned document batch #77" });
+await aira.notarize({ actionType: "classification_done", details: "Classified 142 documents" });
+
+console.log(aira.pendingCount);  // 2
 
-console.log(pkg.package_hash);  // sha256:...
-console.log(pkg.signature);    // ed25519:...
+// Flush to API when back online — receipts are generated for each action
+const results = await aira.sync();
 ```
 
-## Agent Will & Estate
+---
+
+## Webhook Verification
+
+Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
 
 ```typescript
-await aira.setAgentWill("lending-agent", {
-  successorSlug: "lending-agent-v2",
-  successionPolicy: "transfer_to_successor",
-  dataRetentionDays: 2555,
-  notifyEmails: ["compliance@acme.com"],
-});
+import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
 
-await aira.createComplianceSnapshot({
-  framework: "eu-ai-act",
-  agentSlug: "lending-agent",
-  findings: { art_12_logging: "pass", art_14_oversight: "pass" },
+// Verify the webhook signature (HMAC-SHA256)
+const isValid = verifySignature({
+  payload: request.body,
+  signature: request.headers["x-aira-signature"],
+  secret: "whsec_xxx",
 });
+
+if (isValid) {
+  const event = parseEvent(request.body);
+  console.log(event.eventType);    // "action.notarized"
+  console.log(event.data);         // Action data with cryptographic receipt
+  console.log(event.deliveryId);   // Unique delivery ID
+}
 ```
 
-## Escrow (Liability Commitments)
+Supported event types: `action.notarized`, `action.authorized`, `agent.registered`, `agent.decommissioned`, `evidence.sealed`, `escrow.deposited`, `escrow.released`, `escrow.disputed`, `compliance.snapshot_created`, `case.complete`, `case.requires_human_review`.
+
+---
+
+## Core SDK Methods
+
+All 56 methods on `Aira`. Every write operation produces a cryptographic receipt.
+
+| Category | Method | Description |
+|---|---|---|
+| **Actions** | `notarize()` | Notarize an action -- returns Ed25519-signed receipt |
+| | `getAction()` | Retrieve action details + receipt |
+| | `listActions()` | List actions with filters (type, agent, status) |
+| | `authorizeAction()` | Human co-signature on high-stakes action |
+| | `setLegalHold()` | Prevent deletion -- litigation hold |
+| | `releaseLegalHold()` | Release litigation hold |
+| | `getActionChain()` | Chain of custody for an action |
+| | `verifyAction()` | Public verification -- no auth required |
+| **Agents** | `registerAgent()` | Register verifiable agent identity |
+| | `getAgent()` | Retrieve agent profile |
+| | `listAgents()` | List registered agents |
+| | `updateAgent()` | Update agent metadata |
+| | `publishVersion()` | Publish versioned agent config |
+| | `listVersions()` | List agent versions |
+| | `decommissionAgent()` | Decommission agent |
+| | `transferAgent()` | Transfer ownership to another org |
+| | `getAgentActions()` | List actions by agent |
+| **Trust Layer** | `getAgentDid()` | Retrieve agent's W3C DID (`did:web`) |
+| | `rotateAgentKeys()` | Rotate agent's Ed25519 signing keys |
+| | `getAgentCredential()` | Get agent's W3C Verifiable Credential |
+| | `verifyCredential()` | Verify a Verifiable Credential |
+| | `revokeCredential()` | Revoke agent's Verifiable Credential |
+| | `requestMutualSign()` | Initiate mutual notarization with counterparty |
+| | `completeMutualSign()` | Complete mutual notarization (counterparty signs) |
+| | `getMutualSignStatus()` | Check status of a mutual sign request |
+| | `getReputation()` | Get agent reputation score and tier |
+| | `listReputationHistory()` | List reputation score history |
+| | `setEndpointPolicy()` | Set endpoint verification policy |
+| | `getEndpointPolicy()` | Get current endpoint policy |
+| | `resolveDid()` | Resolve any DID to its DID Document |
+| | `checkTrust()` | Run full trust check against a counterparty |
+| | `listCredentials()` | List all credentials for an agent |
+| | `getTrustBundle()` | Get DID + VC + reputation in one call |
+| **Cases** | `runCase()` | Multi-model consensus adjudication |
+| | `getCase()` | Retrieve case result |
+| | `listCases()` | List cases |
+| **Receipts** | `getReceipt()` | Retrieve cryptographic receipt |
+| | `exportReceipt()` | Export receipt as JSON or PDF |
+| **Evidence** | `createEvidencePackage()` | Sealed, tamper-proof evidence bundle |
+| | `listEvidencePackages()` | List evidence packages |
+| | `getEvidencePackage()` | Retrieve evidence package |
+| | `timeTravel()` | Query actions at a point in time |
+| | `liabilityChain()` | Walk full liability chain |
+| **Estate** | `setAgentWill()` | Define succession plan |
+| | `getAgentWill()` | Retrieve agent will |
+| | `issueDeathCertificate()` | Decommission with succession trigger |
+| | `getDeathCertificate()` | Retrieve death certificate |
+| | `createComplianceSnapshot()` | Compliance snapshot (EU AI Act, SR 11-7, GDPR) |
+| | `listComplianceSnapshots()` | List snapshots by framework |
+| **Escrow** | `createEscrowAccount()` | Create liability commitment ledger |
+| | `listEscrowAccounts()` | List escrow accounts |
+| | `getEscrowAccount()` | Retrieve escrow account |
+| | `escrowDeposit()` | Record liability commitment |
+| | `escrowRelease()` | Release commitment after completion |
+| | `escrowDispute()` | Dispute -- flag liability issue |
+| **Chat** | `ask()` | Query your notarized data via AI |
+| **Offline** | `sync()` | Flush offline queue to API |
+| **Session** | `session()` | Scoped session with pre-filled defaults |
+
+---
+
+## Trust Layer
+
+Standards-based identity and trust for agents: W3C DIDs, Verifiable Credentials, mutual notarization, and reputation scoring. Every agent gets a cryptographically verifiable identity that other agents (and humans) can check before interacting.
+
+### DID Identity
+
+Every registered agent gets a W3C-compliant DID (`did:web`):
 
-Escrow accounts are **accountability ledgers** — they record liability commitments with cryptographic proof. No real funds are custodied by Aira.
+```typescript
+// Retrieve the agent's DID
+const did = await aira.getAgentDid("my-agent");
+console.log(did);  // "did:web:airaproof.com:agents:my-agent"
+
+// Rotate signing keys (old keys are revoked, new keys are published)
+await aira.rotateAgentKeys("my-agent");
+```
+
+### Verifiable Credentials
 
 ```typescript
-const account = await aira.createEscrowAccount({ purpose: "Loan liability" });
-await aira.escrowDeposit(account.id, 15000, "Liability commitment for loan #4521");
-await aira.escrowRelease(account.id, 15000, "Loan disbursed successfully");
+// Get the agent's W3C Verifiable Credential
+const vc = await aira.getAgentCredential("my-agent");
+
+// Verify any VC (returns validity, issuer, expiry)
+const result = await aira.verifyCredential(vc);
+console.log(result.valid);  // true
+
+// Revoke a credential
+await aira.revokeCredential("my-agent", { reason: "Agent deprecated" });
 ```
 
-## Chat
+### Mutual Notarization
+
+For high-stakes actions, both parties co-sign:
 
 ```typescript
-const response = await aira.ask("How many loan decisions were notarized this week?", {
-  model: "claude-sonnet-4-6",
+// Agent A initiates — sends a signing request to the counterparty
+const request = await aira.requestMutualSign({
+  actionId: "act-uuid",
+  counterpartyDid: "did:web:partner.com:agents:their-agent",
+});
+
+// Agent B completes — signs the same payload
+const receipt = await aira.completeMutualSign({
+  actionId: "act-uuid",
+  did: "did:web:partner.com:agents:their-agent",
+  signature: "z...",
+  signedPayloadHash: "sha256:...",
 });
-console.log(response.content);
 ```
 
-The `model` parameter is optional. If omitted, the organization's default chat model is used.
+### Reputation
+
+```typescript
+const rep = await aira.getReputation("my-agent");
+console.log(rep.score);  // 84
+console.log(rep.tier);   // "Verified"
+```
 
-> A default chat model must be configured in your dashboard (Settings → Models) before using `ask()` without an explicit model.
+### Trust Policy in Integrations
 
-## Public Verification
+Pass a `trustPolicy` to any framework integration to run automated trust checks before agent interactions:
 
 ```typescript
-// No auth needed — anyone can verify
-const result = await aira.verifyAction("action-uuid");
-console.log(result.valid);    // true
-console.log(result.message);  // "Action receipt exists..."
+import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
+
+const handler = new AiraCallbackHandler(aira, "research-agent", {
+  modelId: "gpt-4o",
+  trustPolicy: {
+    verifyCounterparty: true,    // resolve counterparty DID
+    minReputation: 60,           // warn if reputation score below 60
+    requireValidVc: true,        // check Verifiable Credential validity
+    blockRevokedVc: true,        // block if counterparty VC is revoked
+    blockUnregistered: false,    // don't block agents without Aira DIDs
+  },
+});
 ```
 
+---
+
 ## Error Handling
 
 ```typescript
@@ -182,24 +357,54 @@ try {
 }
 ```
 
+All framework integrations (LangChain.js, Vercel AI, OpenAI Agents) are non-blocking by default -- notarization failures are logged, never raised. Your agent keeps running.
+
+---
+
 ## Configuration
 
 ```typescript
 const aira = new Aira({
-  apiKey: "aira_live_xxx",
-  baseUrl: "https://your-self-hosted.com",  // Self-hosted
-  timeout: 60_000,                           // Request timeout in ms
+  apiKey: "aira_live_xxx",                      // Required — aira_live_ or aira_test_ prefix
+  baseUrl: "https://your-self-hosted.com",      // Self-hosted deployment
+  timeout: 60_000,                              // Request timeout in ms
+  offline: true,                                // Queue locally, sync later
 });
 ```
 
-## License
+| Env Variable | Description |
+|---|---|
+| `AIRA_API_KEY` | API key (used by MCP server) |
+
+---
+
+## SDK Parity
+
+| Feature | Python | TypeScript |
+|---|---|---|
+| Core API (45+ methods) | Yes | Yes |
+| Trust Layer (DID, VC, Reputation) | Yes | Yes |
+| LangChain | Yes | Yes |
+| CrewAI | Yes | -- (Python-only) |
+| Vercel AI | -- (JS-only) | Yes |
+| OpenAI Agents | Yes | Yes |
+| Google ADK | Yes (Python-only) | -- |
+| AWS Bedrock | Yes (Python-only) | -- |
+| MCP Server | Yes | Yes |
+| Webhooks | Yes | Yes |
+| CLI | Yes | -- (use Python CLI) |
+| Offline Mode | Yes | Yes |
+| Session | Yes | Yes |
 
-MIT
+---
 
 ## Links
 
-- [Interactive Demo](https://app.airaproof.com/demo) — try Aira in your browser, no code needed
+- [Website](https://airaproof.com)
+- [npm Package](https://www.npmjs.com/package/aira-sdk)
+- [Python SDK (PyPI)](https://pypi.org/project/aira-sdk/)
 - [Documentation](https://docs.airaproof.com)
 - [API Reference](https://docs.airaproof.com/docs/api-reference)
-- [Python SDK](https://pypi.org/project/aira-sdk/)
+- [Interactive Demo](https://app.airaproof.com/demo) -- try Aira in your browser, no code needed
 - [Dashboard](https://app.airaproof.com)
+- [GitHub](https://github.com/aira-proof/typescript-sdk)

package/dist/client.d.ts

@@ -1,13 +1,16 @@
 import { ActionReceipt, ActionDetail, AgentDetail, AgentVersion, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList } from "./types";
+import { AiraSession } from "./session";
 export interface AiraOptions {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
+    offline?: boolean;
 }
 export declare class Aira {
     private baseUrl;
     private apiKey;
     private timeout;
+    private queue;
     constructor(options: AiraOptions);
     private request;
     private get;
@@ -126,4 +129,42 @@ export declare class Aira {
         tools_used: string[];
         model_id?: string;
     }>;
+    /** Get full DID info for an agent. */
+    getAgentDid(slug: string): Promise<Record<string, unknown>>;
+    /** Rotate an agent's DID keypair. */
+    rotateAgentKeys(slug: string): Promise<Record<string, unknown>>;
+    /** Resolve any did:web DID to its DID document. */
+    resolveDid(did: string): Promise<Record<string, unknown>>;
+    /** Get the current valid VC for an agent. */
+    getAgentCredential(slug: string): Promise<Record<string, unknown>>;
+    /** Get full credential history for an agent. */
+    getAgentCredentials(slug: string): Promise<Record<string, unknown>>;
+    /** Revoke the current credential for an agent. */
+    revokeCredential(slug: string, reason?: string): Promise<Record<string, unknown>>;
+    /** Verify a Verifiable Credential — checks signature, expiry, revocation. */
+    verifyCredential(credential: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Initiate a mutual signing request for an action. */
+    requestMutualSign(actionId: string, counterpartyDid: string): Promise<Record<string, unknown>>;
+    /** Get the action payload awaiting counterparty signature. */
+    getPendingMutualSign(actionId: string): Promise<Record<string, unknown>>;
+    /** Submit counterparty signature to complete mutual signing. */
+    completeMutualSign(actionId: string, did: string, signature: string, signedPayloadHash: string): Promise<Record<string, unknown>>;
+    /** Get the co-signed receipt for a mutually signed action. */
+    getMutualSignReceipt(actionId: string): Promise<Record<string, unknown>>;
+    /** Reject a mutual signing request. */
+    rejectMutualSign(actionId: string, reason?: string): Promise<Record<string, unknown>>;
+    /** Get current reputation score for an agent. */
+    getReputation(slug: string): Promise<Record<string, unknown>>;
+    /** Get full reputation history for an agent. */
+    getReputationHistory(slug: string): Promise<Record<string, unknown>>;
+    /** Submit a signed attestation of a successful interaction. */
+    attestReputation(slug: string, counterpartyDid: string, actionId: string, attestation: string, signature: string): Promise<Record<string, unknown>>;
+    /** Verify a reputation score by returning inputs and score_hash. */
+    verifyReputation(slug: string): Promise<Record<string, unknown>>;
+    /** Create a scoped session with pre-filled defaults. */
+    session(agentId: string, defaults?: Record<string, unknown>): AiraSession;
+    /** Number of queued offline requests. */
+    get pendingCount(): number;
+    /** Flush offline queue to API. Returns list of API responses. */
+    sync(): Promise<Record<string, unknown>[]>;
 }