@cloudpayx/x402-pay 0.0.0-stage → 0.2.1

package/scripts/persistent-spending-budget.mjs

@@ -0,0 +1,137 @@
+/**
+ * Private single-host cumulative XRPL spending capacity gate.
+ * All reserved/uncertain/successful intents COUNT against caps indefinitely.
+ * No automatic release after failure or timeout: refund/release needs a separate
+ * carefully authenticated, ledger-grounded operator workflow (not shipped).
+ * A wallet owner who can replace journalDir or edit storage can bypass these caps;
+ * this is NOT an external enforcement boundary or multi-host coordination.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, lstat, open, readFile, rename, unlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const RLUSD = ['524C555344000000000000000000000000000000', 'rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De'];
+const USDC = ['5553444300000000000000000000000000000000', 'rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE'];
+const CAP_KEYS = ['xrpDrops', 'rlusd', 'usdc'];
+const DROPS = /^(?:0|[1-9][0-9]*)$/;
+const TOKEN = /^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,15})?$/;
+const FACTOR = 10n ** 15n;
+function check(ok, code) { if (!ok) throw new Error(code); }
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function parseAmount(v, key) {
+  check(typeof v === 'string' && v.length > 0 && v.length <= 64 &&
+    (key === 'xrpDrops' ? DROPS : TOKEN).test(v), 'CPX_BUDGET_AMOUNT_INVALID');
+  if (key === 'xrpDrops') return BigInt(v);
+  const [whole, fract = ''] = v.split('.');
+  return BigInt(whole) * FACTOR + BigInt(fract.padEnd(15, '0') || '0');
+}
+export function validateBudgetCaps(caps) {
+  check(record(caps) && Object.keys(caps).length === 3 &&
+    CAP_KEYS.every(k => Object.prototype.hasOwnProperty.call(caps,k)), 'CPX_BUDGET_CAPS_REQUIRED');
+  for (const k of CAP_KEYS) check(parseAmount(caps[k], k) > 0n, 'CPX_BUDGET_CAP_MUST_BE_POSITIVE');
+  return true;
+}
+function keyFor(asset, issuer) {
+  if (asset === 'XRP' && issuer === undefined) return 'xrpDrops';
+  if (asset === RLUSD[0] && issuer === RLUSD[1]) return 'rlusd';
+  if (asset === USDC[0] && issuer === USDC[1]) return 'usdc';
+  throw new Error('CPX_BUDGET_UNSUPPORTED_ASSET_OR_ISSUER');
+}
+async function syncDirectory(dir) {
+  const fd = await open(dir, 'r');
+  try { await fd.sync(); } finally { await fd.close(); }
+}
+async function writeAtomic(dir, file, state) {
+  const temp = file + '.' + randomUUID() + '.tmp';
+  const fd = await open(temp, 'wx', 0o600);
+  try { await fd.writeFile(JSON.stringify(state, null, 2)); await fd.sync(); }
+  finally { await fd.close(); }
+  await rename(temp, file);
+  await syncDirectory(dir);
+}
+export function createPersistentSpendingBudget(journalDir) {
+  check(typeof journalDir === 'string' && journalDir.trim().length > 0, 'CPX_BUDGET_DIRECTORY_REQUIRED');
+  const parent = resolve(journalDir);
+  const dir = join(parent, '.cpx-spending-budget');
+  const fileFor = payer => join(dir, createHash('sha256').update(payer).digest('hex') + '.json');
+
+  async function ensurePrivateDir() {
+    await mkdir(parent, {recursive: true, mode: 0o700});
+    await mkdir(dir, {recursive: true, mode: 0o700});
+    for (const folder of [parent, dir]) {
+      const st = await lstat(folder);
+      check(st.isDirectory() && !st.isSymbolicLink() && (st.mode & 0o077) === 0,
+        'CPX_BUDGET_STORAGE_NOT_PRIVATE');
+    }
+  }
+  async function reserve({intent, issuer, caps, maxFeeDrops, maxSendMax}) {
+    validateBudgetCaps(caps);
+    check(record(intent) && typeof intent.intentId === 'string' && intent.intentId.length >= 12 &&
+      intent.intentId.length <= 200 && typeof intent.payer === 'string' && intent.payer.length > 0 &&
+      typeof intent.asset === 'string', 'CPX_BUDGET_INVALID_INTENT');
+    const key = keyFor(intent.asset, issuer);
+    const deliveryUnits = parseAmount(intent.amount, key);
+    check(deliveryUnits > 0n, 'CPX_BUDGET_AMOUNT_MUST_BE_POSITIVE');
+    const feeUnits = parseAmount(maxFeeDrops, 'xrpDrops');
+    check(feeUnits > 0n, 'CPX_BUDGET_FEE_REQUIRED');
+    // Reserve the WORST-CASE issuer debit, not merely the delivered tokens.
+    check((key === 'xrpDrops' && maxSendMax === undefined) ||
+      (key !== 'xrpDrops' && typeof maxSendMax === 'string'), 'CPX_BUDGET_SENDMAX_REQUIRED');
+    const units = key === 'xrpDrops' ? deliveryUnits : parseAmount(maxSendMax, key);
+    check(units >= deliveryUnits, 'CPX_BUDGET_SENDMAX_BELOW_DELIVERY');
+    check(units <= parseAmount(caps[key], key), 'CPX_CUMULATIVE_BUDGET_EXCEEDED');
+    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;
+    }
+    // The exclusive lock is never automatically broken after a crash: fail closed.
+    // Unlink only during normal cleanup after the state has been fsynced.
+    try {
+      await lockFd.writeFile(String(process.pid)); await lockFd.sync();
+      const wantedCaps = Object.fromEntries(CAP_KEYS.map(k=>[k, parseAmount(caps[k], k).toString()]));
+      let state;
+      try { state = JSON.parse(await readFile(file, 'utf8')); }
+      catch (err) {
+        if (err?.code !== 'ENOENT') throw err;
+        state = {version: 1, payer:intent.payer, caps:wantedCaps,
+          reserved:{xrpDrops:'0',rlusd:'0',usdc:'0'}, intentIds:{}};
+      }
+      check(record(state) && state.version === 1 && state.payer === intent.payer &&
+        record(state.caps) && record(state.reserved) && record(state.intentIds),
+        'CPX_BUDGET_CORRUPT');
+      for (const k of CAP_KEYS) {
+        check(state.caps[k] === wantedCaps[k], 'CPX_BUDGET_CAP_CHANGE_FORBIDDEN');
+        check(typeof state.reserved[k] === 'string' && DROPS.test(state.reserved[k]), 'CPX_BUDGET_CORRUPT');
+        check(BigInt(state.reserved[k]) <= BigInt(state.caps[k]), 'CPX_BUDGET_CORRUPT');
+      }
+      const idHash = createHash('sha256').update(intent.intentId).digest('hex');
+      check(!Object.prototype.hasOwnProperty.call(state.intentIds, idHash), 'CPX_BUDGET_DUPLICATE_INTENT');
+      const next = BigInt(state.reserved[key]) + units;
+      const newXrp = BigInt(state.reserved.xrpDrops) + feeUnits +
+        (key === 'xrpDrops' ? units : 0n);
+      check(next <= BigInt(state.caps[key]) && newXrp <= BigInt(state.caps.xrpDrops),
+        'CPX_CUMULATIVE_BUDGET_EXCEEDED');
+      state.reserved[key] = next.toString();
+      state.reserved.xrpDrops = newXrp.toString();
+      state.intentIds[idHash] = {asset:key, units:units.toString(), feeDrops:feeUnits.toString()};
+      check(Buffer.byteLength(JSON.stringify(state)) <= 4 * 1024 * 1024, 'CPX_BUDGET_JOURNAL_TOO_LARGE');
+      await writeAtomic(dir, file, state);
+      return {status:'BUDGET_CAPACITY_RESERVED',asset:key,
+        reserved:state.reserved[key], limit:state.caps[key], xrpReservedDrops:state.reserved.xrpDrops};
+    } 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};
+}

package/scripts/public-node.mjs

@@ -0,0 +1,10 @@
+/**
+ * Supported cpX x402 Pay Node.js package surface.
+ * Low-level modules are internal plumbing, not public entry points.
+ * An agent controlling its own wallet keys may always bypass any SDK in
+ * its own process; this boundary prevents accidental imports, not hostile
+ * code running with the same privileges.
+ */
+export { executeSecureNodePurchase, validateSecureNodePurchase } from './secure-node-purchase.mjs';
+
+export { reconcileSecureNodePurchase } from './trusted-xrpl-recovery.mjs';

