@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.40

package/server-managed/management-catalog.ts

@@ -0,0 +1,45 @@
+import { roleAtLeast } from '../common/managed/roles.ts'
+import { type RepoScope, contentAccess } from './content-access.ts'
+import type { AdminBundle, AdminReport, ManagedDb } from './db-methods.ts'
+import { ManagedMutationError } from './management.ts'
+
+type CatalogAccess = { repos: { repoId: number; fullName: string }[]; repoScopes: RepoScope[] | null }
+export interface ManagementCatalogStore {
+  getReportCatalog(sessionId: string, now: number): Promise<CatalogAccess & { reports: (AdminReport & { canChangeRepo: boolean })[] }>
+  getBundleCatalog(sessionId: string, now: number): Promise<CatalogAccess & { bundles: (AdminBundle & { canChangeRepo: boolean })[] }>
+}
+type CatalogDb = Pick<ManagedDb, 'getReportAccessSnapshot' | 'listRepoScopesForUser' | 'listSelectedRepos'
+  | 'listReports' | 'listBundles' | 'listReadableBundleIds'>
+
+// The outer store method owns one read snapshot. Use raw methods here so the
+// session, grants, rows and action flags agree without per-row transactions.
+export function managementCatalogMethods(db: CatalogDb): ManagementCatalogStore {
+  async function access(sessionId: string, now: number) {
+    const snapshot = await db.getReportAccessSnapshot(sessionId, now, [])
+    if (!snapshot) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(snapshot.user.role, 'manage')) throw new ManagedMutationError(403, 'forbidden')
+    const scope = await contentAccess(db, snapshot.user)
+    const repos = (await db.listSelectedRepos()).filter(scope.bundle).map(({ repoId, fullName }) => ({ repoId, fullName }))
+    return { userId: snapshot.user.role === 'admin' ? undefined : snapshot.user.id, scope, repos }
+  }
+  return {
+    async getReportCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const reports = await db.listReports(userId)
+      const linked = reports.flatMap(report => report.bundleId ? [report.bundleId] : [])
+      const readable = userId === undefined ? new Set(linked) : new Set(await db.listReadableBundleIds(userId, linked))
+      return { repos, repoScopes: scope.scopes, reports: reports.map(report => ({ ...report,
+        canChangeRepo: report.repoId === null || scope.report(report),
+        bundleId: report.bundleId && readable.has(report.bundleId) ? report.bundleId : null,
+        bundleFilename: report.bundleId && readable.has(report.bundleId) ? report.bundleFilename : null,
+      })) }
+    },
+    async getBundleCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const bundles = await db.listBundles(userId)
+      return { repos, repoScopes: scope.scopes, bundles: bundles.map(bundle => ({ ...bundle,
+        canChangeRepo: bundle.repoId === null || scope.report(bundle),
+      })) }
+    },
+  }
+}

package/server-managed/management.ts

@@ -0,0 +1,99 @@
+import type { AdminReport, BundleReuse, ManagedBundle, ManagedDb, ManagedRepo, RepoDataItem, RepoReportItem, ReportRecord, StoredUser } from './db-methods.ts'
+import { roleAtLeast } from '../common/managed/roles.ts'
+
+export class ManagedMutationError extends Error {
+  status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+
+export type ContentMutation = { type: 'delete' } | { type: 'repo'; repoId: number | null; directory: string } | { type: 'visibility'; visible: boolean }
+export type ReportMutation = ContentMutation
+type RemovalRepo = Pick<ManagedRepo, 'repoId' | 'fullName' | 'addedAt'>
+type RemovalAnnotations = { reports: string; ids: string[] }
+export interface ManagementStore {
+  mutateReport(sessionId: string, id: string, change: ReportMutation): Promise<{ report: ReportRecord; user: StoredUser }>
+  mutateBundle(sessionId: string, id: string, change: ContentMutation): Promise<{ bundle: ManagedBundle; user: StoredUser }>
+  // A repeated upload/build of stored bytes (see reuseBundle). Renames need the
+  // access other bundle mutations need; a server build labels the row anyway.
+  reuseBundleUpload(sessionId: string, id: string, reuse: Omit<BundleReuse, 'rename'>): Promise<boolean>
+  removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null): Promise<{
+    reports: RepoReportItem[]; bundles: RepoDataItem[]; deletedReports: number; deletedBundles: number; deletedTriage: number
+  }>
+}
+type ManagementDb = Pick<ManagedDb, 'sessionWithUser' | 'getReport' | 'getBundle' | 'listReports' | 'listReportsForRepo'
+  | 'listBundlesForRepo' | 'listAllRepos' | 'listSelectedRepos' | 'userCanReadReport' | 'userCanReadBundle' | 'userCanReadRepoPath'
+  | 'deleteReport' | 'setReportRepo' | 'setReportVisible' | 'deleteBundle' | 'setBundleRepo' | 'setBundleVisible' | 'reuseBundle'
+  | 'deleteReportsForRepo' | 'deleteBundlesForRepo' | 'deleteRepo' | 'deleteTriage' | 'recordActivity'>
+
+// Only immutable bytes/format and repository membership affect the overlap
+// scan. Ignore publication, user display names, and unrelated bundle links.
+export function reportReferenceSnapshot(reports: readonly Pick<AdminReport, 'id' | 'sha256' | 'filename' | 'repoId'>[]): string {
+  return JSON.stringify(reports.map(r => [r.id, r.sha256, r.filename, r.repoId]).toSorted((a, b) => String(a[0]).localeCompare(String(b[0]))))
+}
+
+// These methods are wrapped by scopeManagedMethods: authorization, comparison,
+// metadata changes (and repository-removal audit) share the writer transaction. Blob reads
+// and deletes stay outside it. Use the raw store here, never nested scopes.
+export function managementMethods(db: ManagementDb): ManagementStore {
+  async function authorize(sessionId: string, role: 'admin' | 'manage') {
+    const s = await db.sessionWithUser(sessionId, Date.now())
+    if (!s) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(s.user.role, role)) throw new ManagedMutationError(403, 'forbidden')
+    return s.user
+  }
+  async function destination(user: { id: string; role: string }, change: ContentMutation) {
+    if (change.type !== 'repo' || change.repoId === null) return
+    if (!(await db.listSelectedRepos()).some(repo => repo.repoId === change.repoId)) throw new ManagedMutationError(400, 'bad-repo')
+    if (user.role !== 'admin' && !await db.userCanReadRepoPath(user.id, change.repoId, change.directory)) throw new ManagedMutationError(403, 'repo-forbidden')
+  }
+  return {
+    async mutateReport(sessionId: string, id: string, change: ReportMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const report = await db.getReport(id)
+      if (!report || (user.role !== 'admin' && report.uploadedBy !== user.id && !await db.userCanReadReport(user.id, id))) throw new ManagedMutationError(404, 'no-report')
+      if (user.role !== 'admin' && report.repoId !== null && !await db.userCanReadReport(user.id, id)) throw new ManagedMutationError(403, 'repo-forbidden')
+      if (change.type === 'repo' && report.repoEmbedded) throw new ManagedMutationError(409, 'repo-in-report')
+      if (change.type !== 'visibility') await destination(user, change)
+      if (change.type === 'delete') await db.deleteReport(id)
+      else if (change.type === 'visibility') await db.setReportVisible(id, change.visible)
+      else await db.setReportRepo(id, change.repoId, change.directory)
+      return { report, user }
+    },
+    async mutateBundle(sessionId: string, id: string, change: ContentMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const bundle = await db.getBundle(id)
+      if (!bundle || (user.role !== 'admin' && !await db.userCanReadBundle(user.id, id))) throw new ManagedMutationError(404, 'no-bundle')
+      if (user.role !== 'admin' && bundle.repoId !== null && !await db.userCanReadRepoPath(user.id, bundle.repoId, bundle.repoDirectory)) throw new ManagedMutationError(403, 'repo-forbidden')
+      await destination(user, change)
+      if (change.type === 'delete') await db.deleteBundle(id)
+      else if (change.type === 'visibility') await db.setBundleVisible(id, change.visible)
+      else await db.setBundleRepo(id, change.repoId, change.directory)
+      return { bundle, user }
+    },
+    async reuseBundleUpload(sessionId: string, id: string, reuse: Omit<BundleReuse, 'rename'>) {
+      const user = await authorize(sessionId, 'manage')
+      const bundle = await db.getBundle(id)
+      if (!bundle) return false
+      const rename = user.role === 'admin' || (await db.userCanReadBundle(user.id, id)
+        && (bundle.repoId === null || await db.userCanReadRepoPath(user.id, bundle.repoId, bundle.repoDirectory)))
+      if (!rename && reuse.provenance !== 'build') return false
+      return db.reuseBundle(id, { ...reuse, rename })
+    },
+    async removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null) {
+      const user = await authorize(sessionId, 'admin')
+      const repo = (await db.listAllRepos()).find(r => r.repoId === expected.repoId)
+      if (!repo) throw new ManagedMutationError(404, 'no-repo')
+      if (repo.fullName !== expected.fullName || repo.addedAt !== expected.addedAt) throw new ManagedMutationError(409, 'repository-changed')
+      if (annotations && reportReferenceSnapshot(await db.listReports()) !== annotations.reports) throw new ManagedMutationError(409, 'repository-changed')
+      const reports = await db.listReportsForRepo(repo.repoId)
+      const bundles = await db.listBundlesForRepo(repo.repoId)
+      const deletedReports = await db.deleteReportsForRepo(repo.repoId)
+      const deletedBundles = await db.deleteBundlesForRepo(repo.repoId)
+      const deletedTriage = await db.deleteTriage(annotations?.ids ?? [])
+      await db.deleteRepo(repo.repoId)
+      await db.recordActivity({ kind: 'delete', actor: user.login, actorId: user.id, repo: repo.fullName,
+        action: `removed a repository (${deletedReports} reports, ${deletedBundles} bundles, ${deletedTriage} triage entries)` }, Date.now())
+      return { reports, bundles, deletedReports, deletedBundles, deletedTriage }
+    },
+  }
+}

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
+}

