agentwallet-mcp 1.12.2 → 1.12.3

package/README.md

@@ -43,7 +43,7 @@ Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key
 
 `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.
+`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`, `approve`, `increaseAllowance` and Permit2 `approve`, the approvals because an unbounded allowance is a drain waiting to happen. Any other calldata sent to a token contract or to Permit2 is refused while the cap is set, because the guard cannot price it; set `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1` to allow such calls deliberately. Calls to other contracts (routers, bridges) pass, since they can only pull what an approval already allowed. Decimals are resolved locally from the trusted registry, then the token's own `decimals()`; a token that resolves neither way is evaluated at 0 decimals, the only value that cannot fail open.
 
 ### Solana local signing
 
@@ -327,7 +327,8 @@ Which guards apply depends on who holds the key.
 **Local mode** (you hold the key): there is no server in the signing path, so the server-side limits and pause above cannot see or stop a locally signed transaction, and nobody (including us) can freeze a local wallet. Your protection is the per-transaction caps enforced inside your own process before anything is signed. Set them before you fund the wallet; an unset cap means no limit.
 
 - `AGENTWALLET_MAX_TX_NATIVE`: ceiling per transaction in native units (ETH, MATIC, and so on)
-- `AGENTWALLET_MAX_TX_TOKEN`: ceiling per ERC-20 transfer, in human units of the token
+- `AGENTWALLET_MAX_TX_TOKEN`: ceiling per ERC-20 transfer or approval, in human units of the token
+- `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS`: set to `1` to let calldata the token cap cannot price reach a token contract or Permit2 (refused by default while the cap is set)
 - `AGENTWALLET_MAX_TX_SOL`: ceiling per SOL or SPL transfer
 - `AGENTWALLET_MAX_AUTOPAY`: ceiling per x402 auto-payment (default `1`)
 

package/build/index.js

@@ -461,7 +461,7 @@ function resolveChainId(network) {
 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.12.2',
+    version: '1.12.3',
 }, {
     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.
 

package/build/local-wallet.js

@@ -193,7 +193,12 @@ export async function localTokenBalance(chainId, token) {
  * 2-decimal token move 10,000x the configured cap.
  */
 const decimalsCache = new Map();
-async function resolveTokenDecimals(chainId, token) {
+/**
+ * Decimals for `token`: the trusted registry, then the contract's own
+ * decimals() (cached on success). Null when the address does not answer like
+ * an ERC-20 at all, which is how the guard tells a token from a router.
+ */
+async function probeTokenDecimals(chainId, token) {
     const known = lookupTrustedDecimals(chainId, token);
     if (typeof known === 'number')
         return known;
@@ -217,11 +222,33 @@ async function resolveTokenDecimals(chainId, token) {
         }
     }
     catch {
-        // Unreachable RPC, non-standard token, anything at all: fall through to 0.
+        // Unreachable RPC, non-standard token, not a token at all.
     }
-    return 0;
+    return null;
+}
+async function resolveTokenDecimals(chainId, token) {
+    return (await probeTokenDecimals(chainId, token)) ?? 0;
 }
-async function assertWithinTokenCap(chainId, token, data) {
+/** Canonical Permit2, the same address on every EVM chain it is deployed to. */
+const PERMIT2 = '0x000000000022d473030f116ddee9f6b43ac78ba3';
+const CAP_LAYOUTS = {
+    a9059cbb: { amountIndex: 1, what: 'token transfer' }, // transfer(address,uint256)
+    '23b872dd': { amountIndex: 2, what: 'token transfer' }, // transferFrom(address,address,uint256)
+    '095ea7b3': { amountIndex: 1, what: 'approval' }, // approve(address,uint256)
+    '39509351': { amountIndex: 1, what: 'allowance increase' }, // increaseAllowance(address,uint256)
+    '87517c45': { amountIndex: 2, tokenIndex: 0, what: 'Permit2 approval' }, // Permit2.approve(address,address,uint160,uint48)
+};
+/**
+ * The selector table used to be an allowlist that returned early for anything
+ * it did not recognise, so `increaseAllowance`, a direct Permit2 `approve`, or
+ * any other function on a token contract went through uncapped while the guard
+ * reported nothing. Reported privately 2026-09-25. Now: priced calls are
+ * checked, and unpriced calldata aimed at a token contract or at Permit2 is
+ * refused, because any state change there can move funds. Calls to other
+ * contracts (routers, bridges) still pass: they can only pull what an approval
+ * already allowed, and approvals are what this guard bounds.
+ */
+async function assertWithinTokenCap(chainId, to, data) {
     const cap = (process.env.AGENTWALLET_MAX_TX_TOKEN || '').trim();
     if (!cap)
         return;
@@ -230,21 +257,38 @@ async function assertWithinTokenCap(chainId, token, data) {
     }
     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);
+    const isPermit2 = to.toLowerCase() === PERMIT2;
+    const layout = CAP_LAYOUTS[selector];
+    const priced = layout && (layout.tokenIndex === undefined || isPermit2);
+    if (!priced) {
+        if (process.env.AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS === '1')
+            return;
+        const looksLikeToken = isPermit2 || (await probeTokenDecimals(chainId, to)) !== null;
+        if (looksLikeToken) {
+            throw new Error(`Blocked by local guard: calldata selector 0x${selector} sent to ` +
+                `${isPermit2 ? 'Permit2' : 'a token contract'} is not one AGENTWALLET_MAX_TX_TOKEN can price, ` +
+                `so it is refused rather than let through uncapped. Use transfer, transferFrom, approve, ` +
+                `increaseAllowance or Permit2 approve, or set AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1 to allow it deliberately.`);
+        }
+        return; // an ordinary contract call; it can only pull what an approval already allowed
+    }
+    const wordAt = (i) => hex.slice(8 + i * 64, 8 + (i + 1) * 64);
+    const word = wordAt(layout.amountIndex);
     if (word.length !== 64)
         return; // malformed; leave it to the node to reject
     const amount = BigInt('0x' + word);
+    let token = to;
+    if (layout.tokenIndex !== undefined) {
+        const tw = wordAt(layout.tokenIndex);
+        if (tw.length !== 64)
+            return;
+        token = ('0x' + tw.slice(24));
+    }
     const decimals = await resolveTokenDecimals(chainId, token);
     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 ` +
