aira-sdk 1.0.0 → 2.4.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ActionReceipt, ActionDetail, AgentDetail, AgentVersion, 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,21 +16,51 @@ export declare class Aira {
     private get;
     private post;
     private put;
+    private patch;
     private del;
     private paginated;
-    notarize(params: {
+    /**
+     * Step 1 — Authorize an action BEFORE it executes.
+     *
+     * Returns an `Authorization` with a status:
+     *  - "authorized"       → safe to execute the action, then call `notarize()`
+     *  - "pending_approval" → enqueue `action_id` and wait for human approval
+     *
+     * If a policy denies the action, this throws `AiraError` with code
+     * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
+     * `DUPLICATE_REQUEST` (HTTP 409).
+     */
+    authorize(params: {
         actionType: string;
         details: string;
         agentId?: string;
         agentVersion?: string;
+        instructionHash?: string;
         modelId?: string;
         modelVersion?: string;
-        instructionHash?: string;
         parentActionId?: string;
+        endpointUrl?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
         requireApproval?: boolean;
         approvers?: string[];
+        systemPromptHash?: string;
+        toolInputsHash?: string;
+        modelParams?: Record<string, unknown>;
+        executionEnv?: Record<string, unknown>;
+    }): Promise<Authorization>;
+    /**
+     * Step 2 — Notarize the outcome of an already-authorized action.
+     *
+     * Call this AFTER executing the action. Outcome is "completed" by default;
+     * pass "failed" if the action ran but failed so the audit trail captures
+     * the failure. The returned `ActionReceipt` carries the Ed25519 signature
+     * and RFC 3161 timestamp token when the status is "notarized".
+     */
+    notarize(params: {
+        actionId: string;
+        outcome?: "completed" | "failed";
+        outcomeDetails?: string;
     }): Promise<ActionReceipt>;
     getAction(actionId: string): Promise<ActionDetail>;
     listActions(params?: {
@@ -40,7 +70,17 @@ export declare class Aira {
         agentId?: string;
         status?: string;
     }): Promise<PaginatedList<ActionDetail>>;
-    authorizeAction(actionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Add a human co-signature to an action that already exists.
+     *
+     * This is distinct from the authorization gate (it runs against `/cosign`,
+     * not `/authorize`). It records that a specific human has acknowledged or
+     * signed off on an action that was already authorized and notarized.
+     * Requires JWT auth (dashboard user, not an API key).
+     */
+    cosign(params: {
+        actionId: string;
+    }): Promise<CosignResult>;
     setLegalHold(actionId: string): Promise<Record<string, unknown>>;
     releaseLegalHold(actionId: string): Promise<Record<string, unknown>>;
     getActionChain(actionId: string): Promise<Record<string, unknown>[]>;
@@ -163,6 +203,157 @@ export declare class Aira {
     attestReputation(slug: string, counterpartyDid: string, actionId: string, attestation: string, signature: string): Promise<Record<string, unknown>>;
     /** Verify a reputation score by returning inputs and score_hash. */
     verifyReputation(slug: string): Promise<Record<string, unknown>>;
+    /**
+     * Get all reproducibility metadata stored for an action.
+     *
+     * Returns the system_prompt_hash, tool_inputs_hash, model_params,
+     * execution_env, and other knobs that an external replay tool
+     * needs to confirm it has the same inputs as the original run.
+     */
+    getReplayContext(actionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Seal a regulator-ready evidence bundle for a date range.
+     *
+     * `framework` must be one of: `eu_ai_act_art12`, `iso_42001`,
+     * `aiuc_1`, `soc_2_cc7`, `raw`.
+     */
+    createComplianceBundle(params: {
+        framework: "eu_ai_act_art12" | "iso_42001" | "aiuc_1" | "soc_2_cc7" | "raw";
+        periodStart: string;
+        periodEnd: string;
+        title?: string;
+        agentFilter?: string[];
+        /**
+         * Client-supplied key (unique per org) — retrying with the same key
+         * returns the original bundle and does NOT charge a second operation.
+         * Use this if your job runner may replay the call on network flakes.
+         */
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    listComplianceBundles(page?: number, perPage?: number): Promise<PaginatedList<Record<string, unknown>>>;
+    getComplianceBundle(bundleId: string): Promise<Record<string, unknown>>;
+    /**
+     * Download the self-contained JSON document for the bundle. The
+     * exported document inlines every receipt's signed payload + signature
+     * and the JWKS URL so an auditor can re-verify offline.
+     */
+    exportComplianceBundle(bundleId: string): Promise<Record<string, unknown>>;
+    getBundleInclusionProof(bundleId: string, receiptId: string): Promise<Record<string, unknown>>;
+    /**
+     * Score the agent's recent behavior against its active baseline.
+     * Read-only — does NOT persist an alert. Use this for dashboards.
+     */
+    getDriftStatus(agentId: string, lookbackHours?: number): Promise<Record<string, unknown>>;
+    /** Compute a behavioral baseline from production action history. */
+    computeDriftBaseline(params: {
+        agentId: string;
+        windowStart: string;
+        windowEnd: string;
+        activate?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Seed a baseline from a config dict (for cold-start agents). */
+    seedSyntheticBaseline(params: {
+        agentId: string;
+        expectedDistribution: Record<string, number>;
+        expectedActionsPerDay: number;
+        activate?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Score the current window and persist an alert if it exceeds the threshold. */
+    runDriftCheck(agentId: string, lookbackHours?: number): Promise<Record<string, unknown> | null>;
+    listDriftAlerts(agentId: string, page?: number, acknowledged?: boolean): Promise<PaginatedList<Record<string, unknown>>>;
+    acknowledgeDriftAlert(agentId: string, alertId: string): Promise<Record<string, unknown>>;
+    /**
+     * Seal every unsettled receipt for the org into a new settlement.
+     * Admin-only. Returns the new settlement, or null if there were no
+     * unsettled receipts (no-op).
+     */
+    createSettlement(): Promise<Record<string, unknown> | null>;
+    listSettlements(page?: number, perPage?: number): Promise<PaginatedList<Record<string, unknown>>>;
+    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));
 }
@@ -46,7 +84,8 @@ class Aira {
                 return {};
             const data = (await res.json().catch(() => ({ error: res.statusText, code: "UNKNOWN" })));
             if (!res.ok) {
-                throw new types_1.AiraError(res.status, data.code ?? "UNKNOWN", data.error ?? res.statusText);
+                const message = data.message ?? res.statusText;
+                throw new types_1.AiraError(res.status, data.code ?? "UNKNOWN", message, data.details ?? {});
             }
             return data;
         }
@@ -75,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, {});
@@ -86,24 +132,55 @@ 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 };
     }
-    // ==================== Actions ====================
-    async notarize(params) {
+    // ==================== Actions (two-step: authorize → notarize) ====================
+    /**
+     * Step 1 — Authorize an action BEFORE it executes.
+     *
+     * Returns an `Authorization` with a status:
+     *  - "authorized"       → safe to execute the action, then call `notarize()`
+     *  - "pending_approval" → enqueue `action_id` and wait for human approval
+     *
+     * If a policy denies the action, this throws `AiraError` with code
+     * `POLICY_DENIED` (HTTP 403). Duplicate idempotent requests throw
+     * `DUPLICATE_REQUEST` (HTTP 409).
+     */
+    async authorize(params) {
         const body = buildBody({
             action_type: params.actionType,
             details: truncateDetails(params.details),
             agent_id: params.agentId,
             agent_version: params.agentVersion,
+            instruction_hash: params.instructionHash,
             model_id: params.modelId,
             model_version: params.modelVersion,
-            instruction_hash: params.instructionHash,
             parent_action_id: params.parentActionId,
+            endpoint_url: params.endpointUrl,
             store_details: params.storeDetails || undefined,
             idempotency_key: params.idempotencyKey,
             require_approval: params.requireApproval || undefined,
             approvers: params.approvers,
+            system_prompt_hash: params.systemPromptHash,
+            tool_inputs_hash: params.toolInputsHash,
+            model_params: params.modelParams,
+            execution_env: params.executionEnv,
         });
         return this.post("/actions", body);
     }
+    /**
+     * Step 2 — Notarize the outcome of an already-authorized action.
+     *
+     * Call this AFTER executing the action. Outcome is "completed" by default;
+     * pass "failed" if the action ran but failed so the audit trail captures
+     * the failure. The returned `ActionReceipt` carries the Ed25519 signature
+     * and RFC 3161 timestamp token when the status is "notarized".
+     */
+    async notarize(params) {
+        const body = buildBody({
+            outcome: params.outcome ?? "completed",
+            outcome_details: params.outcomeDetails,
+        });
+        return this.post(`/actions/${params.actionId}/notarize`, body);
+    }
     async getAction(actionId) {
         return this.get(`/actions/${actionId}`);
     }
@@ -113,8 +190,16 @@ class Aira {
         }));
         return this.paginated(data);
     }
-    async authorizeAction(actionId) {
-        return this.post(`/actions/${actionId}/authorize`, {});
+    /**
+     * Add a human co-signature to an action that already exists.
+     *
+     * This is distinct from the authorization gate (it runs against `/cosign`,
+     * not `/authorize`). It records that a specific human has acknowledged or
+     * signed off on an action that was already authorized and notarized.
+     * Requires JWT auth (dashboard user, not an API key).
+     */
+    async cosign(params) {
+        return this.post(`/actions/${params.actionId}/cosign`, {});
     }
     async setLegalHold(actionId) {
         return this.post(`/actions/${actionId}/hold`, {});
@@ -341,6 +426,262 @@ class Aira {
     async verifyReputation(slug) {
         return this.get(`/agents/${slug}/reputation/verify`);
     }
+    // ==================== Replay context (F10) ====================
+    /**
+     * Get all reproducibility metadata stored for an action.
+     *
+     * Returns the system_prompt_hash, tool_inputs_hash, model_params,
+     * execution_env, and other knobs that an external replay tool
+     * needs to confirm it has the same inputs as the original run.
+     */
+    async getReplayContext(actionId) {
+        return this.get(`/actions/${actionId}/replay-context`);
+    }
+    // ==================== Compliance bundles ====================
+    /**
+     * Seal a regulator-ready evidence bundle for a date range.
+     *
+     * `framework` must be one of: `eu_ai_act_art12`, `iso_42001`,
+     * `aiuc_1`, `soc_2_cc7`, `raw`.
+     */
+    async createComplianceBundle(params) {
+        const body = buildBody({
+            framework: params.framework,
+            period_start: params.periodStart,
+            period_end: params.periodEnd,
+            title: params.title,
+            agent_filter: params.agentFilter,
+            idempotency_key: params.idempotencyKey,
+        });
+        return this.post("/compliance/bundles", body);
+    }
+    async listComplianceBundles(page = 1, perPage = 20) {
+        const data = await this.get(`/compliance/bundles?page=${page}&per_page=${perPage}`);
+        return this.paginated(data);
+    }
+    async getComplianceBundle(bundleId) {
+        return this.get(`/compliance/bundles/${bundleId}`);
+    }
+    /**
+     * Download the self-contained JSON document for the bundle. The
+     * exported document inlines every receipt's signed payload + signature
+     * and the JWKS URL so an auditor can re-verify offline.
+     */
+    async exportComplianceBundle(bundleId) {
+        return this.get(`/compliance/bundles/${bundleId}/export`);
+    }
+    async getBundleInclusionProof(bundleId, receiptId) {
+        return this.get(`/compliance/bundles/${bundleId}/inclusion-proof/${receiptId}`);
+    }
+    // ==================== Drift detection ====================
+    /**
+     * Score the agent's recent behavior against its active baseline.
+     * Read-only — does NOT persist an alert. Use this for dashboards.
+     */
+    async getDriftStatus(agentId, lookbackHours = 24) {
+        return this.get(`/agents/${agentId}/drift?lookback_hours=${lookbackHours}`);
+    }
+    /** Compute a behavioral baseline from production action history. */
+    async computeDriftBaseline(params) {
+        return this.post(`/agents/${params.agentId}/drift/baseline`, buildBody({
+            window_start: params.windowStart,
+            window_end: params.windowEnd,
+            activate: params.activate ?? true,
+        }));
+    }
+    /** Seed a baseline from a config dict (for cold-start agents). */
+    async seedSyntheticBaseline(params) {
+        return this.post(`/agents/${params.agentId}/drift/baseline/synthetic`, buildBody({
+            expected_distribution: params.expectedDistribution,
+            expected_actions_per_day: params.expectedActionsPerDay,
+            activate: params.activate ?? true,
+        }));
+    }
+    /** Score the current window and persist an alert if it exceeds the threshold. */
+    async runDriftCheck(agentId, lookbackHours = 24) {
+        return this.post(`/agents/${agentId}/drift/check?lookback_hours=${lookbackHours}`, {});
+    }
+    async listDriftAlerts(agentId, page = 1, acknowledged) {
+        let params = `page=${page}&per_page=50`;
+        if (acknowledged !== undefined) {
+            params += `&acknowledged=${acknowledged}`;
+        }
+        const data = await this.get(`/agents/${agentId}/drift/alerts?${params}`);
+        return this.paginated(data);
+    }
+    async acknowledgeDriftAlert(agentId, alertId) {
+        return this.post(`/agents/${agentId}/drift/alerts/${alertId}/acknowledge`, {});
+    }
+    // ==================== Merkle settlement (F8) ====================
+    /**
+     * Seal every unsettled receipt for the org into a new settlement.
+     * Admin-only. Returns the new settlement, or null if there were no
+     * unsettled receipts (no-op).
+     */
+    async createSettlement() {
+        return this.post("/settlements", {});
+    }
+    async listSettlements(page = 1, perPage = 20) {
+        const data = await this.get(`/settlements?page=${page}&per_page=${perPage}`);
+        return this.paginated(data);
+    }
+    async getSettlement(settlementId) {
+        return this.get(`/settlements/${settlementId}`);
+    }
+    /** Get the Merkle inclusion proof for one receipt in its settlement. */
+    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) {