Quickstart, Node.js / TypeScript

Prerequisites

• Node.js 18 or newer (uses the built-in fetch global)

• A Verdifax orchestrator. The examples use a self-hosted one at http://localhost:9090, which needs access to the private image (see Quickstart, Docker). Without that access, use the hosted API at https://api.verdifax.com with an API key, issued after an access request at verdifax.com/request, and replace http://localhost:9090 with it below.

• An API key. On a self-hosted orchestrator, provision one. On a deployment where no key has ever been created, mint the first one with admin scope (a key minted without it is customer scope, which gets 403 on the /admin/* calls, and creating it ends open mode):

  curl -X POST http://localhost:9090/admin/keys \
    -H "Content-Type: application/json" \
    -d '{"name": "node-quickstart", "scope": "admin", "confirm_admin_scope": true}'
  

  The server answers HTTP 201, and the response carries the secret once; store it as VERDIFAX_API_KEY in your environment. Once any key has been created, POST /admin/keys requires an admin key in the X-Verdifax-Key header. See Authentication.

1. Install

npm install verdifax
# or
yarn add verdifax
# or
pnpm add verdifax

2. Three lines

import { fromEnv } from "verdifax";

const client = fromEnv();

const res = await client.attest({
  payload_text: "hello verdifax",
  program_id: "a".repeat(64),
  route_id: "route-test",
  registry_record_hash: "b".repeat(64),
});

console.log(res.manifest.ManifestHash);

fromEnv() reads VERDIFAX_BASE_URL (default https://api.verdifax.com), VERDIFAX_API_KEY, and the optional VERDIFAX_TIMEOUT_MS / VERDIFAX_MAX_RETRIES knobs. Drop the call in favor of new VerdifaxClient({...}) if you'd rather pass config explicitly.

3. Verify

The whole point of the manifest hash is that it re-derives from the run's sealed fields. The orchestrator's verify endpoint recomputes the seal from the stored manifest fields and reports whether it matches:

const v = await client.verifyRun(res.run_id);
if (v.verified) {
  console.log("✓ Stored manifest fields recompute to the recorded hash.");
}

4. Attest a Claude / OpenAI response

If you're sealing AI output text rather than arbitrary bytes, the SDK ships convenience helpers that wire the response into the AIVP governance pipeline for you:

const res = await client.attestClaudeResponse({
  program_id: "a".repeat(64),
  route_id: "support-conversation",
  registry_record_hash: "b".repeat(64),
  prompt: "What is 2+2?",
  response: "2+2 equals 4.",
});

The response text becomes the input to AIVP; the resulting PIA hash binds into the manifest. See AIVP for the deeper integration story.

5. Error handling

The SDK throws typed errors so callers can instanceof to discriminate:

import {
  VerdifaxClient,
  AuthError,
  NotFoundError,
  APIError,
} from "verdifax";

try {
  const run = 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, err.status carries the HTTP code
  }
}

What this SDK covers

21 public methods spanning the canonical operations and the key, erasure and DCAE administrative endpoints (not every admin endpoint):

Idempotent GETs that hit a transient failure (502 / 503 / 504 / 429) are retried with exponential backoff + full jitter (default 3 retries; configurable via maxRetries). Non-idempotent methods (POST / PUT / DELETE) are NOT retried, replay is the caller's responsibility.

TypeScript types

Every method has full type definitions exported from the package:

import type {
  ClientConfig,
  AttestRequest,
  ExecuteResponse,
  ExecutionManifest,
  Run,
  VerifyResponse,
  DeletionReceipt,
  DCAEProofBundle,
  DCAEVerdict,
  AdminAPIKey,
  AdminCreateKeyResponse,
  AdminEraseRequest,
  PDFFormat,
} from "verdifax";

Next steps

• Federation & multi-tenancy, how multiple organizations share a single deployment.
• Troubleshooting, common errors and their resolutions.
• Verify a bundle, offline verification of a run's audit bundle with the open-source verdifax-verify.