@cloudpayx/x402-pay 0.2.4 → 0.2.5

package/scripts/seller-ledger-verifier.mjs

@@ -0,0 +1,228 @@
+import { Client, decode } from "xrpl";
+import { createHash } from "node:crypto";
+import { MAINNET_LEDGER_URL } from "./trusted-xrpl-primitives.mjs";
+import { getSellerTransactionHash } from "./seller-transaction-guard.mjs";
+
+const HASH = /^[0-9A-F]{64}$/;
+
+function fail(code) {
+  throw new Error(code);
+}
+
+function decimal(value) {
+  if (
+    typeof value !== "string" ||
+    !/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value)
+  ) {
+    fail("CPX_SELLER_LEDGER_AMOUNT_INVALID");
+  }
+
+  const [whole, fraction = ""] = value.split(".");
+  return whole + "." + fraction.replace(/0+$/, "");
+}
+
+/**
+ * Checks ledger evidence against the signed transaction and the
+ * exact x402 requirements. No facilitator claim is trusted here.
+ */
+export function verifySellerLedgerEvidence({
+  ledgerResult,
+  signedTxBlob,
+  requirements
+}) {
+  const expectedHash = getSellerTransactionHash(signedTxBlob);
+
+  let signed;
+  try {
+    signed = decode(signedTxBlob);
+  } catch {
+    fail("CPX_SELLER_SIGNED_TRANSACTION_INVALID");
+  }
+
+  if (
+    !requirements ||
+    requirements.network !== "xrpl:0" ||
+    typeof requirements.payTo !== "string" ||
+    typeof requirements.asset !== "string" ||
+    typeof requirements.amount !== "string"
+  ) {
+    fail("CPX_SELLER_LEDGER_REQUIREMENTS_INVALID");
+  }
+
+  // Independently enforce the requested currency on the
+  // ACTUAL signed XRPL transaction, not just ledger metadata.
+  if (
+    signed.TransactionType !== "Payment" ||
+    signed.Destination !== requirements.payTo ||
+    signed.Paths !== undefined ||
+    signed.DeliverMin !== undefined ||
+    (typeof signed.Flags === "number" &&
+      (signed.Flags & 0x00020000) !== 0)
+  ) {
+    fail("CPX_SELLER_SIGNED_PAYMENT_MISMATCH");
+  }
+
+  const signedAmount = signed.DeliverMax ?? signed.Amount;
+
+  if (requirements.asset === "XRP") {
+    if (
+      typeof signedAmount !== "string" ||
+      !/^[0-9]+$/.test(signedAmount) ||
+      !/^[0-9]+$/.test(requirements.amount) ||
+      BigInt(signedAmount) !== BigInt(requirements.amount) ||
+      signed.SendMax !== undefined
+    ) {
+      fail("CPX_SELLER_SIGNED_ASSET_MISMATCH");
+    }
+  } else {
+    const expectedIssuer = requirements.extra?.issuer;
+
+    if (
+      !signedAmount ||
+      typeof signedAmount !== "object" ||
+      signedAmount.currency !== requirements.asset ||
+      signedAmount.issuer !== expectedIssuer ||
+      decimal(signedAmount.value) !==
+        decimal(requirements.amount) ||
+      !signed.SendMax ||
+      typeof signed.SendMax !== "object" ||
+      signed.SendMax.currency !== requirements.asset ||
+      signed.SendMax.issuer !== expectedIssuer ||
+      decimal(signed.SendMax.value) !==
+        decimal(requirements.amount)
+    ) {
+      fail("CPX_SELLER_SIGNED_ASSET_MISMATCH");
+    }
+  }
+
+  const invoiceId = requirements.extra?.invoiceId;
+  const destinationTag = requirements.extra?.destinationTag;
+
+  if (typeof invoiceId !== "string" ||
+      invoiceId.length < 1 || invoiceId.length > 256 ||
+      !Number.isSafeInteger(destinationTag) ||
+      destinationTag < 0 || destinationTag > 0xffffffff) {
+    fail("CPX_SELLER_LEDGER_INVOICE_OR_TAG_REQUIRED");
+  }
+
+  const expectedInvoice = createHash("sha256")
+    .update(invoiceId, "utf8")
+    .digest("hex")
+    .toUpperCase();
+
+  if (signed.InvoiceID?.toUpperCase() !== expectedInvoice ||
+      signed.DestinationTag !== destinationTag) {
+    fail("CPX_SELLER_SIGNED_INVOICE_OR_TAG_MISMATCH");
+  }
+
+  if (
+    requirements.extra?.sourceTag !== undefined &&
+    signed.SourceTag !== requirements.extra.sourceTag
+  ) {
+    fail("CPX_SELLER_SIGNED_SOURCE_TAG_MISMATCH");
+  }
+
+  const tx = ledgerResult?.tx_json ?? ledgerResult?.tx;
+  const meta = ledgerResult?.meta ?? ledgerResult?.metaData;
+
+  const reportedHash = ledgerResult?.hash ?? tx?.hash;
+
+  if (
+    ledgerResult?.validated !== true ||
+    typeof reportedHash !== "string" ||
+    !HASH.test(reportedHash.toUpperCase()) ||
+    reportedHash.toUpperCase() !== expectedHash ||
+    !Number.isSafeInteger(ledgerResult.ledger_index) ||
+    ledgerResult.ledger_index <= 0 ||
+    meta?.TransactionResult !== "tesSUCCESS" ||
+    tx?.TransactionType !== "Payment" ||
+    tx?.Destination !== requirements.payTo
+  ) {
+    fail("CPX_SELLER_LEDGER_PAYMENT_NOT_CONFIRMED");
+  }
+
+  // A successful Payment result must contain a concrete delivered
+  // amount. Do not infer delivery solely from the transaction request.
+  if (
+    requirements.extra?.sourceTag !== undefined &&
+    tx.SourceTag !== requirements.extra.sourceTag
+  ) {
+    fail("CPX_SELLER_LEDGER_SOURCE_TAG_MISMATCH");
+  }
+
+  const delivered = meta.delivered_amount;
+
+  if (requirements.asset === "XRP") {
+    if (
+      typeof delivered !== "string" ||
+      !/^[0-9]+$/.test(delivered) ||
+      !/^[0-9]+$/.test(requirements.amount) ||
+      BigInt(delivered) !== BigInt(requirements.amount)
+    ) {
+      fail("CPX_SELLER_LEDGER_AMOUNT_MISMATCH");
+    }
+  } else {
+    if (
+      !delivered ||
+      typeof delivered !== "object" ||
+      delivered.currency !== requirements.asset ||
+      delivered.issuer !== requirements.extra?.issuer ||
+      decimal(delivered.value) !== decimal(requirements.amount)
+    ) {
+      fail("CPX_SELLER_LEDGER_ASSET_MISMATCH");
+    }
+  }
+
+  if (requirements.extra?.destinationTag !== undefined &&
+      tx.DestinationTag !== requirements.extra.destinationTag) {
+    fail("CPX_SELLER_LEDGER_DESTINATION_TAG_MISMATCH");
+  }
+
+  if (tx.InvoiceID?.toUpperCase() !== expectedInvoice ||
+      tx.DestinationTag !== destinationTag ||
+      tx.Account !== signed.Account ||
+      tx.Fee !== signed.Fee ||
+      (tx.SourceTag ?? undefined) !==
+        (signed.SourceTag ?? undefined)) {
+    fail("CPX_SELLER_LEDGER_TRANSACTION_FIELDS_MISMATCH");
+  }
+
+  return Object.freeze({
+    validated: true,
+    transaction: expectedHash,
+    network: "xrpl:0",
+    ledgerIndex: ledgerResult.ledger_index
+  });
+}
+
+/**
+ * Production verifier uses the fixed Ripple-operated XRPL mainnet
+ * endpoint. This is a single-provider trust dependency, not quorum.
+ * Never supplies signing keys or submits a transaction.
+ */
+export async function confirmSellerLedgerPayment({
+  signedTxBlob,
+  requirements
+}) {
+  const hash = getSellerTransactionHash(signedTxBlob);
+  const client = new Client(MAINNET_LEDGER_URL);
+
+  try {
+    await client.connect();
+
+    const response = await client.request({
+      command: "tx",
+      transaction: hash,
+      binary: false,
+      api_version: 2
+    });
+
+    return verifySellerLedgerEvidence({
+      ledgerResult: response.result,
+      signedTxBlob,
+      requirements
+    });
+  } finally {
+    await client.disconnect();
+  }
+}

