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
// Endpoint contracts for the /forge pipeline handlers: forge-og, forge-poster,
// forge-quality-check, forge-rembg, forge-remesh, forge-segment, forge-share,
// forge-stylize, forge-upload, forge-vote.
//
// Three of these pin regressions found while auditing the batch:
//
// 1. forge-stylize took `style` through a bare `STYLE_BOUNDS[body.style]`
// truthiness test. Every Object.prototype key is truthy there, so
// `style: "constructor"` walked past the allowlist and reached the worker
// with an unknown filter and a NaN resolution.
// 2. forge-upload did the same with `content_type`. Object.freeze does not
// detach a prototype, so `content_type: "constructor"` resolved to the
// Object function and presigned an upload whose storage key ended in the
// stringified builtin.
// 3. The four worker-backed pollers called provider.status() with no guard.
// An upstream fault escaped to wrap() as a 500, which fires a Sentry
// capture and an ops alert, once per poll, per client, for the length of
// a worker outage. They now answer a clean 502.
//
// The DB, object storage, the worker provider, and the rate limiter are the
// process boundaries; everything inside them is the real handler code.
import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
// forge-upload gates on the raw S3_* vars rather than on forge-store's helper,
// so the suite has to declare a configured deployment for it to get past the
// 503. Synthetic values: presignUpload and publicUrl are stubbed below, so
// nothing here reaches an object store.
const S3_ENV = {
S3_ENDPOINT: 'https://s3.test.invalid',
S3_BUCKET: 'test-bucket',
S3_PUBLIC_DOMAIN: 'https://cdn.test.invalid',
S3_ACCESS_KEY_ID: 'test-access-key',
S3_SECRET_ACCESS_KEY: 'test-secret-key',
};
const savedS3 = {};
for (const [k, v] of Object.entries(S3_ENV)) {
savedS3[k] = process.env[k];
process.env[k] = v;
}
afterAll(() => {
for (const k of Object.keys(S3_ENV)) {
if (savedS3[k] === undefined) delete process.env[k];
else process.env[k] = savedS3[k];
}
});
const sqlMock = vi.fn();
vi.mock('../../api/_lib/db.js', () => ({
sql: (...a) => sqlMock(...a),
isDbUnavailableError: () => false,
isDbCapacityError: () => false,
isStoragePressured: async () => ({ pressured: false }),
}));
const rlAllow = { value: true };
const limitStub = vi.fn(async () => ({ success: rlAllow.value, reset: Date.now() + 1_000, limit: 10, remaining: 0 }));
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
mcp3dGenerate: (...a) => limitStub(...a),
mcp3dStatus: (...a) => limitStub(...a),
upload: (...a) => limitStub(...a),
forgeVote: (...a) => limitStub(...a),
visionUser: (...a) => limitStub(...a),
visionIp: (...a) => limitStub(...a),
},
clientIp: () => '203.0.113.9',
}));
// Real SSRF policy is covered by its own suite; here it only has to let a
// known-good https URL through so the handler's own validation is what's tested.
class FakeSsrfError extends Error {}
vi.mock('../../api/_lib/ssrf.js', () => ({
SsrfError: FakeSsrfError,
assertPublicHttpsUrl: async (raw) => {
if (typeof raw !== 'string' || !raw.startsWith('https://')) {
throw new FakeSsrfError('must be a public https URL');
}
return raw;
},
}));
const submitted = [];
const providerState = { configured: true, statusThrows: false };
vi.mock('../../api/_providers/gcp.js', () => ({
createRegenProvider: () => {
if (!providerState.configured) throw new Error('no gcp worker configured');
return {
supportsMode: () => true,
async submit(job) {
submitted.push(job);
return { extJobId: 'j'.repeat(40), eta: 30 };
},
async status() {
if (providerState.statusThrows) throw new Error('worker unreachable');
return { status: 'running' };
},
};
},
}));
const storeState = { enabled: true };
const castVoteMock = vi.fn();
const removeVoteMock = vi.fn();
const attachPosterMock = vi.fn();
vi.mock('../../api/_lib/forge-store.js', () => ({
forgeStoreEnabled: () => storeState.enabled,
hashClient: (raw) => (typeof raw === 'string' && raw.trim() ? `h-${raw.trim()}` : 'anon'),
hashIp: (ip) => (ip ? `hip-${ip}` : null),
castVote: (...a) => castVoteMock(...a),
removeVote: (...a) => removeVoteMock(...a),
attachPoster: (...a) => attachPosterMock(...a),
}));
const presignMock = vi.fn(async ({ key }) => `https://r2.example/${key}?sig=abc`);
// Storage readiness is read through r2.js so the route cannot drift from it.
// Two independent failure modes, because they need different answers: no bucket
// on this deployment (`unconfigured`), and a bucket that refuses our credential
// (`rejected`). Default healthy, flipped per test.
const storageState = { configured: true, rejected: false };
vi.mock('../../api/_lib/r2.js', () => ({
presignUpload: (...a) => presignMock(...a),
publicUrl: (key) => `https://cdn.example/${key}`,
normalizeStoredUrl: (url) => url,
objectStorageConfigured: () => storageState.configured,
objectStorageUsable: async () => {
if (!storageState.configured) return { ok: false, reason: 'unconfigured', message: null };
if (storageState.rejected)
return { ok: false, reason: 'rejected', message: 'does not match the signature' };
return { ok: true, reason: null, message: null };
},
}));
vi.mock('../../api/_lib/auth.js', () => ({
getSessionUser: async () => null,
authenticateBearer: async () => null,
extractBearer: () => null,
}));
const gateState = { configured: false };
vi.mock('../../api/_lib/forge-quality-gate.js', () => ({
qualityGateConfigured: () => gateState.configured,
vertexQualityConfigured: () => false,
QUALITY_GATE_DEFAULTS: { model: 'gemini-test', passScore: 60, maxRetries: 2 },
runQualityGate: async () => ({ pass: true, qa_available: false, score: null }),
buildRetryDirective: () => ({ retry: true }),
}));
const [og, poster, qualityCheck, rembg, remesh, segment, share, stylize, upload, vote] = await Promise.all([
import('../../api/forge-og.js'),
import('../../api/forge-poster.js'),
import('../../api/forge-quality-check.js'),
import('../../api/forge-rembg.js'),
import('../../api/forge-remesh.js'),
import('../../api/forge-segment.js'),
import('../../api/forge-share.js'),
import('../../api/forge-stylize.js'),
import('../../api/forge-upload.js'),
import('../../api/forge-vote.js'),
]).then((mods) => mods.map((m) => m.default));
const UUID = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
const MESH = 'https://cdn.example/mesh.glb';
const JOB = 'j'.repeat(40);
function mkReq({ method = 'GET', url = '/', headers = {}, body } = {}) {
const hdrs = { ...headers };
let rawBody;
if (body !== undefined) {
if (!hdrs['content-type']) hdrs['content-type'] = 'application/json';
rawBody = Buffer.from(typeof body === 'string' ? body : JSON.stringify(body));
}
return { method, url, headers: hdrs, rawBody, on() {}, destroy() {} };
}
function mkRes() {
return {
statusCode: 200,
headers: {},
body: undefined,
writableEnded: false,
headersSent: false,
setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
getHeader(k) { return this.headers[k.toLowerCase()]; },
end(b) { this.body = b === undefined ? '' : String(b); this.writableEnded = true; },
};
}
async function call(handler, reqInit) {
const res = mkRes();
await handler(mkReq(reqInit), res);
return res;
}
const parse = (res) => (res.body ? JSON.parse(res.body) : undefined);
beforeEach(() => {
rlAllow.value = true;
providerState.configured = true;
providerState.statusThrows = false;
storeState.enabled = true;
gateState.configured = false;
submitted.length = 0;
sqlMock.mockReset();
castVoteMock.mockReset();
removeVoteMock.mockReset();
attachPosterMock.mockReset();
presignMock.mockClear();
limitStub.mockClear();
});
describe('forge-stylize', () => {
it('starts a job on a valid style and clamps the resolution', async () => {
const res = await call(stylize, {
method: 'POST',
url: '/api/forge-stylize',
body: { mesh_url: MESH, style: 'brick', resolution: 9_999 },
});
expect(res.statusCode).toBe(202);
expect(parse(res)).toMatchObject({ job_id: JOB, status: 'queued', style: 'brick', resolution: 64 });
expect(submitted[0].params).toMatchObject({ style: 'brick', resolution: 64 });
});
it('rejects a prototype key as a style instead of passing it to the worker', async () => {
for (const style of ['constructor', 'toString', 'valueOf', '__proto__', 'hasOwnProperty']) {
submitted.length = 0;
const res = await call(stylize, {
method: 'POST',
url: '/api/forge-stylize',
body: { mesh_url: MESH, style, resolution: 50 },
});
expect(res.statusCode).toBe(202);
// Falls back to the default filter with a real resolution. The bug sent
// `style: "constructor"` and a NaN resolution straight through.
expect(parse(res).style).toBe('voxel');
expect(submitted[0].params.style).toBe('voxel');
expect(Number.isFinite(submitted[0].params.resolution)).toBe(true);
expect(submitted[0].params.resolution).toBe(50);
}
});
it('rejects a non-https mesh_url at the boundary', async () => {
const res = await call(stylize, {
method: 'POST',
url: '/api/forge-stylize',
body: { mesh_url: 'http://169.254.169.254/latest' },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_mesh_url');
});
it('refuses an FBX mesh with a 400 naming the formats that work, before queuing a job', async () => {
submitted.length = 0;
const res = await call(stylize, {
method: 'POST',
url: '/api/forge-stylize',
body: { mesh_url: 'https://cdn.example/rig.FBX?sig=abc', style: 'voxel' },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('unsupported_mesh_format');
expect(parse(res).message).toContain('GLB, GLTF, OBJ, STL, PLY, OFF or DAE');
// The worker has no FBX reader, so a queued job could only fail later.
expect(submitted).toHaveLength(0);
});
it('still accepts a DAE mesh', async () => {
submitted.length = 0;
const res = await call(stylize, {
method: 'POST',
url: '/api/forge-stylize',
body: { mesh_url: 'https://cdn.example/scene.dae', style: 'voxel' },
});
expect(res.statusCode).toBe(202);
expect(submitted).toHaveLength(1);
});
it('answers 502, not 500, when the worker poll faults', async () => {
providerState.statusThrows = true;
const res = await call(stylize, { url: `/api/forge-stylize?job=${JOB}` });
expect(res.statusCode).toBe(502);
expect(parse(res).error).toBe('stylize_status_failed');
// No `status` field, so the client's poll loop retries rather than
// treating a transient worker fault as a failed job.
expect(parse(res).status).toBeUndefined();
});
it('503s with an actionable message when the worker is unconfigured', async () => {
providerState.configured = false;
const res = await call(stylize, { url: `/api/forge-stylize?job=${JOB}` });
expect(res.statusCode).toBe(503);
expect(parse(res).error).toBe('unconfigured');
});
});
describe('forge-rembg / forge-remesh / forge-segment', () => {
const lanes = [
{ name: 'rembg', handler: () => rembg, path: '/api/forge-rembg', urlField: 'image_url', code: 'rembg_status_failed' },
{ name: 'remesh', handler: () => remesh, path: '/api/forge-remesh', urlField: 'mesh_url', code: 'remesh_status_failed' },
{ name: 'segment', handler: () => segment, path: '/api/forge-segment', urlField: 'mesh_url', code: 'segment_status_failed' },
];
for (const lane of lanes) {
it(`${lane.name}: queues a job on a valid source URL`, async () => {
const res = await call(lane.handler(), {
method: 'POST',
url: lane.path,
body: { [lane.urlField]: MESH },
});
expect(res.statusCode).toBe(202);
expect(parse(res)).toMatchObject({ job_id: JOB, status: 'queued' });
});
it(`${lane.name}: 400s a malformed job id`, async () => {
const res = await call(lane.handler(), { url: `${lane.path}?job=short` });
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_job');
});
it(`${lane.name}: answers 502, not 500, when the worker poll faults`, async () => {
providerState.statusThrows = true;
const res = await call(lane.handler(), { url: `${lane.path}?job=${JOB}` });
expect(res.statusCode).toBe(502);
expect(parse(res).error).toBe(lane.code);
expect(parse(res).status).toBeUndefined();
});
it(`${lane.name}: 405s a verb it does not serve`, async () => {
const res = await call(lane.handler(), { method: 'DELETE', url: lane.path });
expect(res.statusCode).toBe(405);
});
}
});
describe('forge-upload', () => {
it('presigns an upload for an accepted image type', async () => {
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
headers: { 'x-forge-client': 'browser-1' },
body: { content_type: 'image/png', size_bytes: 1_000 },
});
expect(res.statusCode).toBe(200);
const out = parse(res);
expect(out.storage_key).toMatch(/^forge\/uploads\/[^/]+\/[0-9a-f-]{36}\.png$/);
expect(out.method).toBe('PUT');
expect(out.headers['content-type']).toBe('image/png');
expect(out.upload_url).toContain(out.storage_key);
});
// A rejected or whitespace-only R2 credential must degrade to the designed
// "paste a URL" 503. Before the route shared r2.js's trimmed check it would
// hand out a presigned URL that answers 403 with no CORS header, which the
// page can only report as "Network error during upload".
it('503s to the paste-a-URL fallback when object storage is unconfigured', async () => {
storageState.configured = false;
try {
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
headers: { 'x-forge-client': 'browser-1' },
body: { content_type: 'image/png', size_bytes: 1_000 },
});
expect(res.statusCode).toBe(503);
expect(parse(res).error).toBe('unconfigured');
expect(presignMock).not.toHaveBeenCalled();
} finally {
storageState.configured = true;
}
});
// The failure users actually hit on 2026-09-07: every var was present, so the
// old presence-only check called storage healthy and returned 200 with a URL
// the bucket then rejected. Cross-origin, that 403 has no CORS header, so the
// page could only say "Network error during upload" over a photo that was
// never at fault. The route must refuse to mint the URL at all.
it('503s without minting a URL when the bucket rejects our credential', async () => {
storageState.rejected = true;
try {
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
headers: { 'x-forge-client': 'browser-1' },
body: { content_type: 'image/png', size_bytes: 1_000 },
});
expect(res.statusCode).toBe(503);
expect(parse(res).error).toBe('storage_unavailable');
expect(res.headers['retry-after']).toBeDefined();
expect(presignMock).not.toHaveBeenCalled();
} finally {
storageState.rejected = false;
}
});
it('rejects a prototype key as a content type', async () => {
for (const contentType of ['constructor', '__proto__', 'tostring']) {
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
body: { content_type: contentType, size_bytes: 1_000 },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_content_type');
expect(presignMock).not.toHaveBeenCalled();
}
});
it('rejects a size outside the cap', async () => {
for (const size of [0, -1, 9 * 1024 * 1024, 'big']) {
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
body: { content_type: 'image/png', size_bytes: size },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_size');
}
});
it('surfaces a presign failure as 502', async () => {
presignMock.mockRejectedValueOnce(new Error('bucket unreachable'));
const res = await call(upload, {
method: 'POST',
url: '/api/forge-upload',
body: { content_type: 'image/webp', size_bytes: 2_000 },
});
expect(res.statusCode).toBe(502);
expect(parse(res).error).toBe('presign_failed');
});
});
describe('forge-vote', () => {
it('casts a vote and returns the authoritative tally', async () => {
castVoteMock.mockResolvedValueOnce({ creationId: UUID, voteCount: 4, voted: true });
const res = await call(vote, {
method: 'POST',
url: '/api/forge-vote',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID },
});
expect(res.statusCode).toBe(200);
expect(parse(res)).toEqual({ ok: true, creation_id: UUID, vote_count: 4, voted: true });
expect(castVoteMock).toHaveBeenCalledWith({ creationId: UUID, voterKey: 'h-browser-1', ipHash: 'hip-203.0.113.9' });
});
it('removes a vote on an explicit vote:false', async () => {
removeVoteMock.mockResolvedValueOnce({ creationId: UUID, voteCount: 3, voted: false });
const res = await call(vote, {
method: 'POST',
url: '/api/forge-vote',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID, vote: false },
});
expect(res.statusCode).toBe(200);
expect(parse(res).voted).toBe(false);
expect(castVoteMock).not.toHaveBeenCalled();
});
it('refuses a vote with no stable client id', async () => {
const res = await call(vote, { method: 'POST', url: '/api/forge-vote', body: { creation_id: UUID } });
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('no_client_id');
expect(castVoteMock).not.toHaveBeenCalled();
});
it('404s a creation that is not votable', async () => {
castVoteMock.mockResolvedValueOnce(null);
const res = await call(vote, {
method: 'POST',
url: '/api/forge-vote',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID },
});
expect(res.statusCode).toBe(404);
expect(parse(res).error).toBe('not_votable');
});
it('400s a malformed creation id', async () => {
const res = await call(vote, {
method: 'POST',
url: '/api/forge-vote',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: 'not-a-uuid' },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_creation');
});
});
describe('forge-poster', () => {
const PNG = 'data:image/png;base64,iVBORw0KGgo=';
it('attaches a poster and returns the stored preview URL', async () => {
attachPosterMock.mockResolvedValueOnce('https://cdn.example/forge/h-browser/poster.png');
const res = await call(poster, {
method: 'POST',
url: '/api/forge-poster',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID, image: PNG },
});
expect(res.statusCode).toBe(200);
expect(parse(res)).toMatchObject({ ok: true, stored: true });
expect(attachPosterMock.mock.calls[0][0]).toMatchObject({
id: UUID,
clientKey: 'h-browser-1',
contentType: 'image/png',
ext: 'png',
});
});
it('reports a benign no-op as stored:false rather than an error', async () => {
attachPosterMock.mockResolvedValueOnce(null);
const res = await call(poster, {
method: 'POST',
url: '/api/forge-poster',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID, image: PNG },
});
expect(res.statusCode).toBe(200);
expect(parse(res)).toMatchObject({ ok: true, stored: false, preview_image_url: null });
});
it('400s anything that is not a webp/png/jpeg data URL', async () => {
for (const image of ['notadataurl', 'data:image/gif;base64,R0lGOD', 'data:image/png;base64,', 'data:text/html,<script>']) {
const res = await call(poster, {
method: 'POST',
url: '/api/forge-poster',
headers: { 'x-forge-client': 'browser-1' },
body: { creation_id: UUID, image },
});
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('invalid_image');
expect(attachPosterMock).not.toHaveBeenCalled();
}
});
it('short-circuits cleanly when persistence is unconfigured', async () => {
storeState.enabled = false;
const res = await call(poster, {
method: 'POST',
url: '/api/forge-poster',
body: { creation_id: UUID, image: PNG },
});
expect(res.statusCode).toBe(200);
expect(parse(res)).toEqual({ ok: false, stored: false, reason: 'persistence_unconfigured' });
});
});
describe('forge-quality-check', () => {
it('serves a capability probe on GET', async () => {
const res = await call(qualityCheck, { url: '/api/forge-quality-check' });
expect(res.statusCode).toBe(200);
expect(parse(res)).toMatchObject({ configured: false, provider: null, passScore: 60, maxRetries: 2 });
});
it('serves the same probe on HEAD', async () => {
gateState.configured = true;
const res = await call(qualityCheck, { method: 'HEAD', url: '/api/forge-quality-check' });
expect(res.statusCode).toBe(200);
expect(parse(res)).toMatchObject({ configured: true, provider: 'platform-vision' });
});
it('400s a POST with no model to score', async () => {
const res = await call(qualityCheck, { method: 'POST', url: '/api/forge-quality-check', body: {} });
expect(res.statusCode).toBe(400);
expect(parse(res).error).toBe('bad_request');
});
it('scores a supplied render and fails open', async () => {
const res = await call(qualityCheck, {
method: 'POST',
url: '/api/forge-quality-check',
body: { renderUrl: 'https://cdn.example/render.png', prompt: 'a red chair' },
});
expect(res.statusCode).toBe(200);
expect(parse(res)).toEqual({ verdict: { pass: true, qa_available: false, score: null }, retry: null });
});
});
describe('forge-og', () => {
it('302s to the creation preview when one exists', async () => {
sqlMock.mockResolvedValueOnce([{ id: UUID, prompt: 'a red chair', preview_image_url: 'https://cdn.example/p.png' }]);
const res = await call(og, { url: `/api/forge-og?id=${UUID}` });
expect(res.statusCode).toBe(302);
expect(res.headers.location).toBe('https://cdn.example/p.png');
});
it('renders an SVG card when the row has no preview', async () => {
sqlMock.mockResolvedValueOnce([{ id: UUID, prompt: 'a <script> chair', preview_image_url: null }]);
const res = await call(og, { url: `/api/forge-og?id=${UUID}` });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('image/svg+xml');
expect(res.body).toContain('<script>');
expect(res.body).not.toContain('<script>');
});
it('falls back to a 404 card on a malformed id without touching the DB', async () => {
const res = await call(og, { url: '/api/forge-og?id=not-a-uuid' });
expect(res.statusCode).toBe(404);
expect(res.headers['content-type']).toContain('image/svg+xml');
expect(sqlMock).not.toHaveBeenCalled();
});
it('falls back to a card when the DB read throws', async () => {
sqlMock.mockRejectedValueOnce(new Error('db down'));
const res = await call(og, { url: `/api/forge-og?id=${UUID}` });
expect(res.statusCode).toBe(404);
expect(res.headers['content-type']).toContain('image/svg+xml');
});
});
describe('forge-share', () => {
it('bakes escaped OG, Twitter, Frame and oEmbed tags into the page', async () => {
sqlMock.mockResolvedValueOnce([
{ id: UUID, prompt: 'a "quoted" <chair>', preview_image_url: 'https://cdn.example/p.png', status: 'done' },
]);
const res = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('text/html');
expect(res.body).toContain('property="og:image" content="https://cdn.example/p.png"');
expect(res.body).toContain('name="twitter:card" content="summary_large_image"');
expect(res.body).toContain('property="fc:frame" content="vNext"');
expect(res.body).toContain('application/json+oembed');
expect(res.body).toContain('"quoted"');
expect(res.body).not.toContain('<chair>');
});
it('points og:image at the card endpoint when the row has no preview', async () => {
sqlMock.mockResolvedValueOnce([{ id: UUID, prompt: 'a chair', preview_image_url: null, status: 'done' }]);
const res = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(res.body).toContain(`/api/forge-og?id=${UUID}`);
});
it('serves an X player card for a finished creation, embedding the real GLB via /forge/embed', async () => {
sqlMock.mockResolvedValueOnce([
{
id: UUID,
prompt: 'a brass lantern',
preview_image_url: null,
status: 'done',
glb_url: MESH,
web_glb_url: null,
web_size_bytes: null,
size_bytes: 1_800_000,
},
]);
const res = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(res.body).toContain('name="twitter:card" content="player"');
expect(res.body).toMatch(/name="twitter:player" content="https:\/\/three\.ws\/forge\/embed\?src=[^"]*mesh\.glb/);
expect(res.body).toContain('name="twitter:player:width" content="480"');
expect(res.body).toContain('name="twitter:player:height" content="480"');
// Fallback image stays present for clients that only read twitter:image/og:image.
expect(res.body).toMatch(/name="twitter:image" content="[^"]+"/);
});
it('falls back to summary_large_image, with no twitter:player tag, for a creation still in progress', async () => {
sqlMock.mockResolvedValueOnce([
{ id: UUID, prompt: 'a chair', preview_image_url: null, status: 'processing', glb_url: null },
]);
const res = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(res.body).toContain('name="twitter:card" content="summary_large_image"');
expect(res.body).not.toContain('name="twitter:player"');
});
it('describes a finished creation as parseable 3DModel JSON-LD, and never reads a private one', async () => {
sqlMock.mockResolvedValueOnce([
{
id: UUID,
prompt: 'a brass lantern',
preview_image_url: null,
status: 'done',
glb_url: MESH,
web_glb_url: null,
web_size_bytes: null,
size_bytes: 1_800_000,
model_category: 'prop',
created_at: new Date('2026-07-08T09:02:40Z'),
creator_username: 'nirholas',
creator_display_name: 'Nir',
},
]);
const res = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(sqlMock.mock.calls[0][0].join('?')).toMatch(/visibility IN \('public', 'unlisted'\)/);
const ld = JSON.parse(res.body.match(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/)[1]);
const model = ld['@graph'][0];
expect(model['@type']).toBe('3DModel');
expect(model.encoding[0]).toMatchObject({ contentUrl: MESH, encodingFormat: 'model/gltf-binary' });
expect(model.thumbnailUrl).toContain(`/api/render/glb?glbUrl=${encodeURIComponent(MESH)}`);
expect(model.creator).toMatchObject({ url: 'https://three.ws/u/nirholas' });
expect(model.license).toBe('https://three.ws/legal/tos');
expect(model.sameAs).toBe(`https://three.ws/m/${UUID}`);
// No reference image, so the card is the render of the model itself.
expect(res.body).toContain(`name="twitter:image" content="https://three.ws/api/render/glb?glbUrl=`);
});
it('redirects to /forge on a malformed or unknown id', async () => {
const bad = await call(share, { url: '/api/forge-share?id=nope' });
expect(bad.statusCode).toBe(302);
expect(bad.headers.location).toContain('/forge');
expect(sqlMock).not.toHaveBeenCalled();
sqlMock.mockResolvedValueOnce([]);
const missing = await call(share, { url: `/api/forge-share?id=${UUID}` });
expect(missing.statusCode).toBe(302);
expect(missing.headers.location).toContain('/forge');
});
});
describe('rate limiting', () => {
it('429s every metered lane when the bucket is exhausted', async () => {
rlAllow.value = false;
const cases = [
[stylize, { method: 'POST', url: '/api/forge-stylize', body: { mesh_url: MESH } }],
[rembg, { method: 'POST', url: '/api/forge-rembg', body: { image_url: MESH } }],
[remesh, { url: `/api/forge-remesh?job=${JOB}` }],
[segment, { url: `/api/forge-segment?job=${JOB}` }],
[upload, { method: 'POST', url: '/api/forge-upload', body: { content_type: 'image/png', size_bytes: 10 } }],
[vote, { method: 'POST', url: '/api/forge-vote', headers: { 'x-forge-client': 'b' }, body: { creation_id: UUID } }],
[poster, { method: 'POST', url: '/api/forge-poster', body: { creation_id: UUID, image: 'data:image/png;base64,iVBORw0KGgo=' } }],
];
for (const [handler, reqInit] of cases) {
const res = await call(handler, reqInit);
expect(res.statusCode).toBe(429);
expect(res.headers['retry-after']).toBeDefined();
}
});
});