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.

9.0 KB
Raw Blame
// The MCP tool policy, bound to the hosted servers.
//
// The policy itself (groups, tiers, confirm flags, preview tools, and the
// enablement grammar) lives in @three-ws/mcp-policy so the hosted servers and
// every stdio package enforce the same table. This module adds what only the
// hosted side has:
//
//   - a preview store in Redis (api/_lib/cache.js), so a quote issued by one
//     Cloud Run instance is honored by whichever instance runs the execution;
//   - saved settings in mcp_tool_settings (account-wide, plus per-API-key
//     overrides), written by /settings/mcp-tools through /api/mcp-tools;
//   - per-request enablement: X-Three-Allowed-Tools, then X-Three-Tools, then
//     the `tools` query parameter, then the key setting, the account setting,
//     and finally the default (read and write on, financial off).
//
// Every dispatcher calls the same three functions: listForRequest on
// tools/list, gateCall before a handler runs, finishCall after it returns.

import { createPolicy, resolveEnablement, describeEnablement, normalizeEntry, POLICY } from '@three-ws/mcp-policy';

import { cacheDel, cacheGetFresh, cacheSet } from '../_lib/cache.js';
import { sql } from '../_lib/db.js';
import { logger } from '../_lib/usage.js';
import { connectorSpendMessage } from '../_lib/key-scopes.js';

const log = logger('mcp-policy');
const PREVIEW_KEY = (id) => `mcp:preview:${id}`;

/** Redis-backed preview store shared by every instance. */
export const hostedPreviewStore = {
	async put(id, record, ttlMs) {
		await cacheSet(PREVIEW_KEY(id), record, Math.ceil(ttlMs / 1000));
	},
	async get(id) {
		if (typeof id !== 'string' || !/^[pq]_[\w-]{16,64}$/.test(id)) return null;
		return (await cacheGetFresh(PREVIEW_KEY(id))) ?? null;
	},
	async del(id) {
		await cacheDel(PREVIEW_KEY(id));
	},
};

const policies = new Map();

/** The policy runtime for one hosted server id (see SERVERS in the package). */
export function policyFor(serverId) {
	if (!policies.has(serverId)) policies.set(serverId, createPolicy({ serverId, store: hostedPreviewStore }));
	return policies.get(serverId);
}

/**
 * Who a preview belongs to. A quote issued to one account can never authorize
 * another account's execution.
 */
export function principalOf(auth) {
	if (auth?.userId) return `user:${auth.userId}`;
	if (auth?.payer) return `x402:${auth.payer}`;
	if (auth?.rateKey) return `rate:${auth.rateKey}`;
	return 'anonymous';
}

// ── Saved settings ────────────────────────────────────────────────────────────

// Settings are read on every tools/list and tools/call, so each instance keeps
// them briefly. A write on this instance clears its copy immediately; other
// instances pick the change up within SETTINGS_TTL_MS.
const SETTINGS_TTL_MS = 15_000;
const settingsMemo = new Map();

function memoKey(userId, apiKeyId) {
	return `${userId}:${apiKeyId || ''}`;
}

/** Forget cached settings for a user (after a write). */
export function invalidateToolSettings(userId) {
	for (const key of settingsMemo.keys()) if (key.startsWith(`${userId}:`)) settingsMemo.delete(key);
}

/**
 * The saved account settings and, when the call is authenticated by an API
 * key, that key's overrides.
 * @returns {Promise<{ account: object|null, key: object|null }>}
 */
export async function loadToolSettings(userId, apiKeyId = null) {
	if (!userId) return { account: null, key: null };
	const k = memoKey(userId, apiKeyId);
	const hit = settingsMemo.get(k);
	if (hit && hit.expires > Date.now()) return hit.value;
	const rows = await sql`
		SELECT api_key_id, settings FROM mcp_tool_settings
		WHERE user_id = ${userId} AND (api_key_id IS NULL OR api_key_id = ${apiKeyId})
	`;
	const value = {
		account: rows.find((r) => !r.api_key_id)?.settings ?? null,
		key: apiKeyId ? (rows.find((r) => r.api_key_id === apiKeyId)?.settings ?? null) : null,
	};
	settingsMemo.set(k, { value, expires: Date.now() + SETTINGS_TTL_MS });
	return value;
}

function headerValue(req, name) {
	const v = req?.headers?.[name];
	return Array.isArray(v) ? v.join(',') : v;
}

function queryValue(req, name) {
	try {
		return new URL(req?.url || '/', 'http://local').searchParams.get(name);
	} catch {
		return null;
	}
}

/**
 * Resolve the enablement for one request. The result is cached on the request
 * so a batch of calls resolves settings once.
 */
