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.

5.2 KB
Raw Blame
// OAuth scope sets, in one place, because two surfaces have to agree on them.
//
// A dynamically-registered MCP client learns what it may ask for by following
// the chain the 401 hands it: `WWW-Authenticate: Bearer resource_metadata=...`
// points at /.well-known/oauth-protected-resource (RFC 9728), and the client
// registers for the scopes that document lists. So the scope list published
// there and the scope list the registration endpoint actually keeps
// (`filterRegisterableScope`) are the same contract seen from two sides: any
// scope missing from the metadata is a scope no discovery-driven client will
// ever request, and any scope listed there but dropped at registration is a
// promise the server breaks.
//
// They drifted once already. The wallet/services scopes were added to
// registration to make the agent-wallet MCP server (api/mcp-agent) reachable,
// and the published metadata kept advertising the original eight, so a client
// that discovered its scopes the documented way still could not reach
// wallet_status, pay_and_call, provision_wallet or monetize_endpoint. Both
// sides now read this array, and tests/api/oauth-scope-discovery.test.js
// pins them together.

import { SPEND_SCOPE } from './spend-scope.js';

// Scopes a dynamically-registered client may request. Anything outside this set
// (notably privileged scopes like `permissions:redeem`, which authorizes
// gas-spending on-chain redemption) is silently dropped at registration so a
// self-registering client can never mint a token carrying it.
export const REGISTERABLE_SCOPES = Object.freeze([
	'avatars:read',
	'avatars:write',
	'avatars:delete',
	'profile',
	'offline_access',
	// Agent memory MCP tools (remember / recall / forget).
	'memory:read',
	'memory:write',
	// On-chain agent identity MCP tools (register_agent / identity_check).
	'agents:read',
	'agents:write',
	// Visitor feedback MCP tools (list_feedback / get_feedback_repro). Read-only
	// by design: the tools behind it compile a reported session into a failing
	// test and can change nothing (api/_mcp/tools/feedback.js). The handlers also
	// require an admin account, so granting this scope to a non-admin authorizes
	// nothing extra.
	'feedback:read',
	// Home Assistant MCP tools (home_status / home_list_macros / home_grants read;
	// home_activate / home_call act). `home:act` authorises ASKING to act, and
	// nothing more: an action that unlocks, opens, or disarms returns a pending
	// confirmation which only a browser session can satisfy
	// (api/home/[id]/confirm.js refuses every bearer principal, this scope
	// included). There is deliberately no `home:confirm` scope, because a
	// confirmation is a human saying yes and there is no token that can be one.
	'home:read',
	'home:act',
	// The wallet/services scopes gate the agent-wallet MCP server
	// (api/mcp-agent). They are registerable because the user approves each one
	// by name on the consent screen, `wallet:write` only by ticking a separate
	// box (splitSpendScope below), and every spend they authorize is still
	// bounded by the server-side caps and THREEWS_AGENT_PAY_ENABLED.
	'wallet:read',
	'wallet:write',
	'services:write',
	// Narrower grades of wallet:write (key-scopes.js): a client approved for
	// the "trade" consent group may swap, bid and open or close positions
	// without being able to send funds out; "launch" may launch a coin and
	// claim its fees. wallet:write implies both at check time.
	'wallet:trade',
	'wallet:launch',
]);

// Scopes that exist on the authorization server but are NOT self-registerable:
// they gate paid x402 endpoints for first-party and API-key principals via the
// auth-hints extension (installAccessControl({ requiredScope })), never the MCP
// resource. They belong in RFC 8414 authorization-server metadata and must stay
// out of the RFC 9728 protected-resource document for /api/mcp.
export const AUTH_HINT_SCOPES = Object.freeze(['read:agent-reputation', 'x402:bypass']);

// Everything the authorization server can issue, for RFC 8414 scopes_supported.
export const SUPPORTED_SCOPES = Object.freeze([...REGISTERABLE_SCOPES, ...AUTH_HINT_SCOPES]);

const REGISTERABLE = new Set(REGISTERABLE_SCOPES);

export function filterRegisterableScope(requested) {
	const kept = String(requested || '')
		.split(/\s+/)
		.filter((s) => REGISTERABLE.has(s));
	return kept.length ? kept.join(' ') : 'avatars:read';
}

// Design rule for connectors: an app a person signs in to three.ws can never
// spend from their wallet unless they tick a box saying so on the consent
// screen (api/oauth/[action].js). A
// cloud agent such as Grok Bot registers for every scope the protected-resource
// metadata lists, `wallet:write` included, and then holds the token unattended,
// so spending is opt-in rather than something a person approves by clicking
// Authorize. Left unticked, `wallet:write` is dropped and `wallet:read` kept,
// so the app still sees balances and caps.
export function splitSpendScope(scope) {
	const scopes = String(scope || '').split(/\s+/).filter(Boolean);
	const spend = scopes.includes(SPEND_SCOPE);
	const base = scopes.filter((s) => s !== SPEND_SCOPE);
	if (spend && !base.includes('wallet:read')) base.push('wallet:read');
	return { base: base.join(' '), spend };
}