uvd-x402-sdk 2.87.0 → 2.89.0

package/dist/react/index.mjs

@@ -1631,8 +1631,366 @@ var init_solana = __esm({
 
 // src/client/X402Client.ts
 init_types();
+
+// src/policy.ts
+init_types();
+var OFFER_VALIDITY_EXTENSION = "offer-receipt/1";
+function offerValidUntil(extensions) {
+  if (!extensions || typeof extensions !== "object") return void 0;
+  const entry = extensions[OFFER_VALIDITY_EXTENSION];
+  if (!entry || typeof entry !== "object") return void 0;
+  const info = entry.info;
+  if (!info || typeof info !== "object") return void 0;
+  const value = info.validUntil;
+  if (typeof value !== "number") return void 0;
+  if (!Number.isSafeInteger(value) || value < 0) return void 0;
+  return value;
+}
+function canonicalRecipient(address) {
+  const trimmed = address.trim();
+  const rest = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed.slice(2) : null;
+  const isHex = rest !== null && rest.length > 0 && /^[0-9a-fA-F]+$/.test(rest);
+  return isHex ? trimmed.toLowerCase() : trimmed;
+}
+function assetKey(asset) {
+  return `${asset.network.trim().toLowerCase()}|${canonicalRecipient(asset.address)}`;
+}
+function assetLabel(asset) {
+  return asset.address ? `${asset.address} on ${asset.network}` : `(no asset declared) on ${asset.network}`;
+}
+function offerAsset(offer) {
+  return {
+    network: offer.chainName ?? offer.network,
+    address: typeof offer.asset === "string" ? offer.asset : ""
+  };
+}
+function noReadableOffer(offered) {
+  return {
+    code: "no-readable-offer",
+    offered,
+    message: "no offer in this challenge is one this build can pay; offered: " + JSON.stringify(offered)
+  };
+}
+var PolicyRefusedError = class extends X402Error {
+  refusal;
+  constructor(refusal) {
+    super(`payment refused by policy: ${refusal.message}`, "POLICY_REFUSED", refusal);
+    this.name = "PolicyRefusedError";
+    this.refusal = refusal;
+  }
+  /** Stable kebab code of the refusal, for branching. */
+  get policyCode() {
+    return this.refusal.code;
+  }
+};
+var PurchasePolicy = class _PurchasePolicy {
+  perPaymentLimits;
+  cumulativeLimits;
+  /** Shared by reference across every copy: one purse, many holders. */
+  spentTotals;
+  recipients;
+  assetsByKey;
+  unlistedAssetsAllowed;
+  constructor(perPaymentLimits, cumulativeLimits, spentTotals, recipients, assetsByKey, unlistedAssetsAllowed) {
+    this.perPaymentLimits = perPaymentLimits;
+    this.cumulativeLimits = cumulativeLimits;
+    this.spentTotals = spentTotals;
+    this.recipients = recipients;
+    this.assetsByKey = assetsByKey;
+    this.unlistedAssetsAllowed = unlistedAssetsAllowed;
+  }
+  /**
+   * A policy that pays nothing until it is told what it may pay.
+   *
+   * # Why the default is deny
+   *
+   * The limits are a map keyed by asset, and a map answers "no entry" for every
+   * asset nobody thought of. Permitting on a missing entry means a budget in
+   * USDC is **no budget at all** for any other token: a seller offering the same
+   * resource priced in something unlisted walks straight past the ceiling, and
+   * the wallet will sign it, because the EVM signer takes the EIP-712 domain
+   * from the seller's own `extra` and will happily sign for a token and a
+   * network it has never heard of.
+   *
+   * So an asset with no stated ceiling is refused. A caller that genuinely wants
+   * to pay anything says so once, by name, with
+   * {@link PurchasePolicy.allowUnlistedAssets}, and that sentence is then in
+   * their code where a reader can find it.
+   */
+  static create() {
+    return new _PurchasePolicy(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), null, /* @__PURE__ */ new Map(), false);
+  }
+  /**
+   * A policy that permits an asset it was never told about.
+   *
+   * This is what {@link X402Client} holds when the caller supplied no policy,
+   * and it exists for exactly one reason: this SDK had no budget before 2.89.0,
+   * and turning one on silently would refuse payments that callers are making
+   * today. Named rather than defaulted, so choosing it is visible. The asymmetry
+   * is deliberate -- whoever sits down to WRITE a policy deserves the safe
+   * default.
+   */
+  static permissive() {
+    return new _PurchasePolicy(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), null, /* @__PURE__ */ new Map(), true);
+  }
+  /** Permit assets with no configured ceiling. */
+  allowUnlistedAssets() {
+    return this.with({ unlistedAssetsAllowed: true });
+  }
+  /**
+   * Refuse assets with no configured ceiling. The default; here so the intent
+   * can be written down at a call site that wants it explicit.
+   */
+  denyUnlistedAssets() {
+    return this.with({ unlistedAssetsAllowed: false });
+  }
+  /** Most this policy will pay in ONE payment of `asset`, in atomic units. */
+  perPayment(asset, amount) {
+    const key = this.register(asset);
+    const perPaymentLimits = new Map(this.perPaymentLimits);
+    perPaymentLimits.set(key, requireCeiling(amount, "perPayment"));
+    return this.with({ perPaymentLimits });
+  }
+  /**
+   * Most this policy will pay in `asset` in TOTAL, across every payment it
+   * approves for as long as it lives.
+   */
+  cumulative(asset, amount) {
+    const key = this.register(asset);
+    const cumulativeLimits = new Map(this.cumulativeLimits);
+    cumulativeLimits.set(key, requireCeiling(amount, "cumulative"));
+    return this.with({ cumulativeLimits });
+  }
+  /**
+   * Restrict payment to a set of recipients.
+   *
+   * Addresses are canonicalised **by family**, not by lowercasing the string:
+   * see {@link canonicalRecipient}.
+   */
+  onlyPay(recipients) {
+    const set = /* @__PURE__ */ new Set();
+    for (const r of recipients) set.add(canonicalRecipient(r));
+    return this.with({ recipients: set });
+  }
+  /**
+   * Total recorded so far for `asset`, in atomic units.
+   *
+   * A total that is not a sane bigint means something corrupted the purse.
+   * Reporting zero would silently restore the caller's whole budget, so this
+   * reports the CEILING instead: for money, the safe direction is to refuse,
+   * never to permit.
+   */
+  spent(asset) {
+    const key = assetKey(asset);
+    const value = this.spentTotals.get(key);
+    if (value === void 0) return 0n;
+    if (typeof value !== "bigint" || value < 0n) {
+      return this.cumulativeLimits.get(key) ?? 0n;
+    }
+    return value;
+  }
+  /**
+   * Record that a payment actually happened.
+   *
+   * Separate from {@link PurchasePolicy.evaluate} on purpose. Signing can still
+   * fail and a settlement can still be refused; a cumulative limit that counted
+   * attempts rather than payments would lock a caller out of money it never
+   * spent. Call this when a payment settled.
+   *
+   * A negative amount is ignored: handing budget back is not something a
+   * settlement can do, and treating it as one would be a way to widen a policy
+   * from outside.
+   */
+  recordSpend(asset, amount) {
+    if (typeof amount !== "bigint" || amount <= 0n) return;
+    const key = assetKey(asset);
+    if (!this.assetsByKey.has(key)) this.assetsByKey.set(key, asset);
+    const current = this.spent(asset);
+    this.spentTotals.set(key, current + amount);
+  }
+  /**
+   * Whether this policy pays an asset it holds no ceiling for. Read-only: there
+   * is no setter that flips it from inside an evaluation.
+   */
+  get permitsUnlistedAssets() {
+    return this.unlistedAssetsAllowed;
+  }
+  /**
+   * Decide whether this offer may be signed. Steps 2 through 6 of the contract;
+   * step 1 (`no-readable-offer`) is decided on the challenge, before an offer
+   * exists to evaluate -- see {@link decideOnChallenge}.
+   *
+   * **Approving does not record the spend.** See
+   * {@link PurchasePolicy.recordSpend}.
+   */
+  evaluate(offer, options) {
+    const { now, validUntil, quote } = options;
+    if (validUntil !== void 0 && now > validUntil) {
+      return {
+        ok: false,
+        refusal: {
+          code: "offer-expired",
+          validUntil,
+          now,
+          message: `this offer expired at ${validUntil} (now ${now}); ask the seller for new terms`
+        }
+      };
+    }
+    if (this.recipients !== null) {
+      const payTo = canonicalRecipient(offer.payTo);
+      if (!this.recipients.has(payTo)) {
+        return {
+          ok: false,
+          refusal: {
+            code: "recipient-not-permitted",
+            payTo: offer.payTo,
+            message: `this policy does not pay ${offer.payTo}`
+          }
+        };
+      }
+    }
+    const asset = offerAsset(offer);
+    const key = assetKey(asset);
+    const requested = readAmount(offer.amount);
+    if (!this.unlistedAssetsAllowed && !this.perPaymentLimits.has(key) && !this.cumulativeLimits.has(key)) {
+      return {
+        ok: false,
+        refusal: {
+          code: "asset-not-budgeted",
+          asset,
+          message: `this policy has no budget for ${assetLabel(asset)}; it pays only what it was told it may pay`
+        }
+      };
+    }
+    const perPaymentAllowed = this.perPaymentLimits.get(key);
+    if (perPaymentAllowed !== void 0 && requested > perPaymentAllowed) {
+      return {
+        ok: false,
+        refusal: {
+          code: "per-payment-limit",
+          requested,
+          allowed: perPaymentAllowed,
+          asset,
+          message: `offer of ${requested} exceeds the per-payment limit of ${perPaymentAllowed} for ${assetLabel(asset)}`
+        }
+      };
+    }
+    const cumulativeAllowed = this.cumulativeLimits.get(key);
+    if (cumulativeAllowed !== void 0) {
+      const spent = this.spent(asset);
+      const wouldTotal = spent + requested;
+      if (wouldTotal > cumulativeAllowed) {
+        return {
+          ok: false,
+          refusal: {
+            code: "cumulative-limit",
+            requested,
+            spent,
+            wouldTotal,
+            allowed: cumulativeAllowed,
+            asset,
+            message: `offer of ${requested} would take spend to ${wouldTotal}, past the cumulative limit of ${cumulativeAllowed} for ${assetLabel(asset)} (already spent ${spent})`
+          }
+        };
+      }
+    }
+    return {
+      ok: true,
+      approval: { asset, amount: requested, versusQuote: compareToQuote(asset, requested, quote) }
+    };
+  }
+  /** Copy sharing the same purse. Cloning is what a per-request client does. */
+  clone() {
+    return this.with({});
+  }
+  /**
+   * Rebuild with some fields replaced, **always sharing `spentTotals`**. This is
+   * the one place that decides copies share a purse, so it is the one place to
+   * read when asking whether they do.
+   */
+  with(changes) {
+    return new _PurchasePolicy(
+      changes.perPaymentLimits ?? this.perPaymentLimits,
+      changes.cumulativeLimits ?? this.cumulativeLimits,
+      this.spentTotals,
+      changes.recipients !== void 0 ? changes.recipients : this.recipients,
+      this.assetsByKey,
+      changes.unlistedAssetsAllowed ?? this.unlistedAssetsAllowed
+    );
+  }
+  /** Remember an asset's written form and reject one no budget could match. */
+  register(asset) {
+    if (!asset || typeof asset.address !== "string" || asset.address.trim() === "") {
+      throw new X402Error(
+        "A budget needs a token address; an asset with none can never match an offer",
+        "INVALID_CONFIG",
+        { asset }
+      );
+    }
+    if (typeof asset.network !== "string" || asset.network.trim() === "") {
+      throw new X402Error(
+        "A budget needs a network; the same address on two networks is two assets",
+        "INVALID_CONFIG",
+        { asset }
+      );
+    }
+    const key = assetKey(asset);
+    this.assetsByKey.set(key, asset);
+    return key;
+  }
+};
+function requireCeiling(amount, field) {
+  if (typeof amount !== "bigint" || amount < 0n) {
+    throw new X402Error(
+      `${field} must be a non-negative bigint in atomic units`,
+      "INVALID_AMOUNT",
+      { amount: String(amount) }
+    );
+  }
+  return amount;
+}
+function readAmount(amount) {
+  const text = String(amount).trim();
+  if (!/^\d+$/.test(text)) return UNREADABLE_AMOUNT;
+  return BigInt(text);
+}
+var UNREADABLE_AMOUNT = (1n << 256n) - 1n;
+function compareToQuote(asset, requested, quote) {
+  if (!quote) return { code: "not-compared" };
+  if (assetKey(quote.asset) !== assetKey(asset)) {
+    return { code: "different-asset", advertised: quote.asset, offered: asset };
+  }
+  if (quote.amount !== requested) {
+    return { code: "amount-differs", advertised: quote.amount, offered: requested };
+  }
+  return { code: "matches" };
+}
+function decideOnChallenge(policy, challenge, offer, options) {
+  const unreadableCount = challenge.unreadableCount ?? challenge.unreadable.length;
+  if (challenge.offers.length === 0 && unreadableCount > 0) {
+    return { ok: false, refusal: noReadableOffer(challenge.unreadable) };
+  }
+  if (!offer) {
+    return { ok: false, refusal: noReadableOffer(challenge.unreadable) };
+  }
+  return policy.evaluate(offer, {
+    now: options.now,
+    validUntil: offerValidUntil(challenge.extensions),
+    quote: options.quote
+  });
+}
+
+// src/client/X402Client.ts
 init_chains();
 init_utils();
