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.

11.0 KB
Raw Blame
// Real-funds agreement: server-side record and enforcement.
//
// Before any real-funds action, a person signs three documents together: the
// Terms of Service, the Risk Disclosure, and the Agent Wallet Agreement. The
// signing dialog lives in public/risk-ack.js and posts to /api/legal/risk-ack;
// this module validates that signature, writes the durable record into
// legal_signatures (migration 20260917180000_legal_signatures.sql), and gives
// every money-moving endpoint one call, requireRealFundsAgreement(), that
// refuses an account without a current signature. Usage is in
// docs/risk-acknowledgment.md.
//
// The client gate is a convenience; this is the enforcement. It covers session
// and API-key callers alike, so a script cannot skip the agreement the UI shows.
//
// Versions come from AGREEMENT_DOCUMENTS / RISK_ACK_VERSION in the client
// module, so the documents a signature records are always the ones the dialog
// showed. Each signature also stores the sha256 of every document's <main>
// text as this server serves it, which pins exactly what was signed even if
// the page is later edited without a version bump.

import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { sql } from './db.js';
import { withDbRetry } from './db-retry.js';
import { logAuditNow } from './audit.js';
import { clientIp } from './rate-limit.js';
import { error } from './http.js';
import { env } from './env.js';
import {
	AGREEMENT_ATTESTATIONS,
	AGREEMENT_DOCUMENTS,
	RISK_ACK_REQUIRED_ERROR,
	RISK_ACK_VERSION,
	normalizeSignatureName,
} from '../../public/risk-ack.js';

const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
const PATH = /^\/[\x20-\x7e]{0,199}$/;
const UA_MAX = 512;
const SIGN_PATH = '/legal/agreements';

const DOCUMENT_FILES = {
	tos: new URL('../../public/legal/tos.html', import.meta.url),
	risk: new URL('../../public/legal/risk.html', import.meta.url),
	agentWallet: new URL('../../public/legal/agent-wallet.html', import.meta.url),
};

/**
 * sha256 of a legal page's <main> element, whitespace-collapsed so a
 * re-indent does not change the fingerprint but any wording change does. Pure.
 * @param {string} html
 */
export function fingerprintDocumentHtml(html) {
	const match = /<main\b[^>]*>([\s\S]*?)<\/main>/i.exec(html);
	const text = (match ? match[1] : html).replace(/\s+/g, ' ').trim();
	return createHash('sha256').update(text).digest('hex');
}

let _fingerprints = null;

/** Fingerprints of the served documents, computed once per process. Never rejects. */
export function documentFingerprints() {
	if (_fingerprints) return _fingerprints;
	_fingerprints = Promise.all(
		AGREEMENT_DOCUMENTS.map(async (d) => {
			try {
				return [d.key, fingerprintDocumentHtml(await readFile(DOCUMENT_FILES[d.key], 'utf8'))];
			} catch (err) {
				console.error('[real-funds-agreement] could not fingerprint', d.key, err?.message || err);
				return [d.key, null];
			}
		}),
	).then((pairs) => Object.fromEntries(pairs));
	return _fingerprints;
}

/**
 * Validate a signature POST body. Pure: every rule the record must satisfy
 * lives here, so the endpoint cannot store a signature the dialog could not
 * have produced.
 *
 * @param {unknown} body
 * @returns {{ ok: true, value: { version: number, documents: Record<string, number>, attestations: Record<string, true>, signatureName: string, context: string|null, path: string|null } }
 *   | { ok: false, code: string, message: string }}
 */
