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
// /api/evm-rpc: the browser's same-origin EVM JSON-RPC proxy. Locks down the
// read-only method allowlist and the endpoint rotation, so a keyless host that
// answers 403 (or a 200 carrying a non-JSON-RPC body) never reaches the browser.

import { describe, it, expect, vi, beforeEach } from 'vitest';

vi.mock('../api/_lib/http.js', () => ({
	wrap: (fn) => fn,
	cors: () => false,
	method: () => true,
	readJson: async (req) => req.body,
	rateLimited: (res) => {
		res._json = { status: 429, body: { error: 'rate_limited' } };
		return res;
	},
	error: (res, status, code, message) => {
		res._json = { status, body: { error: code, error_description: message } };
		return res;
	},
}));
vi.mock('../api/_lib/rate-limit.js', () => ({
	limits: {
		evmRpcIp: vi.fn(async () => ({ success: true })),
		evmRpcGlobal: vi.fn(async () => ({ success: true })),
	},
	clientIp: () => '1.2.3.4',
}));
const endpoints = ['https://a.test/', 'https://b.test/', 'https://c.test/'];
vi.mock('../api/_lib/evm/rpc.js', () => ({
	evmRpcEndpoints: vi.fn(() => endpoints),
}));

import handler, { rejectReason, forwardWithRotation, ALLOWED_METHODS } from '../api/evm-rpc.js';

const OK = { jsonrpc: '2.0', id: 1, result: '0x1' };
const jsonRes = (body, status = 200) =>
	new Response(typeof body === 'string' ? body : JSON.stringify(body), { status });

function makeRes() {
	const headers = {};
	return {
		statusCode: 0,
		setHeader: (k, v) => { headers[k] = v; },
		end(text) { this.text = text; },
		headers,
	};
}

describe('/api/evm-rpc method allowlist', () => {
	it('accepts every read-only method and refuses everything else', () => {
		for (const m of ALLOWED_METHODS) {
			if (m === 'eth_getLogs') continue; // scoped separately: see read cost bounds
			expect(rejectReason({ jsonrpc: '2.0', id: 1, method: m, params: [] })).toBeNull();
		}
		expect(rejectReason({ method: 'eth_sendRawTransaction', params: ['0x'] })).toBe('method_not_allowed');
		expect(rejectReason({ method: 'eth_subscribe' })).toBe('method_not_allowed');
		expect(rejectReason({ method: 'eth_newFilter' })).toBe('method_not_allowed');
	});

	it('refuses malformed, empty and oversized batches', () => {
		expect(rejectReason([])).toBe('empty_request');
		expect(rejectReason('nope')).toBe('malformed_request');
		expect(rejectReason({ id: 1 })).toBe('malformed_request');
		expect(rejectReason(Array.from({ length: 11 }, () => ({ method: 'eth_chainId' })))).toBe('batch_too_large');
		expect(rejectReason([{ method: 'eth_chainId' }, { method: 'eth_sendRawTransaction' }])).toBe('method_not_allowed');
	});

	it('answers 403 for a write method and 400 for an unknown chain through the handler', async () => {
		let res = makeRes();
		await handler({ url: '/api/evm-rpc?chainId=1', body: { method: 'eth_sendRawTransaction' } }, res);
		expect(res._json.status).toBe(403);
		expect(res._json.body.error).toBe('method_not_allowed');

		res = makeRes();
		await handler({ url: '/api/evm-rpc?chainId=999999', body: { method: 'eth_chainId' } }, res);
		expect(res._json.status).toBe(400);
		expect(res._json.body.error).toBe('unknown_chain');
	});
});

