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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Payment Session CRUD — lifecycle management for Agent Payment Sessions.
//
// Sessions are the funding envelope for platform-managed agent payments.
// A developer creates a session with a budget (drawn from their credits),
// hands the session token to an agent, and the agent calls paid x402
// endpoints via /api/pay/execute without needing its own private key.
//
// Token design:
// - Generated as `pss_<sessionId>_<random32hex>`
// - Never stored plaintext; only the HMAC-SHA256 hash is persisted
// - Caller holds the token; server verifies it by hashing and comparing
//
// Budget accounting:
// - budget_usdc is USDC atomic units (6 decimals), matching the x402 standard
// - budget is drawn from the creator's credit balance at creation time
// - a cancelled/expired session refunds the un-spent portion back to credits
import { randomUUID } from 'node:crypto';
import { sql } from '../db.js';
import { debitCredits, creditAccount } from '../credits.js';
import {
generateSessionToken,
hashToken,
usdToAtomics,
atomicsToUsd,
normalizeHost,
} from './spend-governor.js';
import { SESSION_LIMITS, canonicalizePerRailDaily } from './policy.js';
const {
MAX_LABEL_LEN,
MAX_ALLOWED_HOSTS,
MIN_BUDGET_USD,
MAX_BUDGET_USD,
MIN_TTL_SECONDS,
MAX_TTL_SECONDS,
} = SESSION_LIMITS;
function bad(message, code = 'bad_request') {
return Object.assign(new Error(message), { status: 400, code });
}
function normalizeTtl(ttlSeconds) {
const n = Number(ttlSeconds ?? 3600);
if (!Number.isFinite(n) || n < MIN_TTL_SECONDS || n > MAX_TTL_SECONDS) {
throw bad(
`expiry_seconds must be between ${MIN_TTL_SECONDS} and ${MAX_TTL_SECONDS}`,
'invalid_ttl',
);
}
return Math.round(n);
}
function normalizeAllowedHosts(raw) {
if (!raw) return [];
const arr = Array.isArray(raw) ? raw : String(raw).split(/[\s,]+/);
const hosts = arr.map(normalizeHost).filter(Boolean);
if (hosts.length > MAX_ALLOWED_HOSTS)
throw bad(`allowed_hosts may contain at most ${MAX_ALLOWED_HOSTS} entries`);
return [...new Set(hosts)]; // deduplicate
}
function normalizeBudget(budgetUsd) {
const n = Number(budgetUsd);
if (!Number.isFinite(n) || n < MIN_BUDGET_USD || n > MAX_BUDGET_USD) {
throw bad(
`budget_usd must be between $${MIN_BUDGET_USD} and $${MAX_BUDGET_USD}`,
'invalid_budget',
);
}
return n;
}
function normalizeMaxPerTx(maxPerTxUsd) {
if (maxPerTxUsd == null) return null;
const n = Number(maxPerTxUsd);
if (!Number.isFinite(n) || n < 0.000001) throw bad('max_per_tx_usd must be > $0.000001');
return n;
}
function normalizeApprovalThreshold(approvalThresholdUsd) {
if (approvalThresholdUsd == null) return null;
const n = Number(approvalThresholdUsd);
if (!Number.isFinite(n) || n < 0.000001) throw bad('approval_threshold_usd must be > $0.000001');
return n;
}
function normalizeBlockedHosts(raw) {
if (!raw) return [];
const arr = Array.isArray(raw) ? raw : String(raw).split(/[\s,]+/);
const hosts = arr.map(normalizeHost).filter(Boolean);
if (hosts.length > MAX_ALLOWED_HOSTS)
throw bad(`blocked_hosts may contain at most ${MAX_ALLOWED_HOSTS} entries`);
return [...new Set(hosts)];
}
function normalizePerRailDaily(raw) {
if (raw == null) return {};
if (typeof raw !== 'object' || Array.isArray(raw)) throw bad('per_rail_daily_usd must be an object keyed by network');
for (const value of Object.values(raw)) {
const n = Number(value);
if (!Number.isFinite(n) || n <= 0) throw bad('per_rail_daily_usd values must be positive numbers');
}
return canonicalizePerRailDaily(raw);
}
/**
* Create a new payment session.
*
* @param {object} opts
* @param {string} opts.userId - Creator's user ID
* @param {string} [opts.agentId] - Optional: agent authorized to use this session
* @param {string} [opts.label] - Human-readable label
* @param {number} opts.budgetUsd - Total budget in USD
* @param {number} [opts.maxPerTxUsd] - Per-payment ceiling in USD
* @param {string[]} [opts.allowedHosts] - If set, only pay endpoints at these hosts
* @param {string[]} [opts.blockedHosts] - Hosts this session must never pay, even if allowlisted
* @param {number} [opts.approvalThresholdUsd] - A payment above this needs human approval instead of settling
* @param {object} [opts.perRailDailyUsd] - Rolling 24h spend cap per settlement rail, keyed by network ('solana'/'base') or CAIP-2 id
* @param {string} [opts.network] - 'solana' | 'base' (default: 'solana')
* @param {number} [opts.expirySeconds] - Session lifetime in seconds (default: 3600)
* @param {object} [opts.metadata] - Arbitrary caller metadata
* @returns {Promise<{ session: object, token: string }>}
*/
export async function createPaymentSession({
userId,
agentId,
label,
budgetUsd,
maxPerTxUsd,
allowedHosts,
blockedHosts,
approvalThresholdUsd,
perRailDailyUsd,
network = 'solana',
expirySeconds,
metadata = {},
}) {
if (!userId) throw bad('userId is required');
const budgetN = normalizeBudget(budgetUsd);
const budgetAtomics = usdToAtomics(budgetN);
const maxPerTxAtomics = maxPerTxUsd != null ? usdToAtomics(normalizeMaxPerTx(maxPerTxUsd)) : null;
const hosts = normalizeAllowedHosts(allowedHosts);
const blocked = normalizeBlockedHosts(blockedHosts);
const approvalThresholdAtomics =
approvalThresholdUsd != null ? usdToAtomics(normalizeApprovalThreshold(approvalThresholdUsd)) : null;
const perRailDaily = normalizePerRailDaily(perRailDailyUsd);
const ttl = normalizeTtl(expirySeconds);
const net = network === 'base' ? 'base' : 'solana';
const cleanLabel = String(label ?? '').trim().slice(0, MAX_LABEL_LEN);
// Debit the budget from the user's credit balance up-front.
// If the balance is insufficient, this throws a 402 from credits.js.
const idempotencyKey = `paysess_create_${randomUUID()}`;
await debitCredits({
userId,
amountUsd: budgetN,
action: 'payment_session_create',
refType: 'payment_session',
refId: null, // filled in after INSERT
idempotencyKey,
});
// Generate the bearer token (never stored; only its hash is persisted)
// We generate the UUID first so we can include it in the token.
const sessionId = randomUUID();
const token = generateSessionToken(sessionId);
const tokenHash = hashToken(token);
const expiresAt = new Date(Date.now() + ttl * 1000);
const [row] = await sql`
INSERT INTO payment_sessions
(id, user_id, agent_id, label, budget_usdc, max_per_tx_usdc,
allowed_hosts, blocked_hosts, approval_threshold_usdc, per_rail_daily_usdc,
network, status, expires_at, token_hash, session_metadata)
VALUES
(${sessionId}, ${userId}, ${agentId ?? null},
${cleanLabel}, ${budgetAtomics.toString()},
${maxPerTxAtomics != null ? maxPerTxAtomics.toString() : null},
${hosts}, ${blocked},
${approvalThresholdAtomics != null ? approvalThresholdAtomics.toString() : null},
${JSON.stringify(perRailDaily)}::jsonb,
${net}, 'active', ${expiresAt.toISOString()},
${tokenHash}, ${JSON.stringify(metadata)}::jsonb)
RETURNING id, user_id, agent_id, label, budget_usdc, spent_usdc,
max_per_tx_usdc, allowed_hosts, blocked_hosts,
approval_threshold_usdc, per_rail_daily_usdc,
network, status, expires_at,
session_metadata, created_at
`;
// Back-fill the ref_id now that we have the session ID
await sql`
UPDATE credit_ledger SET ref_id = ${sessionId}
WHERE idempotency_key = ${idempotencyKey}
`.catch(() => {});
return {
session: formatSession(row),
token,
};
}
/**
* Get a session by ID. Returns null if not found or not owned by userId.
*/
export async function getPaymentSession(sessionId, userId) {
const [row] = await sql`
SELECT id, user_id, agent_id, label, budget_usdc, spent_usdc,
max_per_tx_usdc, allowed_hosts, blocked_hosts,
approval_threshold_usdc, per_rail_daily_usdc,
network, status, expires_at,
session_metadata, created_at, updated_at
FROM payment_sessions
WHERE id = ${sessionId}
AND (${userId}::uuid IS NULL OR user_id = ${userId}::uuid)
LIMIT 1
`;
return row ? formatSession(row) : null;
}
/**
* List sessions for a user. Returns latest-first.
*/
export async function listPaymentSessions(userId, { status, limit = 20, cursor } = {}) {
const lim = Math.min(Math.max(Math.floor(Number(limit)) || 20, 1), 100);
const rows = await sql`
SELECT id, user_id, agent_id, label, budget_usdc, spent_usdc,
max_per_tx_usdc, allowed_hosts, blocked_hosts,
approval_threshold_usdc, per_rail_daily_usdc,
network, status, expires_at,
session_metadata, created_at, updated_at
FROM payment_sessions
WHERE user_id = ${userId}
AND (${status ?? null}::text IS NULL OR status = ${status ?? null})
AND (${cursor ?? null}::timestamptz IS NULL OR created_at < ${cursor ?? null}::timestamptz)
ORDER BY created_at DESC
LIMIT ${lim + 1}
`;
const hasMore = rows.length > lim;
const items = rows.slice(0, lim).map(formatSession);
return {
items,
next_cursor: hasMore ? items[items.length - 1].created_at : null,
};
}
/**
* Update mutable fields on an active session.
* Only label, allowed_hosts, and max_per_tx_usd can be changed after creation.
* Returns the updated session row or null if not found / not owned / not active.
*/
export async function updatePaymentSession(
sessionId,
userId,
{ label, allowedHosts, maxPerTxUsd, blockedHosts, approvalThresholdUsd, perRailDailyUsd } = {},
) {
const params = { id: sessionId, userId };
if (label !== undefined) {
params.label = String(label).trim().slice(0, MAX_LABEL_LEN);
}
if (allowedHosts !== undefined) {
params.allowedHosts = normalizeAllowedHosts(allowedHosts);
}
if (maxPerTxUsd !== undefined) {
params.maxPerTxAtomics = maxPerTxUsd != null ? usdToAtomics(normalizeMaxPerTx(maxPerTxUsd)).toString() : null;
}
if (blockedHosts !== undefined) {
params.blockedHosts = normalizeBlockedHosts(blockedHosts);
}
if (approvalThresholdUsd !== undefined) {
params.approvalThresholdAtomics =
approvalThresholdUsd != null ? usdToAtomics(normalizeApprovalThreshold(approvalThresholdUsd)).toString() : null;
}
if (perRailDailyUsd !== undefined) {
params.perRailDaily = normalizePerRailDaily(perRailDailyUsd);
}
const [row] = await sql`
UPDATE payment_sessions
SET
label = CASE WHEN ${params.label !== undefined}::boolean THEN ${params.label ?? null} ELSE label END,
allowed_hosts = CASE WHEN ${params.allowedHosts !== undefined}::boolean THEN ${params.allowedHosts ?? []} ELSE allowed_hosts END,
max_per_tx_usdc = CASE WHEN ${params.maxPerTxAtomics !== undefined}::boolean THEN ${params.maxPerTxAtomics ?? null}::bigint ELSE max_per_tx_usdc END,
blocked_hosts = CASE WHEN ${params.blockedHosts !== undefined}::boolean THEN ${params.blockedHosts ?? []} ELSE blocked_hosts END,
approval_threshold_usdc = CASE WHEN ${params.approvalThresholdAtomics !== undefined}::boolean THEN ${params.approvalThresholdAtomics ?? null}::bigint ELSE approval_threshold_usdc END,
per_rail_daily_usdc = CASE WHEN ${params.perRailDaily !== undefined}::boolean THEN ${params.perRailDaily != null ? JSON.stringify(params.perRailDaily) : '{}'}::jsonb ELSE per_rail_daily_usdc END,
updated_at = now()
WHERE id = ${sessionId} AND user_id = ${userId} AND status = 'active'
RETURNING id, user_id, agent_id, label, budget_usdc, spent_usdc,
max_per_tx_usdc, allowed_hosts, blocked_hosts,
approval_threshold_usdc, per_rail_daily_usdc,
network, status, expires_at,
session_metadata, created_at, updated_at
`;
return row ? formatSession(row) : null;
}
/**
* Cancel a session. Refunds un-spent budget to the user's credit balance.
*/
export async function cancelPaymentSession(sessionId, userId) {
const [row] = await sql`
UPDATE payment_sessions
SET status = 'cancelled', updated_at = now()
WHERE id = ${sessionId} AND user_id = ${userId}
AND status IN ('active', 'exhausted')
RETURNING id, budget_usdc, spent_usdc, user_id
`;
if (!row) return null;
// Refund the un-spent portion
const refundAtomics = BigInt(row.budget_usdc) - BigInt(row.spent_usdc);
if (refundAtomics > 0n) {
const refundUsd = atomicsToUsd(refundAtomics);
await creditAccount({
userId: row.user_id,
amountUsd: refundUsd,
kind: 'refund',
action: 'payment_session_cancel',
refType: 'payment_session',
refId: sessionId,
idempotencyKey: `paysess_refund_${sessionId}`,
}).catch(() => {});
}
return { id: sessionId, refunded_usd: atomicsToUsd(refundAtomics) };
}
/**
* List executions for a session.
*/
export async function listSessionExecutions(sessionId, userId, { limit = 20, cursor } = {}) {
const lim = Math.min(Math.max(Math.floor(Number(limit)) || 20, 1), 100);
const rows = await sql`
SELECT id, endpoint_url, endpoint_host, method, amount_usdc,
network, tx_hash, payer_address, payee_address,
status, error_code, duration_ms, created_at,
policy_digest, verdict_code, verdict_signature, verdict_signed_at
FROM payment_session_executions
WHERE session_id = ${sessionId}
AND user_id = ${userId}
AND (${cursor ?? null}::timestamptz IS NULL OR created_at < ${cursor ?? null}::timestamptz)
ORDER BY created_at DESC
LIMIT ${lim + 1}
`;
const hasMore = rows.length > lim;
const items = rows.slice(0, lim).map(formatExecution);
return { items, next_cursor: hasMore ? items[items.length - 1].created_at : null };
}
/**
* Aggregate spend stats across all sessions for a user.
*/
export async function getPaymentStats(userId) {
const [stats] = await sql`
SELECT
count(*) FILTER (WHERE status = 'active') AS active_sessions,
count(*) FILTER (WHERE status = 'exhausted') AS exhausted_sessions,
count(*) FILTER (WHERE status = 'cancelled') AS cancelled_sessions,
count(*) FILTER (WHERE status = 'expired') AS expired_sessions,
coalesce(sum(budget_usdc), 0) AS total_budget_atomics,
coalesce(sum(spent_usdc), 0) AS total_spent_atomics
FROM payment_sessions
WHERE user_id = ${userId}
`;
const [execStats] = await sql`
SELECT
count(*) FILTER (WHERE e.status = 'settled') AS settled_count,
count(*) FILTER (WHERE e.status = 'failed') AS failed_count,
coalesce(sum(e.amount_usdc) FILTER (WHERE e.status = 'settled'), 0) AS settled_atomics,
count(DISTINCT e.endpoint_host) AS unique_endpoints
FROM payment_session_executions e
JOIN payment_sessions s ON s.id = e.session_id
WHERE s.user_id = ${userId}
`;
return {
sessions: {
active: Number(stats?.active_sessions ?? 0),
exhausted: Number(stats?.exhausted_sessions ?? 0),
cancelled: Number(stats?.cancelled_sessions ?? 0),
expired: Number(stats?.expired_sessions ?? 0),
total_budget_usd: atomicsToUsd(stats?.total_budget_atomics ?? 0),
total_spent_usd: atomicsToUsd(stats?.total_spent_atomics ?? 0),
},
executions: {
settled: Number(execStats?.settled_count ?? 0),
failed: Number(execStats?.failed_count ?? 0),
settled_usd: atomicsToUsd(execStats?.settled_atomics ?? 0),
unique_endpoints: Number(execStats?.unique_endpoints ?? 0),
},
};
}
function formatSession(row) {
return {
id: row.id,
user_id: row.user_id,
agent_id: row.agent_id ?? null,
label: row.label ?? '',
budget_usd: atomicsToUsd(row.budget_usdc),
spent_usd: atomicsToUsd(row.spent_usdc),
remaining_usd: atomicsToUsd(BigInt(row.budget_usdc) - BigInt(row.spent_usdc)),
max_per_tx_usd: row.max_per_tx_usdc != null ? atomicsToUsd(row.max_per_tx_usdc) : null,
allowed_hosts: row.allowed_hosts ?? [],
blocked_hosts: row.blocked_hosts ?? [],
approval_threshold_usd: row.approval_threshold_usdc != null ? atomicsToUsd(row.approval_threshold_usdc) : null,
per_rail_daily_usd: row.per_rail_daily_usdc ?? {},
network: row.network,
status: row.status,
expires_at: row.expires_at,
metadata: row.session_metadata ?? {},
created_at: row.created_at,
updated_at: row.updated_at ?? null,
};
}
function formatExecution(row) {
return {
id: row.id,
endpoint_url: row.endpoint_url,
endpoint_host: row.endpoint_host,
method: row.method,
amount_usd: atomicsToUsd(row.amount_usdc),
network: row.network,
tx_hash: row.tx_hash ?? null,
payer_address: row.payer_address ?? null,
payee_address: row.payee_address ?? null,
status: row.status,
error_code: row.error_code ?? null,
duration_ms: row.duration_ms ?? null,
created_at: row.created_at,
policy_digest: row.policy_digest ?? null,
verdict_code: row.verdict_code ?? null,
verdict_signature: row.verdict_signature ?? null,
verdict_signed_at: row.verdict_signed_at ?? null,
};
}