package/server-managed/npm-kept.ts

@@ -0,0 +1,65 @@
+// What the npm viewer and repository risk scans keep in the database
+// (managed_upstream_cache, upstream-cache.ts), beyond the instance, so that
+// neither asks for it again on every read, nor after a restart or on another
+// instance: public versions' documents, of the fields read of them
+// (npm-manifest.ts npmVersionFields), for a day (readNpmVersion asks npm again
+// then, as a version can be deprecated, its package made private, or itself
+// removed); and, for scans, each package's risk line, for as long as a scan
+// keeps it (repository-risk.ts). Each store removes its own rows kept longer
+// than that as it writes, at most once an hour a database, so that rows no
+// read will take again don't pile up.
+// The database is an optimization: a failure reads as a miss, and writes
+// nothing.
+import { createHash } from 'node:crypto'
+import { plainObject } from './npm-manifest.ts'
+import { type NpmVersionStore, VERSION_KEPT_MS } from './npm-packages.ts'
+import type { UpstreamCacheStore } from './upstream-cache.ts'
+
+// A value kept by key, as JSON, `at` when it was.
+export interface KeptStore<T> {
+  read(key: string): Promise<{ at: number; value: T } | null>
+  write(key: string, value: T, at: number): Promise<void>
+}
+
+// When each database last had each type's old rows removed.
+const PRUNE_EVERY_MS = 60 * 60_000
+const pruned = new WeakMap<UpstreamCacheStore, Map<string, number>>()
+
+// Values of `type`, each read for `keptMs` after it was kept.
+function keptStore<T>(db: UpstreamCacheStore, type: string, keptMs: number, debug: boolean): KeptStore<T> {
+  const warn = (what: string, error: unknown) => { if (debug) console.warn(`managed: kept ${type} ${what} failed:`, error) }
+  const prune = async (at: number) => {
+    const times = pruned.get(db) ?? pruned.set(db, new Map()).get(db)!
+    if (at - (times.get(type) ?? -Infinity) < PRUNE_EVERY_MS) return
+    times.set(type, at)
+    try { await db.deleteUpstreamCacheEntries(`${type}/`, at - keptMs) } catch (error) { warn('prune', error) }
+  }
+  // Keys of any length or character, as the database's: hashed.
+  const keyOf = (key: string) => `${type}/${createHash('sha256').update(key).digest('hex')}`
+  return {
+    async read(key) {
+      try {
+        const kept: unknown = JSON.parse(await db.getUpstreamCacheEntry(keyOf(key)) ?? 'null')
+        return plainObject(kept) && typeof kept['at'] === 'number' && 'value' in kept ? { at: kept['at'], value: kept['value'] as T } : null
+      } catch (error) { warn('read', error); return null }
+    },
+    async write(key, value, at) {
+      try { await db.setUpstreamCacheEntry(keyOf(key), JSON.stringify({ at, value }), at) } catch (error) { warn('write', error) }
+      await prune(at)
+    },
+  }
+}
+
+export function npmVersionStore(db: UpstreamCacheStore, debug = false): NpmVersionStore {
+  const kept = keptStore<Record<string, unknown>>(db, 'npm/version-documents', VERSION_KEPT_MS, debug)
+  return {
+    async read(name, version) {
+      const hit = await kept.read(`${name}@${version}`)
+      return hit && plainObject(hit.value) ? { at: hit.at, json: hit.value } : null
+    },
+    write: (name, version, json) => kept.write(`${name}@${version}`, json, Date.now()),
+  }
+}
+
+// Risk lines, each read for `keptMs`, as long as a scan keeps them.
+export const riskLineStore = <T>(db: UpstreamCacheStore, keptMs: number, debug = false): KeptStore<T> => keptStore<T>(db, 'repository-risk/lines', keptMs, debug)