verdifax 1.3.0 → 1.4.0

package/README.md

@@ -105,6 +105,13 @@ if (v.verified) {
 | `client.testAccountPolicy({ inputs, document?, documentHash? })` | `POST /account/policies/test` | owner key |
 | `client.getAccountPolicyHistory()` | `GET /account/policies/history` | owner key |
 | `client.activateAccountPolicy(documentHash)` | `POST /account/policies/{document_hash}/activate` | owner key |
+| `client.registerApprover(name, approver)` | `POST /account/approvers` | owner key |
+| `client.listApprovers()` | `GET /account/approvers` | owner key |
+| `client.revokeApprover(id)` | `DELETE /account/approvers/{id}` | owner key |
+| `client.getSignOffHistory()` | `GET /account/signoffs/history` | owner key |
+| `client.getNewestSignOff({ asOwner? })` | `GET /signoffs/newest`, or `GET /account/signoffs/newest` with `asOwner` | required, or owner key |
+| `client.signOff(target, decision, approverKey, { note?, asOwner? })` | `POST /signoffs`, or `POST /account/signoffs` with `asOwner` | required, or owner key |
+| `client.getSignOffs(runId, { asOwner? })` | `GET /runs/{id}/signoffs`, or `GET /account/runs/{id}/signoffs` with `asOwner` | required, or owner key |
 | `client.adminCreateKey(name, { accountId? })` | `POST /admin/keys` | admin |
 | `client.adminListKeys()` | `GET /admin/keys` | admin |
 | `client.adminRevokeKey(id)` | `DELETE /admin/keys/{id}` | admin |
@@ -115,7 +122,7 @@ if (v.verified) {
 
 `client.job(jobId)` returns a [job helper](#jobs) and makes no request until a step runs.
 
-These functions make no request: `captureEnvironment`, `formatProviderPayload`, `signRequest`, `signRequestV2`, `requestKeyRegistrationBody`, `requestKeyChangeApproval`, `requestKeyChangePreimage`, `policyActivationApproval`, `policyActivationPreimage`, `requestSignaturePreimage`, `requestSignaturePreimageV2`, `generateRequestKeyPair`, `validateHex64`, `validateJobName`, `validateRouteId`, `dseDispatchHash`, `dcaeClosureHash` and `cresReceiptHash`. `RUN_STATUSES` lists every run status the server uses, and `EXECUTE_FIELDS` lists every top-level key a run request may hold.
+These functions make no request: `captureEnvironment`, `formatProviderPayload`, `signRequest`, `signRequestV2`, `requestKeyRegistrationBody`, `requestKeyChangeApproval`, `requestKeyChangePreimage`, `policyActivationApproval`, `policyActivationPreimage`, `signOffPreimage`, `approverKeyProof`, `requestSignaturePreimage`, `requestSignaturePreimageV2`, `generateRequestKeyPair`, `validateHex64`, `validateJobName`, `validateRouteId`, `dseDispatchHash`, `dcaeClosureHash` and `cresReceiptHash`. `RUN_STATUSES` lists every run status the server uses, and `EXECUTE_FIELDS` lists every top-level key a run request may hold.
 
 `getRunArtifacts`, `getPublicBundle` and `getPublicBundleByToken` return the exact JSON text the server sent, so you can save it and check it with `verdifax-verify`.
 
@@ -293,6 +300,56 @@ The account's view covers the runs its keys made through Verdifax. It does not c
 
 `exportAccountRuns` and `exportAccountRunsCSV` take the same period and `job_id` as `exportRuns` and check the CSV counts the same way. The JSON form also carries `account_id`, and `account_policy_documents` and `account_policy_history` once the account has loaded a policy. `listAccountRuns` pages like `listRuns`. `revokeAccountKey` revokes a member key, and a key in another account, or an owner key, throws `NotFoundError`. `adminCreateKey(name, { accountId })` puts a new customer key in an existing account, by its number.
 
+## Sign-off
+
+A sign-off is an approver's decision, approve or reject, on one exact result: a completed run's record, a refused or halted run's receipt, or a whole job by its final step. The approver signs it on their own machine with an approver key, and Verdifax links it to the account's previous sign-off and logs it on the public log.
+
+```typescript
+import { writeFileSync } from "node:fs";
+import { VerdifaxClient, approverKeyProof, generateRequestKeyPair } from "verdifax";
+
+// The approver creates a key on their own machine and keeps the private key.
+const approverKey = generateRequestKeyPair().privateKey;
+const proof = approverKeyProof(approverKey); // { public_key, proof }, safe to hand to the owner
+
+// The account's owner registers the approver key.
+const owner = new VerdifaxClient({ apiKey: process.env.VERDIFAX_OWNER_KEY! });
+await owner.registerApprover("credit review", proof);
+
+// Any key in the account submits the approver's signed decision on one exact result.
+const member = new VerdifaxClient({ apiKey: process.env.VERDIFAX_API_KEY! });
+const bundle = JSON.parse(await member.getRunArtifacts(1042));
+const signOff = await member.signOff(
+  { kind: "record", run_id: 1042, digest: bundle.bundle_anchor.anchored_digest },
+  "approve",
+  approverKey,
+  { note: "Checked against the loan file." }, // only its SHA-256 is sent
+);
+console.log(signOff.sequence, signOff.signoff_hash);
+
+// Save the run's sign-offs and check them with verdifax-verify --signoff signoffs.json.
+writeFileSync("signoffs.json", JSON.stringify(await member.getSignOffs(1042)));
+
+// The owner saves the account's whole chain for verdifax-verify --signoff-history.
+writeFileSync("signoff-history.json", JSON.stringify(await owner.getSignOffHistory()));
+```
+
+An approver key is registered by the account's owner, and it is never a request key in the same account. The server refuses to register a key that is, so the key that requested a run cannot sign it off. `registerApprover` takes the approver's signing key, from which it makes the proof on this machine, or the `{ public_key, proof }` that `approverKeyProof` made on the approver's own machine, so the owner need not hold the approver's private key. It refuses a proof that does not verify before sending. `revokeApprover` revokes a key, and its earlier sign-offs stay on the record. `listApprovers` lists revoked keys too.
+
+`signOff` reads `getNewestSignOff` first for the account's chain, `account-N`, and its newest sign-off, then signs over them, the target, the decision, the note's hash, the time and a fresh nonce. The approver's private key is never sent. The target's `digest` is what the result's public-log entry covers: for a record, the `bundle_anchor.anchored_digest` of the bundle `getRunArtifacts` returns; for a receipt, its hash; for a job, the final step's record digest, read the same way as a record's, with `job_id`. The note is hashed on your machine and only its SHA-256 is sent and signed: the note's text never reaches Verdifax, so keep it yourself. `signOff` refuses a bad target, decision, key or note before sending anything. It also checks that the record the server returns carries the signature, `approver_key`, `decision`, `previous_signoff_hash` and `target` that were sent, and throws `VerdifaxError` if not. An HTTP 409 means another sign-off came first or the target is not this account's result: it throws the usual `APIError` and is not retried.
+
+With `asOwner: true`, `signOff`, `getNewestSignOff` and `getSignOffs` use the owner key's `/account` routes. `getSignOffs` returns a run's sign-offs 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. `getSignOffHistory` returns the account's whole chain, oldest first, in the form `verdifax-verify --signoff-history FILE` reads, and `exportAccountRuns` carries the same chain as `signoffs`. The SDK returns `signoffs` as the server sent it, without checking it: check it with `verdifax-verify --signoff-history`.
+
+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 that the review was careful, that the result is right, or who the person is. A key is not an identity.
+
+A sign-off gates nothing on its own.
+
+A later sign-off on the same result supersedes the earlier one, and nothing is deleted.
+
+Verdifax did not review the result.
+
+Since v0.22.0, the verifier reads sign-offs with `--signoff` and `--signoff-history`.
+
 ## Evidence export
 
 `exportRuns` lists the runs the server holds for your key in a period, failures included, with up to 10,000 rows per export. `exportRunsCSV` returns the same rows as raw CSV text.

package/dist/index.d.mts

@@ -569,6 +569,11 @@ interface RunsExport {
  *  key in the account, with the account's policy documents and changes. */
 interface AccountRunsExport extends RunsExport {
     account_id: string;
+    /** The account's whole chain of sign-offs, oldest first, as
+     *  {@link VerdifaxClient.getSignOffHistory} returns it. Only the owner
+     *  key's export carries it, and the SDK returns it as the server sent
+     *  it, without checking it: check it with `verdifax-verify`. */
+    signoffs?: SignOffRecord[];
 }
 /** Returned by {@link VerdifaxClient.exportRunsCSV}. */
 interface RunsExportCSV {
@@ -755,6 +760,127 @@ interface AdminAPIKey {
     run_count: number;
     revoked: boolean;
 }
+/** The kind of result a sign-off names: a completed run's record, a
+ *  refused or halted run's receipt, or a whole job by its final step. */
+type SignOffTargetKind = "record" | "receipt" | "job";
+/** An approver's decision on one result. */
+type SignOffDecision = "approve" | "reject";
+/** The exact result a sign-off names, by what its public-log entry
+ *  covers. */
+interface SignOffTarget {
+    kind: SignOffTargetKind;
+    /** The run: for a job, the run of its final step. */
+    run_id: number;
+    /** What the result's public-log entry covers. For a record, its
+     *  `bundle_anchor.anchored_digest` in the bundle
+     *  {@link VerdifaxClient.getRunArtifacts} returns. For a receipt, its
+     *  hash. For a job, the final step's record digest, read the same way
+     *  as a record's. 64 lowercase hex characters. */
+    digest: Hex64;
+    /** The job, for a job target only. */
+    job_id?: string;
+}
+/** One sign-off, verdifax.signoff.v1, as the server records it and
+ *  `verdifax-verify --signoff` and `--signoff-history` read it. */
+interface SignOffRecord {
+    format: string;
+    /** The account's chain, `account-N`. */
+    chain_id: string;
+    sequence: number;
+    /** The sign-off this one follows, or 64 zeros for the account's first. */
+    previous_signoff_hash: Hex64;
+    target: SignOffTarget;
+    decision: SignOffDecision;
+    /** SHA-256 of the approver's note, when there was one. The note's text
+     *  never reaches Verdifax. */
+    note_hash?: string;
+    /** The base64 Ed25519 public key of the approver who signed. */
+    approver_key: string;
+    /** Base64 Ed25519 signature by the approver key. */
+    signature: string;
+    signed_at: string;
+    nonce: string;
+    recorded_at: string;
+    signoff_hash: Hex64;
+    /** Where the sign-off was logged on the public log. */
+    anchor?: Record<string, unknown>;
+}
+/** What an approver signs against: the account's chain and its newest
+ *  sign-off. Returned by {@link VerdifaxClient.getNewestSignOff}. */
+interface NewestSignOff {
+    ok: boolean;
+    /** The account's chain, `account-N`. */
+    chain_id: string;
+    /** The newest sign-off's hash, or 64 zeros when there is none yet. */
+    newest_signoff_hash: Hex64;
+    /** The newest sign-off's place in the chain, 0 when there is none. */
+    sequence: number;
+}
+/** The approver key's part of a sign-off. */
+interface SignOffSignature {
+    /** The base64 Ed25519 public key of the approver. */
+    approver_key: string;
+    /** Base64 Ed25519 signature by the approver key. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per sign-off. */
+    nonce: string;
+}
+/** Options for {@link VerdifaxClient.signOff}. */
+interface SignOffOptions {
+    /** The approver's note. It is hashed on this machine and only its
+     *  SHA-256 is sent and signed: the text never reaches Verdifax. Keep the
+     *  text yourself to show it matches the hash. */
+    note?: string;
+    /** Use the owner key's routes, /account/signoffs/newest and
+     *  /account/signoffs, instead of a member key's. */
+    asOwner?: boolean;
+}
+/** For a method that serves both a member key's route and the owner
+ *  key's /account route. */
+interface AsOwnerOptions {
+    /** Use the owner key's /account route. */
+    asOwner?: boolean;
+}
+/** An approver key's public key and the proof that its holder has the
+ *  private key, from {@link approverKeyProof}. */
+interface ApproverKeyProof {
+    /** Base64 of the raw 32-byte public key. */
+    public_key: string;
+    /** Base64 Ed25519 signature over verdifax.approver-key.v1, a zero byte
+     *  and the base64 public key. */
+    proof: string;
+}
+/** An approver key registered to an account. A key is not an identity:
+ *  `name` is the label the owner gave it. */
+interface Approver {
+    id: number;
+    public_key: string;
+    name: string;
+    /** The account, `account-N`. */
+    account_id: string;
+    registered_at: string;
+    revoked: boolean;
+    revoked_at?: string;
+}
+/** Returned by {@link VerdifaxClient.registerApprover}. */
+interface ApproverRegistration extends Approver {
+    ok: boolean;
+}
+/** Returned by {@link VerdifaxClient.listApprovers}: revoked keys
+ *  included. */
+interface ApproverList {
+    ok: boolean;
+    account_id: string;
+    approvers: Approver[];
+}
+/** Returned by {@link VerdifaxClient.revokeApprover}. */
+interface ApproverRevocation {
+    ok: boolean;
+    id: number;
+    revoked: boolean;
+}
 
 /**
  * The job helper: runs the steps of one job and keeps the map of step ids
@@ -869,6 +995,13 @@ declare const MAX_BATCH_ROWS = 1000;
  * | `testAccountPolicy(req)` | POST /account/policies/test | owner key |
  * | `getAccountPolicyHistory()` | GET /account/policies/history | owner key |
  * | `activateAccountPolicy(documentHash)` | POST /account/policies/{document_hash}/activate | owner key |
+ * | `registerApprover(name, approver)` | POST /account/approvers | owner key |
+ * | `listApprovers()` | GET /account/approvers | owner key |
+ * | `revokeApprover(id)` | DELETE /account/approvers/{id} | owner key |
+ * | `signOff(target, decision, approverKey, options)` | POST /signoffs, or POST /account/signoffs with asOwner | required |
+ * | `getNewestSignOff(options)` | GET /signoffs/newest, or GET /account/signoffs/newest with asOwner | required |
+ * | `getSignOffs(runId, options)` | GET /runs/{id}/signoffs, or GET /account/runs/{id}/signoffs with asOwner | required |
+ * | `getSignOffHistory()` | GET /account/signoffs/history | owner key |
  * | `job(jobId)` | none, returns a {@link VerdifaxJob} | none |
  *
  * With the `signingKey` option set, every path to POST /execute carries
@@ -1037,6 +1170,56 @@ declare class VerdifaxClient {
      *  `account-N`. The server refuses an unsigned account change, so this
      *  needs the `signingKey` option and refuses to send without it. */
     activateAccountPolicy(documentHash: Hex64): Promise<PolicyActivation>;
+    /** 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. */
+    registerApprover(name: string, approver: Uint8Array | KeyObject | ApproverKeyProof): Promise<ApproverRegistration>;
+    /** The account's approver keys, revoked ones included. */
+    listApprovers(): Promise<ApproverList>;
+    /** 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}. */
+    revokeApprover(approverId: number): Promise<ApproverRevocation>;
+    /** 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. */
+    getNewestSignOff(options?: AsOwnerOptions): Promise<NewestSignOff>;
+    /** 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. */
+    signOff(target: SignOffTarget, decision: SignOffDecision, approverKey: Uint8Array | KeyObject, options?: SignOffOptions): Promise<SignOffRecord>;
+    /** 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. */
+    getSignOffs(runId: number, options?: AsOwnerOptions): Promise<SignOffRecord[]>;
+    /** The account's whole chain of sign-offs, oldest first, in the form
+     *  `verdifax-verify --signoff-history FILE` reads. Needs the owner key. */
+    getSignOffHistory(): Promise<SignOffRecord[]>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -1349,6 +1532,29 @@ declare function policyActivationApproval(signingKey: Uint8Array | KeyObject, fi
     signedAt?: string;
     nonce?: string;
 }): PolicyActivationSignature;
+/** The bytes an approver key signs for one sign-off, matching the
+ *  orchestrator's SignOffPreimage: the fields joined with single zero
+ *  bytes. `chain_id` and `previous_signoff_hash` come from GET
+ *  /signoffs/newest (or /account/signoffs/newest for the owner key), so a
+ *  signature cannot be moved to another account, another result or
+ *  another point in the chain. `target.job_id` is empty unless the target
+ *  is a job, and `note_hash` is empty when there is no note. */
+declare function signOffPreimage(fields: {
+    chain_id: string;
+    previous_signoff_hash: string;
+    target: SignOffTarget;
+    decision: SignOffDecision;
+    note_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** The approver key's base64 public key and its proof: its signature over
+ *  verdifax.approver-key.v1, a zero byte and the base64 public key, which
+ *  shows its holder has the private key. The approver can run this on
+ *  their own machine and give the result to the account's owner, who
+ *  registers it with {@link VerdifaxClient.registerApprover}, so the owner
+ *  never holds the approver's private key. */
+declare function approverKeyProof(approverKey: Uint8Array | KeyObject): ApproverKeyProof;
 
 /**
  * Input-validation helpers, mirrors the Python SDK's
@@ -1434,4 +1640,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type Account, type AccountInfo, type AccountKey, type AccountKeyList, type AccountKeyRevocation, type AccountRunsExport, type AdminAPIKey, type AdminCreateAccountOptions, type AdminCreateAccountResponse, type AdminCreateKeyOptions, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type CreateAccountKeyOptions, type CreatedAccountKey, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type KeyTier, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };
+export { APIError, APIKeyRequiredError, type Account, type AccountInfo, type AccountKey, type AccountKeyList, type AccountKeyRevocation, type AccountRunsExport, type AdminAPIKey, type AdminCreateAccountOptions, type AdminCreateAccountResponse, type AdminCreateKeyOptions, type AdminCreateKeyResponse, type AdminEraseRequest, type Approver, type ApproverKeyProof, type ApproverList, type ApproverRegistration, type ApproverRevocation, type AsOwnerOptions, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type CreateAccountKeyOptions, type CreatedAccountKey, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type KeyTier, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, type NewestSignOff, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignOffDecision, type SignOffOptions, type SignOffRecord, type SignOffSignature, type SignOffTarget, type SignOffTargetKind, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, approverKeyProof, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signOffPreimage, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };

package/dist/index.d.ts

@@ -569,6 +569,11 @@ interface RunsExport {
  *  key in the account, with the account's policy documents and changes. */
 interface AccountRunsExport extends RunsExport {
     account_id: string;
+    /** The account's whole chain of sign-offs, oldest first, as
+     *  {@link VerdifaxClient.getSignOffHistory} returns it. Only the owner
+     *  key's export carries it, and the SDK returns it as the server sent
+     *  it, without checking it: check it with `verdifax-verify`. */
+    signoffs?: SignOffRecord[];
 }
 /** Returned by {@link VerdifaxClient.exportRunsCSV}. */
 interface RunsExportCSV {
@@ -755,6 +760,127 @@ interface AdminAPIKey {
     run_count: number;
     revoked: boolean;
 }
+/** The kind of result a sign-off names: a completed run's record, a
+ *  refused or halted run's receipt, or a whole job by its final step. */
+type SignOffTargetKind = "record" | "receipt" | "job";
+/** An approver's decision on one result. */
+type SignOffDecision = "approve" | "reject";
+/** The exact result a sign-off names, by what its public-log entry
+ *  covers. */
+interface SignOffTarget {
+    kind: SignOffTargetKind;
+    /** The run: for a job, the run of its final step. */
+    run_id: number;
+    /** What the result's public-log entry covers. For a record, its
+     *  `bundle_anchor.anchored_digest` in the bundle
+     *  {@link VerdifaxClient.getRunArtifacts} returns. For a receipt, its
+     *  hash. For a job, the final step's record digest, read the same way
+     *  as a record's. 64 lowercase hex characters. */
+    digest: Hex64;
+    /** The job, for a job target only. */
+    job_id?: string;
+}
+/** One sign-off, verdifax.signoff.v1, as the server records it and
+ *  `verdifax-verify --signoff` and `--signoff-history` read it. */
+interface SignOffRecord {
+    format: string;
+    /** The account's chain, `account-N`. */
+    chain_id: string;
+    sequence: number;
+    /** The sign-off this one follows, or 64 zeros for the account's first. */
+    previous_signoff_hash: Hex64;
+    target: SignOffTarget;
+    decision: SignOffDecision;
+    /** SHA-256 of the approver's note, when there was one. The note's text
+     *  never reaches Verdifax. */
+    note_hash?: string;
+    /** The base64 Ed25519 public key of the approver who signed. */
+    approver_key: string;
+    /** Base64 Ed25519 signature by the approver key. */
+    signature: string;
+    signed_at: string;
+    nonce: string;
+    recorded_at: string;
+    signoff_hash: Hex64;
+    /** Where the sign-off was logged on the public log. */
+    anchor?: Record<string, unknown>;
+}
+/** What an approver signs against: the account's chain and its newest
+ *  sign-off. Returned by {@link VerdifaxClient.getNewestSignOff}. */
+interface NewestSignOff {
+    ok: boolean;
+    /** The account's chain, `account-N`. */
+    chain_id: string;
+    /** The newest sign-off's hash, or 64 zeros when there is none yet. */
+    newest_signoff_hash: Hex64;
+    /** The newest sign-off's place in the chain, 0 when there is none. */
+    sequence: number;
+}
+/** The approver key's part of a sign-off. */
+interface SignOffSignature {
+    /** The base64 Ed25519 public key of the approver. */
+    approver_key: string;
+    /** Base64 Ed25519 signature by the approver key. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per sign-off. */
+    nonce: string;
+}
+/** Options for {@link VerdifaxClient.signOff}. */
+interface SignOffOptions {
+    /** The approver's note. It is hashed on this machine and only its
+     *  SHA-256 is sent and signed: the text never reaches Verdifax. Keep the
+     *  text yourself to show it matches the hash. */
+    note?: string;
+    /** Use the owner key's routes, /account/signoffs/newest and
+     *  /account/signoffs, instead of a member key's. */
+    asOwner?: boolean;
+}
+/** For a method that serves both a member key's route and the owner
+ *  key's /account route. */
+interface AsOwnerOptions {
+    /** Use the owner key's /account route. */
+    asOwner?: boolean;
+}
+/** An approver key's public key and the proof that its holder has the
+ *  private key, from {@link approverKeyProof}. */
+interface ApproverKeyProof {
+    /** Base64 of the raw 32-byte public key. */
+    public_key: string;
+    /** Base64 Ed25519 signature over verdifax.approver-key.v1, a zero byte
+     *  and the base64 public key. */
+    proof: string;
+}
+/** An approver key registered to an account. A key is not an identity:
+ *  `name` is the label the owner gave it. */
+interface Approver {
+    id: number;
+    public_key: string;
+    name: string;
+    /** The account, `account-N`. */
+    account_id: string;
+    registered_at: string;
+    revoked: boolean;
+    revoked_at?: string;
+}
+/** Returned by {@link VerdifaxClient.registerApprover}. */
+interface ApproverRegistration extends Approver {
+    ok: boolean;
+}
+/** Returned by {@link VerdifaxClient.listApprovers}: revoked keys
+ *  included. */
+interface ApproverList {
+    ok: boolean;
+    account_id: string;
+    approvers: Approver[];
+}
+/** Returned by {@link VerdifaxClient.revokeApprover}. */
+interface ApproverRevocation {
+    ok: boolean;
+    id: number;
+    revoked: boolean;
+}
 
 /**
  * The job helper: runs the steps of one job and keeps the map of step ids
@@ -869,6 +995,13 @@ declare const MAX_BATCH_ROWS = 1000;
  * | `testAccountPolicy(req)` | POST /account/policies/test | owner key |
  * | `getAccountPolicyHistory()` | GET /account/policies/history | owner key |
  * | `activateAccountPolicy(documentHash)` | POST /account/policies/{document_hash}/activate | owner key |
+ * | `registerApprover(name, approver)` | POST /account/approvers | owner key |
+ * | `listApprovers()` | GET /account/approvers | owner key |
+ * | `revokeApprover(id)` | DELETE /account/approvers/{id} | owner key |
+ * | `signOff(target, decision, approverKey, options)` | POST /signoffs, or POST /account/signoffs with asOwner | required |
+ * | `getNewestSignOff(options)` | GET /signoffs/newest, or GET /account/signoffs/newest with asOwner | required |
+ * | `getSignOffs(runId, options)` | GET /runs/{id}/signoffs, or GET /account/runs/{id}/signoffs with asOwner | required |
+ * | `getSignOffHistory()` | GET /account/signoffs/history | owner key |
  * | `job(jobId)` | none, returns a {@link VerdifaxJob} | none |
  *
  * With the `signingKey` option set, every path to POST /execute carries
@@ -1037,6 +1170,56 @@ declare class VerdifaxClient {
      *  `account-N`. The server refuses an unsigned account change, so this
      *  needs the `signingKey` option and refuses to send without it. */
     activateAccountPolicy(documentHash: Hex64): Promise<PolicyActivation>;
+    /** 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. */
+    registerApprover(name: string, approver: Uint8Array | KeyObject | ApproverKeyProof): Promise<ApproverRegistration>;
+    /** The account's approver keys, revoked ones included. */
+    listApprovers(): Promise<ApproverList>;
+    /** 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}. */
+    revokeApprover(approverId: number): Promise<ApproverRevocation>;
+    /** 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. */
+    getNewestSignOff(options?: AsOwnerOptions): Promise<NewestSignOff>;
+    /** 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. */
+    signOff(target: SignOffTarget, decision: SignOffDecision, approverKey: Uint8Array | KeyObject, options?: SignOffOptions): Promise<SignOffRecord>;
+    /** 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. */
+    getSignOffs(runId: number, options?: AsOwnerOptions): Promise<SignOffRecord[]>;
+    /** The account's whole chain of sign-offs, oldest first, in the form
+     *  `verdifax-verify --signoff-history FILE` reads. Needs the owner key. */
+    getSignOffHistory(): Promise<SignOffRecord[]>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -1349,6 +1532,29 @@ declare function policyActivationApproval(signingKey: Uint8Array | KeyObject, fi
     signedAt?: string;
     nonce?: string;
 }): PolicyActivationSignature;
+/** The bytes an approver key signs for one sign-off, matching the
+ *  orchestrator's SignOffPreimage: the fields joined with single zero
+ *  bytes. `chain_id` and `previous_signoff_hash` come from GET
+ *  /signoffs/newest (or /account/signoffs/newest for the owner key), so a
+ *  signature cannot be moved to another account, another result or
+ *  another point in the chain. `target.job_id` is empty unless the target
+ *  is a job, and `note_hash` is empty when there is no note. */
+declare function signOffPreimage(fields: {
+    chain_id: string;
+    previous_signoff_hash: string;
+    target: SignOffTarget;
+    decision: SignOffDecision;
+    note_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** The approver key's base64 public key and its proof: its signature over
+ *  verdifax.approver-key.v1, a zero byte and the base64 public key, which
+ *  shows its holder has the private key. The approver can run this on
+ *  their own machine and give the result to the account's owner, who
+ *  registers it with {@link VerdifaxClient.registerApprover}, so the owner
+ *  never holds the approver's private key. */
+declare function approverKeyProof(approverKey: Uint8Array | KeyObject): ApproverKeyProof;
 
 /**
  * Input-validation helpers, mirrors the Python SDK's
@@ -1434,4 +1640,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type Account, type AccountInfo, type AccountKey, type AccountKeyList, type AccountKeyRevocation, type AccountRunsExport, type AdminAPIKey, type AdminCreateAccountOptions, type AdminCreateAccountResponse, type AdminCreateKeyOptions, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type CreateAccountKeyOptions, type CreatedAccountKey, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type KeyTier, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };
+export { APIError, APIKeyRequiredError, type Account, type AccountInfo, type AccountKey, type AccountKeyList, type AccountKeyRevocation, type AccountRunsExport, type AdminAPIKey, type AdminCreateAccountOptions, type AdminCreateAccountResponse, type AdminCreateKeyOptions, type AdminCreateKeyResponse, type AdminEraseRequest, type Approver, type ApproverKeyProof, type ApproverList, type ApproverRegistration, type ApproverRevocation, type AsOwnerOptions, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type CreateAccountKeyOptions, type CreatedAccountKey, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type KeyTier, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, type NewestSignOff, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignOffDecision, type SignOffOptions, type SignOffRecord, type SignOffSignature, type SignOffTarget, type SignOffTargetKind, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, approverKeyProof, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signOffPreimage, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   VerdifaxClient: () => VerdifaxClient,
   VerdifaxError: () => VerdifaxError,
   VerdifaxJob: () => VerdifaxJob,
+  approverKeyProof: () => approverKeyProof,
   captureEnvironment: () => captureEnvironment,
   cresReceiptHash: () => cresReceiptHash,
   dcaeClosureHash: () => dcaeClosureHash,
@@ -48,6 +49,7 @@ __export(index_exports, {
   requestKeyRegistrationBody: () => requestKeyRegistrationBody,
   requestSignaturePreimage: () => requestSignaturePreimage,
   requestSignaturePreimageV2: () => requestSignaturePreimageV2,
+  signOffPreimage: () => signOffPreimage,
   signRequest: () => signRequest,
   signRequestV2: () => signRequestV2,
   validateHex64: () => validateHex64,
@@ -389,7 +391,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"
@@ -573,6 +578,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 ?? (0, import_node_crypto.randomBytes)(16).toString("hex");
+  const preimage = signOffPreimage({ ...fields, signed_at, nonce });
+  return {
+    approver_key: rawPublicKey((0, import_node_crypto.createPublicKey)(key)).toString("base64"),
+    signature: (0, import_node_crypto.sign)(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
+}
+function approverKeyProof(approverKey) {
+  const key = loadSigningKey(approverKey);
+  const public_key = rawPublicKey((0, import_node_crypto.createPublicKey)(key)).toString("base64");
+  const proof = (0, import_node_crypto.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 = (0, import_node_crypto.createPublicKey)({
+    key: Buffer.concat([SPKI_ED25519_HEADER, raw]),
+    format: "der",
+    type: "spki"
+  });
+  return (0, import_node_crypto.verify)(
+    null,
+    Buffer.from(`${APPROVER_KEY_PROOF_FORM}\0${proof.public_key}`, "utf8"),
+    publicKey,
+    signature
+  );
+}
+function publicKeyOf(key) {
+  return rawPublicKey((0, import_node_crypto.createPublicKey)(key)).toString("base64");
+}
 
 // src/job.ts
 var STEP_OPTIONS = {
@@ -674,9 +744,10 @@ var VerdifaxJob = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.3.0";
+var SDK_VERSION = "1.4.0";
 
 // src/client.ts
+var import_node_crypto2 = require("crypto");
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
 var DEFAULT_TIMEOUT_MS = 9e4;
 var DEFAULT_MAX_RETRIES = 3;
@@ -689,6 +760,12 @@ var ACCOUNT_PATH = "/account";
 var ACCOUNT_REQUEST_KEY_PATH = "/account/request-key";
 var ACCOUNT_POLICIES_PATH = "/account/policies";
 var ACCOUNT_CHAIN_ID = /^account-[1-9][0-9]*$/;
+var SIGNOFFS_PATH = "/signoffs";
+var ACCOUNT_SIGNOFFS_PATH = "/account/signoffs";
+var APPROVERS_PATH = "/account/approvers";
+var SIGNOFF_TARGET_KINDS = /* @__PURE__ */ new Set(["record", "receipt", "job"]);
+var SIGNOFF_DECISIONS = /* @__PURE__ */ new Set(["approve", "reject"]);
+var MAX_APPROVER_NAME_BYTES = 200;
 var HEADER_EXPORT_TOTAL = "X-Verdifax-Total";
 var HEADER_EXPORT_TRUNCATED = "X-Verdifax-Truncated";
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
@@ -1195,6 +1272,174 @@ var VerdifaxClient = class {
     }
     return this.activatePolicyAt(ACCOUNT_POLICIES_PATH, documentHash, chain);
   }
+  // ── Sign-off ─────────────────────────────────────────────────
+  //
+  // An account's owner registers approver keys. An approver signs a
+  // decision, approve or reject, on one exact result on their own machine,
+  // and any key in the account, or the owner key with asOwner, submits it.
+  // A sign-off shows that the holder of a registered approver key signed
+  // that decision on that exact result and that Verdifax logged it on the
+  // public log. It does not show the review was careful, the result right,
+  // or who the person is, and it gates nothing on its own.
+  /** Registers an approver key to the owner's account. `approver` is the
+   *  approver's signing key, from which the proof is made on this machine,
+   *  or the `{ public_key, proof }` that {@link approverKeyProof} made on
+   *  the approver's own machine, so the owner need not hold the private
+   *  key. A proof that does not verify is refused before sending. The
+   *  server refuses a key that is a request key in the same account.
+   *  `name` is a label, not an identity. */
+  async registerApprover(name, approver) {
+    this.requireAPIKey();
+    if (typeof name !== "string" || name.trim() === "" || Buffer.byteLength(name.trim(), "utf8") > MAX_APPROVER_NAME_BYTES) {
+      throw new VerdifaxError(
+        "verdifax: registerApprover needs a name of at most 200 bytes"
+      );
+    }
+    const body = approver instanceof Uint8Array || approver instanceof import_node_crypto2.KeyObject ? 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();
@@ -1648,6 +1893,52 @@ 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`);
@@ -1778,13 +2069,13 @@ var RUN_STATUSES = [
 ];
 
 // src/section0.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var DSE_FORMULA_VERSION = "dse.tcu.dispatch.v1";
 var DCAE_PREIMAGE_VERSION = "verdifax.dcae.v1";
 var CRES_PREIMAGE_VERSION = "verdifax.cres.v1";
 var CRES_ENGINE_VERSION = "verdifax-cres/1.0.0";
 function sha256Hex2(preimage) {
-  return (0, import_node_crypto2.createHash)("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
+  return (0, import_node_crypto3.createHash)("sha256").update(Buffer.from(preimage, "utf8")).digest("hex");
 }
 function requireHex64(value, name) {
   try {
@@ -1854,6 +2145,7 @@ function cresReceiptHash(fields) {
   VerdifaxClient,
   VerdifaxError,
   VerdifaxJob,
+  approverKeyProof,
   captureEnvironment,
   cresReceiptHash,
   dcaeClosureHash,
@@ -1868,6 +2160,7 @@ function cresReceiptHash(fields) {
   requestKeyRegistrationBody,
   requestSignaturePreimage,
   requestSignaturePreimageV2,
+  signOffPreimage,
   signRequest,
   signRequestV2,
   validateHex64,

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.3.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;
@@ -639,6 +709,12 @@ var ACCOUNT_PATH = "/account";
 var ACCOUNT_REQUEST_KEY_PATH = "/account/request-key";
 var ACCOUNT_POLICIES_PATH = "/account/policies";
 var ACCOUNT_CHAIN_ID = /^account-[1-9][0-9]*$/;
+var SIGNOFFS_PATH = "/signoffs";
+var ACCOUNT_SIGNOFFS_PATH = "/account/signoffs";
+var APPROVERS_PATH = "/account/approvers";
+var SIGNOFF_TARGET_KINDS = /* @__PURE__ */ new Set(["record", "receipt", "job"]);
+var SIGNOFF_DECISIONS = /* @__PURE__ */ new Set(["approve", "reject"]);
+var MAX_APPROVER_NAME_BYTES = 200;
 var HEADER_EXPORT_TOTAL = "X-Verdifax-Total";
 var HEADER_EXPORT_TRUNCATED = "X-Verdifax-Truncated";
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
@@ -1145,6 +1221,174 @@ var VerdifaxClient = class {
     }
     return this.activatePolicyAt(ACCOUNT_POLICIES_PATH, documentHash, chain);
   }
+  // ── Sign-off ─────────────────────────────────────────────────
+  //
+  // An account's owner registers approver keys. An approver signs a
+  // decision, approve or reject, on one exact result on their own machine,
+  // and any key in the account, or the owner key with asOwner, submits it.
+  // A sign-off shows that the holder of a registered approver key signed
+  // that decision on that exact result and that Verdifax logged it on the
+  // public log. It does not show the review was careful, the result right,
+  // or who the person is, and it gates nothing on its own.
+  /** Registers an approver key to the owner's account. `approver` is the
+   *  approver's signing key, from which the proof is made on this machine,
+   *  or the `{ public_key, proof }` that {@link approverKeyProof} made on
+   *  the approver's own machine, so the owner need not hold the private
+   *  key. A proof that does not verify is refused before sending. The
+   *  server refuses a key that is a request key in the same account.
+   *  `name` is a label, not an identity. */
+  async registerApprover(name, approver) {
+    this.requireAPIKey();
+    if (typeof name !== "string" || name.trim() === "" || Buffer.byteLength(name.trim(), "utf8") > MAX_APPROVER_NAME_BYTES) {
+      throw new VerdifaxError(
+        "verdifax: registerApprover needs a name of at most 200 bytes"
+      );
+    }
+    const body = approver instanceof Uint8Array || approver instanceof KeyObject2 ? approverKeyProof(approver) : { public_key: approver?.public_key, proof: approver?.proof };
+    if (!approverKeyProofVerifies(body)) {
+      throw new VerdifaxError(
+        "verdifax: registerApprover needs the approver's signing key, or a public_key and proof from approverKeyProof that verify"
+      );
+    }
+    if (this.signingKey && publicKeyOf(this.signingKey) === body.public_key) {
+      throw new VerdifaxError(
+        "verdifax: an approver key must not be a request key in the same account, and this is the client's signingKey"
+      );
+    }
+    return this.request("POST", APPROVERS_PATH, {
+      public_key: body.public_key,
+      name,
+      proof: body.proof
+    });
+  }
+  /** The account's approver keys, revoked ones included. */
+  async listApprovers() {
+    this.requireAPIKey();
+    const out = await this.request("GET", APPROVERS_PATH);
+    return { ...out, approvers: out?.approvers ?? [] };
+  }
+  /** Revokes one of the account's approver keys. Its earlier sign-offs
+   *  stay on the record. A key that is not an active approver in the
+   *  account throws {@link NotFoundError}. */
+  async revokeApprover(approverId) {
+    this.requireAPIKey();
+    requirePositiveId(approverId, "approverId");
+    return this.request(
+      "DELETE",
+      `${APPROVERS_PATH}/${approverId}`
+    );
+  }
+  /** What an approver signs against: the account's chain `account-N` and
+   *  its newest sign-off (64 zeros when there is none yet). With
+   *  `asOwner` it reads the owner key's route. */
+  async getNewestSignOff(options = {}) {
+    this.requireAPIKey();
+    return this.request(
+      "GET",
+      `${signOffsBase(options, "getNewestSignOff")}/newest`
+    );
+  }
+  /** Signs an approver's decision, approve or reject, on one exact result
+   *  and submits it. It first reads {@link getNewestSignOff} for the
+   *  account's chain and its newest sign-off, then signs over them with
+   *  `approverKey` on this machine. The approver's private key is never
+   *  sent.
+   *
+   *  `target.digest` is what the result's public-log entry covers: for a
+   *  record, the `bundle_anchor.anchored_digest` of the bundle
+   *  {@link getRunArtifacts} returns; for a receipt, its hash; for a job,
+   *  the final step's record digest, read as a record's, with `job_id`.
+   *
+   *  `note` is hashed here and only its SHA-256 is sent and signed: the
+   *  text never reaches Verdifax. With `asOwner` it uses the owner key's
+   *  routes. Bad input is refused before anything is sent.
+   *
+   *  The record the server returns must carry the signature,
+   *  approver_key, decision, previous_signoff_hash and target that were
+   *  sent, or this throws {@link VerdifaxError}.
+   *
+   *  A later sign-off on the same result supersedes this one, and neither
+   *  is deleted. An HTTP 409 means the chain moved or the target is not
+   *  this account's result: it throws the usual {@link APIError} and is
+   *  not retried. */
+  async signOff(target, decision, approverKey, options = {}) {
+    this.requireAPIKey();
+    const base = signOffsBase(options, "signOff");
+    const exact = signOffTargetOf(target);
+    if (!SIGNOFF_DECISIONS.has(decision)) {
+      throw new VerdifaxError(
+        "verdifax: signOff decision must be approve or reject"
+      );
+    }
+    const note = options?.note;
+    if (note !== void 0 && (typeof note !== "string" || note === "")) {
+      throw new VerdifaxError(
+        "verdifax: signOff note must be non-empty text when given"
+      );
+    }
+    const key = loadSigningKey(approverKey);
+    const note_hash = note === void 0 ? "" : sha256Hex(note);
+    const newest = await this.getNewestSignOff(options);
+    if (typeof newest?.chain_id !== "string" || !ACCOUNT_CHAIN_ID.test(newest.chain_id)) {
+      throw new VerdifaxError(
+        "verdifax: the server did not report an account chain_id (account-N), so the sign-off cannot be signed"
+      );
+    }
+    const previous = newest.newest_signoff_hash;
+    if (typeof previous !== "string" || !/^[0-9a-f]{64}$/.test(previous)) {
+      throw new VerdifaxError(
+        "verdifax: the server did not report newest_signoff_hash, so the sign-off cannot name the one it follows"
+      );
+    }
+    const signed = signOffSignature(key, {
+      chain_id: newest.chain_id,
+      previous_signoff_hash: previous,
+      target: exact,
+      decision,
+      note_hash
+    });
+    const body = {
+      previous_signoff_hash: previous,
+      target: exact,
+      decision,
+      ...note_hash ? { note_hash } : {},
+      ...signed
+    };
+    const out = await this.request(
+      "POST",
+      base,
+      body
+    );
+    const record = out?.signoff;
+    if (!recordMatchesSent(record, exact, decision, previous, signed)) {
+      throw new VerdifaxError(
+        "verdifax: the sign-off the server returned does not carry the signature, approver_key, decision, previous_signoff_hash and target that were sent"
+      );
+    }
+    return record;
+  }
+  /** The sign-offs on one run, oldest first, in the form
+   *  `verdifax-verify --signoff FILE` reads: for a member key, a run it
+   *  made; with `asOwner`, any run of the account. The latest is the
+   *  decision in force. */
+  async getSignOffs(runId, options = {}) {
+    this.requireAPIKey();
+    requirePositiveId(runId, "runId");
+    const base = asOwnerOf(options, "getSignOffs") ? `${ACCOUNT_PATH}/runs` : "/runs";
+    return await this.request(
+      "GET",
+      `${base}/${runId}/signoffs`
+    ) ?? [];
+  }
+  /** The account's whole chain of sign-offs, oldest first, in the form
+   *  `verdifax-verify --signoff-history FILE` reads. Needs the owner key. */
+  async getSignOffHistory() {
+    this.requireAPIKey();
+    return await this.request(
+      "GET",
+      `${ACCOUNT_SIGNOFFS_PATH}/history`
+    ) ?? [];
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -1598,6 +1842,52 @@ 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`);
@@ -1803,6 +2093,7 @@ export {
   VerdifaxClient,
   VerdifaxError,
   VerdifaxJob,
+  approverKeyProof,
   captureEnvironment,
   cresReceiptHash,
   dcaeClosureHash,
@@ -1817,6 +2108,7 @@ export {
   requestKeyRegistrationBody,
   requestSignaturePreimage,
   requestSignaturePreimageV2,
+  signOffPreimage,
   signRequest,
   signRequestV2,
   validateHex64,

package/package.json

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