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
fix(dev-proxy): stop decoding avatar GLB and thumbnail bytes as UTF-8
nirholas8720eeaa6775
diff --git a/api/_lib/x-scopes.js b/api/_lib/x-scopes.jsnew file mode 100644index 000000000..2b9be1158--- /dev/null+++ b/api/_lib/x-scopes.js@@ -0,0 +1,113 @@+/**+ * The X OAuth scope sets, and the guards that hold each lane to its own set.+ * ------------------------------------------------------------------------+ * Two very different things are called "connecting X" on this platform:+ *+ * posting : the agent writes to the owner's timeline (api/_lib/x-post.js,+ * api/share/x.js, the agent editor's Social tab). Needs write.+ * seeding : the owner's public posts are read once and distilled into agent+ * memory (api/agents/[id]/memory-seed-x.js). Needs read only.+ *+ * Asking for one authorization that covers both means an owner who only wants+ * their agent to sound like them has to hand over permission to post as them+ * first. The consent screen then promises "seeding only uses the read+ * permissions", which is true of the seeder and beside the point for the grant+ * the owner just signed. So the connect endpoint takes a scope set by name, the+ * seeding card asks for the read-only one, and each lane checks the connection+ * it is about to use actually carries the scopes it needs.+ *+ * `offline.access` is in both sets because it is what returns a refresh token;+ * without it a connection dies at the first token expiry and every lane starts+ * failing an hour after it was set up.+ */++/** Scope sets a connect request may ask for, by name. */+export const X_SCOPE_SETS = Object.freeze({+ /** Everything the platform's X surfaces use: read, post, and attach media. */+ full: Object.freeze(['tweet.read', 'tweet.write', 'users.read', 'media.write', 'offline.access']),+ /** Memory seeding's set: the profile and the timeline, nothing that writes. */+ read: Object.freeze(['tweet.read', 'users.read', 'offline.access']),+});++/** The default when a connect request names no set. */+export const X_DEFAULT_SCOPE_SET = 'full';++/** Reading the profile and recent posts: what the seeder calls. */+export const X_SEED_REQUIRED_SCOPES = Object.freeze(['tweet.read', 'users.read']);++/** Writing a post: what publishTweet calls. */+export const X_POST_REQUIRED_SCOPES = Object.freeze(['tweet.write']);++/**+ * Resolve a scope-set name from untrusted input (a query param) to the set+ * itself. An unknown or missing name resolves to the full set, so a typo can+ * never silently narrow what a posting surface asks for.+ *+ * @param {unknown} name+ * @returns {{name: string, scopes: readonly string[], value: string}}+ */+export function resolveScopeSet(name) {+ const key = typeof name === 'string' ? name.trim().toLowerCase() : '';+ const resolved = Object.prototype.hasOwnProperty.call(X_SCOPE_SETS, key)+ ? key+ : X_DEFAULT_SCOPE_SET;+ const scopes = X_SCOPE_SETS[resolved];+ return { name: resolved, scopes, value: scopes.join(' ') };+}++/**+ * The scopes X actually granted a connection, from the space-separated string+ * stored on social_connections.scopes.+ *+ * @param {unknown} raw+ * @returns {string[]}+ */+export function parseScopes(raw) {+ if (Array.isArray(raw)) return raw.filter((s) => typeof s === 'string' && s).map((s) => s.trim());+ return String(raw ?? '')+ .split(/[\s,]+/)+ .map((s) => s.trim())+ .filter(Boolean);+}++/**+ * Which of `required` a connection is missing.+ *+ * An empty granted list means "not recorded", not "granted nothing": every+ * connection made before the callback started storing scopes has one. Those are+ * reported as missing nothing, so a legacy connection keeps working and the+ * guard only ever refuses a connection whose recorded scopes really are too+ * narrow.+ *+ * @param {unknown} granted raw scopes column, or an array+ * @param {readonly string[]} required+ * @returns {string[]}+ */+export function missingScopes(granted, required) {+ const have = new Set(parseScopes(granted));+ if (!have.size) return [];+ return (required || []).filter((s) => !have.has(s));+}++/**+ * True when a connection's recorded scopes cover `required` (or are unrecorded).+ *+ * @param {unknown} granted+ * @param {readonly string[]} required+ */+export function hasScopes(granted, required) {+ return missingScopes(granted, required).length === 0;+}++/**+ * True when a connection is known to be read-only: its scopes are recorded and+ * do not include the write scope. Drives the UI copy that tells an owner why a+ * read-only connection cannot post, and which reconnect to offer.+ *+ * @param {unknown} granted+ */+export function isReadOnlyConnection(granted) {+ const have = parseScopes(granted);+ if (!have.length) return false;+ return !have.includes('tweet.write');+}diff --git a/api/auth/x/[action].js b/api/auth/x/[action].jsindex 876893608..409568e3e 100644--- a/api/auth/x/[action].js+++ b/api/auth/x/[action].js@@ -2,6 +2,11 @@// Env required: X_OAUTH_CLIENT_ID, X_OAUTH_CLIENT_SECRET// If unset, /connect returns 501 not_configured.//+// /connect takes an optional ?scope=read|full (default full, see+// api/_lib/x-scopes.js). The memory-seeding card asks for `read` so an owner who+// only wants their agent to sound like them never has to grant permission to+// post as them; the posting surfaces ask for `full`.+//// PKCE state ({code_verifier, user_id, agent_id}) is carried in a short-lived,// HMAC-signed httpOnly cookie keyed by the OAuth `state` param. No external// store needed; the cookie is sent back on the top-level redirect from x.com@@ -20,6 +25,7 @@ import { cors, method, wrap, error, redirect, rateLimited } from '../../_lib/httimport { limits, clientIp } from '../../_lib/rate-limit.js';import { env } from '../../_lib/env.js';import { revokeAllSeedConsentsForUser } from '../../_lib/x-seed-consent.js';+import { resolveScopeSet } from '../../_lib/x-scopes.js';// ── Signed-cookie PKCE state ─────────────────────────────────────────────────@@ -33,12 +39,13 @@ function b64urlDecode(s) {return Buffer.from(s, 'base64url').toString('utf8');}-async function signState({ state, codeVerifier, userId, agentId }) {+async function signState({ state, codeVerifier, userId, agentId, scopeSet }) {const payload = {s: state,v: codeVerifier,u: userId,a: agentId,+ k: scopeSet,e: Math.floor(Date.now() / 1000) + STATE_TTL_SEC,};const body = b64urlEncode(JSON.stringify(payload));@@ -62,7 +69,12 @@ async function verifyState(token, expectedState) {}if (!payload || payload.s !== expectedState) return null;if (typeof payload.e !== 'number' || payload.e < Math.floor(Date.now() / 1000)) return null;- return { codeVerifier: payload.v, userId: payload.u, agentId: payload.a };+ return {+ codeVerifier: payload.v,+ userId: payload.u,+ agentId: payload.a,+ scopeSet: resolveScopeSet(payload.k).name,+ };}function readStateCookie(req) {@@ -126,6 +138,7 @@ async function handleConnect(req, res) {const url = new URL(req.url, env.APP_ORIGIN);const agentId = url.searchParams.get('agent_id') || null;+ const scopeSet = resolveScopeSet(url.searchParams.get('scope'));const codeVerifier = randomToken(32); // 43-char base64urlconst codeChallenge = await sha256Base64Url(codeVerifier);@@ -138,9 +151,11 @@ async function handleConnect(req, res) {authUrl.searchParams.set('response_type', 'code');authUrl.searchParams.set('client_id', env.X_OAUTH_CLIENT_ID);authUrl.searchParams.set('redirect_uri', `${env.APP_ORIGIN}/api/auth/x/callback`);- // media.write lets a connected account upload screenshots / walk clips via the- // v2 media-upload endpoint (see api/share/x.js) before attaching them to a tweet.- authUrl.searchParams.set('scope', 'tweet.read tweet.write users.read media.write offline.access');+ // The full set's media.write lets a connected account upload screenshots /+ // walk clips via the v2 media-upload endpoint (see api/share/x.js) before+ // attaching them to a tweet. The read set drops every write scope: it is what+ // memory seeding needs and all it needs.+ authUrl.searchParams.set('scope', scopeSet.value);authUrl.searchParams.set('state', state);authUrl.searchParams.set('code_challenge', codeChallenge);authUrl.searchParams.set('code_challenge_method', 'S256');diff --git a/vite.config.js b/vite.config.jsindex 862a73626..2647d40a3 100644--- a/vite.config.js+++ b/vite.config.js@@ -2694,16 +2694,30 @@ support: resolve(__dirname, 'pages/support.html'),...(req.headers.authorization? { authorization: req.headers.authorization }: {}),+ ...(req.headers.range ? { range: req.headers.range } : {}),},});- const text = await resp.text();- const rewritten = text.replace(R2_PUBLIC_RE, '/r2-proxy/');+ const type = resp.headers.get('content-type') || 'application/json';res.statusCode = resp.status;- res.setHeader(- 'content-type',- resp.headers.get('content-type') || 'application/json',- );- res.end(rewritten);+ res.setHeader('content-type', type);+ // Not every /api/avatars/* GET is JSON: `/api/avatars/:id/glb` and+ // `/thumbnail` return binary (model/gltf-binary, image/*). Reading+ // those through resp.text() decodes them as UTF-8, so every byte+ // >= 0x80 becomes U+FFFD and the "GLB" that reaches the browser is+ // ~60% larger and unparseable ("THREE.GLTFLoader: JSON content not+ // found"), which silently demoted every studio/profile avatar to the+ // fallback robot in dev. Only text payloads can carry an r2.dev URL,+ // so rewrite those and pass anything else through byte-for-byte.+ if (!/^(application\/(json|.*\+json)|text\/)/i.test(type)) {+ for (const h of ['content-length', 'accept-ranges', 'content-range', 'etag', 'cache-control']) {+ const v = resp.headers.get(h);+ if (v) res.setHeader(h, v);+ }+ res.end(Buffer.from(await resp.arrayBuffer()));+ return;+ }+ const text = await resp.text();+ res.end(text.replace(R2_PUBLIC_RE, '/r2-proxy/'));} catch (err) {next();}