@cloudpayx/x402-pay 0.0.0-stage → 0.2.1

package/dist/src/policy.js

@@ -0,0 +1,103 @@
+const DIGITS = /^(0|[1-9][0-9]*)$/;
+const DECIMAL = /^(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+// Syntax gate only, NOT XRPL address checksum verification.
+const CLASSIC_ADDRESS_SHAPE = /^r[1-9A-HJ-NP-Za-km-z]{24,34}$/;
+const ISSUED_CURRENCY_SHAPE = /^(?:[A-Za-z0-9]{3}|[A-Fa-f0-9]{40})$/;
+/** Compare nonnegative decimal strings without Number / float rounding. */
+export function compareAmount(a, b, units) {
+    if (a.length > 64 || b.length > 64)
+        return null;
+    const valid = units === 'drops' ? DIGITS : DECIMAL;
+    if (!valid.test(a) || !valid.test(b))
+        return null;
+    const [aw, af = ''] = a.split('.');
+    const [bw, bf = ''] = b.split('.');
+    const places = Math.max(af.length, bf.length);
+    const nA = BigInt(aw + af.padEnd(places, '0'));
+    const nB = BigInt(bw + bf.padEnd(places, '0'));
+    return nA < nB ? -1 : nA > nB ? 1 : 0;
+}
+function assetKey(asset) {
+    return asset.kind === 'xrp' ? 'XRP' : `${asset.asset}|${asset.issuer}`;
+}
+function isPositiveCap(asset) {
+    const value = asset.kind === 'xrp' ? asset.maxAmountDrops : asset.maxAmount;
+    const units = asset.kind === 'xrp' ? 'drops' : 'token';
+    return compareAmount(value, '0', units) === 1;
+}
+export function createAgentPaymentGate(config) {
+    if (!config.assets?.length || !config.assets.every(isPositiveCap)) {
+        throw new Error('CPX_INVALID_ASSET_CAP');
+    }
+    const names = config.assets.map(assetKey);
+    if (new Set(names).size !== names.length)
+        throw new Error('CPX_DUPLICATE_ASSET');
+    if (config.assets.some(a => (a.kind === 'issued' && (!CLASSIC_ADDRESS_SHAPE.test(a.issuer) ||
+        !ISSUED_CURRENCY_SHAPE.test(a.asset) || a.asset === 'XRP')) ||
+        (a.kind === 'xrp' && a.asset !== 'XRP')))
+        throw new Error('CPX_INVALID_ASSET_DEFINITION');
+    if (config.recipients?.mode !== 'any' && config.recipients?.mode !== 'allowlist')
+        throw new Error('CPX_RECIPIENT_POLICY_REQUIRED');
+    if (config.recipients.mode === 'allowlist' && config.recipients.addresses.length === 0)
+        throw new Error('CPX_EMPTY_RECIPIENT_ALLOWLIST');
+    if (config.approval?.mode !== 'autonomous' && config.approval?.mode !== 'callback')
+        throw new Error('CPX_APPROVAL_POLICY_REQUIRED');
+    if (config.approval.mode === 'callback' && typeof config.approval.authorize !== 'function')
+        throw new Error('CPX_APPROVAL_CALLBACK_REQUIRED');
+    const caps = new Map(config.assets.map(a => [assetKey(a), a]));
+    const recipientAllowlist = config.recipients.mode === 'allowlist' ?
+        new Set(config.recipients.addresses) : null;
+    return {
+        async evaluate(challenge) {
+            const req = challenge?.selectedRequirements;
+            if (!req || challenge?.paymentRequired?.x402Version !== 2 ||
+                req.network !== 'xrpl:0' || req.scheme !== 'exact') {
+                return { allowed: false, reason: 'CPX_UNSUPPORTED_PAYMENT' };
+            }
+            // The XRPL x402 exact scheme requires this to be explicitly false.
+            if (req.extra?.areFeesSponsored !== false &&
+                !(config.legacyT54Offer === true && req.extra?.areFeesSponsored === undefined)) {
+                return { allowed: false, reason: 'CPX_INVALID_FEE_TERMS' };
+            }
+            if (req.extra?.assetTransferMethod !== undefined &&
+                !['sequence', 'ticketSequence'].includes(req.extra?.assetTransferMethod)) {
+                return { allowed: false, reason: 'CPX_INVALID_TRANSFER_METHOD' };
+            }
+            if (!CLASSIC_ADDRESS_SHAPE.test(req.payTo ?? '')) {
+                return { allowed: false, reason: 'CPX_INVALID_RECIPIENT_SHAPE' };
+            }
+            if (recipientAllowlist && !recipientAllowlist.has(req.payTo)) {
+                return { allowed: false, reason: 'CPX_RECIPIENT_NOT_PERMITTED' };
+            }
+            const issuer = req.asset === 'XRP' ? undefined : req.extra?.issuer;
+            // Reject inconsistent or extra issuer data for XRP.
+            if (req.asset === 'XRP' && req.extra?.issuer !== undefined) {
+                return { allowed: false, reason: 'CPX_UNEXPECTED_XRP_ISSUER' };
+            }
+            const cap = caps.get(req.asset === 'XRP' ? 'XRP' : `${req.asset}|${issuer ?? ''}`);
+            if (!cap)
+                return { allowed: false, reason: 'CPX_ASSET_NOT_PERMITTED' };
+            const units = cap.kind === 'xrp' ? 'drops' : 'token';
+            const maximum = cap.kind === 'xrp' ? cap.maxAmountDrops : cap.maxAmount;
+            const cmp = compareAmount(req.amount, maximum, units);
+            if (cmp === null || compareAmount(req.amount, '0', units) !== 1 || cmp === 1) {
+                return { allowed: false, reason: 'CPX_AMOUNT_NOT_PERMITTED' };
+            }
+            const intent = {
+                network: 'xrpl:0', asset: req.asset, amount: req.amount,
+                amountUnit: units, issuer, recipient: req.payTo
+            };
+            if (config.approval.mode === 'callback') {
+                try {
+                    if (!(await config.approval.authorize(intent))) {
+                        return { allowed: false, reason: 'CPX_PAYMENT_DENIED' };
+                    }
+                }
+                catch {
+                    return { allowed: false, reason: 'CPX_AUTHORIZATION_UNAVAILABLE' };
+                }
+            }
+            return { allowed: true, intent };
+        }
+    };
+}

package/dist/src/settlement_verifier.d.ts

@@ -0,0 +1,24 @@
+export type ExpectedXrplSettlement = {
+    /** SHA-512Half transaction hash as returned by the original signer, 64 hex chars. */
+    transactionHash: string;
+    payer: string;
+    recipient: string;
+    destinationTag?: number;
+    sourceTag?: number;
+    /** SHA-256(invoiceId string), upper-case 64 hex, bound by the signing guard. */
+    invoiceID: string;
+    asset: string;
+    issuer?: string;
+    amount: string;
+    maxFeeDrops: string;
+};
+/** Throws on any uncertain or unexpected result. Never authorizes retry. */
+export declare function verifyValidatedXrplSettlement(payload: unknown, expected: ExpectedXrplSettlement): Readonly<{
+    status: "VALIDATED_SUCCESS";
+    transactionHash: string;
+    ledgerIndex: number;
+    deliveredAmount: string;
+    asset: string;
+    feeDrops: string;
+    invoiceID: string;
+}>;

package/dist/src/settlement_verifier.js

@@ -0,0 +1,78 @@
+/**
+ * cpX x402 Pay: XRPL validated-ledger settlement verifier.
+ * Pure data verifier: no wallet, signing, network calls, or transaction submission.
+ * Caller must fetch a transaction from a trusted XRPL mainnet node using `tx`.
+ * A seller's HTTP 200 or payment-response header does NOT replace this check.
+ */
+import { compareAmount } from './policy.js';
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function required(test, code) {
+    if (!test)
+        throw new Error(code);
+}
+const HASH = /^[0-9A-Fa-f]{64}$/;
+const DROPS = /^(0|[1-9][0-9]*)$/;
+const CURRENCY = /^[0-9A-F]{40}$/;
+function equalAmount(a, b, unit) {
+    return typeof a === 'string' && compareAmount(a, b, unit) === 0;
+}
+/** Throws on any uncertain or unexpected result. Never authorizes retry. */
+export function verifyValidatedXrplSettlement(payload, expected) {
+    const outer = record(payload);
+    const data = record(outer?.result) ?? outer;
+    required(data !== undefined, 'CPX_BAD_LEDGER_RESPONSE');
+    required(HASH.test(expected.transactionHash), 'CPX_BAD_EXPECTED_TX_HASH');
+    required(HASH.test(expected.invoiceID), 'CPX_BAD_EXPECTED_INVOICE');
+    required(typeof expected.payer === 'string' && expected.payer.length > 0 &&
+        typeof expected.recipient === 'string' && expected.recipient.length > 0, 'CPX_BAD_EXPECTED_ADDRESSES');
+    required(expected.destinationTag === undefined ||
+        (Number.isInteger(expected.destinationTag) && expected.destinationTag >= 0 &&
+            expected.destinationTag <= 0xffffffff), 'CPX_BAD_EXPECTED_TAG');
+    required(expected.sourceTag === undefined ||
+        (Number.isInteger(expected.sourceTag) && expected.sourceTag >= 0 &&
+            expected.sourceTag <= 0xffffffff), 'CPX_BAD_EXPECTED_SOURCE_TAG');
+    required(DROPS.test(expected.maxFeeDrops) && BigInt(expected.maxFeeDrops) > 0n, 'CPX_BAD_EXPECTED_FEE');
+    required(data.validated === true, 'CPX_TX_NOT_VALIDATED');
+    const meta = record(data.meta);
+    required(meta !== undefined && meta.TransactionResult === 'tesSUCCESS', 'CPX_TX_NOT_SUCCESSFUL');
+    const tx = record(data.tx_json) ?? record(data.tx) ?? data;
+    const actualHash = data.hash ?? tx.hash;
+    required(typeof actualHash === 'string' && actualHash.toUpperCase() === expected.transactionHash.toUpperCase(), 'CPX_TX_HASH_MISMATCH');
+    required(tx.TransactionType === 'Payment', 'CPX_NOT_A_PAYMENT');
+    required(tx.Account === expected.payer, 'CPX_WRONG_PAYER');
+    required(tx.Destination === expected.recipient, 'CPX_WRONG_RECIPIENT');
+    required(tx.DestinationTag === expected.destinationTag, 'CPX_WRONG_TAG');
+    required(tx.SourceTag === expected.sourceTag, 'CPX_WRONG_SOURCE_TAG');
+    required(typeof tx.InvoiceID === 'string' && tx.InvoiceID.toUpperCase() === expected.invoiceID.toUpperCase(), 'CPX_WRONG_INVOICE');
+    required(typeof tx.Fee === 'string' && DROPS.test(tx.Fee) &&
+        BigInt(tx.Fee) > 0n && BigInt(tx.Fee) <= BigInt(expected.maxFeeDrops), 'CPX_FEE_MISMATCH');
+    required(typeof data.ledger_index === 'number' && Number.isSafeInteger(data.ledger_index) &&
+        data.ledger_index > 0, 'CPX_MISSING_VALIDATED_LEDGER');
+    // XRPL v2 uses DeliverMax, v1 uses Amount; delivered_amount is authoritative.
+    const requested = tx.DeliverMax ?? tx.Amount;
+    const delivered = meta.delivered_amount;
+    const unit = expected.asset === 'XRP' ? 'drops' : 'token';
+    if (unit === 'drops') {
+        required(expected.issuer === undefined && equalAmount(requested, expected.amount, 'drops'), 'CPX_WRONG_XRP_REQUEST');
+        required(equalAmount(delivered, expected.amount, 'drops'), 'CPX_WRONG_XRP_DELIVERY');
+    }
+    else {
+        required(CURRENCY.test(expected.asset) && typeof expected.issuer === 'string' && expected.issuer.startsWith('r'), 'CPX_BAD_EXPECTED_ASSET');
+        for (const [label, candidate] of [['REQUEST', requested], ['DELIVERY', delivered]]) {
+            const value = record(candidate);
+            required(value !== undefined && value.currency === expected.asset &&
+                value.issuer === expected.issuer && equalAmount(value.value, expected.amount, 'token'), `CPX_WRONG_${label}`);
+        }
+    }
+    return Object.freeze({
+        status: 'VALIDATED_SUCCESS',
+        transactionHash: expected.transactionHash.toUpperCase(),
+        ledgerIndex: data.ledger_index,
+        deliveredAmount: expected.amount,
+        asset: expected.asset,
+        feeDrops: tx.Fee,
+        invoiceID: expected.invoiceID.toUpperCase()
+    });
+}

package/dist/src/xrpl_x402_wire.d.ts

@@ -0,0 +1 @@
+export declare function createCpXWireFetch(baseFetch: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/src/xrpl_x402_wire.js

@@ -0,0 +1,69 @@
+function decode(header) {
+    if (header.length > 131072)
+        throw Error("CPX_PAYMENT_HEADER_TOO_LARGE");
+    try {
+        const binary = atob(header);
+        const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw Error("CPX_INVALID_PAYMENT_ENVELOPE");
+    }
+}
+function encode(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 8192) {
+        binary += String.fromCharCode(...Array.from(bytes.subarray(i, i + 8192)));
+    }
+    return btoa(binary);
+}
+export function createCpXWireFetch(baseFetch) {
+    return async (input, init) => {
+        const request = new Request(input, init);
+        const url = new URL(request.url);
+        if (url.protocol !== "https:" || url.username || url.password)
+            throw Error("CPX_UNSAFE_PAYMENT_URL");
+        const safe = new Request(request, { redirect: "error" });
+        const signature = safe.headers.get("PAYMENT-SIGNATURE");
+        if (!signature)
+            return baseFetch(safe);
+        const payment = decode(signature);
+        const accepted = payment?.accepted;
+        const extra = accepted?.extra;
+        const isT54Xrp = payment?.x402Version === 2 &&
+            accepted?.scheme === "exact" &&
+            accepted?.network === "xrpl:0" &&
+            accepted?.asset === "XRP" &&
+            extra?.sourceTag === 804681468;
+        // Existing RLUSD and USDC envelopes remain unchanged.
+        if (!isT54Xrp)
+            return baseFetch(safe);
+        const invoice = extra?.invoiceId;
+        const payload = payment.payload;
+        if (extra?.areFeesSponsored !== false ||
+            typeof invoice !== "string" ||
+            invoice.length < 1 ||
+            invoice.length > 128 ||
+            typeof accepted?.payTo !== "string" ||
+            !/^r[1-9A-HJ-NP-Za-km-z]{24,34}$/.test(accepted.payTo) ||
+            typeof accepted?.amount !== "string" ||
+            !/^[1-9][0-9]*$/.test(accepted.amount) ||
+            !payload ||
+            typeof payload.signedTxBlob !== "string" ||
+            !/^(?:[0-9a-fA-F]{2})+$/.test(payload.signedTxBlob) ||
+            (payload.invoiceId !== undefined &&
+                payload.invoiceId !== invoice)) {
+            throw Error("CPX_T54_WIRE_VALIDATION_FAILED");
+        }
+        const headers = new Headers(safe.headers);
+        headers.set("PAYMENT-SIGNATURE", encode({
+            ...payment,
+            payload: { ...payload, invoiceId: invoice }
+        }));
+        return baseFetch(new Request(safe, {
+            headers,
+            redirect: "error"
+        }));
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@cloudpayx/x402-pay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "private": false,
+  "type": "module",
+  "description": "Experimental, wallet-agnostic, account-free XRP, RLUSD and USDC XRPL x402 buyer integration",
+  "dependencies": {
+    "@x402/core": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "@x402/xrpl": "2.28.0",
+    "xrpl": "4.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test:policy": "tsc -p tsconfig.guard.json && node --test tests/*.test.mjs",
+    "demo:dry-run": "tsc -p tsconfig.policy.json && node examples/simulation-only.mjs",
+    "test:signing-guard": "tsc -p tsconfig.guard.json && node --test tests/guard.test.mjs"
+  },
+  "main": "./scripts/public-node.mjs",
+  "types": "./types/public-node.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/public-node.d.ts",
+      "node": "./scripts/public-node.mjs",
+      "default": "./scripts/public-node.mjs"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "scripts/public-node.mjs",
+    "scripts/secure-node-purchase.mjs",
+    "scripts/durable-purchase-lifecycle.mjs",
+    "scripts/local-attempt-journal.mjs",
+    "scripts/persistent-spending-budget.mjs",
+    "scripts/safe-agent-fetch.mjs",
+    "scripts/trusted-xrpl-primitives.mjs",
+    "scripts/trusted-xrpl-recovery.mjs",
+    "types/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/durable-purchase-lifecycle.mjs

@@ -0,0 +1,114 @@
+/**
+ * cpX x402 Pay: local, self-funded-agent purchase lifecycle.
+ * No network, wallet, transaction builder, or submission code is included here.
+ * IMPORTANT: call executeDurablePurchase with the signer factory INSIDE the
+ * exclusive journal reservation. The factory MUST apply createCpXX402AgentPay's
+ * oneShot transaction guard around the provided journaledSigner.
+ * Never use this local file journal for multi-host delegated/managed accounts.
+ */
+const HEX64 = /^[0-9a-fA-F]{64}$/;
+const DROPS = /^(0|[1-9][0-9]*)$/;
+function requireCondition(ok, code) { if (!ok) throw new Error(code); }
+const isRecord = x => x !== null && typeof x === 'object' && !Array.isArray(x);
+function transactionExpectation(tx, hash, maxFeeDrops) {
+  requireCondition(isRecord(tx) && tx.TransactionType === 'Payment', 'CPX_JOURNAL_NOT_PAYMENT');
+  requireCondition(typeof tx.Account === 'string' && typeof tx.Destination === 'string', 'CPX_JOURNAL_BAD_ADDRESS');
+  requireCondition(tx.DestinationTag === undefined ||
+    (Number.isInteger(tx.DestinationTag) && tx.DestinationTag >= 0 && tx.DestinationTag <= 0xffffffff), 'CPX_JOURNAL_BAD_TAG');
+  requireCondition(tx.SourceTag === undefined ||
+    (Number.isInteger(tx.SourceTag) && tx.SourceTag >= 0 && tx.SourceTag <= 0xffffffff), 'CPX_JOURNAL_BAD_SOURCE_TAG');
+  requireCondition(typeof tx.InvoiceID === 'string' && HEX64.test(tx.InvoiceID), 'CPX_JOURNAL_BAD_INVOICE');
+  requireCondition(DROPS.test(maxFeeDrops) && BigInt(maxFeeDrops) > 0n, 'CPX_JOURNAL_BAD_FEE_CAP');
+  requireCondition(typeof tx.Fee === 'string' && DROPS.test(tx.Fee) && BigInt(tx.Fee) > 0n && BigInt(tx.Fee) <= BigInt(maxFeeDrops), 'CPX_JOURNAL_FEE_EXCEEDS_CAP');
+  requireCondition(
+    Number.isSafeInteger(tx.LastLedgerSequence) &&
+    tx.LastLedgerSequence > 0 &&
+    tx.LastLedgerSequence <= 0xffffffff,
+    'CPX_JOURNAL_LAST_LEDGER_REQUIRED'
+  );
+  const value = tx.DeliverMax ?? tx.Amount;
+  let asset, issuer, amount;
+  if (typeof value === 'string') {
+    asset = 'XRP'; amount = value;
+    requireCondition(DROPS.test(amount) && BigInt(amount) > 0n, 'CPX_JOURNAL_BAD_XRP');
+  } else {
+    requireCondition(isRecord(value) && typeof value.currency === 'string' && typeof value.issuer === 'string' && typeof value.value === 'string', 'CPX_JOURNAL_BAD_TOKEN');
+    asset = value.currency; issuer = value.issuer; amount = value.value;
+  }
+  return {transactionHash: hash, payer: tx.Account, recipient: tx.Destination,
+    ...(tx.DestinationTag === undefined ? {} : {destinationTag:tx.DestinationTag}),
+    ...(tx.SourceTag === undefined ? {} : {sourceTag:tx.SourceTag}),
+    invoiceID: tx.InvoiceID.toUpperCase(),
+    lastLedgerSequence: tx.LastLedgerSequence,
+    asset, ...(issuer === undefined ? {} : {issuer}), amount, maxFeeDrops};
+}
+
+/** Persist the original signed transaction hash BEFORE returning the blob to x402. */
+export function createJournaledSigner({signer, journal, intentId, hashSignedTx, maxFeeDrops}) {
+  requireCondition(typeof signer?.classicAddress === 'string' && typeof signer.sign === 'function', 'CPX_SIGNER_REQUIRED');
+  requireCondition(typeof journal?.signed === 'function', 'CPX_JOURNAL_REQUIRED');
+  requireCondition(typeof hashSignedTx === 'function', 'CPX_OFFICIAL_SIGNED_HASH_FUNCTION_REQUIRED');
+  let invoked = false;
+  return {
+    classicAddress: signer.classicAddress,
+    async sign(tx) {
+      requireCondition(!invoked, 'CPX_JOURNAL_SIGNER_ALREADY_USED');
+      invoked = true; // fail-closed even if an await fails or two calls overlap
+      const signed = await signer.sign(tx); // should be invoked THROUGH the official one-shot guard
+      requireCondition(typeof signed?.signedTxBlob === 'string' && signed.signedTxBlob.length > 0, 'CPX_SIGNER_NO_BLOB');
+      const hash = hashSignedTx(signed.signedTxBlob);
+      requireCondition(typeof hash === 'string' && HEX64.test(hash), 'CPX_INVALID_COMPUTED_HASH');
+      if (signed.hash !== undefined) {
+        requireCondition(typeof signed.hash === 'string' && signed.hash.toUpperCase() === hash.toUpperCase(), 'CPX_SIGNED_HASH_MISMATCH');
+      }
+      const expected = transactionExpectation(tx, hash.toUpperCase(), maxFeeDrops);
+      requireCondition(tx.Account === signer.classicAddress, 'CPX_JOURNAL_PAYER_MISMATCH');
+      await journal.signed(intentId, hash.toUpperCase(), expected); // fsync + atomic rename
+      return signed; // NEVER returned if durable persistence fails
+    }
+  };
+}
+
+/**
+ * Reserve a stable economic intent BEFORE requesting the x402 resource.
+ * 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}) {
+  requireCondition(typeof journal?.reserve === 'function', 'CPX_JOURNAL_REQUIRED');
+  requireCondition(typeof createPaymentClient === 'function', 'CPX_CLIENT_FACTORY_REQUIRED');
+  requireCondition(typeof reserveBudget === 'function', 'CPX_BUDGET_RESERVATION_REQUIRED');
+  requireCondition(typeof request?.url === 'string' && request.url === intent.resource, 'CPX_RESOURCE_MISMATCH');
+  await journal.reserve(intent); // duplicates and concurrent same-ID attempts fail here
+  // 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});
+  // Caller must use createCpXX402AgentPay({signer:journaledSigner, policy, oneShot:{...}})
+  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.
+  const response = await buyer.paidFetch(request.url, request.init);
+  // Capture seller rejection text for diagnostics; never treat it as settlement proof.
+  let rejectionBody;
+  if (response.status !== 200) {
+    try { rejectionBody = (await response.clone().text()).slice(0, 2048); }
+    catch { rejectionBody = 'SELLER_RESPONSE_BODY_UNAVAILABLE'; }
+  }
+  return {status: 'HTTP_RESPONSE_LEDGER_UNVERIFIED',
+    ...(rejectionBody === undefined ? {} : {rejectionBody}), httpStatus: response.status,
+    paymentResponseHeaderPresent: response.headers?.has?.('payment-response') === true,
+    journalStatus: (await journal.load(intent.intentId)).status};
+}
+
+/** Strict read-only reconciliation. No submission or retry is possible here. */
+export async function reconcileDurablePurchase({journal, intentId, lookupValidatedTransaction, verifyValidatedXrplSettlement}) {
+  requireCondition(typeof lookupValidatedTransaction === 'function' && typeof verifyValidatedXrplSettlement === 'function', 'CPX_RECONCILER_REQUIRED');
+  const state = await journal.load(intentId);
+  requireCondition(state.status === 'SIGNED_SUBMISSION_UNKNOWN' && isRecord(state.expected), 'CPX_NO_SIGNED_EXPECTATION_TO_RECONCILE');
+  // The lookup must query an independently trusted XRPL mainnet node, NOT the seller.
+  const ledgerResponse = await lookupValidatedTransaction(state.transactionHash);
+  const receipt = verifyValidatedXrplSettlement(ledgerResponse, state.expected);
+  await journal.validated(intentId, receipt);
+  return receipt;
+}

package/scripts/local-attempt-journal.mjs

@@ -0,0 +1,82 @@
+/**
+ * Local durable idempotency demonstration for independent agents.
+ * Each distinct economic purchase MUST have a stable application-provided intentId.
+ * Fail closed if same intentId is seen again, even with a new seller invoice.
+ * No secrets or signed transaction blobs are stored.
+ * Not a multi-host distributed lock, Cloudflare database, or account-wide budget.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const HASH = /^[0-9A-Fa-f]{64}$/;
+function requireValue(condition, code) {
+  if (!condition) throw new Error(code);
+}
+export function createLocalAttemptJournal(folder) {
+  requireValue(typeof folder === 'string' && folder.length > 0, 'CPX_INVALID_JOURNAL_DIR');
+  const dir = resolve(folder);
+  const fileFor = intentId => {
+    requireValue(typeof intentId === 'string' && intentId.length >= 12 && intentId.length <= 200, 'CPX_BAD_INTENT_ID');
+    return join(dir, createHash('sha256').update(intentId).digest('hex') + '.json');
+  };
+  async function load(intentId) {
+    const raw = await readFile(fileFor(intentId), 'utf8');
+    const state = JSON.parse(raw);
+    requireValue(state.intentId === intentId, 'CPX_JOURNAL_ID_MISMATCH');
+    return state;
+  }
+  async function reserve({intentId, payer, seller, resource, asset, amount}) {
+    requireValue([payer,seller,resource,asset,amount].every(v => typeof v === 'string' && v.length > 0), 'CPX_BAD_INTENT');
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const file = fileFor(intentId);
+    // Open with O_EXCL: only one process can claim an intent at a time on local filesystem.
+    let fd;
+    try {
+      fd = await open(file, 'wx', 0o600);
+    } catch (err) {
+      if (err?.code === 'EEXIST') throw new Error('CPX_DUPLICATE_PURCHASE_INTENT_BLOCKED');
+      throw err;
+    }
+    const state = {intentId, payer, seller, resource, asset, amount,
+      status:'RESERVED_OUTCOME_UNKNOWN', createdAt:new Date().toISOString()};
+    try {
+      await fd.writeFile(JSON.stringify(state, null, 2));
+      await fd.sync();
+    } finally { await fd.close(); }
+    return state;
+  }
+  async function signed(intentId, hash, expected) {
+    requireValue(typeof hash === 'string' && HASH.test(hash), 'CPX_INVALID_SIGNED_HASH');
+    const state = await load(intentId);
+    requireValue(state.status === 'RESERVED_OUTCOME_UNKNOWN', 'CPX_SIGNED_STATE_CONFLICT');
+    if (expected !== undefined) {
+      requireValue(expected && typeof expected === 'object' && !Array.isArray(expected) &&
+        expected.transactionHash === hash.toUpperCase() &&
+        expected.payer === state.payer && expected.recipient === state.seller &&
+        expected.asset === state.asset && expected.amount === state.amount,
+        'CPX_EXPECTED_PAYMENT_MISMATCH');
+    }
+    return update(intentId, {...state, status:'SIGNED_SUBMISSION_UNKNOWN',
+      transactionHash:hash.toUpperCase(), ...(expected === undefined ? {} : {expected})});
+  }
+  async function validated(intentId, verifiedReceipt) {
+    const state = await load(intentId);
+    requireValue(state.status === 'SIGNED_SUBMISSION_UNKNOWN' &&
+      verifiedReceipt?.status === 'VALIDATED_SUCCESS' &&
+      verifiedReceipt.transactionHash === state.transactionHash,
+      'CPX_LEDGER_PROOF_REQUIRED');
+    return update(intentId, {...state, status:'VALIDATED_SUCCESS',
+      ledgerIndex:verifiedReceipt.ledgerIndex, verifiedReceipt, verifiedAt:new Date().toISOString()});
+  }
+  async function update(intentId, state) {
+    const dest = fileFor(intentId);
+    const temp = dest + '.' + 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, dest);
+    return state;
+  }
+  return { reserve, signed, validated, load };
+}