aira-sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,30 +1,22 @@
 # Aira TypeScript SDK
 
-**AI compliance infrastructure for AI agents.**
+**AI governance infrastructure.**
 
 [![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)
 
-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.
+Policies evaluate every agent action. Humans approve high-stakes decisions. Cryptographic receipts prove it all. Rules, AI, and multi-model consensus govern what your agents can do — with Ed25519 signatures, RFC 3161 timestamps, and W3C DID identity. Built for EU AI Act, SR 11-7, and GDPR compliance.
 
----
-
-## 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 |
+```bash
+npm install aira-sdk
+```
 
-Or install the core SDK alone:
+Framework integrations use sub-imports — just make sure the peer dependency is installed:
 
 ```bash
-npm install aira-sdk
+npm install aira-sdk langchain      # for LangChain.js
+npm install aira-sdk ai             # for Vercel AI
+npm install aira-sdk @openai/agents # for OpenAI Agents
 ```
 
 ---
@@ -53,154 +45,13 @@ console.log(receipt.action_id);       // uuid — publicly verifiable
 
 ---
 
-## 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
-import { Aira } from "aira-sdk";
-import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
-
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const handler = new AiraCallbackHandler({ client: aira, agentId: "research-agent", modelId: "gpt-4o" });
-
-// Every tool call and chain completion gets a signed receipt
-const result = await chain.invoke({ input: "Analyze Q1 revenue" }, { callbacks: [handler] });
-```
-
-### Vercel AI
-
-`AiraVercelMiddleware` wraps your Vercel AI `streamText` / `generateText` calls so every model invocation is notarized with a tamper-proof receipt.
-
-```typescript
-import { Aira } from "aira-sdk";
-import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
-
-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.
-
-```typescript
-import { createServer } from "aira-sdk/extras/mcp";
-
-const server = createServer({ apiKey: "aira_live_xxx" });
-server.listen(); // stdio transport
-```
-
-The server exposes three tools: `notarize_action`, `verify_action`, and `get_receipt` -- each producing cryptographically signed results.
-
-Add to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "aira": {
-      "command": "npx",
-      "args": ["aira-sdk", "mcp"],
-      "env": { "AIRA_API_KEY": "aira_live_xxx" }
-    }
-  }
-}
-```
-
----
-
-## 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 sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
-
-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" });
-```
-
----
-
-## Offline Mode
-
-Queue notarizations locally when connectivity is unavailable. Cryptographic receipts are generated server-side when you sync -- nothing is lost.
-
-```typescript
-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
-
-// Flush to API when back online — receipts are generated for each action
-const results = await aira.sync();
-```
-
----
-
-## Webhook Verification
-
-Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
-
-```typescript
-import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
-
-// 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
-}
-```
-
-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.
+All 52 methods on `Aira`. Every write operation produces a cryptographic receipt.
 
 | Category | Method | Description |
 |---|---|---|
-| **Actions** | `notarize()` | Notarize an action -- returns Ed25519-signed receipt |
+| **Actions** | `notarize()` | Notarize an action -- returns Ed25519-signed receipt (supports `requireApproval`) |
 | | `getAction()` | Retrieve action details + receipt |
 | | `listActions()` | List actions with filters (type, agent, status) |
 | | `authorizeAction()` | Human co-signature on high-stakes action |
@@ -224,15 +75,9 @@ All 56 methods on `Aira`. Every write operation produces a cryptographic receipt
 | | `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 |
@@ -320,6 +165,45 @@ console.log(rep.score);  // 84
 console.log(rep.tier);   // "Verified"
 ```
 
+### Endpoint Verification
+
+Control which external APIs your agents can call. When `endpointUrl` is passed to `notarize()`, Aira checks it against your org's whitelist. Unrecognized endpoints are blocked in strict mode.
+
+#### Notarize with endpointUrl
+
+```typescript
+const receipt = await aira.notarize({
+  actionType: "api_call",
+  details: "Charged customer $49.99 for subscription renewal",
+  agentId: "billing-agent",
+  modelId: "claude-sonnet-4-6",
+  endpointUrl: "https://api.stripe.com/v1/charges",
+});
+```
+
+#### Handle ENDPOINT_NOT_WHITELISTED
+
+```typescript
+import { Aira, AiraError } from "aira-sdk";
+
+try {
+  const receipt = await aira.notarize({
+    actionType: "api_call",
+    details: "Send SMS via new provider",
+    agentId: "notifications-agent",
+    endpointUrl: "https://api.newprovider.com/v1/sms",
+  });
+} catch (e) {
+  if (e instanceof AiraError && e.code === "ENDPOINT_NOT_WHITELISTED") {
+    console.log(`Blocked: ${e.message}`);
+    console.log(`Approval request: ${e.details.approval_id}`);
+    console.log(`Suggested pattern: ${e.details.url_pattern_suggested}`);
+  } else {
+    throw e;
+  }
+}
+```
+
 ### Trust Policy in Integrations
 
 Pass a `trustPolicy` to any framework integration to run automated trust checks before agent interactions:
