aira-sdk 3.2.0 → 3.5.0

package/README.md

@@ -1,500 +1,122 @@
-# Aira TypeScript SDK — The authorization and audit layer for AI agents.
+# Aira TypeScript 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)
-
-Drop Aira into your agent stack in one line. Define policies without changing code. Get cryptographic proof of every decision — for your auditors, your board, or a court. Not because regulation requires it. Because your agents are acting in production right now.
-
-```bash
+[![License: MIT](https://img.shields.io/npm/l/aira-sdk)](LICENSE)
+[![Node](https://img.shields.io/node/v/aira-sdk)](package.json)
+
+Authorize every AI agent action before it runs. Sign every outcome with Ed25519.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Core methods](#core-methods)
+- [Gateway](#gateway)
+- [Framework integrations](#framework-integrations)
+  - [LangChain.js](#langchainjs)
+  - [Vercel AI SDK](#vercel-ai-sdk)
+  - [OpenAI Agents SDK](#openai-agents-sdk)
+  - [MCP](#mcp)
+- [Content scanning](#content-scanning)
+- [Compliance & DORA](#compliance--dora)
+- [Self-hosted](#self-hosted)
+- [Links](#links)
+
+## Installation
+
+```sh
 npm install aira-sdk
 ```
 
-Framework integrations use sub-imports — just make sure the peer dependency is installed:
-
-```bash
-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
-```
-
----
-
-## Quick Start
-
-Aira uses a **two-step flow**: `authorize()` BEFORE the action runs,
-`notarize()` AFTER. This lets you block disallowed actions before they have
-any real-world effect, and still produce a cryptographic receipt once the
-action has completed.
+## Quick start
 
 ```typescript
 import { Aira, AiraError } from "aira-sdk";
 
 const aira = new Aira({ apiKey: "aira_live_xxx" });
 
-try {
-  // Step 1 — ask Aira whether the action is allowed.
-  const auth = await aira.authorize({
-    actionType: "wire_transfer",
-    details: "Send €75K to vendor X",
-    agentId: "payments-agent",
-  });
-
-  if (auth.status === "authorized") {
-    // Step 2a — execute the action, then notarize the outcome.
-    const result = await sendWire(75_000, "vendor");
-    await aira.notarize({
-      actionId: auth.action_id,
-      outcome: "completed",
-      outcomeDetails: `Sent. ref=${result.id}`,
-    });
-  } else if (auth.status === "pending_approval") {
-    // Step 2b — enqueue for the approver flow; do NOT execute.
-    await queue.enqueue(auth.action_id);
-  }
-} catch (e) {
-  // Step 2c — a policy denied the action. Nothing to execute, nothing to
-  // notarize. POLICY_DENIED is thrown, never returned as a status.
-  if (e instanceof AiraError && e.code === "POLICY_DENIED") {
-    console.log(`Blocked: ${e.message}`);
-  } else {
-    throw e;
-  }
-}
-```
-
-The returned `ActionReceipt` carries the Ed25519 signature and RFC 3161
-timestamp token. If you pass `outcome: "failed"`, the backend still writes
-an audit entry but leaves `signature` / `receipt_id` null.
-
-### Reproducibility metadata (replay context)
-
-Pass any of the following optional fields to `authorize()` and they're committed in the signed receipt payload (v1.3) and surfaced via `getReplayContext()` so an external replay tool can confirm it has the same inputs as the original run:
-
-```typescript
+// 1. Authorize before the action runs
 const auth = await aira.authorize({
-  actionType: "tool_call",
-  details: "Calling search() with structured input",
-  agentId: "research-agent",
-  modelId: "claude-sonnet-4-6",
-  // Optional reproducibility metadata
-  systemPromptHash: "sha256:a1b2c3...",
-  toolInputsHash: "sha256:d4e5f6...",
-  modelParams: { temperature: 0.0, top_p: 1.0, seed: 42 },
-  executionEnv: {
-    sdk_version: "2.0.1",
-    framework: "langchain",
-    framework_version: "0.3.0",
-  },
-});
-```
-
----
-
-## Compliance bundles
-
-Seal a regulator-ready evidence bundle for a date range. Every receipt in the period is Merkle-rooted, signed, and the export is JWKS-verifiable offline.
-
-```typescript
-// Build a Q1 2026 EU AI Act Article 12 evidence packet
-const bundle = await aira.createComplianceBundle({
-  framework: "eu_ai_act_art12", // or iso_42001, aiuc_1, soc_2_cc7, raw
-  periodStart: "2026-01-01T00:00:00Z",
-  periodEnd: "2026-04-01T00:00:00Z",
-  title: "Q1 2026 evidence packet",
-  agentFilter: ["payments-agent", "support-agent"],
-});
-console.log(bundle.merkle_root, bundle.receipt_count);
-
-// Download the self-contained JSON for an auditor
-const exported = await aira.exportComplianceBundle(bundle.id as string);
-// `exported` includes every receipt, the JWKS URL, and a verification recipe.
-```
-
-## Drift detection
-
-Per-agent behavioral baselines + KL divergence scoring + alerts when an agent's behavior shifts away from its expected pattern.
-
-```typescript
-// Compute a baseline from the last 7 days of action history
-const end = new Date();
-const start = new Date(end.getTime() - 7 * 24 * 60 * 60 * 1000);
-
-await aira.computeDriftBaseline({
+  actionType: "wire_transfer",
+  details: "Send EUR 75K to vendor X",
   agentId: "payments-agent",
-  windowStart: start.toISOString(),
-  windowEnd: end.toISOString(),
 });
 
