Skip to content

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.

test(api): lock the play oEmbed provider contract and the share surfaces' GET-only gate

nirholas133cb14de334
diff --git a/tests/play-oembed.test.js b/tests/play-oembed.test.js
new file mode 100644
index 000000000..1f46a84ef
--- /dev/null
+++ b/tests/play-oembed.test.js
@@ -0,0 +1,136 @@
+// Contract for the /play Coin Communities oEmbed provider (api/play-oembed.js).
+//
+// An oEmbed provider hands a third-party consumer (WordPress, Ghost, Discord,
+// Notion, every iframely/embed.ly editor) an iframe it will render under OUR
+// provider name. Three things therefore have to hold, and each one has already
+// been wrong here:
+//
+// 1. The embed target is the canonical app origin, NEVER the request's Host
+// header. The handler used to echo `x-forwarded-host` straight into
+// `html` and `provider_url`, so one crafted request handed any consumer
+// an iframe pointing at an attacker's site, badged "three.ws".
+// 2. The provider answers only for URLs in its own scheme. A foreign url is
+// a 404 per oembed.com, not a generic three.ws card.
+// 3. The documented status codes are real: 400 without url, 501 for a format
+// the provider cannot produce, 405 for a non-GET.
+//
+// Driven end to end against the real default export; the handler needs no
+// database, chain read, or network, so there is nothing to stub.
+
+import { describe, it, expect } from 'vitest';
+
+import handler from '../api/play-oembed.js';
+import { env } from '../api/_lib/env.js';
+
+const MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+
+async function invoke(url, { method = 'GET', headers = {} } = {}) {
+ const chunks = [];
+ const outHeaders = {};
+ let statusCode = 200;
+ const res = {
+ setHeader(k, v) { outHeaders[k.toLowerCase()] = v; },
+ getHeader(k) { return outHeaders[k.toLowerCase()]; },
+ end(buf) { if (buf) chunks.push(Buffer.from(buf)); },
+ get statusCode() { return statusCode; },
+ set statusCode(v) { statusCode = v; },
+ get headersSent() { return false; },
+ get writableEnded() { return false; },
+ };
+ await handler({ method, url, headers: { host: 'three.ws', ...headers } }, res);
+ const body = Buffer.concat(chunks).toString('utf8');
+ return { body, headers: outHeaders, statusCode, json: () => JSON.parse(body) };
+}
+
+function oembedUrl(target, extra = '') {
+ return `/api/play-oembed?url=${encodeURIComponent(target)}${extra}`;
+}
+
+describe('play oEmbed provider', () => {
+ it('embeds a coin world from the canonical share link', async () => {
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/play?coin=${MINT}`));
+ expect(r.statusCode).toBe(200);
+ expect(r.headers['content-type']).toContain('json+oembed');
+ const p = r.json();
+ expect(p.version).toBe('1.0');
+ expect(p.type).toBe('rich');
+ expect(p.provider_url).toBe(env.APP_ORIGIN);
+ expect(p.html).toContain(`${env.APP_ORIGIN}/play?coin=${MINT}&embed=1`);
+ expect(p.thumbnail_url).toBe(`${env.APP_ORIGIN}/api/play-og?coin=${MINT}`);
+ expect(p.thumbnail_width).toBe(1200);
+ expect(p.thumbnail_height).toBe(630);
+ });
+
+ it('accepts the /play/<mint> path form', async () => {
+ const p = (await invoke(oembedUrl(`${env.APP_ORIGIN}/play/${MINT}`))).json();
+ expect(p.html).toContain(`coin=${MINT}`);
+ });
+
+ it('serves the coin-agnostic world when no mint is in the link', async () => {
+ const p = (await invoke(oembedUrl(`${env.APP_ORIGIN}/play`))).json();
+ expect(p.html).toContain(`${env.APP_ORIGIN}/play?embed=1`);
+ expect(p.title).toBe('three.ws · Coin Communities');
+ });
+
+ it('ignores a mint that is not a Solana address', async () => {
+ const p = (await invoke(oembedUrl(`${env.APP_ORIGIN}/play?coin=not-a-mint`))).json();
+ expect(p.html).not.toContain('not-a-mint');
+ expect(p.html).toContain(`${env.APP_ORIGIN}/play?embed=1`);
+ });
+
+ it('never frames a forged Host into the payload it hands a consumer', async () => {
+ const forged = { 'x-forwarded-host': 'evil.example.com', host: 'evil.example.com' };
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/play?coin=${MINT}`), { headers: forged });
+ const p = r.json();
+ expect(p.provider_url).toBe(env.APP_ORIGIN);
+ expect(p.html).not.toContain('evil.example.com');
+ expect(p.thumbnail_url).not.toContain('evil.example.com');
+ expect(p.html).toContain(`${env.APP_ORIGIN}/play`);
+ });
+
+ it('404s a url that is not one of ours', async () => {
+ const r = await invoke(oembedUrl('https://evil.example.com/play?coin=' + MINT));
+ expect(r.statusCode).toBe(404);
+ expect(r.json().error).toBe('not_found');
+ });
+
+ it('404s our own origin outside the /play surface', async () => {
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/account`));
+ expect(r.statusCode).toBe(404);
+ });
+
+ it('serves xml when the consumer asks for it', async () => {
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/play?coin=${MINT}`, '&format=xml'));
+ expect(r.statusCode).toBe(200);
+ expect(r.headers['content-type']).toContain('text/xml');
+ expect(r.body.startsWith('<?xml version="1.0"')).toBe(true);
+ expect(r.body).toContain('<provider_url>https://three.ws</provider_url>');
+ // The iframe markup must arrive escaped, not as live child elements.
+ expect(r.body).toContain('&lt;iframe');
+ expect(r.body).not.toContain('<iframe');
+ });
+
+ it('clamps consumer-supplied dimensions', async () => {
+ const p = (await invoke(oembedUrl(`${env.APP_ORIGIN}/play`, '&maxwidth=99999&maxheight=1'))).json();
+ expect(p.width).toBe(1920);
+ expect(p.height).toBe(160);
+ });
+
+ it('rejects a format it cannot produce with 501', async () => {
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/play`, '&format=yaml'));
+ expect(r.statusCode).toBe(501);
+ expect(r.json().error).toBe('unsupported_format');
+ });
+
+ it('requires the url parameter', async () => {
+ const r = await invoke('/api/play-oembed');
+ expect(r.statusCode).toBe(400);
+ expect(r.json().error).toBe('invalid_request');
+ });
+
+ it('rejects a non-GET method', async () => {
+ const r = await invoke(oembedUrl(`${env.APP_ORIGIN}/play`), { method: 'POST' });
+ expect(r.statusCode).toBe(405);
+ expect(r.json().error).toBe('method_not_allowed');
+ });
+});
diff --git a/tests/share-endpoint-method-gates.test.js b/tests/share-endpoint-method-gates.test.js
new file mode 100644
index 000000000..f0761b33b
--- /dev/null
+++ b/tests/share-endpoint-method-gates.test.js
@@ -0,0 +1,67 @@
+// Every share/verification surface in this batch is a GET-only read, and each
+// one used to render its full response for ANY verb: a POST to /api/page-og or
+// /api/play-og drove a complete satori rasterization, a POST to
+// /api/oracle-share ran the database read plus a live pump.fun fetch, and
+// /api/og-leaderboard answered with an untyped `method not allowed` text body
+// that a consumer sniffs as HTML.
+//
+// This locks the gate: a non-GET is a 405 carrying the shared JSON error shape
+// and an Allow header, decided before any renderer, database, or upstream call
+// runs. Nothing here needs a network, so a rejected method is fully offline.
+
+import { describe, it, expect } from 'vitest';
+
+import pageOg from '../api/page-og.js';
+import playOg from '../api/play-og.js';
+import ogLeaderboard from '../api/og-leaderboard.js';
+import provenance from '../api/provenance.js';
+import oracleShare from '../api/oracle-share.js';
+
+function collector() {
+ const chunks = [];
+ const headers = {};
+ let statusCode = 200;
+ return {
+ res: {
+ setHeader(k, v) { headers[k.toLowerCase()] = v; },
+ getHeader(k) { return headers[k.toLowerCase()]; },
+ end(buf) { if (buf) chunks.push(Buffer.from(buf)); },
+ get statusCode() { return statusCode; },
+ set statusCode(v) { statusCode = v; },
+ get headersSent() { return false; },
+ get writableEnded() { return false; },
+ },
+ read: () => ({ body: Buffer.concat(chunks).toString('utf8'), headers, statusCode }),
+ };
+}
+
+const SURFACES = [
+ ['page-og', pageOg, '/api/page-og?t=Test'],
+ ['play-og', playOg, '/api/play-og'],
+ ['og-leaderboard', ogLeaderboard, '/api/og-leaderboard'],
+ ['provenance', provenance, '/api/provenance'],
+ ['oracle-share', oracleShare, '/api/oracle-share?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump'],
+];
+
+describe('share surfaces reject non-GET methods', () => {
+ for (const [name, handler, url] of SURFACES) {
+ it(`${name} answers POST with a 405 JSON error`, async () => {
+ const c = collector();
+ await handler({ method: 'POST', url, headers: { host: 'three.ws' } }, c.res);
+ const r = c.read();
+ expect(r.statusCode).toBe(405);
+ expect(String(r.headers['content-type'])).toContain('application/json');
+ expect(String(r.headers.allow)).toContain('GET');
+ expect(JSON.parse(r.body).error).toBe('method_not_allowed');
+ });
+
+ it(`${name} still advertises GET as allowed`, async () => {
+ const c = collector();
+ await handler({ method: 'DELETE', url, headers: { host: 'three.ws' } }, c.res);
+ const r = c.read();
+ expect(r.statusCode).toBe(405);
+ expect(String(r.headers.allow)).toMatch(/GET/);
+ expect(String(r.headers.allow)).toMatch(/HEAD/);
+ });
+ }
+});