+var KNOWN_SCHEMES = /* @__PURE__ */ new Set([
+  "exact",
+  "upto",
+  "escrow",
+  "commerce",
+  "fhe-transfer"
+]);
+var CLIENT_PAYABLE_SCHEMES = /* @__PURE__ */ new Set(["exact"]);
 var X402Client = class _X402Client {
   // Configuration
   config;
@@ -1651,6 +2009,16 @@ var X402Client = class _X402Client {
   walletAdapter = null;
   // Event emitter
   eventHandlers = /* @__PURE__ */ new Map();
+  /**
+   * What this buyer is allowed to sign, evaluated against the offer in hand
+   * before anything is signed.
+   *
+   * `permissive()` when the caller supplied none, and that asymmetry is
+   * deliberate: this SDK had no budget before 2.89.0, so switching one on
+   * silently would refuse payments consumers are making today, while whoever
+   * sits down to WRITE a policy gets the deny-by-default one.
+   */
+  purchasePolicy;
   constructor(config = {}) {
     this.config = {
       ...DEFAULT_CONFIG,
@@ -1670,8 +2038,18 @@ var X402Client = class _X402Client {
         }
       }
     }
+    this.purchasePolicy = config.policy ?? PurchasePolicy.permissive();
     this.log("X402Client initialized", { config: this.config });
   }
+  /**
+   * The policy in force, for a caller that wants to record a settled payment
+   * against it with {@link PurchasePolicy.recordSpend}.
+   *
+   * Nothing on the payment path ever widens it.
+   */
+  get policy() {
+    return this.purchasePolicy;
+  }
   // ============================================================================
   // PUBLIC API - Wallet Connection
   // ============================================================================
@@ -1892,8 +2270,13 @@ var X402Client = class _X402Client {
       );
     }
     const tokenType = options.tokenType || "usdc";
