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.

15.9 KB
Raw Blame
// AST analysis of every outbound call in the repo.
//
// Regex cannot answer the question this file exists to answer. "Does this call
// have a deadline" is not a property of the line the call is written on: the
// options object may be built three statements earlier, the deadline may arrive
// through a wrapper, and a `signal,` shorthand looks nothing like `signal:`.
// An earlier regex sweep of this same repo reported one unguarded call and was
// wrong twice over, in both directions. Parsing is what makes the audit
// trustworthy enough to gate a deploy on.
//
// What it produces, per call site: which upstream is being talked to, and which
// of the five protections are present (deadline, retry, failover, lastGood,
// breaker). Everything downstream of this module (the grade, the ratchet, the
// generated map) is a projection of that one table.

import { readFileSync } from 'node:fs';
import { relative, resolve, dirname, join } from 'node:path';
import * as acorn from 'acorn';

// A local walker rather than acorn-walk. This module gates a deploy, so it is
// deliberately free of dependencies beyond the parser itself: the traversal it
// needs is a generic descent that carries the ancestor chain, which is shorter
// than the code that would justify pulling a package in for it.
function walkWithAncestors(node, visit, ancestors = []) {
	if (node === null || typeof node !== 'object') return;
	if (Array.isArray(node)) {
		for (const child of node) walkWithAncestors(child, visit, ancestors);
		return;
	}
	if (typeof node.type !== 'string') return;
	visit(node, ancestors);
	ancestors.push(node);
	for (const key of Object.keys(node)) {
		if (key === 'type' || key === 'loc' || key === 'start' || key === 'end') continue;
		walkWithAncestors(node[key], visit, ancestors);
	}
	ancestors.pop();
}

// Helpers whose use IS the protection: calling one of these is what a guarded
// call site looks like in this repo, so the analyzer resolves them by name
// rather than re-deriving their internals at every call site. Adding a new
// shared helper means adding it here, which is the one maintenance cost.
export const GUARDS = {
	fetchUpstream: ['deadline', 'retry', 'breaker'],
	fetchUpstreamJson: ['deadline', 'retry', 'breaker'],
	fetchAnyJson: ['deadline', 'retry', 'failover'],
	lastGood: ['lastGood'],
	lastGoodValue: ['lastGood'],
	cacheWrapLastGood: ['lastGood'],
	fetchFirst: ['deadline', 'failover'],
	fetchFirstOrNull: ['deadline', 'failover'],
	pumpFetchJson: ['deadline', 'retry'],
	geckoFetch: ['deadline', 'lastGood'],
	paprikaGet: ['deadline'],
	withRetry: ['retry'],
	withBreaker: ['breaker'],
	withRetryAndBreaker: ['retry', 'breaker'],
	makeRotatingFetch: ['deadline', 'failover'],
	// The rotating RPC clients bound each attempt themselves (see
	// makeRotatingFetch in api/_lib/solana/connection.js), so using one is a
	// bounded call even though no deadline is written at the call site.
	solanaConnection: ['deadline', 'failover'],
	evmFallbackProvider: ['deadline', 'failover'],
	evmTransport: ['deadline', 'failover'],
	resolveURI: ['deadline', 'failover'],
	fetchWithFallback: ['deadline', 'failover'],
	loadModule: ['deadline', 'failover'],
	loadScript: ['deadline', 'failover'],
};

// Guards whose first argument is a LIST of providers rather than one URL. Their
// whole point is that several hosts back one read, so each entry is recorded as
// its own call site: that is what makes a failover chain visible per upstream
// instead of collapsing to a single anonymous row.
export const LIST_GUARDS = new Set(['fetchFirst', 'fetchFirstOrNull', 'fetchAnyJson']);

export const PROTECTIONS = ['deadline', 'retry', 'failover', 'lastGood', 'breaker'];

// A relative URL, or one aimed at this machine, is our own origin: covered by
// the same-origin client rather than by upstream failover, so it is out of scope.
const INTERNAL_URL_RE = /^(?:\/|https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|(?:[a-z0-9-]+\.)*three\.ws))/i;

// Marks the position of a `${...}` hole in a reconstructed template literal.
const HOLE = '__EXPR__';

