Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

10.7 KB
Raw Blame
// SSRF guard + shared spend-limit parsing for the x402 MCP bridge.
//
// THREAT MODEL: this bridge holds live EVM + SVM signers and an auto-pay
// interceptor. A URL supplied by the LLM (call_paid_endpoint) or by an
// untrusted Bazaar listing (dynamic tools) flows into a payment-wrapped axios
// request. Without validation, an attacker can point that request at internal
// infrastructure — cloud metadata (169.254.169.254), localhost admin panels,
// RFC-1918 hosts — and, worse, get the bridge to SIGN a payment to do it.
//
// `assertPayableUrl` is the single chokepoint that every outbound payable
// request must pass through. It enforces:
//   - scheme allowlist (https only; http behind an explicit dev opt-in)
//   - DNS resolution of the hostname and rejection if ANY resolved address is
//     private/loopback/link-local/unspecified/ULA/CGNAT (defeats DNS rebinding
//     at request-build time and literal-IP SSRF)
//   - optional strict host allowlist via MCP_BRIDGE_ALLOWED_HOSTS
//
// No external dependency: the CIDR checks parse octets / IPv6 hextets directly.

import { promises as dns } from 'node:dns';
import dnsCb from 'node:dns';
import http from 'node:http';
import https from 'node:https';
import net from 'node:net';

const DEFAULT_MAX_PRICE_ATOMIC = 100_000n; // $0.10 USDC

// ---------------------------------------------------------------------------
// Shared spend-limit parsing: the single source of truth for the effective
// per-call cap. The spending-cap hook and Bazaar discovery MUST read the same
// value; when they disagree, discovery registers tools whose every call the
// hook then refuses. The cap always exists (default when unset), because the
// hook enforces the default even when no env var is configured.
// ---------------------------------------------------------------------------
export function maxPriceAtomic() {
	const raw = process.env.MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC;
	if (!raw) return DEFAULT_MAX_PRICE_ATOMIC;
	let v;
	try {
		v = BigInt(raw);
	} catch {
		throw new Error('MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC must be an integer (atomic units)');
	}
	if (v < 0n) throw new Error('MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC must be non-negative');
	return v;
}

export { DEFAULT_MAX_PRICE_ATOMIC };

// ---------------------------------------------------------------------------
// IP range classification
// ---------------------------------------------------------------------------

function ipv4ToInt(ip) {
	const parts = ip.split('.');
	if (parts.length !== 4) return null;
	let n = 0;
	for (const part of parts) {
		if (!/^\d{1,3}$/.test(part)) return null;
		const octet = Number(part);
		if (octet > 255) return null;
		n = n * 256 + octet;
	}
	return n >>> 0;
}

function inV4Cidr(intIp, baseStr, prefix) {
	const baseInt = ipv4ToInt(baseStr);
	if (baseInt === null) return false;
	const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
	return (intIp & mask) === (baseInt & mask);
}

// Private / non-routable / sensitive IPv4 ranges that must never be paid-fetched.
function isPrivateIPv4(ip) {
	const n = ipv4ToInt(ip);
	if (n === null) return true; // unparseable → treat as unsafe
	return (
		inV4Cidr(n, '0.0.0.0', 8) || // "this" network / unspecified
		inV4Cidr(n, '10.0.0.0', 8) || // RFC1918
		inV4Cidr(n, '127.0.0.0', 8) || // loopback
		inV4Cidr(n, '169.254.0.0', 16) || // link-local incl. 169.254.169.254 metadata
		inV4Cidr(n, '172.16.0.0', 12) || // RFC1918
		inV4Cidr(n, '192.168.0.0', 16) || // RFC1918
		inV4Cidr(n, '100.64.0.0', 10) || // CGNAT (RFC6598)
		inV4Cidr(n, '192.0.0.0', 24) || // IETF protocol assignments
		inV4Cidr(n, '198.18.0.0', 15) || // benchmarking (RFC2544)
		inV4Cidr(n, '224.0.0.0', 4) || // multicast
		inV4Cidr(n, '240.0.0.0', 4) // reserved + broadcast
	);
}

