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.

6.2 KB
Raw Blame
// api/_mcp/payments.js and api/_mcp/embed-policy.js, the two small shared
// modules the MCP servers reach for on the paid path and the embed gate.
//
// payments.js is the single error boundary for every hand-rolled x402 MCP
// endpoint (/api/mcp, /api/mcp-3d, /api/mcp-agent, /api/mcp-bazaar,
// /api/ibm-mcp, /api/okx/3d/*). It has to tell three cases apart: a genuine
// "pay me" (402 with the full payment envelope), a client's own fault (the
// X402Error's own status and code), and an unexpected server fault (a 500 that
// leaks nothing but a support reference). Getting the third case wrong is how a
// driver stack trace reaches a paying agent, so all three are pinned here.
//
// embed-policy.js is the MCP surface's view of an agent's embed policy. The one
// thing render_avatar depends on is that a caller-supplied avatar id that is not
// a uuid never reaches the database.

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

const send402Mock = vi.fn(async (res) => {
	res.statusCode = 402;
	res.setHeader('content-type', 'application/json; charset=utf-8');
	res.end(JSON.stringify({ x402Version: 1, accepts: [] }));
});

vi.mock('../../api/_lib/x402-spec.js', async (importOriginal) => ({
	...(await importOriginal()),
	send402: (...a) => send402Mock(...a),
}));

const reportServerErrorMock = vi.fn(() => 'ref_abc123');
vi.mock('../../api/_lib/http.js', async (importOriginal) => ({
	...(await importOriginal()),
	reportServerError: (...a) => reportServerErrorMock(...a),
}));

const sqlMock = vi.fn(async () => []);
vi.mock('../../api/_lib/db.js', () => ({
	sql: (...a) => sqlMock(...a),
	isDbUnavailableError: () => false,
	isDbCapacityError: () => false,
}));

const { X402Error } = await import('../../api/_lib/x402-errors.js');
const { sendX402Error, reservePaymentProof } = await import('../../api/_mcp/payments.js');
const { readMcpPolicyByAvatar } = await import('../../api/_mcp/embed-policy.js');

function mkRes() {
	const headers = {};
	return {
		statusCode: 200,
		body: null,
		headers,
		setHeader(k, v) {
			headers[k.toLowerCase()] = v;
		},
		getHeader(k) {
			return headers[k.toLowerCase()];
		},
		end(body) {
			this.body = body;
		},
	};
}

const CTX = { resourceUrl: 'https://three.ws/api/mcp', accepts: [{ scheme: 'exact' }] };

beforeEach(() => {
	send402Mock.mockClear();
	reportServerErrorMock.mockClear();
	sqlMock.mockReset();
	sqlMock.mockResolvedValue([]);
});

// ── payments.js ─────────────────────────────────────────────────────────────
describe('sendX402Error', () => {
	it('re-issues the full payment envelope for a 402 X402Error', async () => {
		const res = mkRes();
		await sendX402Error(res, CTX, new X402Error('payment_required', 'pay first', 402));

		expect(send402Mock).toHaveBeenCalledTimes(1);
		const [, opts] = send402Mock.mock.calls[0];
		expect(opts.resourceUrl).toBe(CTX.resourceUrl);
		expect(opts.accepts).toBe(CTX.accepts);
		expect(opts.error).toBe('pay first');
		expect(res.statusCode).toBe(402);
		// A payment fault is the caller's problem, never ours to report.
		expect(reportServerErrorMock).not.toHaveBeenCalled();
	});

	it('passes a non-402 X402Error through with its own status and code', async () => {
		const res = mkRes();
		await sendX402Error(res, CTX, new X402Error('unsupported_network', 'unsupported network: foo', 400));

		expect(send402Mock).not.toHaveBeenCalled();
		expect(res.statusCode).toBe(400);
		expect(res.headers['content-type']).toBe('application/json; charset=utf-8');
		expect(JSON.parse(res.body)).toEqual({
			error: 'unsupported_network',
			error_description: 'unsupported network: foo',
		});
		expect(reportServerErrorMock).not.toHaveBeenCalled();
	});

	// Failure path: an unexpected fault must reach the shared boundary and come
	// back as an opaque 500 carrying only a support reference.
	it('routes an unexpected fault to the error boundary and leaks nothing', async () => {
		const res = mkRes();
		const err = new Error('relation "x402_settlements" does not exist');
		err.code = '42P01';
		await sendX402Error(res, CTX, err);

		expect(reportServerErrorMock).toHaveBeenCalledTimes(1);
		const [reported, opts] = reportServerErrorMock.mock.calls[0];
		expect(reported).toBe(err);
		expect(opts.code).toBe('mcp_x402_failed');
		expect(opts.context).toEqual({ resourceUrl: CTX.resourceUrl });

		expect(res.statusCode).toBe(500);
		const body = JSON.parse(res.body);
		expect(body.error).toBe('internal');
		expect(body.ref).toBe('ref_abc123');
		expect(body.error_description).toContain('ref_abc123');
		// The driver detail stays server-side.
		expect(res.body).not.toContain('x402_settlements');
		expect(res.body).not.toContain('42P01');
		expect(send402Mock).not.toHaveBeenCalled();
	});

	it('re-exports the shared replay guard so every MCP server uses one implementation', () => {
		expect(typeof reservePaymentProof).toBe('function');
	});
});

// ── embed-policy.js ─────────────────────────────────────────────────────────
describe('readMcpPolicyByAvatar', () => {
	it('returns the normalized policy for an avatar owned by a registered agent', async () => {
		sqlMock.mockResolvedValue([{ embed_policy: { surfaces: { mcp: false } } }]);
		const policy = await readMcpPolicyByAvatar('11111111-1111-4111-8111-111111111111');

		expect(sqlMock).toHaveBeenCalledTimes(1);
		expect(policy).toBeTruthy();
		// Normalization fills the rest of the policy in around the stored override.
		expect(policy.surfaces.mcp).toBe(false);
		expect(policy.version).toBeDefined();
		expect(policy.origins).toBeDefined();
	});

	it('returns null when no agent claims the avatar, leaving the surface open', async () => {
		sqlMock.mockResolvedValue([]);
		expect(await readMcpPolicyByAvatar('11111111-1111-4111-8111-111111111111')).toBeNull();
	});

	// Failure path: a caller-supplied id that is not a uuid never reaches the DB.
	it('rejects a non-uuid avatar id without querying', async () => {
		for (const bad of ["'; DROP TABLE avatars; --", '', 'not-a-uuid', null, undefined]) {
			expect(await readMcpPolicyByAvatar(bad)).toBeNull();
		}
		expect(sqlMock).not.toHaveBeenCalled();
	});
});