aira-sdk 0.1.3 → 0.3.0

package/dist/extras/trust.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Trust layer types and helpers shared across all framework integrations.
+ */
+import type { Aira } from "../client";
+/** Policy for automated trust checks before tool execution. */
+export interface TrustPolicy {
+    verifyCounterparty?: boolean;
+    minReputation?: number;
+    requireValidVc?: boolean;
+    blockRevokedVc?: boolean;
+    blockUnregistered?: boolean;
+}
+/** Result of a trust check against a counterparty agent. */
+export interface TrustContext {
+    counterpartyId?: string;
+    didResolved?: boolean;
+    did?: string;
+    vcValid?: boolean | null;
+    reputationScore?: number | null;
+    reputationTier?: string | null;
+    reputationWarning?: string;
+    blocked?: boolean;
+    blockReason?: string;
+    recommendation?: string;
+}
+/**
+ * Run a trust check against a counterparty agent.
+ *
+ * Advisory by default — populates TrustContext with warnings.
+ * Only blocks when `blockRevokedVc` is set and the VC is revoked,
+ * or when `blockUnregistered` is set and the DID cannot be resolved.
+ */
+export declare function checkTrust(client: Aira, policy: TrustPolicy, counterpartyId: string): Promise<TrustContext>;

package/dist/extras/trust.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Trust layer types and helpers shared across all framework integrations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkTrust = checkTrust;
+/**
+ * Run a trust check against a counterparty agent.
+ *
+ * Advisory by default — populates TrustContext with warnings.
+ * Only blocks when `blockRevokedVc` is set and the VC is revoked,
+ * or when `blockUnregistered` is set and the DID cannot be resolved.
+ */
+async function checkTrust(client, policy, counterpartyId) {
+    const ctx = {
+        counterpartyId,
+        blocked: false,
+    };
+    // Step 1: Resolve DID
+    if (policy.verifyCounterparty || policy.requireValidVc || policy.blockUnregistered) {
+        try {
+            const didResult = await client.resolveDid(`did:web:airaproof.com:agents:${counterpartyId}`);
+            ctx.didResolved = true;
+            ctx.did = didResult.did;
+        }
+        catch {
+            ctx.didResolved = false;
+            if (policy.blockUnregistered) {
+                ctx.blocked = true;
+                ctx.blockReason = `Agent '${counterpartyId}' DID could not be resolved`;
+                return ctx;
+            }
+            ctx.recommendation = `Could not resolve DID for '${counterpartyId}' — proceed with caution`;
+            return ctx;
+        }
+    }
+    // Step 2: Verify credential
+    if (policy.requireValidVc || policy.blockRevokedVc) {
+        try {
+            const cred = await client.getAgentCredential(counterpartyId);
+            const verification = await client.verifyCredential(cred);
+            const valid = verification.valid;
+            ctx.vcValid = valid;
+            if (!valid && policy.blockRevokedVc) {
+                ctx.blocked = true;
+                ctx.blockReason = `Agent '${counterpartyId}' has a revoked or invalid credential`;
+                return ctx;
+            }
+            if (!valid) {
+                ctx.recommendation = `Credential for '${counterpartyId}' is invalid — proceed with caution`;
+            }
+        }
+        catch {
+            ctx.vcValid = null;
+            if (policy.blockRevokedVc) {
+                ctx.recommendation = `Could not verify credential for '${counterpartyId}' — treating as unknown`;
+            }
+        }
+    }
+    // Step 3: Check reputation
+    if (policy.minReputation != null) {
+        try {
+            const rep = await client.getReputation(counterpartyId);
+            ctx.reputationScore = rep.score;
+            ctx.reputationTier = rep.tier;
+            if (ctx.reputationScore != null && ctx.reputationScore < policy.minReputation) {
+                ctx.reputationWarning = `Reputation ${ctx.reputationScore} is below minimum ${policy.minReputation}`;
+                ctx.recommendation = ctx.reputationWarning;
+            }
+        }
+        catch {
+            ctx.reputationScore = null;
+            ctx.reputationWarning = `Could not fetch reputation for '${counterpartyId}'`;
+        }
+    }
+    return ctx;
+}

