verdifax 0.2.11 → 0.3.0

package/README.md

@@ -52,6 +52,8 @@ if (v.verified) {
 | `client.execute(req)` | `POST /execute` | required |
 | `client.getRun(id)` | `GET /runs/{id}` | required |
 | `client.verifyRun(id)` | `GET /runs/{id}/verify` | required |
+| `client.registerRequestKey()` | `POST /keys/request-key` | required |
+| `client.clearRequestKey()` | `DELETE /keys/request-key` | required |
 
 The full HTTP surface (every endpoint, deletion-receipt list,
 DCAE verify, admin endpoints) is documented in the
@@ -96,6 +98,40 @@ try {
 }
 ```
 
+## Request signing
+
+Request signing is optional. A client with no signing key sends the same requests as before.
+
+You can register an Ed25519 public key on your API key, so that each run must also be signed with a private key that only you hold. The key pair is created on your machine, and Verdifax receives only the public key.
+
+```typescript
+import { VerdifaxClient, generateRequestKeyPair } from "verdifax";
+
+// Run once, then store privateKey as a secret.
+const { privateKey } = generateRequestKeyPair();
+
+const client = new VerdifaxClient({
+  apiKey: process.env.VERDIFAX_API_KEY!,
+  signingKey: privateKey, // the 32 raw bytes, as a Buffer or Uint8Array
+});
+
+await client.registerRequestKey(); // sends the public key with its proof
+
+// execute, attest, attestClaudeResponse and attestOpenAIResponse now sign.
+await client.execute({
+  program_id: "1111111111111111111111111111111111111111111111111111111111111111",
+  route_id: "demo-attestation",
+  registry_record_hash: "2222222222222222222222222222222222222222222222222222222222222222",
+  payload_text: "first signed attestation",
+});
+
+await client.clearRequestKey(); // stops requiring signatures on this API key
+```
+
+Registering a key changes that API key for every client that uses it: the server then refuses a run without a valid signature, so every caller on the key needs the private key. Each request carries the time and a fresh random nonce. The server refuses a repeated nonce and a time more than five minutes from its own clock.
+
+The signature shows the holder of the key requested the run. It does not show the key holder accepted the outcome.
+
 ## Trust model
 
 This SDK only mediates HTTP I/O, it does NOT verify sealed

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { KeyObject } from 'node:crypto';
+
 /**
  * Type definitions for the Verdifax orchestrator REST API.
  *
@@ -48,6 +50,37 @@ interface ExecuteRequest {
     ai_output_text?: string;
     /** Caller-attested actor + decision metadata; open schema. */
     attested_context?: Record<string, unknown>;
+    /** Filled in by the client when the `signingKey` option is set. */
+    request_signature?: RequestSignature;
+}
+/** The signature an API key with a registered request key must carry.
+ *  The public key comes from the registration, never from the request. */
+interface RequestSignature {
+    /** Base64 Ed25519 signature. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds, for example 2026-11-05T02:18:00Z. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per request. */
+    nonce: string;
+}
+/** A key pair from {@link generateRequestKeyPair}, as raw bytes. */
+interface RequestKeyPair {
+    /** The 32-byte Ed25519 public key. */
+    publicKey: Buffer;
+    /** The 32-byte Ed25519 private key. Keep it secret. */
+    privateKey: Buffer;
+}
+/** Body of POST /keys/request-key. */
+interface RequestKeyRegistrationBody {
+    /** Base64 of the raw 32-byte public key. */
+    public_key: string;
+    /** Base64 signature proving the caller holds the private key. */
+    proof: string;
+}
+/** Returned by {@link VerdifaxClient.registerRequestKey}. */
+interface RequestKeyRegistration {
+    ok: boolean;
+    public_key: string;
 }
 interface ExecuteResponse {
     ok: boolean;
@@ -132,6 +165,10 @@ interface ClientConfig {
      *  it on each subsequent retry (exponential backoff with full
      *  jitter). Defaults to 200ms. */
     retryBaseDelayMs?: number;
+    /** The 32 raw bytes of an Ed25519 private key. When set, every path to
+     *  POST /execute signs its request. The key is never sent to the
+     *  server. Leave unset for unsigned requests. */
+    signingKey?: Uint8Array;
 }
 /** Friendly shape for {@link VerdifaxClient.attest}. Mirrors the
  *  Python SDK's `attest()` signature so polyglot teams have parity. */
@@ -258,6 +295,11 @@ interface AdminAPIKey {
  * | `adminRevokeKey(id)` | DELETE /admin/keys/{id} | required |
  * | `attestClaudeResponse(...)` | POST /execute (helper) | required |
  * | `attestOpenAIResponse(...)` | POST /execute (helper) | required |
+ * | `registerRequestKey()` | POST /keys/request-key | required |
+ * | `clearRequestKey()` | DELETE /keys/request-key | required |
+ *
+ * With the `signingKey` option set, every path to POST /execute carries
+ * a fresh request signature. Without it, requests are unsigned.
  *
  * Idempotent GETs that hit a transient failure (502/503/504/429)
  * are retried with exponential backoff + full jitter. Non-
@@ -271,6 +313,7 @@ declare class VerdifaxClient {
     private readonly userAgent;
     private readonly maxRetries;
     private readonly retryBaseDelayMs;
+    private readonly signingKey;
     constructor(config?: ClientConfig);
     health(): Promise<Health>;
     version(): Promise<VerdifaxVersion>;
@@ -280,6 +323,13 @@ declare class VerdifaxClient {
      *  string (for plain text). Validates the hex fields and
      *  routes the call through to the canonical /execute. */
     attest(req: AttestRequest): Promise<ExecuteResponse>;
+    /** 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
+     *  refuses a run on this API key without a request signature. */
+    registerRequestKey(): Promise<RequestKeyRegistration>;
+    /** Clears the registered public key, so the server stops requiring
+     *  request signatures on this API key. */
+    clearRequestKey(): Promise<void>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -339,6 +389,43 @@ declare class VerdifaxClient {
 
 declare function fromEnv(): VerdifaxClient;
 
+/**
+ * Optional customer request signing.
+ *
+ * A customer can register an Ed25519 public key on an API key. From then
+ * on the orchestrator accepts a run only with a signature by the matching
+ * private key. The private key stays with the customer: it is never sent
+ * to the server, logged, or placed in an error message.
+ */
+
+/** Creates a new Ed25519 key pair on this machine, as raw bytes: a
+ *  32-byte public key and a 32-byte private key. Nothing is sent to
+ *  the server. Store the private key as a secret. */
+declare function generateRequestKeyPair(): RequestKeyPair;
+/** The bytes a request signature signs: the fields joined with single
+ *  zero bytes, matching the orchestrator's RequestSignaturePreimage. */
+declare function requestSignaturePreimage(fields: {
+    payload_hash: string;
+    program_id: string;
+    route_id: string;
+    registry_record_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** Signs one execute request. The server hashes payload_text when it is
+ *  non-empty, otherwise the payload string exactly as sent (it does not
+ *  base64-decode it), so this does the same.
+ *
+ *  `signedAt` and `nonce` default to the current time and fresh random
+ *  bytes. A nonce the server has already seen is refused. */
+declare function signRequest(signingKey: Uint8Array | KeyObject, req: ExecuteRequest, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): RequestSignature;
+/** The body of POST /keys/request-key: the base64 public key and a
+ *  signature proving the caller holds its private key. */
+declare function requestKeyRegistrationBody(signingKey: Uint8Array | KeyObject): RequestKeyRegistrationBody;
+
 /**
  * Input-validation helpers, mirrors the Python SDK's
  * `_validation.py` and the Go SDK's `validation.go` for
@@ -411,4 +498,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, fromEnv, validateHex64, validateRouteId };
+export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, fromEnv, generateRequestKeyPair, requestKeyRegistrationBody, requestSignaturePreimage, signRequest, validateHex64, validateRouteId };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { KeyObject } from 'node:crypto';
+
 /**
  * Type definitions for the Verdifax orchestrator REST API.
  *
@@ -48,6 +50,37 @@ interface ExecuteRequest {
     ai_output_text?: string;
     /** Caller-attested actor + decision metadata; open schema. */
     attested_context?: Record<string, unknown>;
+    /** Filled in by the client when the `signingKey` option is set. */
+    request_signature?: RequestSignature;
+}
+/** The signature an API key with a registered request key must carry.
+ *  The public key comes from the registration, never from the request. */
+interface RequestSignature {
+    /** Base64 Ed25519 signature. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds, for example 2026-11-05T02:18:00Z. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per request. */
+    nonce: string;
+}
+/** A key pair from {@link generateRequestKeyPair}, as raw bytes. */
+interface RequestKeyPair {
+    /** The 32-byte Ed25519 public key. */
+    publicKey: Buffer;
+    /** The 32-byte Ed25519 private key. Keep it secret. */
+    privateKey: Buffer;
+}
+/** Body of POST /keys/request-key. */
+interface RequestKeyRegistrationBody {
+    /** Base64 of the raw 32-byte public key. */
+    public_key: string;
+    /** Base64 signature proving the caller holds the private key. */
+    proof: string;
+}
+/** Returned by {@link VerdifaxClient.registerRequestKey}. */
+interface RequestKeyRegistration {
+    ok: boolean;
+    public_key: string;
 }
 interface ExecuteResponse {
     ok: boolean;
@@ -132,6 +165,10 @@ interface ClientConfig {
      *  it on each subsequent retry (exponential backoff with full
      *  jitter). Defaults to 200ms. */
     retryBaseDelayMs?: number;
+    /** The 32 raw bytes of an Ed25519 private key. When set, every path to
+     *  POST /execute signs its request. The key is never sent to the
+     *  server. Leave unset for unsigned requests. */
+    signingKey?: Uint8Array;
 }
 /** Friendly shape for {@link VerdifaxClient.attest}. Mirrors the
  *  Python SDK's `attest()` signature so polyglot teams have parity. */
@@ -258,6 +295,11 @@ interface AdminAPIKey {
  * | `adminRevokeKey(id)` | DELETE /admin/keys/{id} | required |
  * | `attestClaudeResponse(...)` | POST /execute (helper) | required |
  * | `attestOpenAIResponse(...)` | POST /execute (helper) | required |
+ * | `registerRequestKey()` | POST /keys/request-key | required |
+ * | `clearRequestKey()` | DELETE /keys/request-key | required |
+ *
+ * With the `signingKey` option set, every path to POST /execute carries
+ * a fresh request signature. Without it, requests are unsigned.
  *
  * Idempotent GETs that hit a transient failure (502/503/504/429)
  * are retried with exponential backoff + full jitter. Non-
@@ -271,6 +313,7 @@ declare class VerdifaxClient {
     private readonly userAgent;
     private readonly maxRetries;
     private readonly retryBaseDelayMs;
+    private readonly signingKey;
     constructor(config?: ClientConfig);
     health(): Promise<Health>;
     version(): Promise<VerdifaxVersion>;
@@ -280,6 +323,13 @@ declare class VerdifaxClient {
      *  string (for plain text). Validates the hex fields and
      *  routes the call through to the canonical /execute. */
     attest(req: AttestRequest): Promise<ExecuteResponse>;
+    /** 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
+     *  refuses a run on this API key without a request signature. */
+    registerRequestKey(): Promise<RequestKeyRegistration>;
+    /** Clears the registered public key, so the server stops requiring
+     *  request signatures on this API key. */
+    clearRequestKey(): Promise<void>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -339,6 +389,43 @@ declare class VerdifaxClient {
 
 declare function fromEnv(): VerdifaxClient;
 
+/**
+ * Optional customer request signing.
+ *
+ * A customer can register an Ed25519 public key on an API key. From then
+ * on the orchestrator accepts a run only with a signature by the matching
+ * private key. The private key stays with the customer: it is never sent
+ * to the server, logged, or placed in an error message.
+ */
+
+/** Creates a new Ed25519 key pair on this machine, as raw bytes: a
+ *  32-byte public key and a 32-byte private key. Nothing is sent to
+ *  the server. Store the private key as a secret. */
+declare function generateRequestKeyPair(): RequestKeyPair;
+/** The bytes a request signature signs: the fields joined with single
+ *  zero bytes, matching the orchestrator's RequestSignaturePreimage. */
+declare function requestSignaturePreimage(fields: {
+    payload_hash: string;
+    program_id: string;
+    route_id: string;
+    registry_record_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** Signs one execute request. The server hashes payload_text when it is
+ *  non-empty, otherwise the payload string exactly as sent (it does not
+ *  base64-decode it), so this does the same.
+ *
+ *  `signedAt` and `nonce` default to the current time and fresh random
+ *  bytes. A nonce the server has already seen is refused. */
+declare function signRequest(signingKey: Uint8Array | KeyObject, req: ExecuteRequest, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): RequestSignature;
+/** The body of POST /keys/request-key: the base64 public key and a
+ *  signature proving the caller holds its private key. */
+declare function requestKeyRegistrationBody(signingKey: Uint8Array | KeyObject): RequestKeyRegistrationBody;
+
 /**
  * Input-validation helpers, mirrors the Python SDK's
  * `_validation.py` and the Go SDK's `validation.go` for
@@ -411,4 +498,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, fromEnv, validateHex64, validateRouteId };
+export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, fromEnv, generateRequestKeyPair, requestKeyRegistrationBody, requestSignaturePreimage, signRequest, validateHex64, validateRouteId };

package/dist/index.js

@@ -27,6 +27,10 @@ __export(index_exports, {
   VerdifaxClient: () => VerdifaxClient,
   VerdifaxError: () => VerdifaxError,
   fromEnv: () => fromEnv,
+  generateRequestKeyPair: () => generateRequestKeyPair,
+  requestKeyRegistrationBody: () => requestKeyRegistrationBody,
+  requestSignaturePreimage: () => requestSignaturePreimage,
+  signRequest: () => signRequest,
   validateHex64: () => validateHex64,
   validateRouteId: () => validateRouteId
 });
@@ -75,6 +79,84 @@ var APIKeyRequiredError = class extends VerdifaxError {
   }
 };
 
+// src/signing.ts
+var import_node_crypto = require("crypto");
+var REQUEST_SIGNATURE_FORM = "verdifax.request.v1";
+var REQUEST_KEY_PROOF_FORM = "verdifax.request-key.v1";
+var SIGNING_KEY_BYTES = 32;
+var PKCS8_ED25519_HEADER = Buffer.from(
+  "302e020100300506032b657004220420",
+  "hex"
+);
+function rawPublicKey(key) {
+  return Buffer.from(key.export({ format: "der", type: "spki" }).subarray(-32));
+}
+function generateRequestKeyPair() {
+  const { publicKey, privateKey } = (0, import_node_crypto.generateKeyPairSync)("ed25519");
+  return {
+    publicKey: rawPublicKey(publicKey),
+    privateKey: Buffer.from(
+      privateKey.export({ format: "der", type: "pkcs8" }).subarray(-32)
+    )
+  };
+}
+function loadSigningKey(key) {
+  if (key instanceof import_node_crypto.KeyObject) return key;
+  if (!(key instanceof Uint8Array) || key.length !== SIGNING_KEY_BYTES) {
+    throw new VerdifaxError(
+      "verdifax: signingKey must be the 32 raw bytes of an Ed25519 private key"
+    );
+  }
+  return (0, import_node_crypto.createPrivateKey)({
+    key: Buffer.concat([PKCS8_ED25519_HEADER, key]),
+    format: "der",
+    type: "pkcs8"
+  });
+}
+function requestSignaturePreimage(fields) {
+  return Buffer.from(
+    [
+      REQUEST_SIGNATURE_FORM,
+      fields.payload_hash,
+      fields.program_id,
+      fields.route_id,
+      fields.registry_record_hash,
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
+  );
+}
+function signRequest(signingKey, req, options = {}) {
+  const key = loadSigningKey(signingKey);
+  const signed_at = options.signedAt ?? (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  const nonce = options.nonce ?? (0, import_node_crypto.randomBytes)(16).toString("hex");
+  const payload_hash = (0, import_node_crypto.createHash)("sha256").update(Buffer.from(req.payload_text || req.payload || "", "utf8")).digest("hex");
+  const preimage = requestSignaturePreimage({
+    payload_hash,
+    program_id: req.program_id,
+    route_id: req.route_id,
+    registry_record_hash: req.registry_record_hash,
+    signed_at,
+    nonce
+  });
+  return {
+    signature: (0, import_node_crypto.sign)(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
+}
+function requestKeyRegistrationBody(signingKey) {
+  const key = loadSigningKey(signingKey);
+  const public_key = rawPublicKey((0, import_node_crypto.createPublicKey)(key)).toString("base64");
+  const proof = (0, import_node_crypto.sign)(
+    null,
+    Buffer.from(`${REQUEST_KEY_PROOF_FORM}\0${public_key}`, "utf8"),
+    key
+  ).toString("base64");
+  return { public_key, proof };
+}
+
 // src/validation.ts
 function validateHex64(value, fieldName) {
   if (typeof value !== "string" || value.length !== 64) {
@@ -105,7 +187,7 @@ function validateRouteId(value) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.2.11";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
@@ -114,6 +196,7 @@ var DEFAULT_MAX_RETRIES = 3;
 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 RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var VerdifaxClient = class {
   baseURL;
@@ -122,6 +205,7 @@ var VerdifaxClient = class {
   userAgent;
   maxRetries;
   retryBaseDelayMs;
+  signingKey;
   constructor(config = {}) {
     this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.apiKey = config.apiKey ?? "";
@@ -129,6 +213,7 @@ var VerdifaxClient = class {
     this.userAgent = config.userAgent ?? SDK_USER_AGENT;
     this.maxRetries = config.maxRetries === void 0 ? DEFAULT_MAX_RETRIES : Math.max(0, config.maxRetries);
     this.retryBaseDelayMs = config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+    this.signingKey = config.signingKey === void 0 ? void 0 : loadSigningKey(config.signingKey);
   }
   // ── Health + Version (anonymous) ──────────────────────────────
   async health() {
@@ -150,7 +235,8 @@ var VerdifaxClient = class {
         "verdifax: program_id, route_id, and registry_record_hash are required"
       );
     }
-    return this.request("POST", "/execute", req);
+    const body = this.signingKey ? { ...req, request_signature: signRequest(this.signingKey, req) } : req;
+    return this.request("POST", "/execute", body);
   }
   /** High-level convenience wrapper around `execute()`. Accepts
    *  either a Buffer (for binary payloads, auto-base64) or a
@@ -185,6 +271,29 @@ var VerdifaxClient = class {
     }
     return this.execute(body);
   }
+  // ── 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
+   *  refuses a run on this API key without a request signature. */
+  async registerRequestKey() {
+    this.requireAPIKey();
+    if (!this.signingKey) {
+      throw new VerdifaxError(
+        "verdifax: registerRequestKey needs the signingKey client option"
+      );
+    }
+    return this.request(
+      "POST",
+      REQUEST_KEY_PATH,
+      requestKeyRegistrationBody(this.signingKey)
+    );
+  }
+  /** Clears the registered public key, so the server stops requiring
+   *  request signatures on this API key. */
+  async clearRequestKey() {
+    this.requireAPIKey();
+    await this.request("DELETE", REQUEST_KEY_PATH);
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -459,6 +568,10 @@ function fromEnv() {
   VerdifaxClient,
   VerdifaxError,
   fromEnv,
+  generateRequestKeyPair,
+  requestKeyRegistrationBody,
+  requestSignaturePreimage,
+  signRequest,
   validateHex64,
   validateRouteId
 });

package/dist/index.mjs

@@ -41,6 +41,92 @@ var APIKeyRequiredError = class extends VerdifaxError {
   }
 };
 
+// src/signing.ts
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  KeyObject,
+  randomBytes,
+  sign
+} from "crypto";
+var REQUEST_SIGNATURE_FORM = "verdifax.request.v1";
+var REQUEST_KEY_PROOF_FORM = "verdifax.request-key.v1";
+var SIGNING_KEY_BYTES = 32;
+var PKCS8_ED25519_HEADER = Buffer.from(
+  "302e020100300506032b657004220420",
+  "hex"
+);
+function rawPublicKey(key) {
+  return Buffer.from(key.export({ format: "der", type: "spki" }).subarray(-32));
+}
+function generateRequestKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  return {
+    publicKey: rawPublicKey(publicKey),
+    privateKey: Buffer.from(
+      privateKey.export({ format: "der", type: "pkcs8" }).subarray(-32)
+    )
+  };
+}
+function loadSigningKey(key) {
+  if (key instanceof KeyObject) return key;
+  if (!(key instanceof Uint8Array) || key.length !== SIGNING_KEY_BYTES) {
+    throw new VerdifaxError(
+      "verdifax: signingKey must be the 32 raw bytes of an Ed25519 private key"
+    );
+  }
+  return createPrivateKey({
+    key: Buffer.concat([PKCS8_ED25519_HEADER, key]),
+    format: "der",
+    type: "pkcs8"
+  });
+}
+function requestSignaturePreimage(fields) {
+  return Buffer.from(
+    [
+      REQUEST_SIGNATURE_FORM,
+      fields.payload_hash,
+      fields.program_id,
+      fields.route_id,
+      fields.registry_record_hash,
+      fields.signed_at,
+      fields.nonce
+    ].join("\0"),
+    "utf8"
+  );
+}
+function signRequest(signingKey, req, options = {}) {
+  const key = loadSigningKey(signingKey);
+  const signed_at = options.signedAt ?? (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  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,
+    program_id: req.program_id,
+    route_id: req.route_id,
+    registry_record_hash: req.registry_record_hash,
+    signed_at,
+    nonce
+  });
+  return {
+    signature: sign(null, preimage, key).toString("base64"),
+    signed_at,
+    nonce
+  };
+}
+function requestKeyRegistrationBody(signingKey) {
+  const key = loadSigningKey(signingKey);
+  const public_key = rawPublicKey(createPublicKey(key)).toString("base64");
+  const proof = sign(
+    null,
+    Buffer.from(`${REQUEST_KEY_PROOF_FORM}\0${public_key}`, "utf8"),
+    key
+  ).toString("base64");
+  return { public_key, proof };
+}
+
 // src/validation.ts
 function validateHex64(value, fieldName) {
   if (typeof value !== "string" || value.length !== 64) {
@@ -71,7 +157,7 @@ function validateRouteId(value) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.2.11";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.verdifax.com";
@@ -80,6 +166,7 @@ var DEFAULT_MAX_RETRIES = 3;
 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 RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var VerdifaxClient = class {
   baseURL;
@@ -88,6 +175,7 @@ var VerdifaxClient = class {
   userAgent;
   maxRetries;
   retryBaseDelayMs;
+  signingKey;
   constructor(config = {}) {
     this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.apiKey = config.apiKey ?? "";
@@ -95,6 +183,7 @@ var VerdifaxClient = class {
     this.userAgent = config.userAgent ?? SDK_USER_AGENT;
     this.maxRetries = config.maxRetries === void 0 ? DEFAULT_MAX_RETRIES : Math.max(0, config.maxRetries);
     this.retryBaseDelayMs = config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+    this.signingKey = config.signingKey === void 0 ? void 0 : loadSigningKey(config.signingKey);
   }
   // ── Health + Version (anonymous) ──────────────────────────────
   async health() {
@@ -116,7 +205,8 @@ var VerdifaxClient = class {
         "verdifax: program_id, route_id, and registry_record_hash are required"
       );
     }
-    return this.request("POST", "/execute", req);
+    const body = this.signingKey ? { ...req, request_signature: signRequest(this.signingKey, req) } : req;
+    return this.request("POST", "/execute", body);
   }
   /** High-level convenience wrapper around `execute()`. Accepts
    *  either a Buffer (for binary payloads, auto-base64) or a
@@ -151,6 +241,29 @@ var VerdifaxClient = class {
     }
     return this.execute(body);
   }
+  // ── 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
+   *  refuses a run on this API key without a request signature. */
+  async registerRequestKey() {
+    this.requireAPIKey();
+    if (!this.signingKey) {
+      throw new VerdifaxError(
+        "verdifax: registerRequestKey needs the signingKey client option"
+      );
+    }
+    return this.request(
+      "POST",
+      REQUEST_KEY_PATH,
+      requestKeyRegistrationBody(this.signingKey)
+    );
+  }
+  /** Clears the registered public key, so the server stops requiring
+   *  request signatures on this API key. */
+  async clearRequestKey() {
+    this.requireAPIKey();
+    await this.request("DELETE", REQUEST_KEY_PATH);
+  }
   // ── Runs ──────────────────────────────────────────────────────
   async getRun(runId) {
     this.requireAPIKey();
@@ -424,6 +537,10 @@ export {
   VerdifaxClient,
   VerdifaxError,
   fromEnv,
+  generateRequestKeyPair,
+  requestKeyRegistrationBody,
+  requestSignaturePreimage,
+  signRequest,
   validateHex64,
   validateRouteId
 };

package/package.json

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