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.

7.9 KB
Raw Blame
// Server enforcement for the $THREE hold-to-access lever.
//
// The keystone that turns the `three-access.js` registry from a read into an
// actual gate: one helper any Vercel function calls to require a minimum holder
// tier for a feature, with a hold-OR-pay 402 when the caller falls short.
//
// Semantics mirror cors()/method() in http.js — on a BLOCKED request it writes
// the response itself and returns `{ ok: false }`; on an ALLOWED request it
// writes nothing and returns `{ ok: true, access, level, wallet }`:
//
//   const gate = await requireFeatureAccess(req, res, 'forge.high', { body });
//   if (!gate.ok) return; // 402 three_hold_required already sent
//
// Resolution is pass-first: a signed tier pass is pure-HMAC (no RPC), so a holder
// presenting one is never wrongly blocked during a price/RPC outage. It then
// falls back to the session user's on-chain tier, then anonymous Member. Every
// failure degrades to Member (a normal 402), never a 500.

import { json, error } from './http.js';
import { verifyTierPass, resolveUserTier } from './three-tier.js';
import { accessFromTierLevel, gatedFeature, requiredTierFor } from './three-access.js';
import { catalogEntry } from './pricing/catalog.js';
import { getSessionUser } from './auth.js';
import { resolveCompAccess, COMP_TIER_LEVEL } from './comp-access.js';
import { TOKEN_MINT, publicConfig } from './token/config.js';

// The "how to acquire $THREE" block the 402 surfaces so a non-holder can act
// without leaving the error. Mint is the platform config; the swap/pump URLs are
// derived from the canonical mint. Symbol drops a leading "$" for clean URLs/copy.
function acquireBlock() {
	let symbol = 'THREE';
	try {
		symbol = String(publicConfig().symbol || 'THREE').replace(/^\$/, '') || 'THREE';
	} catch {
		symbol = 'THREE';
	}
	return {
		mint: TOKEN_MINT,
		symbol,
		swap_url: `https://jup.ag/swap/SOL-${TOKEN_MINT}`,
		pump_url: `https://pump.fun/coin/${TOKEN_MINT}`,
	};
}

// Resolve the caller's verified holder level for gating. Comp-first (an allowlisted
// account is entitled regardless of what it holds), then a signed tier pass (pure
// HMAC, never depends on a live RPC), then the session user's on-chain tier, then
// anonymous Member (level 0). Never throws.
async function resolveCaller(req, res, body) {
	// 0. Comped account (api/_lib/comp-access.js): full access with no wallet, no
	//    hold, no payment. Checked FIRST so a stale low-tier pass in the client's
	//    storage can't under-resolve a comped caller, and it costs an anonymous
	//    request nothing (the lookup short-circuits without a session cookie).
	const comp = await resolveCompAccess(req, res);
	if (comp.comped) {
		return {
			level: COMP_TIER_LEVEL,
			wallet: comp.user?.wallet_address || null,
			usd: null,
			source: 'comp',
			hasUser: true,
			hasWallet: Boolean(comp.user?.wallet_address),
		};
	}

	// 1. Signed tier pass — header or parsed body. Pure HMAC, no RPC.
	const token = req.headers?.['x-three-tier-pass'] || body?.tier_pass || null;
	if (token) {
		const payload = verifyTierPass(token);
		if (payload) {
			return {
				level: Math.max(0, Number(payload.level) || 0),
				wallet: payload.wallet || null,
				usd: null,
				source: 'pass',
				hasUser: false,
				hasWallet: Boolean(payload.wallet),
			};
		}
	}

	// 2. Session user → on-chain tier (degrades to Member on any failure).
	let user = null;
	try {
		user = await getSessionUser(req, res);
	} catch {
		user = null;
	}
	if (user?.wallet_address) {
		try {
			const { tier, usd } = await resolveUserTier(user);
			return {
				level: tier.level,
				wallet: user.wallet_address,
				usd: Math.round((Number(usd) || 0) * 100) / 100,
				source: 'onchain',
				hasUser: true,
				hasWallet: true,
			};
		} catch {
			return {
				level: 0,
				wallet: user.wallet_address,
				usd: 0,
				source: 'onchain',
				hasUser: true,
				hasWallet: true,
			};
		}
	}

	// 3. Anonymous / signed-in without a linked wallet.
	return {
		level: 0,
		wallet: null,
		usd: 0,
		source: 'anon',
		hasUser: Boolean(user),
		hasWallet: false,
	};
}

// access.reason upgraded with auth context: a presented (but short) pass is an
// insufficient-tier case; otherwise no user → sign in, user without a wallet →
// link a wallet, else under the threshold.
function reasonFor(caller) {
	if (caller.source === 'pass') return 'insufficient_tier';
	if (!caller.hasUser) return 'sign_in';
	if (!caller.hasWallet) return 'link_wallet';
	return 'insufficient_tier';
}

/**
 * Read-only holder check: resolves the caller (comp, tier pass, on-chain tier) and
 * reports whether they are eligible for a registered gated feature. Writes nothing
 * to `res` beyond what comp resolution may set, so a handler that owns its own 402
 * (a per-tier pay-per-use action, say) can branch on it.
 * @returns {Promise<{ eligible: boolean, level: number, wallet: string|null }>}
 */
export async function checkFeatureAccess(req, res, featureId, { body = null } = {}) {
	const caller = await resolveCaller(req, res, body);
	const access = accessFromTierLevel(caller.level, featureId);
	return { eligible: access.eligible, level: caller.level, wallet: caller.wallet };
}

/**
 * Require a minimum $THREE holder tier for a feature.
 * @param {object} req
 * @param {object} res
 * @param {string} featureId          a key of GATED_FEATURES (three-access.js)
 * @param {object} [opts]
 * @param {boolean} [opts.allowPayPerUse=true]  include the pay-per-use action in
 *   the 402 so a non-holder can pay once in $THREE instead of holding.
 * @param {object|null} [opts.body]    a pre-parsed request body (so the helper can
 *   read body.tier_pass without re-reading the stream).
 * @returns {Promise<{ ok: true, access, level, wallet } | { ok: false }>}
 */
export async function requireFeatureAccess(req, res, featureId, opts = {}) {
	const { allowPayPerUse = true, body = null } = opts;

	// A typo'd featureId is a clean 404, not a 500.
	try {
		gatedFeature(featureId);
	} catch (err) {
		error(res, 404, 'unknown_feature', err?.message || `unknown gated feature: ${featureId}`);
		return { ok: false };
	}

	const caller = await resolveCaller(req, res, body);
	const access = accessFromTierLevel(caller.level, featureId);

	if (access.eligible) {
		return { ok: true, access, level: caller.level, wallet: caller.wallet };
	}

	// Blocked → structured 402 with everything the UI needs to recover. Build the
	// `required` tier explicitly (level/id/label from the access view + the USD
	// threshold from the tier ladder) so the payload carries `min_usd` regardless
	// of the access registry's display shape.
	const requiredMinUsd = Number(requiredTierFor(featureId).minUsd) || 0;
	const required = {
		level: access.required.level,
		id: access.required.id,
		label: access.required.label,
		min_usd: requiredMinUsd,
	};
	// Only the on-chain path carries a USD value; the pass path proved the level
	// without a price (and a passing holder never reaches here anyway).
	const heldUsd = caller.source === 'onchain' ? Number(caller.usd) || 0 : 0;
	const usdToGo = Math.max(0, Math.round((requiredMinUsd - heldUsd) * 100) / 100);

	let payPerUse = null;
	if (allowPayPerUse && access.pay_per_use) {
		let usd = null;
		try {
			const p = Number(catalogEntry(access.pay_per_use).usd);
			usd = p >= 0 ? p : null;
		} catch {
			usd = null; // a missing/variable price never fails the 402
		}
		payPerUse = { action: access.pay_per_use, usd };
	}

	const held = {
		level: access.held.level,
		id: access.held.id,
		label: access.held.label,
		usd: heldUsd,
	};
	const message = payPerUse
		? `${access.label} requires holding $THREE (${required.label}+) — or pay per use.`
		: `${access.label} requires holding $THREE (${required.label}+).`;

	json(res, 402, {
		error: 'three_hold_required',
		message,
		feature: featureId,
		label: access.label,
		why: access.why,
		reason: reasonFor(caller),
		held,
		required,
		usd_to_go: usdToGo,
		acquire: acquireBlock(),
		pay_per_use: payPerUse,
	});
	return { ok: false };
}