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

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. Every refs read of a repository
+// (Create a bundle's, the code viewer's) refreshes its tags, which go with it.
+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,238 @@
+// 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 session = await createSession(config, db, user, now)
+  // Linked to another user's account on their profile (github-links.ts).
+  if (session == null) throw new OAuthError(403, 'github-account-linked')
+  const { setCookie, userId } = session
+  // 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.
+export 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'))
+}