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

package/server-managed/github-app.ts

@@ -0,0 +1,415 @@
+// Repository discovery uses the signed-in user token and App installation
+// tokens. Login and repository installation can use one GitHub App: user
+// authorization requests account permissions, installation grants repository
+// permissions. Discovery itself is read-only and skips archived repositories.
+import { Buffer } from 'node:buffer'
+import { createHash, createSign } from 'node:crypto'
+import { createClient } from '@preventive/upstream/github.js'
+import type { ManagedConfig } from './config.ts'
+import { GithubApiError, githubUnreachable, throwGithubResponseError, upstreamGithub } from './github-errors.ts'
+import { onTokenRejected, shareGithubRead, tokenRejected } from './github-requests.ts'
+import { timed } from './request-timing.ts'
+
+export { GithubApiError } from './github-errors.ts'
+export { onTokenRejected } from './github-requests.ts'
+
+const GITHUB_API = 'https://api.github.com'
+const API_VERSION = '2022-11-28'
+const USER_AGENT = 'deepview-triage'
+const PER_PAGE = 100
+const INSTALLATION_TOKEN_TTL_MS = 5 * 60_000
+const INSTALLATION_TOKEN_EXPIRY_MARGIN_MS = 60_000
+const MAX_INSTALLATION_TOKENS = 256
+interface InstallationTokenEntry { token: string | null; expiresAt: number; pending: Promise<string> | null }
+// Credentials only: visibility, user identities, and permissions are never
+// cached here. Bound memory per transport and separate App/key/install scopes.
+const installationTokens = new WeakMap<typeof fetch, Map<string, InstallationTokenEntry>>()
+
+// A token GitHub rejected (401): an installation's no longer reused.
+onTokenRejected((token, fetchImpl) => {
+  const cache = installationTokens.get(fetchImpl)
+  if (!cache) return
+  for (const [key, entry] of cache) if (entry.token === token) cache.delete(key)
+})
+
+// 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
+}
+
+// App installation credentials are 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, `body` sent as JSON (a GraphQL
+// query's, given longer to answer). Network / non-2xx / malformed fold into a
+// GithubApiError (401 passes through for the caller to handle). Identical GETs
+// share an outstanding read through its body. POSTs only opt in for read-only
+// GraphQL queries (repository-history.ts), never for mutations or token mints.
+export function githubJson(url: string, token: string | null, fetchImpl: typeof fetch, method: 'GET' | 'POST' = 'GET', body?: unknown,
+  readOnly = method === 'GET'): Promise<unknown> {
+  if (readOnly) return shareGithubRead(fetchImpl, JSON.stringify([url, token, method, body]), () => githubJson(url, token, fetchImpl, method, body, false))
+  // Each call told in its request's Server-Timing (request-timing.ts).
+  return timed('gh', async () => {
+    let res: Response
+    const started = Date.now()
+    try {
+      res = await fetchImpl(url, {
+        method,
+        signal: AbortSignal.timeout(body === undefined ? 10_000 : 20_000),
+        redirect: 'error',
+        headers: {
+          ...(token == null ? {} : { authorization: `Bearer ${token}` }), 'accept': 'application/vnd.github+json',
+          ...(body === undefined ? {} : { 'content-type': 'application/json' }), 'user-agent': USER_AGENT, 'x-github-api-version': API_VERSION,
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      })
+    } catch (error) { throw githubUnreachable(error, started) }
+    if (res.status === 401 && token) tokenRejected(token, fetchImpl)
+    if (!res.ok) await throwGithubResponseError(res)
+    // The answer's body is read within the same timeout: one not read whole is
+    // GitHub not reached, as one not answered is; only one that isn't JSON is
+    // malformed.
+    try { return await res.json() } catch (error) {
+      throw error instanceof SyntaxError ? new GithubApiError(502, 'github-malformed') : githubUnreachable(error, started)
+    }
+  })
+}
+
+// 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): Promise<ConnectedRepo> {
+  if (publicRepositoryName(fullName) !== fullName) throw new GithubApiError(400, 'bad-repository')
+  const repo = parseRepo(await upstreamGithub(() => createClient({ token: null, userAgent: USER_AGENT }).getRepo({ repo: fullName })), 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): Promise<ConnectedRepo[]> {
+  const byName = new Map<string, ConnectedRepo>()
+  const body = await upstreamGithub(() => createClient({ token: accessToken, userAgent: USER_AGENT }).listUserRepos())
+  for (const r of body) {
+    const repo = parseRepo(r, null)
+    if (repo != null) byName.set(repo.fullName, repo)
+  }
+  return [...byName.values()].toSorted((a, b) => a.fullName.localeCompare(b.fullName))
+}
+
+// ── PRIVATE: App 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
+}
+
+// Reuse installation credentials only in this process. Refresh well before
+// expiry and coalesce concurrent mints; failed or undated tokens are not cached.
+async function installationAccessToken(appId: string, privateKey: string, installId: number, fetchImpl: typeof fetch): Promise<string> {
+  let cache = installationTokens.get(fetchImpl)
+  if (!cache) { cache = new Map(); installationTokens.set(fetchImpl, cache) }
+  const now = Date.now()
+  for (const [key, entry] of cache) if (!entry.pending && entry.expiresAt <= now) cache.delete(key)
+  const key = JSON.stringify([appId, createHash('sha256').update(privateKey).digest('hex'), installId])
+  const cached = cache.get(key)
+  if (cached) {
+    cache.delete(key)
+    cache.set(key, cached)
+    if (cached.pending) return cached.pending
+    return cached.token!
+  }
+  const entry: InstallationTokenEntry = { token: null, expiresAt: 0, pending: null }
+  const pending = Promise.resolve().then(async () => {
+    try {
+      const jwt = appJwt(appId, privateKey)
+      const body = await githubJson(`${GITHUB_API}/app/installations/${installId}/access_tokens`, jwt, fetchImpl, 'POST') as { token?: unknown; expires_at?: unknown }
+      if (typeof body?.token !== 'string' || body.token === '') throw new GithubApiError(502, 'github-install-token-denied')
+      entry.token = body.token
+      const expiresAt = typeof body.expires_at === 'string' ? Date.parse(body.expires_at) : NaN
+      entry.expiresAt = Number.isFinite(expiresAt) ? Math.min(now + INSTALLATION_TOKEN_TTL_MS, expiresAt - INSTALLATION_TOKEN_EXPIRY_MARGIN_MS) : 0
+      if (entry.expiresAt <= Date.now() && cache.get(key) === entry) cache.delete(key)
+      return body.token
+    } catch (err) {
+      if (cache.get(key) === entry) cache.delete(key)
+      throw err
+    } finally { entry.pending = null }
+  })
+  entry.pending = pending
+  cache.set(key, entry)
+  if (cache.size > MAX_INSTALLATION_TOKENS) cache.delete(cache.keys().next().value!)
+  return await pending
+}
+
+// Resolve this exact repository with the App's identity, then confirm the
+// installation token reaches the same numeric repository. A missing grant is
+// actionable through installation; transport/auth/rate errors must stay errors.
+export async function repositoryInstallation(config: ManagedConfig, repoId: number, fullName: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<number | null> {
+  const { githubAppId, githubAppPrivateKey } = config
+  if (githubAppId == null || githubAppPrivateKey == null) throw new GithubApiError(503, 'github-app-not-configured')
+  if (publicRepositoryName(fullName) !== fullName) throw new GithubApiError(409, 'repo-identity-changed')
+  const path = fullName.split('/').map(encodeURIComponent).join('/')
+  const jwt = appJwt(githubAppId, githubAppPrivateKey)
+  let raw
+  try { raw = await githubJson(`${GITHUB_API}/repos/${path}/installation`, jwt, fetchImpl) } catch (err) {
+    if (err instanceof GithubApiError && err.status === 404) return null
+    throw err
+  }
+  const installation = raw as { id?: unknown; suspended_at?: unknown; permissions?: { contents?: unknown } } | null
+  const id = installation?.id
+  if (typeof id !== 'number' || !Number.isSafeInteger(id) || id <= 0) throw new GithubApiError(502, 'github-malformed')
+  if (installation?.suspended_at != null || !['read', 'write'].includes(String(installation?.permissions?.contents))) return null
+  const token = await installationAccessToken(githubAppId, githubAppPrivateKey, id, fetchImpl)
+  const repo = parseRepo(await githubJson(`${GITHUB_API}/repos/${path}`, token, fetchImpl), id)
+  if (repo == null || repo.id !== repoId || repo.fullName.toLowerCase() !== fullName.toLowerCase()) throw new GithubApiError(409, 'repo-identity-changed')
+  return id
+}
+
+// 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 installationAccessToken(githubAppId, githubAppPrivateKey, 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
+}
+
+// A GitHub account, as GitHub's /user tells it.
+export interface GithubIdentity { id: number; login: string }
+
+// 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 githubUserIdentity(userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<GithubIdentity> {
+  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')
+  return { id: identity.id, login: identity.login }
+}
+
+// The permission's level (`admin`, `write`, `read`), as GitHub tells it of
+// `identity` alone; `none` where it tells of none, or of another account.
+export async function githubRepoPermission(fullName: string, token: string, identity: GithubIdentity, fetchImpl: typeof fetch = globalThis.fetch): Promise<string> {
+  const path = fullName.split('/').map(encodeURIComponent).join('/')
+  try {
+    const body = await githubJson(`${GITHUB_API}/repos/${path}/collaborators/${encodeURIComponent(identity.login)}/permission`, token, fetchImpl) as { permission?: unknown; user?: { id?: unknown } }
+    return body?.user?.id === identity.id && typeof body.permission === 'string' ? body.permission : 'none'
+  } catch (err) {
+    if (err instanceof GithubApiError && err.status === 404) return 'none'
+    throw err // Never broaden access when GitHub cannot verify permission.
+  }
+}
+
+// The levels that read a repository.
+export const READ_PERMISSIONS: ReadonlySet<string> = new Set(['read', 'write', 'admin'])
+
+export async function githubRepoReadPermission(fullName: string, token: string, identity: GithubIdentity, fetchImpl: typeof fetch = globalThis.fetch): Promise<boolean> {
+  return READ_PERMISSIONS.has(await githubRepoPermission(fullName, token, identity, fetchImpl))
+}
+
+export async function filterInstalledRepos(config: ManagedConfig, repositories: ConnectedRepo[], userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+  const identity = await githubUserIdentity(userToken, fetchImpl)
+  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
+    return githubRepoReadPermission(repo.fullName, accessToken, identity, fetchImpl)
+  })
+  return repositories.filter((_, index) => allowed[index])
+}
+
+// Get 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 installationAccessToken(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))
+    } 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-errors.ts