-// Or seed a baseline from a config dict (cold start)
-await aira.seedSyntheticBaseline({
-  agentId: "payments-agent",
-  expectedDistribution: { wire_transfer: 0.05, email_sent: 0.40, api_call: 0.55 },
-  expectedActionsPerDay: 200,
-});
-
-// Read-only status check for dashboards
-const status = await aira.getDriftStatus("payments-agent", 24);
-console.log(status.kl_divergence, status.severity);
-
-// Run a check that records an alert if the threshold is exceeded
-const alert = await aira.runDriftCheck("payments-agent");
-if (alert) console.log(`Drift detected: ${alert.severity}`);
-```
-
-## Merkle settlement
+// 2. Execute your business logic
+const result = await sendWire(75_000, "vendor");
 
-Periodic Merkle anchoring of action receipts. Every receipt eventually gets sealed into exactly one settlement; the settlement's Merkle root is the cryptographic commitment that the batch existed at a specific moment in time.
-
-```typescript
-// Admin: seal all unsettled receipts
-const settlement = await aira.createSettlement();
-if (settlement) {
-  console.log(settlement.merkle_root, settlement.receipt_count);
-}
-
-// An auditor wants to prove a single receipt was in a settlement
-const proof = await aira.getSettlementInclusionProof("rct-abc-123");
-// proof has { merkle_root, leaf_hash, index, leaf_count, siblings }
-// A regulator can verify it offline with a 10-line pure-function walker.
-```
-
----
-
-## Core SDK Methods
-
-Every write operation produces a cryptographic receipt.
-
-| Category | Method | Description |
-|---|---|---|
-| **Actions** | `authorize()` | Step 1 — authorize an action BEFORE it runs (throws POLICY_DENIED). Accepts optional replay context fields (`systemPromptHash`, `toolInputsHash`, `modelParams`, `executionEnv`). |
-| | `notarize()` | Step 2 — notarize the outcome, returns Ed25519-signed receipt |
-| | `getAction()` | Retrieve action details + receipt |
-| | `listActions()` | List actions with filters (type, agent, status) |
-| | `cosign()` | Human co-signature on a high-stakes action |
-| | `setLegalHold()` | Prevent deletion -- litigation hold |
-| | `releaseLegalHold()` | Release litigation hold |
-| | `getActionChain()` | Chain of custody for an action |
-| | `getReplayContext()` | All reproducibility metadata for an action (system prompt hash, tool inputs hash, model params, execution env) |
-| | `verifyAction()` | Public verification -- no auth required. Returns full evidence (signature, public key, signed payload, RFC 3161 token) plus the second-party `policy_evaluator_attestation` for multi-party signing. |
-| **Compliance** | `createComplianceBundle()` | Seal a regulator-ready evidence bundle for a date range. Frameworks: `eu_ai_act_art12`, `iso_42001`, `aiuc_1`, `soc_2_cc7`, `raw`. Merkle-rooted, signed, JWKS-verifiable offline. |
-| | `listComplianceBundles()` | List bundles for the org |
-| | `getComplianceBundle()` | Get bundle metadata |
-| | `exportComplianceBundle()` | Download the self-contained JSON for offline verification |
-| | `getBundleInclusionProof()` | Merkle inclusion proof for one receipt within a bundle |
-| **Drift** | `getDriftStatus()` | Read-only KL divergence + volume ratio against the active baseline |
-| | `computeDriftBaseline()` | Build a baseline from a window of production action history |
-| | `seedSyntheticBaseline()` | Seed a baseline from a config dict (cold start) |
-| | `runDriftCheck()` | Score the current window and persist a `DriftAlert` if it exceeds the threshold |
-| | `listDriftAlerts()` | List drift alerts for an agent |
-| | `acknowledgeDriftAlert()` | Acknowledge an alert |
-| **Settlement** | `createSettlement()` | Seal every unsettled receipt into a Merkle-rooted, signed batch (admin-only) |
-| | `listSettlements()` | List settlements |
-| | `getSettlement()` | Get settlement metadata |
-| | `getSettlementInclusionProof()` | Get a receipt's Merkle inclusion proof from its settlement |
-| **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) |
-| | `getReputation()` | Get agent reputation score and tier |
-| | `listReputationHistory()` | List reputation score history |
-| | `resolveDid()` | Resolve any DID to its DID Document |
-| **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`):
-
-```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
-// 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" });
-```
-
-### Mutual Notarization
-
-For high-stakes actions, both parties co-sign:
-
-```typescript
-// 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:...",
+// 3. Notarize the outcome -- returns an Ed25519-signed receipt
+const receipt = await aira.notarize({
+  actionId: auth.action_id,
+  outcome: "completed",
+  outcomeDetails: `Sent. ref=${result.id}`,
 });
 ```
 
