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
feat(herald): cover the announce endpoint and finish the playground page
nirholasce530f4b81bb
diff --git a/tests/herald-announce-endpoint.test.js b/tests/herald-announce-endpoint.test.jsnew file mode 100644index 000000000..cb294b16e--- /dev/null+++ b/tests/herald-announce-endpoint.test.js@@ -0,0 +1,245 @@+/**+ * 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);+ });+});