package/scripts/seller-node.mjs

@@ -0,0 +1,180 @@
+import {
+  x402ResourceServer,
+  x402HTTPResourceServer,
+  HTTPFacilitatorClient
+} from "@x402/core/server";
+import { ExactXrplScheme } from "@x402/xrpl/exact/server";
+import { isValidClassicAddress } from "xrpl";
+
+const ASSETS = Object.freeze({
+  XRP: {
+    asset: "XRP"
+  },
+  RLUSD: {
+    asset: "524C555344000000000000000000000000000000",
+    issuer: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De"
+  },
+  USDC: {
+    asset: "5553444300000000000000000000000000000000",
+    issuer: "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE"
+  }
+});
+
+function requirePrice(asset, amount) {
+  if (typeof amount !== "string") {
+    throw new TypeError("CPX_SELLER_AMOUNT_MUST_BE_STRING");
+  }
+
+  if (asset === "XRP") {
+    if (!/^[1-9][0-9]*$/.test(amount)) {
+      throw new Error("CPX_SELLER_XRP_REQUIRES_POSITIVE_DROPS");
+    }
+    return;
+  }
+
+  if (
+    !/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(amount) ||
+    !/[1-9]/.test(amount)
+  ) {
+    throw new Error("CPX_SELLER_INVALID_ISSUED_AMOUNT");
+  }
+}
+
+export function createCpXSellerConfig({
+  walletAddress,
+  asset,
+  amount,
+  method = "GET",
+  path = "/paid",
+  description = "Paid XRPL agent service",
+  invoiceId,
+  destinationTag
+}) {
+  if (!isValidClassicAddress(walletAddress)) {
+    throw new Error("CPX_SELLER_INVALID_WALLET_ADDRESS");
+  }
+
+  if (!Object.hasOwn(ASSETS, asset)) {
+    throw new Error("CPX_SELLER_UNSUPPORTED_ASSET");
+  }
+
+  requirePrice(asset, amount);
+
+  if (typeof invoiceId !== "string" ||
+      invoiceId.length < 1 || invoiceId.length > 256) {
+    throw new Error("CPX_SELLER_INVOICE_REQUIRED");
+  }
+
+  if (!Number.isSafeInteger(destinationTag) ||
+      destinationTag < 0 || destinationTag > 0xffffffff) {
+    throw new Error("CPX_SELLER_DESTINATION_TAG_REQUIRED");
+  }
+
+  if (!["GET", "POST"].includes(method)) {
+    throw new Error("CPX_SELLER_UNSUPPORTED_METHOD");
+  }
+
+  if (
+    typeof path !== "string" ||
+    !new RegExp("^/[a-zA-Z0-9/_-]+$").test(path) ||
+    path.includes("//") ||
+    path.includes("..")
+  ) {
+    throw new Error("CPX_SELLER_INVALID_ROUTE");
+  }
+
+  const token = ASSETS[asset];
+
+  const paymentOption = {
+    scheme: "exact",
+    network: "xrpl:0",
+    maxTimeoutSeconds: 120,
+    payTo: walletAddress,
+    price: {
+      asset: token.asset,
+      amount,
+      ...(token.issuer
+        ? { extra: { issuer: token.issuer } }
+        : {})
+    },
+    extra: {
+      ...(token.issuer ? { issuer: token.issuer } : {}),
+      invoiceId,
+      destinationTag,
+      ...((asset === "RLUSD" || asset === "USDC") ? { areFeesSponsored: false } : {}),
+      ...(asset === "XRP" || asset === "RLUSD" || asset === "USDC"
+        ? { sourceTag: 804681468 }
+        : {})
+    }
+  };
+
+  return {
+    [`${method} ${path}`]: {
+      accepts: [paymentOption],
+      description,
+      mimeType: "application/json"
+    }
+  };
+}
+
+export function createCpXSellerServer({
+  facilitatorUrl,
+  routes
+}) {
+  if (
+    typeof facilitatorUrl !== "string" ||
+    !facilitatorUrl.startsWith("https://")
+  ) {
+    throw new Error("CPX_SELLER_HTTPS_FACILITATOR_REQUIRED");
+  }
+
+  if (
+    !routes ||
+    typeof routes !== "object" ||
+    Array.isArray(routes)
+  ) {
+    throw new Error("CPX_SELLER_ROUTES_REQUIRED");
+  }
+
+  const facilitatorClient = new HTTPFacilitatorClient({
+    url: facilitatorUrl
+  });
+
+  // Observe official verification results without changing them.
+  const facilitator = new Proxy(facilitatorClient, {
+    get(target, property) {
+      if (property === "verify") {
+        return async (...args) => {
+          try {
+            const result = await target.verify(...args);
+
+            if (result?.isValid === false) {
+              console.error("[CPX_T54_VERIFY]", {
+                isValid: false,
+                invalidReason: result.invalidReason ?? null,
+                invalidMessage: result.invalidMessage ?? null
+              });
+            }
+
+            return result;
+          } catch (error) {
+            console.error("[CPX_T54_VERIFY_EXCEPTION]", {
+              name: error?.name ?? "Error"
+            });
+            throw error;
+          }
+        };
+      }
+
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function"
+        ? value.bind(target)
+        : value;
+    }
+  });
+
+  const resourceServer = new x402ResourceServer(facilitator)
+    .register("xrpl:*", new ExactXrplScheme());
+
+  return new x402HTTPResourceServer(resourceServer, routes);
+}

