@haven_ai/signer 0.0.0-dev.202609031523.fd49e1a

package/dist/index.d.cts

@@ -0,0 +1,482 @@
+import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod/v3';
+
+/**
+ * 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
+ * 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
+     * validates the typed data, not the bare ERC-4337 hash; raw-signing the
+     * hash produced AA24 on-chain (found live, #908 mainnet canary). Signed
+     * VERBATIM (#829): the exact structure the hosted result carried — and,
+     * unlike a blind hash, a structure whose recipient/amount/account are
+     * 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.
+     *
+     * 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`.
+     */
+    signX402FundingTypedData(typedData: X402FundingTypedData, 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.
+     */
+    signSweepAuthorization(input: SweepSignatureInput): Promise<SweepSignatureResult>;
+}
+interface SweepSignatureInput {
+    /** The authorization fields prepared by the backend. */
+    authorization: SweepAuthorization;
+    /** Haven's signature over the authorization context (binding). */
+    expectedAuth: SweepExpectedAuth;
+    /** Optional Safe address from the local credential, cross-checked against `to`. */
+    expectedSafe?: string;
+}
+interface SweepSignatureResult {
+    /** EIP-712 signature over the TransferWithAuthorization, by the delegate key. */
+    signature: string;
+}
+/** EIP-712 payload the delegation-rail account validates (#1138). */
+interface X402FundingTypedData {
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+interface X402ExpectedPayment {
+    /** Haven payment id for the funding transfer. */
+    paymentId: string;
+    /** Funding hash this expected context authenticates. */
+    payloadHash: string;
+    /**
+     * EIP-712 digest of the typed data the account validates (#1138). Present ⇒
+     * the binding is v2 and the delegation-rail typed-data path is the ONLY
+     * signing path allowed for this intent.
+     */
+    typedDataHash?: string;
+    /**
+     * Resource URL of the x402 payment Haven prepared. On the hosted surface
+     * that is `haven_pay_x402_quote` — `buildX402SigningContext` in
+     * `mcp-server/src/tools.ts` relays `intent.resourceUrl` here, and
+     * `haven_resume_x402_payment` re-emits the same context. Checked against
+     * the merchant header's resource in `assertX402MatchesExpected`.
+     */
+    resourceUrl: string;
+    /**
+     * Merchant recipient of that same prepared payment (`intent.merchantTo`,
+     * same source). Checked against the header's `payTo` in
+     * `assertX402MatchesExpected` and, for an erc7710 settlement child,
+     * against the child's payee caveat in `verifySettlementChild`.
+     */
+    merchantTo: string;
+    /** Atomic amount funded for the merchant header. */
+    amount: string;
+    /** Token contract funded for the merchant header. */
+    asset: string;
+    /** x402 network funded for the merchant header. */
+    network: string;
+    /** ISO expiry for the funding/quote window. When present, the signer refuses stale merchant headers. */
+    expiresAt?: string;
+    /**
+     * The delegate address this quote was created FOR (#1690). Present ⇒ the
+     * context is **version 3**, and the signer refuses to sign when it is not
+     * its own delegate. Inside the Haven-signed message, so it cannot be
+     * stripped or forged without breaking the binding signature.
+     */
+    payerDelegate?: string;
+    /** The paying agent's id — carried for the refusal's diagnosis (#1690). */
+    payerAgentId?: string;
+    /** Haven signature over the expected funding context. */
+    auth: X402ExpectedAuth;
+}
+interface X402HeaderResult {
+    /** The merchant-verifiable X-PAYMENT header value. */
+    paymentHeader: string;
+    /** The x402 option this header pays. */
+    accepted: X402PaymentOption;
+}
+interface X402FundingSignatureResult {
+    /** Raw ECDSA signature over the Haven funding hash. */
+    signature: string;
+    /** Opaque process-local binding for the later merchant header signing step. */
+    x402Binding: string;
+}
+interface EdgeSignerOptions {
+    /** Address allowed to authenticate x402 expected-context messages from Haven. */
+    x402BindingSigner?: string;
+    /**
+     * This signer's OWN agent id, from the local credential (#1690). Used only
+     * to make the payer-mismatch refusal name both sides; the guard itself
+     * compares delegate addresses and works without it.
+     */
+    agentId?: string;
+}
+declare function createEdgeSigner(delegateKey: string, options?: EdgeSignerOptions): EdgeSigner;
+declare function assertX402MatchesExpected(paymentRequired: X402PaymentRequired, option: X402PaymentOption, expected: X402ExpectedPayment): void;
+/**
+ * Expected-context binding versions THIS signer understands (#1143).
+ *
+ * The backend deploys continuously from `dev`; a signer reaches users only on a
+ * merge to `main` (the publish workflow). So a signer that is one release behind
+ * a context bump is a structural state, not an accident, and it needs to report
+ * itself as one. These sets are the signer's authority on what it will sign —
+ * the tool schemas deliberately accept any positive integer so an unknown
+ * 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
+ * `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:
+ * the array announces what this signer can evaluate, it does not define it.
+ */
+declare const SUPPORTED_X402_EXPECTED_VERSIONS: readonly number[];
+declare const SUPPORTED_SWEEP_BINDING_VERSIONS: readonly number[];
+/**
+ * Fail closed on a binding version this signer does not understand, with an
+ * error that names the received version, the ceiling this signer supports, and
+ * the fix — both as PROSE (`message`, unchanged since #1143) and, since #1309,
+ * as MACHINE-READABLE fields on the thrown error itself
+ * (`HavenUnsupportedSignerVersionError`): `code`, `supportedVersions`,
+ * `receivedVersion`, `fallback`. The tool boundary (`normalizeError` in
+ * `tools.ts`) relays those fields verbatim instead of leaving an agent to
+ * regex-parse this prose, which is the diagnosability gap
+ * `docs/operations/mcp-runtime-compatibility.md` documents.
+ *
+ * `supportedVersions`/`receivedVersion` are DERIVED from this call's own
+ * arguments — never a second literal — so they cannot drift from
+ * `SUPPORTED_X402_EXPECTED_VERSIONS` / `SUPPORTED_SWEEP_BINDING_VERSIONS`,
+ * which is what the signing path always passes in.
+ *
+ * The version travels inside the Haven-signed binding message, so the message
+ * also tells the caller not to "fix" it by rewriting the field — an agent that
+ * does would invalidate the signature and misrepresent what Haven declared.
+ * That instruction is NOT weakened by structuring the refusal: this function
+ * still throws before any content check runs, and nothing is ever signed.
+ *
+ * #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
+ * 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
+ * not; the owner-signed delegation and its on-chain caveat are. The property
+ * claimed is unchanged — only the verb naming it. Full argument in
+ * `docs/regulatory/casp-changelog/2026-09-01-2347.md`.
+ *
+ * Exported so a test can pin the historical case (a v2 context against a signer
+ * whose set was `{1}`) that this signer can no longer produce on its own. The
+ * signing path always passes the module constants above.
+ */
+declare function assertSupportedBindingVersion(received: number, supported: readonly number[], context: 'x402 expected context' | 'sweep authorization binding'): void;
+
+/**
+ * Pre-payment skew detection (#1155).
+ *
+ * #1143 made a stale signer say so — but only at the signing step, after the
+ * agent had already quoted and was one call away from funding. This module
+ * moves the same information to the `initialize` handshake, so the set of
+ * expected-context versions this signer understands is observable *before* a
+ * payment is attempted.
+ *
+ * **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
+ * 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
+ * server-side gate. A mismatch is advisory: the enforcement point remains the
+ * #1143 signing-time guard, which is unchanged.
+ *
+ * Everything below is DERIVED from the two constants in `core.ts` that the
+ * signing path actually enforces. A second hand-maintained literal is the one
+ * way this feature could become a lie, so there isn't one — including inside
+ * the human-readable `instructions` string, which renders the same arrays.
+ */
+/**
+ * Vendor-prefixed key under MCP's `capabilities.experimental`.
+ *
+ * `experimental` rather than the newer `extensions` field deliberately: both are
+ * `Record<string, object>` in `@modelcontextprotocol/sdk@1.29`, but a client on
+ * an older SDK parses the `initialize` result with a `ServerCapabilities` schema
+ * that has no `extensions` key, and Zod's default object behaviour would strip
+ * it. `experimental` has been in the schema since the beginning, so it survives
+ * an old client — which is precisely the population this feature exists for.
+ */
+declare const SIGNER_CAPABILITY_KEY = "haven/signer-compatibility";
+interface SignerCompatibility {
+    /** Expected-context versions this signer will verify (`SUPPORTED_X402_EXPECTED_VERSIONS`). */
+    x402_expected_context_versions: number[];
+    /** Sweep-binding versions this signer will verify (`SUPPORTED_SWEEP_BINDING_VERSIONS`). */
+    sweep_binding_versions: number[];
+}
+/** The supported sets this signer enforces, as a plain serialisable object. */
+declare function signerCompatibility(): SignerCompatibility;
+/**
+ * The machine-readable half: `capabilities.experimental['haven/signer-compatibility']`,
+ * returned verbatim in the `initialize` result.
+ *
+ * `ServerCapabilities.experimental` is typed `z.record(z.string(), <any object>)`
+ * and the SDK's `mergeCapabilities` deep-merges per top-level key, so declaring
+ * this at construction survives the `tools` capability `McpServer` registers
+ * when the first tool is added.
+ */
+declare function signerCapabilityAdvertisement(): {
+    experimental: Record<string, SignerCompatibility>;
+};
+/**
+ * The agent-readable half: MCP `instructions`, which clients surface to the
+ * model. The machine-readable capability above is the precise statement, but
+ * most agent runtimes never expose `capabilities.experimental` to the model —
+ * this string is what actually reaches the reader who has to make the call.
+ *
+ * It names the same fix as #1143 so an agent that hits either surface — the
+ * handshake here or the signing-time error there — tells the user the same
+ * thing.
+ */
+declare function signerInstructions(): string;
+
+/**
+ * The edge signer's own credential requires *only* `delegate_key` — unlike
+ * `@haven_ai/mcp`, no `api_key` belongs in this file.
+ *
+ * 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
+ * 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
+ * file, so no directory) leaves that path with no identity to load and the
+ * process making no network calls at all. The delegate key read here is never
+ * part of any request or response either way.
+ */
+interface SignerCredentials {
+    delegateKey: string;
+    agentId?: string;
+    safeAddress?: string;
+    chainId?: number;
+    network?: string;
+    x402BindingSigner?: string;
+    /** Absolute path the key was loaded from, if a file was used. */
+    sourcePath?: string;
+}
+/**
+ * Resolve the delegate key for the edge signer.
+ *
+ * Order — earlier wins:
+ *   1. Explicit `path` (e.g. `--credentials <path>`).
+ *   2. `HAVEN_CREDENTIALS` env var pointing at a credential JSON file.
+ *   3. `HAVEN_DELEGATE_KEY` env var.
+ *
+ * The same credential JSON the dashboard emits works here — we just read its
+ * `delegate_key` and ignore the rest.
+ */
+declare function loadSignerCredentials(path?: string | undefined): Promise<SignerCredentials>;
+/**
+ * Warn (best-effort, POSIX only) when the credential file is readable beyond
+ * its owner. Mirrors `@haven_ai/mcp`'s check — the delegate key is the most
+ * sensitive thing on the machine.
+ *
+ * Exported for testing.
+ */
+declare function warnIfCredentialFilePermissive(path: string, log?: (message: string) => void, platform?: NodeJS.Platform): Promise<void>;
+
+interface SigningAuditEntry {
+    version: 1;
+    timestamp: string;
+    tool: SignerToolName;
+    payload_hash: string;
+    delegate_address: string;
+    safe_address?: string;
+    chain_id?: number;
+}
+interface SigningAuditContext {
+    delegateAddress: string;
+    safeAddress?: string;
+    chainId?: number;
+    auditPath?: string;
+}
+declare function defaultSigningAuditPath(credentialsPath?: string): string;
+declare function appendSigningAuditEntry(entry: SigningAuditEntry, path: string): Promise<void>;
+declare function createSigningAuditEntry(tool: SignerToolName, payloadHash: string, context: SigningAuditContext, now?: Date): SigningAuditEntry;
+declare function hashPayloadForAudit(payload: unknown): string;
+
+interface HavenIdentity {
+    apiUrl: string;
+    apiKey: string;
+}
+
+/**
+ * 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;
+ * they never call the Haven API and never emit the key.
+ */
+type SignerToolName = 'haven_sign' | 'haven_x402_sign_header' | 'haven_sign_x402' | 'haven_sign_sweep_delegate';
+declare const toolSchemas: Record<SignerToolName, z.ZodRawShape>;
+declare const toolDescriptions: Record<SignerToolName, string>;
+interface ToolSuccess<T> {
+    success: true;
+    data: T;
+}
+interface ToolFailure {
+    success: false;
+    code: string;
+    message: string;
+    statusCode?: number;
+    paymentId?: string;
+    next_action?: string;
+    retry_with_new_quote?: boolean;
+    suggested_tool?: string;
+    /**
+     * #1309: present on `UNSUPPORTED_EXPECTED_CONTEXT_VERSION` /
+     * `UNSUPPORTED_SWEEP_BINDING_VERSION` refusals — the exact version set this
+     * signer install enforces, derived from `SUPPORTED_X402_EXPECTED_VERSIONS` /
+     * `SUPPORTED_SWEEP_BINDING_VERSIONS` at the throw site.
+     */
+    supported_versions?: number[];
+    /** #1309: the version Haven sent that triggered the refusal above. */
+    received_version?: number;
+    /**
+     * #1309: precise recovery guidance as DATA, not just prose inside `message`
+     * — the same text the hosted quote's advisory `signer_compatibility.fallback`
+     * carries when the refusal is an out-of-date signer.
+     */
+    fallback?: string;
+}
+type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
+interface ToolHandlerOptions {
+    audit?: SigningAuditContext & {
+        auditPath: string;
+    };
+    /**
+     * #1263: how the payment_id signing path reaches Haven. Lives at the MCP
+     * server layer (the core stays network-free); absent → payment_id calls
+     * refuse with a message naming the typed_data_b64 fallback.
+     */
+    signContext?: {
+        loadIdentity: () => Promise<HavenIdentity | null>;
+        fetchImpl?: typeof fetch;
+    };
+}
+declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOptions): Record<SignerToolName, (input: unknown) => Promise<ToolPayload>>;
+
+interface SignerConsentInput {
+    delegateAddress: string;
+    safeAddress?: string;
+    agentId?: string;
+    chainId?: number;
+    network?: string;
+    toolNames: readonly SignerToolName[];
+}
+interface SignerConsentDecision {
+    ok: boolean;
+    hash: string;
+    reason: 'env_var_match' | 'ack_file_match' | 'wrote_ack_file' | 'env_var_mismatch' | 'no_acknowledgement';
+}
+interface SignerConsentOptions {
+    credentialsPath?: string;
+    writeAck?: boolean;
+    env?: Record<string, string | undefined>;
+    out?: {
+        write: (chunk: string) => unknown;
+    };
+}
+declare const SIGNER_ACK_ENV = "HAVEN_SIGNER_ACK";
+declare function computeSignerConsentHash(input: SignerConsentInput): string;
+declare function renderSignerConsentBlock(input: SignerConsentInput, hash: string): string;
+declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
+
+declare const SIGNER_NAME = "@haven_ai/signer";
+declare const SIGNER_VERSION = "0.0.0-dev.202609031523.fd49e1a";
+interface SignerOptions {
+    /** Path to a Haven credential JSON file (delegate_key is read from it). */
+    credentialsPath?: string;
+    /** Pre-resolved delegate key (skips credential loading). */
+    delegateKey?: string;
+    /** Append local signing audit entries here. Defaults to a credential sidecar or ~/.haven. */
+    auditPath?: string;
+    /** Overridable so the Node-floor refusal is testable without spawning a Node. */
+    nodeVersion?: string;
+    /**
+     * When true, write the consent sidecar file (`<credentials>.signer-ack.json`)
+     * with the current consent hash and proceed. Surfaced via the `--ack` CLI flag.
+     */
+    writeAck?: boolean;
+    /**
+     * When true, skip the consent gate entirely. Reserved for tests and controlled
+     * embedding — production CLIs should not set this.
+     */
+    skipConsent?: boolean;
+    /** Override consent environment lookup. Reserved for tests and controlled embedding. */
+    consentEnv?: Record<string, string | undefined>;
+    /** Override the stream the consent block is printed to. Reserved for tests. */
+    consentOut?: {
+        write: (chunk: string) => unknown;
+    };
+    /** Trusted Haven signer address for x402 expected-context bindings. */
+    x402BindingSigner?: string;
+}
+declare function resolveEdgeSigner(options?: SignerOptions): Promise<EdgeSigner>;
+interface ResolvedSignerRuntime {
+    signer: EdgeSigner;
+    credentials?: SignerCredentials;
+}
+declare function resolveSignerRuntime(options?: SignerOptions): Promise<ResolvedSignerRuntime>;
+/**
+ * Build a local stdio MCP server exposing the sign-only tools, bound to an
+ * edge signer that holds the delegate key. It exposes no construct/relay
+ * tools — it only signs. Its ONE network capability (#1263) is an
+ * authenticated READ: fetching a payment's exact signing context from Haven
+ * by payment_id, so agents never have to relay multi-KB signing payloads
+ * through a model context. The signer CORE below it stays network-free, and
+ * fetched bytes pass the same verification as tool-argument bytes.
+ */
+declare function buildSignerMcpServer(signer: EdgeSigner, options?: Pick<SignerOptions, 'auditPath'> & {
+    credentials?: SignerCredentials;
+}): McpServer;
+/**
+ * Refuse to start on an unsupported Node (#1161).
+ *
+ * Asserted at STARTUP, not only at install, because the two can diverge: a user
+ * upgrades Node, connects successfully, then downgrades — or a version manager
+ * hands the agent runtime a different Node than the shell that ran setup. Only a
+ * startup check sees the version this process is actually running on.
+ *
+ * This is the signer, so refusing is the conservative answer rather than the
+ * aggressive one. It holds the delegate key and produces every payment
+ * signature; on an unsupported runtime the plausible failure is a wrong or
+ * absent signature, which is worse than not starting. The consent gate below
+ * takes the same posture for the same reason.
+ */
+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>;
+
+export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, 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, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive };