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.

feat(x-scopes): refuse a lane its connection cannot serve, and name the missing scopes

nirholasff66b3e5dd13
diff --git a/api/_lib/x-post.js b/api/_lib/x-post.js
index 0201f585e..92c9e6e7b 100644
--- a/api/_lib/x-post.js
+++ b/api/_lib/x-post.js
@@ -5,6 +5,7 @@
import { sql } from './db.js';
import { env } from './env.js';
import { encryptToken, decryptToken } from '../auth/x/[action].js';
+import { X_POST_REQUIRED_SCOPES, missingScopes } from './x-scopes.js';
export const FREE_MONTHLY_QUOTA = 5;
export const PRO_MONTHLY_QUOTA = 100;
@@ -173,6 +174,19 @@ export async function publishTweet({ userId, agentId = null, text, threadParts =
const conn = rows[0];
if (!conn) throw new XPostError('not_connected', 'X account not connected', 400);
+ // A connection made for memory seeding only carries read scopes. Say so, and
+ // point at the reconnect that fixes it, instead of spending the user's quota
+ // check and cadence guard on a call X will reject as unauthorized.
+ const missingWrite = missingScopes(conn.scopes, X_POST_REQUIRED_SCOPES);
+ if (missingWrite.length) {
+ throw new XPostError(
+ 'insufficient_scope',
+ 'this X connection is read-only; reconnect X with posting access to publish',
+ 400,
+ { missing_scopes: missingWrite, connect_url: '/api/auth/x/connect?scope=full' },
+ );
+ }
+
// Reset monthly counter if month boundary crossed.
if (new Date(conn.month_resets_at) <= new Date()) {
await sql`
diff --git a/api/agents/[id]/memory-seed-x.js b/api/agents/[id]/memory-seed-x.js
index f67fe7117..ffa944b1a 100644
--- a/api/agents/[id]/memory-seed-x.js
+++ b/api/agents/[id]/memory-seed-x.js
@@ -31,6 +31,7 @@ import {
seedFromX,
} from '../../_lib/x-memory-seed.js';
import { revokeAgentSeedConsent } from '../../_lib/x-seed-consent.js';
+import { X_SEED_REQUIRED_SCOPES, missingScopes } from '../../_lib/x-scopes.js';
import { decryptToken, encryptToken } from '../../auth/x/[action].js';
// ── Token refresh ─────────────────────────────────────────────────────────────
@@ -184,12 +185,19 @@ async function handleGet(req, res, agentId) {
const conn = await loadConnection(user.id);
const state = consentState(await loadConsent(agentId), conn);
+ const missing = conn ? missingScopes(conn.scopes, X_SEED_REQUIRED_SCOPES) : [];
return json(res, 200, {
connected: !!conn,
configured: !!(env.X_OAUTH_CLIENT_ID && env.X_OAUTH_CLIENT_SECRET),
username: conn?.username ?? agent.x_username ?? null,
connection_scopes: conn?.scopes ?? null,
+ // What seeding needs from the connection, and what this one is short of,
+ // so the card can offer a reconnect instead of letting the owner consent
+ // to a seed that would fail at the X API.
+ required_scopes: X_SEED_REQUIRED_SCOPES,
+ missing_scopes: missing,
+ scopes_ok: missing.length === 0,
seeded_at: agent.x_seeded_at ?? null,
fact_count: await countSeededMemories(agentId),
scope_version: X_SEED_SCOPE_VERSION,
@@ -211,6 +219,20 @@ async function handlePost(req, res, agentId) {
const conn = await loadConnection(user.id);
if (!conn) return error(res, 400, 'not_connected', 'connect your X account first');
+ // A connection narrower than the read the disclosure describes cannot be
+ // seeded from. Refuse here, with the missing scopes named, rather than
+ // recording consent and then failing at the X API with an opaque 502.
+ const missing = missingScopes(conn.scopes, X_SEED_REQUIRED_SCOPES);
+ if (missing.length) {
+ return error(
+ res,
+ 400,
+ 'insufficient_scope',
+ 'this X connection cannot read your profile and posts; reconnect X to seed',
+ { required_scopes: X_SEED_REQUIRED_SCOPES, missing_scopes: missing },
+ );
+ }
+
const body = await readJson(req).catch(() => ({}));
const existing = await loadConsent(agentId);
let state = consentState(existing, conn);
diff --git a/public/settings/index.html b/public/settings/index.html
index a743bbbd5..b4b27bdd5 100644
--- a/public/settings/index.html
+++ b/public/settings/index.html
@@ -1155,9 +1155,10 @@
const el = document.getElementById('x-connect-status');
const msg = document.getElementById('x-msg');
try {
- const connectUrl = _xAgentId
- ? `/api/auth/x/connect?agent_id=${encodeURIComponent(_xAgentId)}`
- : '/api/auth/x/connect';
+ // Seeding reads; it never posts. This card asks X for the read-only
+ // scope set, so consenting to a memory seed never costs the owner
+ // permission to post as them.
+ const connectUrl = xConnectUrl(_xAgentId, 'read');
if (!_xAgentId) {
el.innerHTML = xCardHeader('Loading…');
@@ -1189,6 +1190,12 @@
return String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
}
+ function xConnectUrl(agentId, scope) {
+ const q = new URLSearchParams({ scope });
+ if (agentId) q.set('agent_id', agentId);
+ return `/api/auth/x/connect?${q.toString()}`;
+ }
+
function xCardHeader(meta) {
return `
<div class="provider-info">
@@ -1263,7 +1270,11 @@
if (!data.connected) {
el.innerHTML = xCardHeader('Not connected')
- + `<div class="actions"><a href="${connectUrl}" class="btn" style="font-size:12px;padding:5px 14px;text-decoration:none">Connect X</a></div>`;
+ + `<div class="actions" style="display:flex;gap:10px;align-items:center;flex-wrap:wrap">
+ <a href="${connectUrl}" class="btn" style="font-size:12px;padding:5px 14px;text-decoration:none">Connect X (read-only)</a>
+ <span class="muted" style="font-size:11.5px">Asks X only for read access to your profile and posts. It cannot post as you.</span>
+ </div>
+ <p class="muted" style="font-size:11.5px;margin:10px 0 0">Want this agent to post to X as well? <a href="${xConnectUrl(agentId, 'full')}" class="action">Connect with posting access</a>.</p>`;
return;
}
@@ -1272,6 +1283,24 @@
? `<p class="muted" style="font-size:11.5px;margin:10px 0 0">This connection holds the X permissions: ${escHtml(data.connection_scopes)}. Seeding only uses the read permissions listed above.</p>`
: '';
+ // A connection whose scopes cannot cover the read the disclosure
+ // describes can never produce a seed. Say so before the consent panel,
+ // so nobody agrees to something that would then fail at X.
+ if (data.scopes_ok === false) {
+ el.innerHTML = xCardHeader(`@${escHtml(data.username)} &middot; This connection cannot read your posts`)
+ + `<p class="muted" style="font-size:12.5px;margin:10px 0 0">Seeding needs the X permissions ${escHtml((data.required_scopes || []).join(', '))}, and this connection is missing ${escHtml((data.missing_scopes || []).join(', '))}. Reconnect to grant them. Nothing is read until you consent afterwards.</p>
+ <div class="actions" style="margin-top:10px"><a href="${connectUrl}" class="btn" style="font-size:12px;padding:5px 14px;text-decoration:none">Reconnect X (read-only)</a></div>${scopes}`;
+ return;
+ }
+
+ // Reconnecting keeps the shape of the grant the owner already made: a
+ // read-only connection stays read-only, rather than being quietly
+ // widened to posting access by a link labelled "Reconnect".
+ const reconnectUrl = xConnectUrl(
+ agentId,
+ String(data.connection_scopes || '').split(/\s+/).includes('tweet.write') ? 'full' : 'read',
+ );
+
if (!consent.granted) {
const why = consent.reason === 'scope_version_changed'
? 'What gets read and stored has changed since you last agreed. Review it again to keep seeding.'