package/scripts/seller-proof-guard.mjs

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+/**
+ * Durable, atomic replay guard for exact payment-proof bytes.
+ *
+ * This is a supporting control, not a substitute for XRPL
+ * transaction-hash replay detection and validated-ledger checks.
+ */
+export function createSellerProofGuard({ journalDir }) {
+  if (typeof journalDir !== "string" || !journalDir.trim()) {
+    throw new Error("CPX_SELLER_JOURNAL_REQUIRED");
+  }
+
+  const directory = resolve(journalDir);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+
+  return {
+    claim(proof) {
+      if (typeof proof !== "string" || !proof.trim()) {
+        throw new Error("CPX_SELLER_PROOF_REQUIRED");
+      }
+
+      const digest = createHash("sha256")
+        .update(proof, "utf8")
+        .digest("hex");
+
+      const file = join(directory, digest + ".claim");
+
+      try {
+        writeFileSync(file, "CLAIMED\n", {
+          flag: "wx",
+          mode: 0o600
+        });
+        return true;
+      } catch (error) {
+        if (error?.code === "EEXIST") return false;
+        throw error;
+      }
+    }
+  };
+}

package/scripts/seller-transaction-guard.mjs

@@ -0,0 +1,39 @@
+import { hashes } from "xrpl";
+import { createSellerProofGuard } from "./seller-proof-guard.mjs";
+
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+
+export function getSellerTransactionHash(signedTxBlob) {
+  if (
+    typeof signedTxBlob !== "string" ||
+    !HEX.test(signedTxBlob)
+  ) {
+    throw new Error("CPX_SELLER_SIGNED_TRANSACTION_REQUIRED");
+  }
+
+  const hash = hashes.hashSignedTx(signedTxBlob);
+
+  if (
+    typeof hash !== "string" ||
+    !/^[0-9A-Fa-f]{64}$/.test(hash)
+  ) {
+    throw new Error("CPX_SELLER_INVALID_TRANSACTION_HASH");
+  }
+
+  return hash.toUpperCase();
+}
+
+export function createSellerTransactionGuard({ journalDir }) {
+  const storage = createSellerProofGuard({ journalDir });
+
+  return {
+    claimSignedTransaction(signedTxBlob) {
+      const hash = getSellerTransactionHash(signedTxBlob);
+
+      return {
+        hash,
+        claimed: storage.claim("xrpl:0:transaction:" + hash)
+      };
+    }
+  };
+}

package/types/public-node.d.ts

@@ -53,3 +53,22 @@ export declare function reconcileSecureNodePurchase(options: {journalDir: string
   feeDrops: string;
   invoiceID: string;
 }>;
+
+export declare function createCpXAgentEarn(options: {
+  walletAddress: string;
+  asset: "XRP" | "RLUSD" | "USDC";
+  amount: string;
+  invoiceId: string;
+  destinationTag: number;
+  facilitatorUrl: string;
+  journalDir: string;
+  method?: "GET" | "POST";
+  path?: string;
+  onPaid: (
+    request: Request,
+    settlement: unknown
+  ) => Promise<Response> | Response;
+}): {
+  initialize(): Promise<unknown>;
+  handle(request: Request): Promise<Response>;
+};