verdifax 1.4.0 → 1.5.0

package/dist/index.mjs

@@ -48,6 +48,17 @@ var APIKeyRequiredError = class extends VerdifaxError {
     super("verdifax: apiKey is required for this endpoint");
   }
 };
+var SignalFeedError = class extends VerdifaxError {
+  constructor(lastSequence, reason, options) {
+    super(
+      `verdifax: the signal feed stopped after sequence ${lastSequence}: ${reason}; follow again with after: ${lastSequence}`,
+      options
+    );
+    this.lastSequence = lastSequence;
+  }
+  lastSequence;
+  name = "VerdifaxSignalFeedError";
+};
 
 // src/signing.ts
 import {
@@ -96,6 +107,18 @@ function validateJobName(value, fieldName) {
     );
   }
 }
+function requirePositiveId(id, name) {
+  if (!Number.isSafeInteger(id) || id <= 0) {
+    throw new VerdifaxError(`verdifax: ${name} must be a whole number > 0`);
+  }
+}
+function asOwnerOf(options, method) {
+  const asOwner = options?.asOwner;
+  if (asOwner !== void 0 && typeof asOwner !== "boolean") {
+    throw new VerdifaxError(`verdifax: ${method} asOwner must be true or false`);
+  }
+  return asOwner === true;
+}
 
 // src/helpers.ts
 function formatProviderPayload(provider, prompt, response) {
@@ -692,8 +715,324 @@ var VerdifaxJob = class {
   }
 };
 
