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.

7.4 KB
Raw Blame
// SSRF guard primitives, shared by every server-side fetcher of untrusted URLs.
//
// Fetching an attacker-supplied URL from a server reachable by the internet is a
// classic SSRF vector: the URL can point at cloud metadata (169.254.169.254),
// RFC1918 ranges, or loopback, and we'd happily proxy the response back. The
// defenses here are the ones api/_lib/fetch-model.js pioneered, factored out so
// the x402 monetize proxy (and anything else) enforces the exact same policy:
//   1. Scheme allowlist — https only (http permitted in dev).
//   2. DNS resolution on OUR side; every resolved address checked against an IP
//      blocklist before a socket opens.
//   3. Connections pinned to the validated addresses (custom undici lookup) so a
//      DNS-rebinding host can't swap in a private IP at connect time.
//   4. Redirects followed manually, re-validating the target host each hop.

import { lookup } from 'node:dns/promises';
import { Agent } from 'undici';
import { isPrivateIPv4, isPrivateIPv6 } from './ip-classify.js';
import { readTextCapped } from './read-capped.js';

export { isPrivateIPv4, isPrivateIPv6, parseIPv6Groups } from './ip-classify.js';

const IS_DEV = process.env.NODE_ENV !== 'production';

export class SsrfError extends Error {
	constructor(message, code = 'blocked') {
		super(message);
		this.name = 'SsrfError';
		this.code = code;
	}
}

export function isPrivateAddress(address, family) {
	if (family === 4) return isPrivateIPv4(address);
	if (family === 6) return isPrivateIPv6(address);
	return true; // unknown family → unsafe
}

// node:dns/promises `lookup` accepts no AbortSignal and no timeout, so a stalled
// system resolver (a dead host whose DNS hangs rather than NXDOMAINs) blocks
// forever — and because the lookup is not tied to any fetch AbortController, the
// caller's request timeout never fires either, pinning the whole serverless
// invocation to its hard kill (the root cause of mass /api/img 30s timeouts).
// Bound every resolution with our own timer so a hung resolver fails fast and
// the caller can fall through to its next candidate or placeholder.
const DNS_TIMEOUT_MS = 4_000;

// Resolve `host` once, reject if ANY resolved address is private, and return the
// validated address list to pin the connection to.
export async function resolvePublicHost(host, { dnsTimeoutMs = DNS_TIMEOUT_MS } = {}) {
	if (!host) throw new SsrfError('missing host', 'invalid_url');
	let resolved;
	let timer;
	try {
		resolved = await Promise.race([
			lookup(host, { all: true }),
			new Promise((_, reject) => {
				timer = setTimeout(
					() => reject(new SsrfError(`DNS lookup timed out for ${host}`, 'dns_timeout')),
					dnsTimeoutMs,
				);
			}),
		]);
	} catch (err) {
		if (err instanceof SsrfError) throw err;
		throw new SsrfError(`DNS lookup failed for ${host}`, 'dns_failed');
	} finally {
		clearTimeout(timer);
	}
	const addrs = Array.isArray(resolved) ? resolved : [resolved];
	if (!addrs.length) throw new SsrfError(`DNS lookup failed for ${host}`, 'dns_failed');
	for (const { address, family } of addrs) {
		if (isPrivateAddress(address, family)) {
			throw new SsrfError(`host resolves to private address: ${address}`, 'private_address');
		}
	}
	return addrs;
}

// undici Agent whose DNS lookup only yields the pre-validated addresses for
// `expectedHost`, closing the check-then-connect TOCTOU.
export function pinnedAgent(expectedHost, addrs) {
	return new Agent({
		connect: {
			lookup(hostname, _opts, cb) {
				if (hostname !== expectedHost) {
					cb(new SsrfError(`unexpected connect host: ${hostname}`, 'host_pin_mismatch'));
					return;
				}
				const safe = addrs.filter((a) => !isPrivateAddress(a.address, a.family));
				if (!safe.length) {
					cb(new SsrfError('no public address to connect to', 'private_address'));
					return;
				}
				cb(
					null,
					safe.map((a) => ({ address: a.address, family: a.family })),
				);
			},
		},
	});
}

