aira-sdk 2.1.0 → 2.4.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { Authorization, ActionReceipt, ActionDetail, AgentDetail, AgentVersion, CosignResult, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList } from "./types";
+import { Authorization, ActionReceipt, ActionDetail, AgentDetail, AgentVersion, CosignResult, EvidencePackage, ComplianceSnapshot, EscrowAccount, EscrowTransaction, VerifyResult, PaginatedList, ComplianceReport, ComplianceReportListResponse, ComplianceReportVerification, ActionExplanation, ExplanationVerification, OutputPolicy, OutputPolicyUpdate } from "./types";
 import { AiraSession } from "./session";
 export interface AiraOptions {
     apiKey: string;
@@ -16,6 +16,7 @@ export declare class Aira {
     private get;
     private post;
     private put;
+    private patch;
     private del;
     private paginated;
     /**
@@ -271,6 +272,88 @@ export declare class Aira {
     getSettlement(settlementId: string): Promise<Record<string, unknown>>;
     /** Get the Merkle inclusion proof for one receipt in its settlement. */
     getSettlementInclusionProof(receiptId: string): Promise<Record<string, unknown>>;
+    /**
+     * Generate a regulatory PDF report.
+     *
+     * Frameworks:
+     * - `eu_ai_act_art12` — Annex VII technical file. Requires period.
+     * - `eu_ai_act_art9` — risk management register. Requires period.
+     * - `eu_ai_act_art6` — single-action explanation. Requires actionId.
+     * - `eu_ai_act_annex_iv` — full Annex IV technical documentation
+     *   (§§1..9). Requires period. Typical use: annual file for the
+     *   high-risk AI system provider obligations in Article 11.
+     */
+    createComplianceReport(params: {
+        framework: string;
+        periodStart?: string;
+        periodEnd?: string;
+        actionId?: string;
+        agentFilter?: string[];
+    }): Promise<ComplianceReport>;
+    /** Get the metadata for a compliance report (no PDF bytes). */
+    getComplianceReport(reportId: string): Promise<ComplianceReport>;
+    /** List compliance reports with optional filters. */
+    listComplianceReports(params?: {
+        framework?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ComplianceReportListResponse>;
+    /**
+     * Download the generated PDF as raw bytes (Uint8Array).
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    downloadComplianceReport(reportId: string): Promise<Uint8Array>;
+    /** Verify a compliance report's signature and content hash. */
+    verifyComplianceReport(reportId: string): Promise<ComplianceReportVerification>;
+    /**
+     * Return the org's output content-scan policy.
+     *
+     * Scans apply to the `outcomeDetails` passed to `notarize()`. Mode
+     * controls behaviour:
+     *  - `flag` — hits are recorded on the receipt, nothing blocked
+     *  - `deny` — a hit at or above `deny_severity_threshold` makes
+     *    notarize return 422 with code `OUTPUT_SCAN_VIOLATION`
+     *  - `redact` — matched spans are replaced with `[REDACTED]` and
+     *    the receipt signs over the cleaned bytes
+     */
+    getOutputPolicy(): Promise<OutputPolicy>;
+    /**
+     * Merge the supplied fields into the org's output content-scan
+     * policy. Omitted fields stay at their current values. Admin role
+     * required server-side.
+     */
+    updateOutputPolicy(updates: OutputPolicyUpdate): Promise<OutputPolicy>;
+    /**
+     * Article 6 right-to-explanation for a single action.
+     *
+     * The response includes a cryptographic ``_envelope`` — verify it
+     * later with {@link verifyActionExplanation} (the verify endpoint
+     * is public, so anyone holding the JSON can re-check it).
+     */
+    getActionExplanation(actionId: string): Promise<ActionExplanation>;
+    /**
+     * Public verify — recompute an explanation envelope's signature.
+     *
+     * POSTs the full explanation JSON to the unauthenticated
+     * ``/verify/explanation`` endpoint. The server looks up the public
+     * key by ``_envelope.signing_key_id`` and re-derives the canonical
+     * content hash + Ed25519 signature.
+     *
+     * ``request_id`` is stripped before sending, so a saved JSON
+     * explanation verifies the same way regardless of whether the
+     * caller round-tripped it through their own logs.
+     */
+    verifyActionExplanation(explanation: ActionExplanation | Record<string, unknown>): Promise<ExplanationVerification>;
+    /**
+     * Download the Article 6 explanation as a PDF.
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    downloadActionExplanationPdf(actionId: string): Promise<Uint8Array>;
     /** Create a scoped session with pre-filled defaults. */
     session(agentId: string, defaults?: Record<string, unknown>): AiraSession;
     /** Number of queued offline requests. */

package/dist/client.js

@@ -7,6 +7,44 @@ const session_1 = require("./session");
 const DEFAULT_BASE_URL = "https://api.airaproof.com";
 const DEFAULT_TIMEOUT = 30_000;
 const MAX_DETAILS_LENGTH = 50_000;
+// Binary download endpoints retry on transient 5xx (server hiccups,
+// brief gateway issues). 3 attempts with exponential backoff
+// (250ms -> 500ms -> 1000ms) keeps the worst case under 2s while
+// absorbing the most common flakes. 4xx errors are NOT retried —
+// those indicate a real problem the caller needs to see.
+const DOWNLOAD_MAX_ATTEMPTS = 3;
+const DOWNLOAD_BACKOFF_BASE_MS = 250;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run a fetch with retries on transient 5xx and network errors.
+ * Returns the final Response (which may itself be a 5xx after all
+ * attempts are exhausted — caller decides whether to throw).
+ */
+async function fetchWithRetry(doFetch) {
+    let lastErr;
+    for (let attempt = 0; attempt < DOWNLOAD_MAX_ATTEMPTS; attempt++) {
+        try {
+            const res = await doFetch();
+            if (res.status >= 500 && attempt < DOWNLOAD_MAX_ATTEMPTS - 1) {
+                await sleep(DOWNLOAD_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt < DOWNLOAD_MAX_ATTEMPTS - 1) {
+                await sleep(DOWNLOAD_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            throw err;
+        }
+    }
+    // Unreachable in practice — the loop either returns or throws.
+    throw lastErr ?? new Error("download retry loop exited without a response");
+}
 function buildBody(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
 }
@@ -76,6 +114,13 @@ class Aira {
         }
         return this.request("PUT", path, body);
     }
+    patch(path, body) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("PATCH", path, body);
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
+        return this.request("PATCH", path, body);
+    }
     del(path) {
         if (this.queue) {
             const qid = this.queue.enqueue("DELETE", path, {});
@@ -487,6 +532,156 @@ class Aira {
     async getSettlementInclusionProof(receiptId) {
         return this.get(`/settlements/inclusion-proof/${receiptId}`);
     }
+    // ==================== Compliance reports (Phase 1) ====================
+    /**
+     * Generate a regulatory PDF report.
+     *
+     * Frameworks:
+     * - `eu_ai_act_art12` — Annex VII technical file. Requires period.
+     * - `eu_ai_act_art9` — risk management register. Requires period.
+     * - `eu_ai_act_art6` — single-action explanation. Requires actionId.
+     * - `eu_ai_act_annex_iv` — full Annex IV technical documentation
+     *   (§§1..9). Requires period. Typical use: annual file for the
+     *   high-risk AI system provider obligations in Article 11.
+     */
+    async createComplianceReport(params) {
+        const body = buildBody({
+            framework: params.framework,
+            period_start: params.periodStart,
+            period_end: params.periodEnd,
+            action_id: params.actionId,
+            agent_filter: params.agentFilter,
+        });
+        return this.post("/compliance/reports", body);
+    }
+    /** Get the metadata for a compliance report (no PDF bytes). */
+    async getComplianceReport(reportId) {
+        return this.get(`/compliance/reports/${reportId}`);
+    }
+    /** List compliance reports with optional filters. */
+    async listComplianceReports(params) {
+        return this.get("/compliance/reports", buildBody({ ...params }));
+    }
+    /**
+     * Download the generated PDF as raw bytes (Uint8Array).
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    async downloadComplianceReport(reportId) {
+        if (this.queue) {
+            throw new types_1.AiraError(0, "OFFLINE", "Downloads are not available in offline mode");
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetchWithRetry(() => fetch(`${this.baseUrl}/compliance/reports/${reportId}/download`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                signal: controller.signal,
+            }));
+            if (!res.ok) {
+                throw new types_1.AiraError(res.status, "DOWNLOAD_FAILED", res.statusText);
+            }
+            const buf = await res.arrayBuffer();
+            return new Uint8Array(buf);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Verify a compliance report's signature and content hash. */
+    async verifyComplianceReport(reportId) {
+        return this.get(`/compliance/reports/${reportId}/verify`);
+    }
+    // ==================== Output content-scan policy ====================
+    /**
+     * Return the org's output content-scan policy.
+     *
+     * Scans apply to the `outcomeDetails` passed to `notarize()`. Mode
+     * controls behaviour:
+     *  - `flag` — hits are recorded on the receipt, nothing blocked
+     *  - `deny` — a hit at or above `deny_severity_threshold` makes
+     *    notarize return 422 with code `OUTPUT_SCAN_VIOLATION`
+     *  - `redact` — matched spans are replaced with `[REDACTED]` and
+     *    the receipt signs over the cleaned bytes
+     */
+    async getOutputPolicy() {
+        return this.get("/output-policies");
+    }
+    /**
+     * Merge the supplied fields into the org's output content-scan
+     * policy. Omitted fields stay at their current values. Admin role
+     * required server-side.
+     */
+    async updateOutputPolicy(updates) {
+        // Strip undefined so they don't travel as `null` and accidentally
+        // reset server-side values.
+        const body = {};
+        for (const [k, v] of Object.entries(updates)) {
+            if (v !== undefined)
+                body[k] = v;
+        }
+        return this.patch("/output-policies", body);
+    }
+    /**
+     * Article 6 right-to-explanation for a single action.
+     *
+     * The response includes a cryptographic ``_envelope`` — verify it
+     * later with {@link verifyActionExplanation} (the verify endpoint
+     * is public, so anyone holding the JSON can re-check it).
+     */
+    async getActionExplanation(actionId) {
+        return this.get(`/actions/${actionId}/explanation`);
+    }
+    /**
+     * Public verify — recompute an explanation envelope's signature.
+     *
+     * POSTs the full explanation JSON to the unauthenticated
+     * ``/verify/explanation`` endpoint. The server looks up the public
+     * key by ``_envelope.signing_key_id`` and re-derives the canonical
+     * content hash + Ed25519 signature.
+     *
+     * ``request_id`` is stripped before sending, so a saved JSON
+     * explanation verifies the same way regardless of whether the
+     * caller round-tripped it through their own logs.
+     */
+    async verifyActionExplanation(explanation) {
+        const payload = {};
+        for (const [k, v] of Object.entries(explanation)) {
+            if (k === "request_id")
+                continue;
+            payload[k] = v;
+        }
+        return this.request("POST", "/verify/explanation", { explanation: payload }, false);
+    }
+    /**
+     * Download the Article 6 explanation as a PDF.
+     *
+     * Retries on transient 5xx and network errors (3 attempts,
+     * exponential backoff). 4xx responses surface immediately.
+     */
+    async downloadActionExplanationPdf(actionId) {
+        if (this.queue) {
+            throw new types_1.AiraError(0, "OFFLINE", "Downloads are not available in offline mode");
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetchWithRetry(() => fetch(`${this.baseUrl}/actions/${actionId}/explanation/pdf`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                signal: controller.signal,
+            }));
+            if (!res.ok) {
+                throw new types_1.AiraError(res.status, "DOWNLOAD_FAILED", res.statusText);
+            }
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     // ==================== Session ====================
     /** Create a scoped session with pre-filled defaults. */
     session(agentId, defaults) {

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export type { AiraOptions } from "./client";
 export { AiraSession } from "./session";
 export { OfflineQueue } from "./offline";
 export type { QueuedRequest } from "./offline";
-export { AiraError, type Authorization, type ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type CosignResult, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, } from "./types";
+export { AiraError, FRAMEWORK_ANNEX_IV, FRAMEWORK_ART12, FRAMEWORK_ART9, FRAMEWORK_ART6, type Authorization, type ActionReceipt, type ActionDetail, type AgentDetail, type AgentVersion, type CosignResult, type EvidencePackage, type ComplianceSnapshot, type EscrowAccount, type EscrowTransaction, type VerifyResult, type PaginatedList, type ComplianceReport, type ComplianceReportListResponse, type ComplianceReportVerification, type ActionExplanation, type ExplanationEnvelope, type ExplanationVerification, type OutputPolicy, type OutputPolicyUpdate, type OutputScanFlags, type OutputScanHit, } from "./types";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = exports.OfflineQueue = exports.AiraSession = exports.Aira = void 0;
+exports.FRAMEWORK_ART6 = exports.FRAMEWORK_ART9 = exports.FRAMEWORK_ART12 = exports.FRAMEWORK_ANNEX_IV = 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");
@@ -9,3 +9,7 @@ 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; } });
+Object.defineProperty(exports, "FRAMEWORK_ANNEX_IV", { enumerable: true, get: function () { return types_1.FRAMEWORK_ANNEX_IV; } });
+Object.defineProperty(exports, "FRAMEWORK_ART12", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART12; } });
+Object.defineProperty(exports, "FRAMEWORK_ART9", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART9; } });
+Object.defineProperty(exports, "FRAMEWORK_ART6", { enumerable: true, get: function () { return types_1.FRAMEWORK_ART6; } });

package/dist/types.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Compliance framework identifiers — string values accepted by
+ * `Aira.createComplianceReport()` and returned on `ComplianceReport.framework`.
+ * Import these constants rather than hard-coding the wire strings so
+ * callers stay in lockstep with the backend if a name ever changes.
+ */
+export declare const FRAMEWORK_ART12: "eu_ai_act_art12";
+export declare const FRAMEWORK_ART9: "eu_ai_act_art9";
+export declare const FRAMEWORK_ART6: "eu_ai_act_art6";
+export declare const FRAMEWORK_ANNEX_IV: "eu_ai_act_annex_iv";
 /**
  * Authorization result from `authorize()` — Step 1 of the two-step flow.
  *
@@ -29,11 +39,50 @@ export interface ActionReceipt {
     payload_hash: string | null;
     signature: string | null;
     timestamp_token: string | null;
+    /**
+     * Output content-scan result attached at notarize time when the
+     * org has an output policy enabled. ``null`` when output filtering
+     * is off (global flag or per-org).
+     */
+    output_scan_flags?: OutputScanFlags | null;
     warnings: string[] | null;
 }
+export interface OutputScanHit {
+    name: string;
+    library: string;
+    severity: "info" | "warning" | "critical";
+    description: string;
+    matches: number;
+    /** Always `"[REDACTED]"` — the matched fragment never travels. */
+    sample: string;
+}
+export interface OutputScanFlags {
+    scanned_at: string;
+    libraries: string[];
+    mode: "flag" | "deny" | "redact";
+    decision: "allow" | "require_approval" | "deny";
+    worst_severity: "info" | "warning" | "critical" | null;
+    hits: OutputScanHit[];
+}
+export interface OutputPolicy {
+    enabled: boolean;
+    mode: "flag" | "deny" | "redact";
+    libraries: string[];
+    deny_severity_threshold: "info" | "warning" | "critical";
+    redact_severity_threshold: "info" | "warning" | "critical";
+    request_id: string;
+}
+export interface OutputPolicyUpdate {
+    enabled?: boolean;
+    mode?: "flag" | "deny" | "redact";
+    libraries?: string[];
+    deny_severity_threshold?: "info" | "warning" | "critical";
+    redact_severity_threshold?: "info" | "warning" | "critical";
+}
 /** Full action details including receipt and authorizations. */
 export interface ActionDetail {
     action_id: string;
+    org_id: string;
     action_type: string;
     action_details_hash: string;
     agent_id: string | null;
@@ -51,6 +100,7 @@ export interface ActionDetail {
         timestamp_token: string | null;
         receipt_version: string;
         verify_url: string;
+        created_at: string | null;
     } | null;
     authorizations: {
         id: string;
@@ -58,6 +108,10 @@ export interface ActionDetail {
         authorized_at: string | null;
     }[];
     request_id: string;
+    system_prompt_hash?: string | null;
+    tool_inputs_hash?: string | null;
+    model_params?: Record<string, unknown> | null;
+    execution_env?: Record<string, unknown> | null;
 }
 /** Registered agent identity. */
 export interface AgentDetail {
@@ -163,6 +217,11 @@ export interface VerifyResult {
     algorithm?: string | null;
     timestamp_token?: string | null;
     signed_payload?: Record<string, unknown> | null;
+    policy_evaluator_attestation?: {
+        evaluator_key_id: string;
+        signature: string;
+        payload_hash: string;
+    } | null;
 }
 /** Paginated list response. */
 export interface PaginatedList<T = Record<string, unknown>> {
@@ -202,3 +261,68 @@ export declare class AiraError extends Error {
     details: Record<string, unknown>;
     constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown>);
 }
+export interface ComplianceReport {
+    id: string;
+    framework: string;
+    status: "pending" | "generating" | "ready" | "failed";
+    created_at: string;
+    request_id?: string;
+    org_id?: string;
+    period_start?: string | null;
+    period_end?: string | null;
+    action_id?: string | null;
+    agent_filter?: string[] | null;
+    receipt_count?: number | null;
+    pdf_size_bytes?: number | null;
+    content_hash?: string | null;
+    signature?: string | null;
+    signing_key_id?: string | null;
+    timestamp_token?: string | null;
+    timestamp_token_present?: boolean;
+    report_metadata?: Record<string, unknown> | null;
+    error_message?: string | null;
+    generated_at?: string | null;
+}
+export interface ComplianceReportListResponse {
+    items: ComplianceReport[];
+    total: number;
+    limit: number;
+    offset: number;
+    request_id: string;
+}
+export interface ComplianceReportVerification {
+    report_id: string;
+    valid: boolean;
+    checks: Record<string, unknown>;
+    descriptor?: Record<string, unknown> | null;
+    request_id: string;
+}
+export interface ExplanationEnvelope {
+    alg: string;
+    signing_key_id: string;
+    content_hash: string;
+    signature: string;
+    generated_at: string;
+}
+export interface ActionExplanation {
+    action: Record<string, unknown>;
+    policy_chain: Array<Record<string, unknown>>;
+    approval_chain: Array<Record<string, unknown>>;
+    receipt?: Record<string, unknown> | null;
+    regulation: Record<string, unknown>;
+    /**
+     * Ed25519 signature over the canonical JSON of every field above
+     * (except ``_envelope`` itself and ``request_id``). The on-wire key
+     * is ``_envelope`` — the SDK exposes it under the same name so a
+     * saved ``JSON.stringify(explanation)`` round-trips through
+     * :meth:`Aira.verifyActionExplanation` untouched.
+     */
+    _envelope?: ExplanationEnvelope;
+    request_id: string;
+}
+export interface ExplanationVerification {
+    valid: boolean;
+    checks: Record<string, unknown>;
+    signing_key_id?: string | null;
+    request_id: string;
+}

package/dist/types.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = void 0;
+exports.AiraError = exports.FRAMEWORK_ANNEX_IV = exports.FRAMEWORK_ART6 = exports.FRAMEWORK_ART9 = exports.FRAMEWORK_ART12 = void 0;
+/**
+ * Compliance framework identifiers — string values accepted by
+ * `Aira.createComplianceReport()` and returned on `ComplianceReport.framework`.
+ * Import these constants rather than hard-coding the wire strings so
+ * callers stay in lockstep with the backend if a name ever changes.
+ */
+exports.FRAMEWORK_ART12 = "eu_ai_act_art12";
+exports.FRAMEWORK_ART9 = "eu_ai_act_art9";
+exports.FRAMEWORK_ART6 = "eu_ai_act_art6";
+exports.FRAMEWORK_ANNEX_IV = "eu_ai_act_annex_iv";
 /**
  * Aira API error.
  *

package/package.json

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