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
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.jsindex 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.jsindex 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.jsindex 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].jsindex 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 SETprovider_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_connectionsWHERE 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_connectionsWHERE 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.htmlindex 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;