-### Reputation
+If the policy denies the action, `authorize()` throws an `AiraError` with code `POLICY_DENIED`. Actions requiring human approval return `status: "pending_approval"` -- listen for the webhook or poll `getAction()`.
 
-```typescript
-const rep = await aira.getReputation("my-agent");
-console.log(rep.score);  // 84
-console.log(rep.tier);   // "Verified"
-```
+> **Universal receipts** — Every action — authorized, denied, or failed — produces an Ed25519 receipt. The audit trail has zero gaps.
 
-### Endpoint Verification
+## Core methods
 
-Control which external APIs your agents can call. When `endpointUrl` is
-passed to `authorize()`, Aira checks it against your org's whitelist
-before returning. Unrecognized endpoints throw `ENDPOINT_NOT_WHITELISTED`
-in strict mode — the action is never authorized and you never need to
-call `notarize()`.
+| Method | Description |
+| --- | --- |
+| `authorize()` | Gate an action **before** it runs |
+| `notarize()` | Sign the outcome **after** execution (Ed25519 + RFC 3161) |
+| `verifyAction()` | Verify a receipt -- no auth required |
+| `getAction()` / `listActions()` | Retrieve action details and history |
+| `cosign()` | Human co-signature on high-stakes actions |
+| `registerAgent()` / `getAgent()` | Verifiable agent identity (W3C DID) |
+| `createComplianceBundle()` | Regulator-ready evidence for a date range |
+| `computeDriftBaseline()` / `runDriftCheck()` | Behavioral drift detection (KL divergence) |
+| `createSettlement()` | Merkle-anchor a batch of receipts |
+| `runCase()` | Multi-model consensus adjudication |
+| `ask()` | Query your notarized data via AI |
+| `createComplianceReport()` | Generate a compliance report (EU AI Act, ISO 42001, SOC 2) |
+| `createDoraIncident()` | Report a DORA ICT incident |
+| `getOutputPolicy()` / `updateOutputPolicy()` | Content-scan policy for notarized outputs |
+| `getActionExplanation()` | Human-readable explanation of an action decision |
 
-```typescript
-import { Aira, AiraError } from "aira-sdk";
+60+ methods total. See the [API reference](https://docs.airaproof.com/docs/api-reference) for the full list.
 
-try {
-  const auth = await aira.authorize({
-    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",
-  });
-
-  if (auth.status === "authorized") {
-    const result = await stripe.charges.create({ amount: 4999, /* ... */ });
-    await aira.notarize({
-      actionId: auth.action_id,
-      outcome: "completed",
-      outcomeDetails: `Charged ${result.id}`,
-    });
-  }
-} catch (e) {
-  if (e instanceof AiraError && e.code === "ENDPOINT_NOT_WHITELISTED") {
-    console.log(`Blocked: ${e.message}`);
-  } else {
-    throw e;
-  }
-}
-```
-
-### Trust Policy in Integrations
+## Gateway
 
-Pass a `trustPolicy` to any framework integration to run automated trust checks before agent interactions:
+Route existing LLM calls through Aira with zero code changes. Every request is authorized and logged automatically.
 
 ```typescript
-import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
+import OpenAI from "openai";
+import { gatewayOpenAIConfig } from "aira-sdk/gateway";
 
-const handler = new AiraCallbackHandler(aira, "research-agent", {
-  modelId: "gpt-5.2",
-  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
-  },
+const client = new OpenAI({
+  ...gatewayOpenAIConfig({ airaApiKey: "aira_live_..." }),
+  apiKey: "sk-...",
 });
+// Use `client` exactly as before -- Aira gates every call
 ```
 
----
+Works with OpenAI, Azure OpenAI, and Anthropic:
 
-## Session
+| Helper | Provider |
+| --- | --- |
+| `gatewayOpenAIConfig()` | OpenAI, Azure OpenAI, any OpenAI-compatible API |
+| `gatewayAnthropicConfig()` | Anthropic |
 