package/dist/extras/vercel-ai.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Vercel AI SDK integration — middleware that notarizes tool calls and completions.
+ *
+ * Requires: ai (Vercel AI SDK, peer dependency)
+ *
+ * Usage:
+ *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
+ *   const middleware = new AiraVercelMiddleware(aira, "my-agent");
+ *   // Use as wrap around tool calls or stream callbacks
+ */
+import type { Aira } from "../client";
+import type { TrustPolicy, TrustContext } from "./trust";
+export type { TrustPolicy, TrustContext } from "./trust";
+export declare class AiraVercelMiddleware {
+    private client;
+    private agentId;
+    private modelId?;
+    private trustPolicy?;
+    constructor(client: Aira, agentId: string, options?: {
+        modelId?: string;
+        trustPolicy?: TrustPolicy;
+    });
+    /**
+     * Check trust for a counterparty agent before interacting.
+     * Advisory by default — only blocks on revoked VC or unregistered agent if configured.
+     */
+    checkTrust(counterpartyId: string): Promise<TrustContext>;
+    private notarize;
+    /** Call after a tool execution to notarize it. */
+    onToolCall(toolName: string, argKeys?: string[]): void;
+    /** Call after a tool returns to notarize the result. */
+    onToolResult(toolName: string, resultLength: number): void;
+    /** Call when a text generation step completes. */
+    onStepFinish(stepType: string, tokenCount?: number): void;
+    /** Call when the full generation completes. */
+    onFinish(finishReason: string, totalTokens?: number): void;
+    /**
+     * Returns a Vercel AI SDK-compatible callbacks object for streamText/generateText.
+     *
+     * Usage:
+     *   const result = await streamText({ ...opts, ...middleware.asCallbacks() });
+     */
+    asCallbacks(): Record<string, (...args: unknown[]) => void>;
+    /**
+     * Wraps a tool's execute function to auto-notarize calls and results.
+     */
+    wrapTool<T extends (...args: unknown[]) => unknown>(toolFn: T, toolName: string): T;
+}

package/dist/extras/vercel-ai.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Vercel AI SDK integration — middleware that notarizes tool calls and completions.
+ *
+ * Requires: ai (Vercel AI SDK, peer dependency)
+ *
+ * Usage:
+ *   import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
+ *   const middleware = new AiraVercelMiddleware(aira, "my-agent");
+ *   // Use as wrap around tool calls or stream callbacks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiraVercelMiddleware = void 0;
+const trust_1 = require("./trust");
+const MAX_DETAILS = 5000;
+class AiraVercelMiddleware {
+    client;
+    agentId;
+    modelId;
+    trustPolicy;
+    constructor(client, agentId, options) {
+        this.client = client;
+        this.agentId = agentId;
+        this.modelId = options?.modelId;
+        this.trustPolicy = options?.trustPolicy;
+    }
+    /**
+     * Check trust for a counterparty agent before interacting.
+     * Advisory by default — only blocks on revoked VC or unregistered agent if configured.
+     */
+    async checkTrust(counterpartyId) {
+        if (!this.trustPolicy) {
+            return { counterpartyId, blocked: false, recommendation: "No trust policy configured" };
+        }
+        return (0, trust_1.checkTrust)(this.client, this.trustPolicy, counterpartyId);
+    }
+    notarize(actionType, details) {
+        try {
+            const params = {
+                actionType,
+                details: details.slice(0, MAX_DETAILS),
+                agentId: this.agentId,
+            };
+            if (this.modelId)
+                params.modelId = this.modelId;
+            this.client.notarize(params).catch((e) => {
+                console.warn("Aira notarize failed (non-blocking):", e);
+            });
+        }
+        catch (e) {
+            console.warn("Aira notarize failed (non-blocking):", e);
+        }
+    }
+    /** Call after a tool execution to notarize it. */
+    onToolCall(toolName, argKeys = []) {
+        this.notarize("tool_call", `Tool '${toolName}' called. Arg keys: [${argKeys.join(", ")}]`);
+    }
+    /** Call after a tool returns to notarize the result. */
+    onToolResult(toolName, resultLength) {
+        this.notarize("tool_completed", `Tool '${toolName}' completed. Result length: ${resultLength} chars`);
+    }
+    /** Call when a text generation step completes. */
+    onStepFinish(stepType, tokenCount) {
+        this.notarize("step_completed", `Step '${stepType}' completed.${tokenCount != null ? ` Tokens: ${tokenCount}` : ""}`);
+    }
+    /** Call when the full generation completes. */
+    onFinish(finishReason, totalTokens) {
+        this.notarize("generation_completed", `Generation completed. Reason: ${finishReason}.${totalTokens != null ? ` Total tokens: ${totalTokens}` : ""}`);
+    }
+    /**
+     * Returns a Vercel AI SDK-compatible callbacks object for streamText/generateText.
+     *
+     * Usage:
+     *   const result = await streamText({ ...opts, ...middleware.asCallbacks() });
+     */
+    asCallbacks() {
+        return {
+            onStepFinish: (step) => {
+                const s = step;
+                this.onStepFinish(s?.stepType ?? "unknown", s?.usage?.totalTokens);
+            },
+            onFinish: (result) => {
+                const r = result;
+                this.onFinish(r?.finishReason ?? "unknown", r?.usage?.totalTokens);
+            },
+        };
+    }
+    /**
+     * Wraps a tool's execute function to auto-notarize calls and results.
+     */
+    wrapTool(toolFn, toolName) {
+        const self = this;
+        const wrapped = async function (...args) {
+            self.onToolCall(toolName, args.length > 0 && typeof args[0] === "object" && args[0] ? Object.keys(args[0]) : []);
+            const result = await toolFn.apply(this, args);
+            self.onToolResult(toolName, String(result).length);
+            return result;
+        };
+        return wrapped;
+    }
+}
+exports.AiraVercelMiddleware = AiraVercelMiddleware;