-    const { version, offers } = this.parse402(body, tokenType);
+    const challenge = this.parse402(body, tokenType);
+    const { version, offers } = challenge;
     if (offers.length === 0) {
+      const unreadableCount = challenge.unreadableCount ?? challenge.unreadable.length;
+      if (unreadableCount > 0) {
+        throw new PolicyRefusedError(noReadableOffer(challenge.unreadable));
+      }
       throw new X402Error(
         "402 response offered no usable payment options",
         "NO_ACCEPTABLE_PAYMENT"
@@ -1920,12 +2303,42 @@ var X402Client = class _X402Client {
         );
       }
     }
+    const decision = decideOnChallenge(this.purchasePolicy, challenge, chosen, {
+      now: Math.floor(Date.now() / 1e3),
+      quote: options.advertised
+    });
+    if (!decision.ok) {
+      this.log("policy refused this offer", { cause: decision.refusal.code });
+      this.emit("paymentFailed", {
+        error: decision.refusal.message,
+        code: "POLICY_REFUSED"
+      });
+      throw new PolicyRefusedError(decision.refusal);
+    }
+    const approval = decision.approval;
+    this.log("policy approved this offer", {
+      versusQuote: approval.versusQuote.code,
+      amount: String(approval.amount)
+    });
     if (!chosen.chainName) {
       throw new X402Error(
         `402 asked for payment on unknown network '${chosen.network}'`,
         "CHAIN_NOT_SUPPORTED"
       );
     }
