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
// POST /api/scene/gate-check
//
// Two-phase wallet-ownership proof for a token-gated scene share created by
// api/scene/gate-create.js. The chat client (chat/src/App.svelte) calls it twice:
//
// Phase 1 - { gateId, walletAddress } -> { message, chain }
// Issues a one-time nonce inside a human-readable message the visitor's wallet
// signs. Nothing is granted yet.
//
// Phase 2 - { gateId, walletAddress, signature, message } -> { allowed, reason? }
// Verifies the signature (ed25519 for Solana, personal_sign for EVM), burns the
// nonce, then reads the wallet's REAL on-chain holding for the gate's asset.
//
// Fail-closed, and honest about WHY it failed: a denial ({ allowed: false }) means
// the chain answered and the wallet is short. An RPC outage or a missing provider
// key is an infrastructure fault, so it returns 5xx with a generic message rather
// than a denial carrying the upstream error text (which both lies to the visitor
// and leaks internals to an unauthenticated caller).
//
// The nonce is burned BEFORE the chain read, so a failed read costs the visitor a
// fresh phase 1. That is deliberate: a replayable nonce is worse than a retry.
import { z } from 'zod';
import { verifyMessage, Contract, formatUnits, isAddress } from 'ethers';
import { sql } from '../_lib/db.js';
import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { randomToken } from '../_lib/crypto.js';
import { verifySiwsSignature } from '../_lib/siws.js';
import { parse } from '../_lib/validate.js';
// getSplTokenBalance rotates the shared Solana lane pool (api/_lib/solana/connection.js)
// instead of pinning one endpoint; dasSearchAssets targets Helius, the only provider
// in our stack that implements the DAS methods collection gating needs.
import { getSplTokenBalance } from '../_lib/embed-gate.js';
import { dasRpcUrl, dasSearchAssets, isValidSolanaAddress } from '../_lib/nft-gate.js';
import { evmFallbackProvider } from '../_lib/evm/rpc.js';
const NONCE_TTL_SEC = 10 * 60;
// EVM gates carry a bare contract address with no chain id (see the scene_gates
// schema), so they resolve on Ethereum mainnet. evmRpcEndpoints(1) puts the
// public endpoints behind any configured/Alchemy URL, so gating still works on a
// deployment with no provider key rather than hard-failing on ALCHEMY_API_KEY.
const EVM_CHAIN_ID = 1;
// DAS pages at 1000 assets. A gate only needs to know whether the wallet reaches
// min_balance, so paging stops as soon as the threshold is met; the cap bounds the
// work an unauthenticated caller can trigger with a huge wallet.
const DAS_PAGE_SIZE = 1000;
const DAS_MAX_PAGES = 5;
const ERC_BALANCE_ABI = [
'function balanceOf(address owner) view returns (uint256)',
'function decimals() view returns (uint8)',
];
const phase1Schema = z.object({
gateId: z.string().trim().min(1).max(32),
walletAddress: z.string().trim().min(1).max(128),
});
const phase2Schema = z.object({
gateId: z.string().trim().min(1).max(32),
walletAddress: z.string().trim().min(1).max(128),
signature: z.string().min(1).max(512),
message: z.string().min(1).max(1024),
});
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
res.setHeader('cache-control', 'no-store');
const rl = await limits.sceneGateCheckIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const raw = await readJson(req);
if (raw && raw.signature != null) return handlePhase2(res, raw);
return handlePhase1(res, raw);
});
/** A wallet the gate's chain can actually verify. Catches a Solana address pasted
* into an EVM gate before it reaches an RPC that would answer with noise. */
function walletMatchesChain(chain, walletAddress) {
return chain === 'solana' ? isValidSolanaAddress(walletAddress) : isAddress(walletAddress);
}
async function handlePhase1(res, raw) {
const body = parse(phase1Schema, raw);
const [gate] = await sql`
select id, chain from scene_gates where id = ${body.gateId} limit 1
`;
if (!gate) return error(res, 404, 'not_found', 'gate not found');
if (!walletMatchesChain(gate.chain, body.walletAddress)) {
return error(res, 400, 'validation_error', `walletAddress is not a valid ${gate.chain} address`);
}
let nonce = '';
while (nonce.length < 16) {
nonce += randomToken(20).replace(/[^A-Za-z0-9]/g, '');
}
nonce = nonce.slice(0, 16);
await sql`
insert into gate_nonces (nonce, gate_id, address, expires_at)
values (${nonce}, ${body.gateId}, ${body.walletAddress}, now() + ${`${NONCE_TTL_SEC} seconds`}::interval)
`;
const message = [
'three.ws scene gate verification.',
'',
`Gate ID: ${body.gateId}`,
`Wallet: ${body.walletAddress}`,
`Nonce: ${nonce}`,
`Issued At: ${new Date().toISOString()}`,
].join('\n');
return json(res, 200, { message, chain: gate.chain });
}
async function handlePhase2(res, raw) {
const body = parse(phase2Schema, raw);
const [gate] = await sql`
select id, chain, kind, address, min_balance
from scene_gates where id = ${body.gateId} limit 1
`;
if (!gate) return error(res, 404, 'not_found', 'gate not found');
if (!walletMatchesChain(gate.chain, body.walletAddress)) {
return error(res, 400, 'validation_error', `walletAddress is not a valid ${gate.chain} address`);
}
// A per-wallet ceiling on top of the per-IP flood guard: IPs are cheap to
// rotate, a wallet's signing key is not, so this is the bucket that actually
// bounds a determined attacker replaying signature attempts against one gate.
const wl = await limits.sceneGateCheckWallet(body.walletAddress);
if (!wl.success) return rateLimited(res, wl);
// Verify signature
if (gate.chain === 'solana') {
let valid;
try {
valid = verifySiwsSignature(body.message, body.signature, body.walletAddress);
} catch {
return error(res, 401, 'invalid_signature', 'Solana signature verification failed');
}
if (!valid) return error(res, 401, 'invalid_signature', 'Solana signature does not match wallet');
} else {
let recovered;
try {
recovered = verifyMessage(body.message, body.signature);
} catch {
return error(res, 401, 'invalid_signature', 'EVM signature verification failed');
}
if (recovered.toLowerCase() !== body.walletAddress.toLowerCase()) {
return error(res, 401, 'invalid_signature', 'EVM signature does not match wallet');
}
}
// Extract and burn nonce
const nonceMatch = body.message.match(/^Nonce: (.+)$/m);
if (!nonceMatch) return error(res, 400, 'invalid_message', 'nonce not found in message');
const nonce = nonceMatch[1].trim();
const [nonceRow] = await sql`
select nonce, gate_id, address, expires_at, consumed_at
from gate_nonces where nonce = ${nonce} limit 1
`;
if (!nonceRow) return error(res, 400, 'invalid_nonce', 'unknown nonce');
if (nonceRow.consumed_at) return error(res, 400, 'nonce_reused', 'nonce already used');
if (new Date(nonceRow.expires_at) < new Date()) return error(res, 400, 'nonce_expired', 'nonce expired');
if (nonceRow.gate_id !== body.gateId) return error(res, 400, 'invalid_nonce', 'nonce gate mismatch');
if (nonceRow.address !== body.walletAddress) return error(res, 400, 'invalid_nonce', 'nonce wallet mismatch');
const burned = await sql`
update gate_nonces set consumed_at = now()
where nonce = ${nonce} and consumed_at is null
returning nonce
`;
if (!burned[0]) return error(res, 400, 'nonce_reused', 'nonce already used');
const minBalance = Number(gate.min_balance);
// Query chain holdings
let balance;
try {
balance = await queryBalance(gate, body.walletAddress, minBalance);
} catch (e) {
console.warn(`[scene-gate] balance check failed for gate ${gate.id} (${gate.chain}/${gate.kind}):`, e?.message || e);
if (e?.status === 503) {
return error(
res,
503,
'not_configured',
'This gate cannot be verified right now: its chain provider is not configured.',
);
}
return error(
res,
502,
'gate_check_unavailable',
'Could not read your on-chain balance right now. Try verifying again in a moment.',
);
}
if (balance >= minBalance) {
return json(res, 200, { allowed: true });
}
return json(res, 200, {
allowed: false,
reason: `Insufficient balance: need ${minBalance}, have ${balance}`,
});
}
async function queryBalance(gate, walletAddress, minBalance) {
if (gate.chain === 'solana') return querySolanaBalance(gate, walletAddress, minBalance);
return queryEvmBalance(gate, walletAddress);
}
async function querySolanaBalance(gate, walletAddress, minBalance) {
if (gate.kind === 'spl') return getSplTokenBalance(walletAddress, gate.address);
return countCollectionAssets(walletAddress, gate.address, minBalance);
}
/** How many NFTs of `collectionMint` the wallet holds, counted only as far as
* `minBalance` (the answer past the threshold does not change the decision). */
async function countCollectionAssets(walletAddress, collectionMint, minBalance) {
if (!dasRpcUrl()) {
throw Object.assign(new Error('HELIUS_API_KEY not configured'), { status: 503 });
}
const needed = Math.max(1, Math.ceil(minBalance));
let held = 0;
for (let page = 1; page <= DAS_MAX_PAGES; page++) {
const result = await dasSearchAssets({
ownerAddress: walletAddress,
grouping: ['collection', collectionMint],
// Burnt assets are not held, and a burn must not keep a gate open.
burnt: false,
page,
limit: DAS_PAGE_SIZE,
});
const items = Array.isArray(result.items) ? result.items : [];
held += items.length;
if (held >= needed || items.length < DAS_PAGE_SIZE) break;
}
return held;
}
async function queryEvmBalance(gate, walletAddress) {
const provider = await evmFallbackProvider(EVM_CHAIN_ID);
const token = new Contract(gate.address, ERC_BALANCE_ABI, provider);
const rawBalance = await token.balanceOf(walletAddress);
// ERC-721 balances are whole tokens; ERC-20 needs the contract's own scale, and
// a token that omits decimals() is 18 by convention.
if (gate.kind === 'erc721') return Number(rawBalance);
let decimals = 18;
try {
decimals = Number(await token.decimals());
} catch {
decimals = 18;
}
return Number(formatUnits(rawBalance, decimals));
}