export function validateSignatureBody(body) {
	if (!body || typeof body !== 'object' || Array.isArray(body)) {
		return { ok: false, code: 'invalid_body', message: 'body must be a JSON object' };
	}
	const version = Number(body.version);
	if (!Number.isInteger(version) || version !== RISK_ACK_VERSION) {
		return {
			ok: false,
			code: 'invalid_version',
			message: `version must be ${RISK_ACK_VERSION}, the current agreement version. Reload the page and sign again.`,
		};
	}
	const docs = body.documents && typeof body.documents === 'object' ? body.documents : {};
	for (const d of AGREEMENT_DOCUMENTS) {
		if (Number(docs[d.key]) !== d.version) {
			return {
				ok: false,
				code: 'document_not_accepted',
				message: `${d.title} version ${d.version} must be accepted`,
			};
		}
	}
	const attest = body.attestations && typeof body.attestations === 'object' ? body.attestations : {};
	for (const a of AGREEMENT_ATTESTATIONS) {
		if (attest[a.key] !== true) {
			return { ok: false, code: 'attestation_missing', message: `the "${a.key}" confirmation must be checked` };
		}
	}
	const signatureName = normalizeSignatureName(body.signatureName);
	if (!signatureName) {
		return { ok: false, code: 'invalid_signature', message: 'type your full name to sign' };
	}
	return {
		ok: true,
		value: {
			version,
			documents: Object.fromEntries(AGREEMENT_DOCUMENTS.map((d) => [d.key, d.version])),
			attestations: Object.fromEntries(AGREEMENT_ATTESTATIONS.map((a) => [a.key, true])),
			signatureName,
			context: typeof body.context === 'string' && SLUG.test(body.context) ? body.context : null,
			path: typeof body.path === 'string' && PATH.test(body.path) ? body.path : null,
		},
	};
}

/**
 * Write a validated signature. The legal_signatures row is the deliverable;
 * the audit_log row is the secondary trail. Never throws.
 *
 * @param {{ userId: string|null, value: ReturnType<typeof validateSignatureBody>['value'], req?: import('http').IncomingMessage }} args
 * @returns {Promise<boolean>} true when the legal_signatures row landed
 */
export async function recordRealFundsSignature({ userId, value, req = null }) {
	const fingerprints = await documentFingerprints();
	const documents = Object.fromEntries(
		AGREEMENT_DOCUMENTS.map((d) => [d.key, { version: d.version, sha256: fingerprints[d.key] }]),
	);
	const ip = req ? clientIp(req) : null;
	const ua = req?.headers?.['user-agent'] ? String(req.headers['user-agent']).slice(0, UA_MAX) : null;
	let recorded = false;
	try {
		await withDbRetry(
			() => sql`
				insert into legal_signatures
					(user_id, bundle_version, documents, signature_name, attestations, context, path, ip, user_agent)
				values
					(${userId}, ${value.version}, ${JSON.stringify(documents)}::jsonb, ${value.signatureName},
					 ${JSON.stringify(value.attestations)}::jsonb, ${value.context}, ${value.path}, ${ip}, ${ua})
			`,
			{ timeoutMs: 8_000 },
		);
		recorded = true;
	} catch (err) {
		console.error('[real-funds-agreement] signature insert failed', err?.message || err);
	}
	if (recorded) {
		if (userId) _rememberSigned(userId);
		await logAuditNow({
			userId,
			action: 'risk-ack-accept',
			resourceId: null,
			meta: { version: value.version, documents: value.documents, context: value.context, path: value.path },
			req,
		});
	}
	return recorded;
}

// Positive results only: signatures are append-only and the required version
// is a deploy-time constant, so "signed" can never become false inside one
// process. Negative results are never cached, so a fresh signature takes
// effect on the very next request.
const SIGNED_CACHE_TTL_MS = 10 * 60_000;
const SIGNED_CACHE_MAX = 5_000;
const _signedCache = new Map();

function _cachedSigned(userId) {
	const at = _signedCache.get(userId);
	if (at === undefined) return false;
	if (Date.now() - at > SIGNED_CACHE_TTL_MS) {
		_signedCache.delete(userId);
		return false;
	}
	return true;
}

function _rememberSigned(userId) {
	if (_signedCache.size >= SIGNED_CACHE_MAX) _signedCache.delete(_signedCache.keys().next().value);
	_signedCache.set(userId, Date.now());
}

