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
// 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, readJson, wrap, rateLimited } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { env } from '../../_lib/env.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';
import { fetchUpstream } from '../../_lib/upstream-fetch.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) ─────────────────────────────────────────
async function makeState(payload) {
const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
const sig = await hmacSha256(env.JWT_SECRET, data);
return `${data}.${sig}`;
}
async function verifyState(state) {
const dotIdx = state.lastIndexOf('.');
if (dotIdx < 0) throw Object.assign(new Error('invalid state'), { status: 400 });
const data = state.slice(0, dotIdx);
const sig = state.slice(dotIdx + 1);
const expected = await hmacSha256(env.JWT_SECRET, data);
if (!constantTimeEquals(sig, expected)) throw Object.assign(new Error('invalid state signature'), { status: 400 });
return JSON.parse(Buffer.from(data, 'base64url').toString());
}
// ── connect ───────────────────────────────────────────────────────────────────
async function handleConnect(req, res) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
if (!env.GITHUB_OAUTH_CLIENT_ID) {
return error(res, 501, 'not_configured', 'GitHub OAuth is not configured');
}
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');
const url = new URL(req.url, 'http://x');
const agentId = url.searchParams.get('agent_id') || '';
const state = await makeState({ userId: session.id, agentId, ts: Date.now() });
const redirectUri = `${env.APP_ORIGIN}/api/auth/github/callback`;
const ghUrl = new URL('https://github.com/login/oauth/authorize');
ghUrl.searchParams.set('client_id', env.GITHUB_OAUTH_CLIENT_ID);
ghUrl.searchParams.set('redirect_uri', redirectUri);
ghUrl.searchParams.set('scope', 'read:user,public_repo');
ghUrl.searchParams.set('state', state);
return redirect(res, ghUrl.toString());
}
// ── callback ──────────────────────────────────────────────────────────────────
async function handleCallback(req, res) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
// The IdP sends the user back here as a top-level GET navigation. Anything
// else is not the OAuth flow, and the preflight above already says so.
if (!method(req, res, ['GET'])) return;
if (!env.GITHUB_OAUTH_CLIENT_ID || !env.GITHUB_OAUTH_CLIENT_SECRET) {
return error(res, 501, 'not_configured', 'GitHub OAuth is not configured');
}
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
const code = url.searchParams.get('code');
const stateParam = url.searchParams.get('state');
const ghError = url.searchParams.get('error');
if (ghError) {
return redirect(res, `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=denied`);
}
if (!code || !stateParam) return error(res, 400, 'bad_request', 'missing code or state');
let stateData;
try {
stateData = await verifyState(stateParam);
} catch {
return error(res, 400, 'invalid_state', 'invalid or tampered state parameter');
}
if (Date.now() - stateData.ts > 10 * 60 * 1000) {
return error(res, 400, 'state_expired', 'OAuth state has expired — please try again');
}
// Session-bind, and require the session. The state is a signed token, not a
// browser-bound one, so without this an attacker could start a connect on
// their own account and hand the GitHub link to a signed-out victim who has
// authorized the app before: GitHub redirects silently, and the victim's
// token would land on the attacker's account. The flow starts from a signed-in
// page and returns as a top-level GET, so the SameSite=Lax cookie is present
// on every legitimate callback.
const callbackSession = await getSessionUser(req).catch(() => null);
if (!callbackSession) {
return redirect(res, `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=error`);
}
if (callbackSession.id !== stateData.userId) {
return error(res, 403, 'session_mismatch', 'OAuth state does not match the current session');
}
// Exchange code for access token
const tokenRes = await fetchUpstream('https://github.com/login/oauth/access_token', {
method: 'POST',
headers: { accept: 'application/json', 'content-type': 'application/json' },
body: JSON.stringify({
client_id: env.GITHUB_OAUTH_CLIENT_ID,
client_secret: env.GITHUB_OAUTH_CLIENT_SECRET,
code,
redirect_uri: `${env.APP_ORIGIN}/api/auth/github/callback`,
}),
}, { name: 'github', timeoutMs: 10_000, attempts: 1, okWhen: () => true });
if (!tokenRes.ok) {
return redirect(res, `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=error`);
}
const tokenData = await tokenRes.json();
if (tokenData.error || !tokenData.access_token) {
return redirect(res, `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=error`);
}
// Fetch GitHub user profile
const profileRes = await fetchUpstream('https://api.github.com/user', {
headers: {
authorization: `token ${tokenData.access_token}`,
'user-agent': 'three.ws/1.0',
},
}, { name: 'github', timeoutMs: 10_000, attempts: 2, okWhen: () => true });
if (!profileRes.ok) {
return redirect(res, `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=error`);
}
const profile = await profileRes.json();
const encryptedToken = await encryptGithubToken(tokenData.access_token);
await sql`
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'},
${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()
`;
const dest = stateData.agentId
? `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=connected&agent_id=${encodeURIComponent(stateData.agentId)}`
: `${env.APP_ORIGIN}/settings?tab=connected-accounts&github=connected`;
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) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const session = await getSessionUser(req);
if (!session) return error(res, 401, 'unauthorized', 'sign in required');
// Whether this deployment has a GitHub OAuth app at all. Without it every
// connect click lands on a raw 501 from /connect, so the card needs to know
// 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, raw_data FROM social_connections
WHERE user_id = ${session.id} AND provider = 'github'
`;
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
FROM agent_memories m
JOIN agent_identities a ON a.id = m.agent_id
WHERE a.user_id = ${session.id} AND m.context->>'source' = 'github_seed'
`;
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. 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;
if (!method(req, res, ['POST', 'DELETE'])) return;
const session = await getSessionUser(req);
if (!session) return error(res, 401, 'unauthorized', 'sign in required');
const [row] = await sql`
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`
DELETE FROM agent_memories
WHERE context->>'source' = 'github_seed'
AND agent_id IN (SELECT id FROM agent_identities WHERE user_id = ${session.id})
RETURNING id
`,
sql`DELETE FROM social_connections WHERE id = ${row.id}`,
]);
// 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. 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 (method_ === 'oauth' && env.GITHUB_OAUTH_CLIENT_ID && env.GITHUB_OAUTH_CLIENT_SECRET) {
try {
const token = await decryptGithubToken(row.access_token);
revoked = await revokeGrant(
token,
env.GITHUB_OAUTH_CLIENT_ID,
env.GITHUB_OAUTH_CLIENT_SECRET,
);
} catch (e) {
console.error('[auth/github] grant revoke failed', e?.message);
}
}
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,
});
}
// ── dispatch ──────────────────────────────────────────────────────────────────
export default wrap(async (req, res) => {
const url = new URL(req.url, 'http://x');
const action = url.searchParams.get('action') || url.pathname.split('/').filter(Boolean).pop();
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');
});