+        throw new Error(`Blocked by local guard: ${layout.what} of ${amount} base units exceeds ` +
             `AGENTWALLET_MAX_TX_TOKEN (${cap}, evaluated at ${decimals} decimals). ` +
             `Raise the cap deliberately if this is intended.`);
     }

package/build/ssrf-guard.d.ts

@@ -30,9 +30,17 @@
  * by an anonymous researcher, 2026-08-02 (the DNS rebinding race), and by
  * Arthur Kijkrittaya, 2026-09-08 (credentials surviving cross-origin redirects).
  */
+/** Expand an IPv6 literal (any spelling Node's isIP accepts) into eight 16-bit groups. */
+export declare function expandIPv6(hostRaw: string): number[] | null;
 /**
  * Reduce a host to the IP address it actually denotes.
- * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ * Strips IPv6 brackets and unwraps every IPv6 form that embeds an IPv4
+ * address: IPv4-mapped (::ffff:a.b.c.d), IPv4-translated (::ffff:0:a.b.c.d)
+ * and the deprecated IPv4-compatible form (::a.b.c.d, also spelled
+ * ::7f00:1). The match is on the expanded groups, not on one spelling, so
+ * 0:0:0:0:0:0:7f00:1 and ::7F00:1 canonicalize the same way. The compatible
+ * form was reported as unclassified on 2026-09-25 (not reachable in practice,
+ * modern stacks refuse to route ::/96, but a guard should not depend on that).
  */
 export declare function canonicalizeHost(hostRaw: string): {
     ip: string | null;

package/build/ssrf-guard.js

@@ -79,9 +79,45 @@ const V4_BLOCKED = [
     '224.0.0.0/4', // multicast
     '240.0.0.0/4', // reserved, includes 255.255.255.255
 ];
+/** Expand an IPv6 literal (any spelling Node's isIP accepts) into eight 16-bit groups. */
+export function expandIPv6(hostRaw) {
+    let h = hostRaw.toLowerCase();
+    // A trailing dotted IPv4 (::ffff:1.2.3.4, ::1.2.3.4, 64:ff9b::1.2.3.4) is the last two groups.
+    const dotted = h.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+    if (dotted) {
+        const v4 = ipv4ToInt(dotted[2]);
+        if (v4 === null)
+            return null;
+        h = dotted[1] + (v4 >>> 16).toString(16) + ':' + (v4 & 0xffff).toString(16);
+    }
+    const halves = h.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...tail];
+    const out = [];
+    for (const g of groups) {
+        if (!/^[0-9a-f]{1,4}$/.test(g))
+            return null;
+        out.push(parseInt(g, 16));
+    }
+    return out;
+}
+const embeddedV4 = (hi, lo) => [(hi >> 8) & 255, hi & 255, (lo >> 8) & 255, lo & 255].join('.');
+const zeroThrough = (g, n) => g.slice(0, n).every(x => x === 0);
 /**
  * Reduce a host to the IP address it actually denotes.
- * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ * Strips IPv6 brackets and unwraps every IPv6 form that embeds an IPv4
+ * address: IPv4-mapped (::ffff:a.b.c.d), IPv4-translated (::ffff:0:a.b.c.d)
+ * and the deprecated IPv4-compatible form (::a.b.c.d, also spelled
+ * ::7f00:1). The match is on the expanded groups, not on one spelling, so
+ * 0:0:0:0:0:0:7f00:1 and ::7F00:1 canonicalize the same way. The compatible
+ * form was reported as unclassified on 2026-09-25 (not reachable in practice,
+ * modern stacks refuse to route ::/96, but a guard should not depend on that).
  */
 export function canonicalizeHost(hostRaw) {
     let host = hostRaw.trim().toLowerCase();
@@ -95,16 +131,15 @@ export function canonicalizeHost(hostRaw) {
         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 };
-    }
+    const g = expandIPv6(host);
+    if (!g)
+        return { ip: host, family: 6 };
+    if (zeroThrough(g, 5) && g[5] === 0xffff)
+        return { ip: embeddedV4(g[6], g[7]), family: 4 }; // ::ffff:a.b.c.d
+    if (zeroThrough(g, 4) && g[4] === 0xffff && g[5] === 0)
+        return { ip: embeddedV4(g[6], g[7]), family: 4 }; // ::ffff:0:a.b.c.d
+    if (zeroThrough(g, 6) && !(g[6] === 0 && g[7] <= 1))
+        return { ip: embeddedV4(g[6], g[7]), family: 4 }; // ::a.b.c.d, but not :: or ::1
     return { ip: host, family: 6 };
 }
 /** True when the address is loopback, private, link-local, multicast or reserved. */
@@ -114,17 +149,23 @@ export function isPrivateAddress(ipRaw) {
         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))
+    const g = expandIPv6(ip);
+    if (!g)
+        return true; // isIP said IPv6 but it will not parse: refuse
+    if (zeroThrough(g, 7) && g[7] <= 1)
+        return true; // :: unspecified, ::1 loopback
+    if ((g[0] & 0xfe00) === 0xfc00)
         return true; // fc00::/7 unique-local
-    if (/^fe[89ab][0-9a-f]:/.test(v6))
+    if ((g[0] & 0xffc0) === 0xfe80)
         return true; // fe80::/10 link-local
-    if (/^ff[0-9a-f]{2}:/.test(v6))
+    if ((g[0] & 0xff00) === 0xff00)
         return true; // ff00::/8 multicast
-    if (/^(64:ff9b|2002):/.test(v6))
-        return true; // NAT64 / 6to4 translation
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return true; // 64:ff9b::/96 NAT64
+    if (g[0] === 0x2002)
+        return true; // 2002::/16 6to4
+    if (g[0] === 0x2001 && g[1] === 0xdb8)
+        return true; // 2001:db8::/32 documentation
     return false;
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.12.2",
+  "version": "1.12.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",