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.

16.1 KB
Raw Blame
// The master wallet page (/wallet) and its API client.
//
// These lock in the properties that make a spend surface safe to ship:
//
//   1. Reads carry no CSRF token; every write carries a fresh one. The four
//      /api/user/wallet routes reject a token-less POST with 403, so a missing
//      header is not a style issue, it is a broken button.
//   2. Reviewing a send NEVER signs. The review step must call the endpoint
//      with `simulate: true`, which is what makes the confirmation numbers real
//      instead of a browser guess, and what guarantees pressing "Review" cannot
//      move money.
//   3. A wallet that has never been provisioned is a SUCCESS, not an error.
//      `{"wallet": null}` has to render the create-wallet invitation. Treating
//      it as a failure is how this feature stayed invisible in the first place.
//   4. The page markup is wired to the module that drives it, with the routing
//      and page-index entries that make it reachable.
//
// The client is tested against a stubbed fetch rather than the network: these
// assert the request contract (method, path, headers, body), which is exactly
// the part that regressed historically. The endpoints themselves are exercised
// against real Solana state by docs/user-wallet.md's curl examples.

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { readFileSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const read = (p) => readFileSync(resolve(ROOT, p), 'utf8');

const CSRF = 'tok_master_wallet';

/** Stub fetch, recording every call so the request contract can be asserted. */
function stubFetch(handler) {
	const calls = [];
	globalThis.fetch = vi.fn(async (path, init = {}) => {
		calls.push({ path: String(path), init });
		if (String(path).includes('/api/csrf-token')) {
			return new Response(JSON.stringify({ data: { token: CSRF } }), {
				status: 200,
				headers: { 'content-type': 'application/json' },
			});
		}
		return handler(String(path), init);
	});
	return calls;
}

function jsonResponse(body, status = 200) {
	return new Response(JSON.stringify(body), {
		status,
		headers: { 'content-type': 'application/json' },
	});
}

async function loadClient() {
	// Fresh module per test: src/api.js caches CSRF tokens in module scope.
	vi.resetModules();
	return import('../src/wallet-api.js');
}

describe('master wallet API client', () => {
	beforeEach(() => {
		vi.restoreAllMocks();
	});

	it('reads the wallet without a CSRF token', async () => {
		const calls = stubFetch(() => jsonResponse({ wallet: null }));
		const { fetchWallet } = await loadClient();
		const res = await fetchWallet();

		expect(res.ok).toBe(true);
		expect(res.data).toEqual({ wallet: null });
		const call = calls.find((c) => c.path.endsWith('/api/user/wallet'));
		expect(call).toBeTruthy();
		expect(call.init.method || 'GET').toBe('GET');
		expect(call.init.headers?.['x-csrf-token']).toBeUndefined();
		expect(calls.some((c) => c.path.includes('/api/csrf-token'))).toBe(false);
	});

	it('sends a CSRF token when creating the wallet', async () => {
		const calls = stubFetch(() => jsonResponse({ wallet: { created: true } }, 201));
		const { createWallet } = await loadClient();
		const res = await createWallet();

		expect(res.ok).toBe(true);
		expect(res.status).toBe(201);
		const call = calls.find((c) => c.path.endsWith('/api/user/wallet') && c.init.method === 'POST');
		expect(call.init.headers['x-csrf-token']).toBe(CSRF);
	});

	// The property that makes the confirm step trustworthy: reviewing a transfer
	// must be incapable of moving funds.
	it('previewSend asks the server to simulate, and never omits the flag', async () => {
		const calls = stubFetch(() =>
			jsonResponse({ simulation: { asset: 'SOL', destination: 'Dest111', human_amount: 0.5 } }),
		);
		const { previewSend } = await loadClient();
		const res = await previewSend({ destination: 'Dest111', asset: 'SOL', amount: '0.5' });

		expect(res.ok).toBe(true);
		const call = calls.find((c) => c.path.includes('/api/user/wallet/send'));
		const body = JSON.parse(call.init.body);
		expect(body.simulate).toBe(true);
		expect(body.destination).toBe('Dest111');
		expect(call.init.headers['x-csrf-token']).toBe(CSRF);
	});

	it('send omits the simulate flag so the server broadcasts', async () => {
		const calls = stubFetch(() => jsonResponse({ signature: 'sig123', human_amount: 0.5 }));
		const { send } = await loadClient();
		await send({ destination: 'Dest111', asset: 'SOL', amount: '0.5' });

		const call = calls.find((c) => c.path.includes('/api/user/wallet/send'));
		expect(JSON.parse(call.init.body).simulate).toBeUndefined();
	});

	it('fundAgent posts the agent id the endpoint expects', async () => {
		const calls = stubFetch(() => jsonResponse({ signature: 'sig456' }));
		const { fundAgent } = await loadClient();
		await fundAgent({ agentId: 'agt_1', asset: 'USDC', amount: '5' });

		const call = calls.find((c) => c.path.includes('/api/user/wallet/fund-agent'));
		const body = JSON.parse(call.init.body);
		expect(body.agent_id).toBe('agt_1');
		expect(body.asset).toBe('USDC');
		expect(call.init.headers['x-csrf-token']).toBe(CSRF);
	});

	it('clamps the history limit to what the endpoint accepts', async () => {
		const calls = stubFetch(() => jsonResponse({ history: [] }));
		const { fetchHistory } = await loadClient();
		await fetchHistory(500);
		await fetchHistory(0);

		const limits = calls
			.filter((c) => c.path.includes('/api/user/wallet/history'))
			.map((c) => Number(new URL(c.path, 'https://x').searchParams.get('limit')));
		expect(limits).toEqual([50, 20]);
	});

	// Every failure has to arrive as a value the page can render. A throw here
	// would surface as an unhandled rejection and a blank panel.
	it('turns an API error into a designed result instead of throwing', async () => {
		stubFetch(() =>
			jsonResponse({ error: 'insufficient_balance', error_description: 'too low' }, 400),
		);
		const { previewSend } = await loadClient();
		const res = await previewSend({ destination: 'D', asset: 'SOL', amount: '999' });

		expect(res.ok).toBe(false);
		expect(res.status).toBe(400);
		expect(res.code).toBe('insufficient_balance');
	});

	it('turns a network failure into a designed result instead of throwing', async () => {
		globalThis.fetch = vi.fn(async () => {
			throw new TypeError('Failed to fetch');
		});
		vi.resetModules();
		const { fetchWallet } = await import('../src/wallet-api.js');
		const res = await fetchWallet();

		expect(res.ok).toBe(false);
		expect(res.code).toBe('network_error');
	});
});

describe('master wallet page wiring', () => {
	const html = read('pages/wallet.html');
	const controller = read('src/master-wallet.js');

	it('mounts the controller on the root element it renders into', () => {
		expect(html).toContain('id="wlt-root"');
		expect(html).toContain('/src/master-wallet.js');
		expect(controller).toContain("getElementById('wlt-root')");
	});

	it('loads its own stylesheet and the shared shell', () => {
		expect(html).toContain('/master-wallet.css');
		expect(html).toContain('/style.css');
		expect(html).toContain('id="nav-container"');
		expect(html).toContain('id="footer-container"');
	});

	// A custodial wallet page must never be indexed or framed by a third party.
	it('is noindex', () => {
		expect(html).toMatch(/<meta name="robots" content="noindex"/);
	});

	it('renders a create invitation rather than an error when no wallet exists', () => {
		expect(controller).toContain("state.phase = 'empty'");
		expect(controller).toMatch(/do not have a master wallet yet/i);
		expect(controller).toContain("data-act=\"create\"");
	});

	it('designs every state, including signed out and failure', () => {
		for (const phase of ['loading', 'anon', 'empty', 'ready', 'error']) {
			expect(controller).toContain(`${phase}:`);
		}
		expect(controller).toContain('/login?next=');
	});

	// The confirm step is the spend gate. It must show what is being sent, to
	// whom, and on which network, before any broadcast call exists.
	it('requires an explicit confirmation that states amount, recipient and network', () => {
		expect(controller).toContain('Confirm this transfer');
		expect(controller).toContain('Nothing has been signed or sent yet');
		expect(controller).toContain('Solana mainnet');
		expect(controller).toContain("data-act=\"confirm\"");
		expect(controller).toContain("data-act=\"cancel\"");
	});

	it('escapes interpolated values so a chain-supplied string cannot inject markup', () => {
		expect(controller).toMatch(/function esc\(/);
		// Transaction summaries and addresses come from the chain, not from us.
		expect(controller).toContain('esc(t.summary');
		expect(controller).toContain('esc(t.explorer)');
	});

	it('keeps the external-wallet connector separate from the custodial page', () => {
		// src/wallet.js is the Phantom / Seed Vault connector. Importing it here
		// would put a browser wallet in front of a server-custodied one.
		expect(controller).not.toMatch(/from '\.\/wallet\.js'/);
		expect(read('src/wallet.js')).toContain('window.solana');
	});
});

describe('master wallet page is reachable', () => {
	it('is routed and built', () => {
		const vercel = JSON.parse(read('vercel.json'));
		const routed = vercel.routes.filter((r) => r.src === '/wallet' || r.src === '/wallet/');
		expect(routed).toHaveLength(2);
		for (const r of routed) expect(r.dest).toBe('/wallet.html');
		expect(read('vite.config.js')).toContain("wallet: resolve(__dirname, 'pages/wallet.html')");
	});

	it('is declared in the page index so the sitemap and changelog pick it up', () => {
		const pages = JSON.parse(read('data/pages.json'));
		const all = pages.sections.flatMap((s) => s.pages || []);
		const entry = all.find((p) => p.path === '/wallet');
		expect(entry).toBeTruthy();
		expect(entry.title).toBeTruthy();
		expect(entry.description.length).toBeGreaterThan(40);
		expect(entry.added).toBe('2026-07-30');
	});

	it('is linked from the dashboard sidebar so a signed-in user can find it', () => {
		const nav = read('src/dashboard-next/nav.js');
		expect(nav).toContain("path: '/wallet'");
		expect(nav).toMatch(/wallet:\s+'<svg/); // its icon exists
	});

	it('is documented', () => {
		const doc = read('docs/user-wallet.md');
		expect(doc).toContain('three.ws/wallet');
		expect(doc).toContain('src/master-wallet.js');
		expect(read('STRUCTURE.md')).toContain('pages/wallet.html');
	});
});

describe('reviewing a top-up prices it on the server and signs nothing', () => {
	beforeEach(() => {
		vi.restoreAllMocks();
	});

	it('sends simulate:true and the agent_id body key', async () => {
		const calls = stubFetch(() =>
			jsonResponse({ simulation: { human_amount: 4, usd_value: 4, agent_wallet: 'AgentSol' } }),
		);
		const { previewFundAgent } = await loadClient();
		const res = await previewFundAgent({ agentId: 'a-1', asset: 'USDC', amount: 'max' });

		expect(res.ok).toBe(true);
		const call = calls.find((c) => c.path.endsWith('/api/user/wallet/fund-agent'));
		const body = JSON.parse(call.init.body);
		expect(call.init.method).toBe('POST');
		expect(body.simulate).toBe(true);
		// snake_case: the handler reads body.agent_id, not agentId.
		expect(body.agent_id).toBe('a-1');
		expect(body).not.toHaveProperty('agentId');
		expect(call.init.headers['x-csrf-token']).toBe(CSRF);
	});

	it('omits simulate entirely on the real top-up', async () => {
		const calls = stubFetch(() => jsonResponse({ signature: 'sig' }));
		const { fundAgent } = await loadClient();
		await fundAgent({ agentId: 'a-1', asset: 'SOL', amount: '0.1' });

		const body = JSON.parse(
			calls.find((c) => c.path.endsWith('/api/user/wallet/fund-agent')).init.body,
		);
		// `simulate: false` would still be a truthy key some future handler could
		// misread. The broadcast path carries no simulate key at all.
		expect(body).not.toHaveProperty('simulate');
	});

	it('returns before the key is ever recovered on the simulate path', () => {
		const src = read('api/user/wallet/fund-agent.js');
		const simulateReturn = src.indexOf('if (simulate) {');
		const keyRecovery = src.indexOf('recoverSolanaAgentKeypair(mw.encrypted_solana_secret');
		expect(simulateReturn).toBeGreaterThan(-1);
		expect(keyRecovery).toBeGreaterThan(-1);
		// Ordering IS the guarantee: a preview that reached the decrypt call
		// would be one refactor away from signing.
		expect(simulateReturn).toBeLessThan(keyRecovery);
	});

	it('discloses the token-account rent a top-up silently pays', () => {
		const src = read('api/user/wallet/fund-agent.js');
		expect(src).toContain('creates_token_account');
		expect(src).toContain('token_account_rent_sol');
		// And the page has to actually show it, not just receive it.
		expect(read('src/master-wallet.js')).toContain('wlt-confirm-flag');
	});
});

describe('pricing a transfer does not consume the daily withdrawal budget', () => {
	// withdrawalPerUser is 5 per user per DAY. Both spend routes used to charge
	// it before checking `simulate`, so four price checks locked a user out of
	// their own funds for 24 hours. A preview moves nothing and must not count.
	it('routes simulate to the per-minute limiter on both spend routes', () => {
		for (const path of ['api/user/wallet/send.js', 'api/user/wallet/fund-agent.js']) {
			const src = read(path);
			expect(src).toContain('limits.walletSimulate(session.id)');
			expect(src).toContain('limits.withdrawalPerUser(session.id)');
			// The body must be parsed BEFORE the limiter, or the branch cannot
			// know which budget to draw on.
			expect(src.indexOf('await readJson(req)')).toBeLessThan(
				src.indexOf('limits.walletSimulate(session.id)'),
			);
		}
	});

	it('defines walletSimulate as a real per-minute limiter', () => {
		const src = read('api/_lib/rate-limit.js');
		expect(src).toMatch(/walletSimulate:[\s\S]{0,200}?wallet:simulate/);
		expect(src).toMatch(/wallet:simulate['"],\s*\{\s*limit:\s*\d+,\s*window:\s*'1 m'/);
	});

	it('guards fund-agent by IP as well, matching send', () => {
		// clientIp was imported here and unused, leaving this the only
		// funds-moving wallet route without a per-IP ceiling.
		expect(read('api/user/wallet/fund-agent.js')).toContain('limits.authIp(clientIp(req))');
	});
});

describe('scan-to-fund is wired into the page', () => {
	it('offers Add funds as the primary action and opens the sheet', () => {
		const src = read('src/master-wallet.js');
		expect(src).toContain("import { openDepositSheet } from './wallet-deposit.js'");
		expect(src).toContain('data-act="deposit"');
		expect(src).toContain('openDepositSheet(');
	});

	it('hands the sheet a balance reader rather than the whole client', () => {
		// The watcher only needs balances; a narrow injection is what keeps
		// wallet-deposit.js testable with no network at all.
		expect(read('src/master-wallet.js')).toContain('async readBalances()');
	});

	it('opens the sheet straight after provisioning, since an empty wallet does nothing', () => {
		const src = read('src/master-wallet.js');
		const create = src.indexOf('async function onCreate()');
		const next = src.indexOf('function ', create + 10);
		expect(src.slice(create, next)).toContain('onDeposit()');
	});

	it('offers max on every amount field, not just send', () => {
		const src = read('src/master-wallet.js');
		expect(src).toContain("maxHint('wlt-amount')");
		expect(src).toContain("maxHint('wlt-fund-amount')");
		// The handler must target the field that asked, not a hardcoded one.
		expect(src).toContain('root.querySelector(`#${el.dataset.target}`)');
	});

	it('ships the deposit sheet styles the module depends on', () => {
		const css = read('public/master-wallet.css');
		for (const cls of ['.wlt-sheet', '.wlt-qr', '.wlt-chip', '.wlt-watch-pulse', '.wlt-tip-body']) {
			expect(css).toContain(cls);
		}
		// The QR stays light in both themes; a theme-inverted code fails scanners.
		expect(css).toMatch(/\.wlt-qr\s*\{[^}]*background:\s*#fff/);
	});

	it('explains the concepts that actually confuse people', () => {
		const src = read('src/master-wallet.js');
		expect(src).toContain('function tip(');
		expect(src).toContain('aria-describedby');
		expect(src).toContain('role="tooltip"');
		// The two real confusions: master vs agent wallet, and why SOL is needed.
		expect(src).toMatch(/Each agent has its own separate wallet/);
		expect(src).toMatch(/fee in SOL/);
	});
});