package/scripts/safe-agent-fetch.mjs

@@ -0,0 +1,184 @@
+/**
+ * cpX x402 Pay - Node.js HTTPS-only agent request transport.
+ * Protects agent-side buyer requests to seller resources with public-only,
+ * pinned DNS resolution and no redirect following. No XRPL signing here.
+ * IMPORTANT: Node.js adapter; browser runtimes need a separate transport.
+ */
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { request as httpsRequest } from 'node:https';
+import { isIP, BlockList } from 'node:net';
+
+const BLOCKED = new BlockList();
+for (const [ip,bits] of [
+  ['0.0.0.0',8], ['10.0.0.0',8], ['100.64.0.0',10],
+  ['127.0.0.0',8], ['169.254.0.0',16], ['172.16.0.0',12],
+  ['192.0.0.0',24], ['192.0.2.0',24], ['192.88.99.0',24],
+  ['192.168.0.0',16], ['198.18.0.0',15], ['198.51.100.0',24],
+  ['203.0.113.0',24], ['224.0.0.0',4], ['240.0.0.0',4]
+]) BLOCKED.addSubnet(ip,bits,'ipv4');
+for (const [ip,bits] of [
+  ['::',128], ['::1',128],
+  ['64:ff9b::',96], ['64:ff9b:1::',48], ['100::',64],
+  ['2001::',23], ['2001:db8::',32], ['2002::',16],
+  ['fc00::',7], ['fe80::',10], ['ff00::',8]
+]) BLOCKED.addSubnet(ip,bits,'ipv6');
+
+function deny(code) { throw new Error(code); }
+
+/** Conservative public-address check. Rejects atypical IPv6 routing schemes. */
+export function isPublicIp(address) {
+  const family = isIP(address);
+  if (!family) return false;
+  if (family === 6 && address.toLowerCase().startsWith('::ffff:')) return false;
+  if (BLOCKED.check(address, family===4?'ipv4':'ipv6')) return false;
+  if (family===6) {
+    // IPv6 global unicast: 2000::/3 only, as a conservative baseline.
+    const first = parseInt(address.split(':')[0] || '0',16);
+    if (!Number.isFinite(first) || first < 0x2000 || first > 0x3fff) return false;
+  }
+  return true;
+}
+
+export function validateSellerUrl(input) {
+  // Disallow backslashes before URL normalization (WHATWG treats them as slashes).
+  if (String(input).includes('\\')) deny('CPX_INVALID_SELLER_URL');
+  let url;
+  try { url = new URL(String(input)); }
+  catch { return deny('CPX_INVALID_SELLER_URL'); }
+  if (url.protocol !== 'https:') deny('CPX_HTTPS_REQUIRED');
+  if (url.port && url.port !== '443') deny('CPX_NONSTANDARD_PORT_BLOCKED');
+  if (url.username || url.password) deny('CPX_URL_CREDENTIALS_BLOCKED');
+  if (url.hash) deny('CPX_URL_FRAGMENT_BLOCKED');
+  const host = url.hostname.toLowerCase().replace(/\.$/,'');
+  if (!host || host.length > 253 || host.includes('%') || host.includes('\\')) deny('CPX_INVALID_SELLER_HOST');
+  const isIpHost = isIP(host.replace(/^\[|\]$/g,''));
+  if (isIpHost) {
+    if (!isPublicIp(host.replace(/^\[|\]$/g,''))) deny('CPX_PRIVATE_NETWORK_BLOCKED');
+  } else {
+    if (!/^[a-z0-9.-]+$/.test(host) || !host.includes('.') ||
+      host.split('.').some(p => !p || p.length > 63 || p.startsWith('-') || p.endsWith('-')))
+      deny('CPX_INVALID_SELLER_HOST');
+    if (/(?:^|\.)(?:localhost|local|internal|test|invalid|example|onion)$/.test(host) ||
+      host.endsWith('.home.arpa') || host.endsWith('.arpa')) deny('CPX_PRIVATE_HOST_BLOCKED');
+  }
+  // Constructed Request/URL normalizes alternate IPv4 encodings to dotted-quad.
+  return url;
+}
+
+/** Resolve once, reject ANY non-public DNS answers, pin the chosen answer at socket connect. */
+export async function resolvePublicSeller(hostname, resolve = dnsLookup) {
+  const host = hostname.replace(/^\[|\]$/g,'');
+  const family = isIP(host);
+  if (family) {
+    if (!isPublicIp(host)) deny('CPX_PRIVATE_NETWORK_BLOCKED');
+    return {address:host,family};
+  }
+  let answers;
+  try { answers = await resolve(host, {all:true,verbatim:true}); }
+  catch { return deny('CPX_DNS_LOOKUP_FAILED'); }
+  if (!Array.isArray(answers) || !answers.length) deny('CPX_DNS_LOOKUP_FAILED');
+  if (!answers.every(item => item && item.family === isIP(item.address) && isPublicIp(item.address)))
+    deny('CPX_DNS_PRIVATE_OR_UNROUTABLE_ADDRESS');
+  return {address:answers[0].address, family:answers[0].family};
+}
+
+function getTimeout(value) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 60000) deny('CPX_INVALID_HTTP_TIMEOUT');
+  return value;
+}
+
+/**
+ * Explicit Node-only opt-in transport for SDK requestFetch. No redirects or
+ * browser cookies. Uses the SAME approved DNS address for the actual TLS socket.
+ * The caller decides which seller URL to request; no merchant registration.
+ */
+export function createSafeAgentFetch({
+  resolve = dnsLookup,
+  request = httpsRequest,
+  timeoutMs = 15000,
+  maxRequestBytes = 256 * 1024,
+  maxResponseBytes = 8 * 1024 * 1024
+} = {}) {
+  getTimeout(timeoutMs);
+  if (![maxRequestBytes,maxResponseBytes].every(n=>Number.isSafeInteger(n)&&n>0&&n<=32*1024*1024))
+    deny('CPX_INVALID_HTTP_BODY_LIMIT');
+  return async function safeAgentFetch(input, init = {}) {
+    // Constructing Request preserves x402's method, headers and body on the retry.
+    validateSellerUrl(input instanceof Request ? input.url : input);
+    const req = new Request(input, init);
+    const url = validateSellerUrl(req.url);
+    const pinned = await resolvePublicSeller(url.hostname,resolve);
+    if (req.signal.aborted) deny('CPX_HTTP_ABORTED');
+    const bytes = req.body ? Buffer.from(await req.arrayBuffer()) : Buffer.alloc(0);
+    if (bytes.length > maxRequestBytes) deny('CPX_HTTP_REQUEST_TOO_LARGE');
+    const headers = Object.fromEntries(req.headers);
+    // Node fetch adds implicit Accept-Encoding but https.request doesn't; avoid
+    // transparent decompression ambiguity and keep the response byte limit real.
+    headers['accept-encoding'] = 'identity';
+    headers['content-length'] = String(bytes.length);
+    return await new Promise((resolvePromise,rejectPromise) => {
+      let settled = false;
+      let signalHandler;
+      let deadline;
+      const reject = err => { if (!settled) { settled = true; clearTimeout(deadline); rejectPromise(err); } };
+      const finish = val => { if (!settled) { settled = true; clearTimeout(deadline); resolvePromise(val); } };
+      const requestOptions = {
+        method:req.method,headers,
+        timeout:timeoutMs,
+        autoSelectFamily:false,
+        // TLS certificate validation and SNI use the *original hostname*.
+        // Only the DNS address is pinned, avoiding DNS-rebinding after checks.
+        lookup(host, opts, callback) {
+          if (host.toLowerCase().replace(/\.$/,'') !== url.hostname.toLowerCase().replace(/\.$/,''))
+            return callback(new Error('CPX_DNS_HOST_MISMATCH'));
+          if (opts?.all) return callback(null, [{...pinned}]);
+          callback(null, pinned.address, pinned.family);
+        }
+      };
+      let client;
+      try {
+        client = request(url, requestOptions, incoming => {
+          const code = incoming.statusCode ?? 0;
+          // NEVER follow 3xx, even on a paid x402 retry.
+          if (code >= 300 && code < 400) {
+            incoming.resume();
+            return reject(new Error('CPX_HTTP_REDIRECT_BLOCKED'));
+          }
+          if (code < 200 || code > 599) {
+            incoming.resume();
+            return reject(new Error('CPX_BAD_HTTP_STATUS'));
+          }
+          let total = 0; const chunks=[];
+          incoming.on('data', chunk => {
+            total += chunk.length;
+            if (total > maxResponseBytes) {
+              incoming.destroy(new Error('CPX_HTTP_RESPONSE_TOO_LARGE'));
+              return;
+            }
+            chunks.push(chunk);
+          });
+          incoming.on('error',reject);
+          incoming.on('end',()=>{
+            try {
+              const responseHeaders = new Headers();
+              for (const [name,value] of Object.entries(incoming.headers)) {
+                if (value !== undefined) responseHeaders.set(name,Array.isArray(value)?value.join(', '):value);
+              }
+              const body = [204,205,304].includes(code)?null:Buffer.concat(chunks);
+              finish(new Response(body,{status:code,headers:responseHeaders}));
+            } catch(e) { reject(e); }
+          });
+        });
+      } catch(e) { return reject(e); }
+      deadline = setTimeout(()=>client.destroy(new Error('CPX_HTTP_TIMEOUT')),timeoutMs);
+      deadline.unref?.();
+      client.on('timeout',()=>client.destroy(new Error('CPX_HTTP_TIMEOUT')));
+      client.on('error',reject);
+      signalHandler = () => client.destroy(new Error('CPX_HTTP_ABORTED'));
+      req.signal.addEventListener('abort',signalHandler,{once:true});
+      client.on('close',()=>req.signal.removeEventListener('abort',signalHandler));
+      if (bytes.length) client.write(bytes);
+      client.end();
+    });
+  };
+}

