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.6 KB
Raw Blame
// Signed, single-use previews for the financial trading tools.
//
// Every tool that moves funds or cannot be undone (swap_execute, launch_buy,
// dca_create, limit_order_create, add_to_whitelist, wallet_transfer, ...) is
// the second half of a pair. Its preview tool (swap_quote, launch_quote,
// dca_preview, order_preview, whitelist_preview, transfer_preview) reads live
// state, runs the same guards the execute path will run, and returns an id.
// The financial tool takes only that id plus its named confirm flag, so it can
// never act on anything other than what the owner was shown.
//
// The id is an HMAC-signed token that pins:
//   - the tool family it was issued for (a swap quote cannot authorize a
//     transfer, a limit-order preview cannot create a DCA),
//   - the caller (user id), and the agent when there is one,
//   - every parameter the execute step will use.
// It lives ten minutes (the MCP tool policy's preview window) and is spent once:
// `consumePreview` takes a cross-instance lock on its nonce, so a second
// execute is refused instead of acting twice. A failed execute releases the
// lock so the owner can retry the same approved preview.

import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';

import { env } from '../env.js';
import { acquireLock, releaseLock } from '../cache.js';

/** How long a preview authorizes its financial tool. Matches the MCP policy window. */
export const PREVIEW_TTL_MS = 10 * 60 * 1000;

const b64url = (buf) => Buffer.from(buf).toString('base64url');

function sign(payload) {
	return createHmac('sha256', `trading-preview:${env.JWT_SECRET}`).update(payload).digest();
}

/** A refusal the tool layer turns into an error result naming the preview tool. */
export class PreviewError extends Error {
	/**
	 * @param {string} code  preview_required | preview_invalid | preview_mismatch | preview_stale | preview_used
	 * @param {string} message
	 */
	constructor(code, message) {
		super(message);
		this.code = code;
	}
}

/**
 * Issue a preview id.
 * @param {string} kind     'swap' | 'launch' | 'dca' | 'order' | 'allowlist' | 'transfer'
 * @param {object} claims   pinned parameters; must include userId
 * @param {{ prefix?: 'q'|'p', now?: number }} [opts]  'q' for quotes (quote_id), 'p' for previews (preview_id)
 * @returns {{ id: string, expires_at: string }}
 */
export function issuePreview(kind, claims, { prefix = 'p', now = Date.now() } = {}) {
	if (!claims?.userId) throw new Error('issuePreview: claims.userId is required');
	const exp = now + PREVIEW_TTL_MS;
	const payload = b64url(JSON.stringify({ k: kind, n: randomUUID(), exp, c: claims }));
	return { id: `${prefix}_${payload}.${b64url(sign(payload))}`, expires_at: new Date(exp).toISOString() };
}

/**
 * Verify a preview id and return its pinned claims and nonce.
 * @param {unknown} id
 * @param {string|string[]} kind  accepted kind(s)
 * @param {{ userId: string, now?: number }} who
 * @returns {{ claims: object, nonce: string, kind: string, expires_at: string }}
 */
export function verifyPreview(id, kind, { userId, now = Date.now() }) {
	if (typeof id !== 'string' || !/^[qp]_[\w-]+\.[\w-]+$/.test(id)) {
		throw new PreviewError('preview_required', 'A preview id from the matching preview tool is required.');
	}
	const [payload, sig] = id.slice(2).split('.');
	const expected = sign(payload);
	const given = Buffer.from(sig, 'base64url');
	if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
		throw new PreviewError('preview_invalid', 'This preview id failed verification.');
	}
	let parsed;
	try {
		parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
	} catch {
		throw new PreviewError('preview_invalid', 'This preview id is malformed.');
	}
	const kinds = Array.isArray(kind) ? kind : [kind];
	if (!kinds.includes(parsed.k)) {
		throw new PreviewError('preview_mismatch', `This id was issued for a ${parsed.k} preview, not this action.`);
	}
	if (parsed.c?.userId !== userId) {
		throw new PreviewError('preview_mismatch', 'This preview belongs to a different account.');
	}
	if (!Number.isFinite(parsed.exp) || parsed.exp < now) {
		throw new PreviewError('preview_stale', 'This preview is older than ten minutes, so it no longer reflects live prices and balances.');
	}
	return { claims: parsed.c, nonce: parsed.n, kind: parsed.k, expires_at: new Date(parsed.exp).toISOString() };
}

const lockKey = (nonce) => `trading-preview:used:${nonce}`;

// Process-local record of spent nonces. acquireLock degrades to "granted" when
// Redis is not configured or unreachable, so without this a single instance
// could spend one preview twice during a Redis outage.
const spentLocal = new Map();

function sweepLocal(now) {
	for (const [k, exp] of spentLocal) if (exp < now) spentLocal.delete(k);
}

/**
 * Spend a preview. Resolves a release function when this caller holds it, and
 * throws preview_used when another execute already spent it.
 * @param {string} nonce
 * @returns {Promise<() => Promise<void>>} call on failure to let the owner retry
 */
export async function consumePreview(nonce) {
	const key = lockKey(nonce);
	const now = Date.now();
	sweepLocal(now);
	if (spentLocal.has(key)) throw new PreviewError('preview_used', 'This preview was already used. Request a fresh one.');
	// Held past the preview's own lifetime, so a spent id stays spent until it
	// could no longer verify anyway.
	const ttlSeconds = Math.ceil(PREVIEW_TTL_MS / 1000) + 60;
	const ok = await acquireLock(key, ttlSeconds);
	if (!ok) throw new PreviewError('preview_used', 'This preview was already used. Request a fresh one.');
	spentLocal.set(key, now + ttlSeconds * 1000);
	return async () => {
		spentLocal.delete(key);
		await releaseLock(key);
	};
}