@haven_ai/signer 0.1.32-alpha.0 → 0.1.34-alpha.0

package/README.md

@@ -5,7 +5,7 @@ that's very nearly all it does. It pairs with the hosted, keyless
 `@haven_ai/mcp-server`: the hosted server identifies the agent, constructs
 unsigned payloads and relays signatures; this one signs. **The delegate key
 never leaves this process** — it is not part of any request or response, and
-only signatures (and the standard x402 `X-PAYMENT` header) ever come out.
+only signatures (and the standard x402 merchant payment header) ever come out.
 
 Design: [`docs/architecture/07-edge-signer.md`](../../docs/architecture/07-edge-signer.md).
 Contract: [`docs/architecture/06-hosted-mcp-connect-flow.md`](../../docs/architecture/06-hosted-mcp-connect-flow.md).
@@ -44,7 +44,7 @@ It exposes four stdio MCP tools, all sign-only:
 |---|---|---|
 | `haven_sign` | Sign one payment. Preferred form is `{ payment_id }` alone — the signer fetches the exact payload itself. Signs an EIP-712 typed-data payload on the delegation rail (a redemption, or an erc7710 settlement child), or a bare `payload_hash` on a v1 context; for the EIP-3009 x402 bridge it also records the funding context and returns a binding | `{ signature }` or `{ signature, x402_binding }` |
 | `haven_sign_x402` | One-shot x402: funding signature **and** the merchant header in a single local call (`haven_sign` + `haven_x402_sign_header`). `{ payment_id }` alone is the preferred call | `{ signature, x402_binding, payment_header, accepted }` |
-| `haven_x402_sign_header` | Build + sign the EIP-3009 `X-PAYMENT` header, only when the fresh merchant `payment_required` matches the recorded `x402_binding` | `{ payment_header, accepted }` |
+| `haven_x402_sign_header` | Build + sign the EIP-3009 merchant payment header, only when the fresh merchant `payment_required` matches the recorded `x402_binding` | `{ payment_header, accepted }` |
 | `haven_sign_sweep_delegate` | Sign a Haven-prepared gasless EIP-3009 sweep that recovers stranded funds from the delegate wallet back to your own account. Never broadcasts | `{ signature }` |
 
 The `initialize` handshake advertises which binding versions this signer
@@ -105,7 +105,9 @@ no delegate hot balance and no `haven_x402_sign_header` step:
 hosted:  haven_pay_x402_quote      -> settlement child + settlement_scheme: erc7710
 local:   haven_sign { payment_id } -> child signature (caveats verified locally)
 hosted:  haven_submit { settlement_scheme: "erc7710" } -> payment_header
-agent:   retry merchant with X-PAYMENT
+agent:   retry merchant, setting PAYMENT-SIGNATURE ONLY (never X-PAYMENT:
+         this header carries a delegation chain and duplicating it is
+         refused with HTTP 431)
 ```
 
 x402 — **EIP-3009 bridge**, the fallback for merchants without facilitator-side
@@ -116,8 +118,9 @@ bounded funding leg:
 hosted:  haven_pay_x402_quote     -> { payment_id, payload_hash, x402.expected }
 local:   haven_sign + expected    -> funding signature + x402_binding
 hosted:  haven_submit             -> funds account -> delegate EOA
-local:   haven_x402_sign_header   -> X-PAYMENT header only if binding matches
-agent:   retry merchant with X-PAYMENT
+local:   haven_x402_sign_header   -> payment header only if binding matches
+agent:   retry merchant, setting BOTH PAYMENT-SIGNATURE + X-PAYMENT
+         (both names are correct HERE — the bridged header is small)
 ```
 
 On the bridge, pass `x402.expected` from the hosted quote unchanged into the
@@ -129,7 +132,7 @@ challenge has a different amount, merchant recipient, resource URL, token asset
 or network than the recorded funding intent, refuses an expired window, and
 consumes the binding after one header.
 
-The `X-PAYMENT` header's validity window starts when it is signed, not when
+The merchant payment header's validity window starts when it is signed, not when
 funding confirms — so relay it promptly.
 
 ## What the signer refuses to sign

package/dist/cli.cjs

@@ -184,6 +184,15 @@ function createEdgeSigner(delegateKey, options = {}) {
     );
   }
   const x402Bindings = /* @__PURE__ */ new Map();