package/dist/extras/webhooks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Webhook signature verification and event parsing for Aira webhooks.
+ */
+/** Known Aira webhook event types. */
+export declare const WebhookEventType: {
+    readonly CASE_COMPLETE: "case.complete";
+    readonly CASE_REQUIRES_REVIEW: "case.requires_human_review";
+    readonly ACTION_NOTARIZED: "action.notarized";
+    readonly ACTION_AUTHORIZED: "action.authorized";
+    readonly AGENT_REGISTERED: "agent.registered";
+    readonly AGENT_DECOMMISSIONED: "agent.decommissioned";
+    readonly EVIDENCE_SEALED: "evidence.sealed";
+    readonly ESCROW_DEPOSITED: "escrow.deposited";
+    readonly ESCROW_RELEASED: "escrow.released";
+    readonly ESCROW_DISPUTED: "escrow.disputed";
+    readonly COMPLIANCE_SNAPSHOT: "compliance.snapshot_created";
+};
+export type WebhookEventTypeName = (typeof WebhookEventType)[keyof typeof WebhookEventType];
+/** Parsed webhook event. */
+export interface WebhookEvent {
+    eventType: string;
+    data: Record<string, unknown>;
+    timestamp?: string;
+    deliveryId?: string;
+}
+/**
+ * Verify webhook signature.
+ * Signature format: sha256={hex_digest}
+ */
+export declare function verifySignature(payload: Buffer | string, signature: string, secret: string): boolean;
+/**
+ * Parse raw webhook payload into a WebhookEvent.
+ */
+export declare function parseEvent(payload: Buffer | string): WebhookEvent;

