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
/**
* Portable & Verifiable Brain — ownership endpoints.
*
* GET /api/agents/:id/brain — brain passport: storage mode, signed/
* verified counts, pin status + CIDs,
* on-chain anchor + drift, persona status.
* GET /api/agents/:id/brain/export — download a schema-versioned, signed
* .brain bundle (private memories stay
* encrypted unless explicitly opted in).
* POST /api/agents/:id/brain/verify — verify one memory by id, or a posted
* bundle, against its signatures.
* POST /api/agents/:id/brain/anchor — anchor the current brain_hash on-chain.
* POST /api/agents/:id/brain/storage — set the agent default storage mode and/
* or a per-memory override + record a CID.
* POST /api/agents/:id/brain/import — reconstitute a bundle into THIS owned
* (forked) agent, preserving provenance,
* with diff/merge against existing memories.
*
* All routes are owner-only. Mutations require CSRF. The verify route accepts an
* unauthenticated bundle body too (public verification of a shared brain), but
* never reveals private content.
*/
import { getSessionUser, authenticateBearer, extractBearer } from '../../_lib/auth.js';
import { sql } from '../../_lib/db.js';
import { cors, json, method, readJson, error } from '../../_lib/http.js';
import { requireCsrf } from '../../_lib/csrf.js';
import { IPFS_GATEWAYS } from '../../_lib/ipfs-gateways.js';
import { parse } from '../../_lib/validate.js';
import { z } from 'zod';
import {
verifyMemorySignature,
memoryDigest,
signMemoryWithAgent,
loadAgentSigner,
} from '../../_lib/brain-sign.js';
import {
buildBundle,
buildMemoryEntry,
verifyBundle,
brainBundleSchema,
} from '../../_lib/brain-bundle.js';
import {
anchorBrain,
latestAnchor,
BrainAnchorError,
} from '../../_lib/brain-anchor.js';
const STORAGE_MODES = ['local', 'ipfs', 'encrypted-ipfs', 'none'];
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;
}
async function ownedAgent(id, userId) {
const [agent] = await sql`
SELECT id, user_id, name, description, avatar_id, chain_id, erc8004_agent_id,
wallet_address, memory_storage_mode,
persona_prompt, persona_prompt_hash, persona_prompt_sig,
persona_tone_tags, persona_extracted_at, meta
FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL
`;
if (!agent) return { agent: null, code: 404 };
if (agent.user_id !== userId) return { agent: null, code: 403 };
return { agent, code: 200 };
}
function personaFrom(agent, { includePrompt }) {
if (!agent.persona_prompt_hash) return null;
return {
prompt: includePrompt ? agent.persona_prompt : null,
prompt_hash: agent.persona_prompt_hash,
prompt_sig: agent.persona_prompt_sig,
tone_tags: agent.persona_tone_tags || [],
extracted_at: agent.persona_extracted_at
? new Date(agent.persona_extracted_at).toISOString()
: null,
};
}
/**
* @param {import('http').IncomingMessage} req
* @param {import('http').ServerResponse} res
* @param {string} id agent id
* @param {string} [action] the segment after /brain (export|verify|anchor|storage|import)
*/
export async function handleBrain(req, res, id, action) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
// Public bundle verification: POST /brain/verify with a `bundle` body and no
// session is allowed — it reveals nothing private.
if (req.method === 'POST' && action === 'verify') {
const body = await readJson(req);
if (body && body.bundle) return verifyPostedBundle(res, body.bundle);
// else fall through to authenticated per-memory verify
}
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
const { agent, code } = await ownedAgent(id, auth.userId);
if (!agent) {
return code === 403
? error(res, 403, 'forbidden', 'not your agent')
: error(res, 404, 'not_found', 'agent not found');
}
if (req.method === 'GET' && !action) return getPassport(res, agent);
if (req.method === 'GET' && action === 'export') return exportBundle(req, res, agent);
// Mutations below require CSRF.
if (req.method === 'POST') {
if (!(await requireCsrf(req, res, auth.userId))) return;
if (action === 'verify') return verifyMemory(req, res, agent);
if (action === 'anchor') return anchor(req, res, agent);
if (action === 'storage') return setStorage(req, res, agent);
if (action === 'import') return importBundle(req, res, agent, auth.userId);
}
return error(res, 404, 'not_found', 'unknown brain action');
}
// ── GET /brain — passport ─────────────────────────────────────────────────────
async function getPassport(res, agent) {
const rows = await sql`
SELECT id, type, content, tags, salience, tier, is_public,
content_hash, signature, signer_address, signed_at, storage_mode, ipfs_cid, created_at
FROM agent_memories
WHERE agent_id = ${agent.id} AND (expires_at IS NULL OR expires_at > now())
`;
let signed = 0;
let verified = 0;
let publicCount = 0;
let encrypted = 0;
for (const r of rows) {
if (r.is_public) publicCount++;
if (r.ipfs_cid) encrypted++;
if (r.signature) {
signed++;
const v = verifyMemorySignature(r, {
signature: r.signature,
signer_address: r.signer_address,
content_hash: r.content_hash,
});
if (v.valid) verified++;
}
}
const pins = await sql`
SELECT cid, filename, bytes, created_at FROM agent_memory_pins
WHERE agent_id = ${agent.id}
ORDER BY created_at DESC LIMIT 200
`;
let anchorState = { anchor: null, currentBrainHash: null, inSync: false };
try {
anchorState = await latestAnchor(agent.id);
} catch (err) {
console.error('[brain] latestAnchor failed', agent.id, err?.message);
}
return json(res, 200, {
agent: {
id: agent.id,
name: agent.name,
wallet_address: agent.wallet_address,
chain_id: agent.chain_id,
erc8004_agent_id: agent.erc8004_agent_id != null ? String(agent.erc8004_agent_id) : null,
registered_onchain: agent.erc8004_agent_id != null,
},
storage_mode: agent.memory_storage_mode || 'local',
persona: agent.persona_prompt_hash
? {
has_persona: true,
prompt_hash: agent.persona_prompt_hash,
tone_tags: agent.persona_tone_tags || [],
extracted_at: agent.persona_extracted_at,
}
: { has_persona: false },
memories: {
total: rows.length,
public: publicCount,
private: rows.length - publicCount,
signed,
verified,
unsigned: rows.length - signed,
encrypted_pinned: encrypted,
},
pins: pins.map((p) => ({
cid: p.cid,
filename: p.filename,
bytes: p.bytes,
created_at: p.created_at,
gateway_url: `${IPFS_GATEWAYS[0]}${p.cid}`,
})),
anchor: anchorState.anchor,
current_brain_hash: anchorState.currentBrainHash,
anchor_in_sync: anchorState.inSync,
provenance: agent.meta?.brain_provenance || null,
});
}
// ── GET /brain/export ───────────────────────────────────────────────────────
async function exportBundle(req, res, agent) {
const url = new URL(req.url, 'http://x');
const includePrivate = url.searchParams.get('includePrivate') === 'true';
const publicOnly = url.searchParams.get('publicOnly') === 'true';
const rows = await sql`
SELECT id, agent_id, type, content, tags, salience, tier, is_public,
content_hash, signature, signer_address, signed_at, storage_mode, ipfs_cid, created_at
FROM agent_memories
WHERE agent_id = ${agent.id} AND (expires_at IS NULL OR expires_at > now())
${publicOnly ? sql`AND is_public = true` : sql``}
ORDER BY created_at ASC
`;
// Encrypted private memories travel as a CID reference (ciphertext stays on
// IPFS, key never leaves the owner's wallet).
const cipherRefs = new Map();
for (const r of rows) {
if (!r.is_public && r.ipfs_cid) {
cipherRefs.set(String(r.id), { cid: r.ipfs_cid, filename: `${r.id}.enc` });
}
}
const memoryEntries = rows
.map((r) => buildMemoryEntry(r, { includePrivatePlaintext: includePrivate, cipherRefs }))
.filter(Boolean);
// Sign the bundle with the agent wallet when available.
let signerPrivKey = null;
try {
const signer = await loadAgentSigner(agent.id, { agentId: agent.id, reason: 'brain_export' });
if (signer) signerPrivKey = signer.privKey;
} catch (err) {
console.error('[brain] export signer load failed', agent.id, err?.message);
}
const bundle = await buildBundle({
agent,
persona: personaFrom(agent, { includePrompt: true }),
memoryEntries,
anchor: await safeAnchorForExport(agent.id),
exportedAt: new Date().toISOString(),
signerPrivKey,
});
const filename = `${(agent.name || 'agent').replace(/[^a-z0-9]+/gi, '-').toLowerCase()}-${agent.id.slice(0, 8)}.brain.json`;
res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
return json(res, 200, bundle);
}
async function safeAnchorForExport(agentId) {
try {
const { anchor } = await latestAnchor(agentId);
if (!anchor) return null;
return {
brain_hash: anchor.brain_hash,
proof_uri: anchor.proof_uri || undefined,
proof_hash: anchor.proof_hash || undefined,
tx_hash: anchor.tx_hash || undefined,
chain_id: anchor.chain_id || undefined,
anchored_at: anchor.anchored_at ? new Date(anchor.anchored_at).toISOString() : undefined,
explorer_url: anchor.explorer_url || null,
};
} catch {
return null;
}
}
// ── POST /brain/verify ──────────────────────────────────────────────────────
const verifyBody = z.object({ memoryId: z.string().uuid() });
async function verifyMemory(req, res, agent) {
const body = parse(verifyBody, await readJson(req));
const [row] = await sql`
SELECT id, agent_id, type, content, tags, content_hash, signature, signer_address, signed_at
FROM agent_memories WHERE id = ${body.memoryId} AND agent_id = ${agent.id}
`;
if (!row) return error(res, 404, 'not_found', 'memory not found');
const v = verifyMemorySignature(row, {
signature: row.signature,
signer_address: row.signer_address,
content_hash: row.content_hash,
});
// Cross-check the recovered signer against the agent's known wallet — a
// signature can be valid yet authored by a different key.
const matchesAgentWallet =
v.recovered && agent.wallet_address
? v.recovered.toLowerCase() === agent.wallet_address.toLowerCase()
: null;
return json(res, 200, {
memoryId: row.id,
valid: v.valid,
reason: v.reason,
recovered_signer: v.recovered,
expected_signer: row.signer_address || null,
matches_agent_wallet: matchesAgentWallet,
current_hash: v.digest,
stored_hash: row.content_hash || null,
});
}
function verifyPostedBundle(res, bundle) {
const result = verifyBundle(bundle);
return json(res, 200, result);
}
// ── POST /brain/anchor ──────────────────────────────────────────────────────
const anchorReq = z.object({ publicOnly: z.boolean().optional() });
async function anchor(req, res, agent) {
const body = parse(anchorReq, (await readJson(req)) || {});
try {
const result = await anchorBrain({
agentId: agent.id,
anchoredAt: new Date().toISOString(),
publicOnly: body.publicOnly === true,
});
return json(res, 200, {
ok: true,
brain_hash: result.brain_hash,
tx_hash: result.tx_hash,
proof_uri: result.proof_uri,
chain_id: result.chain_id,
explorer_url: result.explorer_url,
anchored_at: result.anchored_at,
});
} catch (err) {
if (err instanceof BrainAnchorError) {
// Honest, actionable failure — never a fake success.
const status = err.code === 'not_registered' ? 409 : 502;
return error(res, status, err.code, err.message);
}
console.error('[brain] anchor failed', agent.id, err?.message);
return error(res, 500, 'anchor_failed', 'could not anchor brain');
}
}
// ── POST /brain/storage ─────────────────────────────────────────────────────
const storageReq = z.object({
defaultMode: z.enum(STORAGE_MODES).optional(),
memoryId: z.string().uuid().optional(),
memoryMode: z.enum(STORAGE_MODES).nullable().optional(),
// When the client has pinned an encrypted copy, it records the CID here.
cid: z.string().min(1).max(120).optional(),
});
async function setStorage(req, res, agent) {
const body = parse(storageReq, await readJson(req));
if (body.defaultMode) {
await sql`
UPDATE agent_identities SET memory_storage_mode = ${body.defaultMode}, updated_at = now()
WHERE id = ${agent.id}
`;
}
if (body.memoryId) {
const [mem] = await sql`SELECT id FROM agent_memories WHERE id = ${body.memoryId} AND agent_id = ${agent.id}`;
if (!mem) return error(res, 404, 'not_found', 'memory not found');
await sql`
UPDATE agent_memories
SET storage_mode = ${body.memoryMode ?? null},
ipfs_cid = ${body.cid ?? sql`ipfs_cid`}
WHERE id = ${body.memoryId} AND agent_id = ${agent.id}
`;
}
const [updated] = await sql`SELECT memory_storage_mode FROM agent_identities WHERE id = ${agent.id}`;
return json(res, 200, { ok: true, storage_mode: updated.memory_storage_mode });
}
// ── POST /brain/import ──────────────────────────────────────────────────────
const importReq = z.object({
bundle: brainBundleSchema,
strategy: z.enum(['merge', 'replace']).default('merge'),
importPersona: z.boolean().default(false),
});
async function importBundle(req, res, agent, userId) {
const body = parse(importReq, await readJson(req));
const bundle = body.bundle;
// Reject a bundle that fails its own integrity check before it can
// reconstitute a broken or forged mind.
const verdict = verifyBundle(bundle);
if (!verdict.schemaValid) {
return error(res, 422, 'invalid_bundle', `bundle failed schema validation: ${verdict.errors.join('; ')}`);
}
if (!verdict.brainHashValid) {
return error(res, 422, 'integrity_failed', 'bundle brain_hash does not match its memory set');
}
if (verdict.bundleSignatureValid === false) {
return error(res, 422, 'integrity_failed', 'bundle signature failed verification');
}
// A forged plaintext memory (signed but tampered) is a hard reject.
const forged = verdict.memories.find((m) => m.signed && !m.valid && m.reason !== 'encrypted');
if (forged) {
return error(res, 422, 'integrity_failed', `memory ${forged.id} has an invalid signature (${forged.reason})`);
}
// Diff against the target agent's existing memories so a merge is idempotent
// and the response is a real, reviewable diff.
//
// Two hashes per row, and both are load-bearing. A row's own `content_hash` is
// the digest of THAT row (memoryDigest folds in the row id and created_at), so
// an imported copy hashes differently from the bundle entry it came from: on a
// re-import the source hash would miss every time and the merge would insert a
// fresh duplicate of every memory, forever. The source digest recorded in
// provenance at import time is the stable key across that boundary, so match on
// either.
const existing = await sql`
SELECT content_hash, context->'provenance'->>'source_content_hash' AS source_hash
FROM agent_memories
WHERE agent_id = ${agent.id}
AND (content_hash IS NOT NULL OR context->'provenance'->>'source_content_hash' IS NOT NULL)
`;
const existingHashes = new Set(
existing
.flatMap((r) => [r.content_hash, r.source_hash])
.filter(Boolean)
.map((h) => h.toLowerCase()),
);
if (body.strategy === 'replace') {
await sql`DELETE FROM agent_memories WHERE agent_id = ${agent.id}`;
existingHashes.clear();
}
// Only plaintext memories can be reconstituted here — encrypted entries
// require the owner's key client-side and are reported as skipped.
const toImport = bundle.memories.filter((m) => typeof m.content === 'string');
const skippedEncrypted = bundle.memories.length - toImport.length;
let imported = 0;
let duplicates = 0;
const newSignings = [];
for (const m of toImport) {
const hash = (m.content_hash || memoryDigest({ id: m.id, agent_id: bundle.agent.id, type: m.type, content: m.content, tags: m.tags, created_at: m.created_at })).toLowerCase();
if (existingHashes.has(hash)) {
duplicates++;
continue;
}
existingHashes.add(hash);
// Preserve the original authorship as provenance; the new agent re-signs
// for its own chain of custody (handled after insert). `source_content_hash`
// doubles as the dedupe key above, so record the digest actually matched on
// rather than the bundle's optional field: an entry that shipped without one
// would otherwise leave the next re-import nothing to match against.
const provenance = {
source_agent_id: bundle.agent.id,
source_memory_id: m.id,
source_content_hash: hash,
source_signature: m.signature || null,
source_signer_address: m.signer_address || null,
};
const [row] = await sql`
INSERT INTO agent_memories
(agent_id, type, content, tags, context, salience, tier, is_public, created_at)
VALUES (
${agent.id}, ${m.type}, ${String(m.content).slice(0, 10000)}, ${m.tags || []},
${JSON.stringify({ provenance })}::jsonb, ${m.salience ?? 0.5},
${m.tier || 'recall'}, ${m.is_public === true}, now()
)
RETURNING id, agent_id, type, content, tags, created_at
`;
imported++;
newSignings.push(row);
}
// Re-sign imported memories under the new agent's wallet (best-effort).
for (const row of newSignings) {
try {
await signMemoryWithAgent(row);
} catch (err) {
console.error('[brain] import re-sign failed', row.id, err?.message);
}
}
// Optionally adopt the source persona (only if the target has none, unless
// replace strategy). Persona prompt is signed with the platform HMAC the same
// way the persona extractor does — but we keep the source hash as provenance.
let personaImported = false;
if (body.importPersona && bundle.persona?.prompt) {
const adopt = body.strategy === 'replace' || !agent.persona_prompt_hash;
if (adopt) {
await sql`
UPDATE agent_identities
SET persona_prompt = ${bundle.persona.prompt},
persona_prompt_hash = ${bundle.persona.prompt_hash || null},
persona_tone_tags = ${JSON.stringify(bundle.persona.tone_tags || [])}::jsonb,
persona_extracted_at = now(),
updated_at = now()
WHERE id = ${agent.id}
`;
personaImported = true;
}
}
// Record provenance on the agent so the fork's lineage is legible.
const meta = { ...(agent.meta || {}) };
meta.brain_provenance = {
source_agent_id: bundle.agent.id,
source_agent_name: bundle.agent.name || null,
source_brain_hash: bundle.manifest.brain_hash,
imported_at: new Date().toISOString(),
imported_count: imported,
strategy: body.strategy,
};
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${agent.id}`;
return json(res, 200, {
ok: true,
imported,
duplicates,
skipped_encrypted: skippedEncrypted,
persona_imported: personaImported,
strategy: body.strategy,
provenance: meta.brain_provenance,
verification: { verifiedCount: verdict.verifiedCount, signedCount: verdict.signedCount },
});
}
export default function handler(req, res) {
const url = new URL(req.url, 'http://x');
const parts = url.pathname.split('/').filter(Boolean); // api agents :id brain [action]
return handleBrain(req, res, parts[2], parts[4]);
}