@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.40

package/server-managed/github-issues.ts

@@ -0,0 +1,152 @@
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession } from './db.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { ManagedIssue } from './managed-issues.ts'
+import { randomToken } from './crypto.ts'
+import { githubIssueClosedReason } from '../common/github-pr.ts'
+import { reportEntries, reportRepoGithub } from '@preventive/report'
+import { newIssueLabels } from '../common/github-issue-labels.js'
+import { appJwt, githubAppConfigured, installUrl, publicRepositoryName } from './github-app.ts'
+import { ISSUE_LOGIN_PATH, issueUserToken } from './github-issue-oauth.ts'
+import { TeamReportsError, loadTeamReports, recheckTeam, teamSnapshot } from './team-reports.ts'
+
+export const MAX_ISSUE_BODY_BYTES = 512_000
+export class IssueError extends Error {
+  status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+
+type Context = { reportId: string; findingId: string; repository: string }
+export function parseIssueContext(raw: unknown): Context {
+  const value = raw as Partial<Context> | null
+  const repository = publicRepositoryName(value?.repository)
+  if (!repository || typeof value?.reportId !== 'string' || !value.reportId || value.reportId.length > 200
+    || typeof value.findingId !== 'string' || !value.findingId || value.findingId.length > 4096) throw new IssueError(400, 'bad-request')
+  return { repository, reportId: value.reportId, findingId: value.findingId }
+}
+
+async function github(path: string, token: string, fetchImpl: typeof fetch, payload?: unknown) {
+  let response: Response
+  try {
+    response = await fetchImpl(`https://api.github.com${path}`, {
+      method: payload === undefined ? 'GET' : 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+      headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json',
+        'user-agent': 'deepview-triage', 'x-github-api-version': '2022-11-28', 'content-type': 'application/json' },
+      ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
+    })
+  } catch { throw new IssueError(502, payload === undefined ? 'github-unavailable' : 'github-create-uncertain') }
+  return response
+}
+
+function referenceResult(stored: ManagedIssue, repoIds: number[]) {
+  // A shared finding ID does not grant access to another team's repository.
+  if (!repoIds.includes(stored.repoId)) return { mode: 'unavailable' as const }
+  return stored.issueUrl ? { mode: 'existing' as const, url: stored.issueUrl }
+    : { mode: 'pending' as const, repositoryUrl: `https://github.com/${stored.repository}/issues` }
+}
+
+function issueDetails(raw: unknown, url: string, number: number, fallback: { title: string; body: string; labels: string[] }) {
+  const issue = raw as { title?: unknown; body?: unknown; state?: unknown; state_reason?: unknown;
+    user?: { login?: unknown }; labels?: ({ name?: unknown } | string)[] } | null
+  const status = issue?.state === 'closed' ? 'closed' : 'open'
+  return { url, number, title: typeof issue?.title === 'string' ? issue.title : fallback.title,
+    description: typeof issue?.body === 'string' ? issue.body : fallback.body, status,
+    stateReason: status === 'closed' ? githubIssueClosedReason(issue?.state_reason) : null,
+    author: typeof issue?.user?.login === 'string' ? issue.user.login : null,
+    labels: Array.isArray(issue?.labels) ? issue.labels.map(label => typeof label === 'string' ? label : label?.name).filter((label): label is string => typeof label === 'string') : fallback.labels }
+}
+
+// Authorize before any upstream lookup, including installation/label discovery.
+// Report filtering also supplies the full row/link isSecurity classification.
+export async function prepareGithubIssue(config: ManagedConfig, db: ManagedDb, store: BlobStore,
+  session: ManagedSession, teamId: string, context: Context, fetchImpl: typeof fetch = fetch) {
+  const snapshot = await teamSnapshot(db, session.id, teamId, context.reportId)
+  if (!snapshot.reports.some(report => report.id === context.reportId)) throw new TeamReportsError(404, 'no-report')
+  const reports = await loadTeamReports(db, store, snapshot)
+  const report = reports.find(item => item.id === context.reportId)!
+  const findings = (reportEntries(report.data) ?? []).flat() as Record<string, unknown>[]
+  const finding = findings.find(item => item['id'] === context.findingId)
+  if (!finding) throw new TeamReportsError(404, 'no-finding')
+  const recheck = () => recheckTeam(db, session.id, snapshot)
+  await recheck()
+  const labels = newIssueLabels(finding['isSecurity'] === true, config.githubNewIssueLabels ?? '')
+  const repoIds = snapshot.repositories.map(repo => repo.repoId)
+  const stored = await db.getManagedIssue(context.findingId)
+  if (stored) return { ...referenceResult(stored, repoIds), labels, recheck }
+  // The target comes from this finding's own source, or the report's managed
+  // assignment. Team membership alone must not let a caller claim an unrelated
+  // repository's issue as the permanent reference for this finding.
+  const findingRepo = finding['repo'] as { github?: unknown } | null | undefined
+  const targetRepository = publicRepositoryName(reportRepoGithub({ repo: { github: findingRepo?.github || report.repo.github } }))
+  if (!targetRepository || targetRepository.toLowerCase() !== context.repository.toLowerCase()) throw new IssueError(400, 'bad-issue-repository')
+  const repository = snapshot.repositories.find(repo => repo.github.toLowerCase() === targetRepository.toLowerCase())
+  if (!repository || !githubAppConfigured(config)) return { mode: 'form' as const, labels, recheck }
+  const path = `/repos/${targetRepository.split('/').map(encodeURIComponent).join('/')}`
+  const installation = await github(`${path}/installation`, appJwt(config.githubAppId!, config.githubAppPrivateKey!), fetchImpl)
+  if (installation.status === 404) return { mode: 'form' as const, labels, recheck }
+  if (!installation.ok) throw new IssueError(502, 'github-unavailable')
+  let installed: { permissions?: { issues?: string } }
+  try { installed = await installation.json() } catch { throw new IssueError(502, 'github-unavailable') }
+  if (installed?.permissions?.issues !== 'write') return { mode: 'permissions' as const, authorizationPath: installUrl(config), labels, recheck }
+  const token = await issueUserToken(config, db, session.userId, fetchImpl)
+  if (!token) return { mode: 'authorize' as const, authorizationPath: ISSUE_LOGIN_PATH, labels, recheck }
+  // All requested labels are optional, including security and operator labels.
+  // Omit missing names rather than rejecting issue creation or creating labels.
+  const existingLabels: string[] = []
+  for (const name of labels) {
+    const label = await github(`${path}/labels/${encodeURIComponent(name)}`, token, fetchImpl)
+    if (label.status === 401) return { mode: 'authorize' as const, authorizationPath: ISSUE_LOGIN_PATH, labels, recheck }
+    if (label.status === 404) continue
+    if (!label.ok) throw new IssueError(502, 'github-unavailable')
+    existingLabels.push(name)
+  }
+  return { mode: 'api' as const, token, path, labels: existingLabels, recheck,
+    db, findingId: context.findingId, repoId: repository.repoId, repository: targetRepository, repoIds, userId: session.userId }
+}
+
+export async function createGithubIssue(prepared: Awaited<ReturnType<typeof prepareGithubIssue>>, input: unknown, fetchImpl: typeof fetch = fetch) {
+  if (prepared.mode !== 'api') throw new IssueError(409, 'github-authorization-required')
+  const { title, body } = input as { title?: unknown; body?: unknown }
+  if (typeof title !== 'string' || !title.trim() || title.length > 256 || typeof body !== 'string' || body.length > 65_536) throw new IssueError(400, 'bad-issue')
+  const { db, findingId } = prepared
+  const requestId = randomToken()
+  if (!await db.claimManagedIssue({ findingId, repoId: prepared.repoId, repository: prepared.repository,
+    requestId, createdBy: prepared.userId, createdAt: Date.now() })) {
+    const stored = await db.getManagedIssue(findingId)
+    await prepared.recheck()
+    // The competing request may have released its reservation after a definite
+    // failure. Still return a listing, never a fresh creation form, for this race.
+    return stored ? referenceResult(stored, prepared.repoIds)
+      : { mode: 'pending' as const, repositoryUrl: `https://github.com/${prepared.repository}/issues` }
+  }
+  // The last awaited operation before the external write checks current access.
+  // Release only when we know no issue was created; unknown outcomes stay claimed.
+  try { await prepared.recheck() }
+  catch (error) { await db.releaseManagedIssue(findingId, requestId); throw error }
+  const response = await github(`${prepared.path}/issues`, prepared.token, fetchImpl, { title: title.trim(), body, labels: prepared.labels })
+  if (response.status >= 400 && response.status < 500) await db.releaseManagedIssue(findingId, requestId)
+  if (response.status === 401) throw new IssueError(409, 'github-authorization-required')
+  if (response.status === 403) throw new IssueError(403, 'github-issue-forbidden')
+  if (!response.ok) throw new IssueError(response.status === 422 ? 422 : 502, response.status >= 500 ? 'github-create-uncertain' : 'github-create-failed')
+  let issue: { number?: unknown }
+  try { issue = await response.json() } catch { throw new IssueError(502, 'github-create-uncertain') }
+  if (!Number.isSafeInteger(issue?.number) || Number(issue.number) <= 0) throw new IssueError(502, 'github-create-uncertain')
+  // Construct the URL from validated inputs, never an upstream redirect target.
+  const number = Number(issue.number), url = `https://github.com${prepared.path.slice('/repos'.length)}/issues/${issue.number}`
+  if (!await db.finishManagedIssue(findingId, requestId, url)) throw new IssueError(502, 'github-create-uncertain')
+  let details = issueDetails(issue, url, number, { title, body, labels: prepared.labels }), detailsUnavailable = true
+  try {
+    const fetched = await github(`${prepared.path}/issues/${number}`, prepared.token, fetchImpl)
+    if (fetched.ok) {
+      details = issueDetails(await fetched.json(), url, number, { title, body, labels: prepared.labels })
+      detailsUnavailable = false
+    }
+  } catch { /* Creation and its permanent reference succeeded; detail reads are best effort. */ }
+  try { await prepared.recheck() }
+  catch {
+    // The external write and permanent reference succeeded. Withhold details
+    // if current access cannot be confirmed, but never advertise a safe retry.
+    return { mode: 'created-unavailable' as const }
+  }
+  return { url, issue: details, detailsUnavailable }
+}

