@haven_ai/signer 0.1.18-alpha.0 → 0.1.20-alpha.0

package/dist/cli.cjs

@@ -7,11 +7,11 @@ var crypto = require('crypto');
 var promises = require('fs/promises');
 var os = require('os');
 var path = require('path');
-var sdk = require('@haven_ai/sdk');
-var v3 = require('zod/v3');
 var viem = require('viem');
 var accounts = require('viem/accounts');
 var schemes = require('x402/schemes');
+var sdk = require('@haven_ai/sdk');
+var v3 = require('zod/v3');
 
 function defaultSigningAuditPath(credentialsPath) {
   if (credentialsPath) return path.resolve(`${credentialsPath}.signer-audit.jsonl`);
@@ -46,684 +46,867 @@ function stableStringify(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
 }
-var sweepAuthorizationSchema = v3.z.object({
-  from: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
-  to: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
-  value: v3.z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
-  validAfter: v3.z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
-  validBefore: v3.z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
-  nonce: v3.z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
-  token: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
-  chainId: v3.z.number().int().positive()
-});
-var bindingVersionSchema = v3.z.number().int().positive();
-var sweepExpectedAuthSchema = v3.z.object({
-  version: bindingVersionSchema,
-  message: v3.z.string().min(1),
-  signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-  signer: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
-});
-var x402ExpectedSchema = v3.z.object({
-  payment_id: v3.z.string().min(1),
-  payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-  resource_url: v3.z.string().url(),
-  merchant_to: v3.z.string().min(1),
-  amount: v3.z.string().min(1),
-  asset: v3.z.string().min(1),
-  network: v3.z.string().min(1),
-  // Required: expires_at is folded into the Haven-signed binding message, so the
-  // signer must receive the exact same value to reconstruct a matching message.
-  // Omitting it used to fail downstream with a cryptic "authentication message is
-  // invalid" — making it required surfaces a clear INVALID_INPUT at the boundary.
-  expires_at: v3.z.string().min(1),
-  // #1138: present on a delegation-rail (v2) context. It commits to the EIP-712
-  // typed data the account validates; the signer refuses to raw-sign the bare
-  // hash when it is present, and refuses to sign typed data when it is absent.
-  typed_data_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed hex string").optional(),
-  auth: v3.z.object({
-    // Open at the boundary, enforced in the signer — see bindingVersionSchema.
-    version: bindingVersionSchema,
-    message: v3.z.string().min(1),
-    signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-    signer: v3.z.string().min(1)
-  })
-});
-var toolSchemas = {
-  haven_sign_sweep_delegate: {
-    // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
-    // through verbatim from the hosted haven_sweep_delegate tool — the signer
-    // re-derives the binding message from these exact values.
-    authorization: sweepAuthorizationSchema,
-    // Haven's signature over the authorization context (the binding).
-    expected_auth: sweepExpectedAuthSchema
-  },
-  haven_sign: {
-    // The unsigned hash from haven_pay / haven_pay_x402_quote (payload_hash).
-    payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-    // Pass x402.expected from hosted haven_pay_x402_quote when this hash funds
-    // a standard x402 merchant retry. The signer records it locally and returns
-    // an opaque x402_binding for the later header-signing step.
-    x402_expected: x402ExpectedSchema.optional(),
-    // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
-    // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: v3.z.record(v3.z.string(), v3.z.unknown()).optional()
-  },
-  haven_x402_sign_header: {
-    // The parsed HTTP 402 PaymentRequired from the merchant. Typed as an object
-    // (not z.unknown(), which becomes empty JSON Schema `{}`) so MCP clients
-    // embed it as JSON rather than serialising the object to a string.
-    payment_required: v3.z.record(v3.z.string(), v3.z.unknown()),
-    // Opaque binding returned by haven_sign when x402_expected was supplied.
-    x402_binding: v3.z.string().min(1)
-  },
-  haven_sign_x402: {
-    // One-shot x402 signing: funding hash + merchant header in one local call.
-    payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-    x402_expected: x402ExpectedSchema,
-    payment_required: v3.z.record(v3.z.string(), v3.z.unknown()),
-    // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
-    // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: v3.z.record(v3.z.string(), v3.z.unknown()).optional()
-  }
-};
-var SIGN_DESCRIPTION = [
-  "Sign an unsigned Haven payment hash with the local delegate key. The delegate key never leaves",
-  "this process. Pass the payload_hash returned by haven_pay or haven_pay_x402_quote.",
-  "For x402, also pass x402_expected from haven_pay_x402_quote; the signer records it locally",
-  "and returns { signature, x402_binding }. x402_expected includes expires_at; sign before that",
-  "window closes. DELEGATION-RAIL accounts: when the hosted result carries typed_data, pass it too \u2014",
-  "the account validates that EIP-712 payload, not payload_hash, and signing is refused without it.",
-  "Next: call mcp__haven__haven_submit with signature, then pass x402_binding",
-  "to mcp__haven-signer__haven_x402_sign_header. For plain SafeTransfer payments, just pass payload_hash and",
-  "relay the returned signature via mcp__haven__haven_submit."
-].join(" ");
-var X402_SIGN_HEADER_DESCRIPTION = [
-  "Build and sign the EIP-3009 X-PAYMENT header for the merchant leg of an x402 payment.",
-  "The delegate key stays local \u2014 only the signed header crosses any boundary.",
-  "Pass the payment_required from the original merchant 402 response and the x402_binding",
-  "returned by haven_sign. The signer validates the merchant, amount, resource, asset, and",
-  "network against the recorded funding context before signing, checks expires_at when present,",
-  "and rejects mismatches or expired payment windows.",
-  "Returns { payment_header, accepted }. Set X-PAYMENT: <payment_header> on your retry to the",
-  "merchant. Only call after haven_submit has confirmed the funding step (nextAction=none or",
-  "the funding tx has a confirmed status). Next for paid MCP tools: call mcp__haven__haven_complete_mcp_tool."
-].join(" ");
-var SIGN_X402_DESCRIPTION = [
-  "One-shot x402 signing for the fast 3-call flow: sign the funding hash AND build the EIP-3009",
-  "X-PAYMENT header in a single local call (equivalent to haven_sign followed by",
-  "haven_x402_sign_header). The delegate key never leaves this process. From the haven_pay_mcp_tool",
-  "result pass payload_hash, x402_expected (the nested x402.expected object \u2014 passing the whole x402",
-  "object is also accepted and unwrapped for you), and payment_required (verbatim). On a",
-  "delegation-rail account the result also carries typed_data \u2014 pass that verbatim too; the signer",
-  "signs it instead of payload_hash and refuses the bare hash when the context commits to typed data.",
-  "Returns",
-  "{ signature, x402_binding, payment_header, accepted }; hand signature + payment_header to",
-  "mcp__haven__haven_settle_mcp_tool to fund and settle in one hosted call. The header is built now (before",
-  "funding confirms), so its short validity window starts here \u2014 call mcp__haven__haven_settle_mcp_tool promptly,",
-  "and re-run mcp__haven__haven_pay_mcp_tool with the same idempotency_key if a tool returns PAYMENT_WINDOW_EXPIRED.",
-  "Next: call mcp__haven__haven_settle_mcp_tool."
-].join(" ");
-var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
-  "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
-  "wallet back to your Haven wallet. The delegate key never leaves this process and this tool",
-  "never broadcasts \u2014 it returns only an EIP-3009 signature that Haven's relayer submits and",
-  "pays gas for. Pass the authorization and expected_auth returned by the hosted",
-  "haven_sweep_delegate tool. The signer verifies Haven authored the authorization and that it",
-  "pays out to your own Safe before signing, then returns { signature } to hand back to",
-  "mcp__haven__haven_sweep_delegate to complete recovery."
-].join(" ");
-var toolDescriptions = {
-  haven_sign: SIGN_DESCRIPTION,
-  haven_x402_sign_header: X402_SIGN_HEADER_DESCRIPTION,
-  haven_sign_x402: SIGN_X402_DESCRIPTION,
-  haven_sign_sweep_delegate: SIGN_SWEEP_DELEGATE_DESCRIPTION
-};
-async function signFundingLeg(signer, expected, payloadHash, typedData) {
-  if (!expected.typedDataHash) {
-    return signer.signX402FundingHash(payloadHash, expected);
-  }
-  if (!typedData) {
+function createEdgeSigner(delegateKey, options = {}) {
+  let delegateAddress;
+  try {
+    delegateAddress = sdk.addressFromKey(delegateKey);
+  } catch (err) {
     throw new sdk.HavenSigningError(
-      "This x402 funding intent is on the delegation rail: it commits to EIP-712 typed data, which was not supplied. Pass sign_data.typed_data from haven_pay_mcp_tool / haven_pay_x402_quote verbatim \u2014 the bare payload_hash is not what the account validates."
+      `Invalid delegate key: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  return signer.signX402FundingTypedData(typedData, expected);
-}
-function toExpectedX402(raw) {
-  return {
-    paymentId: raw.payment_id,
-    payloadHash: raw.payload_hash,
-    typedDataHash: raw.typed_data_hash,
-    resourceUrl: raw.resource_url,
-    merchantTo: raw.merchant_to,
-    amount: raw.amount,
-    asset: raw.asset,
-    network: raw.network,
-    expiresAt: raw.expires_at,
-    auth: raw.auth
-  };
-}
-function createToolHandlers(signer, options = {}) {
+  const x402Bindings = /* @__PURE__ */ new Map();
+  function signAndVerify(hash) {
+    const signature = sdk.signHash(delegateKey, hash);
+    if (!sdk.verifySignature(hash, signature, delegateAddress)) {
+      throw new sdk.HavenSigningError(
+        "Local signature verification failed \u2014 recovered address does not match the delegate key."
+      );
+    }
+    return signature;
+  }
   return {
-    haven_sign: async (input) => runTool(async () => {
-      const args = parse("haven_sign", coerceX402Expected(input));
-      const x402Expected = args.x402_expected ? toExpectedX402(args.x402_expected) : null;
-      const result = x402Expected ? await signFundingLeg(signer, x402Expected, args.payload_hash, args.typed_data) : null;
-      if (!result) {
-        const signature = signer.signPaymentHash(args.payload_hash);
-        await auditSigning("haven_sign", args.payload_hash);
-        return { signature };
+    delegateAddress,
+    signPaymentHash(hash) {
+      return signAndVerify(hash);
+    },
+    async signDelegationTypedData(typedData) {
+      const account = accounts.privateKeyToAccount(delegateKey);
+      return account.signTypedData(typedData);
+    },
+    signX402FundingHash(hash, expected) {
+      assertExpectedBinding(hash, expected, options.x402BindingSigner, "hash");
+      const signature = signAndVerify(hash);
+      const x402Binding = crypto.randomUUID();
+      x402Bindings.set(x402Binding, { ...expected });
+      return { signature, x402Binding };
+    },
+    async signX402FundingTypedData(typedData, expected) {
+      assertExpectedBinding(expected.payloadHash, expected, options.x402BindingSigner, "typed-data");
+      const digest = viem.hashTypedData(typedData);
+      if (digest.toLowerCase() !== expected.typedDataHash?.toLowerCase()) {
+        throw new sdk.HavenSigningError(
+          "x402 typed data does not match the digest Haven committed to in the expected context. Refusing to sign \u2014 the payload was altered in transit or Haven declared a different one. The most common cause is the typed data being truncated or reshaped while being copied between tool calls (#1255): re-run the hosted quote and pass its typed_data_b64 string through UNCHANGED instead of re-emitting the nested JSON."
+        );
       }
-      await auditSigning("haven_sign", args.payload_hash);
-      return { signature: result.signature, x402_binding: result.x402Binding };
-    }),
-    haven_x402_sign_header: async (input) => runTool(async () => {
-      const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
-      const result = await signer.buildX402PaymentHeader(
-        args.payment_required,
-        args.x402_binding
-      );
-      await auditSigning(
-        "haven_x402_sign_header",
-        hashPayloadForAudit(args.payment_required)
-      );
-      return { payment_header: result.paymentHeader, accepted: result.accepted };
-    }),
-    haven_sign_x402: async (input) => runTool(async () => {
-      const args = parse("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
-      const funding = await signFundingLeg(
-        signer,
-        toExpectedX402(args.x402_expected),
-        args.payload_hash,
-        args.typed_data
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const signature = await account.signTypedData(
+        typedData
       );
-      const header = await signer.buildX402PaymentHeader(
-        args.payment_required,
-        funding.x402Binding
+      const x402Binding = crypto.randomUUID();
+      x402Bindings.set(x402Binding, { ...expected });
+      return { signature, x402Binding };
+    },
+    async buildX402PaymentHeader(paymentRequired, x402Binding) {
+      const expected = x402Bindings.get(x402Binding);
+      if (!expected) {
+        throw new sdk.HavenSigningError(
+          "x402 funding binding is required before signing a merchant header. Sign the hosted funding hash with x402_expected first."
+        );
+      }
+      try {
+        assertX402PaymentWindowOpen(expected);
+      } catch (err) {
+        x402Bindings.delete(x402Binding);
+        throw err;
+      }
+      const option = sdk.selectStandardPaymentOption(paymentRequired.accepts);
+      if (!option) {
+        throw new sdk.HavenApiError(
+          "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+          400
+        );
+      }
+      assertX402MatchesExpected(paymentRequired, option, expected);
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const requirements = sdk.toStandardPaymentRequirements(paymentRequired, option);
+      const header = await schemes.exact.evm.createPaymentHeader(
+        account,
+        paymentRequired.x402Version,
+        requirements
       );
-      await auditSigning("haven_sign_x402", args.payload_hash);
-      await auditSigning("haven_sign_x402", hashPayloadForAudit(args.payment_required));
-      return {
-        signature: funding.signature,
-        x402_binding: funding.x402Binding,
-        payment_header: header.paymentHeader,
-        accepted: header.accepted
-      };
-    }),
-    haven_sign_sweep_delegate: async (input) => runTool(async () => {
-      const args = parse("haven_sign_sweep_delegate", input);
-      const result = await signer.signSweepAuthorization({
-        authorization: args.authorization,
-        expectedAuth: args.expected_auth,
-        // Cross-check `to` against the Safe in the local credential when present.
-        expectedSafe: options.audit?.safeAddress
-      });
-      await auditSigning(
-        "haven_sign_sweep_delegate",
-        hashPayloadForAudit(args.authorization)
-      );
-      return { signature: result.signature };
-    })
+      if (paymentRequired.x402Version < 2) {
+        x402Bindings.delete(x402Binding);
+        return { paymentHeader: header, accepted: option };
+      }
+      try {
+        const payment = sdk.decodeBase64Json(header);
+        const wrapped = sdk.encodeBase64Json({
+          x402Version: paymentRequired.x402Version,
+          accepted: option,
+          payload: payment.payload
+        });
+        return { paymentHeader: wrapped, accepted: option };
+      } finally {
+        x402Bindings.delete(x402Binding);
+      }
+    },
+    async signSweepAuthorization({
+      authorization,
+      expectedAuth,
+      expectedSafe
+    }) {
+      assertSweepBinding(authorization, expectedAuth, options.x402BindingSigner);
+      if (!sameAddress(authorization.from, delegateAddress)) {
+        throw new sdk.HavenSigningError(
+          "Sweep authorization `from` does not match this delegate address."
+        );
+      }
+      if (expectedSafe && !sameAddress(authorization.to, expectedSafe)) {
+        throw new sdk.HavenSigningError(
+          "Sweep authorization `to` does not match the Safe in the local credential."
+        );
+      }
+      const typedData = sdk.buildSweepTypedData(authorization);
+      const viemTypedData = {
+        domain: {
+          ...typedData.domain,
+          verifyingContract: typedData.domain.verifyingContract
+        },
+        types: typedData.types,
+        primaryType: typedData.primaryType,
+        message: {
+          ...typedData.message,
+          from: typedData.message.from,
+          to: typedData.message.to,
+          nonce: typedData.message.nonce
+        }
+      };
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const signature = await account.signTypedData(viemTypedData);
+      const recovered = await viem.recoverTypedDataAddress({ ...viemTypedData, signature });
+      if (!sameAddress(recovered, delegateAddress)) {
+        throw new sdk.HavenSigningError(
+          "Local sweep signature verification failed \u2014 recovered address does not match the delegate key."
+        );
+      }
+      return { signature };
+    }
   };
-  async function auditSigning(tool, payloadHash) {
-    if (!options.audit) return;
-    const { auditPath, ...context } = options.audit;
-    await appendSigningAuditEntry(
-      createSigningAuditEntry(tool, payloadHash, {
-        ...context,
-        delegateAddress: signer.delegateAddress
-      }),
-      auditPath
+}
+function assertSweepBinding(authorization, expectedAuth, trustedSigner) {
+  if (!expectedAuth || typeof expectedAuth !== "object") {
+    throw new sdk.HavenSigningError("Sweep authorization binding is required before signing.");
+  }
+  if (!trustedSigner) {
+    throw new sdk.HavenSigningError(
+      "Sweep binding verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing sweep authorizations."
     );
   }
-}
-function parse(name, input) {
-  return v3.z.object(toolSchemas[name]).parse(input ?? {});
-}
-function coerceX402Expected(input) {
-  if (!input || typeof input !== "object") return input;
-  const record = input;
-  let value = record.x402_expected;
-  if (typeof value === "string") {
-    try {
-      value = JSON.parse(value);
-    } catch {
-      return input;
-    }
+  assertSupportedBindingVersion(
+    expectedAuth.version,
+    SUPPORTED_SWEEP_BINDING_VERSIONS,
+    "sweep authorization binding"
+  );
+  const message = sdk.buildSweepAuthorizationMessage(authorization);
+  if (expectedAuth.message !== message) {
+    throw new sdk.HavenSigningError("Sweep authorization binding does not match the authorization being signed.");
   }
-  if (!value || typeof value !== "object") return input;
-  const obj = value;
-  if (obj.auth === void 0 && obj.expected && typeof obj.expected === "object") {
-    return { ...record, x402_expected: obj.expected };
+  if (!sameAddress(expectedAuth.signer, trustedSigner)) {
+    throw new sdk.HavenSigningError("Sweep authorization binding was not signed by the configured Haven signer.");
+  }
+  if (!sdk.verifySignature(viem.hashMessage(message), expectedAuth.signature, trustedSigner)) {
+    throw new sdk.HavenSigningError("Sweep authorization binding signature could not be verified.");
   }
-  if (value !== record.x402_expected) return { ...record, x402_expected: value };
-  return input;
 }
-function coercePaymentRequired(input) {
-  if (!input || typeof input !== "object") return input;
-  const record = input;
-  if (typeof record.payment_required !== "string") return input;
-  try {
-    return { ...record, payment_required: JSON.parse(record.payment_required) };
-  } catch {
-    return input;
+function assertX402MatchesExpected(paymentRequired, option, expected) {
+  assertExpectedShape(expected);
+  const headerResource = option.resource ?? paymentRequired.resource.url;
+  if (headerResource !== expected.resourceUrl) {
+    throw new sdk.HavenSigningError("x402 payment_required resource does not match the funded intent.");
+  }
+  if (!sameAddress(option.payTo, expected.merchantTo)) {
+    throw new sdk.HavenSigningError("x402 merchant recipient does not match the funded intent.");
+  }
+  if (sdk.x402AuthorizationAmount(option) !== expected.amount) {
+    throw new sdk.HavenSigningError("x402 amount does not match the funded intent.");
+  }
+  if (!sameAddress(option.asset, expected.asset)) {
+    throw new sdk.HavenSigningError("x402 asset does not match the funded intent.");
+  }
+  if (option.network !== expected.network) {
+    throw new sdk.HavenSigningError("x402 network does not match the funded intent.");
   }
 }
-async function runTool(fn) {
-  try {
-    return { success: true, data: await fn() };
-  } catch (err) {
-    return normalizeError(err);
+function assertExpectedShape(expected) {
+  if (!expected || typeof expected !== "object") {
+    throw new sdk.HavenSigningError("x402 expected funding context is required before signing a merchant header.");
   }
 }
-function normalizeError(err) {
-  if (err instanceof v3.z.ZodError) {
-    return {
-      success: false,
-      code: "INVALID_INPUT",
-      message: err.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; "),
-      statusCode: 400
-    };
+var SUPPORTED_X402_EXPECTED_VERSIONS = [1, 2];
+var SUPPORTED_SWEEP_BINDING_VERSIONS = [1];
+function assertSupportedBindingVersion(received, supported, context) {
+  if (supported.includes(received)) return;
+  const highest = Math.max(...supported);
+  const ceiling = received > highest ? `This signer is out of date: it supports ${context} versions up to ${highest}, and Haven sent version ${received}. Update @haven_ai/signer \u2014 rerun the Haven connector (\`npx @haven_ai/connect@alpha\`), which reinstalls the pinned MCP runtime.` : `Unsupported ${context} version ${received}: this signer supports ${supported.join(", ")}.`;
+  throw new sdk.HavenSigningError(
+    `${ceiling} Nothing was signed. Do not rewrite the version field to a supported value: it is part of the Haven-signed binding message, so changing it invalidates the signature and would misrepresent what Haven authorised.`
+  );
+}
+function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "hash") {
+  assertExpectedShape(expected);
+  if (!trustedSigner) {
+    throw new sdk.HavenSigningError(
+      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding hashes."
+    );
   }
-  if (err instanceof sdk.HavenSigningError) {
-    return { success: false, code: err.code, message: err.message };
+  if (expected.auth) {
+    assertSupportedBindingVersion(
+      expected.auth.version,
+      SUPPORTED_X402_EXPECTED_VERSIONS,
+      "x402 expected context"
+    );
   }
-  if (err instanceof sdk.HavenApiError) {
-    return { success: false, code: err.code, message: err.message, statusCode: err.statusCode };
+  if (expected.payloadHash.toLowerCase() !== payloadHash.toLowerCase()) {
+    throw new sdk.HavenSigningError("x402 expected context does not match the funding hash being signed.");
   }
-  if (err instanceof sdk.HavenError) {
-    return {
-      success: false,
-      code: err.code,
-      message: err.message,
-      statusCode: err.statusCode,
-      paymentId: err.paymentId,
-      ...err.code === sdk.AgentPaymentFailureCode.PaymentWindowExpired ? {
-        next_action: sdk.AgentPaymentNextAction.PaymentWindowExpired,
-        retry_with_new_quote: true,
-        suggested_tool: "haven_pay_mcp_tool"
-      } : {}
-    };
+  if (mode === "hash" && expected.typedDataHash) {
+    throw new sdk.HavenSigningError(
+      "This x402 funding intent commits to EIP-712 typed data, so its bare hash must not be raw-signed \u2014 the account would reject that signature on-chain. Sign sign_data.typed_data instead."
+    );
   }
+  if (mode === "typed-data" && !expected.typedDataHash) {
+    throw new sdk.HavenSigningError(
+      "Refusing to sign typed data under an expected context that does not commit to it. Haven must return a v2 x402 expected context (with typedDataHash) for a delegation-rail intent."
+    );
+  }
+  const message = sdk.buildX402ExpectedMessage({
+    paymentId: expected.paymentId,
+    payloadHash: expected.payloadHash,
+    resourceUrl: expected.resourceUrl,
+    merchantTo: expected.merchantTo,
+    amount: expected.amount,
+    asset: expected.asset,
+    network: expected.network,
+    expiresAt: expected.expiresAt,
+    typedDataHash: expected.typedDataHash
+  });
+  const expectedVersion = expected.typedDataHash ? 2 : 1;
+  if (expected.auth?.version !== expectedVersion || expected.auth.message !== message) {
+    throw new sdk.HavenSigningError("x402 expected context authentication message is invalid.");
+  }
+  if (!sameAddress(expected.auth.signer, trustedSigner)) {
+    throw new sdk.HavenSigningError("x402 expected context was not signed by the configured Haven signer.");
+  }
+  if (!sdk.verifySignature(viem.hashMessage(message), expected.auth.signature, trustedSigner)) {
+    throw new sdk.HavenSigningError("x402 expected context signature could not be verified.");
+  }
+}
+function assertX402PaymentWindowOpen(expected) {
+  if (!expected.expiresAt) return;
+  const expiresAtMs = Date.parse(expected.expiresAt);
+  if (Number.isNaN(expiresAtMs)) {
+    throw new sdk.HavenSigningError("x402 expected context expiresAt is not a valid ISO timestamp.");
+  }
+  if (expiresAtMs <= Date.now()) {
+    throw new sdk.HavenError(
+      "The x402 payment window expired before the merchant header could be signed. Re-quote with haven_pay_mcp_tool using the same idempotency_key before trying again.",
+      sdk.AgentPaymentFailureCode.PaymentWindowExpired,
+      410,
+      expected.paymentId
+    );
+  }
+}
+function sameAddress(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+// src/capabilities.ts
+var SIGNER_CAPABILITY_KEY = "haven/signer-compatibility";
+function signerCompatibility() {
   return {
-    success: false,
-    code: "UNKNOWN_ERROR",
-    message: err instanceof Error ? err.message : String(err)
+    x402_expected_context_versions: [...SUPPORTED_X402_EXPECTED_VERSIONS],
+    sweep_binding_versions: [...SUPPORTED_SWEEP_BINDING_VERSIONS]
   };
 }
-
-// src/consent.ts
-var SIGNER_ACK_ENV = "HAVEN_SIGNER_ACK";
-function computeSignerConsentHash(input) {
-  const identity = [
-    input.delegateAddress.toLowerCase(),
-    (input.safeAddress ?? "").toLowerCase(),
-    input.agentId ?? "",
-    input.chainId ?? "",
-    input.network ?? ""
-  ].join("|");
-  const toolCanonical = [...input.toolNames].sort().join(",");
-  return crypto.createHash("sha256").update(`${identity}
-${toolCanonical}`).digest("hex").slice(0, 16);
+function signerCapabilityAdvertisement() {
+  return { experimental: { [SIGNER_CAPABILITY_KEY]: signerCompatibility() } };
 }
-function renderSignerConsentBlock(input, hash) {
-  const lines = [
+function signerInstructions() {
+  const compatibility = signerCompatibility();
+  return [
+    "Haven edge signer: sign-only tools bound to the local delegate key. It never emits the",
+    "key. Its one network capability is an authenticated READ of a signing context from",
+    "Haven by payment_id \u2014 pass payment_id to haven_sign / haven_sign_x402 (preferred for",
+    "delegation-rail x402) instead of relaying bulky typed-data payloads yourself.",
     "",
-    "------------------------------------------------------------",
-    "Haven edge signer - first-launch consent",
-    "------------------------------------------------------------",
+    "Version compatibility (check this BEFORE signing, not after):",
+    `- x402 expected-context versions supported: ${compatibility.x402_expected_context_versions.join(", ")}`,
+    `- sweep authorization binding versions supported: ${compatibility.sweep_binding_versions.join(", ")}`,
     "",
-    `Delegate address: ${input.delegateAddress}`
-  ];
-  lines.push(`Haven wallet:     ${input.safeAddress ?? "not provided to this signer"}`);
-  if (input.agentId) lines.push(`Agent ID:         ${input.agentId}`);
-  if (typeof input.chainId === "number") lines.push(`Chain ID:         ${input.chainId}`);
-  if (input.network) lines.push(`Network:          ${input.network}`);
-  lines.push("");
-  lines.push("This local signer holds the delegate key on this machine and signs");
-  lines.push("payment payloads or x402 merchant headers for the delegate address above.");
-  lines.push("It does not call the Haven API, so it cannot show a live allowance summary.");
-  lines.push("On-chain Safe rules remain the real spend gate, and the wallet owner can");
-  lines.push("pause or revoke agent authority outside this signer.");
-  lines.push("");
-  lines.push("Tools this signer will expose to your agent runtime:");
-  for (const name of input.toolNames) {
-    lines.push(`  - ${name}`);
-    lines.push(`      ${toolDescriptions[name]}`);
+    "Haven quote and prepare results report the expected-context version they will emit",
+    "(signer_compatibility.x402_expected_context_version). If that version is not in the list",
+    "above, this signer is out of date: STOP before signing, and tell the user to update",
+    "@haven_ai/signer by rerunning `npx @haven_ai/connect@alpha`, which reinstalls the pinned",
+    "MCP runtime. Do not edit the version field to a supported value \u2014 it is part of the",
+    "Haven-signed binding message, so changing it invalidates the signature."
+  ].join("\n");
+}
+async function loadHavenIdentity(credentialsPath) {
+  if (!credentialsPath) return null;
+  try {
+    const raw = JSON.parse(
+      await promises.readFile(path.join(path.dirname(credentialsPath), "identity.json"), "utf8")
+    );
+    const apiKey = typeof raw.api_key === "string" ? raw.api_key : void 0;
+    const apiUrl = typeof raw.api_url === "string" ? raw.api_url : void 0;
+    if (!apiKey || !apiUrl) return null;
+    return { apiKey, apiUrl: apiUrl.replace(/\/+$/, "") };
+  } catch {
+    return null;
   }
-  lines.push("");
-  lines.push("A local audit entry is appended for every signing operation. Audit entries");
-  lines.push("record timestamp, tool, payload hash, and delegate address; never the key,");
-  lines.push("signature, or x402 payment header.");
-  lines.push("");
-  lines.push(`Consent hash: ${hash}`);
-  lines.push("");
-  lines.push("To acknowledge, EITHER:");
-  lines.push(`  - set ${SIGNER_ACK_ENV}=${hash} in this process's environment, OR`);
-  lines.push("  - re-run with --ack to write the acknowledgement next to your");
-  lines.push("    credential file (sidecar <credentials>.signer-ack.json).");
-  lines.push("");
-  lines.push("------------------------------------------------------------");
-  lines.push("");
-  return lines.join("\n");
 }
-async function ensureSignerConsent(input, options = {}) {
-  const env = options.env ?? process.env;
-  const out = options.out ?? process.stderr;
-  const hash = computeSignerConsentHash(input);
-  const envAck = env[SIGNER_ACK_ENV];
-  if (typeof envAck === "string" && envAck.length > 0) {
-    if (envAck === hash) return { ok: true, hash, reason: "env_var_match" };
-    out.write(renderSignerConsentBlock(input, hash));
-    out.write(
-      `${SIGNER_ACK_ENV} was set but did not match the current signer consent hash.
-Expected: ${hash}
-Got:      ${envAck}
-Re-acknowledge with the new hash above, or run with --ack.
-
-`
+async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch) {
+  let response;
+  try {
+    response = await fetchImpl(
+      `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
+      { headers: { Authorization: `Bearer ${identity.apiKey}` } }
+    );
+  } catch (err) {
+    throw new sdk.HavenSigningError(
+      `Could not reach Haven to fetch the signing context for ${paymentId}: ${err instanceof Error ? err.message : String(err)}. Retry, or pass typed_data_b64 from the quote result instead.`
     );
-    return { ok: false, hash, reason: "env_var_mismatch" };
   }
-  const ackPath = sidecarPath(options.credentialsPath);
-  if (ackPath) {
-    const stored = await readAckFile(ackPath);
-    if (stored?.ack === hash) return { ok: true, hash, reason: "ack_file_match" };
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const detail = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+    throw new sdk.HavenSigningError(
+      `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." : "")
+    );
+  }
+  const signData = body.sign_data;
+  const x402Expected = body.x402_expected;
+  if (!signData || typeof signData.hash !== "string" || !signData.typed_data || typeof signData.typed_data !== "object" || !x402Expected) {
+    throw new sdk.HavenSigningError(
+      "The Haven sign-context response is missing sign_data.typed_data or x402_expected \u2014 the backend may predate #1263. Pass typed_data_b64 from the quote result instead."
+    );
+  }
+  return {
+    paymentId: String(body.payment_id ?? paymentId),
+    payloadHash: signData.hash,
+    typedData: signData.typed_data,
+    x402Expected
+  };
+}
+
+// src/tools.ts
+var sweepAuthorizationSchema = v3.z.object({
+  from: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
+  to: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
+  value: v3.z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
+  validAfter: v3.z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
+  validBefore: v3.z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
+  nonce: v3.z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
+  token: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
+  chainId: v3.z.number().int().positive()
+});
+var bindingVersionSchema = v3.z.number().int().positive();
+var sweepExpectedAuthSchema = v3.z.object({
+  version: bindingVersionSchema,
+  message: v3.z.string().min(1),
+  signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+  signer: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
+});
+var x402ExpectedShape = {
+  payment_id: v3.z.string().min(1),
+  payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
+  resource_url: v3.z.string().url(),
+  merchant_to: v3.z.string().min(1),
+  amount: v3.z.string().min(1),
+  asset: v3.z.string().min(1),
+  network: v3.z.string().min(1),
+  // Required: expires_at is folded into the Haven-signed binding message, so the
+  // signer must receive the exact same value to reconstruct a matching message.
+  // Omitting it used to fail downstream with a cryptic "authentication message is
+  // invalid" — making it required surfaces a clear INVALID_INPUT at the boundary.
+  expires_at: v3.z.string().min(1),
+  // #1138: present on a delegation-rail (v2) context. It commits to the EIP-712
+  // typed data the account validates; the signer refuses to raw-sign the bare
+  // hash when it is present, and refuses to sign typed data when it is absent.
+  typed_data_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed hex string").optional(),
+  auth: v3.z.object({
+    // Open at the boundary, enforced in the signer — see bindingVersionSchema.
+    version: bindingVersionSchema,
+    message: v3.z.string().min(1),
+    signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+    signer: v3.z.string().min(1)
+  })
+};
+var x402ExpectedSchema = v3.z.object(x402ExpectedShape);
+var toolSchemas = {
+  haven_sign_sweep_delegate: {
+    // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
+    // through verbatim from the hosted haven_sweep_delegate tool — the signer
+    // re-derives the binding message from these exact values.
+    authorization: sweepAuthorizationSchema,
+    // Haven's signature over the authorization context (the binding).
+    expected_auth: sweepExpectedAuthSchema
+  },
+  haven_sign: {
+    // #1263: THE preferred x402 input — the signer fetches the exact signing
+    // payload + expected context from Haven itself (authenticated with the
+    // locally-stored agent credential), so no bulky bytes ever cross the
+    // model. Pass payment_id ALONE for a delegation-rail x402 funding intent.
+    payment_id: v3.z.string().min(1).optional(),
+    // The unsigned hash from haven_pay / haven_pay_x402_quote (payload_hash).
+    // Optional when payment_id is supplied (the fetch carries it).
+    payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    // Pass x402.expected from hosted haven_pay_x402_quote when this hash funds
+    // a standard x402 merchant retry. The signer records it locally and returns
+    // an opaque x402_binding for the later header-signing step.
+    x402_expected: x402ExpectedSchema.optional(),
+    // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
+    // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
+    typed_data: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
+    // #1255: the same payload as ONE opaque base64 string, exactly as returned
+    // by the hosted tools. Preferred over typed_data when both are present —
+    // an agent re-emitting multi-KB nested JSON between tool calls is the
+    // failure mode this field removes (a truncated/reshaped payload fails the
+    // digest check and the payment refuses, correctly but pointlessly).
+    // Bounded: a realistic redemption payload is ~10KB encoded; 256KB is
+    // generous headroom while keeping the offline signer from materializing
+    // arbitrarily large caller input.
+    typed_data_b64: v3.z.string().min(1).max(262144).optional()
+  },
+  haven_x402_sign_header: {
+    // The parsed HTTP 402 PaymentRequired from the merchant. Typed as an object
+    // (not z.unknown(), which becomes empty JSON Schema `{}`) so MCP clients
+    // embed it as JSON rather than serialising the object to a string.
+    payment_required: v3.z.record(v3.z.string(), v3.z.unknown()),
+    // Opaque binding returned by haven_sign when x402_expected was supplied.
+    x402_binding: v3.z.string().min(1)
+  },
+  haven_sign_x402: {
+    // #1263: preferred — pass payment_id (plus payment_required) and the
+    // signer fetches the exact signing payload + expected context itself.
+    payment_id: v3.z.string().min(1).optional(),
+    // One-shot x402 signing: funding hash + merchant header in one local call.
+    // Both optional when payment_id is supplied (the fetch carries them).
+    payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    x402_expected: x402ExpectedSchema.optional(),
+    payment_required: v3.z.record(v3.z.string(), v3.z.unknown()),
+    // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
+    // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
+    typed_data: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
+    // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
+    typed_data_b64: v3.z.string().min(1).max(262144).optional()
+  }
+};
+var SIGN_DESCRIPTION = [
+  "Sign an unsigned Haven payment hash with the local delegate key. The delegate key never leaves",
+  "this process. Pass the payload_hash returned by haven_pay or haven_pay_x402_quote.",
+  "For x402, also pass x402_expected from haven_pay_x402_quote; the signer records it locally",
+  "and returns { signature, x402_binding }. x402_expected includes expires_at; sign before that",
+  "window closes. DELEGATION-RAIL x402 accounts (#1263): pass payment_id ALONE (preferred) \u2014 this",
+  "signer fetches the exact signing payload and expected context from Haven itself, so nothing",
+  "bulky ever crosses your context. Fallback: pass typed_data_b64 through UNCHANGED (never re-type",
+  "the nested typed_data JSON); the account validates that EIP-712 payload, not payload_hash.",
+  "Next: call mcp__haven__haven_submit with signature, then pass x402_binding",
+  "to mcp__haven-signer__haven_x402_sign_header. For plain SafeTransfer payments, just pass payload_hash and",
+  "relay the returned signature via mcp__haven__haven_submit."
+].join(" ");
+var X402_SIGN_HEADER_DESCRIPTION = [
+  "Build and sign the EIP-3009 X-PAYMENT header for the merchant leg of an x402 payment.",
+  "The delegate key stays local \u2014 only the signed header crosses any boundary.",
+  "Pass the payment_required from the original merchant 402 response and the x402_binding",
+  "returned by haven_sign. The signer validates the merchant, amount, resource, asset, and",
+  "network against the recorded funding context before signing, checks expires_at when present,",
+  "and rejects mismatches or expired payment windows.",
+  "Returns { payment_header, accepted }. Set X-PAYMENT: <payment_header> on your retry to the",
+  "merchant. Only call after haven_submit has confirmed the funding step (nextAction=none or",
+  "the funding tx has a confirmed status). Next for paid MCP tools: call mcp__haven__haven_complete_mcp_tool."
+].join(" ");
+var SIGN_X402_DESCRIPTION = [
+  "One-shot x402 signing for the fast 3-call flow: sign the funding hash AND build the EIP-3009",
+  "X-PAYMENT header in a single local call (equivalent to haven_sign followed by",
+  "haven_x402_sign_header). The delegate key never leaves this process. From the haven_pay_mcp_tool",
+  "result pass payment_id and payment_required \u2014 PREFERRED (#1263): this signer fetches the exact",
+  "signing payload and expected context from Haven itself, so nothing bulky crosses your context.",
+  "Fallback for older backends: pass payload_hash, x402_expected (the nested x402.expected object \u2014",
+  "passing the whole x402 object is also accepted and unwrapped for you), and typed_data_b64",
+  "through UNCHANGED; the signer",
+  "signs the typed data instead of payload_hash and refuses the bare hash when the context commits to typed data.",
+  "Returns",
+  "{ signature, x402_binding, payment_header, accepted }; hand signature + payment_header to",
+  "mcp__haven__haven_settle_mcp_tool to fund and settle in one hosted call. The header is built now (before",
+  "funding confirms), so its short validity window starts here \u2014 call mcp__haven__haven_settle_mcp_tool promptly,",
+  "and re-run mcp__haven__haven_pay_mcp_tool with the same idempotency_key if a tool returns PAYMENT_WINDOW_EXPIRED.",
+  "Next: call mcp__haven__haven_settle_mcp_tool."
+].join(" ");
+var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
+  "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
+  "wallet back to your Haven wallet. The delegate key never leaves this process and this tool",
+  "never broadcasts \u2014 it returns only an EIP-3009 signature that Haven's relayer submits and",
+  "pays gas for. Pass the authorization and expected_auth returned by the hosted",
+  "haven_sweep_delegate tool. The signer verifies Haven authored the authorization and that it",
+  "pays out to your own Safe before signing, then returns { signature } to hand back to",
+  "mcp__haven__haven_sweep_delegate to complete recovery."
+].join(" ");
+var toolDescriptions = {
+  haven_sign: SIGN_DESCRIPTION,
+  haven_x402_sign_header: X402_SIGN_HEADER_DESCRIPTION,
+  haven_sign_x402: SIGN_X402_DESCRIPTION,
+  haven_sign_sweep_delegate: SIGN_SWEEP_DELEGATE_DESCRIPTION
+};
+async function signFundingLeg(signer, expected, payloadHash, typedData) {
+  if (!expected.typedDataHash) {
+    return signer.signX402FundingHash(payloadHash, expected);
   }
-  if (options.writeAck && ackPath) {
-    out.write(renderSignerConsentBlock(input, hash));
-    await writeAckFile(ackPath, hash);
-    out.write(`Wrote acknowledgement to ${ackPath}
-
-`);
-    return { ok: true, hash, reason: "wrote_ack_file" };
+  if (!typedData) {
+    throw new sdk.HavenSigningError(
+      "This x402 funding intent is on the delegation rail: it commits to EIP-712 typed data, which was not supplied. Pass typed_data_b64 from haven_pay_mcp_tool / haven_pay_x402_quote through unchanged (or typed_data verbatim) \u2014 the bare payload_hash is not what the account validates."
+    );
   }
-  out.write(renderSignerConsentBlock(input, hash));
-  return { ok: false, hash, reason: "no_acknowledgement" };
-}
-function registeredSignerToolNames() {
-  return Object.keys(toolSchemas);
+  return signer.signX402FundingTypedData(typedData, expected);
 }
-function sidecarPath(credentialsPath) {
-  if (!credentialsPath) return null;
-  return path.resolve(`${credentialsPath}.signer-ack.json`);
+function toExpectedX402(raw) {
+  return {
+    paymentId: raw.payment_id,
+    payloadHash: raw.payload_hash,
+    typedDataHash: raw.typed_data_hash,
+    resourceUrl: raw.resource_url,
+    merchantTo: raw.merchant_to,
+    amount: raw.amount,
+    asset: raw.asset,
+    network: raw.network,
+    expiresAt: raw.expires_at,
+    auth: raw.auth
+  };
 }
-async function readAckFile(path) {
-  try {
-    const raw = await promises.readFile(path, "utf8");
-    const parsed = JSON.parse(raw);
-    return { ack: typeof parsed.ack === "string" ? parsed.ack : void 0 };
-  } catch {
-    return null;
+function parseFetchedExpected(fetched) {
+  const parsed = v3.z.object(x402ExpectedShape).safeParse(fetched.x402Expected);
+  if (!parsed.success) {
+    throw new sdk.HavenSigningError(
+      `The Haven sign-context response carried a malformed x402_expected \u2014 the backend may predate #1263. Pass payload_hash + x402_expected from the quote result instead. Underlying: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`
+    );
   }
+  return parsed.data;
 }
-async function writeAckFile(path$1, hash) {
-  await promises.mkdir(path.dirname(path$1), { recursive: true });
-  await promises.writeFile(
-    path$1,
-    JSON.stringify({ ack: hash, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2),
-    "utf8"
-  );
-}
-function createEdgeSigner(delegateKey, options = {}) {
-  let delegateAddress;
+function resolveTypedData(args) {
+  if (!args.typed_data_b64) return args.typed_data;
   try {
-    delegateAddress = sdk.addressFromKey(delegateKey);
+    const decoded = JSON.parse(
+      Buffer.from(args.typed_data_b64, "base64").toString("utf8")
+    );
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+      throw new Error("decoded value is not an object");
+    }
+    return decoded;
   } catch (err) {
     throw new sdk.HavenSigningError(
-      `Invalid delegate key: ${err instanceof Error ? err.message : String(err)}`
+      `typed_data_b64 did not decode to a JSON object. Pass the exact string returned by the hosted Haven tool, unchanged \u2014 do not re-encode, trim, or reformat it. Underlying error: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  const x402Bindings = /* @__PURE__ */ new Map();
-  function signAndVerify(hash) {
-    const signature = sdk.signHash(delegateKey, hash);
-    if (!sdk.verifySignature(hash, signature, delegateAddress)) {
+}
+function createToolHandlers(signer, options = {}) {
+  async function resolveSignContext(args) {
+    if (!args.payment_id) return null;
+    const identity = await options.signContext?.loadIdentity() ?? null;
+    if (!identity) {
       throw new sdk.HavenSigningError(
-        "Local signature verification failed \u2014 recovered address does not match the delegate key."
+        "payment_id signing needs the agent identity (identity.json next to the signer credentials), which this signer could not load. Re-run `npx @haven_ai/connect@alpha` to restore it, or pass typed_data_b64 from the quote result instead."
       );
     }
-    return signature;
+    const ctx = await fetchX402SignContext(
+      identity,
+      args.payment_id,
+      options.signContext?.fetchImpl
+    );
+    if (args.payload_hash && args.payload_hash.toLowerCase() !== ctx.payloadHash.toLowerCase()) {
+      throw new sdk.HavenSigningError(
+        `The supplied payload_hash does not match the signing context Haven serves for payment ${args.payment_id}. Pass payment_id alone, or check which quote the hash came from.`
+      );
+    }
+    return ctx;
   }
   return {
-    delegateAddress,
-    signPaymentHash(hash) {
-      return signAndVerify(hash);
-    },
-    signX402FundingHash(hash, expected) {
-      assertExpectedBinding(hash, expected, options.x402BindingSigner, "hash");
-      const signature = signAndVerify(hash);
-      const x402Binding = crypto.randomUUID();
-      x402Bindings.set(x402Binding, { ...expected });
-      return { signature, x402Binding };
-    },
-    async signX402FundingTypedData(typedData, expected) {
-      assertExpectedBinding(expected.payloadHash, expected, options.x402BindingSigner, "typed-data");
-      const digest = viem.hashTypedData(typedData);
-      if (digest.toLowerCase() !== expected.typedDataHash?.toLowerCase()) {
-        throw new sdk.HavenSigningError(
-          "x402 typed data does not match the digest Haven committed to in the expected context. Refusing to sign \u2014 the payload was altered in transit or Haven declared a different one."
-        );
-      }
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const signature = await account.signTypedData(
-        typedData
-      );
-      const x402Binding = crypto.randomUUID();
-      x402Bindings.set(x402Binding, { ...expected });
-      return { signature, x402Binding };
-    },
-    async buildX402PaymentHeader(paymentRequired, x402Binding) {
-      const expected = x402Bindings.get(x402Binding);
-      if (!expected) {
+    haven_sign: async (input) => runTool(async () => {
+      const args = parse("haven_sign", coerceX402Expected(input));
+      const fetched = await resolveSignContext(args);
+      const typedData = fetched?.typedData ?? resolveTypedData(args);
+      const payloadHash = fetched?.payloadHash ?? args.payload_hash;
+      if (!payloadHash) {
         throw new sdk.HavenSigningError(
-          "x402 funding binding is required before signing a merchant header. Sign the hosted funding hash with x402_expected first."
+          "Pass payment_id (preferred for delegation-rail x402) or payload_hash."
         );
       }
-      try {
-        assertX402PaymentWindowOpen(expected);
-      } catch (err) {
-        x402Bindings.delete(x402Binding);
-        throw err;
-      }
-      const option = sdk.selectStandardPaymentOption(paymentRequired.accepts);
-      if (!option) {
-        throw new sdk.HavenApiError(
-          "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-          400
-        );
+      const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
+      const x402Expected = expectedRaw ? toExpectedX402(expectedRaw) : null;
+      const result = x402Expected ? await signFundingLeg(signer, x402Expected, payloadHash, typedData) : null;
+      if (!result) {
+        if (typedData) {
+          const signature2 = await signer.signDelegationTypedData(typedData);
+          await auditSigning("haven_sign", payloadHash);
+          return { signature: signature2 };
+        }
+        const signature = signer.signPaymentHash(payloadHash);
+        await auditSigning("haven_sign", payloadHash);
+        return { signature };
       }
-      assertX402MatchesExpected(paymentRequired, option, expected);
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const requirements = sdk.toStandardPaymentRequirements(paymentRequired, option);
-      const header = await schemes.exact.evm.createPaymentHeader(
-        account,
-        paymentRequired.x402Version,
-        requirements
+      await auditSigning("haven_sign", payloadHash);
+      return { signature: result.signature, x402_binding: result.x402Binding };
+    }),
+    haven_x402_sign_header: async (input) => runTool(async () => {
+      const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
+      const result = await signer.buildX402PaymentHeader(
+        args.payment_required,
+        args.x402_binding
       );
-      if (paymentRequired.x402Version < 2) {
-        x402Bindings.delete(x402Binding);
-        return { paymentHeader: header, accepted: option };
-      }
-      try {
-        const payment = sdk.decodeBase64Json(header);
-        const wrapped = sdk.encodeBase64Json({
-          x402Version: paymentRequired.x402Version,
-          accepted: option,
-          payload: payment.payload
-        });
-        return { paymentHeader: wrapped, accepted: option };
-      } finally {
-        x402Bindings.delete(x402Binding);
-      }
-    },
-    async signSweepAuthorization({
-      authorization,
-      expectedAuth,
-      expectedSafe
-    }) {
-      assertSweepBinding(authorization, expectedAuth, options.x402BindingSigner);
-      if (!sameAddress(authorization.from, delegateAddress)) {
-        throw new sdk.HavenSigningError(
-          "Sweep authorization `from` does not match this delegate address."
-        );
-      }
-      if (expectedSafe && !sameAddress(authorization.to, expectedSafe)) {
+      await auditSigning(
+        "haven_x402_sign_header",
+        hashPayloadForAudit(args.payment_required)
+      );
+      return { payment_header: result.paymentHeader, accepted: result.accepted };
+    }),
+    haven_sign_x402: async (input) => runTool(async () => {
+      const args = parse("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
+      const fetched = await resolveSignContext(args);
+      const payloadHash = fetched?.payloadHash ?? args.payload_hash;
+      const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
+      if (!payloadHash || !expectedRaw) {
         throw new sdk.HavenSigningError(
-          "Sweep authorization `to` does not match the Safe in the local credential."
+          "Pass payment_id (preferred \u2014 the signer fetches the signing context itself) or payload_hash + x402_expected from the quote result."
         );
       }
-      const typedData = sdk.buildSweepTypedData(authorization);
-      const viemTypedData = {
-        domain: {
-          ...typedData.domain,
-          verifyingContract: typedData.domain.verifyingContract
-        },
-        types: typedData.types,
-        primaryType: typedData.primaryType,
-        message: {
-          ...typedData.message,
-          from: typedData.message.from,
-          to: typedData.message.to,
-          nonce: typedData.message.nonce
-        }
+      const funding = await signFundingLeg(
+        signer,
+        toExpectedX402(expectedRaw),
+        payloadHash,
+        fetched?.typedData ?? resolveTypedData(args)
+      );
+      const header = await signer.buildX402PaymentHeader(
+        args.payment_required,
+        funding.x402Binding
+      );
+      await auditSigning("haven_sign_x402", payloadHash);
+      await auditSigning("haven_sign_x402", hashPayloadForAudit(args.payment_required));
+      return {
+        signature: funding.signature,
+        x402_binding: funding.x402Binding,
+        payment_header: header.paymentHeader,
+        accepted: header.accepted
       };
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const signature = await account.signTypedData(viemTypedData);
-      const recovered = await viem.recoverTypedDataAddress({ ...viemTypedData, signature });
-      if (!sameAddress(recovered, delegateAddress)) {
-        throw new sdk.HavenSigningError(
-          "Local sweep signature verification failed \u2014 recovered address does not match the delegate key."
-        );
-      }
-      return { signature };
-    }
+    }),
+    haven_sign_sweep_delegate: async (input) => runTool(async () => {
+      const args = parse("haven_sign_sweep_delegate", input);
+      const result = await signer.signSweepAuthorization({
+        authorization: args.authorization,
+        expectedAuth: args.expected_auth,
+        // Cross-check `to` against the Safe in the local credential when present.
+        expectedSafe: options.audit?.safeAddress
+      });
+      await auditSigning(
+        "haven_sign_sweep_delegate",
+        hashPayloadForAudit(args.authorization)
+      );
+      return { signature: result.signature };
+    })
   };
-}
-function assertSweepBinding(authorization, expectedAuth, trustedSigner) {
-  if (!expectedAuth || typeof expectedAuth !== "object") {
-    throw new sdk.HavenSigningError("Sweep authorization binding is required before signing.");
-  }
-  if (!trustedSigner) {
-    throw new sdk.HavenSigningError(
-      "Sweep binding verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing sweep authorizations."
+  async function auditSigning(tool, payloadHash) {
+    if (!options.audit) return;
+    const { auditPath, ...context } = options.audit;
+    await appendSigningAuditEntry(
+      createSigningAuditEntry(tool, payloadHash, {
+        ...context,
+        delegateAddress: signer.delegateAddress
+      }),
+      auditPath
     );
   }
-  assertSupportedBindingVersion(
-    expectedAuth.version,
-    SUPPORTED_SWEEP_BINDING_VERSIONS,
-    "sweep authorization binding"
-  );
-  const message = sdk.buildSweepAuthorizationMessage(authorization);
-  if (expectedAuth.message !== message) {
-    throw new sdk.HavenSigningError("Sweep authorization binding does not match the authorization being signed.");
-  }
-  if (!sameAddress(expectedAuth.signer, trustedSigner)) {
-    throw new sdk.HavenSigningError("Sweep authorization binding was not signed by the configured Haven signer.");
+}
+function parse(name, input) {
+  return v3.z.object(toolSchemas[name]).parse(input ?? {});
+}
+function coerceX402Expected(input) {
+  if (!input || typeof input !== "object") return input;
+  const record = input;
+  let value = record.x402_expected;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return input;
+    }
   }
-  if (!sdk.verifySignature(viem.hashMessage(message), expectedAuth.signature, trustedSigner)) {
-    throw new sdk.HavenSigningError("Sweep authorization binding signature could not be verified.");
+  if (!value || typeof value !== "object") return input;
+  const obj = value;
+  if (obj.auth === void 0 && obj.expected && typeof obj.expected === "object") {
+    return { ...record, x402_expected: obj.expected };
   }
+  if (value !== record.x402_expected) return { ...record, x402_expected: value };
+  return input;
 }
-function assertX402MatchesExpected(paymentRequired, option, expected) {
-  assertExpectedShape(expected);
-  const headerResource = option.resource ?? paymentRequired.resource.url;
-  if (headerResource !== expected.resourceUrl) {
-    throw new sdk.HavenSigningError("x402 payment_required resource does not match the funded intent.");
+function coercePaymentRequired(input) {
+  if (!input || typeof input !== "object") return input;
+  const record = input;
+  if (typeof record.payment_required !== "string") return input;
+  try {
+    return { ...record, payment_required: JSON.parse(record.payment_required) };
+  } catch {
+    return input;
   }
-  if (!sameAddress(option.payTo, expected.merchantTo)) {
-    throw new sdk.HavenSigningError("x402 merchant recipient does not match the funded intent.");
+}
+async function runTool(fn) {
+  try {
+    return { success: true, data: await fn() };
+  } catch (err) {
+    return normalizeError(err);
   }
-  if (sdk.x402AuthorizationAmount(option) !== expected.amount) {
-    throw new sdk.HavenSigningError("x402 amount does not match the funded intent.");
+}
+function normalizeError(err) {
+  if (err instanceof v3.z.ZodError) {
+    return {
+      success: false,
+      code: "INVALID_INPUT",
+      message: err.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; "),
+      statusCode: 400
+    };
   }
-  if (!sameAddress(option.asset, expected.asset)) {
-    throw new sdk.HavenSigningError("x402 asset does not match the funded intent.");
+  if (err instanceof sdk.HavenSigningError) {
+    return { success: false, code: err.code, message: err.message };
   }
-  if (option.network !== expected.network) {
-    throw new sdk.HavenSigningError("x402 network does not match the funded intent.");
+  if (err instanceof sdk.HavenApiError) {
+    return { success: false, code: err.code, message: err.message, statusCode: err.statusCode };
   }
-}
-function assertExpectedShape(expected) {
-  if (!expected || typeof expected !== "object") {
-    throw new sdk.HavenSigningError("x402 expected funding context is required before signing a merchant header.");
+  if (err instanceof sdk.HavenError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      statusCode: err.statusCode,
+      paymentId: err.paymentId,
+      ...err.code === sdk.AgentPaymentFailureCode.PaymentWindowExpired ? {
+        next_action: sdk.AgentPaymentNextAction.PaymentWindowExpired,
+        retry_with_new_quote: true,
+        suggested_tool: "haven_pay_mcp_tool"
+      } : {}
+    };
   }
+  return {
+    success: false,
+    code: "UNKNOWN_ERROR",
+    message: err instanceof Error ? err.message : String(err)
+  };
 }
-var SUPPORTED_X402_EXPECTED_VERSIONS = [1, 2];
-var SUPPORTED_SWEEP_BINDING_VERSIONS = [1];
-function assertSupportedBindingVersion(received, supported, context) {
-  if (supported.includes(received)) return;
-  const highest = Math.max(...supported);
-  const ceiling = received > highest ? `This signer is out of date: it supports ${context} versions up to ${highest}, and Haven sent version ${received}. Update @haven_ai/signer \u2014 rerun the Haven connector (\`npx @haven_ai/connect@alpha\`), which reinstalls the pinned MCP runtime.` : `Unsupported ${context} version ${received}: this signer supports ${supported.join(", ")}.`;
-  throw new sdk.HavenSigningError(
-    `${ceiling} Nothing was signed. Do not rewrite the version field to a supported value: it is part of the Haven-signed binding message, so changing it invalidates the signature and would misrepresent what Haven authorised.`
-  );
+
+// src/consent.ts
+var SIGNER_ACK_ENV = "HAVEN_SIGNER_ACK";
+var SIGNER_CONSENT_SURFACE_VERSION = 2;
+function computeSignerConsentHash(input) {
+  const identity = [
+    input.delegateAddress.toLowerCase(),
+    (input.safeAddress ?? "").toLowerCase(),
+    input.agentId ?? "",
+    input.chainId ?? "",
+    input.network ?? ""
+  ].join("|");
+  const toolCanonical = [...input.toolNames].sort().join(",");
+  return crypto.createHash("sha256").update(`${identity}
+${toolCanonical}
+surface:v${SIGNER_CONSENT_SURFACE_VERSION}`).digest("hex").slice(0, 16);
 }
-function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "hash") {
-  assertExpectedShape(expected);
-  if (!trustedSigner) {
-    throw new sdk.HavenSigningError(
-      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding hashes."
-    );
-  }
-  if (expected.auth) {
-    assertSupportedBindingVersion(
-      expected.auth.version,
-      SUPPORTED_X402_EXPECTED_VERSIONS,
-      "x402 expected context"
-    );
-  }
-  if (expected.payloadHash.toLowerCase() !== payloadHash.toLowerCase()) {
-    throw new sdk.HavenSigningError("x402 expected context does not match the funding hash being signed.");
-  }
-  if (mode === "hash" && expected.typedDataHash) {
-    throw new sdk.HavenSigningError(
-      "This x402 funding intent commits to EIP-712 typed data, so its bare hash must not be raw-signed \u2014 the account would reject that signature on-chain. Sign sign_data.typed_data instead."
-    );
+function renderSignerConsentBlock(input, hash) {
+  const lines = [
+    "",
+    "------------------------------------------------------------",
+    "Haven edge signer - first-launch consent",
+    "------------------------------------------------------------",
+    "",
+    `Delegate address: ${input.delegateAddress}`
+  ];
+  lines.push(`Haven wallet:     ${input.safeAddress ?? "not provided to this signer"}`);
+  if (input.agentId) lines.push(`Agent ID:         ${input.agentId}`);
+  if (typeof input.chainId === "number") lines.push(`Chain ID:         ${input.chainId}`);
+  if (input.network) lines.push(`Network:          ${input.network}`);
+  lines.push("");
+  lines.push("This local signer holds the delegate key on this machine and signs");
+  lines.push("payment payloads or x402 merchant headers for the delegate address above.");
+  lines.push("Its one network use is a read-only fetch of a pending payment's signing");
+  lines.push("payload from Haven, authenticated with the agent credential stored next to");
+  lines.push("this signer's key file - it never sends the key, a signature, or anything");
+  lines.push("else outbound, and it cannot show a live allowance summary.");
+  lines.push("On-chain Safe rules remain the real spend gate, and the wallet owner can");
+  lines.push("pause or revoke agent authority outside this signer.");
+  lines.push("");
+  lines.push("Tools this signer will expose to your agent runtime:");
+  for (const name of input.toolNames) {
+    lines.push(`  - ${name}`);
+    lines.push(`      ${toolDescriptions[name]}`);
   }
-  if (mode === "typed-data" && !expected.typedDataHash) {
-    throw new sdk.HavenSigningError(
-      "Refusing to sign typed data under an expected context that does not commit to it. Haven must return a v2 x402 expected context (with typedDataHash) for a delegation-rail intent."
+  lines.push("");
+  lines.push("A local audit entry is appended for every signing operation. Audit entries");
+  lines.push("record timestamp, tool, payload hash, and delegate address; never the key,");
+  lines.push("signature, or x402 payment header.");
+  lines.push("");
+  lines.push(`Consent hash: ${hash}`);
+  lines.push("");
+  lines.push("To acknowledge, EITHER:");
+  lines.push(`  - set ${SIGNER_ACK_ENV}=${hash} in this process's environment, OR`);
+  lines.push("  - re-run with --ack to write the acknowledgement next to your");
+  lines.push("    credential file (sidecar <credentials>.signer-ack.json).");
+  lines.push("");
+  lines.push("------------------------------------------------------------");
+  lines.push("");
+  return lines.join("\n");
+}
+async function ensureSignerConsent(input, options = {}) {
+  const env = options.env ?? process.env;
+  const out = options.out ?? process.stderr;
+  const hash = computeSignerConsentHash(input);
+  const envAck = env[SIGNER_ACK_ENV];
+  if (typeof envAck === "string" && envAck.length > 0) {
+    if (envAck === hash) return { ok: true, hash, reason: "env_var_match" };
+    out.write(renderSignerConsentBlock(input, hash));
+    out.write(
+      `${SIGNER_ACK_ENV} was set but did not match the current signer consent hash.
+Expected: ${hash}
+Got:      ${envAck}
+Re-acknowledge with the new hash above, or run with --ack.
+
+`
     );
+    return { ok: false, hash, reason: "env_var_mismatch" };
   }
-  const message = sdk.buildX402ExpectedMessage({
-    paymentId: expected.paymentId,
-    payloadHash: expected.payloadHash,
-    resourceUrl: expected.resourceUrl,
-    merchantTo: expected.merchantTo,
-    amount: expected.amount,
-    asset: expected.asset,
-    network: expected.network,
-    expiresAt: expected.expiresAt,
-    typedDataHash: expected.typedDataHash
-  });
-  const expectedVersion = expected.typedDataHash ? 2 : 1;
-  if (expected.auth?.version !== expectedVersion || expected.auth.message !== message) {
-    throw new sdk.HavenSigningError("x402 expected context authentication message is invalid.");
-  }
-  if (!sameAddress(expected.auth.signer, trustedSigner)) {
-    throw new sdk.HavenSigningError("x402 expected context was not signed by the configured Haven signer.");
+  const ackPath = sidecarPath(options.credentialsPath);
+  if (ackPath) {
+    const stored = await readAckFile(ackPath);
+    if (stored?.ack === hash) return { ok: true, hash, reason: "ack_file_match" };
   }
-  if (!sdk.verifySignature(viem.hashMessage(message), expected.auth.signature, trustedSigner)) {
-    throw new sdk.HavenSigningError("x402 expected context signature could not be verified.");
+  if (options.writeAck && ackPath) {
+    out.write(renderSignerConsentBlock(input, hash));
+    await writeAckFile(ackPath, hash);
+    out.write(`Wrote acknowledgement to ${ackPath}
+
+`);
+    return { ok: true, hash, reason: "wrote_ack_file" };
   }
+  out.write(renderSignerConsentBlock(input, hash));
+  return { ok: false, hash, reason: "no_acknowledgement" };
 }
-function assertX402PaymentWindowOpen(expected) {
-  if (!expected.expiresAt) return;
-  const expiresAtMs = Date.parse(expected.expiresAt);
-  if (Number.isNaN(expiresAtMs)) {
-    throw new sdk.HavenSigningError("x402 expected context expiresAt is not a valid ISO timestamp.");
-  }
-  if (expiresAtMs <= Date.now()) {
-    throw new sdk.HavenError(
-      "The x402 payment window expired before the merchant header could be signed. Re-quote with haven_pay_mcp_tool using the same idempotency_key before trying again.",
-      sdk.AgentPaymentFailureCode.PaymentWindowExpired,
-      410,
-      expected.paymentId
-    );
+function registeredSignerToolNames() {
+  return Object.keys(toolSchemas);
+}
+function sidecarPath(credentialsPath) {
+  if (!credentialsPath) return null;
+  return path.resolve(`${credentialsPath}.signer-ack.json`);
+}
+async function readAckFile(path) {
+  try {
+    const raw = await promises.readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return { ack: typeof parsed.ack === "string" ? parsed.ack : void 0 };
+  } catch {
+    return null;
   }
 }
-function sameAddress(a, b) {
-  return a.toLowerCase() === b.toLowerCase();
+async function writeAckFile(path$1, hash) {
+  await promises.mkdir(path.dirname(path$1), { recursive: true });
+  await promises.writeFile(
+    path$1,
+    JSON.stringify({ ack: hash, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2),
+    "utf8"
+  );
 }
 async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
   if (path) return loadFromFile(path);
@@ -815,8 +998,9 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.1.18-alpha.0";
+var SIGNER_VERSION = "0.1.20-alpha.0";
 async function resolveSignerRuntime(options = {}) {
+  assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {
     return {
       signer: createEdgeSigner(options.delegateKey, {
@@ -833,7 +1017,13 @@ async function resolveSignerRuntime(options = {}) {
   };
 }
 function buildSignerMcpServer(signer, options = {}) {
-  const server = new mcp_js.McpServer({ name: SIGNER_NAME, version: SIGNER_VERSION });
+  const server = new mcp_js.McpServer(
+    { name: SIGNER_NAME, version: SIGNER_VERSION },
+    {
+      capabilities: signerCapabilityAdvertisement(),
+      instructions: signerInstructions()
+    }
+  );
   const credentialsPath = options.credentials?.sourcePath;
   const handlers = createToolHandlers(signer, {
     audit: {
@@ -841,6 +1031,14 @@ function buildSignerMcpServer(signer, options = {}) {
       delegateAddress: signer.delegateAddress,
       safeAddress: options.credentials?.safeAddress,
       chainId: options.credentials?.chainId
+    },
+    // #1263: the payment_id signing path — the ONLY network call this server
+    // can make, an authenticated read of a signing context from Haven, using
+    // the agent identity the connector stores next to the signer credential.
+    // 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)
     }
   });
   const registerTool = server.tool.bind(server);
@@ -854,6 +1052,14 @@ function buildSignerMcpServer(signer, options = {}) {
   }
   return server;
 }
+function assertSupportedNodeVersion(nodeVersion = process.versions.node) {
+  if (sdk.isSupportedNodeVersion(nodeVersion)) return;
+  const err = new Error(
+    sdk.unsupportedNodeVersionMessage({ subject: "The Haven signer", nodeVersion })
+  );
+  err.code = "HAVEN_SIGNER_UNSUPPORTED_NODE";
+  throw err;
+}
 async function runSignerStdioServer(options = {}) {
   const { signer, credentials } = await resolveSignerRuntime(options);
   if (!options.skipConsent) {