@haven_ai/sdk 0.8.0-alpha.0 → 0.9.0-alpha.0

package/dist/base64-BZDPJ8M1.d.ts

@@ -0,0 +1,1344 @@
+import { Q as AgentNextStep, Z as AgentPaymentNextAction, aL as X402PaymentOption, aK as X402ExpectedContext, X as X402PaymentRequired, I as HavenError, am as HavenSigningError } from './types-CrszUJ7Z.js';
+import { PaymentRequirements } from 'x402/types';
+import { Hex, Address } from 'viem';
+
+/**
+ * Gasless delegate-sweep primitives — the single source of truth shared by the
+ * edge signer (which signs) and the Haven backend (which relays).
+ *
+ * A stranded delegate EOA holds USDC but no ETH, so a raw ERC-20 transfer can't
+ * pay for its own gas. Instead the delegate signs an *off-chain* EIP-3009
+ * `TransferWithAuthorization` and the Haven relayer submits it on-chain and pays
+ * gas. The relayer is only a gas payer: it holds no allowance and is never a
+ * spender, so a relayer compromise cannot move user funds.
+ *
+ * Framework-neutral on purpose: `buildSweepTypedData` returns a plain
+ * `{ domain, types, primaryType, message }` that both viem
+ * (`signTypedData`/`recoverTypedDataAddress`) and ethers v6
+ * (`signTypedData`/`verifyTypedData`) accept, so the signer (viem) and backend
+ * (ethers) stay in lockstep without sharing a crypto library.
+ */
+/** Base mainnet. The only chain Haven sweeps today. */
+declare const SWEEP_BASE_CHAIN_ID = 8453;
+/** Base Sepolia testnet — used by the dev environment / QA harness. */
+declare const SWEEP_BASE_SEPOLIA_CHAIN_ID = 84532;
+/** Canonical Circle USDC on Base (FiatTokenV2_2). */
+declare const SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** Circle's canonical Base Sepolia testnet USDC. */
+declare const SWEEP_BASE_SEPOLIA_USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+/** True when the gasless sweep supports a chain (its USDC domain + address are known). */
+declare function isSweepableChain(chainId: number): boolean;
+/** EIP-712 `TransferWithAuthorization` struct, per EIP-3009. */
+declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+interface SweepEip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+/**
+ * A fully-specified EIP-3009 authorization. All amounts/times are decimal
+ * strings (JSON-safe) and `nonce` is a 0x-prefixed 32-byte hex value. `token`
+ * and `chainId` are carried explicitly so the signer can assert they are
+ * canonical before signing.
+ */
+interface SweepAuthorization {
+    /** Delegate EOA the funds are swept FROM. */
+    from: string;
+    /** The agent's Haven account the funds are swept TO. */
+    to: string;
+    /** Atomic USDC amount (decimal string). */
+    value: string;
+    /** Unix seconds the authorization becomes valid (decimal string, usually "0"). */
+    validAfter: string;
+    /** Unix seconds the authorization expires (decimal string). */
+    validBefore: string;
+    /** Random 0x-prefixed 32-byte hex nonce. */
+    nonce: string;
+    /** USDC contract address. */
+    token: string;
+    /** Chain id (8453 today). */
+    chainId: number;
+}
+/**
+ * Haven's signature over the sweep authorization context, signed with the same
+ * binding key the x402 expected-context uses. Lets the edge signer verify the
+ * authorization actually came from Haven (and wasn't crafted by a compromised
+ * hosted server pointing `to` at an attacker) before it signs.
+ */
+interface SweepExpectedAuth {
+    /**
+     * Currently always 1. Typed as `number` for the same reason as
+     * `X402ExpectedAuth.version` (#1143): it is inbound, so a stale signer must be
+     * able to *receive* an unknown version in order to report it. The signer's
+     * `SUPPORTED_SWEEP_BINDING_VERSIONS` is the authority on what it will sign.
+     */
+    version: number;
+    message: string;
+    signature: string;
+    signer: string;
+}
+/** What `POST /machine-payments/sweep/prepare` returns when funds are stranded. */
+interface SweepPreparation {
+    authorization: SweepAuthorization;
+    expectedAuth: SweepExpectedAuth;
+}
+/** Wire response from `POST /machine-payments/sweep/prepare` (snake_case). */
+interface SweepPrepareResponse {
+    /** Present and true when the delegate holds nothing to recover. */
+    nothing_stranded?: boolean;
+    /**
+     * Present and true when the stranded balance is below the sweep floor (#700):
+     * it is left on the delegate as dust rather than recovered, because the gas to
+     * sweep it would exceed its value. `min_usdc` carries the configured floor. No
+     * `authorization` is built.
+     */
+    below_min?: boolean;
+    min_usdc?: string;
+    /** The authorization to sign — absent when nothing is stranded or below the floor. */
+    authorization?: SweepAuthorization;
+    /** Haven's binding over the authorization — absent when nothing is stranded. */
+    expected_auth?: SweepExpectedAuth;
+    asset?: string;
+    amount?: string;
+    amount_atomic?: string;
+    chain_id: number;
+    sign_instructions?: string;
+    message?: string;
+}
+/** Wire response from `POST /machine-payments/sweep/submit` (snake_case). */
+interface SweepSubmitResponse {
+    tx_hash: string;
+    asset: string;
+    amount: string;
+    amount_atomic: string;
+    from_address: string;
+    to_address: string;
+    chain_id: number;
+    explorer_url: string;
+    idempotent_replay?: boolean;
+}
+/** Result of a submitted gasless sweep. */
+interface SweepSubmitResult {
+    txHash: string;
+    amount: string;
+    amountAtomic: string;
+    asset: string;
+    fromAddress: string;
+    toAddress: string;
+    chainId: number;
+    explorerUrl: string;
+}
+interface SweepTypedData {
+    domain: SweepEip712Domain;
+    types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
+    primaryType: 'TransferWithAuthorization';
+    message: {
+        from: string;
+        to: string;
+        value: bigint;
+        validAfter: bigint;
+        validBefore: bigint;
+        nonce: string;
+    };
+}
+/** Resolve the canonical USDC contract for a sweepable chain, or throw. */
+declare function sweepUsdcAddress(chainId: number): string;
+/** Resolve the USDC EIP-712 domain for a sweepable chain, or throw. */
+declare function sweepUsdcDomain(chainId: number): SweepEip712Domain;
+/**
+ * Build the EIP-712 typed data for an authorization, validating that the token
+ * and chain are canonical (the domain's `verifyingContract` must match the
+ * authorization's `token`). Returns bigint-valued fields so both viem and
+ * ethers v6 sign/recover identically.
+ */
+declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
+/**
+ * Canonical, deterministic string the backend signs and the signer re-derives
+ * for the authorization binding. The `Haven sweep authorization v1` namespace
+ * (and `kind`) is distinct from the x402 expected-context namespace so an x402
+ * binding can never be replayed as a sweep authorization even though they share
+ * a signing key.
+ */
+declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
+
+/**
+ * Client identity on Haven API requests (#3303, epic #3302).
+ *
+ * Every published Haven client names itself with one header,
+ * `X-Haven-Client: <package>/<version>`, so the backend can tell an outdated
+ * client what to run — a `client_update` hint on its responses, or, only below
+ * a minimum the deployment has explicitly set, a 426 `client_outdated` refusal
+ * at the payment-initiating routes (the signer: at sign-context). The backend's
+ * table and decision live in `@haven_ai/core`'s `client-compat.ts`; this module
+ * is the client half and deliberately holds no thresholds.
+ *
+ * Deliberately free of any other SDK import so `@haven_ai/sdk/edge` (the
+ * signer's ethers-free entry) can re-export it.
+ */
+/**
+ * This SDK's own version. Owned by `scripts/release-bump.mjs`, which rewrites
+ * it with the package version on every release — never hand-edit it.
+ */
+declare const SDK_VERSION = "0.9.0-alpha.0";
+/** The request header every published Haven client sends. */
+declare const HAVEN_CLIENT_HEADER = "X-Haven-Client";
+/** `<package>/<version>` — the value of {@link HAVEN_CLIENT_HEADER}. */
+declare function havenClientIdentity(pkg: string, version: string): string;
+/** What a bare SDK embedder sends when it names no package of its own. */
+declare const SDK_CLIENT_IDENTITY: string;
+/**
+ * The `client_update` object the backend attaches to a response when this
+ * client is behind (`required: false`) or below a set minimum
+ * (`required: true`). Every field is the backend's; the SDK never computes one.
+ */
+interface HavenClientUpdate {
+    package: string;
+    current: string;
+    recommended: string | null;
+    min_version: string | null;
+    required: boolean;
+    upgrade_command: string;
+    notes_url: string | null;
+}
+/** Narrow an unknown response field to a {@link HavenClientUpdate}, or undefined. */
+declare function readClientUpdate(value: unknown): HavenClientUpdate | undefined;
+
+/**
+ * #3101 (epic #3105, slice 2/5): the typed next-step builder.
+ *
+ * Every hosted payment tool ends by naming the agent's next tool and its
+ * arguments (#1308). Until this module, the tool was a free string and the
+ * arguments a `Record<string, unknown>`, so nothing tied the keys to the tool
+ * named beside them — three sites handed `{ payment_id: null }` to a tool
+ * whose `payment_id` is a required string, and the compiler could not see it.
+ *
+ * The builder is generic over a TARGET MAP the caller supplies: bare tool
+ * name → { role, validate }. It is deliberately schema-library-agnostic (the
+ * SDK carries no zod): the hosted server derives each target's argument type
+ * from its own zod shape and passes a `validate` closure; this module only
+ * needs to know the role (to render `mcp__<server>__<tool>`) and how to say
+ * whether arguments parse. Keyed on the bare name + role (decision 1) so the
+ * namespaced string is rendered in exactly one place and the runtime-neutral
+ * `next_tool_server` / `next_tool_name` / `next_tool_server_role` fields are
+ * derived from the same input rather than parsed back out of a literal.
+ *
+ * Decisions 3 and 8: `nextTool` is REQUIRED on the input and may be `null` —
+ * a site that forgets it is a compile error; a site with no next tool says
+ * why, and the wire omits `next_tool` and carries `next_tool_omitted_reason`.
+ * `next_tool` is never null on the wire.
+ */
+type NextToolServerRole = 'hosted' | 'signer';
+/** The DEFAULT server name each role is wired under (#1588, #2550). */
+declare const NEXT_TOOL_SERVER_NAMES: Record<NextToolServerRole, string>;
+/** Default server name → role. An unknown server yields no role rather than a guess (#2550). */
+declare const NEXT_TOOL_SERVER_ROLES: Record<string, NextToolServerRole>;
+/** Renders the Claude-family namespaced tool name — the one string clients have followed since #1308. */
+declare function renderNextTool(role: NextToolServerRole, name: string): string;
+/** Parses a namespaced literal back into its parts; `role` is absent for an unknown server. */
+declare function parseNextTool(literal: string): {
+    server: string;
+    name: string;
+    role?: NextToolServerRole;
+} | null;
+/**
+ * One target the builder may hand off to. `TArgs` is the argument type the
+ * caller derived from the tool's declared schema; `validate` is the runtime
+ * twin of that type and returns `null` when the arguments parse, else why not.
+ */
+interface NextStepTarget<TArgs> {
+    role: NextToolServerRole;
+    validate: (input: unknown) => string | null;
+    /** Phantom carrier for the argument type; never read at runtime. */
+    readonly _args?: TArgs;
+}
+type NextStepTargets = Record<string, NextStepTarget<unknown>>;
+/** The argument type a target carries. */
+type NextStepArguments<Targets extends NextStepTargets, T extends keyof Targets> = Targets[T] extends NextStepTarget<infer A> ? A : never;
+/**
+ * The handoff half of a next step: a registered tool with arguments that
+ * tool accepts, or no tool with the reason. A discriminated union over the
+ * target map's keys, so a wrong key, a missing required key, an unregistered
+ * tool name and an omitted `nextTool` are each a compile error at the site.
+ */
+type NextStepHandoff<Targets extends NextStepTargets> = {
+    [T in keyof Targets & string]: {
+        nextTool: T;
+        nextArguments: NextStepArguments<Targets, T>;
+    };
+}[keyof Targets & string] | {
+    nextTool: null;
+    nextToolOmittedReason: string;
+};
+type NextStepInput<Targets extends NextStepTargets> = NextStepHandoff<Targets> & {
+    nextAction: AgentPaymentNextAction;
+    safeToContinue: boolean;
+    reason: string;
+};
+/** The wire shape: `AgentNextStep` (its `next_tool` family) — never a null `next_tool`. */
+type NextStep = AgentNextStep;
+/**
+ * Per-`next_action` default tool (decision 9): the tool a site names unless it
+ * has a reason to override. Only actions with ONE sensible target are listed;
+ * `retry_original_x402_request` is absent because its only live emitter names
+ * no tool on purpose (the agent's own HTTP retry); `sign_and_submit_payment`
+ * is absent because the signer tool
+ * depends on the settlement scheme (`haven_sign` for erc7710 delegations,
+ * `haven_sign_x402` for the EIP-3009 bridge) and a wrong default there would be
+ * worse than none.
+ */
+declare const DEFAULT_NEXT_TOOL_BY_ACTION: {
+    readonly check_status_later: "haven_get_payment_status";
+    readonly sweep_stranded_funds: "haven_sweep_delegate";
+};
+declare function defaultNextToolFor(action: AgentPaymentNextAction): string | undefined;
+/**
+ * Builds a `nextStep` function bound to a target map. The returned function
+ * renders the wire fields from the bare name + role, and re-validates the
+ * arguments at runtime: on a mismatch it FAILS SAFE — omits the tool and says
+ * why in `next_tool_omitted_reason` — rather than throwing out of a handler
+ * that has already moved money. The compile-time twin makes that branch
+ * unreachable from typed sites; it exists for callers that bypass the types.
+ */
+declare function createNextStepBuilder<Targets extends NextStepTargets>(targets: Targets): (input: NextStepInput<Targets>) => NextStep;
+
+/**
+ * The npm dist-tag the published Haven packages tell a user to re-run (#2423,
+ * slice 3 of epic #2420).
+ *
+ * ## Why a constant and not a literal
+ *
+ * Roughly a dozen user- and agent-facing strings across `@haven_ai/sdk`,
+ * `@haven_ai/signer`, `@haven_ai/connect` and the hosted MCP server say some
+ * form of "re-run `npx @haven_ai/connect@alpha`". Every one of them was a
+ * hard-coded literal, which is correct only for a build published under the
+ * `alpha` dist-tag. Once `dev`-branch snapshots publish under a `dev` tag
+ * (#2421), a snapshot build telling its tester to re-run `@alpha` would hand
+ * them the production connector — silently replacing the very build they are
+ * testing. So the tag becomes one build-time constant and every hint derives
+ * from it.
+ *
+ * ## Who writes it
+ *
+ * `scripts/release-bump.mjs` rewrites {@link HAVEN_CONNECTOR_CHANNEL} from the
+ * version it is bumping to, using exactly the rule `.github/workflows/publish.yml`
+ * uses to pick the `--tag` for that same version:
+ *
+ * | version | dist-tag / channel |
+ * |---|---|
+ * | `0.1.34-alpha.0` | `alpha` |
+ * | `0.0.0-dev.202609021200.abc1234` | `dev` |
+ * | `0.2.0` | `latest` |
+ *
+ * One rule, two consumers. `scripts/ci/connector-channel-agreement.test.mjs`
+ * executes the workflow's own shell and the bump script's own function over the
+ * same version table and fails if they ever disagree.
+ *
+ * ## Build-time here, run-time there
+ *
+ * A published tarball cannot read a deployment's environment, so for the
+ * published packages the channel is baked in at release time. A surface that is
+ * *deployed* rather than published has no release at which to bake anything in,
+ * so it reads the `HAVEN_CONNECTOR_CHANNEL` environment variable and falls back
+ * to this constant. Two surfaces do that: the hosted MCP server
+ * (`packages/mcp-server/src/connector-channel.ts`) and, since slice 2 (#2422),
+ * the backend's connector handout (`parseConnectorChannel` in
+ * `packages/backend/src/config.ts`). All three readers share one variable name,
+ * one default and one validation pattern, and that agreement is EXECUTED rather
+ * than asserted: `packages/backend/src/__tests__/connector-channel.test.ts`
+ * runs this module's `resolveConnectorChannel` and the backend's
+ * `parseConnectorChannel` over the same input table and fails if they ever
+ * diverge.
+ *
+ * **This says nothing about how any environment is configured.** Setting the
+ * variable anywhere is an operator action (epic #2420, operator step 3); no
+ * code here can observe it and none of this comment asserts it has happened.
+ */
+/** The published connector package. Never varies; only its tag does. */
+declare const CONNECTOR_PACKAGE_NAME = "@haven_ai/connect";
+/**
+ * The npm dist-tag this build's re-run hints name.
+ *
+ * **Do not hand-edit.** `scripts/release-bump.mjs` owns this literal the same
+ * way it owns `CONNECTOR_VERSION` and its siblings, and
+ * `scripts/release-bump.test.mjs` fails if the two drift.
+ */
+declare const HAVEN_CONNECTOR_CHANNEL = "alpha";
+/** True when `value` is a well-formed dist-tag. */
+declare function isConnectorChannel(value: string): boolean;
+/**
+ * Resolve a channel from a deployment's `HAVEN_CONNECTOR_CHANNEL`.
+ *
+ * - unset, empty or whitespace ⇒ `fallback` (dashboards store a cleared
+ *   variable as `""`, and that must land on the production-safe value);
+ * - well-formed ⇒ itself;
+ * - anything else ⇒ **throws**. It does not quietly fall back: a typo such as
+ *   `dve` would then land on the production channel, and the environment would
+ *   look fixed while reproducing the exact defect this slice removes.
+ *
+ * Well-formed-but-wrong (`dve` again) is *not* caught here and cannot be — it
+ * fails later at `npx`, where the error names the package. Stated rather than
+ * implied.
+ */
+declare function resolveConnectorChannel(raw: string | undefined | null, fallback?: string): string;
+/** `@haven_ai/connect@<channel>` — the spec an `npx` invocation names. */
+declare function connectorSpec(channel?: string): string;
+/**
+ * The re-run command every hint embeds.
+ *
+ * `connectorRerunCommand()` → `npx @haven_ai/connect@alpha`
+ * `connectorRerunCommand('--doctor')` → `npx @haven_ai/connect@alpha --doctor`
+ *
+ * `args` is appended verbatim so each call site keeps its own flags and its own
+ * surrounding sentence. The wording of those sentences is deliberately NOT
+ * moved here: several are inside signer refusal messages that users and agents
+ * pattern-match on, and this change is meant to move the channel token and
+ * nothing else.
+ */
+declare function connectorRerunCommand(args?: string, options?: {
+    channel?: string;
+    npxFlags?: string;
+}): string;
+/**
+ * The command every UPGRADE hint names (#3412): `npx -y @haven_ai/connect@<channel> --doctor`.
+ *
+ * A bare connector re-run is a SETUP command — on a machine that is already
+ * set up it stops at "Missing --setup <hv_setup_...> setup token", so an
+ * outdated signer, local MCP or connector told to "re-run the connector" was
+ * handed a dead end. The flagless doctor works as pasted on an existing
+ * install (#3210: it resolves the runtime from the setup record), diagnoses an
+ * outdated signer, and prints the exact `--doctor --repair` line for the agent
+ * it describes — with `--credentials-dir` whenever more than one agent lives on
+ * the machine, so the repair cannot land on a different agent.
+ *
+ * `-y` because an upgrade hint is often run by an agent in a non-interactive
+ * shell. `@haven_ai/core`'s `upgradeCommandFor` (the backend's
+ * `client_update.upgrade_command`) cannot import this package, so it carries a
+ * copy; `packages/backend/src/__tests__/connector-upgrade-command-parity.test.ts`
+ * fails if the two ever disagree. Setup-time hints (identity restore,
+ * mid-setup retry) legitimately stay on {@link connectorRerunCommand}.
+ */
+declare function connectorUpgradeCommand(options?: {
+    channel?: string;
+}): string;
+
+/**
+ * The Node.js floor Haven's published packages support (#1161).
+ *
+ * ## Why this lives in the SDK
+ *
+ * Three packages need to enforce the same floor — `connect` (at setup),
+ * `signer` and `mcp` (at startup) — and `@haven_ai/sdk` is the only dependency
+ * all three already share. A copy per package is how the floor drifted in the
+ * first place: `engines` said `>=24` everywhere while connect's runtime manifest
+ * enforced `20.0.0`, so a connect run on Node v23 passed the guard, installed
+ * the signer, and signed a real payment. Two numbers for one fact is one number
+ * too many.
+ *
+ * Each consumer still owns its own refusal — the error type, the exit code, the
+ * wording of "what to do next" — because a library must never terminate its
+ * host process. This module only answers *is this version supported* and *what
+ * should we tell the user*.
+ *
+ * ## Why a floor is enforced at all
+ *
+ * `engines` is advisory: npm emits `EBADENGINE` and installs anyway unless the
+ * user happens to have `engine-strict` set. For a normal library that is a
+ * reasonable default. For the **signer** it is not — it holds the delegate key
+ * and produces every payment signature, so a subtle runtime incompatibility
+ * shows up as a wrong or missing signature on a money path. "It seemed to work"
+ * is precisely the evidence that cannot be relied on there.
+ */
+/**
+ * The minimum supported Node.js version, as `major.minor.patch`.
+ *
+ * MUST equal the `engines.node` floor declared by every published Haven
+ * package. A guard test in each package asserts exactly that against its own
+ * `package.json`, so the two cannot drift again silently.
+ */
+declare const HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
+/**
+ * Compare two Node versions. Negative when `left` is older.
+ *
+ * An unparseable version parses to `0.0.0` and therefore compares as older than
+ * any real floor — fail-closed. A version string Haven cannot read is not
+ * evidence of a supported runtime, and treating it as one would reopen exactly
+ * the hole this module closes.
+ */
+declare function compareNodeVersions(left: string, right: string): number;
+declare function isSupportedNodeVersion(nodeVersion?: string, minimumNodeVersion?: string): boolean;
+interface UnsupportedNodeVersionMessageOptions {
+    /**
+     * What is being refused, in the user's terms — "Haven setup", "The Haven
+     * signer". Leads the message so the reader knows what just stopped.
+     */
+    subject: string;
+    nodeVersion?: string;
+    minimumNodeVersion?: string;
+    /** Appended verbatim as the closing line. Used for the re-run instruction. */
+    retryHint?: string;
+}
+/**
+ * The refusal text.
+ *
+ * Names the detected version, the required version, and **how to fix it** — the
+ * previous message stopped after the two version numbers, which tells a user
+ * they are stuck without telling them how to get unstuck. The version-manager
+ * lines are the fix for nearly everyone; the closing caveat is there because the
+ * runtime that *spawns* the signer is frequently not the shell that was
+ * upgraded, and a desktop app can keep launching the old Node long after
+ * `node -v` in a terminal says otherwise.
+ */
+declare function unsupportedNodeVersionMessage(options: UnsupportedNodeVersionMessageOptions): string;
+
+/**
+ * x402 protocol support for the Haven SDK.
+ *
+ * Provides:
+ * - parsePaymentRequired() — extract payment requirements from a 402 response
+ * - parsePaymentRequiredResponse() — async parser with JSON body fallback
+ * - encodePaymentProof()   — encode a receipt as a PAYMENT-SIGNATURE header
+ *
+ * The main authorizeX402() and fetchWithPayment() are methods on HavenClient
+ * (see client.ts) since they need API access and signing.
+ */
+
+/**
+ * Persisted, agent-scoped facts used to preflight a signed standard x402
+ * payment header. This is an integrity comparison only: it never rebuilds,
+ * modifies, persists, or submits the supplied authorization.
+ */
+interface X402PaymentHeaderContext {
+    merchantTo: string;
+    amountAtomic: string;
+    asset: string;
+    network: string;
+    resourceUrl: string;
+    payer: string;
+    chainId: number;
+}
+/** A deliberately value-free refusal for untrusted payment-header input. */
+declare class X402PaymentHeaderValidationError extends Error {
+    constructor();
+}
+/**
+ * Upper bound on the MERCHANT-requested part of the EIP-3009 authorization
+ * window (#715, epic #713). The x402 library sets
+ * `validBefore = now + maxTimeoutSeconds` straight from the MERCHANT's 402
+ * challenge — without a cap, a malicious or sloppy merchant can request a
+ * year-long window and a leaked signed authorization stays spendable that
+ * whole time. 600 s is generous for any facilitator settle (typical is
+ * 30–60 s). This cap applies only to the signed authorization, never to the
+ * advertised requirements echoed in `accepted`. A merchant requiring more
+ * than the bounded lifetime can still reject at verification; preserving its
+ * offer does not widen Haven's signing policy.
+ */
+declare const X402_MAX_AUTHORIZATION_WINDOW_SECONDS = 600;
+/**
+ * Forward margin ADDED on top of the (clamped) merchant timeout when the
+ * authorization is actually signed (#1256). The x402 verify rule requires
+ * `validBefore ≥ now + maxTimeoutSeconds` AT THE FACILITATOR — but the
+ * upstream library computes `validBefore = now + maxTimeoutSeconds` at
+ * SIGNING time, leaving zero forward margin. Haven's flow guarantees elapsed
+ * time between the two (the funding UserOp confirms before the merchant
+ * retry, ~1 min plus latency), so every purchase against a merchant whose
+ * `maxTimeoutSeconds` exceeded that latency failed structurally — measured
+ * live on Base mainnet: Anchor requires 300 s, and 226 s remained at verify.
+ *
+ * 300 s covers funding + retry latency with room to spare. The #715 exposure
+ * ceiling becomes clamped-timeout + margin ≤ 900 s total forward — a
+ * deliberate widening from 600 s, recorded on #1256: an authorization that
+ * cannot pass verify protects no one, and 900 s is still bounded by the same
+ * clamp discipline.
+ */
+declare const X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = 300;
+declare function normalizePaymentRequired(value: unknown): X402PaymentRequired | null;
+/**
+ * The x402 wire header names, in one place (#2289).
+ *
+ * v2 renamed all three; v1's only name was `X-PAYMENT`, used in BOTH
+ * directions. Haven had adopted the v2 names for everything it *reads* and
+ * kept the v1 name for the one thing it *writes*, which is how a strict v2
+ * merchant came to never see a payment header at all.
+ *
+ * The 2026-08-31 owner decision was to send both outbound names on every
+ * retry rather than switch on `x402Version`: a v1 merchant ignores the name it
+ * does not know, a v2 merchant ignores the legacy one, and no version
+ * heuristic has to be right for a payment to land.
+ *
+ * **That is no longer unconditional (#2341).** It held while the cost of a
+ * spare header was zero, and on the EIP-3009 bridge it still is. On erc7710 it
+ * is not: that header carries a whole delegation chain, and duplicating it
+ * overflowed the merchant's header limit — HTTP 431, every erc7710 settlement
+ * refused. `x402PaymentHeaderNamesFor` below is the live rule; read it rather
+ * than this paragraph, which records why the simpler rule was right first.
+ */
+/** v2 client→server payment payload. The name a strict v2 merchant reads. */
+declare const X402_PAYMENT_HEADER_NAME = "PAYMENT-SIGNATURE";
+/** v1 client→server payment payload; still accepted by most v2 merchants. */
+declare const X402_LEGACY_PAYMENT_HEADER_NAME = "X-PAYMENT";
+/** v2 server→client payment requirements. */
+declare const X402_PAYMENT_REQUIRED_HEADER_NAME = "PAYMENT-REQUIRED";
+/** v2 server→client settlement receipt. */
+declare const X402_PAYMENT_RESPONSE_HEADER_NAME = "PAYMENT-RESPONSE";
+/**
+ * Both wire names, v2 first — the value an EIP-3009 retry actually sends.
+ *
+ * **Not the general answer any more (#2341), and not what a recorder should
+ * reach for.** This was the evidence record's `paymentProofHeaderName` while
+ * both names always went on the wire; erc7710 now sends one, so a recorder
+ * still reading this constant would log a legacy header that was never sent —
+ * exactly the drift the previous wording promised it prevented. Use
+ * `x402PaymentHeaderNamesSent(paymentHeader)`. Kept exported because it is a
+ * published surface and removing it would break consumers.
+ */
+declare const X402_PAYMENT_HEADER_NAMES_SENT = "PAYMENT-SIGNATURE, X-PAYMENT";
+/**
+ * Which payment header names to put on the wire for THIS payload (#2341).
+ *
+ * #2289 set both names unconditionally, and on the EIP-3009 bridge that is
+ * right: the header is a signature plus a six-field authorization, doubling it
+ * costs nothing, and lenient v1-only merchants are real. On **erc7710** it is
+ * not right, and it is not merely wasteful — the header carries the whole
+ * `[child, budget]` delegation chain plus the UserOperation, so sending it
+ * twice pushed the request past the server header-size limit and merchants
+ * answered **HTTP 431 Request Header Fields Too Large**. Every erc7710
+ * settlement failed, with the funding leg already spent on the hosted path.
+ *
+ * The rule is by SCHEME, not by byte count, because the scheme is what makes
+ * the alias pointless rather than merely large: an erc7710 payload is always
+ * `x402Version: 2` (the backend's `encodeXPaymentHeader` hardcodes it), and a
+ * merchant that can redeem a delegation chain is by construction running x402
+ * v2 plus the MetaMask erc7710 extension — it reads `PAYMENT-SIGNATURE`. The
+ * legacy name cannot help it and can only cost the request. A size threshold
+ * would be an arbitrary number that changes behaviour silently near its edge.
+ *
+ * An unreadable header falls back to BOTH names — the #2289 behaviour. Haven
+ * builds this value itself, so a parse failure means something is already
+ * wrong; the conservative answer there is the one that keeps v1 merchants
+ * working rather than the one that happens to fix a size problem we cannot
+ * confirm this payload has.
+ */
+declare function x402PaymentHeaderNamesFor(paymentHeader: string): readonly string[];
+/**
+ * The retry headers an agent sets on its own merchant retry, ready-made:
+ * `{ <name>: <paymentHeader> }` for every name `x402PaymentHeaderNamesFor`
+ * puts on the wire for this payload (#3727).
+ *
+ * Exists so no caller re-derives the names from prose: the rule is the SDK's
+ * live one (both `PAYMENT-SIGNATURE` and `X-PAYMENT` on eip3009,
+ * `PAYMENT-SIGNATURE` only on erc7710 — the #2341 rule), and a change to it
+ * flows here through the same function the request path uses. Every value is
+ * the header verbatim; only the NAMES vary.
+ */
+declare function x402RetryHeadersFor(paymentHeader: string): Record<string, string>;
+/**
+ * The x402 v2 payment envelope: `{x402Version, resource?, accepted, payload,
+ * extensions?}` per the spec's PaymentPayload (§5.2.2).
+ *
+ * The `resource` and `extensions` echoes are the #2361 fix, and they are not
+ * optional politeness: the spec makes the extensions echo a MUST ("the client
+ * must include at least the info received"), and CoinGecko's facilitator was
+ * live-bisected rejecting the echo-less envelope with a bare 400 while
+ * accepting the identical signature and `accepted`/`payload` bytes with the
+ * echoes added (#2360, Base mainnet, 2026-09-01). Both objects are echoed
+ * VERBATIM from the merchant's 402 — never reconstructed — and omitted when
+ * the challenge carries none, which keeps the envelope byte-identical to the
+ * pre-#2361 shape for echo-less merchants (Ampersend and Soundside settled
+ * that shape live, so omission is the proven-compatible default).
+ *
+ * The `accepted` wrap itself is #303's shape and predates this helper — see
+ * the #300/#303 history before "fixing" it: scheme/network live INSIDE
+ * `accepted` in v2, never at the top level.
+ */
+declare function x402V2PaymentEnvelope(paymentRequired: Pick<X402PaymentRequired, 'x402Version' | 'resource' | 'extensions'>, accepted: X402PaymentOption, payload: unknown): Record<string, unknown>;
+/**
+ * Parse an HTTP 402 response into x402 PaymentRequired data.
+ *
+ * Supports:
+ * - v2: PAYMENT-REQUIRED header (base64 JSON)
+ * - v1 fallback: X-PAYMENT header or response body
+ */
+declare function parsePaymentRequired(response: Response): X402PaymentRequired;
+/**
+ * Parse an HTTP 402 response into x402 PaymentRequired data.
+ *
+ * Soundside and other Bazaar-style MCP endpoints return the PaymentRequired
+ * object in the JSON body, while older Haven demos and many x402 examples use
+ * base64 headers. This keeps the synchronous header parser intact and adds the
+ * body fallback needed for those endpoints.
+ */
+declare function parsePaymentRequiredResponse(response: Response): Promise<X402PaymentRequired>;
+/**
+ * Select the best payment option from the x402 accepts array.
+ *
+ * Preference order:
+ * 1. Option on a Haven-supported network with a known token
+ * 2. Any option on a Haven-supported network
+ * 3. null — no compatible option
+ */
+declare function selectPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/** The `extra.assetTransferMethod` value that marks an erc7710-settleable entry. */
+declare const ERC7710_ASSET_TRANSFER_METHOD = "erc7710";
+/**
+ * Read `extra.assetTransferMethod` defensively. `extra` is the merchant's own
+ * object, so it is untrusted shape: anything that is not the exact string is
+ * treated as "not erc7710" rather than coerced.
+ */
+declare function x402AssetTransferMethod(option: X402PaymentOption): string | null;
+/** True when the merchant advertises this entry as erc7710-settleable. */
+declare function isErc7710Option(option: X402PaymentOption): boolean;
+/**
+ * The facilitator addresses a merchant advertises for an erc7710 entry, for
+ * the #1058 redeemer pin — or `null` when it pins nothing.
+ *
+ * **An EMPTY array is `null`, not `[]`.** The backend rejects an empty
+ * `redeemers` list with a 400 (`routes/x402.ts`), and the QA scenario already
+ * treats empty as absent. Returning `[]` here would hand callers a value that
+ * means "pin to nobody" — which is not a narrower pin, it is an unbuildable
+ * delegation.
+ *
+ * Malformed entries are DROPPED rather than failing the whole option, and that
+ * asymmetry is deliberate. A pin narrowed by a merchant's typo means the
+ * facilitator that actually tries to redeem is not on the list, so redemption
+ * reverts — and erc7710 has no funding leg, so nothing moved and nothing is
+ * stranded. Refusing the option outright would instead deny a payment the
+ * remaining valid facilitators could have settled. Losing the payment is the
+ * worse outcome, precisely because the failure this issue closes (#1453) is the
+ * one where funds move BEFORE the rejection.
+ */
+declare function x402FacilitatorAddresses(option: X402PaymentOption): string[] | null;
+/**
+ * Select an option that can be paid with the official x402 EIP-3009 exact
+ * scheme. Haven's older tx-hash proof path can describe more networks; the
+ * merchant-verified path currently needs Base USDC.
+ *
+ * **Skips erc7710-tagged entries (#1453).** It used to return the first
+ * positional match and never look at `extra.assetTransferMethod`, so a merchant
+ * that listed its erc7710 entry first made a Haven client echo that option
+ * while signing a standard EIP-3009 authorization. The merchant rejects the
+ * mismatch cleanly — but on the two-leg bridge the account→delegate funding
+ * transfer has already executed, so the visible result is a stranded delegate
+ * balance for the sweep to reclaim. Only our own demo merchant's ordering was
+ * holding that shut, and that pin binds our merchant, not the ones we do not
+ * control.
+ */
+declare function selectStandardPaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/**
+ * Select the erc7710-settleable option, if the merchant advertises one.
+ */
+declare function selectErc7710PaymentOption(accepts: X402PaymentOption[]): X402PaymentOption | null;
+/** What a settlement-scheme decision resolved to. */
+interface X402SchemeSelection {
+    scheme: 'erc7710' | 'eip3009';
+    option: X402PaymentOption;
+    /** Redeemer pin for the settlement child; only ever set on erc7710. */
+    facilitatorAddresses: string[] | null;
+}
+/**
+ * THE preference rule, in one place (#1450 owner decision, #1453).
+ *
+ *   Prefer erc7710 whenever the account is on the delegation rail and the
+ *   merchant advertises `extra.assetTransferMethod: "erc7710"`; fall back to
+ *   the EIP-3009 bridge otherwise.
+ *
+ * Both halves of that condition are required, and the rail half is the
+ * caller's to supply — the SDK cannot see which rail an account is on from a
+ * 402 response alone. A legacy AllowanceModule account passing
+ * `delegationRail: true` would select a scheme its account cannot settle; the
+ * backend refuses that at authorize with the #1986 retired-rail 410 (#2245 —
+ * previously a scheme-specific 400 that wrongly implied the legacy rail could
+ * still settle via EIP-3009), which is where a rail mismatch SHOULD fail,
+ * on-chain-adjacent rather than in a client that could be lying to itself.
+ *
+ * Returns `null` when neither scheme has a payable entry — the caller decides
+ * whether that is an error or a reason to look elsewhere.
+ */
+declare function selectX402SettlementScheme(accepts: X402PaymentOption[], opts: {
+    delegationRail: boolean;
+}): X402SchemeSelection | null;
+declare function x402AuthorizationAmount(option: X402PaymentOption): string;
+/**
+ * Canonical Haven-authenticated x402 expected context, recomputed byte-for-byte
+ * by the edge signer before it signs anything.
+ *
+ * **Two versions, and the version is derived — never passed in (#1138).**
+ * `typedDataHash` present ⇒ v2, absent ⇒ v1. A v1 message is byte-identical to
+ * what shipped before, so existing signers keep verifying legacy-rail bindings
+ * unchanged.
+ *
+ * The version lives in both the header line and the payload so neither can be
+ * reinterpreted as the other: a v2 context cannot be replayed as a v1 one that
+ * drops the typed-data commitment, and a v1 context cannot be presented as v2.
+ * That downgrade is exactly the attack the digest exists to stop — see
+ * `assertExpectedBinding` in `@haven_ai/signer`, which refuses to raw-sign a
+ * hash under a v2 binding and refuses to sign typed data without one.
+ */
+declare function buildX402ExpectedMessage(context: X402ExpectedContext): string;
+declare function toStandardPaymentRequirements(paymentRequired: X402PaymentRequired, option: X402PaymentOption): PaymentRequirements;
+/**
+ * Strictly validate an edge-signed EIP-3009 X-PAYMENT header against the
+ * persisted x402 intent context before a hosted relay can submit funding.
+ *
+ * The merchant/facilitator remains the final protocol verifier. This closes a
+ * separate hosted-relay integrity gap: malformed or context-mismatched input
+ * must never cause Haven to relay the funding signature first.
+ */
+declare function validateStandardX402PaymentHeader(paymentHeader: string, context: X402PaymentHeaderContext): Promise<void>;
+/**
+ * Encode a payment receipt as a base64 PAYMENT-SIGNATURE header value.
+ *
+ * This follows the x402 v2 protocol — the server's facilitator will
+ * verify the on-chain transaction referenced by tx_hash.
+ */
+declare function encodePaymentProof(receipt: {
+    txHash: string;
+    paymentId: string;
+    token: string;
+    amount: string;
+    to: string;
+    resourceUrl?: string;
+    accepted?: X402PaymentOption;
+    payer?: string;
+    chainId?: number;
+}): string;
+/**
+ * Resolve a token symbol from a contract address.
+ *
+ * Checks all supported chains. For chain-specific resolution,
+ * pass the optional `network` CAIP-2 string (e.g. "eip155:8453").
+ */
+declare function resolveTokenFromAddress(address: string, network?: string): {
+    symbol: string;
+    decimals: number;
+} | null;
+/**
+ * #3410: token decimals from a SYMBOL + CHAIN — the same registry
+ * `resolveTokenFromAddress` reads, keyed the other way. The address-based
+ * resolver needs the token's contract address, which the consent seed path
+ * (setup-time credential files) does not carry; the symbol and chain it does
+ * carry. Null when the symbol is not registered on that chain (unknown or
+ * custom tokens) — callers must fall back to an explicit atomic label rather
+ * than reading an atomic amount as whole tokens.
+ */
+declare function resolveTokenBySymbol(chainId: number, symbol: string): {
+    symbol: string;
+    decimals: number;
+} | null;
+
+/**
+ * #3271: the integrity check every client runs before signing a direct
+ * delegation-rail payment's typed data.
+ *
+ * A direct payment (`POST /payments`, surfaced as `haven_send` / `haven_pay`)
+ * is signed as the HybridDeleGator's EIP-712 `PackedUserOperation`, and Haven
+ * returns two things for it: that typed data, and `payload_hash` — the
+ * ERC-4337 v0.7 UserOperation hash of the same operation. Nothing used to tie
+ * the two together at signing time. The typed data is multi-KB and reaches the
+ * signer through a language model when it is relayed by hand, so one corrupted
+ * character produced a valid-looking signature over the wrong digest, and the
+ * first sign of it was `AA24 signature error` from the bundler (#3271,
+ * reproduced on dev 2026-09-24).
+ *
+ * This recomputes the v0.7 hash from the typed data's own message and domain
+ * and refuses unless it equals `payload_hash`, and it pins the parts of the
+ * typed data the hash does NOT cover (domain name/version/verifyingContract,
+ * the field list, the EntryPoint). It is a CORRUPTION check: the caller supplies
+ * both values, so it proves they describe the same operation, never that Haven
+ * prepared it. Provenance is the byte-free sign context (`payment_id`); what a
+ * delegate key will sign at all is `assertBoundDirectPaymentUserOp`
+ * (`direct-payment-guard.ts`, #3272 / #3283), which every caller of this check
+ * — `HavenClient.signForData` and the signer's `haven_sign` — runs next.
+ *
+ * Pure viem, no ethers: `@haven_ai/sdk/edge` re-exports it for the edge signer,
+ * and `edge-imports.test.ts` pins that graph.
+ */
+/** Version of the direct-payment sign context (`GET /payments/:id/sign-context`). */
+declare const DIRECT_SIGN_CONTEXT_VERSION = 1;
+/**
+ * #3419: version of the task-budget sign context (`GET
+ * /task-budgets/:id/sign-context`), the sign-then-submit envelope every
+ * `haven_sign { task_budget_id }` call fetches. The backend emits it
+ * (`task-budget-service.ts`, `task_sign_context_version: 1`); the signer
+ * derives its enforced set `SUPPORTED_TASK_SIGN_CONTEXT_VERSIONS` from this
+ * constant — never a second literal — and the hosted/local task-budget
+ * handoffs report it in `signer_compatibility.task_sign_context_version`.
+ * The signer could not carry the single source itself (a published package
+ * cannot host a constant the backend also serves), so it lives beside the
+ * other binding constants here, exactly as `DIRECT_SIGN_CONTEXT_VERSION` does.
+ */
+declare const TASK_SIGN_CONTEXT_VERSION = 1;
+/** The ERC-4337 v0.7 EntryPoint — the only one the delegation rail submits to. */
+declare const ENTRY_POINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+/**
+ * The HybridDeleGator EIP-712 domain constants and the `PackedUserOperation`
+ * field list, vendored from `@metamask/smart-accounts-kit`
+ * (`contracts.HybridDeleGator.constants`, `SIGNABLE_USER_OP_TYPED_DATA`) so the
+ * published packages need no runtime dependency on the kit. Pinned equal to the
+ * kit's values by `userop-binding.test.ts`.
+ */
+declare const HYBRID_DELEGATOR_DOMAIN_NAME = "HybridDeleGator";
+declare const HYBRID_DELEGATOR_DOMAIN_VERSION = "1";
+declare const PACKED_USER_OPERATION_FIELDS: ReadonlyArray<{
+    name: string;
+    type: string;
+}>;
+/** Refusal raised when UserOperation typed data (a direct payment, or the SDK's x402 funding leg) does not match its `payload_hash`. */
+declare class HavenUserOpBindingError extends HavenError {
+    constructor(message: string);
+}
+/** True when the typed data is a `PackedUserOperation` (the direct-payment shape). */
+declare function isPackedUserOperationTypedData(value: unknown): boolean;
+/**
+ * Compute the ERC-4337 v0.7 UserOperation hash from a HybridDeleGator
+ * `PackedUserOperation` typed-data object — the value Haven returns as
+ * `payload_hash` for a direct payment (`getUserOperationHash`, entryPoint 0.7).
+ */
+declare function packedUserOperationHash(typedData: unknown): Hex;
+/**
+ * Refuse (throw `HavenUserOpBindingError`) unless this `PackedUserOperation`
+ * typed data is the operation `payloadHash` names, in the HybridDeleGator
+ * domain of its own sender, against the v0.7 EntryPoint. Returns the
+ * recomputed hash.
+ */
+declare function assertUserOpTypedDataBinding(typedData: unknown, payloadHash: string): Hex;
+
+/**
+ * The counterfactual HybridDeleGator account address for an owner EOA (#3272).
+ *
+ * `haven_sign`'s unbound branch (`@haven_ai/signer`'s `tools.ts`) and, since
+ * #3283, `HavenClient.signForData` (`direct-payment-guard.ts`) sign a
+ * `PackedUserOperation`
+ * only when its `sender` (== `domain.verifyingContract`) is THIS SIGNER'S OWN
+ * delegate account — never any other HybridDeleGator, and never a third
+ * party's. Haven provisions that account counterfactually at signup (#970):
+ * it may have zero on-chain transactions, so the signer must be able to
+ * compute its address OFFLINE, from nothing but the delegate key's own
+ * address.
+ *
+ * This is exactly what `@metamask/smart-accounts-kit`'s
+ * `getCounterfactualAccountData` computes for
+ * `implementation: 'Hybrid'`, `deployParams: [owner, [], [], []]` (no passkey
+ * co-owners — the only shape Haven's signup flow provisions), `deploySalt:
+ * '0x'`: CREATE2 of an `ERC1967Proxy(HybridDeleGatorImpl, initialize(owner,
+ * [], [], []))` behind the `SimpleFactory`.
+ *
+ * VENDORED, NOT IMPORTED. `@metamask/smart-accounts-kit` is a devDependency
+ * only (see `package.json`) — this package installs on users' machines and
+ * must not carry it at runtime. The constants below (the factory and
+ * implementation addresses, the `ERC1967Proxy` bytecode) are copied from the
+ * kit's pinned environment / `@metamask/delegation-abis`' bytecode export,
+ * exactly like `settlement-child.ts` vendors the DelegationManager and caveat
+ * enforcer addresses for the same reason. Cross-checked against the kit by
+ * `packages/signer/src/delegate-account.pins.test.ts`, including against the real, on-chain
+ * `direct-payment-userop.json` fixture.
+ */
+
+/**
+ * SimpleFactory — deterministically deployed, so Base and Base Sepolia share
+ * the address (matches `packages/backend/src/rails/delegation-contracts.ts`'s
+ * `simpleFactory` pin for both chains).
+ */
+declare const SIMPLE_FACTORY_ADDRESS: Address;
+/**
+ * HybridDeleGator implementation — matches `delegation-contracts.ts`'s
+ * `hybridDeleGatorImpl` pin for both chains.
+ */
+declare const HYBRID_DELEGATOR_IMPLEMENTATION: Address;
+/**
+ * Derive the counterfactual HybridDeleGator account address for `owner`, with
+ * no passkey co-owners — the only shape Haven's signup flow provisions
+ * (#970). Pure and offline: no RPC call, no dependency on the account having
+ * been deployed. Verified byte-for-byte against
+ * `@metamask/smart-accounts-kit`'s `getCounterfactualAccountData` by
+ * `packages/signer/src/delegate-account.pins.test.ts`, including against a real Base Sepolia payload served by the dev backend
+ * (`direct-payment-userop.json`).
+ */
+declare function deriveDelegateAccountAddress(owner: Address): Address;
+
+/**
+ * Independent verification of an erc7710 x402 settlement child (#1455).
+ *
+ * Moved from `@haven_ai/signer` into the SDK by #3283 (epic #3284) so the
+ * signer and `HavenClient.signForData` run ONE verifier. The signer checks the
+ * child against the Haven-signed expected context; the SDK checks it against
+ * the merchant's own 402, which Haven does not produce.
+ *
+ * WHY THIS EXISTS. `assertExpectedBinding` proves Haven *declared* a payload:
+ * the expected context is signed by `HAVEN_X402_BINDING_SIGNER` and commits to
+ * the digest of the exact bytes being signed. That is a real property, and it
+ * is not this one. It says nothing about what the payload MEANS.
+ *
+ * A backend that declared `merchantTo = the real merchant` while pinning a
+ * different payee in the child's `AllowedCalldata` caveat would produce a
+ * perfectly consistent pair: the declaration binds the digest, the digest is
+ * the child's, and the child pays someone else. The signature is the authority
+ * here — the merchant's facilitator redeems it and pulls from the treasury — so
+ * the signer has to re-derive the meaning locally or it is a pass-through with
+ * extra steps.
+ *
+ * ADDRESSES ARE PINNED HERE ON PURPOSE. Reading the enforcer map from Haven
+ * would make the check circular: an attacker who can pick which contract counts
+ * as "the payee enforcer" can satisfy any comparison. Taking
+ * `@metamask/smart-accounts-kit` as a runtime dependency was the other option
+ * and was rejected — this package installs on users' machines. The constants
+ * below are snapshot-pinned and cross-checked against the kit by a test
+ * (`packages/signer/src/settlement-child.pins.test.ts`), the same pattern
+ * `packages/core/src/chains.ts` uses against its registry.
+ *
+ * EXTRA CAVEATS ARE ALLOWED, and that is deliberate — verified, not assumed
+ * (#1455 review challenged it directly).
+ *
+ * `DelegationManager.redeemDelegations` loops every caveat of every delegation
+ * and calls `beforeHook` on each, with no break and no try/catch: a single
+ * revert aborts the whole redemption, and nothing lets one caveat cause another
+ * to be skipped. Top-level caveats are therefore strictly AND-ed, so one this
+ * file does not recognise can only add a constraint, never remove one.
+ *
+ * The specific challenge was `LogicalOrWrapperEnforcer`, whose terms encode
+ * several caveat GROUPS and whose own security notice warns that "the redeemer
+ * can select the least restrictive group, bypassing stricter requirements in
+ * other groups". That warning is about groups INSIDE the wrapper — it binds
+ * whoever authors wrapper terms. The wrapper is itself one caveat among the
+ * delegation's, so it is AND-ed with the four required below and cannot unlock
+ * them.
+ *
+ * The shape that WOULD be dangerous is the inverse: a required caveat hidden
+ * inside a wrapper group instead of sitting at top level, where the redeemer
+ * could select a group that omits it. This file scans top-level caveats and
+ * refuses on absence, so that child is refused for lacking the caveat — which
+ * is the correct outcome and is pinned by a test.
+ */
+/** DelegationManager, the EIP-712 `verifyingContract` for a delegation. */
+declare const DELEGATION_MANAGER = "0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3";
+/**
+ * Caveat enforcers, by role. Deterministically deployed, so Base and Base
+ * Sepolia share addresses — verified for both chains by the pin test.
+ */
+declare const CAVEAT_ENFORCERS: {
+    readonly erc20TransferAmount: "0xf100b0819427117EcF76Ed94B358B1A5b5C6D2Fc";
+    readonly allowedCalldata: "0xc2b0d624c1c4319760C96503BA27C347F3260f55";
+    readonly timestamp: "0x1046bb45C8d673d4ea75321280DB34899413c069";
+    readonly redeemer: "0xE144b0b2618071B4E56f746313528a669c7E65c5";
+};
+/** The backend's own ceiling (`MAX_SETTLEMENT_WINDOW_SECONDS`), enforced again here. */
+declare const MAX_SETTLEMENT_WINDOW_SECONDS = 600;
+interface SettlementChildTypedData {
+    domain: {
+        name?: string;
+        version?: string;
+        chainId?: number | string;
+        verifyingContract?: string;
+    };
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/**
+ * True when this typed data is a delegation — the shape that must never be
+ * signed unbound. Excludes a SELF-delegation (`delegate === delegator`,
+ * #3329): that is the shape of a task-budget child
+ * (`task-budget-guards.ts`'s `isTaskChildTypedData`), a DIFFERENT typed-data
+ * class verified by a different function against a different expectation. A
+ * real settlement child's `delegate` is always a facilitator or
+ * `ANY_BENEFICIARY` — never this account's own address — so narrowing here
+ * costs this verifier nothing and keeps the two classes from ever
+ * overlapping.
+ */
+declare function isSettlementChildTypedData(value: unknown): value is SettlementChildTypedData;
+/**
+ * Map an x402 network string to a chain id. Local on purpose (#1455 review):
+ * the chain must come from Haven's SIGNED `network` field, never from the
+ * payload under verification — see `verifySettlementChild`.
+ */
+declare function chainIdForNetwork(network: string | undefined): number | undefined;
+interface SettlementChildExpectation {
+    merchantTo: string;
+    amount: string;
+    asset: string;
+    /**
+     * Derived from the expected context's SIGNED `network`, never from
+     * `typedData.domain.chainId`. Comparing the payload's own claim against
+     * itself is a check that cannot fail — which is exactly what shipped in the
+     * first draft of this file's call site, and what the review caught.
+     */
+    chainId: number;
+    /** ISO timestamp; the child must not outlive it. */
+    expiresAt?: string;
+    /**
+     * #3283 / #3281 criterion 8: the signer's OWN derived delegate account.
+     * When set, the child's `delegator` must be exactly this account — the
+     * child is a re-delegation of this agent's budget, never a grant from some
+     * other account the key happens to control.
+     */
+    delegatorAccount?: string;
+    /**
+     * #3283: the facilitator addresses the merchant's 402 advertised
+     * (`extra.facilitatorAddresses`). When non-empty, the child must carry a
+     * `RedeemerEnforcer` caveat pinning exactly this set — otherwise the child
+     * is a bearer instrument any party could redeem within its bounds.
+     */
+    redeemers?: readonly string[];
+}
+/** `@metamask/delegation-core`'s `ROOT_AUTHORITY` — a delegation chained to nothing. */
+declare const ROOT_AUTHORITY: string;
+/**
+ * Verify a settlement child implements what the expected context declares.
+ * Throws `HavenSigningError` on any disagreement; returns nothing on success.
+ *
+ * `now` is injectable so the expiry checks are testable without faking clocks.
+ */
+declare function verifySettlementChild(typedData: SettlementChildTypedData, expected: SettlementChildExpectation, now?: number): void;
+
+/** Wire code for a typed-data payload outside the signable allowlist. */
+declare const TYPED_DATA_NOT_ALLOWED: "TYPED_DATA_NOT_ALLOWED";
+/**
+ * A typed-data payload was refused before signing because it is not a shape
+ * a delegate key may sign. Nothing was signed. `@haven_ai/signer` subclasses
+ * this to attach its MCP next step; the `code` is the same on both.
+ */
+declare class HavenTypedDataRefusedError extends HavenSigningError {
+    readonly code: typeof TYPED_DATA_NOT_ALLOWED;
+    constructor(message: string);
+}
+/**
+ * Chains the delegation rail has PINNED delegation contracts for
+ * (`packages/backend/src/rails/delegation-contracts.ts`) — the only chains a
+ * direct-payment UserOp may be scoped to. No other chain has a pinned
+ * DelegationManager/enforcer set, so every other chain is deliberately
+ * excluded even where the delegate account itself could exist.
+ */
+declare const DIRECT_PAYMENT_CHAIN_IDS: ReadonlySet<number>;
+/** The DeleGator's single-execution `execute((address,uint256,bytes))` — selector `0x5c1c6dcd`. */
+declare const EXECUTE_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "execute";
+    readonly inputs: readonly [{
+        readonly name: "_execution";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "callData";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+}];
+/**
+ * The content + provenance allowlist (#3272 criteria 1–2). Call ONLY after
+ * `assertUserOpTypedDataBinding` has already proven `typedData` is a
+ * well-formed `PackedUserOperation` matching its own hash — this function
+ * trusts `typedData.domain`/`message` are shaped correctly and checks only
+ * what they SAY. Throws `HavenTypedDataRefusedError` (never returns) on any
+ * disagreement.
+ */
+declare function assertBoundDirectPaymentUserOp(typedData: Record<string, unknown>, delegateAddress: string): void;
+
+/**
+ * The settlement-child half of the same surface (#3283): verify an erc7710
+ * child against `expectation` (from somewhere Haven did not write — the
+ * merchant's 402 in the SDK, the Haven-signed expected context in the
+ * signer), AND that it is re-delegated from this key's OWN account. Throws
+ * `HavenTypedDataRefusedError` (code `TYPED_DATA_NOT_ALLOWED`) on any
+ * disagreement.
+ */
+declare function assertOwnSettlementChild(typedData: unknown, expectation: SettlementChildExpectation, delegateAddress: string): void;
+/**
+ * #3281 (epic #3284, criterion 5): pin WHERE an x402 EIP-3009 funding leg's
+ * redemption sends the money. The funding leg is always
+ * `transfer(<delegate EOA>, <amount>)` of the quoted token
+ * (`delegation-authorize.ts` → `prepareDelegationPayment(agent, token,
+ * payTo = the delegate EOA, amountRaw)`), so the single execution must be
+ * exactly `encodePacked(asset, 0, transfer(delegateAddress, amount))`.
+ *
+ * `delegateAddress` is the signing key's OWN address — local, not from Haven —
+ * so even a compromised Haven can at most move budget into the agent's own
+ * EOA (the hot-delegate residual the sweep returns), never to an attacker.
+ * `asset` and `amount` keep the leg consistent with what is being paid. Two
+ * callers, two sources: the signer's x402 arm (#3281) passes the Haven-signed
+ * expected context's; `HavenClient.signForData` (#3375) passes the 402 option
+ * the SDK is paying, never the `/x402` response.
+ *
+ * Call ONLY after `assertBoundDirectPaymentUserOp` has passed on the same
+ * typed data (it proves the `execute` → `redeemDelegations` shape this reads).
+ * Throws `HavenTypedDataRefusedError` on any disagreement.
+ */
+declare function assertFundingLegPaysDelegate(typedData: Record<string, unknown>, expected: {
+    delegateAddress: string;
+    asset: string;
+    amount: string;
+}): void;
+
+/**
+ * Task budgets (#3329): independent verification of a task child delegation
+ * and its close UserOp, mirroring `settlement-child.ts` / `direct-payment-
+ * guard.ts` for a DIFFERENT typed-data class.
+ *
+ * A task budget's child is a SELF-delegation: the agent's own delegate
+ * account grants itself a narrower, time-boxed slice of its budget
+ * delegation (`delegate === delegator === the agent's own account`), chained
+ * under the budget via `authority`. That is what separates it from an x402
+ * settlement child, whose `delegate` is a facilitator/ANY_BENEFICIARY — never
+ * the agent's own account. `isSettlementChildTypedData` (`settlement-
+ * child.ts`) was narrowed to return `false` for a self-delegated payload so
+ * the two classes cannot be confused by either verifier; this file is the
+ * task-child counterpart, verified against a different expectation
+ * (`GET /task-budgets/:id/sign-context`, never a merchant's 402).
+ *
+ * Two shapes, two functions:
+ *  - `assertOwnTaskChild` verifies the `Delegation` typed data signed to OPEN
+ *    a task budget.
+ *  - `assertOwnTaskBudgetCloseUserOp` verifies the `PackedUserOperation`
+ *    typed data signed to CLOSE one early (an on-chain
+ *    `disableDelegation(child)` call from the agent's own account) — an
+ *    authority-REDUCING action only, never a grant.
+ *
+ * `hashDelegation` below reproduces `@metamask/smart-accounts-kit/utils`'s
+ * struct hash (via `@metamask/delegation-core`) byte-for-byte, WITHOUT taking
+ * the kit as a runtime dependency (this package installs on users' machines —
+ * same reasoning `delegate-account.ts` and `settlement-child.ts` give for
+ * their own vendored constants). `DELEGATION_TYPEHASH` / `CAVEAT_TYPEHASH`
+ * are pinned literals, cross-checked against the kit's own `hashDelegation`
+ * by a test vector in `task-budget-guards.test.ts` (which imports the kit
+ * ONLY in that test file).
+ */
+
+/** The backend's own ceiling (`MAX_TASK_BUDGET_TTL_SECONDS`), enforced again here. */
+declare const MAX_TASK_BUDGET_TTL_SECONDS = 86400;
+interface TaskChildTypedData {
+    domain: {
+        name?: string;
+        version?: string;
+        chainId?: number | string;
+        verifyingContract?: string;
+    };
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/**
+ * True when this typed data is a task-budget child: a `Delegation` whose
+ * `delegate` equals its own `delegator` (self-delegation). This is the ONLY
+ * shape distinguishing it from an x402 settlement child (whose `delegate` is
+ * a facilitator or `ANY_BENEFICIARY`) — `isSettlementChildTypedData` is
+ * narrowed to return `false` for this same shape so the two verifiers never
+ * overlap.
+ */
+declare function isTaskChildTypedData(value: unknown): value is TaskChildTypedData;
+interface TaskChildExpectation {
+    chainId: number;
+    tokenAddress: string;
+    maxAmountAtomic: string;
+    recipientAddress: string | null;
+    /** unix seconds — the `TimestampEnforcer`'s `beforeThreshold`. */
+    expiresAt: number;
+    parentDelegationHash: string;
+}
+/**
+ * Verify a task-budget child delegation is EXACTLY what
+ * `GET /task-budgets/:id/sign-context` (purpose `open`) declared, AND that
+ * both `delegate` and `delegator` are this signer's OWN account. Throws
+ * `HavenTypedDataRefusedError` (never returns) on any disagreement.
+ */
+declare function assertOwnTaskChild(typedData: unknown, expected: TaskChildExpectation, delegateAddress: string, now?: number): void;
+interface TaskBudgetCloseExpectation {
+    /** The child delegation's own struct hash (`agent_task_budgets.delegation_hash`). */
+    delegationHash: string;
+}
+/**
+ * Verify a task-budget close UserOp is EXACTLY an on-chain
+ * `disableDelegation(child)` call from the agent's own delegate account —
+ * authority-REDUCING only, never a grant. Throws `HavenTypedDataRefusedError`
+ * (never returns) on any disagreement.
+ */
+declare function assertOwnTaskBudgetCloseUserOp(typedData: Record<string, unknown>, expected: TaskBudgetCloseExpectation, delegateAddress: string): void;
+/**
+ * `@metamask/delegation-core`'s `DELEGATION_TYPEHASH` — pinned, cross-checked
+ * against the kit by a test vector in `task-budget-guards.test.ts`.
+ */
+declare const DELEGATION_TYPEHASH: Hex;
+/** `@metamask/delegation-core`'s `CAVEAT_TYPEHASH` — pinned, same cross-check. */
+declare const CAVEAT_TYPEHASH: Hex;
+interface DelegationForHashing {
+    delegate: Address;
+    delegator: Address;
+    authority: Hex;
+    caveats: readonly {
+        enforcer: Address;
+        terms: Hex;
+    }[];
+    salt: bigint;
+}
+/**
+ * Reproduces `@metamask/smart-accounts-kit/utils`'s `hashDelegation`
+ * byte-for-byte, WITHOUT the kit at runtime (see the file header). Ignores
+ * `signature` — the kit's own `hashDelegation` does the same (it hashes with
+ * `signature: '0x'` regardless of what the caller passes).
+ */
+declare function hashDelegation(delegation: DelegationForHashing): Hex;
+
+/**
+ * Runtime-agnostic base64 helpers — the single source of truth for the wire
+ * encoding shared by the SDK and the edge signer (#325).
+ *
+ * Why this module exists: the SDK used `atob`/`btoa` (Web globals) while the
+ * signer used `Buffer` (Node-only). Both worked because both currently run in
+ * Node ≥ 16, but the duplication was a latent wire-incompatibility — and the
+ * signer is headed for non-Node runtimes (browsers, Cloudflare Workers) where
+ * `Buffer` does not exist (#314).
+ *
+ * Encoding contract:
+ * - Output is ALWAYS standard base64 (`+`, `/`, padded). The x402 protocol's
+ *   reference implementation validates headers against
+ *   `/^[A-Za-z0-9+/]*={0,2}$/` — URL-safe output would be rejected.
+ * - Decoding is tolerant: URL-safe input (`-`, `_`, unpadded) is normalized
+ *   before decoding, since third-party merchants are not guaranteed to be as
+ *   strict as the reference implementation.
+ * - UTF-8 throughout. Naive `btoa(JSON.stringify(...))` throws on any
+ *   non-Latin-1 character (e.g. a merchant description with an emoji or
+ *   non-ASCII name); these helpers route through TextEncoder/TextDecoder on
+ *   the Web path so multibyte characters round-trip identically on both
+ *   runtimes.
+ */
+/** Encode a UTF-8 string as standard base64. */
+declare function encodeBase64Utf8(value: string): string;
+/** Decode standard or URL-safe base64 to a UTF-8 string. */
+declare function decodeBase64Utf8(value: string): string;
+/** Encode a JSON-serializable value as a standard-base64 string. */
+declare function encodeBase64Json(value: unknown): string;
+/**
+ * Decode a base64 JSON payload.
+ *
+ * Pass a `label` to get a wrapped error message instead of the raw
+ * JSON/base64 error — call sites parsing untrusted merchant headers use this
+ * to produce actionable failures.
+ */
+declare function decodeBase64Json<T>(value: string, label?: string): T;
+
+export { X402_PAYMENT_HEADER_NAMES_SENT as $, type SweepEip712Domain as A, type SweepExpectedAuth as B, CONNECTOR_PACKAGE_NAME as C, DEFAULT_NEXT_TOOL_BY_ACTION as D, ENTRY_POINT_V07 as E, type SweepPreparation as F, type SweepSubmitResult as G, type HavenClientUpdate as H, type SweepTypedData as I, TRANSFER_WITH_AUTHORIZATION_TYPES as J, TYPED_DATA_NOT_ALLOWED as K, type TaskBudgetCloseExpectation as L, MAX_TASK_BUDGET_TTL_SECONDS as M, NEXT_TOOL_SERVER_NAMES as N, type TaskChildExpectation as O, PACKED_USER_OPERATION_FIELDS as P, type TaskChildTypedData as Q, ROOT_AUTHORITY as R, type SweepPrepareResponse as S, TASK_SIGN_CONTEXT_VERSION as T, type UnsupportedNodeVersionMessageOptions as U, X402PaymentHeaderValidationError as V, type X402SchemeSelection as W, type X402PaymentHeaderContext as X, X402_LEGACY_PAYMENT_HEADER_NAME as Y, X402_MAX_AUTHORIZATION_WINDOW_SECONDS as Z, X402_PAYMENT_HEADER_NAME as _, type SweepAuthorization as a, HYBRID_DELEGATOR_IMPLEMENTATION as a$, X402_PAYMENT_REQUIRED_HEADER_NAME as a0, X402_PAYMENT_RESPONSE_HEADER_NAME as a1, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS as a2, assertBoundDirectPaymentUserOp as a3, assertOwnTaskBudgetCloseUserOp as a4, assertOwnTaskChild as a5, assertUserOpTypedDataBinding as a6, buildSweepAuthorizationMessage as a7, buildSweepTypedData as a8, buildX402ExpectedMessage as a9, renderNextTool as aA, resolveConnectorChannel as aB, resolveTokenBySymbol as aC, resolveTokenFromAddress as aD, selectErc7710PaymentOption as aE, selectPaymentOption as aF, selectStandardPaymentOption as aG, selectX402SettlementScheme as aH, sweepUsdcAddress as aI, sweepUsdcDomain as aJ, toStandardPaymentRequirements as aK, unsupportedNodeVersionMessage as aL, validateStandardX402PaymentHeader as aM, verifySettlementChild as aN, x402AssetTransferMethod as aO, x402AuthorizationAmount as aP, x402FacilitatorAddresses as aQ, x402PaymentHeaderNamesFor as aR, x402RetryHeadersFor as aS, x402V2PaymentEnvelope as aT, type DelegationForHashing as aU, CAVEAT_ENFORCERS as aV, CAVEAT_TYPEHASH as aW, DELEGATION_MANAGER as aX, DELEGATION_TYPEHASH as aY, DIRECT_PAYMENT_CHAIN_IDS as aZ, EXECUTE_ABI as a_, compareNodeVersions as aa, connectorRerunCommand as ab, connectorSpec as ac, connectorUpgradeCommand as ad, createNextStepBuilder as ae, decodeBase64Json as af, decodeBase64Utf8 as ag, defaultNextToolFor as ah, deriveDelegateAccountAddress as ai, encodeBase64Json as aj, encodeBase64Utf8 as ak, encodePaymentProof as al, hashDelegation as am, havenClientIdentity as an, isConnectorChannel as ao, isErc7710Option as ap, isPackedUserOperationTypedData as aq, isSupportedNodeVersion as ar, isSweepableChain as as, isTaskChildTypedData as at, normalizePaymentRequired as au, packedUserOperationHash as av, parseNextTool as aw, parsePaymentRequired as ax, parsePaymentRequiredResponse as ay, readClientUpdate as az, type SweepSubmitResponse as b, MAX_SETTLEMENT_WINDOW_SECONDS as b0, SIMPLE_FACTORY_ADDRESS as b1, type SettlementChildTypedData as b2, assertFundingLegPaysDelegate as b3, assertOwnSettlementChild as b4, chainIdForNetwork as b5, isSettlementChildTypedData as b6, DIRECT_SIGN_CONTEXT_VERSION as c, ERC7710_ASSET_TRANSFER_METHOD as d, HAVEN_CLIENT_HEADER as e, HAVEN_CONNECTOR_CHANNEL as f, HAVEN_MINIMUM_NODE_VERSION as g, HYBRID_DELEGATOR_DOMAIN_NAME as h, HYBRID_DELEGATOR_DOMAIN_VERSION as i, HavenTypedDataRefusedError as j, HavenUserOpBindingError as k, NEXT_TOOL_SERVER_ROLES as l, type NextStep as m, type NextStepArguments as n, type NextStepHandoff as o, type NextStepInput as p, type NextStepTarget as q, type NextStepTargets as r, type NextToolServerRole as s, SDK_CLIENT_IDENTITY as t, SDK_VERSION as u, SWEEP_BASE_CHAIN_ID as v, SWEEP_BASE_SEPOLIA_CHAIN_ID as w, SWEEP_BASE_SEPOLIA_USDC_ADDRESS as x, SWEEP_BASE_USDC_ADDRESS as y, type SettlementChildExpectation as z };