verdifax 1.0.0 → 1.2.0

package/dist/index.mjs

@@ -23,15 +23,23 @@ var NotFoundError = class extends VerdifaxError {
   name = "VerdifaxNotFoundError";
 };
 var APIError = class extends VerdifaxError {
-  constructor(status, path, message) {
+  constructor(status, path, message, recordHash, signedRequest) {
     super(`verdifax: API error at ${path} (HTTP ${status}): ${message}`);
     this.status = status;
     this.path = path;
     this.message = message;
+    this.recordHash = recordHash;
+    if (signedRequest !== void 0) {
+      Object.defineProperty(this, "signedRequest", {
+        value: signedRequest,
+        enumerable: false
+      });
+    }
   }
   status;
   path;
   message;
+  recordHash;
   name = "VerdifaxAPIError";
 };
 var APIKeyRequiredError = class extends VerdifaxError {
@@ -51,8 +59,286 @@ import {
   randomBytes,
   sign
 } from "crypto";
+
+// src/validation.ts
+function validateHex64(value, fieldName) {
+  if (typeof value !== "string" || value.length !== 64) {
+    throw new VerdifaxError(
+      `verdifax: ${fieldName} must be 64 hex characters (got ${typeof value === "string" ? value.length : typeof value})`
+    );
+  }
+  if (!/^[0-9a-f]{64}$/.test(value)) {
+    throw new VerdifaxError(
+      `verdifax: ${fieldName} must contain only lowercase hex (0-9, a-f)`
+    );
+  }
+}
+function validateRouteId(value) {
+  if (!value || typeof value !== "string") {
+    throw new VerdifaxError("verdifax: route_id is required");
+  }
+  if (value.length > 256) {
+    throw new VerdifaxError(
+      `verdifax: route_id is too long (${value.length} > 256)`
+    );
+  }
+  if (!/^[\x20-\x7E]+$/.test(value)) {
+    throw new VerdifaxError(
+      "verdifax: route_id contains non-printable-ASCII character"
+    );
+  }
+}
+function validateJobName(value, fieldName) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) {
+    throw new VerdifaxError(
+      `verdifax: ${fieldName} must be 1 to 128 letters, digits, dots, underscores, colons or dashes`
+    );
+  }
+}
+
+// src/helpers.ts
+function formatProviderPayload(provider, prompt, response) {
+  if ([provider, prompt, response].some((text) => /[\uD800-\uDFFF]/u.test(text))) {
+    throw new VerdifaxError(
+      "verdifax: provider payload text cannot be encoded as UTF-8"
+    );
+  }
+  return JSON.stringify({ prompt, provider, response });
+}
+function isProvided(value) {
+  return value !== null && value !== void 0 && value !== "" && value !== false;
+}
+function withAttestedFlag(context) {
+  const provided = Object.entries(context).some(
+    ([name, value]) => name !== "attested" && isProvided(value)
+  );
+  return { ...context, attested: provided };
+}
+function withDeclaredFlag(context) {
+  const declared = Object.entries(context).some(
+    ([name, value]) => name !== "declared" && isProvided(value) && !(Array.isArray(value) && value.length === 0)
+  );
+  return { ...context, declared };
+}
+function refuseCallerOriginHashes(substance) {
+  const origin = substance?.origin;
+  if (origin?.source_ip_hash || origin?.user_agent_hash) {
+    throw new VerdifaxError(
+      "verdifax: request_substance.origin.source_ip_hash and user_agent_hash are computed by the server and cannot be supplied"
+    );
+  }
+}
+var JOB_FIELDS = {
+  job_id: true,
+  step_id: true,
+  previous_record_hashes: true,
+  external_previous: true,
+  final: true
+};
+function refuseUnknownFields(value, known, label) {
+  for (const name of Object.keys(value)) {
+    if (!Object.hasOwn(known, name)) {
+      throw new VerdifaxError(`verdifax: ${label} has an unknown field: ${name}`);
+    }
+  }
+}
+function sortedUnique(hashes, fieldName) {
+  if (hashes === void 0) return [];
+  if (!Array.isArray(hashes) || hashes.some((hash) => typeof hash !== "string")) {
+    throw new VerdifaxError(`verdifax: ${fieldName} must be a list of strings`);
+  }
+  return [...new Set(hashes)].sort();
+}
+function normalizedJob(job) {
+  if (typeof job !== "object" || job === null || Array.isArray(job)) {
+    throw new VerdifaxError("verdifax: job must be an object");
+  }
+  refuseUnknownFields(job, JOB_FIELDS, "job");
+  validateJobName(job.job_id, "job_id");
+  validateJobName(job.step_id, "step_id");
+  if (job.final !== void 0 && typeof job.final !== "boolean") {
+    throw new VerdifaxError("verdifax: job.final must be true or false");
+  }
+  const out = { job_id: job.job_id, step_id: job.step_id };
+  const previous = sortedUnique(job.previous_record_hashes, "previous_record_hashes");
+  if (previous.length > 0) out.previous_record_hashes = previous;
+  const external = sortedUnique(job.external_previous, "external_previous");
+  if (external.length > 0) out.external_previous = external;
+  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;
+  } else {
+    body.job = normalizedJob(req.job);
+  }
+  if (req.attested_context) {
+    body.attested_context = withAttestedFlag(req.attested_context);
+  }
+  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;
+}
+
+// src/signing.ts
 var REQUEST_SIGNATURE_FORM = "verdifax.request.v1";