+    const configuredToken = getTokenConfig(chosen.chainName, tokenType);
+    if (chosen.asset && configuredToken && canonicalRecipient(configuredToken.address) !== canonicalRecipient(chosen.asset)) {
+      throw new X402Error(
+        `402 wants ${chosen.asset} on ${chosen.chainName}, but this client signs ${configuredToken.address} (tokenType '${tokenType}'). Pass the tokenType that matches the offer; signing the configured token would pay a different asset than the one that was approved.`,
+        "NO_ACCEPTABLE_PAYMENT",
+        {
+          offered: chosen.asset,
+          wouldSign: configuredToken.address,
+          tokenType,
+          network: chosen.chainName
+        }
+      );
+    }
     if (chosen.chainName !== this.currentChainName) {
       await this.switchChain(chosen.chainName);
     }
@@ -1943,29 +2356,70 @@ var X402Client = class _X402Client {
     if (version === 2) {
       paidHeaders["PAYMENT-SIGNATURE"] = payment.paymentHeader;
     }
-    return doFetch(url, { ...options.init, method, headers: paidHeaders });
+    const paid = await doFetch(url, { ...options.init, method, headers: paidHeaders });
+    if (paid.status !== 402) {
+      options.onPaid?.(approval);
+    }
+    return paid;
   }
   /**
-   * Normalise a 402 body into its envelope version and its payment offers.
+   * Normalise a 402 body into its envelope version, its payment offers, the ones
+   * it could not read, and the challenge's `extensions`.
    *
    * Reads both spec shapes -- `{x402Version, accepts: [...]}` and the non-spec
    * one where a lone requirement sits at the top level -- and both dialects of
    * the price field (`maxAmountRequired` in v1, `amount` in v2).
+   *
+   * **`accepts` is a list, so one unreadable entry does not sink the list.** A
+   * seller offering `exact` alongside a scheme this build does not implement used
+   * to be unpayable in the Rust crate, and the buyer never learned there was a
+   * perfectly payable offer right there. The readable ones are kept and the
+   * others are counted by scheme name, so a refusal can say what the seller
+   * offered instead of "could not parse". Discovering the service keeps working
+   * even when buying it automatically does not.
+   *
+   * Returns the WHOLE challenge on purpose: handing `offers` alone downstream is
+   * what dropped the seller's `validUntil` on the floor in Rust for a full commit
+   * with every unit test green.
    */
   parse402(body, tokenType) {
     const doc = body ?? {};
     const version = Number(doc.x402Version) === 2 ? 2 : 1;
     const rawAccepts = Array.isArray(doc.accepts) ? doc.accepts : doc.payTo ? [doc] : [];
     const offers = [];
+    const unreadable = [];
+    let unreadableCount = 0;
+    const cannotRead = (accept) => {
+      unreadableCount += 1;
+      const scheme = accept?.scheme;
+      if (typeof scheme === "string" && scheme) unreadable.push(scheme);
+    };
     for (const entry of rawAccepts) {
-      if (!entry || typeof entry !== "object") continue;
+      if (!entry || typeof entry !== "object") {
+        cannotRead(null);
+        continue;
+      }
       const accept = entry;
+      const declaredScheme = accept.scheme;
+      if (typeof declaredScheme !== "string" || !declaredScheme || !KNOWN_SCHEMES.has(declaredScheme) || !CLIENT_PAYABLE_SCHEMES.has(declaredScheme)) {
+        cannotRead(accept);
+        continue;
+      }
       const amount = accept.amount ?? accept.maxAmountRequired;
       const payTo = accept.payTo;
       const network = accept.network;
-      if (amount === void 0 || amount === null) continue;
-      if (typeof payTo !== "string" || !payTo) continue;
-      if (typeof network !== "string" || !network) continue;
+      if (amount === void 0 || amount === null) {
+        cannotRead(accept);
+        continue;
+      }
+      if (typeof payTo !== "string" || !payTo) {
+        cannotRead(accept);
+        continue;
+      }
+      if (typeof network !== "string" || !network) {
+        cannotRead(accept);
+        continue;
+      }
       const chainName = getChainByName(network) ? network : caip2ToChain(network);
       offers.push({
         network,
@@ -1977,7 +2431,8 @@ var X402Client = class _X402Client {
         raw: accept
       });
     }
-    return { version, offers };
+    const extensions = doc.extensions && typeof doc.extensions === "object" && !Array.isArray(doc.extensions) ? doc.extensions : void 0;
+    return { version, offers, unreadable, unreadableCount, extensions };
   }
   /**
    * Decimals to read an offer's atomic `amount` with.