agentwallet-mcp 1.10.1 → 1.10.3

package/README.md

@@ -41,7 +41,9 @@ Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key
 
 `AGENTWALLET_RPC_<chainId>` (or `AGENTWALLET_RPC_URL` for all chains) points at an endpoint you trust. Without it a public RPC is used, and a public RPC can see which addresses you ask about.
 
-`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units. In hosted mode the server enforces limits; in local mode there is no server, so this guard is the only one there is. Set it.
+`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units (ETH, MATIC and so on). In hosted mode the server enforces limits; in local mode there is no server, so these guards are the only ones there are. Set them.
+
+`AGENTWALLET_MAX_TX_TOKEN` is the equivalent ceiling for ERC-20 movement, in human units of the token. **Set this one too if you hold stablecoins.** The native cap cannot see a token transfer: an ERC-20 send carries `value = 0` with the amount in the calldata, so `AGENTWALLET_MAX_TX_NATIVE` alone leaves a USDC balance uncapped. `AGENTWALLET_MAX_TX_TOKEN` covers `transfer`, `transferFrom` and `approve`, the last because an unbounded allowance is a drain waiting to happen. Decimals are resolved locally; unknown tokens are evaluated at 6 decimals, the tightest common value, so it fails closed rather than open.
 
 ### Solana local signing
 

package/build/index.js

@@ -13,7 +13,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { assertPublicUrl, safeFetch } from './ssrf-guard.js';
-import { deriveX402Payment, isWithinCap } from './x402-payment.js';
+import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, } from './x402-payment.js';
 import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
 import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, } from './local-solana.js';
 /** True when either chain family is running non-custodially. */
@@ -187,6 +187,53 @@ async function api(path, method = 'GET', body, extraHeaders) {
     }
     return data;
 }
+/**
+ * Resolve an asset's decimals from a source the paying party controls, never
+ * from the 402 response.
+ *
+ * Order: known-asset registry first (offline, works in local self-custody mode
+ * where there may be no reachable API), then the token contract's own
+ * decimals() via eth_call. If neither answers we refuse rather than guess,
+ * because guessing is exactly what let a hostile endpoint inflate the cap.
+ */
+const decimalsCache = new Map();
+async function resolveTrustedDecimals(chainId, token) {
+    const key = `${chainId}:${token.toLowerCase()}`;
+    const cached = decimalsCache.get(key);
+    if (typeof cached === 'number')
+        return cached;
+    const known = lookupTrustedDecimals(chainId, token);
+    if (known !== null) {
+        decimalsCache.set(key, known);
+        return known;
+    }
+    if (isSolanaChain(chainId)) {
+        throw new Error(`x402 blocked: cannot verify decimals for SPL mint ${token} on chain ${chainId}. ` +
+            `Unknown mints are refused because the payment cap cannot be checked without trusted decimals.`);
+    }
+    // decimals() selector
+    let onChain = null;
+    try {
+        const r = (await api('/eth-call', 'POST', {
+            chain_id: chainId, to: token, data: '0x313ce567',
+        }, { 'X-AGW-SKIP-X402': 'true' }));
+        const hex = (r?.result || '').replace(/^0x/, '');
+        if (hex && /^[0-9a-fA-F]+$/.test(hex)) {
+            const n = parseInt(hex, 16);
+            if (Number.isInteger(n) && n >= 0 && n <= 36)
+                onChain = n;
+        }
+    }
+    catch {
+        onChain = null; // fall through to the refusal below
+    }
+    if (onChain === null) {
+        throw new Error(`x402 blocked: could not resolve on-chain decimals for ${token} on chain ${chainId}. ` +
+            `The payment cap cannot be enforced without them, so the payment was refused.`);
+    }
+    decimalsCache.set(key, onChain);
+    return onChain;
+}
 /**
  * Handle x402 auto-payment: pay on-chain, then retry the original request
  */
