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(github-auth): accept a personal access token and report what its scopes allow

nirholas88e6594ec942
diff --git a/api/_lib/draft-mint.js b/api/_lib/draft-mint.js
index 56e392e5c..7e78c483c 100644
--- a/api/_lib/draft-mint.js
+++ b/api/_lib/draft-mint.js
@@ -89,7 +89,7 @@ function alreadyMintedOn(meta, network) {
return !!meta?.devnet?.sol_mint_address;
}
-async function solanaDraftMint({ agent, network }) {
+export async function solanaDraftMint({ agent, network }) {
if (alreadyMintedOn(agent.meta, network)) {
const asset =
network === 'mainnet' ? agent.meta.sol_mint_address : agent.meta.devnet.sol_mint_address;
@@ -180,7 +180,7 @@ async function pinDraftCard(card, agentId) {
return publicUrl(key);
}
-async function evmDraftMint({ agent, userId, chainId }) {
+export async function evmDraftMint({ agent, userId, chainId }) {
const { CHAIN_BY_ID } = await import('./erc8004-chains.js');
const chain = CHAIN_BY_ID[chainId];
if (!chain) return { status: 'skipped', reason: 'unsupported_chain', chainId };
@@ -308,7 +308,7 @@ async function evmDraftMint({ agent, userId, chainId }) {
chainId,
chain: chain.name,
registry: chain.registry,
- onchainId,
+ onchainId: onChainId,
owner: evmAddress,
txHash: receipt.hash,
metadataUri,
diff --git a/api/_lib/github-api.js b/api/_lib/github-api.js
index 2b3db2428..64dccad3f 100644
--- a/api/_lib/github-api.js
+++ b/api/_lib/github-api.js
@@ -35,6 +35,26 @@ export function fetchProfile(token) {
return ghJson('/user', token);
}
+/**
+ * Check a token the user pasted and report back what it can do. Returns the
+ * profile it belongs to plus the raw `x-oauth-scopes` header, which is the only
+ * place GitHub states a classic PAT's grants (fine-grained tokens omit it, so
+ * the header comes back null). A token GitHub rejects returns `valid: false`
+ * rather than throwing, because a mistyped paste is a user error to explain, not
+ * an upstream outage to report.
+ */
+export async function verifyToken(token) {
+ const res = await fetch(`${API}/user`, {
+ headers: headers(token),
+ signal: AbortSignal.timeout(TIMEOUT_MS),
+ });
+ if (res.status === 401 || res.status === 403) return { valid: false, status: res.status };
+ if (!res.ok) throw upstream(`GitHub token check failed: ${res.status}`);
+ const profile = await res.json();
+ if (!profile?.login) return { valid: false, status: res.status };
+ return { valid: true, status: res.status, profile, scopeHeader: res.headers.get('x-oauth-scopes') };
+}
+
/** Public repos the user owns, most recently pushed first. */
export function fetchRepos(token, perPage = 40) {
return ghJson(
diff --git a/api/_lib/github-token.js b/api/_lib/github-token.js
index f9e4037a8..d4e6686fd 100644
--- a/api/_lib/github-token.js
+++ b/api/_lib/github-token.js
@@ -1,4 +1,4 @@
-// Encryption for stored GitHub OAuth access tokens.
+// Encryption and scope policy for stored GitHub access tokens.
//
// The key is derived from JWT_SECRET with HKDF-SHA256 and the fixed salt
// 'github-token', so a rotated JWT_SECRET invalidates stored tokens (the user
@@ -6,6 +6,9 @@
// definition of that derivation: the OAuth callback, the seeding endpoints, and
// disconnect all import it, so the salt can never drift between writer and
// reader.
+//
+// It also owns the scope policy for the personal-access-token connect path,
+// which is the route in when a deployment has no GitHub OAuth app registered.
import { webcrypto } from 'node:crypto';
import { env } from './env.js';
@@ -53,3 +56,62 @@ export async function decryptGithubToken(ciphertext) {
const plain = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
return new TextDecoder().decode(plain);
}
+
+// ── Personal access token policy ──────────────────────────────────────────────
+
+/**
+ * Classic-PAT scopes this platform will hold. Seeding reads a public profile,
+ * public repositories, and their READMEs, so nothing beyond the user surface and
+ * public repository data is ever needed. The list is an allowlist rather than a
+ * denylist on purpose: a scope GitHub invents after this code is written is
+ * refused by default instead of being silently accepted.
+ *
+ * `repo` is deliberately absent. It grants read AND write on private
+ * repositories, and the catalog is public-only by construction, so a token
+ * carrying it would hand us far more access than the feature can ever use.
+ */
+export const ALLOWED_TOKEN_SCOPES = Object.freeze([
+ 'read:user',
+ 'user:email',
+ 'user:follow',
+ 'user',
+ 'public_repo',
+ 'repo:status',
+ 'read:org',
+]);
+
+/** The scopes we ask people to tick, in the order the docs list them. */
+export const RECOMMENDED_TOKEN_SCOPES = Object.freeze(['read:user']);
+
+/**
+ * Decide whether a token GitHub just accepted is one we are willing to store.
+ *
+ * GitHub reports a classic PAT's grants in the `x-oauth-scopes` response header.
+ * Fine-grained tokens and GitHub App user tokens omit the header entirely: their
+ * permissions were already narrowed by the person who minted them, and there is
+ * no scope string to audit, so they are accepted as-is.
+ *
+ * @param {string|null|undefined} header raw `x-oauth-scopes` response header
+ * @returns {{kind: 'fine_grained'|'classic', scopes: string[], allowed: boolean, refused: string[]}}
+ */
+export function classifyTokenScopes(header) {
+ if (header == null) return { kind: 'fine_grained', scopes: [], allowed: true, refused: [] };
+
+ const scopes = String(header)
+ .split(',')
+ .map((s) => s.trim())
+ .filter(Boolean);
+ const refused = scopes.filter((s) => !ALLOWED_TOKEN_SCOPES.includes(s));
+ return { kind: 'classic', scopes, allowed: refused.length === 0, refused };
+}
+
+/**
+ * Shape-check a pasted token before spending a GitHub round trip on it. This
+ * only rejects input that cannot be a token at all (blank, containing
+ * whitespace, absurdly long); GitHub itself is the authority on validity.
+ */
+export function looksLikeGithubToken(value) {
+ if (typeof value !== 'string') return false;
+ const token = value.trim();
+ return token.length >= 20 && token.length <= 255 && !/\s/.test(token);
+}
diff --git a/api/auth/github/[action].js b/api/auth/github/[action].js
index 3ddcd1e3c..2ecc9aaf5 100644
--- a/api/auth/github/[action].js
+++ b/api/auth/github/[action].js
@@ -1,18 +1,37 @@
-// GitHub OAuth social connect.
+// GitHub social connect.
// Routes: /api/auth/github/connect — redirect to GitHub OAuth
// /api/auth/github/callback — exchange code, store encrypted token
+// /api/auth/github/token : connect with a personal access token
// /api/auth/github/status — connection status for the signed-in user
// /api/auth/github/disconnect — revoke the grant and delete every memory
// seeded from GitHub across the user's agents
+//
+// There are two ways in, and both land on the same encrypted row that the
+// seeding endpoints read. OAuth is the nicer one, but it only exists on a
+// deployment whose operator registered a GitHub OAuth app. The token path needs
+// nothing provisioned, so self-hosters and this platform's users are never left
+// with a Connect button that can only produce an error page.
import { sql } from '../../_lib/db.js';
import { getSessionUser } from '../../_lib/auth.js';
+import { requireCsrf } from '../../_lib/csrf.js';
import { hmacSha256, constantTimeEquals } from '../../_lib/crypto.js';
-import { cors, json, redirect, error, method, wrap, rateLimited } from '../../_lib/http.js';
+import { cors, json, redirect, error, method, readJson, wrap, rateLimited } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { env } from '../../_lib/env.js';
-import { encryptGithubToken, decryptGithubToken } from '../../_lib/github-token.js';
-import { revokeGrant } from '../../_lib/github-api.js';
+import {
+ encryptGithubToken,
+ decryptGithubToken,
+ classifyTokenScopes,
+ looksLikeGithubToken,
+ ALLOWED_TOKEN_SCOPES,
+ RECOMMENDED_TOKEN_SCOPES,
+} from '../../_lib/github-token.js';
+import { revokeGrant, verifyToken } from '../../_lib/github-api.js';
+
+/** Where to send someone to mint a token with exactly the grants we accept. */
+const TOKEN_CREATE_URL = `https://github.com/settings/tokens/new?description=three.ws%20agent%20memory&scopes=${RECOMMENDED_TOKEN_SCOPES.join(',')}`;
+const TOKEN_MANAGE_URL = 'https://github.com/settings/tokens';
// ── CSRF state (HMAC-signed payload) ─────────────────────────────────────────
@@ -140,20 +159,22 @@ async function handleCallback(req, res) {
const encryptedToken = await encryptGithubToken(tokenData.access_token);
await sql`
- INSERT INTO social_connections (user_id, provider, provider_uid, username, access_token, scopes)
+ INSERT INTO social_connections (user_id, provider, provider_uid, username, access_token, scopes, raw_data)
VALUES (
${stateData.userId},
'github',
${String(profile.id)},
${profile.login},
${encryptedToken},
- ${tokenData.scope || 'read:user,public_repo'}
+ ${tokenData.scope || 'read:user,public_repo'},
+ ${JSON.stringify({ connect_method: 'oauth' })}::jsonb
)
ON CONFLICT (user_id, provider) DO UPDATE SET
provider_uid = EXCLUDED.provider_uid,
username = EXCLUDED.username,
access_token = EXCLUDED.access_token,
scopes = EXCLUDED.scopes,
+ raw_data = EXCLUDED.raw_data,
connected_at = now()
`;
@@ -164,6 +185,99 @@ async function handleCallback(req, res) {
return redirect(res, dest);
}
+// ── token connect ─────────────────────────────────────────────────────────────
+
+/**
+ * Connect with a personal access token instead of OAuth.
+ *
+ * This exists because OAuth is not always available: it needs an operator to
+ * register a GitHub OAuth app and put its client id and secret on the service,
+ * and until that happens /connect can only answer 501. A token needs nothing
+ * provisioned on our side, so the consent flow, the catalog, the seed, and the
+ * revoke all work on any deployment.
+ *
+ * Consent is at least as explicit as the OAuth screen: the user mints the token
+ * themselves on GitHub, choosing its grants, and we refuse to store one carrying
+ * access the feature cannot use (see ALLOWED_TOKEN_SCOPES). What the token is
+ * then allowed to read is still narrowed twice more downstream, by the
+ * public-only catalog and by the tick-boxes the user sets on it.
+ */
+async function handleTokenConnect(req, res) {
+ if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
+ if (!method(req, res, ['POST'])) return;
+
+ const rl = await limits.authIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const session = await getSessionUser(req);
+ if (!session) return error(res, 401, 'unauthorized', 'sign in required');
+ if (!(await requireCsrf(req, res, session.id))) return;
+
+ const body = (await readJson(req)) ?? {};
+ const token = typeof body.token === 'string' ? body.token.trim() : '';
+ if (!looksLikeGithubToken(token)) {
+ return error(res, 400, 'validation_error', 'paste a GitHub personal access token', {
+ create_url: TOKEN_CREATE_URL,
+ });
+ }
+
+ const check = await verifyToken(token);
+ if (!check.valid) {
+ return error(res, 400, 'invalid_token', 'GitHub rejected that token. Check it was copied in full and has not expired', {
+ create_url: TOKEN_CREATE_URL,
+ });
+ }
+
+ const scopeInfo = classifyTokenScopes(check.scopeHeader);
+ if (!scopeInfo.allowed) {
+ // Refusing here is the whole point: a token that can write to or read
+ // private repositories is more access than seeding will ever use, and
+ // storing it anyway would make the privacy promise on this feature false.
+ return error(
+ res,
+ 400,
+ 'token_scope_refused',
+ `that token carries ${scopeInfo.refused.join(', ')}, which is more access than memory seeding needs. Create one with ${RECOMMENDED_TOKEN_SCOPES.join(', ')} instead`,
+ {
+ refused_scopes: scopeInfo.refused,
+ allowed_scopes: ALLOWED_TOKEN_SCOPES,
+ create_url: TOKEN_CREATE_URL,
+ },
+ );
+ }
+
+ const encryptedToken = await encryptGithubToken(token);
+ const [row] = await sql`
+ INSERT INTO social_connections (user_id, provider, provider_uid, username, access_token, scopes, raw_data)
+ VALUES (
+ ${session.id},
+ 'github',
+ ${String(check.profile.id)},
+ ${check.profile.login},
+ ${encryptedToken},
+ ${scopeInfo.scopes.join(',')},
+ ${JSON.stringify({ connect_method: 'token', token_kind: scopeInfo.kind })}::jsonb
+ )
+ ON CONFLICT (user_id, provider) DO UPDATE SET
+ provider_uid = EXCLUDED.provider_uid,
+ username = EXCLUDED.username,
+ access_token = EXCLUDED.access_token,
+ scopes = EXCLUDED.scopes,
+ raw_data = EXCLUDED.raw_data,
+ connected_at = now()
+ RETURNING username, connected_at
+ `;
+
+ return json(res, 200, {
+ connected: true,
+ connect_method: 'token',
+ token_kind: scopeInfo.kind,
+ username: row.username,
+ connected_at: row.connected_at,
+ scopes: scopeInfo.scopes,
+ });
+}
+
// ── status ────────────────────────────────────────────────────────────────────
async function handleStatus(req, res) {
@@ -178,12 +292,22 @@ async function handleStatus(req, res) {
// before it renders a button that cannot work.
const configured = Boolean(env.GITHUB_OAUTH_CLIENT_ID && env.GITHUB_OAUTH_CLIENT_SECRET);
+ // The token path needs nothing provisioned, so it is always on offer. The
+ // card reads this to decide whether an unconfigured deployment is a dead end
+ // (it is not) or simply one where pasting a token is the way in.
+ const tokenConnect = {
+ available: true,
+ create_url: TOKEN_CREATE_URL,
+ recommended_scopes: RECOMMENDED_TOKEN_SCOPES,
+ };
+
const [row] = await sql`
- SELECT username, connected_at FROM social_connections
+ SELECT username, connected_at, raw_data FROM social_connections
WHERE user_id = ${session.id} AND provider = 'github'
`;
- if (!row) return json(res, 200, { connected: false, configured, seeded_fact_count: 0 });
+ if (!row)
+ return json(res, 200, { connected: false, configured, token_connect: tokenConnect, seeded_fact_count: 0 });
const [seeded] = await sql`
SELECT count(*)::int AS n
@@ -195,19 +319,40 @@ async function handleStatus(req, res) {
return json(res, 200, {
connected: true,
configured,
+ token_connect: tokenConnect,
+ // Rows written before the token path existed carry no marker, and OAuth
+ // was the only way they could have been created.
+ connect_method: connectMethod(row.raw_data),
username: row.username,
connected_at: row.connected_at,
seeded_fact_count: seeded?.n ?? 0,
});
}
+/** Read the connect method off a stored row, defaulting pre-token rows to oauth. */
+function connectMethod(rawData) {
+ const parsed = typeof rawData === 'string' ? safeParse(rawData) : rawData;
+ return parsed?.connect_method === 'token' ? 'token' : 'oauth';
+}
+
+function safeParse(text) {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
// ── disconnect ────────────────────────────────────────────────────────────────
/**
* Revocation is not just "forget the token". Everything the connection was used
* to learn goes with it: every memory seeded from GitHub, on every agent this
- * user owns, is deleted in the same transaction that drops the connection. The
- * grant is also revoked on GitHub's side so the token stops working there too.
+ * user owns, is deleted in the same transaction that drops the connection. An
+ * OAuth grant is also revoked on GitHub's side so the token stops working there
+ * too. A pasted personal access token cannot be revoked through the API by the
+ * token itself, so that case reports honestly and hands back the page where the
+ * user can delete it.
*/
async function handleDisconnect(req, res) {
if (cors(req, res, { methods: 'POST,DELETE,OPTIONS', credentials: true })) return;
@@ -217,10 +362,11 @@ async function handleDisconnect(req, res) {
if (!session) return error(res, 401, 'unauthorized', 'sign in required');
const [row] = await sql`
- SELECT id, access_token FROM social_connections
+ SELECT id, access_token, raw_data FROM social_connections
WHERE user_id = ${session.id} AND provider = 'github'
`;
if (!row) return json(res, 200, { disconnected: false, memories_deleted: 0 });
+ const method_ = connectMethod(row.raw_data);
const [deleted] = await sql.transaction([
sql`
@@ -233,9 +379,12 @@ async function handleDisconnect(req, res) {
]);
// GitHub-side revocation is best effort: the local grant is already gone, and
- // a GitHub outage must not leave the user's memories un-deleted.
+ // a GitHub outage must not leave the user's memories un-deleted. It also only
+ // applies to OAuth: GitHub exposes no way to delete a personal access token
+ // using that same token, so pretending to try one would only produce a
+ // misleading `grant_revoked: false`.
let revoked = false;
- if (env.GITHUB_OAUTH_CLIENT_ID && env.GITHUB_OAUTH_CLIENT_SECRET) {
+ if (method_ === 'oauth' && env.GITHUB_OAUTH_CLIENT_ID && env.GITHUB_OAUTH_CLIENT_SECRET) {
try {
const token = await decryptGithubToken(row.access_token);
revoked = await revokeGrant(
@@ -250,8 +399,12 @@ async function handleDisconnect(req, res) {
return json(res, 200, {
disconnected: true,
+ connect_method: method_,
memories_deleted: deleted.length,
grant_revoked: revoked,
+ // Only meaningful for a pasted token: the copy we held is destroyed, but
+ // the token still exists on GitHub until the user deletes it there.
+ revoke_url: method_ === 'token' ? TOKEN_MANAGE_URL : null,
});
}
@@ -263,6 +416,7 @@ export default wrap(async (req, res) => {
if (action === 'connect') return handleConnect(req, res);
if (action === 'callback') return handleCallback(req, res);
+ if (action === 'token') return handleTokenConnect(req, res);
if (action === 'status') return handleStatus(req, res);
if (action === 'disconnect') return handleDisconnect(req, res);
return error(res, 404, 'not_found', 'unknown github auth action');
diff --git a/public/settings/index.html b/public/settings/index.html
index b4b27bdd5..5ce5039dc 100644
--- a/public/settings/index.html
+++ b/public/settings/index.html
@@ -1155,11 +1155,6 @@
const el = document.getElementById('x-connect-status');
const msg = document.getElementById('x-msg');
try {
- // 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…');
// Seeding always targets one agent. With no ?agent_id= in the
@@ -1167,13 +1162,13 @@
// usable from a bare /settings visit.
const agentId = (await loadMyAgents())[0]?.id ?? null;
if (agentId) {
- renderXStatus(el, agentId, connectUrl);
+ renderXStatus(el, agentId);
} else {
el.innerHTML = xCardHeader('Create an agent to seed its memory from X')
+ '<div class="actions"><a href="/create" class="btn sec" style="font-size:12px;padding:5px 14px;text-decoration:none">Create an agent</a></div>';
}
} else {
- renderXStatus(el, _xAgentId, connectUrl);
+ renderXStatus(el, _xAgentId);
}
} catch {
el.innerHTML = '<p class="muted" style="font-size:14px">Could not load connection status.</p>';
@@ -1250,15 +1245,19 @@
return `${data.fact_count} seeded ${data.fact_count === 1 ? 'memory' : 'memories'}, last refreshed ${when}.`;
}
- async function renderXStatus(el, agentId, connectUrl) {
+ async function renderXStatus(el, agentId) {
const msg = document.getElementById('x-msg');
+ // 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(agentId, 'read');
let data;
try {
data = await apiJson(`/api/agents/${agentId}/memory/seed/x`);
} catch (e) {
el.innerHTML = xCardHeader('Could not load status')
+ `<div class="actions"><button class="btn sec" id="x-retry-btn">Retry</button></div>`;
- document.getElementById('x-retry-btn')?.addEventListener('click', () => renderXStatus(el, agentId, connectUrl));
+ document.getElementById('x-retry-btn')?.addEventListener('click', () => renderXStatus(el, agentId));
return;
}
@@ -1323,7 +1322,7 @@
body: JSON.stringify({ consent: { accepted: true, scope_version: data.scope_version } }),
});
showMsg(msg, 'ok', `Seeded ${res.seeded} ${res.seeded === 1 ? 'memory' : 'memories'} from ${res.posts_read} posts by @${res.username}. ${res.in_context} stay in the agent's live context.`);
- renderXStatus(el, agentId, connectUrl);
+ renderXStatus(el, agentId);
} catch (e) {
showMsg(msg, 'err', e.data?.error_description || 'Seeding failed.');
grant.disabled = false;
@@ -1337,7 +1336,7 @@
+ `<div class="actions" style="display:flex;gap:8px;align-items:center;flex-wrap:wrap">
<button class="btn sec" id="x-seed-btn">Re-seed</button>
<button class="btn danger" id="x-revoke-btn">Revoke and delete</button>
- <a href="${connectUrl}" class="action" style="font-size:12.5px">Reconnect</a>
+ <a href="${reconnectUrl}" class="action" style="font-size:12.5px">Reconnect</a>
</div>
<p class="muted" style="font-size:11.5px;margin:10px 0 0">Consented ${escHtml(new Date(consent.granted_at).toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' }))} to disclosure ${escHtml(consent.scope_version)}. Re-seeding replaces the previous batch; revoking deletes every one of them.</p>${scopes}`;
@@ -1350,7 +1349,7 @@
method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}',
});
showMsg(msg, 'ok', `Re-seeded ${res.seeded} ${res.seeded === 1 ? 'memory' : 'memories'} from ${res.posts_read} posts by @${res.username}.`);
- renderXStatus(el, agentId, connectUrl);
+ renderXStatus(el, agentId);
} catch (e) {
showMsg(msg, 'err', e.data?.error_description || 'Seeding failed.');
btn.disabled = false;
@@ -1366,7 +1365,7 @@
try {
const res = await apiJson(`/api/agents/${agentId}/memory/seed/x`, { method: 'DELETE' });
showMsg(msg, 'ok', `Consent revoked. ${res.deleted} seeded ${res.deleted === 1 ? 'memory' : 'memories'} deleted.`);
- renderXStatus(el, agentId, connectUrl);
+ renderXStatus(el, agentId);
} catch (e) {
showMsg(msg, 'err', e.data?.error_description || 'Revoke failed.');
btn.disabled = false;