verdifax 0.3.0 → 1.0.0

package/dist/index.js

@@ -23,9 +23,20 @@ __export(index_exports, {
   APIError: () => APIError,
   APIKeyRequiredError: () => APIKeyRequiredError,
   AuthError: () => AuthError,
+  CRES_ENGINE_VERSION: () => CRES_ENGINE_VERSION,
+  CRES_PREIMAGE_VERSION: () => CRES_PREIMAGE_VERSION,
+  DCAE_PREIMAGE_VERSION: () => DCAE_PREIMAGE_VERSION,
+  DSE_FORMULA_VERSION: () => DSE_FORMULA_VERSION,
+  MAX_BATCH_ROWS: () => MAX_BATCH_ROWS,
   NotFoundError: () => NotFoundError,
+  RUN_STATUSES: () => RUN_STATUSES,
   VerdifaxClient: () => VerdifaxClient,
   VerdifaxError: () => VerdifaxError,
+  captureEnvironment: () => captureEnvironment,
+  cresReceiptHash: () => cresReceiptHash,
+  dcaeClosureHash: () => dcaeClosureHash,
+  dseDispatchHash: () => dseDispatchHash,
+  formatProviderPayload: () => formatProviderPayload,
   fromEnv: () => fromEnv,
   generateRequestKeyPair: () => generateRequestKeyPair,
   requestKeyRegistrationBody: () => requestKeyRegistrationBody,
@@ -157,6 +168,49 @@ function requestKeyRegistrationBody(signingKey) {
   return { public_key, proof };
 }
 
+// src/helpers.ts
+function formatProviderPayload(provider, prompt, response) {
+  if ([provider, prompt, response].some((text) => /[\uD800-\uDFFF]/u.test(text))) {
+    throw new VerdifaxError(
+      "verdifax: provider payload text cannot be encoded as UTF-8"
+    );
+  }
+  return JSON.stringify({ prompt, provider, response });
+}
+function isProvided(value) {
+  return value !== null && value !== void 0 && value !== "" && value !== false;
+}
+function withAttestedFlag(context) {
+  const provided = Object.entries(context).some(
+    ([name, value]) => name !== "attested" && isProvided(value)
+  );
+  return { ...context, attested: provided };
+}
+function withDeclaredFlag(context) {
+  const declared = Object.entries(context).some(
+    ([name, value]) => name !== "declared" && isProvided(value) && !(Array.isArray(value) && value.length === 0)
+  );
+  return { ...context, declared };
+}
+function refuseCallerOriginHashes(substance) {
+  const origin = substance?.origin;
+  if (origin?.source_ip_hash || origin?.user_agent_hash) {
+    throw new VerdifaxError(
+      "verdifax: request_substance.origin.source_ip_hash and user_agent_hash are computed by the server and cannot be supplied"
+    );
+  }
+}
+function withExecuteFlags(req) {
+  const body = { ...req };
+  if (req.attested_context) {
+    body.attested_context = withAttestedFlag(req.attested_context);
+  }
+  if (req.reproducibility_context) {
+    body.reproducibility_context = withDeclaredFlag(req.reproducibility_context);
+  }
+  return body;
+}
+
 // src/validation.ts
 function validateHex64(value, fieldName) {
   if (typeof value !== "string" || value.length !== 64) {
@@ -187,7 +241,7 @@ function validateRouteId(value) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "1.0.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
@@ -197,7 +251,10 @@ var DEFAULT_RETRY_BASE_DELAY_MS = 200;
 var SDK_USER_AGENT = `verdifax-sdk-node/${SDK_VERSION}`;
 var HEADER_API_KEY = "X-Verdifax-Key";
 var REQUEST_KEY_PATH = "/keys/request-key";
+var HEADER_EXPORT_TOTAL = "X-Verdifax-Total";
+var HEADER_EXPORT_TRUNCATED = "X-Verdifax-Truncated";
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var MAX_BATCH_ROWS = 1e3;
 var VerdifaxClient = class {
   baseURL;
   apiKey;
@@ -222,21 +279,52 @@ var VerdifaxClient = class {
   async version() {
     return this.request("GET", "/version");
   }
+  /** The server's own API description. */
+  async getOpenAPI() {
+    return this.request("GET", "/openapi.json");
+  }
+  /** Run counts for this API key. */
+  async getStats() {
+    this.requireAPIKey();
+    return this.request("GET", "/stats");
+  }
   // ── Execute / Attest (auth) ───────────────────────────────────
   async execute(req) {
+    this.requireExecuteFields(req);
+    return this.request("POST", "/execute", this.prepared(req));
+  }
+  /** Runs one payload twice on the server and compares the manifest
+   *  hashes. One signature covers the request, and the server claims
+   *  its nonce once. Both runs are recorded. */
+  async verifyDeterminism(req) {
+    this.requireExecuteFields(req);
+    return this.request(
+      "POST",
+      "/execute/verify-determinism",
+      this.prepared(req)
+    );
+  }
+  /** Sends up to {@link MAX_BATCH_ROWS} runs in one request. With a
+   *  signing key each row carries its own signature and nonce. A row
+   *  that fails comes back in `results` with `ok: false`, so the call
+   *  does not throw for it. The rows are not checked here: the server
+   *  reports a bad row in that row's result.
+   *
+   *  This is one POST and it is never retried. After a timeout the
+   *  server may have run some or all of the rows. */
+  async executeBatch(runs) {
     this.requireAPIKey();
-    if (!req.payload && !req.payload_text) {
-      throw new VerdifaxError(
-        "verdifax: ExecuteRequest needs payload or payload_text"
-      );
+    if (!Array.isArray(runs) || runs.length === 0) {
+      throw new VerdifaxError("verdifax: executeBatch needs at least one run");
     }
-    if (!req.program_id || !req.route_id || !req.registry_record_hash) {
+    if (runs.length > MAX_BATCH_ROWS) {
       throw new VerdifaxError(
-        "verdifax: program_id, route_id, and registry_record_hash are required"
+        `verdifax: executeBatch accepts at most ${MAX_BATCH_ROWS} runs (got ${runs.length})`
       );
     }
-    const body = this.signingKey ? { ...req, request_signature: signRequest(this.signingKey, req) } : req;
-    return this.request("POST", "/execute", body);
+    return this.request("POST", "/execute/batch", {
+      runs: runs.map((run) => this.prepared(run))
+    });
   }
   /** High-level convenience wrapper around `execute()`. Accepts
    *  either a Buffer (for binary payloads, auto-base64) or a
@@ -262,7 +350,12 @@ var VerdifaxClient = class {
       route_id: req.route_id,
       registry_record_hash: req.registry_record_hash,
       ai_output_text: req.ai_output_text,
-      attested_context: req.attested_context
+      attested_context: req.attested_context,
+      reproducibility_context: req.reproducibility_context,
+      request_substance: req.request_substance,
+      authorization_chain: req.authorization_chain,
+      regulatory_scaffolding: req.regulatory_scaffolding,
+      causal_graph: req.causal_graph
     };
     if (req.payload !== void 0) {
       body.payload = Buffer.isBuffer(req.payload) ? req.payload.toString("base64") : Buffer.from(req.payload).toString("base64");
@@ -319,6 +412,94 @@ var VerdifaxClient = class {
     const out = await this.request("GET", path);
     return { runs: out.runs ?? [], total: out.total ?? 0 };
   }
+  /** Searches this key's runs. `manifest_hash` matches a prefix. The
+   *  server ignores a `from` or `to` it cannot parse here, unlike
+   *  {@link exportRuns}, which refuses one. */
+  async searchRuns(params = {}) {
+    this.requireAPIKey();
+    const q = new URLSearchParams();
+    for (const name of [
+      "manifest_hash",
+      "program_id",
+      "route_id",
+      "status",
+      "from",
+      "to"
+    ]) {
+      const value = params[name];
+      if (value) q.set(name, value);
+    }
+    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/search?${qs}` : "/runs/search";
+    const out = await this.request("GET", path);
+    return { runs: out.runs ?? [], total: out.total ?? 0 };
+  }
+  /** Lists what the server holds for this key in a period, failures
+   *  included, up to 10,000 rows. `truncated` is true when the period
+   *  holds more. The list states what was stored, not a verdict, and a
+   *  call that never reached Verdifax cannot appear in it. */
+  async exportRuns(params = {}) {
+    this.requireAPIKey();
+    return this.request("GET", this.exportPath(params, "json"));
+  }
+  /** The same rows as {@link exportRuns}: the raw CSV text with `total`
+   *  and `truncated` from the response headers. Check `truncated`: when
+   *  true, the CSV is missing rows for the period. Throws when the server
+   *  does not send those headers, so that a cut-off export cannot pass
+   *  for a complete one. */
+  async exportRunsCSV(params = {}) {
+    this.requireAPIKey();
+    const { text, headers } = await this.requestRaw(
+      this.exportPath(params, "csv")
+    );
+    const total = Number.parseInt(headers.get(HEADER_EXPORT_TOTAL) ?? "", 10);
+    const truncated = headers.get(HEADER_EXPORT_TRUNCATED);
+    if (!Number.isSafeInteger(total) || truncated !== "true" && truncated !== "false") {
+      throw new VerdifaxError(
+        `verdifax: the server did not report ${HEADER_EXPORT_TOTAL} and ${HEADER_EXPORT_TRUNCATED}, so this CSV may be cut off; use exportRuns instead`
+      );
+    }
+    return { csv: text, total, truncated: truncated === "true" };
+  }
+  exportPath(params, format) {
+    const q = new URLSearchParams();
+    if (params.from) q.set("from", params.from);
+    if (params.to) q.set("to", params.to);
+    q.set("format", format);
+    return `/runs/export?${q.toString()}`;
+  }
+  // ── Attestation receipts (auth) ──────────────────────────────
+  async listAttestations(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();
+    return this.request(
+      "GET",
+      qs ? `/attestations?${qs}` : "/attestations"
+    );
+  }
+  async getAttestation(attestationId) {
+    this.requireAPIKey();
+    if (attestationId <= 0) {
+      throw new VerdifaxError("verdifax: attestationId must be > 0");
+    }
+    return this.request(
+      "GET",
+      `/attestations/${attestationId}`
+    );
+  }
   // ── Sealed-artifact retrieval (auth) ─────────────────────────
   async getAllowToken(runId) {
     return this.getRunArtifact(runId, "allow-token");
@@ -335,6 +516,39 @@ var VerdifaxClient = class {
   async getAivpT4HaltReceipt(runId) {
     return this.getRunArtifact(runId, "aivp-t4-halt-receipt");
   }
+  async getAttestationGapReceipt(runId) {
+    return this.getRunArtifact(runId, "attestation-gap-receipt");
+  }
+  async getCESAuditRecord(runId) {
+    return this.getRunArtifact(runId, "ces-audit-record");
+  }
+  /** The audit report for a run, as JSON. */
+  async getRunReport(runId) {
+    const out = await this.getRunArtifact(runId, "report");
+    return out.report;
+  }
+  /** The run's sealed audit bundle as the exact JSON text the server
+   *  sent, to save and check with `verdifax-verify`. It is not parsed:
+   *  JSON.parse would round a number above 2^53 and the recomputed hash
+   *  would stop matching. */
+  async getRunArtifacts(runId) {
+    this.requireAPIKey();
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    return (await this.requestRaw(`/runs/${runId}/artifacts`)).text;
+  }
+  /** The public audit bundle of a record published by run id, as the
+   *  exact JSON text the server sent. Needs no API key. */
+  async getPublicBundle(runId) {
+    if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
+    return (await this.requestRaw(`/runs/${runId}/bundle.json`)).text;
+  }
+  /** The public audit bundle a share token points to, as the exact JSON
+   *  text the server sent. Needs no API key. */
+  async getPublicBundleByToken(token) {
+    if (!token) throw new VerdifaxError("verdifax: token is required");
+    const path = `/public/runs/${encodeURIComponent(token)}/bundle.json`;
+    return (await this.requestRaw(path)).text;
+  }
   async getRunArtifact(runId, suffix) {
     this.requireAPIKey();
     if (runId <= 0) throw new VerdifaxError("verdifax: runId must be > 0");
@@ -421,13 +635,15 @@ var VerdifaxClient = class {
     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 governance pipeline
-   *  by setting `ai_output_text`. */
+  /** Convenience for attesting an Anthropic Claude API response. With
+   *  `govern: true` the response text also goes to the AIVP review as
+   *  `ai_output_text`; that is off by default, so the text leaves your
+   *  machine for review only when you ask. */
   async attestClaudeResponse(args) {
     return this.attestProviderResponse({ ...args, provider: "anthropic" });
   }
-  /** Convenience for attesting an OpenAI API response. */
+  /** Convenience for attesting an OpenAI API response. `govern` works as
+   *  in {@link attestClaudeResponse}. */
   async attestOpenAIResponse(args) {
     return this.attestProviderResponse({ ...args, provider: "openai" });
   }
@@ -437,17 +653,16 @@ var VerdifaxClient = class {
         "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,
+      payload_text: formatProviderPayload(
+        args.provider,
+        args.prompt,
+        args.response
+      ),
       program_id: args.program_id,
       route_id: args.route_id,
       registry_record_hash: args.registry_record_hash,
-      ai_output_text: args.response,
+      ai_output_text: args.govern ? args.response : void 0,
       attested_context: {
         actor_role: "ai_assistant",
         model_provider: args.provider
@@ -455,7 +670,7 @@ var VerdifaxClient = class {
     });
   }
   // ── HTTP plumbing, retry-aware ──────────────────────────────
-  async request(method, path, body) {
+  async request(method, path, body, rawText = false) {
     const url = this.baseURL + path;
     const headers = {
       "User-Agent": this.userAgent
@@ -512,6 +727,7 @@ var VerdifaxClient = class {
             throw new APIError(resp.status, path, errMessage);
         }
       }
+      if (rawText) return { text, headers: resp.headers };
       if (text.length === 0) return void 0;
       try {
         return JSON.parse(text);
@@ -525,17 +741,44 @@ var VerdifaxClient = class {
       `verdifax: retry budget exhausted${lastErr ? `: ${String(lastErr)}` : ""}`
     );
   }
+  /** A GET whose body is kept as sent, retried like any other GET. */
+  requestRaw(path) {
+    return this.request("GET", path, void 0, true);
+  }
   requireAPIKey() {
     if (!this.apiKey) throw new APIKeyRequiredError();
   }
+  requireExecuteFields(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"
+      );
+    }
+    validateHex64(req.program_id, "program_id");
+    validateHex64(req.registry_record_hash, "registry_record_hash");
+    validateRouteId(req.route_id);
+    refuseCallerOriginHashes(req.request_substance);
+  }
+  /** The request with its derived flags and, with a signing key, a fresh
+   *  signature and nonce, on a copy. */
+  prepared(req) {
+    const body = withExecuteFlags(req);
+    return this.signingKey ? { ...body, request_signature: signRequest(this.signingKey, body) } : body;
+  }
 };
 
 // src/config.ts
 function fromEnv() {
   const cfg = {
-    baseURL: process.env.VERDIFAX_BASE_URL ?? void 0,
+    baseURL: process.env.VERDIFAX_BASE_URL || process.env.VERDIFAX_API_URL || void 0,
     apiKey: process.env.VERDIFAX_API_KEY ?? void 0,
-    userAgent: process.env.VERDIFAX_USER_AGENT ?? void 0
+    userAgent: process.env.VERDIFAX_USER_AGENT || void 0
   };
   const timeoutRaw = process.env.VERDIFAX_TIMEOUT_MS;
   if (timeoutRaw !== void 0 && timeoutRaw !== "") {
@@ -559,14 +802,177 @@ function fromEnv() {
   }
   return new VerdifaxClient(cfg);
 }
+
+// src/environment.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var HASH_64 = /^[0-9a-f]{64}$/;
+var GIT_SHA = /^([0-9a-f]{40}|[0-9a-f]{64})$/;
+var PLATFORM_NAMES = { win32: "windows" };
+var ARCH_NAMES = { x64: "amd64", ia32: "386" };
+function packageVersion(dir) {
+  try {
+    const pkg = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(dir, "package.json"), "utf8"));
+    return pkg.name && pkg.version ? `${pkg.name}==${pkg.version}` : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function packageDirs(root) {
+  const dirs = [];
+  for (const entry of (0, import_node_fs.readdirSync)(root)) {
+    if (entry.startsWith(".")) continue;
+    if (!entry.startsWith("@")) {
+      dirs.push((0, import_node_path.join)(root, entry));
+      continue;
+    }
+    for (const scoped of (0, import_node_fs.readdirSync)((0, import_node_path.join)(root, entry))) {
+      dirs.push((0, import_node_path.join)(root, entry, scoped));
+    }
+  }
+  return dirs;
+}
+function detectDependencies() {
+  try {
+    const pins = packageDirs((0, import_node_path.join)(process.cwd(), "node_modules")).map(packageVersion).filter((pin) => pin !== void 0);
+    pins.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+    return pins.length > 0 ? pins : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function detectGitSHA() {
+  try {
+    const sha = (0, import_node_child_process.execFileSync)("git", ["rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    }).trim().toLowerCase();
+    return GIT_SHA.test(sha) ? sha : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function detectContainerHash() {
+  try {
+    const text = (0, import_node_fs.readFileSync)("/proc/self/cgroup", "utf8");
+    return text.split("\n").flatMap((line) => line.split("/")).map((segment) => segment.trim()).find((segment) => HASH_64.test(segment));
+  } catch {
+    return void 0;
+  }
+}
+function captureEnvironment(options = {}) {
+  const seeds = Object.entries(options.declaredSeeds ?? {}).map(([name, seed]) => `${name}=${seed}`).sort();
+  const pinned = options.includeDependencies === false ? void 0 : detectDependencies();
+  const git = options.includeGit === false ? void 0 : detectGitSHA();
+  const container = options.includeContainer === false ? void 0 : detectContainerHash();
+  const os = PLATFORM_NAMES[process.platform] ?? process.platform;
+  const arch = ARCH_NAMES[process.arch] ?? process.arch;
+  return {
+    declared: true,
+    runtime_name: "node",
+    runtime_version: process.versions.node,
+    platform: `${os}/${arch}`,
+    ...pinned ? { pinned_dependencies: pinned } : {},
+    ...git ? { git_commit_sha: git } : {},
+    ...container ? { container_image_hash: container } : {},
+    ...seeds.length > 0 ? { random_seeds: seeds } : {}
+  };
+}
+
+// src/types.ts
+var RUN_STATUSES = [
+  "ok",
+  "probe",
+  "pepg_deny",
+  "ccv_halt",
+  "macc_halt",
+  "aivp_t4_halt",
+  "attestation_gap",
+  "stage_error"
+];
+
+// src/section0.ts
+var import_node_crypto2 = require("crypto");
+var DSE_FORMULA_VERSION = "dse.tcu.dispatch.v1";
+var DCAE_PREIMAGE_VERSION = "verdifax.dcae.v1";
+var CRES_PREIMAGE_VERSION = "verdifax.cres.v1";
+var CRES_ENGINE_VERSION = "verdifax-cres/1.0.0";
+function sha256Hex(preimage) {
+  return (0, import_node_crypto2.createHash)("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
+}
+function requireHex64(value, name) {
+  try {
+    validateHex64(value, name);
+  } catch (err) {
+    throw new VerdifaxError(
+      `verdifax: section0: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function dseDispatchHash(fields) {
+  requireHex64(fields.program_id, "program_id");
+  requireHex64(fields.registry_record_hash, "registry_record_hash");
+  return sha256Hex(
+    [
+      DSE_FORMULA_VERSION,
+      fields.envelope_id,
+      fields.sequence_id,
+      fields.program_id,
+      fields.registry_record_hash
+    ].join(".")
+  );
+}
+function dcaeClosureHash(fields) {
+  requireHex64(fields.manifest_hash, "manifest_hash");
+  requireHex64(fields.aer_hash, "aer_hash");
+  requireHex64(fields.zksp_binding_hash, "zksp_binding_hash");
+  return sha256Hex(
+    [
+      DCAE_PREIMAGE_VERSION,
+      fields.manifest_hash,
+      fields.aer_hash,
+      fields.envelope_id,
+      fields.zksp_binding_hash,
+      fields.formal_verifier_status
+    ].join("|")
+  );
+}
+function cresReceiptHash(fields) {
+  requireHex64(fields.ciphertext_hash_at_shred, "ciphertext_hash_at_shred");
+  return sha256Hex(
+    [
+      CRES_PREIMAGE_VERSION,
+      fields.envelope_id,
+      fields.field_path,
+      fields.deletion_clock,
+      fields.actor_id,
+      fields.ciphertext_hash_at_shred,
+      fields.dsar_reference,
+      fields.engine_version ?? CRES_ENGINE_VERSION
+    ].join("|")
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
   APIKeyRequiredError,
   AuthError,
+  CRES_ENGINE_VERSION,
+  CRES_PREIMAGE_VERSION,
+  DCAE_PREIMAGE_VERSION,
+  DSE_FORMULA_VERSION,
+  MAX_BATCH_ROWS,
   NotFoundError,
+  RUN_STATUSES,
   VerdifaxClient,
   VerdifaxError,
+  captureEnvironment,
+  cresReceiptHash,
+  dcaeClosureHash,
+  dseDispatchHash,
+  formatProviderPayload,
   fromEnv,
   generateRequestKeyPair,
   requestKeyRegistrationBody,