// Release a single-use pinned agent. Always destroy(), never close(): close()
// waits for every in-flight request on the agent to finish, and a response whose
// body was never read (a non-2xx we throw on, an oversized content-length, a
// redirect hop) never finishes while the upstream holds its socket open. That is
// how /api/news/image sat at the 900 s Cloud Run limit on publishers that answer
// 403 and then stall. Every caller is done with the agent by the time it
// disposes it, so aborting what is left on it loses nothing.
export async function disposeAgent(agent) {
	if (!agent) return;
	await agent.destroy().catch(() => {});
}

// Parse + scheme-check a URL. https only (http allowed in dev). Returns the URL.
export function validatePublicUrl(rawUrl, { allowHttp = IS_DEV } = {}) {
	let url;
	try {
		url = new URL(rawUrl);
	} catch {
		throw new SsrfError('invalid URL', 'invalid_url');
	}
	if (url.protocol !== 'https:' && !(allowHttp && url.protocol === 'http:')) {
		throw new SsrfError(`scheme not allowed: ${url.protocol}`, 'scheme_not_allowed');
	}
	return url;
}

// Static + DNS validation for a user-supplied target URL at registration time.
// Resolves the host so a URL pointing at a private IP is rejected before we ever
// store it. Returns the normalized href.
export async function assertPublicHttpsUrl(rawUrl, opts = {}) {
	const url = validatePublicUrl(rawUrl, opts);
	await resolvePublicHost(url.hostname);
	return url.href;
}

// SSRF-guarded fetch of an untrusted URL, re-validating each redirect hop and
// returning the parsed JSON (or raw text when not JSON). Used by the x402 paid
// proxy to relay a buyer's call to the agent's upstream `target_url`.
export async function safeFetchJson(
	rawUrl,
	{ method = 'GET', headers = {}, body, timeoutMs = 25_000, maxRedirects = 3, allowHttp, maxResponseBytes = 5 * 1024 * 1024 } = {},
) {
	let currentUrl = validatePublicUrl(rawUrl, { allowHttp });
	let redirects = 0;
	const controller = new AbortController();
	const timer = setTimeout(() => controller.abort(), timeoutMs);
	let agent = null;
	try {
		while (true) {
			const addrs = await resolvePublicHost(currentUrl.hostname);
			await disposeAgent(agent);
			agent = pinnedAgent(currentUrl.hostname, addrs);

			const res = await fetch(currentUrl, {
				method,
				redirect: 'manual',
				signal: controller.signal,
				dispatcher: agent,
				headers: {
					'user-agent': '3d-agent-x402/1.0 (+https://three.ws/)',
					accept: 'application/json, text/plain;q=0.8, */*;q=0.5',
					...(body != null ? { 'content-type': 'application/json' } : {}),
					...headers,
				},
				...(body != null
					? { body: typeof body === 'string' ? body : JSON.stringify(body) }
					: {}),
			});

			if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
				if (++redirects > maxRedirects) {
					throw new SsrfError('too many redirects', 'too_many_redirects');
				}
				currentUrl = validatePublicUrl(
					new URL(res.headers.get('location'), currentUrl).toString(),
					{
						allowHttp,
					},
				);
				continue;
			}

			const { text, truncated } = await readTextCapped(res, maxResponseBytes);
			if (truncated) {
				throw new SsrfError(`response exceeds ${maxResponseBytes} bytes`, 'response_too_large');
			}
			let data = text;
			const ct = res.headers.get('content-type') || '';
			if (ct.includes('application/json') || ct.includes('+json')) {
				try {
					data = text ? JSON.parse(text) : null;
				} catch {
					data = text;
				}
			}
			return { status: res.status, ok: res.ok, contentType: ct, data };
		}
	} finally {
		clearTimeout(timer);
		await disposeAgent(agent);
	}
}