@haven_ai/signer 0.0.0-dev.202609250737.3bd5a51 → 0.0.0-dev.202609251409.98ed67a

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk/edge';
+import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth, HavenClientUpdate } from '@haven_ai/sdk/edge';
 export { deriveDelegateAccountAddress } from '@haven_ai/sdk/edge';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z as z$1 } from 'zod/v3';
@@ -725,8 +725,10 @@ interface ToolFailure {
      * the direct `/payments/:id/sign-context` fetch since #3271.
      */
     http_status?: number;
-    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`). */
+    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`, and since #3303 `client_outdated`). */
     backend_error_code?: string;
+    /** #3303: on `client_outdated`, the backend's update hint — `upgrade_command` is what updates this signer. */
+    client_update?: HavenClientUpdate;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 interface ToolHandlerOptions {
@@ -741,6 +743,8 @@ interface ToolHandlerOptions {
     signContext?: {
         loadIdentity: () => Promise<HavenIdentity | null>;
         fetchImpl?: typeof fetch;
+        /** #3303: `@haven_ai/signer/<version>`, sent as `X-Haven-Client` on every sign-context read. */
+        clientIdentity?: string;
     };
 }
 declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOptions): Record<SignerToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -772,7 +776,7 @@ declare function renderSignerConsentBlock(input: SignerConsentInput, hash: strin
 declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
 
 declare const SIGNER_NAME = "@haven_ai/signer";
-declare const SIGNER_VERSION = "0.0.0-dev.202609250737.3bd5a51";
+declare const SIGNER_VERSION = "0.0.0-dev.202609251409.98ed67a";
 interface SignerOptions {
     /** Path to a Haven credential JSON file (delegate_key is read from it). */
     credentialsPath?: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk/edge';
+import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth, HavenClientUpdate } from '@haven_ai/sdk/edge';
 export { deriveDelegateAccountAddress } from '@haven_ai/sdk/edge';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z as z$1 } from 'zod/v3';
@@ -725,8 +725,10 @@ interface ToolFailure {
      * the direct `/payments/:id/sign-context` fetch since #3271.
      */
     http_status?: number;
-    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`). */
+    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`, and since #3303 `client_outdated`). */
     backend_error_code?: string;
+    /** #3303: on `client_outdated`, the backend's update hint — `upgrade_command` is what updates this signer. */
+    client_update?: HavenClientUpdate;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 interface ToolHandlerOptions {
@@ -741,6 +743,8 @@ interface ToolHandlerOptions {
     signContext?: {
         loadIdentity: () => Promise<HavenIdentity | null>;
         fetchImpl?: typeof fetch;
+        /** #3303: `@haven_ai/signer/<version>`, sent as `X-Haven-Client` on every sign-context read. */
+        clientIdentity?: string;
     };
 }
 declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOptions): Record<SignerToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -772,7 +776,7 @@ declare function renderSignerConsentBlock(input: SignerConsentInput, hash: strin
 declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
 
 declare const SIGNER_NAME = "@haven_ai/signer";
-declare const SIGNER_VERSION = "0.0.0-dev.202609250737.3bd5a51";
+declare const SIGNER_VERSION = "0.0.0-dev.202609251409.98ed67a";
 interface SignerOptions {
     /** Path to a Haven credential JSON file (delegate_key is read from it). */
     credentialsPath?: string;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { randomUUID, createHash } from 'crypto';
 import { recoverTypedDataAddress, hashTypedData, hashMessage } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
-import { createNextStepBuilder, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, isSettlementChildTypedData, chainIdForNetwork, assertOwnSettlementChild, isPackedUserOperationTypedData, assertUserOpTypedDataBinding, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, DIRECT_SIGN_CONTEXT_VERSION, AgentPaymentNextAction, HavenError, AgentPaymentFailureCode, isSupportedNodeVersion, unsupportedNodeVersionMessage, HavenUserOpBindingError } from '@haven_ai/sdk/edge';
+import { createNextStepBuilder, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, isSettlementChildTypedData, chainIdForNetwork, assertOwnSettlementChild, isPackedUserOperationTypedData, assertUserOpTypedDataBinding, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, DIRECT_SIGN_CONTEXT_VERSION, AgentPaymentNextAction, HavenError, AgentPaymentFailureCode, havenClientIdentity, isSupportedNodeVersion, unsupportedNodeVersionMessage, HavenUserOpBindingError, readClientUpdate, HAVEN_CLIENT_HEADER } from '@haven_ai/sdk/edge';
 export { deriveDelegateAccountAddress } from '@haven_ai/sdk/edge';
 import { stat, lstat, chmod, readFile, mkdir, rename, appendFile, writeFile } from 'fs/promises';
 import { resolve, dirname, join } from 'path';
@@ -430,6 +430,12 @@ var HavenSignContextError = class extends HavenSigningError {
   http_status;
   /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
   backend_error_code;
+  /**
+   * #3303: on a 426 `client_outdated` refusal, the backend's update hint —
+   * this signer is below the minimum the deployment set, and
+   * `client_update.upgrade_command` is what updates it.
+   */
+  client_update;
   constructor(message, code, refusal, paymentId, flow = "x402") {
     super(message);
     this.code = code;
@@ -438,7 +444,15 @@ var HavenSignContextError = class extends HavenSigningError {
     if (code === "SIGN_CONTEXT_REFUSED") {
       this.http_status = refusal?.httpStatus;
       this.backend_error_code = refusal?.errorCode;
-      if (flow === "direct" && refusal?.httpStatus === 404) {
+      if (refusal?.errorCode === "client_outdated") {
+        this.client_update = refusal.clientUpdate;
+        this.next_action = AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.StopAndTellUser,
+          nextTool: null,
+          nextToolOmittedReason: `this signer is below the minimum version Haven accepts \u2014 tell the user to run ${refusal.clientUpdate?.upgrade_command ?? "the connector again"}, restart the agent runtime, then retry the same haven_sign / haven_sign_x402 call`
+        });
+      } else if (flow === "direct" && refusal?.httpStatus === 404) {
         this.fallback = "typed_data_b64";
         this.next_action = AgentPaymentNextAction.StopAndTellUser;
         step = signerRefusalStep({
@@ -496,13 +510,26 @@ async function loadHavenIdentity(credentialsPath) {
   }
 }
 var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
-async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
+function signContextHeaders(identity, clientIdentity) {
+  return {
+    Authorization: `Bearer ${identity.apiKey}`,
+    ...clientIdentity ? { [HAVEN_CLIENT_HEADER]: clientIdentity } : {}
+  };
+}
+function refusalOf(status, body) {
+  return {
+    httpStatus: status,
+    errorCode: typeof body.error_code === "string" ? body.error_code : void 0,
+    clientUpdate: readClientUpdate(body.client_update)
+  };
+}
+async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
   let response;
   try {
     response = await fetchImpl(
       `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
       {
-        headers: { Authorization: `Bearer ${identity.apiKey}` },
+        headers: signContextHeaders(identity, clientIdentity),
         signal: AbortSignal.timeout(timeoutMs)
       }
     );
@@ -534,7 +561,7 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     throw new HavenSignContextError(
       `Haven refused the signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 check the payment_id came from this agent\u2019s own quote." : response.status === 410 ? " Re-run the quote with the same idempotency key, then sign the fresh payment_id." : ""),
       "SIGN_CONTEXT_REFUSED",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 },
+      refusalOf(response.status, body),
       paymentId
     );
   }
@@ -554,17 +581,18 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     payloadHash: signData.hash,
     typedData: signData.typed_data,
     x402Expected,
-    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null
+    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null,
+    clientUpdate: readClientUpdate(body.client_update)
   };
 }
 var SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS = [DIRECT_SIGN_CONTEXT_VERSION];
-async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
+async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
   let response;
   try {
     response = await fetchImpl(
       `${identity.apiUrl}/payments/${encodeURIComponent(paymentId)}/sign-context`,
       {
-        headers: { Authorization: `Bearer ${identity.apiKey}` },
+        headers: signContextHeaders(identity, clientIdentity),
         signal: AbortSignal.timeout(timeoutMs)
       }
     );
@@ -598,7 +626,7 @@ async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, ti
     throw new HavenSignContextError(
       `Haven refused the direct-payment signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 either the payment_id is not from this agent\u2019s own POST /payments call, or this Haven backend predates #3271. Pass payload_hash and typed_data_b64 from the haven_send / haven_pay result, unchanged, instead." : body.error_code === "expired" ? " The payment window has expired; call haven_send / haven_pay again with the same idempotency_key." : ""),
       "SIGN_CONTEXT_REFUSED",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 },
+      refusalOf(response.status, body),
       paymentId,
       "direct"
     );
@@ -619,7 +647,8 @@ async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, ti
     payloadHash: signData.hash,
     typedData: signData.typed_data,
     status: typeof body.status === "string" ? body.status : "pending_signature",
-    expiresAt: typeof body.expires_at === "string" ? body.expires_at : void 0
+    expiresAt: typeof body.expires_at === "string" ? body.expires_at : void 0,
+    clientUpdate: readClientUpdate(body.client_update)
   };
 }
 
@@ -1146,6 +1175,9 @@ function parseFetchedExpected(fetched) {
   }
   return parsed.data;
 }
+function clientUpdateField(resolved) {
+  return resolved?.ctx.clientUpdate ? { client_update: resolved.ctx.clientUpdate } : {};
+}
 function resolveTypedData(args) {
   if (!args.typed_data_b64) return args.typed_data;
   try {
@@ -1179,14 +1211,26 @@ function createToolHandlers(signer, options = {}) {
       );
     }
     try {
-      const ctx = await fetchX402SignContext(identity, args.payment_id, options.signContext?.fetchImpl);
+      const ctx = await fetchX402SignContext(
+        identity,
+        args.payment_id,
+        options.signContext?.fetchImpl,
+        void 0,
+        options.signContext?.clientIdentity
+      );
       checkPayloadHashMatch(args.payload_hash, ctx.payloadHash, args.payment_id);
       return { kind: "x402", ctx };
     } catch (err) {
       if (opts.allowDirectFallback && err instanceof HavenSignContextError && err.http_status === 409 && err.backend_error_code === "sign_context_unavailable") {
         let ctx;
         try {
-          ctx = await fetchDirectSignContext(identity, args.payment_id, options.signContext?.fetchImpl);
+          ctx = await fetchDirectSignContext(
+            identity,
+            args.payment_id,
+            options.signContext?.fetchImpl,
+            void 0,
+            options.signContext?.clientIdentity
+          );
         } catch (directErr) {
           if (directErr instanceof HavenSignContextError && directErr.http_status === 409 && directErr.backend_error_code === "sign_context_unavailable") {
             throw err;
@@ -1236,12 +1280,12 @@ function createToolHandlers(signer, options = {}) {
           assertBoundDirectPaymentUserOp2(typedData, signer.delegateAddress);
           const signature = await signer.signDelegationTypedData(typedData);
           await auditSigning("haven_sign", hashTypedData(typedData));
-          return { signature };
+          return { signature, ...clientUpdateField(resolved) };
         }
         throw new HavenBareHashRefusedError();
       }
       await auditSigning("haven_sign", hashTypedData(typedData));
-      return { signature: result.signature, x402_binding: result.x402Binding };
+      return { signature: result.signature, x402_binding: result.x402Binding, ...clientUpdateField(resolved) };
     }),
     haven_x402_sign_header: async (input) => runTool(async () => {
       const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
@@ -1287,7 +1331,8 @@ function createToolHandlers(signer, options = {}) {
         signature: funding.signature,
         x402_binding: funding.x402Binding,
         payment_header: header.paymentHeader,
-        accepted: header.accepted
+        accepted: header.accepted,
+        ...clientUpdateField(resolved)
       };
     }),
     haven_sign_sweep_delegate: async (input) => runTool(async () => {
@@ -1426,6 +1471,7 @@ function normalizeError(err) {
       ...err.retry_with_new_quote ? { retry_with_new_quote: true } : {},
       ...err.http_status !== void 0 ? { http_status: err.http_status } : {},
       ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {},
+      ...err.client_update ? { client_update: err.client_update } : {},
       // #3103: the typed step the error decided beside its action.
       ...err.next_tool ? { next_tool: err.next_tool } : {},
       ...err.next_tool_server ? { next_tool_server: err.next_tool_server } : {},
@@ -1600,7 +1646,7 @@ async function writeAckFile(path, hash) {
   );
 }
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.0.0-dev.202609250737.3bd5a51";
+var SIGNER_VERSION = "0.0.0-dev.202609251409.98ed67a";
 async function resolveEdgeSigner(options = {}) {
   const { signer } = await resolveSignerRuntime(options);
   return signer;
@@ -1649,7 +1695,10 @@ function buildSignerMcpServer(signer, options = {}) {
     // The signer CORE stays network-free; fetched bytes still pass the same
     // binding verification + digest re-derivation as tool-argument bytes.
     signContext: {
-      loadIdentity: () => loadHavenIdentity(credentialsPath)
+      loadIdentity: () => loadHavenIdentity(credentialsPath),
+      // #3303: the backend refuses a signer below a minimum it has set, at
+      // sign-context — the one place this signer meets it.
+      clientIdentity: havenClientIdentity(SIGNER_NAME, SIGNER_VERSION)
     }
   });
   const registerTool = server.tool.bind(server);