@haven_ai/signer 0.8.1-alpha.0 → 0.10.0-alpha.0

package/dist/cli.cjs

@@ -154,6 +154,8 @@ function createSigningAuditEntry(tool, payloadHash, context, now = /* @__PURE__
   };
   if (context.accountAddress) entry.safe_address = context.accountAddress;
   if (typeof context.chainId === "number") entry.chain_id = context.chainId;
+  if (context.domain !== void 0) entry.domain = context.domain;
+  if (context.nonce !== void 0) entry.nonce = context.nonce;
   return entry;
 }
 function hashPayloadForAudit(payload) {
@@ -677,10 +679,237 @@ async function fetchTaskBudgetSignContext(identity, taskBudgetId, fetchImpl = fe
   }
   return malformed(`unknown purpose '${String(purpose)}'`);
 }
+var SIWX_REFUSED = "SIWX_REFUSED";
+var HavenSiwxRefusedError = class extends edge.HavenSigningError {
+  next_action = edge.AgentPaymentNextAction.StopAndTellUser;
+  step;
+  constructor(message) {
+    super(message);
+    this.code = SIWX_REFUSED;
+    this.name = "HavenSiwxRefusedError";
+    this.step = signerRefusalStep({
+      nextAction: edge.AgentPaymentNextAction.StopAndTellUser,
+      nextTool: null,
+      nextToolOmittedReason: "check the 402 sign-in-with-x challenge and the URL against the refusal above, then call haven_sign_siwx again with corrected inputs \u2014 a challenge that fails validation is never signed"
+    });
+  }
+};
+var SIWX_MAX_AGE_SECONDS = 300;
+var SIWX_CLOCK_SKEW_SECONDS = 30;
+var SIWX_VERSION = "1";
+function refuse(message) {
+  throw new HavenSiwxRefusedError(message);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(info, name) {
+  const value = info[name];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") {
+    refuse(`The sign-in-with-x challenge field "${name}" must be a string.`);
+  }
+  return value;
+}
+function assertSingleLine(value, name) {
+  if (/[\n\r]/.test(value)) {
+    refuse(`The sign-in-with-x challenge field "${name}" contains a line break; EIP-4361 fields are single-line. Refusing \u2014 a line break could smuggle an attacker-chosen line into the signed message.`);
+  }
+}
+function validateSiwxChallenge(input) {
+  const { url, challenge, chainId } = input;
+  const now = input.now ?? /* @__PURE__ */ new Date();
+  if (typeof url !== "string" || url.length === 0) {
+    refuse("url is required: the URL the agent is calling, so the signature is bound to that origin.");
+  }
+  let urlObj;
+  try {
+    urlObj = new URL(url);
+  } catch {
+    refuse("url is not a valid absolute URL.");
+  }
+  if (urlObj.protocol !== "https:") {
+    refuse(
+      `url must be https \u2014 this signer never signs a sign-in bound to a plain-HTTP origin (got '${urlObj.protocol}//').`
+    );
+  }
+  if (!isPlainObject(challenge)) {
+    refuse('challenge must be the sign-in-with-x object from the merchant 402 (extensions["sign-in-with-x"]).');
+  }
+  const hasWrapper = isPlainObject(challenge.info);
+  const info = hasWrapper ? challenge.info : challenge;
+  const supportedChains = hasWrapper ? challenge.supportedChains : challenge.supportedChains;
+  const domain = stringField(info, "domain");
+  if (domain === void 0) refuse("The sign-in-with-x challenge carries no domain.");
+  assertSingleLine(domain, "domain");
+  if (/\s/.test(domain)) {
+    refuse("The sign-in-with-x challenge domain is not a valid authority (contains whitespace).");
+  }
+  if (domain.toLowerCase() !== urlObj.host.toLowerCase()) {
+    refuse(
+      `The challenge domain '${domain}' does not match the host of the URL being called ('${urlObj.host}'). A sign-in is only valid for the origin that issued it.`
+    );
+  }
+  const uri = stringField(info, "uri");
+  if (uri === void 0) refuse("The sign-in-with-x challenge carries no uri.");
+  assertSingleLine(uri, "uri");
+  let uriObj;
+  try {
+    uriObj = new URL(uri);
+  } catch {
+    refuse("The sign-in-with-x challenge uri is not a valid absolute URI.");
+  }
+  if (uriObj.protocol !== urlObj.protocol || uriObj.host.toLowerCase() !== urlObj.host.toLowerCase()) {
+    refuse(
+      `The challenge resource uri origin ('${uriObj.protocol}//${uriObj.host}') does not match the origin of the URL being called ('${urlObj.protocol}//${urlObj.host}').`
+    );
+  }
+  const version = stringField(info, "version");
+  if (version === void 0) {
+    refuse("The sign-in-with-x challenge carries no version; this signer composes CAIP-122 version 1 only.");
+  }
+  if (version !== SIWX_VERSION) {
+    refuse(
+      `The sign-in-with-x challenge version is '${version}'; this signer composes version '${SIWX_VERSION}' only. Update @haven_ai/signer if the spec has moved on.`
+    );
+  }
+  const nonce = stringField(info, "nonce");
+  if (nonce === void 0) {
+    refuse("The sign-in-with-x challenge carries no nonce \u2014 refusing: the nonce is what makes the sign-in single-use.");
+  }
+  if (!/^[A-Za-z0-9]{8,}$/.test(nonce)) {
+    refuse("The sign-in-with-x challenge nonce fails the EIP-4361 grammar (alphanumeric, at least 8 characters).");
+  }
+  const issuedAt = stringField(info, "issuedAt");
+  if (issuedAt === void 0) refuse("The sign-in-with-x challenge carries no issuedAt timestamp.");
+  assertSingleLine(issuedAt, "issuedAt");
+  if (Number.isNaN(Date.parse(issuedAt))) {
+    refuse("The sign-in-with-x challenge issuedAt is not a parseable timestamp.");
+  }
+  const expirationTime = stringField(info, "expirationTime");
+  if (expirationTime === void 0) {
+    refuse(
+      "The sign-in-with-x challenge carries no absolute expirationTime. A relative expirationSeconds is not accepted by this signer \u2014 only a challenge with an absolute expiry window the signer can bound is signed."
+    );
+  }
+  assertSingleLine(expirationTime, "expirationTime");
+  const expiresAtMs = Date.parse(expirationTime);
+  if (Number.isNaN(expiresAtMs)) {
+    refuse("The sign-in-with-x challenge expirationTime is not a parseable timestamp.");
+  }
+  if (expiresAtMs < now.getTime() - SIWX_CLOCK_SKEW_SECONDS * 1e3) {
+    refuse("The sign-in-with-x challenge has already expired (expirationTime is in the past, beyond the clock-skew tolerance). Nothing was signed.");
+  }
+  if (expiresAtMs - now.getTime() > (SIWX_MAX_AGE_SECONDS + SIWX_CLOCK_SKEW_SECONDS) * 1e3) {
+    refuse(
+      `The sign-in-with-x challenge expiry window is longer than the spec's ${SIWX_MAX_AGE_SECONDS}-second max age (beyond the clock-skew tolerance). Refusing to sign a long-lived challenge.`
+    );
+  }
+  const statement = stringField(info, "statement");
+  if (statement !== void 0) assertSingleLine(statement, "statement");
+  const notBefore = stringField(info, "notBefore");
+  if (notBefore !== void 0) {
+    assertSingleLine(notBefore, "notBefore");
+    if (Number.isNaN(Date.parse(notBefore))) {
+      refuse("The sign-in-with-x challenge notBefore is not a parseable timestamp.");
+    }
+  }
+  const requestId = stringField(info, "requestId");
+  if (requestId !== void 0) assertSingleLine(requestId, "requestId");
+  let resources;
+  if (info.resources !== void 0) {
+    if (!Array.isArray(info.resources) || info.resources.some((r) => typeof r !== "string")) {
+      refuse("The sign-in-with-x challenge resources must be an array of URI strings.");
+    }
+    for (const resource of info.resources) {
+      assertSingleLine(resource, "resources[]");
+      try {
+        new URL(resource);
+      } catch {
+        refuse(`The sign-in-with-x challenge resources entry '${resource}' is not a valid absolute URI.`);
+      }
+    }
+    resources = info.resources;
+  }
+  if (typeof chainId !== "number" || !Number.isInteger(chainId) || chainId <= 0) {
+    refuse(
+      "This signer credential carries no chain id, so the signer cannot check the challenge against the chain its delegate key pays on. Re-run the connector to refresh the credential."
+    );
+  }
+  const chainIdCaip2 = `eip155:${chainId}`;
+  if (!Array.isArray(supportedChains) || supportedChains.length === 0) {
+    refuse("The sign-in-with-x challenge carries no supportedChains array.");
+  }
+  const matched = supportedChains.some(
+    (entry) => isPlainObject(entry) && typeof entry.chainId === "string" && entry.chainId.toLowerCase() === chainIdCaip2 && entry.type === "eip191"
+  );
+  if (!matched) {
+    refuse(
+      `The challenge's supportedChains does not offer the credential chain ${chainIdCaip2} with an eip191 signature type \u2014 the delegate EOA cannot answer this challenge.`
+    );
+  }
+  return {
+    domain,
+    uri,
+    version,
+    nonce,
+    issuedAt,
+    expirationTime,
+    statement,
+    notBefore,
+    requestId,
+    resources,
+    chainIdCaip2,
+    numericChainId: chainId
+  };
+}
+function composeSiwxMessage(fields, address) {
+  const suffixLines = [
+    `URI: ${fields.uri}`,
+    `Version: ${fields.version ?? SIWX_VERSION}`,
+    `Chain ID: ${fields.numericChainId}`,
+    `Nonce: ${fields.nonce}`,
+    `Issued At: ${fields.issuedAt}`
+  ];
+  if (fields.expirationTime !== void 0) suffixLines.push(`Expiration Time: ${fields.expirationTime}`);
+  if (fields.notBefore !== void 0) suffixLines.push(`Not Before: ${fields.notBefore}`);
+  if (fields.requestId !== void 0) suffixLines.push(`Request ID: ${fields.requestId}`);
+  if (fields.resources !== void 0) {
+    suffixLines.push(["Resources:", ...fields.resources.map((r) => `- ${r}`)].join("\n"));
+  }
+  let head = [`${fields.domain} wants you to sign in with your Ethereum account:`, address].join("\n");
+  if (fields.statement === void 0) {
+    head += "\n\n";
+  } else {
+    head = [head, fields.statement].join("\n\n") + "\n";
+  }
+  return [head, suffixLines.join("\n")].join("\n");
+}
+function buildSiwxPayload(fields, address, signature) {
+  return {
+    domain: fields.domain,
+    address,
+    statement: fields.statement,
+    uri: fields.uri,
+    version: fields.version ?? SIWX_VERSION,
+    chainId: fields.chainIdCaip2,
+    type: "eip191",
+    nonce: fields.nonce,
+    issuedAt: fields.issuedAt,
+    expirationTime: fields.expirationTime,
+    notBefore: fields.notBefore,
+    requestId: fields.requestId,
+    resources: fields.resources,
+    signature
+  };
+}
+function encodeSiwxHeader(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
 
 // src/tools.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.8.1-alpha.0";
+var SIGNER_VERSION = "0.10.0-alpha.0";
 var UNSUPPORTED_ARGUMENT_MARKER = "HavenSignerUnsupportedArgument:";
 var USEROP_BINDING_MISMATCH = "USEROP_BINDING_MISMATCH";
 var HavenUserOpBindingRefusedError = class extends edge.HavenSigningError {
@@ -843,6 +1072,18 @@ var toolSchemas = {
     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()
+  },
+  haven_sign_siwx: {
+    // #3728: the https URL the agent is calling — the challenge's domain and
+    // resource uri are pinned to THIS origin before anything is signed.
+    url: v3.z.string().min(1),
+    // The merchant's sign-in-with-x challenge. Accepted as EITHER the 402
+    // extension object (payment_required.extensions['sign-in-with-x'] —
+    // { info, supportedChains, schema? }) or the flattened info object the
+    // x402 reference client builds ({ ...info, chainId, type }). Validated
+    // field by field in siwx.ts; the signer composes the EIP-4361 message
+    // itself and never signs a caller-supplied message.
+    challenge: v3.z.record(v3.z.string(), v3.z.unknown())
   }
   // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
@@ -881,8 +1122,10 @@ var X402_SIGN_HEADER_DESCRIPTION = [
   "do not call this tool. 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 }. On your retry set BOTH PAYMENT-SIGNATURE (x402 v2) and",
-  "X-PAYMENT (v1) to <payment_header>; a strict v2 merchant reads only the first.",
+  "Returns { payment_header, retry_headers, accepted }. On your retry set EVERY header named in",
+  "retry_headers to <payment_header> \u2014 the names come from the same rule the wire uses (both",
+  "PAYMENT-SIGNATURE (x402 v2) and X-PAYMENT (v1) on the EIP-3009 bridge; a strict v2 merchant reads",
+  "only the first).",
   "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(" ");
@@ -908,8 +1151,8 @@ var SIGN_X402_DESCRIPTION = [
   "haven_sign, not to this one. payment_header IS the header to use.",
   "Next: for a paid MCP tool, call mcp__haven__haven_settle_mcp_tool. For a direct plain-HTTP x402",
   "merchant (the haven_pay_x402_quote path), relay signature via mcp__haven__haven_submit and then",
-  "retry the original merchant URL YOURSELF, setting BOTH PAYMENT-SIGNATURE (x402 v2) and",
-  "X-PAYMENT (v1) to payment_header \u2014 Haven never contacts that merchant."
+  "retry the original merchant URL YOURSELF, setting EVERY header the result names in",
+  "retry_headers to payment_header \u2014 Haven never sends that merchant the paid request."
 ].join(" ");
 var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
   "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
@@ -921,8 +1164,28 @@ var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
   "when the credential carries one, and otherwise rests on Haven's binding signature. Then it",
   "returns { signature } to hand back to mcp__haven__haven_sweep_delegate to complete recovery."
 ].join(" ");
+var SIGN_SIWX_DESCRIPTION = [
+  "Answer a merchant x402 Sign-In-With-X (SIWX) sign-in challenge with the local delegate key (#3728).",
+  "Use it when a merchant 402 carries a sign-in-with-x extension, or when the merchant documents a",
+  "sign-in route (CAIP-122): pass url \u2014 the FINAL URL the header will be sent to, i.e. after any",
+  "redirects, not the originally requested one \u2014 and challenge, the sign-in-with-x object from the",
+  "402 (extensions['sign-in-with-x'], or the flattened info object). NEVER follow a redirect with",
+  "the SIGN-IN-WITH-X header (or a resulting session token) attached: re-sign for the final origin.",
+  "This signer composes the EIP-4361 message ITSELF from the validated challenge fields and the",
+  "delegate address read from the key \u2014 it never signs a caller-supplied message, and an address",
+  "inside the challenge cannot change whose wallet signs in. It refuses (SIWX_REFUSED) unless the",
+  "challenge domain matches the URL host, its resource uri origin matches the URL origin, the URL is",
+  "https, the nonce is well-formed, the expiry window is at most 5 minutes (plus a small clock-skew",
+  "tolerance), and supportedChains offers the credential chain with an eip191 signature type. This",
+  "tool MOVES NO FUNDS and grants no spend authority: it only proves the delegate wallet is the one",
+  "that paid the merchant. Returns { sign_in_with_x_header } \u2014 retry the merchant request with the",
+  "SIGN-IN-WITH-X header set to that value. The merchant then recognises the delegate wallet as a",
+  "paying customer (a session it mints typically outlives the 5-minute signature; what the session",
+  "reaches is merchant-defined)."
+].join(" ");
 var toolDescriptions = {
   haven_sign: SIGN_DESCRIPTION,
+  haven_sign_siwx: SIGN_SIWX_DESCRIPTION,
   haven_x402_sign_header: X402_SIGN_HEADER_DESCRIPTION,
   haven_sign_x402: SIGN_X402_DESCRIPTION,
   haven_sign_sweep_delegate: SIGN_SWEEP_DELEGATE_DESCRIPTION
@@ -1250,7 +1513,13 @@ function createToolHandlers(signer, options = {}) {
         "haven_x402_sign_header",
         hashPayloadForAudit(args.payment_required)
       );
-      return { payment_header: result.paymentHeader, accepted: result.accepted };
+      return {
+        payment_header: result.paymentHeader,
+        accepted: result.accepted,
+        // #3727: the ready-made retry headers beside the prose — the names
+        // come from the SDK's live rule, never re-derived here.
+        retry_headers: edge.x402RetryHeadersFor(result.paymentHeader)
+      };
     }),
     haven_sign_x402: async (input) => runTool(async () => {
       const args = parseStrictFor("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
@@ -1285,6 +1554,9 @@ function createToolHandlers(signer, options = {}) {
         x402_binding: funding.x402Binding,
         payment_header: header.paymentHeader,
         accepted: header.accepted,
+        // #3727: the ready-made retry headers beside the prose — the names
+        // come from the SDK's live rule, never re-derived here.
+        retry_headers: edge.x402RetryHeadersFor(header.paymentHeader),
         ...clientUpdateField(resolved)
       };
     }),
@@ -1302,15 +1574,35 @@ function createToolHandlers(signer, options = {}) {
         hashPayloadForAudit(args.authorization)
       );
       return { signature: result.signature };
+    }),
+    haven_sign_siwx: async (input) => runTool(async () => {
+      const args = parseStrictFor("haven_sign_siwx", input);
+      const chainId = options.audit?.chainId;
+      const fields = validateSiwxChallenge({
+        url: args.url,
+        challenge: args.challenge,
+        chainId
+      });
+      const message = composeSiwxMessage(fields, signer.delegateAddress);
+      const signature = await signer.signSiwxMessage(message);
+      const header = encodeSiwxHeader(
+        buildSiwxPayload(fields, signer.delegateAddress, signature)
+      );
+      await auditSigning("haven_sign_siwx", hashPayloadForAudit(message), {
+        domain: fields.domain,
+        nonce: fields.nonce
+      });
+      return { sign_in_with_x_header: header };
     })
   };