+// src/signals.ts
+import { createHash as createHash2, createHmac, timingSafeEqual } from "crypto";
+var SIGNAL_FORM = "verdifax.signal.v1";
+var SIGNALS_PATH = "/signals";
+var ACCOUNT_SIGNALS_PATH = "/account/signals";
+var FEED_KEYS_PATH = "/account/feed-keys";
+var WEBHOOKS_PATH = "/account/webhooks";
+var MAX_SIGNAL_LIMIT = 500;
+var MAX_SIGNAL_WAIT_SECONDS = 25;
+var DEFAULT_FOLLOW_WAIT_SECONDS = 25;
+var SIGNAL_TIMEOUT_MARGIN_MS = 3e4;
+var EMPTY_PAGE_PAUSE_MS = 1e3;
+var MAX_DELIVERY_LIMIT = 500;
+var MAX_FEED_KEY_NAME_BYTES = 200;
+var WEBHOOK_SECRET_PREFIX = "whsec_";
+var WEBHOOK_SIGNATURE_VERSION = "v1";
+var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+var HMAC_SHA256_BYTES = 32;
+var SIGNAL_KINDS = Object.freeze([
+  "run.refused",
+  "run.halted",
+  "run.failed",
+  "policy.changed",
+  "signoff.recorded",
+  "approver.registered",
+  "approver.revoked",
+  "key.created",
+  "key.revoked"
+]);
+function signalsRead(options, method, clientTimeoutMs) {
+  const asOwner = asOwnerOf(options, method);
+  const after = given(options?.after, 0);
+  const limit = options?.limit;
+  const wait = given(options?.wait, 0);
+  requireAfter(after, method);
+  if (limit !== void 0) requireLimit(limit, method, MAX_SIGNAL_LIMIT);
+  requireWait(wait, method);
+  const q = new URLSearchParams();
+  q.set("after", String(after));
+  if (limit !== void 0) q.set("limit", String(limit));
+  q.set("wait", String(wait));
+  return {
+    path: `${asOwner ? ACCOUNT_SIGNALS_PATH : SIGNALS_PATH}?${q.toString()}`,
+    timeoutMs: Math.max(clientTimeoutMs, wait * 1e3 + SIGNAL_TIMEOUT_MARGIN_MS)
+  };
+}
+function followStart(options) {
+  const method = "followSignals";
+  const asOwner = asOwnerOf(options, method);
+  const after = given(options?.after, 0);
+  const wait = given(options?.wait, DEFAULT_FOLLOW_WAIT_SECONDS);
+  requireAfter(after, method);
+  requireWait(wait, method);
+  return { after, wait, asOwner };
+}
+async function* followSignalFeed(read, start) {
+  let last = start.after;
+  for (; ; ) {
+    let page;
+    try {
+      page = await read(last);
+    } catch (err) {
+      throw new SignalFeedError(
+        last,
+        err instanceof Error ? err.message : String(err),
+        { cause: err }
+      );
+    }
+    const events = pageEvents(page, last);
+    for (const event of events) {
+      yield event;
+      last = event.data.sequence;
+    }
+    if (events.length === 0 && start.wait === 0) {
+      await new Promise((r) => setTimeout(r, EMPTY_PAGE_PAUSE_MS));
+    }
+  }
+}
+function pageEvents(page, after) {
+  const events = page?.events ?? [];
+  if (!Array.isArray(events)) {
+    throw new SignalFeedError(after, "the server's page has no events list");
+  }
+  let previous = after;
+  for (const event of events) {
+    const sequence = event?.data?.sequence;
+    if (!Number.isSafeInteger(sequence) || sequence <= previous) {
+      throw new SignalFeedError(
+        after,
+        `the server's page holds an event out of order (sequence ${String(sequence)} after ${previous})`
+      );
+    }
+    previous = sequence;
+  }
+  if (page?.next_after !== previous) {
+    throw new SignalFeedError(
+      after,
+      `the server's next_after ${String(page?.next_after)} is not the last sequence on its page (${previous})`
+    );
+  }
+  return events;
+}
+function feedKeyBody(name, expiresAt) {
+  if (typeof name !== "string" || name.trim() === "" || Buffer.byteLength(name.trim(), "utf8") > MAX_FEED_KEY_NAME_BYTES) {
+    throw new VerdifaxError(
+      "verdifax: createFeedKey needs a name of at most 200 bytes"
+    );
+  }
+  if (expiresAt !== void 0 && typeof expiresAt !== "string") {
+    throw new VerdifaxError(
+      "verdifax: createFeedKey expiresAt must be an RFC 3339 time or a YYYY-MM-DD date, as a string"
+    );
+  }
+  return expiresAt === void 0 ? { name } : { name, expires_at: expiresAt };
+}
+function webhookBody(url, options) {
+  if (typeof url !== "string" || !url.startsWith("https://") || url.length <= 8) {
+    throw new VerdifaxError(
+      "verdifax: createWebhook needs a url that starts with https://"
+    );
+  }
+  const types = options?.types;
+  if (types === void 0) return { url };
+  if (!Array.isArray(types)) {
+    throw new VerdifaxError(
+      "verdifax: createWebhook types must be a list of signal kinds"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const kind of types) {
+    if (!SIGNAL_KINDS.includes(kind) || seen.has(kind)) {
+      throw new VerdifaxError(
+        `verdifax: createWebhook types must be distinct signal kinds (${SIGNAL_KINDS.join(", ")}); an empty list takes every kind`
+      );
+    }
+    seen.add(kind);
+  }
+  return { url, types: [...types] };
+}
+function deliveriesPath(id, options) {
+  const limit = options?.limit;
+  if (limit === void 0) return `${WEBHOOKS_PATH}/${id}/deliveries`;
+  requireLimit(limit, "listWebhookDeliveries", MAX_DELIVERY_LIMIT);
+  return `${WEBHOOKS_PATH}/${id}/deliveries?limit=${limit}`;
+}
+function verifyWebhook(headers, body, secret, options = {}) {
+  const key = webhookSecretBytes(secret);
+  const tolerance = options?.toleranceSeconds ?? DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+  if (typeof tolerance !== "number" || !Number.isFinite(tolerance) || tolerance < 0) {
+    throw new VerdifaxError(
+      "verdifax: verifyWebhook toleranceSeconds must be a number of seconds of 0 or more"
+    );
+  }
+  const now = options?.now ?? /* @__PURE__ */ new Date();
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
+    throw new VerdifaxError("verdifax: verifyWebhook now must be a valid Date");
+  }
+  let raw;
+  if (typeof body === "string") {
+    raw = Buffer.from(body, "utf8");
+  } else if (body instanceof Uint8Array) {
+    raw = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+  } else {
+    throw new VerdifaxError(
+      "verdifax: verifyWebhook needs the body as the raw bytes received (a Buffer, Uint8Array or string), not parsed JSON"
+    );
+  }
+  const id = singleHeader(headers, "webhook-id");
+  const timestamp = singleHeader(headers, "webhook-timestamp");
+  const signatures = headerValues(headers, "webhook-signature").join(" ");
+  if (!signatures) {
+    throw new VerdifaxError("verdifax: webhook check failed: the webhook-signature header is missing");
+  }
+  if (!/^[0-9]{1,15}$/.test(timestamp)) {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: webhook-timestamp is not a whole number of seconds"
+    );
+  }
+  const age = Math.abs(now.getTime() / 1e3 - Number(timestamp));
+  if (age > tolerance) {
+    throw new VerdifaxError(
+      `verdifax: webhook check failed: webhook-timestamp is more than ${tolerance} seconds from now`
+    );
+  }
+  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.`, "utf8").update(raw).digest();
+  let v1Seen = false;
+  let matched = false;
+  for (const entry of signatures.split(" ")) {
+    const comma = entry.indexOf(",");
+    if (comma < 0 || entry.slice(0, comma) !== WEBHOOK_SIGNATURE_VERSION) continue;
+    v1Seen = true;
+    const given2 = Buffer.from(entry.slice(comma + 1), "base64");
+    if (given2.length === HMAC_SHA256_BYTES && timingSafeEqual(given2, expected)) {
+      matched = true;
+    }
+  }
+  if (!v1Seen) {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: webhook-signature holds no v1 signature"
+    );
+  }
+  if (!matched) {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: no v1 signature in webhook-signature matches the id, timestamp and body under this secret"
+    );
+  }
+  let event;
+  try {
+    event = JSON.parse(raw.toString("utf8"));
+  } catch {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: the signature matches but the body is not JSON"
+    );
+  }
+  if (typeof event !== "object" || event === null || Array.isArray(event)) {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: the signature matches but the body is not a CloudEvent object"
+    );
+  }
+  if (event.id !== id) {
+    throw new VerdifaxError(
+      "verdifax: webhook check failed: the event id in the body does not match webhook-id"
+    );
+  }
+  return event;
+}
+function signalEventHash(kind, entryHash, fields) {
+  const { account, sequence, previousSignalHash } = fields ?? {};
+  for (const [name, value] of [
+    ["kind", kind],
+    ["entryHash", entryHash],
+    ["account", account],
+    ["previousSignalHash", previousSignalHash]
+  ]) {
+    if (typeof value !== "string" || value.includes("\0")) {
+      throw new VerdifaxError(
+        `verdifax: signalEventHash ${name} must be text without a zero byte`
+      );
+    }
+  }
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    throw new VerdifaxError(
+      "verdifax: signalEventHash sequence must be a whole number of 0 or more"
+    );
+  }
+  return createHash2("sha256").update(
+    [SIGNAL_FORM, kind, entryHash, account, String(sequence), previousSignalHash].join("\0"),
+    "utf8"
+  ).digest("hex");
+}
+function given(value, fallback) {
+  return value === void 0 ? fallback : value;
+}
+function requireAfter(after, method) {
+  if (!Number.isSafeInteger(after) || after < 0) {
+    throw new VerdifaxError(
+      `verdifax: ${method} after must be a whole number of 0 or more, the last sequence read`
+    );
+  }
+}
+function requireLimit(limit, method, max) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > max) {
+    throw new VerdifaxError(
+      `verdifax: ${method} limit must be a whole number from 1 to ${max}`
+    );
+  }
+}
+function requireWait(wait, method) {
+  if (!Number.isSafeInteger(wait) || wait < 0 || wait > MAX_SIGNAL_WAIT_SECONDS) {
+    throw new VerdifaxError(
+      `verdifax: ${method} wait must be a whole number of seconds from 0 to ${MAX_SIGNAL_WAIT_SECONDS}`
+    );
+  }
+}
+function webhookSecretBytes(secret) {
+  if (typeof secret !== "string" || !secret.startsWith(WEBHOOK_SECRET_PREFIX)) {
+    throw new VerdifaxError(
+      "verdifax: verifyWebhook needs the subscription's secret, which starts with whsec_"
+    );
+  }
+  const encoded = secret.slice(WEBHOOK_SECRET_PREFIX.length);
+  const key = Buffer.from(encoded, "base64");
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || key.length === 0 || key.toString("base64").replace(/=+$/, "") !== encoded.replace(/=+$/, "")) {
+    throw new VerdifaxError(
+      "verdifax: verifyWebhook needs the subscription's secret: whsec_ and then base64"
+    );
+  }
+  return key;
+}
+function headerValues(headers, name) {
+  if (typeof headers !== "object" || headers === null) {
+    throw new VerdifaxError("verdifax: verifyWebhook needs the delivery's headers");
+  }
+  if (typeof headers.get === "function") {
+    const value = headers.get(name);
+    return value === null || value === void 0 ? [] : [String(value)];
+  }
+  const out = [];
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== name) continue;
+    if (Array.isArray(value)) out.push(...value.map(String));
+    else if (value !== void 0) out.push(String(value));
+  }
+  return out;
+}
+function singleHeader(headers, name) {
+  const values = headerValues(headers, name);
+  if (values.length === 0 || values[0] === "") {
+    throw new VerdifaxError(`verdifax: webhook check failed: the ${name} header is missing`);
+  }
+  if (values.length > 1) {
+    throw new VerdifaxError(`verdifax: webhook check failed: the ${name} header appears more than once`);
+  }
+  return values[0];
+}
+
 // src/version.ts
-var SDK_VERSION = "1.4.0";
+var SDK_VERSION = "1.5.0";
 
 // src/client.ts
 import { KeyObject as KeyObject2 } from "crypto";
@@ -1389,6 +1728,103 @@ var VerdifaxClient = class {
       `${ACCOUNT_SIGNOFFS_PATH}/history`
     ) ?? [];
   }
+  // ── Signal feed ──────────────────────────────────────────────
+  //
+  // Every control signal Verdifax recorded for the account, in order, each
+  // with its sealed entry. The feed cannot show a signal Verdifax never
+  // recorded. A feed key reads it on GET /signals and does nothing else;
+  // the owner key reads it with asOwner and manages feed keys and webhooks.
+  // The feed and webhook logic is in signals.ts.
+  /** One page of the account's feed: the events after `after`, oldest
+   *  first, with `next_after` to read from next. With `wait` the server
+   *  holds the request open up to that many seconds for the next event, and
+   *  this call's timeout is at least the wait plus 30 seconds. With
+   *  `asOwner` it reads GET /account/signals with the owner key. Bad
+   *  options are refused before sending. Save the events and check them
+   *  with `verdifax-verify --signals`. */
+  async getSignals(options = {}) {
+    this.requireAPIKey();
+    const read = signalsRead(options, "getSignals", this.timeoutMs);
+    const out = await this.request(
+      "GET",
+      read.path,
+      void 0,
+      false,
+      read.timeoutMs
+    );
+    return { ...out, events: out?.events ?? [] };
+  }
+  /** Follows the feed from `after`, yielding each event once, in order,
+   *  until you stop with `break` or `return`. Each read starts at the page
+   *  before's `next_after`, waits up to `wait` seconds (default 25) when
+   *  there is no event, and is retried like any GET. A read that still
+   *  fails throws {@link SignalFeedError}, whose `lastSequence` is the last
+   *  sequence yielded: follow again from there and nothing is lost. Bad
+   *  options are refused here, before anything is sent. */
+  followSignals(options = {}) {
+    this.requireAPIKey();
+    const start = followStart(options);
+    return followSignalFeed(
+      (after) => this.getSignals({ after, wait: start.wait, asOwner: start.asOwner }),
+      start
+    );
+  }
+  /** Creates a feed key in the owner's account. A feed key reads the
+   *  account's signal feed, with {@link getSignals} and
+   *  {@link followSignals}, and nothing else. The secret is in the result
+   *  this once. */
+  async createFeedKey(name, options = {}) {
+    this.requireAPIKey();
+    return this.request(
+      "POST",
+      FEED_KEYS_PATH,
+      feedKeyBody(name, options?.expiresAt)
+    );
+  }
+  /** Revokes one of the account's feed keys. An id that is not a feed key
+   *  of the account throws {@link NotFoundError}. */
+  async revokeFeedKey(id) {
+    this.requireAPIKey();
+    requirePositiveId(id, "id");
+    return this.request("DELETE", `${FEED_KEYS_PATH}/${id}`);
+  }
+  /** Subscribes an https address to the account's signals. `types` are the
+   *  kinds to deliver, each once; empty or left out takes every kind. The
+   *  secret, `whsec_` and base64, is in the result this once: check each
+   *  delivery with {@link verifyWebhook}. A delivery is a copy: the pull
+   *  feed and the public log are the record. The server checks the address
+   *  too, and refuses an eleventh subscription with HTTP 409. */
+  async createWebhook(url, options = {}) {
+    this.requireAPIKey();
+    return this.request(
+      "POST",
+      WEBHOOKS_PATH,
+      webhookBody(url, options)
+    );
+  }
+  /** The account's webhook subscriptions, without their secrets. */
+  async listWebhooks() {
+    this.requireAPIKey();
+    const out = await this.request("GET", WEBHOOKS_PATH);
+    return { ...out, webhooks: out?.webhooks ?? [] };
+  }
+  /** Ends a webhook subscription. Its events stay in the pull feed. */
+  async deleteWebhook(id) {
+    this.requireAPIKey();
+    requirePositiveId(id, "id");
+    return this.request("DELETE", `${WEBHOOKS_PATH}/${id}`);
+  }
+  /** A webhook's newest deliveries first, up to `limit` (1 to 500; the
+   *  server's default is 50). */
+  async listWebhookDeliveries(id, options = {}) {
+    this.requireAPIKey();
+    requirePositiveId(id, "id");
+    const out = await this.request(
+      "GET",
+      deliveriesPath(id, options)
+    );
+    return { ...out, deliveries: out?.deliveries ?? [] };
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -1534,6 +1970,14 @@ var VerdifaxClient = class {
   async getCESAuditRecord(runId) {
     return this.getRunArtifact(runId, "ces-audit-record");
   }
+  /** A failed run's sealed failure receipt, in the form `verdifax-verify`
+   *  reads. A run that failed before failure receipts were sealed has none
+   *  and throws {@link NotFoundError}. */
+  async getFailureReceipt(runId) {
+    this.requireAPIKey();
+    requirePositiveId(runId, "runId");
+    return this.getRunArtifact(runId, "failure-receipt");
+  }
   /** The audit report for a run, as JSON. */
   async getRunReport(runId) {
     const out = await this.getRunArtifact(runId, "report");
@@ -1731,7 +2175,7 @@ var VerdifaxClient = class {
     });
   }
   // ── HTTP plumbing, retry-aware ──────────────────────────────
-  async request(method, path, body, rawText = false) {
+  async request(method, path, body, rawText = false, timeoutMs = this.timeoutMs) {
     const url = this.baseURL + path;
     const headers = {
       "User-Agent": this.userAgent
@@ -1748,7 +2192,7 @@ var VerdifaxClient = class {
         await new Promise((r) => setTimeout(r, sleep));
       }
       const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
       let resp;
       try {
         resp = await fetch(url, {
@@ -1845,13 +2289,6 @@ var VerdifaxClient = class {
 function signOffsBase(options, method) {
   return asOwnerOf(options, method) ? ACCOUNT_SIGNOFFS_PATH : SIGNOFFS_PATH;
 }
-function asOwnerOf(options, method) {
-  const asOwner = options?.asOwner;
-  if (asOwner !== void 0 && typeof asOwner !== "boolean") {
-    throw new VerdifaxError(`verdifax: ${method} asOwner must be true or false`);
-  }
-  return asOwner === true;
-}
 function signOffTargetOf(target) {
   if (typeof target !== "object" || target === null || Array.isArray(target)) {
     throw new VerdifaxError("verdifax: signOff needs a target object");
@@ -1888,11 +2325,6 @@ function recordMatchesSent(record, target, decision, previous, signed) {
   const got = record?.target;
   return typeof record === "object" && record !== null && record.signature === signed.signature && record.approver_key === signed.approver_key && record.decision === decision && record.previous_signoff_hash === previous && typeof got === "object" && got !== null && got.kind === target.kind && got.run_id === target.run_id && got.digest === target.digest && (got.job_id ?? "") === (target.job_id ?? "");
 }
-function requirePositiveId(id, name) {
-  if (!Number.isSafeInteger(id) || id <= 0) {
-    throw new VerdifaxError(`verdifax: ${name} must be a whole number > 0`);
-  }
-}
 function withSignedText(result, sent) {
   return "signed_request" in sent ? { ...result, signed_request: sent.signed_request } : result;
 }
@@ -2018,13 +2450,13 @@ var RUN_STATUSES = [
 ];
 
 // src/section0.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "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 sha256Hex2(preimage) {
-  return createHash2("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
+  return createHash3("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
 }
 function requireHex64(value, name) {
   try {
@@ -2090,6 +2522,7 @@ export {
   MAX_BATCH_ROWS,
   NotFoundError,
   RUN_STATUSES,
+  SignalFeedError,
   VerdifaxClient,
   VerdifaxError,
   VerdifaxJob,
@@ -2111,7 +2544,9 @@ export {
   signOffPreimage,
   signRequest,
   signRequestV2,
+  signalEventHash,
   validateHex64,
   validateJobName,
-  validateRouteId
+  validateRouteId,
+  verifyWebhook
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verdifax",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Official Node.js / TypeScript SDK for the Verdifax orchestrator REST API.",
   "license": "MIT",
   "author": "Verdifax <team@verdifax.com>",