@preventive/triage 1.0.0-alpha.37 → 1.0.0-alpha.38

package/server-managed/index.ts

@@ -10,6 +10,8 @@ import { startServer } from '../server-common/standalone.ts'
 import { initializeApp } from '../server-common/initialize.ts'
 import { type ManagedConfig, loadManagedConfig } from './config.ts'
 import { type ManagedHttpDeps, createManagedRequestHandler } from './http.ts'
+import { setNpmTarballCache } from './npm-loads.ts'
+import { setNpmDocumentCache } from './npm-packages.ts'
 import { loadManagedStatic } from './static.ts'
 import { openManagedStorage } from './storage.ts'
 import { setCacheDir } from '@preventive/upstream/npm.js'
@@ -23,8 +25,12 @@ type ManagedAppOptions = Partial<Pick<ManagedHttpDeps, 'next' | 'serverInfo' | '
 
 export async function createManagedApp(config: ManagedConfig, options: ManagedAppOptions = {}) {
   // Audits keep upstream's records on disk where the config has a cache
-  // directory; bundle builds set it in their own worker.
+  // directory; bundle builds set it in their own worker. The npm viewer
+  // keeps the tarballs it downloads there too, beside theirs, and public
+  // packages' whole documents (npm-packages.ts).
   setCacheDir(config.upstreamCacheDir ?? false)
+  setNpmTarballCache(config.upstreamCacheDir ?? null)
+  setNpmDocumentCache(config.upstreamCacheDir ?? null)
   // Load the optional peer only for serverless managed deployments. Embedding
   // hosts can discard listener promises, so retain maintenance inside the app.
   const waitUntil = config.serverless ? (await import('@vercel/functions')).waitUntil : undefined
@@ -33,7 +39,7 @@ export async function createManagedApp(config: ManagedConfig, options: ManagedAp
 
 async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOptions, rollback: AsyncDisposableStack, waitUntil?: (promise: Promise<unknown>) => void) {
   const storage = await openManagedStorage(config)
-  const { db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache } = storage
+  const { db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, prettyCache, npmCacheStorage } = storage
   rollback.defer(() => db.close())
   const originGate = createOriginGate(config.host, config.trustProxyEnv)
 
@@ -49,13 +55,12 @@ async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOpti
     indexOnly: options.next != null, scanServer: options.serverInfo?.deepviewScanServer ?? null,
   })
   const routeRequest = createManagedRequestHandler({
-    ...options, config, db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, originGate, serveStatic,
+    ...options, config, db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, prettyCache, npmCacheStorage, originGate, serveStatic,
     ...(storage.uploadStore ? { uploadStore: storage.uploadStore } : {}),
     isShuttingDown, track,
   })
 
-  let cleanup: Promise<void> | undefined
-  let nextCleanupAt = 0
+  let cleanup: Promise<void> | undefined, nextCleanupAt = 0
   const maintenance = new AbortController()
   function reap(automatic = false): Promise<void> {
     if (cleanup) return cleanup
@@ -71,6 +76,7 @@ async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOpti
         await runReapers({
           sessions: async () => { sessions = await db.deleteExpiredSessions(Date.now()) },
           ...(storage.reapUploads ? { uploads: async () => { uploads = await storage.reapUploads!(maintenance.signal) } } : {}),
+          ...('reapPrettyCopies' in storage ? { prettyCopies: () => storage.reapPrettyCopies(maintenance.signal) } : {}),
           ...('reapStorage' in storage ? { storage: () => storage.reapStorage(maintenance.signal) } : {}),
         })
         succeeded = true

package/server-managed/kept.ts

@@ -0,0 +1,28 @@
+// Answers kept for an hour, by what they answer (npm-insights.ts,
+// npm-provenance.ts), at most `max` of them, the oldest asked going first;
+// one still being asked for is shared, and one that failed, or that `whole`
+// says is partial, is dropped once it is answered. `peek` gives one already
+// answered, asking for nothing; undefined where none is.
+const KEPT_MS = 60 * 60_000
+
+export function kept<T>(max: number, whole: (value: T) => boolean = () => true) {
+  const answers = new Map<string, { at: number; value: Promise<T>; answered?: { value: T } }>()
+  const get = (key: string, ask: () => Promise<T>): Promise<T> => {
+    const now = Date.now()
+    const hit = answers.get(key)
+    if (hit && now - hit.at < KEPT_MS) return hit.value
+    const value = ask()
+    const entry: { at: number; value: Promise<T>; answered?: { value: T } } = { at: now, value }
+    answers.delete(key)
+    answers.set(key, entry)
+    while (answers.size > max) answers.delete(answers.keys().next().value!)
+    const drop = () => { if (answers.get(key) === entry) answers.delete(key) }
+    value.then(answer => { if (whole(answer)) entry.answered = { value: answer }; else drop(); return answer }, drop)
+    return value
+  }
+  const peek = (key: string): T | undefined => {
+    const hit = answers.get(key)
+    return hit?.answered && Date.now() - hit.at < KEPT_MS ? hit.answered.value : undefined
+  }
+  return Object.assign(get, { peek })
+}

package/server-managed/locked-packages.ts

@@ -0,0 +1,85 @@
+// The packages a lockfile of npm's ecosystem locks, as @preventive/lockfile
+// reads package-lock.json and npm-shrinkwrap.json of `lockfileVersion: 3`,
+// pnpm-lock.yaml of pnpm 9 to 12 and Yarn 1's yarn.lock, each with where it
+// is installed from (repository-risk.ts).
+import { LockfileError, parseNpmLockfile } from '@preventive/lockfile/npm.js'
+import { parsePnpmLockfile } from '@preventive/lockfile/pnpm.js'
+import { parseYarn1Lockfile } from '@preventive/lockfile/yarn1.js'
+import type { LockfileFormat } from '@preventive/upstream/github.js'
+
+export interface LockedPackage {
+  name: string
+  // None for a git dependency whose package.json has none.
+  version: string | null
+  // Where it is installed from: npm's registry, another host's tarball with
+  // an integrity, such as a company's mirror of npm's, a git repository, a
+  // tarball with none, or a file of the project.
+  source: 'registry' | 'mirror' | 'git' | 'tarball' | 'file'
+  // Where one from elsewhere than npm's registry comes from, without any
+  // credentials its URL has.
+  from?: string
+  // A mirror's tarball's, as the lockfile has it: npm's package of its name
+  // and version only where npm's integrity is among it.
+  integrity?: string
+}
+
+// A package as each reader resolves one, its name the one it is published
+// under, and a registry tarball's URL held to its name and version.
+type Resolution =
+  | { type: 'tarball'; tarball: string | undefined; integrity: string | undefined; gitHosted?: boolean }
+  | { type: 'git'; repo: string }
+  | { type: 'directory' }
+interface ReadPackage { name: string; version: string | undefined; resolution: Resolution | undefined }
+
+// The packages of a lockfile of `format`, as its reader resolves them.
+// Versions go unchecked against ranges, as only what is locked is asked for.
+function packagesOf(format: LockfileFormat, text: string): ReadPackage[] {
+  if (format === 'npm') return Object.values(parseNpmLockfile(text, { checkVersions: false }).packages)
+  if (format === 'pnpm') {
+    const { lockfile, env } = parsePnpmLockfile(text)
+    return [...Object.values(env?.packages ?? {}), ...Object.values(lockfile?.packages ?? {})]
+  }
+  if (format !== 'yarn') throw new TypeError(`lockedPackages: ${format} lockfiles are not read`)
+  // Yarn 2 and later write another format, which only the text tells apart.
+  if (/^__metadata:/mu.test(text)) throw new LockfileError('a yarn.lock of Yarn 2 or later, which is not read')
+  // Yarn 1 names an alias, `my-q@npm:q@^1.5.1`, by its own name.
+  return Object.values(parseYarn1Lockfile(text, { checkVersions: false }).packages)
+    .map(pkg => ({ ...pkg, name: /@npm:((?:@[^/@]+\/)?[^/@]+)/u.exec(pkg.patterns[0] ?? '')?.[1] ?? pkg.name }))
+}
+
+// npm's registry, by either of its names, and yarn's mirror of it, as
+// @preventive/lockfile holds their tarballs to a package's name and version.
+const REGISTRY_HOSTS = new Set(['registry.npmjs.org', 'registry.npmjs.com', 'registry.yarnpkg.com'])
+const isRegistry = (url: URL) => url.protocol === 'https:' && !url.port && !url.username && !url.password
+  && REGISTRY_HOSTS.has(url.hostname.replace(/\.+$/u, ''))
+// Where a URL is, as it may be shown: its credentials, query and fragment
+// left out.
+const shown = (url: URL | null) => url ? { from: `${url.protocol}//${url.host}${url.pathname}` } : {}
+
+// Where a package read comes from (LockedPackage); null for one a package
+// bundles, with no resolution, or one of the project's own directories.
+function locked({ name, version, resolution }: ReadPackage): LockedPackage | null {
+  const at = { name, version: version ?? null }
+  if (resolution === undefined || resolution.type === 'directory') return null
+  if (resolution.type === 'git') return { ...at, source: 'git', ...shown(URL.parse(resolution.repo)) }
+  const { tarball, integrity } = resolution
+  if (resolution.gitHosted) return { ...at, source: 'git', ...shown(URL.parse(tarball ?? '')) }
+  if (tarball === undefined) return { ...at, source: 'registry' }
+  if (tarball.startsWith('file:')) return { ...at, source: 'file' }
+  const url = URL.parse(tarball)
+  if (url && isRegistry(url)) return { ...at, source: 'registry' }
+  return integrity ? { ...at, ...shown(url), source: 'mirror', integrity } : { ...at, ...shown(url), source: 'tarball' }
+}
+
+// The packages a lockfile of `format` (npm, pnpm or yarn, as
+// findRepoLockfiles names them) locks, each once, in the lockfile's order.
+// Throws the reader's LockfileError or YamlError for one it refuses.
+export function lockedPackages(format: LockfileFormat, text: string): LockedPackage[] {
+  const found = new Map<string, LockedPackage>()
+  for (const pkg of packagesOf(format, text)) {
+    const one = locked(pkg)
+    const key = one && `${one.source}\0${one.name}@${one.version ?? ''}\0${one.from ?? ''}\0${one.integrity ?? ''}`
+    if (one && key && !found.has(key)) found.set(key, one)
+  }
+  return [...found.values()]
+}

package/server-managed/lru.ts

@@ -0,0 +1,30 @@
+// Values by key, the least recently used going first once their weights
+// (`weight`, 1 each unless given) are past `limit`.
+export interface Lru<V> { get(key: string): V | undefined; set(key: string, value: V): void }
+export function lru<V>(limit: number, weight: (value: V) => number = () => 1): Lru<V> {
+  const kept = new Map<string, V>()
+  let total = 0
+  const forget = (key: string) => {
+    const value = kept.get(key)
+    if (value === undefined) return
+    kept.delete(key)
+    total -= weight(value)
+  }
+  return {
+    get(key) {
+      const value = kept.get(key)
+      if (value !== undefined) { kept.delete(key); kept.set(key, value) }
+      return value
+    },
+    set(key, value) {
+      forget(key)
+      if (weight(value) > limit) return
+      kept.set(key, value)
+      total += weight(value)
+      for (const first of kept.keys()) {
+        if (total <= limit) break
+        forget(first)
+      }
+    },
+  }
+}

package/server-managed/npm-insights.ts

@@ -0,0 +1,440 @@
+// 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: here it is one
+  // row, its ranges joined as semver joins them, the versions and CWEs they
+  // cover together, and the highest score.
+  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 key = `${row.source}\0${row.id}`
+    const known = merged.get(key)
+    if (!known) {
+      merged.set(key, {
+        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,
+      })
+      continue
+    }
+    const range = [known.range, row.range].filter(Boolean).join(' || ')
+    const cvss = Math.max(known.cvss ?? -1, row.cvss ?? -1)
+    merged.set(key, { ...known, ...range && { range }, ...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
+}