@haven_ai/signer 0.2.0-alpha.0 → 0.3.0-alpha.0

package/README.md

@@ -187,14 +187,49 @@ what a payload means; they re-derive it.
   the one asymmetry in this list: the signer compares the sweep's `to` against
   the account address **only when the local credential records one**
   (`account_address`, or the pre-#2908 `safe_address` / `safeAddress`, which
-  are read permanently; from the environment, `HAVEN_ACCOUNT_ADDRESS`, or the
-  older `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` until #2914). Run with
+  are read permanently; from the environment, `HAVEN_ACCOUNT_ADDRESS` only —
+  `HAVEN_WALLET_ADDRESS` and `HAVEN_SAFE_ADDRESS` were removed by #2914, so a
+  machine still configured through either records no account address and lands
+  in exactly the degraded case this paragraph describes). Run with
   `HAVEN_DELEGATE_KEY` alone — or with a credential
   whose account address is absent — and there is no local value to compare
   against, so the destination is authenticated by Haven's binding signature and
   the token/chain canonicality check, but not independently re-derived. Prefer
   a credential file that carries the account address.
 
+## Sign-context refusal codes
+
+`{ payment_id }` calls (`haven_sign` / `haven_sign_x402`) fetch the exact
+signing payload from Haven (`GET /x402/:id/sign-context`, see
+[Custody](#custody)). Every refusal on that fetch is a `HavenSignContextError`
+(#3001) — a `HavenSigningError` subclass, so `instanceof HavenSigningError`
+still holds everywhere it did before, but structured like the version-mismatch
+refusal below rather than prose alone: `code`, `next_action`, and — per
+refusal class — `fallback`, `retry_with_new_quote`, `http_status`,
+`backend_error_code`. `message` is unchanged.
+
+| `code` | When | `next_action` | `fallback` | extra |
+|---|---|---|---|---|
+| `SIGN_CONTEXT_TIMEOUT` | The fetch (or its body read) did not finish within `SIGN_CONTEXT_TIMEOUT_MS` | `stop_and_tell_user` | `typed_data_b64` | — |
+| `SIGN_CONTEXT_UNREACHABLE` | The fetch failed before any response (DNS, connection refused, TLS, …) | `stop_and_tell_user` | `typed_data_b64` | — |
+| `SIGN_CONTEXT_MALFORMED` | The response body was missing `sign_data.typed_data` or `x402_expected` (a pre-#1263 backend) | `stop_and_tell_user` | `typed_data_b64` | — |
+| `SIGN_CONTEXT_REFUSED` (410 / `expired`) | The quote's window closed | `payment_window_expired` | — | `retry_with_new_quote: true`, `http_status`, `backend_error_code: 'expired'` |
+| `SIGN_CONTEXT_REFUSED` (other) | Unknown `payment_id` (404), `already_executed` / `not_signable` / `sign_context_unavailable` (409) | `stop_and_tell_user` | — | `http_status`, `backend_error_code` |
+
+`fallback: 'typed_data_b64'` appears only where signing OTHER bytes is a
+remedy — a transport failure or a body this signer could not read. It is
+**not** in the default quote result since #1272: obtain it by re-running the
+SAME quote tool with the SAME `idempotency_key` plus
+`include_signing_payload: true`, then pass `typed_data_b64` (plus
+`payload_hash` / `x402_expected`) instead of `payment_id`. A backend REFUSAL
+carries no fallback: an expired, executed or unsignable intent cannot be
+rescued by re-signing its bytes — an expired one is re-quoted (the same
+`payment_window_expired` + `retry_with_new_quote` the signer emits for
+`PAYMENT_WINDOW_EXPIRED`), the rest stop. These codes are signer-local,
+not part of `@haven_ai/sdk`'s `AgentPaymentFailureCode` taxonomy, since they
+describe a local fetch failure, not a payment-domain outcome, and never reach
+the backend's REST/OpenAPI surface — only this package's MCP tool responses.
+
 ## Custody
 
 The delegate key is read from `HAVEN_DELEGATE_KEY` or a `--credentials` file's
@@ -207,7 +242,14 @@ read.** Since [#1263](https://github.com/d-hinders/Haven-AI/issues/1263) the
 authenticated, read-only `GET /x402/:payment_id/sign-context` against Haven, so
 that agents never have to relay multi-KB EIP-712 payloads through a model's
 context window. **Only the Bearer API key goes out; the delegate key is never
-part of that request or its response.** Nothing else in the package reaches the
+part of that request or its response.** Since #2985 that read is bounded:
+it aborts after `SIGN_CONTEXT_TIMEOUT_MS` (15 s) and reports a
+`HavenSignContextError` naming the timeout and the `typed_data_b64` fallback,
+so a hung backend cannot hang the signer — and the agent — past the funding
+window. Every refusal on this fetch (timeout, unreachable host, a non-ok
+backend response, a malformed body) is structured the same way, not just
+prose — see [Sign-context refusal codes](#sign-context-refusal-codes) below.
+Nothing else in the package reaches the
 network: `haven_x402_sign_header` and `haven_sign_sweep_delegate` never fetch,
 the library surface above (`createEdgeSigner` and its six signing methods, over
 the network-free `src/core.ts`) never fetches, and passing the payload as

package/dist/cli.cjs

@@ -30,7 +30,7 @@ function createSigningAuditEntry(tool, payloadHash, context, now = /* @__PURE__
     payload_hash: payloadHash,
     delegate_address: context.delegateAddress
   };
-  if (context.safeAddress) entry.safe_address = context.safeAddress;
+  if (context.accountAddress) entry.safe_address = context.accountAddress;
   if (typeof context.chainId === "number") entry.chain_id = context.chainId;
   return entry;
 }
@@ -534,6 +534,49 @@ function signerInstructions() {
     "fallback fields alongside the message, so you can branch on it directly."
   ].join("\n");
 }
+var HavenSignContextError = class extends sdk.HavenSigningError {
+  /**
+   * #3001 / #3010 review: the recovery path, when signing OTHER bytes is
+   * actually a remedy — a transport failure (timeout, unreachable) or a
+   * body this signer could not read. `typed_data_b64` is NOT in the default
+   * quote result since #1272: obtain it by re-running the SAME quote tool
+   * with the SAME idempotency_key plus `include_signing_payload: true`.
+   * Absent on a backend REFUSAL: an expired, executed or unsignable intent
+   * cannot be rescued by re-signing its bytes.
+   */
+  fallback;
+  /**
+   * #3001: `AgentPaymentNextAction` values the signer already emits — the
+   * version-mismatch refusal's `stop_and_tell_user` for the classes where
+   * retrying the same call cannot help, and `payment_window_expired` (with
+   * `retry_with_new_quote`) for the backend's 410 `expired`, exactly as the
+   * plain `HavenError` branch already does for that code.
+   */
+  next_action;
+  retry_with_new_quote;
+  /** Present only for `SIGN_CONTEXT_REFUSED` (the backend's HTTP status). */
+  http_status;
+  /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
+  backend_error_code;
+  constructor(message, code, refusal) {
+    super(message);
+    this.code = code;
+    this.name = "HavenSignContextError";
+    if (code === "SIGN_CONTEXT_REFUSED") {
+      this.http_status = refusal?.httpStatus;
+      this.backend_error_code = refusal?.errorCode;
+      if (refusal?.httpStatus === 410 || refusal?.errorCode === "expired") {
+        this.next_action = sdk.AgentPaymentNextAction.PaymentWindowExpired;
+        this.retry_with_new_quote = true;
+      } else {
+        this.next_action = sdk.AgentPaymentNextAction.StopAndTellUser;
+      }
+    } else {
+      this.fallback = "typed_data_b64";
+      this.next_action = sdk.AgentPaymentNextAction.StopAndTellUser;
+    }
+  }
+};
 async function loadHavenIdentity(credentialsPath) {
   if (!credentialsPath) return null;
   try {
@@ -548,30 +591,50 @@ async function loadHavenIdentity(credentialsPath) {
     return null;
   }
 }
-async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch) {
+var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
+async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
   let response;
   try {
     response = await fetchImpl(
       `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
-      { headers: { Authorization: `Bearer ${identity.apiKey}` } }
+      {
+        headers: { Authorization: `Bearer ${identity.apiKey}` },
+        signal: AbortSignal.timeout(timeoutMs)
+      }
     );
   } 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.`
+    const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+    throw new HavenSignContextError(
+      timedOut ? `Haven did not answer the signing-context fetch for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.` : `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.`,
+      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE"
     );
   }
-  const body = await response.json().catch(() => ({}));
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+      throw new HavenSignContextError(
+        `Haven did not finish sending the signing context for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.`,
+        "SIGN_CONTEXT_TIMEOUT"
+      );
+    }
+    body = {};
+  }
   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." : "")
+    throw new HavenSignContextError(
+      `Haven refused the signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 check the payment_id came from this agent\u2019s own quote." : response.status === 410 ? " Re-run the quote with the same idempotency key, then sign the fresh payment_id." : ""),
+      "SIGN_CONTEXT_REFUSED",
+      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 }
     );
   }
   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."
+    throw new HavenSignContextError(
+      "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.",
+      "SIGN_CONTEXT_MALFORMED"
     );
   }
   const paymentRequired = body.payment_required;
@@ -922,7 +985,7 @@ function createToolHandlers(signer, options = {}) {
         authorization: args.authorization,
         expectedAuth: args.expected_auth,
         // Cross-check `to` against the Safe in the local credential when present.
-        expectedSafe: options.audit?.safeAddress
+        expectedSafe: options.audit?.accountAddress
       });
       await auditSigning(
         "haven_sign_sweep_delegate",
@@ -1002,6 +1065,18 @@ function normalizeError(err) {
       next_action: sdk.AgentPaymentNextAction.StopAndTellUser
     };
   }
+  if (err instanceof HavenSignContextError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...err.fallback !== void 0 ? { fallback: err.fallback } : {},
+      ...err.retry_with_new_quote ? { retry_with_new_quote: true } : {},
+      ...err.http_status !== void 0 ? { http_status: err.http_status } : {},
+      ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {}
+    };
+  }
   if (err instanceof sdk.HavenSigningError) {
     return { success: false, code: err.code, message: err.message };
   }
@@ -1035,7 +1110,7 @@ var SIGNER_CONSENT_SURFACE_VERSION = 2;
 function computeSignerConsentHash(input) {
   const identity = [
     input.delegateAddress.toLowerCase(),
-    (input.safeAddress ?? "").toLowerCase(),
+    (input.accountAddress ?? "").toLowerCase(),
     input.agentId ?? "",
     input.chainId ?? "",
     input.network ?? ""
@@ -1054,7 +1129,7 @@ function renderSignerConsentBlock(input, hash) {
     "",
     `Delegate address: ${input.delegateAddress}`
   ];
-  lines.push(`Haven wallet:     ${input.safeAddress ?? "not provided to this signer"}`);
+  lines.push(`Haven wallet:     ${input.accountAddress ?? "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}`);
@@ -1156,7 +1231,6 @@ async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
       delegateKey: envKey,
       agentId: stringField(process.env.HAVEN_AGENT_ID),
       accountAddress,
-      safeAddress: 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)
@@ -1191,7 +1265,6 @@ async function loadFromFile(path) {
     delegateKey,
     agentId: stringField(raw.agent_id ?? raw.agentId),
     accountAddress,
-    safeAddress: accountAddress,
     chainId: chainIdField(raw.chain_id ?? raw.chainId, "chain_id"),
     network: stringField(raw.network),
     x402BindingSigner: stringField(
@@ -1204,7 +1277,22 @@ function readAccountAddressField(raw) {
   return stringField(raw.account_address ?? raw.safe_address ?? raw.safeAddress);
 }
 function readAccountAddressEnv(env) {
-  return stringField(env.HAVEN_ACCOUNT_ADDRESS ?? env.HAVEN_WALLET_ADDRESS ?? env.HAVEN_SAFE_ADDRESS);
+  const current = stringField(env.HAVEN_ACCOUNT_ADDRESS);
+  for (const name of ["HAVEN_WALLET_ADDRESS", "HAVEN_SAFE_ADDRESS"]) {
+    const retired = stringField(env[name]);
+    if (!retired) continue;
+    if (!current) {
+      throw new Error(
+        `${name} is retired (#2906) \u2014 Haven accounts are addressed as accounts, not Safes. Set HAVEN_ACCOUNT_ADDRESS to the same value. Refusing rather than ignoring it, because an unset account address silently skips the sweep-destination check.`
+      );
+    }
+    if (retired.toLowerCase() !== current.toLowerCase()) {
+      throw new Error(
+        `${name} and HAVEN_ACCOUNT_ADDRESS were both set to different addresses. Remove the retired name, or make them match \u2014 picking one silently would hide the mismatch.`
+      );
+    }
+  }
+  return current;
 }
 function stringField(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -1247,7 +1335,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.2.0-alpha.0";
+var SIGNER_VERSION = "0.3.0-alpha.0";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {
@@ -1282,7 +1370,7 @@ function buildSignerMcpServer(signer, options = {}) {
     audit: {
       auditPath: options.auditPath ?? defaultSigningAuditPath(credentialsPath),
       delegateAddress: signer.delegateAddress,
-      safeAddress: options.credentials?.accountAddress ?? options.credentials?.safeAddress,
+      accountAddress: options.credentials?.accountAddress,
       chainId: options.credentials?.chainId
     },
     // #1263: the payment_id signing path — the ONLY network call this server
@@ -1332,7 +1420,7 @@ async function runSignerConsentGate(signer, credentials, options) {
   return ensureSignerConsent(
     {
       delegateAddress: signer.delegateAddress,
-      safeAddress: credentials?.accountAddress ?? credentials?.safeAddress,
+      accountAddress: credentials?.accountAddress,
       agentId: credentials?.agentId,
       chainId: credentials?.chainId,
       network: credentials?.network,