@haven_ai/signer 0.4.0-alpha.0 → 0.5.0-alpha.1

package/dist/index.d.cts

@@ -1,21 +1,23 @@
-import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk';
+import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth, HavenClientUpdate } from '@haven_ai/sdk/edge';
+export { deriveDelegateAccountAddress } from '@haven_ai/sdk/edge';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod/v3';
-import { z as z$1 } from 'zod';
+import { z as z$1 } from 'zod/v3';
+import { Stats } from 'node:fs';
+import { z } from 'zod';
 
 /**
  * The edge signer core.
  *
- * Holds the delegate key in this process and exposes the two signing
- * operations a hosted-MCP flow needs. It performs no network I/O and never
+ * Holds the delegate key in this process and exposes the signing operations a
+ * hosted-MCP flow needs — five, none of them a raw-hash primitive (#3169): each
+ * takes a payload something can check — a Haven binding verified here, typed
+ * data the account validates on-chain, or a sweep authorization. It performs no network I/O and never
  * returns the key — only signatures and the standard x402 header. See
  * docs/architecture/07-edge-signer.md.
  */
 interface EdgeSigner {
     /** Address derived from the delegate key. */
     readonly delegateAddress: string;
-    /** Sign an AllowanceModule funding/transfer hash (raw ECDSA, 65 bytes). */
-    signPaymentHash(hash: string): string;
     /**
      * Sign a DIRECT delegation-rail payment's EIP-712 typed data (#1254) — the
      * non-x402 counterpart of `signX402FundingTypedData`. The Hybrid account
@@ -26,24 +28,27 @@ interface EdgeSigner {
      * visible to this process's audit log.
      */
     signDelegationTypedData(typedData: Record<string, unknown>): Promise<string>;
-    /** Sign an x402 funding hash and remember the funded merchant-header context. */
-    signX402FundingHash(hash: string, expected: X402ExpectedPayment): X402FundingSignatureResult;
     /**
      * Sign a delegation-rail x402 funding intent's EIP-712 typed data (#1138) and
-     * remember the funded merchant-header context, exactly as the hash path does.
+     * remember the funded merchant-header context — every x402 funding intent
+     * now takes this path (#3272 criterion 8: the bare-hash v1 rail is
+     * retired).
      *
-     * The account validates this typed data, NOT the bare ERC-4337 hash, so the
-     * expected context must be v2 and commit to its digest — see
-     * `assertExpectedBinding`.
+     * The account validates this typed data, NOT a bare hash, so the expected
+     * context must be v2/v3 and commit to its digest — see
+     * `assertExpectedBinding`. `typedData` is `undefined` when the caller had
+     * none to supply; that is itself refused (a v1 context that needed no typed
+     * data is refused earlier, by the version check).
      */
-    signX402FundingTypedData(typedData: X402FundingTypedData, expected: X402ExpectedPayment): Promise<X402FundingSignatureResult>;
+    signX402FundingTypedData(typedData: X402FundingTypedData | undefined, expected: X402ExpectedPayment): Promise<X402FundingSignatureResult>;
     /** Build + sign the EIP-3009 X-PAYMENT header for the merchant leg of x402. */
     buildX402PaymentHeader(paymentRequired: X402PaymentRequired, x402Binding: string): Promise<X402HeaderResult>;
     /**
      * Sign a Haven-prepared EIP-3009 sweep authorization (gasless USDC recovery
-     * delegate → Safe). Verifies the authorization came from Haven and pays out to
-     * the delegate's own Safe before signing; the relayer broadcasts it and pays
-     * gas. Never broadcasts — pure signing.
+     * delegate → the agent's account (Haven wallet)). Verifies the authorization
+     * came from Haven and pays out to the agent's account (Haven wallet) — the
+     * account belongs to the agent, not the delegate — before signing; the
+     * relayer broadcasts it and pays gas. Never broadcasts — pure signing.
      */
     signSweepAuthorization(input: SweepSignatureInput): Promise<SweepSignatureResult>;
 }