+var REQUEST_SIGNATURE_FORM_V2 = "verdifax.request.v2";
+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",
@@ -83,6 +369,12 @@ function loadSigningKey(key) {
     type: "pkcs8"
   });
 }
+function sha256Hex(text) {
+  return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+function signedAtNow() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+}
 function requestSignaturePreimage(fields) {
   return Buffer.from(
     [
@@ -97,13 +389,62 @@ function requestSignaturePreimage(fields) {
     "utf8"
   );
 }
+function requestSignaturePreimageV2(fields) {
+  const { job } = fields;
+  return Buffer.from(
+    [
+      REQUEST_SIGNATURE_FORM_V2,
+      fields.body_hash,
+      fields.payload_hash,
+      fields.program_id,
+      fields.route_id,
+      fields.registry_record_hash,
+      fields.ai_output_hash,
+      JOB_FORM,
+      job?.job_id ?? "",
+      job?.step_id ?? "",
+      (job?.previous_record_hashes ?? []).join(","),
+      (job?.external_previous ?? []).join(","),
+      job?.final ? "true" : "false",
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
+  );
+}
+function signRequestV2(signingKey, req, options = {}) {
+  const key = loadSigningKey(signingKey);
+  const { request_signature: _unsigned, ...fields } = withExecuteFlags(req);
+  const signed_request = JSON.stringify(fields);
+  const signed_at = options.signedAt ?? signedAtNow();
+  const nonce = options.nonce ?? randomBytes(16).toString("hex");
+  const preimage = requestSignaturePreimageV2({
+    body_hash: sha256Hex(signed_request),
+    payload_hash: sha256Hex(fields.payload_text || fields.payload || ""),
+    program_id: fields.program_id,
+    route_id: fields.route_id,
+    registry_record_hash: fields.registry_record_hash,
+    ai_output_hash: fields.ai_output_text ? sha256Hex(fields.ai_output_text) : "",
+    job: fields.job,
+    signed_at,
+    nonce
+  });
+  return {
+    signed_request,
+    request_signature: {
+      version: REQUEST_SIGNATURE_VERSION_2,
+      signature: sign(null, preimage, key).toString("base64"),
+      signed_at,
+      nonce
+    }
+  };
+}
 function signRequest(signingKey, req, options = {}) {
   const key = loadSigningKey(signingKey);
-  const signed_at = options.signedAt ?? (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  const signed_at = options.signedAt ?? signedAtNow();
   const nonce = options.nonce ?? randomBytes(16).toString("hex");
-  const payload_hash = createHash("sha256").update(Buffer.from(req.payload_text || req.payload || "", "utf8")).digest("hex");
   const preimage = requestSignaturePreimage({
-    payload_hash,
+    payload_hash: sha256Hex(req.payload_text || req.payload || ""),
     program_id: req.program_id,
     route_id: req.route_id,
     registry_record_hash: req.registry_record_hash,
@@ -126,81 +467,164 @@ function requestKeyRegistrationBody(signingKey) {
   ).toString("base64");
   return { public_key, proof };
 }
-
-// src/helpers.ts
-function formatProviderPayload(provider, prompt, response) {
-  if ([provider, prompt, response].some((text) => /[\uD800-\uDFFF]/u.test(text))) {
-    throw new VerdifaxError(
-      "verdifax: provider payload text cannot be encoded as UTF-8"
-    );
-  }
-  return JSON.stringify({ prompt, provider, response });
-}
-function isProvided(value) {
-  return value !== null && value !== void 0 && value !== "" && value !== false;
-}
-function withAttestedFlag(context) {
-  const provided = Object.entries(context).some(
-    ([name, value]) => name !== "attested" && isProvided(value)
+function requestKeyChangePreimage(fields) {
+  return Buffer.from(
+    [
+      REQUEST_KEY_CHANGE_FORM,
+      fields.new_public_key,
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
   );
-  return { ...context, attested: provided };
 }
-function withDeclaredFlag(context) {
-  const declared = Object.entries(context).some(
-    ([name, value]) => name !== "declared" && isProvided(value) && !(Array.isArray(value) && value.length === 0)
-  );
-  return { ...context, declared };
+function requestKeyChangeApproval(currentSigningKey, newPublicKey, options = {}) {
+  const key = loadSigningKey(currentSigningKey);
+  const signed_at = options.signedAt ?? signedAtNow();
+  const nonce = options.nonce ?? randomBytes(16).toString("hex");
+  const preimage = requestKeyChangePreimage({
+    new_public_key: newPublicKey,
+    signed_at,
+    nonce
+  });
+  return {
+    signature: sign(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
 }
-function refuseCallerOriginHashes(substance) {
-  const origin = substance?.origin;
-  if (origin?.source_ip_hash || origin?.user_agent_hash) {
-    throw new VerdifaxError(
-      "verdifax: request_substance.origin.source_ip_hash and user_agent_hash are computed by the server and cannot be supplied"
-    );
-  }
+function 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 withExecuteFlags(req) {
-  const body = { ...req };
-  if (req.attested_context) {
-    body.attested_context = withAttestedFlag(req.attested_context);
-  }
-  if (req.reproducibility_context) {
-    body.reproducibility_context = withDeclaredFlag(req.reproducibility_context);
-  }
-  return body;
+function policyActivationApproval(signingKey, fields, options = {}) {
+  const key = loadSigningKey(signingKey);
+  const signed_at = options.signedAt ?? signedAtNow();
+  const nonce = options.nonce ?? 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: sign(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
 }
 
-// src/validation.ts
-function validateHex64(value, fieldName) {
-  if (typeof value !== "string" || value.length !== 64) {
-    throw new VerdifaxError(
-      `verdifax: ${fieldName} must be 64 hex characters (got ${typeof value === "string" ? value.length : typeof value})`
-    );
-  }
-  if (!/^[0-9a-f]{64}$/.test(value)) {
-    throw new VerdifaxError(
-      `verdifax: ${fieldName} must contain only lowercase hex (0-9, a-f)`
-    );
-  }
-}
-function validateRouteId(value) {
-  if (!value || typeof value !== "string") {
-    throw new VerdifaxError("verdifax: route_id is required");
+// src/job.ts
+var STEP_OPTIONS = {
+  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,
+  policy_context: true,
+  expected_policy_hash: true,
+  after: true,
+  external_previous: true,
+  final: true
+};
+var VerdifaxJob = class {
+  jobId;
+  client;
+  hashes = /* @__PURE__ */ new Map();
+  #signedRequests = /* @__PURE__ */ new Map();
+  lastStepId;
+  constructor(client, jobId) {
+    validateJobName(jobId, "job_id");
+    this.client = client;
+    this.jobId = jobId;
+  }
+  /** Step id to record hash for every step that left a record, on a copy. */
+  get recordHashes() {
+    return Object.fromEntries(this.hashes);
+  }
+  /** Step id to the exact text that was signed, for every signed step that
+   *  left a record, refused and halted steps included, on a copy. Each text
+   *  can be passed to `verdifax-verify --request FILE`. */
+  get signedRequests() {
+    return Object.fromEntries(this.#signedRequests);
+  }
+  /** Runs one step and records its hash and signed text. A refused or halted
+   *  step records both from the error, then throws the same error `attest`
+   *  throws. */
+  async step(stepId, options) {
+    validateJobName(stepId, "step_id");
+    refuseUnknownFields(options, STEP_OPTIONS, "step options");
+    const { after, external_previous, final, ...attest } = options;
+    const job = {
+      job_id: this.jobId,
+      step_id: stepId,
+      previous_record_hashes: this.previousHashes(after),
+      external_previous,
+      final
+    };
+    let result;
+    try {
+      result = await this.client.attest({ ...attest, job });
+    } catch (err) {
+      if (err instanceof APIError && err.recordHash) {
+        this.record(stepId, err.recordHash, err.signedRequest);
+      }
+      throw err;
+    }
+    const hash = result?.record_hash || result?.manifest_hash || result?.manifest?.ManifestHash;
+    if (!hash) {
+      throw new VerdifaxError(
+        `verdifax: the server returned no record_hash or manifest_hash for step ${stepId}, so the job map cannot continue from it`
+      );
+    }
+    this.record(stepId, hash, result.signed_request);
+    return result;
   }
-  if (value.length > 256) {
-    throw new VerdifaxError(
-      `verdifax: route_id is too long (${value.length} > 256)`
-    );
+  previousHashes(after) {
+    if (after === void 0 || after === null) {
+      return this.lastStepId === void 0 ? [] : [this.hashes.get(this.lastStepId)];
+    }
+    if (!Array.isArray(after)) {
+      throw new VerdifaxError("verdifax: after must be a list of step ids");
+    }
+    return after.map((stepId) => {
+      const hash = this.hashes.get(stepId);
+      if (hash === void 0) {
+        throw new VerdifaxError(
+          `verdifax: after names ${String(stepId)}, which is not a step in job ${this.jobId}`
+        );
+      }
+      return hash;
+    });
   }
-  if (!/^[\x20-\x7E]+$/.test(value)) {
-    throw new VerdifaxError(
-      "verdifax: route_id contains non-printable-ASCII character"
-    );
+  record(stepId, hash, signedRequest) {
+    this.hashes.set(stepId, hash);
+    if (signedRequest !== void 0) {
+      this.#signedRequests.set(stepId, signedRequest);
+    }
+    this.lastStepId = stepId;
   }
-}
+};
 
 // src/version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.2.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
@@ -210,10 +634,42 @@ 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 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;
@@ -249,25 +705,39 @@ var VerdifaxClient = class {
   }
   // ── Execute / Attest (auth) ───────────────────────────────────
   async execute(req) {
+    refuseUnknownRequestFields(req);
     this.requireExecuteFields(req);
-    return this.request("POST", "/execute", this.prepared(req));
+    const sent = this.prepared(req);
+    const out = await this.request("POST", "/execute", sent);
+    return withSignedText(out, sent);
   }
   /** Runs one payload twice on the server and compares the manifest
    *  hashes. One signature covers the request, and the server claims
-   *  its nonce once. Both runs are recorded. */
+   *  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);
-    return this.request(
+    if (req.job !== void 0 && req.job !== null) {
+      throw new VerdifaxError(
+        "verdifax: a determinism check runs twice, so it cannot be a job step"
+      );
+    }
+    const sent = this.prepared(req);
+    const out = await this.request(
       "POST",
       "/execute/verify-determinism",
-      this.prepared(req)
+      sent
     );
+    return withSignedText(out, sent);
   }
   /** Sends up to {@link MAX_BATCH_ROWS} runs in one request. With a
    *  signing key each row carries its own signature and nonce. A row
    *  that fails comes back in `results` with `ok: false`, so the call
-   *  does not throw for it. The rows are not checked here: the server
-   *  reports a bad row in that row's result.
+   *  does not throw for it. The rows are not checked here, except a job
+   *  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. */
@@ -281,9 +751,20 @@ var VerdifaxClient = class {
         `verdifax: executeBatch accepts at most ${MAX_BATCH_ROWS} runs (got ${runs.length})`
       );
     }
-    return this.request("POST", "/execute/batch", {
-      runs: runs.map((run) => this.prepared(run))
-    });
+    runs.forEach((run, i) => refuseUnknownRequestFields(run, `runs[${i}]`));
+    const sent = runs.map((run) => this.prepared(run));
+    const out = await this.request(
+      "POST",
+      "/execute/batch",
+      { runs: sent }
+    );
+    if (!Array.isArray(out?.results)) return out;
+    return {
+      ...out,
+      results: out.results.map(
+        (row, i) => i < sent.length ? withSignedText(row, sent[i]) : row
+      )
+    };
   }
   /** High-level convenience wrapper around `execute()`. Accepts
    *  either a Buffer (for binary payloads, auto-base64) or a
@@ -291,6 +772,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"
@@ -314,7 +797,10 @@ var VerdifaxClient = class {
       request_substance: req.request_substance,
       authorization_chain: req.authorization_chain,
       regulatory_scaffolding: req.regulatory_scaffolding,
-      causal_graph: req.causal_graph
+      causal_graph: req.causal_graph,
+      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");
@@ -323,6 +809,12 @@ var VerdifaxClient = class {
     }
     return this.execute(body);
   }
+  /** A helper that runs the steps of one job through {@link attest} and
+   *  keeps each step's record hash, so a later step can name it. It makes
+   *  no request until a step runs. */
+  job(jobId) {
+    return new VerdifaxJob(this, jobId);
+  }
   // ── Request signing (auth) ───────────────────────────────────
   /** Registers this client's public key on its API key, with the proof
    *  that the client holds the private key. From then on the server
@@ -340,11 +832,162 @@ var VerdifaxClient = class {
       requestKeyRegistrationBody(this.signingKey)
     );
   }
+  /** Replaces the registered key with `newSigningKey`. The new key proves
+   *  itself and this client's current key approves the change. After
+   *  success this client signs with the new key. If the call fails it
+   *  keeps the current key, including after a timeout, when the server may
+   *  have made the change. */
+  async rotateRequestKey(newSigningKey) {
+    this.requireAPIKey();
+    if (!this.signingKey) {
+      throw new VerdifaxError(
+        "verdifax: rotateRequestKey needs the current key in the signingKey client option"
+      );
+    }
+    const next = loadSigningKey(newSigningKey);
+    const registration = requestKeyRegistrationBody(next);
+    const out = await this.request(
+      "POST",
+      REQUEST_KEY_PATH,
+      {
+        ...registration,
+        change: requestKeyChangeApproval(
+          this.signingKey,
+          registration.public_key
+        )
+      }
+    );
+    this.signingKey = next;
+    return out;
+  }
   /** Clears the registered public key, so the server stops requiring
-   *  request signatures on this API key. */
+   *  request signatures on this API key. With a signing key the client
+   *  sends that key's approval, which the server requires while a key is
+   *  registered. After success the client drops its signing key and sends
+   *  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() {
     this.requireAPIKey();
-    await this.request("DELETE", REQUEST_KEY_PATH);
+    await this.request(
+      "DELETE",
+      REQUEST_KEY_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) {
+    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 });
+  }
+  /** 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) {
+    this.requireAPIKey();
+    validateHex64(documentHash, "documentHash");
+    return this.request(
+      "GET",
+      `${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
+    );
+  }
+  /** 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");
+    const chain = await this.listPolicies();
+    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",
+      `${POLICIES_PATH}/${documentHash}/activate`,
+      body
+    );
+    return out.activation;
   }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
@@ -430,6 +1073,7 @@ var VerdifaxClient = class {
     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()}`;
   }
@@ -593,17 +1237,29 @@ var VerdifaxClient = class {
     }
     await this.request("DELETE", `/admin/keys/${keyId}`);
   }
+  /** Clears the request key on an API key whose holder lost it, after a
+   *  manual check. It is the one way to clear a key without that key. The
+   *  id can be any API key, so this client keeps its own signing key. */
+  async adminClearRequestKey(keyId) {
+    this.requireAPIKey();
+    if (keyId <= 0) {
+      throw new VerdifaxError("verdifax: keyId must be > 0");
+    }
+    await this.request("DELETE", `/admin/keys/${keyId}/request-key`);
+  }
   // ── Provider helpers (Claude / OpenAI) ───────────────────────
   /** Convenience for attesting an Anthropic Claude API response. With
    *  `govern: true` the response text also goes to the AIVP review as
    *  `ai_output_text`; that is off by default, so the text leaves your
    *  machine for review only when you ask. */
   async attestClaudeResponse(args) {
+    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) {
@@ -625,7 +1281,10 @@ var VerdifaxClient = class {
       attested_context: {
         actor_role: "ai_assistant",
         model_provider: args.provider
-      }
+      },
+      job: args.job,
+      policy_context: args.policy_context,
+      expected_policy_hash: args.expected_policy_hash
     });
   }
   // ── HTTP plumbing, retry-aware ──────────────────────────────
@@ -672,9 +1331,13 @@ var VerdifaxClient = class {
           continue;
         }
         let errMessage = text.trim();
+        let recordHash;
         try {
           const env = JSON.parse(text);
           if (env.error) errMessage = env.error;
+          if (typeof env.record_hash === "string" && env.record_hash) {
+            recordHash = env.record_hash;
+          }
         } catch {
         }
         switch (resp.status) {
@@ -683,7 +1346,13 @@ var VerdifaxClient = class {
           case 404:
             throw new NotFoundError(path, errMessage);
           default:
-            throw new APIError(resp.status, path, errMessage);
+            throw new APIError(
+              resp.status,
+              path,
+              errMessage,
+              recordHash,
+              body?.signed_request
+            );
         }
       }
       if (rawText) return { text, headers: resp.headers };
@@ -724,13 +1393,15 @@ var VerdifaxClient = class {
     validateRouteId(req.route_id);
     refuseCallerOriginHashes(req.request_substance);
   }
-  /** The request with its derived flags and, with a signing key, a fresh
-   *  signature and nonce, on a copy. */
+  /** The body to send, on a copy: the request with its derived flags or,
+   *  with a signing key, the signed text with a fresh signature and nonce. */
   prepared(req) {
-    const body = withExecuteFlags(req);
-    return this.signingKey ? { ...body, request_signature: signRequest(this.signingKey, body) } : body;
+    return this.signingKey ? signRequestV2(this.signingKey, req) : withExecuteFlags(req);
   }
 };
+function withSignedText(result, sent) {
+  return "signed_request" in sent ? { ...result, signed_request: sent.signed_request } : result;
+}
 
 // src/config.ts
 function fromEnv() {
@@ -858,7 +1529,7 @@ var DSE_FORMULA_VERSION = "dse.tcu.dispatch.v1";
 var DCAE_PREIMAGE_VERSION = "verdifax.dcae.v1";
 var CRES_PREIMAGE_VERSION = "verdifax.cres.v1";
 var CRES_ENGINE_VERSION = "verdifax-cres/1.0.0";
-function sha256Hex(preimage) {
+function sha256Hex2(preimage) {
   return createHash2("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
 }
 function requireHex64(value, name) {
@@ -873,7 +1544,7 @@ function requireHex64(value, name) {
 function dseDispatchHash(fields) {
   requireHex64(fields.program_id, "program_id");
   requireHex64(fields.registry_record_hash, "registry_record_hash");
-  return sha256Hex(
+  return sha256Hex2(
     [
       DSE_FORMULA_VERSION,
       fields.envelope_id,
@@ -887,7 +1558,7 @@ function dcaeClosureHash(fields) {
   requireHex64(fields.manifest_hash, "manifest_hash");
   requireHex64(fields.aer_hash, "aer_hash");
   requireHex64(fields.zksp_binding_hash, "zksp_binding_hash");
-  return sha256Hex(
+  return sha256Hex2(
     [
       DCAE_PREIMAGE_VERSION,
       fields.manifest_hash,
@@ -900,7 +1571,7 @@ function dcaeClosureHash(fields) {
 }
 function cresReceiptHash(fields) {
   requireHex64(fields.ciphertext_hash_at_shred, "ciphertext_hash_at_shred");
-  return sha256Hex(
+  return sha256Hex2(
     [
       CRES_PREIMAGE_VERSION,
       fields.envelope_id,
@@ -921,11 +1592,13 @@ export {
   CRES_PREIMAGE_VERSION,
   DCAE_PREIMAGE_VERSION,
   DSE_FORMULA_VERSION,
+  EXECUTE_FIELDS,
   MAX_BATCH_ROWS,
   NotFoundError,
   RUN_STATUSES,
   VerdifaxClient,
   VerdifaxError,
+  VerdifaxJob,
   captureEnvironment,
   cresReceiptHash,
   dcaeClosureHash,
@@ -933,9 +1606,16 @@ export {
   formatProviderPayload,
   fromEnv,
   generateRequestKeyPair,
+  policyActivationApproval,
+  policyActivationPreimage,
+  requestKeyChangeApproval,
+  requestKeyChangePreimage,
   requestKeyRegistrationBody,
   requestSignaturePreimage,
+  requestSignaturePreimageV2,
   signRequest,
+  signRequestV2,
   validateHex64,
+  validateJobName,
   validateRouteId
 };