@haven_ai/signer 0.1.31-alpha.0 → 0.1.33-alpha.0

package/README.md

@@ -1,17 +1,31 @@
 # @haven_ai/signer
 
 The Haven **edge signer**. It holds the delegate key locally and signs — and
-that's all it does. It pairs with the hosted, keyless `@haven_ai/mcp-server`:
-the hosted server constructs and relays, this signs. The key never leaves this
-process, and only signatures (and the standard x402 header) ever come out.
+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 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).
 
+Requires **Node >= 22**; the signer refuses to start on anything older, before
+it reads a key.
+
 ## Two ways to use it
 
 **As a local MCP signer** (for Claude Desktop / Code / Cursor) — run it
-alongside the hosted Haven connection:
+alongside the hosted Haven connection. The supported install is the connector
+the Haven dashboard hands out, which writes the MCP config and pins the
+runtime:
+
+```sh
+npx @haven_ai/connect@alpha
+```
+
+Rerunning it is also the documented fix for a signer that has fallen behind the
+backend's expected-context version. To run the signer directly:
 
 ```sh
 HAVEN_DELEGATE_KEY=0x... npx @haven_ai/signer
@@ -24,12 +38,22 @@ metadata found in the credential file, and the sign-only tool list. It refuses
 to start until acknowledged with either `HAVEN_SIGNER_ACK=<hash>` or
 `npx @haven_ai/signer --credentials /path/to/haven-agent.json --ack`.
 
-It exposes two stdio MCP tools:
+It exposes four stdio MCP tools, all sign-only:
 
 | Tool | Does | Emits |
 |---|---|---|
-| `haven_sign` | Sign the `payload_hash` from `haven_pay` / `haven_x402_authorize`; for x402, record `x402.expected` and return a binding | `{ signature }` or `{ signature, x402_binding }` |
-| `haven_x402_sign_header` | Build + sign the EIP-3009 `X-PAYMENT` header only when `payment_required` matches the recorded `x402_binding` | `{ payment_header }` |
+| `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 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
+understands, under `capabilities.experimental['haven/signer-compatibility']`
+and in the MCP `instructions` string. Both are **derived** from
+`SUPPORTED_X402_EXPECTED_VERSIONS` / `SUPPORTED_SWEEP_BINDING_VERSIONS` in
+`src/core.ts` — the same constants the signing path enforces — so this README
+deliberately does not restate the numbers. Read them from the handshake, or
+from those constants.
 
 **As a library** (for SDK / autonomous agents):
 
@@ -37,54 +61,135 @@ It exposes two stdio MCP tools:
 import { createEdgeSigner } from '@haven_ai/signer'
 
 const signer = createEdgeSigner(process.env.HAVEN_DELEGATE_KEY!)
-const signature = signer.signPaymentHash(payloadHash)
-const funding = signer.signX402FundingHash(payloadHash, {
-  resourceUrl,
-  merchantTo,
-  amount,
-  asset,
-  network,
-  auth,
-})
-const { paymentHeader } = await signer.buildX402PaymentHeader(paymentRequired, funding.x402Binding)
+
+// Delegation-rail direct payment: sign the EIP-712 typed data the account
+// validates — not the bare ERC-4337 hash.
+const signature = await signer.signDelegationTypedData(typedData)
+
+// x402, EIP-3009 bridge: sign the funding leg, then the merchant header.
+const funding = await signer.signX402FundingTypedData(fundingTypedData, expected)
+const { paymentHeader } = await signer.buildX402PaymentHeader(
+  paymentRequired,
+  funding.x402Binding,
+)
 ```
 
+The signer also exposes `signPaymentHash(hash)` (raw ECDSA over a legacy
+AllowanceModule funding/transfer hash) and `signX402FundingHash(hash, expected)`
+for v1 contexts, and `signSweepAuthorization(input)` for the gasless sweep. All
+five are methods on the object `createEdgeSigner` returns, not standalone
+exports.
+
 ## Orchestration
 
+Direct payment:
+
+```
+hosted:  haven_pay                -> { payment_id, payload to sign }
+local:   haven_sign               -> { signature }
+hosted:  haven_submit             -> { status, tx_hash }
+```
+
+On the delegation rail the payload is the EIP-712 typed data the account
+validates, not the bare ERC-4337 hash. Note the trust-model asymmetry: this
+direct leg has no Haven-signed expected context to verify against, so the
+authority boundary is the account's on-chain caveat enforcers rather than a
+client-side gate — unlike the x402 legs below.
+
+x402 — **erc7710 direct settlement**, the preferred scheme when the account is
+on the delegation rail and the merchant advertises
+`extra.assetTransferMethod: "erc7710"`. There is **no funding leg**, so there is
+no delegate hot balance and no `haven_x402_sign_header` step:
+
 ```