@@ -52,7 +57,7 @@ interface SweepSignatureInput {
     authorization: SweepAuthorization;
     /** Haven's signature over the authorization context (binding). */
     expectedAuth: SweepExpectedAuth;
-    /** Optional Safe address from the local credential, cross-checked against `to`. */
+    /** Optional account (Haven wallet) address from the local credential, cross-checked against `to` when present. */
     expectedSafe?: string;
 }
 interface SweepSignatureResult {
@@ -121,7 +126,7 @@ interface X402HeaderResult {
     accepted: X402PaymentOption;
 }
 interface X402FundingSignatureResult {
-    /** Raw ECDSA signature over the Haven funding hash. */
+    /** EIP-712 signature over the Haven-committed funding typed data. */
     signature: string;
     /** Opaque process-local binding for the later merchant header signing step. */
     x402Binding: string;
@@ -149,11 +154,12 @@ declare function assertX402MatchesExpected(paymentRequired: X402PaymentRequired,
  * version arrives *here* instead of dying at the schema boundary with a raw
  * validation string.
  *
- * **Adding a version here is not sufficient to support it.** The mode rules in
+ * **Adding a version here is not sufficient to support it.** The rules in
  * `assertExpectedBinding` derive the expected version from the context's
- * *contents* (`typedDataHash` present ⇒ 2), not from `auth.version`, so a v3
- * that carries anything new needs that derivation extended in the same change.
- * Widening this array alone would admit a v3 context to the v1/v2 rule set:
+ * *contents* (`payerDelegate` present ⇒ 3, else 2 — `typedDataHash` is
+ * required unconditionally, #3272), not from `auth.version`, so a v4 that
+ * carries anything new needs that derivation extended in the same change.
+ * Widening this array alone would admit a v4 context to the v2/v3 rule set:
  * the array announces what this signer can evaluate, it does not define it.
  */
 declare const SUPPORTED_X402_EXPECTED_VERSIONS: readonly number[];
@@ -182,7 +188,7 @@ declare const SUPPORTED_SWEEP_BINDING_VERSIONS: readonly number[];
  *
  * #2347: that word was "authorised" until this change, and the reading was
  * always the correct one — Haven does sign this message. It is now "declared",
- * the word `settlement-child.ts` already uses for this exact binding ("proves
+ * the word the settlement-child verifier (`@haven_ai/sdk`'s `settlement-child.ts`) already uses for this exact binding ("proves
  * Haven *declared* a payload … it says nothing about what the payload MEANS"),
  * because on an agent-facing refusal inside a payment flow the broader word
  * invites the #2334 misreading that Haven is what authorises the spend. It is
@@ -207,9 +213,10 @@ declare function assertSupportedBindingVersion(received: number, supported: read
  *
  * **The check is necessarily agent-mediated.** The signer and the hosted Haven
  * MCP are two separate servers connected to the same client; neither can
- * introspect the other. The signer's single Haven call (#1263, the read-only
- * `GET /x402/:payment_id/sign-context` in `sign-context.ts`) does not help
- * here: it fetches one payment's signing bytes, not the hosted server's
+ * introspect the other. The signer's Haven reads (#1263's read-only
+ * `GET /x402/:payment_id/sign-context` and #3271's direct-payment
+ * `GET /payments/:payment_id/sign-context`, both in `sign-context.ts`) do not help
+ * here: each fetches one payment's signing bytes, not the hosted server's
  * handshake, and it happens at signing time — after the quote this module
  * exists to get ahead of. So only the agent sees both handshakes, and what
  * ships here is the *information* plus the prompt to compare it — never a
@@ -237,6 +244,13 @@ interface SignerCompatibility {
     x402_expected_context_versions: number[];
     /** Sweep-binding versions this signer will verify (`SUPPORTED_SWEEP_BINDING_VERSIONS`). */
     sweep_binding_versions: number[];
+    /**
+     * #3271: `direct_sign_context_version`s this signer will fetch and verify
+     * from `GET /payments/:id/sign-context` — derived from the SDK's
+     * `DIRECT_SIGN_CONTEXT_VERSION` via `SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS`,
+     * never a second literal.
+     */
+    direct_sign_context_versions: number[];
 }
 /** The supported sets this signer enforces, as a plain serialisable object. */
 declare function signerCompatibility(): SignerCompatibility;
@@ -270,9 +284,11 @@ declare function signerInstructions(): string;
  *
  * That is a claim about this credential, not about the process, and the
  * difference matters: the sentence that used to stand here ("it does not call
- * the Haven API") was retired by #1263. The MCP server layer does make one
- * authenticated call — a read-only `GET /x402/:payment_id/sign-context`, see
- * `sign-context.ts` — and it reads the `api_url` / `api_key` for it from a
+ * the Haven API") was retired by #1263. The MCP server layer does make at
+ * most two authenticated reads per signing call — a read-only
+ * `GET /x402/:payment_id/sign-context` and, for a direct payment via
+ * `haven_sign` since #3271, then `GET /payments/:payment_id/sign-context`, see
+ * `sign-context.ts` — and it reads the `api_url` / `api_key` for them from a
  * SEPARATE `identity.json` in the same directory as the credential file
  * resolved here. That is why `sourcePath` below is load-bearing rather than
  * diagnostic, and why a key supplied through `HAVEN_DELEGATE_KEY` alone (no
@@ -353,6 +369,65 @@ declare function readAccountAddressEnv(env: NodeJS.ProcessEnv): string | undefin
  */
 declare function warnIfCredentialFilePermissive(path: string, log?: (message: string) => void, platform?: NodeJS.Platform): Promise<void>;
 
+/** Owner-only: the mode every file this package writes beside a credential gets. */
+declare const OWNER_ONLY_MODE = 384;
+type PermissionLog = (message: string) => void;
+interface PermissiveFile {
+    /** The offending mode, e.g. `0644`. */
+    octal: string;
+    /** False for a symlink, directory or device at that path — never chmod those. */
+    regular: boolean;
+}
+/**
+ * Is this path readable, writable or executable by anyone but its owner?
+ * Returns null when the path cannot be stat'ed or is owner-only, and on
+ * Windows where POSIX mode bits do not map cleanly (the same carve-out
+ * `@haven_ai/mcp` makes). Pass `stats` to reuse a stat the caller took
+ * IMMEDIATELY before — with `stats` the path is not touched, so a cached
+ * `Stats` would be trusted over the disk. `follow` decides what a symlink at the path means: a file the signer
+ * only READS (the credential) is judged by its target, which is what the
+ * content protection is about and what the pre-#3172 `stat` did; a file the
+ * signer is about to CHMOD (the audit sidecar) is judged as the link, so a
+ * planted symlink is never chmod-ed through (#3172 review).
+ */
+declare function permissiveMode(path: string, platform?: NodeJS.Platform, stats?: Stats, follow?: 'follow' | 'nofollow'): Promise<PermissiveFile | null>;
+/**
+ * Warn (best-effort, POSIX only) when a file this signer READS is readable
+ * beyond its owner. The signer does not own the credential, so it tells the
+ * operator what to run rather than changing a file it was handed. Follows a
+ * symlink, as the pre-#3172 `stat` did: a link to a 0600 credential is fine.
+ */
+declare function warnIfFilePermissive(kind: string, path: string, log?: PermissionLog, platform?: NodeJS.Platform): Promise<void>;
+type TightenOutcome = 'owner-only' | 'tightened' | 'warned' | 'skipped';
+/**
+ * Tighten a file this signer WRITES to owner-only when it finds it
+ * permissive (#3172): the audit sidecar was created with the default mode
+ * (0644 under the usual umask 022) by every release before this one, so an
+ * existing sidecar is fixed in place rather than warned about. Judged with
+ * `lstat`. Falls back to the warning when the path is not a regular file (a
+ * symlink would make chmod hit whatever it points at) or when chmod is
+ * refused (a file owned by another user). Outcomes: `tightened` / `warned`
+ * as above; `owner-only` when there is nothing to tighten (owner-only file,
+ * or no file at that path); `skipped` on Windows only.
+ */
+declare function tightenIfFilePermissive(kind: string, path: string, log?: PermissionLog, platform?: NodeJS.Platform, stats?: Stats): Promise<TightenOutcome>;
+
+/**
+ * #3172: the sidecar is bounded. When it reaches this size the current file is
+ * renamed to `<path>.1` (replacing the previous `.1`) and a fresh file starts,
+ * so at most two generations — the live file and one predecessor — ever exist.
+ * 8 MiB is roughly 30 000 entries at the ~270-byte row size; nothing in the
+ * signer reads the file back, so the bound protects the disk and the reader's
+ * patience, never a signing decision.
+ */
+declare const AUDIT_ROTATE_BYTES: number;
+interface AppendAuditOptions {
+    /** Where permission notices go; defaults to stderr. */
+    log?: PermissionLog;
+    /** Rotation threshold in bytes; exported default `AUDIT_ROTATE_BYTES`. */
+    rotateAtBytes?: number;
+    platform?: NodeJS.Platform;
+}
 interface SigningAuditEntry {
     version: 1;
     timestamp: string;
@@ -377,7 +452,7 @@ interface SigningAuditContext {
     auditPath?: string;
 }
 declare function defaultSigningAuditPath(credentialsPath?: string): string;
-declare function appendSigningAuditEntry(entry: SigningAuditEntry, path: string): Promise<void>;
+declare function appendSigningAuditEntry(entry: SigningAuditEntry, path: string, options?: AppendAuditOptions): Promise<void>;
 declare function createSigningAuditEntry(tool: SignerToolName, payloadHash: string, context: SigningAuditContext, now?: Date): SigningAuditEntry;
 declare function hashPayloadForAudit(payload: unknown): string;
 
@@ -386,6 +461,26 @@ interface HavenIdentity {
     apiKey: string;
 }
 
+/**
+ * #3103 (epic #3105, slice 4/5): the signer's typed next step.
+ *
+ * The signer decides a `next_action` on its refusals and, until this module,
+ * never said which tool to call. It cannot know the client's server names
+ * (#2550), so the handoff is expressed through the role fields the SDK
+ * builder renders — `next_tool_server_role: hosted`, `next_tool_name` — from
+ * a bare tool name. The signer must not import the hosted server (it is an
+ * npm package installed on user machines; the hosted server is a Docker
+ * deployment), so the hosted tools it hands off to are DECLARED here as the
+ * argument shape the signer actually emits, and `next-step-signer-parity`
+ * in the hosted server's own suite pins them to the hosted schemas at test
+ * time — the mirror of how the hosted server declares the signer's shapes.
+ */
+declare const SIGNER_HOSTED_HANDOFF_SHAPES: {
+    readonly haven_get_payment_status: {
+        readonly payment_id: z.ZodString;
+    };
+};
+
 /**
  * Local signer tool set. These run on the agent's machine, next to the key,
  * and pair with the hosted server's construct/relay tools (#183). They sign;
@@ -394,16 +489,16 @@ interface HavenIdentity {
 type SignerToolName = 'haven_sign' | 'haven_x402_sign_header' | 'haven_sign_x402' | 'haven_sign_sweep_delegate';
 declare const toolSchemas: {
     readonly haven_sign_sweep_delegate: {
-        readonly authorization: z.ZodObject<{
-            from: z.ZodString;
-            to: z.ZodString;
-            value: z.ZodString;
-            validAfter: z.ZodString;
-            validBefore: z.ZodString;
-            nonce: z.ZodString;
-            token: z.ZodString;
-            chainId: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
+        readonly authorization: z$1.ZodObject<{
+            from: z$1.ZodString;
+            to: z$1.ZodString;
+            value: z$1.ZodString;
+            validAfter: z$1.ZodString;
+            validBefore: z$1.ZodString;
+            nonce: z$1.ZodString;
+            token: z$1.ZodString;
+            chainId: z$1.ZodNumber;
+        }, "strip", z$1.ZodTypeAny, {
             chainId: number;
             to: string;
             from: string;
@@ -422,12 +517,12 @@ declare const toolSchemas: {
             validAfter: string;
             validBefore: string;
         }>;
-        readonly expected_auth: z.ZodObject<{
-            version: z.ZodNumber;
-            message: z.ZodString;
-            signature: z.ZodString;
-            signer: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
+        readonly expected_auth: z$1.ZodObject<{
+            version: z$1.ZodNumber;
+            message: z$1.ZodString;
+            signature: z$1.ZodString;
+            signer: z$1.ZodString;
+        }, "strip", z$1.ZodTypeAny, {
             message: string;
             version: number;
             signature: string;
@@ -440,26 +535,26 @@ declare const toolSchemas: {
         }>;
     };
     readonly haven_sign: {
-        readonly payment_id: z.ZodOptional<z.ZodString>;
-        readonly payload_hash: z.ZodOptional<z.ZodString>;
-        readonly x402_expected: z.ZodOptional<z.ZodObject<{
-            payment_id: z.ZodString;
-            payload_hash: z.ZodString;
-            resource_url: z.ZodString;
-            merchant_to: z.ZodString;
-            amount: z.ZodString;
-            asset: z.ZodString;
-            network: z.ZodString;
-            expires_at: z.ZodString;
-            typed_data_hash: z.ZodOptional<z.ZodString>;
-            payer_delegate: z.ZodOptional<z.ZodString>;
-            payer_agent_id: z.ZodOptional<z.ZodString>;
-            auth: z.ZodObject<{
-                version: z.ZodNumber;
-                message: z.ZodString;
-                signature: z.ZodString;
-                signer: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+        readonly payment_id: z$1.ZodOptional<z$1.ZodString>;
+        readonly payload_hash: z$1.ZodOptional<z$1.ZodString>;
+        readonly x402_expected: z$1.ZodOptional<z$1.ZodObject<{
+            payment_id: z$1.ZodString;
+            payload_hash: z$1.ZodString;
+            resource_url: z$1.ZodString;
+            merchant_to: z$1.ZodString;
+            amount: z$1.ZodString;
+            asset: z$1.ZodString;
+            network: z$1.ZodString;
+            expires_at: z$1.ZodString;
+            typed_data_hash: z$1.ZodOptional<z$1.ZodString>;
+            payer_delegate: z$1.ZodOptional<z$1.ZodString>;
+            payer_agent_id: z$1.ZodOptional<z$1.ZodString>;
+            auth: z$1.ZodObject<{
+                version: z$1.ZodNumber;
+                message: z$1.ZodString;
+                signature: z$1.ZodString;
+                signer: z$1.ZodString;
+            }, "strip", z$1.ZodTypeAny, {
                 message: string;
                 version: number;
                 signature: string;
@@ -470,15 +565,15 @@ declare const toolSchemas: {
                 signature: string;
                 signer: string;
             }>;
-        }, "strip", z.ZodTypeAny, {
-            network: string;
+        }, "strip", z$1.ZodTypeAny, {
             payment_id: string;
+            expires_at: string;
+            network: string;
             payload_hash: string;
             resource_url: string;
             merchant_to: string;
             amount: string;
             asset: string;
-            expires_at: string;
             auth: {
                 message: string;
                 version: number;
@@ -489,14 +584,14 @@ declare const toolSchemas: {
             payer_delegate?: string | undefined;
             payer_agent_id?: string | undefined;
         }, {
-            network: string;
             payment_id: string;
+            expires_at: string;
+            network: string;
             payload_hash: string;
             resource_url: string;
             merchant_to: string;
             amount: string;
             asset: string;
-            expires_at: string;
             auth: {
                 message: string;
                 version: number;
@@ -507,34 +602,34 @@ declare const toolSchemas: {
             payer_delegate?: string | undefined;
             payer_agent_id?: string | undefined;
         }>>;
-        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+        readonly typed_data: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>>;
+        readonly typed_data_b64: z$1.ZodOptional<z$1.ZodString>;
     };
     readonly haven_x402_sign_header: {
-        readonly payment_required: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        readonly x402_binding: z.ZodString;
+        readonly payment_required: z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>;
+        readonly x402_binding: z$1.ZodString;
     };
     readonly haven_sign_x402: {
-        readonly payment_id: z.ZodOptional<z.ZodString>;
-        readonly payload_hash: z.ZodOptional<z.ZodString>;
-        readonly x402_expected: z.ZodOptional<z.ZodObject<{
-            payment_id: z.ZodString;
-            payload_hash: z.ZodString;
-            resource_url: z.ZodString;
-            merchant_to: z.ZodString;
-            amount: z.ZodString;
-            asset: z.ZodString;
-            network: z.ZodString;
-            expires_at: z.ZodString;
-            typed_data_hash: z.ZodOptional<z.ZodString>;
-            payer_delegate: z.ZodOptional<z.ZodString>;
-            payer_agent_id: z.ZodOptional<z.ZodString>;
-            auth: z.ZodObject<{
-                version: z.ZodNumber;
-                message: z.ZodString;
-                signature: z.ZodString;
-                signer: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+        readonly payment_id: z$1.ZodOptional<z$1.ZodString>;
+        readonly payload_hash: z$1.ZodOptional<z$1.ZodString>;
+        readonly x402_expected: z$1.ZodOptional<z$1.ZodObject<{
+            payment_id: z$1.ZodString;
+            payload_hash: z$1.ZodString;
+            resource_url: z$1.ZodString;
+            merchant_to: z$1.ZodString;
+            amount: z$1.ZodString;
+            asset: z$1.ZodString;
+            network: z$1.ZodString;
+            expires_at: z$1.ZodString;
+            typed_data_hash: z$1.ZodOptional<z$1.ZodString>;
+            payer_delegate: z$1.ZodOptional<z$1.ZodString>;
+            payer_agent_id: z$1.ZodOptional<z$1.ZodString>;
+            auth: z$1.ZodObject<{
+                version: z$1.ZodNumber;
+                message: z$1.ZodString;
+                signature: z$1.ZodString;
+                signer: z$1.ZodString;
+            }, "strip", z$1.ZodTypeAny, {
                 message: string;
                 version: number;
                 signature: string;
@@ -545,15 +640,15 @@ declare const toolSchemas: {
                 signature: string;
                 signer: string;
             }>;
-        }, "strip", z.ZodTypeAny, {
-            network: string;
+        }, "strip", z$1.ZodTypeAny, {
             payment_id: string;
+            expires_at: string;
+            network: string;
             payload_hash: string;
             resource_url: string;
             merchant_to: string;
             amount: string;
             asset: string;
-            expires_at: string;
             auth: {
                 message: string;
                 version: number;
@@ -564,14 +659,14 @@ declare const toolSchemas: {
             payer_delegate?: string | undefined;
             payer_agent_id?: string | undefined;
         }, {
-            network: string;
             payment_id: string;
+            expires_at: string;
+            network: string;
             payload_hash: string;
             resource_url: string;
             merchant_to: string;
             amount: string;
             asset: string;
-            expires_at: string;
             auth: {
                 message: string;
                 version: number;
@@ -582,9 +677,9 @@ declare const toolSchemas: {
             payer_delegate?: string | undefined;
             payer_agent_id?: string | undefined;
         }>>;
-        readonly payment_required: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+        readonly payment_required: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>>;
+        readonly typed_data: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>>;
+        readonly typed_data_b64: z$1.ZodOptional<z$1.ZodString>;
     };
 };
 declare const toolDescriptions: Record<SignerToolName, string>;
@@ -626,11 +721,14 @@ interface ToolFailure {
     fallback?: string;
     /**
      * #3001: present on `SIGN_CONTEXT_REFUSED` — the HTTP status the backend
-     * answered the `/x402/:id/sign-context` fetch with (404, 410, …).
+     * answered the sign-context fetch with (404, 410, …) — the x402 fetch, or
+     * the direct `/payments/:id/sign-context` fetch since #3271.
      */
     http_status?: number;
-    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`). */
+    /** #3001: the backend's own `error_code` on `SIGN_CONTEXT_REFUSED` (`expired`, `already_executed`, `not_signable`, `sign_context_unavailable`, and since #3303 `client_outdated`). */
     backend_error_code?: string;
+    /** #3303: on `client_outdated`, the backend's update hint — `upgrade_command` is what updates this signer. */
+    client_update?: HavenClientUpdate;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 interface ToolHandlerOptions {
@@ -645,6 +743,8 @@ interface ToolHandlerOptions {
     signContext?: {
         loadIdentity: () => Promise<HavenIdentity | null>;
         fetchImpl?: typeof fetch;
+        /** #3303: `@haven_ai/signer/<version>`, sent as `X-Haven-Client` on every sign-context read. */
+        clientIdentity?: string;
     };
 }
 declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOptions): Record<SignerToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -676,7 +776,7 @@ declare function renderSignerConsentBlock(input: SignerConsentInput, hash: strin
 declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
 
 declare const SIGNER_NAME = "@haven_ai/signer";
-declare const SIGNER_VERSION = "0.4.0-alpha.0";
+declare const SIGNER_VERSION = "0.5.0-alpha.1";
 interface SignerOptions {
     /** Path to a Haven credential JSON file (delegate_key is read from it). */
     credentialsPath?: string;
@@ -741,24 +841,4 @@ declare function assertSupportedNodeVersion(nodeVersion?: string): void;
 declare function runSignerStdioServer(options?: SignerOptions): Promise<void>;
 declare function runSignerConsentGate(signer: EdgeSigner, credentials: SignerCredentials | undefined, options: SignerOptions): Promise<SignerConsentDecision>;
 
-/**
- * #3103 (epic #3105, slice 4/5): the signer's typed next step.
- *
- * The signer decides a `next_action` on its refusals and, until this module,
- * never said which tool to call. It cannot know the client's server names
- * (#2550), so the handoff is expressed through the role fields the SDK
- * builder renders — `next_tool_server_role: hosted`, `next_tool_name` — from
- * a bare tool name. The signer must not import the hosted server (it is an
- * npm package installed on user machines; the hosted server is a Docker
- * deployment), so the hosted tools it hands off to are DECLARED here as the
- * argument shape the signer actually emits, and `next-step-signer-parity`
- * in the hosted server's own suite pins them to the hosted schemas at test
- * time — the mirror of how the hosted server declares the signer's shapes.
- */
-declare const SIGNER_HOSTED_HANDOFF_SHAPES: {
-    readonly haven_get_payment_status: {
-        readonly payment_id: z$1.ZodString;
-    };
-};
-
-export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive };
+export { AUDIT_ROTATE_BYTES, type AppendAuditOptions, type EdgeSigner, OWNER_ONLY_MODE, type PermissionLog, type PermissiveFile, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type TightenOutcome, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, permissiveMode, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, tightenIfFilePermissive, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive, warnIfFilePermissive };