@@ -208,7 +255,11 @@ async function handleX402Payment(x402Data, originalPath, originalMethod, origina
     // 402 response cannot drain the wallet. AGENTWALLET_MAX_AUTOPAY is in
     // human-readable units of the asset; default 1.
     const maxAutopay = process.env.AGENTWALLET_MAX_AUTOPAY || '1';
-    const { tokenAddress, rawAmount, decimals } = deriveX402Payment(accept, maxAutopay);
+    const assetForDecimals = accept.asset || accept.extra?.token || '';
+    const trustedDecimals = assetForDecimals
+        ? await resolveTrustedDecimals(chainId, assetForDecimals)
+        : 18; // native asset: value is already in wei-equivalent base units
+    const { tokenAddress, rawAmount, decimals } = deriveX402Payment(accept, maxAutopay, trustedDecimals);
     // Send payment using our wallet (with X-AGW-SKIP-X402 to prevent recursion)
     let txHash;
     try {
@@ -359,6 +410,18 @@ function resolveChainId(network) {
     return null;
 }
 // ─── Server ──────────────────────────────────────────────────────
+/**
+ * Destination address shape, EVM or Solana.
+ *
+ * The contract-address params were regex-guarded but the DESTINATION on every
+ * transfer tool was a bare z.string(), so a truncated or mistyped address went
+ * straight into a signed transaction. On-chain sends are irreversible, and the
+ * chain will happily accept any well-formed address, so the cheapest place to
+ * catch a malformed one is before it is signed. This does not validate the
+ * EIP-55 checksum, only the shape; a wrong-but-well-formed address is still the
+ * caller's responsibility.
+ */
+const AddressSchema = z.string().regex(/^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/, 'Must be a 0x-prefixed 40-hex EVM address or a base58 Solana address');
 const server = new McpServer({
     name: 'agentwallet',
     version: '1.10.1',
@@ -477,7 +540,7 @@ server.tool('sign_transaction', 'Sign a transaction with a wallet\'s private key
     'For EVM: returns signed raw transaction hex. For Solana: returns base64 signed transaction. ' +
     'Does NOT broadcast — use send_transaction for sign + broadcast.', {
     wallet_id: z.number().int().describe('Wallet ID'),
-    to: z.string().describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
+    to: AddressSchema.describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
     chain_id: z.number().int().optional().describe('Chain ID (defaults to wallet\'s default)'),
     value: z.string().default('0').describe('Value in wei/lamports (decimal string)'),
     data: z.string().default('').describe('Hex-encoded calldata (0x-prefixed) for EVM contract calls'),
@@ -519,7 +582,7 @@ server.tool('send_transaction', 'Sign and broadcast a transaction. ' +
     'Returns the transaction hash (EVM) or signature (Solana) on success. ' +
     'The transaction is signed server-side and broadcast via RPC.', {
     wallet_id: z.number().int().describe('Wallet ID'),
-    to: z.string().describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
+    to: AddressSchema.describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
     chain_id: z.number().int().optional().describe('Chain ID (defaults to wallet\'s default)'),
     value: z.string().default('0').describe('Value in wei/lamports (decimal string)'),
     data: z.string().default('').describe('Hex-encoded calldata (0x-prefixed) for EVM contract calls'),
@@ -561,7 +624,7 @@ server.tool('transfer', 'Send native tokens (ETH, AVAX, BNB, POL, PLS, SOL) to a
     'Specify the amount in human-readable format (e.g. "0.1" for 0.1 ETH). ' +
     'The amount is converted to wei/lamports automatically. Signs and broadcasts the transaction.', {
     wallet_id: z.number().int().describe('Wallet ID to send from'),
-    to: z.string().describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
+    to: AddressSchema.describe('Destination address (0x-prefixed for EVM, Base58 for Solana)'),
     amount: z.string().describe('Amount to send in human-readable format (e.g. "0.1" for 0.1 ETH)'),
     chain_id: z.number().int().describe('Chain ID (1=Ethereum, 8453=Base, 42161=Arbitrum, 10=Optimism, 137=Polygon, 43114=Avalanche, 56=BSC, 7777777=Zora, 369=PulseChain, 900=Solana, 901=Solana Devnet)'),
 }, async ({ wallet_id, to, amount, chain_id }) => {
@@ -624,7 +687,7 @@ server.tool('transfer_token', 'Send ERC-20 tokens (EVM) or SPL tokens (Solana) t
     'Signs and broadcasts the transaction. Use get_chains to find stablecoin addresses.', {
     wallet_id: z.number().int().describe('Wallet ID to send from'),
     token: z.string().describe('Token address (0x-prefixed ERC-20 contract for EVM, Base58 mint for Solana)'),
-    to: z.string().describe('Recipient address (0x-prefixed for EVM, Base58 for Solana)'),
+    to: AddressSchema.describe('Recipient address (0x-prefixed for EVM, Base58 for Solana)'),
     amount: z.string().describe('Amount in human-readable format (e.g. "100" for 100 USDC)'),
     chain_id: z.number().int().describe('Chain ID'),
     decimals: z.number().int().default(18).describe('Token decimals (6 for USDC, 18 for most tokens)'),
@@ -958,8 +1021,18 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         throw new Error(`Unsupported x402 network: "${option.network}". ` +
             `Supported: ${Object.keys(X402_NETWORKS).join(', ')}, or any CAIP-2 / numeric chain ID.`);
     }
-    // Calculate human-readable amount
-    const amount = formatUnits(option.maxAmountRequired, option.requiredDecimals);
+    // Decimals come from the registry or the token contract, NEVER from the 402
+    // body. The endpoint controls requiredDecimals, so trusting it lets a
+    // hostile server inflate the cap AND misreport the amount shown to the
+    // agent. The declared value is only used to detect a mismatch and refuse.
+    const assetForDecimals = option.asset || option.extra?.token || '';
+    const trustedDecimals = assetForDecimals
+        ? await resolveTrustedDecimals(chainId, assetForDecimals)
+        : 18;
+    assertDeclaredDecimals(option.requiredDecimals, trustedDecimals);
+    // Human-readable amount, computed with trusted decimals so what the agent
+    // is told matches what will actually leave the wallet.
+    const amount = formatUnits(option.maxAmountRequired, trustedDecimals);
     // Step 4: Enforce a hard per-payment cap. ALWAYS applied — if the caller
     // omits max_payment we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"),
     // mirroring the internal auto-pay path (deriveX402Payment). Without this, an
@@ -967,7 +1040,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     // maxAmountRequired and drain the wallet. The cap is never silently skipped.
     const capSource = max_payment ? 'max_payment' : 'AGENTWALLET_MAX_AUTOPAY';
     const effectiveMax = max_payment || process.env.AGENTWALLET_MAX_AUTOPAY || '1';
-    if (!isWithinCap(option.maxAmountRequired, option.requiredDecimals, effectiveMax)) {
+    if (!isWithinCap(option.maxAmountRequired, trustedDecimals, effectiveMax)) {
         return jsonResponse({
             status: 402,
             payment_required: true,
@@ -999,7 +1072,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
                 to: option.payTo,
                 value: option.maxAmountRequired,
                 token_mint: tokenAddress,
-                token_decimals: option.requiredDecimals,
+                token_decimals: trustedDecimals,
                 chain_id: chainId,
             }));
         }

package/build/local-solana.js

@@ -14,6 +14,7 @@
 import { readFileSync } from 'node:fs';
 import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, LAMPORTS_PER_SOL, } from '@solana/web3.js';
 import bs58 from 'bs58';
+import { lookupTrustedDecimals } from './x402-payment.js';
 /* ── Program IDs ─────────────────────────────────────────────────── */
 const TOKEN_PROGRAM = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
 const TOKEN_2022_PROGRAM = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb');
@@ -114,6 +115,34 @@ function assertWithinSolCap(lamports) {
         throw new Error(`Blocked by local guard: amount exceeds AGENTWALLET_MAX_TX_SOL (${cap} SOL).`);
     }
 }
+/**
+ * Bound SPL movement. AGENTWALLET_MAX_TX_SOL only ever covered native SOL, so
+ * an SPL transfer, which is how USDC moves on Solana and the whole point of the
+ * x402 rail here, went out with no local ceiling at all. Mirrors
+ * AGENTWALLET_MAX_TX_TOKEN on the EVM side and uses the same variable so an
+ * operator sets one token cap, not one per chain family.
+ *
+ * Decimals for the cap come from the trusted table when the mint is known.
+ * The caller-supplied value is not used for the ceiling: an inflated one would
+ * inflate the cap exactly like the x402 bypass. When the mint is unknown we
+ * assume 6, the tightest common value, so it fails closed.
+ */
+function assertWithinSplCap(mint, rawAmount) {
+    const cap = (process.env.AGENTWALLET_MAX_TX_TOKEN || '').trim();
+    if (!cap)
+        return;
+    if (!/^\d+(\.\d+)?$/.test(cap)) {
+        throw new Error(`AGENTWALLET_MAX_TX_TOKEN must be a decimal number, got "${cap}".`);
+    }
+    const decimals = lookupTrustedDecimals(900, mint) ?? 6;
+    const [whole, frac = ''] = cap.split('.');
+    const capRaw = BigInt(whole + frac.padEnd(decimals, '0').slice(0, decimals));
+    if (rawAmount > capRaw) {
+        throw new Error(`Blocked by local guard: SPL transfer of ${rawAmount} base units exceeds ` +
+            `AGENTWALLET_MAX_TX_TOKEN (${cap}, evaluated at ${decimals} decimals). ` +
+            `Raise the cap deliberately if this is intended.`);
+    }
+}
 /* ── Reads ───────────────────────────────────────────────────────── */
 export async function localSolBalance(chainId = 900) {
     const conn = connection(chainId);
@@ -161,6 +190,11 @@ export async function localSplBalance(mintStr, chainId = 900) {
 export async function localSolTransfer(to, lamports, chainId = 900) {
     const amount = BigInt(lamports);
     assertWithinSolCap(amount);
+    // Number() silently loses precision past 2**53 lamports. Refuse rather than
+    // sign a transaction for an amount other than the one that was requested.
+    if (amount > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`Amount ${lamports} lamports exceeds safe integer range and was refused.`);
+    }
     const conn = connection(chainId);
     const payer = getSolanaKeypair();
     const tx = new Transaction().add(SystemProgram.transfer({
@@ -216,6 +250,9 @@ function createAtaIdempotentIx(payer, ata, owner, mint, tokenProgram) {
  * not exist, using the idempotent instruction so a race cannot fail the send.
  */
 export async function localSplTransfer(mintStr, to, rawAmount, decimals, chainId = 900) {
+    // Checked before any RPC round trip: a blocked transfer should cost nothing
+    // and should not announce itself to the RPC provider first.
+    assertWithinSplCap(mintStr, BigInt(rawAmount));
     const conn = connection(chainId);
     const payer = getSolanaKeypair();
     const mint = new PublicKey(mintStr);

package/build/local-wallet.d.ts

@@ -64,10 +64,6 @@ export interface LocalSendResult {
     mode: 'local';
     signed_locally: true;
 }
-/**
- * Sign and broadcast a transaction. viem fills nonce, gas and EIP-1559 fees
- * from the RPC unless they are supplied.
- */
 export declare function localSend(chainId: number, to: Address, valueWei: bigint, data?: Hex): Promise<LocalSendResult>;
 /** ERC-20 transfer, encoded locally. */
 export declare function localTransferToken(chainId: number, token: Address, to: Address, rawAmount: string): Promise<LocalSendResult>;

package/build/local-wallet.js

@@ -17,6 +17,7 @@
 import { readFileSync } from 'node:fs';
 import { createPublicClient, createWalletClient, http, encodeFunctionData, parseAbi, formatUnits, } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
+import { lookupTrustedDecimals } from './x402-payment.js';
 /* ── Key loading ─────────────────────────────────────────────────── */
 /**
  * Read the key once at startup. Kept module-private: nothing exports the key
@@ -166,8 +167,53 @@ export async function localTokenBalance(chainId, token) {
  * Sign and broadcast a transaction. viem fills nonce, gas and EIP-1559 fees
  * from the RPC unless they are supplied.
  */
+/**
+ * Bound ERC-20 movement, which the native cap does not see.
+ *
+ * A token transfer is `to = tokenContract, value = 0, data = transfer(...)`, so
+ * assertWithinNativeCap always passed it. In local mode there is no server-side
+ * limit behind this, and the README tells operators the local guard is the only
+ * one they have, so a wallet holding USDC was effectively uncapped. Covers
+ * transfer, transferFrom and approve, since an unbounded approval is a drain
+ * waiting to happen.
+ *
+ * Opt-in via AGENTWALLET_MAX_TX_TOKEN, expressed in human units of the token.
+ * When the token's decimals are not known locally we assume 6, the smallest in
+ * common use, which makes the raw ceiling the tightest one and fails closed
+ * rather than open.
+ */
+function assertWithinTokenCap(chainId, token, data) {
+    const cap = (process.env.AGENTWALLET_MAX_TX_TOKEN || '').trim();
+    if (!cap)
+        return;
+    if (!/^\d+(\.\d+)?$/.test(cap)) {
+        throw new Error(`AGENTWALLET_MAX_TX_TOKEN must be a decimal number, got "${cap}".`);
+    }
+    const hex = data.slice(2);
+    const selector = hex.slice(0, 8).toLowerCase();
+    // transfer(address,uint256) | approve(address,uint256) | transferFrom(address,address,uint256)
+    const layouts = { a9059cbb: 1, '095ea7b3': 1, '23b872dd': 2 };
+    const argIndex = layouts[selector];
+    if (argIndex === undefined)
+        return; // not a value-moving ERC-20 call
+    const word = hex.slice(8 + argIndex * 64, 8 + (argIndex + 1) * 64);
+    if (word.length !== 64)
+        return; // malformed; leave it to the node to reject
+    const amount = BigInt('0x' + word);
+    const decimals = lookupTrustedDecimals(chainId, token) ?? 6;
+    const [whole, frac = ''] = cap.split('.');
+    const capRaw = BigInt(whole + frac.padEnd(decimals, '0').slice(0, decimals));
+    if (amount > capRaw) {
+        const what = selector === '095ea7b3' ? 'approval' : 'token transfer';
+        throw new Error(`Blocked by local guard: ${what} of ${amount} base units exceeds ` +
+            `AGENTWALLET_MAX_TX_TOKEN (${cap}, evaluated at ${decimals} decimals). ` +
+            `Raise the cap deliberately if this is intended.`);
+    }
+}
 export async function localSend(chainId, to, valueWei, data) {
     assertWithinNativeCap(valueWei);
+    if (data && data.length >= 10)
+        assertWithinTokenCap(chainId, to, data);
     const { wallet } = clients(chainId);
     const hash = await wallet.sendTransaction({
         to,

package/build/x402-payment.d.ts

@@ -3,6 +3,16 @@
  *
  * Isolated from the server bootstrap in index.ts so the funds-sensitive amount
  * math can be unit-tested without starting the MCP server.
+ *
+ * SECURITY INVARIANT: token decimals must NEVER come from the 402 response.
+ * A resource server controls `asset`, `payTo`, `maxAmountRequired` AND
+ * `requiredDecimals`. If the cap is scaled using server-declared decimals, the
+ * server can inflate the cap arbitrarily: declaring 18 decimals for 6-decimal
+ * USDC turns a "1 USDC" cap into 10^18 base units, so a request for
+ * 1,000,000,000,000 units (1,000,000 USDC) passes a 1 USDC cap. Reported by
+ * ARC Security Research, 2026-08-02, against 1.10.1. Decimals are now resolved
+ * from a trusted source and the declared value is only ever used to detect a
+ * mismatch and refuse.
  */
 export interface X402AcceptLike {
     maxAmountRequired: string;
@@ -12,22 +22,48 @@ export interface X402AcceptLike {
         token?: string;
     };
 }
+/**
+ * Decimals for assets that x402 endpoints actually settle in, keyed by
+ * chain id then lowercased contract address (or SPL mint on Solana).
+ *
+ * This exists so the common path needs no network call, and so local
+ * self-custody mode (which may have no reachable API) can still verify a cap.
+ * It is intentionally small: every entry is a value that can be checked by
+ * hand. Anything not listed is resolved on-chain instead, and if that fails
+ * the payment is refused rather than guessed.
+ */
+export declare const TRUSTED_DECIMALS: Record<number, Record<string, number>>;
+/** Solana SPL mints, keyed by mint address (case-sensitive base58). */
+export declare const TRUSTED_SPL_DECIMALS: Record<string, number>;
+/**
+ * Look up decimals we already know to be correct. Returns null when the asset
+ * is unknown, which means the caller must resolve it on-chain or refuse.
+ */
+export declare function lookupTrustedDecimals(chainId: number, token: string): number | null;
+/**
+ * Guard the server's declared decimals against the trusted value.
+ *
+ * A mismatch is not a formatting quirk. It is the exact shape of the cap-bypass
+ * attack, so it fails closed and says so.
+ */
+export declare function assertDeclaredDecimals(declared: unknown, trusted: number): void;
 /**
  * Derive the on-chain transfer parameters from an x402 payment requirement.
  *
  * CRITICAL: x402 `maxAmountRequired` is ALREADY denominated in base/atomic
  * units (e.g. "10000" = 0.01 USDC at 6 decimals). It MUST be used directly.
  * Running it through parseUnits() re-scales it by 10**decimals and overpays by
- * that factor (1,000,000x for USDC). This mirrors the pay_x402 tool, which has
- * always used maxAmountRequired directly.
+ * that factor (1,000,000x for USDC).
  *
- * Also enforces a hard ceiling so a malformed or malicious 402 response can
- * never authorize a transfer larger than `maxAutopayHuman` units of the asset.
+ * Enforces a hard ceiling so a malformed or malicious 402 response can never
+ * authorize a transfer larger than `maxAutopayHuman` units of the asset.
  *
  * @param accept           the chosen x402 accept option
  * @param maxAutopayHuman  max auto-pay, in human-readable units of the asset
+ * @param trustedDecimals  decimals resolved from a registry or the token
+ *                         contract. MUST NOT be taken from the 402 response.
  */
-export declare function deriveX402Payment(accept: X402AcceptLike, maxAutopayHuman: string): {
+export declare function deriveX402Payment(accept: X402AcceptLike, maxAutopayHuman: string, trustedDecimals: number): {
     tokenAddress: string;
     rawAmount: string;
     decimals: number;
@@ -42,7 +78,7 @@ export declare function deriveX402Payment(accept: X402AcceptLike, maxAutopayHuma
  * can return a structured rejection to the calling agent.
  *
  * @param rawAmountRequired x402 maxAmountRequired, already in base units
- * @param decimals          token decimals
+ * @param trustedDecimals   token decimals from a trusted source, NOT the 402 body
  * @param capHuman          cap in human-readable units of the asset (e.g. "1")
  */
-export declare function isWithinCap(rawAmountRequired: string, decimals: number, capHuman: string): boolean;
+export declare function isWithinCap(rawAmountRequired: string, trustedDecimals: number, capHuman: string): boolean;

package/build/x402-payment.js

@@ -3,12 +3,100 @@
  *
  * Isolated from the server bootstrap in index.ts so the funds-sensitive amount
  * math can be unit-tested without starting the MCP server.
+ *
+ * SECURITY INVARIANT: token decimals must NEVER come from the 402 response.
+ * A resource server controls `asset`, `payTo`, `maxAmountRequired` AND
+ * `requiredDecimals`. If the cap is scaled using server-declared decimals, the
+ * server can inflate the cap arbitrarily: declaring 18 decimals for 6-decimal
+ * USDC turns a "1 USDC" cap into 10^18 base units, so a request for
+ * 1,000,000,000,000 units (1,000,000 USDC) passes a 1 USDC cap. Reported by
+ * ARC Security Research, 2026-08-02, against 1.10.1. Decimals are now resolved
+ * from a trusted source and the declared value is only ever used to detect a
+ * mismatch and refuse.
+ */
+/**
+ * Decimals for assets that x402 endpoints actually settle in, keyed by
+ * chain id then lowercased contract address (or SPL mint on Solana).
+ *
+ * This exists so the common path needs no network call, and so local
+ * self-custody mode (which may have no reachable API) can still verify a cap.
+ * It is intentionally small: every entry is a value that can be checked by
+ * hand. Anything not listed is resolved on-chain instead, and if that fails
+ * the payment is refused rather than guessed.
+ */
+export const TRUSTED_DECIMALS = {
+    // Ethereum
+    1: {
+        '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': 6, // USDC
+        '0xdac17f958d2ee523a2206206994597c13d831ec7': 6, // USDT
+        '0x6b175474e89094c44da98b954eedeac495271d0f': 18, // DAI
+    },
+    // Base
+    8453: {
+        '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 6, // USDC
+        '0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca': 6, // USDbC
+        '0x4200000000000000000000000000000000000006': 18, // WETH
+    },
+    // Polygon
+    137: {
+        '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': 6, // USDC (native)
+        '0xc2132d05d31c914a87c6611c10748aeb04b58e8f': 6, // USDT
+    },
+    // Arbitrum One
+    42161: {
+        '0xaf88d065e77c8cc2239327c5edb3a432268e5831': 6, // USDC
+    },
+    // Optimism
+    10: {
+        '0x0b2c639c533813f4aa9d7837caf62653d097ff85': 6, // USDC
+    },
+};
+/** Solana SPL mints, keyed by mint address (case-sensitive base58). */
+export const TRUSTED_SPL_DECIMALS = {
+    EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: 6, // USDC
+    Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB: 6, // USDT
+};
+/**
+ * Look up decimals we already know to be correct. Returns null when the asset
+ * is unknown, which means the caller must resolve it on-chain or refuse.
+ */
+export function lookupTrustedDecimals(chainId, token) {
+    if (!token)
+        return null;
+    const spl = TRUSTED_SPL_DECIMALS[token];
+    if (typeof spl === 'number')
+        return spl;
+    const forChain = TRUSTED_DECIMALS[chainId];
+    if (!forChain)
+        return null;
+    const d = forChain[token.toLowerCase()];
+    return typeof d === 'number' ? d : null;
+}
+/**
+ * Guard the server's declared decimals against the trusted value.
+ *
+ * A mismatch is not a formatting quirk. It is the exact shape of the cap-bypass
+ * attack, so it fails closed and says so.
  */
+export function assertDeclaredDecimals(declared, trusted) {
+    if (declared === undefined || declared === null)
+        return; // absent is fine, we use trusted
+    if (typeof declared !== 'number' || !Number.isInteger(declared) || declared < 0 || declared > 36) {
+        throw new Error(`x402: malformed requiredDecimals (${String(declared)}). Refusing to derive a payment amount.`);
+    }
+    if (declared !== trusted) {
+        throw new Error(`x402 blocked: the endpoint declared ${declared} decimals for this asset but its ` +
+            `on-chain value is ${trusted}. This is how a payment cap is bypassed, so the payment was refused.`);
+    }
+}
 /** Convert a human-readable decimal amount (e.g. "0.01") to base/atomic units. */
 function toBaseUnits(amount, decimals) {
     if (!/^\d+(\.\d+)?$/.test(amount)) {
         throw new Error(`Invalid amount "${amount}".`);
     }
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+        throw new Error(`Invalid decimals "${decimals}".`);
+    }
     const [whole, frac = ''] = amount.split('.');
     const fracPadded = frac.slice(0, decimals).padEnd(decimals, '0');
     return BigInt(whole + fracPadded).toString();
@@ -19,30 +107,31 @@ function toBaseUnits(amount, decimals) {
  * CRITICAL: x402 `maxAmountRequired` is ALREADY denominated in base/atomic
  * units (e.g. "10000" = 0.01 USDC at 6 decimals). It MUST be used directly.
  * Running it through parseUnits() re-scales it by 10**decimals and overpays by
- * that factor (1,000,000x for USDC). This mirrors the pay_x402 tool, which has
- * always used maxAmountRequired directly.
+ * that factor (1,000,000x for USDC).
  *
- * Also enforces a hard ceiling so a malformed or malicious 402 response can
- * never authorize a transfer larger than `maxAutopayHuman` units of the asset.
+ * Enforces a hard ceiling so a malformed or malicious 402 response can never
+ * authorize a transfer larger than `maxAutopayHuman` units of the asset.
  *
  * @param accept           the chosen x402 accept option
  * @param maxAutopayHuman  max auto-pay, in human-readable units of the asset
+ * @param trustedDecimals  decimals resolved from a registry or the token
+ *                         contract. MUST NOT be taken from the 402 response.
  */
-export function deriveX402Payment(accept, maxAutopayHuman) {
-    const decimals = accept.requiredDecimals || 6;
+export function deriveX402Payment(accept, maxAutopayHuman, trustedDecimals) {
     // Standard x402 uses `asset` for the token address; AgentWallet's own server
     // currently emits it under extra.token. Prefer the standard field, fall back.
     const tokenAddress = accept.asset || accept.extra?.token || '';
+    assertDeclaredDecimals(accept.requiredDecimals, trustedDecimals);
     const rawAmount = accept.maxAmountRequired;
     if (!/^\d+$/.test(rawAmount)) {
         throw new Error(`x402 auto-pay: invalid maxAmountRequired "${rawAmount}" (expected an integer base-unit amount).`);
     }
-    const capRaw = toBaseUnits(maxAutopayHuman, decimals);
+    const capRaw = toBaseUnits(maxAutopayHuman, trustedDecimals);
     if (BigInt(rawAmount) > BigInt(capRaw)) {
         throw new Error(`x402 auto-pay blocked: required amount (${rawAmount} base units) exceeds the ` +
             `AGENTWALLET_MAX_AUTOPAY cap of ${maxAutopayHuman}. Raise AGENTWALLET_MAX_AUTOPAY to allow it.`);
     }
-    return { tokenAddress, rawAmount, decimals };
+    return { tokenAddress, rawAmount, decimals: trustedDecimals };
 }
 /**
  * Returns true if an x402 required amount (already in base/atomic units) is
@@ -54,13 +143,13 @@ export function deriveX402Payment(accept, maxAutopayHuman) {
  * can return a structured rejection to the calling agent.
  *
  * @param rawAmountRequired x402 maxAmountRequired, already in base units
- * @param decimals          token decimals
+ * @param trustedDecimals   token decimals from a trusted source, NOT the 402 body
  * @param capHuman          cap in human-readable units of the asset (e.g. "1")
  */
-export function isWithinCap(rawAmountRequired, decimals, capHuman) {
+export function isWithinCap(rawAmountRequired, trustedDecimals, capHuman) {
     if (!/^\d+$/.test(rawAmountRequired)) {
         throw new Error(`Invalid maxAmountRequired "${rawAmountRequired}" (expected an integer base-unit amount).`);
     }
-    const capRaw = toBaseUnits(capHuman, decimals);
+    const capRaw = toBaseUnits(capHuman, trustedDecimals);
     return BigInt(rawAmountRequired) <= BigInt(capRaw);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
   "type": "module",
   "main": "build/index.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
-    "test": "node test/x402-payment.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs",
+    "test": "node test/x402-payment.test.mjs && node test/token-cap.test.mjs && node test/spl-cap.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [