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
// External wallets proved by a signed message.
//
// An owner or an agent attaches a wallet the platform does not hold the key
// for, in one of two roles:
//
// owner a sign-in wallet on the account (user_wallets). Proves the person
// at the keyboard controls the key, the same way /api/auth/wallets
// does, and refuses an address that already signs in elsewhere.
// payout where an agent's earnings are sent (agent_payout_wallets). The
// first payout wallet for a (user, agent, chain) is live at once.
// Replacing one is how an attacker with a stolen session or key
// would drain an account, so it is slower on purpose:
// - an owner in a signed-in session confirms with a password or
// a fresh re-authentication (step-up) and the new address only
// takes effect after PAYOUT_COOLDOWN_HOURS;
// - an agent (an API key, an MCP tool) files an approval request
// the owner decides from the inbox, and the cooldown starts at
// the approval.
// Withdrawals only ever read approved rows whose cooldown has run.
//
// Proof is a Sign-In with Solana or Sign-In with Ethereum message that names
// the role, bound to this origin, carrying a single-use nonce issued to the
// caller. Nothing here signs anything or moves funds.
import { createHash } from 'node:crypto';
import { verifyMessage, getAddress } from 'ethers';
import { sql } from '../db.js';
import { env } from '../env.js';
import { logAudit } from '../audit.js';
import { parseSiweMessage } from '../siwe.js';
import { parseSiwsMessage, verifySiwsSignature } from '../siws.js';
import { issueNonce, consumeNonce, NONCE_TTL_SEC } from '../../auth/wallets/_link-nonces.js';
import { isValidSolanaAddress, isValidEvmAddress } from '../validate.js';
import { createApprovalRequest, ApprovalError } from '../approvals.js';
import { readReauth } from '../identities.js';
import { verifyPassword } from '../auth.js';
export const CHAINS = Object.freeze(['solana', 'evm']);
export const ROLES = Object.freeze(['owner', 'payout']);
export const PAYOUT_COOLDOWN_HOURS = 24;
export const APPROVAL_SOURCE = 'external_wallet';
export const APPROVAL_VENUE = 'payout_wallet';
export const APPROVAL_ACTION = 'payout_wallet_set';
const LOCAL_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/;
const SOLANA_CHAIN_IDS = new Set(['mainnet', 'devnet', 'testnet']);
export class ExternalWalletError extends Error {
constructor(code, message, status = 400, extra = null) {
super(message);
this.code = code;
this.status = status;
this.extra = extra;
}
}
export function roleStatement(role, { agentName = null } = {}) {
if (role === 'owner') return 'Link this wallet to my three.ws account as a sign-in wallet.';
return agentName
? `Set this wallet as the payout wallet for my three.ws agent "${agentName}".`
: 'Set this wallet as the payout wallet for my three.ws account.';
}
function normalizeAddress(chain, address) {
if (chain === 'solana') {
if (!isValidSolanaAddress(address)) throw new ExternalWalletError('invalid_address', 'not a valid Solana address');
return address;
}
if (!isValidEvmAddress(address)) throw new ExternalWalletError('invalid_address', 'not a valid EVM address');
return getAddress(address);
}
// ── challenge ─────────────────────────────────────────────────────────────────
/**
* Build the message the wallet signs. The nonce is bound to the caller's
* user id (consumeNonce refuses it for anyone else) and burns on first use.
*/
export async function issueWalletChallenge({ userId, chain, address, role, agentId = null, agentName = null }) {
if (!CHAINS.includes(chain)) throw new ExternalWalletError('invalid_chain', `chain must be one of ${CHAINS.join(', ')}`);
if (!ROLES.includes(role)) throw new ExternalWalletError('invalid_role', `role must be one of ${ROLES.join(', ')}`);
const addr = normalizeAddress(chain, address);
const nonce = await issueNonce(userId);
const origin = env.APP_ORIGIN;
const host = new URL(origin).host;
const issuedAt = new Date();
const expiresAt = new Date(issuedAt.getTime() + NONCE_TTL_SEC * 1000);
const lines = [
`${host} wants you to sign in with your ${chain === 'solana' ? 'Solana' : 'Ethereum'} account:`,
addr,
'',
roleStatement(role, { agentName }),
'',
`URI: ${origin}/dashboard/account`,
'Version: 1',
`Chain ID: ${chain === 'solana' ? 'mainnet' : '1'}`,
`Nonce: ${nonce}`,
`Issued At: ${issuedAt.toISOString()}`,
`Expiration Time: ${expiresAt.toISOString()}`,
`Request ID: ${role}${agentId ? `:${agentId}` : ''}`,
];
return { chain, address: addr, role, agent_id: agentId, message: lines.join('\n'), nonce, expires_at: expiresAt.toISOString() };
}
// ── proof ─────────────────────────────────────────────────────────────────────
function checkBinding(fields) {
const appOrigin = env.APP_ORIGIN;
const appHost = new URL(appOrigin).host;
const isLocalDev = !env.isProduction && LOCAL_ORIGIN.test(appOrigin);
const domainOk = fields.domain === appHost || (isLocalDev && /^localhost(:\d+)?$/.test(fields.domain));
if (!domainOk) throw new ExternalWalletError('invalid_domain', `domain must be ${appHost}`);
let u;
try { u = new URL(fields.uri); } catch { throw new ExternalWalletError('invalid_uri', 'uri not a valid URL'); }
const originOk = u.origin === appOrigin || (isLocalDev && LOCAL_ORIGIN.test(u.origin));
if (!originOk) throw new ExternalWalletError('invalid_uri', 'uri origin mismatch');
const now = Date.now();
if (fields.expirationTime && Date.parse(fields.expirationTime) < now) throw new ExternalWalletError('expired', 'message expired');
if (fields.notBefore && Date.parse(fields.notBefore) > now) throw new ExternalWalletError('not_yet_valid', 'message not yet valid');
}
/**
* Verify a signed challenge for `userId`. Returns the proved address and the
* role the message named. The nonce is consumed here, so a replayed message
* fails on its nonce before any signature math runs.
*/
export async function verifyWalletProof({ userId, chain, message, signature }) {
if (!CHAINS.includes(chain)) throw new ExternalWalletError('invalid_chain', `chain must be one of ${CHAINS.join(', ')}`);
if (typeof message !== 'string' || typeof signature !== 'string' || !message || !signature) {
throw new ExternalWalletError('invalid_message', 'message and signature are required');
}
const fields = chain === 'solana' ? parseSiwsMessage(message) : parseSiweMessage(message);
if (!fields) throw new ExternalWalletError('invalid_message', `malformed ${chain === 'solana' ? 'SIWS' : 'SIWE'} message`);
checkBinding(fields);
if (chain === 'solana' && fields.chainId && !SOLANA_CHAIN_IDS.has(fields.chainId)) throw new ExternalWalletError('invalid_chain', 'unknown Solana chain ID');
const role = String(fields.requestId || '').split(':')[0];
if (!ROLES.includes(role)) throw new ExternalWalletError('invalid_message', 'the message does not name a wallet role');
if (!(await consumeNonce(fields.nonce, userId))) throw new ExternalWalletError('invalid_nonce', 'unknown, expired, or already used nonce');
let valid = false;
let address;
try {
if (chain === 'solana') {
valid = verifySiwsSignature(message, signature, fields.address);
address = fields.address;
} else {
address = getAddress(fields.address);
valid = getAddress(verifyMessage(message, signature)) === address;
}
} catch {
throw new ExternalWalletError('invalid_signature', 'signature verification failed', 401);
}
if (!valid) throw new ExternalWalletError('invalid_signature', 'signer does not match address', 401);
const agentId = fields.requestId?.includes(':') ? fields.requestId.split(':')[1] : null;
return { address, role, agentId, signatureHash: createHash('sha256').update(signature).digest('hex') };
}
// ── owner wallets ─────────────────────────────────────────────────────────────
export async function attachOwnerWallet({ userId, chain, address, req = null }) {
const chainType = chain === 'solana' ? 'solana' : 'evm';
const [mine] = await sql`select id from user_wallets where user_id = ${userId} and address = ${address} limit 1`;
if (mine) return { address, chain_type: chainType, already_linked: true };
const [other] = await sql`select user_id from user_wallets where address = ${address} limit 1`;
if (other) throw new ExternalWalletError('address_in_use', 'this address already signs in to another account', 409);
await sql`insert into user_wallets (user_id, address, chain_type, is_primary) values (${userId}, ${address}, ${chainType}, false)`;
logAudit({ userId, action: 'link_owner_wallet', resourceId: address, meta: { chain: chainType, via: 'external_wallet' }, req });
return { address, chain_type: chainType, already_linked: false };
}
// ── payout wallets ────────────────────────────────────────────────────────────
function payoutChain(chain) {
// agent_payout_wallets stores the settlement chain; EVM payouts land on Base.
return chain === 'solana' ? 'solana' : 'base';
}
// 'base' and 'evm' are one rail with two historical chain labels (see
// api/monetization/wallet.js), so a replacement check and a default clear
// must cover the whole rail or the older row wins the withdrawal tie.
export function railChains(chain) {
return chain === 'solana' ? ['solana'] : ['base', 'evm'];
}
export function publicPayoutWallet(w, now = Date.now()) {
const effective = new Date(w.effective_at).getTime() <= now;
return {
id: w.id,
agent_id: w.agent_id,
address: w.address,
chain: w.chain,
is_default: w.is_default,
preferred_network: w.preferred_network,
created_at: w.created_at,
verified_at: w.verified_at || null,
approved_at: w.approved_at || null,
effective_at: w.effective_at,
approval_request_id: w.approval_request_id || null,
set_by: w.set_by || null,
status: !w.approved_at ? 'awaiting_approval' : effective ? 'active' : 'cooldown',
};
}
async function currentPayoutWallet({ userId, agentId, chain }) {
const rail = railChains(chain);
const [row] = await sql`
select * from agent_payout_wallets
where user_id = ${userId} and chain = any(${rail}) and agent_id is not distinct from ${agentId}
order by is_default desc, created_at desc limit 1
`;
return row || null;
}
/**
* The wallet a change is judged against. An agent with no row of its own is
* already paid to the account-level wallet on the rail (the withdrawal query
* falls back to it), so its first per-agent wallet REDIRECTS earnings and must
* face the same step-up, approval and cooldown as any replacement. Judging it
* as a "first wallet" is how a stolen session or a wallet:write key could
* re-point payouts instantly.
*/
async function policyBaseWallet({ userId, agentId, chain }) {
const own = await currentPayoutWallet({ userId, agentId, chain });
if (own || !agentId) return own;
return currentPayoutWallet({ userId, agentId: null, chain });
}
/**
* The cooldown and step-up rules, shared with the unproved writers
* (api/monetization/wallet.js, api/billing/payout-wallets/index.js) so no
* route can replace a live payout address instantly.
* first wallet on the rail, or the same address again: live at once
* a different address: step-up required, live after PAYOUT_COOLDOWN_HOURS
*/
export async function payoutChangePolicy({ userId, agentId = null, chain, address, stepUp = false }) {
const existing = await policyBaseWallet({ userId, agentId, chain });
const now = new Date().toISOString();
if (!existing || existing.address === address) return { approvedAt: now, effectiveAt: now, previous: null, replacing: false };
if (!stepUp) {
throw new ExternalWalletError('step_up_required', 'changing a payout wallet needs your password or a fresh sign-in', 403, {
current_address: existing.address, cooldown_hours: PAYOUT_COOLDOWN_HOURS,
});
}
return { approvedAt: now, effectiveAt: new Date(Date.now() + PAYOUT_COOLDOWN_HOURS * 3600 * 1000).toISOString(), previous: existing.address, replacing: true };
}
/** Step-up for a session: a fresh re-authentication cookie, or the password in the body. */
export async function stepUpProven(req, userId, body = {}) {
if (await readReauth(req, userId)) return true;
if (typeof body?.password !== 'string' || !body.password) return false;
const [row] = await sql`select password_hash from users where id = ${userId} limit 1`;
return Boolean(row?.password_hash) && (await verifyPassword(body.password, row.password_hash));
}
async function writePayoutWallet({ userId, agentId, chain, address, proofChain, signatureHash, setBy, approvedAt, effectiveAt, approvalRequestId = null }) {
const existing = await currentPayoutWallet({ userId, agentId, chain });
await sql`
update agent_payout_wallets set is_default = false
where user_id = ${userId} and chain = any(${railChains(chain)}) and agent_id is not distinct from ${agentId}
`;
if (existing) {
const [row] = await sql`
update agent_payout_wallets
set address = ${address}, chain = ${chain}, is_default = true, proof_chain = ${proofChain}, proof_signature_hash = ${signatureHash},
verified_at = now(), set_by = ${setBy}, approved_at = ${approvedAt}, effective_at = ${effectiveAt},
approval_request_id = ${approvalRequestId}
where id = ${existing.id} returning *
`;
return { row, previous: existing.address };
}
const [row] = await sql`
insert into agent_payout_wallets
(user_id, agent_id, address, chain, is_default, proof_chain, proof_signature_hash, verified_at, set_by, approved_at, effective_at, approval_request_id)
values (${userId}, ${agentId}, ${address}, ${chain}, true, ${proofChain}, ${signatureHash}, now(), ${setBy}, ${approvedAt}, ${effectiveAt}, ${approvalRequestId})
returning *
`;
return { row, previous: null };
}
async function agentOwnedBy(agentId, userId) {
if (!agentId) return null;
const [agent] = await sql`select id, user_id, name from agent_identities where id = ${agentId} and deleted_at is null limit 1`;
if (!agent) throw new ExternalWalletError('agent_not_found', 'agent not found', 404);
if (agent.user_id !== userId) throw new ExternalWalletError('forbidden', 'you do not own this agent', 403);
return agent;
}
/**
* Set a proved payout wallet.
* actor 'owner' a signed-in session. A replacement needs `stepUp` true.
* actor 'agent' an API key or MCP tool. A replacement files an approval.
*/
export async function setPayoutWallet({ userId, agentId = null, chain, address, signatureHash, actor, stepUp = false, req = null }) {
const agent = await agentOwnedBy(agentId, userId);
const payoutChainName = payoutChain(chain);
const own = await currentPayoutWallet({ userId, agentId, chain: payoutChainName });
const existing = own || (agentId ? await currentPayoutWallet({ userId, agentId: null, chain: payoutChainName }) : null);
const proofChain = chain;
if (own && own.address === address && own.approved_at) {
return { outcome: 'unchanged', wallet: publicPayoutWallet(own) };
}
// No wallet at all, or the agent adopting the very address it is already
// paid to through the account wallet: nothing is redirected, so it is live.
if (!existing || (!own && existing.address === address)) {
const { row } = await writePayoutWallet({
userId, agentId, chain: payoutChainName, address, proofChain, signatureHash, setBy: actor,
approvedAt: new Date().toISOString(), effectiveAt: new Date().toISOString(),
});
logAudit({ userId, action: 'link_payout_wallet', resourceId: row.id, meta: { chain: payoutChainName, address, agent_id: agentId, actor, first: true }, req });
return { outcome: 'active', wallet: publicPayoutWallet(row) };
}
const effectiveAt = new Date(Date.now() + PAYOUT_COOLDOWN_HOURS * 3600 * 1000).toISOString();
if (actor === 'owner') {
if (!stepUp) {
throw new ExternalWalletError('step_up_required', 'changing a payout wallet needs your password or a fresh sign-in', 403, {
current_address: existing.address, cooldown_hours: PAYOUT_COOLDOWN_HOURS,
});
}
const { row, previous } = await writePayoutWallet({
userId, agentId, chain: payoutChainName, address, proofChain, signatureHash, setBy: actor,
approvedAt: new Date().toISOString(), effectiveAt,
});
logAudit({ userId, action: 'link_payout_wallet', resourceId: row.id, meta: { chain: payoutChainName, address, previous, agent_id: agentId, actor, effective_at: effectiveAt, step_up: true }, req });
return { outcome: 'cooldown', wallet: publicPayoutWallet(row), previous, cooldown_hours: PAYOUT_COOLDOWN_HOURS };
}
// An agent asked. The owner decides from the approvals inbox; the address
// is written only by the executor below, after the approval.
let created;
try {
created = await createApprovalRequest({
userId,
agentId,
requesterRole: 'agent',
source: APPROVAL_SOURCE,
sourceRef: `payout:${agentId || 'account'}:${payoutChainName}`,
actionType: APPROVAL_ACTION,
venue: APPROVAL_VENUE,
payload: { user_id: userId, agent_id: agentId, chain: payoutChainName, proof_chain: proofChain, address, previous: existing.address, signature_hash: signatureHash },
summary: `Change the ${payoutChainName === 'solana' ? 'Solana' : 'Base'} payout wallet${agent ? ` for ${agent.name}` : ''} to ${address}`,
chain: payoutChainName,
recipient: address,
recipientLabel: 'New payout wallet',
riskNotes: [
`Earnings currently go to ${existing.address}.`,
`The new wallet takes effect ${PAYOUT_COOLDOWN_HOURS} hours after you approve.`,
],
gateReason: 'An agent asked to change where its earnings are paid out. Only you can approve that.',
idempotencyKey: `payout_wallet:${userId}:${agentId || 'account'}:${payoutChainName}:${signatureHash}`,
autoApprovable: false,
});
} catch (err) {
if (err instanceof ApprovalError) throw new ExternalWalletError(err.code, err.message, err.status);
throw err;
}
logAudit({ userId, action: 'link_payout_wallet_requested', resourceId: created.request.id, meta: { chain: payoutChainName, address, previous: existing.address, agent_id: agentId, actor }, req });
return { outcome: 'awaiting_approval', approval: { id: created.request.id, status: created.request.status, expires_at: created.request.expires_at, payload_hash: created.request.payload_hash }, previous: existing.address, cooldown_hours: PAYOUT_COOLDOWN_HOURS };
}
/** The approvals executor for APPROVAL_SOURCE: writes the address once the owner approved. */
export async function executeApprovedPayoutWallet(row) {
const p = row.payload || {};
if (!p.user_id || !p.address || !p.chain) return { status: 'error', note: 'The request payload is incomplete, so nothing was changed.' };
if (String(p.user_id) !== String(row.user_id)) return { status: 'error', note: 'This request belongs to a different account, so nothing was changed.' };
if (p.agent_id) {
const [agent] = await sql`select user_id from agent_identities where id = ${p.agent_id} and deleted_at is null limit 1`;
if (!agent || agent.user_id !== row.user_id) return { status: 'error', note: 'This agent is no longer owned by the account that approved it, so nothing was changed.' };
}
const effectiveAt = new Date(Date.now() + PAYOUT_COOLDOWN_HOURS * 3600 * 1000).toISOString();
const { row: wallet, previous } = await writePayoutWallet({
userId: row.user_id, agentId: p.agent_id || null, chain: p.chain, address: p.address, proofChain: p.proof_chain || null,
signatureHash: p.signature_hash || null, setBy: 'agent', approvedAt: new Date().toISOString(), effectiveAt, approvalRequestId: row.id,
});
logAudit({ userId: row.user_id, action: 'link_payout_wallet', resourceId: wallet.id, meta: { chain: p.chain, address: p.address, previous, agent_id: p.agent_id || null, actor: 'agent', approval_id: row.id, effective_at: effectiveAt } });
return { status: 'ok', note: `Payout wallet set to ${p.address}; it takes effect in ${PAYOUT_COOLDOWN_HOURS} hours.`, wallet_id: wallet.id, effective_at: effectiveAt };
}
/** Every payout wallet with its live status, for the account page and get_linked_accounts. */
export async function listPayoutWallets(userId) {
const rows = await sql`
select w.*, a.name as agent_name
from agent_payout_wallets w left join agent_identities a on a.id = w.agent_id
where w.user_id = ${userId}
order by w.agent_id nulls first, w.chain, w.is_default desc, w.created_at desc
`;
return rows.map((w) => ({ ...publicPayoutWallet(w), agent_name: w.agent_name || null }));
}