-Pre-fill defaults for a block of related actions. Every `authorize()` call
-within the session inherits the agent identity, producing receipts that
-share a common provenance chain.
+Both helpers accept a `gatewayUrl` option for [self-hosted](#self-hosted) deployments.
 
-```typescript
-const sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
+## Framework integrations
 
-async function notarize(actionType: string, details: string) {
-  const auth = await sess.authorize({ actionType, details });
-  if (auth.status === "authorized") {
-    await sess.notarize({ actionId: auth.action_id, outcome: "completed" });
-  }
-}
+Each integration is a sub-import path. Install the peer dependency alongside `aira-sdk`.
 
-await notarize("identity_verified", "Verified customer ID #4521");
-await notarize("account_created", "Created account for customer #4521");
-await notarize("welcome_sent", "Sent welcome email to customer #4521");
-```
-
----
-
-## Offline Mode
-
-Queue `authorize()` calls locally when connectivity is unavailable. On
-`sync()`, the backend runs the real authorizations and returns their
-results. The agent can then call `notarize()` per action to close the loop.
-
-```typescript
-const aira = new Aira({ apiKey: "aira_live_xxx", offline: true });
-
-// These queue locally — no network calls
-await aira.authorize({ actionType: "scan_completed", details: "Scanned document batch #77" });
-await aira.authorize({ actionType: "classification_done", details: "Classified 142 documents" });
-
-console.log(aira.pendingCount);  // 2
-
-// Flush to the API when back online — returns the Authorization for each
-// queued request. Use the action_ids to notarize outcomes afterwards.
-const results = await aira.sync();
-```
-
-Offline mode is intended for actions the agent will execute regardless of
-Aira's decision (sensor reads, local scans). For actions whose execution
-depends on the authorization result, run the SDK online.
-
----
-
-## Human Approval
-
-Hold high-stakes actions for human review before they execute. Approvers
-receive an email with Approve/Deny buttons. If the action is held, the SDK
-returns `status: "pending_approval"` from `authorize()` and the agent must
-enqueue the `action_id` instead of executing.
-
-```typescript
-const auth = await aira.authorize({
-  actionType: "loan_decision",
-  details: "Approve €15,000 loan for Maria Schmidt",
-  agentId: "lending-agent",
-  requireApproval: true,
-  approvers: ["compliance@acme.com", "risk@acme.com"],
-});
-
-if (auth.status === "pending_approval") {
-  // Do NOT execute the action. Store action_id and wait for the
-  // action.approved webhook, then execute + notarize.
-  await queue.enqueue(auth.action_id);
-}
-```
-
-The approver clicks "Approve" in the email → the action transitions to
-`authorized` → `action.approved` webhook fires → your handler executes the
-action and calls `aira.notarize({ actionId, outcome: "completed" })`.
-
-Configure default approvers in the [dashboard](https://app.airaproof.com/dashboard/settings/approvers).
-
-### Automatic Policy Evaluation
-
-Org admins configure policies in the dashboard — your code doesn't change.
-Every `authorize()` call is automatically evaluated against active policies
-before returning. If a policy denies the action, the SDK throws
-`AiraError` with code `POLICY_DENIED` and the action is never persisted as
-authorized. If a policy forces human review, `status` is
-`pending_approval`. Otherwise `status` is `authorized`.
-
-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
-import { AiraError } from "aira-sdk";
-
-try {
-  const auth = await aira.authorize({
-    actionType: "data_deletion",
-    details: "Delete customer records",
-    agentId: "support-agent",
-  });
-  // ... execute + notarize ...
-} catch (e) {
-  if (e instanceof AiraError && e.code === "POLICY_DENIED") {
-    console.log(e.message);  // "Action denied by policy 'Block deletions': ..."
-  }
-}
-```
-
-Configure policies at [Settings → Policies](https://app.airaproof.com/dashboard/policies).
-
----
-
-## Framework Integrations
-
-Drop Aira into your existing agent framework with one import. Every integration is honestly labeled as one of three kinds:
-
-- **gate** — intercepts before execution and can deny. The action is authorized through Aira's policy engine *before* the framework runs the underlying call. Denied actions never run.
-- **audit** — runs after execution because the host framework does not expose a pre-execution hook that can abort. Aira still records a signed receipt; it just cannot prevent the action.
-- **adapter** — exposes Aira's own API as a tool the host framework can call. Neither a gate nor an audit hook over other tools.
-
-We ship fewer integrations than some competitors and label every one of them honestly. The integration matrix is generated from `INTEGRATIONS` in `aira-sdk/extras` — the docs cannot drift from the code.
-
-| Integration | Import | Type | Pre-execution gate? | Surface | Notes |
-|---|---|---|---|---|---|
-| **LangChain.js** | `aira-sdk/extras/langchain` | gate | Yes (tools); No (chains/LLMs) | `AiraCallbackHandler` | `handleToolStart` calls `authorize()` and throws on `POLICY_DENIED` so the tool never runs. Chain/LLM hooks are post-hoc because LangChain has no pre-execution chain hook that can abort. |
-| **Vercel AI SDK** | `aira-sdk/extras/vercel-ai` | gate | Yes (`wrapTool`); No (`onFinish`) | `AiraVercelMiddleware` | `wrapTool()` wraps the tool's `execute` so `authorize()` runs before the tool body. `onStepFinish` / `onFinish` callbacks are explicitly labeled audit-only. |
-| **OpenAI Agents** | `aira-sdk/extras/openai-agents` | gate | Yes | `AiraGuardrail.wrapTool()` | Wraps each tool function: `authorize()` runs before the tool body. Denied calls throw; failed calls notarize with `outcome="failed"`. |
-| **MCP** | `aira-sdk/extras/mcp` | adapter | N/A | `createServer()` | MCP is bidirectional: the agent CHOOSES to call `authorize_action` / `notarize_action`. Not a wrapper over other MCP tools — it's a protocol adapter. |
-| **Webhooks** | `aira-sdk/extras/webhooks` | adapter | N/A | `verifySignature()` | Standalone HMAC-SHA256 webhook signature verifier. Not an agent integration. |
+| Framework | Import path | Install |
+| --- | --- | --- |
+| LangChain.js | `aira-sdk/extras/langchain` | `npm i aira-sdk @langchain/core` |
+| Vercel AI SDK | `aira-sdk/extras/vercel-ai` | `npm i aira-sdk ai` |
+| OpenAI Agents SDK | `aira-sdk/extras/openai-agents` | `npm i aira-sdk openai` |
+| MCP | `aira-sdk/extras/mcp` | `npm i aira-sdk @modelcontextprotocol/sdk` |
+| Webhooks | `aira-sdk/extras/webhooks` | `npm i aira-sdk` |
 
 ### LangChain.js
 
-`AiraCallbackHandler` runs the two-step flow on every tool, chain, and LLM
-event. The `Start` callbacks call `authorize()` — if a policy denies the
-action or flags it for human review, LangChain aborts the step. The `End`
-and `Error` callbacks call `notarize()` with the appropriate outcome. This
-is a **real authorization gate**, not just post-hoc audit logging.
-
 ```typescript
 import { Aira } from "aira-sdk";
 import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
@@ -502,7 +124,6 @@ import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
 const aira = new Aira({ apiKey: "aira_live_xxx" });
 const handler = new AiraCallbackHandler(aira, "research-agent", {
   modelId: "gpt-5.2",
-  strict: false, // fail-open on network errors; set true to fail-closed
 });
 
 const result = await chain.invoke(
@@ -511,16 +132,7 @@ const result = await chain.invoke(
 );
 ```
 
-### Vercel AI
-
-`AiraVercelMiddleware` exposes two integration points:
-
-- **`wrapTool()`** — the real authorization gate. Calls `authorize()`
-  before the tool runs, notarizes the outcome afterwards. Use this for any
-  tool that touches the outside world.
-- **`onStepFinish` / `onFinish`** — post-hoc audit callbacks. These fire
-  after the step has run and cannot gate execution. Useful for logging
-  generation metadata.
+### Vercel AI SDK
 
 ```typescript
 import { Aira } from "aira-sdk";
@@ -528,8 +140,10 @@ import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
 import { tool } from "ai";
 import { z } from "zod";
 
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const middleware = new AiraVercelMiddleware(aira, "assistant-agent");
+const middleware = new AiraVercelMiddleware(
+  new Aira({ apiKey: "aira_live_xxx" }),
+  "assistant-agent",
+);
 
 const webSearch = tool({
   description: "Search the web",
@@ -538,58 +152,23 @@ const webSearch = tool({
     return await search(query);
   }, "web_search"),
 });
-
-const result = await generateText({
-  model: openai("gpt-5.2"),
-  prompt: "Find today's EU AI Act news",
-  tools: { webSearch },
-  ...middleware.asCallbacks(),
-});
 ```
 
 ### OpenAI Agents SDK
 
-`AiraGuardrail.wrapTool()` gates every tool invocation through Aira's
-two-step flow: `authorize()` runs first and can block the tool on
-`POLICY_DENIED` or `pending_approval`, then `notarize()` closes the loop
-after the tool returns. Only tool names and arg keys are sent — raw user
-input stays in your process.
-
 ```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(aira, "assistant-agent");
+const guardrail = new AiraGuardrail(
+  new Aira({ apiKey: "aira_live_xxx" }),
+  "assistant-agent",
+);
 
 const search = guardrail.wrapTool(searchTool, "web_search");
-const execute = guardrail.wrapTool(codeExecutor, "code_exec");
-```
-
----
-
-## MCP Server
-
-Expose Aira as an MCP tool server. Any MCP-compatible AI agent can run the
-two-step flow and verify receipts without a direct SDK dependency.
-
-```typescript
-import { Aira } from "aira-sdk";
-import { createServer } from "aira-sdk/extras/mcp";
-
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const { listTools, callTool } = createServer(aira);
-// Wire into @modelcontextprotocol/sdk's Server.
 ```
 
-The server exposes the two-step flow as explicit tools:
-`authorize_action`, `notarize_action`, `get_action`, `verify_action`,
-`get_receipt`, plus trust-layer helpers. An MCP client is expected to call
-`authorize_action` before performing a side effect and `notarize_action`
-after — the MCP protocol has no hidden hook point, so the authorization
-gate only exists if the agent cooperates with the contract.
-
-Add to your MCP client config:
+### MCP
 
 ```json
 {
@@ -603,104 +182,79 @@ Add to your MCP client config:
 }
 ```
 
----
-
-## Webhook Verification
+## Content scanning
 
-Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
+Aira can scan content passed to `notarize()` and block or flag policy violations. Configure the org-level policy:
 
 ```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",
+const policy = await aira.updateOutputPolicy({
+  mode: "block",
+  categories: ["pii", "secrets", "malware"],
 });
 
-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
-}
+// If outcomeDetails triggers a scan hit, notarize() returns 422
+// with code OUTPUT_SCAN_VIOLATION
 ```
 
-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`.
+Retrieve the current policy at any time with `getOutputPolicy()`.
 
----
+## Compliance & DORA
 
-## Error Handling
+Generate regulator-ready evidence packets and manage ICT incidents under DORA:
 
 ```typescript
-import { Aira, AiraError } from "aira-sdk";
+// Compliance bundle (EU AI Act, ISO 42001, SOC 2)
+const bundle = await aira.createComplianceBundle({
+  startDate: "2026-01-01",
+  endDate: "2026-03-31",
+  framework: "eu_ai_act",
+});
 
-try {
-  const auth = await aira.authorize({ actionType: "test", details: "test" });
-  // ...
-} catch (e) {
-  if (e instanceof AiraError) {
-    console.log(e.status);   // e.g. 403
-    console.log(e.code);     // e.g. "POLICY_DENIED"
-    console.log(e.message);
-  }
-}
+// DORA incident reporting
+const incident = await aira.createDoraIncident({
+  title: "API gateway outage",
+  description: "Payment processing unavailable for 45 minutes",
+  severity: "major",
+  detectedAt: new Date().toISOString(),
+});
+
+// Compliance report with PDF download
+const report = await aira.createComplianceReport({
+  framework: "eu_ai_act",
+  startDate: "2026-01-01",
+  endDate: "2026-03-31",
+});
+const pdf = await aira.downloadComplianceReport(report.id);
 ```
 
-Framework integrations (LangChain.js, Vercel AI, OpenAI Agents) **fail open
-by default** on transient errors (network, 5xx) — a warning is logged and
-the tool still runs. `POLICY_DENIED` and `pending_approval` always
-propagate as thrown errors so disallowed actions are never executed. Pass
-`strict: true` to the integration constructor to fail closed on transient
-errors too.
+Additional DORA methods: `classifyDoraIncident()`, `resolveDoraIncident()`, `createDoraTest()`, `createIctThirdParty()`, and more.
 
----
+## Self-hosted
 
-## Configuration
+Point the SDK at your own deployment:
 
 ```typescript
 const aira = new Aira({
-  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
+  apiKey: "aira_live_xxx",
+  baseUrl: "https://aira.your-company.com",
 });
 ```
 
-| Env Variable | Description |
-|---|---|
-| `AIRA_API_KEY` | API key (used by MCP server) |
-
----
-
-## SDK Parity
+Gateway helpers also accept a `gatewayUrl` parameter:
 
-| 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 |
-
----
+```typescript
+gatewayOpenAIConfig({
+  airaApiKey: "aira_live_...",
+  gatewayUrl: "https://aira.your-company.com/gateway",
+});
+```
 
 ## Links
 
-- [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)
-- [Interactive Demo](https://app.airaproof.com/demo) -- try Aira in your browser, no code needed
+- [Gateway Guide](https://docs.airaproof.com/docs/gateway)
 - [Dashboard](https://app.airaproof.com)
+- [Interactive Demo](https://app.airaproof.com/demo)
 - [GitHub](https://github.com/aira-proof/typescript-sdk)
+- [Python SDK](https://pypi.org/project/aira-sdk/)

package/dist/client.d.ts

@@ -19,6 +19,73 @@ export declare class Aira {
     private patch;
     private del;
     private paginated;
+    /** Create a governance policy. */
+    createPolicy(params: {
+        name: string;
+        mode: string;
+        decision?: string;
+        priority?: number;
+        conditions?: Array<{
+            field: string;
+            op: string;
+            value: any;
+        }>;
+        aiPrompt?: string;
+        aiModels?: string[];
+        scanConfig?: Record<string, any>;
+        description?: string;
+    }): Promise<Record<string, any>>;
+    /** List all active policies. */
+    listPolicies(): Promise<Array<Record<string, any>>>;
+    /** Get a single policy by ID. */
+    getPolicy(policyId: string): Promise<Record<string, any>>;
+    /** Update a policy. Pass only fields to change. */
+    updatePolicy(policyId: string, params: Record<string, any>): Promise<Record<string, any>>;
+    /** Delete a policy. */
+    deletePolicy(policyId: string): Promise<Record<string, any>>;
+    /** Activate a policy. */
+    activatePolicy(policyId: string): Promise<Record<string, any>>;
+    /** Deactivate a policy. */
+    deactivatePolicy(policyId: string): Promise<Record<string, any>>;
+    /** Test a policy against an action context without executing it. */
+    dryRunPolicy(policyId: string, actionContext: Record<string, any>): Promise<Record<string, any>>;
+    /** Scan text for PII, PHI, secrets, and prompt injection. */
+    sanitizeText(params: {
+        content: string;
+        policy?: string;
+        mode?: string;
+        aiModel?: string;
+    }): Promise<Record<string, any>>;
+    /** Reverse tokenization — map tokens back to original values. */
+    detokenize(params: {
+        content: string;
+        tokenMapping: Record<string, string>;
+    }): Promise<Record<string, any>>;
+    /** Create a webhook subscription. */
+    createWebhook(params: {
+        url: string;
+        events?: string[];
+        secret?: string;
+    }): Promise<Record<string, any>>;
+    /** List all webhooks for the organization. */
+    listWebhooks(): Promise<Array<Record<string, any>>>;
+    /** Delete a webhook. */
+    deleteWebhook(webhookId: string): Promise<Record<string, any>>;
+    /** Get usage summary for the current billing period. */
+    getUsage(): Promise<Record<string, any>>;
+    /** List individual usage events. */
+    listUsageEvents(params?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Record<string, any>>;
+    /** List available models. */
+    listModels(includeDisabled?: boolean): Promise<Array<Record<string, any>>>;
+    /** Get model preferences (disabled models list). */
+    getModelPreferences(): Promise<Record<string, any>>;
+    /** Update which models are disabled. */
+    updateModelPreferences(disabledModels: string[]): Promise<Record<string, any>>;
+    /** Get Aira's policy violations for a GitHub PR. */
+    getPrViolations(owner: string, repo: string, pullNumber: number): Promise<Array<Record<string, any>>>;
     /**
      * Step 1 — Authorize an action BEFORE it executes.
      *

package/dist/client.js

@@ -132,6 +132,114 @@ class Aira {
         const p = data.pagination;
         return { data: data.data, total: p.total, page: p.page, per_page: p.per_page, has_more: p.has_more };
     }
+    // ==================== Policies ====================
+    /** Create a governance policy. */
+    async createPolicy(params) {
+        return this.post("/policies", buildBody({
+            name: params.name,
+            mode: params.mode,
+            decision: params.decision ?? "deny",
+            priority: params.priority ?? 0,
+            conditions: params.conditions,
+            ai_prompt: params.aiPrompt,
+            ai_models: params.aiModels,
+            scan_config: params.scanConfig,
+            description: params.description,
+        }));
+    }
+    /** List all active policies. */
+    async listPolicies() {
+        const data = await this.get("/policies");
+        return data.data ?? [];
+    }
+    /** Get a single policy by ID. */
+    async getPolicy(policyId) {
+        return this.get(`/policies/${policyId}`);
+    }
+    /** Update a policy. Pass only fields to change. */
+    async updatePolicy(policyId, params) {
+        return this.put(`/policies/${policyId}`, buildBody(params));
+    }
+    /** Delete a policy. */
+    async deletePolicy(policyId) {
+        return this.del(`/policies/${policyId}`);
+    }
+    /** Activate a policy. */
+    async activatePolicy(policyId) {
+        return this.post(`/policies/${policyId}/activate`, {});
+    }
+    /** Deactivate a policy. */
+    async deactivatePolicy(policyId) {
+        return this.post(`/policies/${policyId}/deactivate`, {});
+    }
+    /** Test a policy against an action context without executing it. */
+    async dryRunPolicy(policyId, actionContext) {
+        return this.post(`/policies/${policyId}/dry-run`, { action_context: actionContext });
+    }
+    // ==================== Sanitize ====================
+    /** Scan text for PII, PHI, secrets, and prompt injection. */
+    async sanitizeText(params) {
+        return this.post("/sanitize", buildBody({
+            content: params.content,
+            policy: params.policy ?? "standard",
+            mode: params.mode ?? "flag",
+            ai_model: params.aiModel,
+        }));
+    }
+    /** Reverse tokenization — map tokens back to original values. */
+    async detokenize(params) {
+        return this.post("/sanitize/detokenize", {
+            content: params.content,
+            token_mapping: params.tokenMapping,
+        });
+    }
+    // ==================== Webhooks ====================
+    /** Create a webhook subscription. */
+    async createWebhook(params) {
+        return this.post("/webhooks", buildBody(params));
+    }
+    /** List all webhooks for the organization. */
+    async listWebhooks() {
+        return this.get("/webhooks");
+    }
+    /** Delete a webhook. */
+    async deleteWebhook(webhookId) {
+        return this.del(`/webhooks/${webhookId}`);
+    }
+    // ==================== Usage ====================
+    /** Get usage summary for the current billing period. */
+    async getUsage() {
+        return this.get("/usage");
+    }
+    /** List individual usage events. */
+    async listUsageEvents(params) {
+        const qs = new URLSearchParams();
+        if (params?.page)
+            qs.set("page", String(params.page));
+        if (params?.perPage)
+            qs.set("per_page", String(params.perPage));
+        return this.get(`/usage/events?${qs}`);
+    }
+    // ==================== Models ====================
+    /** List available models. */
+    async listModels(includeDisabled = false) {
+        const suffix = includeDisabled ? "?include_disabled=true" : "";
+        return this.get(`/models${suffix}`);
+    }
+    /** Get model preferences (disabled models list). */
+    async getModelPreferences() {
+        return this.get("/models/preferences");
+    }
+    /** Update which models are disabled. */
+    async updateModelPreferences(disabledModels) {
+        return this.put("/models/preferences", { disabled_models: disabledModels });
+    }
+    // ==================== Code Governance ====================
+    /** Get Aira's policy violations for a GitHub PR. */
+    async getPrViolations(owner, repo, pullNumber) {
+        const data = await this.get(`/webhooks/github/violations/${owner}/${repo}/${pullNumber}`);
+        return data.data ?? [];
+    }
     // ==================== Actions (two-step: authorize → notarize) ====================
     /**
      * Step 1 — Authorize an action BEFORE it executes.

package/dist/extras/mcp.js

@@ -144,6 +144,24 @@ function getTools() {
                 required: ["action_uuid", "counterparty_did"],
             },
         },
+        {
+            name: "get_pr_violations",
+            description: "Get Aira's policy violation findings for a GitHub pull request. Returns file, line, finding, description, and suggested fix for each violation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "GitHub org or user" },
+                    repo: { type: "string", description: "Repository name" },
+                    pull_number: { type: "integer", description: "PR number" },
+                },
+                required: ["owner", "repo", "pull_number"],
+            },
+        },
+        {
+            name: "list_policies",
+            description: "List all active governance policies for the organization",
+            inputSchema: { type: "object", properties: {} },
+        },
     ];
 }
 /** Handle an MCP tool call and return text content. */
@@ -197,6 +215,14 @@ async function handleToolCall(client, name, args) {
             const result = await client.requestMutualSign(args.action_uuid, args.counterparty_did);
             return [{ type: "text", text: JSON.stringify(result) }];
         }
+        if (name === "get_pr_violations") {
+            const result = await client.getPrViolations(args.owner, args.repo, args.pull_number);
+            return [{ type: "text", text: JSON.stringify(result) }];
+        }
+        if (name === "list_policies") {
+            const result = await client.listPolicies();
+            return [{ type: "text", text: JSON.stringify(result) }];
+        }
         return [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }];
     }
     catch (e) {

package/dist/types.d.ts

@@ -27,12 +27,17 @@ export interface Authorization {
 /**
  * Cryptographic receipt from notarizing an action — Step 2 of the two-step flow.
  *
- * Only populated when `status === "notarized"`. For "failed" outcomes,
- * the receipt fields stay null — only the audit trail is recorded.
+ * Status values:
+ *  - "notarized"       — action completed successfully, receipt minted
+ *  - "failed"          — action failed, Ed25519 receipt still minted for audit
+ *  - "denied"          — policy denied the action, Ed25519 receipt minted for the denial
+ *  - "denied_by_human" — human reviewer denied the action, Ed25519 receipt minted
+ *
+ * Every action state produces an Ed25519 receipt — the audit trail has zero gaps.
  */
 export interface ActionReceipt {
     action_uuid: string;
-    status: "notarized" | "failed";
+    status: "notarized" | "failed" | "denied" | "denied_by_human";
     created_at: string;
     request_id: string;
     receipt_uuid: string | null;
@@ -313,7 +318,8 @@ export declare class AiraError extends Error {
     statusCode: number;
     /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code: string;
-    /** Optional backend-supplied context (policy_uuid, action_uuid, etc.). */
+    /** Optional backend-supplied context (policy_uuid, action_uuid, receipt_uuid, etc.).
+     *  For POLICY_DENIED errors, `receipt_uuid` is the Ed25519 receipt minted for the denial. */
     details: Record<string, unknown>;
     constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown>);
 }

package/dist/types.js

@@ -23,7 +23,8 @@ class AiraError extends Error {
     statusCode;
     /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code;
-    /** Optional backend-supplied context (policy_uuid, action_uuid, etc.). */
+    /** Optional backend-supplied context (policy_uuid, action_uuid, receipt_uuid, etc.).
+     *  For POLICY_DENIED errors, `receipt_uuid` is the Ed25519 receipt minted for the denial. */
     details;
     constructor(statusCode, code, message, details = {}) {
         super(`[${code}] ${message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aira-sdk",
-  "version": "3.2.0",
+  "version": "3.5.0",
   "description": "The authorization and audit layer for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",