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
/**
* HTTP-level tests for POST /api/herald/announce, the rail that lets a build
* script, a cron, or an AI agent make the caller's own avatar say something.
*
* The pieces worth pinning are the ones that decide who can interrupt whom:
*
* 1. A session or a key with the `herald:announce` scope, and nothing else.
* A valid key WITHOUT the scope must be a 403, not a delivery: keys are
* minted for other purposes and must not silently gain this one.
* 2. The record that lands on the queue is normalised, not echoed. A hostile
* url never reaches the recipient's page as a clickable link.
* 3. A queue write that fails is a 503, never a 202: "queued" has to mean it.
*
* Only the impure edges are stubbed (auth, Redis, the rate limiter). The
* handler, its validation, and its wire shape are the real module.
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
let sessionUser = null;
let bearerResult = null;
vi.mock('../api/_lib/auth.js', () => ({
getSessionUser: async () => sessionUser,
authenticateBearer: async () => bearerResult,
extractBearer: (req) => {
const h = req.headers.authorization || '';
return h.toLowerCase().startsWith('bearer ') ? h.slice(7) : null;
},
hasScope: (granted, required) => {
const g = new Set((granted || '').split(/\s+/).filter(Boolean));
return required.split(/\s+/).every((s) => g.has(s));
},
}));
const redisOps = [];
let redisAvailable = true;
let redisThrows = false;
vi.mock('../api/_lib/redis.js', () => ({
getRedis: () =>
redisAvailable
? {
async rpush(key, value) {
if (redisThrows) throw new Error('upstash down');
redisOps.push(['rpush', key, value]);
return 1;
},
async ltrim(key, start, stop) {
redisOps.push(['ltrim', key, start, stop]);
},
async expire(key, ttl) {
redisOps.push(['expire', key, ttl]);
},
}
: null,
}));
const heraldAnnounce = vi.fn(async () => ({
success: true,
limit: 60,
remaining: 59,
reset: Date.now() + 60_000,
}));
vi.mock('../api/_lib/rate-limit.js', () => ({
limits: { heraldAnnounce: (...a) => heraldAnnounce(...a) },
clientIp: () => '127.0.0.1',
}));
const { default: handler } = await import('../api/herald/announce.js');
function mockRes() {
return {
statusCode: 200,
_headers: {},
_body: '',
setHeader(k, v) {
this._headers[k.toLowerCase()] = v;
},
getHeader(k) {
return this._headers[k.toLowerCase()];
},
end(b) {
this._body = b || '';
},
get json() {
try {
return JSON.parse(this._body);
} catch {
return null;
}
},
};
}
function mockReq(body, headers = {}) {
// The platform's readBody() concatenates Buffers, so the stub must emit
// Buffers too or every handler test 500s inside the body reader.
const payload = Buffer.from(JSON.stringify(body));
return {
method: 'POST',
url: '/api/herald/announce',
headers: { host: 'three.ws', origin: 'https://three.ws', 'content-type': 'application/json', ...headers },
on(event, cb) {
if (event === 'data') cb(payload);
if (event === 'end') cb();
return this;
},
};
}
const post = async (body, headers) => {
const res = mockRes();
await handler(mockReq(body, headers), res);
return res;
};
beforeEach(() => {
sessionUser = null;
bearerResult = null;
redisAvailable = true;
redisThrows = false;
redisOps.length = 0;
heraldAnnounce.mockClear();
});
describe('who may interrupt', () => {
it('rejects an anonymous caller', async () => {
const res = await post({ text: 'hello' });
expect(res.statusCode).toBe(401);
});
it('accepts a signed-in session', async () => {
sessionUser = { id: 'user-1' };
const res = await post({ text: 'Deploy is green' });
expect(res.statusCode).toBe(202);
expect(res.json.queued).toBe(true);
});
it('accepts a key carrying the herald:announce scope', async () => {
bearerResult = { userId: 'user-2', scope: 'profile herald:announce' };
const res = await post({ text: 'from CI' }, { authorization: 'Bearer sk_live_x' });
expect(res.statusCode).toBe(202);
expect(redisOps[0][1]).toBe('herald:user-2:queue');
});
it('refuses a valid key that was never granted the scope', async () => {
bearerResult = { userId: 'user-3', scope: 'avatars:read' };
const res = await post({ text: 'sneaky' }, { authorization: 'Bearer sk_live_y' });
expect(res.statusCode).toBe(403);
expect(res.json.error).toBe('insufficient_scope');
expect(redisOps).toHaveLength(0);
});
it('always delivers to the caller, never to an address in the body', async () => {
sessionUser = { id: 'user-1' };
await post({ text: 'hi', to: 'someone-else', user_id: 'someone-else' });
expect(redisOps[0][1]).toBe('herald:user-1:queue');
});
});
describe('the record that lands on the queue', () => {
beforeEach(() => {
sessionUser = { id: 'user-1' };
});
it('normalises the announcement rather than echoing the body', async () => {
const res = await post({
text: ' Deploy is green ',
importance: 88,
url: '/dashboard',
from: 'CI',
});
const queued = JSON.parse(redisOps[0][2]);
expect(queued.text).toBe('Deploy is green');
expect(queued.importance).toBe(88);
expect(queued.url).toBe('/dashboard');
expect(queued.from).toBe('CI');
expect(queued.id).toEqual(expect.any(String));
expect(res.json.announcement.text).toBe('Deploy is green');
});
it('drops a url that could execute or redirect off-site', async () => {
await post({ text: 'click me', url: 'javascript:alert(1)' });
expect(JSON.parse(redisOps[0][2]).url).toBeUndefined();
});
it('accepts `message` as an alias for `text`', async () => {
const res = await post({ message: 'alias works' });
expect(res.statusCode).toBe(202);
expect(JSON.parse(redisOps[0][2]).text).toBe('alias works');
});
it('rejects a body with no line in it', async () => {
const res = await post({ from: 'CI' });
expect(res.statusCode).toBe(400);
});
it('caps the backlog and expires the queue', async () => {
await post({ text: 'one' });
const ops = redisOps.map((o) => o[0]);
expect(ops).toEqual(['rpush', 'ltrim', 'expire']);
const [, , ttl] = redisOps[2];
expect(ttl).toBeLessThanOrEqual(600);
});
});
describe('when the rail is unavailable', () => {
beforeEach(() => {
sessionUser = { id: 'user-1' };
});
it('answers 503 rather than claiming a delivery', async () => {
redisAvailable = false;
const res = await post({ text: 'nobody will hear this' });
expect(res.statusCode).toBe(503);
expect(res.json.queued).toBeUndefined();
});
it('answers 503 when the write itself fails', async () => {
redisThrows = true;
const res = await post({ text: 'write fails' });
expect(res.statusCode).toBe(503);
});
});
describe('rate limiting', () => {
it('is keyed by the user, so one integration cannot spend another account budget', async () => {
sessionUser = { id: 'user-42' };
await post({ text: 'hello' });
expect(heraldAnnounce).toHaveBeenCalledWith('user-42');
});
it('returns 429 when the bucket is empty', async () => {
sessionUser = { id: 'user-1' };
heraldAnnounce.mockResolvedValueOnce({
success: false,
limit: 60,
remaining: 0,
reset: Date.now() + 30_000,
});
const res = await post({ text: 'too much' });
expect(res.statusCode).toBe(429);
});
});