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
feat(human-tasks,auth): escrow arithmetic for task payouts and refunds, and the Google identity linking module
nirholasbe12390313d1
diff --git a/api/_lib/human-tasks/money.js b/api/_lib/human-tasks/money.jsnew file mode 100644index 000000000..45819a646--- /dev/null+++ b/api/_lib/human-tasks/money.js@@ -0,0 +1,106 @@+// Escrow accounting for human tasks. Pure BigInt arithmetic on USDC atomics+// (6 decimals), never floats.+//+// Posting locks bounty + fee in the task's escrow account. Exactly one of two+// things then leaves it, and together they always add up to what went in:+//+// release bounty -> the worker's payout wallet, fee -> the platform fee wallet+// refund bounty + fee -> the poster agent's wallet (nothing was earned)+//+// The fee is taken only when a task pays out: a cancelled or expired task+// refunds the full escrow, fee included.++import { formatAtomics, parseAmount } from '../agent-market/chain.js';++export const USDC_DECIMALS = 6;+const ATOMICS = 10n ** BigInt(USDC_DECIMALS);++export const MIN_BOUNTY_ATOMICS = 1n * ATOMICS;+export const DEFAULT_MAX_BOUNTY_USDC = 500;+export const MAX_FEE_BPS = 1000;++function typed(status, code, message) {+ return Object.assign(new Error(message), { status, code, expose: true });+}++/** The largest bounty a single task may carry (HUMAN_TASK_MAX_BOUNTY_USDC, default 500). */+export function maxBountyAtomics() {+ const raw = Number(process.env.HUMAN_TASK_MAX_BOUNTY_USDC);+ const usdc = Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_BOUNTY_USDC;+ return BigInt(usdc) * ATOMICS;+}++/** Parse a bounty given in USDC ("2.5") into atomics, inside the allowed range. */+export function parseBounty(value) {+ const atomics = parseAmount(value, USDC_DECIMALS);+ if (atomics < MIN_BOUNTY_ATOMICS) {+ throw typed(400, 'bounty_too_small', `A bounty must be at least ${formatAtomics(MIN_BOUNTY_ATOMICS, USDC_DECIMALS)} USDC.`);+ }+ const max = maxBountyAtomics();+ if (atomics > max) {+ throw typed(400, 'bounty_too_large', `A bounty can be at most ${formatAtomics(max, USDC_DECIMALS)} USDC.`);+ }+ return atomics;+}++/** Clamp a basis-point fee rate into [0, MAX_FEE_BPS]. */+export function clampFeeBps(bps) {+ const n = Math.floor(Number(bps));+ if (!Number.isFinite(n) || n < 0) return 0;+ return Math.min(n, MAX_FEE_BPS);+}++/**+ * The escrow a bounty requires at a fee rate. The fee rounds down, so the+ * poster is never charged a fraction of an atomic unit they were not quoted.+ * @returns {{ bounty: bigint, fee: bigint, escrow: bigint, feeBps: number }}+ */+export function computeEscrow(bountyAtomics, feeBps) {+ const bounty = BigInt(String(bountyAtomics));+ if (bounty <= 0n) throw typed(400, 'bad_amount', 'bounty must be greater than zero');+ const bps = clampFeeBps(feeBps);+ const fee = (bounty * BigInt(bps)) / 10_000n;+ return { bounty, fee, escrow: bounty + fee, feeBps: bps };+}++/**+ * The legs that release a task's escrow: the bounty to the worker, then the fee+ * to the fee wallet when there is one. Their sum is always escrow_atomics.+ */+export function releaseLegs(task) {+ const bounty = BigInt(String(task.bounty_atomics));+ const fee = BigInt(String(task.fee_atomics || 0));+ if (!task.payout_address) throw typed(409, 'no_payout_address', 'This task has no payout address to release to.');+ const legs = [{ kind: 'payout', legId: `payout:${task.id}`, recipient: task.payout_address, atomics: bounty }];+ if (fee > 0n) {+ if (!task.fee_recipient) throw typed(409, 'no_fee_recipient', 'This task charged a fee but has no fee wallet recorded.');+ legs.push({ kind: 'fee', legId: `fee:${task.id}`, recipient: task.fee_recipient, atomics: fee });+ }+ assertBalanced(task, legs);+ return legs;+}++/** The single leg that refunds a task: the whole escrow back to the poster agent. */+export function refundLeg(task, destination) {+ if (!destination) throw typed(409, 'no_refund_address', 'The poster agent has no wallet to refund to.');+ const leg = { kind: 'refund', legId: `refund:${task.id}`, recipient: destination, atomics: BigInt(String(task.escrow_atomics)) };+ assertBalanced(task, [leg]);+ return leg;+}++/** Throw unless the legs move exactly the escrow, no more and no less. */+export function assertBalanced(task, legs) {+ const escrow = BigInt(String(task.escrow_atomics));+ const bounty = BigInt(String(task.bounty_atomics));+ const fee = BigInt(String(task.fee_atomics || 0));+ if (bounty + fee !== escrow) throw typed(500, 'escrow_unbalanced', `task ${task.id} escrow does not equal bounty plus fee`);+ const total = legs.reduce((s, l) => s + BigInt(String(l.atomics)), 0n);+ if (total !== escrow) throw typed(500, 'escrow_unbalanced', `legs for task ${task.id} move ${total}, escrow holds ${escrow}`);+}++/** "2.5" for 2500000n. */+export function usdc(atomics) {+ return formatAtomics(atomics, USDC_DECIMALS);+}++export { parseAmount, formatAtomics };diff --git a/api/_lib/identities.js b/api/_lib/identities.jsnew file mode 100644index 000000000..877889fcb--- /dev/null+++ b/api/_lib/identities.js@@ -0,0 +1,337 @@+// Sign-in identities linked to an account beyond its original method.+//+// Today that is Google (OpenID Connect). An account keeps signing in the way it+// always did (password, wallet, email code) and can ALSO sign in with a linked+// Google account. The table is user_identities (migration+// 20260922190000_account_social_sso.sql); this module is its only writer.+//+// Three flows share one round trip to Google (api/auth/google/[action].js):+//+// login no session needed. The Google `sub` must already be linked to an+// account; an unlinked Google account is never turned into a new+// account or matched by email, so a Google account can only ever+// reach the three.ws account that deliberately linked it.+// link needs a session. Links the Google account to the signed-in user.+// reauth needs a session. Proves the person at the keyboard can sign in to+// the Google account linked to this user right now (prompt=login,+// max_age=0), and grants a five-minute re-authentication proof that+// unlinking honors. A password works as the other proof.+//+// The PKCE verifier, nonce and intent ride in a short-lived HMAC-signed+// __Host- cookie, the same shape api/auth/x uses, so no server-side store is+// needed between the redirect out and the callback.++import { createRemoteJWKSet, jwtVerify } from 'jose';+import { sql } from './db.js';+import { env } from './env.js';+import { hmacSha256, constantTimeEquals, randomToken, sha256Base64Url } from './crypto.js';+import { fetchUpstream } from './upstream-fetch.js';++export const GOOGLE_AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth';+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';+export const GOOGLE_JWKS_URL = 'https://www.googleapis.com/oauth2/v3/certs';+export const GOOGLE_ISSUERS = Object.freeze(['https://accounts.google.com', 'accounts.google.com']);++export const FLOW_COOKIE = '__Host-gsi';+export const REAUTH_COOKIE = '__Host-reauth';+export const FLOW_TTL_SEC = 600;+export const REAUTH_TTL_SEC = 300;+export const INTENTS = Object.freeze(['login', 'link', 'reauth']);++/** The identity providers an account can link. Same shape for every future one. */+export const PROVIDERS = Object.freeze([+ { id: 'google', label: 'Google', start: '/api/auth/google/start' },+]);++export class IdentityError extends Error {+ constructor(code, message, status = 400, extra = undefined) {+ super(message);+ this.code = code;+ this.status = status;+ this.extra = extra;+ }+}++export function googleConfigured() {+ return Boolean(env.GOOGLE_OAUTH_CLIENT_ID && env.GOOGLE_OAUTH_CLIENT_SECRET);+}++export function googleRedirectUri() {+ return `${env.APP_ORIGIN}/api/auth/google/callback`;+}++// ── Signed cookies ───────────────────────────────────────────────────────────++async function sign(payload) {+ const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');+ const sig = await hmacSha256(env.JWT_SECRET, `identity:${body}`);+ return `${body}.${sig}`;+}++async function unsign(token) {+ if (typeof token !== 'string') return null;+ const dot = token.lastIndexOf('.');+ if (dot <= 0) return null;+ const body = token.slice(0, dot);+ const expected = await hmacSha256(env.JWT_SECRET, `identity:${body}`);+ if (!constantTimeEquals(token.slice(dot + 1), expected)) return null;+ try {+ const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));+ if (!payload || typeof payload.e !== 'number' || payload.e < Math.floor(Date.now() / 1000)) return null;+ return payload;+ } catch {+ return null;+ }+}++export function readCookie(req, name) {+ const header = req?.headers?.cookie || '';+ const m = header.match(new RegExp(`(?:^|;\\s*)${name.replace(/[-]/g, '\\-')}=([^;]+)`));+ return m ? decodeURIComponent(m[1]) : null;+}++export function cookie(name, value, maxAge) {+ return `${name}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`;+}++export function clearCookie(name) {+ return `${name}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;+}++/**+ * Start a Google round trip. Returns the URL to send the browser to and the+ * cookie that carries the flow's secrets back to the callback.+ * @param {{ intent: 'login'|'link'|'reauth', userId?: string|null, next?: string|null, loginHint?: string|null }} o+ */+export async function startGoogleFlow({ intent, userId = null, next = null, loginHint = null }) {+ if (!INTENTS.includes(intent)) throw new IdentityError('validation_error', `intent must be one of ${INTENTS.join(', ')}`);+ if (intent !== 'login' && !userId) throw new IdentityError('unauthorized', 'sign in first', 401);+ const state = randomToken(16);+ const nonce = randomToken(16);+ const verifier = randomToken(32);+ const challenge = await sha256Base64Url(verifier);+ const flow = await sign({+ s: state,+ n: nonce,+ v: verifier,+ i: intent,+ u: userId,+ x: next,+ e: Math.floor(Date.now() / 1000) + FLOW_TTL_SEC,+ });+ const url = new URL(GOOGLE_AUTH_URL);+ url.searchParams.set('client_id', env.GOOGLE_OAUTH_CLIENT_ID);+ url.searchParams.set('redirect_uri', googleRedirectUri());+ url.searchParams.set('response_type', 'code');+ url.searchParams.set('scope', 'openid email profile');+ url.searchParams.set('state', state);+ url.searchParams.set('nonce', nonce);+ url.searchParams.set('code_challenge', challenge);+ url.searchParams.set('code_challenge_method', 'S256');+ if (intent === 'reauth') {+ // Force a fresh credential entry; the callback also checks auth_time.+ url.searchParams.set('prompt', 'login');+ url.searchParams.set('max_age', '0');+ } else {+ url.searchParams.set('prompt', 'select_account');+ }+ if (loginHint) url.searchParams.set('login_hint', loginHint);+ return { url: url.toString(), cookie: cookie(FLOW_COOKIE, flow, FLOW_TTL_SEC) };+}++/** Read and check the flow cookie against the `state` Google sent back. */+export async function readGoogleFlow(req, state) {+ const payload = await unsign(readCookie(req, FLOW_COOKIE));+ if (!payload || typeof state !== 'string' || !constantTimeEquals(payload.s, state)) return null;+ return { nonce: payload.n, verifier: payload.v, intent: payload.i, userId: payload.u || null, next: payload.x || null };+}++// ── Google token exchange and ID token verification ─────────────────────────++let jwks = null;+function googleJwks() {+ if (!jwks) jwks = createRemoteJWKSet(new URL(GOOGLE_JWKS_URL));+ return jwks;+}++/** Swap an authorization code for Google's ID token. */+export async function exchangeGoogleCode({ code, verifier }) {+ const res = await fetchUpstream(+ GOOGLE_TOKEN_URL,+ {+ method: 'POST',+ headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },+ body: new URLSearchParams({+ code,+ client_id: env.GOOGLE_OAUTH_CLIENT_ID,+ client_secret: env.GOOGLE_OAUTH_CLIENT_SECRET,+ redirect_uri: googleRedirectUri(),+ grant_type: 'authorization_code',+ code_verifier: verifier,+ }).toString(),+ },+ { name: 'google-oauth', timeoutMs: 10_000, attempts: 1, okWhen: () => true },+ );+ const body = await res.json().catch(() => ({}));+ if (!res.ok || !body.id_token) {+ throw new IdentityError('exchange_failed', body.error_description || body.error || `Google answered ${res.status}`, 502);+ }+ return body.id_token;+}++/**+ * Normalize verified ID token claims. Exported so tests and the verifier agree+ * on exactly which claims are required.+ */+export function claimsFromPayload(payload, { nonce, maxAuthAgeSec = null, now = Date.now() } = {}) {+ if (!payload?.sub || typeof payload.sub !== 'string') throw new IdentityError('invalid_token', 'the Google token has no subject');+ if (nonce && payload.nonce !== nonce) throw new IdentityError('invalid_token', 'the Google token was issued for a different sign-in');+ if (maxAuthAgeSec != null) {+ const authTime = Number(payload.auth_time);+ if (!Number.isFinite(authTime) || now / 1000 - authTime > maxAuthAgeSec) {+ throw new IdentityError('reauth_stale', 'Google did not ask for your password again; try re-authenticating once more', 401);+ }+ }+ return {+ subject: payload.sub,+ email: typeof payload.email === 'string' ? payload.email.toLowerCase() : null,+ email_verified: payload.email_verified === true || payload.email_verified === 'true',+ display_name: typeof payload.name === 'string' ? payload.name.slice(0, 120) : null,+ avatar_url: typeof payload.picture === 'string' && /^https:\/\//.test(payload.picture) ? payload.picture : null,+ };+}++export async function verifyGoogleIdToken(idToken, { nonce, maxAuthAgeSec = null } = {}) {+ let payload;+ try {+ ({ payload } = await jwtVerify(idToken, googleJwks(), {+ issuer: [...GOOGLE_ISSUERS],+ audience: env.GOOGLE_OAUTH_CLIENT_ID,+ }));+ } catch (err) {+ throw new IdentityError('invalid_token', `the Google token did not verify: ${err?.code || err?.message}`);+ }+ return claimsFromPayload(payload, { nonce, maxAuthAgeSec });+}++// ── Accounts ─────────────────────────────────────────────────────────────────++/** The live account an identity signs in to, or null. */+export async function findUserByIdentity(provider, subject) {+ const [row] = await sql`+ select u.id, u.deleted_at, i.id as identity_id+ from user_identities i join users u on u.id = i.user_id+ where i.provider = ${provider} and i.subject = ${subject}+ limit 1+ `;+ return row || null;+}++export async function touchIdentity(identityId) {+ await sql`update user_identities set last_used_at = now() where id = ${identityId}`;+}++/**+ * Link an identity to a user. Refuses an identity already linked elsewhere,+ * and a second, different account of the same provider on this user.+ */+export async function linkIdentity({ userId, provider, claims }) {+ const owner = await findUserByIdentity(provider, claims.subject);+ if (owner && owner.id !== userId) {+ throw new IdentityError('identity_in_use', `that ${provider} account is already linked to another three.ws account`, 409);+ }+ const [existing] = await sql`+ select subject from user_identities where user_id = ${userId} and provider = ${provider} limit 1+ `;+ if (existing && existing.subject !== claims.subject) {+ throw new IdentityError('already_linked', `a different ${provider} account is already linked; unlink it first`, 409);+ }+ const [row] = await sql`+ insert into user_identities (user_id, provider, subject, email, email_verified, display_name, avatar_url, last_used_at)+ values (${userId}, ${provider}, ${claims.subject}, ${claims.email}, ${claims.email_verified},+ ${claims.display_name}, ${claims.avatar_url}, now())+ on conflict (user_id, provider) do update set+ email = excluded.email,+ email_verified = excluded.email_verified,+ display_name = excluded.display_name,+ avatar_url = excluded.avatar_url,+ last_used_at = now()+ returning id, provider, email, linked_at+ `;+ return { ...row, relinked: Boolean(existing) };+}++/**+ * Every way this account can sign in. `count` is what the unlink guards read:+ * an account is never left with zero.+ */+export async function listSignInMethods(userId) {+ const [[user], wallets, identities] = await Promise.all([+ sql`select email, password_hash is not null as has_password, privy_did is not null as has_privy+ from users where id = ${userId} limit 1`,+ sql`select address, chain_type, is_primary, created_at, last_used_at+ from user_wallets where user_id = ${userId} order by is_primary desc, created_at asc`,+ sql`select provider, email, email_verified, display_name, linked_at, last_used_at+ from user_identities where user_id = ${userId} order by linked_at asc`,+ ]);+ const password = Boolean(user?.has_password);+ const privy = Boolean(user?.has_privy);+ return {+ password,+ email: user?.email || null,+ email_code: privy,+ wallets: wallets.map((w) => ({+ address: w.address,+ chain: w.chain_type,+ primary: w.is_primary,+ linked_at: w.created_at,+ last_used_at: w.last_used_at,+ })),+ identities: identities.map((i) => ({+ provider: i.provider,+ email: i.email,+ email_verified: i.email_verified,+ display_name: i.display_name,+ linked_at: i.linked_at,+ last_used_at: i.last_used_at,+ })),+ count: (password ? 1 : 0) + (privy ? 1 : 0) + wallets.length + identities.length,+ };+}++// ── Re-authentication ────────────────────────────────────────────────────────++/** Cookie proving this user re-authenticated with a provider just now. */+export async function reauthCookie(userId, provider) {+ const token = await sign({ u: userId, p: provider, e: Math.floor(Date.now() / 1000) + REAUTH_TTL_SEC });+ return cookie(REAUTH_COOKIE, token, REAUTH_TTL_SEC);+}++/** The provider the user re-authenticated with in the last five minutes, or null. */+export async function readReauth(req, userId) {+ const payload = await unsign(readCookie(req, REAUTH_COOKIE));+ return payload && payload.u === userId ? payload.p : null;+}++/**+ * Unlink an identity. `proof` is how the caller re-authenticated ('password'+ * or a provider id); the handler verifies it before calling this.+ */+export async function unlinkIdentity({ userId, provider }) {+ const methods = await listSignInMethods(userId);+ if (!methods.identities.some((i) => i.provider === provider)) {+ throw new IdentityError('not_linked', `no ${provider} account is linked`, 404);+ }+ if (methods.count <= 1) {+ throw new IdentityError(+ 'last_sign_in_method',+ `${provider} is the only way into this account. Set a password or link a wallet first`,+ 409,+ { settings_url: '/settings/connections#sign-in' },+ );+ }+ const rows = await sql`+ delete from user_identities where user_id = ${userId} and provider = ${provider} returning id+ `;+ return { unlinked: rows.length > 0, provider, remaining_methods: methods.count - rows.length };+}