@@ -328,7 +212,7 @@ Pass a `trustPolicy` to any framework integration to run automated trust checks
 import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
 
 const handler = new AiraCallbackHandler(aira, "research-agent", {
-  modelId: "gpt-4o",
+  modelId: "gpt-5.2",
   trustPolicy: {
     verifyCounterparty: true,    // resolve counterparty DID
     minReputation: 60,           // warn if reputation score below 60
@@ -341,6 +225,224 @@ const handler = new AiraCallbackHandler(aira, "research-agent", {
 
 ---
 
+## 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 sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
+
+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" });
+```
+
+---
+
+## Offline Mode
+
+Queue notarizations locally when connectivity is unavailable. Cryptographic receipts are generated server-side when you sync -- nothing is lost.
+
+```typescript
+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
+
+// Flush to API when back online — receipts are generated for each action
+const results = await aira.sync();
+```
+
+---
+
+## Human Approval
+
+Hold high-stakes actions for human review before the cryptographic receipt is issued. Approvers receive an email with Approve/Deny buttons.
+
+```typescript
+const receipt = await aira.notarize({
+  actionType: "loan_decision",
+  details: "Approved €15,000 loan for Maria Schmidt",
+  agentId: "lending-agent",
+  requireApproval: true,
+  approvers: ["compliance@acme.com", "risk@acme.com"],
+});
+console.log(receipt.status);      // "pending_approval"
+console.log(receipt.receipt_id);  // undefined — no receipt until approved
+
+// Falls back to org default approvers (Settings → Approvers)
+const receipt2 = await aira.notarize({
+  actionType: "wire_transfer",
+  details: "Transfer $50,000 to vendor account",
+  agentId: "payments-agent",
+  requireApproval: true,
+});
+```
+
+The approver clicks "Approve" in the email → receipt is minted with Ed25519 signature + RFC 3161 timestamp → `action.approved` webhook fires.
+
+Configure default approvers in the [dashboard](https://app.airaproof.com/dashboard/settings/approvers) or via the `/approvers` API.
+
+### Automatic Policy Evaluation
+
+Org admins configure policies in the dashboard — your code doesn't change. Every `notarize()` call is automatically evaluated against active policies before the receipt is issued.
+
+Three evaluation modes:
+
+- **Rules**: Deterministic conditions — instant, no LLM call
+- **AI**: Single LLM evaluates action against a natural language policy (1-5s)
+- **Consensus**: Multiple LLMs evaluate independently — disagreement triggers human review (3-10s)
+
+```typescript
+// Your code stays the same — policies evaluate automatically
+const receipt = await aira.notarize({
+  actionType: "wire_transfer",
+  details: "Transfer $50,000 to vendor account",
+  agentId: "billing-agent",
+});
+
+// If a policy triggers "require_approval":
+console.log(receipt.status);             // "pending_approval"
+console.log(receipt.policy_evaluation);  // { policy_name: "Wire transfers need approval", decision: "require_approval", ... }
+
+// If a policy triggers "deny":
+import { AiraError } from "aira-sdk";
+try {
+  await aira.notarize({ actionType: "data_deletion", details: "Delete customer records" });
+} catch (e) {
+  if (e instanceof AiraError && e.code === "POLICY_DENIED") {
+    console.log(e.message);  // "Action denied by policy 'Block deletions': ..."
+  }
+}
+```
+
+Every policy evaluation produces a cryptographic receipt — proof the policy was checked. The SDK `requireApproval: true` override still works and skips policy evaluation entirely.
+
+Configure policies at [Settings → Policies](https://app.airaproof.com/dashboard/policies).
+
+---
+
+## Framework Integrations
+
+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 |
+
+### LangChain.js
+
+`AiraCallbackHandler` notarizes every tool call, chain completion, and LLM invocation with a cryptographic receipt. No changes to your chain logic.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
+
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const handler = new AiraCallbackHandler({ client: aira, agentId: "research-agent", modelId: "gpt-5.2" });
+
+// Every tool call and chain completion gets a signed receipt
+const result = await chain.invoke({ input: "Analyze Q1 revenue" }, { callbacks: [handler] });
+```
+
+### Vercel AI
+
+`AiraVercelMiddleware` wraps your Vercel AI `streamText` / `generateText` calls so every model invocation is notarized with a tamper-proof receipt.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
+
+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-5.2"),
+  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.
+
+```typescript
+import { createServer } from "aira-sdk/extras/mcp";
+
+const server = createServer({ apiKey: "aira_live_xxx" });
+server.listen(); // stdio transport
+```
+
+The server exposes three tools: `notarize_action`, `verify_action`, and `get_receipt` -- each producing cryptographically signed results.
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "aira": {
+      "command": "npx",
+      "args": ["aira-sdk", "mcp"],
+      "env": { "AIRA_API_KEY": "aira_live_xxx" }
+    }
+  }
+}
+```
+
+---
+
+## Webhook Verification
+
+Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
+
+```typescript
+import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
+
+// 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
+}
+```
+
+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`.
+
+---
+
 ## Error Handling
 
 ```typescript

package/dist/client.d.ts

@@ -29,6 +29,8 @@ export declare class Aira {
         parentActionId?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
+        requireApproval?: boolean;
+        approvers?: string[];
     }): Promise<ActionReceipt>;
     getAction(actionId: string): Promise<ActionDetail>;
     listActions(params?: {

package/dist/client.js

@@ -91,6 +91,8 @@ class Aira {
             parent_action_id: params.parentActionId,
             store_details: params.storeDetails || undefined,
             idempotency_key: params.idempotencyKey,
+            require_approval: params.requireApproval || undefined,
+            approvers: params.approvers,
         });
         return this.post("/actions", body);
     }
@@ -259,7 +261,7 @@ class Aira {
     }
     // ==================== Chat ====================
     async ask(message, params) {
-        return this.post("/chat", buildBody({ message, history: params?.history, model: params?.model }));
+        return this.post("/chat", buildBody({ message, history: params?.history, model_id: params?.model }));
     }
     // ==================== DID ====================
     /** Get full DID info for an agent. */

package/dist/session.d.ts

@@ -16,5 +16,7 @@ export declare class AiraSession {
         parentActionId?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
+        requireApproval?: boolean;
+        approvers?: string[];
     }): Promise<ActionReceipt>;
 }

package/dist/types.d.ts

@@ -1,12 +1,23 @@
 /** Cryptographic receipt from notarizing an action. */
 export interface ActionReceipt {
     action_id: string;
+    receipt_id: string;
     payload_hash: string;
     signature: string;
-    receipt_id: string;
-    action_type: string;
-    agent_id: string | null;
+    timestamp_token: string | null;
     created_at: string;
+    request_id: string;
+    status?: string;
+    action_type?: string;
+    agent_id?: string | null;
+    warnings?: string[] | null;
+    policy_evaluation?: {
+        policy_id: string;
+        policy_name: string;
+        decision: string;
+        reasoning: string | null;
+        confidence: number | null;
+    } | null;
 }
 /** Full action details including receipt and authorizations. */
 export interface ActionDetail {
@@ -66,46 +77,62 @@ export interface EvidencePackage {
     id: string;
     title: string;
     description: string | null;
+    action_ids: string[];
     package_hash: string;
     signature: string;
-    action_count: number;
+    status: string;
     created_at: string;
+    request_id: string;
+    agent_slugs?: string[] | null;
 }
 /** Compliance snapshot. */
 export interface ComplianceSnapshot {
     id: string;
     framework: string;
-    agent_slug: string | null;
-    findings: Record<string, string>;
     status: string;
+    findings: Record<string, string>;
+    snapshot_hash: string;
+    signature: string;
+    snapshot_at: string;
     created_at: string;
+    request_id: string;
+    agent_id?: string | null;
 }
 /** Escrow account. */
 export interface EscrowAccount {
     id: string;
-    status: string;
     currency: string;
     balance: string;
-    purpose: string | null;
+    status: string;
     created_at: string;
+    request_id: string;
+    agent_id?: string | null;
+    counterparty_org_id?: string | null;
+    purpose?: string | null;
+    transactions?: EscrowTransaction[];
 }
 /** Escrow transaction (deposit, release, dispute). */
 export interface EscrowTransaction {
     id: string;
     transaction_type: string;
     amount: string;
-    description: string | null;
+    currency: string;
     transaction_hash: string;
     signature: string;
+    status: string;
     created_at: string;
+    description?: string | null;
+    reference_action_id?: string | null;
 }
 /** Public verification result. */
 export interface VerifyResult {
     valid: boolean;
-    receipt_id: string | null;
-    verified_at: string;
     public_key_id: string;
     message: string;
+    verified_at: string;
+    request_id: string;
+    receipt_id?: string | null;
+    action_id?: string | null;
 }
 /** Paginated list response. */
 export interface PaginatedList<T = Record<string, unknown>> {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aira-sdk",
-  "version": "0.3.0",
-  "description": "TypeScript SDK for Aira — legal infrastructure for AI agents",
+  "version": "0.4.0",
+  "description": "TypeScript SDK for Aira — AI governance infrastructure",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {