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.

12.3 KB
Raw Blame
/**
 * Sub-resource handler dispatch + ownership gating for the three agent modules
 * that are never routed directly: api/agents/orders.js and api/agents/portfolio.js
 * (dispatched by api/agents/[id].js) and api/agents/patronage.js (dispatched by
 * api/agents/solana-wallet.js). vercel.json rewrites every
 * /api/agents/<segment>... path to api/agents/[id].js, so these modules are only
 * ever entered as handler(req, res, agentId, action).
 *
 * The engines behind them are covered by orders-engine.test.js, portfolio.test.js,
 * and patronage.test.js. What is pinned here is the layer above: which action maps
 * to which behaviour, and that a visitor can never read or mutate another owner's
 * orders, portfolio, or perk ladder.
 */

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

const OWNER = 'user-owner';
const AGENT = '11111111-2222-4333-8444-555555555555';
const ORDER = '99999999-8888-4777-8666-555555555555';
// $THREE, the only coin this platform references.
const THREE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';

let sessionUser = { id: OWNER };
let agentRow = { id: AGENT, user_id: OWNER, name: 'Test Agent', meta: { solana_address: THREE } };

// The real-funds agreement gate is covered by tests/real-funds-agreement.test.js;
// here the account has signed, so the handler's own guards are what is under test.
vi.mock('../api/_lib/real-funds-agreement.js', () => ({
	requireRealFundsAgreement: vi.fn(async () => true),
	currentSignatureFor: vi.fn(async () => ({ signedAt: '2026-09-17T00:00:00.000Z', signatureName: 'Test Signer', context: null })),
	agreementRequirement: () => ({ version: 2, sign_url: 'https://three.ws/legal/agreements', documents: [] }),
}));

vi.mock('../api/_lib/http.js', () => ({
	wrap: (fn) => fn,
	cors: () => false,
	method: (req, res, allowed) => {
		if (allowed.includes(req.method)) return true;
		res._json = { status: 405, body: { error: 'method_not_allowed' } };
		return false;
	},
	readJson: async (req) => req.body ?? {},
	rateLimited: (res) => {
		res._json = { status: 429, body: { error: 'rate_limited' } };
		return res;
	},
	error: (res, status, code, message, extra = {}) => {
		res._json = { status, body: { error: code, error_description: message, ...extra } };
		return res;
	},
	json: (res, status, body) => {
		res._json = { status, body };
		return res;
	},
	serverError: (res, status, code) => {
		res._json = { status, body: { error: code } };
		return res;
	},
}));

vi.mock('../api/_lib/rate-limit.js', () => ({
	limits: {
		walletRead: vi.fn(async () => ({ success: true })),
		tradePerUser: vi.fn(async () => ({ success: true })),
		agentProfileIp: vi.fn(async () => ({ success: true })),
	},
	clientIp: () => '1.2.3.4',
}));

vi.mock('../api/_lib/auth.js', () => ({
	getSessionUser: vi.fn(async () => sessionUser),
	authenticateBearer: vi.fn(async () => null),
	extractBearer: vi.fn(() => null),
}));

vi.mock('../api/_lib/db.js', () => ({
	sql: (strings) => {
		const text = strings.join(' ');
		if (/from agent_identities/i.test(text)) return Promise.resolve(agentRow ? [agentRow] : []);
		return Promise.resolve([]);
	},
}));

vi.mock('../api/_lib/csrf.js', () => ({ requireCsrf: vi.fn(async () => true) }));

// Orders dependencies. The pure model (normalizeOrder, describeOrder) stays real
// so the 422 case below exercises the actual validator.
vi.mock('../api/_lib/orders.js', async (importOriginal) => {
	const actual = await importOriginal();
	return {
		...actual,
		listOrders: vi.fn(async () => []),
		ordersSummary: vi.fn(async () => ({ total: 0, active: 0 })),
		getOrder: vi.fn(async () => null),
		listFills: vi.fn(async () => []),
		createOrder: vi.fn(async () => ({ id: ORDER })),
		updateOrder: vi.fn(async () => null),
		cancelOrder: vi.fn(async () => null),
		cancelAllOrders: vi.fn(async () => 0),
	};
});
vi.mock('../api/_lib/agent-wallet.js', () => ({
	getSolanaAddressBalances: vi.fn(async () => ({ sol: 0 })),
}));
vi.mock('../api/_lib/agent-trade-guards.js', () => ({
	getSpendLimits: () => ({ per_tx_usd: 10, daily_usd: 50, frozen: false }),
	getTradeLimits: () => ({ kill_switch: false, per_trade_sol: 1, daily_budget_sol: 5 }),
}));
vi.mock('../api/_lib/pump.js', () => ({ getPumpTradeClient: vi.fn(async () => ({ connection: {} })) }));
vi.mock('../api/_lib/trade-firewall.js', () => ({ assessTradeSafety: vi.fn(async () => null) }));
vi.mock('../workers/agent-orders/market.js', () => ({
	getSignals: vi.fn(async () => ({ market: null, signals: {} })),
	metricValue: vi.fn(() => null),
}));

// Portfolio dependencies.
const portfolioSnapshot = { t: 1, sol_usd: 75, net_worth: { sol: 0, usd: 0 }, holdings: [] };
vi.mock('../api/_lib/portfolio.js', () => ({
	getPortfolio: vi.fn(async () => portfolioSnapshot),
}));

// Patronage dependencies. The tier ladder and entitlement math stay real.
vi.mock('../api/_lib/patronage.js', async (importOriginal) => {
	const actual = await importOriginal();
	return {
		...actual,
		aggregatePatrons: vi.fn(async () => []),
		patronTotals: vi.fn(async () => ({ patrons: 0, usd: 0, supports: 0 })),
		patronStanding: vi.fn(async () => ({
			usd: 0, supportCount: 0, firstAt: null, lastAt: null, level: null,
			progress: { pct: 0, next: null, remainingUsd: 10 },
		})),
		listPerks: vi.fn(async () => []),
		resolvePatronName: vi.fn(async () => null),
		hiddenWallets: vi.fn(async () => new Set()),
	};
});
vi.mock('../api/_lib/siws.js', () => ({ verifySiwsSignature: vi.fn(() => false) }));
vi.mock('../api/_lib/audit.js', () => ({ logAudit: vi.fn() }));

const ordersHandler = (await import('../api/agents/orders.js')).default;
const portfolioHandler = (await import('../api/agents/portfolio.js')).default;
const patronageHandler = (await import('../api/agents/patronage.js')).default;
const { authenticateBearer, extractBearer } = await import('../api/_lib/auth.js');

function mkReq(method = 'GET', url = `/api/agents/${AGENT}/orders`, body) {
	return { method, url, headers: {}, body, on: () => {} };
}
function mkRes() {
	return { _json: null, setHeader() {}, writeHead() {}, flushHeaders() {}, write() {}, end() {} };
}

beforeEach(() => {
	sessionUser = { id: OWNER };
	agentRow = { id: AGENT, user_id: OWNER, name: 'Test Agent', meta: { solana_address: THREE } };
});

describe('api/agents/orders.js dispatch', () => {
	it('lists the owner orders with the live summary (main path)', async () => {
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, undefined);
		expect(res._json.status).toBe(200);
		expect(res._json.body.data.orders).toEqual([]);
		expect(res._json.body.data.summary.frozen).toBe(false);
		expect(res._json.body.data.summary.kill_switch).toBe(false);
	});

	it('serves the closed condition vocabulary on /schema', async () => {
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, 'schema');
		expect(res._json.status).toBe(200);
		expect(res._json.body.data.order_types).toContain('conditional');
		expect(res._json.body.data.number_ops).toContain('gte');
	});

	it('refuses a visitor who is not the owner (failure path)', async () => {
		sessionUser = { id: 'someone-else' };
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, undefined);
		expect(res._json.status).toBe(403);
		expect(res._json.body.error).toBe('forbidden');
	});

	it('refuses an anonymous caller before touching the agent row', async () => {
		sessionUser = null;
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, undefined);
		expect(res._json.status).toBe(401);
	});

	it('404s an unknown sub-resource rather than falling through to the list', async () => {
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, 'not-a-real-action');
		expect(res._json.status).toBe(404);
		expect(res._json.body.error_description).toMatch(/unknown orders sub-resource/);
	});

	it('rejects an unsupported method on a single order', async () => {
		const res = mkRes();
		await ordersHandler(mkReq('PATCH'), res, AGENT, ORDER);
		expect(res._json.status).toBe(405);
	});

	it('422s an order the engine cannot validate', async () => {
		const res = mkRes();
		await ordersHandler(mkReq('POST', `/api/agents/${AGENT}/orders`, { type: 'limit' }), res, AGENT, undefined);
		expect(res._json.status).toBe(422);
	});
});

// An app the owner connected over OAuth, or an API key, holds only the scopes
// it was granted. Creating or editing a live order commits the agent wallet to
// a trade, so without wallet:write it is refused; reading and cancelling are not.
describe('api/agents/orders.js with a bearer credential', () => {
	const asBearer = (scope) => {
		sessionUser = null;
		extractBearer.mockReturnValue('bearer-token');
		authenticateBearer.mockResolvedValue({ userId: OWNER, scope, source: 'oauth', clientId: 'mcp_grok' });
	};
	afterEach(() => {
		extractBearer.mockReturnValue(null);
		authenticateBearer.mockResolvedValue(null);
	});

	it('refuses to create an order for a connector that cannot spend', async () => {
		asBearer('avatars:read agents:write wallet:read');
		const res = mkRes();
		await ordersHandler(mkReq('POST', `/api/agents/${AGENT}/orders`, { type: 'limit' }), res, AGENT, undefined);
		expect(res._json.status).toBe(403);
		expect(res._json.body.error).toBe('insufficient_scope');
	});

	it('refuses to edit an order for a connector that cannot spend', async () => {
		asBearer('avatars:read');
		const res = mkRes();
		await ordersHandler(mkReq('PUT', `/api/agents/${AGENT}/orders/${ORDER}`, { slippage_bps: 5000 }), res, AGENT, ORDER);
		expect(res._json.status).toBe(403);
	});

	it('still lets that connector read the orders', async () => {
		asBearer('wallet:read');
		const res = mkRes();
		await ordersHandler(mkReq('GET'), res, AGENT, undefined);
		expect(res._json.status).toBe(200);
	});

	it('lets a credential holding wallet:write reach validation', async () => {
		asBearer('wallet:read wallet:write');
		const res = mkRes();
		await ordersHandler(mkReq('POST', `/api/agents/${AGENT}/orders`, { type: 'limit' }), res, AGENT, undefined);
		expect(res._json.status).toBe(422);
	});
});

describe('api/agents/portfolio.js dispatch', () => {
	it('returns the owner snapshot when no action is given (main path)', async () => {
		const res = mkRes();
		await portfolioHandler(mkReq('GET', `/api/agents/${AGENT}/portfolio`), res, AGENT, undefined);
		expect(res._json.status).toBe(200);
		expect(res._json.body.data).toBe(portfolioSnapshot);
	});

	it('404s an unknown sub-resource (failure path)', async () => {
		const res = mkRes();
		await portfolioHandler(mkReq('GET'), res, AGENT, 'bogus');
		expect(res._json.status).toBe(404);
	});

	it('never exposes another owner attribution ledger', async () => {
		sessionUser = { id: 'someone-else' };
		const res = mkRes();
		await portfolioHandler(mkReq('GET'), res, AGENT, undefined);
		expect(res._json.status).toBe(403);
	});
});

describe('api/agents/patronage.js dispatch', () => {
	it('serves the public ladder and wall on GET (main path)', async () => {
		sessionUser = null;
		const res = mkRes();
		await patronageHandler(mkReq('GET', `/api/agents/${AGENT}/solana/patronage`), res, AGENT);
		expect(res._json.status).toBe(200);
		expect(res._json.body.data.is_owner).toBe(false);
		expect(res._json.body.data.levels.map((l) => l.key)).toContain('benefactor');
		expect(res._json.body.data.wall).toEqual([]);
	});

	it('marks the owner so the editor can render its own payloads', async () => {
		const res = mkRes();
		await patronageHandler(mkReq('GET', `/api/agents/${AGENT}/solana/patronage`), res, AGENT);
		expect(res._json.status).toBe(200);
		expect(res._json.body.data.is_owner).toBe(true);
	});

	it('rejects an unknown POST op (failure path)', async () => {
		const res = mkRes();
		await patronageHandler(
			mkReq('POST', `/api/agents/${AGENT}/solana/patronage`, { op: 'nope' }),
			res,
			AGENT,
		);
		expect(res._json.status).toBe(400);
		expect(res._json.body.error_description).toMatch(/unknown op/);
	});

	it('will not unlock a perk without a wallet signature', async () => {
		const res = mkRes();
		await patronageHandler(
			mkReq('POST', `/api/agents/${AGENT}/solana/patronage`, { op: 'unlock', wallet: THREE }),
			res,
			AGENT,
		);
		expect(res._json.status).toBe(401);
		expect(res._json.body.error_description).toMatch(/missing signature/);
	});

	it('404s a patronage read for an agent that does not exist', async () => {
		agentRow = null;
		const res = mkRes();
		await patronageHandler(mkReq('GET', `/api/agents/${AGENT}/solana/patronage`), res, AGENT);
		expect(res._json.status).toBe(404);
	});
});