@haven_ai/sdk 0.0.0-dev.202609180723.d49b927 → 0.0.0-dev.202609180817.b16be14

package/dist/index.cjs

@@ -1420,6 +1420,51 @@ function throwPaymentStateError(label, raw) {
   throw new HavenApiError(message, statusCode, raw);
 }
 
+// src/x402-retry-target.ts
+function resolveX402RetryTarget(input) {
+  const requestUrl = input.requestUrl?.trim() || void 0;
+  if (requestUrl) {
+    return {
+      url: requestUrl,
+      source: "request",
+      resourceUrlDiffersFromRequest: requestUrl !== input.resourceUrl
+    };
+  }
+  return { url: input.resourceUrl, source: "resource" };
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "::1", "[::1]"]);
+var RESERVED_SUFFIXES = [".test", ".localhost", ".invalid", ".example"];
+var IPV4_LOOPBACK = /^127(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function isSecureX402RetryTarget(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol === "https:") return true;
+  if (parsed.protocol !== "http:") return false;
+  const host = parsed.hostname.toLowerCase();
+  if (LOOPBACK_HOSTS.has(host) || IPV4_LOOPBACK.test(host)) return true;
+  return RESERVED_SUFFIXES.some((suffix) => host.endsWith(suffix));
+}
+var INSECURE_RETRY_TARGET_CODE = "INSECURE_RETRY_TARGET";
+var HavenInsecureRetryTargetError = class extends HavenError {
+  constructor(url) {
+    super(
+      `Refusing to send a payment header to ${url}: the paid x402 retry must go to an https URL (or a loopback / reserved test host). The merchant's challenge declared this resource URL; retry with the https URL you quoted (pass it as \`url\`), and report a merchant whose challenge downgrades the scheme.`,
+      INSECURE_RETRY_TARGET_CODE,
+      400
+    );
+    this.url = url;
+    this.name = "HavenInsecureRetryTargetError";
+  }
+  url;
+};
+function assertSecureX402RetryTarget(url) {
+  if (!isSecureX402RetryTarget(url)) throw new HavenInsecureRetryTargetError(url);
+}
+
 // src/mcp-merchant-transport.ts
 var DEFAULT_MERCHANT_TIMEOUT = 3e5;
 var MCP_NOTIFICATION_TIMEOUT = 1e4;
