uvd-x402-sdk 2.85.0 → 2.87.0

package/dist/backend/index.mjs

@@ -1,4 +1,4 @@
-import 'ethers';
+import { ethers } from 'ethers';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -46,6 +46,19 @@ var CAIP2_IDENTIFIERS = {
 var CAIP2_TO_CHAIN = Object.fromEntries(
   Object.entries(CAIP2_IDENTIFIERS).map(([k, v]) => [v, k])
 );
+var X402Error = class _X402Error extends Error {
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.name = "X402Error";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _X402Error);
+    }
+  }
+};
 
 // src/chains/index.ts
 var DEFAULT_FACILITATOR_URL = "https://facilitator.ultravioletadao.xyz";
@@ -1113,6 +1126,195 @@ var DEFAULT_MIN_FEE_BPS = 0;
 var DEFAULT_MAX_FEE_BPS = OPERATOR_FEE_BPS + MAX_PROTOCOL_FEE_BPS;
 var REVIEW_WINDOW_SEC = 7 * 24 * 3600;
 var REFUND_WINDOW_SEC = 7 * 24 * 3600;
+var LIFECYCLE_DOMAIN_NAME = "x402 escrow lifecycle";
+var LIFECYCLE_DOMAIN_VERSION = "1";
+var LIFECYCLE_MAX_DEADLINE_SECS = 900;
+var LIFECYCLE_DEFAULT_DEADLINE_SECS = 600;
+var LIFECYCLE_ACTIONS = ["release", "refundInEscrow"];
+var LIFECYCLE_ORDER_TYPES = {
+  LifecycleOrder: [
+    { name: "action", type: "string" },
+    { name: "amount", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+    { name: "paymentInfo", type: "PaymentInfo" }
+  ],
+  PaymentInfo: [
+    { name: "operator", type: "address" },
+    { name: "payer", type: "address" },
+    { name: "receiver", type: "address" },
+    { name: "token", type: "address" },
+    { name: "maxAmount", type: "uint120" },
+    { name: "preApprovalExpiry", type: "uint48" },
+    { name: "authorizationExpiry", type: "uint48" },
+    { name: "refundExpiry", type: "uint48" },
+    { name: "minFeeBps", type: "uint16" },
+    { name: "maxFeeBps", type: "uint16" },
+    { name: "feeReceiver", type: "address" },
+    { name: "salt", type: "uint256" }
+  ]
+};
+var LIFECYCLE_PI_KEYS = [
+  "operator",
+  "receiver",
+  "token",
+  "maxAmount",
+  "preApprovalExpiry",
+  "authorizationExpiry",
+  "refundExpiry",
+  "minFeeBps",
+  "maxFeeBps",
+  "feeReceiver",
+  "salt"
+];
+function saltToBigInt(salt) {
+  if (typeof salt === "bigint") return salt;
+  if (typeof salt === "number") {
+    if (!Number.isInteger(salt) || salt < 0) {
+      throw new X402Error(`paymentInfo.salt invalid: ${String(salt)}`, "INVALID_CONFIG");
+    }
+    return BigInt(salt);
+  }
+  if (typeof salt === "string") {
+    const trimmed = salt.trim();
+    const hex = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed : `0x${trimmed}`;
+    try {
+      return BigInt(hex);
+    } catch {
+      throw new X402Error(`paymentInfo.salt invalid: ${salt}`, "INVALID_CONFIG");
+    }
+  }
+  throw new X402Error(`paymentInfo.salt invalid: ${String(salt)}`, "INVALID_CONFIG");
+}
+function nonceToBytes32(nonce) {
+  if (typeof nonce !== "string") {
+    throw new X402Error(`lifecycleAuth.nonce invalid: ${String(nonce)}`, "INVALID_CONFIG");
+  }
+  const raw = nonce.startsWith("0x") || nonce.startsWith("0X") ? nonce.slice(2) : nonce;
+  if (!/^[0-9a-fA-F]*$/.test(raw)) {
+    throw new X402Error(`lifecycleAuth.nonce is not hex: ${nonce}`, "INVALID_CONFIG");
+  }
+  if (raw.length !== 64) {
+    throw new X402Error(
+      `lifecycleAuth.nonce must be 32 bytes, got ${raw.length / 2}`,
+      "INVALID_CONFIG"
+    );
+  }
+  return `0x${raw.toLowerCase()}`;
+}
+function randomNonce() {
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues) {
+    const bytes = new Uint8Array(32);
+    webCrypto.getRandomValues(bytes);
+    return ethers.hexlify(bytes);
+  }
+  return ethers.hexlify(ethers.randomBytes(32));
+}
+function resolveOrderTiming(params) {
+  const nowSec = params.now === void 0 ? Math.floor(Date.now() / 1e3) : Math.floor(params.now);
+  return {
+    nowSec,
+    deadline: params.deadline === void 0 ? nowSec + LIFECYCLE_DEFAULT_DEADLINE_SECS : Math.floor(params.deadline),
+    nonce: params.nonce === void 0 ? randomNonce() : params.nonce
+  };
+}
+function toUintString(value, field) {
+  let n;
+  try {
+    n = typeof value === "bigint" ? value : BigInt(value);
+  } catch {
+    throw new X402Error(`${field} must be a non-negative integer, got ${String(value)}`, "INVALID_CONFIG");
+  }
+  if (n < 0n) {
+    throw new X402Error(`${field} must be a non-negative integer, got ${String(value)}`, "INVALID_CONFIG");
+  }
+  return n.toString();
+}
+function buildLifecycleTypedData(params) {
+  const { action, paymentInfo, payer, amount, chainId } = params;
+  const { deadline, nonce } = resolveOrderTiming(params);
+  if (!LIFECYCLE_ACTIONS.includes(action)) {
+    throw new X402Error(
+      `unknown lifecycle action ${String(action)}; the facilitator only signs ${LIFECYCLE_ACTIONS.join(", ")}`,
+      "INVALID_CONFIG"
+    );
+  }
+  let amountBig;
+  try {
+    amountBig = typeof amount === "bigint" ? amount : BigInt(amount);
+  } catch {
+    throw new X402Error(`amount must be an integer >= 0, got ${String(amount)}`, "INVALID_AMOUNT");
+  }
+  if (amountBig < 0n) {
+    throw new X402Error(`amount must be an integer >= 0, got ${String(amount)}`, "INVALID_AMOUNT");
+  }
+  const pi = paymentInfo ?? {};
+  const missing = LIFECYCLE_PI_KEYS.filter((k) => pi[k] === void 0);
+  if (missing.length > 0) {
+    throw new X402Error(
+      `paymentInfo is missing fields that enter the signature: ${missing.join(", ")}. The paymentInfo that is SENT is the one that is signed; defaulting a field would sign a different struct than the one that reaches the facilitator.`,
+      "INVALID_CONFIG"
+    );
+  }
+  return {
+    domain: {
+      name: LIFECYCLE_DOMAIN_NAME,
+      version: LIFECYCLE_DOMAIN_VERSION,
+      chainId: Number(chainId)
+    },
+    types: LIFECYCLE_ORDER_TYPES,
+    primaryType: "LifecycleOrder",
+    message: {
+      action,
+      amount: amountBig.toString(),
+      deadline: toUintString(deadline, "deadline"),
+      nonce: nonceToBytes32(nonce),
+      paymentInfo: {
+        operator: ethers.getAddress(paymentInfo.operator),
+        payer: ethers.getAddress(payer),
+        receiver: ethers.getAddress(paymentInfo.receiver),
+        token: ethers.getAddress(paymentInfo.token),
+        maxAmount: toUintString(paymentInfo.maxAmount, "paymentInfo.maxAmount"),
+        preApprovalExpiry: toUintString(paymentInfo.preApprovalExpiry, "paymentInfo.preApprovalExpiry"),
+        authorizationExpiry: toUintString(
+          paymentInfo.authorizationExpiry,
+          "paymentInfo.authorizationExpiry"
+        ),
+        refundExpiry: toUintString(paymentInfo.refundExpiry, "paymentInfo.refundExpiry"),
+        minFeeBps: toUintString(paymentInfo.minFeeBps, "paymentInfo.minFeeBps"),
+        maxFeeBps: toUintString(paymentInfo.maxFeeBps, "paymentInfo.maxFeeBps"),
+        feeReceiver: ethers.getAddress(paymentInfo.feeReceiver),
+        // uint256 in the signature, bytes32 on the wire — see saltToBigInt.
+        salt: saltToBigInt(paymentInfo.salt).toString()
+      }
+    }
+  };
+}
+async function buildLifecycleAuth(params) {
+  const { wallet, ...rest } = params;
+  const { nowSec, deadline: dl, nonce: nonceHex } = resolveOrderTiming(params);
+  if (dl < nowSec) {
+    throw new X402Error(
+      `deadline ${dl} is in the past (now ${nowSec}): the facilitator discards it as \`expired\``,
+      "INVALID_CONFIG"
+    );
+  }
+  if (dl - nowSec > LIFECYCLE_MAX_DEADLINE_SECS) {
+    throw new X402Error(
+      `deadline ${dl} is ${dl - nowSec} s ahead and the facilitator's ceiling is ${LIFECYCLE_MAX_DEADLINE_SECS} s (\`deadline_too_far\`): a leaked order cannot be a standing permission`,
+      "INVALID_CONFIG"
+    );
+  }
+  const typed = buildLifecycleTypedData({ ...rest, deadline: dl, nonce: nonceHex });
+  const signed = await wallet.signTypedData(JSON.stringify(typed));
+  return {
+    signer: wallet.getAddress(),
+    deadline: dl,
+    nonce: nonceToBytes32(nonceHex),
+    signature: signed.signature
+  };
+}
 
 // src/backend/facilitator-error.ts
 var WRITER_LEASE_REASONS = [
@@ -4062,6 +4264,25 @@ var TIER_TIMINGS = {
   premium: { pre: 14400, auth: 172800, refund: 1209600 },
   enterprise: { pre: 86400, auth: 604800, refund: 2592e3 }
 };
+async function resolveLifecycleAuth(action, options, order) {
+  if (options?.lifecycleSigner && options?.lifecycleAuth) {
+    throw new X402Error(
+      "lifecycleSigner and lifecycleAuth are mutually exclusive: the first signs an order here, the second was already signed elsewhere. Passing both means two different orders exist and only one can travel.",
+      "INVALID_CONFIG"
+    );
+  }
+  if (options?.lifecycleAuth) return options.lifecycleAuth;
+  if (!options?.lifecycleSigner) return void 0;
+  return buildLifecycleAuth({
+    action,
+    paymentInfo: order.paymentInfo,
+    payer: order.payer,
+    amount: order.amount,
+    chainId: order.chainId,
+    wallet: options.lifecycleSigner,
+    deadline: options.lifecycleDeadline
+  });
+}
 var OPERATOR_ABI = [
   "function release(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount)",
   "function refundInEscrow(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint120 amount)",
@@ -4202,8 +4423,8 @@ var AdvancedEscrowClient = class {
    * Matches the on-chain AuthCaptureEscrow nonce derivation.
    */
   async computeNonce(paymentInfo) {
-    const { ethers: ethers3 } = await import('ethers');
-    const piTuple = ethers3.AbiCoder.defaultAbiCoder().encode(
+    const { ethers: ethers4 } = await import('ethers');
+    const piTuple = ethers4.AbiCoder.defaultAbiCoder().encode(
       ["bytes32", "tuple(address,address,address,address,uint120,uint48,uint48,uint48,uint16,uint16,address,uint256)"],
       [
         PAYMENT_INFO_TYPEHASH,
@@ -4224,12 +4445,12 @@ var AdvancedEscrowClient = class {
         ]
       ]
     );
-    const piHash = ethers3.keccak256(piTuple);
-    const finalEncoded = ethers3.AbiCoder.defaultAbiCoder().encode(
+    const piHash = ethers4.keccak256(piTuple);
+    const finalEncoded = ethers4.AbiCoder.defaultAbiCoder().encode(
       ["uint256", "address", "bytes32"],
       [this.chainId, this.contracts.escrow, piHash]
     );
-    return ethers3.keccak256(finalEncoded);
+    return ethers4.keccak256(finalEncoded);
   }
   /**
    * Sign ReceiveWithAuthorization for ERC-3009.
@@ -4386,17 +4607,17 @@ var AdvancedEscrowClient = class {
   async release(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, abi, (iface) => {
+        return this.sendViaAdapter(ethers4, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("release", [tuple, amt, "0x"]) : iface.encodeFunctionData("release", [tuple, amt]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.release(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.release(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4420,17 +4641,17 @@ var AdvancedEscrowClient = class {
   async refundInEscrow(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, abi, (iface) => {
+        return this.sendViaAdapter(ethers4, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("refundInEscrow", [tuple, amt, "0x"]) : iface.encodeFunctionData("refundInEscrow", [tuple, amt]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.refundInEscrow(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4465,30 +4686,53 @@ var AdvancedEscrowClient = class {
    * const result = await client.releaseViaFacilitator(pi);
    * console.log(result.transactionHash);
    * ```
+   *
+   * @example Signed release (the payer proves the release is theirs to ask for)
+   * ```typescript
+   * await client.releaseViaFacilitator(pi, undefined, {
+   *   lifecycleSigner: payerWallet,   // EnvKeyAdapter, OWS, wagmiLifecycleSigner(...)
+   * });
+   * ```
+   *
+   * @example Transporting an order the publisher signed in their browser
+   * ```typescript
+   * // The browser sent back a signature over a document THIS backend built.
+   * const lifecycleAuth = lifecycleAuthFromSignature(typedData, signature, payer);
+   * await client.releaseViaFacilitator(pi, amount, { lifecycleAuth });
+   * ```
    */
-  async releaseViaFacilitator(paymentInfo, amount) {
+  async releaseViaFacilitator(paymentInfo, amount, options) {
     if (!this.payerAddress) await this.init();
     try {
+      const wirePaymentInfo = {
+        operator: paymentInfo.operator,
+        receiver: paymentInfo.receiver,
+        token: paymentInfo.token,
+        maxAmount: paymentInfo.maxAmount,
+        preApprovalExpiry: paymentInfo.preApprovalExpiry,
+        authorizationExpiry: paymentInfo.authorizationExpiry,
+        refundExpiry: paymentInfo.refundExpiry,
+        minFeeBps: paymentInfo.minFeeBps,
+        maxFeeBps: paymentInfo.maxFeeBps,
+        feeReceiver: paymentInfo.feeReceiver,
+        salt: paymentInfo.salt
+      };
+      const releaseAmount = amount || paymentInfo.maxAmount;
+      const lifecycleAuth = await resolveLifecycleAuth("release", options, {
+        paymentInfo: wirePaymentInfo,
+        payer: this.payerAddress,
+        amount: releaseAmount,
+        chainId: this.chainId
+      });
       const payload = {
         x402Version: 2,
         scheme: "escrow",
         action: "release",
         payload: {
-          paymentInfo: {
-            operator: paymentInfo.operator,
-            receiver: paymentInfo.receiver,
-            token: paymentInfo.token,
-            maxAmount: paymentInfo.maxAmount,
-            preApprovalExpiry: paymentInfo.preApprovalExpiry,
-            authorizationExpiry: paymentInfo.authorizationExpiry,
-            refundExpiry: paymentInfo.refundExpiry,
-            minFeeBps: paymentInfo.minFeeBps,
-            maxFeeBps: paymentInfo.maxFeeBps,
-            feeReceiver: paymentInfo.feeReceiver,
-            salt: paymentInfo.salt
-          },
+          paymentInfo: wirePaymentInfo,
           payer: this.payerAddress,
-          amount: amount || paymentInfo.maxAmount
+          amount: releaseAmount,
+          ...lifecycleAuth ? { lifecycleAuth } : {}
         },
         paymentRequirements: {
           scheme: "escrow",
@@ -4591,29 +4835,38 @@ var AdvancedEscrowClient = class {
    * }
    * ```
    */
-  async refundViaFacilitator(paymentInfo, amount) {
+  async refundViaFacilitator(paymentInfo, amount, options) {
     if (!this.payerAddress) await this.init();
     try {
+      const wirePaymentInfo = {
+        operator: paymentInfo.operator,
+        receiver: paymentInfo.receiver,
+        token: paymentInfo.token,
+        maxAmount: paymentInfo.maxAmount,
+        preApprovalExpiry: paymentInfo.preApprovalExpiry,
+        authorizationExpiry: paymentInfo.authorizationExpiry,
+        refundExpiry: paymentInfo.refundExpiry,
+        minFeeBps: paymentInfo.minFeeBps,
+        maxFeeBps: paymentInfo.maxFeeBps,
+        feeReceiver: paymentInfo.feeReceiver,
+        salt: paymentInfo.salt
+      };
+      const refundAmount = amount || paymentInfo.maxAmount;
+      const lifecycleAuth = await resolveLifecycleAuth("refundInEscrow", options, {
+        paymentInfo: wirePaymentInfo,
+        payer: this.payerAddress,
+        amount: refundAmount,
+        chainId: this.chainId
+      });
       const payload = {
         x402Version: 2,
         scheme: "escrow",
         action: "refundInEscrow",
         payload: {
-          paymentInfo: {
-            operator: paymentInfo.operator,
-            receiver: paymentInfo.receiver,
-            token: paymentInfo.token,
-            maxAmount: paymentInfo.maxAmount,
-            preApprovalExpiry: paymentInfo.preApprovalExpiry,
-            authorizationExpiry: paymentInfo.authorizationExpiry,
-            refundExpiry: paymentInfo.refundExpiry,
-            minFeeBps: paymentInfo.minFeeBps,
-            maxFeeBps: paymentInfo.maxFeeBps,
-            feeReceiver: paymentInfo.feeReceiver,
-            salt: paymentInfo.salt
-          },
+          paymentInfo: wirePaymentInfo,
           payer: this.payerAddress,
-          amount: amount || paymentInfo.maxAmount
+          amount: refundAmount,
+          ...lifecycleAuth ? { lifecycleAuth } : {}
         },
         paymentRequirements: {
           scheme: "escrow",
@@ -4733,7 +4986,7 @@ var AdvancedEscrowClient = class {
   async charge(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const nonce = await this.computeNonce(paymentInfo);
       const amt = amount || paymentInfo.maxAmount;
       const auth = {
@@ -4745,10 +4998,10 @@ var AdvancedEscrowClient = class {
         nonce
       };
       const signature = await this.signErc3009(auth);
-      const collectorData = ethers3.getBytes(signature);
+      const collectorData = ethers4.getBytes(signature);
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers4, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("charge", [
             tuple,
             amt,
@@ -4757,7 +5010,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.charge(
         tuple,
         amt,
@@ -4799,11 +5052,11 @@ var AdvancedEscrowClient = class {
   async refundPostEscrow(paymentInfo, amount, tokenCollector, collectorData) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers4, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("refundPostEscrow", [
             tuple,
             amt,
@@ -4812,7 +5065,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.refundPostEscrow(
         tuple,
         amt,