verdifax 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Type definitions for the Verdifax orchestrator REST API.
+ *
+ * Mirrors the canonical schemas from the OpenAPI spec at
+ * `verdifax-orchestrator/openapi/verdifax.yaml`. When the spec
+ * adds a new field, update this file alongside the OpenAPI to
+ * keep the SDK's surface in sync.
+ */
+/** A 64-character lowercase hex string — the canonical §0
+ *  SHA-256 encoding. Aliased rather than newtyped so callers
+ *  pass plain strings without ceremony. */
+type Hex64 = string;
+interface Health {
+    ok: boolean;
+    service: string;
+    version: string;
+    orchestrator_version?: string;
+    orchestrator_git_sha?: string;
+    time: string;
+}
+interface FormulaEra {
+    era: string;
+    label: string;
+}
+interface VerdifaxVersion {
+    service: string;
+    api_contract_version?: string;
+    orchestrator_version?: string;
+    orchestrator_git_sha?: string;
+    formula_version?: string;
+    formula_eras?: FormulaEra[];
+    kernel_versions?: Record<string, string>;
+    engine_versions?: Record<string, string>;
+    aivp_t4_mode?: string;
+    region?: string;
+    instance?: string;
+    time: string;
+}
+interface ExecuteRequest {
+    /** Base64-encoded payload bytes. Mutually exclusive with payload_text. */
+    payload?: string;
+    /** Plain-text payload. Mutually exclusive with payload. */
+    payload_text?: string;
+    program_id: Hex64;
+    route_id: string;
+    registry_record_hash: Hex64;
+    /** When non-empty, opts the request into the AIVP-T4 governance pipeline. */
+    ai_output_text?: string;
+    /** Caller-attested actor + decision metadata; open schema. */
+    attested_context?: Record<string, unknown>;
+}
+interface ExecuteResponse {
+    ok: boolean;
+    run_id: number;
+    manifest: ExecutionManifest;
+    duration_ms: number;
+}
+/**
+ * Sealed manifest. Field names match the orchestrator's Go-default
+ * JSON encoding (CapitalCamelCase).
+ *
+ * Subset of the canonical fields — see the orchestrator's
+ * `internal/pipeline/types.go` for the full struct. The fields
+ * listed here are the ones every Track-2 / Track-3 / Track-5
+ * surface depends on.
+ */
+interface ExecutionManifest {
+    EnvelopeID: string;
+    EnvelopeHash: Hex64;
+    ManifestHash: Hex64;
+    DseCommitmentHash?: Hex64;
+    TokOrderingHash?: Hex64;
+    DscFinalStateHash?: Hex64;
+    NrepActorID?: string;
+    NrepActorPublicKey?: string;
+    NrepSignature?: string;
+    AivpOutcome?: string;
+    AivpPiaHash?: Hex64;
+    AivpAdapterID?: string;
+    AivpDecision?: string;
+    /** Phase-17 (CRES) sealed-at-write erasure state. */
+    EraseStatus?: "intact" | "shredded" | "tombstone" | "";
+    ExecutionRegion?: string;
+    FormalVerifierStatus?: string;
+    HardwareAttestationHash?: Hex64;
+    LedgerBackend?: string;
+    LedgerLeafHash?: Hex64;
+    LedgerProofHash?: Hex64;
+    LogEntryID?: string;
+}
+interface Run {
+    ok: boolean;
+    id: number;
+    created_at: string;
+    payload_hash: Hex64;
+    program_id: Hex64;
+    route_id: string;
+    manifest_hash: Hex64;
+    duration_ms: number;
+    status: "ok" | "pepg_deny" | "ccv_halt" | "macc_halt" | "stage_error";
+    error_stage?: string;
+    error_message?: string;
+    manifest: ExecutionManifest;
+}
+interface VerifyResponse {
+    ok: boolean;
+    verified: boolean;
+    manifest_hash: Hex64;
+    recomputed_hash: Hex64;
+    formula_version: string;
+    verification_at: string;
+    verification_kind: string;
+    dcae_engine_hint?: {
+        available_at: string;
+        engine_version: string;
+    };
+}
+interface ClientConfig {
+    /** Orchestrator endpoint. Trailing slash optional. Defaults to https://api.verdifax.com. */
+    baseURL?: string;
+    /** X-Verdifax-Key value. Required for every endpoint except /health, /version, /dcae/verify. */
+    apiKey?: string;
+    /** Per-request timeout in ms. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Override the default User-Agent. Useful for telemetry attribution. */
+    userAgent?: string;
+    /** Retry budget for idempotent GET/HEAD/OPTIONS that fail with a
+     *  transient error (502/503/504/429 or network failure).
+     *  Defaults to 3. Set to 0 to disable retries entirely. */
+    maxRetries?: number;
+    /** First inter-retry sleep in ms. The retry middleware doubles
+     *  it on each subsequent retry (exponential backoff with full
+     *  jitter). Defaults to 200ms. */
+    retryBaseDelayMs?: number;
+}
+/** Friendly shape for {@link VerdifaxClient.attest}. Mirrors the
+ *  Python SDK's `attest()` signature so polyglot teams have parity. */
+interface AttestRequest {
+    /** Raw bytes — auto-base64-encoded before sending. Mutually
+     *  exclusive with `payload_text`. */
+    payload?: Buffer | Uint8Array;
+    /** Plain-text payload — sent as-is. Mutually exclusive with
+     *  `payload`. */
+    payload_text?: string;
+    program_id: Hex64;
+    route_id: string;
+    registry_record_hash: Hex64;
+    ai_output_text?: string;
+    attested_context?: Record<string, unknown>;
+}
+/** Optional filters for {@link VerdifaxClient.listRuns}. */
+interface ListRunsParams {
+    limit?: number;
+    offset?: number;
+}
+/** Lightweight projection used in `/runs` and `/runs/search`
+ *  responses. Excludes the heavy ManifestJSON; call `getRun(id)`
+ *  for the full sealed manifest. */
+interface RunSummary {
+    id: number;
+    created_at: string;
+    program_id: Hex64;
+    route_id: string;
+    manifest_hash: Hex64;
+    status: "ok" | "pepg_deny" | "ccv_halt" | "macc_halt" | "stage_error";
+    outcome_kind?: string;
+}
+/** Audit-PDF format selector. */
+type PDFFormat = "brief" | "auditor" | "legal" | "comprehensive";
+/** Body shape for {@link VerdifaxClient.adminErase}. */
+interface AdminEraseRequest {
+    run_id: number;
+    field_path: string;
+    /** SHA-256 hex of the ciphertext that was sealed for this field
+     *  at encryption time. Caller looks this up in their own records. */
+    ciphertext_hash: Hex64;
+    /** Optional opaque reference for the originating DSAR / RTBF /
+     *  HIPAA-authorization. */
+    dsar_reference?: string;
+}
+/** A sealed CRES DeletionReceipt. Mirrors the orchestrator's
+ *  `cres.DeletionReceipt` shape with snake_case JSON keys. */
+interface DeletionReceipt {
+    preimage_version: string;
+    envelope_id: string;
+    field_path: string;
+    deletion_clock: string;
+    actor_id: string;
+    ciphertext_hash_at_shred: Hex64;
+    dsar_reference?: string;
+    engine_version: string;
+    receipt_hash: Hex64;
+    id?: number;
+}
+/** Input shape for {@link VerdifaxClient.dcaeVerify}. */
+interface DCAEProofBundle {
+    preimage_version?: string;
+    envelope_id: string;
+    envelope_hash: Hex64;
+    aer_hash: Hex64;
+    zksp_binding_hash: Hex64;
+    formal_verifier_status: string;
+    manifest_hash: Hex64;
+    canonical_manifest_preimage?: string;
+}
+/** Output shape for {@link VerdifaxClient.dcaeVerify}. */
+interface DCAEVerdict {
+    verified: boolean;
+    failure_reason?: string;
+    verified_closure_hash?: Hex64;
+    engine_version: string;
+}
+/** Body returned by `POST /admin/keys`. The `secret` field is
+ *  shown ONCE — store it immediately. */
+interface AdminCreateKeyResponse {
+    ok: boolean;
+    id: number;
+    name: string;
+    secret: string;
+    hint: string;
+}
+/** Projection returned by {@link VerdifaxClient.adminListKeys}.
+ *  Secrets are NEVER surfaced — only metadata. */
+interface AdminAPIKey {
+    id: number;
+    name: string;
+    created_at: string;
+    last_used_at?: string;
+    run_count: number;
+    revoked: boolean;
+}
+
+/**
+ * The Verdifax SDK client.
+ *
+ * Carries Python-parity surface coverage:
+ *
+ * | Method | HTTP | Auth |
+ * | --- | --- | --- |
+ * | `health()` | GET /health | none |
+ * | `version()` | GET /version | none |
+ * | `execute(req)` | POST /execute | required |
+ * | `attest(req)` | POST /execute (helper) | required |
+ * | `getRun(id)` | GET /runs/{id} | required |
+ * | `verifyRun(id)` | GET /runs/{id}/verify | required |
+ * | `listRuns(params)` | GET /runs | required |
+ * | `downloadAuditPDF(id, format)` | GET /runs/{id}/report.pdf | required |
+ * | `getAllowToken(id)` | GET /runs/{id}/allow-token | required |
+ * | `getDenyReceipt(id)` | GET /runs/{id}/deny-receipt | required |
+ * | `getCCVHaltReceipt(id)` | GET /runs/{id}/ccv-halt-receipt | required |
+ * | `getMACCHaltReceipt(id)` | GET /runs/{id}/macc-halt-receipt | required |
+ * | `getAivpT4HaltReceipt(id)` | GET /runs/{id}/aivp-t4-halt-receipt | required |
+ * | `listDeletionReceipts(id)` | GET /runs/{id}/deletion-receipts | required |
+ * | `adminErase(req)` | POST /admin/erase | required |
+ * | `dcaeVerify(bundle)` | POST /dcae/verify | none |
+ * | `adminCreateKey(name)` | POST /admin/keys | required |
+ * | `adminListKeys()` | GET /admin/keys | required |
+ * | `adminRevokeKey(id)` | DELETE /admin/keys/{id} | required |
+ * | `attestClaudeResponse(...)` | POST /execute (helper) | required |
+ * | `attestOpenAIResponse(...)` | POST /execute (helper) | required |
+ *
+ * Idempotent GETs that hit a transient failure (502/503/504/429)
+ * are retried with exponential backoff + full jitter. Non-
+ * idempotent methods (POST, PUT, DELETE) are NOT retried — replay
+ * is the caller's responsibility.
+ */
+declare class VerdifaxClient {
+    private readonly baseURL;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    constructor(config?: ClientConfig);
+    health(): Promise<Health>;
+    version(): Promise<VerdifaxVersion>;
+    execute(req: ExecuteRequest): Promise<ExecuteResponse>;
+    /** High-level convenience wrapper around `execute()`. Accepts
+     *  either a Buffer (for binary payloads — auto-base64) or a
+     *  string (for plain text). Validates the hex fields and
+     *  routes the call through to the canonical /execute. */
+    attest(req: AttestRequest): Promise<ExecuteResponse>;
+    getRun(runId: number): Promise<Run>;
+    verifyRun(runId: number): Promise<VerifyResponse>;
+    listRuns(params?: ListRunsParams): Promise<{
+        runs: RunSummary[];
+        total: number;
+    }>;
+    getAllowToken(runId: number): Promise<Record<string, unknown>>;
+    getDenyReceipt(runId: number): Promise<Record<string, unknown>>;
+    getCCVHaltReceipt(runId: number): Promise<Record<string, unknown>>;
+    getMACCHaltReceipt(runId: number): Promise<Record<string, unknown>>;
+    getAivpT4HaltReceipt(runId: number): Promise<Record<string, unknown>>;
+    private getRunArtifact;
+    /** Streams the audit PDF bytes as a Buffer. Format defaults to
+     *  "comprehensive" when not specified. */
+    downloadAuditPDF(runId: number, format?: PDFFormat): Promise<Buffer>;
+    listDeletionReceipts(runId: number): Promise<DeletionReceipt[]>;
+    adminErase(req: AdminEraseRequest): Promise<DeletionReceipt>;
+    dcaeVerify(bundle: DCAEProofBundle): Promise<DCAEVerdict>;
+    adminCreateKey(name: string): Promise<AdminCreateKeyResponse>;
+    adminListKeys(): Promise<AdminAPIKey[]>;
+    adminRevokeKey(keyId: number): Promise<void>;
+    /** Convenience for attesting an Anthropic Claude API response.
+     *  Wires the response text into the AIVP-T4 governance pipeline
+     *  by setting `ai_output_text`. */
+    attestClaudeResponse(args: {
+        program_id: Hex64;
+        route_id: string;
+        registry_record_hash: Hex64;
+        prompt: string;
+        response: string;
+    }): Promise<ExecuteResponse>;
+    /** Convenience for attesting an OpenAI API response. */
+    attestOpenAIResponse(args: {
+        program_id: Hex64;
+        route_id: string;
+        registry_record_hash: Hex64;
+        prompt: string;
+        response: string;
+    }): Promise<ExecuteResponse>;
+    private attestProviderResponse;
+    private request;
+    private requireAPIKey;
+}
+
+/**
+ * Environment-variable constructor — mirrors the Python SDK's
+ * `from_env()` and the Go SDK's `FromEnv()` for polyglot parity.
+ *
+ * Variables consumed (identical names across SDKs):
+ *
+ *   VERDIFAX_BASE_URL    base URL (defaults to https://api.verdifax.com)
+ *   VERDIFAX_API_KEY     X-Verdifax-Key value
+ *   VERDIFAX_TIMEOUT_MS  per-request timeout in ms (defaults to 30000)
+ *   VERDIFAX_USER_AGENT  override the default User-Agent
+ *   VERDIFAX_MAX_RETRIES retry budget for idempotent GETs (defaults to 3)
+ */
+
+declare function fromEnv(): VerdifaxClient;
+
+/**
+ * Input-validation helpers — mirrors the Python SDK's
+ * `_validation.py` and the Go SDK's `validation.go` for
+ * cross-language parity.
+ *
+ * Every helper throws (rather than returning a boolean) so the
+ * SDK's type system surfaces the failure as a typed error.
+ */
+/** Throws unless `value` is exactly 64 lowercase hex characters —
+ *  the §0-canonical SHA-256 encoding the orchestrator expects for
+ *  program_id, registry_record_hash, manifest_hash, and
+ *  ciphertext_hash. */
+declare function validateHex64(value: string, fieldName: string): void;
+/** Throws unless `value` is a non-empty, printable-ASCII route
+ *  identifier of bounded length (≤ 256). The orchestrator accepts
+ *  a wider character set, but the SDK enforces the conservative
+ *  subset by default to catch typos early. */
+declare function validateRouteId(value: string): void;
+
+/**
+ * Typed errors returned by the Verdifax SDK.
+ *
+ * Callers can use `instanceof` to discriminate:
+ *
+ * ```typescript
+ * try {
+ *   await client.getRun(142);
+ * } catch (err) {
+ *   if (err instanceof NotFoundError) {
+ *     // run doesn't exist (or belongs to a different key)
+ *   } else if (err instanceof AuthError) {
+ *     // missing or invalid API key
+ *   } else if (err instanceof APIError) {
+ *     // every other non-2xx
+ *   }
+ * }
+ * ```
+ */
+declare class VerdifaxError extends Error {
+    readonly name: string;
+}
+/** HTTP 401 — missing or invalid API key. */
+declare class AuthError extends VerdifaxError {
+    readonly status: number;
+    readonly message: string;
+    readonly name: string;
+    constructor(status: number, message: string);
+}
+/** HTTP 404 — resource not found. Carries the path that 404'd
+ *  for easier diagnosis. */
+declare class NotFoundError extends VerdifaxError {
+    readonly path: string;
+    readonly message: string;
+    readonly name: string;
+    constructor(path: string, message: string);
+}
+/** Every other non-2xx response. Carries the HTTP status and
+ *  the path so callers can switch on either dimension. */
+declare class APIError extends VerdifaxError {
+    readonly status: number;
+    readonly path: string;
+    readonly message: string;
+    readonly name: string;
+    constructor(status: number, path: string, message: string);
+}
+/** Returned when an authenticated method is called on a client
+ *  constructed without an apiKey. */
+declare class APIKeyRequiredError extends VerdifaxError {
+    readonly name: string;
+    constructor();
+}
+
+export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, fromEnv, validateHex64, validateRouteId };