@@ -0,0 +1,70 @@
+import { HttpError } from '@preventive/upstream/github.js'
+
+// 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
+  retryAfter: number | null
+  // What failed, where GitHub wasn't reached (githubUnreachable).
+  detail: string | null
+  constructor(status: number, message: string, retryAfter: number | null = null, detail: string | null = null) {
+    super(message)
+    this.name = 'GithubApiError'
+    this.status = status
+    this.retryAfter = retryAfter
+    this.detail = detail
+  }
+}
+
+// GitHub not reached, or its answer not read whole, `started` ms since the
+// epoch: as `github-unreachable`, with what failed as the error and its causes
+// tell it (a timeout, a connection closed, an answer too large) and after how
+// long, for an admin's page to show (repository-risk.ts). Only the errors'
+// names, codes and messages, never GitHub's text nor a request's headers.
+export function githubUnreachable(error: unknown, started: number): GithubApiError {
+  const told: string[] = []
+  for (let at = error, depth = 0; at instanceof Error && depth < 4; at = at.cause, depth++) {
+    const code = 'code' in at && typeof at.code === 'string' && at.code !== at.name ? ` ${at.code}` : ''
+    told.push(`${at.name}${code}${at.message ? `: ${at.message.slice(0, 200)}` : ''}`)
+  }
+  const failed = told.length > 0 ? told.join('; ') : String(error).slice(0, 200)
+  return new GithubApiError(502, 'github-unreachable', null, `${failed}, after ${((Date.now() - started) / 1000).toFixed(1)}s`)
+}
+
+export async function throwGithubResponseError(res: Response): Promise<never> {
+  if (res.status === 403 || res.status === 429) {
+    const body = await res.json().catch(() => null) as { message?: unknown } | null
+    if (res.status === 429 || res.headers.get('x-ratelimit-remaining') === '0' || res.headers.has('retry-after')
+      || (typeof body?.message === 'string' && /rate limit|abuse detection/iu.test(body.message))) {
+      const retry = Number(res.headers.get('retry-after'))
+      const reset = Number(res.headers.get('x-ratelimit-reset')) * 1000
+      const wait = Math.max(Number.isFinite(retry) ? retry : 0, Number.isFinite(reset) ? (reset - Date.now()) / 1000 : 0)
+      throw new GithubApiError(429, 'github-rate-limited', Math.max(60, Math.ceil(wait)))
+    }
+  }
+  if (res.status === 401) throw new GithubApiError(401, 'github-unauthorized')
+  if (res.status === 404) throw new GithubApiError(404, 'github-not-found')
+  throw new GithubApiError(502, `github-status-${res.status}`)
+}
+
+export async function upstreamGithub<T>(request: () => Promise<T>): Promise<T> {
+  const started = Date.now()
+  try { return await request() } catch (error) {
+    // Already told as the router surfaces it.
+    if (error instanceof GithubApiError) throw error
+    if (error instanceof HttpError) {
+      // The upstream error includes GitHub's response text. Retain managed
+      // status handling, including rate limits, without exposing that text.
+      if (error.status === 401) throw new GithubApiError(401, 'github-unauthorized')
+      if (error.status === 404) throw new GithubApiError(404, 'github-not-found')
+      if (error.status === 429 || (error.status === 403 && /rate limit|abuse detection/iu.test(error.message))) {
+        throw new GithubApiError(429, 'github-rate-limited', 60)
+      }
+      throw new GithubApiError(502, `github-status-${error.status}`)
+    }
+    if (error instanceof Error && (error.name === 'AssertionError' || error.cause instanceof SyntaxError)) {
+      throw new GithubApiError(502, 'github-malformed')
+    }
+    throw githubUnreachable(error, started)
+  }
+}