-hosted:  haven_pay              -> { payment_id, payload_hash }
-local:   haven_sign             -> { signature }
-hosted:  haven_submit           -> { status, tx_hash }
+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, setting PAYMENT-SIGNATURE ONLY (never X-PAYMENT:
+         this header carries a delegation chain and duplicating it is
+         refused with HTTP 431)
 ```
 
-x402 (two delegate signatures, both local):
+x402 — **EIP-3009 bridge**, the fallback for merchants without facilitator-side
+erc7710 support (still most of them). Two local delegate signatures, and a
+bounded funding leg:
 
 ```
-hosted:  haven_x402_authorize   -> { payment_id, payload_hash, x402.expected }
-local:   haven_sign + expected  -> funding signature + x402_binding
-hosted:  haven_submit           -> funds Safe -> delegate EOA
-local:   haven_x402_sign_header -> X-PAYMENT header only if binding matches
-agent:   retry merchant with X-PAYMENT
+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   -> 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)
 ```
 
-For x402, pass `x402.expected` from the hosted `haven_x402_authorize` response
-unchanged into the local `haven_sign` call. The signer records that context and
-returns a process-local `x402_binding`; pass that binding into
-`haven_x402_sign_header` after `haven_submit` confirms. The signer refuses to
-authorize the merchant header when the fresh merchant challenge has a different
-amount, merchant recipient, resource URL, token asset, or network than the
-recorded funding intent, and consumes the binding after one successful header.
-The expected context must also carry Haven's `auth` signature; configure
-`HAVEN_X402_BINDING_SIGNER` (or `x402_binding_signer` in the credential file) so
-the signer can reject locally invented or tampered x402 contexts before signing
-the funding hash.
+On the bridge, pass `x402.expected` from the hosted quote unchanged into the
+local `haven_sign` call, or just pass `{ payment_id }` and let the signer fetch
+it. The signer records that context and returns a process-local `x402_binding`;
+pass that binding into `haven_x402_sign_header` after `haven_submit` confirms.
+The signer refuses to authorize the merchant header when the fresh merchant
+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 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
+
+These are local, independent checks. They do not trust Haven's assertion about
+what a payload means; they re-derive it.
+
+- **Unauthenticated context.** The expected context must carry Haven's `auth`
+  signature over it. Configure `HAVEN_X402_BINDING_SIGNER` (or
+  `x402_binding_signer` in the credential file) so the signer can reject
+  locally invented or tampered contexts before signing anything.
+- **Wrong signing mode.** The *context* selects the path, never the caller's
+  arguments: a context that commits to a typed-data digest requires the typed
+  data, one that does not requires the bare hash. A mismatch is refused rather
+  than signed into an on-chain failure.
+- **Another agent's quote.** A context naming a `payer_delegate` that is not
+  this signer's own delegate is refused.
+- **An unbound delegation payload.** Typed data with `primaryType: "Delegation"`
+  is never raw-signed without a context binding it.
+- **An erc7710 settlement child whose caveats do not match what Haven declared.**
+  The signer re-derives the child's meaning from its own pinned
+  `DelegationManager` and caveat-enforcer addresses (cross-checked against
+  `@metamask/smart-accounts-kit` by a test, never fetched from Haven, which
+  would make the check circular): the payee pin, the exact token and amount,
+  the chain, and a settlement window bounded at 600 seconds. Extra caveats are
+  allowed — top-level caveats are AND-ed during redemption, so an unrecognised
+  one can only add a constraint.
+- **A binding version it does not understand.** The refusal is machine-readable
+  — `code`, `supported_versions`, `received_version`, `fallback` — and names
+  updating the signer as the fix.
+- **A sweep that does not move funds out of this delegate's own key** — the
+  `from` check is unconditional. The **destination** check is not, and this is
+  the one asymmetry in this list: the signer compares the sweep's `to` against
+  the account address **only when the local credential records one**
+  (`safe_address`). Run with `HAVEN_DELEGATE_KEY` alone — or with a credential
+  whose `safe_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.
 
 ## Custody
 
 The delegate key is read from `HAVEN_DELEGATE_KEY` or a `--credentials` file's
