verdifax 1.3.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 {
@@ -57,7 +68,8 @@ import {
   generateKeyPairSync,
   KeyObject,
   randomBytes,
-  sign
+  sign,
+  verify
 } from "crypto";
 
 // src/validation.ts
@@ -95,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) {
@@ -339,7 +363,10 @@ var JOB_FORM = "verdifax.job.v1";
 var REQUEST_KEY_PROOF_FORM = "verdifax.request-key.v1";
 var REQUEST_KEY_CHANGE_FORM = "verdifax.request-key-change.v1";
 var POLICY_ACTIVATION_FORM = "verdifax.policy-activation.v1";
+var SIGNOFF_FORM = "verdifax.signoff.v1";
+var APPROVER_KEY_PROOF_FORM = "verdifax.approver-key.v1";
 var SIGNING_KEY_BYTES = 32;
+var SPKI_ED25519_HEADER = Buffer.from("302a300506032b6570032100", "hex");
 var PKCS8_ED25519_HEADER = Buffer.from(
   "302e020100300506032b657004220420",
   "hex"
@@ -523,6 +550,71 @@ function policyActivationApproval(signingKey, fields, options = {}) {
     nonce
   };
 }
+function signOffPreimage(fields) {
+  const { target } = fields;
+  return Buffer.from(
+    [
+      SIGNOFF_FORM,
+      fields.chain_id,
+      fields.previous_signoff_hash,
+      target.kind,
+      String(target.run_id),
+      target.digest,
+      target.job_id ?? "",
+      fields.decision,
+      fields.note_hash,
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
+  );
+}
+function signOffSignature(approverKey, fields, options = {}) {
+  const key = loadSigningKey(approverKey);
+  const signed_at = options.signedAt ?? signedAtNow();
+  const nonce = options.nonce ?? randomBytes(16).toString("hex");
+  const preimage = signOffPreimage({ ...fields, signed_at, nonce });
+  return {
+    approver_key: rawPublicKey(createPublicKey(key)).toString("base64"),
+    signature: sign(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
+}
+function approverKeyProof(approverKey) {
+  const key = loadSigningKey(approverKey);
+  const public_key = rawPublicKey(createPublicKey(key)).toString("base64");
+  const proof = sign(
+    null,
+    Buffer.from(`${APPROVER_KEY_PROOF_FORM}\0${public_key}`, "utf8"),
+    key
+  ).toString("base64");
+  return { public_key, proof };
+}
+function approverKeyProofVerifies(proof) {
+  if (typeof proof?.public_key !== "string" || typeof proof?.proof !== "string") {
+    return false;
+  }
+  const raw = Buffer.from(proof.public_key, "base64");
+  const signature = Buffer.from(proof.proof, "base64");
+  if (raw.length !== 32 || raw.toString("base64") !== proof.public_key || signature.length !== 64 || signature.toString("base64") !== proof.proof) {
+    return false;
+  }
+  const publicKey = createPublicKey({
+    key: Buffer.concat([SPKI_ED25519_HEADER, raw]),
+    format: "der",
+    type: "spki"
+  });
+  return verify(
+    null,
+    Buffer.from(`${APPROVER_KEY_PROOF_FORM}\0${proof.public_key}`, "utf8"),
+    publicKey,
+    signature
+  );
+}
+function publicKeyOf(key) {
+  return rawPublicKey(createPublicKey(key)).toString("base64");
+}
 
 // src/job.ts
 var STEP_OPTIONS = {
@@ -623,10 +715,327 @@ 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.3.0";
+var SDK_VERSION = "1.5.0";
 
 // src/client.ts
+import { KeyObject as KeyObject2 } from "crypto";
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
 var DEFAULT_TIMEOUT_MS = 9e4;
 var DEFAULT_MAX_RETRIES = 3;
@@ -639,6 +1048,12 @@ var ACCOUNT_PATH = "/account";
 var ACCOUNT_REQUEST_KEY_PATH = "/account/request-key";
 var ACCOUNT_POLICIES_PATH = "/account/policies";
 var ACCOUNT_CHAIN_ID = /^account-[1-9][0-9]*$/;
+var SIGNOFFS_PATH = "/signoffs";
+var ACCOUNT_SIGNOFFS_PATH = "/account/signoffs";
+var APPROVERS_PATH = "/account/approvers";
+var SIGNOFF_TARGET_KINDS = /* @__PURE__ */ new Set(["record", "receipt", "job"]);
+var SIGNOFF_DECISIONS = /* @__PURE__ */ new Set(["approve", "reject"]);
+var MAX_APPROVER_NAME_BYTES = 200;
 var HEADER_EXPORT_TOTAL = "X-Verdifax-Total";
 var HEADER_EXPORT_TRUNCATED = "X-Verdifax-Truncated";
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
@@ -1145,6 +1560,271 @@ var VerdifaxClient = class {
     }
     return this.activatePolicyAt(ACCOUNT_POLICIES_PATH, documentHash, chain);
   }
+  // ── Sign-off ─────────────────────────────────────────────────
+  //
+  // An account's owner registers approver keys. An approver signs a
+  // decision, approve or reject, on one exact result on their own machine,
+  // and any key in the account, or the owner key with asOwner, submits it.
+  // A sign-off shows that the holder of a registered approver key signed
+  // that decision on that exact result and that Verdifax logged it on the
+  // public log. It does not show the review was careful, the result right,
+  // or who the person is, and it gates nothing on its own.
+  /** Registers an approver key to the owner's account. `approver` is the
+   *  approver's signing key, from which the proof is made on this machine,
+   *  or the `{ public_key, proof }` that {@link approverKeyProof} made on
+   *  the approver's own machine, so the owner need not hold the private
+   *  key. A proof that does not verify is refused before sending. The
+   *  server refuses a key that is a request key in the same account.
+   *  `name` is a label, not an identity. */
+  async registerApprover(name, approver) {
+    this.requireAPIKey();
+    if (typeof name !== "string" || name.trim() === "" || Buffer.byteLength(name.trim(), "utf8") > MAX_APPROVER_NAME_BYTES) {
+      throw new VerdifaxError(
+        "verdifax: registerApprover needs a name of at most 200 bytes"
+      );
+    }
+    const body = approver instanceof Uint8Array || approver instanceof KeyObject2 ? approverKeyProof(approver) : { public_key: approver?.public_key, proof: approver?.proof };
+    if (!approverKeyProofVerifies(body)) {
+      throw new VerdifaxError(
+        "verdifax: registerApprover needs the approver's signing key, or a public_key and proof from approverKeyProof that verify"
+      );
+    }
+    if (this.signingKey && publicKeyOf(this.signingKey) === body.public_key) {
+      throw new VerdifaxError(
+        "verdifax: an approver key must not be a request key in the same account, and this is the client's signingKey"
+      );
+    }
+    return this.request("POST", APPROVERS_PATH, {
+      public_key: body.public_key,
+      name,
+      proof: body.proof
+    });
+  }
+  /** The account's approver keys, revoked ones included. */
+  async listApprovers() {
+    this.requireAPIKey();
+    const out = await this.request("GET", APPROVERS_PATH);
+    return { ...out, approvers: out?.approvers ?? [] };
+  }
+  /** Revokes one of the account's approver keys. Its earlier sign-offs
+   *  stay on the record. A key that is not an active approver in the
+   *  account throws {@link NotFoundError}. */
+  async revokeApprover(approverId) {
+    this.requireAPIKey();
+    requirePositiveId(approverId, "approverId");
+    return this.request(
+      "DELETE",
+      `${APPROVERS_PATH}/${approverId}`
+    );
+  }
+  /** What an approver signs against: the account's chain `account-N` and
+   *  its newest sign-off (64 zeros when there is none yet). With
+   *  `asOwner` it reads the owner key's route. */
+  async getNewestSignOff(options = {}) {
+    this.requireAPIKey();
+    return this.request(
+      "GET",
+      `${signOffsBase(options, "getNewestSignOff")}/newest`
+    );
+  }
+  /** Signs an approver's decision, approve or reject, on one exact result
+   *  and submits it. It first reads {@link getNewestSignOff} for the
+   *  account's chain and its newest sign-off, then signs over them with
+   *  `approverKey` on this machine. The approver's private key is never
+   *  sent.
+   *
+   *  `target.digest` is what the result's public-log entry covers: for a
+   *  record, the `bundle_anchor.anchored_digest` of the bundle
+   *  {@link getRunArtifacts} returns; for a receipt, its hash; for a job,
+   *  the final step's record digest, read as a record's, with `job_id`.
+   *
+   *  `note` is hashed here and only its SHA-256 is sent and signed: the
+   *  text never reaches Verdifax. With `asOwner` it uses the owner key's
+   *  routes. Bad input is refused before anything is sent.
+   *
+   *  The record the server returns must carry the signature,
+   *  approver_key, decision, previous_signoff_hash and target that were
+   *  sent, or this throws {@link VerdifaxError}.
+   *
+   *  A later sign-off on the same result supersedes this one, and neither
+   *  is deleted. An HTTP 409 means the chain moved or the target is not
+   *  this account's result: it throws the usual {@link APIError} and is
+   *  not retried. */
+  async signOff(target, decision, approverKey, options = {}) {
+    this.requireAPIKey();
+    const base = signOffsBase(options, "signOff");
+    const exact = signOffTargetOf(target);
+    if (!SIGNOFF_DECISIONS.has(decision)) {
+      throw new VerdifaxError(
+        "verdifax: signOff decision must be approve or reject"
+      );
+    }
+    const note = options?.note;
+    if (note !== void 0 && (typeof note !== "string" || note === "")) {
+      throw new VerdifaxError(
+        "verdifax: signOff note must be non-empty text when given"
+      );
+    }
+    const key = loadSigningKey(approverKey);
+    const note_hash = note === void 0 ? "" : sha256Hex(note);
+    const newest = await this.getNewestSignOff(options);
+    if (typeof newest?.chain_id !== "string" || !ACCOUNT_CHAIN_ID.test(newest.chain_id)) {
+      throw new VerdifaxError(
+        "verdifax: the server did not report an account chain_id (account-N), so the sign-off cannot be signed"
+      );
+    }
+    const previous = newest.newest_signoff_hash;
+    if (typeof previous !== "string" || !/^[0-9a-f]{64}$/.test(previous)) {
+      throw new VerdifaxError(
+        "verdifax: the server did not report newest_signoff_hash, so the sign-off cannot name the one it follows"
+      );
+    }
+    const signed = signOffSignature(key, {
+      chain_id: newest.chain_id,
+      previous_signoff_hash: previous,
+      target: exact,
+      decision,
+      note_hash
+    });
+    const body = {
+      previous_signoff_hash: previous,
+      target: exact,
+      decision,
+      ...note_hash ? { note_hash } : {},
+      ...signed
+    };
+    const out = await this.request(
+      "POST",
+      base,
+      body
+    );
+    const record = out?.signoff;
+    if (!recordMatchesSent(record, exact, decision, previous, signed)) {
+      throw new VerdifaxError(
+        "verdifax: the sign-off the server returned does not carry the signature, approver_key, decision, previous_signoff_hash and target that were sent"
+      );
+    }
+    return record;
+  }
+  /** The sign-offs on one run, oldest first, in the form
+   *  `verdifax-verify --signoff FILE` reads: for a member key, a run it
+   *  made; with `asOwner`, any run of the account. The latest is the
+   *  decision in force. */
+  async getSignOffs(runId, options = {}) {
+    this.requireAPIKey();
+    requirePositiveId(runId, "runId");
+    const base = asOwnerOf(options, "getSignOffs") ? `${ACCOUNT_PATH}/runs` : "/runs";
+    return await this.request(
+      "GET",
+      `${base}/${runId}/signoffs`
+    ) ?? [];
+  }
+  /** The account's whole chain of sign-offs, oldest first, in the form
+   *  `verdifax-verify --signoff-history FILE` reads. Needs the owner key. */
+  async getSignOffHistory() {
+    this.requireAPIKey();
+    return await this.request(
+      "GET",
+      `${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();
@@ -1290,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");
@@ -1487,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
@@ -1504,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, {
@@ -1598,10 +2286,44 @@ var VerdifaxClient = class {
     return this.signingKey ? signRequestV2(this.signingKey, req) : withExecuteFlags(req);
   }
 };
-function requirePositiveId(id, name) {
-  if (!Number.isSafeInteger(id) || id <= 0) {
-    throw new VerdifaxError(`verdifax: ${name} must be a whole number > 0`);
+function signOffsBase(options, method) {
+  return asOwnerOf(options, method) ? ACCOUNT_SIGNOFFS_PATH : SIGNOFFS_PATH;
+}
+function signOffTargetOf(target) {
+  if (typeof target !== "object" || target === null || Array.isArray(target)) {
+    throw new VerdifaxError("verdifax: signOff needs a target object");
+  }
+  for (const name of Object.keys(target)) {
+    if (!["kind", "run_id", "digest", "job_id"].includes(name)) {
+      throw new VerdifaxError(`verdifax: signOff target has an unknown field: ${name}`);
+    }
+  }
+  if (!SIGNOFF_TARGET_KINDS.has(target.kind)) {
+    throw new VerdifaxError(
+      "verdifax: signOff target kind must be record, receipt or job"
+    );
+  }
+  requirePositiveId(target.run_id, "target.run_id");
+  validateHex64(target.digest, "target.digest");
+  if (target.kind === "job") {
+    validateJobName(target.job_id, "target.job_id");
+    return {
+      kind: target.kind,
+      run_id: target.run_id,
+      digest: target.digest,
+      job_id: target.job_id
+    };
   }
+  if (target.job_id !== void 0) {
+    throw new VerdifaxError(
+      "verdifax: signOff target job_id is for a job target only"
+    );
+  }
+  return { kind: target.kind, run_id: target.run_id, digest: target.digest };
+}
+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 withSignedText(result, sent) {
   return "signed_request" in sent ? { ...result, signed_request: sent.signed_request } : result;
@@ -1728,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 {
@@ -1800,9 +2522,11 @@ export {
   MAX_BATCH_ROWS,
   NotFoundError,
   RUN_STATUSES,
+  SignalFeedError,
   VerdifaxClient,
   VerdifaxError,
   VerdifaxJob,
+  approverKeyProof,
   captureEnvironment,
   cresReceiptHash,
   dcaeClosureHash,
@@ -1817,9 +2541,12 @@ export {
   requestKeyRegistrationBody,
   requestSignaturePreimage,
   requestSignaturePreimageV2,
+  signOffPreimage,
   signRequest,
   signRequestV2,
+  signalEventHash,
   validateHex64,
   validateJobName,
-  validateRouteId
+  validateRouteId,
+  verifyWebhook
 };