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

package/risk/npm/manifest.js

@@ -0,0 +1,65 @@
+// What risk reads of a version from npm's version document, as the npm viewer
+// is served it (server-managed/npm-packages.ts npmManifest): the npm account
+// that published it, or the CI that did by npm's trusted publishing, which of
+// its accounts are known to publish (@preventive/publishers), whether npm
+// keeps a provenance statement for it, the scripts npm runs installing it,
+// its dependencies, and its deprecation; and whether a package's scope is one
+// of npm's most downloaded packages'.
+import publishers from '@preventive/publishers/npm.js'
+import scopes from '@preventive/publishers/npm-scopes.js'
+import { INSTALL_SCRIPTS } from './install-scripts.js'
+
+const NPM_ACCOUNT = /^[\w.-]{1,214}$/u
+// The npm accounts known to publish: those with standing on one of npm's
+// most downloaded packages.
+const KNOWN_PUBLISHERS = new Set(publishers.map(name => name.toLowerCase()))
+// The scopes of npm's most downloaded packages, which only their owners, an
+// npm organization or account, publish in; and those accounts' own, by
+// scope: npm's accounts and organizations share one namespace, so `@name` is
+// the account `name`'s.
+const KNOWN_SCOPES = new Set(scopes)
+const PUBLISHER_SCOPES = new Map(publishers.map(name => [`@${name.toLowerCase()}`, name]))
+
+// A package's scope where it is known: one of npm's most downloaded
+// packages' (`{ scope }`, `@babel` of `@babel/core`), or else a known
+// publisher's own (`{ scope, account }`, `@sindresorhus` of
+// `@sindresorhus/is`); else null.
+export function npmKnownScope(name) {
+  const scope = name.startsWith('@') ? name.slice(0, name.indexOf('/')) : null
+  if (!scope) return null
+  if (KNOWN_SCOPES.has(scope)) return { scope }
+  const account = PUBLISHER_SCOPES.get(scope)
+  return account ? { scope, account } : null
+}
+const plainObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+const stringRecord = value => plainObject(value) ? Object.fromEntries(Object.entries(value).filter(([, item]) => typeof item === 'string')) : undefined
+
+// One of package.json's people's name: `{ name }`, or `Name <email> (url)` in
+// one string.
+function personName(value) {
+  const text = part => typeof part === 'string' && part.trim() !== '' ? part.trim() : null
+  if (plainObject(value)) return text(value.name)
+  return typeof value === 'string' ? text(/^([^<(]*)/u.exec(value)?.[1]) : null
+}
+
+// A version document's manifest, as risk reads it: `publisher` (or
+// `trustedPublisher`), `knownAccounts`, `provenance`, `installScripts`,
+// `dependencies`, `peerDependencies` and `optionalDependencies`, and
+// `deprecated`, each where it has one.
+export function npmVersionManifest(json) {
+  const pick = {}
+  if (typeof json?.deprecated === 'string') pick.deprecated = json.deprecated
+  const publisher = personName(json?._npmUser)
+  if (publisher && NPM_ACCOUNT.test(publisher)) pick.publisher = publisher
+  else if (publisher && publisher.length <= 64 && plainObject(json._npmUser.trustedPublisher)) pick.trustedPublisher = publisher
+  if (pick.publisher && KNOWN_PUBLISHERS.has(pick.publisher.toLowerCase())) pick.knownAccounts = [pick.publisher]
+  for (const key of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+    const record = stringRecord(json?.[key])
+    if (record && Object.keys(record).length > 0) pick[key] = record
+  }
+  if (plainObject(json?.dist) && plainObject(json.dist.attestations) && plainObject(json.dist.attestations.provenance)) pick.provenance = true
+  const scripts = stringRecord(json?.scripts)
+  const install = scripts ? INSTALL_SCRIPTS.filter(script => script in scripts) : []
+  if (install.length > 0) pick.installScripts = Object.fromEntries(install.map(script => [script, scripts[script]]))
+  return pick
+}

package/risk/npm/new-dependency.js

@@ -0,0 +1,60 @@
+// What risk tells of a dependency a version adds, by its package: its tier by
+// its downloads, its latest two weeks' left out (downloads.js
+// npmSettledDownloads), as a package a release just pulled in, as a
+// compromised one depending on it would, could owe those to that release
+// alone; and below the top 20,000, how old the package was where it didn't
+// exist when the version compared with was published, as plain-crypto-js
+// was eighteen hours old when axios 1.14.1 was published depending on it.
+import { npmDownloadTier, npmSettledDownloads, npmTierLow } from './downloads.js'
+
+// A dependency added, from its package's facts so far: `downloads`, npm's
+// count of them (null where npm counts none, as it counts none of a package's
+// until the day after it was first published, nor any of a private one's);
+// `listed`, once its version list is read, `{ created, private, installs? }`,
+// when its first version was published, whether only a token reads it, and
+// the version of it its spec installs (registry.js npmPublicFacts); and
+// `published`, when the version compared with and the open one were; and
+// whether nothing of the version imports it (`unused`). Its `tier`
+// (Infinity, unpopular, where npm counts none of a public package's; null
+// where it can't yet be told), whether its version list is `wanted` to tell
+// more (below the top 20,000, or none counted, or unused whatever its tier,
+// as how new its package is grades it, npmUnusedDependencySeverity),
+// `created`, `gap` where its package is new since the version compared
+// with: when its first version was published, and how long before the open
+// version that was (negative for after, as a name someone took once a
+// release named it); and where told, the version its spec `installs`,
+// `new` where that was published since the version compared with.
+export function npmAddedDependency({ downloads, listed = null, published = [], unused = false }, now = Date.now()) {
+  const settled = npmSettledDownloads(downloads, now)
+  const counted = settled ? npmDownloadTier(settled) : null
+  const wanted = !settled || unused || (counted !== null && npmTierLow(counted))
+  const tier = settled ? counted : listed && !listed.private ? Infinity : null
+  const [was, open] = published
+  const created = wanted && tier !== null && listed?.created && was && open && Date.parse(listed.created) > Date.parse(was) ? listed.created : null
+  const installs = listed?.installs ? { ...listed.installs, new: Boolean(was && listed.installs.published && Date.parse(listed.installs.published) > Date.parse(was)) } : null
+  return { tier, wanted, created, gap: created ? Date.parse(open) - Date.parse(created) : null, ...installs ? { installs } : {} }
+}
+
+// What a dependency nothing of a version imports calls for (compare.js
+// `unused-deps`), by what risk tells of its package (`told`, its row as
+// assess.js addedDependencies tells it, or none): one kept from the version
+// compared with (`kept`) yellow, as that version, risk's pick of the most
+// likely free of an attack, held it; else red where its package is new
+// since that version (`created`), as plain-crypto-js was to axios 1.14.1,
+// or the version its spec installs (`installs`) is, has install scripts and
+// isn't its package's latest, as an old package's old major line given a
+// release to run them would, where a package still releasing its latest
+// wouldn't; orange where that version has install scripts, as installing an unused
+// dependency runs them and nothing else, or npm has none of its package
+// for anyone (`missing`), as once unpublished or taken down, whatever
+// downloads it still counts; yellow among npm's top 20,000, as
+// a dependency named for another's peer or by a tool's config is (react,
+// typescript, eslint), older and more downloaded than the package naming
+// it; orange past them, or where its package isn't told.
+export function npmUnusedDependencySeverity(told, kept) {
+  if (kept) return 'moderate'
+  const { scripts, new: anew, version, latest } = told?.installs ?? {}
+  if (told?.created || (scripts && anew && version !== latest)) return 'critical'
+  if (scripts || told?.missing) return 'high'
+  return told?.level && !npmTierLow(told.tier ?? Infinity) ? 'moderate' : 'high'
+}

package/risk/npm/old-version.js

@@ -0,0 +1,108 @@
+// The version an open version is compared with where the caller leaves it to
+// risk (assess.js `oldVersion: true`): of the package's others, the one most
+// likely free of what an attack injects, as a pair's findings flag only what
+// is new against it, so an attack's own earlier version, or one published
+// with it, would hide what it injected. Told by what npm's document says of
+// each version alone (registry.js npmPackageFacts): when it was published,
+// its publisher and whether that account is known (manifest.js), its
+// deprecation, and those since removed from npm, whose times it keeps; no
+// tarball is read for it.
+import { DAY_MS } from './downloads.js'
+import { npmAccountStanding } from './release.js'
+
+// How long a version is on npm before it is taken as looked at: a month, as
+// an attack's versions are mostly found and pulled within days.
+const SETTLED_MS = 30 * DAY_MS
+// How near the open version's publish, either side, a version comes with it:
+// a week, as an attack publishes its versions within days of each other.
+const CLOSE_MS = 7 * DAY_MS
+// How near a version since removed from npm, either side, a version comes
+// with it: a day, as an attack's versions come within hours of each other,
+// and npm removes those it finds.
+const REMOVED_MS = DAY_MS
+
+// A version as npm publishes one, `{ core, pre }`: its MAJOR.MINOR.PATCH, each
+// to 16 digits and a safe integer as semver takes them, and its prerelease's
+// identifiers, build metadata aside; null for any other.
+const VERSION = /^(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})(?:-([\da-z-]+(?:\.[\da-z-]+)*))?(?:\+[\da-z-]+(?:\.[\da-z-]+)*)?$/iu
+function parsed(version) {
+  const match = VERSION.exec(version)
+  const core = match?.slice(1, 4).map(Number)
+  return core?.every(Number.isSafeInteger) ? { core, pre: match[4]?.split('.') ?? [] } : null
+}
+
+// Which of two versions is higher, by semver's precedence: their cores, a
+// release above its prereleases, and prereleases by their identifiers, a
+// number below a word.
+function compared(a, b) {
+  const core = a.core.findIndex((part, at) => part !== b.core[at])
+  if (core !== -1) return a.core[core] - b.core[core]
+  if (a.pre.length === 0 || b.pre.length === 0) return b.pre.length - a.pre.length
+  for (let at = 0; at < Math.max(a.pre.length, b.pre.length); at++) {
+    const x = a.pre[at], y = b.pre[at]
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1
+    if (x === y) continue
+    const xNumber = /^\d+$/u.test(x), yNumber = /^\d+$/u.test(y)
+    if (xNumber !== yNumber) return xNumber ? -1 : 1
+    if (xNumber && x.length !== y.length) return x.length - y.length
+    return x < y ? -1 : 1
+  }
+  return 0
+}
+
+// Of a package's versions (`releases`, `{ version, published, publisher,
+// known, deprecated, removed }` each, `removed` one since removed from npm,
+// its time alone kept), the one `version` is compared with at `now`, or null
+// where none is below it. Each account by its standing on the package when
+// the open version was published (release.js npmAccountStanding), the most
+// first: known, one that publishes one of npm's most downloaded packages;
+// one of its maintainers, on it three months or more, or first to publish
+// it; and new to it. Of those below it, a release where it is one, the
+// highest that is preferred, each preference kept only where some version
+// holds it, in turn:
+//
+// - Where an account new to it published it, one another published, as an
+//   attack may have published more than one.
+// - One published before it, not after, as one published since (a
+//   backport) is no version it came from.
+// - Where the highest of those an account of a higher standing than its own
+//   published, as when a package is taken from its maintainers, one an
+//   account of that standing or higher published.
+// - One published a day or more apart from any version since removed from
+//   npm, as not one of the attack npm removed those of.
+// - One published a week or more apart from it, as not one of an attack's,
+//   and on npm a month or more, as looked at; but for one a known account
+//   other than its own published, trusted however new, and one a maintainer
+//   other than its own published, held to the week alone, as an account taken
+//   leaves another's versions alone, and a maintainer few know of is taken
+//   with its peers as often. Its own account's are held to both, as it may be
+//   the one taken.
+// - One npm doesn't say is deprecated, as one a maintainer took back.
+//
+// The highest is in its branch (`1.x.y`, `0.2.y`, `0.0.y`) where one is
+// there, else in the closest branch below.
+const RANKS = { new: 0, maintainer: 1, known: 2 }
+export function npmOldVersion(version, releases, now) {
+  const open = releases.find(row => row.version === version && !row.removed)
+  const at = open && parsed(version)
+  if (!at) return null
+  const prefer = (rows, wanted) => { const kept = rows.filter(wanted); return kept.length > 0 ? kept : rows }
+  const time = row => row.published === null ? Number.NaN : Date.parse(row.published)
+  const opened = time(open)
+  const versions = releases.flatMap(row => { const of = parsed(row.version); return of ? [{ ...row, of }] : [] })
+  const removed = versions.filter(row => row.removed).map(time).filter(Number.isFinite)
+  const standing = npmAccountStanding(releases, open.published)
+  const rank = row => row?.publisher ? RANKS[standing(row.publisher, row.known)] : RANKS.new
+  const own = rank(open)
+  let rows = prefer(versions.filter(row => !row.removed && compared(row.of, at) < 0).toSorted((a, b) => compared(b.of, a.of)),
+    row => row.of.pre.length === 0 || at.pre.length > 0)
+  if (open.publisher && own === RANKS.new) rows = prefer(rows, row => row.publisher !== open.publisher)
+  rows = prefer(rows, row => time(row) < opened)
+  const top = rank(rows[0])
+  if (open.publisher && top > own) rows = rows.filter(row => rank(row) >= top)
+  rows = prefer(rows, row => removed.every(gone => Math.abs(time(row) - gone) >= REMOVED_MS))
+  const vouched = row => row.publisher === open.publisher ? RANKS.new : rank(row)
+  rows = prefer(prefer(rows, row => vouched(row) === RANKS.known || Math.abs(time(row) - opened) >= CLOSE_MS),
+    row => vouched(row) >= RANKS.maintainer || now - time(row) >= SETTLED_MS)
+  return prefer(rows, row => !row.deprecated)[0]?.version ?? null
+}

