@cloudpayx/x402-pay 0.0.0-stage → 0.2.2

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# cpX x402 Pay | XRPL Agent Payment SDK
 
-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 an XRPL-native SDK for autonomous agents purchasing x402-protected resources.
+
+The SDK supports wallet-agnostic signing, three-asset payment policies, spending controls, guarded signing, and validated-ledger reconciliation. Agents must use compatible XRPL signers and maintain sufficient funds.
+
+## 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.
+- **Security protections:** Spending budgets, duplicate-payment protection, resource-host validation, anti-SSRF controls, replay protection, fee budgeting, guarded signing, and validated-ledger reconciliation are covered by the SDK's security tests. These controls apply when payments use the guarded SDK interface.
+- 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.
+
+XRPL-issued assets require sufficient balances, applicable trustlines, and XRP for fees and reserves. Payment success and resource delivery depend on the network and seller. An agent with unrestricted access to its own signing keys can bypass local SDK policies.
+
+**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).
+
+## Integration guidance
+
+Use a dedicated, limited-balance XRPL wallet when integrating a new signer or seller. Validate the complete payment and resource-delivery flow before granting unattended spending authority. For stronger enforcement, keep signing authority outside the agent's direct control.
+
+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>;
+};