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.

fix(mcp): only a persona's owner moves its funds, and unpaid 3D mints get a budget

nirholas8c61e84e7765
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index cf5590f23..efb6be9b2 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -911,6 +911,15 @@ export const limits = {
// double an inspect and gets half the budget.
mcpDiff: (key) =>
getLimiter('mcp:diff', { limit: 15, window: '1 m', critical: true }).limit(key),
+ // mint_3d_asset calls that did not pay per call (an OAuth / API key caller,
+ // or an x402 subscription window). The platform authority pays the rent and
+ // fee of every mint, and a fresh recipient wallet defeats the idempotency
+ // key, so without this an account could loop mainnet mints off the treasury.
+ // Per-call x402 payments skip it: each of those already covered its own cost.
+ mcpMint3dUnpaidMainnet: (key) =>
+ getLimiter('mcp:mint3d:unpaid:mainnet', { limit: 5, window: '1 d', critical: true }).limit(key),
+ mcpMint3dUnpaidDevnet: (key) =>
+ getLimiter('mcp:mint3d:unpaid:devnet', { limit: 30, window: '1 h', critical: true }).limit(key),
// 3D Studio MCP. Generation submits a real GPU job on Replicate (text→image
// and/or image→3D reconstruction) that costs real money, so it gets a hard
// hourly ceiling per principal. Status polling is cheap and frequent.
diff --git a/api/_mcp/tools/tokenize.js b/api/_mcp/tools/tokenize.js
index 160752050..c2a2bcc29 100644
--- a/api/_mcp/tools/tokenize.js
+++ b/api/_mcp/tools/tokenize.js
@@ -1,5 +1,6 @@
import { mintTokenized3dAsset, readTokenized3dAsset, TOKENIZE_3D_ROYALTY_CAP_BPS } from '../../_lib/tokenize-3d.js';
import { priceFor } from '../../_lib/pump-pricing.js';
+import { limits } from '../../_lib/rate-limit.js';
// A handled boundary error carries a status + code; surface it as a clean MCP
// tool error (isError) rather than letting an unexpected 500 bubble.
@@ -11,6 +12,22 @@ function toolError(message) {
return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
}
+// A mint nobody paid for per call still costs the platform authority its rent
+// and fee, so those callers get a small budget per account (or payer).
+export async function unpaidMintLimited(network, auth) {
+ const limiter = network === 'mainnet' ? limits.mcpMint3dUnpaidMainnet : limits.mcpMint3dUnpaidDevnet;
+ const rl = await limiter(String(auth?.userId || auth?.payer || auth?.rateKey || 'anon'));
+ if (rl.success) return null;
+ const retryAfter = Math.max(1, Math.ceil((rl.reset - Date.now()) / 1000));
+ return {
+ ...toolError(
+ `Mint limit reached for this account on ${network === 'mainnet' ? 'mainnet' : 'devnet'}. ` +
+ `Retry in ${retryAfter}s, or pay per mint over x402 to mint without this limit.`,
+ ),
+ structuredContent: { ok: false, reason: 'rate_limited', retry_after: retryAfter },
+ };
+}
+
export const toolDefs = [
{
name: 'mint_3d_asset',
@@ -39,7 +56,7 @@ export const toolDefs = [
"routes the parent creator's royalty slice out of THIS mint's fee as a real on-chain USDC " +
'transfer. Returns the mint address, explorer + viewer links, royalty terms, the provenance ' +
'ledger reference, and (for a remix) the royalty settlement. Priced per call via x402 (USDC); ' +
- 'an OAuth bearer token bypasses payment.',
+ 'an OAuth bearer token bypasses payment within a small per-account mint budget (5 mainnet mints a day).',
inputSchema: {
type: 'object',
properties: {
@@ -97,10 +114,14 @@ export const toolDefs = [
// ACTUALLY collected for this exact call: a genuine per-call x402
// settlement (auth.x402Paid), never a subscription window or an OAuth
// bypass (both real access, but no fresh fee here to split).
- const mintFeeAtomicsCollected =
- auth?.source === 'x402' && auth?.x402Paid
- ? BigInt(Math.round((priceFor('mint_3d_asset')?.amount_usdc || 0) * 1_000_000))
- : 0n;
+ const paidPerCall = auth?.source === 'x402' && Boolean(auth?.x402Paid);
+ const mintFeeAtomicsCollected = paidPerCall
+ ? BigInt(Math.round((priceFor('mint_3d_asset')?.amount_usdc || 0) * 1_000_000))
+ : 0n;
+ if (!paidPerCall) {
+ const limited = await unpaidMintLimited(args.network, auth);
+ if (limited) return limited;
+ }
const result = await mintTokenized3dAsset({
avatarId: args.avatar_id,
glbUrl: args.glb_url,
diff --git a/api/_mcp3d/tools/persona-identity.js b/api/_mcp3d/tools/persona-identity.js
index cfd1dea3d..c4f57e6af 100644
--- a/api/_mcp3d/tools/persona-identity.js
+++ b/api/_mcp3d/tools/persona-identity.js
@@ -114,10 +114,27 @@ async function handlePersonaIdentity(args, auth) {
};
}
+// A persona created by a signed-in account moves funds only for that account.
+// The persona_id travels in every embodiment embed URL (it is how the hosted
+// body reloads), so for an owned persona it cannot also be the key to its
+// wallet: anyone shown a shared artifact could otherwise send its USDC to
+// themselves. A persona minted with no account keeps the bearer-capability
+// model it was created under.
+export function personaSpendForbidden(record, auth) {
+ if (!record?.owner_id) return false;
+ return !auth?.userId || String(auth.userId) !== String(record.owner_id);
+}
+
async function handlePersonaValueOp(args, auth, { tool, verb }) {
await enforce(limits.mcp3dPersonaSpend, auth);
const { record, error } = await loadPersonaOrError(args.persona_id);
if (error) return error;
+ if (personaSpendForbidden(record, auth)) {
+ return toolError(
+ `${verb} blocked: this persona belongs to a three.ws account, and only that account can move its funds. Sign in as its owner.`,
+ { status: 'blocked', code: 'not_owner' },
+ );
+ }
const persona = personaPublicView(record);
const usdc = Number(args.usdc);
diff --git a/tests/mcp3d-persona-spend-owner.test.js b/tests/mcp3d-persona-spend-owner.test.js
new file mode 100644
index 000000000..9c04a38bf
--- /dev/null
+++ b/tests/mcp3d-persona-spend-owner.test.js
@@ -0,0 +1,105 @@
+// persona_tip / persona_send on an OWNED persona move funds only for the owner.
+//
+// The persona_id rides in every embodiment embed URL, so it cannot double as
+// the key to an owned persona's wallet. These tests drive the real tool
+// handlers with the store and the settlement path stubbed at the module edge,
+// and prove a stranger is refused before any settlement is attempted.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+process.env.JWT_SECRET ||= 'test-jwt-secret-not-a-real-secret-0123456789';
+process.env.PERSONA_WALLET_SECRET ||= 'test-persona-wallet-secret-0123456789';
+
+const state = vi.hoisted(() => ({ record: null, sends: [] }));
+
+vi.mock('../api/_lib/rate-limit.js', () => ({
+ limits: new Proxy({}, { get: () => async () => ({ success: true, reset: Date.now() }) }),
+ clientIp: () => '127.0.0.1',
+}));
+
+vi.mock('../api/_lib/persona-store.js', async (importOriginal) => {
+ const real = await importOriginal();
+ return { ...real, getPersona: async () => state.record };
+});
+
+vi.mock('../api/_lib/persona-wallet.js', async (importOriginal) => {
+ const real = await importOriginal();
+ return {
+ ...real,
+ sendPersonaUsdc: async (input) => {
+ state.sends.push(input);
+ return {
+ status: 'sent',
+ usdc: input.usdc,
+ to: input.to,
+ signature: 'sig',
+ explorer: 'https://explorer.example/tx/sig',
+ session_spent_usdc: input.usdc,
+ session_cap_usdc: 5,
+ };
+ },
+ };
+});
+
+const { toolDefs, personaSpendForbidden } = await import('../api/_mcp3d/tools/persona-identity.js');
+
+const PERSONA_ID = 'persona_abcdefghijklmnop';
+const TO = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+const OWNER = '11111111-1111-4111-8111-111111111111';
+const STRANGER = '22222222-2222-4222-8222-222222222222';
+
+function persona(ownerId) {
+ return {
+ id: PERSONA_ID,
+ owner_id: ownerId,
+ name: 'Test Persona',
+ glb_url: 'https://three.ws/x.glb',
+ look: {},
+ emotion_baseline: 'neutral',
+ };
+}
+
+const call = (name, auth) =>
+ toolDefs.find((t) => t.name === name).handler({ persona_id: PERSONA_ID, to: TO, usdc: 0.1 }, auth);
+
+beforeEach(() => {
+ state.sends = [];
+});
+
+describe('personaSpendForbidden', () => {
+ it('lets anyone holding the id spend an unowned persona (its creation model)', () => {
+ expect(personaSpendForbidden({ owner_id: null }, { userId: null })).toBe(false);
+ });
+ it('refuses an anonymous or different caller on an owned persona', () => {
+ expect(personaSpendForbidden({ owner_id: OWNER }, { userId: null, source: 'x402' })).toBe(true);
+ expect(personaSpendForbidden({ owner_id: OWNER }, { userId: STRANGER })).toBe(true);
+ });
+ it('allows the owner', () => {
+ expect(personaSpendForbidden({ owner_id: OWNER }, { userId: OWNER })).toBe(false);
+ });
+});
+
+describe('persona value tools enforce ownership before settlement', () => {
+ for (const name of ['persona_tip', 'persona_send']) {
+ it(`${name}: a stranger cannot drain an owned persona`, async () => {
+ state.record = persona(OWNER);
+ const out = await call(name, { userId: STRANGER, scope: 'all' });
+ expect(out.isError).toBe(true);
+ expect(out.structuredContent.code).toBe('not_owner');
+ expect(state.sends).toHaveLength(0);
+ });
+
+ it(`${name}: an anonymous x402 payer cannot drain an owned persona`, async () => {
+ state.record = persona(OWNER);
+ const out = await call(name, { userId: null, source: 'x402', rateKey: 'payer', scope: '' });
+ expect(out.structuredContent.code).toBe('not_owner');
+ expect(state.sends).toHaveLength(0);
+ });
+
+ it(`${name}: the owner can send`, async () => {
+ state.record = persona(OWNER);
+ const out = await call(name, { userId: OWNER, scope: 'all' });
+ expect(out.isError).toBeUndefined();
+ expect(state.sends).toHaveLength(1);
+ });
+ }
+});