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(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.js
new file mode 100644
index 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].js
index 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/htt
import { 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 base64url
const 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.js
index 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();
}