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.

3.3 KB
Raw Blame
// Who is calling a companion route, and with which credential.
//
// Two kinds of credential reach /api/companion/*:
//
//   - The bridge token (`cmp_...`), which a device holds: the desktop app, the
//     CLI, the MCP server, a browser extension, a Raspberry Pi in the hallway.
//     It is the whole of what @three-ws/companion is given, so every call that
//     package makes (list the feed, mark a delivery spoken, answer one, read the
//     contacts, check sources now) has to accept it. It resolves to exactly one
//     account, and every store query downstream is scoped to that account's
//     user id, so it reaches its owner's companion and nothing else.
//   - A session cookie, an API key, or an OAuth access token, for everything.
//     A cookie session carries every scope; a bearer needs `profile`, because
//     private messages and the bridge token itself live behind these routes.
//
// Routes that change what the companion is (sources, settings, contact edits,
// rotating the token) do not take the bridge token: a leaked phone shortcut must
// not be able to swap a Telegram bot, read a stored credential, or rotate itself
// out from under its owner. Those answer a plain 403 that says so, instead of a
// 401 that reads like the token is wrong.

import { extractBearer, getRequestUser, requestUserHasScope } from '../auth.js';
import { error } from '../http.js';
import { userForIngestToken } from './store.js';

const BRIDGE_TOKEN_PREFIX = 'cmp_';

export function isBridgeToken(token) {
	return typeof token === 'string' && token.startsWith(BRIDGE_TOKEN_PREFIX);
}

/**
 * Resolve the caller, or answer the request with 401/403 and return null.
 *
 * @param {import('node:http').IncomingMessage} req
 * @param {import('node:http').ServerResponse} res
 * @param {{ bridge?: boolean }} [options] bridge: whether this route accepts the bridge token.
 * @returns {Promise<{ id: string, via: 'bridge_token' | 'session' | 'bearer' } | null>}
 */
export async function companionCaller(req, res, { bridge = false } = {}) {
	const bearer = extractBearer(req);
	if (isBridgeToken(bearer)) {
		if (!bridge) {
			error(
				res,
				403,
				'bridge_token_not_accepted',
				'the companion bridge token cannot change sources, settings, or contacts; sign in at three.ws/companion or use an API key with the profile scope',
			);
			return null;
		}
		const settings = await userForIngestToken(bearer);
		if (!settings) {
			error(res, 401, 'unauthorized', 'unknown bridge token, check three.ws/companion for the current one');
			return null;
		}
		return { id: settings.user_id, via: 'bridge_token' };
	}

	const user = await getRequestUser(req, res);
	if (!user) {
		error(res, 401, 'unauthorized', bridge ? 'sign in, or send your companion bridge token as a Bearer header' : 'sign in required');
		return null;
	}
	if (!requestUserHasScope(user, 'profile')) {
		error(res, 403, 'insufficient_scope', 'this token needs the profile scope');
		return null;
	}
	return { id: user.id, via: user.source === 'bearer' ? 'bearer' : 'session' };
}

/**
 * A bridge token travels in an Authorization header a browser never attaches on
 * its own, so a request authenticated by one carries no cross-site risk and
 * needs no CSRF token. Everything else goes through the normal check.
 */
export function needsCsrf(caller) {
	return caller.via !== 'bridge_token';
}