package/risk/npm/registry.js

@@ -0,0 +1,388 @@
+// What risk asks npm for, each kept in the caller's cache where it gives one
+// (`cache`, as @preventive/upstream's CacheStore: `read(type, key)` and
+// `write(type, key, value)`, each type its caller's to keep where it will):
+//
+// - `npm/tarballs`, `<name>@<version>`: a version's tarball, its bytes, as
+//   upstream's getTarball keeps one, checked against its integrity.
+// - `risk/npm/versions`, `<name>@<version>`: what a version's document says,
+//   which npm never changes once published: its manifest (manifest.js, its
+//   deprecation aside), when it was published, and its dist.
+// - `risk/npm/packages`, `<name>`: the versions npm says are deprecated, those
+//   it removed (each one's when), and whether it took the package down, as
+//   `at` a time, asked again after an hour, as npm deprecates and removes a
+//   version any time.
+// - `risk/npm/old-versions`, `<name>@<version>`: the version it is compared
+//   with where risk picks it (old-version.js npmOldVersion), or none, as `at`
+//   a time, picked again after an hour, as npm publishes and deprecates
+//   versions any time and those it has grow older.
+// - `risk/npm/public`, `<name>`: when a package anyone can read was first
+//   published, or `{ missing: true }`, as `at` a time, asked again after an
+//   hour.
+// - `risk/npm/downloads`, `<name>@<from>:<to>`: its downloads a day over those
+//   days, `{ start, end, days }`, or `{ none: true }` where npm counts none.
+//
+// The package assessed is asked for as upstream asks, with the npm token the
+// environment has for a scoped one (PREVENTIVE_MEASURES_NPM_TOKEN,
+// STASIS_NPM_TOKEN or NPM_TOKEN), so a private one can be read; its
+// dependencies' public facts and downloads with none. A caller may ask for
+// packages' documents (`packument`) and versions' tarballs (`tarball`)
+// itself, as the managed server does, within the bounds it holds every read
+// of npm to; else a tarball is upstream's getTarball's, bounded as upstream
+// bounds it. What risk asks npm itself is given up on after 30 seconds, and
+// read no further than its bounds, `upstream-too-large` past them, as is a
+// tarball unpacking past tarball.js's, `package-too-large`.
+import { advisories } from '@preventive/upstream/advisories.js'
+import { getTarball } from '@preventive/upstream/npm.js'
+import { compareVersions, satisfies, validRange } from '@preventive/upstream/semver.js'
+import { npmVersionManifest } from './manifest.js'
+import { npmAlias } from './specs.js'
+import { npmPlaceholder } from './malware.js'
+import { npmOldVersion } from './old-version.js'
+import { npmTarballVersion } from './tarball.js'
+import { DAY_MS } from './downloads.js'
+
+const REGISTRY = 'https://registry.npmjs.org'
+const DOWNLOADS = 'https://api.npmjs.org/downloads/range'
+const PACKAGE_MS = 60 * 60_000
+// How long a version's advisories are kept, as the managed server keeps a
+// package's and a lockfile's: an hour, as a new one may come at any time.
+const ADVISORIES_MS = 60 * 60_000
+// How much of npm's answers is read: a whole document, as the managed server
+// reads one (server-managed/npm-packages.ts PACKUMENT_BYTES), and a few
+// months' downloads a day.
+const PACKUMENT_BYTES = 64 * 1024 * 1024
+const DOWNLOADS_BYTES = 1024 * 1024
+// How long a package's downloads are kept: a week, as the tier they put it in,
+// by the most of its latest six weeks' (downloads.js npmDownloadTier), hardly
+// moves in one, and npm's downloads API answers only some 40 lookups a minute.
+const DOWNLOADS_MS = 7 * DAY_MS
+// How many packages npm's downloads API answers in one lookup, unscoped ones
+// alone (it refuses a scoped one in a bulk lookup), and how much of it is read.
+const BULK_DOWNLOADS = 128
+const BULK_DOWNLOADS_BYTES = 8 * 1024 * 1024
+// How long npm is waited on for an answer, as the managed server waits on its
+// upstreams (server-managed/npm-packages.ts askUpstream).
+const REQUEST_MS = 30_000
+
+export class NpmRiskError extends Error {
+  constructor(code, message = code) { super(message); this.code = code }
+}
+
+const isTime = value => typeof value === 'string' && value.length <= 40 && !Number.isNaN(Date.parse(value))
+// An object as JSON holds one, not an array (manifest.js plainObject).
+const plainObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+// A scoped name in a downloads API path, its slash escaped.
+const encoded = name => name.replace('/', '%2f')
+const token = () => typeof process === 'undefined' ? null
+  : ['PREVENTIVE_MEASURES_NPM_TOKEN', 'STASIS_NPM_TOKEN', 'NPM_TOKEN'].map(key => process.env[key]).find(Boolean) ?? null
+
+// A value kept under `type` and `key`, else `ask`ed and kept; one `fresh`
+// says is stale asked again.
+async function kept({ cache }, type, key, ask, fresh = () => true) {
+  const hit = cache ? await cache.read(type, key) : null
+  if (hit != null && fresh(hit)) return hit
+  const value = await ask()
+  if (cache && value != null) await cache.write(type, key, value)
+  return value
+}
+
+// What is kept under each `[type, key]` of `entries`, in their order, null
+// where nothing is: in one read where the cache reads records of any types at
+// once (`readEach`), else one a key.
+const readEach = (cache, entries) => cache.readEach ? cache.readEach(entries) : Promise.all(entries.map(([type, key]) => cache.read(type, key)))
+
+// An answer's body as JSON, read no further than `limit` bytes.
+async function jsonOf(res, limit, what) {
+  const tooLarge = () => new NpmRiskError('upstream-too-large', `npm's answer for ${what} is over ${limit} bytes`)
+  if (Number(res.headers.get('content-length')) > limit) { await res.body?.cancel(); throw tooLarge() }
+  const chunks = []
+  let size = 0
+  for await (const chunk of res.body ?? []) {
+    size += chunk.byteLength
+    if (size > limit) throw tooLarge()
+    chunks.push(chunk)
+  }
+  try { return JSON.parse(await new Blob(chunks).text()) } catch { throw new NpmRiskError('upstream-invalid', `npm's answer for ${what} isn't JSON`) }
+}
+
+// What npm answers `url` as JSON (jsonOf), null where it answers 404; given up
+// on after REQUEST_MS, or once the caller's `signal` aborts, its abort
+// rethrown as it is. `upstream-busy` where npm asks to be asked later (429),
+// as its downloads API does past a burst of requests;
+// `upstream-unavailable` where it can't be asked or answers otherwise.
+async function askNpm(url, headers, limit, what, { signal }) {
+  try {
+    const res = await fetch(url, { headers: { accept: 'application/json', ...headers }, redirect: 'error', signal: AbortSignal.any([AbortSignal.timeout(REQUEST_MS), ...signal ? [signal] : []]) })
+    if (res.status === 404) { await res.body?.cancel(); return null }
+    if (!res.ok) { await res.body?.cancel(); throw new NpmRiskError(res.status === 429 ? 'upstream-busy' : 'upstream-unavailable', `npm answered ${res.status} for ${what}`) }
+    return await jsonOf(res, limit, what)
+  } catch (error) {
+    if (error instanceof NpmRiskError || signal?.aborted) throw error
+    throw new NpmRiskError('upstream-unavailable', `npm couldn't be asked for ${what}: ${error.message}`)
+  }
+}
+
+// A package's whole document, null where npm has none for this asker: the
+// caller's (`packument`) where it gives one, else risk's own.
+function packageDocument(name, context, authorized) {
+  if (context.packument) return context.packument(name, { authorized, signal: context.signal })
+  const secret = authorized && name.startsWith('@') ? token() : null
+  return askNpm(`${REGISTRY}/${name}`, secret ? { authorization: `Bearer ${secret}` } : {}, PACKUMENT_BYTES, name, context)
+}
+
+// When a document says its package's first version was published, one since
+// unpublished among them: the earliest time it lists.
+const firstPublished = doc => Object.entries(doc?.time ?? {}).filter(([key, at]) => key !== 'modified' && isTime(at)).map(([, at]) => at)
+  .reduce((first, at) => first === null || Date.parse(at) < Date.parse(first) ? at : first, null)
+
+// Each version a package's document lists, as old-version.js npmOldVersion
+// picks among them: `{ version, published, publisher, known, deprecated,
+// removed }`, its publisher's account as manifest.js reads it, and whether
+// that is known; and each it lists a time of and no document, as one since
+// removed from npm, `removed`, its time alone, as npmPackageFacts reads none
+// of it. Its times' other keys (`created`, `modified`) are no versions, as
+// none of a version starts with a letter.
+const versionsOf = doc => [...new Set([...Object.keys(doc.versions ?? {}), ...Object.keys(doc.time ?? {}).filter(key => /^\d/u.test(key))])]
+const releasesOf = (doc, deprecated = {}) => versionsOf(doc).map(version => {
+  const json = doc.versions?.[version]
+  const { publisher = null, knownAccounts } = json ? npmVersionManifest(json) : {}
+  return { version, published: isTime(doc.time?.[version]) ? doc.time[version] : null, publisher, known: Boolean(knownAccounts),
+    deprecated: Object.hasOwn(deprecated, version), removed: !json }
+})
+
+// What risk reads of `version` of a package, of the one it is compared with
+// (`oldVersion`: one, null for none, or true for the one old-version.js
+// npmOldVersion picks of its versions, by its document), and of the package:
+// `versions`, each one's `{ manifest, published, dist }`, those of them npm
+// removed since they were published (`removed`, each one's when), none
+// picked to compare a removed one with, `deprecated`, by version, whether
+// npm's security team took the package down (`takenDown`, its latest version
+// npm's placeholder, malware.js npmPlaceholder), `removals`, how many
+// versions of it npm removed, `oldVersion`, the one compared with or null,
+// and where its document was read and either the pick
+// or another account publishing each wants them, `releases`, each version it
+// lists (releasesOf), so that no more of the document is held. Its document
+// is read once at most, and not at all where all of it is kept and fresh. A
+// version's facts are kept for good, as npm never changes a version, but npm
+// may remove it: the package's, kept an hour, has which it removed, and they
+// go by that.
+export async function npmPackageFacts(name, version, oldVersion, context) {
+  const { cache, now } = context
+  const fresh = hit => hit != null && now - hit.at < PACKAGE_MS
+  const picked = cache && oldVersion === true ? await cache.read('risk/npm/old-versions', `${name}@${version}`) : null
+  const given = oldVersion === true ? fresh(picked) ? picked.oldVersion : undefined : oldVersion
+  if (cache && given !== undefined) {
+    const wanted = given === null ? [version] : [version, given]
+    const [pkg, ...facts] = await readEach(cache, [['risk/npm/packages', name], ...wanted.map(at => ['risk/npm/versions', `${name}@${at}`])])
+    const gone = at => Object.hasOwn(pkg.removed, at)
+    if (fresh(pkg) && 'removed' in pkg && wanted.every((at, i) => facts[i] || gone(at))) {
+      return { versions: new Map(wanted.flatMap((at, i) => gone(at) ? [] : [[at, facts[i]]])), removed: new Map(wanted.filter(gone).map(at => [at, pkg.removed[at]])),
+        removals: Object.keys(pkg.removed).length, deprecated: pkg.deprecated, takenDown: pkg.takenDown, oldVersion: given }
+    }
+  }
+  const doc = await packageDocument(name, context, true)
+  if (!doc) throw new NpmRiskError('package-not-found', `npm has no package ${name}`)
+  const removed = new Map()
+  const factsOf = at => {
+    const json = doc.versions?.[at]
+    if (!json && isTime(doc.time?.[at])) { removed.set(at, doc.time[at]); return null }
+    if (!json) throw new NpmRiskError('version-not-found', `npm has no ${name}@${at}`)
+    const { deprecated: _, ...manifest } = npmVersionManifest(json)
+    return { manifest, published: isTime(doc.time?.[at]) ? doc.time[at] : null, dist: { tarball: json.dist?.tarball, integrity: json.dist?.integrity } }
+  }
+  const opened = factsOf(version)
+  const deprecated = Object.fromEntries(Object.entries(doc.versions ?? {}).filter(([, json]) => typeof json?.deprecated === 'string' && json.deprecated !== '').map(([at, json]) => [at, json.deprecated]))
+  let releases = oldVersion === true && opened ? releasesOf(doc, deprecated) : null
+  const old = oldVersion === true ? opened && npmOldVersion(version, releases, now) : oldVersion
+  const read = new Map([...opened ? [[version, opened]] : [], ...old === null ? [] : [[old, factsOf(old)]]].filter(([, fact]) => fact))
+  const takenDown = npmPlaceholder(doc.versions?.[doc['dist-tags']?.latest])
+  const publishers = [version, old].map(at => read.get(at)?.manifest.publisher)
+  if (publishers.every(Boolean) && publishers[0] !== publishers[1]) releases ??= releasesOf(doc, deprecated)
+  const gone = Object.fromEntries(Object.entries(doc.time ?? {}).filter(([at, when]) => at !== 'created' && at !== 'modified' && isTime(when) && !doc.versions?.[at]))
+  if (cache) {
+    await Promise.all([...read].map(([at, fact]) => cache.write('risk/npm/versions', `${name}@${at}`, fact)))
+    await cache.write('risk/npm/packages', name, { at: now, deprecated, takenDown, removed: gone })
+    if (oldVersion === true) await cache.write('risk/npm/old-versions', `${name}@${version}`, { at: now, oldVersion: old })
+  }
+  return { versions: read, removed, removals: Object.keys(gone).length, deprecated, takenDown, oldVersion: old, ...releases ? { releases } : {} }
+}
+
+// npm's advisories of `version` of a package, as `npm audit` asks them, and
+// where `osv`, OSV's records npm's registry hasn't, as the malicious
+// packages' of nx's versions are (MAL-2025-41443, of GHSA-cxm3-wv7p-598c,
+// which npm's registry hasn't): upstream's `advisories` and its `osv`, an
+// advisory of npm's an OSV record names taking the record's ids among its
+// `aliases`. Each `{ id, url?, title?, cwe, aliases }`, kept ADVISORIES_MS,
+// and given up on once `signal` aborts.
+export async function npmVersionAdvisories(name, version, osv, context) {
+  const what = `${name}@${version}`
+  const { rows } = await kept(context, 'risk/npm/advisories', what, async () => {
+    context.signal?.throwIfAborted()
+    const asked = await untilAborted(advisories([{ ecosystem: 'npm', name, versions: [version] }], { cache: false, osv }), context.signal).catch(error => {
+      throw context.signal?.aborted ? error : new NpmRiskError(error?.status === 429 ? 'upstream-busy' : 'upstream-unavailable', `advisories of ${what} couldn't be had: ${error.message}`)
+    })
+    return { at: context.now, osv, rows: asked.map(({ id, url, title, cwe, aliases }) => ({ id, ...url ? { url } : {}, ...title ? { title } : {}, cwe, aliases })) }
+  }, hit => context.now - hit.at < ADVISORIES_MS && hit.osv === osv)
+  return rows
+}
+
+// Each version a package's document lists (releasesOf), the document read
+// anew, as npmPackageFacts reads it.
+export async function npmPackageReleases(name, context) {
+  const doc = await packageDocument(name, context, true)
+  if (!doc) throw new NpmRiskError('package-not-found', `npm has no package ${name}`)
+  return releasesOf(doc)
+}
+
+// `promise`, given up on once `signal` aborts, its reason thrown: what it
+// waits on, which takes no signal (upstream's getTarball), left to settle
+// unheeded.
+function untilAborted(promise, signal) {
+  if (!signal) return promise
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
+  })
+}
+
+// A version's files, as compare.js takes a version, from its tarball
+// (tarball.js): the caller's (`tarball`) where it gives one, its failures
+// thrown as they are, else upstream's, given up on once `signal` aborts; with
+// `npm` its `{ name, version, manifest, published }`.
+export async function npmVersionFiles(name, version, { manifest, published, dist }, { cache, tarball: read, signal }) {
+  const what = `${name}@${version}`
+  signal?.throwIfAborted()
+  const tarball = read ? await read(name, version, { signal }) : await untilAborted(getTarball(name, version, dist, cache === undefined ? {} : { cache }), signal).catch(error => {
+    throw signal?.aborted ? error : new NpmRiskError('upstream-unavailable', `npm's tarball of ${what} couldn't be had: ${error.message}`)
+  })
+  try { return { npm: { name, version, manifest, published }, ...await npmTarballVersion(tarball) } } catch (error) {
+    throw new NpmRiskError(error.message === 'package-too-large' ? 'package-too-large' : 'upstream-invalid', `npm's tarball of ${what}: ${error.message}`)
+  }
+}
+
+// The version of a package's document npm installs for a dependency's spec
+// (`spec`, an alias's by its own range, `npm:name@^1`, as specs.js npmAlias
+// reads one), as npm picks one:
+// the tag it names, else its `latest` where that satisfies it, or any range
+// does (`*`, a prerelease latest too), and isn't deprecated, else the highest
+// that satisfies it, one not deprecated first; null for none, or for a spec
+// that is no range nor tag (a URL, a repository).
+function installedVersion(doc, spec) {
+  const alias = npmAlias(spec)
+  const range = (alias ? alias.spec : String(spec)).trim()
+  const tags = plainObject(doc['dist-tags']) ? doc['dist-tags'] : {}, versions = plainObject(doc.versions) ? doc.versions : {}
+  if (Object.hasOwn(tags, range) && Object.hasOwn(versions, tags[range])) return tags[range]
+  if (validRange(range || '*') === null) return null
+  if (Object.hasOwn(versions, tags.latest) && typeof versions[tags.latest]?.deprecated !== 'string' && ((range || '*') === '*' || satisfies(tags.latest, range))) return tags.latest
+  const matching = Object.keys(versions).filter(version => satisfies(version, range || '*'))
+  const current = matching.filter(version => typeof versions[version]?.deprecated !== 'string')
+  return (current.length > 0 ? current : matching).reduce((best, version) => best === null || compareVersions(version, best) > 0 ? version : best, null)
+}
+
+// When a package anyone can read was first published, `{ created }`, or null
+// for one npm has none of for anyone; and for a dependency's spec (`spec`),
+// the version of it npm installs (installedVersion), `installs`: `{ version,
+// latest, published, scripts }`, its package's `latest` beside it, when it
+// was published and whether it has install scripts: its manifest's, or
+// node-gyp's for a `binding.gyp` (`gypfile`), or as the registry says
+// (`hasInstallScript`); null for none.
+export async function npmPublicFacts(name, context, spec = null) {
+  const facts = await kept(context, 'risk/npm/public', spec === null ? name : `${name}@${spec}`, async () => {
+    const doc = await packageDocument(name, context, false)
+    if (!doc) return { at: context.now, missing: true }
+    const version = spec === null ? null : installedVersion(doc, spec)
+    return { at: context.now, created: firstPublished(doc), ...spec === null ? {} : { installs: version === null ? null
+      : { version, latest: typeof doc['dist-tags']?.latest === 'string' ? doc['dist-tags'].latest : null, published: isTime(doc.time?.[version]) ? doc.time[version] : null,
+        scripts: Boolean(npmVersionManifest(doc.versions[version]).installScripts) || doc.versions[version]?.gypfile === true || doc.versions[version]?.hasInstallScript === true } } }
+  }, hit => context.now - hit.at < PACKAGE_MS)
+  return facts.missing ? null : { created: facts.created, ...spec === null ? {} : { installs: facts.installs } }
+}
+
+// The days a package's downloads are asked over at `now`: from the first of
+// the month before last to yesterday, as the npm viewer asks them.
+const day = time => new Date(time).toISOString().slice(0, 10)
+function rangeAt(now) {
+  const today = new Date(now)
+  return `${day(Date.UTC(today.getUTCFullYear(), today.getUTCMonth() - 2, 1))}:${day(now - DAY_MS)}`
+}
+
+// A package's downloads as kept, from npm's answer of them over a range of
+// days `asked` then: `{ at, start, end, days }`, a count a day from
+// `start`, or `{ at, none }` where npm counts none (null).
+function downloadsOf(json, asked) {
+  if (json === null) return { at: asked, none: true }
+  const start = Date.parse(json.start)
+  const length = Math.round((Date.parse(json.end) - start) / DAY_MS) + 1
+  const days = Array.from({ length: Number.isSafeInteger(length) && length > 0 && length <= 400 ? length : 0 }, () => 0)
+  for (const row of json.downloads ?? []) {
+    const at = Math.round((Date.parse(row.day) - start) / DAY_MS)
+    if (at >= 0 && at < days.length && Number.isSafeInteger(row.downloads)) days[at] = row.downloads
+  }
+  return { at: asked, start: json.start, end: json.end, days }
+}
+// Whether downloads kept are told as they are: kept within DOWNLOADS_MS.
+const freshDownloads = (held, now) => held != null && now - held.at < DOWNLOADS_MS
+
+// A package's downloads a day over rangeAt's days when asked, `{ start, end,
+// days }`, kept a week (DOWNLOADS_MS), null where npm counts none.
+export async function npmDownloads(name, context) {
+  const answer = await kept(context, 'risk/npm/downloads', name,
+    async () => downloadsOf(await askNpm(`${DOWNLOADS}/${rangeAt(context.now)}/${encoded(name)}`, {}, DOWNLOADS_BYTES, `${name}'s downloads`, context), context.now),
+    hit => freshDownloads(hit, context.now))
+  return answer.none ? null : answer
+}
+
+// Readies, at once, the downloads assessNpm asks of each of these packages
+// (`names`) that can be, kept in `cache` as npmDownloads keeps them, so that
+// their assessments ask npm none: those kept within a week (DOWNLOADS_MS), as
+// they are, and unscoped ones, asked of npm BULK_DOWNLOADS at a time, as its downloads API
+// answers them; `ready` is told each once its downloads are kept. The rest,
+// scoped ones (it answers those only one by one) and any a bulk lookup
+// didn't answer, are left for npmReadyDownload, one at a time. npm asking to
+// be asked later is thrown (`upstream-busy`), as is any other failure, those
+// readied by then told.
+export async function npmReadyDownloads(names, ready, { cache, signal, now = Date.now() }) {
+  const context = { cache, signal, now }
+  const range = rangeAt(now)
+  const unique = [...new Set(names)]
+  const unscoped = []
+  const ask = async part => {
+    const json = await askNpm(`${DOWNLOADS}/${range}/${part.join(',')}`, {}, BULK_DOWNLOADS_BYTES, `${part.length} packages' downloads`, context)
+    const answered = part.filter(name => json && Object.hasOwn(json, name))
+    await keepMany(cache, answered.map(name => [name, downloadsOf(json[name], now)]))
+    for (const name of answered) ready(name)
+  }
+  // Those kept read BULK_DOWNLOADS at a time, the rest asked as they fill a
+  // lookup.
+  for (let at = 0; at < unique.length; at += BULK_DOWNLOADS) {
+    const part = unique.slice(at, at + BULK_DOWNLOADS)
+    const held = await keptMany(cache, part)
+    for (const name of part) {
+      if (freshDownloads(held.get(name), now)) ready(name)
+      else if (!name.startsWith('@')) unscoped.push(name)
+    }
+    while (unscoped.length >= BULK_DOWNLOADS) await ask(unscoped.splice(0, BULK_DOWNLOADS))
+  }
+  // A lookup of one is answered as that package's own, not by its name.
+  if (unscoped.length > 1) await ask(unscoped)
+}
+
+// Downloads kept under each of `keys`, by key, and many kept at once: in one
+// read and one write where the cache reads and writes many at once
+// (`readMany`, `writeMany`), else a key at a time.
+const keptMany = async (cache, keys) => cache.readMany ? await cache.readMany('risk/npm/downloads', keys)
+  : new Map(await Promise.all(keys.map(async key => [key, await cache.read('risk/npm/downloads', key)])))
+const keepMany = async (cache, entries) => {
+  if (cache.writeMany) await cache.writeMany('risk/npm/downloads', entries)
+  else for (const [key, value] of entries) await cache.write('risk/npm/downloads', key, value)
+}
+
+// Readies the downloads assessNpm asks of a package, asked of npm on their
+// own where they aren't kept (npmDownloads), as npmReadyDownloads leaves a
+// scoped one's: npm asking to be asked later thrown (`upstream-busy`).
+export async function npmReadyDownload(name, { cache, signal, now = Date.now() }) {
+  await npmDownloads(name, { cache, signal, now })
+}