/** Hostname for a URL-ish string, or null when it is relative or unknowable. */
export function hostOf(raw) {
	if (typeof raw !== 'string') return null;
	const m = raw.match(/^https?:\/\/([^/?#]+)/i);
	return m ? m[1].toLowerCase() : null;
}

// A template literal's static skeleton: `${BASE}/coins/${mint}` becomes
// "<HOLE>/coins/<HOLE>", which is enough to recognise an absolute URL and to
// name the upstream whenever the host half is written literally.
function staticText(node, consts = null) {
	if (!node) return '';
	if (node.type === 'Literal') return typeof node.value === 'string' ? node.value : '';
	if (node.type === 'TemplateLiteral') {
		// Substitute a known module-level constant into its hole so
		// `${PUMP_BASE}/coins/x` is attributed to the host PUMP_BASE holds,
		// instead of collapsing into an anonymous "dynamic" row.
		return node.quasis
			.map((q, i) => {
				if (i >= node.expressions.length) return q.value.cooked;
				const filled = staticText(node.expressions[i], consts);
				return q.value.cooked + (filled && filled !== HOLE ? filled : HOLE);
			})
			.join('');
	}
	if (node.type === 'BinaryExpression' && node.operator === '+') {
		return staticText(node.left, consts) + staticText(node.right, consts);
	}
	if (node.type === 'Identifier') {
		const known = consts?.get(node.name);
		return known !== undefined ? known : HOLE;
	}
	if (node.type === 'MemberExpression') return HOLE;
	return '';
}

/** Does this options-object AST node carry a deadline? */
function objectHasDeadline(node) {
	if (!node || node.type !== 'ObjectExpression') return false;
	return node.properties.some((p) => {
		if (p.type === 'SpreadElement') return false;
		const key = p.key?.name ?? p.key?.value;
		// `signal: x`, the `signal` shorthand, and an explicit timeout all count.
		return key === 'signal' || key === 'timeout' || key === 'timeoutMs';
	});
}

function calleeName(node) {
	if (!node) return null;
	if (node.type === 'Identifier') return node.name;
	if (node.type === 'MemberExpression') return node.property?.name ?? null;
	return null;
}

function displayUrl(text) {
	return text.split(HOLE).join('${}');
}

/**
 * Analyze one source file.
 *
 * @param {string} code
 * @param {string} file  path used for reporting
 * @returns {{ callSites: Array<object>, parseError: string | null }}
 */
export function analyzeSource(code, file, resolveImported = null) {
	let ast;
	try {
		ast = acorn.parse(code, {
			ecmaVersion: 'latest',
			sourceType: 'module',
			allowAwaitOutsideFunction: true,
			allowHashBang: true,
			allowReturnOutsideFunction: true,
			locations: true,
		});
	} catch (err) {
		return { callSites: [], parseError: err.message };
	}

	// Which guard helpers this file imports, so a bare call to one is
	// attributable to the shared implementation rather than to a local function
	// that happens to share its name.
	// Module-level `const X = 'https://...'` (and simple concatenations of them)
	// are the base URLs nearly every call site is written against, so resolving
	// them is what turns a wall of "dynamic" rows into named upstreams.
	const consts = new Map();
	// Provider chains are frequently hoisted to a module constant
	// (`export const PROVIDERS = [...]`) and passed to fetchFirst by name, so the
	// array node has to be resolvable from the identifier or the entire chain is
	// invisible to the audit.
	const arrayConsts = new Map();
	for (const stmt of ast.body || []) {
		const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt;
		if (!decl || decl.type !== 'VariableDeclaration') continue;
		for (const d of decl.declarations) {
			if (d.id?.type !== 'Identifier' || !d.init) continue;
			if (d.init.type === 'ArrayExpression') arrayConsts.set(d.id.name, d.init);
			const text = staticText(d.init, consts);
			if (text && !text.includes(HOLE)) consts.set(d.id.name, text);
		}
	}

	const imported = new Set();
	// local binding name -> { from, name }, so a URL built on an imported base
	// constant can be resolved against the module that exports it.
	const importBindings = new Map();
	walkWithAncestors(ast, (n) => {
		if (n.type !== 'ImportDeclaration') return;
		const from = typeof n.source?.value === 'string' ? n.source.value : null;
		for (const spec of n.specifiers || []) {
			const name = spec.imported?.name ?? spec.local?.name;
			if (name) imported.add(name);
			if (from && spec.local?.name) {
				importBindings.set(spec.local.name, { from, name: spec.imported?.name ?? spec.local.name });
			}
		}
	});

	// Imported constants resolve through the caller-supplied resolver, which the
	// two-pass driver backs with every exported string constant in the repo.
	if (resolveImported) {
		for (const [local, ref] of importBindings) {
			const value = resolveImported(file, ref.from, ref.name);
			if (typeof value === 'string' && value && !consts.has(local)) consts.set(local, value);
		}
	}

	const callSites = [];

	// A guard call anywhere up the ancestor chain puts its protections in scope
	// for the raw fetch it wraps: `withRetry(() => fetch(url))` is one guarded
	// site, not a guard plus a naked fetch. Tracking ancestors is what tells
	// those two shapes apart.
	walkWithAncestors(ast, (node, ancestors) => {
		if (node.type !== 'CallExpression') return;
		{
			const name = calleeName(node.callee);
			if (!name) return;

			const inherited = new Set();
			for (const a of ancestors) {
				if (a === node || a.type !== 'CallExpression') continue;
				const outer = calleeName(a.callee);
				if (outer && GUARDS[outer] && imported.has(outer)) {
					for (const g of GUARDS[outer]) inherited.add(g);
				}
			}

			const isGuard = Boolean(GUARDS[name]) && imported.has(name);
			if (!isGuard && name !== 'fetch') return;

			// A provider-list guard: unpack the array so every host in the chain is
			// counted, each carrying the chain's protections.
			if (isGuard && LIST_GUARDS.has(name)) {
				let arr = node.arguments[0];
				if (arr?.type === 'Identifier') arr = arrayConsts.get(arr.name) ?? arr;
				if (arr?.type !== 'ArrayExpression') return;
				const chainProtections = new Set(inherited);
				for (const g of GUARDS[name]) chainProtections.add(g);
				for (const el of arr.elements) {
					if (!el) continue;
					// Either a bare URL string or a { name, url, parse } provider object.
					let entryUrl = '';
					if (el.type === 'ObjectExpression') {
						const urlProp = el.properties.find(
							(pr) => pr.type !== 'SpreadElement' && (pr.key?.name ?? pr.key?.value) === 'url',
						);
						entryUrl = urlProp ? staticText(urlProp.value, consts) : '';
					} else {
						entryUrl = staticText(el, consts);
					}
					if (!entryUrl || !entryUrl.includes('://')) continue;
					callSites.push({
						file,
						line: (el.loc ?? node.loc).start.line,
						via: name,
						host: hostOf(entryUrl) ?? 'dynamic',
						url: displayUrl(entryUrl).slice(0, 120),
						protections: [...chainProtections].sort(),
					});
				}
				return;
			}

			const urlText = staticText(node.arguments[0], consts);
			if (!urlText || INTERNAL_URL_RE.test(urlText)) return;
			// Only grade calls we can PROVE leave this origin. A bare `fetch(path)`
			// or a `${base}/api/x` is same-origin or unknowable, and counting those
			// as unguarded upstreams buries the real ones: an earlier pass of this
			// analyzer reported 513 unbounded calls, of which 507 were same-origin.
			// A scheme in the resolved text is the proof; anything else is skipped.
			if (!urlText.includes('://')) return;
			const host = hostOf(urlText);

			const protections = new Set(inherited);
			if (isGuard) for (const g of GUARDS[name]) protections.add(g);
			// An explicit per-call deadline counts wherever it appears.
			for (const arg of node.arguments.slice(1)) {
				if (objectHasDeadline(arg)) protections.add('deadline');
			}

			callSites.push({
				file,
				line: node.loc.start.line,
				via: isGuard ? name : 'fetch',
				host: host ?? 'dynamic',
				url: displayUrl(urlText).slice(0, 120),
				protections: [...protections].sort(),
			});
		}
	});

	return { callSites, parseError: null };
}

/**
 * Every module-level string constant a file defines, exported or not, resolved
 * as far as literal concatenation allows. Pass 1 of the two-pass analysis.
 * @returns {Map<string, string>}
 */
export function collectStringConstants(code) {
	const out = new Map();
	let ast;
	try {
		ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
	} catch {
		return out;
	}
	for (const stmt of ast.body || []) {
		const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt;
		if (!decl || decl.type !== 'VariableDeclaration') continue;
		for (const d of decl.declarations) {
			if (d.id?.type !== 'Identifier' || !d.init) continue;
			const text = staticText(d.init, out);
			if (text && !text.includes(HOLE)) out.set(d.id.name, text);
		}
	}
	return out;
}

/**
 * Analyze a list of absolute paths, reported relative to `root`.
 * @returns {{ callSites: Array<object>, parseErrors: Array<object> }}
 */
export function analyzeFiles(files, root) {
	const callSites = [];
	const parseErrors = [];

	// Pass 1: every module's string constants. Base URLs in this repo are
	// overwhelmingly `export const PUMP_FRONTEND_BASE = 'https://...'` in one
	// module and imported everywhere else, so without this pass the majority of
	// call sites cannot be attributed to the host they actually talk to.
	const sources = new Map();
	const constsByFile = new Map();
	for (const abs of files) {
		let code;
		try {
			code = readFileSync(abs, 'utf8');
		} catch {
			continue;
		}
		sources.set(abs, code);
		constsByFile.set(abs, collectStringConstants(code));
	}

	const byRel = new Map([...sources.keys()].map((abs) => [relative(root, abs), abs]));

	// Resolve `import { NAME } from './x.js'` against pass 1, trying the
	// extensions and index forms Node would.
	const resolveImported = (fromRel, spec, name) => {
		if (!spec.startsWith('.')) return undefined;
		const baseDir = dirname(resolve(root, fromRel));
		const target = resolve(baseDir, spec);
		const candidates = [
			target,
			`${target}.js`,
			`${target}.mjs`,
			join(target, 'index.js'),
			join(target, 'index.mjs'),
		];
		for (const cand of candidates) {
			const consts = constsByFile.get(cand);
			if (consts?.has(name)) return consts.get(name);
		}
		return undefined;
	};

	// Pass 2: grade every call site with imported constants resolved.
	for (const [abs, code] of sources) {
		const rel = relative(root, abs);
		const { callSites: found, parseError } = analyzeSource(code, rel, resolveImported);
		if (parseError) parseErrors.push({ file: rel, error: parseError });
		callSites.push(...found);
	}
	return { callSites, parseErrors, filesScanned: sources.size, byRel };
}

/**
 * A call site's grade. `deadline` is the floor, because without one a single
 * stalled socket outlives the request that opened it and no other protection
 * ever gets a turn. Above the floor, what earns a grade is having somewhere else
 * to go (failover) or something to serve (lastGood).
 *
 *   A  bounded, and survives the upstream being down
 *   B  bounded, with one way to survive
 *   C  bounded, and re-tries or trips, but has no second source
 *   D  bounded only
 *   F  unbounded: can hang the request
 */
export function gradeOf(site) {
	const p = new Set(site.protections);
	if (!p.has('deadline')) return 'F';
	if (p.has('failover') && (p.has('lastGood') || p.has('retry'))) return 'A';
	if (p.has('failover') || p.has('lastGood')) return 'B';
	if (p.has('retry') || p.has('breaker')) return 'C';
	return 'D';
}

/** Roll call sites up per upstream host, worst grade first. */
export function byHost(callSites) {
	const order = { F: 0, D: 1, C: 2, B: 3, A: 4 };
	const hosts = new Map();
	for (const site of callSites) {
		let h = hosts.get(site.host);
		if (!h) {
			h = { host: site.host, sites: 0, worst: 'A', grades: { A: 0, B: 0, C: 0, D: 0, F: 0 } };
			hosts.set(site.host, h);
		}
		const g = gradeOf(site);
		h.sites += 1;
		h.grades[g] += 1;
		if (order[g] < order[h.worst]) h.worst = g;
	}
	return [...hosts.values()].sort(
		(a, b) => order[a.worst] - order[b.worst] || b.sites - a.sites,
	);
}