agentwallet-mcp 1.10.0 → 1.10.2

package/build/index.js

@@ -12,7 +12,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { deriveX402Payment, isWithinCap } from './x402-payment.js';
+import { assertPublicUrl, safeFetch } from './ssrf-guard.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. */
@@ -186,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
  */
@@ -207,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 {
@@ -360,82 +412,82 @@ function resolveChainId(network) {
 // ─── Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.8.0',
+    version: '1.10.1',
 }, {
-    instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
-
-## Getting Started
-1. Call list_wallets to see existing wallets, or create_wallet to make a new one.
-2. Fund the wallet by sending tokens to its address from an external source.
-3. Use transfer (native tokens) or transfer_token (ERC-20/SPL tokens) to send funds.
-
-## Supported Chains
-- **EVM chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), Avalanche (43114), BSC (56), Zora (7777777), PulseChain (369)
-- **Solana:** Mainnet (900), Devnet (901)
-- Call get_chains for the full list with native tokens and stablecoin contract addresses.
-
-## EVM vs Solana
-- **Addresses:** EVM uses 0x-prefixed hex (42 chars). Solana uses Base58 (32-44 chars).
-- **Native tokens:** EVM = ETH/POL/BNB/etc (18 decimals, wei). Solana = SOL (9 decimals, lamports).
-- **Token standards:** EVM uses ERC-20. Solana uses SPL tokens.
-- **EVM-only tools:** approve_token, get_allowance, wrap_eth, unwrap_eth, call_contract, get_token_info. These do not work on Solana.
-- **Works on both:** create_wallet, transfer, transfer_token, send_transaction, sign_transaction, get_balance, get_token_balance.
-
-## Common Workflows
-
-### Send native tokens (ETH, SOL, etc.)
-Use the transfer tool with a human-readable amount (e.g. "0.1" ETH). It auto-converts to wei/lamports.
-
-### Send ERC-20 or SPL tokens
-Use transfer_token. You need: wallet_id, token contract address, recipient, amount, chain_id, and decimals (6 for USDC, 18 for most ERC-20s). Call get_chains to find stablecoin addresses.
-
-### Interact with DeFi (EVM only)
-1. Check allowance with get_allowance.
-2. If needed, call approve_token to let the DeFi contract spend your tokens.
-3. Use send_transaction with the contract's calldata to execute the interaction.
-
-### Wrap/unwrap native tokens (EVM only)
-Use wrap_eth to convert ETH → WETH (required by many DeFi protocols). Use unwrap_eth to convert back.
-
-### Read on-chain data (EVM only)
-Use call_contract for gas-free read-only calls (eth_call). Provide ABI-encoded calldata.
-
-## x402 Payments — Paying for Resources
-The pay_x402 tool handles the full x402 payment flow automatically:
-1. Fetches the URL.
-2. If the server returns HTTP 402, parses the payment requirements.
-3. Pays on-chain using your wallet.
-4. Retries the request with proof of payment.
-Always set max_payment to prevent overspending (e.g. "1.00" for max 1 USDC).
-
-## x402 Paywalls — Accepting Payments
-Create paywalls to charge other agents for accessing your resources:
-1. create_paywall — set price, token, chain, and the resource URL to protect.
-2. Share the access URL. Clients that pay on-chain get the resource; others get HTTP 402.
-3. list_paywalls and get_paywall_payments to track revenue.
-4. get_x402_revenue for aggregate stats across all paywalls.
-
-## Wallet Security
-- Use pause_wallet to immediately freeze a wallet if compromised. No transactions can be signed while paused.
-- Use unpause_wallet to resume operations.
-- Use delete_wallet to permanently disable a wallet.
-- Wallets have server-enforced spending limits.
-
-## Tool Selection Guide
-| Goal | Tool |
-|------|------|
-| Send ETH/SOL/native tokens | transfer |
-| Send USDC/ERC-20/SPL tokens | transfer_token |
-| Check native balance | get_balance |
-| Check token balance | get_token_balance |
-| Look up token details | get_token_info (EVM only) |
-| Approve DeFi spending | approve_token (EVM only) |
-| Check approval amount | get_allowance (EVM only) |
-| Read smart contract | call_contract (EVM only) |
-| Custom transaction | send_transaction |
-| Sign without broadcasting | sign_transaction |
-| Pay for x402 resource | pay_x402 |
-| Charge for your resource | create_paywall |
+    instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
+
+## Getting Started
+1. Call list_wallets to see existing wallets, or create_wallet to make a new one.
+2. Fund the wallet by sending tokens to its address from an external source.
+3. Use transfer (native tokens) or transfer_token (ERC-20/SPL tokens) to send funds.
+
+## Supported Chains
+- **EVM chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), Avalanche (43114), BSC (56), Zora (7777777), PulseChain (369)
+- **Solana:** Mainnet (900), Devnet (901)
+- Call get_chains for the full list with native tokens and stablecoin contract addresses.
+
+## EVM vs Solana
+- **Addresses:** EVM uses 0x-prefixed hex (42 chars). Solana uses Base58 (32-44 chars).
+- **Native tokens:** EVM = ETH/POL/BNB/etc (18 decimals, wei). Solana = SOL (9 decimals, lamports).
+- **Token standards:** EVM uses ERC-20. Solana uses SPL tokens.
+- **EVM-only tools:** approve_token, get_allowance, wrap_eth, unwrap_eth, call_contract, get_token_info. These do not work on Solana.
+- **Works on both:** create_wallet, transfer, transfer_token, send_transaction, sign_transaction, get_balance, get_token_balance.
+
+## Common Workflows
+
+### Send native tokens (ETH, SOL, etc.)
+Use the transfer tool with a human-readable amount (e.g. "0.1" ETH). It auto-converts to wei/lamports.
+
+### Send ERC-20 or SPL tokens
+Use transfer_token. You need: wallet_id, token contract address, recipient, amount, chain_id, and decimals (6 for USDC, 18 for most ERC-20s). Call get_chains to find stablecoin addresses.
+
+### Interact with DeFi (EVM only)
+1. Check allowance with get_allowance.
+2. If needed, call approve_token to let the DeFi contract spend your tokens.
+3. Use send_transaction with the contract's calldata to execute the interaction.
+
+### Wrap/unwrap native tokens (EVM only)
+Use wrap_eth to convert ETH → WETH (required by many DeFi protocols). Use unwrap_eth to convert back.
+
+### Read on-chain data (EVM only)
+Use call_contract for gas-free read-only calls (eth_call). Provide ABI-encoded calldata.
+
+## x402 Payments — Paying for Resources
+The pay_x402 tool handles the full x402 payment flow automatically:
+1. Fetches the URL.
+2. If the server returns HTTP 402, parses the payment requirements.
+3. Pays on-chain using your wallet.
+4. Retries the request with proof of payment.
+Always set max_payment to prevent overspending (e.g. "1.00" for max 1 USDC).
+
+## x402 Paywalls — Accepting Payments
+Create paywalls to charge other agents for accessing your resources:
+1. create_paywall — set price, token, chain, and the resource URL to protect.
+2. Share the access URL. Clients that pay on-chain get the resource; others get HTTP 402.
+3. list_paywalls and get_paywall_payments to track revenue.
+4. get_x402_revenue for aggregate stats across all paywalls.
+
+## Wallet Security
+- Use pause_wallet to immediately freeze a wallet if compromised. No transactions can be signed while paused.
+- Use unpause_wallet to resume operations.
+- Use delete_wallet to permanently disable a wallet.
+- Wallets have server-enforced spending limits.
+
+## Tool Selection Guide
+| Goal | Tool |
+|------|------|
+| Send ETH/SOL/native tokens | transfer |
+| Send USDC/ERC-20/SPL tokens | transfer_token |
+| Check native balance | get_balance |
+| Check token balance | get_token_balance |
+| Look up token details | get_token_info (EVM only) |
+| Approve DeFi spending | approve_token (EVM only) |
+| Check approval amount | get_allowance (EVM only) |
+| Read smart contract | call_contract (EVM only) |
+| Custom transaction | send_transaction |
+| Sign without broadcasting | sign_transaction |
+| Pay for x402 resource | pay_x402 |
+| Charge for your resource | create_paywall |
 | Check usage/billing | get_usage |`,
 });
 // ─── Tool: create_wallet ─────────────────────────────────────────
@@ -900,19 +952,10 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             throw new Error('Invalid headers JSON. Must be a JSON object (e.g. {"Authorization": "Bearer ..."}).');
         }
     }
-    // Validate URL — block private IPs and cloud metadata endpoints
-    const urlObj = new URL(url);
-    const hostname = urlObj.hostname.toLowerCase();
-    const blockedHosts = ['localhost', '127.0.0.1', '0.0.0.0', '[::1]', '169.254.169.254', 'metadata.google.internal'];
-    const blockedPrefixes = ['10.', '172.16.', '172.17.', '172.18.', '172.19.', '172.20.', '172.21.',
-        '172.22.', '172.23.', '172.24.', '172.25.', '172.26.', '172.27.', '172.28.', '172.29.',
-        '172.30.', '172.31.', '192.168.'];
-    if (blockedHosts.includes(hostname) || blockedPrefixes.some(p => hostname.startsWith(p))) {
-        throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
-    }
-    if (urlObj.protocol !== 'https:') {
-        throw new Error('Only HTTPS URLs are supported for x402 payments.');
-    }
+    // Validate URL: canonicalizes IP literals (including IPv4-mapped IPv6) and
+    // resolves DNS names, rejecting any private/internal destination. Redirect
+    // hops are re-validated by safeFetch below.
+    await assertPublicUrl(url);
     // Step 1: Make initial request
     const reqOptions = {
         method,
@@ -924,7 +967,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         if (!reqHeaders['Content-Type'])
             reqHeaders['Content-Type'] = 'application/json';
     }
-    const initialRes = await fetch(url, reqOptions);
+    const initialRes = await safeFetch(url, reqOptions);
     // If not 402, return the response as-is (no payment needed)
     if (initialRes.status !== 402) {
         const text = await initialRes.text();
@@ -966,8 +1009,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
@@ -975,7 +1028,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,
@@ -1007,7 +1060,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,
             }));
         }
@@ -1058,7 +1111,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     if (reqBody && method !== 'GET') {
         retryOptions.body = reqBody;
     }
-    const retryRes = await fetch(url, retryOptions);
+    const retryRes = await safeFetch(url, retryOptions);
     const retryText = await retryRes.text();
     let retryParsed;
     try {

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/ssrf-guard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SSRF guard for outbound x402 requests.
+ *
+ * The previous guard compared `new URL(url).hostname` against literal strings
+ * and dotted-decimal prefixes. That misses every alternate spelling of a
+ * private destination: IPv4-mapped IPv6 (`[::ffff:127.0.0.1]` parses to
+ * `[::ffff:7f00:1]`), the rest of 127.0.0.0/8, IPv6 unique-local and
+ * link-local, the whole 169.254.0.0/16 link-local range rather than only the
+ * metadata address, and 100.64.0.0/10.
+ *
+ * This module canonicalizes the host into actual IP addresses and tests them
+ * against numeric ranges, then resolves DNS names and applies the same test to
+ * every answer, so a public name pointing at a private address is refused too.
+ *
+ * Reported privately by ARC Security Research, 2026-07-31.
+ */
+/**
+ * Reduce a host to the IP address it actually denotes.
+ * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ */
+export declare function canonicalizeHost(hostRaw: string): {
+    ip: string | null;
+    family: 0 | 4 | 6;
+};
+/** True when the address is loopback, private, link-local, multicast or reserved. */
+export declare function isPrivateAddress(ipRaw: string): boolean;
+/**
+ * Throw unless `url` is an https URL pointing at a public destination.
+ * DNS names are resolved and every answer is checked, so a public name that
+ * maps to a private address is rejected.
+ */
+export declare function assertPublicUrl(url: string): Promise<void>;
+/**
+ * fetch() that validates the target, and every redirect hop, against
+ * assertPublicUrl. Redirects are followed manually because the automatic
+ * follower would happily land on a private address after a public first hop.
+ */
+export declare function safeFetch(url: string, options?: RequestInit, maxHops?: number): Promise<Response>;

package/build/ssrf-guard.js

@@ -0,0 +1,178 @@
+/**
+ * SSRF guard for outbound x402 requests.
+ *
+ * The previous guard compared `new URL(url).hostname` against literal strings
+ * and dotted-decimal prefixes. That misses every alternate spelling of a
+ * private destination: IPv4-mapped IPv6 (`[::ffff:127.0.0.1]` parses to
+ * `[::ffff:7f00:1]`), the rest of 127.0.0.0/8, IPv6 unique-local and
+ * link-local, the whole 169.254.0.0/16 link-local range rather than only the
+ * metadata address, and 100.64.0.0/10.
+ *
+ * This module canonicalizes the host into actual IP addresses and tests them
+ * against numeric ranges, then resolves DNS names and applies the same test to
+ * every answer, so a public name pointing at a private address is refused too.
+ *
+ * Reported privately by ARC Security Research, 2026-07-31.
+ */
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+/** Hostnames that must never be reached regardless of what they resolve to. */
+const BLOCKED_NAMES = new Set([
+    'localhost',
+    'metadata.google.internal',
+    'metadata.goog',
+    'instance-data',
+]);
+function ipv4ToInt(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    let n = 0;
+    for (const p of parts) {
+        const v = Number(p);
+        if (!Number.isInteger(v) || v < 0 || v > 255)
+            return null;
+        n = (n << 8 >>> 0) + v;
+    }
+    return n >>> 0;
+}
+function inV4Range(ip, cidr) {
+    const [base, bitsRaw] = cidr.split('/');
+    const bits = Number(bitsRaw);
+    const a = ipv4ToInt(ip);
+    const b = ipv4ToInt(base);
+    if (a === null || b === null)
+        return false;
+    if (bits === 0)
+        return true;
+    const mask = (0xffffffff << (32 - bits)) >>> 0;
+    return (a & mask) === (b & mask);
+}
+/** Ranges that are never a legitimate x402 payment endpoint. */
+const V4_BLOCKED = [
+    '0.0.0.0/8', // this network / unspecified
+    '10.0.0.0/8', // private
+    '100.64.0.0/10', // carrier-grade NAT
+    '127.0.0.0/8', // loopback, all of it
+    '169.254.0.0/16', // link-local, includes cloud metadata
+    '172.16.0.0/12', // private
+    '192.0.0.0/24', // IETF protocol assignments
+    '192.168.0.0/16', // private
+    '198.18.0.0/15', // benchmarking
+    '224.0.0.0/4', // multicast
+    '240.0.0.0/4', // reserved, includes 255.255.255.255
+];
+/**
+ * Reduce a host to the IP address it actually denotes.
+ * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ */
+export function canonicalizeHost(hostRaw) {
+    let host = hostRaw.trim().toLowerCase();
+    if (host.startsWith('[') && host.endsWith(']'))
+        host = host.slice(1, -1);
+    const zone = host.indexOf('%'); // fe80::1%eth0
+    if (zone !== -1)
+        host = host.slice(0, zone);
+    const fam = isIP(host);
+    if (fam === 0)
+        return { ip: null, family: 0 };
+    if (fam === 4)
+        return { ip: host, family: 4 };
+    // IPv6: unwrap ::ffff:a.b.c.d and its hex spelling ::ffff:7f00:1
+    const mapped = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return { ip: mapped[1], family: 4 };
+    const hexMapped = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hexMapped) {
+        const hi = parseInt(hexMapped[1], 16);
+        const lo = parseInt(hexMapped[2], 16);
+        return { ip: [(hi >> 8) & 255, hi & 255, (lo >> 8) & 255, lo & 255].join('.'), family: 4 };
+    }
+    return { ip: host, family: 6 };
+}
+/** True when the address is loopback, private, link-local, multicast or reserved. */
+export function isPrivateAddress(ipRaw) {
+    const { ip, family } = canonicalizeHost(ipRaw);
+    if (!ip)
+        return false;
+    if (family === 4)
+        return V4_BLOCKED.some(c => inV4Range(ip, c));
+    const v6 = ip;
+    if (v6 === '::' || v6 === '::1')
+        return true; // unspecified, loopback
+    if (/^f[cd][0-9a-f]{2}:/.test(v6))
+        return true; // fc00::/7 unique-local
+    if (/^fe[89ab][0-9a-f]:/.test(v6))
+        return true; // fe80::/10 link-local
+    if (/^ff[0-9a-f]{2}:/.test(v6))
+        return true; // ff00::/8 multicast
+    if (/^(64:ff9b|2002):/.test(v6))
+        return true; // NAT64 / 6to4 translation
+    return false;
+}
+/**
+ * Throw unless `url` is an https URL pointing at a public destination.
+ * DNS names are resolved and every answer is checked, so a public name that
+ * maps to a private address is rejected.
+ */
+export async function assertPublicUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error('Invalid URL.');
+    }
+    if (u.protocol !== 'https:') {
+        throw new Error('Only HTTPS URLs are supported for x402 payments.');
+    }
+    const hostRaw = u.hostname.toLowerCase();
+    const bare = hostRaw.startsWith('[') && hostRaw.endsWith(']') ? hostRaw.slice(1, -1) : hostRaw;
+    if (BLOCKED_NAMES.has(bare)) {
+        throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
+    }
+    const { ip, family } = canonicalizeHost(hostRaw);
+    if (family !== 0) {
+        if (isPrivateAddress(ip)) {
+            throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
+        }
+        return;
+    }
+    // A name: every address it resolves to must be public.
+    let answers;
+    try {
+        answers = await lookup(bare, { all: true });
+    }
+    catch {
+        throw new Error(`Could not resolve host "${bare}".`);
+    }
+    if (!answers.length)
+        throw new Error(`Could not resolve host "${bare}".`);
+    for (const a of answers) {
+        if (isPrivateAddress(a.address)) {
+            throw new Error('URL resolves to a private/internal address. Only public URLs are allowed.');
+        }
+    }
+}
+/**
+ * fetch() that validates the target, and every redirect hop, against
+ * assertPublicUrl. Redirects are followed manually because the automatic
+ * follower would happily land on a private address after a public first hop.
+ */
+export async function safeFetch(url, options = {}, maxHops = 3) {
+    let current = url;
+    for (let hop = 0; hop <= maxHops; hop++) {
+        await assertPublicUrl(current);
+        const res = await fetch(current, { ...options, redirect: 'manual' });
+        const isRedirect = res.status >= 300 && res.status < 400 && res.headers.has('location');
+        if (!isRedirect)
+            return res;
+        const next = new URL(res.headers.get('location'), current).toString();
+        // A redirected request must not replay the body or method blindly.
+        if (res.status === 303 || ((res.status === 301 || res.status === 302) && options.method && options.method !== 'GET')) {
+            options = { ...options, method: 'GET', body: undefined };
+        }
+        current = next;
+    }
+    throw new Error('Too many redirects while contacting the x402 endpoint.');
+}