@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/server-managed/github-issue-links.ts

@@ -0,0 +1,140 @@
+import { type GithubFixResult, githubIssueClosedReason, isGithubRepoName, parseGithubFixUrl } from '../common/github-pr.ts'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, TeamReportAccessSnapshot } from './db.ts'
+import type { ManagedIssue } from './managed-issues.ts'
+import { ensureUserAccessToken } from './github-oauth.ts'
+import { lookupFixes } from './github-pulls.ts'
+
+export type IssueFixUpdate = { findingId: string; issueUrl: string; previous: string | null; next: string | null; checkedAt: number }
+type Pull = { number: number; title: string; body: string | null; state: string; isDraft: boolean; createdAt: string;
+  repository: { databaseId: number; nameWithOwner: string } }
+type Connection = { nodes: Pull[]; pageInfo: { hasNextPage: boolean; endCursor: string | null } }
+type Issue = { number: number; title: string; body: string | null; state: string; stateReason: string | null; closedByPullRequestsReferences?: Connection }
+type Repository = TeamReportAccessSnapshot['repositories'][number]
+type Job = { repo: Repository; kind: 'pull' | 'issue'; number: number; aliases: string[];
+  linked: boolean; cursor: string | null; pulls: Pull[]; complete: boolean }
+type Metadata = Exclude<GithubFixResult, { error: string }>
+const pullFields = 'number title body state isDraft createdAt repository { databaseId nameWithOwner }'
+
+function metadataQuery(jobs: Job[]) {
+  return `{ ${jobs.map((job, index) => {
+    const [owner, name] = job.repo.github.split('/')
+    const fields = job.kind === 'pull' ? pullFields : `number title body state stateReason ${job.linked
+      ? `closedByPullRequestsReferences(first: 100, includeClosedPrs: true, after: ${JSON.stringify(job.cursor)}) { nodes { ${pullFields} } pageInfo { hasNextPage endCursor } }` : ''}`
+    return `r${index}: repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { databaseId nameWithOwner item: ${job.kind === 'pull' ? 'pullRequest' : 'issue'}(number: ${job.number}) { ${fields} } }`
+  }).join('\n')} }`
+}
+
+function itemMetadata(item: Issue | Pull, kind: Job['kind']): Omit<Metadata, 'url'> | null {
+  if (!item || typeof item.title !== 'string' || !item.title.trim() || item.title.length > 1024
+    || item.body != null && typeof item.body !== 'string' || !['OPEN', 'CLOSED', ...(kind === 'pull' ? ['MERGED'] : [])].includes(item.state)) return null
+  const status = item.state === 'MERGED' ? 'merged' : item.state === 'CLOSED' ? 'closed' : 'isDraft' in item && item.isDraft === true ? 'draft' : 'open'
+  const stateReason = kind === 'issue' && status === 'closed' ? githubIssueClosedReason(String((item as Issue).stateReason).toLowerCase()) : null
+  return { title: item.title, description: item.body ?? null, status, stateReason }
+}
+
+function readPage(job: Job, item: Issue | Pull, metadata: Map<string, Metadata>): boolean {
+  const details = itemMetadata(item, job.kind)
+  if (!details || item.number !== job.number) return false
+  for (const url of job.aliases) metadata.set(url, { url, ...details })
+  if (!job.linked) return false
+  const connection = (item as Issue).closedByPullRequestsReferences
+  if (!connection || !Array.isArray(connection.nodes) || typeof connection.pageInfo?.hasNextPage !== 'boolean'
+    || connection.nodes.some(pr => !pr || !Number.isSafeInteger(pr.number) || pr.number <= 0 || typeof pr.createdAt !== 'string'
+      || !Number.isFinite(Date.parse(pr.createdAt)) || !itemMetadata(pr, 'pull') || typeof pr.isDraft !== 'boolean'
+      || !Number.isSafeInteger(pr.repository?.databaseId) || typeof pr.repository?.nameWithOwner !== 'string' || !isGithubRepoName(pr.repository.nameWithOwner))) return false
+  job.pulls.push(...connection.nodes)
+  if (!connection.pageInfo.hasNextPage) { job.complete = true; return false }
+  if (typeof connection.pageInfo.endCursor !== 'string' || !connection.pageInfo.endCursor || connection.pageInfo.endCursor === job.cursor) return false
+  job.cursor = connection.pageInfo.endCursor
+  return true
+}
+
+function issueUpdates(jobs: Job[], issues: ManagedIssue[], allowed: Map<string, Repository>, checkedAt: number, metadata: Map<string, Metadata>) {
+  const updates: IssueFixUpdate[] = []
+  // The issues each job's issue is, by repository and number, read once.
+  const byIssue = new Map<string, ManagedIssue[]>()
+  for (const issue of issues) {
+    const ref = parseGithubFixUrl(issue.issueUrl)
+    if (ref?.kind !== 'issue') continue
+    const key = `${issue.repoId}:${ref.number}`, same = byIssue.get(key)
+    if (same) same.push(issue)
+    else byIssue.set(key, [issue])
+  }
+  for (const job of jobs) {
+    if (!job.linked || !job.complete) continue
+    // "Last" means the newest PR by creation time, never its latest comment.
+    const latest = job.pulls.filter(pr => pr.state !== 'CLOSED').toSorted((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || b.number - a.number)[0]
+    const repo = latest && allowed.get(latest.repository.nameWithOwner.toLowerCase())
+    // The viewer's token can have broader access than this workspace. Never
+    // persist or disclose a PR from outside the workspace repository grants.
+    if (latest && (!repo || repo.repoId !== latest.repository.databaseId)) continue
+    const next = latest ? `https://github.com/${repo!.github}/pull/${latest.number}` : null
+    if (latest && next) metadata.set(next, { url: next, ...itemMetadata(latest, 'pull')! })
+    // Only a changed derived Fix is written: an unchanged one's check time
+    // alone would bump the annotations revision that every open team feed
+    // polls, for nothing they show. Changes still stamp it, so an older lookup
+    // never replaces a newer change (managed-issues.ts). An older lookup that
+    // differs can now land after a newer unchanged one, as it could already
+    // land before it (whose compare-and-set then fails); either way the next
+    // lookup finds the stored Fix differs, and writes the current one.
+    for (const issue of byIssue.get(`${job.repo.repoId}:${job.number}`) ?? []) {
+      if (issue.autoFixUrl !== next) updates.push({ findingId: issue.findingId, issueUrl: issue.issueUrl!, previous: issue.autoFixUrl, next, checkedAt })
+    }
+  }
+  return updates
+}
+
+// Fetch issue details, linked PR states and manual Fix metadata in one batch.
+// Pagination and workspaces with over 200 distinct links need further batches.
+// Live GraphQL results prove this viewer's access; never publish them into the
+// REST shared cache under an older public-visibility grant.
+export async function lookupIssueLinks(config: ManagedConfig, db: ManagedDb, snapshot: TeamReportAccessSnapshot,
+  urls: string[], issues: ManagedIssue[], fetchImpl: typeof fetch = fetch): Promise<{ fixes: GithubFixResult[]; updates: IssueFixUpdate[] }> {
+  const checkedAt = Date.now(), signal = AbortSignal.timeout(10_000)
+  const allowed = new Map(snapshot.repositories.filter(repo => isGithubRepoName(repo.github)).map(repo => [repo.github.toLowerCase(), repo]))
+  const jobs = new Map<string, Job>()
+  const linked = new Set(issues.filter(issue => issue.issueUrl).map(issue => {
+    const ref = parseGithubFixUrl(issue.issueUrl)
+    return ref?.kind === 'issue' ? `${issue.repoId}:issue:${ref.number}` : ''
+  }))
+  for (const url of urls) {
+    const ref = parseGithubFixUrl(url), repo = ref && allowed.get(ref.repo.toLowerCase())
+    if (!ref || !repo) continue
+    const key = `${repo.repoId}:${ref.kind}:${ref.number}`, previous = jobs.get(key)
+    if (previous) { previous.aliases.push(url); continue }
+    jobs.set(key, { repo, kind: ref.kind, number: ref.number, aliases: [url], linked: linked.has(key), cursor: null, pulls: [], complete: false })
+  }
+  if (jobs.size === 0) return { fixes: [], updates: [] }
+  const withinDeadline: typeof fetch = (input, init) => { signal.throwIfAborted(); return fetchImpl(input, { ...init, signal }) }
+  const token = await ensureUserAccessToken(config, db, snapshot.user.id, checkedAt, withinDeadline)
+  if (!token) return { fixes: await lookupFixes(config, db, snapshot, urls, withinDeadline), updates: [] }
+  const metadata = new Map<string, Metadata>(), selected = [...jobs.values()]
+  let pending = selected
+  for (let page = 0; pending.length > 0 && page < 100 && !signal.aborted; page++) {
+    const batch = pending.slice(0, 200), query = metadataQuery(batch)
+    let data: Record<string, { databaseId: number; nameWithOwner: string; item: Issue | Pull } | null>
+    try {
+      const response = await withinDeadline('https://api.github.com/graphql', {
+        method: 'POST', redirect: 'error',
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', 'user-agent': 'deepview-triage' }, body: JSON.stringify({ query }),
+      })
+      if (!response.ok) break
+      const body = await response.json() as { data?: typeof data; errors?: { path?: unknown[] }[] }
+      // Errors attached to an alias invalidate that whole job, including its
+      // connection. Other aliases can succeed even if one issue was deleted.
+      if (!body?.data || body.errors != null && (!Array.isArray(body.errors)
+        || body.errors.some(error => typeof error?.path?.[0] !== 'string' || !/^r\d+$/u.test(error.path[0])))) break
+      data = body.data
+      for (const error of body.errors ?? []) data[error.path![0] as string] = null
+    } catch { break }
+    pending = pending.slice(batch.length)
+    for (const [index, job] of batch.entries()) {
+      const repository = data[`r${index}`]
+      if (repository?.databaseId !== job.repo.repoId || typeof repository.nameWithOwner !== 'string' || repository.nameWithOwner.toLowerCase() !== job.repo.github.toLowerCase()) continue
+      if (readPage(job, repository.item, metadata)) pending.push(job)
+    }
+  }
+  const updates = issueUpdates(selected, issues, allowed, checkedAt, metadata)
+  return { fixes: [...metadata.values()], updates }
+}

package/server-managed/github-issue-oauth.ts

@@ -0,0 +1,47 @@
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession } from './db.ts'
+import { randomToken, safeEqual } from './crypto.ts'
+import { ISSUE_STATE_COOKIE, buildCookie, clearCookie, cookieName, parseCookies } from './session.ts'
+import { OAuthError, ensureUserAccessToken, exchangeCode, fetchIdentity } from './github-oauth.ts'
+
+export const ISSUE_LOGIN_PATH = '/api/oauth/github/issues/login'
+
+export function isIssueOAuthCallback(config: ManagedConfig, query: URLSearchParams, cookie: string | undefined): boolean {
+  const expected = parseCookies(cookie).get(cookieName(config, ISSUE_STATE_COOKIE))?.split('.')[0]
+  return !!expected && safeEqual(query.get('state') ?? '', expected)
+}
+
+export function issueLoginRedirect(config: ManagedConfig, session: ManagedSession, now = Date.now()) {
+  const state = randomToken()
+  const url = new URL('https://github.com/login/oauth/authorize')
+  url.searchParams.set('client_id', config.githubClientId)
+  url.searchParams.set('redirect_uri', config.oauthCallbackUrl)
+  url.searchParams.set('state', state)
+  url.searchParams.set('allow_signup', 'false')
+  // Reauthorize the same app for the current account, without replacing the
+  // DeepView session or permitting an OAuth account switch during creation.
+  const value = `${state}.${session.id}.${now}`
+  return { location: url.href, setCookie: buildCookie(cookieName(config, ISSUE_STATE_COOKIE), value,
+    { secure: config.cookieSecure, maxAgeS: 600, sameSite: 'Lax' }) }
+}
+
+export async function issueOAuthCallback(config: ManagedConfig, db: ManagedDb, session: ManagedSession,
+  query: URLSearchParams, cookie: string | undefined, fetchImpl: typeof fetch = fetch, now = Date.now()) {
+  const [expected, sessionId, timestamp] = (parseCookies(cookie).get(cookieName(config, ISSUE_STATE_COOKIE)) ?? '').split('.')
+  const code = query.get('code'), state = query.get('state')
+  if (!code || !state || !expected || !safeEqual(state, expected) || sessionId !== session.id
+    || !timestamp || !Number.isFinite(Number(timestamp)) || now < Number(timestamp) || now - Number(timestamp) > 600_000) {
+    throw new OAuthError(400, 'invalid-oauth-state')
+  }
+  const tokens = await exchangeCode(config, code, now, fetchImpl)
+  const identity = await fetchIdentity(tokens.accessToken, fetchImpl)
+  if (identity.githubUserId !== await db.getUserGithubId(session.userId)) throw new OAuthError(403, 'github-account-mismatch')
+  const current = await db.sessionWithUser(session.id, Date.now())
+  if (!current || current.user.role === 'none' || current.session.userId !== session.userId) throw new OAuthError(401, 'unauthenticated')
+  await db.setUserTokens(session.userId, tokens)
+  return { location: '/github-issue-authorized.html', setCookie: clearCookie(cookieName(config, ISSUE_STATE_COOKIE), config.cookieSecure) }
+}
+
+export function issueUserToken(config: ManagedConfig, db: ManagedDb, userId: string, fetchImpl: typeof fetch = fetch) {
+  return ensureUserAccessToken(config, db, userId, Date.now(), fetchImpl)
+}

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-link-oauth.ts

@@ -0,0 +1,69 @@
+// Linking another GitHub account to the signed-in user (github-links.ts): the
+// App's user authorization again, completed by the account to link. GitHub is
+// asked for its account picker, as the browser is usually signed in to the
+// account the user signs in here with. The token GitHub grants reads the
+// account's identity and avatar; it is never stored.
+import type { AvatarStore } from './avatar-store.ts'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession } from './db.ts'
+import { randomToken, safeEqual } from './crypto.ts'
+import { LINK_STATE_COOKIE, buildCookie, clearCookie, cookieName, parseCookies } from './session.ts'
+import { OAuthError, cacheAvatar, exchangeCode, fetchIdentity } from './github-oauth.ts'
+import { ManagedMutationError } from './management.ts'
+
+export const LINK_LOGIN_PATH = '/api/oauth/github/link'
+// The profile page, where linking starts and its callback lands.
+const PROFILE_PATH = '/my/profile'
+const STATE_TTL_MS = 600_000
+
+export function isLinkOAuthCallback(config: ManagedConfig, query: URLSearchParams, cookie: string | undefined): boolean {
+  const expected = parseCookies(cookie).get(cookieName(config, LINK_STATE_COOKIE))?.split('.')[0]
+  return !!expected && safeEqual(query.get('state') ?? '', expected)
+}
+
+// The state is bound to the session that started linking, so the account
+// links to the user who asked, never to whoever is signed in on return.
+export function linkLoginRedirect(config: ManagedConfig, session: ManagedSession, now = Date.now()): { location: string; setCookie: string } {
+  const state = randomToken()
+  const url = new URL('https://github.com/login/oauth/authorize')
+  url.searchParams.set('client_id', config.githubClientId)
+  url.searchParams.set('redirect_uri', config.oauthCallbackUrl)
+  url.searchParams.set('state', state)
+  url.searchParams.set('allow_signup', 'false')
+  url.searchParams.set('prompt', 'select_account')
+  return { location: url.href, setCookie: buildCookie(cookieName(config, LINK_STATE_COOKIE), `${state}.${session.id}.${now}`,
+    { secure: config.cookieSecure, maxAgeS: STATE_TTL_MS / 1000, sameSite: 'Lax' }) }
+}
+
+// Back from GitHub: link the account that authorized, then land on the
+// profile, naming the refusal (`link-error`) when it was refused.
+// `linked` is the login of an account linked anew.
+export async function linkOAuthCallback(config: ManagedConfig, db: ManagedDb, session: ManagedSession,
+  query: URLSearchParams, cookie: string | undefined,
+  { avatarStore, fetchImpl = fetch, now = Date.now() }: { avatarStore?: AvatarStore; fetchImpl?: typeof fetch; now?: number } = {},
+): Promise<{ location: string; setCookie: string; linked: string | null }> {
+  const setCookie = clearCookie(cookieName(config, LINK_STATE_COOKIE), config.cookieSecure)
+  try {
+    const [expected, sessionId, timestamp] = (parseCookies(cookie).get(cookieName(config, LINK_STATE_COOKIE)) ?? '').split('.')
+    const code = query.get('code'), started = Number(timestamp), state = query.get('state')
+    if (!state || !expected || !safeEqual(state, expected) || sessionId !== session.id
+      || !timestamp || !Number.isFinite(started) || now < started || now - started > STATE_TTL_MS) {
+      throw new OAuthError(400, 'invalid-oauth-state')
+    }
+    // Declined on GitHub's side, which sends an error in place of a code.
+    if (!code) throw new OAuthError(400, query.get('error') ? 'github-authorization-declined' : 'invalid-oauth-state')
+    const tokens = await exchangeCode(config, code, now, fetchImpl)
+    const account = await fetchIdentity(tokens.accessToken, fetchImpl)
+    const link = await db.linkGithubAccount(session.id, account, now)
+    // Best-effort, as at sign-in: the avatar falls back to an initial.
+    if (avatarStore != null && account.avatarUrl != null) {
+      await cacheAvatar(avatarStore, link.id, account.avatarUrl, fetchImpl).catch((err) => {
+        console.warn('managed: linked avatar cache failed:', err)
+      })
+    }
+    return { location: PROFILE_PATH, setCookie, linked: link.created ? account.login : null }
+  } catch (err) {
+    if (!(err instanceof OAuthError || err instanceof ManagedMutationError)) throw err
+    return { location: `${PROFILE_PATH}?${new URLSearchParams({ 'link-error': err.message })}`, setCookie, linked: null }
+  }
+}