package/dist/extras/webhooks.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Webhook signature verification and event parsing for Aira webhooks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEventType = void 0;
+exports.verifySignature = verifySignature;
+exports.parseEvent = parseEvent;
+const crypto_1 = require("crypto");
+/** Known Aira webhook event types. */
+exports.WebhookEventType = {
+    CASE_COMPLETE: "case.complete",
+    CASE_REQUIRES_REVIEW: "case.requires_human_review",
+    ACTION_NOTARIZED: "action.notarized",
+    ACTION_AUTHORIZED: "action.authorized",
+    AGENT_REGISTERED: "agent.registered",
+    AGENT_DECOMMISSIONED: "agent.decommissioned",
+    EVIDENCE_SEALED: "evidence.sealed",
+    ESCROW_DEPOSITED: "escrow.deposited",
+    ESCROW_RELEASED: "escrow.released",
+    ESCROW_DISPUTED: "escrow.disputed",
+    COMPLIANCE_SNAPSHOT: "compliance.snapshot_created",
+};
+/**
+ * Verify webhook signature.
+ * Signature format: sha256={hex_digest}
+ */
+function verifySignature(payload, signature, secret) {
+    if (!signature.startsWith("sha256="))
+        return false;
+    const payloadBuf = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+    const expected = (0, crypto_1.createHmac)("sha256", secret).update(payloadBuf).digest("hex");
+    const expectedSig = `sha256=${expected}`;
+    // Constant-time comparison
+    try {
+        return (0, crypto_1.timingSafeEqual)(Buffer.from(signature, "utf-8"), Buffer.from(expectedSig, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse raw webhook payload into a WebhookEvent.
+ */
+function parseEvent(payload) {
+    let data;
+    try {
+        data = JSON.parse(typeof payload === "string" ? payload : payload.toString("utf-8"));
+    }
+    catch (e) {
+        throw new Error(`Invalid webhook payload: ${e}`);
+    }
+    return {
+        eventType: data.event ?? "unknown",
+        data: data.data ?? data,
+        timestamp: data.timestamp,
+        deliveryId: data.delivery_id,
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { Aira } from "./client";
 export type { AiraOptions } from "./client";
+export { AiraSession } from "./session";
+export { OfflineQueue } from "./offline";
+export type { QueuedRequest } from "./offline";
 export { AiraError, type ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, } from "./types";

package/dist/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = exports.Aira = void 0;
+exports.AiraError = exports.OfflineQueue = exports.AiraSession = exports.Aira = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "Aira", { enumerable: true, get: function () { return client_1.Aira; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "AiraSession", { enumerable: true, get: function () { return session_1.AiraSession; } });
+var offline_1 = require("./offline");
+Object.defineProperty(exports, "OfflineQueue", { enumerable: true, get: function () { return offline_1.OfflineQueue; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "AiraError", { enumerable: true, get: function () { return types_1.AiraError; } });

package/dist/offline.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Offline queue for Aira SDK — queues actions locally, syncs later.
+ */
+export interface QueuedRequest {
+    id: string;
+    method: string;
+    path: string;
+    body: Record<string, unknown>;
+}
+export declare class OfflineQueue {
+    private items;
+    enqueue(method: string, path: string, body: Record<string, unknown>): string;
+    get pendingCount(): number;
+    clear(): void;
+    drain(): QueuedRequest[];
+}

package/dist/offline.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Offline queue for Aira SDK — queues actions locally, syncs later.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineQueue = void 0;
+const crypto_1 = require("crypto");
+class OfflineQueue {
+    items = [];
+    enqueue(method, path, body) {
+        const id = `offline_${(0, crypto_1.randomUUID)().replace(/-/g, "").slice(0, 12)}`;
+        this.items.push({ id, method, path, body });
+        return id;
+    }
+    get pendingCount() {
+        return this.items.length;
+    }
+    clear() {
+        this.items = [];
+    }
+    drain() {
+        const drained = [...this.items];
+        this.items = [];
+        return drained;
+    }
+}
+exports.OfflineQueue = OfflineQueue;

package/dist/session.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AiraSession — scoped session with pre-filled defaults.
+ */
+import type { Aira } from "./client";
+import type { ActionReceipt } from "./types";
+export declare class AiraSession {
+    private client;
+    private defaults;
+    constructor(client: Aira, agentId: string, defaults?: Record<string, unknown>);
+    notarize(params: {
+        actionType: string;
+        details: string;
+        modelId?: string;
+        modelVersion?: string;
+        instructionHash?: string;
+        parentActionId?: string;
+        storeDetails?: boolean;
+        idempotencyKey?: string;
+    }): Promise<ActionReceipt>;
+}

package/dist/session.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * AiraSession — scoped session with pre-filled defaults.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiraSession = void 0;
+class AiraSession {
+    client;
+    defaults;
+    constructor(client, agentId, defaults) {
+        this.client = client;
+        this.defaults = { agentId, ...(defaults ?? {}) };
+    }
+    async notarize(params) {
+        const merged = {
+            agentId: this.defaults.agentId,
+            ...(this.defaults.modelId ? { modelId: this.defaults.modelId } : {}),
+            ...(this.defaults.agentVersion ? { agentVersion: this.defaults.agentVersion } : {}),
+            ...params,
+        };
+        return this.client.notarize(merged);
+    }
+}
+exports.AiraSession = AiraSession;

package/package.json

@@ -1,9 +1,39 @@
 {
   "name": "aira-sdk",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "TypeScript SDK for Aira — legal infrastructure for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./extras/langchain": {
+      "types": "./dist/extras/langchain.d.ts",
+      "default": "./dist/extras/langchain.js"
+    },
+    "./extras/vercel-ai": {
+      "types": "./dist/extras/vercel-ai.d.ts",
+      "default": "./dist/extras/vercel-ai.js"
+    },
+    "./extras/openai-agents": {
+      "types": "./dist/extras/openai-agents.d.ts",
+      "default": "./dist/extras/openai-agents.js"
+    },
+    "./extras/mcp": {
+      "types": "./dist/extras/mcp.d.ts",
+      "default": "./dist/extras/mcp.js"
+    },
+    "./extras/webhooks": {
+      "types": "./dist/extras/webhooks.d.ts",
+      "default": "./dist/extras/webhooks.js"
+    },
+    "./extras": {
+      "types": "./dist/extras/index.d.ts",
+      "default": "./dist/extras/index.js"
+    }
+  },
   "files": [
     "dist"
   ],
@@ -21,7 +51,11 @@
     "notarization",
     "compliance",
     "eu-ai-act",
-    "cryptographic-receipts"
+    "cryptographic-receipts",
+    "langchain",
+    "vercel-ai",
+    "openai",
+    "mcp"
   ],
   "scripts": {
     "build": "tsc",
@@ -30,9 +64,30 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^2.0.0",
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   },
+  "peerDependencies": {
+    "@langchain/core": ">=0.2.0",
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "ai": ">=3.0.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   }