verdifax 0.2.0

package/dist/index.mjs

@@ -0,0 +1,426 @@
+// src/errors.ts
+var VerdifaxError = class extends Error {
+  name = "VerdifaxError";
+};
+var AuthError = class extends VerdifaxError {
+  constructor(status, message) {
+    super(`verdifax: auth error (HTTP ${status}): ${message}`);
+    this.status = status;
+    this.message = message;
+  }
+  status;
+  message;
+  name = "VerdifaxAuthError";
+};
+var NotFoundError = class extends VerdifaxError {
+  constructor(path, message) {
+    super(`verdifax: not found at ${path}: ${message}`);
+    this.path = path;
+    this.message = message;
+  }
+  path;
+  message;
+  name = "VerdifaxNotFoundError";
+};
+var APIError = class extends VerdifaxError {
+  constructor(status, path, message) {
+    super(`verdifax: API error at ${path} (HTTP ${status}): ${message}`);
+    this.status = status;
+    this.path = path;
+    this.message = message;
+  }
+  status;
+  path;
+  message;
+  name = "VerdifaxAPIError";
+};
+var APIKeyRequiredError = class extends VerdifaxError {
+  name = "VerdifaxAPIKeyRequiredError";
+  constructor() {
+    super("verdifax: apiKey is required for this endpoint");
+  }
+};
+
+// src/validation.ts
+function validateHex64(value, fieldName) {
+  if (typeof value !== "string" || value.length !== 64) {
+    throw new VerdifaxError(
+      `verdifax: ${fieldName} must be 64 hex characters (got ${typeof value === "string" ? value.length : typeof value})`
+    );
+  }
+  if (!/^[0-9a-f]{64}$/.test(value)) {
+    throw new VerdifaxError(
+      `verdifax: ${fieldName} must contain only lowercase hex (0-9, a-f)`
+    );
+  }
+}
+function validateRouteId(value) {
+  if (!value || typeof value !== "string") {
+    throw new VerdifaxError("verdifax: route_id is required");
+  }
+  if (value.length > 256) {
+    throw new VerdifaxError(
+      `verdifax: route_id is too long (${value.length} > 256)`
+    );
+  }
+  if (!/^[\x20-\x7E]+$/.test(value)) {
+    throw new VerdifaxError(
+      "verdifax: route_id contains non-printable-ASCII character"
+    );
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.verdifax.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_DELAY_MS = 200;
+var SDK_USER_AGENT = "verdifax-sdk-node/0.2.0";
+var HEADER_API_KEY = "X-Verdifax-Key";
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var VerdifaxClient = class {
+  baseURL;
+  apiKey;
+  timeoutMs;
+  userAgent;
+  maxRetries;
+  retryBaseDelayMs;
+  constructor(config = {}) {
+    this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey ?? "";
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = config.userAgent ?? SDK_USER_AGENT;
+    this.maxRetries = config.maxRetries === void 0 ? DEFAULT_MAX_RETRIES : Math.max(0, config.maxRetries);
+    this.retryBaseDelayMs = config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+  }
+  // ── Health + Version (anonymous) ──────────────────────────────
+  async health() {
+    return this.request("GET", "/health");
+  }
+  async version() {
+    return this.request("GET", "/version");
+  }
+  // ── Execute / Attest (auth) ───────────────────────────────────
+  async execute(req) {
+    this.requireAPIKey();
+    if (!req.payload && !req.payload_text) {
+      throw new VerdifaxError(
+        "verdifax: ExecuteRequest needs payload or payload_text"
+      );
+    }
+    if (!req.program_id || !req.route_id || !req.registry_record_hash) {
+      throw new VerdifaxError(
+        "verdifax: program_id, route_id, and registry_record_hash are required"
+      );
+    }
+    return this.request("POST", "/execute", req);
+  }
+  /** 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. */
+  async attest(req) {
+    this.requireAPIKey();
+    if (req.payload !== void 0 && req.payload_text !== void 0) {
+      throw new VerdifaxError(
+        "verdifax: attest accepts payload OR payload_text, not both"
+      );
+    }
+    if (req.payload === void 0 && req.payload_text === void 0) {
+      throw new VerdifaxError(
+        "verdifax: attest needs payload or payload_text"
+      );
+    }
+    validateHex64(req.program_id, "program_id");
+    validateHex64(req.registry_record_hash, "registry_record_hash");
+    validateRouteId(req.route_id);
+    const body = {
+      program_id: req.program_id,
+      route_id: req.route_id,
+      registry_record_hash: req.registry_record_hash,
+      ai_output_text: req.ai_output_text,
+      attested_context: req.attested_context
+    };
+    if (req.payload !== void 0) {
+      body.payload = Buffer.isBuffer(req.payload) ? req.payload.toString("base64") : Buffer.from(req.payload).toString("base64");
+    } else {
+      body.payload_text = req.payload_text;
+    }
+    return this.execute(body);
+  }
+  // ── Runs ──────────────────────────────────────────────────────
+  async getRun(runId) {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    return this.request("GET", `/runs/${runId}`);
+  }
+  async verifyRun(runId) {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    return this.request("GET", `/runs/${runId}/verify`);
+  }
+  async listRuns(params = {}) {
+    this.requireAPIKey();
+    const q = new URLSearchParams();
+    if (params.limit && params.limit > 0) {
+      q.set("limit", String(params.limit));
+    }
+    if (params.offset && params.offset > 0) {
+      q.set("offset", String(params.offset));
+    }
+    const qs = q.toString();
+    const path = qs ? `/runs?${qs}` : "/runs";
+    const out = await this.request("GET", path);
+    return { runs: out.runs ?? [], total: out.total ?? 0 };
+  }
+  // ── Sealed-artifact retrieval (auth) ─────────────────────────
+  async getAllowToken(runId) {
+    return this.getRunArtifact(runId, "allow-token");
+  }
+  async getDenyReceipt(runId) {
+    return this.getRunArtifact(runId, "deny-receipt");
+  }
+  async getCCVHaltReceipt(runId) {
+    return this.getRunArtifact(runId, "ccv-halt-receipt");
+  }
+  async getMACCHaltReceipt(runId) {
+    return this.getRunArtifact(runId, "macc-halt-receipt");
+  }
+  async getAivpT4HaltReceipt(runId) {
+    return this.getRunArtifact(runId, "aivp-t4-halt-receipt");
+  }
+  async getRunArtifact(runId, suffix) {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    return this.request(
+      "GET",
+      `/runs/${runId}/${suffix}`
+    );
+  }
+  // ── Audit PDF (auth) ─────────────────────────────────────────
+  /** Streams the audit PDF bytes as a Buffer. Format defaults to
+   *  "comprehensive" when not specified. */
+  async downloadAuditPDF(runId, format = "comprehensive") {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    const path = `/runs/${runId}/report.pdf?format=${encodeURIComponent(format)}`;
+    const headers = {
+      "User-Agent": this.userAgent,
+      [HEADER_API_KEY]: this.apiKey
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await fetch(this.baseURL + path, {
+        method: "GET",
+        headers,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!resp.ok) {
+      throw new APIError(resp.status, path, "audit PDF download failed");
+    }
+    const buf = await resp.arrayBuffer();
+    return Buffer.from(buf);
+  }
+  // ── CRES — deletion receipts (auth) ──────────────────────────
+  async listDeletionReceipts(runId) {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    const out = await this.request("GET", `/runs/${runId}/deletion-receipts`);
+    return out.receipts ?? [];
+  }
+  async adminErase(req) {
+    this.requireAPIKey();
+    if (!req.run_id || req.run_id <= 0) {
+      throw new VerdifaxError("verdifax: run_id must be > 0");
+    }
+    if (!req.field_path) {
+      throw new VerdifaxError("verdifax: field_path is required");
+    }
+    validateHex64(req.ciphertext_hash, "ciphertext_hash");
+    const out = await this.request("POST", "/admin/erase", req);
+    return out.deletion_receipt;
+  }
+  // ── DCAE stateless verification (anonymous) ──────────────────
+  async dcaeVerify(bundle) {
+    return this.request("POST", "/dcae/verify", bundle);
+  }
+  // ── Admin: API keys (auth) ───────────────────────────────────
+  async adminCreateKey(name) {
+    this.requireAPIKey();
+    if (!name) {
+      throw new VerdifaxError("verdifax: name is required for adminCreateKey");
+    }
+    return this.request("POST", "/admin/keys", {
+      name
+    });
+  }
+  async adminListKeys() {
+    this.requireAPIKey();
+    const out = await this.request(
+      "GET",
+      "/admin/keys"
+    );
+    return out.keys ?? [];
+  }
+  async adminRevokeKey(keyId) {
+    this.requireAPIKey();
+    if (keyId <= 0) {
+      throw new VerdifaxError("verdifax: keyId must be > 0");
+    }
+    await this.request("DELETE", `/admin/keys/${keyId}`);
+  }
+  // ── Provider helpers (Claude / OpenAI) ───────────────────────
+  /** Convenience for attesting an Anthropic Claude API response.
+   *  Wires the response text into the AIVP-T4 governance pipeline
+   *  by setting `ai_output_text`. */
+  async attestClaudeResponse(args) {
+    return this.attestProviderResponse({ ...args, provider: "anthropic" });
+  }
+  /** Convenience for attesting an OpenAI API response. */
+  async attestOpenAIResponse(args) {
+    return this.attestProviderResponse({ ...args, provider: "openai" });
+  }
+  async attestProviderResponse(args) {
+    if (!args.response) {
+      throw new VerdifaxError(
+        "verdifax: response is required for attestation"
+      );
+    }
+    const payloadText = JSON.stringify({
+      provider: args.provider,
+      prompt: args.prompt,
+      response: args.response
+    });
+    return this.attest({
+      payload_text: payloadText,
+      program_id: args.program_id,
+      route_id: args.route_id,
+      registry_record_hash: args.registry_record_hash,
+      ai_output_text: args.response,
+      attested_context: {
+        actor_role: "ai_assistant",
+        model_provider: args.provider
+      }
+    });
+  }
+  // ── HTTP plumbing — retry-aware ──────────────────────────────
+  async request(method, path, body) {
+    const url = this.baseURL + path;
+    const headers = {
+      "User-Agent": this.userAgent
+    };
+    if (this.apiKey) headers[HEADER_API_KEY] = this.apiKey;
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const isRetryable = method === "GET" || method === "HEAD" || method === "OPTIONS";
+    const maxAttempts = isRetryable ? this.maxRetries + 1 : 1;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (attempt > 0) {
+        const max = this.retryBaseDelayMs * Math.pow(2, attempt - 1);
+        const sleep = Math.floor(Math.random() * (max + 1));
+        await new Promise((r) => setTimeout(r, sleep));
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let resp;
+      try {
+        resp = await fetch(url, {
+          method,
+          headers,
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (err) {
+        lastErr = err;
+        if (!isRetryable || attempt === maxAttempts - 1) {
+          throw new VerdifaxError(
+            `verdifax: HTTP transport: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+      const text = await resp.text();
+      if (!resp.ok) {
+        if (isRetryable && RETRYABLE_STATUSES.has(resp.status) && attempt < maxAttempts - 1) {
+          continue;
+        }
+        let errMessage = text.trim();
+        try {
+          const env = JSON.parse(text);
+          if (env.error) errMessage = env.error;
+        } catch {
+        }
+        switch (resp.status) {
+          case 401:
+            throw new AuthError(resp.status, errMessage);
+          case 404:
+            throw new NotFoundError(path, errMessage);
+          default:
+            throw new APIError(resp.status, path, errMessage);
+        }
+      }
+      if (text.length === 0) return void 0;
+      try {
+        return JSON.parse(text);
+      } catch (err) {
+        throw new VerdifaxError(
+          `verdifax: failed to decode response body at ${path}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    throw new VerdifaxError(
+      `verdifax: retry budget exhausted${lastErr ? `: ${String(lastErr)}` : ""}`
+    );
+  }
+  requireAPIKey() {
+    if (!this.apiKey) throw new APIKeyRequiredError();
+  }
+};
+
+// src/config.ts
+function fromEnv() {
+  const cfg = {
+    baseURL: process.env.VERDIFAX_BASE_URL ?? void 0,
+    apiKey: process.env.VERDIFAX_API_KEY ?? void 0,
+    userAgent: process.env.VERDIFAX_USER_AGENT ?? void 0
+  };
+  const timeoutRaw = process.env.VERDIFAX_TIMEOUT_MS;
+  if (timeoutRaw !== void 0 && timeoutRaw !== "") {
+    const ms = Number.parseInt(timeoutRaw, 10);
+    if (!Number.isFinite(ms)) {
+      throw new VerdifaxError(
+        `verdifax: VERDIFAX_TIMEOUT_MS=${timeoutRaw} is not an integer`
+      );
+    }
+    cfg.timeoutMs = ms;
+  }
+  const retriesRaw = process.env.VERDIFAX_MAX_RETRIES;
+  if (retriesRaw !== void 0 && retriesRaw !== "") {
+    const n = Number.parseInt(retriesRaw, 10);
+    if (!Number.isFinite(n)) {
+      throw new VerdifaxError(
+        `verdifax: VERDIFAX_MAX_RETRIES=${retriesRaw} is not an integer`
+      );
+    }
+    cfg.maxRetries = n;
+  }
+  return new VerdifaxClient(cfg);
+}
+export {
+  APIError,
+  APIKeyRequiredError,
+  AuthError,
+  NotFoundError,
+  VerdifaxClient,
+  VerdifaxError,
+  fromEnv,
+  validateHex64,
+  validateRouteId
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "verdifax",
+  "version": "0.2.0",
+  "description": "Official Node.js / TypeScript SDK for the Verdifax orchestrator REST API.",
+  "license": "MIT",
+  "author": "Verdifax <team@verdifax.com>",
+  "homepage": "https://verdifax.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Verdifax/verdifax-sdk-node.git"
+  },
+  "keywords": [
+    "verdifax",
+    "attestation",
+    "ai",
+    "audit",
+    "compliance",
+    "manifest",
+    "hash",
+    "cryptographic",
+    "provenance",
+    "gdpr",
+    "hipaa"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "node --test --test-reporter=spec test/*.test.mjs",
+    "test:build": "npm run build && npm test",
+    "lint": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}