package/server-managed/github-links.ts

@@ -0,0 +1,204 @@
+// GitHub accounts a user links to their own on the profile page. A linked
+// account's identity is reserved for that user: it can neither sign in nor
+// register (upsertUser refuses it in the transaction that would create the
+// user), and an account that has registered cannot be linked. The user's
+// login and GitHub id stay the sign-in account's; the displayed name and
+// avatar may come from any of their accounts.
+import { randomUUID } from 'node:crypto'
+import type { ManagedUser } from './db-methods.ts'
+import { ManagedMutationError } from './management.ts'
+import type { ManagedSql } from './sql.ts'
+
+// login/name are snapshots of the account as it was last linked; linking it
+// again refreshes them. Its avatar is cached under the link id (avatar-store.ts).
+export const GITHUB_LINK_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_github_link (
+  id             TEXT PRIMARY KEY,
+  user_id        TEXT NOT NULL REFERENCES managed_user(id) ON DELETE CASCADE,
+  github_user_id INTEGER NOT NULL UNIQUE,
+  login          TEXT NOT NULL,
+  name           TEXT,
+  linked_at      INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS managed_github_link_user_idx ON managed_github_link(user_id);
+`
+
+// managed_user columns added with the table. managed_user.name is the
+// displayed name; github_name keeps the sign-in account's own. name_link and
+// avatar_link name the linked account each comes from, NULL the sign-in one.
+export const GITHUB_LINK_USER_COLUMNS: readonly (readonly [string, string])[] = [
+  ['github_name', 'TEXT'],
+  ['name_link', 'TEXT REFERENCES managed_github_link(id) ON DELETE SET NULL'],
+  ['avatar_link', 'TEXT REFERENCES managed_github_link(id) ON DELETE SET NULL'],
+]
+
+export interface LinkedGithubAccount {
+  id: string
+  // Its GitHub account's numeric id, which GitHub never gives another.
+  githubId: number
+  login: string
+  name: string | null
+  linkedAt: number
+}
+
+export interface ManagedProfile {
+  // Always the sign-in account's.
+  login: string
+  // The displayed name, and the sign-in account's own GitHub name.
+  name: string | null
+  githubName: string | null
+  // The linked account the displayed name or avatar comes from, null the sign-in one.
+  nameAccount: string | null
+  avatarAccount: string | null
+  accounts: LinkedGithubAccount[]
+}
+
+// A user as the app shows them where a GitHub login of theirs is named: by
+// their id, whose avatar /api/avatar/<id> serves (the one they chose), their
+// sign-in login and the name they chose.
+export interface AppUser {
+  id: string
+  login: string
+  name: string | null
+}
+
+// Which account the displayed name and avatar each come from: a linked
+// account's id, or null for the sign-in account. An absent key is unchanged.
+export interface ProfileChoice {
+  name?: string | null
+  avatar?: string | null
+}
+
+export interface GithubLinkStore {
+  getProfile(userId: string): Promise<ManagedProfile | null>
+  // Link `account` to the session's own user, or refresh the snapshot of one
+  // they linked before. Refused for the sign-in account itself, an account
+  // another user linked, and any account that has registered.
+  linkGithubAccount(sessionId: string, account: ManagedUser, now: number): Promise<{ id: string; created: boolean }>
+  // Unlink one of the session user's accounts, which may then sign in or
+  // register again; a name or avatar it gave falls back to the sign-in
+  // account's. Null when the user has no such link.
+  unlinkGithubAccount(sessionId: string, id: string, now: number): Promise<LinkedGithubAccount | null>
+  setProfileChoice(sessionId: string, choice: ProfileChoice, now: number): Promise<void>
+  // The avatar to serve for `id`: a user's chosen linked account's, else `id`'s own.
+  getAvatarKey(id: string): Promise<string>
+  // The approved users signing in with, or having linked, each of
+  // `accounts`, by the login as asked: by the account's numeric id where it
+  // is known, which GitHub never gives another; else by its login (matched
+  // regardless of case, as GitHub matches them), one more than one user
+  // claims, renamed on GitHub since another signed in with it or linked it,
+  // left out. No access users are left out.
+  listUsersByAccount(accounts: readonly GithubAccount[]): Promise<Record<string, AppUser>>
+}
+
+// A GitHub account a repository's activity names: by its login, and its
+// numeric id where GitHub told it.
+export interface GithubAccount { login: string; githubId: number | null }
+
+type LinkRow = { id: string; githubId: number; login: string; name: string | null; linkedAt: number }
+const accountOf = (row: LinkRow): LinkedGithubAccount => ({ id: row.id, githubId: row.githubId, login: row.login, name: row.name, linkedAt: row.linkedAt })
+
+// GithubLinkStore.listUsersByAccount.
+async function usersByAccount(db: ManagedSql, accounts: readonly GithubAccount[]): Promise<Record<string, AppUser>> {
+  if (accounts.length === 0) return {}
+  const ids = accounts.flatMap(account => account.githubId ?? [])
+  const logins = accounts.flatMap(account => account.githubId === null ? [account.login] : [])
+  const rows = await db.prepare(`SELECT a.login, a.githubId, u.id, u.login AS appLogin, u.name, u.role FROM (
+      SELECT login, github_user_id AS githubId, id AS claimant FROM managed_user
+      UNION ALL SELECT login, github_user_id AS githubId, user_id AS claimant FROM managed_github_link
+    ) a JOIN managed_user u ON u.id = a.claimant
+    WHERE a.githubId IN (SELECT CAST(value AS BIGINT) FROM json_each(?)) OR lower(a.login) IN (SELECT lower(value) FROM json_each(?))`)
+    .all(JSON.stringify(ids), JSON.stringify(logins)) as { login: string; githubId: number; id: string; appLogin: string; name: string | null; role: string }[]
+  const byId = new Map(rows.map(row => [row.githubId, row]))
+  const claims = new Map<string, typeof rows>()
+  for (const row of rows) claims.set(row.login.toLowerCase(), [...claims.get(row.login.toLowerCase()) ?? [], row])
+  const users: Record<string, AppUser> = {}
+  for (const { login, githubId } of accounts) {
+    const [user, ...others] = githubId === null ? claims.get(login.toLowerCase()) ?? [] : byId.has(githubId) ? [byId.get(githubId)!] : []
+    if (!user || user.role === 'none' || others.some(other => other.id !== user.id)) continue
+    users[login] = { id: user.id, login: user.appLogin, name: user.name }
+  }
+  return users
+}
+
+export function githubLinkMethods(db: ManagedSql): GithubLinkStore {
+  // Linking is the session user's own act: never an admin's view as them,
+  // nor an account that has not been approved for the workspace.
+  async function sessionUser(sessionId: string, now: number): Promise<{ id: string; githubId: number }> {
+    const row = await db.prepare(`SELECT u.id, u.github_user_id AS githubId, u.role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+      WHERE s.id = ? AND s.expires_at > ? AND s.viewer_session IS NULL`).get(sessionId, now) as { id: string; githubId: number; role: string } | undefined
+    if (!row) throw new ManagedMutationError(401, 'unauthenticated')
+    if (row.role === 'none') throw new ManagedMutationError(403, 'forbidden')
+    return row
+  }
+  const linkOf = (userId: string, id: string) => db.prepare(`SELECT id, github_user_id AS githubId, login, name, linked_at AS linkedAt FROM managed_github_link
+    WHERE id = ? AND user_id = ?`).get(id, userId) as Promise<LinkRow | undefined>
+
+  return {
+    async getProfile(userId) {
+      const user = await db.prepare(`SELECT login, name, github_name AS githubName, name_link AS nameAccount, avatar_link AS avatarAccount
+        FROM managed_user WHERE id = ?`).get(userId) as Omit<ManagedProfile, 'accounts'> | undefined
+      if (!user) return null
+      const accounts = await db.prepare(`SELECT id, github_user_id AS githubId, login, name, linked_at AS linkedAt FROM managed_github_link
+        WHERE user_id = ? ORDER BY linked_at, id`).all(userId) as LinkRow[]
+      return { ...user, accounts: accounts.map(accountOf) }
+    },
+    async linkGithubAccount(sessionId, account, now) {
+      const user = await sessionUser(sessionId, now)
+      if (account.githubUserId === user.githubId) throw new ManagedMutationError(409, 'github-account-own')
+      if (await db.prepare('SELECT 1 AS found FROM managed_user WHERE github_user_id = ?').get(account.githubUserId)) {
+        throw new ManagedMutationError(409, 'github-account-registered')
+      }
+      const existing = await db.prepare('SELECT id, user_id AS userId FROM managed_github_link WHERE github_user_id = ?')
+        .get(account.githubUserId) as { id: string; userId: string } | undefined
+      if (existing && existing.userId !== user.id) throw new ManagedMutationError(409, 'github-account-linked')
+      if (existing) {
+        await db.prepare('UPDATE managed_github_link SET login = ?, name = ? WHERE id = ?').run(account.login, account.name, existing.id)
+        await db.prepare('UPDATE managed_user SET name = ?, updated_at = ? WHERE id = ? AND name_link = ?').run(account.name, now, user.id, existing.id)
+        return { id: existing.id, created: false }
+      }
+      const id = randomUUID()
+      await db.prepare(`INSERT INTO managed_github_link (id, user_id, github_user_id, login, name, linked_at)
+        VALUES (?, ?, ?, ?, ?, ?)`).run(id, user.id, account.githubUserId, account.login, account.name, now)
+      return { id, created: true }
+    },
+    async unlinkGithubAccount(sessionId, id, now) {
+      const user = await sessionUser(sessionId, now)
+      const link = await linkOf(user.id, id)
+      if (!link) return null
+      await db.prepare(`UPDATE managed_user SET
+          name = CASE WHEN name_link = :link THEN github_name ELSE name END,
+          name_link = CASE WHEN name_link = :link THEN NULL ELSE name_link END,
+          avatar_link = CASE WHEN avatar_link = :link THEN NULL ELSE avatar_link END,
+          updated_at = :now
+        WHERE id = :user`).run({ link: id, now, user: user.id })
+      await db.prepare('DELETE FROM managed_github_link WHERE id = ?').run(id)
+      return accountOf(link)
+    },
+    async setProfileChoice(sessionId, choice, now) {
+      const user = await sessionUser(sessionId, now)
+      const links = new Map<string, LinkRow>()
+      for (const id of [choice.name, choice.avatar]) {
+        if (id == null || links.has(id)) continue
+        const link = await linkOf(user.id, id)
+        if (!link) throw new ManagedMutationError(404, 'no-account')
+        links.set(id, link)
+      }
+      if (choice.name !== undefined) {
+        // A linked account without a name leaves the user without one too.
+        await db.prepare(`UPDATE managed_user SET name_link = :link,
+            name = CASE WHEN :link IS NULL THEN github_name ELSE :name END, updated_at = :now
+          WHERE id = :user`).run({ link: choice.name, name: choice.name === null ? null : links.get(choice.name)!.name, now, user: user.id })
+      }
+      if (choice.avatar !== undefined) {
+        await db.prepare('UPDATE managed_user SET avatar_link = ?, updated_at = ? WHERE id = ?').run(choice.avatar, now, user.id)
+      }
+    },
+    async getAvatarKey(id) {
+      const row = await db.prepare('SELECT avatar_link AS link FROM managed_user WHERE id = ?').get(id) as { link: string | null } | undefined
+      return row?.link ?? id
+    },
+    listUsersByAccount: accounts => usersByAccount(db, accounts),
+  }
+}