@preventive/triage 1.0.0-alpha.42 → 1.0.0-alpha.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.42",
+  "version": "1.0.0-alpha.43",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT OR Apache-2.0",
   "author": {
@@ -152,6 +152,7 @@
     "server-managed/rename-diff.ts",
     "server-managed/rename-diff-worker.js",
     "server-managed/public-workspace.ts",
+    "server-managed/queue.ts",
     "server-managed/repo-path.ts",
     "server-managed/report-migration.ts",
     "server-managed/report-query.ts",
@@ -164,6 +165,9 @@
     "server-managed/repository-discovery.ts",
     "server-managed/repository-policy.ts",
     "server-managed/repository-risk.ts",
+    "server-managed/repository-risk-assess.ts",
+    "server-managed/repository-risk-audit.ts",
+    "server-managed/scan-downloads.ts",
     "server-managed/session.ts",
     "server-managed/slugs.ts",
     "server-managed/solidity-entry-points.ts",
@@ -255,6 +259,8 @@
     "common/revalidation-input-groups.js",
     "common/server-info.ts",
     "common/scan-server.ts",
+    "common/security-links.d.ts",
+    "common/security-links.js",
     "common/utf8.d.ts",
     "common/utf8.js",
     "common/workspace-app.js",
@@ -346,9 +352,9 @@
   "dependencies": {
     "@exodus/stasis": "1.0.0-beta.9",
     "@exodus/stasis-core": "1.0.0-beta.9",
-    "@preventive/compare": "^1.2.3",
+    "@preventive/compare": "^1.2.8",
     "@preventive/diff": "^1.0.2",
-    "@preventive/lockfile": "1.0.0",
+    "@preventive/lockfile": "1.1.0",
     "@preventive/publishers": "^1.1.0",
     "@preventive/report": "1.0.0-alpha.9",
     "@preventive/sourcemap": "1.0.0-alpha.1",

package/risk/index.d.ts

@@ -114,6 +114,13 @@ export interface DependencyRisk {
   uncounted?: true
   created?: string
   gap?: number
+  // For one nothing imports, the version its spec installs (registry.js
+  // npmPublicFacts): its package's latest beside it, when it was published,
+  // whether it has install scripts, and whether that was since the version
+  // compared with (`new`).
+  installs?: { version: string; latest: string | null; published: string | null; scripts: boolean; new: boolean }
+  // Where its package was looked up and npm has none of it for anyone.
+  missing?: true
 }
 
 // A version's risk as one number (risk/npm/score.js): what its findings call
@@ -147,6 +154,25 @@ export interface NpmAssessment {
 
 export function assessNpm(name: string, version: string, options?: AssessNpmOptions): Promise<NpmAssessment>
 
+// Readies, at once, the downloads assessNpm asks of each of these packages
+// that can be, kept in `cache` as it keeps them, so that their assessments
+// ask npm none: those kept within a week, and unscoped ones, asked of npm 128
+// at a time. `ready` is told each once its downloads are kept; the rest (scoped
+// ones, which npm answers only one by one) are left for npmReadyDownload.
+// npm asking to be asked later is thrown as an NpmRiskError
+// (`upstream-busy`), those readied by then told.
+// A cache that reads and writes many at once too (`readMany`, `writeMany`)
+// is read once and written once a lookup.
+export function npmReadyDownloads(names: string[], ready: (name: string) => void, options: { cache: CacheStore & {
+  readMany?(type: string, keys: string[]): Promise<Map<string, unknown>>
+  writeMany?(type: string, entries: [key: string, value: unknown][]): Promise<void>
+}; signal?: AbortSignal; now?: number }): Promise<void>
+
+// Readies the downloads assessNpm asks of a package, asked of npm on their
+// own where they aren't kept; npm asking to be asked later thrown as an
+// NpmRiskError (`upstream-busy`).
+export function npmReadyDownload(name: string, options: { cache: CacheStore; signal?: AbortSignal; now?: number }): Promise<void>
+
 // Whether an advisory is of malware rather than a vulnerability: OSV's of a
 // malicious package (`MAL-…`), or one such a record names (its `aliases`),
 // CWE-506, embedded malicious code, whatever its title, or a title naming

package/risk/index.js

@@ -3,5 +3,5 @@
 export { assessNpm } from './npm/assess.js'
 export { npmMalwareAdvisory } from './npm/malware.js'
 export { DEFAULT_MINIMUM_RELEASE_AGE } from './npm/release.js'
-export { NpmRiskError } from './npm/registry.js'
+export { NpmRiskError, npmReadyDownload, npmReadyDownloads } from './npm/registry.js'
 export { SEVERITIES, npmFileRisk } from './files/stamps.js'

package/risk/npm/assess.js

@@ -12,13 +12,14 @@ import { NpmRiskError, npmDownloads, npmPackageFacts, npmPackageReleases, npmPub
 import { npmMalwareFinding } from './malware.js'
 import { npmKnownScope } from './manifest.js'
 import { DEFAULT_MINIMUM_RELEASE_AGE, npmAccountStanding } from './release.js'
-import { npmAddedDependency } from './new-dependency.js'
+import { npmAddedDependency, npmUnusedDependencySeverity } from './new-dependency.js'
+import { SEVERITIES } from '../files/stamps.js'
 import { npmRiskScore } from './score.js'
 
 // Which reading of a version an assessment kept (`risk/npm/assessments`) is:
 // one more whenever a heuristic changes what it finds, so one kept by an
 // older reading is read anew.
-const RISK_VERSION = 16
+const RISK_VERSION = 17
 
 // How long an assessment kept may be as JSON, and what risk reads of either
 // version's files: a package past it, whose files name thousands of hosts or
@@ -123,26 +124,32 @@ const MAX_TOLD_DEPENDENCIES = 100
 // with what risk tells of its package
 // (new-dependency.js npmAddedDependency): its tier, its last whole month's
 // downloads by what its tier goes by where it has one (`month`, `{ total,
-// from }`), `uncounted` where npm counts none of them, and `created` and `gap`
+// from }`), `uncounted` where npm counts none of them, `created` and `gap`
 // where it is new since the version compared with (`published`, when that
-// and the open version were); four asked at a time, whether each is the
+// and the open version were), and for one nothing imports (flagged so, or
+// among `unusedKeys`), the version its spec installs (`installs`,
+// registry.js npmPublicFacts); `missing` where
+// its package was looked up and npm has none of it for anyone, as once
+// unpublished or taken down; four asked at a time, whether each is the
 // caller's own among them, none more once one fails or MAX_TOLD_DEPENDENCIES
 // not the caller's own were taken, however many a version adds.
-async function addedDependencies(added, published, context, owned) {
+async function addedDependencies(added, published, context, owned, unusedKeys = new Set()) {
   const told = [...added]
   const asked = told.flatMap((row, at) => row.opens ? [at] : [])
   let next = 0, taken = 0
   const tell = async row => {
     const downloads = await npmDownloads(row.opens, context)
-    let facts = npmAddedDependency({ downloads, published }, context.now)
+    const unused = row.flags.some(flag => flag.check === 'unimported') || unusedKeys.has(keyOf(row))
+    let facts = npmAddedDependency({ downloads, published, unused }, context.now), missing = false
     if (facts.wanted) {
-      const listed = await npmPublicFacts(row.opens, context)
-      facts = npmAddedDependency({ downloads, listed: listed && { ...listed, private: false }, published }, context.now)
+      const listed = await npmPublicFacts(row.opens, context, unused ? row.range : null)
+      missing = listed === null
+      facts = npmAddedDependency({ downloads, listed: listed && { ...listed, private: false }, published, unused }, context.now)
     }
     const settled = npmSettledDownloads(downloads, context.now)
     const month = npmDownloadMonths(settled).at(-1)
     return { ...row, ...facts.tier === null ? {} : { ...tierOf(facts.tier), ...settled ? month && { month: { total: month.total, from: month.from.toISOString().slice(0, 10) } } : { uncounted: true } },
-      ...facts.created ? { created: facts.created, gap: facts.gap } : {} }
+      ...facts.created ? { created: facts.created, gap: facts.gap } : {}, ...facts.installs ? { installs: facts.installs } : {}, ...missing ? { missing } : {} }
   }
   await Promise.all(Array.from({ length: 4 }, async () => {
     while (next < asked.length && taken < MAX_TOLD_DEPENDENCIES) {
@@ -201,21 +208,60 @@ export async function assessNpm(name, version, { oldVersion = null, fromEmpty =
   const own = npmVersionFindings({ deprecated: facts.deprecated[version], published, minimumReleaseAge, now, known: Boolean(manifest.knownAccounts), scope: npmKnownScope(name),
     provenance: Boolean(manifest.provenance), downloads: counted })
   const was = old === null ? null : facts.versions.get(old).published
-  const added = downloads && dependencies ? await addedDependencies(kept.dependencies.added, [was, published], context, owned) : kept.dependencies.added
-  const assessment = npmAssessmentOf(kept, malware ? [malware, ...own] : own, added)
+  // Those it holds that nothing imports by another spec than the version
+  // compared with's, told by their new spec as an added one nothing imports
+  // is (`respecified`), and an added one nothing imports however it was
+  // flagged, as one moved from another kind of dependency is.
+  const unusedKeys = unusedKeysOf(kept)
+  const respecified = kept.dependencies.changed.filter(row => unusedKeys.has(keyOf(row))).map(row => ({ ...row, range: row.to }))
+  const told = downloads && dependencies ? await addedDependencies([...kept.dependencies.added, ...respecified], [was, published], context, owned, unusedKeys)
+    : [...kept.dependencies.added, ...respecified]
+  const added = told.slice(0, kept.dependencies.added.length)
+  const assessment = npmAssessmentOf(kept, malware ? [malware, ...own] : own, added, told.slice(added.length))
   return { name, version, oldVersion: old, published, ...assessment, score: npmRiskScore(assessment.findings, { published, now, tier: counted ? npmDownloadTier(counted) : null }) }
 }
 
+// A dependency's key among a version's, by its kind and name.
+const keyOf = row => `${row.kind ?? ''}\0${row.name}`
+
+// The keys of the dependencies a version holds that nothing of it imports
+// (`kept`, npmLastingRisk's: its `held-unused-deps`).
+const unusedKeysOf = kept => new Set((kept.findings.find(({ id }) => id === 'held-unused-deps')?.dependencies ?? []).map(keyOf))
+
+// The dependencies nothing of a version imports (`held-unused-deps`), each
+// graded by what risk tells of its package fresh (`told`, as
+// addedDependencies tells it; new-dependency.js
+// npmUnusedDependencySeverity), with its tier, when its package was first
+// published and the version its spec installs where told: kept from the
+// version compared with where there was one (`compared`) and it named it as
+// the same kind of dependency by the same spec: not one marked new, nor
+// `added` (its kind and name new, as one moved from another kind is), nor
+// `changed` (each said with the spec it had, `was`). The finding as its most severe.
+function unusedGraded(finding, told, compared, { added, changed }) {
+  const facts = new Map(told.map(row => [keyOf(row), row])), was = new Map(changed.map(row => [keyOf(row), row.from]))
+  const anew = new Set(added.map(keyOf))
+  const dependencies = finding.dependencies.map(row => {
+    const of = facts.get(keyOf(row))
+    return { ...row, ...was.has(keyOf(row)) ? { was: was.get(keyOf(row)) } : {}, severity: npmUnusedDependencySeverity(of, compared && !row.added && !anew.has(keyOf(row)) && !was.has(keyOf(row))),
+      ...of?.level ? { tier: of.tier, level: of.level } : {}, ...of?.created ? { created: of.created, gap: of.gap } : {}, ...of?.installs ? { installs: of.installs } : {},
+      ...of?.missing ? { missing: true } : {} }
+  })
+  return { ...finding, severity: SEVERITIES[Math.min(...dependencies.map(row => SEVERITIES.indexOf(row.severity)))], dependencies }
+}
+
 // An assessment of what of it holds whatever the time (`kept`,
 // npmLastingRisk's) and what is told fresh: the open version's own findings
 // (`own`, held.js npmVersionFindings, and its malware), its malware and
 // deprecation first and the rest last, its tier as JSON holds it (tierOf),
-// and its dependencies `added`, as addedDependencies tells them. The managed
+// and its dependencies `added`, as addedDependencies tells them, those it
+// holds by another spec that nothing imports beside them (`respecified`),
+// for its unused dependencies' grades. The managed
 // server's (assessNpm), and a test's of versions it holds.
 const FIRST = new Set(['malware', 'deprecated'])
-export function npmAssessmentOf(kept, own, added = kept.dependencies.added) {
+export function npmAssessmentOf(kept, own, added = kept.dependencies.added, respecified = []) {
   return {
-    findings: [...own.filter(({ id }) => FIRST.has(id)), ...kept.findings,
+    findings: [...own.filter(({ id }) => FIRST.has(id)), ...kept.findings.map(finding => finding.id === 'held-unused-deps'
+      ? unusedGraded(finding, [...added, ...respecified], Boolean(kept.dependencies.held), kept.dependencies) : finding),
       ...own.filter(({ id }) => !FIRST.has(id)).map(finding => finding.id === 'popularity' ? { ...finding, ...tierOf(finding.tier) } : finding)],
     files: kept.files,
     dependencies: { ...kept.dependencies, added },

package/risk/npm/dependencies.js

@@ -108,10 +108,18 @@ const typesStubOf = ({ json, npm }, name, spec) => npm?.name === typesOf(name) &
 // (importsOf); never where its files aren't read. Not a peer dependency,
 // which the package expects whoever installs it to provide, nor types from
 // DefinitelyTyped (`@types/`), imported by another name, where no one else
-// publishes; nor the package a stub of DefinitelyTyped's types of it
-// depends on (typesStubOf), with no code to import it.
+// publishes; nor tslib, TypeScript's helpers, which a package compiled
+// with them inlined names all the same, as a third of popular packages
+// naming a dependency nothing imports do; each where npm installs that
+// package from its registry (installsAs), not another under its name
+// (`"tslib": "npm:other@1"`, a repository); nor the package a stub of
+// DefinitelyTyped's types of it depends on (typesStubOf), with no code to
+// import it.
+const installsAs = (name, spec) => npmRegistrySpec(spec) ? npmAlias(spec)?.name ?? name : null
 export function npmDependencyUnimported(details, { name, kind, range, to }) {
-  if (!details?.json || kind === 'peer' || name.startsWith('@types/') || typesStubOf(details, name, to ?? range)) return false
+  const installs = installsAs(name, to ?? range)
+  if (!details?.json || kind === 'peer' || (name.startsWith('@types/') && installs?.startsWith('@types/')) || (name === 'tslib' && installs === 'tslib')
+    || typesStubOf(details, name, to ?? range)) return false
   const { whole, parts, commands } = importsOf(details)
   return !whole.has(name) && ![...name.slice(1).matchAll(/[-/]/gu)].some(({ index }) => parts.has(name.slice(0, index + 2)))
     && !commands.some(command => commandNames(command, name))

package/risk/npm/new-dependency.js

@@ -10,21 +10,51 @@ 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 }`, when its
-// first version was published and whether only a token reads it; and
-// `published`, when the version compared with and the open one were. 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), and `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).
-export function npmAddedDependency({ downloads, listed = null, published = [] }, now = Date.now()) {
+// `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 || (counted !== null && npmTierLow(counted))
+  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
-  return { tier, wanted, created, gap: created ? Date.parse(open) - Date.parse(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/registry.js

@@ -33,7 +33,9 @@
 // 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'
@@ -50,6 +52,14 @@ const ADVISORIES_MS = 60 * 60_000
 // 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
@@ -59,6 +69,9 @@ export class NpmRiskError extends Error {
 }
 
 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
@@ -245,13 +258,42 @@ export async function npmVersionFiles(name, version, { manifest, published, dist
   }
 }
 
+// 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.
-export async function npmPublicFacts(name, context) {
-  const facts = await kept(context, 'risk/npm/public', name,
-    async () => { const doc = await packageDocument(name, context, false); return doc ? { at: context.now, created: firstPublished(doc) } : { at: context.now, missing: true } },
-    hit => context.now - hit.at < PACKAGE_MS)
-  return facts.missing ? null : { created: facts.created }
+// 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
@@ -262,21 +304,80 @@ function rangeAt(now) {
   return `${day(Date.UTC(today.getUTCFullYear(), today.getUTCMonth() - 2, 1))}:${day(now - DAY_MS)}`
 }
 
-// A package's downloads a day over rangeAt's days, `{ start, end, days }`,
-// null where npm counts none.
+// 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 range = rangeAt(context.now)
-  const answer = await kept(context, 'risk/npm/downloads', `${name}@${range}`, async () => {
-    const json = await askNpm(`${DOWNLOADS}/${range}/${encoded(name)}`, {}, DOWNLOADS_BYTES, `${name}'s downloads`, context)
-    if (json === null) return { 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 { start: json.start, end: json.end, days }
-  })
+  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 })
+}