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.

15.3 KB
Raw Blame
// The companion bridge token is the credential a device holds. The desktop app,
// the CLI (`companion login`, `list`, `check`, `doctor`), the MCP server's
// `list_deliveries` tool and the stage all hand @three-ws/companion nothing but
// that token, so every route the SDK calls has to accept it, and each one must
// resolve it to exactly its owner: never to another account's feed, contacts,
// or messages. The routes that change what the companion is (contact edits,
// settings, sources) refuse it with a 403 that says so.
//
// The store is replaced by an in-memory one with the same user-scoped contract
// as api/_lib/companion/store.js (every lookup takes the caller's user id and
// misses on a row another account owns), so these tests exercise the real
// handlers, the real caller resolver, and the real SDK client end to end.

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { Readable } from 'node:stream';

const ALICE = 'aaaaaaaa-0000-4000-8000-000000000001';
const BOB = 'bbbbbbbb-0000-4000-8000-000000000002';
const ALICE_TOKEN = 'cmp_alice_bridge_token_0123456789abcdef';
const BOB_TOKEN = 'cmp_bob_bridge_token_0123456789abcdefgh';
const ALICE_EVENT = 'a1a1a1a1-1111-4111-8111-111111111111';
const BOB_EVENT = 'b2b2b2b2-2222-4222-8222-222222222222';

const state = {
	session: null,
	csrfCalls: [],
	rateKeys: [],
	marked: [],
	replies: [],
	polled: [],
	upserts: [],
};

function freshDb() {
	return {
		settings: {
			[ALICE]: { user_id: ALICE, ingest_token: ALICE_TOKEN, threshold: 60, enabled: true },
			[BOB]: { user_id: BOB, ingest_token: BOB_TOKEN, threshold: 40, enabled: true },
		},
		events: [
			{ id: ALICE_EVENT, user_id: ALICE, source_kind: 'telegram', title: 'Sarah: at the door', importance: 88, reply_to: { chat_id: 1, message_id: 7 } },
			{ id: BOB_EVENT, user_id: BOB, source_kind: 'telegram', title: 'Bob private message', importance: 91, reply_to: { chat_id: 2, message_id: 9 } },
		],
		contacts: [
			{ id: 'c-alice', user_id: ALICE, identifier: 'sarah', display_name: 'Sarah' },
			{ id: 'c-bob', user_id: BOB, identifier: 'carol', display_name: 'Carol' },
		],
	};
}
let db = freshDb();

// What the real queries select: the owner id and the reply routing stay server side.
function strip(row) {
	const out = { ...row };
	delete out.user_id;
	delete out.reply_to;
	return out;
}

vi.mock('../api/_lib/auth.js', () => ({
	extractBearer(req) {
		const h = req.headers.authorization || '';
		if (!h.toLowerCase().startsWith('bearer ')) return null;
		return h.slice(7).trim();
	},
	getRequestUser: vi.fn(async () => state.session),
	requestUserHasScope(user, required) {
		if (!user) return false;
		if (user.source !== 'bearer') return true;
		return String(user.scope || '').split(/\s+/).includes(required);
	},
}));

vi.mock('../api/_lib/companion/store.js', () => ({
	userForIngestToken: vi.fn(async (token) => {
		const row = Object.values(db.settings).find((s) => s.ingest_token === token);
		return row ? { ...row } : null;
	}),
	getSettings: vi.fn(async (userId) => db.settings[userId]),
	updateSettings: vi.fn(),
	rotateIngestToken: vi.fn(),
	listEvents: vi.fn(async (userId) => db.events.filter((e) => e.user_id === userId).map(strip)),
	markEvent: vi.fn(async (userId, id, flags) => {
		const row = db.events.find((e) => e.id === id && e.user_id === userId);
		if (!row) return null;
		state.marked.push({ userId, id, flags });
		return { id, delivered_at: flags.delivered ? '2026-10-09T00:00:00.000Z' : null, dismissed_at: null };
	}),
	getReplyTarget: vi.fn(async (userId, id) => {
		const row = db.events.find((e) => e.id === id && e.user_id === userId);
		if (!row) return null;
		return { ...row, source_kind_actual: 'telegram', config: { bot_token: `bot-of-${userId}` }, sender: 'Sarah' };
	}),
	recordReply: vi.fn(async (userId, id, text) => ({ id, replied_at: '2026-10-09T00:00:00.000Z', reply_text: text })),
	listContacts: vi.fn(async (userId) => db.contacts.filter((c) => c.user_id === userId).map(strip)),
	upsertContact: vi.fn(async (userId, contact) => {
		state.upserts.push({ userId, contact });
		return { id: 'c-new', ...contact };
	}),
}));

vi.mock('../api/_lib/companion/poll.js', () => ({
	pollUser: vi.fn(async (userId) => {
		state.polled.push(userId);
		return { sources: [{ kind: 'telegram', label: `bot of ${userId}`, ok: true, ingested: 0 }] };
	}),
	laneFor: () => ({
		reply: async (config, replyTo, text) => {
			state.replies.push({ config, replyTo, text });
			return { chat: 'Sarah' };
		},
	}),
}));

vi.mock('../api/_lib/csrf.js', () => ({
	requireCsrf: vi.fn(async (_req, _res, userId) => {
		state.csrfCalls.push(userId);
		return true;
	}),
}));

vi.mock('../api/_lib/rate-limit.js', () => ({
	limits: new Proxy({}, {
		get: (_target, bucket) => async (key) => {
			state.rateKeys.push({ bucket, key });
			return { success: true };
		},
	}),
}));

vi.mock('../api/_lib/db.js', () => ({
	sql: vi.fn(async () => []),
	isDbUnavailableError: () => false,
	isDbCapacityError: () => false,
	isStoragePressured: async () => ({ pressured: false }),
}));

vi.mock('../api/_lib/llm.js', () => ({
	llmConfigured: () => false,
	llmComplete: vi.fn(),
}));

const { default: eventsHandler } = await import('../api/companion/events/index.js');
const { default: eventHandler } = await import('../api/companion/events/[id].js');
const { default: replyHandler } = await import('../api/companion/events/[id]/reply.js');
const { default: contactsHandler } = await import('../api/companion/contacts/index.js');
const { default: pollHandler } = await import('../api/companion/poll.js');
const { default: settingsHandler } = await import('../api/companion/settings.js');
const { default: checkoutHandler } = await import('../api/companion/checkout.js');
const { createCompanionClient, CompanionError } = await import('../packages/companion-sdk/src/client.js');

function makeReq({ method = 'GET', url, token = null, headers = {}, body = null, query = {} }) {
	const req = body ? Readable.from([Buffer.from(JSON.stringify(body))]) : Readable.from([]);
	req.method = method;
	req.url = url;
	req.query = query;
	req.headers = {
		host: 'three.ws',
		...(body ? { 'content-type': 'application/json' } : {}),
		...(token ? { authorization: `Bearer ${token}` } : {}),
		...headers,
	};
	return req;
}

function makeRes() {
	const headers = {};
	return {
		statusCode: 200,
		body: '',
		headersSent: false,
		writableEnded: false,
		setHeader(k, v) {
			headers[k.toLowerCase()] = v;
		},
		getHeader(k) {
			return headers[k.toLowerCase()];
		},
		end(chunk) {
			if (chunk !== undefined) this.body += chunk;
			this.writableEnded = true;
		},
	};
}

async function invoke(handler, opts) {
	const res = makeRes();
	await handler(makeReq(opts), res);
	return { status: res.statusCode, body: res.body ? JSON.parse(res.body) : null };
}

// Routes the SDK's fetch straight into the handlers, so the client is tested
// against the real server code rather than a canned response.
const ROUTES = [
	[/^\/api\/companion\/events$/, eventsHandler],
	[/^\/api\/companion\/events\/([^/]+)\/reply$/, replyHandler],
	[/^\/api\/companion\/events\/([^/]+)$/, eventHandler],
	[/^\/api\/companion\/contacts$/, contactsHandler],
	[/^\/api\/companion\/poll$/, pollHandler],
];

async function inProcessFetch(href, init = {}) {
	const url = new URL(href);
	const match = ROUTES.map(([re, handler]) => [url.pathname.match(re), handler]).find(([m]) => m);
	if (!match) throw new Error(`no route for ${url.pathname}`);
	const [m, handler] = match;
	const res = makeRes();
	const req = makeReq({
		method: init.method || 'GET',
		url: `${url.pathname}${url.search}`,
		headers: init.headers || {},
		body: init.body ? JSON.parse(init.body) : null,
		query: m[1] ? { id: decodeURIComponent(m[1]) } : {},
	});
	await handler(req, res);
	return { ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, text: async () => res.body };
}

beforeEach(() => {
	db = freshDb();
	state.session = null;
	state.csrfCalls = [];
	state.rateKeys = [];
	state.marked = [];
	state.replies = [];
	state.polled = [];
	state.upserts = [];
});

describe('GET /api/companion/events with the bridge token', () => {
	it('lists only the token owner\'s deliveries', async () => {
		const { status, body } = await invoke(eventsHandler, { url: '/api/companion/events?limit=10', token: ALICE_TOKEN });
		expect(status).toBe(200);
		expect(body.events.map((e) => e.id)).toEqual([ALICE_EVENT]);
		expect(body.threshold).toBe(60);
		expect(state.rateKeys).toContainEqual({ bucket: 'companionRead', key: ALICE });
	});

	it('gives another account\'s token that account\'s feed, never alice\'s', async () => {
		const { body } = await invoke(eventsHandler, { url: '/api/companion/events', token: BOB_TOKEN });
		expect(body.events.map((e) => e.id)).toEqual([BOB_EVENT]);
	});

	it('refuses an unknown bridge token with 401, even next to a live session', async () => {
		state.session = { id: ALICE };
		const { status, body } = await invoke(eventsHandler, { url: '/api/companion/events', token: 'cmp_revoked_token_value' });
		expect(status).toBe(401);
		expect(body.error).toBe('unauthorized');
	});
});

describe('PATCH /api/companion/events/:id with the bridge token', () => {
	it('marks the owner\'s delivery spoken without a CSRF token', async () => {
		const { status, body } = await invoke(eventHandler, {
			method: 'PATCH',
			url: `/api/companion/events/${ALICE_EVENT}`,
			query: { id: ALICE_EVENT },
			token: ALICE_TOKEN,
			body: { delivered: true },
		});
		expect(status).toBe(200);
		expect(body.event.id).toBe(ALICE_EVENT);
		expect(state.marked).toEqual([{ userId: ALICE, id: ALICE_EVENT, flags: { delivered: true, dismissed: false } }]);
		expect(state.csrfCalls).toEqual([]);
	});

	it('cannot touch another account\'s delivery', async () => {
		const { status } = await invoke(eventHandler, {
			method: 'PATCH',
			url: `/api/companion/events/${BOB_EVENT}`,
			query: { id: BOB_EVENT },
			token: ALICE_TOKEN,
			body: { dismissed: true },
		});
		expect(status).toBe(404);
		expect(state.marked).toEqual([]);
	});
});

describe('POST /api/companion/events/:id/reply with the bridge token', () => {
	it('answers the owner\'s message through the owner\'s own lane', async () => {
		const { status, body } = await invoke(replyHandler, {
			method: 'POST',
			url: `/api/companion/events/${ALICE_EVENT}/reply`,
			query: { id: ALICE_EVENT },
			token: ALICE_TOKEN,
			body: { text: 'on my way down' },
		});
		expect(status).toBe(200);
		expect(body.sent).toBe(true);
		expect(state.replies).toEqual([{ config: { bot_token: `bot-of-${ALICE}` }, replyTo: { chat_id: 1, message_id: 7 }, text: 'on my way down' }]);
		expect(state.csrfCalls).toEqual([]);
	});

	it('cannot answer another account\'s message', async () => {
		const { status } = await invoke(replyHandler, {
			method: 'POST',
			url: `/api/companion/events/${BOB_EVENT}/reply`,
			query: { id: BOB_EVENT },
			token: ALICE_TOKEN,
			body: { text: 'hijack' },
		});
		expect(status).toBe(404);
		expect(state.replies).toEqual([]);
	});
});

describe('/api/companion/contacts with the bridge token', () => {
	it('reads only the owner\'s contacts', async () => {
		const { status, body } = await invoke(contactsHandler, { url: '/api/companion/contacts', token: ALICE_TOKEN });
		expect(status).toBe(200);
		expect(body.contacts.map((c) => c.display_name)).toEqual(['Sarah']);
	});

	it('cannot edit contacts', async () => {
		const { status, body } = await invoke(contactsHandler, {
			method: 'POST',
			url: '/api/companion/contacts',
			token: ALICE_TOKEN,
			body: { identifier: 'mallory', display_name: 'Mallory' },
		});
		expect(status).toBe(403);
		expect(body.error).toBe('bridge_token_not_accepted');
		expect(state.upserts).toEqual([]);
	});
});

describe('POST /api/companion/poll with the bridge token', () => {
	it('checks only the owner\'s sources, without a CSRF token', async () => {
		const { status, body } = await invoke(pollHandler, { method: 'POST', url: '/api/companion/poll', token: BOB_TOKEN });
		expect(status).toBe(200);
		expect(state.polled).toEqual([BOB]);
		expect(body.sources[0].label).toBe(`bot of ${BOB}`);
		expect(state.csrfCalls).toEqual([]);
	});
});

describe('routes the bridge token does not reach', () => {
	it('settings answers 403 bridge_token_not_accepted, so the token cannot read or rotate itself', async () => {
		const { status, body } = await invoke(settingsHandler, { url: '/api/companion/settings', token: ALICE_TOKEN });
		expect(status).toBe(403);
		expect(body.error).toBe('bridge_token_not_accepted');
	});
});

describe('session and API-key callers keep their rules', () => {
	it('a session still reads its own feed and still passes CSRF on a write', async () => {
		state.session = { id: ALICE };
		const list = await invoke(eventsHandler, { url: '/api/companion/events' });
		expect(list.body.events.map((e) => e.id)).toEqual([ALICE_EVENT]);

		await invoke(eventHandler, {
			method: 'PATCH',
			url: `/api/companion/events/${ALICE_EVENT}`,
			query: { id: ALICE_EVENT },
			body: { delivered: true },
		});
		expect(state.csrfCalls).toEqual([ALICE]);
	});

	it('an API key without the profile scope is refused with 403 insufficient_scope', async () => {
		state.session = { id: ALICE, source: 'bearer', scope: 'inference' };
		const { status, body } = await invoke(eventsHandler, { url: '/api/companion/events', token: 'sk_live_narrow' });
		expect(status).toBe(403);
		expect(body.error).toBe('insufficient_scope');
	});

	it('no credential at all is a 401', async () => {
		const { status } = await invoke(pollHandler, { method: 'POST', url: '/api/companion/poll' });
		expect(status).toBe(401);
	});
});

describe('POST /api/companion/checkout with the bridge token', () => {
	it('keys the rate limit and the model-key lookup on the owner\'s user id', async () => {
		const { status } = await invoke(checkoutHandler, {
			method: 'POST',
			url: '/api/companion/checkout',
			token: ALICE_TOKEN,
			body: { url: 'https://shop.example/checkout', text: 'Total $49.99', amounts: [{ value: 4999, role: 'total' }] },
		});
		expect(status).toBe(200);
		expect(state.rateKeys).toContainEqual({ bucket: 'companionCheckout', key: ALICE });
	});
});

describe('@three-ws/companion given only a bridge token', () => {
	const client = (token) => createCompanionClient({ token, apiBase: 'https://three.ws', fetch: inProcessFetch });

	it('list, markDelivered, reply, contacts and checkNow all succeed for the owner', async () => {
		const companion = client(ALICE_TOKEN);
		const feed = await companion.list({ limit: 1 });
		expect(feed.events.map((e) => e.id)).toEqual([ALICE_EVENT]);
		await expect(companion.markDelivered(ALICE_EVENT)).resolves.toMatchObject({ event: { id: ALICE_EVENT } });
		await expect(companion.reply(ALICE_EVENT, 'on my way')).resolves.toMatchObject({ sent: true });
		await expect(companion.contacts()).resolves.toMatchObject({ contacts: [{ display_name: 'Sarah' }] });
		await expect(companion.checkNow()).resolves.toMatchObject({ sources: [{ ok: true }] });
		expect(state.polled).toEqual([ALICE]);
	});

	it('cannot reach another account\'s delivery through the SDK either', async () => {
		const err = await client(ALICE_TOKEN).reply(BOB_EVENT, 'hijack').catch((e) => e);
		expect(err).toBeInstanceOf(CompanionError);
		expect(err.status).toBe(404);
		expect(state.replies).toEqual([]);
	});

	it('a rotated token fails with a message that says where to get the new one', async () => {
		const err = await client('cmp_rotated_away_token').list().catch((e) => e);
		expect(err.status).toBe(401);
		expect(err.message).toMatch(/three\.ws\/companion/);
	});
});