// Expand an IPv6 address (possibly with `::` or an embedded IPv4 tail) to its
// 8 16-bit hextet integers. Returns null if it cannot be parsed.
function expandIPv6(addr) {
	let s = addr.trim();
	// Strip zone id (fe80::1%eth0).
	const pct = s.indexOf('%');
	if (pct !== -1) s = s.slice(0, pct);

	const halves = s.split('::');
	if (halves.length > 2) return null;

	const toHextets = (segment) => {
		if (segment === '') return [];
		const out = [];
		for (const part of segment.split(':')) {
			if (part.includes('.')) {
				// Embedded IPv4 tail (e.g. ::ffff:10.0.0.1) → two hextets.
				const v4 = ipv4ToInt(part);
				if (v4 === null) return null;
				out.push((v4 >>> 16) & 0xffff, v4 & 0xffff);
			} else {
				if (!/^[0-9a-fA-F]{1,4}$/.test(part)) return null;
				out.push(parseInt(part, 16));
			}
		}
		return out;
	};

	const head = toHextets(halves[0]);
	if (head === null) return null;
	let tail = [];
	if (halves.length === 2) {
		tail = toHextets(halves[1]);
		if (tail === null) return null;
	} else if (head.length !== 8) {
		return null; // no `::`, so it must be fully specified
	}

	const fill = 8 - head.length - tail.length;
	if (fill < 0) return null;
	return [...head, ...new Array(fill).fill(0), ...tail];
}

function isPrivateIPv6(addr) {
	const h = expandIPv6(addr);
	if (h === null) return true; // unparseable → unsafe

	// ::  (unspecified)
	if (h.every((x) => x === 0)) return true;
	// ::1 (loopback)
	if (h.slice(0, 7).every((x) => x === 0) && h[7] === 1) return true;
	// fc00::/7 (ULA)
	if ((h[0] & 0xfe00) === 0xfc00) return true;
	// fe80::/10 (link-local)
	if ((h[0] & 0xffc0) === 0xfe80) return true;

	// IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible — re-check the v4 tail.
	const isV4Mapped = h.slice(0, 5).every((x) => x === 0) && h[5] === 0xffff;
	const isV4Compat = h.slice(0, 6).every((x) => x === 0) && (h[6] !== 0 || h[7] > 1);
	if (isV4Mapped || isV4Compat) {
		const v4 = `${h[6] >>> 8}.${h[6] & 0xff}.${h[7] >>> 8}.${h[7] & 0xff}`;
		return isPrivateIPv4(v4);
	}

	// ff00::/8 multicast.
	if ((h[0] & 0xff00) === 0xff00) return true;

	// Tunnelled IPv4: NAT64 (64:ff9b::/96) and 6to4 (2002::/16) carry an IPv4
	// address that a translator or relay will happily dial, so a private v4 in
	// either wrapper is as unsafe as the bare address.
	const embeds = (a, b) => `${a >>> 8}.${a & 0xff}.${b >>> 8}.${b & 0xff}`;
	if (h[0] === 0x64 && h[1] === 0xff9b && h.slice(2, 6).every((x) => x === 0)) {
		return isPrivateIPv4(embeds(h[6], h[7]));
	}
	if (h[0] === 0x2002) return isPrivateIPv4(embeds(h[1], h[2]));

	return false;
}

// True if `ip` (a literal address string) is in a blocked range.
export function isBlockedAddress(ip) {
	const kind = net.isIP(ip);
	if (kind === 4) return isPrivateIPv4(ip);
	if (kind === 6) return isPrivateIPv6(ip);
	// Not a literal IP — caller must resolve via DNS first.
	return true;
}

// ---------------------------------------------------------------------------
// Allowlists / scheme policy
// ---------------------------------------------------------------------------

function allowedHosts() {
	const raw = process.env.MCP_BRIDGE_ALLOWED_HOSTS;
	if (!raw || !raw.trim()) return null;
	return new Set(
		raw
			.split(',')
			.map((h) => h.trim().toLowerCase())
			.filter(Boolean),
	);
}

