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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The `three-ws` CLI's server half (packages/three-ws-cli).
//
// POST /api/cli/link start a device link: { client_name, hostname, scope }
// -> { device_code, user_code, verification_uri, ... }
// GET /api/cli/link ?code=XXXX-XXXX, signed in: what the link is asking for
// POST /api/cli/approve signed in + CSRF: { code, decision, scope } allow or deny
// POST /api/cli/token { device_code }: poll; hands over the minted key once
// GET /api/cli/whoami Bearer: the account, credential, plan and agent wallet
//
// The link is the RFC 8628 device authorization grant, issuing a three.ws API
// key instead of an OAuth token. It exists for the two places a loopback OAuth
// redirect cannot reach: a terminal over SSH or in a container, and an API key
// that the stdio `@three-ws/*-mcp` packages read from their env block. Error
// codes on the poll are RFC 8628 §3.5's, so any device-flow client reads them.
//
// Approval is a person in a browser. `approve` refuses every bearer principal,
// API keys and OAuth tokens included: a credential must never be able to widen
// itself into a new credential without a human pressing the button.
import { randomInt } from 'node:crypto';
import { sql } from '../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { randomToken, sha256 } from '../_lib/crypto.js';
import { cors, error, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { env } from '../_lib/env.js';
import { API_KEY_SCOPES, mintApiKey, normalizeKeyScopes } from '../_lib/api-keys.js';
import { getUserWalletStatus } from '../_lib/x402-user-payer.js';
import { logAudit } from '../_lib/audit.js';
const LINK_TTL_SECONDS = 600;
const POLL_INTERVAL_SECONDS = 3;
// RFC 8628 §6.1: consonants only, no vowels (so no words) and no characters
// that read alike (0/O, 1/I/L). 19^8 is ~1.7e10 codes, and a code only lives
// ten minutes behind a signed-in session, so guessing one is not a strategy.
const USER_CODE_ALPHABET = 'BCDFGHJKMNPQRSTVWXZ';
const DEFAULT_SCOPE = 'profile avatars:read avatars:write memory:read memory:write agents:read wallet:read';
const SCOPE_LABELS = {
'avatars:read': 'Read your avatars',
'avatars:write': 'Create and update avatars',
'avatars:delete': 'Delete your avatars',
profile: 'See your name, email and plan',
'memory:read': 'Recall your agents’ memories',
'memory:write': 'Store and forget your agents’ memories',
'agents:read': 'Read your agents and their identities',
'agents:write': 'Create, update and register agents',
'herald:announce': 'Post announcements through the Herald',
'wallet:read': 'See your agent wallet balance and spending caps',
'wallet:write': 'Spend USDC from your agent wallet, within your caps',
'wallet:trade': 'Swap, bid and open or close positions from your agent wallet, within your caps',
'wallet:launch': 'Launch coins from your agent wallet and claim their creator fees',
'services:write': 'Publish paid services that earn USDC to your agent wallet',
inference: 'Call models on your credits through the OpenAI-compatible endpoint',
};
// Scopes that let the key move money. The authorize page marks them so the
// person sees the difference before they approve, not after.
const FINANCIAL_SCOPES = new Set(['wallet:write', 'wallet:trade', 'wallet:launch', 'services:write']);
export function generateUserCode() {
let out = '';
for (let i = 0; i < 8; i++) out += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)];
return `${out.slice(0, 4)}-${out.slice(4)}`;
}
// Accepts what a person actually types: lower case, spaces, a missing dash.
export function normalizeUserCode(input) {
const letters = String(input || '').toUpperCase().replace(/[^A-Z]/g, '');
if (letters.length !== 8) return null;
for (const c of letters) if (!USER_CODE_ALPHABET.includes(c)) return null;
return `${letters.slice(0, 4)}-${letters.slice(4)}`;
}
function cleanLabel(value, max) {
const s = String(value ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim();
return s ? s.slice(0, max) : null;
}
function describeScopes(scope) {
return String(scope || '').split(/\s+/).filter(Boolean).map((s) => ({
scope: s,
label: SCOPE_LABELS[s] || s,
financial: FINANCIAL_SCOPES.has(s),
}));
}
function publicLink(row) {
return {
user_code: row.user_code,
client_name: row.client_name,
hostname: row.hostname,
status: row.status,
requested_scopes: describeScopes(row.requested_scope),
created_at: row.created_at,
expires_at: row.expires_at,
expired: new Date(row.expires_at) < new Date(),
};
}
// ── link: start (POST, unauthenticated) and inspect (GET, signed in) ─────────
async function handleLink(req, res) {
if (req.method === 'GET') return inspectLink(req, res);
const rl = await limits.cliLinkIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl, 'too many sign-in links from this network, wait a few minutes');
const body = (await readJson(req, 4_000).catch(() => null)) || {};
const { scopes, invalid } = normalizeKeyScopes(body.scope || DEFAULT_SCOPE);
if (invalid.length) return error(res, 400, 'invalid_scope', `unknown scopes: ${invalid.join(', ')}`);
if (!scopes.length) return error(res, 400, 'invalid_scope', 'scope must name at least one permission');
const deviceCode = randomToken(32);
const deviceHash = await sha256(deviceCode);
const clientName = cleanLabel(body.client_name, 80) || 'three-ws CLI';
const hostname = cleanLabel(body.hostname, 120);
// A user-code collision is astronomically unlikely but the column is unique,
// so retry on the constraint instead of surfacing a 500 for it.
let userCode = null;
for (let attempt = 0; attempt < 5 && !userCode; attempt++) {
const candidate = generateUserCode();
const rows = await sql`
insert into cli_link_requests (device_code_hash, user_code, client_name, hostname, requested_scope, created_ip, expires_at)
values (${deviceHash}, ${candidate}, ${clientName}, ${hostname}, ${scopes.join(' ')}, ${clientIp(req)}, now() + ${`${LINK_TTL_SECONDS} seconds`}::interval)
on conflict (user_code) do nothing
returning user_code
`;
if (rows[0]) userCode = rows[0].user_code;
}
if (!userCode) return error(res, 503, 'unavailable', 'could not allocate a sign-in code, try again');
const verificationUri = `${env.APP_ORIGIN}/cli/authorize`;
return json(res, 201, {
device_code: deviceCode,
user_code: userCode,
verification_uri: verificationUri,
verification_uri_complete: `${verificationUri}?code=${encodeURIComponent(userCode)}`,
expires_in: LINK_TTL_SECONDS,
interval: POLL_INTERVAL_SECONDS,
scope: scopes.join(' '),
}, { 'cache-control': 'no-store' });
}
async function inspectLink(req, res) {
const user = await getSessionUser(req);
if (!user) return error(res, 401, 'unauthorized', 'sign in to approve a CLI sign-in');
const rl = await limits.authedReadIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const code = normalizeUserCode(new URL(req.url, 'http://x').searchParams.get('code'));
if (!code) return error(res, 400, 'invalid_code', 'that is not a three-ws sign-in code; codes look like BCDF-GHJK');
const [row] = await sql`select * from cli_link_requests where user_code = ${code} limit 1`;
if (!row) return error(res, 404, 'unknown_code', 'no sign-in is waiting for that code');
if (row.user_id && row.user_id !== user.id) return error(res, 404, 'unknown_code', 'no sign-in is waiting for that code');
return json(res, 200, {
link: publicLink(row),
account: { email: user.email, display_name: user.display_name || null },
available_scopes: describeScopes(API_KEY_SCOPES.join(' ')),
}, { 'cache-control': 'no-store' });
}
// ── approve (POST, browser session only) ─────────────────────────────────────
async function handleApprove(req, res) {
if (!method(req, res, ['POST'])) return;
if (extractBearer(req)) return error(res, 403, 'forbidden', 'a CLI sign-in is approved by a person in a browser, not by a token');
const user = await getSessionUser(req);
if (!user) return error(res, 401, 'unauthorized', 'sign in to approve a CLI sign-in');
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
if (!(await requireCsrf(req, res, user.id))) return;
const body = (await readJson(req, 4_000).catch(() => null)) || {};
const code = normalizeUserCode(body.code);
if (!code) return error(res, 400, 'invalid_code', 'that is not a three-ws sign-in code');
const decision = body.decision === 'allow' ? 'allow' : body.decision === 'deny' ? 'deny' : null;
if (!decision) return error(res, 400, 'invalid_request', 'decision must be allow or deny');
const [row] = await sql`select * from cli_link_requests where user_code = ${code} limit 1`;
if (!row) return error(res, 404, 'unknown_code', 'no sign-in is waiting for that code');
if (row.status !== 'pending') return error(res, 409, 'already_decided', `this sign-in was already ${row.status === 'denied' ? 'denied' : 'approved'}`);
if (new Date(row.expires_at) < new Date()) return error(res, 410, 'expired_token', 'this sign-in code expired; run the command again for a new one');
if (decision === 'deny') {
await sql`update cli_link_requests set status = 'denied', user_id = ${user.id}, decided_at = now() where id = ${row.id} and status = 'pending'`;
logAudit({ userId: user.id, action: 'cli_link_deny', resourceId: row.id, meta: { client: row.client_name, hostname: row.hostname }, req });
return json(res, 200, { status: 'denied' });
}
// The approver may narrow the request, never widen it.
const requested = new Set(row.requested_scope.split(/\s+/).filter(Boolean));
const { scopes: chosen } = normalizeKeyScopes(body.scope ?? row.requested_scope);
const granted = chosen.filter((s) => requested.has(s));
if (!granted.length) return error(res, 400, 'invalid_scope', 'keep at least one permission, or deny the sign-in instead');
const updated = await sql`
update cli_link_requests
set status = 'approved', user_id = ${user.id}, granted_scope = ${granted.join(' ')}, decided_at = now()
where id = ${row.id} and status = 'pending' and expires_at > now()
returning id
`;
if (!updated[0]) return error(res, 409, 'already_decided', 'this sign-in changed while you were looking at it; run the command again');
logAudit({ userId: user.id, action: 'cli_link_approve', resourceId: row.id, meta: { client: row.client_name, hostname: row.hostname, scope: granted.join(' ') }, req });
return json(res, 200, { status: 'approved', scope: granted.join(' ') });
}
// ── token (POST, the CLI polling with its device code) ───────────────────────
async function handleToken(req, res) {
if (!method(req, res, ['POST'])) return;
const body = (await readJson(req, 4_000).catch(() => null)) || {};
const deviceCode = typeof body.device_code === 'string' ? body.device_code : '';
if (!deviceCode) return error(res, 400, 'invalid_request', 'device_code required');
const deviceHash = await sha256(deviceCode);
const rl = await limits.cliPoll(deviceHash);
if (!rl.success) return error(res, 400, 'slow_down', `poll at most every ${POLL_INTERVAL_SECONDS} seconds`);
const [row] = await sql`select * from cli_link_requests where device_code_hash = ${deviceHash} limit 1`;
if (!row) return error(res, 400, 'invalid_grant', 'unknown device code');
if (row.status === 'consumed') return error(res, 400, 'invalid_grant', 'this sign-in already delivered its key');
if (row.status === 'denied') return error(res, 400, 'access_denied', 'the sign-in was denied in the browser');
if (new Date(row.expires_at) < new Date()) return error(res, 400, 'expired_token', 'the sign-in code expired before it was approved');
if (row.status === 'pending') {
const tooSoon = row.last_polled_at && Date.now() - new Date(row.last_polled_at).getTime() < (POLL_INTERVAL_SECONDS - 1) * 1000;
await sql`update cli_link_requests set last_polled_at = now() where id = ${row.id}`;
if (tooSoon) return error(res, 400, 'slow_down', `poll at most every ${POLL_INTERVAL_SECONDS} seconds`);
return error(res, 400, 'authorization_pending', 'waiting for approval in the browser');
}
// Approved: claim the row first so two concurrent polls can never mint twice.
const claimed = await sql`
update cli_link_requests set status = 'consumed', consumed_at = now()
where id = ${row.id} and status = 'approved'
returning id, user_id, granted_scope, hostname, client_name
`;
if (!claimed[0]) return error(res, 400, 'invalid_grant', 'this sign-in already delivered its key');
const link = claimed[0];
const name = `${link.client_name}${link.hostname ? ` on ${link.hostname}` : ''}`.slice(0, 80);
const { row: key, secret } = await mintApiKey({
userId: link.user_id,
name,
scopes: link.granted_scope.split(/\s+/).filter(Boolean),
req,
via: 'cli_link',
});
await sql`update cli_link_requests set api_key_id = ${key.id} where id = ${link.id}`;
const [account] = await sql`select email from users where id = ${link.user_id} limit 1`;
return json(res, 200, {
access_token: secret,
token_type: 'Bearer',
scope: key.scope,
key: { id: key.id, name: key.name, prefix: key.prefix, created_at: key.created_at },
account: { email: account?.email || null },
}, { 'cache-control': 'no-store' });
}
// ── whoami (GET, bearer) ─────────────────────────────────────────────────────
async function handleWhoami(req, res) {
if (!method(req, res, ['GET'])) return;
const token = extractBearer(req);
if (!token) return error(res, 401, 'unauthorized', 'send an API key or access token as a Bearer credential; run `npx three-ws login`');
const auth = await authenticateBearer(token, { audience: env.MCP_RESOURCE });
if (!auth) return error(res, 401, 'invalid_token', 'this credential is revoked, expired or unknown; run `npx three-ws login`');
const rl = await limits.authedReadIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const scope = auth.scope || '';
const canProfile = hasScope(scope, 'profile');
const canWallet = hasScope(scope, 'wallet:read') || hasScope(scope, 'wallet:write');
const [[user], keyRows, walletStatus] = await Promise.all([
sql`
select u.id, u.email, u.display_name, u.username, u.plan, q.mcp_calls_per_day,
(select count(*) from usage_events e where e.user_id = u.id and e.kind = 'tool_call' and e.created_at > now() - interval '24 hours') as mcp_calls_24h
from users u left join plan_quotas q on q.plan = u.plan
where u.id = ${auth.userId} and u.deleted_at is null limit 1
`,
auth.apiKeyId
? sql`select name, prefix, expires_at, last_used_at, created_at from api_keys where id = ${auth.apiKeyId} limit 1`
: Promise.resolve([]),
canWallet ? getUserWalletStatus(auth.userId) : Promise.resolve(null),
]);
if (!user) return error(res, 401, 'invalid_token', 'the account behind this credential no longer exists');
return json(res, 200, {
user: canProfile
? { id: user.id, email: user.email, display_name: user.display_name || null, username: user.username || null }
: { id: user.id },
plan: canProfile
? { plan: user.plan, mcp_calls_per_day: user.mcp_calls_per_day == null ? null : Number(user.mcp_calls_per_day), mcp_calls_24h: Number(user.mcp_calls_24h || 0) }
: null,
credential: {
source: auth.source,
scope,
client_id: auth.clientId || null,
api_key: keyRows[0] || null,
},
wallet: canWallet ? walletStatus : null,
missing: [!canProfile && 'profile', !canWallet && 'wallet:read'].filter(Boolean),
}, { 'cache-control': 'no-store' });
}
const DISPATCH = {
link: handleLink,
approve: handleApprove,
token: handleToken,
whoami: handleWhoami,
};
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
const action = req.query?.action ?? new URL(req.url, 'http://x').pathname.split('/').pop();
const fn = DISPATCH[action];
if (!fn) return error(res, 404, 'not_found', `unknown cli action: ${action}`);
if (action === 'link' && !method(req, res, ['GET', 'POST'])) return;
return fn(req, res);
});