@cloudpayx/x402-pay 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# cpX x402 Pay — XRP + RLUSD + USDC XRPL agent SDK (Alpha)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Purpose:** Let an unaffiliated, self-funded agent participate in the XRPL x402 economy without a cloudpayX registration, dashboard, Supabase session, or required wallet brand. This is a *local client integration* for buying x402 resources, **not** a publicly deployed service, published npm package, or operator-funded wallet gateway.
+
+This package is **pre-release security work**. It does not authenticate an operator, implement managed mandates, custody funds, create wallets, enforce global daily budgets, or provide guaranteed purchase idempotency. It has not yet been tested end-to-end with a third-party wallet/signer or a live 402 seller. **Do not give it unattended signing access to a valuable wallet.**
+
+## Source
+
+- `src/policy.ts` — strict, dependency-free XRPL x402 V2 policy checks.
+- `src/assets.ts` — verified XRPL mainnet XRP / Ripple RLUSD / Circle USDC identity constants and three-asset policy builder.
+- `src/index.ts` — adapter to the existing proven `@x402/core`, `@x402/fetch`, `@x402/xrpl` client.
+- `examples/feral-agent.example.ts` — signer-injection example; no secrets or hardcoded wallet provider.
+- `examples/simulation-only.mjs` — no-wallet, no-network, no-payment demonstration.
+- `tests/policy.test.mjs` and `tests/three-assets.test.mjs` — locally executable approval/denial tests for all three assets.
+
+## On your Mac (do not deploy yet)
+
+**Keep this a separate test folder, do not copy over `src/cloudpayx_x402_pay.ts` or `src/cloudpayx_x402_pay_configured.ts`.**
+
+1. Unzip, open Terminal in the unzipped directory.
+2. Run `npm install` (the official `@x402/*` packages are required for the SDK adapter).
+3. Run `npm run test:policy` and `npm run demo:dry-run`.
+4. Run `npm run build` to check SDK integration types against the actual installed packages.
+
+`npm run test:policy` needs only the TypeScript compiler, Node.js, and the dependency-free policy module. The build needs official x402 packages; network/package installation was unavailable during packaging.
+
+## Three verified XRPL mainnet assets
+
+The optional helper `createThreeAssetPolicy` pins the network to `xrpl:0` and enables ONLY these official asset identities:
+
+| Asset | x402 `asset` | x402 `extra.issuer` | Max amount unit |
+| --- | --- | --- | --- |
+| XRP | `XRP` | None | Integer drops (1 XRP = 1,000,000 drops) |
+| Ripple RLUSD | `524C555344000000000000000000000000000000` | `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` | Decimal RLUSD tokens |
+| Circle USDC on XRPL | `5553444300000000000000000000000000000000` | `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE` | Decimal USDC tokens |
+
+Only these XRPL issuances are accepted by this helper, *not* similarly named bridged tokens, Base USDC, or arbitrary USD IOUs. Signing always uses a caller-supplied `ClientXrplSigner`. **There is no automatic token conversion, exchange quoting, currency netting, or account registration.**
+
+## Sample: permissionless, self-funded agent using all three
+
+```ts
+import { createCpXX402AgentPay, createThreeAssetPolicy } from './src/index.js';
+
+const { paidFetch } = createCpXX402AgentPay({
+  signer: MY_SECURE_XRPL_SIGNER, // compatible @x402/xrpl ClientXrplSigner
+  policy: createThreeAssetPolicy({
+    limits: {
+      xrpDrops: '50000', // 0.05 XRP
+      rlusd: '0.05',    // 0.05 RLUSD
+      usdc: '0.05'      // 0.05 Circle USDC (XRPL)
+    },
+    recipients: { mode: 'any' }, // opt-in open seller participation
+    approval: { mode: 'autonomous' } // explicit local operator/agent opt-in
+  })
+});
+const response = await paidFetch('https://a-trusted-x402-resource.example/report');
+```
+
+`MY_SECURE_XRPL_SIGNER` and seller URL are placeholders. Don't paste wallet secrets into this file. **An unknown agent can use the SDK with its own signer, but does not gain authority over anyone else's funds.**
+
+`npm run demo:dry-run` simulates XRP, RLUSD, and USDC policy decisions without a wallet or network.
+
+## Units are not interchangeable
+
+| XRPL asset | x402 `amount` units | `maxAmount...` example |
+| --- | --- | --- |
+| Native XRP | Drops (1,000,000 drops = 1 XRP) | `{kind:'xrp',asset:'XRP',maxAmountDrops:'50000'}` = 0.05 XRP |
+| RLUSD, USDC or other XRPL-issued token | Decimal issued-token value | `{kind:'issued', asset:'...', issuer:'...', maxAmount:'0.05'}` = 0.05 token |
+
+This module rejects scientific notation and prices above its exact cap. Limits are independent; they are **not** an equivalent USD portfolio budget. **Network fees are extra; the per-payment cap bounds the x402 transfer amount, not the combined cost including XRPL fees, trustline reserves, or issuer transfer fees.** XRPL recipient validation here only checks basic address *shape*. The underlying SDK/signer/facilitator must validate destination checksum, invoice/transaction binding, signature authorization, settlement, and errors.
+
+## Security boundaries
+
+- No Xaman dependency and no human cloudpayX account required for self-funded agents.
+- Strict XRPL mainnet `xrpl:0`, x402 V2, `exact` scheme, `areFeesSponsored=false`.
+- Explicit assets and exact amount caps; opt-in seller-neutral recipient policy or allowlist.
+- Explicit `autonomous` opt-in or application-provided authorization callback, with fail-closed exceptions.
+- A self-funded agent retains *unrestricted authority over its own signer*. A local SDK is **not a trust boundary** against an agent holding the key: it can bypass these checks. Hardware signers, dedicated wallets, and controlled signer services are needed for stronger enforcement.
+- **Not yet solved:** daily budgets; concurrent duplicate payments; resource-host validation, anti-SSRF, payment replays; wallet cross-network replay risks; fee caps; seller fraud; external signing adapters; end-to-end validated settlement checks; managed/delegated spending and revocation. The XRPL scheme uses account sequence/tickets; concurrent sequence-method payments require coordination.
+- The live x402 facilitator/service should validate transaction signatures and bind invoice, amount, asset, destination and network, as described in the XRPL exact scheme spec.
+
+## Operational conditions for USDC and RLUSD
+
+The agent wallet must have the required XRPL token trustline/balance/authorization (where applicable) and enough XRP for transaction fees and reserves. A valid policy decision **does not** guarantee a successful token payment or a resource response. The resource server must advertise a compatible x402 `accepts` entry; the SDK does not auto-swap XRP into stablecoins.
+
+The underlying XRPL exact scheme includes issuer binding and fee-payment rules. The current Alpha does not make independent fee ceilings, balance checks, trustline checks, daily budgets, concurrency locks, or validated settlement guarantees. A self-funded agent holding its own signing authority can bypass an SDK policy. **Do not enable unattended real-money signing until those boundaries are addressed.**
+
+**Official issuers:** [Ripple RLUSD](https://docs.ripple.com/products/stablecoin/developer-resources/rlusd-on-the-xrpl) and [Circle XRPL USDC](https://www.circle.com/blog/now-available-usdc-on-the-xrpl).
+
+## Next milestone
+
+Use a **dedicated funded test wallet** and a real compatible XRPL x402 resource in a supervised, deliberately low-value interoperability test. First reconcile Node/Bun and dependency-compatibility, then add durable budget reservation and signing isolation for *operator-funded* agents. Do not enable real-money unattended signing on this Alpha example.
+
+Specifications: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md

package/dist/src/assets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Verified XRPL MAINNET asset identifiers for cpX x402 Pay.
+ * Issued tokens are ALWAYS identified by (currency code, issuer), not by symbol.
+ *
+ * XRP: native drops, no issuer.
+ * RLUSD: Ripple's XRPL issuance (not EVM RLUSD).
+ * USDC: Circle's native XRPL issuance (not bridged USDC or USDC on Base).
+ *
+ * Sources:
+ * https://docs.ripple.com/products/stablecoin/developer-resources/rlusd-on-the-xrpl
+ * https://www.circle.com/blog/now-available-usdc-on-the-xrpl
+ * https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
+ */
+import type { AgentPaymentConfig } from './policy.js';
+export declare const CPX_XRPL_MAINNET_ASSETS: Readonly<{
+    XRP: Readonly<{
+        kind: "xrp";
+        asset: "XRP";
+        network: "xrpl:0";
+    }>;
+    RLUSD: Readonly<{
+        kind: "issued";
+        asset: "524C555344000000000000000000000000000000";
+        issuer: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De";
+        network: "xrpl:0";
+    }>;
+    USDC: Readonly<{
+        kind: "issued";
+        asset: "5553444300000000000000000000000000000000";
+        issuer: "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE";
+        network: "xrpl:0";
+    }>;
+}>;
+export type ThreeAssetLimits = {
+    /** XRP's x402 amount is integer DROPS, not XRP units. 50000 = 0.05 XRP. */
+    xrpDrops: string;
+    /** RLUSD's x402 amount is a decimal token value, e.g. "0.05". */
+    rlusd: string;
+    /** Circle's XRPL USDC amount is a decimal token value, e.g. "0.05". */
+    usdc: string;
+};
+export type ThreeAssetPolicyOptions = {
+    /** All three limits are mandatory and must be positive; no implied unlimited cap. */
+    limits: ThreeAssetLimits;
+    recipients: AgentPaymentConfig['recipients'];
+    approval: AgentPaymentConfig['approval'];
+};
+/**
+ * Builds a policy restricted to the three official cpX mainnet asset identities.
+ * This helper DOES NOT create a signer, send a payment, or authorize an operator.
+ * Pass to createCpXX402AgentPay({ signer, policy }) and keep the signer isolated.
+ */
+export declare function createThreeAssetPolicy(options: ThreeAssetPolicyOptions): AgentPaymentConfig;

package/dist/src/assets.js

@@ -0,0 +1,36 @@
+export const CPX_XRPL_MAINNET_ASSETS = Object.freeze({
+    XRP: Object.freeze({ kind: 'xrp', asset: 'XRP', network: 'xrpl:0' }),
+    RLUSD: Object.freeze({
+        kind: 'issued',
+        asset: '524C555344000000000000000000000000000000',
+        issuer: 'rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De',
+        network: 'xrpl:0'
+    }),
+    USDC: Object.freeze({
+        kind: 'issued',
+        asset: '5553444300000000000000000000000000000000',
+        issuer: 'rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE',
+        network: 'xrpl:0'
+    })
+});
+/**
+ * Builds a policy restricted to the three official cpX mainnet asset identities.
+ * This helper DOES NOT create a signer, send a payment, or authorize an operator.
+ * Pass to createCpXX402AgentPay({ signer, policy }) and keep the signer isolated.
+ */
+export function createThreeAssetPolicy(options) {
+    if (!options?.limits)
+        throw new Error('CPX_THREE_ASSET_LIMITS_REQUIRED');
+    const { limits, recipients, approval } = options;
+    return {
+        assets: [
+            { kind: 'xrp', asset: CPX_XRPL_MAINNET_ASSETS.XRP.asset, maxAmountDrops: limits.xrpDrops },
+            { kind: 'issued', asset: CPX_XRPL_MAINNET_ASSETS.RLUSD.asset,
+                issuer: CPX_XRPL_MAINNET_ASSETS.RLUSD.issuer, maxAmount: limits.rlusd },
+            { kind: 'issued', asset: CPX_XRPL_MAINNET_ASSETS.USDC.asset,
+                issuer: CPX_XRPL_MAINNET_ASSETS.USDC.issuer, maxAmount: limits.usdc }
+        ],
+        recipients,
+        approval
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+import { x402Client } from '@x402/core/client';
+import { type ClientXrplSigner } from '@x402/xrpl';
+import { type AgentPaymentConfig } from './policy.js';
+import { type GuardOptions } from './one_shot_guard.js';
+export { compareAmount, createAgentPaymentGate } from './policy.js';
+export { CPX_XRPL_MAINNET_ASSETS, createThreeAssetPolicy } from './assets.js';
+export { createOneShotXrplSigner } from './one_shot_guard.js';
+export type { GuardOptions } from './one_shot_guard.js';
+export type { ThreeAssetLimits, ThreeAssetPolicyOptions } from './assets.js';
+export type { AgentPaymentConfig, PaymentIntent, XrplAsset, X402Requirements } from './policy.js';
+/**
+ * Bring-your-own XRPL signer. One-shot mode binds the selected x402 offer
+ * to a checked transaction just before sign() runs.
+ * Self-funded agents own their keys; they can bypass SDK restrictions if they
+ * deliberately use their own signer outside the SDK.
+ */
+export declare function createCpXX402AgentPay(options: {
+    signer: ClientXrplSigner;
+    policy: AgentPaymentConfig;
+    requestFetch?: typeof fetch;
+    /** Strongly recommended for the first supervised purchase; NOT a persistent budget. */
+    oneShot?: GuardOptions;
+}): {
+    paidFetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    client: x402Client;
+    /** For instrumentation only; not evidence of settlement. */
+    oneShotStatus: () => {
+        armed: boolean;
+        consumed: boolean;
+    } | undefined;
+};

package/dist/src/index.js

@@ -0,0 +1,85 @@
+import { Client as CpXXrplClient } from "xrpl";
+import { createCpXWireFetch } from "./xrpl_x402_wire.js";
+import { x402Client } from '@x402/core/client';
+import { wrapFetchWithPayment } from '@x402/fetch';
+import { ExactXrplScheme } from '@x402/xrpl';
+import { createAgentPaymentGate } from './policy.js';
+import { createOneShotXrplSigner } from './one_shot_guard.js';
+export { compareAmount, createAgentPaymentGate } from './policy.js';
+export { CPX_XRPL_MAINNET_ASSETS, createThreeAssetPolicy } from './assets.js';
+export { createOneShotXrplSigner } from './one_shot_guard.js';
+/**
+ * Bring-your-own XRPL signer. One-shot mode binds the selected x402 offer
+ * to a checked transaction just before sign() runs.
+ * Self-funded agents own their keys; they can bypass SDK restrictions if they
+ * deliberately use their own signer outside the SDK.
+ */
+export function createCpXX402AgentPay(options) {
+    const gate = createAgentPaymentGate(options.policy);
+    const guarded = options.oneShot ? createOneShotXrplSigner(options.signer, options.oneShot) : undefined;
+    const signer = guarded?.signer ?? options.signer;
+    const client = new x402Client((_version, requirements) => {
+        const chosen = requirements.find(req => req.network === 'xrpl:0' &&
+            req.scheme === 'exact' &&
+            options.policy.assets.some(asset => asset.asset === req.asset &&
+                (asset.kind === 'xrp' || asset.issuer === req.extra?.issuer)));
+        if (!chosen)
+            throw new Error('CPX_NO_PERMITTED_XRPL_ASSET');
+        return chosen;
+    }).setSpendControls({
+        // Explicitly select only the asset(s) authorized by this agent's policy.
+        allowedAssets: options.policy.assets.map(a => ({ network: 'xrpl:0', asset: a.asset }))
+    }).register('xrpl:0', new ExactXrplScheme(signer, {
+        preparePaymentTransaction: async (transaction, requirements) => {
+            if (requirements.network !== "xrpl:0") {
+                throw new Error("CPX_XRPL_MAINNET_ONLY");
+            }
+            const seconds = Number(requirements.maxTimeoutSeconds);
+            if (!Number.isSafeInteger(seconds) || seconds <= 0) {
+                throw new Error("CPX_INVALID_PAYMENT_TIMEOUT");
+            }
+            const ledger = new CpXXrplClient("wss://s1.ripple.com");
+            try {
+                await ledger.connect();
+                const currentLedger = await ledger.getLedgerIndex();
+                const maxLedger = currentLedger + Math.ceil(seconds / 5) + 2;
+                const expiry = transaction.LastLedgerSequence;
+                if (expiry !== undefined &&
+                    (!Number.isSafeInteger(expiry) ||
+                        expiry <= currentLedger ||
+                        expiry > maxLedger)) {
+                    throw new Error("CPX_INVALID_LEDGER_EXPIRY");
+                }
+                return await ledger.autofill({
+                    ...transaction,
+                    LastLedgerSequence: expiry ?? maxLedger
+                });
+            }
+            finally {
+                await ledger.disconnect();
+            }
+        },
+        wsUrlByNetwork: { 'xrpl:0': 'wss://s1.ripple.com' },
+        // Never let the guarded signer authorize a TicketCreate transaction.
+        ...(guarded ? { ticketCreateCount: 0 } : {})
+    }));
+    client.onBeforePaymentCreation(async ({ paymentRequired, selectedRequirements }) => {
+        const result = await gate.evaluate({ paymentRequired, selectedRequirements });
+        if (!result.allowed)
+            return { abort: true, reason: result.reason };
+        if (guarded) {
+            try {
+                await guarded.arm(selectedRequirements);
+            }
+            catch {
+                return { abort: true, reason: 'CPX_ONE_SHOT_ARM_FAILED' };
+            }
+        }
+    });
+    return {
+        paidFetch: wrapFetchWithPayment(createCpXWireFetch(options.requestFetch ?? globalThis.fetch), client),
+        client,
+        /** For instrumentation only; not evidence of settlement. */
+        oneShotStatus: () => guarded?.getStatus()
+    };
+}

package/dist/src/one_shot_guard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * cpX x402 Pay: bounded, single-signature guard for a supervised XRPL purchase.
+ * NO wallet keys, network requests, or transaction submission in this module.
+ * The guarded signer may only sign one validated Payment for one selected x402 offer.
+ */
+import { type X402Requirements } from './policy.js';
+export type XrplSigningTransaction = Record<string, unknown>;
+export type MinimalXrplSigner<T extends object> = {
+    classicAddress: string;
+    sign(transaction: T): Promise<{
+        signedTxBlob: string;
+        hash?: string;
+    }> | {
+        signedTxBlob: string;
+        hash?: string;
+    };
+};
+export type GuardOptions = {
+    recipient: string;
+    asset: string;
+    issuer?: string;
+    /** XRP in drops, or issued-token decimal units. */
+    exactAmount: string;
+    /** For issued tokens, cap token SendMax including any transfer fee. */
+    maxSendMax?: string;
+    /** The largest signing fee in integer XRP drops. */
+    maxFeeDrops: string;
+    /** Explicitly opt in to deployed t54 seller conventions for this purchase only. */
+    legacyT54Offer?: boolean;
+    /** Query XRPL MAINNET's current validated ledger index. Never use a user-controlled value in production. */
+    getValidatedLedgerIndex: () => Promise<number>;
+};
+export declare function createOneShotXrplSigner<T extends object>(original: MinimalXrplSigner<T>, options: GuardOptions): {
+    signer: {
+        classicAddress: string;
+        sign(tx: T): Promise<{
+            signedTxBlob: string;
+            hash?: string;
+        } | {
+            signedTxBlob: string;
+            hash?: string;
+        }>;
+    };
+    /** Arms the guard for exactly one challenge AFTER x402 policy and human approval. */
+    arm(req: X402Requirements & {
+        maxTimeoutSeconds?: number;
+    }): Promise<void>;
+    getStatus(): {
+        armed: boolean;
+        consumed: boolean;
+    };
+};

package/dist/src/one_shot_guard.js

@@ -0,0 +1,143 @@
+/**
+ * cpX x402 Pay: bounded, single-signature guard for a supervised XRPL purchase.
+ * NO wallet keys, network requests, or transaction submission in this module.
+ * The guarded signer may only sign one validated Payment for one selected x402 offer.
+ */
+import { compareAmount } from './policy.js';
+const INT = /^(0|[1-9][0-9]*)$/;
+const ALLOWED_TX_FIELDS = new Set([
+    'TransactionType', 'Account', 'Destination', 'DestinationTag', 'SourceTag',
+    'Amount', 'DeliverMax', 'SendMax', 'Fee', 'Flags', 'Sequence',
+    'LastLedgerSequence', 'InvoiceID', 'NetworkID' // xrpl.js may add an undefined property on mainnet.
+]);
+function requireCondition(condition, error) {
+    if (!condition)
+        throw new Error(error);
+}
+function isUint32(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+function validUnsignedDrops(value) {
+    return typeof value === 'string' && value.length <= 18 && INT.test(value);
+}
+function validIssued(value, asset, issuer) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const x = value;
+    return Object.keys(x).sort().join(',') === 'currency,issuer,value' &&
+        x.currency === asset && x.issuer === issuer && typeof x.value === 'string';
+}
+async function invoiceHash(invoice) {
+    const input = new TextEncoder().encode(invoice);
+    const digest = await crypto.subtle.digest('SHA-256', input);
+    return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+export function createOneShotXrplSigner(original, options) {
+    requireCondition(typeof original?.classicAddress === 'string' && original.classicAddress.startsWith('r'), 'CPX_INVALID_SIGNER');
+    requireCondition(validUnsignedDrops(options.maxFeeDrops) && BigInt(options.maxFeeDrops) > 0n, 'CPX_INVALID_FEE_CAP');
+    requireCondition(options.recipient.length > 0 && options.asset.length > 0, 'CPX_INVALID_GUARD');
+    requireCondition(typeof options.getValidatedLedgerIndex === 'function', 'CPX_LEDGER_CHECK_REQUIRED');
+    const unit = options.asset === 'XRP' ? 'drops' : 'token';
+    requireCondition(compareAmount(options.exactAmount, '0', unit) === 1, 'CPX_INVALID_AMOUNT');
+    if (unit === 'token') {
+        requireCondition(typeof options.issuer === 'string' && !!options.issuer, 'CPX_ISSUER_REQUIRED');
+        requireCondition(typeof options.maxSendMax === 'string' && compareAmount(options.maxSendMax, options.exactAmount, 'token') !== null && compareAmount(options.maxSendMax, options.exactAmount, 'token') >= 0, 'CPX_INVALID_SENDMAX_CAP');
+    }
+    else {
+        requireCondition(options.issuer === undefined && options.maxSendMax === undefined, 'CPX_UNEXPECTED_XRP_FIELDS');
+    }
+    let armed;
+    let started = false;
+    let consumed = false;
+    return {
+        signer: {
+            classicAddress: original.classicAddress,
+            async sign(tx) {
+                requireCondition(armed !== undefined && !started && !consumed, 'CPX_SIGNING_NOT_AUTHORIZED');
+                started = true; // BEFORE awaiting anything: racing sign() requests fail closed.
+                consumed = true; // No automatic second signing, even after failure.
+                const offer = armed;
+                requireCondition(tx && typeof tx === 'object' && !Array.isArray(tx), 'CPX_INVALID_TRANSACTION');
+                const fields = tx;
+                requireCondition(Object.keys(fields).every(k => ALLOWED_TX_FIELDS.has(k)), 'CPX_UNKNOWN_TRANSACTION_FIELD');
+                requireCondition(fields.TransactionType === 'Payment', 'CPX_PAYMENT_ONLY');
+                requireCondition(fields.Account === original.classicAddress, 'CPX_WRONG_PAYER');
+                requireCondition(fields.Destination === offer.recipient, 'CPX_WRONG_DESTINATION');
+                requireCondition(fields.DestinationTag === offer.destinationTag, 'CPX_WRONG_DESTINATION_TAG');
+                requireCondition(fields.SourceTag === undefined || offer.sourceTag !== undefined, 'CPX_UNKNOWN_TRANSACTION_FIELD');
+                requireCondition(fields.SourceTag === undefined || fields.SourceTag === offer.sourceTag, 'CPX_WRONG_SOURCE_TAG');
+                requireCondition(typeof fields.InvoiceID === 'string' && fields.InvoiceID.toUpperCase() === offer.invoiceID, 'CPX_WRONG_INVOICE');
+                // XRPL mainnet (xrpl:0) requires NetworkID to be absent from the SIGNED transaction.
+                // Official xrpl.js autofill may supply a JavaScript own-property with value undefined.
+                // Accept that placeholder only; never accept a concrete NetworkID (including zero).
+                requireCondition(fields.NetworkID === undefined, 'CPX_MAINNET_NETWORK_ID_FORBIDDEN');
+                requireCondition(!('Paths' in fields) && !('DeliverMin' in fields) && !('Delegate' in fields) && !('Memos' in fields), 'CPX_FORBIDDEN_TRANSACTION_FIELD');
+                requireCondition(fields.Flags === undefined || fields.Flags === 0 || fields.Flags === 0x80000000, 'CPX_FORBIDDEN_FLAGS');
+                requireCondition(validUnsignedDrops(fields.Fee) && BigInt(fields.Fee) > 0n && BigInt(fields.Fee) <= BigInt(options.maxFeeDrops), 'CPX_FEE_EXCEEDS_LIMIT');
+                requireCondition(isUint32(fields.Sequence) && fields.Sequence > 0 && !('TicketSequence' in fields), 'CPX_SEQUENCE_ONLY');
+                requireCondition(isUint32(fields.LastLedgerSequence) && fields.LastLedgerSequence > 0, 'CPX_EXPIRY_REQUIRED');
+                const ledger = await options.getValidatedLedgerIndex();
+                requireCondition(isUint32(ledger) && ledger > 0, 'CPX_LEDGER_CHECK_FAILED');
+                const maxLedgerDelta = Math.ceil(offer.timeout / 5) + 2;
+                requireCondition(fields.LastLedgerSequence > ledger && fields.LastLedgerSequence <= ledger + maxLedgerDelta, 'CPX_EXPIRY_OUT_OF_RANGE');
+                requireCondition(('Amount' in fields) !== ('DeliverMax' in fields), 'CPX_EXACTLY_ONE_DELIVERY_FIELD');
+                const destAmount = fields.DeliverMax ?? fields.Amount;
+                if (offer.asset === 'XRP') {
+                    requireCondition(validUnsignedDrops(destAmount) && compareAmount(destAmount, offer.amount, 'drops') === 0, 'CPX_WRONG_XRP_AMOUNT');
+                    requireCondition(!('SendMax' in fields), 'CPX_XRP_SENDMAX_FORBIDDEN');
+                }
+                else {
+                    requireCondition(validIssued(destAmount, offer.asset, offer.issuer) && compareAmount(destAmount.value, offer.amount, 'token') === 0, 'CPX_WRONG_ISSUED_AMOUNT');
+                    requireCondition(validIssued(fields.SendMax, offer.asset, offer.issuer), 'CPX_INVALID_SENDMAX');
+                    const sendMax = fields.SendMax.value;
+                    requireCondition(compareAmount(sendMax, offer.amount, 'token') !== null && compareAmount(sendMax, offer.amount, 'token') >= 0, 'CPX_SENDMAX_BELOW_DELIVERY');
+                    requireCondition(compareAmount(sendMax, options.maxSendMax, 'token') !== null && compareAmount(sendMax, options.maxSendMax, 'token') <= 0, 'CPX_SENDMAX_EXCEEDS_LIMIT');
+                }
+                // Normalize ONLY the undefined placeholder, removing it before the wallet signs.
+                // This does not add/change a network ID or construct an XRPL transaction.
+                if (Object.prototype.hasOwnProperty.call(fields, 'NetworkID') || offer.sourceTag !== undefined) {
+                    const normalized = { ...fields };
+                    if (Object.prototype.hasOwnProperty.call(normalized, 'NetworkID'))
+                        delete normalized.NetworkID;
+                    if (normalized.DestinationTag === undefined)
+                        delete normalized.DestinationTag;
+                    if (normalized.SourceTag === undefined)
+                        delete normalized.SourceTag;
+                    if (offer.sourceTag !== undefined)
+                        normalized.SourceTag = offer.sourceTag;
+                    return await original.sign(normalized);
+                }
+                return await original.sign(tx);
+            }
+        },
+        /** Arms the guard for exactly one challenge AFTER x402 policy and human approval. */
+        async arm(req) {
+            requireCondition(!started && !consumed && !armed, 'CPX_ALREADY_ARMED');
+            started = true; // Reserve immediately; asynchronous hash may yield.
+            try {
+                requireCondition(req.network === 'xrpl:0' && req.scheme === 'exact' &&
+                    (req.extra?.areFeesSponsored === false ||
+                        (options.legacyT54Offer === true && req.extra?.areFeesSponsored === undefined)), 'CPX_NOT_XRPL_EXACT');
+                requireCondition(req.payTo === options.recipient && req.asset === options.asset && req.amount === options.exactAmount, 'CPX_OFFER_MISMATCH');
+                requireCondition(req.extra?.issuer === options.issuer, 'CPX_OFFER_ISSUER_MISMATCH');
+                requireCondition(req.extra?.assetTransferMethod === undefined || req.extra.assetTransferMethod === 'sequence', 'CPX_TICKETS_NOT_SUPPORTED');
+                requireCondition(isUint32(req.extra?.destinationTag) ||
+                    (options.legacyT54Offer === true && req.extra?.destinationTag === undefined), 'CPX_DESTINATION_TAG_REQUIRED');
+                requireCondition(req.extra?.sourceTag === undefined ||
+                    (options.legacyT54Offer === true && isUint32(req.extra.sourceTag)), 'CPX_SOURCE_TAG_INVALID');
+                requireCondition(typeof req.extra?.invoiceId === 'string' && req.extra.invoiceId.length > 0 && req.extra.invoiceId.length <= 256, 'CPX_INVOICE_REQUIRED');
+                requireCondition(typeof req.maxTimeoutSeconds === 'number' && Number.isInteger(req.maxTimeoutSeconds) && req.maxTimeoutSeconds > 0 && req.maxTimeoutSeconds <= (options.legacyT54Offer === true ? 600 : 120), 'CPX_TIMEOUT_INVALID');
+                const id = await invoiceHash(req.extra.invoiceId);
+                armed = { recipient: req.payTo,
+                    ...(req.extra?.destinationTag === undefined ? {} : { destinationTag: req.extra.destinationTag }),
+                    ...(req.extra?.sourceTag === undefined ? {} : { sourceTag: req.extra.sourceTag }),
+                    invoiceID: id,
+                    asset: req.asset, issuer: req.extra.issuer, amount: req.amount, timeout: req.maxTimeoutSeconds };
+            }
+            finally {
+                started = false;
+            }
+        },
+        getStatus() { return { armed: !!armed, consumed }; }
+    };
+}

package/dist/src/policy.d.ts

@@ -0,0 +1,74 @@
+/**
+ * cpX x402 Pay — self-funded agent policy gate.
+ * No account, Supabase, Cloudflare, Xaman, or private keys are required here.
+ * NOTE: XRP x402 amounts are DROPS. XRPL-issued tokens use decimal token values.
+ */
+export type XrplAsset = {
+    kind: 'xrp';
+    asset: 'XRP';
+    maxAmountDrops: string;
+} | {
+    kind: 'issued';
+    asset: string;
+    issuer: string;
+    maxAmount: string;
+};
+export type X402Requirements = {
+    network: string;
+    scheme: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    extra?: {
+        issuer?: string;
+        areFeesSponsored?: unknown;
+        assetTransferMethod?: string;
+        [name: string]: unknown;
+    };
+};
+export type PaymentChallenge = {
+    paymentRequired: {
+        x402Version?: number;
+    };
+    selectedRequirements: X402Requirements;
+};
+export type PaymentIntent = {
+    network: 'xrpl:0';
+    asset: string;
+    amount: string;
+    amountUnit: 'drops' | 'token';
+    issuer?: string;
+    recipient: string;
+};
+export type AgentPaymentConfig = {
+    /** Required positive caps; no implicit unlimited spending. */
+    assets: readonly XrplAsset[];
+    /** Explicitly choose permissionless destinations or an allowlist. */
+    recipients: {
+        mode: 'any';
+    } | {
+        mode: 'allowlist';
+        addresses: readonly string[];
+    };
+    /** Autonomous approval must be explicitly selected by the agent operator. */
+    /** Opt-in support for live t54-oriented challenges omitting areFeesSponsored. */
+    legacyT54Offer?: boolean;
+    approval: {
+        mode: 'autonomous';
+    } | {
+        mode: 'callback';
+        authorize: (intent: PaymentIntent) => Promise<boolean>;
+    };
+};
+export type GateResult = {
+    allowed: true;
+    intent: PaymentIntent;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Compare nonnegative decimal strings without Number / float rounding. */
+export declare function compareAmount(a: string, b: string, units: 'drops' | 'token'): number | null;
+export declare function createAgentPaymentGate(config: AgentPaymentConfig): {
+    evaluate(challenge: PaymentChallenge): Promise<GateResult>;
+};