export async function enablementFor(req, auth) {
	if (req && req.__threeToolPolicy) return req.__threeToolPolicy;
	const allowedTools = headerValue(req, 'x-three-allowed-tools');
	const headerSpec = headerValue(req, 'x-three-tools');
	const querySpec = queryValue(req, 'tools');
	let saved = { account: null, key: null };
	if (!allowedTools && !headerSpec && !querySpec && auth?.userId) {
		try {
			saved = await loadToolSettings(auth.userId, auth.apiKeyId || null);
		} catch (err) {
			// Fail safe: without the saved settings the session gets the default,
			// which never includes a financial tool.
			log.warn('settings_unavailable', { message: err?.message });
		}
	}
	const en = resolveEnablement({ allowedTools, headerSpec, querySpec, keySettings: saved.key, accountSettings: saved.account });
	if (req && typeof req === 'object') Object.defineProperty(req, '__threeToolPolicy', { value: en, enumerable: false });
	return en;
}

// Financial-tier tools a connector key may still call: they delete the
// caller's own data or run an action on the caller's own gear, and move no
// funds. Every other financial tool spends, pays, launches or withdraws.
const NON_SPENDING_CONFIRMS = new Set(['confirm_delete', 'confirm_run']);

// A handful of tools are money-adjacent without being POLICY's "financial"
// tier: they read or mint a virtual card's live data (quote, raw data, a
// connect link that can provision one), or stand up a wallet/paid endpoint.
// None carries a confirmFlag for the tier check above to catch, so they are
// named here instead. A key issued for an unattended agent may never call them.
const EXTRA_VALUE_TOOLS = Object.freeze({
	'three.ws': new Set(['agent_card_quote', 'agent_card_data', 'agent_card_connect_link']),
	'threews-agent': new Set(['provision_wallet', 'monetize_endpoint']),
});

/** True when a tool moves value, so a key issued for an unattended agent may never call it. */
export function movesValue(serverId, name) {
	if (EXTRA_VALUE_TOOLS[serverId]?.has(name)) return true;
	const row = POLICY[serverId]?.[name];
	if (!row) return false;
	const entry = normalizeEntry(name, row);
	return entry.tier === 'financial' && !NON_SPENDING_CONFIRMS.has(entry.confirmFlag);
}

/** The JSON-RPC error a connector key gets for a value-moving tool. */
export function connectorSpendError(name) {
	return Object.assign(new Error(connectorSpendMessage(name)), {
		code: -32003,
		data: { reason: 'spend_requires_browser_session', tool: name, url: 'https://three.ws/dashboard' },
	});
}

/** tools/list for this request: disabled tools removed, financial ones annotated. */
export async function listForRequest(serverId, catalog, auth, req) {
	const tools = await policyFor(serverId).listTools(catalog, await enablementFor(req, auth));
	// A connector key cannot call a value-moving tool, so it never sees one.
	return auth?.connector ? tools.filter((t) => !movesValue(serverId, t.name)) : tools;
}

/**
 * Gate one tools/call. A connector key calling a value-moving tool throws a
 * JSON-RPC error (-32003). Otherwise returns { ok: false, result } with a designed refusal,
 * or { ok: true, args, preview } with the arguments to pass the handler.
 * @param {string[]} ownArgs  argument names the tool's own schema declares
 */
export async function gateCall(serverId, name, args, auth, req, ownArgs = []) {
	// Before the enablement check, so a connector key is told it needs a browser
	// session instead of being told to switch the tool on.
	if (auth?.connector && movesValue(serverId, name)) throw connectorSpendError(name);
	const en = await enablementFor(req, auth);
	return policyFor(serverId).beforeCall({ name, args, en, principal: principalOf(auth), ownArgs });
}

/** Stamp a preview id onto a preview result, or burn the one a financial call spent. */
export async function finishCall(serverId, name, args, auth, result, preview) {
	return policyFor(serverId).afterCall({ name, args, principal: principalOf(auth), result, preview });
}

/** Argument names declared by a JSON Schema tool. */
export function declaredArgs(tool) {
	return Object.keys(tool?.inputSchema?.properties || {});
}

/**
 * Read a preview record for a handler that needs the previewed arguments (the
 * swap and payment executors). Returns null for an unknown, expired, foreign
 * or mismatched id; the gate has already refused those, so a null here only
 * means the record vanished between gate and handler.
 */
export async function readPreview(id, auth, { tool } = {}) {
	const record = await hostedPreviewStore.get(id);
	if (!record || record.principal !== principalOf(auth)) return null;
	if (tool && record.tool !== tool) return null;
	return record;
}

export { describeEnablement };