package/server-managed/github-graphql.ts

@@ -0,0 +1,39 @@
+// GitHub's GraphQL API, a query at a time, as the repository readers ask it
+// (repository-history.ts, repository-agents.ts, repository-pulse.ts and the rest).
+import { GithubApiError, githubJson } from './github-app.ts'
+
+export type GraphqlError = { type?: unknown; path?: unknown; message?: unknown }
+
+const NAMED_ERRORS = new Set(['RATE_LIMITED', 'NOT_FOUND', 'FORBIDDEN'])
+// GitHub's own words for a query it stopped past its time (ten seconds):
+// "Something went wrong while executing your query. This may be the result
+// of a timeout, …", with no type.
+const TIMED_OUT = /\btimeout\b/iu
+
+// One GraphQL query with `token`, answered with its `data`: one GitHub answers
+// with errors, but for those the caller reads past (`tolerated`, the fields
+// they name then null), is rate limited, names what isn't there, is refused,
+// as one a GitHub App lacks the permission for is, or a token the scope for
+// (`INSUFFICIENT_SCOPES`, a sign-in's having none), took GitHub too long, or
+// else is malformed, as one GitHub rejects unread is (a field or type its API
+// doesn't know). GitHub's words for errors of none of those first three types
+// are logged, those read past too.
+export async function githubGraphql(query: string, variables: Record<string, unknown>, token: string, fetchImpl: typeof fetch,
+  tolerated: (error: GraphqlError) => boolean = () => false) {
+  const body = await githubJson('https://api.github.com/graphql', token, fetchImpl, 'POST', { query, variables }, true) as { data?: unknown; errors?: GraphqlError[] } | null
+  const all = Array.isArray(body?.errors) ? body.errors : []
+  const unnamed = all.filter(error => !NAMED_ERRORS.has(String(error?.type)))
+  if (unnamed.length > 0) {
+    console.warn('managed: GitHub answered a query with errors:', JSON.stringify(unnamed.slice(0, 3)
+      .map(error => ({ type: error?.type, message: String(error?.message).slice(0, 300), path: error?.path }))))
+  }
+  const errors = all.filter(error => !tolerated(error))
+  if (errors.length > 0) {
+    if (errors.some(error => error?.type === 'RATE_LIMITED')) throw new GithubApiError(429, 'github-rate-limited', 60)
+    if (errors.some(error => error?.type === 'NOT_FOUND')) throw new GithubApiError(404, 'github-not-found')
+    if (errors.some(error => error?.type === 'FORBIDDEN' || error?.type === 'INSUFFICIENT_SCOPES')) throw new GithubApiError(502, 'github-status-403')
+    if (errors.some(error => typeof error?.message === 'string' && TIMED_OUT.test(error.message))) throw new GithubApiError(502, 'github-timeout')
+    throw new GithubApiError(502, 'github-malformed')
+  }
+  return body?.data
+}