-  async function auditSigning(tool, payloadHash) {
+  async function auditSigning(tool, payloadHash, extra = {}) {
     if (!options.audit) return;
     const { auditPath, ...context } = options.audit;
     try {
       await appendSigningAuditEntry(
         createSigningAuditEntry(tool, payloadHash, {
           ...context,
+          ...extra,
           delegateAddress: signer.delegateAddress
         }),
         auditPath
@@ -1465,6 +1757,15 @@ function normalizeError(err) {
       ...err.next_tool_omitted_reason ? { next_tool_omitted_reason: err.next_tool_omitted_reason } : {}
     };
   }
+  if (err instanceof HavenSiwxRefusedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
+  }
   if (err instanceof edge.HavenSigningError) {
     return { success: false, code: err.code, message: err.message };
   }
@@ -1501,6 +1802,7 @@ function normalizeError(err) {
 // src/consent.ts
 var toolSummaries = {
   haven_sign: "signs a Haven-prepared payment, task-budget or sub-budget open or close (a UserOp from your own account redeeming a delegation made to it, directly or via a task-budget child; a sub-budget child narrowing your budget for another agent of yours; or an x402 funding intent against a Haven-signed context)",
+  haven_sign_siwx: "signs a merchant x402 Sign-In-With-X sign-in challenge as the delegate wallet \u2014 proves the wallet paid that merchant, moves no funds and grants no spend authority",
   haven_x402_sign_header: "builds and signs the EIP-3009 merchant payment header for an x402 payment",
   haven_sign_x402: "the two above in one call: funding payload + merchant header",
   haven_sign_sweep_delegate: "signs a Haven-prepared gasless sweep of stranded funds back to your own account"
@@ -1540,13 +1842,16 @@ function renderSignerConsentBlock(input, hash) {
   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("payment payloads, x402 merchant headers, or x402 Sign-In-With-X sign-in");
+  lines.push("challenges for the delegate address above. A sign-in challenge proves to a");
+  lines.push("merchant that this wallet paid it before; it moves no funds and grants no");
+  lines.push("spend authority.");
   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("The agent's signed budget delegation is the real spend gate, and the wallet");
-  lines.push("owner can pause or revoke agent authority outside this signer.");
+  lines.push("owner can stop the agent's budget or remove the agent outside this signer.");
   lines.push("");
   lines.push("Tools this signer will expose to your agent runtime (one line each; the");
   lines.push("full agent-facing descriptions are what the runtime sees):");
@@ -1556,7 +1861,7 @@ function renderSignerConsentBlock(input, hash) {
   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("signature, x402 payment header, or sign-in message.");
   lines.push("");
   lines.push(`Consent hash: ${hash}`);
   lines.push("");
@@ -1811,11 +2116,14 @@ function createEdgeSigner(delegateKey, options = {}) {
       const requirements = edge.toStandardPaymentRequirements(paymentRequired, option);
       const { exact } = await loadX402Schemes();
       assertWindowOpenOrRetire();
-      const header = await exact.evm.createPaymentHeader(
-        account,
+      const unsigned = exact.evm.preparePaymentHeader(
+        account.address,
         paymentRequired.x402Version,
         requirements
       );
+      unsigned.payload.authorization.nonce = edge.deriveX402PaymentNonce(expected.paymentId);
+      const signed = await exact.evm.signPaymentHeader(account, requirements, unsigned);
+      const header = exact.evm.encodePayment(signed);
       if (paymentRequired.x402Version < 2) {
         x402Bindings.delete(x402Binding);
         retireX402Binding(x402Binding, "header_built");
@@ -1872,6 +2180,10 @@ function createEdgeSigner(delegateKey, options = {}) {
         );
       }
       return { signature };
+    },
+    async signSiwxMessage(message) {
+      const account = accounts.privateKeyToAccount(delegateKey);
+      return account.signMessage({ message });
     }
   };
 }
@@ -2040,7 +2352,13 @@ function signerCompatibility() {
 function signerCapabilityAdvertisement() {
   return { experimental: { [SIGNER_CAPABILITY_KEY]: signerCompatibility() } };
 }
-function signerInstructions() {
+function signerIdentityLines(identity) {
+  if (!identity?.agentId && !identity?.delegateAddress) return [];
+  const agent = identity.agentId ? `agent id ${identity.agentId}` : "no recorded agent id";
+  const delegate = identity.delegateAddress ? ` and delegate address ${identity.delegateAddress}` : "";
+  return [`This signer is bound to ${agent}${delegate}.`];
+}
+function signerInstructions(identity) {
   const compatibility = signerCompatibility();
   return [
     "Haven edge signer: sign-only tools bound to the local delegate key. It never emits the",
@@ -2049,6 +2367,16 @@ function signerInstructions() {
     "#3271, and delegation-rail x402) or haven_sign_x402 (x402 only) instead of relaying bulky",
     "typed-data payloads yourself.",
     "",
+    ...signerIdentityLines(identity),
+    "When more than one Haven pair is configured, you act as ONE agent per task: if the",
+    "user has not said which (in the request, or a project-level choice they stated), ask",
+    "before any payment tool. Sign only through the signer of the hosted server you called:",
+    "haven-<slug> with haven-signer-<slug>, bare haven with haven-signer, Codex haven with",
+    "haven_signer. Before signing, compare the identity this signer states with",
+    "haven_get_agent (its id and delegateAddress) from that hosted server \u2014 the delegate",
+    "address alone when this signer has no recorded agent id. If they differ, stop and sign",
+    "nothing \u2014 switch to the signer whose identity matches.",
+    "",
     "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(", ")}`,
@@ -2067,28 +2395,36 @@ function signerInstructions() {
     "machine-readable, not just prose: it carries code, supported_versions, received_version, and",
     "fallback fields alongside the message, so you can branch on it directly. Every signer",
     "refusal also carries the next-step family: next_tool_name + next_tool_server_role when a",
-    "hosted tool follows (resolve the role against your own server names), else",
+    "hosted tool follows (resolve the role against your own server names \u2014 with several",
+    "Haven pairs, the hosted server of THIS signer's pair), else",
     "next_tool_omitted_reason saying why not.",
     "",
     "An undeclared top-level argument is refused, not stripped: haven_sign answers",
     "UNSUPPORTED_ARGUMENT with unknown_arguments, signer_version and fallback (the update",
     "command) instead of dropping the key and answering the generic signing error \u2014 if you see",
     "that refusal, this signer predates the argument form you sent. Update the signer; nothing",
-    "was signed, fetched or audited."
+    "was signed, fetched or audited.",
+    "",
+    "Sign-In-With-X (#3728): when a merchant 402 carries a sign-in-with-x extension (or the",
+    "merchant documents a CAIP-122 sign-in route), call haven_sign_siwx with { url, challenge }.",
+    "The signer composes the EIP-4361 message itself from the validated challenge and signs it with",
+    "the delegate key \u2014 it returns { sign_in_with_x_header }; retry the merchant with the",
+    "SIGN-IN-WITH-X header set to that value. This proves the delegate wallet paid the merchant; it",
+    "moves no funds and cannot approve any payment."
   ].join("\n");
 }
 async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
   if (path) return loadFromFile(path);
-  const envKey = stringField(process.env.HAVEN_DELEGATE_KEY);
+  const envKey = stringField2(process.env.HAVEN_DELEGATE_KEY);
   if (envKey) {
     const accountAddress = readAccountAddressEnv(process.env);
     return {
       delegateKey: envKey,
-      agentId: stringField(process.env.HAVEN_AGENT_ID),
+      agentId: stringField2(process.env.HAVEN_AGENT_ID),
       accountAddress,
       chainId: chainIdField(process.env.HAVEN_CHAIN_ID, "HAVEN_CHAIN_ID"),
-      network: stringField(process.env.HAVEN_NETWORK),
-      x402BindingSigner: stringField(process.env.HAVEN_X402_BINDING_SIGNER)
+      network: stringField2(process.env.HAVEN_NETWORK),
+      x402BindingSigner: stringField2(process.env.HAVEN_X402_BINDING_SIGNER)
     };
   }
   throw new Error(
@@ -2111,30 +2447,30 @@ async function loadFromFile(path) {
   } catch {
     throw new Error("Haven credentials must be JSON with a delegate_key field.");
   }
-  const delegateKey = stringField(raw.delegate_key ?? raw.delegateKey);
+  const delegateKey = stringField2(raw.delegate_key ?? raw.delegateKey);
   if (!delegateKey) {
     throw new Error("Haven credentials are missing delegate_key \u2014 the edge signer needs it to sign.");
   }
   const accountAddress = readAccountAddressField(raw);
   return {
     delegateKey,
-    agentId: stringField(raw.agent_id ?? raw.agentId),
+    agentId: stringField2(raw.agent_id ?? raw.agentId),
     accountAddress,
     chainId: chainIdField(raw.chain_id ?? raw.chainId, "chain_id"),
-    network: stringField(raw.network),
-    x402BindingSigner: stringField(
+    network: stringField2(raw.network),
+    x402BindingSigner: stringField2(
       raw.x402_binding_signer ?? raw.x402BindingSigner ?? process.env.HAVEN_X402_BINDING_SIGNER
     ),
     sourcePath: path
   };
 }
 function readAccountAddressField(raw) {
-  return stringField(raw.account_address ?? raw.safe_address ?? raw.safeAddress);
+  return stringField2(raw.account_address ?? raw.safe_address ?? raw.safeAddress);
 }
 function readAccountAddressEnv(env) {
-  const current = stringField(env.HAVEN_ACCOUNT_ADDRESS);
+  const current = stringField2(env.HAVEN_ACCOUNT_ADDRESS);
   for (const name of ["HAVEN_WALLET_ADDRESS", "HAVEN_SAFE_ADDRESS"]) {
-    const retired = stringField(env[name]);
+    const retired = stringField2(env[name]);
     if (!retired) continue;
     if (!current) {
       throw new Error(
@@ -2149,7 +2485,7 @@ function readAccountAddressEnv(env) {
   }
   return current;
 }
-function stringField(value) {
+function stringField2(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function chainIdField(value, label) {
@@ -2203,7 +2539,12 @@ function buildSignerMcpServer(signer, options = {}) {
     { name: SIGNER_NAME, version: SIGNER_VERSION },
     {
       capabilities: signerCapabilityAdvertisement(),
-      instructions: signerInstructions()
+      // #3738: the identity line lets a model holding several Haven pairs
+      // confirm this signer belongs to the hosted server it called.
+      instructions: signerInstructions({
+        agentId: options.credentials?.agentId,
+        delegateAddress: signer.delegateAddress
+      })
     }
   );
   const credentialsPath = options.credentials?.sourcePath;