@agentokratia/x402-escrow 2.0.0

package/dist/index.js

@@ -0,0 +1,568 @@
+// src/client/session-wrapper.ts
+import { isAddress, getAddress as getAddress2 } from "viem";
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+
+// src/client/escrow.ts
+import { toHex as toHex2, getAddress } from "viem";
+
+// src/types.ts
+var X402_HEADERS = {
+  /** Server → Client: Payment options (402 response) - base64 JSON */
+  PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
+  /** Client → Server: Payment payload - base64 JSON */
+  PAYMENT_SIGNATURE: "PAYMENT-SIGNATURE",
+  /** Server → Client: Settlement result - base64 JSON (includes session data) */
+  PAYMENT_RESPONSE: "PAYMENT-RESPONSE"
+};
+function fromBase64(str) {
+  try {
+    if (typeof atob !== "undefined") {
+      return decodeURIComponent(escape(atob(str)));
+    }
+    return Buffer.from(str, "base64").toString("utf-8");
+  } catch {
+    return Buffer.from(str, "base64").toString("utf-8");
+  }
+}
+function generateRequestId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+function generateRandomBytes(length) {
+  const bytes = new Uint8Array(length);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < length; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return bytes;
+}
+function parsePaymentResponseHeader(header) {
+  try {
+    return JSON.parse(fromBase64(header));
+  } catch {
+    return null;
+  }
+}
+
+// src/constants.ts
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var DEFAULT_SESSION_DURATION = 3600;
+var DEFAULT_REFUND_WINDOW = 86400;
+
+// src/client/storage.ts
+var BaseStorage = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  get(network, receiver) {
+    const now = Date.now() / 1e3;
+    for (const session of this.sessions.values()) {
+      if (session.network === network && session.receiver.toLowerCase() === receiver.toLowerCase() && session.authorizationExpiry > now) {
+        return session;
+      }
+    }
+    return null;
+  }
+  findBest(network, receiver, minAmount) {
+    const now = Date.now() / 1e3;
+    let best = null;
+    let bestBalance = 0n;
+    for (const session of this.sessions.values()) {
+      if (session.network === network && session.receiver.toLowerCase() === receiver.toLowerCase() && session.authorizationExpiry > now) {
+        const balance = BigInt(session.balance);
+        if (balance >= minAmount && balance > bestBalance) {
+          best = session;
+          bestBalance = balance;
+        }
+      }
+    }
+    return best;
+  }
+  set(session) {
+    this.sessions.set(session.sessionId, session);
+    this.onUpdate();
+  }
+  update(sessionId, balance) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      this.sessions.set(sessionId, { ...session, balance });
+      this.onUpdate();
+    }
+  }
+  list() {
+    return Array.from(this.sessions.values());
+  }
+  remove(sessionId) {
+    this.sessions.delete(sessionId);
+    this.onUpdate();
+  }
+  /** Override in subclasses for persistence */
+  onUpdate() {
+  }
+};
+var InMemoryStorage = class extends BaseStorage {
+  // No persistence needed
+};
+var BrowserLocalStorage = class extends BaseStorage {
+  constructor(key = "x402-sessions") {
+    super();
+    this.key = key;
+    this.load();
+  }
+  onUpdate() {
+    this.save();
+  }
+  load() {
+    if (typeof localStorage === "undefined") return;
+    try {
+      const data = localStorage.getItem(this.key);
+      if (data) {
+        const sessions = JSON.parse(data);
+        for (const s of sessions) this.sessions.set(s.sessionId, s);
+      }
+    } catch {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn("[x402] Failed to load sessions from localStorage");
+      }
+    }
+  }
+  save() {
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(this.key, JSON.stringify(Array.from(this.sessions.values())));
+    } catch {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn("[x402] Failed to save sessions to localStorage");
+      }
+    }
+  }
+};
+function createStorage(type, storageKey) {
+  return type === "localStorage" ? new BrowserLocalStorage(storageKey) : new InMemoryStorage();
+}
+
+// src/client/session-manager.ts
+var SessionManager = class {
+  constructor(network, options = {}) {
+    this.network = network;
+    this.storage = createStorage(options.storage ?? "memory", options.storageKey);
+  }
+  /**
+   * Store a session from escrow settlement response.
+   */
+  store(session) {
+    this.storage.set({ ...session, createdAt: Date.now() });
+  }
+  /**
+   * Get session for a specific receiver.
+   */
+  getForReceiver(receiver) {
+    return this.storage.get(this.network, receiver);
+  }
+  /**
+   * Find best session for receiver with minimum balance.
+   */
+  findBest(receiver, minAmount) {
+    return this.storage.findBest(this.network, receiver, minAmount);
+  }
+  /**
+   * Check if valid session exists for receiver.
+   */
+  hasValid(receiver, minAmount) {
+    const session = minAmount ? this.storage.findBest(this.network, receiver, BigInt(minAmount)) : this.storage.get(this.network, receiver);
+    return session !== null;
+  }
+  /**
+   * Update session balance after debit.
+   */
+  updateBalance(sessionId, newBalance) {
+    this.storage.update(sessionId, newBalance);
+  }
+  /**
+   * Get all stored sessions.
+   */
+  getAll() {
+    return this.storage.list();
+  }
+  /**
+   * Remove a specific session.
+   */
+  remove(sessionId) {
+    this.storage.remove(sessionId);
+  }
+  /**
+   * Clear all sessions.
+   */
+  clear() {
+    for (const session of this.storage.list()) {
+      this.storage.remove(session.sessionId);
+    }
+  }
+};
+
+// src/client/eip712.ts
+import {
+  keccak256,
+  encodeAbiParameters,
+  parseAbiParameters,
+  toHex
+} from "viem";
+var PAYMENT_INFO_TYPE = "PaymentInfo(address operator,address payer,address receiver,address token,uint120 maxAmount,uint48 preApprovalExpiry,uint48 authorizationExpiry,uint48 refundExpiry,uint16 minFeeBps,uint16 maxFeeBps,address feeReceiver,uint256 salt)";
+var PAYMENT_INFO_TYPEHASH = keccak256(toHex(new TextEncoder().encode(PAYMENT_INFO_TYPE)));
+var PAYMENT_INFO_ABI_PARAMS = "bytes32, address, address, address, address, uint120, uint48, uint48, uint48, uint16, uint16, address, uint256";
+var NONCE_ABI_PARAMS = "uint256, address, bytes32";
+var ERC3009_TYPES = {
+  ReceiveWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function computeEscrowNonce(chainId, escrowContract, paymentInfo) {
+  const paymentInfoHash = keccak256(
+    encodeAbiParameters(parseAbiParameters(PAYMENT_INFO_ABI_PARAMS), [
+      PAYMENT_INFO_TYPEHASH,
+      paymentInfo.operator,
+      ZERO_ADDRESS,
+      // payer = 0 for payer-agnostic
+      paymentInfo.receiver,
+      paymentInfo.token,
+      paymentInfo.maxAmount,
+      paymentInfo.preApprovalExpiry,
+      paymentInfo.authorizationExpiry,
+      paymentInfo.refundExpiry,
+      paymentInfo.minFeeBps,
+      paymentInfo.maxFeeBps,
+      paymentInfo.feeReceiver,
+      paymentInfo.salt
+    ])
+  );
+  return keccak256(
+    encodeAbiParameters(parseAbiParameters(NONCE_ABI_PARAMS), [
+      BigInt(chainId),
+      escrowContract,
+      paymentInfoHash
+    ])
+  );
+}
+async function signERC3009(wallet, authorization, domain) {
+  if (!wallet.account) {
+    throw new Error("WalletClient must have an account");
+  }
+  return wallet.signTypedData({
+    account: wallet.account,
+    domain,
+    types: ERC3009_TYPES,
+    primaryType: "ReceiveWithAuthorization",
+    message: {
+      from: authorization.from,
+      to: authorization.to,
+      value: authorization.value,
+      validAfter: authorization.validAfter,
+      validBefore: authorization.validBefore,
+      nonce: authorization.nonce
+    }
+  });
+}
+
+// src/client/escrow.ts
+var EscrowScheme = class {
+  constructor(walletClient, options = {}) {
+    this.scheme = "escrow";
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain");
+    }
+    this.wallet = walletClient;
+    this.chainId = walletClient.chain.id;
+    this.network = `eip155:${walletClient.chain.id}`;
+    this.sessionDuration = options.sessionDuration ?? DEFAULT_SESSION_DURATION;
+    this.refundWindow = options.refundWindow ?? DEFAULT_REFUND_WINDOW;
+    this.customDepositAmount = options.depositAmount ? BigInt(options.depositAmount) : void 0;
+    this.sessions = new SessionManager(this.network, {
+      storage: options.storage,
+      storageKey: options.storageKey
+    });
+  }
+  get address() {
+    return this.wallet.account.address;
+  }
+  // ========== Payment Payload Creation ==========
+  /**
+   * Creates payment payload for escrow scheme.
+   * Auto-detects whether to create new session or use existing one.
+   */
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    const receiver = getAddress(paymentRequirements.payTo);
+    const amount = BigInt(paymentRequirements.amount);
+    const existingSession = this.sessions.findBest(receiver, amount);
+    if (existingSession) {
+      return this.createUsagePayload(x402Version, existingSession, paymentRequirements.amount);
+    }
+    return this.createCreationPayload(x402Version, paymentRequirements);
+  }
+  // ========== Private: Payload Builders ==========
+  /**
+   * Session USAGE payload - uses existing session (no signature).
+   */
+  createUsagePayload(x402Version, session, amount) {
+    return {
+      x402Version,
+      payload: {
+        session: {
+          id: session.sessionId,
+          token: session.sessionToken
+        },
+        amount,
+        requestId: generateRequestId()
+      }
+    };
+  }
+  /**
+   * Session CREATION payload - requires wallet signature.
+   */
+  async createCreationPayload(x402Version, paymentRequirements) {
+    const extra = paymentRequirements.extra;
+    if (!extra.escrowContract || !extra.facilitator || !extra.tokenCollector) {
+      throw new Error("Missing required escrow configuration in payment requirements");
+    }
+    const escrowContract = getAddress(extra.escrowContract);
+    const facilitator = getAddress(extra.facilitator);
+    const tokenCollector = getAddress(extra.tokenCollector);
+    const receiver = getAddress(paymentRequirements.payTo);
+    const token = getAddress(paymentRequirements.asset);
+    const now = Math.floor(Date.now() / 1e3);
+    const salt = this.generateSalt();
+    const authorizationExpiry = now + this.sessionDuration;
+    const refundExpiry = authorizationExpiry + this.refundWindow;
+    const minDeposit = extra.minDeposit ? BigInt(extra.minDeposit) : BigInt(paymentRequirements.amount);
+    const maxDeposit = extra.maxDeposit ? BigInt(extra.maxDeposit) : minDeposit;
+    let amount;
+    if (this.customDepositAmount !== void 0) {
+      if (this.customDepositAmount < minDeposit) {
+        throw new Error(
+          `Deposit amount ${this.customDepositAmount} is below minimum ${minDeposit}`
+        );
+      }
+      if (this.customDepositAmount > maxDeposit) {
+        throw new Error(`Deposit amount ${this.customDepositAmount} exceeds maximum ${maxDeposit}`);
+      }
+      amount = this.customDepositAmount;
+    } else {
+      amount = maxDeposit;
+    }
+    const validAfter = 0n;
+    const validBefore = BigInt(authorizationExpiry);
+    const nonce = computeEscrowNonce(this.chainId, escrowContract, {
+      operator: facilitator,
+      payer: this.address,
+      receiver,
+      token,
+      maxAmount: amount,
+      preApprovalExpiry: authorizationExpiry,
+      authorizationExpiry,
+      refundExpiry,
+      minFeeBps: 0,
+      maxFeeBps: 0,
+      feeReceiver: ZERO_ADDRESS,
+      salt: BigInt(salt)
+    });
+    const domain = {
+      name: extra.name,
+      version: extra.version,
+      chainId: this.chainId,
+      verifyingContract: token
+    };
+    const signature = await signERC3009(
+      this.wallet,
+      { from: this.address, to: tokenCollector, value: amount, validAfter, validBefore, nonce },
+      domain
+    );
+    const payload = {
+      signature,
+      authorization: {
+        from: this.address,
+        to: tokenCollector,
+        value: amount.toString(),
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce
+      },
+      sessionParams: {
+        salt,
+        authorizationExpiry,
+        refundExpiry
+      }
+    };
+    if (paymentRequirements.scheme === "escrow") {
+      payload.requestId = generateRequestId();
+    }
+    const accepted = {
+      scheme: paymentRequirements.scheme,
+      network: paymentRequirements.network,
+      asset: paymentRequirements.asset,
+      amount: paymentRequirements.amount,
+      payTo: paymentRequirements.payTo,
+      maxTimeoutSeconds: paymentRequirements.maxTimeoutSeconds,
+      extra: { ...paymentRequirements.extra, facilitator, escrowContract, tokenCollector }
+    };
+    return { x402Version, accepted, payload };
+  }
+  generateSalt() {
+    return toHex2(generateRandomBytes(32));
+  }
+};
+
+// src/client/session-wrapper.ts
+function createEscrowFetch(walletClient, options) {
+  const scheme = new EscrowScheme(walletClient, options);
+  const x402 = new x402Client().register(scheme.network, scheme);
+  const baseFetch = options?.fetch ?? globalThis.fetch;
+  const paidFetch = wrapFetchWithPayment(baseFetch, x402);
+  return {
+    fetch: withSessionExtraction(paidFetch, scheme),
+    scheme,
+    x402
+    // Expose for adding hooks
+  };
+}
+function extractSession(getHeader, escrowScheme) {
+  const paymentResponseHeader = getHeader("PAYMENT-RESPONSE") || getHeader("payment-response");
+  if (!paymentResponseHeader) return;
+  try {
+    const data = JSON.parse(fromBase64(paymentResponseHeader));
+    if (!data.session?.id) return;
+    if (!data.session.token) {
+      if (data.session.balance !== void 0) {
+        escrowScheme.sessions.updateBalance(data.session.id, data.session.balance);
+      }
+      return;
+    }
+    const receiver = data.requirements?.payTo || data.receiver;
+    if (!receiver) {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn("[x402] Session missing receiver - cannot store");
+      }
+      return;
+    }
+    if (!isAddress(receiver)) {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn("[x402] Invalid receiver address in session:", receiver);
+      }
+      return;
+    }
+    escrowScheme.sessions.store({
+      sessionId: data.session.id,
+      sessionToken: data.session.token,
+      network: escrowScheme.network,
+      payer: escrowScheme.address,
+      receiver: getAddress2(receiver),
+      balance: data.session.balance || "0",
+      authorizationExpiry: data.session.expiresAt || 0
+    });
+  } catch (error) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn("[x402] Failed to parse PAYMENT-RESPONSE:", error);
+    }
+  }
+}
+function withSessionExtraction(paidFetch, escrowScheme) {
+  return async (input, init) => {
+    const response = await paidFetch(input, init);
+    extractSession((name) => response.headers.get(name), escrowScheme);
+    return response;
+  };
+}
+function withAxiosSessionExtraction(escrowScheme) {
+  return (response) => {
+    extractSession((name) => response.headers[name.toLowerCase()], escrowScheme);
+    return response;
+  };
+}
+
+// src/server/utils.ts
+function parseUsdcPrice(price, usdcAddress, decimals = 6) {
+  const defaultAsset = usdcAddress || "";
+  if (typeof price === "object" && "amount" in price && "asset" in price) {
+    return {
+      amount: price.amount,
+      asset: price.asset || defaultAsset,
+      extra: price.extra
+    };
+  }
+  let usdAmount;
+  if (typeof price === "number") {
+    usdAmount = price;
+  } else {
+    const cleanPrice = price.toString().replace(/^\$/, "").trim();
+    usdAmount = parseFloat(cleanPrice);
+  }
+  if (isNaN(usdAmount) || usdAmount < 0) {
+    throw new Error(`Invalid price: ${price}`);
+  }
+  const multiplier = Math.pow(10, decimals);
+  const amount = Math.round(usdAmount * multiplier).toString();
+  return {
+    amount,
+    asset: defaultAsset
+  };
+}
+
+// src/server/escrow.ts
+var EscrowScheme2 = class {
+  constructor(config) {
+    this.scheme = "escrow";
+    this.usdcDecimals = config?.usdcDecimals ?? 6;
+  }
+  /**
+   * Parse a user-friendly price to USDC amount
+   *
+   * Supports:
+   * - Number: 0.10 -> 100000 (assuming USD)
+   * - String: "$0.10", "0.10" -> 100000
+   * - AssetAmount: { amount: "100000", asset: "0x..." } -> passthrough
+   */
+  async parsePrice(price, _network) {
+    return parseUsdcPrice(price, void 0, this.usdcDecimals);
+  }
+  /**
+   * Enhance payment requirements with escrow-specific extra data.
+   * Config comes from facilitator's supportedKind.extra.
+   */
+  async enhancePaymentRequirements(paymentRequirements, supportedKind, _facilitatorExtensions) {
+    const facilitatorExtra = supportedKind.extra || {};
+    const asset = paymentRequirements.asset || facilitatorExtra.asset || "";
+    return {
+      ...paymentRequirements,
+      asset,
+      extra: {
+        ...paymentRequirements.extra,
+        ...facilitatorExtra
+      }
+    };
+  }
+};
+
+// src/server/index.ts
+import { HTTPFacilitatorClient } from "@x402/core/server";
+export {
+  EscrowScheme,
+  EscrowScheme2 as EscrowServerScheme,
+  X402_HEADERS,
+  createEscrowFetch,
+  parsePaymentResponseHeader,
+  withAxiosSessionExtraction,
+  withSessionExtraction
+};
+//# sourceMappingURL=index.js.map