@preventive/triage 1.0.0-alpha.2 → 1.0.0-alpha.20

package/server-managed/github-app.ts

@@ -0,0 +1,332 @@
+// Repository listing for the "Manage repositories" page, READ-ONLY. Two sources,
+// merged + deduped by full name:
+//
+//   PUBLIC  — the logged-in user's own repos (GET /user/repos) read with their
+//             identity-only login token. No installation; the login App needs no
+//             repository permissions, so login never shows "Act on your behalf".
+//   PRIVATE — a SEPARATE GitHub App (Contents: Read) the user installs on the
+//             repos they want; read server-side via installation tokens. That
+//             App's Contents permission lives on IT, never on the login App, so
+//             login stays clean. "Connect a repository" installs it (installUrl).
+//
+// Archived repos are skipped. Nothing here writes.
+import { Buffer } from 'node:buffer'
+import { createSign } from 'node:crypto'
+import type { ManagedConfig } from './config.ts'
+
+const GITHUB_API = 'https://api.github.com'
+const API_VERSION = '2022-11-28'
+const USER_AGENT = 'deepview-triage'
+const PER_PAGE = 100
+
+// One listed repository. Carries the context to read its contents later:
+// `installationId` mints an App installation token (Contents: Read) for a repo
+// reached through an installation — null for a public repo listed off the user
+// token, readable without the App — and `defaultBranch` is the ref to read.
+export interface ConnectedRepo {
+  id: number
+  fullName: string
+  private: boolean
+  visibility: 'public' | 'private' | 'internal' | null
+  htmlUrl: string
+  defaultBranch: string
+  installationId: number | null
+}
+
+// A failure carrying the HTTP status the router should surface. 401 passes
+// through so the user-token path can map it to "log in again".
+export class GithubApiError extends Error {
+  status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = 'GithubApiError'
+    this.status = status
+  }
+}
+
+// The separate repositories App is configured (id + private key present) →
+// private repos can be listed via its installation tokens.
+export function githubAppConfigured(config: ManagedConfig): boolean {
+  return config.githubAppId != null && config.githubAppPrivateKey != null
+}
+
+// The install URL for the repositories App ("Connect a repository"), or null
+// when no slug is set.
+export function installUrl(config: ManagedConfig): string | null {
+  if (config.githubAppSlug == null) return null
+  return `https://github.com/apps/${encodeURIComponent(config.githubAppSlug)}/installations/new`
+}
+
+// Merge repo lists from every source, deduped by full name and sorted. Later
+// sources win a collision (the handler lists private after public).
+export function mergeRepos(...lists: ConnectedRepo[][]): ConnectedRepo[] {
+  const byName = new Map<string, ConnectedRepo>()
+  for (const list of lists) {
+    for (const repo of list) byName.set(repo.fullName, repo)
+  }
+  return [...byName.values()].toSorted((a, b) => a.fullName.localeCompare(b.fullName))
+}
+
+// One GitHub API call returning parsed JSON, optionally Bearer-authed by a
+// user token, App JWT, or installation token. Network / non-2xx / malformed
+// fold into a GithubApiError (401 passes through for the caller to handle).
+async function githubJson(url: string, token: string | null, fetchImpl: typeof fetch, method: 'GET' | 'POST' = 'GET'): Promise<unknown> {
+  let res: Response
+  try {
+    res = await fetchImpl(url, {
+      method,
+      signal: AbortSignal.timeout(10_000),
+      redirect: 'error',
+      headers: {
+        ...(token == null ? {} : { authorization: `Bearer ${token}` }), 'accept': 'application/vnd.github+json',
+        'user-agent': USER_AGENT, 'x-github-api-version': API_VERSION,
+      },
+    })
+  } catch { throw new GithubApiError(502, 'github-unreachable') }
+  if (res.status === 401) throw new GithubApiError(401, 'github-unauthorized')
+  if (res.status === 404) throw new GithubApiError(404, 'github-not-found')
+  if (!res.ok) throw new GithubApiError(502, `github-status-${res.status}`)
+  try { return await res.json() } catch { throw new GithubApiError(502, 'github-malformed') }
+}
+
+// Validate one repo object into a ConnectedRepo (or null to skip), tagging it
+// with the installation it was reached through (null for the user-token path). A
+// missing numeric id or full name → skip (can't key/locate it). Archived repos
+// are skipped — read-only history, not triage targets.
+function parseRepo(raw: unknown, installationId: number | null): ConnectedRepo | null {
+  if (raw == null || typeof raw !== 'object') return null
+  if ((raw as { archived?: unknown }).archived === true) return null
+  const id = (raw as { id?: unknown }).id
+  const fullName = (raw as { full_name?: unknown }).full_name
+  if (typeof id !== 'number' || !Number.isSafeInteger(id) || id <= 0) return null
+  if (typeof fullName !== 'string' || fullName === '') return null
+  const htmlUrl = (raw as { html_url?: unknown }).html_url
+  const branch = (raw as { default_branch?: unknown }).default_branch
+  const visibility = (raw as { visibility?: unknown }).visibility
+  return {
+    id,
+    fullName,
+    private: (raw as { private?: unknown }).private === true,
+    visibility: visibility === 'public' || visibility === 'private' || visibility === 'internal' ? visibility : null,
+    htmlUrl: typeof htmlUrl === 'string' ? htmlUrl : '',
+    defaultBranch: typeof branch === 'string' ? branch : '',
+    installationId,
+  }
+}
+
+// Accept an owner/repo or exact GitHub repository URL, never an arbitrary API
+// path. Reject traversal and encoded separators before constructing a fixed URL.
+export function publicRepositoryName(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null
+  const name = raw.trim().replace(/^https:\/\/github\.com\//iu, '').replace(/\/$/u, '')
+  if (!/^[a-z\d](?:[a-z\d-]{0,38})\/[a-z\d_.-]{1,100}$/iu.test(name)) return null
+  if (['.', '..'].includes(name.split('/')[1]!)) return null
+  return name
+}
+
+// Public additions must be readable by the server without the acting user's
+// credentials. Require explicit public visibility and use GitHub's canonical
+// metadata, never client-supplied ids, installation ids, or branches.
+export async function fetchPublicRepository(fullName: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo> {
+  if (publicRepositoryName(fullName) !== fullName) throw new GithubApiError(400, 'bad-repository')
+  const path = fullName.split('/').map(encodeURIComponent).join('/')
+  const repo = parseRepo(await githubJson(`${GITHUB_API}/repos/${path}`, null, fetchImpl), null)
+  if (repo == null || repo.private || repo.visibility !== 'public') throw new GithubApiError(409, 'repo-not-public')
+  if (publicRepositoryName(repo.fullName) !== repo.fullName || repo.fullName.toLowerCase() !== fullName.toLowerCase()) throw new GithubApiError(502, 'github-malformed')
+  return { ...repo, htmlUrl: `https://github.com/${repo.fullName}` }
+}
+
+// ── PUBLIC: the user's own repos via their login token ──
+
+// List the authenticated user's repositories (GET /user/repos), paginated until
+// a short page, deduped + sorted. With an identity-only token this returns the
+// user's PUBLIC repos. READ-ONLY.
+export async function listUserRepos(accessToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+  const byName = new Map<string, ConnectedRepo>()
+  for (let page = 1; ; page++) {
+    const url = `${GITHUB_API}/user/repos?per_page=${PER_PAGE}&page=${page}&sort=full_name`
+    const body = await githubJson(url, accessToken, fetchImpl)
+    if (!Array.isArray(body)) break
+    for (const r of body) {
+      const repo = parseRepo(r, null)
+      if (repo != null) byName.set(repo.fullName, repo)
+    }
+    if (body.length < PER_PAGE) break
+  }
+  return [...byName.values()].toSorted((a, b) => a.fullName.localeCompare(b.fullName))
+}
+
+// ── PRIVATE: the separate App's installations via installation tokens ──
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString('base64url')
+}
+
+// Mint a short-lived App JWT (RS256) for the repositories App. iat backdated 60s
+// for clock skew; exp 8 min out (within GitHub's 10-min cap); iss = the App id.
+export function appJwt(appId: string, privateKeyPem: string, now: number = Date.now()): string {
+  const seconds = Math.floor(now / 1000)
+  const iat = seconds - 60
+  const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))
+  const payload = base64url(JSON.stringify({ iat, exp: seconds + 480, iss: appId }))
+  const signingInput = `${header}.${payload}`
+  return `${signingInput}.${base64url(createSign('RSA-SHA256').update(signingInput).sign(privateKeyPem))}`
+}
+
+// The repositories App's installation ids (one per org/user that installed it).
+async function listInstallationIds(jwt: string, fetchImpl: typeof fetch): Promise<number[]> {
+  const ids: number[] = []
+  for (let page = 1; ; page++) {
+    const body = await githubJson(`${GITHUB_API}/app/installations?per_page=${PER_PAGE}&page=${page}`, jwt, fetchImpl)
+    if (!Array.isArray(body)) throw new GithubApiError(502, 'github-malformed')
+    for (const inst of body) {
+      const id = (inst as { id?: unknown }).id
+      if (typeof id === 'number' && Number.isSafeInteger(id) && id > 0) ids.push(id)
+    }
+    if (body.length < PER_PAGE) break
+  }
+  return ids
+}
+
+// Exchange the App JWT for a scoped installation access token (inherits the
+// App's Contents: Read).
+async function mintInstallationToken(jwt: string, installId: number, fetchImpl: typeof fetch): Promise<string> {
+  const body = await githubJson(`${GITHUB_API}/app/installations/${installId}/access_tokens`, jwt, fetchImpl, 'POST')
+  const token = (body as { token?: unknown }).token
+  if (typeof token !== 'string' || token === '') throw new GithubApiError(502, 'github-install-token-denied')
+  return token
+}
+
+// The `repositories` array of one /installation/repositories page → ConnectedRepo[],
+// each tagged with the installation id that can read it.
+function repoPage(body: unknown, installationId: number): ConnectedRepo[] {
+  const repositories = (body as { repositories?: unknown }).repositories
+  if (!Array.isArray(repositories)) return []
+  const out: ConnectedRepo[] = []
+  for (const r of repositories) {
+    const repo = parseRepo(r, installationId)
+    if (repo != null) out.push(repo)
+  }
+  return out
+}
+
+// Every repository one installation can read, paginated by the page count from
+// `total_count` (avoids Link-header parsing).
+async function listInstallationRepos(token: string, installationId: number, fetchImpl: typeof fetch): Promise<ConnectedRepo[]> {
+  const pageUrl = (page: number): string => `${GITHUB_API}/installation/repositories?per_page=${PER_PAGE}&page=${page}`
+  const first = await githubJson(pageUrl(1), token, fetchImpl) as { total_count?: unknown }
+  const repos = repoPage(first, installationId)
+  const total = typeof first.total_count === 'number' ? first.total_count : repos.length
+  const pages = Math.ceil(total / PER_PAGE)
+  for (let page = 2; page <= pages; page++) {
+    repos.push(...repoPage(await githubJson(pageUrl(page), token, fetchImpl), installationId))
+  }
+  return repos
+}
+
+// List every repo the repositories App is installed on, across installations
+// (public + PRIVATE within those installs), deduped + sorted. Empty when the App
+// isn't configured. READ-ONLY.
+export async function listInstalledRepos(config: ManagedConfig, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+  const { githubAppId, githubAppPrivateKey } = config
+  if (githubAppId == null || githubAppPrivateKey == null) return []
+  const jwt = appJwt(githubAppId, githubAppPrivateKey)
+  const lists = await mapGithubRequests(await listInstallationIds(jwt, fetchImpl), async (id) => {
+    const token = await mintInstallationToken(jwt, id, fetchImpl)
+    return listInstallationRepos(token, id, fetchImpl)
+  })
+  return mergeRepos(...lists)
+}
+
+// Bound fan-out while keeping independent installations/permission checks off
+// one long serial critical path. Preserve input order for deterministic merges.
+async function mapGithubRequests<T, U>(items: T[], work: (item: T) => Promise<U>): Promise<U[]> {
+  const results: U[] = []
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(4, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next++
+      results[index] = await work(items[index]!)
+    }
+  }))
+  return results
+}
+
+// The login App and repository App are separate: /user/repos with the login
+// token is not evidence of private-repo access. Ask the repository App for the
+// user's effective GitHub permission (including teams/org/enterprise grants).
+// This endpoint accepts installation tokens with Metadata: read; it does NOT
+// require Administration permission (unlike collaborator mutation endpoints).
+// https://docs.github.com/en/rest/collaborators/collaborators#get-repository-permissions-for-a-user
+// Resolve the current login from /user so renamed handles cannot check someone
+// else's access. All repo paths come from GitHub's installation catalogue.
+export async function filterInstalledRepos(config: ManagedConfig, repositories: ConnectedRepo[], userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+  const identity = await githubJson(`${GITHUB_API}/user`, userToken, fetchImpl) as { id?: unknown; login?: unknown }
+  if (typeof identity?.login !== 'string' || !identity.login || typeof identity.id !== 'number' || !Number.isSafeInteger(identity.id) || identity.id <= 0) throw new GithubApiError(502, 'github-malformed')
+  const tokens = new Map<number, Promise<string | null>>()
+  const allowed = await mapGithubRequests(repositories, async (repo) => {
+    // Internal repos may have private=false; missing visibility is not proof
+    // of public access either. Only explicitly public repositories skip checks.
+    if (repo.visibility === 'public') return true
+    if (repo.installationId == null) return false
+    let token = tokens.get(repo.installationId)
+    if (!token) {
+      token = repoAccessToken(config, repo.installationId, fetchImpl)
+      tokens.set(repo.installationId, token)
+    }
+    const accessToken = await token
+    if (!accessToken) return false
+    const path = repo.fullName.split('/').map(encodeURIComponent).join('/')
+    try {
+      const body = await githubJson(`${GITHUB_API}/repos/${path}/collaborators/${encodeURIComponent(identity.login as string)}/permission`, accessToken, fetchImpl) as { permission?: unknown; user?: { id?: unknown } }
+      return body?.user?.id === identity.id && ['read', 'write', 'admin'].includes(String(body?.permission))
+    } catch (err) {
+      if (err instanceof GithubApiError && err.status === 404) return false
+      throw err // Never broaden the list when GitHub cannot verify access.
+    }
+  })
+  return repositories.filter((_, index) => allowed[index])
+}
+
+// Mint a token to READ a selected repo's contents: an installation token (the
+// App's Contents: Read) when the repo was reached through an installation, or
+// null for a public repo readable unauthenticated. This is the whole point of
+// persisting `installationId` — the stored context is enough to read.
+export async function repoAccessToken(config: ManagedConfig, installationId: number | null, fetchImpl: typeof fetch = globalThis.fetch): Promise<string | null> {
+  const { githubAppId, githubAppPrivateKey } = config
+  if (installationId == null || githubAppId == null || githubAppPrivateKey == null) return null
+  return await mintInstallationToken(appJwt(githubAppId, githubAppPrivateKey), installationId, fetchImpl)
+}
+
+// ── merged listing ──
+
+export interface RepoListing {
+  repositories: ConnectedRepo[]
+  tokenMissing: boolean
+}
+
+// Every repo a user can reach, merged (deduped + sorted): PUBLIC via their login
+// token + PRIVATE via the App's installations. Each source is best-effort so one
+// failing never blanks the other; `tokenMissing` flags a missing/stale user
+// token (→ the page prompts re-login). A repo seen on both sides keeps the
+// installation tag (private listed last → wins the merge).
+export async function collectRepos(config: ManagedConfig, userToken: string | null, fetchImpl: typeof fetch = globalThis.fetch): Promise<RepoListing> {
+  let tokenMissing = userToken == null
+  const lists: ConnectedRepo[][] = []
+  if (userToken != null) {
+    try {
+      lists.push(await listUserRepos(userToken, fetchImpl))
+    } catch (err) {
+      if (err instanceof GithubApiError && err.status === 401) tokenMissing = true
+      else console.warn('managed: public repo list failed:', err)
+    }
+  }
+  if (githubAppConfigured(config)) {
+    try {
+      lists.push(await listInstalledRepos(config, fetchImpl))
+    } catch (err) {
+      console.warn('managed: private repo list failed:', err)
+    }
+  }
+  return { repositories: mergeRepos(...lists), tokenMissing }
+}

package/server-managed/github-metadata.ts

@@ -0,0 +1,65 @@
+import type { GithubFixStatus, GithubIssueClosedReason } from '../common/github-pr.ts'
+import type { ManagedSql } from './sql.ts'
+
+export interface GithubMetadata {
+  key: string
+  title: string
+  description: string | null
+  status: GithubFixStatus
+  // NULL on legacy entries; 'unknown' means a closed issue was checked but
+  // GitHub supplied no recognized reason, so it needs no further backfill.
+  stateReason: GithubIssueClosedReason | null
+  fetchedAt: number
+  attemptedAt: number | null
+}
+export interface GithubMetadataStore {
+  listGithubMetadata(keys: readonly string[]): Promise<GithubMetadata[]>
+  setGithubMetadata(entries: readonly Omit<GithubMetadata, 'attemptedAt'>[]): Promise<void>
+  recordGithubMetadataAttempts(keys: readonly string[], attemptedAt: number): Promise<void>
+}
+
+// Successful GitHub reads are shared and retained without eviction. The stable
+// repository ID in the key survives renames, but is never an access grant.
+// Callers must authorize the current user -> team -> repo before every read.
+export const GITHUB_STATE_REASON_COLUMN = "TEXT CHECK (state_reason IN ('completed', 'not_planned', 'duplicate', 'unknown'))"
+export const GITHUB_METADATA_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_github_metadata (
+  cache_key TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL CHECK (status IN ('open', 'draft', 'closed', 'merged')),
+  state_reason ${GITHUB_STATE_REASON_COLUMN},
+  fetched_at INTEGER NOT NULL,
+  attempted_at INTEGER
+) STRICT;
+`
+
+export function githubMetadataMethods(db: ManagedSql): GithubMetadataStore {
+  const list = db.prepare(`SELECT cache_key AS key, title, description, status, state_reason AS stateReason, fetched_at AS fetchedAt, attempted_at AS attemptedAt
+    FROM managed_github_metadata WHERE cache_key IN (SELECT value FROM json_each(?))`)
+  const set = db.prepare(`INSERT INTO managed_github_metadata (cache_key, title, description, status, state_reason, fetched_at)
+    SELECT json_extract(e.value, '$.key'), json_extract(e.value, '$.title'),
+      json_extract(e.value, '$.description'), json_extract(e.value, '$.status'), json_extract(e.value, '$.stateReason'),
+      CAST(json_extract(e.value, '$.fetchedAt') AS BIGINT)
+    FROM json_each(:contexts) e WHERE 1 = 1
+    ON CONFLICT (cache_key) DO UPDATE SET title = excluded.title, description = excluded.description,
+      status = excluded.status, state_reason = excluded.state_reason, fetched_at = excluded.fetched_at
+    WHERE managed_github_metadata.status != 'merged' AND managed_github_metadata.fetched_at <= excluded.fetched_at`)
+  // Scheduling attempts never overwrite metadata or make stale data fresh.
+  // The monotonic guard preserves a newer attempt recorded by another reader.
+  const attempt = db.prepare(`UPDATE managed_github_metadata SET attempted_at = ?
+    WHERE cache_key IN (SELECT value FROM json_each(?)) AND (attempted_at IS NULL OR attempted_at < ?)`)
+  return {
+    async listGithubMetadata(keys) {
+      if (keys.length === 0) return []
+      const rows = await list.all(JSON.stringify(keys)) as GithubMetadata[]
+      return rows.map(row => ({ ...row }))
+    },
+    async setGithubMetadata(entries) {
+      if (entries.length > 0) await set.run({ contexts: JSON.stringify(entries) })
+    },
+    async recordGithubMetadataAttempts(keys, attemptedAt) {
+      if (keys.length > 0) await attempt.run(attemptedAt, JSON.stringify(keys), attemptedAt)
+    },
+  }
+}

package/server-managed/github-oauth.ts

@@ -0,0 +1,215 @@
+// GitHub App user-authorization (identity) for the managed server. This is the
+// GitHub *App* user-to-server flow, NOT an OAuth App: the authorize request
+// carries NO `scope` (a GitHub App's permissions live on the App itself), so
+// login asks for identity only — repo access is a SEPARATE installation flow
+// (later work), keeping the broad "act on your behalf" ask off of login.
+//
+//   GET /api/oauth/github/login     → 302 to github.com/login/oauth/authorize
+//                                      with a CSRF `state` mirrored into a
+//                                      short-lived state cookie.
+//   GET /api/oauth/github/callback   → verify `state` vs the cookie, exchange
+//                                      the code for a user token, read the
+//                                      GitHub identity, upsert the user, mint a
+//                                      session, set the cookie, 302 to the app.
+//
+// The user-to-server token is read for the identity AND persisted (see
+// db.setUserTokens): the "Manage repositories" page lists the user's repos with
+// it on demand (GET /user/repos — public repos with no App install; private
+// ones once the App is installed). `ensureUserAccessToken` refreshes it when the
+// App issues expiring tokens.
+import { Buffer } from 'node:buffer'
+import type { AvatarStore } from './avatar-store.ts'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedUser, UserTokens } from './db.ts'
+import { randomToken, safeEqual } from './crypto.ts'
+import { STATE_COOKIE, buildCookie, clearCookie, cookieName, createSession, parseCookies } from './session.ts'
+
+const GITHUB_AUTHORIZE_URL = 'https://github.com/login/oauth/authorize'
+const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token'
+const GITHUB_USER_URL = 'https://api.github.com/user'
+const STATE_TTL_S = 600
+
+export const LOGIN_PATH = '/api/oauth/github/login'
+export const CALLBACK_PATH = '/api/oauth/github/callback'
+
+// A failure with the HTTP status the router should surface.
+export class OAuthError extends Error {
+  status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = 'OAuthError'
+    this.status = status
+  }
+}
+
+export interface CallbackResult { location: string; setCookies: string[] }
+export interface CallbackDeps { config: ManagedConfig; db: ManagedDb; avatarStore?: AvatarStore; now?: number; fetchImpl?: typeof fetch }
+
+// GET /api/oauth/github/login — redirect to GitHub, stashing the CSRF state. No
+// `scope` is sent: as the GitHub App user-authorization flow, the App's own
+// permission set governs access, so login requests identity only (repo access
+// is granted separately by installing the App).
+export function buildLoginRedirect(config: ManagedConfig): { location: string; setCookie: string } {
+  const state = randomToken()
+  const u = new URL(GITHUB_AUTHORIZE_URL)
+  u.searchParams.set('client_id', config.githubClientId)
+  u.searchParams.set('redirect_uri', config.oauthCallbackUrl)
+  u.searchParams.set('state', state)
+  u.searchParams.set('allow_signup', 'false')
+  const setCookie = buildCookie(cookieName(config, STATE_COOKIE), state, {
+    maxAgeS: STATE_TTL_S, secure: config.cookieSecure, sameSite: 'Lax',
+  })
+  return { location: u.toString(), setCookie }
+}
+
+// GET /api/oauth/github/callback?code&state — the GitHub OAuth hook.
+export async function handleCallback(
+  query: URLSearchParams, cookieHeader: string | undefined, deps: CallbackDeps,
+): Promise<CallbackResult> {
+  const { config, db } = deps
+  const now = deps.now ?? Date.now()
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch
+  const code = query.get('code')
+  const state = query.get('state')
+  const stateCookie = parseCookies(cookieHeader).get(cookieName(config, STATE_COOKIE))
+  // CSRF: the `state` GitHub echoes back must match the one we set at /login.
+  if (!code || !state || !stateCookie || !safeEqual(state, stateCookie)) {
+    throw new OAuthError(400, 'invalid-oauth-state')
+  }
+  const tokens = await exchangeCode(config, code, now, fetchImpl)
+  const user = await fetchIdentity(tokens.accessToken, fetchImpl)
+  const { setCookie, userId } = await createSession(config, db, user, now)
+  // Persist the user token so the repositories page can list repos on demand.
+  await db.setUserTokens(userId, tokens)
+  // Cache the avatar for same-origin serving (the page's CSP forbids loading
+  // github's CDN directly). Best-effort: a fetch/store failure must not break
+  // login, and the avatar endpoint just 404s until a later login fills it.
+  if (deps.avatarStore != null && user.avatarUrl != null) {
+    await cacheAvatar(deps.avatarStore, userId, user.avatarUrl, fetchImpl).catch((err) => {
+      console.warn('managed: avatar cache failed:', err)
+    })
+  }
+  // Clear the spent state cookie, set the session cookie, land on the app.
+  return {
+    location: '/',
+    setCookies: [clearCookie(cookieName(config, STATE_COOKIE), config.cookieSecure), setCookie],
+  }
+}
+
+// Exchange the authorization code for a user-to-server token set.
+function exchangeCode(config: ManagedConfig, code: string, now: number, fetchImpl: typeof fetch): Promise<UserTokens> {
+  return postToken({
+    client_id: config.githubClientId, client_secret: config.githubClientSecret,
+    code, redirect_uri: config.oauthCallbackUrl,
+  }, now, fetchImpl)
+}
+
+// Refresh an expiring user-to-server token (GitHub Apps with expiring tokens
+// enabled). Returns the fresh token set; OAuthError(502) on any failure.
+export function refreshUserToken(config: ManagedConfig, refreshToken: string, now: number, fetchImpl: typeof fetch = globalThis.fetch): Promise<UserTokens> {
+  return postToken({
+    client_id: config.githubClientId, client_secret: config.githubClientSecret,
+    grant_type: 'refresh_token', refresh_token: refreshToken,
+  }, now, fetchImpl)
+}
+
+// POST the GitHub token endpoint and parse the {access_token, refresh_token?,
+// expires_in?} body into a UserTokens (expiry resolved to an absolute ms time).
+async function postToken(payload: Record<string, string>, now: number, fetchImpl: typeof fetch): Promise<UserTokens> {
+  let res: Response
+  try {
+    res = await fetchImpl(GITHUB_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'accept': 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  } catch { throw new OAuthError(502, 'github-token-unreachable') }
+  if (!res.ok) throw new OAuthError(502, `github-token-status-${res.status}`)
+  let body: unknown
+  try { body = await res.json() } catch { throw new OAuthError(502, 'github-token-malformed') }
+  const tok = (body as { access_token?: unknown }).access_token
+  if (typeof tok !== 'string' || tok === '') throw new OAuthError(502, 'github-token-denied')
+  const refresh = (body as { refresh_token?: unknown }).refresh_token
+  const expiresIn = (body as { expires_in?: unknown }).expires_in
+  return {
+    accessToken: tok,
+    refreshToken: typeof refresh === 'string' && refresh !== '' ? refresh : null,
+    expiresAt: typeof expiresIn === 'number' && expiresIn > 0 ? now + expiresIn * 1000 : null,
+  }
+}
+
+// Resolve a usable access token for a user: the stored one if still valid, else
+// refreshed (when a refresh token is on file) and re-persisted. Null when there
+// is no token or it's expired and unrefreshable — the caller prompts re-login.
+// A 60s skew margin avoids handing back a token about to expire mid-request.
+export async function ensureUserAccessToken(
+  config: ManagedConfig, db: ManagedDb, userId: string, now: number, fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<string | null> {
+  const tokens = await db.getUserTokens(userId)
+  if (tokens == null) return null
+  if (tokens.expiresAt == null || tokens.expiresAt > now + 60_000) return tokens.accessToken
+  if (tokens.refreshToken == null) return null
+  try {
+    const fresh = await refreshUserToken(config, tokens.refreshToken, now, fetchImpl)
+    await db.setUserTokens(userId, fresh)
+    return fresh.accessToken
+  } catch (err) {
+    console.warn('managed: token refresh failed:', err)
+    return null
+  }
+}
+
+// Read the authenticated user's identity (`GET /user`).
+async function fetchIdentity(token: string, fetchImpl: typeof fetch): Promise<ManagedUser> {
+  let res: Response
+  try {
+    res = await fetchImpl(GITHUB_USER_URL, {
+      headers: {
+        'authorization': `Bearer ${token}`, 'accept': 'application/vnd.github+json',
+        'user-agent': 'deepview-triage', 'x-github-api-version': '2022-11-28',
+      },
+    })
+  } catch { throw new OAuthError(502, 'github-user-unreachable') }
+  if (!res.ok) throw new OAuthError(502, `github-user-status-${res.status}`)
+  let body: unknown
+  try { body = await res.json() } catch { throw new OAuthError(502, 'github-user-malformed') }
+  const user = parseGithubUser(body)
+  if (user == null) throw new OAuthError(502, 'github-user-invalid')
+  return user
+}
+
+// Validate GitHub's `GET /user` payload into a ManagedUser (or null).
+function parseGithubUser(body: unknown): ManagedUser | null {
+  if (body == null || typeof body !== 'object') return null
+  const id = (body as { id?: unknown }).id
+  const login = (body as { login?: unknown }).login
+  if (typeof id !== 'number' || !Number.isSafeInteger(id) || typeof login !== 'string' || login === '') return null
+  const name = (body as { name?: unknown }).name
+  const avatar = (body as { avatar_url?: unknown }).avatar_url
+  return {
+    githubUserId: id, login,
+    name: typeof name === 'string' ? name : null,
+    avatarUrl: typeof avatar === 'string' ? avatar : null,
+  }
+}
+
+// Fetch the user's GitHub avatar and cache it for same-origin serving. The host
+// is validated (githubusercontent.com over https) as SSRF defence-in-depth,
+// even though the URL comes from GitHub's own /user response.
+async function cacheAvatar(store: AvatarStore, id: string, avatarUrl: string, fetchImpl: typeof fetch): Promise<void> {
+  if (!isGithubAvatarUrl(avatarUrl)) return
+  // `redirect: 'manual'` so a 3xx off the (validated) avatars host can't bounce
+  // the fetch to an internal address — an opaque-redirect / 3xx fails the
+  // `res.ok` + image check below and is skipped (SSRF defence-in-depth).
+  const res = await fetchImpl(avatarUrl, { redirect: 'manual' })
+  const contentType = res.headers.get('content-type') ?? ''
+  if (!res.ok || !contentType.startsWith('image/')) return
+  await store.put(id, contentType, Buffer.from(await res.arrayBuffer()))
+}
+
+function isGithubAvatarUrl(raw: string): boolean {
+  let url: URL
+  try { url = new URL(raw) } catch { return false }
+  return url.protocol === 'https:'
+    && (url.hostname === 'avatars.githubusercontent.com' || url.hostname.endsWith('.githubusercontent.com'))
+}