@@ -1577,6 +1622,7 @@ var McpMerchantTransport = class {
    * overwrite, which is worse than the duplicate this change removes.
    */
   async deliverPayment(url, init, paymentHeader) {
+    assertSecureX402RetryTarget(url);
     const headers = new Headers(init?.headers);
     const send = x402PaymentHeaderNamesFor(paymentHeader);
     for (const name of X402_PAYMENT_HEADER_NAMES) {
@@ -2006,6 +2052,11 @@ function buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport)
     request,
     ...mcpTransport ? { mcpTransport } : {},
     resourceUrl: paymentRequired.resource.url,
+    // #3097: the merchant's declaration vs the URL the caller quoted. The
+    // paid retry goes to the caller's URL; a quote that says the two disagree
+    // is how an agent sees a challenge that downgrades the scheme or moves
+    // the host before it pays.
+    resourceUrlDiffersFromRequest: paymentRequired.resource.url !== request.url,
     description: paymentRequired.resource.description ?? option.description ?? null,
     mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
     amountAtomic: x402AuthorizationAmount(option),
@@ -4289,10 +4340,10 @@ var toolDescriptions = {
     nextActionGuidance: "On a decline, report the reason to the user and ask them to raise the budget in Haven \u2014 there is no approval queue to wait on. This tool retries the merchant itself while it runs, so do not wait on a signal mid-call. If the process crashes after payment, a later haven_get_payment_status call may report nextAction=retry_original_x402_request \u2014 resume via haven_resume_x402_payment instead of paying again."
   },
   discoverTools: {
-    summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use next.",
-    selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Use verified=verified for entries Haven watched pass a live quote probe (operator-curated or self-submitted) \u2014 domain_verified is the only ownership claim; never treat these badges as proof of merchant honesty, quality, or reliability. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the pay tool to use next.",
-    behavior: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, suggested_tool, and the provenance badges source/domain_verified/verified_payable. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
-    nextActionGuidance: `Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1") \u2014 never convert it to atomic units by hand.`
+    summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, the next call.",
+    selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Use verified=verified for entries Haven watched pass a live quote probe (operator-curated or self-submitted) \u2014 domain_verified is the only ownership claim; never treat these badges as proof of merchant honesty, quality, or reliability. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the next tool to call.",
+    behavior: "Use each entry's suggested_tool + suggested_arguments first; an entry without them says why. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, the hint, and the provenance badges source/domain_verified/verified_payable. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
+    nextActionGuidance: `Call suggested_tool with suggested_arguments VERBATIM (no hint: read suggested_tool_omitted_reason). Confirm the price from the live quote or pay result, not the catalog; if the next tool takes a cap, pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1"), never atomic units by hand.`
   },
   submitCatalogEntry: {
     summary: "Submit a merchant's payable (x402/MCP) endpoint to Haven's Verified Payable Directory for verification and listing.",
@@ -5087,11 +5138,13 @@ exports.HAVEN_SKILL_MD = HAVEN_SKILL_MD;
 exports.HavenApiError = HavenApiError;
 exports.HavenClient = HavenClient;
 exports.HavenError = HavenError;
+exports.HavenInsecureRetryTargetError = HavenInsecureRetryTargetError;
 exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.HavenUnsupportedSignerVersionError = HavenUnsupportedSignerVersionError;
 exports.HavenZeroSettlementHashError = HavenZeroSettlementHashError;
+exports.INSECURE_RETRY_TARGET_CODE = INSECURE_RETRY_TARGET_CODE;
 exports.MERCHANT_DISCOVERY_PATHS = MERCHANT_DISCOVERY_PATHS;
 exports.MerchantTimeoutError = MerchantTimeoutError;
 exports.RECEIPT_VERSION = RECEIPT_VERSION;
@@ -5114,6 +5167,7 @@ exports.X402_PAYMENT_REQUIRED_HEADER_NAME = X402_PAYMENT_REQUIRED_HEADER_NAME;
 exports.X402_PAYMENT_RESPONSE_HEADER_NAME = X402_PAYMENT_RESPONSE_HEADER_NAME;
 exports.X402_SETTLEMENT_FORWARD_MARGIN_SECONDS = X402_SETTLEMENT_FORWARD_MARGIN_SECONDS;
 exports.addressFromKey = addressFromKey;
+exports.assertSecureX402RetryTarget = assertSecureX402RetryTarget;
 exports.buildSweepAuthorizationMessage = buildSweepAuthorizationMessage;
 exports.buildSweepTypedData = buildSweepTypedData;
 exports.buildX402ExpectedMessage = buildX402ExpectedMessage;
@@ -5130,6 +5184,7 @@ exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.isConnectorChannel = isConnectorChannel;
 exports.isErc7710Option = isErc7710Option;
+exports.isSecureX402RetryTarget = isSecureX402RetryTarget;
 exports.isSupportedNodeVersion = isSupportedNodeVersion;
 exports.isSweepableChain = isSweepableChain;
 exports.isZeroSettlementTxHash = isZeroSettlementTxHash;
@@ -5139,6 +5194,7 @@ exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.readX402ReceiptPayer = readX402ReceiptPayer;
 exports.resolveConnectorChannel = resolveConnectorChannel;
 exports.resolveTokenFromAddress = resolveTokenFromAddress;
+exports.resolveX402RetryTarget = resolveX402RetryTarget;
 exports.sameUrl = sameUrl;
 exports.selectErc7710PaymentOption = selectErc7710PaymentOption;
 exports.selectPaymentOption = selectPaymentOption;