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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// GET /api/sim-readiness: the free public physics grade.
//
// The real handler, the real grader, and a real bundled GLB run end to end; the
// only mocked seams are the two the endpoint cannot own in a test: the network
// fetch (SSRF-guarded) and the Postgres cache. Both are driven per test so the
// full status table in specs/SIM_READINESS.md is asserted rather than described,
// including the case that is deliberately NOT an error: bytes that are not glTF
// come back 200 with verdict "unreadable", because "this is not a GLB" is a
// valid grade and a client gating on `verdict` must not need a second code path.
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { Readable } from 'node:stream';
import { readFileSync, existsSync } from 'node:fs';
import { resolve } from 'node:path';
import { createHash } from 'node:crypto';
const avatar = (name) => resolve(process.cwd(), 'public/avatars', name);
const REAL_GLB_PATH = ['cesium-man.glb', 'fox.glb', 'mannequin.glb'].map(avatar).find(existsSync);
const REAL_GLB = REAL_GLB_PATH ? readFileSync(REAL_GLB_PATH) : null;
const REAL_HASH = REAL_GLB ? createHash('sha256').update(REAL_GLB).digest('hex') : 'a'.repeat(64);
// What the mocked upstream serves, and what the mocked store holds. Reset per test.
let upstream;
let stored;
let puts;
class MaxBytesExceededError extends Error {
constructor(observed, limit) {
super(`response exceeds max bytes: ${observed} > ${limit}`);
this.code = 'max_bytes_exceeded';
this.status = 413;
}
}
class SsrfBlockedError extends Error {
constructor(reason) {
super(reason);
this.code = 'ssrf_blocked';
this.status = 400;
}
}
vi.mock('../../api/_lib/ssrf-guard.js', () => ({
MaxBytesExceededError,
SsrfBlockedError,
fetchSafePublicUrlPinned: vi.fn(async () => {
if (upstream.throws) throw upstream.throws;
return {
ok: upstream.status >= 200 && upstream.status < 300,
status: upstream.status,
headers: new Map([['content-length', String(upstream.body?.length ?? 0)]]),
arrayBuffer: async () => upstream.body,
};
}),
}));
// Switchable per-IP quota, so the metered lane is asserted rather than assumed.
let rlOk = true;
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
apiIp: async () => (rlOk
? { success: true, limit: 30, remaining: 29, reset: Date.now() + 300_000 }
: { success: false, limit: 30, remaining: 0, reset: Date.now() + 300_000 }),
},
clientIp: () => '203.0.113.9',
}));
vi.mock('../../api/_lib/sim-readiness-store.js', () => ({
simReadinessStoreEnabled: () => true,
getGrade: vi.fn(async (hash) => stored.get(hash) ?? null),
putGrade: vi.fn(async (row) => {
puts.push(row);
const at = new Date().toISOString();
stored.set(row.glbSha256, { report: row.report, gradedAt: at, graderVersion: row.report.grader, sourceUrl: row.sourceUrl ?? null });
return at;
}),
}));
beforeEach(() => {
rlOk = true;
upstream = { status: 200, body: REAL_GLB, throws: null };
stored = new Map();
puts = [];
vi.clearAllMocks();
});
function makeReq(url, method = 'GET') {
const stream = Readable.from([]);
stream.method = method;
stream.url = url;
stream.headers = { host: 'three.ws' };
const q = url.indexOf('?');
stream.query = q >= 0 ? Object.fromEntries(new URLSearchParams(url.slice(q + 1))) : {};
return stream;
}
function makeRes() {
return {
statusCode: 200,
_h: {},
writableEnded: false,
headersSent: false,
setHeader(k, v) { this._h[k.toLowerCase()] = v; },
getHeader(k) { return this._h[k.toLowerCase()]; },
end(body) { this._body = body; this.writableEnded = true; },
};
}
async function get(url, method = 'GET') {
const res = makeRes();
const mod = await import('../../api/sim-readiness.js');
await mod.default(makeReq(url, method), res);
return { status: res.statusCode, headers: res._h, body: res._body ? JSON.parse(res._body) : null };
}
const HAS_GLB = Boolean(REAL_GLB);
describe('GET /api/sim-readiness: the request contract', () => {
it('400s when neither src nor hash is given', async () => {
const r = await get('/api/sim-readiness');
expect(r.status).toBe(400);
expect(r.body.error).toMatch(/glb_url|hash/i);
expect(r.headers['cache-control']).toBe('no-store');
});
it('400s on a malformed hash rather than treating it as a src', async () => {
const r = await get('/api/sim-readiness?hash=not-a-hash');
expect(r.status).toBe(400);
});
it('400s on a non-https src', async () => {
const r = await get('/api/sim-readiness?src=http%3A%2F%2Fexample.com%2Fa.glb');
expect(r.status).toBe(400);
expect(r.body.error).toContain('https');
});
it('404s for a content hash nobody has graded, without fetching anything', async () => {
const { fetchSafePublicUrlPinned } = await import('../../api/_lib/ssrf-guard.js');
const r = await get(`/api/sim-readiness?hash=${'b'.repeat(64)}`);
expect(r.status).toBe(404);
expect(r.body).toEqual({ error: 'not graded' });
// The whole point of the hash lane: it is a lookup, never a download.
expect(fetchSafePublicUrlPinned).not.toHaveBeenCalled();
});
it('meters the expensive lane and tells the caller to use a hash instead', async () => {
rlOk = false;
const { fetchSafePublicUrlPinned } = await import('../../api/_lib/ssrf-guard.js');
const r = await get('/api/sim-readiness?src=https%3A%2F%2Fthree.ws%2Fa.glb');
expect(r.status).toBe(429);
expect(r.body.error).toBe('rate_limited');
expect(r.headers['retry-after']).toBeTruthy();
// The whole point of the cap: the fetch never happened.
expect(fetchSafePublicUrlPinned).not.toHaveBeenCalled();
});
it('never meters the cheap hash lookup, which is one indexed read', async () => {
rlOk = false;
const r = await get(`/api/sim-readiness?hash=${'b'.repeat(64)}`);
// 404 rather than 429: the lookup ran.
expect(r.status).toBe(404);
});
it('refuses a POST: grading is a read', async () => {
const r = await get('/api/sim-readiness?src=https://three.ws/a.glb', 'POST');
expect(r.status).toBe(405);
});
});
describe('GET /api/sim-readiness: upstream failures', () => {
it('413s when the asset is over the byte cap', async () => {
upstream.throws = new MaxBytesExceededError(70_000_000, 67_108_864);
const r = await get('/api/sim-readiness?src=https://three.ws/huge.glb');
expect(r.status).toBe(413);
expect(r.body.error).toMatch(/64 MB/);
});
it('400s (not 502) when the guard blocks the host', async () => {
upstream.throws = new SsrfBlockedError('blocked address');
const r = await get('/api/sim-readiness?src=https://169.254.169.254/a.glb');
expect(r.status).toBe(400);
expect(r.body.error).toContain('https');
});
it('502s with the upstream status when the fetch fails', async () => {
upstream = { status: 404, body: Buffer.alloc(0), throws: null };
const r = await get('/api/sim-readiness?src=https://three.ws/gone.glb');
expect(r.status).toBe(502);
expect(r.body).toEqual({ error: 'could not fetch the asset', status: 404 });
});
it('502s on a timeout rather than reporting a verdict it never measured', async () => {
const timeout = new Error('The operation was aborted due to timeout');
timeout.name = 'TimeoutError';
upstream.throws = timeout;
const r = await get('/api/sim-readiness?src=https://three.ws/slow.glb');
expect(r.status).toBe(502);
expect(r.body.error).toContain('timed out');
});
it('grades bytes that are not glTF as unreadable, with a 200', async () => {
upstream.body = Buffer.from('this is definitely not a GLB');
const r = await get('/api/sim-readiness?src=https://three.ws/notes.txt');
expect(r.status).toBe(200);
expect(r.body.readable).toBe(false);
expect(r.body.verdict).toBe('unreadable');
expect(r.body.blockers).toContain('unreadable_glb');
expect(r.body.grader).toBe('threews.sim.readiness.v1');
});
});
describe.runIf(HAS_GLB)('GET /api/sim-readiness: grading a real asset', () => {
const SRC = 'https://three.ws/avatars/cesium-man.glb';
it('grades on demand, caches by content hash, and says it was fresh', async () => {
const r = await get(`/api/sim-readiness?src=${encodeURIComponent(SRC)}`);
expect(r.status).toBe(200);
expect(r.body.cached).toBe(false);
expect(r.body.glbSha256).toBe(REAL_HASH);
expect(['simulation_ready', 'needs_scale', 'needs_repair', 'unusable']).toContain(r.body.verdict);
expect(r.body.grader).toBe('threews.sim.readiness.v1');
expect(typeof r.body.mass.volumeM3).toBe('number');
expect(r.body.topology).toBeTruthy();
expect(r.headers['cache-control']).toContain('s-maxage=300');
// Cached by CONTENT, with the source URL kept only for triage.
expect(puts).toHaveLength(1);
expect(puts[0].glbSha256).toBe(REAL_HASH);
expect(puts[0].sourceUrl).toBe(SRC);
expect(puts[0].gradeMs).toBeGreaterThanOrEqual(0);
});
it('serves the second request from the cache without re-grading', async () => {
const first = await get(`/api/sim-readiness?src=${encodeURIComponent(SRC)}`);
const second = await get(`/api/sim-readiness?src=${encodeURIComponent(SRC)}`);
expect(second.body.cached).toBe(true);
expect(second.body.gradedAt).toBe(first.body.gradedAt);
expect(second.body.verdict).toBe(first.body.verdict);
// One grade, two answers.
expect(puts).toHaveLength(1);
});
it('answers ?hash= from the cache once those bytes have been graded', async () => {
await get(`/api/sim-readiness?src=${encodeURIComponent(SRC)}`);
const { fetchSafePublicUrlPinned } = await import('../../api/_lib/ssrf-guard.js');
fetchSafePublicUrlPinned.mockClear();
const r = await get(`/api/sim-readiness?hash=${REAL_HASH}`);
expect(r.status).toBe(200);
expect(r.body.cached).toBe(true);
expect(r.body.glbSha256).toBe(REAL_HASH);
expect(fetchSafePublicUrlPinned).not.toHaveBeenCalled();
});
it('carries no payment, wallet, or coin surface', async () => {
const r = await get(`/api/sim-readiness?src=${encodeURIComponent(SRC)}`);
const text = JSON.stringify(r.body).toLowerCase();
for (const word of ['usdc', 'wallet', 'x402', 'payment', 'price', 'token', 'solana', 'mint']) {
expect(text).not.toContain(word);
}
});
});