package/server-managed/github-metadata.ts

@@ -0,0 +1,213 @@
+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 GithubRepositoryVisibility {
+  repoId: number
+  github: string
+  public: boolean
+  checkedAt: number
+}
+// A commit's details, keyed by githubCommitKey. Commits never change, so an
+// entry is never refreshed or evicted.
+export interface GithubCommit {
+  key: string
+  message: string
+  authorName: string | null
+  authorLogin: string | null
+  authoredAt: number | null
+  committedAt: number | null
+  fetchedAt: number
+}
+export interface GithubTag { name: string; sha: string }
+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>
+  listGithubRepositoryVisibility(repoIds: readonly number[]): Promise<GithubRepositoryVisibility[]>
+  setGithubRepositoryVisibility(entries: readonly GithubRepositoryVisibility[]): Promise<void>
+}
+export interface GithubCommitStore {
+  listGithubCommits(keys: readonly string[]): Promise<GithubCommit[]>
+  setGithubCommits(entries: readonly GithubCommit[]): Promise<void>
+  // The cached tags that point to each commit, by githubCommitKey.
+  listGithubCommitTags(keys: readonly string[]): Promise<{ key: string; name: string }[]>
+  // `complete` is a listing of every tag the repository has: tags it leaves
+  // out were deleted. Otherwise only the listed tags are updated. `observedUs`
+  // orders overlapping refreshes (see githubCommitMethods).
+  refreshGithubTags(repoId: number, tags: readonly GithubTag[], complete: boolean, observedUs: number): Promise<void>
+}
+
+// A stable repository ID survives renames, as in the PR metadata keys.
+export function githubCommitKey(repoId: number, sha: string): string {
+  return `${repoId}:${sha}`
+}
+
+// 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 verify current user -> team -> repo grants plus either recently
+// verified public visibility or the viewer's live GitHub access with their token.
+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;
+CREATE TABLE IF NOT EXISTS managed_github_repository_visibility (
+  repo_id INTEGER PRIMARY KEY,
+  github TEXT NOT NULL,
+  is_public INTEGER NOT NULL CHECK (is_public IN (0, 1)),
+  checked_at INTEGER NOT NULL
+) STRICT;
+`
+// Bundles show their commit's details and tags from these tables. Readers rely
+// on bundle access alone; only a GitHub read made with access fills them.
+// Commits are retained without eviction. Create a bundle refreshes a
+// repository's tags, which go with the repository.
+export const GITHUB_COMMIT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_github_commit (
+  cache_key TEXT PRIMARY KEY,
+  message TEXT NOT NULL,
+  author_name TEXT,
+  author_login TEXT,
+  authored_at INTEGER,
+  committed_at INTEGER,
+  fetched_at INTEGER NOT NULL
+) STRICT;
+CREATE TABLE IF NOT EXISTS managed_github_tag (
+  repo_id INTEGER NOT NULL REFERENCES managed_selected_repo(repo_id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  commit_key TEXT NOT NULL,
+  observed_us INTEGER NOT NULL,
+  PRIMARY KEY (repo_id, name)
+) STRICT;
+CREATE INDEX IF NOT EXISTS managed_github_tag_commit_idx ON managed_github_tag(commit_key);
+CREATE TABLE IF NOT EXISTS managed_github_tag_listing (
+  repo_id INTEGER PRIMARY KEY REFERENCES managed_selected_repo(repo_id) ON DELETE CASCADE,
+  observed_us INTEGER NOT NULL
+) 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 < ?)`)
+  const visibility = db.prepare(`SELECT repo_id AS repoId, github, is_public AS public, checked_at AS checkedAt
+    FROM managed_github_repository_visibility WHERE repo_id IN (SELECT CAST(value AS BIGINT) FROM json_each(?))`)
+  const setVisibility = db.prepare(`INSERT INTO managed_github_repository_visibility (repo_id, github, is_public, checked_at)
+    SELECT CAST(json_extract(e.value, '$.repoId') AS BIGINT), json_extract(e.value, '$.github'),
+      CAST(json_extract(e.value, '$.public') AS BIGINT), CAST(json_extract(e.value, '$.checkedAt') AS BIGINT)
+    FROM json_each(:contexts) e WHERE 1 = 1
+    ON CONFLICT (repo_id) DO UPDATE SET github = excluded.github, is_public = excluded.is_public, checked_at = excluded.checked_at
+    WHERE managed_github_repository_visibility.checked_at < excluded.checked_at
+      OR (managed_github_repository_visibility.checked_at = excluded.checked_at
+        AND (managed_github_repository_visibility.is_public = 1 OR excluded.is_public = 0))`)
+  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)
+    },
+    async listGithubRepositoryVisibility(repoIds) {
+      if (repoIds.length === 0) return []
+      const rows = await visibility.all(JSON.stringify(repoIds)) as (Omit<GithubRepositoryVisibility, 'public'> & { public: number })[]
+      return rows.map(row => ({ ...row, public: row.public === 1 }))
+    },
+    async setGithubRepositoryVisibility(entries) {
+      if (entries.length > 0) await setVisibility.run({ contexts: JSON.stringify(entries.map(entry => ({ ...entry, public: entry.public ? 1 : 0 }))) })
+    },
+  }
+}
+
+export function githubCommitMethods(db: ManagedSql): GithubCommitStore {
+  const commits = db.prepare(`SELECT cache_key AS key, message, author_name AS authorName, author_login AS authorLogin,
+      authored_at AS authoredAt, committed_at AS committedAt, fetched_at AS fetchedAt
+    FROM managed_github_commit WHERE cache_key IN (SELECT value FROM json_each(?))`)
+  // Concurrent reads of one commit store the same details; the first stays.
+  const setCommits = db.prepare(`INSERT INTO managed_github_commit (cache_key, message, author_name, author_login, authored_at, committed_at, fetched_at)
+    SELECT json_extract(e.value, '$.key'), json_extract(e.value, '$.message'), json_extract(e.value, '$.authorName'),
+      json_extract(e.value, '$.authorLogin'), CAST(json_extract(e.value, '$.authoredAt') AS BIGINT),
+      CAST(json_extract(e.value, '$.committedAt') AS BIGINT), CAST(json_extract(e.value, '$.fetchedAt') AS BIGINT)
+    FROM json_each(:contexts) e WHERE 1 = 1
+    ON CONFLICT (cache_key) DO NOTHING`)
+  const commitTags = db.prepare(`SELECT commit_key AS key, name FROM managed_github_tag
+    WHERE commit_key IN (SELECT value FROM json_each(?)) ORDER BY commit_key, name`)
+  // Overlapping browses can finish out of order, so every refresh carries
+  // when it was observed (in microseconds). Each tag keeps the time it was
+  // last observed and only a later observation moves it; a complete listing
+  // deletes only the tags observed before it. The listing table holds the
+  // last complete listing applied: one observed no later knew whether every
+  // tag existed, so a refresh it supersedes is skipped (a tie keeps the first).
+  const lastListing = db.prepare('SELECT observed_us AS observedUs FROM managed_github_tag_listing WHERE repo_id = ?')
+  const setListing = db.prepare(`INSERT INTO managed_github_tag_listing (repo_id, observed_us) VALUES (?, ?)
+    ON CONFLICT (repo_id) DO UPDATE SET observed_us = excluded.observed_us`)
+  const deleteTags = db.prepare(`DELETE FROM managed_github_tag WHERE repo_id = ? AND observed_us < ?
+    AND name NOT IN (SELECT value FROM json_each(?))`)
+  const setTags = db.prepare(`INSERT INTO managed_github_tag (repo_id, name, commit_key, observed_us)
+    SELECT CAST(json_extract(e.value, '$.repoId') AS BIGINT), json_extract(e.value, '$.name'), json_extract(e.value, '$.key'),
+      CAST(json_extract(e.value, '$.observedUs') AS BIGINT)
+    FROM json_each(:contexts) e WHERE 1 = 1
+    ON CONFLICT (repo_id, name) DO UPDATE SET commit_key = excluded.commit_key, observed_us = excluded.observed_us
+    WHERE managed_github_tag.observed_us < excluded.observed_us`)
+  return {
+    async listGithubCommits(keys) {
+      if (keys.length === 0) return []
+      const rows = await commits.all(JSON.stringify(keys)) as GithubCommit[]
+      return rows.map(row => ({ ...row }))
+    },
+    async setGithubCommits(entries) {
+      if (entries.length > 0) await setCommits.run({ contexts: JSON.stringify(entries) })
+    },
+    async listGithubCommitTags(keys) {
+      if (keys.length === 0) return []
+      const rows = await commitTags.all(JSON.stringify(keys)) as { key: string; name: string }[]
+      return rows.map(row => ({ ...row }))
+    },
+    async refreshGithubTags(repoId, tags, complete, observedUs) {
+      // Writes hold the store's writer lock: the listing read stays current.
+      const last = (await lastListing.get(repoId) as { observedUs: number } | undefined)?.observedUs
+      if (last !== undefined && last >= observedUs) return
+      // Postgres refuses an upsert that names one row twice.
+      const unique = [...new Map(tags.map(tag => [tag.name, tag])).values()]
+      if (complete) {
+        await setListing.run(repoId, observedUs)
+        await deleteTags.run(repoId, observedUs, JSON.stringify(unique.map(tag => tag.name)))
+      }
+      if (unique.length > 0) {
+        await setTags.run({ contexts: JSON.stringify(unique.map(tag => ({ repoId, name: tag.name, key: githubCommitKey(repoId, tag.sha), observedUs }))) })
+      }
+    },
+  }
+}

package/server-managed/github-oauth.ts

@@ -0,0 +1,235 @@
+// GitHub App user authorization for managed sign-in. Configure no additional
+// account permissions on the App. Repository permissions are granted separately
+// at installation; login does not install the App or request OAuth scopes.
+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'
+import { isViewing } from './view-as.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. Keep account permissions minimal; repository
+// grants are approved separately when 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.
+export 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,
+  }
+}
+
+// The refreshes in flight in this process, by user. GitHub rotates refresh
+// tokens and refuses a spent one (bad_refresh_token), so requests that find the
+// token expired together share one refresh rather than race on the same token.
+const refreshing = new Map<string, Promise<string | null>>()
+// After GitHub refuses a refresh token, how long to wait before each further
+// read for the pair another instance got with it: a second in all.
+const STORED_PAIR_WAITS_MS = [100, 200, 300, 400]
+
+// 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.
+// An admin viewing as another user never borrows that user's GitHub access.
+export async function ensureUserAccessToken(
+  config: ManagedConfig, db: ManagedDb, userId: string, now: number, fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<string | null> {
+  if (isViewing()) return null
+  const tokens = await db.getUserTokens(userId)
+  if (tokens == null) return null
+  if (usableAt(tokens, now)) return tokens.accessToken
+  if (tokens.refreshToken == null) return null
+  let pending = refreshing.get(userId)
+  if (pending == null) {
+    pending = refreshStoredToken(config, db, userId, tokens.accessToken, tokens.refreshToken, now, fetchImpl)
+      .finally(() => refreshing.delete(userId))
+    refreshing.set(userId, pending)
+  }
+  return pending
+}
+
+function usableAt(tokens: UserTokens, now: number): boolean {
+  return tokens.expiresAt == null || tokens.expiresAt > now + 60_000
+}
+
+async function refreshStoredToken(
+  config: ManagedConfig, db: ManagedDb, userId: string, staleToken: string, refreshToken: string, now: number, fetchImpl: typeof fetch,
+): Promise<string | null> {
+  try {
+    const fresh = await refreshUserToken(config, refreshToken, now, fetchImpl)
+    await db.setUserTokens(userId, fresh)
+    return fresh.accessToken
+  } catch (err) {
+    // Another request or instance may have spent the refresh token first: use
+    // the pair it stored rather than leave this request to ask anonymously.
+    // Where GitHub refused the token, that pair may not be stored yet.
+    const waits = err instanceof OAuthError && err.message === 'github-token-denied' ? STORED_PAIR_WAITS_MS : []
+    for (const wait of [0, ...waits]) {
+      if (wait > 0) await new Promise(resolve => { setTimeout(resolve, wait) })
+      const stored = await db.getUserTokens(userId).catch(() => null)
+      if (stored != null && stored.accessToken !== staleToken && usableAt(stored, now)) return stored.accessToken
+    }
+    console.warn('managed: token refresh failed:', err)
+    return null
+  }
+}
+
+// Read the authenticated user's identity (`GET /user`).
+export 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'))
+}