verdifax 1.1.0 → 1.3.0

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CRES_PREIMAGE_VERSION: () => CRES_PREIMAGE_VERSION,
   DCAE_PREIMAGE_VERSION: () => DCAE_PREIMAGE_VERSION,
   DSE_FORMULA_VERSION: () => DSE_FORMULA_VERSION,
+  EXECUTE_FIELDS: () => EXECUTE_FIELDS,
   MAX_BATCH_ROWS: () => MAX_BATCH_ROWS,
   NotFoundError: () => NotFoundError,
   RUN_STATUSES: () => RUN_STATUSES,
@@ -40,6 +41,8 @@ __export(index_exports, {
   formatProviderPayload: () => formatProviderPayload,
   fromEnv: () => fromEnv,
   generateRequestKeyPair: () => generateRequestKeyPair,
+  policyActivationApproval: () => policyActivationApproval,
+  policyActivationPreimage: () => policyActivationPreimage,
   requestKeyChangeApproval: () => requestKeyChangeApproval,
   requestKeyChangePreimage: () => requestKeyChangePreimage,
   requestKeyRegistrationBody: () => requestKeyRegistrationBody,
@@ -214,7 +217,144 @@ function normalizedJob(job) {
   if (job.final) out.final = true;
   return out;
 }
+var POLICY_ACTOR_TYPES = ["agent", "user", "service", "system"];
+var POLICY_OBJECT_TYPES = ["text", "transaction", "code", "data", "model", "file"];
+var POLICY_CLASSIFICATIONS = [
+  "PUBLIC",
+  "INTERNAL",
+  "CONFIDENTIAL",
+  "RESTRICTED",
+  "TOP_SECRET",
+  "TS_SCI"
+];
+var MAX_POLICY_OBJECT_ID_BYTES = 256;
+var POLICY_CONTEXT_FIELDS = {
+  actor_type: true,
+  mfa_satisfied: true,
+  session_age_seconds: true,
+  object_type: true,
+  object_id: true,
+  classification: true
+};
+function refuseOutsideList(value, allowed, fieldName) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new VerdifaxError(
+      `verdifax: policy_context.${fieldName} must be one of ${allowed.join(", ")}`
+    );
+  }
+}
+function checkedPolicyContext(context) {
+  if (typeof context !== "object" || context === null || Array.isArray(context)) {
+    throw new VerdifaxError("verdifax: policy_context must be an object");
+  }
+  refuseUnknownFields(context, POLICY_CONTEXT_FIELDS, "policy_context");
+  const out = {};
+  const {
+    actor_type,
+    mfa_satisfied,
+    session_age_seconds,
+    object_type,
+    object_id,
+    classification
+  } = context;
+  if (actor_type !== void 0) {
+    refuseOutsideList(actor_type, POLICY_ACTOR_TYPES, "actor_type");
+    out.actor_type = actor_type;
+  }
+  if (mfa_satisfied !== void 0) {
+    if (typeof mfa_satisfied !== "boolean") {
+      throw new VerdifaxError(
+        "verdifax: policy_context.mfa_satisfied must be true or false"
+      );
+    }
+    out.mfa_satisfied = mfa_satisfied;
+  }
+  if (session_age_seconds !== void 0) {
+    if (!Number.isSafeInteger(session_age_seconds) || session_age_seconds < 0) {
+      throw new VerdifaxError(
+        "verdifax: policy_context.session_age_seconds must be a whole number of seconds, not negative"
+      );
+    }
+    out.session_age_seconds = session_age_seconds;
+  }
+  if (object_type !== void 0) {
+    refuseOutsideList(object_type, POLICY_OBJECT_TYPES, "object_type");
+    out.object_type = object_type;
+  }
+  if (object_id !== void 0) {
+    if (typeof object_id !== "string") {
+      throw new VerdifaxError("verdifax: policy_context.object_id must be a string");
+    }
+    if (Buffer.byteLength(object_id, "utf8") > MAX_POLICY_OBJECT_ID_BYTES) {
+      throw new VerdifaxError(
+        `verdifax: policy_context.object_id is longer than ${MAX_POLICY_OBJECT_ID_BYTES} bytes`
+      );
+    }
+    out.object_id = object_id;
+  }
+  if (classification !== void 0) {
+    refuseOutsideList(classification, POLICY_CLASSIFICATIONS, "classification");
+    out.classification = classification;
+  }
+  return out;
+}
+function refuseActorFactsWithoutActor(context, attested) {
+  const declaresActor = context.actor_type !== void 0 || context.mfa_satisfied === true || (context.session_age_seconds ?? 0) !== 0;
+  if (declaresActor && attested?.attested !== true) {
+    throw new VerdifaxError(
+      "verdifax: policy_context.actor_type, mfa_satisfied and session_age_seconds describe the attested actor; send attested_context with the actor, for example its actor_id"
+    );
+  }
+}
+var EXECUTE_FIELD_SET = {
+  payload: true,
+  payload_text: true,
+  program_id: true,
+  route_id: true,
+  registry_record_hash: true,
+  ai_output_text: true,
+  attested_context: true,
+  reproducibility_context: true,
+  request_substance: true,
+  authorization_chain: true,
+  regulatory_scaffolding: true,
+  causal_graph: true,
+  request_signature: true,
+  signed_request: true,
+  job: true,
+  policy_context: true,
+  expected_policy_hash: true
+};
+var EXECUTE_FIELDS = Object.freeze(
+  Object.keys(EXECUTE_FIELD_SET)
+);
+var ATTESTED_CONTEXT_FIELDS = {
+  attested: true,
+  actor_id: true,
+  actor_role: true,
+  authorization_policy: true,
+  actor_signature: true,
+  model_provider: true,
+  model_name: true,
+  model_version: true,
+  model_temperature: true,
+  prompt_hash: true,
+  decision_kind: true,
+  decision_result: true,
+  decision_note: true
+};
+function refuseUnknownRequestFields(req, label = "request") {
+  if (typeof req !== "object" || req === null || Array.isArray(req)) {
+    throw new VerdifaxError(`verdifax: ${label} must be an object`);
+  }
+  refuseUnknownFields(req, EXECUTE_FIELD_SET, label);
+  const context = req.attested_context;
+  if (typeof context === "object" && context !== null) {
+    refuseUnknownFields(context, ATTESTED_CONTEXT_FIELDS, "attested_context");
+  }
+}
 function withExecuteFlags(req) {
+  refuseUnknownRequestFields(req);
   const body = { ...req };
   if (req.job === void 0 || req.job === null) {
     delete body.job;
@@ -227,6 +367,17 @@ function withExecuteFlags(req) {
   if (req.reproducibility_context) {
     body.reproducibility_context = withDeclaredFlag(req.reproducibility_context);
   }
+  if (req.policy_context === void 0 || req.policy_context === null) {
+    delete body.policy_context;
+  } else {
+    body.policy_context = checkedPolicyContext(req.policy_context);
+    refuseActorFactsWithoutActor(body.policy_context, body.attested_context);
+  }
+  if (req.expected_policy_hash === void 0 || req.expected_policy_hash === null) {
+    delete body.expected_policy_hash;
+  } else {
+    validateHex64(req.expected_policy_hash, "expected_policy_hash");
+  }
   return body;
 }
 
@@ -237,6 +388,7 @@ var REQUEST_SIGNATURE_VERSION_2 = "2";
 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 SIGNING_KEY_BYTES = 32;
 var PKCS8_ED25519_HEADER = Buffer.from(
   "302e020100300506032b657004220420",
@@ -391,6 +543,36 @@ function requestKeyChangeApproval(currentSigningKey, newPublicKey, options = {})
     nonce
   };
 }
+function policyActivationPreimage(fields) {
+  return Buffer.from(
+    [
+      POLICY_ACTIVATION_FORM,
+      fields.chain_id,
+      fields.document_hash,
+      fields.previous_activation_hash,
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
+  );
+}
+function policyActivationApproval(signingKey, fields, options = {}) {
+  const key = loadSigningKey(signingKey);
+  const signed_at = options.signedAt ?? signedAtNow();
+  const nonce = options.nonce ?? (0, import_node_crypto.randomBytes)(16).toString("hex");
+  const preimage = policyActivationPreimage({
+    chain_id: fields.chain_id,
+    document_hash: fields.document_hash,
+    previous_activation_hash: fields.previous_activation_hash,
+    signed_at,
+    nonce
+  });
+  return {
+    signature: (0, import_node_crypto.sign)(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
+}
 
 // src/job.ts
 var STEP_OPTIONS = {
@@ -406,6 +588,8 @@ var STEP_OPTIONS = {
   authorization_chain: true,
   regulatory_scaffolding: true,
   causal_graph: true,
+  policy_context: true,
+  expected_policy_hash: true,
   after: true,
   external_previous: true,
   final: true
@@ -490,7 +674,7 @@ var VerdifaxJob = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.3.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
@@ -500,10 +684,46 @@ 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 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 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 ATTEST_FIELDS = {
+  payload: true,
+  payload_text: true,
+  program_id: true,
+  route_id: true,
+  registry_record_hash: true,
+  ai_output_text: true,
+  attested_context: true,
+  reproducibility_context: true,
+  request_substance: true,
+  authorization_chain: true,
+  regulatory_scaffolding: true,
+  causal_graph: true,
+  job: true,
+  policy_context: true,
+  expected_policy_hash: true
+};
+var PROVIDER_ARGS = Object.fromEntries(
+  [
+    "program_id",
+    "route_id",
+    "registry_record_hash",
+    "prompt",
+    "response",
+    "govern",
+    "job",
+    "policy_context",
+    "expected_policy_hash",
+    ...EXECUTE_FIELDS
+  ].map((name) => [name, true])
+);
 var VerdifaxClient = class {
   baseURL;
   apiKey;
@@ -539,6 +759,7 @@ var VerdifaxClient = class {
   }
   // ── Execute / Attest (auth) ───────────────────────────────────
   async execute(req) {
+    refuseUnknownRequestFields(req);
     this.requireExecuteFields(req);
     const sent = this.prepared(req);
     const out = await this.request("POST", "/execute", sent);
@@ -549,6 +770,7 @@ var VerdifaxClient = class {
    *  its nonce once. Both runs are recorded. A run that happens twice
    *  cannot be one job step, so a `job` is refused here. */
   async verifyDeterminism(req) {
+    refuseUnknownRequestFields(req);
     this.requireExecuteFields(req);
     if (req.job !== void 0 && req.job !== null) {
       throw new VerdifaxError(
@@ -567,8 +789,9 @@ var VerdifaxClient = class {
    *  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, except a job
-   *  block, which is refused before anything is sent: the server reports
-   *  any other bad row in that row's result.
+   *  block, a `policy_context` and an `expected_policy_hash`, which are
+   *  refused before anything is sent: the server reports any other 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. */
@@ -582,6 +805,7 @@ var VerdifaxClient = class {
         `verdifax: executeBatch accepts at most ${MAX_BATCH_ROWS} runs (got ${runs.length})`
       );
     }
+    runs.forEach((run, i) => refuseUnknownRequestFields(run, `runs[${i}]`));
     const sent = runs.map((run) => this.prepared(run));
     const out = await this.request(
       "POST",
@@ -602,6 +826,8 @@ var VerdifaxClient = class {
    *  routes the call through to the canonical /execute. */
   async attest(req) {
     this.requireAPIKey();
+    refuseUnknownRequestFields(req, "attest request");
+    refuseUnknownFields(req, ATTEST_FIELDS, "attest request");
     if (req.payload !== void 0 && req.payload_text !== void 0) {
       throw new VerdifaxError(
         "verdifax: attest accepts payload OR payload_text, not both"
@@ -626,7 +852,9 @@ var VerdifaxClient = class {
       authorization_chain: req.authorization_chain,
       regulatory_scaffolding: req.regulatory_scaffolding,
       causal_graph: req.causal_graph,
-      job: req.job
+      job: req.job,
+      policy_context: req.policy_context,
+      expected_policy_hash: req.expected_policy_hash
     };
     if (req.payload !== void 0) {
       body.payload = Buffer.isBuffer(req.payload) ? req.payload.toString("base64") : Buffer.from(req.payload).toString("base64");
@@ -646,15 +874,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)
     );
   }
@@ -693,14 +924,277 @@ 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;
   }
+  // ── Policies (auth) ──────────────────────────────────────────
+  /** Stores a policy document. Nothing changes until it is activated with
+   *  {@link activatePolicy}. The server hashes the exact text, so this
+   *  sends the string it is given unchanged and refuses anything that is
+   *  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) {
+    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
+   *  document in force (empty under the built-in policy). */
+  async listPolicies() {
+    this.requireAPIKey();
+    return this.request("GET", POLICIES_PATH);
+  }
+  /** One stored document, with its exact text as `document`. */
+  async getPolicy(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) {
+    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
+   *  `writeFileSync("policy-history.json", JSON.stringify(history))`, and
+   *  check it with `verdifax-verify --policy-history policy-history.json`. */
+  async getPolicyHistory() {
+    this.requireAPIKey();
+    return this.request("GET", `${POLICIES_PATH}/history`);
+  }
+  /** Makes a stored document the policy in force and returns the change
+   *  record. It first reads GET /policies for the chain and its newest
+   *  change, then names that change as the one this follows. With the
+   *  `signingKey` option the request key signs the change, which the server
+   *  requires while a request key is registered.
+   *
+   *  Rolling back is activating an earlier document: it is one more change
+   *  in the chain, so the change it undoes stays on the record.
+   *
+   *  An HTTP 409 means the chain moved because another change came first,
+   *  or the document is not yet effective. It throws the usual
+   *  {@link APIError} and is not retried: read the policies again and
+   *  decide. */
+  async activatePolicy(documentHash) {
+    this.requireAPIKey();
+    validateHex64(documentHash, "documentHash");
+    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(
+        "verdifax: the server did not report newest_activation_hash, so the change cannot name the one it follows"
+      );
+    }
+    const body = { previous_activation_hash: previous };
+    if (this.signingKey) {
+      if (typeof chain.chain_id !== "string" || chain.chain_id === "") {
+        throw new VerdifaxError(
+          "verdifax: the server did not report chain_id, so the change cannot be signed"
+        );
+      }
+      body.signature = policyActivationApproval(this.signingKey, {
+        chain_id: chain.chain_id,
+        document_hash: documentHash,
+        previous_activation_hash: previous
+      });
+    }
+    const out = await this.request(
+      "POST",
+      `${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);
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -713,6 +1207,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) {
@@ -722,7 +1219,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 };
   }
@@ -760,7 +1257,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
@@ -768,9 +1268,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);
@@ -781,13 +1284,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 = {}) {
@@ -925,14 +1428,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();
@@ -965,11 +1502,13 @@ var VerdifaxClient = class {
    *  `ai_output_text`; that is off by default, so the text leaves your
    *  machine for review only when you ask. */
   async attestClaudeResponse(args) {
+    refuseUnknownFields(args, PROVIDER_ARGS, "attestClaudeResponse arguments");
     return this.attestProviderResponse({ ...args, provider: "anthropic" });
   }
   /** Convenience for attesting an OpenAI API response. `govern` works as
    *  in {@link attestClaudeResponse}. */
   async attestOpenAIResponse(args) {
+    refuseUnknownFields(args, PROVIDER_ARGS, "attestOpenAIResponse arguments");
     return this.attestProviderResponse({ ...args, provider: "openai" });
   }
   async attestProviderResponse(args) {
@@ -992,7 +1531,9 @@ var VerdifaxClient = class {
         actor_role: "ai_assistant",
         model_provider: args.provider
       },
-      job: args.job
+      job: args.job,
+      policy_context: args.policy_context,
+      expected_policy_hash: args.expected_policy_hash
     });
   }
   // ── HTTP plumbing, retry-aware ──────────────────────────────
@@ -1107,6 +1648,11 @@ 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 withSignedText(result, sent) {
   return "signed_request" in sent ? { ...result, signed_request: sent.signed_request } : result;
 }
@@ -1301,6 +1847,7 @@ function cresReceiptHash(fields) {
   CRES_PREIMAGE_VERSION,
   DCAE_PREIMAGE_VERSION,
   DSE_FORMULA_VERSION,
+  EXECUTE_FIELDS,
   MAX_BATCH_ROWS,
   NotFoundError,
   RUN_STATUSES,
@@ -1314,6 +1861,8 @@ function cresReceiptHash(fields) {
   formatProviderPayload,
   fromEnv,
   generateRequestKeyPair,
+  policyActivationApproval,
+  policyActivationPreimage,
   requestKeyChangeApproval,
   requestKeyChangePreimage,
   requestKeyRegistrationBody,