-`delegate_key` (with a permissive-file warning). It stays in this process. The
-signer makes no network calls — it can't leak the key to Haven or anyone else.
-It needs no `api_key`: identity lives with the hosted connection, not here.
+`delegate_key` (with a permissive-file warning). It stays in this process, and
+is never transmitted.
+
+**The signer makes exactly one kind of network call.** Since
+[#1263](https://github.com/d-hinders/Haven-AI/issues/1263) it performs an
+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. It reads `api_url` and `api_key` from an `identity.json` sitting
+next to the signer credential file — the signer's own credential still needs no
+`api_key`. The signer **core** (`src/core.ts`) remains network-free, and fetched
+bytes are treated as untrusted input exactly like a tool argument: the same
+digest re-derivation and Haven-binding verification apply, because what makes
+them safe is the verification, not where they came from. It never relays,
+submits, or broadcasts.
 
 Connect Agent 2 may create the signer credential file locally during setup. In
 that flow Haven receives the public signing address, proof, API-key hash/prefix,
@@ -95,14 +200,17 @@ protected storage/runtime config.
 
 Every MCP signing operation appends a JSONL row locally. File-backed runs write
 next to the credential as `<credential>.signer-audit.jsonl`; env-only runs use
-`~/.haven/signer-audit.jsonl`. Rows include timestamp, tool, payload hash, and
-delegate address. They never include the delegate key, signature, or x402
+`~/.haven/signer-audit.jsonl`. Rows include timestamp, tool, payload hash and
+delegate address, plus the account address and chain id when the credential
+carries them. They never include the delegate key, the signature, or the x402
 payment header.
 
 ## Hot-wallet minimization
 
-Standard x402 briefly funds the delegate EOA before the merchant settles the
-EIP-3009 authorization. Keep delegate balances transient: use small/reset-bound
-x402 allowances, retry the original merchant session only after funding
-confirms, and reconcile or sweep stranded delegate balances when the merchant
-retry fails or does not settle before authorization expiry.
+This applies to the **EIP-3009 bridge only** — the erc7710 path above has no
+funding leg and no delegate balance to strand. On the bridge, the account
+briefly funds the delegate EOA before the merchant settles the EIP-3009
+authorization. Keep delegate balances transient: keep budgets small and
+period-bound, retry the original merchant session only after funding confirms,
+and sweep stranded delegate balances (`haven_sign_sweep_delegate`) when the
+merchant retry fails or does not settle before authorization expiry.

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,6 +297,7 @@ function createEdgeSigner(delegateKey, options = {}) {
       );
       if (paymentRequired.x402Version < 2) {
         x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
         return { paymentHeader: header, accepted: option };
       }
       try {
@@ -288,6 +310,7 @@ function createEdgeSigner(delegateKey, options = {}) {
         return { paymentHeader: wrapped, accepted: option };
       } finally {
         x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
       }
     },
     async signSweepAuthorization({
@@ -689,19 +712,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 +743,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 +1239,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.1.31-alpha.0";
+var SIGNER_VERSION = "0.1.33-alpha.0";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {