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.

45.2 KB
Raw Blame
// The destination whitelist: which addresses an agent wallet may send funds to.
//
// Why it exists. A stolen session or a prompt-injected agent used to be able to
// add an attacker address and drain a wallet in one minute. This module closes
// that with four rules, enforced here and nowhere else:
//
//   1. A new address is never usable at once. It serves a cooldown (default 24
//      hours, owner-configurable, never below MIN_COOLDOWN_SECONDS) and the owner
//      is notified the moment it is added, on every channel they have connected,
//      with a one-click cancel link.
//   2. Adding, approving or editing needs step-up: the owner re-authenticates
//      (password, wallet signature or an emailed code) and receives a one-time
//      grant bound to their session and to the exact operation. Only a browser
//      session can obtain one. An API key, OAuth token or agent cannot.
//   3. An agent can PROPOSE an address, never activate one. A proposal is inert
//      until the owner approves it with step-up, and then it still serves the
//      cooldown.
//   4. Anything that makes the wallet safer is instant and needs no step-up:
//      removing an address, cancelling a pending one, lengthening the cooldown.
//      Anything that loosens protection (a shorter cooldown, enforcement off) is
//      itself parked for one full current cooldown before it takes effect.
//
// Addresses are compared by a canonical key (see normalizeDestination), never by
// the string a caller typed, so casing tricks, padding, zero-width characters
// and Unicode lookalikes can neither match a listed address nor smuggle in a
// second spelling of one.
//
// The guards (api/_lib/agent-trade-guards.js, api/_lib/evm-leg/guards.js) call
// evaluateDestination() for every outbound category. Doc: docs/destination-whitelist.md.

import { createHash, createHmac, randomInt, timingSafeEqual } from 'node:crypto';
import bs58 from 'bs58';
import { getAddress, isAddress } from 'viem';

import { sql } from './db.js';
import { env } from './env.js';
import { logAudit } from './audit.js';

export const MIN_COOLDOWN_SECONDS = 3600;
export const DEFAULT_COOLDOWN_SECONDS = 24 * 3600;
export const MAX_COOLDOWN_SECONDS = 30 * 24 * 3600;
export const MAX_ENTRIES = 50;
export const MAX_LABEL_LENGTH = 60;
export const STEP_UP_TTL_MS = 5 * 60 * 1000;
export const EMAIL_CODE_TTL_MS = 10 * 60 * 1000;
export const STEP_UP_METHODS = Object.freeze(['password', 'wallet', 'email_code']);

/**
 * Categories that are not a send to a third party. A swap or snipe lands in the
 * agent's own wallet, and an x402 payment goes to whatever service the agent was
 * asked to call, which is not a destination an owner can list in advance (it is
 * bounded by the spend caps and the per-service policy instead). Everything else
 * that moves funds out (withdraw, transfer, tip, bridge, order and invoice
 * payouts, card withdrawals, signals, intents) is checked.
 */
export const EXEMPT_CATEGORIES = Object.freeze(new Set(['trade', 'snipe', 'x402']));

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

// ── address normalisation ──────────────────────────────────────────────────────

const PRINTABLE_ASCII = /^[\x21-\x7e]+$/;
const BASE58_ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;

/**
 * Parse an address into its canonical form.
 *
 * Only printable ASCII is accepted, after trimming surrounding whitespace, so a
 * zero-width space, a Cyrillic "а", a full-width digit or an embedded newline is
 * rejected outright instead of being quietly stripped into a different string.
 * Solana addresses are case-sensitive base58 that must decode to 32 bytes: a
 * differently cased string is a different address and never matches. EVM
 * addresses compare case-insensitively, and a mixed-case spelling must carry a
 * valid EIP-55 checksum, so a mistyped checksum is refused rather than guessed.
 *
 * @returns {{ chain: 'solana'|'evm', address: string, key: string } | null}
 */
export function normalizeDestination(input) {
	if (typeof input !== 'string') return null;
	const s = input.trim();
	if (!s || s.length > 64 || !PRINTABLE_ASCII.test(s)) return null;

	if (s.startsWith('0x')) {
		if (!EVM_ADDRESS.test(s)) return null;
		const hex = s.slice(2);
		const mixed = /[a-f]/.test(hex) && /[A-F]/.test(hex);
		if (mixed && !isAddress(s, { strict: true })) return null;
		const address = getAddress(s);
		return { chain: 'evm', address, key: address.toLowerCase() };
	}

	if (!BASE58_ADDRESS.test(s)) return null;
	try {
		if (bs58.decode(s).length !== 32) return null;
	} catch {
		return null;
	}
	return { chain: 'solana', address: s, key: s };
}

/** True when two spellings name the same destination. */
export function sameDestination(a, b) {
	const x = normalizeDestination(a);
	const y = normalizeDestination(b);
	return !!x && !!y && x.chain === y.chain && x.key === y.key;
}

/**
 * Address-poisoning check: an attacker plants an address that shares its first
 * and last characters with one the owner already uses, hoping a glance matches.
 * @returns {object|null} the existing entry the new address imitates
 */
export function findLookalike(entries, norm) {
	const head = norm.chain === 'evm' ? 6 : 4;
	const tail = 4;
	const k = norm.key;
	for (const e of entries) {
		if (e.chain !== norm.chain || e.address_key === k) continue;
		if (e.status === 'cancelled' || e.status === 'removed') continue;
		const o = e.address_key;
		if (o.slice(0, head) === k.slice(0, head) && o.slice(-tail) === k.slice(-tail)) return e;
	}
	return null;
}

export function shortAddress(address) {
	const s = String(address || '');
	return s.length > 14 ? `${s.slice(0, 6)}...${s.slice(-6)}` : s;
}

const INVISIBLE_OR_CONTROL = new RegExp(
	'[' + [
		'\\u0000-\\u001f', '\\u007f-\\u009f', '\\u200b-\\u200f',
		'\\u2028-\\u202e', '\\u2060-\\u206f', '\\ufeff',
	].join('') + ']',
	'g',
);

/** Plain text only: control characters, markup and links are removed, not escaped. */
export function sanitizeLabel(value) {
	if (value == null) return null;
	if (typeof value !== 'string') throw new WhitelistError(400, 'invalid_label', 'label must be a string');
	const clean = value
		.normalize('NFKC')
		.replace(INVISIBLE_OR_CONTROL, ' ')
		.replace(/[<>`]/g, '')
		.replace(/\bhttps?:\/\/\S+/gi, '')
		.replace(/\s+/g, ' ')
		.trim()
		.slice(0, MAX_LABEL_LENGTH);
	return clean || null;
}

function sanitizeCap(value, field) {
	if (value == null || value === '') return null;
	const n = Number(value);
	if (!Number.isFinite(n) || n <= 0 || n > 1e9) {
		throw new WhitelistError(400, 'invalid_cap', `${field} must be a positive number of USD`);
	}
	return Math.round(n * 100) / 100;
}

// ── settings ───────────────────────────────────────────────────────────────────

function settingsView(row) {
	return {
		cooldown_seconds: row?.cooldown_seconds ?? DEFAULT_COOLDOWN_SECONDS,
		enforced: row?.enforced === true,
		configured: !!row,
		pending_change: row?.pending_change || null,
		updated_at: row?.updated_at || null,
	};
}

/** Apply a parked loosening change once its time has come. */
async function applyDueSettingsChange(row) {
	const ch = row?.pending_change;
	if (!ch || !ch.effective_at || new Date(ch.effective_at).getTime() > Date.now()) return row;
	const [next] = await sql`
		UPDATE destination_whitelist_settings
		SET cooldown_seconds = ${ch.cooldown_seconds ?? row.cooldown_seconds},
		    enforced = ${ch.enforced ?? row.enforced},
		    pending_change = NULL, updated_at = now()
		WHERE agent_id = ${row.agent_id} AND pending_change = ${JSON.stringify(ch)}::jsonb
		RETURNING *`;
	return next || row;
}

export async function getSettings(agentId) {
	const [row] = await sql`SELECT * FROM destination_whitelist_settings WHERE agent_id = ${agentId}`;
	return settingsView(await applyDueSettingsChange(row));
}

// ── step-up ────────────────────────────────────────────────────────────────────

function stableStringify(v) {
	if (v === null || typeof v !== 'object') return JSON.stringify(v);
	if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
	return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
}

export function hashOp(op) {
	return createHash('sha256').update(stableStringify(op)).digest('hex');
}

/**
 * The canonical form of a whitelist operation, built from the raw request body.
 * Both the step-up endpoint and the operation endpoint build it the same way, so
 * a grant minted for one operation cannot authorise any other.
 */
export function buildOp(kind, agentId, body = {}) {
	switch (kind) {
		case 'add': {
			const norm = normalizeDestination(body.address);
			if (!norm) throw new WhitelistError(400, 'invalid_address', 'That is not a valid Solana or EVM address.');
			return {
				t: 'add', a: agentId, c: norm.chain, k: norm.key,
				l: sanitizeLabel(body.label), p: sanitizeCap(body.per_tx_cap_usd, 'per_tx_cap_usd'), d: sanitizeCap(body.daily_cap_usd, 'daily_cap_usd'),
			};
		}
		case 'approve':
			return { t: 'approve', a: agentId, id: String(body.id || '') };
		case 'edit':
			return {
				t: 'edit', a: agentId, id: String(body.id || ''),
				l: 'label' in body ? sanitizeLabel(body.label) : undefined,
				p: 'per_tx_cap_usd' in body ? sanitizeCap(body.per_tx_cap_usd, 'per_tx_cap_usd') : undefined,
				d: 'daily_cap_usd' in body ? sanitizeCap(body.daily_cap_usd, 'daily_cap_usd') : undefined,
			};
		case 'settings':
			return {
				t: 'settings', a: agentId,
				cs: 'cooldown_seconds' in body ? Number(body.cooldown_seconds) : undefined,
				en: 'enforced' in body ? body.enforced === true : undefined,
			};
		case 'payout_wallet': {
			// Creator-fee payout destination (api/_lib/creator-payouts.js): the grant is
			// bound to this agent and this exact wallet.
			const norm = normalizeDestination(body.wallet);
			if (!norm || norm.chain !== 'solana') throw new WhitelistError(400, 'invalid_address', 'That is not a valid Solana address.');
			return { t: 'payout_wallet', a: agentId, w: norm.key };
		}
		case 'set_list': {
			const list = Array.isArray(body.withdraw_allowlist) ? body.withdraw_allowlist : [];
			const keys = list.map((x) => {
				const n = normalizeDestination(x);
				if (!n) throw new WhitelistError(400, 'invalid_address', 'withdraw_allowlist holds an invalid address.');
				return `${n.chain}:${n.key}`;
			});
			return { t: 'set_list', a: agentId, keys: [...new Set(keys)].sort() };
		}
		default:
			throw new WhitelistError(400, 'invalid_operation', 'Unknown whitelist operation.');
	}
}

export function stepUpMessage({ opHash, sessionId, expiresAt }) {
	return `three.ws step-up\nApprove allowlist change ${opHash}\nSession ${sessionId}\nValid until ${expiresAt}`;
}

const codeHash = (code, opHash, sessionId) =>
	createHmac('sha256', env.JWT_SECRET).update(`whitelist-code:${opHash}:${sessionId}:${code}`).digest('hex');

function requireBrowserSession(actor) {
	if (!actor?.sessionId || actor.kind !== 'owner') {
		throw new WhitelistError(403, 'session_required', 'This needs the owner signed in to the three.ws site. API keys, OAuth tokens and agents cannot do it.');
	}
}

async function mintGrant({ actor, agentId, opHash, method }) {
	const [row] = await sql`
		INSERT INTO destination_stepup_grants (user_id, session_id, agent_id, op_hash, method, expires_at)
		VALUES (${actor.userId}, ${actor.sessionId}, ${agentId}, ${opHash}, ${method}, now() + ${STEP_UP_TTL_MS / 1000} * interval '1 second')
		RETURNING id, expires_at`;
	return { grant: row.id, expires_at: row.expires_at, method };
}

/** Email a six-digit code that proves the owner holds the account's inbox. */
export async function sendStepUpCode({ actor, agentId, op }) {
	requireBrowserSession(actor);
	const opHash = hashOp(op);
	const [user] = await sql`SELECT email FROM users WHERE id = ${actor.userId}`;
	if (!user?.email) throw new WhitelistError(409, 'no_email', 'This account has no email address to send a code to. Use your password or wallet instead.');
	const [recent] = await sql`
		SELECT count(*)::int AS n FROM destination_stepup_codes
		WHERE user_id = ${actor.userId} AND created_at > now() - interval '10 minutes'`;
	if (recent.n >= 5) throw new WhitelistError(429, 'too_many_codes', 'Too many codes requested. Wait a few minutes and try again.');
	const code = String(randomInt(0, 1_000_000)).padStart(6, '0');
	await sql`
		INSERT INTO destination_stepup_codes (user_id, session_id, op_hash, code_hash, expires_at)
		VALUES (${actor.userId}, ${actor.sessionId}, ${opHash}, ${codeHash(code, opHash, actor.sessionId)}, now() + ${EMAIL_CODE_TTL_MS / 1000} * interval '1 second')`;
	const { sendEmail, renderStepUpCode } = await import('./email.js');
	const sent = await sendEmail({ to: user.email, ...renderStepUpCode({ code, expiresInMinutes: EMAIL_CODE_TTL_MS / 60000, agentId }) });
	if (sent?.skipped) throw new WhitelistError(503, 'email_unavailable', 'Email is not configured on this server. Use your password or wallet instead.');
	return { sent: true, expires_in_seconds: EMAIL_CODE_TTL_MS / 1000 };
}

/**
 * Re-authenticate the owner and mint a one-time grant for exactly one operation.
 * @param {{ actor: object, agentId: string, op: object, method: string, proof: object }} o
 */
export async function mintStepUp({ actor, agentId, op, method, proof = {} }) {
	requireBrowserSession(actor);
	if (!STEP_UP_METHODS.includes(method)) throw new WhitelistError(400, 'invalid_method', `method must be one of ${STEP_UP_METHODS.join(', ')}`);
	const opHash = hashOp(op);

	if (method === 'password') {
		const { verifyPassword } = await import('./auth.js');
		const [u] = await sql`SELECT password_hash FROM users WHERE id = ${actor.userId}`;
		if (!u?.password_hash) throw new WhitelistError(409, 'no_password', 'This account has no password. Use your wallet or an emailed code instead.');
		if (typeof proof.password !== 'string' || !(await verifyPassword(proof.password, u.password_hash))) {
			throw new WhitelistError(401, 'step_up_failed', 'That password is not correct.');
		}
	} else if (method === 'wallet') {
		const [u] = await sql`SELECT wallet_address FROM users WHERE id = ${actor.userId}`;
		if (!u?.wallet_address) throw new WhitelistError(409, 'no_wallet', 'No wallet is linked to this account. Use your password or an emailed code instead.');
		const { verifySiwsSignature } = await import('./siws.js');
		const message = String(proof.message || '');
		const m = /^three\.ws step-up\nApprove allowlist change ([0-9a-f]{64})\nSession (\S+)\nValid until (\S+)$/.exec(message);
		const until = m ? Date.parse(m[3]) : NaN;
		if (!m || m[1] !== opHash || m[2] !== String(actor.sessionId) || !(until > Date.now()) || until > Date.now() + 15 * 60 * 1000) {
			throw new WhitelistError(401, 'step_up_failed', 'That signed message is not for this change, or it has expired.');
		}
		let valid = false;
		try {
			valid = verifySiwsSignature(message, String(proof.signature || ''), u.wallet_address);
		} catch {
			valid = false;
		}
		if (!valid) throw new WhitelistError(401, 'step_up_failed', 'That signature was not made by your linked wallet.');
	} else {
		const code = String(proof.code || '').trim();
		if (!/^\d{6}$/.test(code)) throw new WhitelistError(400, 'invalid_code', 'Enter the six-digit code from the email.');
		const [row] = await sql`
			SELECT id, code_hash, attempts FROM destination_stepup_codes
			WHERE user_id = ${actor.userId} AND session_id = ${actor.sessionId} AND op_hash = ${opHash}
			  AND used_at IS NULL AND expires_at > now() AND attempts < 5
			ORDER BY created_at DESC LIMIT 1`;
		if (!row) throw new WhitelistError(401, 'step_up_failed', 'No valid code for this change. Request a new one.');
		const expected = Buffer.from(row.code_hash, 'hex');
		const got = Buffer.from(codeHash(code, opHash, actor.sessionId), 'hex');
		if (expected.length !== got.length || !timingSafeEqual(expected, got)) {
			await sql`UPDATE destination_stepup_codes SET attempts = attempts + 1 WHERE id = ${row.id}`;
			throw new WhitelistError(401, 'step_up_failed', 'That code is not correct.');
		}
		const [used] = await sql`UPDATE destination_stepup_codes SET used_at = now() WHERE id = ${row.id} AND used_at IS NULL RETURNING id`;
		if (!used) throw new WhitelistError(401, 'step_up_failed', 'That code was already used.');
	}

	return { ...(await mintGrant({ actor, agentId, opHash, method })), op_hash: opHash };
}

/** Spend a grant. One use, this session, this user, this agent, this exact operation. */
export async function consumeGrant({ grantId, actor, agentId, op }) {
	const opHash = hashOp(op);
	if (typeof grantId === 'string' && /^[0-9a-f-]{36}$/i.test(grantId) && actor?.sessionId) {
		const [row] = await sql`
			UPDATE destination_stepup_grants SET used_at = now()
			WHERE id = ${grantId} AND user_id = ${actor.userId} AND session_id = ${actor.sessionId}
			  AND agent_id = ${agentId} AND op_hash = ${opHash}
			  AND used_at IS NULL AND expires_at > now()
			RETURNING method`;
		if (row) return row.method;
	}
	throw new WhitelistError(403, 'step_up_required', 'Confirm this change by re-entering your password, signing with your wallet, or entering an emailed code.', {
		op, op_hash: opHash, methods: STEP_UP_METHODS,
	});
}

// ── agents and entries ─────────────────────────────────────────────────────────

async function loadAgent(agentId, userId) {
	if (!/^[0-9a-f-]{36}$/i.test(String(agentId || ''))) throw new WhitelistError(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 WhitelistError(404, 'agent_not_found', 'Agent not found.');
	if (agent.user_id !== userId) throw new WhitelistError(403, 'forbidden', 'Only the owner of this agent can manage its allowlist.');
	return agent;
}

function ownAddresses(meta) {
	return [meta?.solana_address, meta?.evm_address, meta?.evm?.address].filter(Boolean);
}

export function entryView(row, now = Date.now()) {
	if (!row) return null;
	const activatesMs = row.activates_at ? new Date(row.activates_at).getTime() : null;
	const usable = (row.status === 'active' || row.status === 'pending') && activatesMs != null && activatesMs <= now;
	return {
		id: row.id,
		agent_id: row.agent_id,
		chain: row.chain,
		address: row.address,
		label: row.label,
		per_tx_cap_usd: row.per_tx_cap_usd != null ? Number(row.per_tx_cap_usd) : null,
		daily_cap_usd: row.daily_cap_usd != null ? Number(row.daily_cap_usd) : null,
		status: usable && row.status === 'pending' ? 'active' : row.status,
		usable,
		proposed_by: row.proposed_by,
		created_at: row.created_at,
		activates_at: row.activates_at,
		seconds_until_active: !usable && row.status === 'pending' && activatesMs ? Math.max(0, Math.ceil((activatesMs - now) / 1000)) : 0,
	};
}

const LIVE = ['proposed', 'pending', 'active'];

async function liveEntries(agentId) {
	return sql`SELECT * FROM destination_whitelist_entries WHERE agent_id = ${agentId} AND status = ANY(${LIVE}) ORDER BY created_at`;
}

/** Everything the owner or an agent needs to see about an agent's allowlist. */
export async function getWhitelist(agentId, userId, { history = false } = {}) {
	await loadAgent(agentId, userId);
	await activateDue(agentId);
	const [settings, rows] = await Promise.all([
		getSettings(agentId),
		history
			? sql`SELECT * FROM destination_whitelist_entries WHERE agent_id = ${agentId} ORDER BY created_at DESC LIMIT 200`
			: liveEntries(agentId),
	]);
	const entries = rows.map((r) => entryView(r));
	return {
		agent_id: agentId,
		enforced: settings.enforced,
		settings,
		min_cooldown_seconds: MIN_COOLDOWN_SECONDS,
		max_entries: MAX_ENTRIES,
		entries,
		counts: {
			active: entries.filter((e) => e.status === 'active').length,
			pending: entries.filter((e) => e.status === 'pending').length,
			proposed: entries.filter((e) => e.status === 'proposed').length,
		},
	};
}

// ── notifications ──────────────────────────────────────────────────────────────

const APP_ORIGIN = () => process.env.APP_ORIGIN || 'https://three.ws';

function cancelSignature(body) {
	return createHmac('sha256', env.JWT_SECRET).update(`whitelist-cancel:${body}`).digest('base64url');
}

/** A link that cancels one pending or proposed entry, usable without signing in. */
export function signCancelToken({ entryId, userId, expiresAt }) {
	const exp = Math.floor(new Date(expiresAt).getTime() / 1000);
	const body = Buffer.from(JSON.stringify({ i: entryId, u: String(userId), e: exp }), 'utf8').toString('base64url');
	return `w1.${body}.${cancelSignature(body)}`;
}

export function verifyCancelToken(token, now = Date.now()) {
	if (typeof token !== 'string' || !token.startsWith('w1.')) return null;
	const parts = token.split('.');
	if (parts.length !== 3 || !parts[1] || !parts[2]) return null;
	const a = Buffer.from(cancelSignature(parts[1]), 'utf8');
	const b = Buffer.from(parts[2], 'utf8');
	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
	try {
		const c = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
		if (!c.i || !c.u || !Number.isFinite(c.e) || c.e * 1000 <= now) return null;
		return { entryId: c.i, userId: c.u };
	} catch {
		return null;
	}
}

export function cancelUrl(entry, userId) {
	const expiresAt = new Date(Math.max(Date.now(), new Date(entry.activates_at || Date.now()).getTime()) + 14 * 24 * 3600 * 1000);
	return `${APP_ORIGIN()}/api/wallet-whitelist?cancel=${signCancelToken({ entryId: entry.id, userId, expiresAt })}`;
}

const HEADLINES = {
	whitelist_proposed: 'An agent proposed a new destination',
	whitelist_pending: 'New destination added: cooling down',
	whitelist_active: 'A destination is now active',
	whitelist_cancelled: 'A pending destination was cancelled',
	whitelist_removed: 'A destination was removed',
	whitelist_edited: 'A destination was edited',
	whitelist_settings: 'Allowlist protection changed',
};
export const WHITELIST_NOTIFICATION_TYPES = Object.freeze(Object.keys(HEADLINES));

/**
 * Tell the owner on every channel they have connected (in-app, push, Telegram,
 * Discord; the notification preference matrix does not mute these, see
 * ALWAYS_NOTIFY_TYPES in notify-prefs.js) and by email. Never throws: the change
 * has already happened, and a delivery problem must not undo or hide it.
 */
export async function notifyOwner({ userId, agent, type, entry = null, detail = '', withCancel = false }) {
	try {
		const { insertNotification } = await import('./notify.js');
		const target = entry ? `${entry.label ? `"${entry.label}" ` : ''}${shortAddress(entry.address)}` : '';
		const message = [HEADLINES[type], target, detail].filter(Boolean).join(': ');
		const link = `/agent-wallet?agent=${encodeURIComponent(agent.id)}&tab=whitelist`;
		const cancel = withCancel && entry ? cancelUrl(entry, userId) : null;
		await insertNotification(userId, type, {
			agent_id: agent.id,
			agent_name: agent.name || null,
			entry_id: entry?.id || null,
			message,
			link,
			cancel_url: cancel,
			activates_at: entry?.activates_at || null,
		});
		const [u] = await sql`SELECT email FROM users WHERE id = ${userId}`;
		if (u?.email) {
			const { sendEmail, renderWhitelistNotice } = await import('./email.js');
			await sendEmail({
				to: u.email,
				...renderWhitelistNotice({
					headline: HEADLINES[type], agentName: agent.name, entry, detail, cancelUrl: cancel, link: `${APP_ORIGIN()}${link}`,
				}),
			}).catch((e) => console.warn('[whitelist] email failed', e?.message));
		}
	} catch (e) {
		console.warn('[whitelist] notify failed', e?.message);
	}
}

async function record(agent, userId, reason, entry, extra = {}, req = null) {
	const { recordCustodyEvent } = await import('./agent-trade-guards.js');
	await recordCustodyEvent({
		agentId: agent.id, userId, eventType: 'limit_change', reason,
		destination: entry?.address || null, meta: { entry_id: entry?.id || null, label: entry?.label || null, ...extra },
	}).catch((e) => console.warn('[whitelist] custody record failed', e?.message));
	logAudit({ userId, action: `custody.${reason}`, resourceId: agent.id, meta: { entry_id: entry?.id || null, address: entry?.address || null, ...extra }, req });
}

// ── lifecycle ──────────────────────────────────────────────────────────────────

async function ownerCooldownSeconds(agentId) {
	return (await getSettings(agentId)).cooldown_seconds;
}

/**
 * Add an address. `skipGrant` is for callers inside this module that already
 * consumed a grant covering the whole operation (replaceSolanaList).
 *
 * An owner browser session with a valid step-up grant creates a PENDING entry
 * that activates after the cooldown. Any other principal (an agent over MCP, an
 * API key, an OAuth token, a session without a grant) can only create a
 * PROPOSED entry, which is inert until the owner approves it with step-up. A
 * grant is only ever required of a session; a machine principal is never asked
 * for one because it could never satisfy it.
 */
export async function addEntry({ agentId, actor, body, grantId = null, skipGrant = false, req = null }) {
	const agent = await loadAgent(agentId, actor.userId);
	const op = buildOp('add', agentId, body);
	const norm = normalizeDestination(body.address);
	if (ownAddresses(agent.meta).some((a) => sameDestination(a, norm.address))) {
		throw new WhitelistError(400, 'own_wallet', 'That is this agent\'s own wallet. It is always allowed and does not need a place on the list.');
	}

	const live = await liveEntries(agentId);
	if (live.length >= MAX_ENTRIES) throw new WhitelistError(409, 'list_full', `An agent can have at most ${MAX_ENTRIES} allowlist entries.`);
	const dup = live.find((e) => e.chain === norm.chain && e.address_key === norm.key);
	if (dup) throw new WhitelistError(409, 'already_listed', 'That address is already on the list.', { entry: entryView(dup) });
	const lookalike = findLookalike(live, norm);

	const owner = actor.kind === 'owner';
	if (owner && !skipGrant) await consumeGrant({ grantId, actor, agentId, op });

	const cooldown = await ownerCooldownSeconds(agentId);
	const status = owner ? 'pending' : 'proposed';
	let row;
	try {
		[row] = await sql`
			INSERT INTO destination_whitelist_entries
				(agent_id, user_id, chain, address, address_key, label, per_tx_cap_usd, daily_cap_usd,
				 status, proposed_by, approved_at, activates_at)
			VALUES (${agentId}, ${agent.user_id}, ${norm.chain}, ${norm.address}, ${norm.key}, ${op.l}, ${op.p}, ${op.d},
				${status}, ${owner ? 'owner' : String(actor.kind || 'agent')},
				${owner ? sql`now()` : null},
				${owner ? sql`now() + ${cooldown} * interval '1 second'` : null})
			RETURNING *`;
	} catch (e) {
		if (e?.code === '23505') throw new WhitelistError(409, 'already_listed', 'That address is already on the list.');
		throw e;
	}

	await record(agent, actor.userId, owner ? 'whitelist_add' : 'whitelist_propose', row, { status, lookalike_of: lookalike?.id || null }, req);
	await notifyOwner({
		userId: agent.user_id, agent, entry: row,
		type: owner ? 'whitelist_pending' : 'whitelist_proposed',
		detail: owner
			? `usable in ${Math.round(cooldown / 3600)}h unless you cancel it`
			: 'it cannot receive funds until you approve it',
		withCancel: true,
	});
	return { entry: entryView(row), cooldown_seconds: owner ? cooldown : null, lookalike_of: lookalike ? entryView(lookalike) : null };
}

/** Owner approves a proposal. Starts the cooldown; the address is still not usable yet. */
export async function approveEntry({ agentId, entryId, actor, grantId, req = null }) {
	requireBrowserSession(actor);
	const agent = await loadAgent(agentId, actor.userId);
	const op = buildOp('approve', agentId, { id: entryId });
	const [cur] = await sql`SELECT * FROM destination_whitelist_entries WHERE id = ${entryId} AND agent_id = ${agentId}`;
	if (!cur) throw new WhitelistError(404, 'entry_not_found', 'No such allowlist entry.');
	if (cur.status !== 'proposed') throw new WhitelistError(409, 'not_proposed', 'Only a proposed address can be approved.', { status: cur.status });
	await consumeGrant({ grantId, actor, agentId, op });
	const cooldown = await ownerCooldownSeconds(agentId);
	const [row] = await sql`
		UPDATE destination_whitelist_entries
		SET status = 'pending', approved_at = now(), activates_at = now() + ${cooldown} * interval '1 second', updated_at = now()
		WHERE id = ${entryId} AND status = 'proposed' RETURNING *`;
	if (!row) throw new WhitelistError(409, 'not_proposed', 'That proposal changed. Reload and try again.');
	await record(agent, actor.userId, 'whitelist_approve', row, {}, req);
	await notifyOwner({ userId: agent.user_id, agent, entry: row, type: 'whitelist_pending', detail: `usable in ${Math.round(cooldown / 3600)}h unless you cancel it`, withCancel: true });
	return { entry: entryView(row), cooldown_seconds: cooldown };
}

/** Edit a label or the per-destination caps. The address and the status cannot be edited. */
export async function editEntry({ agentId, entryId, actor, body, grantId, req = null }) {
	requireBrowserSession(actor);
	const agent = await loadAgent(agentId, actor.userId);
	const op = buildOp('edit', agentId, { ...body, id: entryId });
	const [cur] = await sql`SELECT * FROM destination_whitelist_entries WHERE id = ${entryId} AND agent_id = ${agentId}`;
	if (!cur || !LIVE.includes(cur.status)) throw new WhitelistError(404, 'entry_not_found', 'No such allowlist entry.');
	await consumeGrant({ grantId, actor, agentId, op });
	const [row] = await sql`
		UPDATE destination_whitelist_entries
		SET label = ${op.l !== undefined ? op.l : cur.label},
		    per_tx_cap_usd = ${op.p !== undefined ? op.p : cur.per_tx_cap_usd},
		    daily_cap_usd = ${op.d !== undefined ? op.d : cur.daily_cap_usd},
		    updated_at = now()
		WHERE id = ${entryId} AND status = ANY(${LIVE}) RETURNING *`;
	if (!row) throw new WhitelistError(409, 'entry_changed', 'That entry changed. Reload and try again.');
	await record(agent, actor.userId, 'whitelist_edit', row, { before: { label: cur.label, per_tx_cap_usd: cur.per_tx_cap_usd, daily_cap_usd: cur.daily_cap_usd } }, req);
	await notifyOwner({ userId: agent.user_id, agent, entry: row, type: 'whitelist_edited' });
	return { entry: entryView(row) };
}

/** Cancel a pending or proposed entry. One click, no step-up: it only removes access. */
export async function cancelEntry({ entryId, userId, via = 'web', req = null }) {
	const [cur] = await sql`SELECT * FROM destination_whitelist_entries WHERE id = ${entryId} AND user_id = ${userId}`;
	if (!cur) throw new WhitelistError(404, 'entry_not_found', 'No such allowlist entry.');
	const agent = await loadAgent(cur.agent_id, userId);
	const [row] = await sql`
		UPDATE destination_whitelist_entries SET status = 'cancelled', cancelled_at = now(), updated_at = now()
		WHERE id = ${entryId} AND status IN ('pending', 'proposed') RETURNING *`;
	if (!row) {
		if (cur.status === 'cancelled') return { entry: entryView(cur), already: true };
		throw new WhitelistError(409, 'not_cancellable', cur.status === 'active' ? 'That address is already active. Remove it instead.' : 'That entry can no longer be cancelled.', { status: cur.status });
	}
	await record(agent, userId, 'whitelist_cancel', row, { via }, req);
	await notifyOwner({ userId, agent, entry: row, type: 'whitelist_cancelled' });
	return { entry: entryView(row) };
}

/** Remove an entry. Instant, for any principal that owns the agent. */
export async function removeEntry({ agentId, entryId, actor, req = null }) {
	const agent = await loadAgent(agentId, actor.userId);
	const [row] = await sql`
		UPDATE destination_whitelist_entries SET status = 'removed', removed_at = now(), updated_at = now()
		WHERE id = ${entryId} AND agent_id = ${agentId} AND status IN ('proposed', 'pending', 'active') RETURNING *`;
	if (!row) throw new WhitelistError(404, 'entry_not_found', 'No such allowlist entry, or it was already removed.');
	await record(agent, actor.userId, 'whitelist_remove', row, { via: actor.kind }, req);
	await notifyOwner({ userId: agent.user_id, agent, entry: row, type: 'whitelist_removed' });
	return { entry: entryView(row) };
}

/**
 * Change the cooldown or the enforcement switch.
 * Safer settings apply now. Looser ones (a shorter cooldown, enforcement off)
 * need step-up and are parked for one full current cooldown, so a stolen session
 * cannot shorten the cooldown and add an address in the same minute.
 */
export async function updateSettings({ agentId, actor, body, grantId = null, skipGrant = false, req = null }) {
	requireBrowserSession(actor);
	const agent = await loadAgent(agentId, actor.userId);
	const op = buildOp('settings', agentId, body);
	const cur = await getSettings(agentId);

	if (body.cancel_pending_change === true) {
		await sql`UPDATE destination_whitelist_settings SET pending_change = NULL, updated_at = now() WHERE agent_id = ${agentId}`;
		await record(agent, actor.userId, 'whitelist_settings_cancel', null, {}, req);
		return { settings: await getSettings(agentId) };
	}

	let cooldown = cur.cooldown_seconds;
	if (op.cs !== undefined) {
		if (!Number.isInteger(op.cs) || op.cs < MIN_COOLDOWN_SECONDS) {
			throw new WhitelistError(400, 'cooldown_too_short', `The cooldown cannot be shorter than ${MIN_COOLDOWN_SECONDS / 3600} hour.`);
		}
		if (op.cs > MAX_COOLDOWN_SECONDS) throw new WhitelistError(400, 'cooldown_too_long', `The cooldown cannot be longer than ${MAX_COOLDOWN_SECONDS / 86400} days.`);
		cooldown = op.cs;
	}
	let enforced = cur.enforced;
	if (op.en !== undefined) enforced = op.en;
	if (op.cs === undefined && op.en === undefined) throw new WhitelistError(400, 'nothing_to_change', 'Send cooldown_seconds, enforced or cancel_pending_change.');

	const loosensCooldown = cooldown < cur.cooldown_seconds;
	const loosensEnforce = cur.enforced && !enforced;
	if (enforced && !cur.enforced) {
		const [active] = await sql`SELECT count(*)::int AS n FROM destination_whitelist_entries WHERE agent_id = ${agentId} AND status IN ('pending', 'active') AND activates_at <= now()`;
		if (!active.n) throw new WhitelistError(409, 'nothing_to_enforce', 'Add an address and wait for its cooldown before turning enforcement on, or every send would be refused.');
	}
	if ((loosensCooldown || loosensEnforce) && !skipGrant) await consumeGrant({ grantId, actor, agentId, op });

	const park = {};
	if (loosensCooldown) { park.cooldown_seconds = cooldown; cooldown = cur.cooldown_seconds; }
	if (loosensEnforce) { park.enforced = false; enforced = cur.enforced; }
	const pending = Object.keys(park).length
		? { ...park, requested_at: new Date().toISOString(), effective_at: new Date(Date.now() + cur.cooldown_seconds * 1000).toISOString() }
		: cur.pending_change;

	await sql`
		INSERT INTO destination_whitelist_settings (agent_id, user_id, cooldown_seconds, enforced, pending_change)
		VALUES (${agentId}, ${agent.user_id}, ${cooldown}, ${enforced}, ${pending ? JSON.stringify(pending) : null}::jsonb)
		ON CONFLICT (agent_id) DO UPDATE
		SET cooldown_seconds = EXCLUDED.cooldown_seconds, enforced = EXCLUDED.enforced,
		    pending_change = EXCLUDED.pending_change, updated_at = now()`;

	await record(agent, actor.userId, 'whitelist_settings', null, { cooldown_seconds: cooldown, enforced, parked: park }, req);
	await notifyOwner({
		userId: agent.user_id, agent, type: 'whitelist_settings',
		detail: Object.keys(park).length
			? `a looser setting takes effect at ${pending.effective_at}; you can cancel it until then`
			: `cooldown ${Math.round(cooldown / 3600)}h, enforcement ${enforced ? 'on' : 'off'}`,
	});
	return { settings: await getSettings(agentId), parked: Object.keys(park).length > 0 };
}

/**
 * The legacy whole-list write (PUT /api/agents/:id/solana-wallet, field
 * withdraw_allowlist). It keeps working, under the same rules: addresses missing
 * from the new list are removed at once; addresses new to it become pending
 * entries that serve the cooldown and need step-up; and a list that would be
 * empty never switches enforcement off early (that is parked like any loosening).
 */
export async function replaceSolanaList(args) {
	return replaceList({ ...args, chain: 'solana' });
}

/** The whole-list write for one chain. Same rules for Solana and EVM. */
export async function replaceList({ agentId, actor, list, chain = 'solana', grantId = null, req = null }) {
	requireBrowserSession(actor);
	const agent = await loadAgent(agentId, actor.userId);
	const op = buildOp('set_list', agentId, { withdraw_allowlist: list });
	const wanted = new Map();
	for (const item of list) {
		const n = normalizeDestination(item);
		if (!n || n.chain !== chain) throw new WhitelistError(400, 'invalid_address', `The list holds an address that is not a valid ${chain === 'evm' ? 'EVM' : 'Solana'} address.`);
		wanted.set(n.key, n);
	}
	if (wanted.size > MAX_ENTRIES) throw new WhitelistError(400, 'list_full', `An allowlist holds at most ${MAX_ENTRIES} addresses.`);

	const live = (await liveEntries(agentId)).filter((e) => e.chain === chain);
	const byKey = new Map(live.map((e) => [e.address_key, e]));
	const toRemove = live.filter((e) => !wanted.has(e.address_key));
	const toAdd = [...wanted.values()].filter((n) => !byKey.has(n.key));
	const toApprove = live.filter((e) => e.status === 'proposed' && wanted.has(e.address_key));

	if (toAdd.length || toApprove.length) await consumeGrant({ grantId, actor, agentId, op });

	for (const e of toRemove) await removeEntry({ agentId, entryId: e.id, actor, req });
	const added = [];
	for (const n of toAdd) {
		const out = await addEntry({ agentId, actor, body: { address: n.address }, grantId: null, req, skipGrant: true });
		added.push(out.entry);
	}
	for (const e of toApprove) {
		const cooldown = await ownerCooldownSeconds(agentId);
		await sql`UPDATE destination_whitelist_entries SET status = 'pending', approved_at = now(), activates_at = now() + ${cooldown} * interval '1 second', updated_at = now() WHERE id = ${e.id} AND status = 'proposed'`;
	}

	if (chain === 'solana' && !wanted.size && (await getSettings(agentId)).enforced) {
		await updateSettings({ agentId, actor, body: { enforced: false }, grantId: null, skipGrant: true, req });
	}
	const view = await getWhitelist(agentId, actor.userId);
	return { ...view, added: added.length, removed: toRemove.length, pending: view.entries.filter((e) => e.status === 'pending') };
}

/** Active Solana addresses for an agent: what the legacy `withdraw_allowlist` field now reports. */
export async function activeAddresses(agentId, chain = 'solana') {
	await activateDue(agentId);
	const rows = await sql`SELECT address FROM destination_whitelist_entries WHERE agent_id = ${agentId} AND chain = ${chain} AND status = 'active' ORDER BY created_at`;
	return rows.map((r) => r.address);
}

// ── activation ─────────────────────────────────────────────────────────────────

/**
 * Flip entries whose cooldown has ended from pending to active, switch
 * enforcement on for an agent that never configured it (a first active entry
 * means the owner wants a list), and tell the owner. Safe to run from several
 * places at once: the UPDATE hands each entry to exactly one caller.
 */
export async function activateDue(agentId = null) {
	const rows = agentId
		? await sql`UPDATE destination_whitelist_entries SET status = 'active', activated_at = now(), updated_at = now()
			WHERE status = 'pending' AND activates_at <= now() AND agent_id = ${agentId} RETURNING *`
		: await sql`UPDATE destination_whitelist_entries SET status = 'active', activated_at = now(), updated_at = now()
			WHERE status = 'pending' AND activates_at <= now() RETURNING *`;
	for (const row of rows) {
		await sql`
			INSERT INTO destination_whitelist_settings (agent_id, user_id, enforced)
			VALUES (${row.agent_id}, ${row.user_id}, true) ON CONFLICT (agent_id) DO NOTHING`;
		const [agent] = await sql`SELECT id, name FROM agent_identities WHERE id = ${row.agent_id}`;
		if (agent) await notifyOwner({ userId: row.user_id, agent, entry: row, type: 'whitelist_active', detail: 'it can now receive funds' });
	}
	const due = await sql`SELECT agent_id FROM destination_whitelist_settings WHERE pending_change IS NOT NULL AND (pending_change->>'effective_at')::timestamptz <= now()`;
	for (const d of due) await getSettings(d.agent_id);
	return { activated: rows.length, settings_applied: due.length };
}

// ── enforcement ────────────────────────────────────────────────────────────────

/**
 * Decide whether `destination` may receive funds from this agent.
 *
 * Returns { allowed, state, ... }. `state` is one of exempt, own_wallet,
 * not_enforced, active, cooling_down, proposed, not_listed, invalid. The
 * entry's caps come back with an allowed decision so the caller can apply them
 * (the spend guard owns the per-destination spend ledger).
 */
export async function evaluateDestination({ agentId, destination, category, chain: hintChain = null, ownAddress = null, now = Date.now() }) {
	if (EXEMPT_CATEGORIES.has(category)) return { allowed: true, state: 'exempt', enforced: false };
	const norm = normalizeDestination(destination);
	const chain = norm?.chain || hintChain || 'solana';

	if (norm && ownAddress && sameDestination(ownAddress, norm.address)) {
		return { allowed: true, state: 'own_wallet', enforced: false, chain };
	}

	const [settings, entryRows] = await Promise.all([
		getSettings(agentId),
		norm
			? sql`SELECT * FROM destination_whitelist_entries
				WHERE agent_id = ${agentId} AND chain = ${norm.chain} AND address_key = ${norm.key} AND status IN ('proposed', 'pending', 'active')
				LIMIT 1`
			: Promise.resolve([]),
	]);
	// An agent that keeps an EVM list is restricted to it even when the switch
	// was never turned on; the EVM leg itself refuses unlisted destinations
	// unconditionally (evm-leg/guards.js). With no EVM list the switch decides.
	let enforced = settings.enforced;
	if (!enforced && chain === 'evm') {
		const [any] = await sql`SELECT 1 AS n FROM destination_whitelist_entries WHERE agent_id = ${agentId} AND chain = 'evm' AND status IN ('proposed', 'pending', 'active') LIMIT 1`;
		enforced = !!any;
	}
	const entry = entryRows[0] ? entryView(entryRows[0], now) : null;

	if (entry?.usable) return { allowed: true, state: 'active', enforced, chain, entry };
	if (!enforced) return { allowed: true, state: entry ? (entry.status === 'proposed' ? 'proposed' : 'cooling_down') : 'not_enforced', enforced, chain, entry };

	if (!norm) {
		return {
			allowed: false, state: 'invalid', enforced, chain, code: 'destination_invalid',
			message: 'That destination is not a valid address, so it cannot be checked against the allowlist.',
		};
	}
	if (entry?.status === 'pending') {
		return {
			allowed: false, state: 'cooling_down', enforced, chain, entry, code: 'destination_cooling_down',
			message: `That address was added recently and is still in its cooldown. It becomes usable at ${new Date(entry.activates_at).toISOString()}.`,
			detail: { activates_at: entry.activates_at, seconds_until_active: entry.seconds_until_active },
		};
	}
	if (entry?.status === 'proposed') {
		return {
			allowed: false, state: 'proposed', enforced, chain, entry, code: 'destination_awaiting_approval',
			message: 'That address was proposed but the owner has not approved it yet.',
		};
	}
	return {
		allowed: false, state: 'not_listed', enforced, chain, code: 'destination_not_whitelisted',
		message: 'That destination is not on this agent\'s allowlist. Add it under Limits & Safety; a new address becomes usable after its cooldown.',
	};
}

/** The one line a confirmation table shows for a destination's allowlist state. */
export function allowlistLine(decision) {
	switch (decision?.state) {
		case 'exempt': return 'Not applicable to this kind of payment';
		case 'own_wallet': return 'This agent\'s own wallet (always allowed)';
		case 'active': return `On the allowlist${decision.entry?.label ? `: ${decision.entry.label}` : ''}`;
		case 'not_enforced': return 'Allowlist is off for this agent (any address is allowed)';
		case 'cooling_down': return decision.allowed
			? 'Cooling down (allowlist is off, so it is allowed)'
			: `BLOCKED: cooling down until ${new Date(decision.entry.activates_at).toISOString()}`;
		case 'proposed': return decision.allowed ? 'Proposed, not yet approved (allowlist is off)' : 'BLOCKED: proposed by an agent, not yet approved';
		case 'not_listed': return 'BLOCKED: not on the allowlist';
		case 'invalid': return 'BLOCKED: not a valid address';
		default: return 'Unknown';
	}
}

/** A confirmation-table row for an outbound send. Never throws. */
export async function allowlistRow({ agentId, destination, category, ownAddress = null }) {
	try {
		const decision = await evaluateDestination({ agentId, destination, category, ownAddress });
		return { label: 'Allowlist', value: allowlistLine(decision), state: decision.state, allowed: decision.allowed };
	} catch (e) {
		return { label: 'Allowlist', value: 'Could not be checked right now', state: 'unknown', allowed: false };
	}
}