/** Test hook: forget cached signature lookups. */
export function resetRealFundsAgreementCache() {
	_signedCache.clear();
}

/**
 * The account's latest signature at or above the current version.
 * Throws on a database failure; callers decide how to fail.
 * @param {string} userId
 * @returns {Promise<{ signedAt: string, signatureName: string, context: string|null } | null>}
 */
export async function currentSignatureFor(userId) {
	const rows = await withDbRetry(
		() => sql`
			select created_at, signature_name, context
			from legal_signatures
			where user_id = ${userId} and bundle_version >= ${RISK_ACK_VERSION}
			order by created_at desc
			limit 1
		`,
		{ timeoutMs: 5_000 },
	);
	const row = rows?.[0];
	if (!row) return null;
	_rememberSigned(userId);
	return {
		signedAt: new Date(row.created_at).toISOString(),
		signatureName: row.signature_name,
		context: row.context ?? null,
	};
}

/**
 * Every signature this account has made, newest first, for the review page.
 * @param {string} userId
 * @param {{ limit?: number }} [opts]
 */
export async function signatureHistoryFor(userId, { limit = 20 } = {}) {
	const rows = await withDbRetry(
		() => sql`
			select id, bundle_version, documents, signature_name, context, path, created_at
			from legal_signatures
			where user_id = ${userId}
			order by created_at desc
			limit ${Math.min(Math.max(1, limit), 100)}
		`,
		{ timeoutMs: 5_000 },
	);
	return (rows || []).map((r) => ({
		id: r.id,
		version: r.bundle_version,
		current: r.bundle_version >= RISK_ACK_VERSION,
		documents: r.documents,
		signatureName: r.signature_name,
		context: r.context ?? null,
		path: r.path ?? null,
		signedAt: new Date(r.created_at).toISOString(),
	}));
}

/** The machine-readable part of a refusal, so any client can route the user to sign. */
export function agreementRequirement() {
	const origin = env.APP_ORIGIN;
	return {
		version: RISK_ACK_VERSION,
		sign_url: `${origin}${SIGN_PATH}`,
		documents: AGREEMENT_DOCUMENTS.map((d) => ({
			key: d.key,
			title: d.title,
			version: d.version,
			url: `${origin}${d.path}`,
		})),
	};
}

/**
 * Refuse a real-funds request from an account that has not signed the current
 * agreements. Sends the response and resolves false when refused; resolves
 * true when the caller may proceed.
 *
 * Devnet is exempt: it moves no real value, and the client gate exempts it
 * too. A database failure fails CLOSED with 503: real funds never move on an
 * unverified agreement.
 *
 * @param {import('http').IncomingMessage} req
 * @param {import('http').ServerResponse} res
 * @param {{ userId: string|null|undefined, network?: string|null, context?: string }} opts
 * @returns {Promise<boolean>}
 */
export async function requireRealFundsAgreement(req, res, { userId, network = null, context = 'real-funds' } = {}) {
	if (String(network || '').toLowerCase() === 'devnet') return true;
	if (!userId) {
		error(res, 401, 'unauthorized', 'sign in to use real-funds features');
		return false;
	}
	if (_cachedSigned(userId)) return true;
	let signature;
	try {
		signature = await currentSignatureFor(userId);
	} catch (err) {
		console.error('[real-funds-agreement] signature lookup failed', context, err?.message || err);
		error(
			res,
			503,
			'agreement_check_unavailable',
			'We could not verify your signed real-funds agreements, so nothing was sent. Try again in a moment.',
		);
		return false;
	}
	if (signature) return true;
	error(
		res,
		403,
		RISK_ACK_REQUIRED_ERROR,
		'Sign the real-funds agreements (Terms of Service, Risk Disclosure, and Agent Wallet Agreement) before using ' +
			`real funds. Nothing was sent. Sign at ${env.APP_ORIGIN}${SIGN_PATH}`,
		{ context, ...agreementRequirement() },
	);
	return false;
}