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

package/server-managed/npm-delta.ts

@@ -0,0 +1,194 @@
+// The lines a version of a package changes against another, or against none,
+// its whole package's (GET /api/npm/delta), as a list of versions wanting
+// reviews tells them beside each: added and removed (`additions`,
+// `deletions`), as git's --numstat counts them, of their text files, a
+// renamed one diffed with what it was; and, where some of the files changed
+// are declaration files @preventive/compare's compareTrees proves changed in
+// types alone (`typeOnly`, proveTypeOnly: types and comments alone erased,
+// the runtime they leave as it was, an added one's empty or a single bare
+// `export {}`), those of the rest (`typeless`), what a reviewer may pass by
+// leaving those out; and whether a binary file, which they count none of,
+// was added, removed or changed (`binary`), one moved as it was not. Worked
+// out in a worker, off the event loop, as many at once per process as
+// MAX_ACTIVE, both sides' files read together only once their turn has come,
+// those waiting past MAX_WAITING refused, each waiting a minute at most and
+// counting in a minute at most; one asked again meanwhile sharing the
+// first's; and kept by both sides' integrities, in this instance and beyond
+// it (`kept`), what a version holds never changing. Access is the caller's
+// to check.
+import { Worker } from 'node:worker_threads'
+import { createHash } from 'node:crypto'
+import type { KeptStore } from './npm-kept.ts'
+import { type Lru, lru } from './lru.ts'
+import { NpmPackageError, type NpmPackageFile, npmFileText } from './npm-packages.ts'
+
+export interface NpmDelta { additions: number; deletions: number; typeless: { additions: number; deletions: number } | null; binary: boolean }
+
+const MAX_ACTIVE = 2
+const MAX_WAITING = 64
+const DELTA_TIMEOUT_MS = 60_000
+// The text the two sides may hold together, past which none is counted.
+const MAX_TEXT_LENGTH = 64 * 1024 * 1024
+
+const deltas: Lru<NpmDelta> = lru(20_000)
+const working = new Map<string, Promise<NpmDelta>>()
+let active = 0
+const waiting: Array<() => void> = []
+
+async function turn(deadline: number): Promise<void> {
+  if (active < MAX_ACTIVE) { active++; return }
+  if (waiting.length >= MAX_WAITING) throw new NpmPackageError(429, 'delta-busy')
+  await new Promise<void>((resolve, reject) => {
+    const next = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      waiting.splice(waiting.indexOf(next), 1)
+      reject(new NpmPackageError(504, 'delta-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else active--
+}
+
+const lines = (told: unknown): told is { additions: number; deletions: number } => typeof told === 'object' && told !== null
+  && Number.isSafeInteger((told as { additions?: unknown }).additions) && Number.isSafeInteger((told as { deletions?: unknown }).deletions)
+// A delta as kept, none where it isn't one, or was kept before it told of
+// binary files.
+const deltaOf = (told: unknown): NpmDelta | null => lines(told) && ((told as NpmDelta).typeless === null || lines((told as NpmDelta).typeless))
+  && typeof (told as NpmDelta).binary === 'boolean' ? { additions: told.additions, deletions: told.deletions, typeless: (told as NpmDelta).typeless,
+    binary: (told as NpmDelta).binary } : null
+
+type Counted = { additions: number; deletions: number; typeAdditions: number; typeDeletions: number; typeFiles: number }
+const isCounted = (told: unknown): told is Counted => typeof told === 'object' && told !== null
+  && ['additions', 'deletions', 'typeAdditions', 'typeDeletions', 'typeFiles'].every(key => Number.isSafeInteger((told as Record<string, unknown>)[key]))
+
+// What the worker counts of `base` against `other`, each its text files' paths and texts.
+function counted(base: [string, string][], other: [string, string][], deadline: number): Promise<Counted> {
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./npm-delta-worker.js', import.meta.url), {
+      workerData: { base, other }, execArgv: ['--disable-warning=ExperimentalWarning'], resourceLimits: { maxOldGenerationSizeMb: 1536 },
+    })
+  } catch (err) {
+    console.warn('managed: a package delta could not start:', err)
+    throw new NpmPackageError(503, 'unavailable')
+  }
+  return new Promise((resolve, reject) => {
+    let answer: Counted | null = null, failure = new NpmPackageError(422, 'delta-failed')
+    const timer = setTimeout(() => { failure = new NpmPackageError(504, 'delta-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (told: unknown) => {
+      if (isCounted(told)) answer = told
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a package delta failed:', err) })
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (answer) resolve(answer)
+      else reject(failure)
+    })
+  })
+}
+
+// A side's text files, by path, how long their texts are, and its other,
+// binary, files.
+function texts(files: NpmPackageFile[] | null) {
+  let length = 0
+  const binaries: NpmPackageFile[] = []
+  const read = (files ?? []).flatMap(file => {
+    const text = npmFileText(file.bytes)
+    if (text === null) { binaries.push(file); return [] }
+    length += text.length
+    return [[file.path, text] as [string, string]]
+  })
+  return { read, length, binaries }
+}
+
+const same = (a: Uint8Array, b: Uint8Array) => Buffer.from(a.buffer, a.byteOffset, a.byteLength).equals(b)
+const digest = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('base64')
+
+// Whether `news`, a side's binary files, differ from `olds`, the other's:
+// one added, removed or changed, one moved where it is the same as one that
+// was elsewhere not, matched by their digests, each file looked at once.
+function binaryChanged(olds: NpmPackageFile[], news: NpmPackageFile[]): boolean {
+  if (olds.length !== news.length) return true
+  const left = new Map(olds.map(({ path, bytes }) => [path, bytes]))
+  const moved: Uint8Array[] = []
+  for (const { path, bytes } of news) {
+    const was = left.get(path)
+    if (was && same(was, bytes)) left.delete(path)
+    else moved.push(bytes)
+  }
+  // Those not where they were, by their digests, as many of each as there are.
+  const unmoved = new Map<string, number>()
+  for (const bytes of left.values()) {
+    const key = digest(bytes)
+    unmoved.set(key, (unmoved.get(key) ?? 0) + 1)
+  }
+  return moved.some(bytes => {
+    const key = digest(bytes)
+    const count = unmoved.get(key) ?? 0
+    if (count === 0) return true
+    unmoved.set(key, count - 1)
+    return false
+  })
+}
+
+type Side = { integrity: string; files: () => Promise<NpmPackageFile[]> }
+
+// The delta of `other` (its integrity, and how to read its files) against
+// `base`, or none, as held, else shared with one asked before it, else
+// looked for where it is kept, else worked out and kept: shared from before
+// it is looked for, lest those asked together each look, find none, and work
+// it out.
+export function npmDelta(base: Side | null, other: Side, kept: KeptStore<NpmDelta> | null = null): Promise<NpmDelta> {
+  const key = `${base?.integrity ?? '(empty)'}\0${other.integrity}`
+  const known = deltas.get(key)
+  if (known) return Promise.resolve(known)
+  const shared = working.get(key)
+  if (shared) return shared
+  const work = worked(key, base, other, kept).finally(() => working.delete(key))
+  working.set(key, work)
+  return work
+}
+
+// The deltas of those of `sides` (each the integrities of the version it is
+// against, or none, and of the version) held or kept, by their keys
+// (npmDelta's), in one read of `kept` for those not held: none worked out.
+export async function keptNpmDeltas(sides: [string | null, string][], kept: KeptStore<NpmDelta>): Promise<Map<string, NpmDelta>> {
+  const keys = [...new Set(sides.map(([base, other]) => `${base ?? '(empty)'}\0${other}`))]
+  const found = new Map(keys.flatMap(key => { const known = deltas.get(key); return known ? [[key, known] as const] : [] }))
+  const unheld = keys.filter(key => !found.has(key))
+  for (const [key, row] of unheld.length > 0 ? await kept.readMany(unheld) : []) {
+    const known = deltaOf(row.value)
+    if (!known) continue
+    deltas.set(key, known)
+    found.set(key, known)
+  }
+  return found
+}
+
+// As kept, else its turn awaited, then both sides' files read, counted and kept.
+async function worked(key: string, base: Side | null, other: Side, kept: KeptStore<NpmDelta> | null): Promise<NpmDelta> {
+  const known = deltaOf((await kept?.read(key))?.value)
+  if (known) { deltas.set(key, known); return known }
+  await turn(Date.now() + DELTA_TIMEOUT_MS)
+  let binary, told
+  try {
+    // Its turn held till both sides are read, or have failed.
+    const [baseRead, otherRead] = await Promise.allSettled([base ? base.files() : Promise.resolve(null), other.files()])
+    if (baseRead.status === 'rejected') throw baseRead.reason
+    if (otherRead.status === 'rejected') throw otherRead.reason
+    const [olds, news] = [texts(baseRead.value), texts(otherRead.value)]
+    if (olds.length + news.length > MAX_TEXT_LENGTH) throw new NpmPackageError(413, 'package-too-large')
+    binary = binaryChanged(olds.binaries, news.binaries)
+    told = await counted(olds.read, news.read, Date.now() + DELTA_TIMEOUT_MS)
+  } finally { done() }
+  const delta = { additions: told.additions, deletions: told.deletions,
+    typeless: told.typeFiles > 0 ? { additions: told.additions - told.typeAdditions, deletions: told.deletions - told.typeDeletions } : null, binary }
+  deltas.set(key, delta)
+  await kept?.write(key, delta, Date.now())
+  return delta
+}

package/server-managed/npm-insights.ts

@@ -0,0 +1,449 @@
+// Figures and advisories for the npm package viewer's Overview, beside a
+// version's files (npm-packages.ts, npm-loads.ts): the package's downloads
+// over the last year, from npm's public downloads API; its GitHub
+// repository's stars, forks and open issues; and its advisories across every
+// published version, as `npm audit` has them and as its repository publishes
+// them on GitHub, asked as bundle advisories ask (bundle-advisories.ts); and
+// Socket's scores and alerts for a version. All of it is public: npm is asked
+// without the server's token, Socket only about a version npm answers for
+// without one (http.ts), and a repository's figures, tags and advisories are
+// asked for, and kept, only where GitHub says it is public. Each
+// answer is kept for an hour, a failure not at all; the reader's access to
+// the package is checked on every request before any of it is answered
+// (http.ts handleNpm).
+import type { Advisory, CacheStore } from '@preventive/upstream/advisories.js'
+import { type Client, HttpError, createClient } from '@preventive/upstream/github.js'
+import { ADVISORIES_TIMEOUT_MS, fetchBundleAdvisories } from './bundle-advisories.ts'
+import { isExactVersion } from '@preventive/upstream/semver.js'
+import { kept } from './kept.ts'
+import { type NpmProvenance, keptNpmProvenance } from './npm-provenance.ts'
+import { NpmPackageError, askUpstreamJson, plainObject, readLimited } from './npm-packages.ts'
+
+const DOWNLOADS_API = 'https://api.npmjs.org/downloads/range'
+// What npm's range API may answer for each package asked: a year of days is
+// some 16 KiB.
+const DOWNLOADS_BYTES = 64 * 1024
+// Socket's answer for a package version, by its purl, as Socket Firewall
+// asks it: no key needed. Its scores are cut to two decimals; its badge's,
+// the supply chain score, is rounded (askSocketBadge).
+const SOCKET_API = 'https://firewall-api.socket.dev/purl'
+const SOCKET_BADGE = 'https://badge.socket.dev/npm/package'
+const BADGE_BYTES = 16 * 1024
+const API_TIMEOUT_MS = 30_000
+const API_BYTES = 1024 * 1024
+const DAY_MS = 24 * 60 * 60_000
+const SEVERITY_RANK: Record<string, number> = { critical: 0, high: 1, moderate: 2, low: 3 }
+
+const count = (value: unknown) => Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : 0
+const isDay = (value: unknown): value is string => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/u.test(value) && !Number.isNaN(Date.parse(value))
+
+// A package's downloads, one count a day from `start` to `end` (UTC dates),
+// none for a day npm leaves out; null where npm has none for it.
+export interface NpmDownloads { start: string; end: string; days: number[] }
+
+const isoDay = (time: number) => new Date(time).toISOString().slice(0, 10)
+
+// Its last year, as npm counts it (to the last day it has counted), from
+// the first of the month that year starts in, so that month is whole too.
+async function askDownloads(name: string): Promise<NpmDownloads | null> {
+  const year = await askDownloadRange('last-year', name)
+  const start = new Date(year?.start ?? 0)
+  if (year === null || start.getUTCDate() === 1) return year
+  const first = Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1)
+  const before = await askDownloadRange(`${isoDay(first)}:${isoDay(start.getTime() - DAY_MS)}`, name).catch(() => null)
+  return before?.start === isoDay(first) && before.days.length === (start.getTime() - first) / DAY_MS
+    ? { start: before.start, end: year.end, days: [...before.days, ...year.days] } : year
+}
+
+// npm's downloads of `name` over `range`: null where npm has none.
+async function askDownloadRange(range: string, name: string): Promise<NpmDownloads | null> {
+  const json = await askUpstreamJson(`${DOWNLOADS_API}/${range}/${name.replace('/', '%2f')}`, { headers: { accept: 'application/json' }, limit: DOWNLOADS_BYTES })
+  return json === null ? null : readDownloads(json)
+}
+
+// One package's downloads as npm's range API gives them.
+function readDownloads(json: unknown): NpmDownloads {
+  if (!plainObject(json) || !isDay(json['start']) || !isDay(json['end']) || !Array.isArray(json['downloads'])) throw new NpmPackageError(502, 'upstream-invalid')
+  const start = Date.parse(json['start'])
+  const length = (Date.parse(json['end']) - start) / DAY_MS + 1
+  if (!Number.isSafeInteger(length) || length < 1 || length > 400) throw new NpmPackageError(502, 'upstream-invalid')
+  const days = Array.from({ length }, () => 0)
+  for (const row of json['downloads']) {
+    if (!plainObject(row) || !isDay(row['day'])) continue
+    const at = (Date.parse(row['day']) - start) / DAY_MS
+    if (Number.isSafeInteger(at) && at >= 0 && at < length) days[at] = count(row['downloads'])
+  }
+  return { start: json['start'], end: json['end'], days }
+}
+
+const downloads = kept<NpmDownloads | null>(500)
+// The repository each package's latest version names (owner/name, null where
+// it names none), as its figures were first asked with within the hour: what
+// npmKnown finds them by.
+const latestRepos = kept<string | null>(500)
+
+export const npmLatestRepo = (name: string, repo: string | null): void => void latestRepos(name, () => Promise.resolve(repo))
+
+export function npmDownloads(name: string): Promise<NpmDownloads | null> {
+  return downloads(name, () => askDownloads(name))
+}
+
+const SOCKET_SCORES = ['overall', 'supplyChain', 'vulnerability', 'quality', 'maintenance', 'license'] as const
+const SOCKET_SEVERITY_RANK: Record<string, number> = { critical: 0, high: 1, middle: 2, low: 3 }
+const SOCKET_ALERTS = 50
+const SOCKET_NOTE_CHARS = 4000
+
+// Socket's report on a version: its scores, each 0 to 1 (null where Socket
+// gave none), and the alerts it raises, such as malware, most severe first,
+// each with the file it was found in, by its path in the package (the
+// tarball's root left out, as the package's files have it), where it names
+// one, and Socket's note on it.
+export interface NpmSocketAlert { type: string; severity: string; category: string | null; file: string | null; note: string | null }
+export interface NpmSocketReport { scores: Record<typeof SOCKET_SCORES[number], number> | null; alerts: NpmSocketAlert[] }
+
+const text = (value: unknown) => typeof value === 'string' && value !== '' ? value : null
+
+// The supply chain score, out of 100, that the version's badge shows; null
+// where it shows none, and undefined where it can't be had, as while Socket
+// limits how often it's asked.
+async function askSocketBadge(name: string, version: string): Promise<number | null | undefined> {
+  try {
+    const res = await fetch(`${SOCKET_BADGE}/${name}/${encodeURIComponent(version)}`,
+      { headers: { accept: 'image/svg+xml' }, redirect: 'error', signal: AbortSignal.timeout(API_TIMEOUT_MS) })
+    if (!res.ok) { await res.body?.cancel(); return res.status === 429 || res.status >= 500 ? undefined : null }
+    const shown = /<title>Socket: (\d{1,3})<\/title>/u.exec((await readLimited(res, BADGE_BYTES)).toString('utf8'))
+    return shown ? Number(shown[1]) : null
+  } catch { return undefined }
+}
+
+// Scores the badge couldn't round: Socket's own, a point low at most, their
+// report answered but not kept, so the next view asks again.
+const unbadged = new WeakSet<object>()
+
+async function askSocket(name: string, version: string): Promise<NpmSocketReport | null> {
+  const badge = askSocketBadge(name, version)
+  // One line, as one purl was asked.
+  const json = await askUpstreamJson(`${SOCKET_API}/${encodeURIComponent(`pkg:npm/${name}@${version}`)}`,
+    { headers: { accept: 'application/x-ndjson' }, limit: API_BYTES }, body => JSON.parse(body.split('\n', 1)[0]!))
+  if (json === null) return null
+  if (!plainObject(json) || json['version'] !== version || [json['namespace'], json['name']].filter(Boolean).join('/') !== name) throw new NpmPackageError(502, 'upstream-invalid')
+  // A version Socket hasn't seen is answered with a made-up id and nothing else.
+  if (String(json['id']).startsWith('synthetic:')) return null
+  const score = json['score']
+  const scores = plainObject(score) && SOCKET_SCORES.every(key => typeof score[key] === 'number' && score[key] >= 0 && score[key] <= 1)
+    ? Object.fromEntries(SOCKET_SCORES.map(key => [key, score[key]])) as NpmSocketReport['scores'] : null
+  // The supply chain score as the badge rounds it, at most one more than the
+  // score cut to two decimals; lower where the badge is, as when the score
+  // has fallen since.
+  const shown = await badge
+  if (scores && typeof shown === 'number') scores.supplyChain = Math.min(Math.round(scores.supplyChain * 100) + 1, shown) / 100
+  else if (scores && shown === undefined) unbadged.add(scores)
+  const alerts = (Array.isArray(json['alerts']) ? json['alerts'] : [])
+    .filter((alert): alert is Record<string, unknown> => plainObject(alert) && text(alert['type']) !== null && typeof alert['severity'] === 'string' && alert['severity'] in SOCKET_SEVERITY_RANK)
+    .slice(0, SOCKET_ALERTS)
+    .map(alert => ({
+      type: alert['type'] as string, severity: alert['severity'] as string, category: text(alert['category']),
+      file: text(text(alert['file'])?.replace(/^[^/]*\//u, '')),
+      note: text(plainObject(alert['props']) ? alert['props']['note'] : null)?.slice(0, SOCKET_NOTE_CHARS) ?? null,
+    }))
+    .toSorted((a, b) => SOCKET_SEVERITY_RANK[a.severity]! - SOCKET_SEVERITY_RANK[b.severity]!)
+  return scores === null && alerts.length === 0 ? null : { scores, alerts }
+}
+
+const socketReports = kept<NpmSocketReport | null>(1000, report => !report?.scores || !unbadged.has(report.scores))
+
+// Socket's report on a version of a public package; null where Socket has
+// none. Its name goes to Socket: never ask it about a private one.
+export function npmSocketReport(name: string, version: string): Promise<NpmSocketReport | null> {
+  return socketReports(`${name}@${version}`, () => askSocket(name, version))
+}
+
+// A public repository's figures: GitHub's `openIssues` takes in its open pull
+// requests, which `openPulls` counts on their own, null where GitHub didn't
+// say.
+export interface NpmGithubStats {
+  repo: string; stars: number; forks: number; openIssues: number; openPulls: number | null; archived: boolean; pushedAt: string | null
+}
+
+// How many pull requests a repository has open: the last page of their list,
+// one a page, as its Link header names it, or the one page's length.
+async function countOpenPulls(repo: string, token: string | null): Promise<number | null> {
+  const path = repo.split('/').map(encodeURIComponent).join('/')
+  let res: Response
+  try {
+    res = await fetch(`https://api.github.com/repos/${path}/pulls?state=open&per_page=1`, {
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'deepview-triage', ...token && { authorization: `Bearer ${token}` } },
+      redirect: 'error', signal: AbortSignal.timeout(API_TIMEOUT_MS),
+    })
+  } catch { return null }
+  if (!res.ok) { await res.body?.cancel(); return null }
+  const last = /[?&]page=(\d+)>;\s*rel="last"/u.exec(res.headers.get('link') ?? '')?.[1]
+  if (last !== undefined) { await res.body?.cancel(); return Number(last) }
+  try {
+    const json = JSON.parse((await readLimited(res, API_BYTES)).toString('utf8')) as unknown
+    return Array.isArray(json) ? json.length : null
+  } catch { return null }
+}
+
+// GitHub has no repository to show: none by that name, or a redirect upstream
+// won't follow, anywhere but to the repository by its id, or a second.
+const NONE = new Set([301, 302, 307, 308, 404])
+
+// What GitHub answers for `repo`, or where it was renamed or transferred, for
+// the repository it is now (its `full_name`), where it says it is public,
+// with the token it was asked with: `token`, or none where that is revoked.
+// Upstream follows GitHub's redirect for such a repository to it by its id
+// (`followRedirect`), once, with the same token. Null where GitHub has no such
+// repository to show, or it is not public; anything else fails, to be asked
+// again next time. Public is `visibility: 'public'`, as github-app.ts
+// requires: an internal repository answers `private: false`.
+async function publicRepo(repo: string, token: string | null): Promise<{ json: Record<string, unknown> & { full_name: string }; auth: string | null } | null> {
+  const ask = (auth: string | null) => createClient({ token: auth, userAgent: 'deepview-triage' }).getRepo({ repo, followRedirect: true }) as Promise<unknown>
+  let auth = token, json: unknown
+  try { json = await ask(token) }
+  catch (error) {
+    if (!(error instanceof HttpError) || !(error.status === 401 || NONE.has(error.status))) throw error
+    if (error.status !== 401 || token === null) return null
+    auth = null
+    try { json = await ask(null) }
+    catch (retry) { if (retry instanceof HttpError && NONE.has(retry.status)) return null; throw retry }
+  }
+  if (!plainObject(json) || json['private'] !== false || json['visibility'] !== 'public' || typeof json['full_name'] !== 'string') return null
+  return { json: json as Record<string, unknown> & { full_name: string }, auth }
+}
+
+async function askGithub(repo: string, token: string | null): Promise<NpmGithubStats | null> {
+  const found = await publicRepo(repo, token)
+  if (found === null) return null
+  const { json, auth } = found
+  return {
+    repo: json['full_name'], stars: count(json['stargazers_count']), forks: count(json['forks_count']), openIssues: count(json['open_issues_count']),
+    openPulls: await countOpenPulls(json['full_name'], auth),
+    archived: json['archived'] === true, pushedAt: typeof json['pushed_at'] === 'string' ? json['pushed_at'] : null,
+  }
+}
+
+const repositories = kept<NpmGithubStats | null>(1000)
+
+// `repo` as a package's manifest names it (owner/name); `githubToken` the
+// reader's own, where they have one, for GitHub's rate limits, never for what
+// it shows, asked for only where the figures aren't kept.
+export function npmGithubStats(repo: string, githubToken: () => Promise<string | null>): Promise<NpmGithubStats | null> {
+  return repositories(repo.toLowerCase(), async () => askGithub(repo, await githubToken()))
+}
+
+const GITHUB_GRAPHQL = 'https://api.github.com/graphql'
+// A ref's target is a commit, or for an annotated tag a tag object, which may
+// itself name another tag before the commit.
+const TAGS_QUERY = `query($owner: String!, $name: String!, $query: String!) {
+  repository(owner: $owner, name: $name) {
+    visibility
+    refs(refPrefix: "refs/tags/", query: $query, first: 100) {
+      nodes { name target { __typename oid ... on Tag { target { __typename oid ... on Tag { target { __typename oid } } } } } }
+    }
+  }
+}`
+
+function taggedCommit(target: unknown): unknown {
+  let at = target
+  for (let depth = 0; depth < 3 && plainObject(at) && at['__typename'] === 'Tag'; depth++) at = at['target']
+  return plainObject(at) && at['__typename'] === 'Commit' ? at['oid'] : null
+}
+
+async function askTags(repo: string, sha: string, version: string, token: string): Promise<string[]> {
+  const [owner, name] = repo.split('/')
+  const json = await askUpstreamJson(GITHUB_GRAPHQL, {
+    method: 'POST', limit: API_BYTES, absent: [],
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', 'user-agent': 'deepview-triage' },
+    body: JSON.stringify({ query: TAGS_QUERY, variables: { owner, name, query: version } }),
+  })
+  const data = plainObject(json) ? json['data'] : null
+  const repository = plainObject(data) ? data['repository'] : null
+  // A repository gone, or not public (private, or internal to an enterprise),
+  // has none to show anyone.
+  if (!plainObject(repository) || repository['visibility'] !== 'PUBLIC') return []
+  const refs = repository['refs']
+  const nodes = plainObject(refs) && Array.isArray(refs['nodes']) ? refs['nodes'] as unknown[] : []
+  return nodes.filter((node): node is { name: string; target: unknown } => plainObject(node) && typeof node['name'] === 'string' && node['name'] !== '')
+    .filter(node => taggedCommit(node.target) === sha).map(node => node.name).toSorted()
+}
+
+// Null where no token asked: nothing to keep for a reader who has one.
+const commitTags = kept<string[] | null>(500, tags => tags !== null)
+
+// The tags of a public repository (owner/name) that point to `sha`, a
+// version's publish commit, among those naming its `version` (`v1.2.3`,
+// `pkg@1.2.3`, …), as GitHub's GraphQL API finds them by name. GraphQL needs
+// a token: the reader's own (`githubToken`, asked for only where the tags
+// aren't kept), where they have one; without, none are asked.
+export async function npmCommitTags(repo: string, sha: string, version: string, githubToken: () => Promise<string | null>): Promise<string[]> {
+  return await commitTags(`${repo.toLowerCase()}\0${sha}\0${version}`, async () => {
+    const token = await githubToken()
+    return token === null ? null : askTags(repo, sha, version, token)
+  }) ?? []
+}
+
+// An advisory on the package, with the versions it covers as their indexes in
+// the list it was asked with: npm's (`registry`), or one its repository
+// publishes on GitHub before GitHub reviews it into npm's (`repository`); its
+// text (markdown) where its source has one.
+export interface NpmAdvisory {
+  id: string; source: Advisory['source']; ghsa?: string; url?: string; title?: string; severity?: string; cvss?: number; cwe: string[]; range?: string
+  details?: string; affected: number[]
+}
+
+// `versions` those `affected` indexes; `repository` false where the
+// repository's advisories could not be had (GitHub refusing, its rate limit
+// spent), leaving npm's alone; `keptAt`, where GitHub couldn't give them but
+// their listing was kept before, however long ago, when it was.
+export interface NpmAdvisoryList { versions: string[]; advisories: NpmAdvisory[]; repository: boolean; keptAt?: string }
+
+export interface NpmAdvisoryOptions {
+  // The reader's GitHub token, and the repository the package names (owner/
+  // name, null where it names none), each asked for only where the list is
+  // not kept.
+  githubToken: () => Promise<string | null>
+  repo: () => Promise<string | null>
+  // Where repositories' listings are kept, as bundle advisories keep them
+  // (upstream-cache.ts auditCache), for as long as `signal` asks; and a
+  // repository's as last kept there, however old (lastListing).
+  cache: (signal: AbortSignal) => CacheStore | undefined
+  lastListing: (repo: string) => Promise<{ at: number; cache: CacheStore } | null>
+  debug?: boolean
+}
+
+async function askAdvisories(name: string, versions: string[], { githubToken, repo, cache, lastListing, debug = false }: NpmAdvisoryOptions): Promise<NpmAdvisoryList> {
+  // Every version upstream takes, as it checks each one it is asked about.
+  const asked = versions.filter(version => isExactVersion(version))
+  if (asked.length === 0) return { versions, advisories: [], repository: true }
+  // Its repository's own advisories are asked for only where GitHub says, now
+  // and not from an answer kept, that it is public, and that repository is the
+  // one asked, by the name GitHub gives it now where it was renamed or
+  // transferred: the list is kept for every reader of the package, and the
+  // reader's token could read a private repository's, or a listing of one
+  // kept for another reader.
+  let github: string | null = null, named: string | null = null, repository = true
+  try {
+    named = await repo()
+    github = named === null ? null : (await publicRepo(named, await githubToken()))?.json.full_name ?? null
+  } catch { repository = false }
+  // With the advisories `listed` publishes, where it isn't null, GitHub asked
+  // with the reader's token or by a client of the caller's.
+  const ask = (listed: string | null, store: (signal: AbortSignal) => CacheStore | undefined, client: { githubToken: string | null } | { github: Client }) => {
+    const signal = AbortSignal.timeout(ADVISORIES_TIMEOUT_MS)
+    const packages = [{ ecosystem: 'npm' as const, name, versions: asked, ...listed !== null && { github: listed } }]
+    return fetchBundleAdvisories(packages, signal, { debug, repoAdvisories: listed !== null, details: true, ...client, cache: store(signal) })
+  }
+  let result = repository ? await ask(github, cache, { githubToken: github === null ? null : await githubToken() }) : null
+  // Where GitHub can't say whether it is public, or refuses its listing, its
+  // listing as last kept is taken instead, however old (lastListing), as
+  // audits take a kept listing for any reader: only public repositories
+  // publish advisories (upstream-cache.ts). GitHub is asked nothing for it:
+  // upstream asks for a listing only once npm has answered, and where it
+  // won't take the kept one, which leaves npm's alone, as where none is kept.
+  // An audit failing otherwise is npm's, not asked a third time. Neither list
+  // is kept, so GitHub is asked again next time.
+  let keptAt: string | undefined
+  if (result === null || (result.status !== 200 && github !== null)) {
+    const unreached = github ?? named
+    const last = unreached === null ? null : await lastListing(unreached)
+    let untaken = false
+    const offline: Client = { ...createClient({ token: null, userAgent: 'deepview-triage' }),
+      listRepoAdvisories: () => { untaken = true; return Promise.reject(new Error('GitHub can\'t be reached')) } }
+    const listed = last && await ask(unreached, () => last.cache, { github: offline })
+    if (last && listed?.status === 200) {
+      result = listed
+      repository = true
+      keptAt = new Date(last.at).toISOString()
+    } else {
+      result = listed && !untaken ? listed : await ask(null, cache, { githubToken: null })
+      repository = false
+    }
+  }
+  if (result.status !== 200) throw new NpmPackageError(502, 'upstream-unavailable')
+  const index = new Map(versions.map((version, i) => [version, i]))
+  // npm's registry answers an advisory once a range it covers, and upstream
+  // answers the versions OSV's record of it, or its repository, covers beyond
+  // npm's under the same id, in a row of their own (as hermes-engine's
+  // GHSA-f5x2-xv93-4p23: npm's `<=0.4.3`, OSV's fixed in 0.5.2): here it is
+  // one row, the first's (npm's, then OSV's, then the repository's, as
+  // upstream orders them) with what it lacks taken from the rest, its ranges
+  // joined as semver joins them, the versions and CWEs they cover together,
+  // and the worst severity and highest score of them: a version only the
+  // repository reports keeps the severity it gives.
+  const merged = new Map<string, NpmAdvisory>()
+  for (const row of result.body) {
+    const affected = row.versions.map(version => index.get(version)).filter(at => at !== undefined)
+    const own: NpmAdvisory = {
+      id: row.id, source: row.source, ...row.ghsa && { ghsa: row.ghsa }, ...row.url && { url: row.url }, ...row.title && { title: row.title },
+      ...row.severity && { severity: row.severity }, ...row.cvss !== undefined && { cvss: row.cvss }, cwe: row.cwe, ...row.range && { range: row.range },
+      ...row.details && { details: row.details }, affected,
+    }
+    const known = merged.get(row.id)
+    if (!known) {
+      merged.set(row.id, own)
+      continue
+    }
+    const range = [known.range, row.range].filter(Boolean).join(' || ')
+    const cvss = Math.max(known.cvss ?? -1, row.cvss ?? -1)
+    const rank = (severity: string | undefined) => SEVERITY_RANK[severity ?? ''] ?? 4
+    const severity = rank(row.severity) < rank(known.severity) ? row.severity : known.severity
+    merged.set(row.id, { ...own, ...known, ...range && { range }, ...severity && { severity }, ...cvss >= 0 && { cvss }, cwe: [...new Set([...known.cwe, ...row.cwe])],
+      affected: [...known.affected, ...affected] })
+  }
+  return {
+    versions, repository, ...keptAt && { keptAt },
+    advisories: [...merged.values()].map(row => ({ ...row, affected: [...new Set(row.affected)].toSorted((a, b) => a - b) })).filter(row => row.affected.length > 0)
+      .toSorted((a, b) => (SEVERITY_RANK[a.severity ?? ''] ?? 4) - (SEVERITY_RANK[b.severity ?? ''] ?? 4) || a.id.localeCompare(b.id)),
+  }
+}
+
+const ADVISORY_LISTS = 100
+const advisoryLists = kept<NpmAdvisoryList>(ADVISORY_LISTS, list => list.repository && !list.keptAt)
+// What each package's list was last asked by, for npmKnown.
+const advisoryKeys = new Map<string, string>()
+
+// The package's advisories, `versions` its published versions as the version
+// list has them; asked again once a version is published, and a list without
+// its repository's, next time.
+export function npmAdvisories(name: string, versions: string[], options: NpmAdvisoryOptions): Promise<NpmAdvisoryList> {
+  const key = `${name}\0${versions.length}\0${versions[0] ?? ''}`
+  advisoryKeys.delete(name)
+  advisoryKeys.set(name, key)
+  while (advisoryKeys.size > ADVISORY_LISTS) advisoryKeys.delete(advisoryKeys.keys().next().value!)
+  return advisoryLists(key, () => askAdvisories(name, versions, options))
+}
+
+// What is kept about a version's package, each part as its own route answers
+// it (http.ts handleNpm), for the version's response to carry: its figures,
+// where those of the repository its latest version names are kept too; its
+// advisories, where kept for a version list that has this version; the tags
+// of its publish commit (`sha`, in `repo`, the repository it names);
+// Socket's report on it; and npm's provenance for it (npm-provenance.ts).
+// Nothing is asked for: what isn't kept is left out, for the viewer to ask
+// for. A private package's name never leaves for Socket, so its report is
+// none, nor is it asked for provenance.
+export interface NpmKnown {
+  stats?: { name: string; downloads: NpmDownloads | null; github: NpmGithubStats | null }
+  advisories?: { name: string } & NpmAdvisoryList
+  tags?: { name: string; version: string; tags: string[] }
+  socket?: { name: string; version: string; socket: NpmSocketReport | null }
+  provenance?: { name: string; version: string; provenance: NpmProvenance | null }
+}
+
+export function npmKnown(name: string, version: string, isPrivate: boolean, repo: string | null, sha: string | null): NpmKnown {
+  const known: NpmKnown = {}
+  const days = downloads.peek(name), latest = latestRepos.peek(name)
+  const github = latest === null ? null : latest === undefined ? undefined : repositories.peek(latest.toLowerCase())
+  if (days !== undefined && github !== undefined) known.stats = { name, downloads: days, github }
+  const key = advisoryKeys.get(name)
+  const list = key === undefined ? undefined : advisoryLists.peek(key)
+  if (list?.versions.includes(version)) known.advisories = { name, ...list }
+  const tags = repo === null || sha === null ? [] : commitTags.peek(`${repo.toLowerCase()}\0${sha}\0${version}`)
+  if (tags) known.tags = { name, version, tags }
+  const socket = isPrivate ? null : socketReports.peek(`${name}@${version}`)
+  if (socket !== undefined) known.socket = { name, version, socket }
+  const provenance = isPrivate ? null : keptNpmProvenance(name, version)
+  if (provenance !== undefined) known.provenance = { name, version, provenance }
+  return known
+}