@haven_ai/sdk 0.1.18-alpha.0 → 0.1.19-alpha.0

package/dist/index.d.cts

@@ -1692,6 +1692,75 @@ declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for thing
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 
+/**
+ * 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 = "24.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.
  *
@@ -1704,6 +1773,36 @@ declare const SKILL_FOLDER_NAME = "haven-pay";
  * (see client.ts) since they need API access and signing.
  */
 
+/**
+ * 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); we CLAMP rather than reject so payments keep flowing while
+ * exposure stays bounded. `validBefore` is a deadline, not a demand —
+ * settling earlier is always valid.
+ */
+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;
 /**
  * Parse an HTTP 402 response into x402 PaymentRequired data.
  *
@@ -1816,4 +1915,4 @@ declare function encodeBase64Json(value: unknown): string;
  */
 declare function decodeBase64Json<T>(value: string, label?: string): T;
 
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };

package/dist/index.d.ts

@@ -1692,6 +1692,75 @@ declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for thing
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 
+/**
+ * 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 = "24.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.
  *
@@ -1704,6 +1773,36 @@ declare const SKILL_FOLDER_NAME = "haven-pay";
  * (see client.ts) since they need API access and signing.
  */
 
+/**
+ * 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); we CLAMP rather than reject so payments keep flowing while
+ * exposure stays bounded. `validBefore` is a deadline, not a demand —
+ * settling earlier is always valid.
+ */
+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;
 /**
  * Parse an HTTP 402 response into x402 PaymentRequired data.
  *
@@ -1816,4 +1915,4 @@ declare function encodeBase64Json(value: unknown): string;
  */
 declare function decodeBase64Json<T>(value: string, label?: string): T;
 
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type ClaudeTool, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpTransport, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };

package/dist/index.js

@@ -347,6 +347,7 @@ function optionAuthorizationAmount(option) {
   return option.maxAmountRequired ?? option.amount;
 }
 var X402_MAX_AUTHORIZATION_WINDOW_SECONDS = 600;
+var X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = 300;
 function clampAuthorizationWindow(seconds) {
   const requested = typeof seconds === "number" && Number.isFinite(seconds) ? seconds : 30;
   return Math.min(Math.max(Math.floor(requested), 1), X402_MAX_AUTHORIZATION_WINDOW_SECONDS);
@@ -544,7 +545,12 @@ function toStandardPaymentRequirements(paymentRequired, option) {
     // Second enforcement point (#715): the parse path clamps too, but this is
     // the last stop before the x402 library turns the timeout into
     // `validBefore` — options constructed without parsing are bounded here.
-    maxTimeoutSeconds: clampAuthorizationWindow(option.maxTimeoutSeconds),
+    // The forward margin (#1256) is added ONLY here, at signing: the parse
+    // path keeps recording the merchant's advertised timeout unchanged, and
+    // the library's `validBefore = now + this value` then carries enough
+    // slack to satisfy the facilitator's `validBefore ≥ now + maxTimeout`
+    // verify rule after our funding leg confirms.
+    maxTimeoutSeconds: clampAuthorizationWindow(option.maxTimeoutSeconds) + X402_SETTLEMENT_FORWARD_MARGIN_SECONDS,
     extra: option.extra
   };
 }
@@ -3606,6 +3612,45 @@ for that credential.
 `;
 var SKILL_FOLDER_NAME = "haven-pay";
 
+// src/node-version.ts
+var HAVEN_MINIMUM_NODE_VERSION = "24.0.0";
+function parseNodeVersion(value) {
+  const match = value.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!match) return [0, 0, 0];
+  return [Number(match[1] ?? 0), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+function compareNodeVersions(left, right) {
+  const leftParts = parseNodeVersion(left);
+  const rightParts = parseNodeVersion(right);
+  for (let i = 0; i < 3; i += 1) {
+    if (leftParts[i] !== rightParts[i]) return leftParts[i] > rightParts[i] ? 1 : -1;
+  }
+  return 0;
+}
+function isSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = HAVEN_MINIMUM_NODE_VERSION) {
+  return compareNodeVersions(nodeVersion, minimumNodeVersion) >= 0;
+}
+function unsupportedNodeVersionMessage(options) {
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  const minimum = options.minimumNodeVersion ?? HAVEN_MINIMUM_NODE_VERSION;
+  const lines = [
+    `${options.subject} requires Node.js >=${minimum}, but this is Node.js ${nodeVersion}.`,
+    "",
+    "Upgrade Node, then try again:",
+    `  nvm install ${major(minimum)} && nvm use ${major(minimum)}      (nvm)`,
+    `  fnm install ${major(minimum)} && fnm use ${major(minimum)}      (fnm)`,
+    `  volta install node@${major(minimum)}                 (volta)`,
+    `  or download Node ${major(minimum)} from https://nodejs.org`,
+    "",
+    "If you use a version manager, check that the agent runtime launching Haven picks up the same version \u2014 upgrading your shell does not always change what a desktop app spawns."
+  ];
+  if (options.retryHint) lines.push("", options.retryHint);
+  return lines.join("\n");
+}
+function major(version) {
+  return String(parseNodeVersion(version)[0]);
+}
+
 // src/sweep.ts
 var SWEEP_BASE_CHAIN_ID = 8453;
 var SWEEP_BASE_SEPOLIA_CHAIN_ID = 84532;
@@ -3711,6 +3756,6 @@ function stableStringify2(value) {
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
 }
 
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, RECEIPT_VERSION, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, RECEIPT_VERSION, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map