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
/**
* Plugin Marketplace API
* ─────────────────────
* GET /api/plugins/categories
* GET /api/plugins/list ?category=&q=&sort=&cursor=&limit=
* GET /api/plugins/:id
* POST /api/plugins/import { manifest_url } — fetch + validate + optionally save
* POST /api/plugins/publish { manifest_json } — publish plugin to marketplace
* POST /api/plugins/:id/install — increment install_count (called client-side on install)
*/
import { z } from 'zod';
import { sql } from '../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import {
fetchSafePublicUrlPinned,
MaxBytesExceededError,
SsrfBlockedError,
} from '../_lib/ssrf-guard.js';
import { requireCsrf } from '../_lib/csrf.js';
import { isUuid } from '../_lib/validate.js';
const VALID_SORTS = new Set(['popular', 'new', 'az']);
const MAX_MANIFEST_BYTES = 64 * 1024; // 64 KB
const FETCH_TIMEOUT_MS = 8000;
// identifier is half of the (identifier, author_id) unique key and is echoed
// back in every listing, so it gets a length ceiling rather than inheriting the
// unbounded `text` column. api[] is capped for the same reason: the manifest is
// stored whole and re-served on every detail read.
const MAX_IDENTIFIER_LENGTH = 128;
const MAX_TOOLS = 100;
// Every tool declared here is handed straight to the model provider as a tool
// definition by the installer (src/plugins/index.js `toClaudeTools`), and both
// Anthropic and OpenAI reject a name outside this charset. Validating it at the
// publish boundary keeps a malformed manifest from breaking chat for everyone
// who installs it from the marketplace.
const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
const MAX_TOOL_DESCRIPTION_LENGTH = 1024;
// ── Manifest validation — LobeHub/pai-chat ToolManifest format ───────────────
// Required: identifier, meta.title, api[]
// Optional: systemRole, type, settings, version, openapi, gateway, ui
function validateManifest(json) {
if (!json || typeof json !== 'object') throw new Error('Manifest must be a JSON object');
if (!json.identifier || typeof json.identifier !== 'string')
throw new Error('Missing identifier');
if (!/^[a-z0-9._-]+$/i.test(json.identifier))
throw new Error('identifier must be alphanumeric with dots, hyphens, or underscores');
if (json.identifier.length > MAX_IDENTIFIER_LENGTH)
throw new Error(`identifier must be ${MAX_IDENTIFIER_LENGTH} characters or fewer`);
if (!json.meta?.title) throw new Error('Missing meta.title');
if (!Array.isArray(json.api) || !json.api.length)
throw new Error('api must be a non-empty array');
if (json.api.length > MAX_TOOLS) throw new Error(`api must declare at most ${MAX_TOOLS} tools`);
for (const tool of json.api) {
if (!tool || typeof tool !== 'object' || Array.isArray(tool))
throw new Error('every api entry must be a JSON object');
if (typeof tool.name !== 'string' || !tool.name)
throw new Error('every api entry needs a name, given as a string');
// The name is echoed back in the message, so it is truncated: the manifest
// ceiling still allows a 64KB one, and a rejection is not a reason to hand
// the caller their own payload back in full.
if (!TOOL_NAME_PATTERN.test(tool.name))
throw new Error(
`Tool "${tool.name.slice(0, 64)}" name must be 1-64 characters of letters, digits, underscores, or hyphens`,
);
if (typeof tool.description !== 'string' || !tool.description.trim())
throw new Error(`Tool "${tool.name}" needs a non-empty description`);
if (tool.description.length > MAX_TOOL_DESCRIPTION_LENGTH)
throw new Error(
`Tool "${tool.name}" description must be ${MAX_TOOL_DESCRIPTION_LENGTH} characters or fewer`,
);
}
// The manifest is stored whole and re-served on every list and detail read, so
// the same ceiling the import fetch enforces applies to a directly published
// one. Without it /publish accepted a body up to readJson's generic limit.
if (Buffer.byteLength(JSON.stringify(json), 'utf8') > MAX_MANIFEST_BYTES)
throw new Error(`manifest must be ${MAX_MANIFEST_BYTES / 1024}KB or smaller`);
}
// ── Auth ──────────────────────────────────────────────────────────────────────
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id };
const bearer = await authenticateBearer(extractBearer(req));
if (bearer) return { userId: bearer.userId };
return null;
}
// ── Row → API shape ───────────────────────────────────────────────────────────
function toPlugin(row) {
const price =
row.asset_price_amount != null
? {
amount: String(row.asset_price_amount),
currency_mint: row.asset_price_currency_mint,
chain: row.asset_price_chain,
mint_decimals: row.asset_price_mint_decimals ?? 6,
}
: null;
return {
id: row.id,
identifier: row.identifier,
manifest_url: row.manifest_url,
manifest_json: row.manifest_json,
name: row.name,
description: row.description,
category: row.category,
tags: row.tags || [],
install_count: row.install_count || 0,
avg_rating: Number(row.avg_rating) || 0,
author: row.author_id ? { id: row.author_id, display_name: row.author_display_name } : null,
created_at: row.created_at,
price,
};
}
// ── Route dispatcher ──────────────────────────────────────────────────────────
export default wrap(async (req, res) => {
const url = new URL(req.url, 'http://x');
const parts = url.pathname.split('/').filter(Boolean); // ['api','plugins',...]
const segment = parts[2]; // 'categories' | 'list' | 'import' | 'publish' | <uuid>
if (segment === 'categories') return handleCategories(req, res);
if (segment === 'list' || !segment) return handleList(req, res, url);
if (segment === 'import') return handleImport(req, res);
if (segment === 'publish') return handlePublish(req, res);
// /api/plugins/:id[/install]
if (isUuid(segment)) {
const sub = parts[3];
if (sub === 'install') return handleInstall(req, res, segment);
if (!sub) return handleDetail(req, res, segment);
}
return error(res, 404, 'not_found', 'unknown plugin action');
});
// ── Categories ────────────────────────────────────────────────────────────────
async function handleCategories(req, res) {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.widgetRead(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const rows = await sql`
SELECT category, count(*)::int AS count
FROM plugins
WHERE is_public = true AND deleted_at IS NULL
GROUP BY category
HAVING count(*) > 0
ORDER BY count DESC
`;
return json(
res,
200,
{ data: { categories: rows.map((r) => ({ slug: r.category, count: r.count })) } },
{ 'cache-control': 'public, max-age=60' },
);
}
// ── List ──────────────────────────────────────────────────────────────────────
async function handleList(req, res, url) {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.widgetRead(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const q = (url.searchParams.get('q') || '').trim().slice(0, 80) || null;
const category = url.searchParams.get('category') || null;
const sortParam = url.searchParams.get('sort') || 'popular';
const sort = VALID_SORTS.has(sortParam) ? sortParam : 'popular';
const cursor = url.searchParams.get('cursor') || null;
const limit = Math.min(40, Math.max(1, Number(url.searchParams.get('limit')) || 20));
// The cursor is this endpoint's own opaque offset, handed back as next_cursor.
// A hand-typed one still has to be a non-negative integer: Number('abc') is
// NaN, and NaN reaching OFFSET made Postgres throw, which surfaced as a 500
// for what is plainly a client fault.
const offset = cursor === null ? 0 : Number(cursor);
if (!Number.isInteger(offset) || offset < 0)
return error(res, 400, 'validation_error', 'cursor must be a non-negative integer');
// `%` and `_` are LIKE wildcards, so an unescaped search for "50%" matched
// every row and "a_b" matched "axb". Escape them (and the escape character
// itself) so the query text is taken literally, which is what the search box
// promises.
const qLike = q ? `%${q.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%` : null;
const fetchLimit = limit + 1;
// p.id closes the ORDER BY. Every seeded plugin shares one created_at and an
// install_count of 0, so the sort key was not unique and Postgres was free to
// order the ties differently per query: paging the marketplace at limit=2
// returned one plugin twice and never showed another at all.
const rows = await sql`
SELECT p.*, u.display_name AS author_display_name,
ap.amount AS asset_price_amount,
ap.currency_mint AS asset_price_currency_mint,
ap.chain AS asset_price_chain,
ap.mint_decimals AS asset_price_mint_decimals
FROM plugins p
LEFT JOIN users u ON u.id = p.author_id
LEFT JOIN asset_prices ap
ON ap.item_type = 'plugin' AND ap.item_id = p.id AND ap.is_active = true
WHERE p.is_public = true
AND p.deleted_at IS NULL
AND (${category}::text IS NULL OR p.category = ${category})
AND (${qLike}::text IS NULL OR p.name ILIKE ${qLike} OR p.description ILIKE ${qLike})
ORDER BY
CASE WHEN ${sort} = 'popular' THEN p.install_count END DESC NULLS LAST,
CASE WHEN ${sort} = 'az' THEN p.name END ASC NULLS LAST,
p.created_at DESC,
p.id DESC
LIMIT ${fetchLimit} OFFSET ${offset}
`;
const hasMore = rows.length > limit;
const items = rows.slice(0, limit).map(toPlugin);
return json(res, 200, {
data: {
items,
next_cursor: hasMore ? String(offset + limit) : null,
},
});
}
// ── Detail ────────────────────────────────────────────────────────────────────
async function handleDetail(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.widgetRead(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// `is_public: false` is a real publish option, and list/categories both honor
// it. Detail used to read by id alone, so anyone holding the UUID could pull
// an unpublished plugin's full manifest. Gate it the same way: public to
// everyone, private to its author only. An anonymous reader has a null viewer
// id, and `author_id = NULL` is never true, so the row simply 404s for them.
const auth = await resolveAuth(req);
const viewerId = auth?.userId ?? null;
const [row] = await sql`
SELECT p.*, u.display_name AS author_display_name,
ap.amount AS asset_price_amount,
ap.currency_mint AS asset_price_currency_mint,
ap.chain AS asset_price_chain,
ap.mint_decimals AS asset_price_mint_decimals
FROM plugins p
LEFT JOIN users u ON u.id = p.author_id
LEFT JOIN asset_prices ap
ON ap.item_type = 'plugin' AND ap.item_id = p.id AND ap.is_active = true
WHERE p.id = ${id}
AND p.deleted_at IS NULL
AND (p.is_public = true OR p.author_id = ${viewerId}::uuid)
`;
if (!row) return error(res, 404, 'not_found', 'plugin not found');
return json(res, 200, { data: { plugin: toPlugin(row) } });
}
// ── Import by URL ─────────────────────────────────────────────────────────────
async function handleImport(req, res) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const rl = await limits.pluginImportIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const body = await readJson(req);
const manifestUrl = (body?.manifest_url || '').trim();
if (!manifestUrl) return error(res, 400, 'validation_error', 'manifest_url is required');
let parsed;
try {
parsed = new URL(manifestUrl);
} catch {
return error(res, 400, 'validation_error', 'manifest_url is not a valid URL');
}
if (!['https:', 'http:'].includes(parsed.protocol))
return error(res, 400, 'validation_error', 'manifest_url must be http or https');
// Fetch the manifest server-side to avoid CORS issues. The pinned variant
// DNS-resolves the host (and every redirect hop), rejects private, loopback,
// link-local, and cloud-metadata ranges, and connects straight to the address
// it validated so a hostile resolver cannot rebind between the check and the
// socket. It is the right variant here because the fetched body is handed
// back to the caller rather than merely rendered.
//
// maxBytes aborts the transfer the instant it crosses the manifest ceiling,
// from the advertised content-length up front and from the streamed bytes
// after that. Reading the body first and measuring it afterwards, as this
// used to, let a hostile host stream gigabytes into the instance before the
// size check ever ran.
let manifest;
try {
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
let resp;
try {
resp = await fetchSafePublicUrlPinned(
manifestUrl,
{ signal: ac.signal },
{ allowHttp: true, maxBytes: MAX_MANIFEST_BYTES },
);
} finally {
clearTimeout(timer);
}
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const text = await resp.text();
try {
manifest = JSON.parse(text);
} catch {
// Linking a repository page instead of the raw file is the common way to
// land here, and a bare parse message ("Unexpected token '<'") does not
// tell the caller that.
return error(
res,
422,
'invalid_manifest',
'manifest_url did not return JSON. Link directly to the manifest file, not to a web page.',
);
}
} catch (err) {
if (err instanceof SsrfBlockedError)
return error(res, 400, 'validation_error', `manifest_url rejected: ${err.message}`);
if (err instanceof MaxBytesExceededError)
return error(
res,
422,
'fetch_failed',
`Manifest exceeds the ${MAX_MANIFEST_BYTES / 1024}KB limit`,
);
return error(res, 422, 'fetch_failed', `Could not fetch manifest: ${err.message}`);
}
try {
validateManifest(manifest);
} catch (err) {
return error(res, 422, 'invalid_manifest', err.message);
}
// Return the validated manifest — client decides whether to install locally
return json(res, 200, {
data: {
manifest: { ...manifest, _manifest_url: manifestUrl },
},
});
}
// ── Publish ───────────────────────────────────────────────────────────────────
const publishSchema = z.object({
manifest_json: z.record(z.any()),
manifest_url: z.string().url().optional(),
is_public: z.boolean().default(true),
});
async function handlePublish(req, res) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'authentication required');
// Cookie sessions are attached by the browser on any cross-site POST, so the
// only thing separating a real publish from one a hostile page triggered is
// the double-submit token. Bearer callers are exempt inside requireCsrf.
if (!(await requireCsrf(req, res, auth.userId))) return;
const rl = await limits.pluginPublishUser(auth.userId);
if (!rl.success) return rateLimited(res, rl);
// Bounded at the manifest ceiling plus room for the envelope's other fields, so
// an oversized publish is refused (413) at the boundary instead of being parsed
// into memory first and rejected by validateManifest afterwards.
const raw = await readJson(req, MAX_MANIFEST_BYTES + 4096);
let body;
try {
body = publishSchema.parse(raw);
} catch (err) {
return error(res, 400, 'validation_error', err.errors?.[0]?.message || 'invalid body');
}
const manifest = body.manifest_json;
try {
validateManifest(manifest);
} catch (err) {
return error(res, 422, 'invalid_manifest', err.message);
}
const name = String(manifest.meta?.title || manifest.identifier).slice(0, 80);
const description = String(manifest.meta?.description || '').slice(0, 500);
const category = String(manifest.meta?.category || 'general').slice(0, 50);
const tags = Array.isArray(manifest.meta?.tags)
? manifest.meta.tags.slice(0, 20).map((t) => String(t).slice(0, 40))
: [];
// Upsert on identifier + author so re-publishing updates the record.
// The RETURNING row carries author_id but no author_display_name, so the
// author's name is joined back on afterwards: without it this endpoint answered
// with a half-populated `author` object that list and detail both fill in.
const [row] = await sql`
INSERT INTO plugins (author_id, identifier, manifest_url, manifest_json, name, description, category, tags, is_public)
VALUES (
${auth.userId},
${manifest.identifier},
${body.manifest_url ?? null},
${JSON.stringify(manifest)},
${name},
${description},
${category},
${tags},
${body.is_public}
)
ON CONFLICT (identifier, author_id) DO UPDATE SET
manifest_url = EXCLUDED.manifest_url,
manifest_json = EXCLUDED.manifest_json,
name = EXCLUDED.name,
description = EXCLUDED.description,
category = EXCLUDED.category,
tags = EXCLUDED.tags,
is_public = EXCLUDED.is_public,
updated_at = now()
RETURNING *
`;
const [author] = await sql`SELECT display_name FROM users WHERE id = ${auth.userId}`;
return json(res, 200, {
data: { plugin: toPlugin({ ...row, author_display_name: author?.display_name ?? null }) },
});
}
// ── Install (counter) ─────────────────────────────────────────────────────────
async function handleInstall(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
if (!method(req, res, ['POST'])) return;
const ip = clientIp(req);
const rl = await limits.widgetRead(ip);
if (!rl.success) return rateLimited(res, rl);
// Same visibility rule as detail: a private plugin's counter is its author's
// business. Without this the endpoint confirmed a private plugin's existence
// and let anyone holding the UUID drive its install_count.
const auth = await resolveAuth(req);
const viewerId = auth?.userId ?? null;
const [target] = await sql`
SELECT id, install_count FROM plugins
WHERE id = ${id}
AND deleted_at IS NULL
AND (is_public = true OR author_id = ${viewerId}::uuid)
`;
if (!target) return error(res, 404, 'not_found', 'plugin not found');
// One counted install per (IP, plugin) per 30 minutes. A repeat inside the
// window is not an error the client should surface (the marketplace fires this
// as fire-and-forget), so it answers 200 with counted:false and the unchanged
// total rather than a 429 the caller would have to special-case.
const dedupe = await limits.pluginInstallDedupe(`${ip}:${id}`);
if (!dedupe.success)
return json(res, 200, { data: { ok: true, counted: false, install_count: target.install_count } });
const [row] = await sql`
UPDATE plugins SET install_count = install_count + 1
WHERE id = ${id} AND deleted_at IS NULL
RETURNING install_count
`;
return json(res, 200, {
data: { ok: true, counted: true, install_count: row?.install_count ?? target.install_count + 1 },
});
}