@cloudpayx/x402-pay 0.2.4 → 0.2.5

package/examples/earn-http-server.mjs

@@ -0,0 +1,60 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { createCpXAgentEarn } from "@cloudpayx/x402-pay";
+
+const address = process.env.XRPL_RECEIVING_ADDRESS;
+const facilitator = process.env.X402_FACILITATOR_URL;
+
+if (!address || !facilitator) {
+  console.error("Set XRPL_RECEIVING_ADDRESS and X402_FACILITATOR_URL.");
+  process.exitCode = 1;
+} else {
+  const earn = createCpXAgentEarn({
+    walletAddress: address,
+    asset: process.env.CPX_ASSET ?? "XRP",
+    amount: process.env.CPX_AMOUNT ?? "1000",
+    invoiceId: process.env.CPX_INVOICE_ID ?? "agent-service-001",
+    destinationTag: Number(process.env.CPX_DESTINATION_TAG ?? "12345"),
+    facilitatorUrl: facilitator,
+    journalDir: process.env.CPX_EARN_JOURNAL ?? "./private-earn-journal",
+    method: "POST",
+    path: "/paid",
+    onPaid: async (_request, _settlement) =>
+      Response.json({ delivered: true, result: "Replace with your service" })
+  });
+
+  await earn.initialize();
+
+  createServer(async (req, res) => {
+    try {
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value !== undefined)
+          headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+      }
+
+      const request = new Request(
+        new URL(req.url, "http://localhost"),
+        {
+          method: req.method,
+          headers,
+          ...(["GET", "HEAD"].includes(req.method) ? {} : {
+            body: Readable.toWeb(req),
+            duplex: "half"
+          })
+        }
+      );
+
+      const response = await earn.handle(request);
+      res.writeHead(response.status, Object.fromEntries(response.headers));
+      res.end(Buffer.from(await response.arrayBuffer()));
+    } catch (error) {
+      console.error("Earn request error:", error?.message);
+      res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "Service unavailable" }));
+    }
+  }).listen(8788, "127.0.0.1", () => {
+    console.log("Earn example: http://127.0.0.1:8788/paid");
+    console.log("Deploy behind appropriately secured HTTPS for public access.");
+  });
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cloudpayx/x402-pay",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
-  "description": "XRPL-native x402 payment SDK for autonomous AI agents. Secure, wallet-agnostic XRP, RLUSD and Circle USDC payments with spending policies and verified settlement.",
+  "description": "XRPL-native x402 Pay + Earn SDK for autonomous AI agents. Purchase and monetize services using XRP, RLUSD, and Circle USDC with guarded payments and verified XRPL settlement.",
   "dependencies": {
     "@x402/core": "2.28.0",
     "@x402/fetch": "2.28.0",
@@ -39,6 +39,15 @@
     "scripts/trusted-xrpl-recovery.mjs",
     "types/",
     "README.md",
-    "examples/quickstart-validation.mjs"
+    "examples/quickstart-validation.mjs",
+    "scripts/seller-earn.mjs",
+    "scripts/seller-node.mjs",
+    "scripts/seller-http.mjs",
+    "scripts/seller-proof-guard.mjs",
+    "scripts/seller-transaction-guard.mjs",
+    "scripts/seller-ledger-verifier.mjs",
+    "AGENTS.md",
+    "docs/",
+    "examples/earn-http-server.mjs"
   ]
 }

package/scripts/durable-purchase-lifecycle.mjs

