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
// Handler tests for the Magic Brush region-retexture gateway
// (api/studio/retexture-region.js).
//
// Only the two real external boundaries are stubbed: the auth lookup, the rate
// limiter, and the SSRF DNS probe (each covered by its own suite), plus
// global.fetch standing in for the GCP texture worker's HTTP surface. The
// provider (api/_providers/gcp.js) runs for real, so these pin the actual wire
// contract this endpoint speaks to workers/texture: POST /retexture_region and
// GET /tasks/:id, and the opaque job token that carries the task handle between
// them.
import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
const getSessionUserMock = vi.fn();
const authenticateBearerMock = vi.fn();
vi.mock('../api/_lib/auth.js', () => ({
getSessionUser: (...a) => getSessionUserMock(...a),
authenticateBearer: (...a) => authenticateBearerMock(...a),
extractBearer: (req) => req.headers?.authorization?.replace(/^Bearer /i, '') || null,
hasScope: (scopes, want) => String(scopes || '').split(/[\s,]+/).includes(want),
}));
// Quota behaviour has its own suites; here the limiters are open so the handler
// logic is what's under test. `allow` flips them to exercise the 429 path.
let allow = true;
const limitResult = () => ({
success: allow,
limit: 60,
remaining: allow ? 59 : 0,
reset: 1_000_000,
});
vi.mock('../api/_lib/rate-limit.js', () => ({
clientIp: () => '203.0.113.7',
limits: {
upload: async () => limitResult(),
mcp3dStatus: async () => limitResult(),
},
}));
// The guard resolves DNS; its own behaviour is covered by tests/ssrf-pinned-lookup
// and tests/auto-rig-ssrf. Here it enforces the shape the handler depends on
// (https + public host) without touching the network.
vi.mock('../api/_lib/ssrf-guard.js', () => ({
assertSafePublicUrl: async (raw, { allowHttp = false } = {}) => {
const u = new URL(raw);
if (u.protocol !== 'https:' && !allowHttp) throw new Error('https required');
if (/^(localhost|127\.|10\.|192\.168\.)/.test(u.hostname)) throw new Error('private host');
return u;
},
}));
const WORKER = 'https://texture-worker.test';
const { default: handler } = await import('../api/studio/retexture-region.js');
const MESH = 'https://three.ws/cdn/models/avatar.glb';
const MASK = 'iVBORw0KGgoAAAANSUhEUg==';
function mkReq({ method = 'GET', url = '/api/studio/retexture-region', headers = {}, body = null } = {}) {
return {
method,
url,
headers: { ...headers },
on(event, cb) {
if (event === 'data' && body != null) {
const buf = Buffer.from(typeof body === 'string' ? body : JSON.stringify(body));
queueMicrotask(() => {
cb(buf);
this._endCb?.();
});
} else if (event === 'end') {
this._endCb = cb;
if (body == null) queueMicrotask(cb);
}
},
destroy() {},
};
}
function mkRes() {
return {
statusCode: 200,
headers: {},
body: undefined,
writableEnded: false,
headersSent: false,
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
end(chunk) {
this.body = chunk;
this.writableEnded = true;
},
};
}
async function call(opts) {
const res = mkRes();
await handler(mkReq(opts), res);
return { status: res.statusCode, body: res.body ? JSON.parse(res.body) : undefined, res };
}
const post = (body) =>
call({ method: 'POST', headers: { 'content-type': 'application/json' }, body });
const poll = (job) =>
call({ url: `/api/studio/retexture-region?job=${encodeURIComponent(job)}` });
const realFetch = global.fetch;
afterAll(() => {
global.fetch = realFetch;
});
let workerCalls = [];
beforeEach(() => {
allow = true;
workerCalls = [];
process.env.GCP_RECONSTRUCTION_KEY = 'test-worker-key';
process.env.GCP_TEXTURE_URL = WORKER;
getSessionUserMock.mockReset().mockResolvedValue({ id: 'user-1' });
authenticateBearerMock.mockReset().mockResolvedValue(null);
global.fetch = vi.fn(async (url, opts = {}) => {
const u = String(url);
workerCalls.push({ url: u, method: opts.method || 'GET', body: opts.body ? JSON.parse(opts.body) : null, headers: opts.headers });
if (u === `${WORKER}/retexture_region`) {
return { ok: true, status: 200, json: async () => ({ task_id: 'task-42', status: 'queued' }) };
}
if (u.startsWith(`${WORKER}/tasks/`)) {
return {
ok: true,
status: 200,
json: async () => ({ status: 'done', result_url: 'https://three.ws/cdn/out/avatar-retex.glb' }),
};
}
throw new Error(`unexpected fetch: ${u}`);
});
});
describe('POST /api/studio/retexture-region: the success path', () => {
it('submits the masked region to the texture worker and returns an opaque job token', async () => {
const { status, body } = await post({
mesh_url: MESH,
prompt: 'worn red leather',
mask_b64: MASK,
texture_size: 2048,
strength: 0.6,
});
expect(status).toBe(202);
expect(body.ok).toBe(true);
expect(body.status).toBe('queued');
expect(typeof body.job).toBe('string');
expect(workerCalls).toHaveLength(1);
const sent = workerCalls[0];
expect(sent.url).toBe(`${WORKER}/retexture_region`);
expect(sent.method).toBe('POST');
expect(sent.headers.authorization).toBe('Bearer test-worker-key');
expect(sent.body).toMatchObject({
mesh: MESH,
prompt: 'worn red leather',
mask_b64: MASK,
texture_size: 2048,
strength: 0.6,
feather: 24,
seed: 0,
});
// The token carries the task handle plus the worker it was issued for.
const job = JSON.parse(Buffer.from(body.job, 'base64url').toString('utf8'));
expect(job).toMatchObject({ mode: 'retex_region', taskId: 'task-42', baseUrl: WORKER });
});
it('accepts a colour-only edit with no prompt', async () => {
const { status } = await post({ mesh_url: MESH, mask_b64: MASK, color: '#3fa9f5' });
expect(status).toBe(202);
expect(workerCalls[0].body.color).toBe('#3fa9f5');
});
it('polls the task through and hands back the finished texture', async () => {
const { body: submitted } = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
const { status, body } = await poll(submitted.job);
expect(status).toBe(200);
expect(body).toMatchObject({
ok: true,
status: 'done',
result_url: 'https://three.ws/cdn/out/avatar-retex.glb',
error: null,
});
expect(workerCalls[1].url).toBe(`${WORKER}/tasks/task-42`);
});
});
describe('auth and quota', () => {
it('rejects an anonymous submit and an anonymous poll with 401', async () => {
getSessionUserMock.mockResolvedValue(null);
const submit = await post({ mesh_url: MESH, prompt: 'gold leaf', mask_b64: MASK });
expect(submit.status).toBe(401);
expect(submit.body.error).toBe('unauthorized');
const status = await poll('anything');
expect(status.status).toBe(401);
expect(workerCalls).toHaveLength(0);
});
it('accepts a bearer token carrying the avatars:write scope', async () => {
getSessionUserMock.mockResolvedValue(null);
authenticateBearerMock.mockResolvedValue({ userId: 'agent-9', scope: 'avatars:read avatars:write' });
const { status } = await call({
method: 'POST',
headers: { 'content-type': 'application/json', authorization: 'Bearer tok' },
body: { mesh_url: MESH, prompt: 'gold leaf', mask_b64: MASK },
});
expect(status).toBe(202);
});
it('rejects a bearer token missing the write scope', async () => {
getSessionUserMock.mockResolvedValue(null);
authenticateBearerMock.mockResolvedValue({ userId: 'agent-9', scope: 'avatars:read' });
const { status, body } = await call({
method: 'POST',
headers: { 'content-type': 'application/json', authorization: 'Bearer tok' },
body: { mesh_url: MESH, prompt: 'gold leaf', mask_b64: MASK },
});
expect(status).toBe(401);
expect(body.error).toBe('unauthorized');
});
it('rate-limits both the submit and the status poll', async () => {
allow = false;
const submit = await post({ mesh_url: MESH, prompt: 'gold leaf', mask_b64: MASK });
expect(submit.status).toBe(429);
expect(submit.body.error).toBe('rate_limited');
const status = await poll('anything');
expect(status.status).toBe(429);
expect(workerCalls).toHaveLength(0);
});
});
describe('input validation', () => {
it('rejects a request with neither a usable prompt nor a colour', async () => {
const { status, body } = await post({ mesh_url: MESH, mask_b64: MASK, prompt: 'ab' });
expect(status).toBe(400);
expect(body.error).toBe('validation_error');
expect(body.error_description).toContain('prompt');
});
it.each([
['a missing mesh_url and mask', {}],
['a non-hex colour', { mesh_url: MESH, mask_b64: MASK, color: 'reddish' }],
['an unsupported texture size', { mesh_url: MESH, mask_b64: MASK, prompt: 'x-ray', texture_size: 333 }],
['an out-of-range strength', { mesh_url: MESH, mask_b64: MASK, prompt: 'x-ray', strength: 4 }],
['a fractional feather', { mesh_url: MESH, mask_b64: MASK, prompt: 'x-ray', feather: 2.5 }],
])('rejects %s with a 400 JSON error', async (_label, body) => {
const { status, body: out } = await post(body);
expect(status).toBe(400);
expect(out.error).toBe('validation_error');
expect(workerCalls).toHaveLength(0);
});
it('rejects a mesh_url the SSRF guard will not vouch for', async () => {
const { status, body } = await post({
mesh_url: 'http://127.0.0.1:8080/private.glb',
prompt: 'gold leaf',
mask_b64: MASK,
});
expect(status).toBe(400);
expect(body.error).toBe('invalid_mesh_url');
expect(workerCalls).toHaveLength(0);
});
it('rejects a poll with no job token', async () => {
const { status, body } = await call({ url: '/api/studio/retexture-region' });
expect(status).toBe(400);
expect(body.error).toBe('invalid_request');
});
});
describe('job-token forgery cannot steer the server fetch', () => {
it('refuses a token pointing at a host that is not the configured worker', async () => {
const forged = Buffer.from(
JSON.stringify({ mode: 'retex_region', taskId: 'x', baseUrl: 'https://evil.example.com' }),
).toString('base64url');
const { status, body } = await poll(forged);
expect(status).toBe(400);
expect(body.error).toBe('invalid_job');
expect(workerCalls).toHaveLength(0);
});
it('refuses a token for a different worker mode on our own host', async () => {
const forged = Buffer.from(
JSON.stringify({ mode: 'reconstruct', taskId: 'x', baseUrl: WORKER }),
).toString('base64url');
const { status, body } = await poll(forged);
expect(status).toBe(400);
expect(body.error).toBe('invalid_job');
expect(workerCalls).toHaveLength(0);
});
it('refuses a token that is not decodable at all', async () => {
const { status, body } = await poll('%%%not-a-token%%%');
expect(status).toBe(400);
expect(body.error).toBe('invalid_job');
expect(workerCalls).toHaveLength(0);
});
});
describe('the texture worker is unavailable', () => {
it('answers 501 on both verbs when the worker URL is unset, never a bogus "malformed token"', async () => {
// A token issued while the lane was up must not be reported as forged just
// because the deployment lost GCP_TEXTURE_URL: the honest answer is 501.
const { body: submitted } = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
delete process.env.GCP_TEXTURE_URL;
const submit = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
expect(submit.status).toBe(501);
expect(submit.body.error).toBe('region_retex_unconfigured');
const status = await poll(submitted.job);
expect(status.status).toBe(501);
expect(status.body.error).toBe('region_retex_unconfigured');
expect(workerCalls).toHaveLength(1); // only the first, pre-outage submit
});
it('answers 501 when the shared worker key is unset', async () => {
delete process.env.GCP_RECONSTRUCTION_KEY;
const { status, body } = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
expect(status).toBe(501);
expect(body.error).toBe('region_retex_unconfigured');
});
it('surfaces a worker rejection as a 502 rather than a stack trace', async () => {
global.fetch = vi.fn(async () => ({
ok: false,
status: 503,
json: async () => ({ detail: 'model server warming up' }),
}));
const { status, body } = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
expect(status).toBe(502);
expect(body.error).toBe('provider_error');
expect(body.error_description).toBe('model server warming up');
});
it('reports a failed task through the poll body instead of throwing', async () => {
const { body: submitted } = await post({ mesh_url: MESH, prompt: 'brushed steel', mask_b64: MASK });
global.fetch = vi.fn(async () => ({
ok: true,
status: 200,
json: async () => ({ status: 'failed', error: 'mask covered no UV island' }),
}));
const { status, body } = await poll(submitted.job);
expect(status).toBe(200);
expect(body).toMatchObject({ status: 'failed', result_url: null, error: 'mask covered no UV island' });
});
});
describe('transport', () => {
it('answers a CORS preflight and refuses an unsupported method', async () => {
const pre = await call({ method: 'OPTIONS', headers: { origin: 'https://three.ws' } });
expect(pre.status).toBe(204);
expect(pre.res.headers['access-control-allow-methods']).toContain('POST');
const put = await call({ method: 'PUT' });
expect(put.status).toBe(405);
});
});