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.4 KB
Raw Blame
// Unit tests for the Solana Developer Platform (SDP) client (api/_lib/sdp.js).
// fetch is mocked, so these run with no network and no real SDP key. They pin
// the wire contract the proxy (api/sdp/*) and any server-side caller depend on:
//   1. the path allowlist mirrors the upstream router — unknown paths are
//      refused before any request goes out (no open-proxy).
//   2. health/openapi/llms need no key; everything else fails closed with 503
//      when SDP_API_KEY is unset (never a fake success).
//   3. the server-side key is attached as a Bearer Authorization header and the
//      base host is overridable via SDP_API_BASE.
//   4. upstream non-2xx surfaces the structured { error: { code, message } }.

import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
import {
	isSdpAllowedPath,
	sdpConfigured,
	sdpPathNeedsKey,
	sdpRequest,
	sdpCall,
	sdpHealth,
} from '../api/_lib/sdp.js';

const realFetch = global.fetch;
let lastRequest = null; // { url, method, headers, body }

function mockFetch(status, body, { contentType = 'application/json', traceId = null } = {}) {
	global.fetch = vi.fn(async (url, init = {}) => {
		lastRequest = {
			url,
			method: init.method || 'GET',
			headers: init.headers || {},
			body: init.body ?? null,
		};
		const text = typeof body === 'string' ? body : JSON.stringify(body);
		const headers = new Map([['content-type', contentType]]);
		if (traceId) headers.set('x-sdp-trace-id', traceId);
		return {
			status,
			headers: { get: (k) => headers.get(k.toLowerCase()) ?? null },
			text: async () => text,
		};
	});
}

beforeEach(() => {
	lastRequest = null;
	delete process.env.SDP_API_KEY;
	delete process.env.SDP_API_BASE;
});

afterEach(() => {
	global.fetch = realFetch;
	vi.restoreAllMocks();
});

describe('path allowlist', () => {
	it('accepts the documented v1 resources and top-level surfaces', () => {
		for (const p of [
			'health',
			'health/ready',
			'openapi.json',
			'llms.txt',
			'v1/wallets',
			'v1/wallets/abc-123',
			'v1/issuance',
			'v1/payments/transfers',
			'v1/compliance/address-screenings',
			'v1/projects',
		]) {
			expect(isSdpAllowedPath(p), p).toBe(true);
		}
	});

	it('rejects unknown resources, traversal, and arbitrary paths', () => {
		for (const p of [
			'',
			'v1/secrets',
			'v2/wallets',
			'../etc/passwd',
			'v1/wallets/../../admin',
			'admin/allowlist',
		]) {
			expect(isSdpAllowedPath(p), p).toBe(false);
		}
	});

	it('rejects encoded dot segments and URL-structure characters the upstream URL parser would act on', () => {
		for (const p of [
			'v1/wallets/%2e%2e/%2e%2e/admin',
			'v1/wallets/.%2E/admin',
			'v1/wallets/%2E./admin',
			'v1/wallets/./x',
			'v1/wallets/.\t./admin',
			'v1/wallets%3fx=1',
			'v1/wallets?x=1',
			'v1/wallets#x',
			'v1/wallets\\..\\admin',
		]) {
			expect(isSdpAllowedPath(p), p).toBe(false);
		}
	});

	it('leading slashes are normalized', () => {
		expect(isSdpAllowedPath('/v1/wallets')).toBe(true);
	});
});

describe('key requirements', () => {
	it('health/openapi/llms need no key; v1 routes do', () => {
		expect(sdpPathNeedsKey('health')).toBe(false);
		expect(sdpPathNeedsKey('health/ready')).toBe(false);
		expect(sdpPathNeedsKey('openapi.json')).toBe(false);
		expect(sdpPathNeedsKey('llms.txt')).toBe(false);
		expect(sdpPathNeedsKey('v1/wallets')).toBe(true);
	});

	it('sdpConfigured reflects SDP_API_KEY', () => {
		expect(sdpConfigured()).toBe(false);
		process.env.SDP_API_KEY = 'sdp_test_key';
		expect(sdpConfigured()).toBe(true);
	});
});

describe('sdpRequest', () => {
	it('refuses a disallowed path without making a request', async () => {
		mockFetch(200, { ok: true });
		await expect(sdpRequest('v1/secrets')).rejects.toMatchObject({ status: 404 });
		expect(global.fetch).not.toHaveBeenCalled();
	});

	it('fails closed with 503 when an authenticated route has no key', async () => {
		mockFetch(200, { ok: true });
		await expect(sdpRequest('v1/wallets')).rejects.toMatchObject({ status: 503 });
		expect(global.fetch).not.toHaveBeenCalled();
	});

	it('calls health with no key and no Authorization header', async () => {
		mockFetch(200, { status: 'ok' });
		const res = await sdpRequest('health');
		expect(res.status).toBe(200);
		expect(res.body).toEqual({ status: 'ok' });
		expect(lastRequest.url).toBe('https://api.solana.com/health');
		expect(lastRequest.headers.authorization).toBeUndefined();
	});

	it('omits the key on the public doc surfaces even when one is configured', async () => {
		process.env.SDP_API_KEY = 'sdp_live_abc';
		mockFetch(200, { openapi: '3.1.0' });
		await sdpRequest('openapi.json');
		expect(lastRequest.url).toBe('https://api.solana.com/openapi.json');
		expect(lastRequest.headers.authorization).toBeUndefined();
	});

	it('attaches the Bearer key and honors SDP_API_BASE', async () => {
		process.env.SDP_API_KEY = 'sdp_live_abc';
		process.env.SDP_API_BASE = 'https://sandbox.example.com/';
		mockFetch(200, { items: [] });
		await sdpRequest('v1/wallets', { query: { limit: 10, skip: '' } });
		expect(lastRequest.url).toBe('https://sandbox.example.com/v1/wallets?limit=10');
		expect(lastRequest.headers.authorization).toBe('Bearer sdp_live_abc');
	});

	it('serializes a JSON body on POST and sets content-type', async () => {
		process.env.SDP_API_KEY = 'sdp_live_abc';
		mockFetch(201, { id: 'wal_1' });
		await sdpRequest('v1/wallets', { method: 'POST', body: { name: 'treasury' } });
		expect(lastRequest.method).toBe('POST');
		expect(lastRequest.headers['content-type']).toBe('application/json');
		expect(JSON.parse(lastRequest.body)).toEqual({ name: 'treasury' });
	});

	it('returns the upstream status + body without throwing on HTTP errors', async () => {
		process.env.SDP_API_KEY = 'sdp_live_abc';
		mockFetch(400, { error: { code: 'BAD_REQUEST', message: 'nope' } }, { traceId: 'trace-9' });
		const res = await sdpRequest('v1/wallets', { method: 'POST', body: {} });
		expect(res.status).toBe(400);
		expect(res.traceId).toBe('trace-9');
		expect(res.body.error.code).toBe('BAD_REQUEST');
	});
});

describe('sdpCall', () => {
	it('returns the body on 2xx', async () => {
		mockFetch(200, { status: 'ok' });
		await expect(sdpHealth()).resolves.toEqual({ status: 'ok' });
	});

	it('throws the structured upstream error on non-2xx', async () => {
		process.env.SDP_API_KEY = 'sdp_live_abc';
		mockFetch(409, { error: { code: 'ALREADY_INITIALIZED', message: 'exists' } });
		await expect(sdpCall('v1/wallets', { method: 'POST', body: {} })).rejects.toMatchObject({
			status: 409,
			code: 'ALREADY_INITIALIZED',
		});
	});
});