@@ -74,7 +74,7 @@ export function createJournaledSigner({signer, journal, intentId, hashSignedTx,
  * createPaymentClient MUST return a guarded SDK instance whose oneShot is ON.
  * Returning HTTP 200 is intentionally not treated as validated settlement.
  */
-export async function executeDurablePurchase({journal, intent, signer, hashSignedTx, maxFeeDrops, createPaymentClient, request, reserveBudget}) {
+export async function executeDurablePurchase({journal, intent, signer, hashSignedTx, maxFeeDrops, createPaymentClient, request, reserveBudget, releaseUnsigned}) {
   requireCondition(typeof journal?.reserve === 'function', 'CPX_JOURNAL_REQUIRED');
   requireCondition(typeof createPaymentClient === 'function', 'CPX_CLIENT_FACTORY_REQUIRED');
   requireCondition(typeof reserveBudget === 'function', 'CPX_BUDGET_RESERVATION_REQUIRED');
@@ -83,8 +83,25 @@ export async function executeDurablePurchase({journal, intent, signer, hashSigne
   // Must hold durable capacity before constructing any payment client, HTTP or signer.
   // A crash between intent and budget reservation intentionally blocks retry.
   await reserveBudget(intent);
-  const journaledSigner = createJournaledSigner({signer, journal, intentId: intent.intentId, hashSignedTx, maxFeeDrops});
+  let signingAttempted = false;
+
+  const watchedSigner = {
+    classicAddress: signer.classicAddress,
+    async sign(tx) {
+      signingAttempted = true;
+      return signer.sign(tx);
+    }
+  };
+
+  const journaledSigner = createJournaledSigner({
+    signer: watchedSigner,
+    journal,
+    intentId: intent.intentId,
+    hashSignedTx,
+    maxFeeDrops
+  });
   // Caller must use createCpXX402AgentPay({signer:journaledSigner, policy, oneShot:{...}})
+  try {
   const buyer = await createPaymentClient(journaledSigner);
   requireCondition(typeof buyer?.paidFetch === 'function' && typeof buyer?.oneShotStatus === 'function', 'CPX_ONE_SHOT_CLIENT_REQUIRED');
   // Never retry automatically. If this throws or times out, the intent stays blocked.
@@ -99,6 +116,21 @@ export async function executeDurablePurchase({journal, intent, signer, hashSigne
     ...(rejectionBody === undefined ? {} : {rejectionBody}), httpStatus: response.status,
     paymentResponseHeaderPresent: response.headers?.has?.('payment-response') === true,
     journalStatus: (await journal.load(intent.intentId)).status};
+
+  } catch (error) {
+    if (!signingAttempted && typeof releaseUnsigned === 'function') {
+      try {
+        await releaseUnsigned({intent, journal});
+      } catch (releaseError) {
+        throw new AggregateError(
+          [error, releaseError],
+          'CPX_UNSIGNED_RELEASE_NOT_CONFIRMED'
+        );
+      }
+    }
+
+    throw error;
+  }
 }
 
 /** Strict read-only reconciliation. No submission or retry is possible here. */

package/scripts/persistent-spending-budget.mjs

@@ -129,9 +129,109 @@ export function createPersistentSpendingBudget(journalDir) {
       await syncDirectory(dir);
     }
   }
+
+  // Only the durable lifecycle may authorize this operation.
+  // The original intent remains recorded forever.
+  async function releaseUnsigned({intent, journal}) {
+    check(record(intent) &&
+      typeof intent.intentId === 'string' &&
+      typeof intent.payer === 'string' &&
+      typeof journal?.load === 'function',
+      'CPX_RELEASE_INVALID_REQUEST');
+
+    await ensurePrivateDir();
+
+    const file = fileFor(intent.payer);
+    const lock = file + '.lock';
+
+    let lockFd;
+    try {
+      lockFd = await open(lock, 'wx', 0o600);
+    } catch (err) {
+      if (err?.code === 'EEXIST')
+        throw new Error('CPX_BUDGET_LOCKED_FAIL_CLOSED');
+      throw err;
+    }
+
+    try {
+      await lockFd.writeFile(String(process.pid));
+      await lockFd.sync();
+
+      const state = JSON.parse(await readFile(file, 'utf8'));
+
+      check(state?.version === 1 &&
+        state.payer === intent.payer &&
+        record(state.caps) &&
+        record(state.reserved) &&
+        record(state.intentIds),
+        'CPX_BUDGET_CORRUPT');
+
+      const idHash = createHash('sha256')
+        .update(intent.intentId).digest('hex');
+
+      const entry = state.intentIds[idHash];
+
+      check(record(entry) &&
+        entry.releasedUnsigned !== true &&
+        CAP_KEYS.includes(entry.asset) &&
+        DROPS.test(entry.units) &&
+        DROPS.test(entry.feeDrops),
+        'CPX_RELEASE_INTENT_NOT_RESERVED');
+
+      const previous = await journal.load(intent.intentId);
+
+      check(previous.status === 'RESERVED_OUTCOME_UNKNOWN' &&
+        previous.payer === intent.payer &&
+        previous.seller === intent.seller &&
+        previous.asset === intent.asset &&
+        previous.amount === intent.amount &&
+        previous.resource === intent.resource &&
+        !previous.transactionHash &&
+        !previous.expected,
+        'CPX_RELEASE_NOT_PROVEN_UNSIGNED');
+
+      const units = BigInt(entry.units);
+      const fee = BigInt(entry.feeDrops);
+
+      const xrpExposure =
+        fee + (entry.asset === 'xrpDrops' ? units : 0n);
+
+      check(BigInt(state.reserved.xrpDrops) >= xrpExposure &&
+        (entry.asset === 'xrpDrops' ||
+          BigInt(state.reserved[entry.asset]) >= units),
+        'CPX_RELEASE_BUDGET_UNDERFLOW');
+
+      if (entry.asset !== 'xrpDrops') {
+        state.reserved[entry.asset] = (
+          BigInt(state.reserved[entry.asset]) - units
+        ).toString();
+      }
+
+      state.reserved.xrpDrops = (
+        BigInt(state.reserved.xrpDrops) - xrpExposure
+      ).toString();
+
+      state.intentIds[idHash] = {
+        ...entry,
+        releasedUnsigned: true
+      };
+
+      await writeAtomic(dir, file, state);
+
+      return {
+        status: 'UNSIGNED_CAPACITY_RELEASED',
+        intentId: intent.intentId
+      };
+    } finally {
+      await lockFd.close();
+      await unlink(lock);
+      await syncDirectory(dir);
+    }
+  }
+
   async function inspect(payer) {
     await ensurePrivateDir();
     return JSON.parse(await readFile(fileFor(payer), 'utf8'));
   }
-  return {reserve, inspect};
+  return {reserve, inspect, releaseUnsigned};
 }

package/scripts/public-node.mjs

@@ -8,3 +8,5 @@
 export { executeSecureNodePurchase, validateSecureNodePurchase } from './secure-node-purchase.mjs';
 
 export { reconcileSecureNodePurchase } from './trusted-xrpl-recovery.mjs';
+
+export { createCpXAgentEarn } from "./seller-earn.mjs";

package/scripts/secure-node-purchase.mjs

@@ -1,5 +1,5 @@
 /**
- * Private pre-release, Node-only cpX x402 Pay entry point.
+ * cpX x402 Pay Node.js payment entry point.
  * One caller-facing function wires safe HTTPS-only Node transport, one-shot
  * XRPL signing constraints, and the durable same-intent purchase journal.
  * This does NOT make the lower-level SDK impossible to invoke unsafely;
@@ -79,6 +79,8 @@ export async function executeSecureNodePurchase(options) {
     intent: options.intent,
     reserveBudget: intent => budget.reserve({intent,issuer:options.oneShot.issuer,caps:options.budgetCaps,
       maxFeeDrops:options.maxFeeDrops,maxSendMax:options.oneShot.maxSendMax}),
+    releaseUnsigned: ({intent, journal}) =>
+      budget.releaseUnsigned({intent, journal}),
     signer: options.signer,
     hashSignedTx: trusted.hashSignedTx,
     maxFeeDrops: options.maxFeeDrops,

package/scripts/seller-earn.mjs

@@ -0,0 +1,67 @@
+import { join, resolve } from "node:path";
+import { createCpXSellerConfig, createCpXSellerServer } from "./seller-node.mjs";
+import { createCpXSellerHandler } from "./seller-http.mjs";
+import { createSellerProofGuard } from "./seller-proof-guard.mjs";
+import { createSellerTransactionGuard } from "./seller-transaction-guard.mjs";
+import { confirmSellerLedgerPayment } from "./seller-ledger-verifier.mjs";
+
+/**
+ * cpX Agent Earn: XRPL-mainnet seller.
+ * No wallet secret or signing key required.
+ */
+export function createCpXAgentEarn({
+  walletAddress,
+  asset,
+  amount,
+  invoiceId,
+  destinationTag,
+  facilitatorUrl,
+  journalDir,
+  onPaid,
+  method = "POST",
+  path = "/paid"
+}) {
+  if (typeof journalDir !== "string" || !journalDir.trim()) {
+    throw Error("CPX_SELLER_JOURNAL_REQUIRED");
+  }
+
+  if (typeof onPaid !== "function") {
+    throw Error("CPX_SELLER_PAID_HANDLER_REQUIRED");
+  }
+
+  const routes = createCpXSellerConfig({
+    walletAddress,
+    asset,
+    amount,
+    invoiceId,
+    destinationTag,
+    method,
+    path
+  });
+
+  const server = createCpXSellerServer({
+    facilitatorUrl,
+    routes
+  });
+
+  const directory = resolve(journalDir);
+
+  const handle = createCpXSellerHandler({
+    httpServer: server,
+    proofGuard: createSellerProofGuard({
+      journalDir: join(directory, "proofs")
+    }),
+    transactionGuard: createSellerTransactionGuard({
+      journalDir: join(directory, "transactions")
+    }),
+    confirmLedger: confirmSellerLedgerPayment,
+    method,
+    path,
+    onPaid
+  });
+
+  return Object.freeze({
+    initialize: () => server.initialize(),
+    handle
+  });
+}

package/scripts/seller-http.mjs

@@ -0,0 +1,287 @@
+/**
+ * cpX Agent Earn: settlement-gated Fetch API adapter.
+ *
+ * XRPL seller HTTP adapter with guarded payment verification, replay protection, and settlement-gated delivery.
+ * Never calls the protected service before settlement succeeds.
+ */
+
+function reject(status, error) {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    }
+  });
+}
+
+export function createCpXSellerHandler({
+  httpServer,
+  proofGuard,
+  transactionGuard,
+  confirmLedger,
+  method = "POST",
+  path = "/paid",
+  onPaid
+}) {
+  if (
+    !httpServer ||
+    typeof httpServer.processHTTPRequest !== "function" ||
+    typeof httpServer.processSettlement !== "function"
+  ) {
+    throw new Error("CPX_SELLER_HTTP_SERVER_REQUIRED");
+  }
+
+  if (!proofGuard || typeof proofGuard.claim !== "function") {
+    throw new Error("CPX_SELLER_PROOF_GUARD_REQUIRED");
+  }
+
+  if (
+    !transactionGuard ||
+    typeof transactionGuard.claimSignedTransaction !== "function"
+  ) {
+    throw new Error("CPX_SELLER_TRANSACTION_GUARD_REQUIRED");
+  }
+
+  if (typeof confirmLedger !== "function") {
+    throw new Error("CPX_SELLER_LEDGER_VERIFIER_REQUIRED");
+  }
+
+  if (typeof onPaid !== "function") {
+    throw new Error("CPX_SELLER_PAID_HANDLER_REQUIRED");
+  }
+
+  if (
+    typeof path !== "string" ||
+    !path.startsWith("/") ||
+    !["GET", "POST"].includes(method)
+  ) {
+    throw new Error("CPX_SELLER_INVALID_PROTECTED_ROUTE");
+  }
+
+  return async function handle(request) {
+    if (!(request instanceof Request)) {
+      return reject(400, "INVALID_REQUEST");
+    }
+
+    const requestUrl = new URL(request.url);
+
+    if (
+      request.method !== method ||
+      requestUrl.pathname !== path
+    ) {
+      return reject(404, "ROUTE_NOT_FOUND");
+    }
+
+    const headers = request.headers;
+
+    const adapter = {
+      getHeader: name => headers.get(name) ?? undefined,
+      getMethod: () => request.method,
+      getPath: () => requestUrl.pathname,
+      getUrl: () => request.url,
+      getAcceptHeader: () => headers.get("accept") ?? "",
+      getUserAgent: () => headers.get("user-agent") ?? "",
+      getQueryParams: () =>
+        Object.fromEntries(requestUrl.searchParams),
+      getQueryParam: name =>
+        requestUrl.searchParams.get(name) ?? undefined
+    };
+
+    const context = {
+      adapter,
+      path: requestUrl.pathname,
+      method: request.method,
+      paymentHeader:
+        headers.get("payment-signature") ??
+        headers.get("x-payment") ??
+        undefined
+    };
+
+    let result;
+
+    try {
+      result = await httpServer.processHTTPRequest(context);
+    } catch {
+      return reject(503, "PAYMENT_VERIFICATION_UNAVAILABLE");
+    }
+
+    if (result?.type === "payment-error") {
+      const response = result.response;
+      const body = response?.body;
+      let parsed = body;
+      if (typeof body === "string") {
+        try { parsed = JSON.parse(body); } catch { parsed = {}; }
+      }
+      const reason = parsed?.invalidReason ??
+        parsed?.invalidMessage ??
+        parsed?.errorMessage ??
+        parsed?.errorReason ??
+        parsed?.error ??
+        parsed?.reason ??
+        parsed?.verification?.invalidReason ??
+        "UNSPECIFIED";
+
+      if (context.paymentHeader) {
+        console.error("[CPX_EARN_VERIFY_REJECTED]", {
+          status: response?.status,
+          reason: typeof reason === "string"
+            ? reason.slice(0, 160) : "UNSPECIFIED",
+          responseFields: parsed && typeof parsed === "object"
+            ? Object.keys(parsed).slice(0, 20)
+            : []
+        });
+      }
+
+      if (!response || !Number.isInteger(response.status)) {
+        return reject(503, "PAYMENT_RESPONSE_INVALID");
+      }
+
+      return new Response(
+        response.body == null
+          ? null
+          : typeof response.body === "string"
+            ? response.body
+            : JSON.stringify(response.body),
+        {
+          status: response.status,
+          headers: {
+            ...response.headers,
+            "Cache-Control": "no-store"
+          }
+        }
+      );
+    }
+
+    // This adapter protects ONLY paid endpoints.
+    // An unexpected free-access result must not unlock content.
+    if (result?.type !== "payment-verified") {
+      return reject(403, "PAYMENT_REQUIRED");
+    }
+
+    // Enforce unsponsored XRPL payments before settlement.
+    // Never settle a payment whose verified requirements
+    // do not explicitly disable facilitator fee sponsorship.
+    if (result.paymentRequirements?.extra?.areFeesSponsored !== false) {
+      return reject(403, "CPX_FEE_SPONSORSHIP_NOT_ALLOWED");
+    }
+
+    // The installed XRPL server supports multiple payment flows.
+    // Until each flow has been tested, refuse requests that report
+    // a pre-handler settlement rather than assuming its outcome.
+    if (result.beforeHandlerSettlement !== undefined) {
+      return reject(503, "PRESETTLED_FLOW_NOT_YET_SUPPORTED");
+    }
+
+    // A verified proof must be claimed before settlement.
+    // Atomic persistent claims block concurrent and repeated requests.
+    const proof = context.paymentHeader;
+
+    if (typeof proof !== "string" || !proof.trim()) {
+      return reject(403, "PAYMENT_PROOF_MISSING");
+    }
+
+    try {
+      if (!proofGuard.claim(proof)) {
+        return reject(409, "PAYMENT_PROOF_ALREADY_CLAIMED");
+      }
+    } catch {
+      return reject(503, "PAYMENT_PROOF_GUARD_UNAVAILABLE");
+    }
+
+    // Identify the signed XRPL transaction, not just its HTTP encoding.
+    const signedTxBlob = result.paymentPayload?.payload?.signedTxBlob;
+
+    if (typeof signedTxBlob !== "string" || !signedTxBlob) {
+      return reject(403, "SIGNED_XRPL_TRANSACTION_MISSING");
+    }
+
+    let transactionClaim;
+    try {
+      transactionClaim =
+        transactionGuard.claimSignedTransaction(signedTxBlob);
+    } catch {
+      return reject(503, "TRANSACTION_GUARD_UNAVAILABLE");
+    }
+
+    if (!transactionClaim?.claimed) {
+      return reject(409, "XRPL_TRANSACTION_ALREADY_CLAIMED");
+    }
+
+    let settlement;
+
+    try {
+      settlement = await httpServer.processSettlement(
+        result.paymentPayload,
+        result.paymentRequirements,
+        result.declaredExtensions,
+        { request: context }
+      );
+    } catch {
+      // A settlement timeout may be indeterminate.
+      // Never retry settlement automatically here.
+      return reject(503, "SETTLEMENT_OUTCOME_UNCERTAIN");
+    }
+
+    if (settlement?.success !== true) {
+      const reason = settlement?.errorReason ??
+        settlement?.error ?? settlement?.reason ?? "UNSPECIFIED";
+      console.error("[CPX_EARN_SETTLEMENT_REJECTED]", {
+        reason: typeof reason === "string"
+          ? reason.slice(0, 160) : "UNSPECIFIED"
+      });
+      return reject(402, "PAYMENT_NOT_SETTLED");
+    }
+
+    // A successful facilitator response must identify the exact
+    // signed XRPL transaction claimed before settlement.
+    if (
+      typeof transactionClaim?.hash !== "string" ||
+      !/^[0-9A-Fa-f]{64}$/.test(transactionClaim.hash) ||
+      typeof settlement.transaction !== "string" ||
+      settlement.transaction.toUpperCase() !==
+        transactionClaim.hash.toUpperCase() ||
+      settlement.network !== "xrpl:0"
+    ) {
+      return reject(503, "SETTLEMENT_IDENTITY_MISMATCH");
+    }
+
+    // Independently confirm validated XRPL settlement.
+    // A facilitator's success response alone cannot unlock content.
+    let ledgerReceipt;
+    try {
+      ledgerReceipt = await confirmLedger({
+        signedTxBlob,
+        requirements: result.paymentRequirements
+      });
+    } catch {
+      return reject(503, "LEDGER_CONFIRMATION_UNAVAILABLE");
+    }
+
+    if (
+      ledgerReceipt?.validated !== true ||
+      ledgerReceipt?.network !== "xrpl:0" ||
+      typeof ledgerReceipt.transaction !== "string" ||
+      ledgerReceipt.transaction.toUpperCase() !==
+        transactionClaim.hash.toUpperCase()
+    ) {
+      return reject(503, "LEDGER_CONFIRMATION_MISMATCH");
+    }
+
+    // Only successful, independently confirmed settlement
+    // reaches the protected service.
+    try {
+      const paidResponse = await onPaid(request, settlement);
+
+      if (!(paidResponse instanceof Response)) {
+        return reject(500, "PAID_HANDLER_INVALID_RESPONSE");
+      }
+
+      paidResponse.headers.set("Cache-Control", "no-store");
+
+      return paidResponse;
+    } catch {
+      return reject(500, "PAID_SERVICE_FAILED");
+    }
+  };
+}