// An app's server's sessions at HUD, for the browsers it draws pages for: // each browser's accounts (accounts.ts), HUD's tokens for each sealed in // one HttpOnly cookie (seal.ts) that only the server opens, signed in to // as an MCP client of HUD (oauth.ts). The host makes one `Sessions` with // its configuration, and for each request a `Hud` (`request`): the // request's way to HUD as the account in use, and the endpoints the // shell's pages reach (the host routes each to it): signing in and its // callback, signing out, switching accounts, the pages' tool calls and // uploads. // // Sealed in the cookie rather than kept in a store, so the server holds // nothing a restart or a rollback loses and needs no volume: five // accounts' tokens (two opaque 43-character tokens, a DID, the client's // ID and a time each) seal to under 2 KB, well within a cookie's 4 KB, // which `fit` holds it to whatever they are. A session ends when its // tokens do, or at sign-out, when its refresh token is revoked at HUD. // What a row of the accounts shows (a name, a handle, a picture) is read // with the account's own tokens, as the frame's `account.picture` says, // and kept in memory a while, by DID, never in the cookie. // // `__Host-` keeps each cookie to the app's origin over https, at `/`. The // pending sign-in's lasts its ten minutes; the accounts' as long as a // refresh token (30 days from its last rotation), written again at each. // The account's scheme is no secret, but kept the same way; it is read // only beside a session, and let go as the account in use changes. // // No mixing: a page is drawn as one account, start to end. Where HUD // refuses the account in use partway through a request, the rest of the // request is drawn signed out, and the next as the account the cookie // then has in use. Switching, adding or signing out, the shell loads the // page anew, so nothing of the account before (its screens remembered, // what was read ahead, its counts, an open form) is drawn again. import type { ToolResult } from '@hud/shared/result'; import { added, fit, keptOf, removed, renewed, used, type Kept } from './accounts'; import { at, type App } from './app'; import { SignInNeeded, toolRequest, toolResult } from './client'; import { SignIn, type Pending, type Session, type SignInConfig } from './oauth'; import { same } from './routes'; import { Seal } from './seal'; import type { Caller } from './server'; import { schemeIn, schemeOf } from './theme'; /** A request's cookies, as a host's server reads and sets them (SvelteKit's `cookies`). */ export type Cookies = { get(name: string): string | undefined; set(name: string, value: string, options: { path: string; httpOnly?: boolean; secure?: boolean; sameSite?: 'lax'; maxAge?: number }): void; delete(name: string, options: { path: string; secure?: boolean }): void; }; /** What the server's sessions are kept with. */ export type SessionsConfig = SignInConfig & { /** The secret the cookies are sealed with: at least 32 characters; null under a dev server, a key made per run. Changing it signs everyone out. */ secret: string | null; /** What the seal's key is derived with beside the secret; changing it signs everyone out. */ salt: string; /** The start of the cookies' names: `__Host--session`, `__Host--signin`, `-scheme`. */ prefix: string; }; /** One account the browser is signed in to, as a row of the accounts shows it. */ export type AccountRow = { did: string; handle: string | null; name: string | null; picture: string | null }; /** The browser's accounts: the rows, in the order they were added, and the one in use. */ export type AccountsData = { list: AccountRow[]; current: string }; /** How long a call to HUD may take before the page gives up on it. */ const WAIT = 15_000; /** How long before its access token lapses a session is refreshed, so a page's calls, streamed ones too, carry a live one. */ const EARLY = 60_000; const SESSION_LIFE = 30 * 86_400; const SIGNIN_LIFE = 600; /** How long a row of the accounts is kept, and how many. */ const ROW_LIFE = 10 * 60_000; const ROWS_MAX = 1000; /** Handles resolved, how many and how long. */ const DIDS_MAX = 10_000; const DID_LIFE = 10 * 60_000; const NO_STORE = { 'cache-control': 'private, no-store' }; const options = (maxAge: number) => ({ path: '/', httpOnly: true, secure: true, sameSite: 'lax' as const, maxAge }); /** A row of the accounts from the account's own answer to the frame's picture call: its name, handle and picture where the frame says where they are. */ function rowOf(did: string, answer: unknown, app: App): AccountRow { const shown = app.frame?.account?.picture; const text = (path: string | undefined) => { const found = path ? at(answer, path) : undefined; return typeof found === 'string' && found !== '' ? found : null; }; const picture = text(shown?.at); return { did, name: text(shown?.name), handle: text(shown?.handle), picture: picture?.startsWith('https://') ? picture : null }; } export class Sessions { readonly signIn: SignIn; readonly seal: Seal; readonly names: { session: string; signIn: string; scheme: string }; readonly #config: SessionsConfig; /** Each account's row, by DID, and until when it is drawn without being read again. */ readonly rows = new Map(); /** Handles resolved: a handle in a URL is resolved once in a while, not on every page. */ readonly dids = new Map(); constructor(config: SessionsConfig) { this.#config = config; this.signIn = new SignIn(config); this.seal = new Seal(config.secret, config.salt); this.names = { session: `__Host-${config.prefix}-session`, signIn: `__Host-${config.prefix}-signin`, scheme: `${config.prefix}-scheme` }; } get hud() { return this.#config.hud; } get origin() { return this.#config.origin; } /** The app as an OAuth client of HUD: its client ID metadata document, for the app to serve at `/client-metadata.json`. */ clientMetadata() { return this.signIn.clientMetadata(); } /** A row kept, as an account's own answer read it. */ remember(row: AccountRow) { if (this.rows.size >= ROWS_MAX) this.rows.delete(this.rows.keys().next().value!); this.rows.delete(row.did); this.rows.set(row.did, { row, until: Date.now() + ROW_LIFE }); } /** * A request's way to HUD: its cookie's accounts, the one in use * refreshed where its access token lapses soon (or where a cookie from * before accounts were kept does not name it yet); one HUD no longer * takes let go, the one before it in use after. */ async request(cookies: Cookies): Promise { const raw = cookies.get(this.names.session); let kept = keptOf(await this.seal.open(this.names.session, raw)); let changed = raw !== undefined && kept === null; while (kept) { const session = kept.sessions[kept.active]; if (session.did !== null && session.expiresAt - EARLY >= Date.now()) break; const fresh = await this.signIn.refresh(session); changed = true; if (fresh) { kept = renewed(kept, kept.active, fresh); break; } kept = removed(kept, kept.active); } const hud = new Hud(this, cookies, kept, raw !== undefined); if (changed) await hud.keep(kept); return hud; } } /** A request's way to HUD, as the account its cookie has in use, and the shell's endpoints. */ export class Hud implements Caller { readonly #sessions: Sessions; readonly #cookies: Cookies; #kept: Kept | null; /** The account in use, as the request started; null signed out, or once HUD refused it here. */ #session: Session | null; /** Writes of the cookie begun: only the last sets it. */ #writes = 0; /** Whether the request came with a session cookie, live or not. */ readonly asked: boolean; constructor(sessions: Sessions, cookies: Cookies, kept: Kept | null, asked: boolean) { this.#sessions = sessions; this.#cookies = cookies; this.#kept = kept; this.#session = kept ? kept.sessions[kept.active] : null; this.asked = asked; } /** The account in use's session, as this request is drawn: null signed out. */ get session(): Session | null { return this.#session; } /** The account's own scheme, as its cookie keeps it: read only beside a session, so it alone never changes a page anyone else is sent. */ get scheme(): 'light' | 'dark' | null { return this.#session ? schemeOf(this.#cookies.get(this.#sessions.names.scheme)) : null; } /** Whether the account's scheme is kept in its cookie yet. */ get schemeKept(): boolean { return this.#cookies.get(this.#sessions.names.scheme) !== undefined; } /** The account's own scheme kept for the pages drawn next (`undefined` forgets it, for the next account's to be read). */ keepScheme(scheme: 'light' | 'dark' | null | undefined) { const name = this.#sessions.names.scheme; if (scheme === undefined) this.#cookies.delete(name, { path: '/', secure: true }); else this.#cookies.set(name, scheme ?? 'system', options(365 * 86_400)); } /** The accounts changed: the cookie follows them, as many as fit it (the rest revoked), where the response has not begun (a promise streamed after it cannot: the next request's cookie, its refresh shared, carries it). */ async keep(kept: Kept | null) { this.#kept = kept; const write = ++this.#writes; const { session } = this.#sessions.names; if (!kept) { if (write === this.#writes) this.#forget(session); return; } const fitted = await fit(kept, (k) => this.#sessions.seal.seal(session, k)); for (const gone of fitted.dropped) void this.#sessions.signIn.revoke(gone); if (fitted.kept !== kept) this.#kept = fitted.kept; if (write !== this.#writes) return; try { this.#cookies.set(session, fitted.sealed, options(SESSION_LIFE)); } catch { // Streaming already. } } #forget(name: string) { try { this.#cookies.delete(name, { path: '/', secure: true }); } catch { // Streaming already. } } #send(session: Session | null, name: string, args: Record) { return fetch(`${this.#sessions.hud}/mcp`, { ...toolRequest(name, args, session?.access ?? null), signal: AbortSignal.timeout(WAIT) }); } /** * A call as one of the browser's accounts: a token HUD refuses * refreshed once and the call made again; a session HUD no longer takes * let go (`SignInNeeded` thrown). Its new tokens are kept as the session * it is now, found by itself in the accounts, as calls run side by side. */ async #as(session: Session, name: string, args: Record): Promise<{ result: Promise; now: Session | null }> { let res = await this.#send(session, name, args); let now: Session | null = session; if (res.status === 401) { now = await this.#sessions.signIn.refresh(session); const kept = this.#kept; const i = kept ? kept.sessions.indexOf(session) : -1; if (kept && i >= 0) await this.keep(now ? renewed(kept, i, now) : removed(kept, i)); if (now) res = await this.#send(now, name, args); if (res.status === 401 && now) { const later = this.#kept; const j = later ? later.sessions.indexOf(now) : -1; if (later && j >= 0) await this.keep(removed(later, j)); now = null; } } return { result: toolResult(res), now }; } /** One of HUD's tools as the account in use: its result, failures included (`isError`); throws `SignInNeeded` where it needs an account this request has not, and with why where HUD could not be reached. */ async call(name: string, args: Record): Promise { const session = this.#session; if (!session) return toolResult(await this.#send(null, name, args)); const { result, now } = await this.#as(session, name, args); // The account in use refused: the rest of this request is drawn signed out, never as another. if (this.#session === session) this.#session = now; return result; } /** A handle's DID, as `describe_repo` resolves it, kept a while; the handle as it is where it cannot. */ async resolve(actor: string): Promise { const dids = this.#sessions.dids; const now = Date.now(); const kept = dids.get(actor); if (kept && kept.until > now) return kept.did; const result = await this.call('describe_repo', { actor }).catch(() => null); const did = (result?.structuredContent as { did?: unknown } | null | undefined)?.did; if (result?.isError || typeof did !== 'string') return actor; if (dids.size >= DIDS_MAX) dids.delete(dids.keys().next().value!); dids.set(actor, { did, until: now + DID_LIFE }); return did; } /** * The browser's accounts as rows: the one in use's from `own`, its * answer to the frame's picture call; each other's kept a while, else * read with its own tokens. Null signed out. */ async accounts(app: App, own: Promise): Promise { const kept = this.#kept; const active = this.#session; if (!kept || !active?.did) return null; const shown = app.frame?.account?.picture; const rows = await Promise.all( kept.sessions.map(async (session): Promise => { const did = session.did; if (!did) return null; const cached = this.#sessions.rows.get(did); if (session === active) { const answer = await own; if (answer === null && cached) return cached.row; const row = rowOf(did, answer, app); if (answer !== null) this.#sessions.remember(row); return row; } if (cached && cached.until > Date.now()) return cached.row; if (!shown) return rowOf(did, null, app); const read = await this.#as(session, shown.call.name, shown.call.args).catch(() => null); const result = await read?.result.catch(() => null); // Let go (HUD no longer takes it): no row; not reached: as it was. if (read && !read.now) return null; if (!result || result.isError) return cached?.row ?? rowOf(did, null, app); const row = rowOf(did, result.structuredContent, app); this.#sessions.remember(row); return row; }) ); return { list: rows.filter((row) => row !== null), current: active.did }; } /** Whether a request that changes something comes from the app's own pages: its `Origin`, where a browser sends one, the app's public origin (or the one it was asked at, under a dev server). */ #own(request: Request, url: URL): boolean { const from = request.headers.get('origin'); return from === null || from === this.#sessions.origin || from === url.origin; } /** * The app's own sign-in screen's form, posted to it at `url` (the host's * sign-in path): the account its `handle` names, or with `create` a new * one, signed in to, then back to its `back`. Where HUD goes straight on, * where the browser goes (`to`: the account's server), what it comes * back to kept in its sign-in cookie; else why not, with the handle as * typed, for the screen to say. Signed in already, another account is * added. Only from the app's origin. */ async signIn(request: Request, url: URL): Promise<{ to: string } | { handle: string; error: string }> { if (!this.#own(request, url)) return { handle: '', error: 'Not from this site.' }; const form = await request.formData().catch(() => null); const field = (name: string) => { const value = form?.get(name); return typeof value === 'string' ? value : null; }; const handle = (field('handle') ?? '').trim(); const create = field('create') === '1'; if (!create && !handle.replace(/^@/, '')) return { handle, error: 'Enter your handle, as alice.bsky.social.' }; try { const { url: at, pending } = await this.#sessions.signIn.authorize(field('back'), { from: url.pathname, handle, create }); const went = await this.#sessions.signIn.begin(at); if ('error' in went) return { handle, error: went.error }; this.#cookies.set(this.#sessions.names.signIn, await this.#sessions.seal.seal(this.#sessions.names.signIn, pending), options(SIGNIN_LIFE)); return { to: went.to }; } catch (why) { return { handle, error: why instanceof Error ? why.message : String(why) }; } } /** * HUD's sign-in come back: its code exchanged for the account's tokens, * the account added to the browser's (in place of its own where it was * signed in to already, whose old session is revoked) and put in use, * and the browser sent back where it signed in from. Refused (the * account's server, or the person there, said no), the browser goes * back to the screen it signed in from, saying why, its handle filled * in. */ async callback(url: URL): Promise { const name = this.#sessions.names.signIn; const pending = await this.#sessions.seal.open(name, this.#cookies.get(name)); this.#forget(name); const refused = (message: string) => new Response(message, { status: 400, headers: { 'content-type': 'text/plain; charset=utf-8', ...NO_STORE } }); if (!pending) return refused('No sign-in was under way in this browser, or it took longer than ten minutes. Sign in again.'); let session: Session; try { session = await this.#sessions.signIn.finish(pending, url.searchParams); } catch (why) { const params = url.searchParams; const message = params.has('error') ? params.get('error_description') || 'Signing in was refused.' : why instanceof Error ? why.message : String(why); if (!pending.from) return refused(message); const screen = new URLSearchParams({ back: pending.back, handle: pending.handle ?? '', error: message }); return new Response(null, { status: 303, headers: { location: `${pending.from}?${screen}`, ...NO_STORE } }); } const { kept, replaced, dropped } = added(this.#kept, session); for (const gone of [...(replaced && replaced.refresh !== session.refresh ? [replaced] : []), ...dropped]) void this.#sessions.signIn.revoke(gone); await this.keep(kept); this.keepScheme(undefined); return new Response(null, { status: 303, headers: { location: pending.back, ...NO_STORE } }); } /** Sign out of the account in use: its refresh token revoked at HUD, which ends its session there; the one before it in use after, if any is left. Only from the app's origin, by POST. */ async signOut(request: Request, url: URL): Promise { if (!this.#own(request, url)) return new Response(null, { status: 403 }); const kept = this.#kept; const session = kept ? kept.sessions[kept.active] : null; await this.keep(kept && removed(kept, kept.active)); this.keepScheme(undefined); if (session) await this.#sessions.signIn.revoke(session); return new Response(null, { status: 204, headers: NO_STORE }); } /** Switch to another of the browser's accounts (`{did}`, JSON): only one it is signed in to, only from the app's origin, by POST. */ async use(request: Request, url: URL): Promise { if (!this.#own(request, url)) return Response.json({ message: 'Not from this site.' }, { status: 403, headers: NO_STORE }); const asked = (await request.json().catch(() => null)) as { did?: unknown } | null; const now = this.#kept && typeof asked?.did === 'string' ? used(this.#kept, asked.did) : null; if (!now) return Response.json({ message: 'This browser is not signed in to that account.' }, { status: 404, headers: NO_STORE }); await this.keep(now); this.keepScheme(undefined); return new Response(null, { status: 204, headers: NO_STORE }); } /** * The pages' calls of HUD's tools: `{name, args}`, made as the account * in use, answered with the tool's result; 401 where it needs an account * the request has not. JSON only, so a page elsewhere cannot send one * without asking first (CORS), and only from the app's origin. Where it * is the app's scheme call, the scheme it answers is kept in its cookie, * for the pages drawn next. */ async mcp(request: Request, url: URL, app: App): Promise { const answer = (body: unknown, status = 200) => Response.json(body, { status, headers: NO_STORE }); if (!this.#own(request, url)) return answer({ message: 'Not from this site.' }, 403); if (!request.headers.get('content-type')?.startsWith('application/json')) return answer({ message: 'Send JSON.' }, 415); const asked = (await request.json().catch(() => null)) as { name?: unknown; args?: unknown } | null; if (typeof asked?.name !== 'string' || typeof asked.args !== 'object' || asked.args === null || Array.isArray(asked.args)) return answer({ message: 'A call is {name, args}.' }, 400); const call = { name: asked.name, args: asked.args as Record }; try { const result = await this.call(call.name, call.args); const scheme = app.scheme; if (scheme && this.#session && !result.isError && same(call, scheme.call)) this.keepScheme(schemeIn(result.structuredContent, scheme.at)); return answer(result); } catch (error) { const message = error instanceof Error ? error.message : String(error); return answer({ message }, error instanceof SignInNeeded ? 401 : 502); } } /** A picture uploaded as the account in use: its bytes streamed on to HUD's `place.hud.uploadBlob` with its token, HUD's answer (the blob ref, or why not) streamed back. */ async upload(request: Request, url: URL): Promise { const answer = (body: unknown, status: number) => Response.json(body, { status, headers: NO_STORE }); if (!this.#own(request, url)) return answer({ message: 'Not from this site.' }, 403); const session = this.#session; if (!session) return answer({ message: 'Sign in to upload.' }, 401); const res = await fetch(`${this.#sessions.hud}/xrpc/place.hud.uploadBlob`, { method: 'POST', headers: { authorization: `Bearer ${session.access}`, 'content-type': request.headers.get('content-type') ?? 'application/octet-stream' }, body: request.body, // @ts-expect-error: Node's fetch streams a request body only half duplex, which its types do not name. duplex: 'half' }).catch(() => null); if (!res) return answer({ message: 'The upload could not reach HUD.' }, 502); return new Response(res.body, { status: res.status, headers: { 'content-type': res.headers.get('content-type') ?? 'application/json', ...NO_STORE } }); } }