describe('/api/evm-rpc read cost bounds', () => {
	const logs = (f) => ({ jsonrpc: '2.0', id: 1, method: 'eth_getLogs', params: [f] });
	const ADDR = '0x' + '11'.repeat(20);

	it('refuses eth_getLogs without an address or blockHash', () => {
		expect(rejectReason(logs({ fromBlock: '0x1', toBlock: '0x2' }))).toBe('logs_scope_required');
	});

	it('refuses eth_getLogs spanning more than 2000 blocks or with open-ended tags', () => {
		expect(rejectReason(logs({ address: ADDR, fromBlock: '0x0', toBlock: '0xffffff' }))).toBe('logs_range_too_large');
		expect(rejectReason(logs({ address: ADDR, fromBlock: '0x0', toBlock: 'latest' }))).toBe('logs_range_too_large');
		expect(rejectReason(logs({ address: ADDR }))).toBe('logs_range_too_large');
	});

	it('accepts a bounded eth_getLogs and a blockHash query', () => {
		expect(rejectReason(logs({ address: ADDR, fromBlock: '0x10', toBlock: '0x20' }))).toBeNull();
		expect(rejectReason(logs({ blockHash: '0x' + 'ab'.repeat(32) }))).toBeNull();
	});

	it('refuses eth_call with state-override params', () => {
		const call = { jsonrpc: '2.0', id: 1, method: 'eth_call', params: [{ to: ADDR }, 'latest', {}] };
		expect(rejectReason(call)).toBe('params_not_allowed');
		expect(rejectReason({ ...call, params: [{ to: ADDR }, 'latest'] })).toBeNull();
	});

	it('charges the per-IP limiter once per batch entry', async () => {
		const { limits } = await import('../api/_lib/rate-limit.js');
		limits.evmRpcIp.mockClear();
		const res = makeRes();
		const batch = Array.from({ length: 5 }, (_, i) => ({ jsonrpc: '2.0', id: i, method: 'eth_chainId' }));
		await handler({ url: '/api/evm-rpc?chainId=1', body: batch }, res);
		expect(limits.evmRpcIp).toHaveBeenCalledTimes(5);
	});
});

describe('/api/evm-rpc endpoint rotation', () => {
	let calls;
	beforeEach(() => { calls = []; });

	it('rotates past a 403, a non-JSON-RPC 200 body and a network error to the first good host', async () => {
		const fetchImpl = vi.fn(async (url) => {
			calls.push(url);
			if (url === 'https://a.test/') return jsonRes('forbidden', 403);
			if (url === 'https://b.test/') return jsonRes({ error: 'Unauthorized: You must authenticate your request with an API key' });
			return jsonRes(OK);
		});
		const out = await forwardWithRotation(endpoints, { jsonrpc: '2.0', id: 1, method: 'eth_chainId' }, { fetchImpl });
		expect(out.url).toBe('https://c.test/');
		expect(JSON.parse(out.text)).toEqual(OK);
		expect(calls).toEqual(endpoints);
	});

	it('rotates past a timeout', async () => {
		const fetchImpl = vi.fn((url, init) => {
			calls.push(url);
			if (url === 'https://a.test/') {
				return new Promise((_, reject) => {
					init.signal.addEventListener('abort', () => reject(new Error('aborted')));
				});
			}
			return Promise.resolve(jsonRes(OK));
		});
		const out = await forwardWithRotation(endpoints, { method: 'eth_blockNumber' }, { fetchImpl, timeoutMs: 20 });
		expect(out.url).toBe('https://b.test/');
		expect(calls).toEqual(['https://a.test/', 'https://b.test/']);
	});

	it('returns a legitimate JSON-RPC error envelope without rotating (a revert is an answer, not an outage)', async () => {
		const revert = { jsonrpc: '2.0', id: 1, error: { code: 3, message: 'execution reverted' } };
		const fetchImpl = vi.fn(async () => jsonRes(revert));
		const out = await forwardWithRotation(endpoints, { method: 'eth_call' }, { fetchImpl });
		expect(out.url).toBe('https://a.test/');
		expect(fetchImpl).toHaveBeenCalledTimes(1);
	});

	it('answers 502 upstream_error once every endpoint has failed', async () => {
		const orig = global.fetch;
		global.fetch = vi.fn(async () => jsonRes('nope', 500));
		try {
			const res = makeRes();
			await handler({ url: '/api/evm-rpc?chainId=8453', body: { jsonrpc: '2.0', id: 1, method: 'eth_chainId' } }, res);
			expect(res._json.status).toBe(502);
			expect(res._json.body.error).toBe('upstream_error');
			expect(global.fetch).toHaveBeenCalledTimes(endpoints.length);
		} finally {
			global.fetch = orig;
		}
	});

	it('streams the first good upstream body through with no-store caching', async () => {
		const orig = global.fetch;
		global.fetch = vi.fn(async () => jsonRes(OK));
		try {
			const res = makeRes();
			await handler({ url: '/api/evm-rpc?chainId=1', body: { jsonrpc: '2.0', id: 1, method: 'eth_chainId' } }, res);
			expect(res.statusCode).toBe(200);
			expect(res.headers['cache-control']).toBe('no-store');
			expect(JSON.parse(res.text)).toEqual(OK);
		} finally {
			global.fetch = orig;
		}
	});
});