verdifax 1.2.0 → 1.4.0

package/dist/index.mjs

@@ -57,7 +57,8 @@ import {
   generateKeyPairSync,
   KeyObject,
   randomBytes,
-  sign
+  sign,
+  verify
 } from "crypto";
 
 // src/validation.ts
@@ -339,7 +340,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 +527,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 = {
@@ -624,9 +693,10 @@ var VerdifaxJob = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.2.0";
+var SDK_VERSION = "1.4.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;
@@ -635,6 +705,16 @@ var SDK_USER_AGENT = `verdifax-sdk-node/${SDK_VERSION}`;
 var HEADER_API_KEY = "X-Verdifax-Key";
 var REQUEST_KEY_PATH = "/keys/request-key";
 var POLICIES_PATH = "/policies";
+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]);
@@ -820,15 +900,18 @@ var VerdifaxClient = class {
    *  that the client holds the private key. From then on the server
    *  refuses a run on this API key without a request signature. */
   async registerRequestKey() {
+    return this.registerRequestKeyAt(REQUEST_KEY_PATH, "registerRequestKey");
+  }
+  async registerRequestKeyAt(path, method) {
     this.requireAPIKey();
     if (!this.signingKey) {
       throw new VerdifaxError(
-        "verdifax: registerRequestKey needs the signingKey client option"
+        `verdifax: ${method} needs the signingKey client option`
       );
     }
     return this.request(
       "POST",
-      REQUEST_KEY_PATH,
+      path,
       requestKeyRegistrationBody(this.signingKey)
     );
   }
@@ -867,10 +950,13 @@ var VerdifaxClient = class {
    *  unsigned requests, because the server refuses a signed run on an API
    *  key with no registered key. If the call fails it keeps the key. */
   async clearRequestKey() {
+    await this.clearRequestKeyAt(REQUEST_KEY_PATH);
+  }
+  async clearRequestKeyAt(path) {
     this.requireAPIKey();
     await this.request(
       "DELETE",
-      REQUEST_KEY_PATH,
+      path,
       this.signingKey ? { change: requestKeyChangeApproval(this.signingKey, "") } : void 0
     );
     this.signingKey = void 0;
@@ -882,13 +968,7 @@ var VerdifaxClient = class {
    *  not a string: serializing an object here would change the hash.
    *  Verdifax does not write, review or approve a customer's policy. */
   async uploadPolicy(document) {
-    this.requireAPIKey();
-    if (typeof document !== "string") {
-      throw new VerdifaxError(
-        "verdifax: document must be the policy's exact text, as a string"
-      );
-    }
-    return this.request("POST", POLICIES_PATH, { document });
+    return this.uploadPolicyAt(POLICIES_PATH, document);
   }
   /** This key's stored documents, with the chain its changes belong to,
    *  the newest change in it (64 zeros when there is none yet) and the
@@ -899,44 +979,13 @@ var VerdifaxClient = class {
   }
   /** One stored document, with its exact text as `document`. */
   async getPolicy(documentHash) {
-    this.requireAPIKey();
-    validateHex64(documentHash, "documentHash");
-    return this.request(
-      "GET",
-      `${POLICIES_PATH}/${documentHash}`
-    );
+    return this.getPolicyAt(POLICIES_PATH, documentHash);
   }
   /** Shows which rule would fire on sample inputs, for a document given as
    *  text or one already stored, named by its hash: exactly one of the two.
    *  It seals nothing. */
   async testPolicy(req) {
-    this.requireAPIKey();
-    const { inputs, document, documentHash } = req ?? {};
-    if (document === void 0 === (documentHash === void 0)) {
-      throw new VerdifaxError(
-        "verdifax: testPolicy needs exactly one of document or documentHash"
-      );
-    }
-    if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs)) {
-      throw new VerdifaxError("verdifax: testPolicy needs inputs as an object");
-    }
-    const body = { inputs };
-    if (document !== void 0) {
-      if (typeof document !== "string") {
-        throw new VerdifaxError(
-          "verdifax: document must be the policy's exact text, as a string"
-        );
-      }
-      body.document = document;
-    } else {
-      validateHex64(documentHash, "documentHash");
-      body.document_hash = documentHash;
-    }
-    return this.request(
-      "POST",
-      `${POLICIES_PATH}/test`,
-      body
-    );
+    return this.testPolicyAt(POLICIES_PATH, req, "testPolicy");
   }
   /** This key's policy changes, oldest first, as the list the server sends.
    *  Save it as JSON, for example with
@@ -962,7 +1011,54 @@ var VerdifaxClient = class {
   async activatePolicy(documentHash) {
     this.requireAPIKey();
     validateHex64(documentHash, "documentHash");
-    const chain = await this.listPolicies();
+    return this.activatePolicyAt(
+      POLICIES_PATH,
+      documentHash,
+      await this.listPolicies()
+    );
+  }
+  async uploadPolicyAt(base, document) {
+    this.requireAPIKey();
+    if (typeof document !== "string") {
+      throw new VerdifaxError(
+        "verdifax: document must be the policy's exact text, as a string"
+      );
+    }
+    return this.request("POST", base, { document });
+  }
+  async getPolicyAt(base, documentHash) {
+    this.requireAPIKey();
+    validateHex64(documentHash, "documentHash");
+    return this.request("GET", `${base}/${documentHash}`);
+  }
+  async testPolicyAt(base, req, method) {
+    this.requireAPIKey();
+    const { inputs, document, documentHash } = req ?? {};
+    if (document === void 0 === (documentHash === void 0)) {
+      throw new VerdifaxError(
+        `verdifax: ${method} needs exactly one of document or documentHash`
+      );
+    }
+    if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs)) {
+      throw new VerdifaxError(`verdifax: ${method} needs inputs as an object`);
+    }
+    const body = { inputs };
+    if (document !== void 0) {
+      if (typeof document !== "string") {
+        throw new VerdifaxError(
+          "verdifax: document must be the policy's exact text, as a string"
+        );
+      }
+      body.document = document;
+    } else {
+      validateHex64(documentHash, "documentHash");
+      body.document_hash = documentHash;
+    }
+    return this.request("POST", `${base}/test`, body);
+  }
+  /** Posts the change that follows the newest one in `chain`, signed by
+   *  the request key when the client has one. */
+  async activatePolicyAt(base, documentHash, chain) {
     const previous = chain?.newest_activation_hash;
     if (typeof previous !== "string") {
       throw new VerdifaxError(
@@ -984,11 +1080,315 @@ var VerdifaxClient = class {
     }
     const out = await this.request(
       "POST",
-      `${POLICIES_PATH}/${documentHash}/activate`,
+      `${base}/${documentHash}/activate`,
       body
     );
     return out.activation;
   }
+  // ── Account, with its owner key (auth) ───────────────────────
+  //
+  // An account is a company on Verdifax. Every key belongs to one account
+  // for life. These methods need the account's owner key, which manages the
+  // account and cannot run anything: the server refuses it on every other
+  // route. The account number is a label Verdifax assigned, not a verified
+  // company identity.
+  /** The owner's account: its number, name, tier, key counts and the
+   *  chain of its policy changes. */
+  async getAccount() {
+    this.requireAPIKey();
+    return this.request("GET", ACCOUNT_PATH);
+  }
+  /** Creates a member key in the account. It takes the account's tier and
+   *  stays in the account for life. The secret is in the result this once.
+   *  On a trial account the key needs a request key before it can run. */
+  async createAccountKey(name, options = {}) {
+    this.requireAPIKey();
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new VerdifaxError(
+        "verdifax: name is required for createAccountKey"
+      );
+    }
+    const body = { name };
+    if (options.expiresAt !== void 0) body.expires_at = options.expiresAt;
+    return this.request(
+      "POST",
+      `${ACCOUNT_PATH}/keys`,
+      body
+    );
+  }
+  /** Every key in the account, owner keys included, without secrets. */
+  async listAccountKeys() {
+    this.requireAPIKey();
+    const out = await this.request(
+      "GET",
+      `${ACCOUNT_PATH}/keys`
+    );
+    return { ...out, keys: out?.keys ?? [] };
+  }
+  /** Revokes one of the account's member keys. A key in another account,
+   *  or an owner key, throws {@link NotFoundError}. */
+  async revokeAccountKey(keyId) {
+    this.requireAPIKey();
+    requirePositiveId(keyId, "keyId");
+    return this.request(
+      "DELETE",
+      `${ACCOUNT_PATH}/keys/${keyId}`
+    );
+  }
+  /** Registers this client's public key as the owner key's request key,
+   *  which must sign every change to the account's policy. It works as
+   *  {@link registerRequestKey} does. */
+  async registerAccountRequestKey() {
+    return this.registerRequestKeyAt(
+      ACCOUNT_REQUEST_KEY_PATH,
+      "registerAccountRequestKey"
+    );
+  }
+  /** Clears the owner key's request key, as {@link clearRequestKey} does
+   *  for a key's own. With none registered the account's policy cannot be
+   *  changed. A trial owner key's request key cannot be cleared. */
+  async clearAccountRequestKey() {
+    await this.clearRequestKeyAt(ACCOUNT_REQUEST_KEY_PATH);
+  }
+  /** The runs of every key in the account, paged as {@link listRuns}. */
+  async listAccountRuns(params = {}) {
+    return this.listRunsAt(`${ACCOUNT_PATH}/runs`, params);
+  }
+  /** The runs of every key in the account in a period, as
+   *  {@link exportRuns} lists a key's, with the account's number, its
+   *  policy documents and its chain of changes. The account's view covers
+   *  the runs its keys made through Verdifax, not runs made elsewhere. */
+  async exportAccountRuns(params = {}) {
+    this.requireAPIKey();
+    return this.request(
+      "GET",
+      this.exportPath(`${ACCOUNT_PATH}/runs/export`, params, "json")
+    );
+  }
+  /** The same rows as {@link exportAccountRuns} as raw CSV text, checked
+   *  as {@link exportRunsCSV} checks a key's. */
+  async exportAccountRunsCSV(params = {}) {
+    return this.exportCSVAt(`${ACCOUNT_PATH}/runs/export`, params);
+  }
+  /** Stores an account policy document, as {@link uploadPolicy} stores a
+   *  key's. Every key in the account must pass the account's policy on top
+   *  of its own. Verdifax does not write, review or approve it. */
+  async uploadAccountPolicy(document) {
+    return this.uploadPolicyAt(ACCOUNT_POLICIES_PATH, document);
+  }
+  /** The account's stored documents, its chain `account-N`, the newest
+   *  change in it and the document in force. */
+  async listAccountPolicies() {
+    this.requireAPIKey();
+    return this.request("GET", ACCOUNT_POLICIES_PATH);
+  }
+  /** One of the account's documents, with its exact text. */
+  async getAccountPolicy(documentHash) {
+    return this.getPolicyAt(ACCOUNT_POLICIES_PATH, documentHash);
+  }
+  /** {@link testPolicy} for the account's documents. It seals nothing. */
+  async testAccountPolicy(req) {
+    return this.testPolicyAt(ACCOUNT_POLICIES_PATH, req, "testAccountPolicy");
+  }
+  /** The account's policy changes, oldest first, in the form
+   *  `verdifax-verify --policy-history FILE` reads. */
+  async getAccountPolicyHistory() {
+    this.requireAPIKey();
+    return this.request(
+      "GET",
+      `${ACCOUNT_POLICIES_PATH}/history`
+    );
+  }
+  /** Makes a stored document the account's policy in force, as
+   *  {@link activatePolicy} does for a key's. It reads
+   *  {@link listAccountPolicies} for the chain and its newest change, and
+   *  the owner key's request key signs the change over that chain,
+   *  `account-N`. The server refuses an unsigned account change, so this
+   *  needs the `signingKey` option and refuses to send without it. */
+  async activateAccountPolicy(documentHash) {
+    this.requireAPIKey();
+    validateHex64(documentHash, "documentHash");
+    if (!this.signingKey) {
+      throw new VerdifaxError(
+        "verdifax: activateAccountPolicy needs the owner key's request key in the signingKey client option, because the server refuses an unsigned account policy change"
+      );
+    }
+    const chain = await this.listAccountPolicies();
+    if (typeof chain?.chain_id !== "string" || !ACCOUNT_CHAIN_ID.test(chain.chain_id)) {
+      throw new VerdifaxError(
+        "verdifax: the server did not report an account chain_id (account-N), so the change cannot be signed"
+      );
+    }
+    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`
+    ) ?? [];
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -1001,6 +1401,9 @@ var VerdifaxClient = class {
     return this.request("GET", `/runs/${runId}/verify`);
   }
   async listRuns(params = {}) {
+    return this.listRunsAt("/runs", params);
+  }
+  async listRunsAt(base, params) {
     this.requireAPIKey();
     const q = new URLSearchParams();
     if (params.limit && params.limit > 0) {
@@ -1010,7 +1413,7 @@ var VerdifaxClient = class {
       q.set("offset", String(params.offset));
     }
     const qs = q.toString();
-    const path = qs ? `/runs?${qs}` : "/runs";
+    const path = qs ? `${base}?${qs}` : base;
     const out = await this.request("GET", path);
     return { runs: out.runs ?? [], total: out.total ?? 0 };
   }
@@ -1048,7 +1451,10 @@ var VerdifaxClient = class {
    *  call that never reached Verdifax cannot appear in it. */
   async exportRuns(params = {}) {
     this.requireAPIKey();
-    return this.request("GET", this.exportPath(params, "json"));
+    return this.request(
+      "GET",
+      this.exportPath("/runs/export", params, "json")
+    );
   }
   /** The same rows as {@link exportRuns}: the raw CSV text with `total`
    *  and `truncated` from the response headers. Check `truncated`: when
@@ -1056,9 +1462,12 @@ var VerdifaxClient = class {
    *  does not send those headers, so that a cut-off export cannot pass
    *  for a complete one. */
   async exportRunsCSV(params = {}) {
+    return this.exportCSVAt("/runs/export", params);
+  }
+  async exportCSVAt(base, params) {
     this.requireAPIKey();
     const { text, headers } = await this.requestRaw(
-      this.exportPath(params, "csv")
+      this.exportPath(base, params, "csv")
     );
     const total = Number.parseInt(headers.get(HEADER_EXPORT_TOTAL) ?? "", 10);
     const truncated = headers.get(HEADER_EXPORT_TRUNCATED);
@@ -1069,13 +1478,13 @@ var VerdifaxClient = class {
     }
     return { csv: text, total, truncated: truncated === "true" };
   }
-  exportPath(params, format) {
+  exportPath(base, params, format) {
     const q = new URLSearchParams();
     if (params.from) q.set("from", params.from);
     if (params.to) q.set("to", params.to);
     if (params.job_id) q.set("job_id", params.job_id);
     q.set("format", format);
-    return `/runs/export?${q.toString()}`;
+    return `${base}?${q.toString()}`;
   }
   // ── Attestation receipts (auth) ──────────────────────────────
   async listAttestations(params = {}) {
@@ -1213,14 +1622,48 @@ var VerdifaxClient = class {
     return this.request("POST", "/dcae/verify", bundle);
   }
   // ── Admin: API keys (auth) ───────────────────────────────────
-  async adminCreateKey(name) {
+  /** Creates a customer key. With `accountId` the key joins that existing
+   *  account; without it the key gets an account of its own. A key never
+   *  changes account. */
+  async adminCreateKey(name, options = {}) {
     this.requireAPIKey();
     if (!name) {
       throw new VerdifaxError("verdifax: name is required for adminCreateKey");
     }
-    return this.request("POST", "/admin/keys", {
-      name
-    });
+    const body = { name };
+    if (options.accountId !== void 0) {
+      requirePositiveId(options.accountId, "accountId");
+      body.account_id = options.accountId;
+    }
+    return this.request("POST", "/admin/keys", body);
+  }
+  /** Creates an account and its first owner key, whose secret is in the
+   *  result this once. The owner key creates the member keys. The account
+   *  number is a label Verdifax assigned, not a verified company identity. */
+  async adminCreateAccount(name, options = {}) {
+    this.requireAPIKey();
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new VerdifaxError(
+        "verdifax: name is required for adminCreateAccount"
+      );
+    }
+    const body = { name };
+    if (options.tier !== void 0) body.tier = options.tier;
+    if (options.expiresAt !== void 0) body.expires_at = options.expiresAt;
+    return this.request(
+      "POST",
+      "/admin/accounts",
+      body
+    );
+  }
+  /** Every account, with its key counts. */
+  async adminListAccounts() {
+    this.requireAPIKey();
+    const out = await this.request(
+      "GET",
+      "/admin/accounts"
+    );
+    return out?.accounts ?? [];
   }
   async adminListKeys() {
     this.requireAPIKey();
@@ -1399,6 +1842,57 @@ var VerdifaxClient = class {
     return this.signingKey ? signRequestV2(this.signingKey, req) : withExecuteFlags(req);
   }
 };
+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");
+  }
+  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 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;
 }
@@ -1599,6 +2093,7 @@ export {
   VerdifaxClient,
   VerdifaxError,
   VerdifaxJob,
+  approverKeyProof,
   captureEnvironment,
   cresReceiptHash,
   dcaeClosureHash,
@@ -1613,6 +2108,7 @@ export {
   requestKeyRegistrationBody,
   requestSignaturePreimage,
   requestSignaturePreimageV2,
+  signOffPreimage,
   signRequest,
   signRequestV2,
   validateHex64,