aira-sdk 1.0.0 → 2.4.0

package/dist/types.d.ts

@@ -1,27 +1,88 @@
-/** Cryptographic receipt from notarizing an action. */
+/**
+ * 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.
+ *
+ * Status tells you what to do next:
+ *  - "authorized"       → execute the action, then call `notarize()`
+ *  - "pending_approval" → enqueue the action_id and wait for human approval
+ *
+ * POLICY_DENIED is raised as an `AiraError` — not returned as a status.
+ */
+export interface Authorization {
+    action_id: string;
+    status: "authorized" | "pending_approval";
+    created_at: string;
+    request_id: string;
+    warnings: string[] | null;
+}
+/**
+ * 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.
+ */
 export interface ActionReceipt {
     action_id: string;
-    receipt_id?: string;
-    payload_hash?: string;
-    signature?: string;
-    timestamp_token?: string | null;
+    status: "notarized" | "failed";
     created_at: string;
     request_id: string;
-    status?: string;
-    action_type?: string;
-    agent_id?: string | null;
-    warnings?: string[] | null;
-    policy_evaluation?: {
-        policy_id: string;
-        policy_name: string;
-        decision: string;
-        reasoning: string | null;
-        confidence: number | null;
-    } | null;
+    receipt_id: string | null;
+    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;
@@ -39,6 +100,7 @@ export interface ActionDetail {
         timestamp_token: string | null;
         receipt_version: string;
         verify_url: string;
+        created_at: string | null;
     } | null;
     authorizations: {
         id: string;
@@ -46,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 {
@@ -125,7 +191,18 @@ export interface EscrowTransaction {
     description?: string | null;
     reference_action_id?: string | null;
 }
-/** Public verification result. */
+/**
+ * Result of a public action receipt verification.
+ *
+ * The endpoint actually recomputes the SHA-256 hash and verifies the
+ * Ed25519 signature against the published public key — `valid` is the
+ * result of that real cryptographic check, not just an existence check.
+ *
+ * On a successful (or tamper-detected) verification the result includes
+ * the full evidence — `signature`, `public_key`, `signed_payload`,
+ * `timestamp_token` — so an external auditor can re-run the same check
+ * with OpenSSL or any Ed25519 library without trusting Aira's verdict.
+ */
 export interface VerifyResult {
     valid: boolean;
     public_key_id: string;
@@ -134,6 +211,17 @@ export interface VerifyResult {
     request_id: string;
     receipt_id?: string | null;
     action_id?: string | null;
+    payload_hash?: string | null;
+    signature?: string | null;
+    public_key?: string | null;
+    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>> {
@@ -143,9 +231,98 @@ export interface PaginatedList<T = Record<string, unknown>> {
     per_page: number;
     has_more: boolean;
 }
-/** Aira API error. */
+/**
+ * Human co-signature on an action.
+ *
+ * Returned by `Aira.cosign()`. Records that a specific human has
+ * acknowledged or signed off on an action that was already authorized
+ * (and optionally already notarized).
+ */
+export interface CosignResult {
+    cosignature_id: string;
+    action_id: string;
+    cosigner_email: string;
+    cosigned_at: string;
+    request_id: string;
+}
+/**
+ * Aira API error.
+ *
+ * There is a single error type — catch `AiraError` and branch on
+ * `e.code` (`"POLICY_DENIED"`, `"INVALID_STATE"`, `"NOT_FOUND"`, ...).
+ * There are no subclasses per error code.
+ */
 export declare class AiraError extends Error {
-    status: number;
+    /** HTTP status code from the backend response. */
+    statusCode: number;
+    /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code: string;
-    constructor(status: number, code: string, message: string);
+    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    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,15 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiraError = void 0;
-/** Aira API error. */
+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.
+ *
+ * There is a single error type — catch `AiraError` and branch on
+ * `e.code` (`"POLICY_DENIED"`, `"INVALID_STATE"`, `"NOT_FOUND"`, ...).
+ * There are no subclasses per error code.
+ */
 class AiraError extends Error {
-    status;
+    /** HTTP status code from the backend response. */
+    statusCode;
+    /** Error code string (e.g. "POLICY_DENIED", "INVALID_STATE"). */
     code;
-    constructor(status, code, message) {
+    /** Optional backend-supplied context (policy_id, action_id, etc.). */
+    details;
+    constructor(statusCode, code, message, details = {}) {
         super(`[${code}] ${message}`);
         this.name = "AiraError";
-        this.status = status;
+        this.statusCode = statusCode;
         this.code = code;
+        this.details = details;
     }
 }
 exports.AiraError = AiraError;

package/package.json

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