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.

12.5 KB
Raw Blame
// Per-user x402 payer — lets an authenticated three.ws user's agent pay an
// arbitrary external x402 endpoint in USDC from THEIR OWN Solana agent wallet,
// bounded by spending caps. This is the money core behind the `pay_and_call`
// MCP tool ("add a wallet to Claude").
//
// It reuses the SDK's audited exact-scheme signing (@x402/svm) rather than
// hand-rolling transaction construction: we build an x402Client, register the
// Solana exact scheme with a signer derived from the user's recovered keypair,
// install the platform spending cap (enforceCap → commit / rollback), and let
// @x402/axios run the full 402 → sign → settle dance.
//
// registerExactSvmScheme() wires BOTH wire formats on the same client: v2's
// CAIP-2 `solana:*` wildcard and v1's flat network strings (`solana`,
// `solana-devnet`, `solana-testnet`), the format most of the open x402 bazaar
// and the owner's x402-suite still speak. @x402/core's x402HTTPClient already
// prefers the v2 `PAYMENT-REQUIRED` header over a v1-shaped JSON body when a
// seller advertises both, so no extra selection logic is needed here.
//
// SAFETY: spending is OFF unless THREEWS_AGENT_PAY_ENABLED=1. This is real money
// moving from a real user wallet; the flag exists so the capability ships dark
// and is only enabled after a funded-wallet integration test. When disabled,
// resolveSpendEnabled() returns false and callers degrade to a payment-details
// handoff instead of moving funds.

import dns from 'node:dns';
import https from 'node:https';
import http from 'node:http';
import { sql } from './db.js';
import { solanaConnection } from './solana/connection.js';
import { env } from './env.js';
import { recoverSolanaAgentKeypair } from './agent-wallet.js';
import { installSpendingCap } from './x402-spending-cap.js';
import { validatePublicUrl, isPrivateAddress, SsrfError } from './ssrf.js';

// SSRF guard for the user-paying client. `pay_and_call` forwards a caller-
// supplied URL into a server-side HTTP request, so without this an authenticated
// user could steer the request at cloud metadata (169.254.169.254), localhost,
// or RFC-1918 hosts and read the reflected body. We defend in three layers:
//   1. validatePublicUrl() — https-only (http in dev), at the boundary.
//   2. guardedLookup — rejects resolution to any private/loopback/link-local/
//      metadata address AT CONNECT TIME, closing the DNS-rebinding window that a
//      resolve-then-connect check would leave open.
//   3. maxRedirects: 0 on the axios client — a public host cannot 30x-redirect
//      into an internal target.
// This mirrors the guard the local mcp-bridge already applies (assertPayableUrl
// + maxRedirects:0); the hosted path was the one missing it.
function guardedLookup(hostname, options, callback) {
	const cb = typeof options === 'function' ? options : callback;
	const opts = typeof options === 'function' ? {} : options || {};
	dns.lookup(hostname, { ...opts, all: true, verbatim: true }, (err, addresses) => {
		if (err) return cb(err);
		const addrs = Array.isArray(addresses) ? addresses : [addresses];
		for (const a of addrs) {
			if (isPrivateAddress(a.address, a.family)) {
				return cb(
					new SsrfError(`blocked private address for ${hostname}`, 'private_address'),
				);
			}
		}
		if (opts.all) return cb(null, addrs);
		return cb(null, addrs[0].address, addrs[0].family);
	});
}

const ssrfHttpsAgent = new https.Agent({ lookup: guardedLookup, keepAlive: false });
const ssrfHttpAgent = new http.Agent({ lookup: guardedLookup, keepAlive: false });

// Boundary check: scheme + that the literal/resolved host is not private. Throws
// an Error with a safe `.code` for the MCP handler to translate.
async function assertPublicPayableUrl(rawUrl) {
	let url;
	try {
		url = validatePublicUrl(rawUrl);
	} catch (e) {
		throw Object.assign(new Error('target URL is not a permitted public https endpoint'), {
			code: 'invalid_url',
			cause: e,
		});
	}
	// Resolve up front so an obviously-internal target is rejected before we
	// recover the user's key or move any money. The connect-time guardedLookup is
	// the authoritative check; this is a fast fail.
	await new Promise((resolve, reject) => {
		guardedLookup(url.hostname, { all: true }, (err) =>
			err
				? reject(
						Object.assign(new Error('target URL resolves to a non-public address'), {
							code: 'blocked_url',
						}),
					)
				: resolve(),
		);
	});
	return url.href;
}

// Atomic-USDC caps. Defaults are intentionally tiny; operators raise them via
// env once they trust the flow. A per-call override from the tool can only
// LOWER the per-call cap, never raise it past the env ceiling.
const DEFAULT_MAX_PER_CALL = 100_000n; // $0.10
const DEFAULT_MAX_PER_HOUR = 1_000_000n; // $1.00
const DEFAULT_MAX_PER_DAY = 10_000_000n; // $10.00

function envAtomic(name, fallback) {
	const raw = env[name] ?? (typeof process !== 'undefined' ? process.env?.[name] : undefined);
	if (!raw) return fallback;
	try {
		const v = BigInt(raw);
		return v >= 0n ? v : fallback;
	} catch {
		return fallback;
	}
}

export function resolveSpendEnabled() {
	const raw =
		env.THREEWS_AGENT_PAY_ENABLED ??
		(typeof process !== 'undefined' ? process.env?.THREEWS_AGENT_PAY_ENABLED : undefined);
	return raw === '1' || raw === 'true';
}

// The user's primary agent wallet — first agent by creation, matching the
// existing x402-pay convention (getAgentsForUser orders by created_at ASC).
export async function resolveUserAgentWallet(userId) {
	if (!userId) return null;
	const [row] = await sql`
		SELECT id, name, meta FROM agent_identities
		WHERE user_id = ${userId} AND deleted_at IS NULL
		ORDER BY created_at ASC
		LIMIT 1
	`;
	if (!row) return null;
	return shapeWallet(row);
}

function shapeWallet(row) {
	if (!row) return null;
	return {
		agentId: row.id,
		name: row.name || null,
		address: row.meta?.solana_address || null,
		hasSecret: !!row.meta?.encrypted_solana_secret,
		encryptedSecret: row.meta?.encrypted_solana_secret || null,
	};
}

// A SPECIFIC agent's wallet, but only if the caller owns it. Used by the
// agent-to-agent economy so the hiring agent the owner chose is the one that
// pays — not just their first-created agent. Returns null when the agent does not
// exist or is not owned by `userId`, so the caller fails closed.
export async function resolveAgentWalletById(agentId, userId) {
	if (!agentId || !userId) return null;
	const [row] = await sql`
		SELECT id, name, meta FROM agent_identities
		WHERE id = ${agentId} AND user_id = ${userId} AND deleted_at IS NULL
		LIMIT 1
	`;
	return shapeWallet(row);
}

// Build a paying axios instance bound to the user's Solana keypair, with the
// platform spending cap installed. Returns { api, client, uninstall, address }.
async function buildUserPayingClient({ wallet, userId, maxPerCallOverride }) {
	const [
		{ default: axios },
		{ x402Client, x402HTTPClient },
		{ wrapAxiosWithPayment },
		{ registerExactSvmScheme },
		{ createKeyPairSignerFromBytes },
	] = await Promise.all([
		import('axios'),
		import('@x402/core/client'),
		import('@x402/axios'),
		import('@x402/svm/exact/client'),
		import('@solana/kit'),
	]);

	const keypair = await recoverSolanaAgentKeypair(wallet.encryptedSecret, {
		agentId: wallet.agentId,
		userId,
		reason: 'pay_and_call',
	});
	const svmSigner = await createKeyPairSignerFromBytes(keypair.secretKey);

	const client = new x402Client();
	registerExactSvmScheme(client, { signer: svmSigner });

	const envPerCall = envAtomic('X402_MAX_PER_CALL_ATOMIC', DEFAULT_MAX_PER_CALL);
	const perCall =
		maxPerCallOverride != null && maxPerCallOverride < envPerCall
			? maxPerCallOverride
			: envPerCall;
	const uninstall = installSpendingCap(client, {
		address: wallet.address,
		maxPerCall: perCall.toString(),
		maxPerHour: envAtomic('X402_MAX_PER_HOUR_ATOMIC', DEFAULT_MAX_PER_HOUR).toString(),
		maxPerDay: envAtomic('X402_MAX_PER_DAY_ATOMIC', DEFAULT_MAX_PER_DAY).toString(),
	});

	const httpClient = new x402HTTPClient(client);
	const api = wrapAxiosWithPayment(
		axios.create({
			timeout: 60_000,
			validateStatus: (s) => s >= 200 && s < 300,
			// SSRF defense: pin connects to non-private addresses and never follow
			// a redirect into an internal target. See guardedLookup above.
			maxRedirects: 0,
			httpsAgent: ssrfHttpsAgent,
			httpAgent: ssrfHttpAgent,
		}),
		client,
	);
	return { api, client, httpClient, uninstall, address: wallet.address };
}

function extractReceipt(httpClient, response) {
	if (!response?.headers) return null;
	try {
		return (
			httpClient.getPaymentSettleResponse(
				(n) => response.headers[n] ?? response.headers[n.toLowerCase()],
			) || null
		);
	} catch {
		return null;
	}
}

const USDC_MAINNET_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';

// Read-only wallet status for the user's primary agent: address, SOL + USDC
// balance, the active spending caps, and whether autonomous spend is enabled.
// Safe to expose — no keys touched, no funds moved.
export async function getUserWalletStatus(userId) {
	const wallet = await resolveUserAgentWallet(userId);
	const caps = {
		max_per_call_usdc:
			Number(envAtomic('X402_MAX_PER_CALL_ATOMIC', DEFAULT_MAX_PER_CALL)) / 1e6,
		max_per_hour_usdc:
			Number(envAtomic('X402_MAX_PER_HOUR_ATOMIC', DEFAULT_MAX_PER_HOUR)) / 1e6,
		max_per_day_usdc: Number(envAtomic('X402_MAX_PER_DAY_ATOMIC', DEFAULT_MAX_PER_DAY)) / 1e6,
	};
	const spend_enabled = resolveSpendEnabled();
	if (!wallet || !wallet.address) {
		return { provisioned: false, address: null, spend_enabled, caps };
	}

	let sol = null;
	let usdc = null;
	try {
		const { Connection, PublicKey } = await import('@solana/web3.js');
		const { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } =
			await import('@solana/spl-token');
		const rpc =
			env.SOLANA_RPC_URL ??
			(typeof process !== 'undefined' ? process.env?.SOLANA_RPC_URL : null) ??
			'https://api.mainnet-beta.solana.com';
		const conn = solanaConnection({ url: rpc, commitment: 'confirmed' });
		const owner = new PublicKey(wallet.address);
		const lamports = await conn.getBalance(owner);
		sol = lamports / 1e9;
		try {
			const ata = getAssociatedTokenAddressSync(
				new PublicKey(USDC_MAINNET_MINT),
				owner,
				false,
				TOKEN_PROGRAM_ID,
				ASSOCIATED_TOKEN_PROGRAM_ID,
			);
			const bal = await conn.getTokenAccountBalance(ata);
			usdc = bal?.value?.uiAmount ?? 0;
		} catch {
			usdc = 0; // no ATA yet → zero USDC
		}
	} catch {
		// RPC failure — report the wallet without live balances rather than throw.
	}

	return {
		provisioned: true,
		agent_id: wallet.agentId,
		agent_name: wallet.name,
		address: wallet.address,
		network: 'solana',
		balances: { sol, usdc },
		spend_enabled,
		caps,
	};
}

// Pay an external x402 endpoint from the user's wallet. Throws an Error with a
// `.code` for the boundary (the MCP handler) to translate into a clean result.
export async function payExternalX402({ userId, agentId, url, method = 'GET', body, maxUsd, headers }) {
	if (!resolveSpendEnabled()) {
		throw Object.assign(new Error('autonomous spending is disabled on this server'), {
			code: 'spend_disabled',
		});
	}
	if (!userId) {
		throw Object.assign(new Error('sign in required to pay from your wallet'), {
			code: 'auth_required',
		});
	}
	// When the caller names a specific agent (the agent-to-agent economy), that
	// agent — owned by this user — is the payer. Otherwise fall back to the user's
	// primary agent wallet (the original pay_and_call behavior).
	const wallet = agentId
		? await resolveAgentWalletById(agentId, userId)
		: await resolveUserAgentWallet(userId);
	if (!wallet) {
		throw Object.assign(new Error('no agent wallet found for this account'), {
			code: 'no_wallet',
		});
	}
	if (!wallet.address || !wallet.hasSecret) {
		throw Object.assign(new Error('your agent has no Solana wallet provisioned'), {
			code: 'no_solana_wallet',
		});
	}

	// Reject internal / non-public targets before recovering the key or moving
	// money. Throws { code: invalid_url | blocked_url } for the handler.
	const safeUrl = await assertPublicPayableUrl(url);

	const maxPerCallOverride =
		typeof maxUsd === 'number' && maxUsd > 0 ? BigInt(Math.round(maxUsd * 1_000_000)) : null;

	const { api, httpClient, uninstall, address } = await buildUserPayingClient({
		wallet,
		userId,
		maxPerCallOverride,
	});

	try {
		const response = await api.request({
			url: safeUrl,
			method,
			...(body != null ? { data: body } : {}),
			...(headers && typeof headers === 'object' ? { headers } : {}),
		});
		return {
			ok: true,
			payer: address,
			result: response.data,
			receipt: extractReceipt(httpClient, response),
		};
	} finally {
		if (typeof uninstall === 'function') uninstall();
	}
}