function httpAllowed() {
	return process.env.MCP_BRIDGE_ALLOW_HTTP === '1';
}

// ---------------------------------------------------------------------------
// The guard
// ---------------------------------------------------------------------------

/**
 * Validate that `rawUrl` is safe to issue a payment-wrapped request against.
 * Throws a clear Error on any violation. Returns the (string) validated URL.
 */
export async function assertPayableUrl(rawUrl) {
	let parsed;
	try {
		parsed = new URL(rawUrl);
	} catch {
		throw new Error(`refused: not a parseable URL: ${String(rawUrl)}`);
	}

	// Scheme policy: https only, http behind explicit dev opt-in. Everything
	// else (file:, ftp:, data:, gopher:, etc.) is rejected outright.
	if (parsed.protocol === 'http:') {
		if (!httpAllowed()) {
			throw new Error(
				'refused: http:// is disabled (set MCP_BRIDGE_ALLOW_HTTP=1 for local dev only)',
			);
		}
	} else if (parsed.protocol !== 'https:') {
		throw new Error(`refused: unsupported URL scheme "${parsed.protocol}" (only https is allowed)`);
	}

	const host = parsed.hostname.toLowerCase();
	if (!host) throw new Error('refused: URL has no host');

	// Strict host allowlist mode.
	const allow = allowedHosts();
	if (allow && !allow.has(host)) {
		throw new Error(`refused: host "${host}" is not in MCP_BRIDGE_ALLOWED_HOSTS allowlist`);
	}

	// Literal-IP host → check directly, no DNS.
	const literalKind = net.isIP(host) || net.isIP(stripBrackets(host));
	if (literalKind) {
		const ip = stripBrackets(host);
		if (isBlockedAddress(ip)) {
			throw new Error(`refused: host resolves to a private/blocked address (${ip})`);
		}
		return parsed.toString();
	}

	// Hostname → resolve ALL addresses and reject if ANY is internal. Checking
	// every result (not just the first) closes the multi-A-record / partial
	// rebinding gap.
	let records;
	try {
		records = await dns.lookup(host, { all: true });
	} catch (err) {
		throw new Error(`refused: DNS lookup failed for "${host}": ${err?.code || err?.message || 'error'}`);
	}
	if (!records || records.length === 0) {
		throw new Error(`refused: "${host}" did not resolve to any address`);
	}
	for (const { address } of records) {
		if (isBlockedAddress(address)) {
			throw new Error(`refused: "${host}" resolves to a private/blocked address (${address})`);
		}
	}

	return parsed.toString();
}

function stripBrackets(host) {
	return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
}

/**
 * dns.lookup replacement for http(s) agents. assertPayableUrl resolves once to
 * validate, but the HTTP client resolves again at connect time, so a rebinding
 * DNS server could answer public first and an internal address second. This
 * lookup re-checks every address at the moment the socket is opened, and the
 * connection is made to the very address that passed the check.
 */
export function guardedLookup(hostname, options, callback) {
	const opts = typeof options === 'function' ? {} : options || {};
	const cb = typeof options === 'function' ? options : callback;
	dnsCb.lookup(hostname, { ...opts, all: true }, (err, records) => {
		if (err) return cb(err);
		const bad = (records || []).find(({ address }) => isBlockedAddress(address));
		if (!records || records.length === 0 || bad) {
			const e = new Error(
				`refused: "${hostname}" resolves to a private/blocked address${bad ? ` (${bad.address})` : ''}`,
			);
			e.code = 'ESSRF_BLOCKED';
			return cb(e);
		}
		if (opts.all) return cb(null, records);
		return cb(null, records[0].address, records[0].family);
	});
}

// Agents whose connect-time DNS resolution is subject to the same range check.
export function createGuardedAgents() {
	return {
		httpAgent: new http.Agent({ lookup: guardedLookup }),
		httpsAgent: new https.Agent({ lookup: guardedLookup }),
	};
}