package/scripts/secure-node-purchase.mjs

@@ -0,0 +1,93 @@
+/**
+ * Private pre-release, Node-only cpX x402 Pay 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;
+ * before publication the public package exports must be restricted/audited.
+ */
+import { createSafeAgentFetch, validateSellerUrl } from './safe-agent-fetch.mjs';
+import { createLocalAttemptJournal } from './local-attempt-journal.mjs';
+import { createPersistentSpendingBudget, validateBudgetCaps } from './persistent-spending-budget.mjs';
+import { executeDurablePurchase } from './durable-purchase-lifecycle.mjs';
+import { loadOfficialXrplPrimitives } from './trusted-xrpl-primitives.mjs';
+
+const KEYS = new Set([
+  'intent', 'journalDir', 'signer', 'policy', 'oneShot',
+  'maxFeeDrops', 'request', 'timeoutMs', 'budgetCaps'
+]);
+const INT = /^(0|[1-9][0-9]*)$/;
+const OWN = Object.prototype.hasOwnProperty;
+function fail(code) { throw new Error(code); }
+function object(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+function requireValue(ok, code) { if (!ok) fail(code); }
+
+export function validateSecureNodePurchase(options) {
+  requireValue(object(options), 'CPX_SECURE_OPTIONS_REQUIRED');
+  requireValue(Object.keys(options).every(key => KEYS.has(key)), 'CPX_UNSAFE_OPTION_FORBIDDEN');
+  const { intent, journalDir, signer, policy, oneShot,
+    maxFeeDrops, request, timeoutMs = 20000, budgetCaps } = options;
+  validateBudgetCaps(budgetCaps);
+  requireValue(object(intent) && typeof intent.intentId === 'string' && intent.intentId.length >= 12,
+    'CPX_STABLE_INTENT_ID_REQUIRED');
+  requireValue(typeof intent.resource === 'string' && typeof intent.seller === 'string' &&
+    typeof intent.payer === 'string' && typeof intent.asset === 'string' && typeof intent.amount === 'string',
+    'CPX_PURCHASE_INTENT_REQUIRED');
+  validateSellerUrl(intent.resource); // reject unsafe URL before reserving journal or signing
+  requireValue(typeof journalDir === 'string' && journalDir.length > 0,
+    'CPX_DURABLE_JOURNAL_PATH_REQUIRED');
+  requireValue(object(signer) && signer.classicAddress === intent.payer && typeof signer.sign === 'function',
+    'CPX_WRONG_OR_MISSING_PAYER_SIGNER');
+  requireValue(object(policy), 'CPX_POLICY_REQUIRED');
+  requireValue(object(oneShot) && oneShot.recipient === intent.seller &&
+    oneShot.asset === intent.asset && oneShot.exactAmount === intent.amount &&
+    !OWN.call(oneShot, 'getValidatedLedgerIndex'), 'CPX_ONE_SHOT_INTENT_MISMATCH');
+  requireValue(typeof maxFeeDrops === 'string' && INT.test(maxFeeDrops) && BigInt(maxFeeDrops) > 0n &&
+    oneShot.maxFeeDrops === maxFeeDrops, 'CPX_FEE_CEILING_MISMATCH');
+  requireValue((intent.asset === 'XRP' && oneShot.issuer === undefined && oneShot.maxSendMax === undefined) ||
+    (intent.asset !== 'XRP' && typeof oneShot.issuer === 'string' &&
+      typeof oneShot.maxSendMax === 'string'), 'CPX_ASSET_GUARD_REQUIRED');
+  requireValue(object(request) && request.url === intent.resource && object(request.init),
+    'CPX_RESOURCE_MISMATCH');
+  requireValue((request.init.method ?? 'GET').toUpperCase() === 'POST', 'CPX_POST_REQUIRED');
+  requireValue(typeof request.init.body === 'string' && request.init.body.length <= 262144,
+    'CPX_REQUEST_BODY_REQUIRED');
+  requireValue(Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= 60000,
+    'CPX_INVALID_HTTP_TIMEOUT');
+  requireValue(!OWN.call(request.init, 'signal') || request.init.signal instanceof AbortSignal,
+    'CPX_BAD_ABORT_SIGNAL');
+  // Only the first unpaid request is caller supplied. The official x402 client
+  // alone can populate the payment-signature header on its paid retry.
+  const headers = new Headers(request.init.headers);
+  for (const h of ['payment-signature', 'x-payment', 'authorization', 'cookie']) {
+    requireValue(!headers.has(h), 'CPX_CREDENTIALS_IN_INITIAL_REQUEST_FORBIDDEN');
+  }
+  // The normal requestFetch override is deliberately not an option here.
+  return true;
+}
+
+export async function executeSecureNodePurchase(options) {
+  validateSecureNodePurchase(options);
+  // Imported at runtime from the pinned official xrpl package; no caller injection.
+  const trusted = await loadOfficialXrplPrimitives();
+  const lockedOneShot = { ...options.oneShot, getValidatedLedgerIndex:trusted.getValidatedLedgerIndex };
+  const { createCpXX402AgentPay } = await import('../dist/src/index.js');
+  const journal = createLocalAttemptJournal(options.journalDir);
+  const budget = createPersistentSpendingBudget(options.journalDir);
+  const safeNodeFetch = createSafeAgentFetch({timeoutMs: options.timeoutMs ?? 20000});
+  return executeDurablePurchase({
+    journal,
+    intent: options.intent,
+    reserveBudget: intent => budget.reserve({intent,issuer:options.oneShot.issuer,caps:options.budgetCaps,
+      maxFeeDrops:options.maxFeeDrops,maxSendMax:options.oneShot.maxSendMax}),
+    signer: options.signer,
+    hashSignedTx: trusted.hashSignedTx,
+    maxFeeDrops: options.maxFeeDrops,
+    request: options.request,
+    createPaymentClient: journaledSigner => createCpXX402AgentPay({
+      signer: journaledSigner,
+      policy: options.policy,
+      oneShot: lockedOneShot,
+      requestFetch: safeNodeFetch
+    })
+  });
+}

package/scripts/trusted-xrpl-primitives.mjs

@@ -0,0 +1,46 @@
+/**
+ * Official XRPL transaction primitives for the private secure Node purchase path.
+ * The supported package API MUST NOT accept caller replacements for these.
+ * A single fixed Ripple-operated mainnet endpoint is a trust dependency, not
+ * a cryptographic consensus quorum.
+ */
+export const MAINNET_LEDGER_URL = 'wss://s1.ripple.com';
+const HASH = /^[0-9A-F]{64}$/;
+function required(condition, code) { if (!condition) throw new Error(code); }
+
+/** Private constructor seam: the public API always uses import('xrpl'). */
+export function buildTrustedXrplPrimitives(xrpl) {
+  required(xrpl && typeof xrpl === 'object' && typeof xrpl.Client === 'function' &&
+    typeof xrpl.hashes?.hashSignedTx === 'function', 'CPX_OFFICIAL_XRPL_LIBRARY_REQUIRED');
+
+  function hashSignedTx(signedTxBlob) {
+    required(typeof signedTxBlob === 'string' && signedTxBlob.length > 0 &&
+      signedTxBlob.length % 2 === 0 && /^[a-fA-F0-9]+$/.test(signedTxBlob),
+      'CPX_SIGNED_BLOB_INVALID');
+    const hash = xrpl.hashes.hashSignedTx(signedTxBlob);
+    required(typeof hash === 'string' && HASH.test(hash.toUpperCase()),
+      'CPX_OFFICIAL_SIGNED_HASH_INVALID');
+    return hash.toUpperCase();
+  }
+
+  async function getValidatedLedgerIndex() {
+    const client = new xrpl.Client(MAINNET_LEDGER_URL);
+    try {
+      await client.connect();
+      const index = await client.getLedgerIndex();
+      required(Number.isSafeInteger(index) && index > 0 && index <= 0xffffffff,
+        'CPX_UNTRUSTED_LEDGER_INDEX');
+      return index;
+    } finally {
+      // No alternate RPC, submitted transaction, or payment keys are involved.
+      // A failed disconnect must fail closed rather than authorize signing.
+      await client.disconnect();
+    }
+  }
+  return Object.freeze({ hashSignedTx, getValidatedLedgerIndex });
+}
+
+export async function loadOfficialXrplPrimitives() {
+  const xrpl = await import('xrpl');
+  return buildTrustedXrplPrimitives(xrpl);
+}

package/scripts/trusted-xrpl-recovery.mjs

@@ -0,0 +1,64 @@
+/**
+ * Read-only XRPL mainnet reconciliation for cpX x402 Pay.
+ * The public path cannot inject a seller-controlled RPC, verifier or HTTP response.
+ * The fixed public XRPL server is a trusted service dependency, not independent
+ * cryptographic consensus verification. All uncertain outcomes remain blocked.
+ */
+import { createLocalAttemptJournal } from './local-attempt-journal.mjs';
+import { verifyValidatedXrplSettlement } from '../dist/src/settlement_verifier.js';
+
+export const XRPL_MAINNET_READ_ONLY_URL = 'wss://s1.ripple.com';
+const HASH = /^[A-F0-9]{64}$/;
+const valid = (v, code) => { if (!v) throw new Error(code); };
+
+/** Internal test seam. Not exported by package root. */
+export async function queryValidatedTransaction({hash, makeClient}) {
+  valid(typeof hash === 'string' && HASH.test(hash), 'CPX_RECOVERY_INVALID_HASH');
+  valid(typeof makeClient === 'function', 'CPX_RECOVERY_CLIENT_REQUIRED');
+  const client = await makeClient(XRPL_MAINNET_READ_ONLY_URL);
+  valid(client && typeof client.connect === 'function' && typeof client.request === 'function' &&
+    typeof client.disconnect === 'function', 'CPX_RECOVERY_INVALID_CLIENT');
+  try {
+    await client.connect();
+    // No submit, submitAndWait, sign, autofill, account_tx or seller endpoint.
+    return await client.request({
+      command:'tx', transaction:hash, binary:false, api_version:2
+    });
+  } finally {
+    await client.disconnect();
+  }
+}
+
+/** Private test seam, intentionally not a package export. */
+export async function reconcileWithLedger({journal, intentId, makeClient}) {
+  valid(journal && typeof journal.load === 'function' && typeof journal.validated === 'function',
+    'CPX_RECOVERY_JOURNAL_REQUIRED');
+  valid(typeof intentId === 'string' && intentId.length >= 12 && intentId.length <= 200,
+    'CPX_RECOVERY_INTENT_REQUIRED');
+  const state = await journal.load(intentId);
+  valid(state.status === 'SIGNED_SUBMISSION_UNKNOWN' && state.expected &&
+    state.transactionHash === state.expected.transactionHash && HASH.test(state.transactionHash),
+    'CPX_RECOVERY_SIGNED_EXPECTATION_REQUIRED');
+  // If tx isn't found, network errors, is unvalidated, or has mismatched fields,
+  // DO NOT update the journal or permit a new payment.
+  const txResult = await queryValidatedTransaction({hash:state.transactionHash, makeClient});
+  const receipt = verifyValidatedXrplSettlement(txResult,state.expected);
+  await journal.validated(intentId,receipt);
+  return receipt;
+}
+
+/** Public supported entry point. No caller-provided lookup or verification functions. */
+export async function reconcileSecureNodePurchase(options) {
+  valid(options && typeof options === 'object' && !Array.isArray(options) &&
+    Object.keys(options).length === 2 &&
+    Object.keys(options).every(x=>x === 'intentId' || x === 'journalDir'),
+    'CPX_RECOVERY_UNSAFE_OPTION');
+  const {journalDir, intentId} = options;
+  valid(typeof journalDir === 'string' && journalDir.length > 0, 'CPX_RECOVERY_JOURNAL_DIR_REQUIRED');
+  // Load the official XRPL library, never a caller-supplied node or callback.
+  const { Client } = await import('xrpl');
+  return reconcileWithLedger({
+    journal:createLocalAttemptJournal(journalDir), intentId,
+    makeClient: url => new Client(url)
+  });
+}

package/types/public-node.d.ts

@@ -0,0 +1,55 @@
+/** cpX x402 Pay private pre-release Node API; no wallet keys are handled here. */
+import type { ClientXrplSigner } from '@x402/xrpl';
+import type { AgentPaymentConfig } from '../dist/src/policy.js';
+import type { GuardOptions } from '../dist/src/one_shot_guard.js';
+
+export type SecureNodePurchaseOptions = {
+  intent: {
+    intentId: string;
+    payer: string;
+    seller: string;
+    resource: string;
+    asset: string;
+    amount: string;
+  };
+  journalDir: string;
+  /** Strict cumulative single-host spending caps; XRP in drops, tokens in decimal units.
+   *  Reservation is not automatically released after a failure or timeout. */
+  budgetCaps: { xrpDrops: string; rlusd: string; usdc: string };
+  signer: ClientXrplSigner;
+  policy: AgentPaymentConfig;
+  /** Ledger-index lookup is provided internally from official xrpl.js on mainnet. */
+  oneShot: Omit<GuardOptions, 'getValidatedLedgerIndex'>;
+  maxFeeDrops: string;
+  request: {
+    url: string;
+    init: { method: 'POST'; body: string; headers?: HeadersInit; signal?: AbortSignal };
+  };
+  timeoutMs?: number;
+};
+
+/** Validate safe configuration without constructing any payment request. */
+export declare function validateSecureNodePurchase(options: SecureNodePurchaseOptions): true;
+
+/**
+ * Initiates at most one guarded x402 HTTP payment attempt with durable journal.
+ * A successful HTTP response is NOT equivalent to verified XRPL settlement.
+ */
+export declare function executeSecureNodePurchase(options: SecureNodePurchaseOptions): Promise<{
+  status: 'HTTP_RESPONSE_LEDGER_UNVERIFIED';
+  httpStatus: number;
+  paymentResponseHeaderPresent: boolean;
+  journalStatus: string;
+}>;
+
+/** Read-only, XRPL-mainnet settlement recovery for a previously signed, journaled purchase.
+ *  Rejects unknown/unvalidated/failed transactions; NEVER resubmits payments. */
+export declare function reconcileSecureNodePurchase(options: {journalDir: string; intentId: string}): Promise<{
+  status: 'VALIDATED_SUCCESS';
+  transactionHash: string;
+  ledgerIndex: number;
+  deliveredAmount: string;
+  asset: string;
+  feeDrops: string;
+  invoiceID: string;
+}>;