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
// Integration tests for /api/avatar/:id/og.
//
// The renderer itself (puppeteer + chromium) is exercised in
// tests/render-glb.test.js. Here we stub it at the module boundary and
// assert the endpoint's responsibilities: cache-first redirect, fallback
// rules, R2 + DB write-back on cache miss, in-memory concurrency lock.
import { describe, it, expect, vi, beforeEach } from 'vitest';
const sqlMock = vi.fn(async () => []);
const getAvatarMock = vi.fn();
const renderGlbToPngMock = vi.fn();
const putObjectMock = vi.fn(async () => {});
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 }));
vi.mock('../../api/_lib/env.js', () => ({
env: { APP_ORIGIN: 'http://localhost:3000' },
}));
vi.mock('../../api/_lib/zauth.js', () => ({ instrument: () => {}, drain: async () => {} }));
vi.mock('../../api/_lib/sentry.js', () => ({ captureException: () => {} }));
const { default: handler, __testInternals } = await import('../../api/avatar-og.js');
// ── Helpers ────────────────────────────────────────────────────────────────
function mkReq({ url = '/api/avatar/avatar_demo_alice/og', method = 'GET', headers = {} } = {}) {
return { url, method, headers: { host: 'three.ws', ...headers } };
}
function mkRes() {
return {
statusCode: 200,
_h: {},
_body: undefined,
writableEnded: false,
setHeader(k, v) { this._h[k.toLowerCase()] = v; },
getHeader(k) { return this._h[k.toLowerCase()]; },
end(b) { this._body = b; this.writableEnded = true; },
};
}
beforeEach(() => {
sqlMock.mockReset();
sqlMock.mockResolvedValue([]);
getAvatarMock.mockReset();
renderGlbToPngMock.mockReset();
putObjectMock.mockReset();
putObjectMock.mockResolvedValue(undefined);
__testInternals._renderLocks.clear();
});
// ── Tests ──────────────────────────────────────────────────────────────────
describe('GET /api/avatar/:id/og — 404 paths', () => {
it('returns SVG 404 for unknown demo id', async () => {
const req = mkReq({ url: '/api/avatar/avatar_demo_nope/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(404);
expect(res._h['content-type']).toMatch(/image\/svg/);
});
it('returns SVG 404 when DB lookup misses', async () => {
getAvatarMock.mockResolvedValueOnce(null);
const req = mkReq({ url: '/api/avatar/00000000-0000-0000-0000-000000000000/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(404);
expect(getAvatarMock).toHaveBeenCalledWith({ id: '00000000-0000-0000-0000-000000000000' });
});
it('returns SVG card for private avatars (no model_url)', async () => {
getAvatarMock.mockResolvedValueOnce({
id: 'a1',
name: 'Private One',
description: 'shh',
thumbnail_url: null,
model_url: null,
storage_key: 'u/uid/x/abc.glb',
tags: [],
});
const req = mkReq({ url: '/api/avatar/a1/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res._h['content-type']).toMatch(/image\/svg/);
expect(String(res._body)).toContain('Private One');
expect(renderGlbToPngMock).not.toHaveBeenCalled();
});
});
describe('GET /api/avatar/:id/og — cached thumbnail path', () => {
it('302-redirects to thumbnail_url when set', async () => {
getAvatarMock.mockResolvedValueOnce({
id: 'a2',
name: 'X',
thumbnail_url: 'https://cdn.test/u/uid/x/abc_thumb.jpg',
model_url: 'https://cdn.test/u/uid/x/abc.glb',
storage_key: 'u/uid/x/abc.glb',
});
const req = mkReq({ url: '/api/avatar/a2/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(302);
expect(res._h.location).toBe('https://cdn.test/u/uid/x/abc_thumb.jpg');
expect(renderGlbToPngMock).not.toHaveBeenCalled();
expect(putObjectMock).not.toHaveBeenCalled();
});
it('302s a server-rendered _og.png thumbnail instead of wiping its own cache', async () => {
// The regression this pins: the endpoint used to re-test `thumbnail_url`
// with isLegacyOgThumbnailKey (`^https?://.*_og\.png$`). Every thumbnail it
// writes itself is `<key>_og.png`, and thumbnailUrl() turns that into an
// absolute bucket URL, so its own cached render matched the poisoned-key
// shape, the row's thumbnail_key was nulled, and chromium re-rendered on
// every crawl. A genuinely poisoned key never gets this far: thumbnailUrl()
// already resolves it to null (see the render-path test below).
getAvatarMock.mockResolvedValueOnce({
id: 'a9',
name: 'Michelle',
thumbnail_url: 'https://cdn.test/u/uid/x/michelle_og.png',
model_url: 'https://cdn.test/u/uid/x/michelle.glb',
storage_key: 'u/uid/x/michelle.glb',
tags: [],
});
const req = mkReq({ url: '/api/avatar/a9/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(302);
expect(res._h.location).toBe('https://cdn.test/u/uid/x/michelle_og.png');
expect(renderGlbToPngMock).not.toHaveBeenCalled();
expect(putObjectMock).not.toHaveBeenCalled();
// Above all: a crawl is a read. It must not write to the avatars table.
expect(sqlMock).not.toHaveBeenCalled();
});
});
describe('GET /api/avatar/:id/og — server render path', () => {
const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
beforeEach(() => {
// Stub the GLB HEAD request — content-length under the 10 MB cap.
globalThis.fetch = vi.fn(async () => ({
ok: true,
headers: { get: (h) => (h.toLowerCase() === 'content-length' ? '1024' : null) },
}));
});
it('renders, uploads to R2, updates DB, streams PNG', async () => {
getAvatarMock.mockResolvedValueOnce({
id: 'a3',
name: 'Bob',
thumbnail_url: null,
model_url: 'https://cdn.test/u/uid/bob/123.glb',
storage_key: 'u/uid/bob/123.glb',
tags: [],
});
renderGlbToPngMock.mockResolvedValueOnce(PNG_MAGIC);
const req = mkReq({ url: '/api/avatar/a3/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res._h['content-type']).toBe('image/png');
expect(res._h['cache-control']).toMatch(/max-age/);
expect(res._body).toEqual(PNG_MAGIC);
// Renderer called with the avatar's GLB URL.
expect(renderGlbToPngMock).toHaveBeenCalledTimes(1);
expect(renderGlbToPngMock.mock.calls[0][0].glbUrl).toBe(
'https://cdn.test/u/uid/bob/123.glb',
);
// R2 write: sibling key with _og.png suffix.
expect(putObjectMock).toHaveBeenCalledTimes(1);
expect(putObjectMock.mock.calls[0][0].key).toBe('u/uid/bob/123_og.png');
expect(putObjectMock.mock.calls[0][0].contentType).toBe('image/png');
expect(putObjectMock.mock.calls[0][0].body).toEqual(PNG_MAGIC);
// DB write: update statement was issued.
expect(sqlMock).toHaveBeenCalledTimes(1);
const sqlArgs = sqlMock.mock.calls[0];
const text = sqlArgs[0].join('?');
expect(text).toMatch(/update avatars set thumbnail_key/);
expect(sqlArgs).toContain('u/uid/bob/123_og.png');
expect(sqlArgs).toContain('a3');
// The write-back only fills an empty slot (so a concurrent customizer-save
// snapshot survives) or replaces a legacy poisoned key, which thumbnailUrl()
// refuses to resolve. Without the second arm a poisoned row is unrepairable
// and re-renders through chromium on every crawl, forever.
expect(text).toMatch(/thumbnail_key is null or thumbnail_key ~\* '\^https\?:\/\/\.\*_og\[\.\]png\$'/);
});
it('heals a poisoned key: thumbnailUrl gives null, the render write-back replaces it', async () => {
// A pre-fix row stores an ABSOLUTE `*_og.png` in thumbnail_key. thumbnailUrl()
// resolves that to null, so getAvatar hands the handler thumbnail_url: null
// and it takes the render path, which is exactly where the widened guard
// above overwrites the bad key with a real bucket key.
getAvatarMock.mockResolvedValueOnce({
id: 'a8',
name: 'Michelle',
thumbnail_url: null,
model_url: 'https://three.ws/avatars/michelle.glb',
storage_key: 'https://three.ws/avatars/michelle.glb',
tags: [],
});
renderGlbToPngMock.mockResolvedValueOnce(PNG_MAGIC);
const req = mkReq({ url: '/api/avatar/a8/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res._body).toEqual(PNG_MAGIC);
// An absolute storage_key is not a writable bucket key, so the OG object
// lands under the deterministic id-keyed path instead of a sibling.
expect(putObjectMock).toHaveBeenCalledTimes(1);
expect(putObjectMock.mock.calls[0][0].key).toBe('og/avatar/a8.png');
expect(sqlMock.mock.calls[0]).toContain('og/avatar/a8.png');
});
it('falls back to the named card on GLB-too-large precheck', async () => {
// 50 MB content-length triggers the 12 MB cap.
globalThis.fetch = vi.fn(async () => ({
ok: true,
headers: { get: (h) => (h.toLowerCase() === 'content-length' ? String(50 * 1024 * 1024) : null) },
}));
getAvatarMock.mockResolvedValueOnce({
id: 'a4',
name: 'Big',
thumbnail_url: null,
model_url: 'https://cdn.test/u/uid/big/123.glb',
storage_key: 'u/uid/big/123.glb',
});
const req = mkReq({ url: '/api/avatar/a4/og' });
const res = mkRes();
await handler(req, res);
// A branded card naming the avatar beats the anonymous site logo for crawlers.
expect(res.statusCode).toBe(200);
expect(res._h['content-type']).toMatch(/image\/svg/);
expect(String(res._body)).toContain('Big');
expect(renderGlbToPngMock).not.toHaveBeenCalled();
expect(putObjectMock).not.toHaveBeenCalled();
});
it('falls back to the named card when the renderer throws', async () => {
getAvatarMock.mockResolvedValueOnce({
id: 'a5',
name: 'Err',
thumbnail_url: null,
model_url: 'https://cdn.test/u/uid/err/123.glb',
storage_key: 'u/uid/err/123.glb',
});
renderGlbToPngMock.mockRejectedValueOnce(new Error('chromium crashed'));
const req = mkReq({ url: '/api/avatar/a5/og' });
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res._h['content-type']).toMatch(/image\/svg/);
expect(String(res._body)).toContain('Err');
expect(putObjectMock).not.toHaveBeenCalled();
expect(sqlMock).not.toHaveBeenCalled();
});
it('serializes concurrent renders for the same avatar id', async () => {
const avatar = {
id: 'a6',
name: 'Once',
thumbnail_url: null,
model_url: 'https://cdn.test/u/uid/once/123.glb',
storage_key: 'u/uid/once/123.glb',
};
getAvatarMock.mockResolvedValue(avatar);
// Block the render until both requests have started.
let resolveRender;
renderGlbToPngMock.mockImplementation(
() => new Promise((resolve) => { resolveRender = resolve; }),
);
const req1 = mkReq({ url: '/api/avatar/a6/og' });
const req2 = mkReq({ url: '/api/avatar/a6/og' });
const res1 = mkRes();
const res2 = mkRes();
const p1 = handler(req1, res1);
const p2 = handler(req2, res2);
// Give microtasks a chance to hit the lock check.
await new Promise((r) => setImmediate(r));
resolveRender(PNG_MAGIC);
await Promise.all([p1, p2]);
// Renderer invoked once despite two concurrent requests.
expect(renderGlbToPngMock).toHaveBeenCalledTimes(1);
expect(putObjectMock).toHaveBeenCalledTimes(1);
expect(sqlMock).toHaveBeenCalledTimes(1);
// Both responses got the PNG.
expect(res1._body).toEqual(PNG_MAGIC);
expect(res2._body).toEqual(PNG_MAGIC);
expect(res1.statusCode).toBe(200);
expect(res2.statusCode).toBe(200);
});
it('serves the self-contained card on render failure, never an attacker-controllable redirect', async () => {
// The fallback used to 302 to a logo URL built from request host headers,
// which a spoofed `x-forwarded-host` could repoint at an attacker site. The
// failure path now renders a self-contained SVG card inline — no Location
// header, so the header can't influence where a crawler is sent.
getAvatarMock.mockResolvedValueOnce({
id: 'a7',
name: 'X',
thumbnail_url: null,
model_url: 'https://cdn.test/u/uid/x/x.glb',
storage_key: 'u/uid/x/x.glb',
});
renderGlbToPngMock.mockRejectedValueOnce(new Error('boom'));
const req = mkReq({
url: '/api/avatar/a7/og',
headers: {
host: 'three.ws',
'x-forwarded-host': 'staging.three.ws',
'x-forwarded-proto': 'https',
},
});
const res = mkRes();
await handler(req, res);
expect(res.statusCode).toBe(200);
expect(res._h['content-type']).toMatch(/image\/svg/);
expect(res._h.location).toBeUndefined();
});
});