+  const retiredX402Bindings = /* @__PURE__ */ new Map();
+  const RETIRED_BINDING_MEMORY = 64;
+  function retireX402Binding(id, reason) {
+    retiredX402Bindings.set(id, reason);
+    if (retiredX402Bindings.size > RETIRED_BINDING_MEMORY) {
+      const oldest = retiredX402Bindings.keys().next();
+      if (!oldest.done) retiredX402Bindings.delete(oldest.value);
+    }
+  }
   function signAndVerify(hash) {
     const signature = sdk.signHash(delegateKey, hash);
     if (!sdk.verifySignature(hash, signature, delegateAddress)) {
@@ -249,14 +258,26 @@ function createEdgeSigner(delegateKey, options = {}) {
     async buildX402PaymentHeader(paymentRequired, x402Binding) {
       const expected = x402Bindings.get(x402Binding);
       if (!expected) {
+        const retired = retiredX402Bindings.get(x402Binding);
+        if (retired === "header_built") {
+          throw new sdk.HavenSigningError(
+            "This x402 binding was already used to build a merchant header. Bindings are single-use. If you called haven_sign_x402, it already returned the payment_header \u2014 retry the merchant with THAT header instead of building another; haven_x402_sign_header is the follow-up to haven_sign, not to haven_sign_x402. If you no longer have the header, re-run the quote tool with the same idempotency_key."
+          );
+        }
+        if (retired === "window_expired") {
+          throw new sdk.HavenSigningError(
+            "This x402 binding was retired because its payment window closed before a merchant header could be built \u2014 no header exists to retry with. Re-run the quote tool with the same idempotency_key to get a fresh window, then sign again."
+          );
+        }
         throw new sdk.HavenSigningError(
-          "x402 funding binding is required before signing a merchant header. Sign the hosted funding hash with x402_expected first."
+          "x402 funding binding is required before signing a merchant header. Sign the hosted funding hash with x402_expected first (haven_sign returns a binding this tool can use). A binding is also lost when the signer process restarts, since bindings live in memory only \u2014 re-sign to mint a fresh one."
         );
       }
       try {
         assertX402PaymentWindowOpen(expected);
       } catch (err) {
         x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "window_expired");
         throw err;
       }
       const option = sdk.selectStandardPaymentOption(paymentRequired.accepts);
@@ -276,18 +297,18 @@ function createEdgeSigner(delegateKey, options = {}) {
       );
       if (paymentRequired.x402Version < 2) {
         x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
         return { paymentHeader: header, accepted: option };
       }
       try {
         const payment = sdk.decodeBase64Json(header);
-        const wrapped = sdk.encodeBase64Json({
-          x402Version: paymentRequired.x402Version,
-          accepted: option,
-          payload: payment.payload
-        });
+        const wrapped = sdk.encodeBase64Json(
+          sdk.x402V2PaymentEnvelope(paymentRequired, option, payment.payload)
+        );
         return { paymentHeader: wrapped, accepted: option };
       } finally {
         x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
       }
     },
     async signSweepAuthorization({
@@ -392,7 +413,7 @@ function assertSupportedBindingVersion(received, supported, context) {
   const ceiling = outOfDate ? `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(", ")}.`;
   const fallback = outOfDate ? sdk.SIGNER_UPDATE_FALLBACK : `This ${context} version (${received}) is older than what this signer enforces (${supported.join(", ")}) \u2014 updating @haven_ai/signer will not restore it. Nothing was signed or spent; stop and tell the user rather than retrying.`;
   throw new sdk.HavenUnsupportedSignerVersionError(
-    `${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.`,
+    `${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 declared.`,
     code,
     supported,
     received,
@@ -689,19 +710,23 @@ var SIGN_DESCRIPTION = [
   "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.",
+  "Build and sign the EIP-3009 merchant 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",
+  "returned by haven_sign. It must be haven_sign \u2014 NOT haven_sign_x402, which is a",
+  "one-shot that builds the header itself and spends its own binding doing so. If you called",
+  "haven_sign_x402, its result already carries payment_header; retry the merchant with that and",
+  "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 }. Set X-PAYMENT: <payment_header> on your retry to the",
-  "merchant. Only call after haven_submit has confirmed the funding step (nextAction=none or",
+  "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.",
+  "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",
+  "merchant 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 JUST payment_id \u2014 PREFERRED (#1263, #1355): this signer fetches the exact signing",
   "payload, expected context, and merchant payment_required from Haven itself, so nothing bulky",
@@ -716,7 +741,13 @@ var SIGN_X402_DESCRIPTION = [
   "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."
+  "The returned x402_binding is ALREADY SPENT \u2014 this tool consumed it building payment_header \u2014",
+  "so never pass it to mcp__haven-signer__haven_x402_sign_header; that tool is the follow-up to",
+  "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."
 ].join(" ");
 var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
   "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
@@ -1206,7 +1237,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.1.32-alpha.0";
+var SIGNER_VERSION = "0.1.34-alpha.0";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {