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.

32.7 KB
Raw Blame
// Agent cards service: the one place card purchases, status, reveals and
// withdrawals happen. The REST routes (api/v1/agent-cards.js) and the MCP tools
// (api/_mcp/tools/cards.js) are thin boundaries over these functions.
//
// Money path (live mode)
//   quote   creates the provider's price-locked USDC invoice and stores it as a
//           card row in status 'quoted' for QUOTE_TTL_MS.
//   create  requires confirm_spend === true and that fresh quote id. It claims
//           the quote atomically (so it settles at most once), re-reads the
//           provider invoice to prove the address and exact amount are
//           unchanged, then pays through transferUsdcGuarded: the custody
//           reserve under the agent's spend limits, natural-language policy,
//           capability scope and the anomaly freeze, all before any key is
//           touched, with the spend recorded in agent_custody_events.
//
// Secret path
//   On delivery the redemption data is fetched once, secret-box encrypted
//   (the custodial-wallet scheme) and stored; only a masked form and the list
//   of field names are kept in the clear. `data` issues a single-use reveal
//   grant; `reveal` requires confirm_reveal === true plus that grant, returns
//   the secret, clears the ciphertext in the same statement, and logs who
//   revealed what (field names, never values) in agent_card_events.

import { createHash, randomBytes } from 'node:crypto';
import { sql } from '../db.js';
import { encryptSecret, decryptSecret } from '../agent-wallet.js';
import { transferUsdcGuarded } from '../agent-usdc-transfer.js';
import { currentSignatureFor, agreementRequirement } from '../real-funds-agreement.js';
import { logAudit } from '../audit.js';
import { getCardProvider, CardProviderError, DEFAULT_PROVIDER } from './provider.js';
import { resolveDenomination } from './bitrefill.js';

export const QUOTE_TTL_MS = 10 * 60 * 1000;
export const REVEAL_GRANT_TTL_MS = 5 * 60 * 1000;
const MAX_QUOTES_PER_HOUR = 30;
const OPEN_STATUSES = ['paying', 'processing', 'needs_verification'];
const TERMINAL = new Set(['delivered', 'failed', 'refunded', 'cancelled', 'expired']);
const POLL_ATTEMPTS = 4;
const POLL_GAP_MS = 2500;

/** Live purchases are enabled per deploy; sandbox always works. */
export function liveCardsEnabled() {
	return process.env.AGENT_CARDS_LIVE === '1';
}

export class CardError extends Error {
	constructor(status, code, message, details = null) {
		super(message);
		this.name = 'CardError';
		this.status = status;
		this.code = code;
		this.details = details;
	}
}

/** Map an adapter error onto the service error shape. */
function fromProvider(e) {
	if (e instanceof CardProviderError) return new CardError(e.status, e.code, e.message, e.detail || null);
	return e;
}

async function withProvider(fn) {
	try {
		return await fn();
	} catch (e) {
		throw fromProvider(e);
	}
}

function actorKind(principal) {
	if (!principal) return 'system';
	if (principal.source === 'session') return 'owner_session';
	if (principal.source === 'apikey') return 'api_key';
	if (principal.source === 'oauth') return 'oauth';
	if (principal.source === 'mcp') return 'mcp';
	return String(principal.source || 'owner');
}

/** Load an agent the principal owns, or throw a designed 401/403/404. */
export async function loadOwnedAgent(agentId, principal) {
	if (!principal?.userId) throw new CardError(401, 'unauthorized', 'Sign in to manage agent cards.');
	if (!/^[0-9a-f-]{36}$/i.test(String(agentId || ''))) {
		throw new CardError(400, 'invalid_agent_id', 'agent id must be a UUID');
	}
	const [agent] = await sql`
		SELECT id, user_id, name, meta
		FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL
	`;
	if (!agent) throw new CardError(404, 'agent_not_found', 'Agent not found.');
	if (agent.user_id !== principal.userId) {
		throw new CardError(403, 'forbidden', 'Only the owner of this agent can manage its cards.');
	}
	return agent;
}

async function recordCardEvent(card, principal, event, { from = null, to = null, detail = {}, grantHash = null, grantExpiresAt = null } = {}) {
	const [row] = await sql`
		INSERT INTO agent_card_events
			(card_id, agent_id, actor_user_id, actor_kind, event, from_status, to_status,
			 grant_hash, grant_expires_at, ip, detail)
		VALUES (
			${card.id}, ${card.agent_id}, ${principal?.userId ?? null}, ${actorKind(principal)}, ${event},
			${from}, ${to}, ${grantHash}, ${grantExpiresAt}, ${principal?.ip ?? null},
			${JSON.stringify(detail)}::jsonb
		)
		RETURNING id, created_at
	`;
	return row;
}

/** The owner-facing shape of a card. Never includes the ciphertext. */
export function cardView(row) {
	if (!row) return null;
	return {
		id: row.id,
		agent_id: row.agent_id,
		provider: row.provider,
		mode: row.mode,
		kind: row.kind,
		product_id: row.product_id,
		product_name: row.product_name,
		merchant: row.merchant,
		country_code: row.country_code,
		image_url: row.image_url,
		face_value: Number(row.face_value),
		currency: row.currency,
		status: row.status,
		provider_status: row.provider_status,
		total_usdc: Number(row.quote_total_usdc),
		fee_usdc: Number(row.quote_fee_usdc),
		quote_expires_at: row.quote_expires_at,
		pay_address: row.pay_address,
		pay_network: row.pay_network,
		pay_signature: row.pay_signature,
		pay_explorer: row.pay_signature ? `https://solscan.io/tx/${row.pay_signature}` : null,
		masked_number: row.masked_number,
		secret_fields: row.secret_fields || [],
		redeem_instructions: row.redeem_instructions,
		expires_on: row.expires_on,
		revealed_at: row.revealed_at,
		reveal_count: Number(row.reveal_count || 0),
		error_code: row.error_code,
		error_message: row.error_message,
		created_at: row.created_at,
		updated_at: row.updated_at,
		delivered_at: row.delivered_at,
	};
}

function quoteView(row, product) {
	const card = cardView(row);
	const live = row.mode === 'live';
	return {
		quote_id: row.id,
		mode: row.mode,
		product: product ? {
			id: product.id, name: product.name, merchant: product.merchant, kind: product.kind,
			country_code: product.country_code, image_url: product.image_url,
		} : { id: row.product_id, name: row.product_name, merchant: row.merchant, kind: row.kind },
		face_value: card.face_value,
		currency: card.currency,
		total_usdc: card.total_usdc,
		fee_usdc: card.fee_usdc,
		expires_at: row.quote_expires_at,
		// The exact table an owner must see before saying yes (stop-and-ask gate 1).
		confirm: {
			recipient: live ? row.pay_address : `${row.provider} sandbox (test product, no funds move)`,
			amount: live ? card.total_usdc.toFixed(6).replace(/0+$/, '').replace(/\.$/, '') : '0',
			token: 'USDC',
			chain: 'Solana',
			buys: `${card.merchant} ${row.kind === 'prepaid_card' ? 'prepaid card' : 'gift card'}, ${card.face_value} ${card.currency}`,
			provider: row.provider,
		},
		next: {
			tool: 'agent_card_create',
			args: { agent_id: row.agent_id, quote_id: row.id, confirm_spend: true },
			note: 'Show the confirm table to the owner and wait for an explicit yes before calling agent_card_create.',
		},
	};
}

// ── catalog ──────────────────────────────────────────────────────────────────

function providerFor(name) {
	try {
		return getCardProvider(name || DEFAULT_PROVIDER);
	} catch (e) {
		throw fromProvider(e);
	}
}

export function providerInfo(name) {
	const p = providerFor(name);
	return {
		name: p.name,
		label: p.label,
		capabilities: p.capabilities,
		configured: p.configured(),
		live_enabled: liveCardsEnabled(),
	};
}

export async function searchMerchants({ q, country, kind, sandbox, limit, provider } = {}) {
	const p = providerFor(provider);
	return withProvider(() => p.searchMerchants({ q, country, kind, sandbox, limit }));
}

export async function searchProducts({ q, country, category, merchant, kind, sandbox, limit, start, provider } = {}) {
	const p = providerFor(provider);
	return withProvider(() => p.searchProducts({ q, country, category, merchant, kind, sandbox, limit, start }));
}

export async function getProduct({ productId, provider } = {}) {
	const p = providerFor(provider);
	return withProvider(() => p.getProduct(productId));
}

// ── quote ────────────────────────────────────────────────────────────────────

async function requireAgreement(userId) {
	let sig;
	try {
		sig = await currentSignatureFor(userId);
	} catch {
		throw new CardError(503, 'agreement_check_failed', 'Could not verify your real-funds agreement. No funds moved; try again.');
	}
	if (!sig) {
		throw new CardError(403, 'agreement_required',
			'Buying a live card spends real USDC. Sign the real-funds agreements first, then try again.',
			agreementRequirement());
	}
}

export async function quoteCard({ agentId, principal, productId, amount, provider }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const p = providerFor(provider);
	const product = await withProvider(() => p.getProduct(productId));
	if (!product.in_stock) throw new CardError(409, 'out_of_stock', `${product.name} is out of stock right now. Pick another merchant or try later.`);
	const denom = await withProvider(async () => resolveDenomination(product, amount));

	const mode = p.isSandboxProduct(product.id) ? 'sandbox' : 'live';
	const meta = agent.meta || {};
	if (mode === 'live') {
		if (!liveCardsEnabled()) {
			throw new CardError(409, 'live_cards_disabled',
				'Live card purchases are not switched on for this deployment yet. Sandbox test products work today; search with sandbox: true to try the full flow.');
		}
		if (!meta.solana_address || !meta.encrypted_solana_secret) {
			throw new CardError(409, 'wallet_preparing', 'This agent has no Solana wallet yet, so it cannot pay for a card. Open its wallet page to provision one.');
		}
	}

	const [{ n }] = await sql`
		SELECT count(*)::int AS n FROM agent_cards
		WHERE agent_id = ${agent.id} AND created_at > now() - interval '1 hour'
	`;
	if (n >= MAX_QUOTES_PER_HOUR) {
		throw new CardError(429, 'quote_rate_limited', `This agent has requested ${n} card quotes in the last hour. Wait a while before quoting again.`);
	}

	const q = await withProvider(() => p.quote({
		product, value: denom.value, packageId: denom.packageId, mode,
		refundAddress: mode === 'live' ? meta.solana_address : null,
	}));

	const expiresAt = new Date(Date.now() + QUOTE_TTL_MS);
	const [row] = await sql`
		INSERT INTO agent_cards
			(agent_id, user_id, provider, mode, kind, product_id, product_name, merchant, country_code,
			 image_url, face_value, currency, status, quote_total_usdc, quote_total_atomic, quote_fee_usdc,
			 quote_expires_at, pay_address, provider_invoice_id, provider_order_id, provider_status, meta)
		VALUES (
			${agent.id}, ${agent.user_id}, ${p.name}, ${mode}, ${product.kind}, ${product.id}, ${product.name},
			${product.merchant}, ${product.country_code}, ${product.image_url}, ${denom.value}, ${product.currency},
			'quoted', ${q.total_usdc}, ${q.total_atomic.toString()}, ${q.fee_usdc}, ${expiresAt.toISOString()},
			${q.pay_address}, ${q.provider_invoice_id}, ${q.provider_order_id}, ${q.provider_status},
			${JSON.stringify({ package_id: denom.packageId })}::jsonb
		)
		RETURNING *
	`;
	await recordCardEvent(row, principal, 'quoted', {
		to: 'quoted',
		detail: { total_usdc: q.total_usdc, face_value: denom.value, currency: product.currency, mode },
	});
	return quoteView(row, product);
}

// ── create ───────────────────────────────────────────────────────────────────

async function claimQuote(agentId, quoteId) {
	const [row] = await sql`
		UPDATE agent_cards SET status = 'paying', updated_at = now()
		WHERE id = ${quoteId} AND agent_id = ${agentId} AND status = 'quoted' AND quote_expires_at > now()
		RETURNING *
	`;
	if (row) return row;
	const [existing] = await sql`SELECT * FROM agent_cards WHERE id = ${quoteId} AND agent_id = ${agentId}`;
	if (!existing) throw new CardError(404, 'quote_not_found', 'No quote with that id for this agent. Call agent_card_quote first.');
	if (existing.status === 'quoted') {
		await sql`UPDATE agent_cards SET status = 'expired', updated_at = now() WHERE id = ${quoteId} AND status = 'quoted'`;
		throw new CardError(409, 'quote_expired', 'That quote is more than ten minutes old. Call agent_card_quote again for a fresh price.');
	}
	throw new CardError(409, 'quote_used', `That quote was already used (card status: ${existing.status}). Call agent_card_quote for a new card.`);
}

async function setStatus(card, principal, patch, event = 'status') {
	const [row] = await sql`
		UPDATE agent_cards SET
			status = COALESCE(${patch.status ?? null}, status),
			provider_status = COALESCE(${patch.provider_status ?? null}, provider_status),
			pay_signature = COALESCE(${patch.pay_signature ?? null}, pay_signature),
			custody_event_id = COALESCE(${patch.custody_event_id ?? null}, custody_event_id),
			error_code = ${patch.error_code !== undefined ? patch.error_code : card.error_code ?? null},
			error_message = ${patch.error_message !== undefined ? patch.error_message : card.error_message ?? null},
			delivered_at = COALESCE(${patch.delivered_at ?? null}, delivered_at),
			updated_at = now()
		WHERE id = ${card.id}
		RETURNING *
	`;
	if (patch.status && patch.status !== card.status) {
		await recordCardEvent(row, principal, event, {
			from: card.status, to: patch.status,
			detail: patch.error_code ? { error_code: patch.error_code } : {},
		});
	}
	return row;
}

/**
 * Store the redemption data encrypted, once, right after delivery. Only runs
 * while the card has never been revealed, so a revealed secret is never
 * written back.
 */
async function sealSecret(card, p) {
	if (card.secret_enc || card.revealed_at) return card;
	const secret = await withProvider(() => p.reveal({ card }));
	const data = await withProvider(() => p.cardData({ card }));
	const fields = Object.keys(secret || {});
	if (!fields.length) return card;
	const sealed = await encryptSecret(JSON.stringify(secret));
	const [row] = await sql`
		UPDATE agent_cards SET
			secret_enc = ${sealed}, secret_fields = ${fields}, masked_number = ${data.masked},
			redeem_instructions = ${data.instructions}, expires_on = ${data.expires_on}, updated_at = now()
		WHERE id = ${card.id} AND secret_enc IS NULL AND revealed_at IS NULL
		RETURNING *
	`;
	return row || card;
}

/** Pull the provider's status onto the row; seals the secret on delivery. */
async function syncCard(card, principal) {
	const p = providerFor(card.provider);
	if (card.status === 'quoted') {
		if (new Date(card.quote_expires_at).getTime() <= Date.now()) {
			return setStatus(card, principal, { status: 'expired' });
		}
		return card;
	}
	if (TERMINAL.has(card.status) && card.status !== 'delivered') return card;
	if (card.status === 'delivered' && (card.secret_enc || card.revealed_at)) return card;
	// A live card whose payment never broadcast has nothing to ask the provider.
	if (card.status === 'paying' && card.mode === 'live' && !card.pay_signature) return card;

	const s = await withProvider(() => p.status({ card }));
	let next = card.status;
	if (s.status === 'delivered') next = 'delivered';
	else if (s.status === 'failed') next = 'failed';
	else if (s.status === 'refunded') next = 'refunded';
	else if (s.status === 'needs_verification') next = 'needs_verification';
	else if (s.status === 'processing' || (s.status === 'awaiting_payment' && card.pay_signature)) next = 'processing';

	let row = await setStatus(card, principal, {
		status: next,
		provider_status: s.provider_status,
		delivered_at: next === 'delivered' ? (s.delivered_at || new Date().toISOString()) : null,
		error_code: next === 'failed' ? 'provider_failed' : undefined,
		error_message: next === 'failed' ? s.error : undefined,
	});
	if (row.status === 'delivered') row = await sealSecret(row, p);
	return row;
}

const pause = (ms) => new Promise((r) => setTimeout(r, ms));

async function pollUntilSettled(card, principal) {
	let row = card;
	for (let i = 0; i < POLL_ATTEMPTS; i++) {
		row = await syncCard(row, principal);
		if (TERMINAL.has(row.status) || row.status === 'needs_verification') return row;
		await pause(POLL_GAP_MS);
	}
	return row;
}

export async function createCard({ agentId, principal, quoteId, confirmSpend }) {
	const agent = await loadOwnedAgent(agentId, principal);
	if (confirmSpend !== true) {
		throw new CardError(400, 'confirm_required',
			'agent_card_create moves funds. Call agent_card_quote first, show the owner its confirm table, and pass confirm_spend: true only after they say yes.',
			{ preview_tool: 'agent_card_quote', confirm_flag: 'confirm_spend' });
	}
	if (typeof quoteId !== 'string' || !/^[0-9a-f-]{36}$/i.test(quoteId)) {
		throw new CardError(400, 'quote_required', 'quote_id from agent_card_quote is required.', { preview_tool: 'agent_card_quote' });
	}

	const [peek] = await sql`SELECT mode FROM agent_cards WHERE id = ${quoteId} AND agent_id = ${agent.id}`;
	if (peek?.mode === 'live') {
		if (!liveCardsEnabled()) throw new CardError(409, 'live_cards_disabled', 'Live card purchases are not switched on for this deployment.');
		await requireAgreement(principal.userId);
	}

	let card = await claimQuote(agent.id, quoteId);
	await recordCardEvent(card, principal, 'purchase_confirmed', { from: 'quoted', to: 'paying', detail: { total_usdc: Number(card.quote_total_usdc) } });
	const p = providerFor(card.provider);

	if (card.mode === 'sandbox') {
		try {
			await p.create({ card });
		} catch (e) {
			const err = fromProvider(e);
			await setStatus(card, principal, { status: 'failed', error_code: err.code || 'provider_error', error_message: err.message });
			throw err;
		}
		card = await setStatus(card, principal, { status: 'processing' }, 'paid');
		return cardView(await pollUntilSettled(card, principal));
	}

	// Live: prove the provider invoice still asks for exactly what the owner confirmed.
	let pr;
	try {
		pr = await p.paymentRequest(card.provider_invoice_id);
	} catch (e) {
		await setStatus(card, principal, { status: 'failed', error_code: 'invoice_unreadable', error_message: 'Could not re-read the provider invoice. No funds moved.' });
		throw fromProvider(e);
	}
	const expected = BigInt(card.quote_total_atomic);
	if (pr.status !== 'unpaid' || pr.currency !== 'USDC' || pr.address !== card.pay_address || pr.total_atomic !== expected) {
		await setStatus(card, principal, { status: 'failed', error_code: 'invoice_changed', error_message: 'The provider invoice no longer matches the quote. No funds moved; request a new quote.' });
		throw new CardError(409, 'invoice_changed', 'The provider invoice no longer matches the quote you confirmed. No funds moved; request a new quote.');
	}

	const pay = await transferUsdcGuarded({
		fromAgentId: agent.id,
		fromUserId: agent.user_id,
		fromMeta: agent.meta || {},
		toAddress: card.pay_address,
		usdc: Number(card.quote_total_usdc),
		amountAtomics: expected,
		network: 'mainnet',
		category: 'card',
		destinationTrust: 'system',
		idempotencyKey: `card:${card.id}`,
		rowMeta: { card_id: card.id, provider: card.provider, product_id: card.product_id, invoice_id: card.provider_invoice_id },
	});

	if (pay.status === 'blocked') {
		await setStatus(card, principal, { status: 'failed', error_code: pay.code, error_message: pay.message });
		throw new CardError(403, pay.code, pay.message || 'The agent spend policy blocked this purchase. No funds moved.');
	}
	if (pay.status === 'failed' && pay.code === 'unconfirmed') {
		card = await setStatus(card, principal, { pay_signature: pay.signature, custody_event_id: pay.custodyEventId });
		logAudit({ userId: agent.user_id, action: 'cards.purchase_unconfirmed', resourceId: agent.id, meta: { card_id: card.id, signature: pay.signature } });
		return cardView(card);
	}
	if (pay.status !== 'paid' && pay.status !== 'replayed') {
		const message = pay.code === 'wallet_preparing'
			? 'This agent has no Solana wallet yet.'
			: `The USDC payment did not go through (${pay.code}). No card was bought.`;
		await setStatus(card, principal, { status: 'failed', error_code: pay.code, error_message: message });
		throw new CardError(502, pay.code || 'payment_failed', message);
	}

	card = await setStatus(card, principal, {
		status: 'processing', pay_signature: pay.signature, custody_event_id: pay.custodyEventId,
	}, 'paid');
	logAudit({
		userId: agent.user_id, action: 'cards.purchase', resourceId: agent.id,
		meta: { card_id: card.id, usdc: Number(card.quote_total_usdc), signature: pay.signature, provider: card.provider },
	});
	return cardView(await pollUntilSettled(card, principal));
}

// ── read ─────────────────────────────────────────────────────────────────────

async function loadCard(agentId, cardId) {
	if (typeof cardId !== 'string' || !/^[0-9a-f-]{36}$/i.test(cardId)) {
		throw new CardError(400, 'invalid_card_id', 'card id must be a UUID');
	}
	const [row] = await sql`SELECT * FROM agent_cards WHERE id = ${cardId} AND agent_id = ${agentId}`;
	if (!row) throw new CardError(404, 'card_not_found', 'No card with that id for this agent.');
	return row;
}

export async function listCards({ agentId, principal, status = null, limit = 25, cursor = null }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const lim = Math.min(100, Math.max(1, Number(limit) || 25));
	let before = null;
	if (cursor) {
		const d = new Date(String(cursor));
		if (!Number.isNaN(d.getTime())) before = d.toISOString();
	}
	const rows = await sql`
		SELECT * FROM agent_cards
		WHERE agent_id = ${agent.id}
		  AND (${status}::text IS NULL OR status = ${status})
		  AND (${before}::timestamptz IS NULL OR created_at < ${before}::timestamptz)
		  AND NOT (status IN ('expired', 'cancelled') AND created_at < now() - interval '1 day')
		ORDER BY created_at DESC
		LIMIT ${lim + 1}
	`;
	const pageRows = rows.slice(0, lim);
	// Bring in-flight cards up to date so a list read reflects delivery.
	const synced = [];
	let budget = 5;
	for (const r of pageRows) {
		const stale = OPEN_STATUSES.includes(r.status) || (r.status === 'quoted' && new Date(r.quote_expires_at) <= new Date());
		if (stale && budget > 0) {
			budget -= 1;
			try {
				synced.push(await syncCard(r, principal));
				continue;
			} catch {
				// Provider unreachable: show the stored state rather than failing the list.
			}
		}
		synced.push(r);
	}
	const [totals] = await sql`
		SELECT
			count(*) FILTER (WHERE status = 'delivered')::int AS delivered,
			COALESCE(sum(quote_total_usdc) FILTER (WHERE status IN ('delivered', 'processing') AND mode = 'live'), 0)::float8 AS spent_usdc
		FROM agent_cards WHERE agent_id = ${agent.id}
	`;
	return {
		items: synced.map(cardView),
		has_more: rows.length > lim,
		next_cursor: rows.length > lim ? new Date(pageRows[pageRows.length - 1].created_at).toISOString() : null,
		totals: { delivered: totals.delivered, spent_usdc: Number(totals.spent_usdc) },
	};
}

export async function getCard({ agentId, principal, cardId }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	const events = await sql`
		SELECT id, actor_kind, event, from_status, to_status, detail, created_at
		FROM agent_card_events
		WHERE card_id = ${row.id} AND event <> 'reveal_preview'
		ORDER BY id DESC LIMIT 30
	`;
	return { card: cardView(row), events };
}

export async function refreshCard({ agentId, principal, cardId }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	return cardView(await syncCard(row, principal));
}

export async function cardBalance({ agentId, principal, cardId }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	const p = providerFor(row.provider);
	if (p.capabilities.balance) {
		const b = await withProvider(() => p.balance({ card: row }));
		return { card_id: row.id, balance: b.balance, currency: b.currency, source: 'provider' };
	}
	const live = row.status === 'delivered';
	return {
		card_id: row.id,
		balance: live ? Number(row.face_value) : 0,
		currency: row.currency,
		source: 'face_value',
		note: live
			? `${p.label} does not report balances. A delivered gift card holds its face value until it is redeemed at ${row.merchant}.`
			: `This card is ${row.status}, so it holds no balance.`,
	};
}

// ── reveal ───────────────────────────────────────────────────────────────────

const hashGrant = (id) => createHash('sha256').update(String(id)).digest('hex');

/**
 * Card data without the secret, plus a single-use reveal grant (`preview_id`)
 * that agent_card_reveal must present with confirm_reveal: true.
 */
export async function cardData({ agentId, principal, cardId }) {
	const agent = await loadOwnedAgent(agentId, principal);
	let row = await loadCard(agent.id, cardId);
	if (row.status !== 'delivered') row = await syncCard(row, principal);
	if (row.status !== 'delivered') {
		throw new CardError(409, 'not_delivered', `This card is ${row.status}; its data is available once it is delivered.`);
	}
	const previewId = randomBytes(24).toString('base64url');
	const expiresAt = new Date(Date.now() + REVEAL_GRANT_TTL_MS);
	await recordCardEvent(row, principal, 'reveal_preview', {
		grantHash: hashGrant(previewId), grantExpiresAt: expiresAt.toISOString(),
		detail: { fields: row.secret_fields || [] },
	});
	return {
		card: cardView(row),
		fields: row.secret_fields || [],
		masked_number: row.masked_number,
		instructions: row.redeem_instructions,
		expires_on: row.expires_on,
		preview_id: previewId,
		preview_expires_at: expiresAt.toISOString(),
		next: {
			tool: 'agent_card_reveal',
			args: { agent_id: agent.id, card_id: row.id, preview_id: previewId, confirm_reveal: true },
			note: 'Revealing exposes the redemption secret. Confirm with the owner first. The preview id works once.',
		},
	};
}

export async function revealCard({ agentId, principal, cardId, previewId, confirmReveal }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	const refuse = async (code, message, status = 400) => {
		await recordCardEvent(row, principal, 'reveal_refused', { detail: { reason: code } });
		throw new CardError(status, code, message, { preview_tool: 'agent_card_data', confirm_flag: 'confirm_reveal' });
	};
	if (confirmReveal !== true) {
		await refuse('confirm_required', 'agent_card_reveal exposes the card secret. Call agent_card_data, confirm with the owner, then pass its preview_id with confirm_reveal: true.');
	}
	if (typeof previewId !== 'string' || previewId.length < 16 || previewId.length > 128) {
		await refuse('preview_required', 'preview_id from agent_card_data is required.');
	}
	if (row.status !== 'delivered') {
		await refuse('not_delivered', `This card is ${row.status}; there is nothing to reveal.`, 409);
	}
	const [grant] = await sql`
		UPDATE agent_card_events SET grant_consumed_at = now()
		WHERE grant_hash = ${hashGrant(previewId)} AND card_id = ${row.id}
		  AND grant_consumed_at IS NULL AND grant_expires_at > now()
		RETURNING id
	`;
	if (!grant) {
		await refuse('preview_invalid', 'That preview id was already used or has expired. Call agent_card_data for a new one and confirm again.', 409);
	}

	// Take the ciphertext and clear it in one statement.
	const [taken] = await sql`
		UPDATE agent_cards c SET secret_enc = NULL, revealed_at = now(), reveal_count = c.reveal_count + 1, updated_at = now()
		FROM (SELECT id, secret_enc FROM agent_cards WHERE id = ${row.id} FOR UPDATE) o
		WHERE c.id = o.id
		RETURNING o.secret_enc AS sealed, c.reveal_count
	`;
	let secret;
	let source;
	if (taken?.sealed) {
		secret = JSON.parse(await decryptSecret(taken.sealed));
		source = 'sealed';
	} else {
		const p = providerFor(row.provider);
		secret = await withProvider(() => p.reveal({ card: row }));
		source = 'provider';
	}
	const fields = Object.keys(secret || {});
	await recordCardEvent(row, principal, 'revealed', { detail: { fields, source, reveal_count: taken?.reveal_count ?? null } });
	logAudit({ userId: agent.user_id, action: 'cards.reveal', resourceId: agent.id, meta: { card_id: row.id, fields } });
	return {
		card_id: row.id,
		merchant: row.merchant,
		face_value: Number(row.face_value),
		currency: row.currency,
		secret,
		fields,
		instructions: row.redeem_instructions,
		notice: 'Shown once. three.ws no longer stores this secret; save it somewhere safe now.',
	};
}

// ── cancel / withdraw / connect ─────────────────────────────────────────────

export async function cancelCard({ agentId, principal, cardId, confirmCancel }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	if (confirmCancel !== true) {
		throw new CardError(400, 'confirm_required', 'Cancelling is irreversible. Show the card to the owner and pass confirm_cancel: true after they agree.',
			{ preview_tool: 'agent_card_get', confirm_flag: 'confirm_cancel' });
	}
	const p = providerFor(row.provider);
	await withProvider(() => p.cancel({ card: row }));
	const [updated] = await sql`
		UPDATE agent_cards SET status = 'cancelled', updated_at = now()
		WHERE id = ${row.id} AND status = 'quoted'
		RETURNING *
	`;
	if (!updated) throw new CardError(409, 'not_cancellable', 'This card can no longer be cancelled.');
	await recordCardEvent(updated, principal, 'cancelled', { from: row.status, to: 'cancelled' });
	return cardView(updated);
}

export async function withdrawCard({ agentId, principal, cardId, amount, confirmWithdraw }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	const p = providerFor(row.provider);
	if (!p.capabilities.withdraw) {
		await withProvider(() => p.withdraw({ card: row }));
	}
	if (confirmWithdraw !== true) {
		throw new CardError(400, 'confirm_required', 'Withdrawing moves the card balance. Check agent_card_balance, confirm with the owner, then pass confirm_withdraw: true.',
			{ preview_tool: 'agent_card_balance', confirm_flag: 'confirm_withdraw' });
	}
	if (row.status !== 'delivered') throw new CardError(409, 'not_delivered', 'Only a delivered card has a balance to withdraw.');
	const amt = Number(amount);
	if (!(amt > 0)) throw new CardError(400, 'invalid_amount', 'amount must be a positive number');
	const destination = agent.meta?.solana_address;
	if (!destination) throw new CardError(409, 'wallet_preparing', 'This agent has no Solana wallet to receive the withdrawal.');
	const [w] = await sql`
		INSERT INTO agent_card_withdrawals (card_id, agent_id, user_id, provider, amount, currency, destination)
		VALUES (${row.id}, ${agent.id}, ${agent.user_id}, ${row.provider}, ${amt}, ${row.currency}, ${destination})
		RETURNING *
	`;
	try {
		const r = await p.withdraw({ card: row, amount: amt, destination });
		const [done] = await sql`
			UPDATE agent_card_withdrawals SET status = ${r.status || 'processing'}, provider_ref = ${r.provider_ref || null},
				usdc_amount = ${r.usdc_amount ?? null}, signature = ${r.signature || null}, updated_at = now()
			WHERE id = ${w.id} RETURNING *
		`;
		await recordCardEvent(row, principal, 'withdraw_requested', { detail: { withdrawal_id: w.id, amount: amt } });
		return done;
	} catch (e) {
		const err = fromProvider(e);
		await sql`UPDATE agent_card_withdrawals SET status = 'failed', error_message = ${err.message}, updated_at = now() WHERE id = ${w.id}`;
		throw err;
	}
}

export async function listWithdrawals({ agentId, principal, cardId }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const row = await loadCard(agent.id, cardId);
	const items = await sql`
		SELECT id, amount, currency, usdc_amount, destination, status, signature, error_message, created_at, updated_at
		FROM agent_card_withdrawals WHERE card_id = ${row.id} ORDER BY created_at DESC LIMIT 50
	`;
	return { items, supported: Boolean(providerFor(row.provider).capabilities.withdraw) };
}

export async function connectStatus({ agentId, principal, provider }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const p = providerFor(provider);
	const c = await withProvider(() => p.connectLink({ agent }));
	return { provider: p.name, required: Boolean(c.required), status: c.status, has_link: Boolean(c.url) };
}

export async function connectLink({ agentId, principal, provider }) {
	const agent = await loadOwnedAgent(agentId, principal);
	const p = providerFor(provider);
	const c = await withProvider(() => p.connectLink({ agent }));
	if (!c.required || !c.url) {
		throw new CardError(409, 'connect_not_required', `${p.label} needs no identity steps for this account. Cards can be bought right away.`);
	}
	return { provider: p.name, url: c.url, status: c.status };
}