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.

test(api): pin the MCP bazaar challenge and character boundary contracts

nirholase0745e6d3ad7
diff --git a/tests/api/avatar-og.test.js b/tests/api/avatar-og.test.js
index ed9815fa7..75462c86c 100644
--- a/tests/api/avatar-og.test.js
+++ b/tests/api/avatar-og.test.js
@@ -11,15 +11,11 @@ const sqlMock = vi.fn(async () => []);
const getAvatarMock = vi.fn();
const renderGlbToPngMock = vi.fn();
const putObjectMock = vi.fn(async () => {});
-const publicUrlMock = vi.fn((k) => `https://cdn.test/${k}`);
vi.mock('../../api/_lib/db.js', () => ({ sql: sqlMock, isDbUnavailableError: () => false, isDbCapacityError: () => false }));
vi.mock('../../api/_lib/avatars.js', () => ({ getAvatar: getAvatarMock }));
vi.mock('../../api/_lib/render-glb.js', () => ({ renderGlbToPng: renderGlbToPngMock }));
-vi.mock('../../api/_lib/r2.js', () => ({
- putObject: putObjectMock,
- publicUrl: publicUrlMock,
-}));
+vi.mock('../../api/_lib/r2.js', () => ({ putObject: putObjectMock }));
vi.mock('../../api/_lib/env.js', () => ({
env: { APP_ORIGIN: 'http://localhost:3000' },
@@ -55,8 +51,6 @@ beforeEach(() => {
renderGlbToPngMock.mockReset();
putObjectMock.mockReset();
putObjectMock.mockResolvedValue(undefined);
- publicUrlMock.mockReset();
- publicUrlMock.mockImplementation((k) => `https://cdn.test/${k}`);
__testInternals._renderLocks.clear();
});
diff --git a/tests/api/characters.test.js b/tests/api/characters.test.js
new file mode 100644
index 000000000..484f80356
--- /dev/null
+++ b/tests/api/characters.test.js
@@ -0,0 +1,170 @@
+// Boundary tests for GET /api/characters, the public published-agent feed.
+//
+// The handler runs for real (http.js json/cors/method/wrap included); the DB,
+// rate limiter and bucket-URL helper are stubbed at the module boundary. What
+// these pin is the pagination contract: a hand-edited `cursor` must come back
+// as a 4xx, not as a 500 from `new Date('junk').toISOString()` throwing a
+// RangeError deep inside the handler.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const rows = [];
+const sqlCalls = [];
+vi.mock('../../api/_lib/db.js', () => {
+ const sql = vi.fn(async (...args) => {
+ sqlCalls.push(args);
+ return rows.splice(0, rows.length);
+ });
+ return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };
+});
+
+let rateLimitOk = true;
+vi.mock('../../api/_lib/rate-limit.js', () => ({
+ limits: {
+ publicIp: vi.fn(async () => ({
+ success: rateLimitOk,
+ limit: 60,
+ remaining: rateLimitOk ? 59 : 0,
+ reset: 0,
+ })),
+ },
+ clientIp: vi.fn(() => '127.0.0.1'),
+}));
+
+vi.mock('../../api/_lib/r2.js', () => ({
+ thumbnailUrl: vi.fn((k) => (k ? `https://cdn.test/${k}` : null)),
+}));
+
+vi.mock('../../api/_lib/zauth.js', () => ({ instrument: () => {}, drain: async () => {} }));
+vi.mock('../../api/_lib/sentry.js', () => ({ captureException: () => {} }));
+
+const { default: handler } = await import('../../api/characters.js');
+
+function mkReq({ query = '', method = 'GET' } = {}) {
+ return { method, url: `/api/characters${query}`, query: {}, headers: {} };
+}
+
+function mkRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: '',
+ writableEnded: false,
+ setHeader(k, v) {
+ this.headers[k.toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return this.headers[k.toLowerCase()];
+ },
+ end(payload) {
+ this.body = payload || '';
+ this.writableEnded = true;
+ },
+ get json() {
+ try {
+ return JSON.parse(this.body);
+ } catch {
+ return null;
+ }
+ },
+ };
+}
+
+// The interpolated values of the Nth sql`` call (everything after the strings).
+function interpolations(n) {
+ return sqlCalls[n].slice(1);
+}
+
+const AGENT = {
+ id: '0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0',
+ name: 'Zenith',
+ description: 'An accountability partner.',
+ meta: { solana_address: '37wDaX4Xe25zFZXZqXawMzM1Kt6JK7pdsnWUNo3kAh2q' },
+ created_at: '2026-08-15T13:37:01.660Z',
+ avatar_id: null,
+ author_name: 'ChiQhi',
+ author_username: null,
+ author_avatar: null,
+ avatar_thumbnail_key: 'thumb/abc.png',
+ avatar_visibility: 'public',
+ chat_count: 4,
+};
+
+beforeEach(() => {
+ rows.length = 0;
+ sqlCalls.length = 0;
+ rateLimitOk = true;
+ vi.clearAllMocks();
+});
+
+describe('GET /api/characters', () => {
+ it('serves the feed with a CDN cache header and a next cursor', async () => {
+ rows.push(AGENT, { ...AGENT, id: 'b', created_at: '2026-08-14T00:00:00.000Z' });
+ const res = mkRes();
+ await handler(mkReq({ query: '?limit=1' }), res);
+
+ expect(res.statusCode).toBe(200);
+ expect(res.headers['cache-control']).toMatch(/s-maxage=60/);
+ expect(res.json.characters).toHaveLength(1);
+ expect(res.json.characters[0].name).toBe('Zenith');
+ // A public avatar's thumbnail becomes the card image.
+ expect(res.json.characters[0].image_url).toBe('https://cdn.test/thumb/abc.png');
+ // limit + 1 is fetched so `has more` needs no second query.
+ expect(res.json.next_cursor).toBe('2026-08-15T13:37:01.660Z');
+ });
+
+ it('400s an unparseable cursor instead of 500ing on Invalid Date', async () => {
+ const res = mkRes();
+ await handler(mkReq({ query: '?cursor=notadate' }), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.json.error).toBe('bad_request');
+ // Rejected at the boundary: the query never ran.
+ expect(sqlCalls).toHaveLength(0);
+ });
+
+ it('passes a normalised ISO cursor through to the keyset predicate', async () => {
+ rows.push(AGENT);
+ const res = mkRes();
+ await handler(mkReq({ query: '?cursor=2026-08-16T00:00:00Z' }), res);
+
+ expect(res.statusCode).toBe(200);
+ expect(interpolations(0)).toContain('2026-08-16T00:00:00.000Z');
+ });
+
+ it('coerces junk pagination and caps the page size', async () => {
+ rows.push(AGENT);
+ const junk = mkRes();
+ await handler(mkReq({ query: '?limit=abc' }), junk);
+ // clampInt fallback 24, fetched as limit + 1.
+ expect(interpolations(0)).toContain(25);
+
+ sqlCalls.length = 0;
+ rows.push(AGENT);
+ const over = mkRes();
+ await handler(mkReq({ query: '?limit=9999' }), over);
+ expect(interpolations(0)).toContain(61);
+ });
+
+ it('hides an avatar thumbnail the viewer is not allowed to see', async () => {
+ rows.push({ ...AGENT, avatar_visibility: 'private', meta: {} });
+ const res = mkRes();
+ await handler(mkReq(), res);
+ expect(res.json.characters[0].image_url).toBeNull();
+ });
+
+ it('405s a write method', async () => {
+ const res = mkRes();
+ await handler(mkReq({ method: 'POST' }), res);
+ expect(res.statusCode).toBe(405);
+ expect(sqlCalls).toHaveLength(0);
+ });
+
+ it('429s when the public IP bucket is exhausted', async () => {
+ rateLimitOk = false;
+ const res = mkRes();
+ await handler(mkReq(), res);
+ expect(res.statusCode).toBe(429);
+ expect(sqlCalls).toHaveLength(0);
+ });
+});
diff --git a/tests/api/mcp-bazaar-challenge.test.js b/tests/api/mcp-bazaar-challenge.test.js
index f8a89b87c..d9310e5d3 100644
--- a/tests/api/mcp-bazaar-challenge.test.js
+++ b/tests/api/mcp-bazaar-challenge.test.js
@@ -168,3 +168,54 @@ describe('POST /api/mcp-bazaar: free discovery for plain clients', () => {
expect(res.statusCode).toBe(402);
});
});
+
+// The identity fix above covered the challenge a caller gets BEFORE paying.
+// The re-challenge a caller gets when their payment fails ran through a
+// different helper (sendX402Error) that was never handed BAZAAR_CHALLENGE, so
+// the payer who most needs an accurate envelope, the one about to sign a
+// corrected payment, was the one who got the main server's description back.
+// Reproduced against production on 2026-08-16 before the fix.
+describe('POST /api/mcp-bazaar: the re-challenge after a failed payment', () => {
+ const wrongRecipientPayment = Buffer.from(
+ JSON.stringify({
+ x402Version: 1,
+ scheme: 'exact',
+ network: 'eip155:8453',
+ payload: {
+ signature: `0x${'0'.repeat(130)}`,
+ authorization: {
+ from: `0x${'1'.repeat(40)}`,
+ to: `0x${'2'.repeat(40)}`,
+ value: '1000',
+ validAfter: '0',
+ validBefore: '99999999999',
+ nonce: `0x${'3'.repeat(64)}`,
+ },
+ },
+ }),
+ 'utf8',
+ ).toString('base64');
+
+ it('names the bazaar, not the main MCP server', async () => {
+ const res = makeRes();
+ await handler(
+ makeReq({ body: searchCall, headers: { 'x-payment': wrongRecipientPayment } }),
+ res,
+ );
+ expect(res.statusCode).toBe(402);
+ const challenge = JSON.parse(res.body);
+ expect(challenge.resource.url).toBe('https://three.ws/api/mcp-bazaar');
+ expect(challenge.resource.serviceName).toBe('three.ws x402 Bazaar MCP');
+ expect(challenge.resource.description).toContain('search_services');
+ expect(challenge.resource.description).not.toContain('3D avatar viewer');
+ });
+
+ it('still reports why the payment was rejected', async () => {
+ const res = makeRes();
+ await handler(
+ makeReq({ body: searchCall, headers: { 'x-payment': wrongRecipientPayment } }),
+ res,
+ );
+ expect(JSON.parse(res.body).error).toMatch(/payTo|recipient/i);
+ });
+});