@preventive/upstream 1.0.1 → 1.2.0

package/advisories.d.ts

@@ -50,23 +50,43 @@ export interface AdvisoryOptions {
   // and its rows take OSV's record of their GHSA, one more request each
   // (no GitHub client needed).
   details?: boolean
+  // Also asks OSV of each npm package's versions, as cargo and composer
+  // packages always are, for what the registry does not have: above all
+  // the malicious packages' records (MAL-...), which it has none of, as
+  // those of npm releases taken down that GitHub's database has no
+  // advisory of. A version a registry row reports under the same advisory,
+  // its id among an OSV record's id and aliases, is left to that row,
+  // which takes the record's ids among its aliases; the versions a record
+  // of the row's own id covers beyond the registry's range join it too.
+  // Sends each npm package's name and versions to OSV, so not for a
+  // private package.
+  osv?: boolean
 }
 
 // One advisory on one package, with the versions asked about that it
-// covers (never empty).
+// covers (never empty): one row an id, however many of its sources answer
+// it, or however often one does.
 export interface Advisory {
   ecosystem: Ecosystem
   name: string
-  // `registry`: npm's, as `npm audit` has it, one row per vulnerable
-  // range. `osv`: OSV's records for cargo and composer, RustSec's, GitHub's
-  // and malicious packages' (MAL-...) among them; of the records naming each
-  // other as aliases, directly or through others, a version is reported
-  // under one only: RustSec's, else the GHSA, else the first by id. Each
-  // has the others' ids among its aliases.
-  // `repository`: published on the package's repository, one row per
-  // range, holding only the versions the others' answer does not report
-  // under that GHSA. The only source for `soldeer` and `github`, where
-  // every range counts, whichever package it names.
+  // `registry`: npm's, as `npm audit` has it. `osv`: OSV's records for
+  // cargo and composer, and with `osv` for npm, the versions they cover
+  // that no registry row reports under the same advisory; RustSec's,
+  // GitHub's and malicious packages' (MAL-...) among them; of the records
+  // naming each other as aliases, directly or through others, a version is
+  // reported under one only: RustSec's, else the GHSA, else the first by
+  // id. Each has the others' ids among its aliases, and stays a row of its
+  // own, as its source rates it.
+  // `repository`: published on the package's repository, holding only the
+  // versions the others' answer does not report under that GHSA. The only
+  // source for `soldeer` and `github`, where every range counts, whichever
+  // package it names.
+  // An id answered more than once -- by npm's registry once a range, by
+  // OSV's record of it or its repository for versions beyond the registry's
+  // range, by its repository once a range -- is one row: the registry's,
+  // else OSV's, else the repository's, with what it lacks of theirs (title,
+  // details), the worst severity of them, the highest CVSS score with its
+  // own vector, and all their ranges, CWEs and versions.
   source: 'registry' | 'osv' | 'repository'
   // A GHSA, RUSTSEC-..., MAL-..., DRUPAL-CORE-... or another OSV id, or
   // npm:<id> for a registry row without a GHSA.
@@ -81,6 +101,8 @@ export interface Advisory {
   // (https://osv.dev/vulnerability/RUSTSEC-...). Built, never fetched: only
   // a registry row without a GHSA (npm:<id>) has none.
   url?: string
+  // The advisory's other ids: an `osv` row's record's own and its group's,
+  // and with `osv`, a registry row's OSV records' of it.
   aliases: string[]
   title?: string
   // With `details`, the advisory's full text, Markdown as published: an
@@ -96,11 +118,17 @@ export interface Advisory {
   cvssVector?: string
   cwe: string[]
   // As written: npm's syntax from the registry, GitHub's
-  // (`>= 1.0.0, < 1.2.6`) from a repository; OSV rows have none. A
+  // (`>= 1.0.0, < 1.2.6`) from a repository; OSV's records have none. A
   // repository range semver cannot read, or none, covers every version.
+  // Each range its id was answered with that covers an asked version,
+  // joined by ` || `; none ('') where one is none. A version only OSV
+  // reports may be outside it: hermes-engine's GHSA-f5x2-xv93-4p23 is
+  // `<=0.4.3` on npm, the last version known affected, and fixed in 0.5.2
+  // by OSV's record of it, which reports 0.5.0 too.
   range?: string
   // RustSec's kind for an advisory that is not a vulnerability as such:
-  // `unmaintained`, `unsound`, `notice`.
+  // `unmaintained`, `unsound`, `notice`. For an id answered more than once,
+  // only where each answer gives it.
   informational?: string
   versions: string[]
 }
@@ -110,14 +138,18 @@ export interface Advisory {
 // merged, and must not name two repositories. npm is asked 250 names a
 // request, OSV 1000 versions, Soldeer one project, and with `details`, OSV
 // one GHSA among npm's rows; a project Soldeer does not have or that names
-// no GitHub repository, and a repository gone, renamed or blocked, add
-// nothing, and a GHSA OSV does not have adds no `details`. Any other
-// failure, a malformed answer, or one about something not asked, throws:
-// nothing is left out quietly.
+// no GitHub repository, a repository gone or blocked, and one GitHub
+// redirects anywhere but to a repository by its id, add nothing, and a
+// GHSA OSV does not have adds no `details`. A repository renamed or
+// transferred, which GitHub redirects to it by its id, is listed by the
+// name it has now, as getRepo's `followRedirect` (github.js) finds it, its
+// rows' `url` on it. Any other failure, a malformed answer, or one about
+// something not asked, throws: nothing is left out quietly.
 // A repository's listing is kept for 90 minutes, as one entry for every
-// spelling of its name, holding only what rows are made from, `details`
-// included: in setCacheDir's cache gzipped, in a `cache` store as it is,
-// or with `cache` false, nowhere. 90 minutes is how late an advisory its
+// spelling of the name it is asked by, one renamed or transferred too,
+// holding only what rows are made from, `details` included: in
+// setCacheDir's cache gzipped, in a `cache` store as it is, or with
+// `cache` false, nowhere. 90 minutes is how late an advisory its
 // maintainer publishes can be seen. One gone or malformed is not kept.
 // Sorted by ecosystem and name. Versions are matched by npm's semver, from
 // the npm beside node, or by the semver peer where there is no npm.

package/github.d.ts

@@ -7,7 +7,7 @@
 // encoded segments and has to come back out of URL parsing unchanged.
 // Redirects are refused, so an answer is about the repo asked for, except
 // the tarballs' and, where asked, getRepo's for a repo renamed or
-// transferred. A response is read up to a size limit (64 MiB of JSON, 128
+// transferred. A response is read up to a size limit (128 MiB of JSON, 128
 // MiB of a file, 512 MiB of a tarball) and within a timeout (30 seconds, 5
 // minutes for a tarball), and what it says goes into an error message
 // escaped.

package/npm.d.ts

@@ -127,7 +127,11 @@ export interface Dist {
 // `bugs` an object, of which only the strings named below are read. Each is
 // absent where the document has none, or has another shape, or an object
 // with none of those strings. All of it is the publisher's word, held to no
-// repository.
+// repository. `unpackedSize` is the document's dist.unpackedSize: the bytes
+// of the files in the tarball, as the registry counted them when the
+// version was published, held to no tarball. It is absent where the
+// document has none, as for a version published before the registry
+// counted them, or has one that is not a whole number of bytes.
 export interface PackageMeta {
   name: string
   version: string
@@ -136,6 +140,7 @@ export interface PackageMeta {
   repository?: string | PackageRepository
   homepage?: string
   bugs?: string | PackageBugs
+  unpackedSize?: number
 }
 
 export interface PackageRepository {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.1",
-  "description": "Minimal npm, crates.io and Soldeer registry clients, a GitHub client, and a git checkout reader: the calls we use, nothing more",
+  "version": "1.2.0",
+  "description": "Minimal npm, crates.io, Soldeer, GitHub and git checkout clients",
   "type": "module",
   "exports": {
     "./advisories.js": {

package/src/advisories/github.js

@@ -1,9 +1,9 @@
 import assert from 'node:assert/strict'
 
-import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isStrings } from '../args.js'
+import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isRepo, isStrings } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
 import { isGone } from '../github/client.js'
-import { recover } from '../http.js'
+import { HttpError, recover } from '../http.js'
 import { pool } from '../pool.js'
 import { isExactVersion } from '../semver.js'
 import { advisoryUrl, covered, detailsOf, isText, mayBeInRange, metrics } from './common.js'
@@ -21,7 +21,7 @@ const isRepoAdvisory = (advisory) => advisory && typeof advisory === 'object' &&
   && advisory.state === 'published' && isText(advisory.summary)
   && (advisory.vulnerabilities == null || Array.isArray(advisory.vulnerabilities)) && (advisory.cwe_ids == null || isStrings(advisory.cwe_ids))
 
-export const assertClient = assertion('a GitHub client from createClient', (value) => typeof value?.listRepoAdvisories === 'function')
+export const assertClient = assertion('a GitHub client from createClient', (value) => typeof value?.listRepoAdvisories === 'function' && typeof value.getRepo === 'function')
 
 // A maintainer may give a vulnerable range only its lower bound, and the
 // version that fixed it apart (`>= 5.0.0-beta.1`, patched in `5.0.0-rc.2`),
@@ -67,18 +67,37 @@ const isDigest = (advisory) => advisory && typeof advisory === 'object' && isGhs
   && (advisory.description === undefined || isText(advisory.description))
   && Array.isArray(advisory.ranges) && advisory.ranges.every((entry) => typeof entry?.range === 'string')
 
-// A repository's listing, digested, through the cache: GitHub's names are
-// case-insensitive, so one entry answers every spelling. A repository gone,
-// renamed or blocked has none, and that is not kept.
+// GitHub answers for a repository renamed or transferred with a redirect,
+// which getRepo follows to the repository it is now, listed by that name.
+const isRedirect = (err) => err instanceof HttpError && err.status >= 300 && err.status < 400
+
+async function listingOf(github, repo) {
+  try {
+    return { repo, list: await github.listRepoAdvisories({ repo }) }
+  } catch (err) {
+    if (!isRedirect(err)) throw err
+  }
+  const moved = (await github.getRepo({ repo, followRedirect: true })).full_name
+  return { repo: moved, list: await github.listRepoAdvisories({ repo: moved }) }
+}
+
+// A repository's listing, digested, through the cache, and the repository
+// it is of: GitHub's names are case-insensitive, so one entry answers every
+// spelling, and one renamed or transferred is kept under the name asked,
+// with `repo` the one it has now. A repository gone or blocked, or
+// redirected anywhere getRepo does not follow, has none, and that is not
+// kept.
 async function listAdvisories(github, repo, cache) {
   const name = repo.toLowerCase()
   const entry = await readRecord(DIR, name, cache, LISTING_TTL_MS)
-  if (entry?.v === VERSION && Array.isArray(entry.advisories) && entry.advisories.every(isDigest)) return entry.advisories
-  const list = await github.listRepoAdvisories({ repo }).catch(recover(isGone, null))
-  if (list === null) return []
-  const advisories = digest(repo, list)
-  if (advisories.every(isDigest)) await writeRecord(DIR, name, { v: VERSION, advisories }, cache)
-  return advisories
+  if (entry?.v === VERSION && (entry.repo === undefined || isRepo(entry.repo)) && Array.isArray(entry.advisories) && entry.advisories.every(isDigest)) {
+    return { repo: entry.repo ?? repo, advisories: entry.advisories }
+  }
+  const found = await listingOf(github, repo).catch(recover((err) => isGone(err) || isRedirect(err), null))
+  if (found === null) return { repo, advisories: [] }
+  const advisories = digest(found.repo, found.list)
+  if (advisories.every(isDigest)) await writeRecord(DIR, name, { v: VERSION, ...(found.repo !== repo && { repo: found.repo }), advisories }, cache)
+  return { repo: found.repo, advisories }
 }
 
 // GitHub's `>= 1.0.0, < 1.2.6` is npm's with the commas dropped.
@@ -109,10 +128,10 @@ function fromRepository(repo, name, advisory, range, asked, { covers, details })
 async function repositoryAdvisories(github, asked, { repoOf, takes = () => true, covers, details, cache }) {
   // GitHub's names are case-insensitive: one spelling asks for all.
   const namesOf = Map.groupBy([...asked.keys()].filter(repoOf), (name) => repoOf(name).toLowerCase())
-  const listed = await pool([...namesOf.values()], REPOS_AT_ONCE, async (names) => ({ repo: repoOf(names[0]), names, list: await listAdvisories(github, repoOf(names[0]), cache) }))
+  const listed = await pool([...namesOf.values()], REPOS_AT_ONCE, async (names) => ({ names, ...(await listAdvisories(github, repoOf(names[0]), cache)) }))
   const rows = new Map()
-  for (const { repo, names, list } of listed) {
-    for (const advisory of list) {
+  for (const { repo, names, advisories } of listed) {
+    for (const advisory of advisories) {
       for (const { range, ...pkg } of advisory.ranges) {
         for (const name of names.filter((candidate) => takes(candidate, pkg))) {
           rows.set(`${name} ${advisory.ghsa} ${range}`, fromRepository(repo, name, advisory, range, asked.get(name), { covers, details }))

package/src/advisories/index.js

@@ -34,8 +34,59 @@ function collect(packages) {
   return byEcosystem
 }
 
+// Which of an advisory's rows stands for it: npm's registry's, then OSV's,
+// then its repository's.
+const SOURCES = ['registry', 'osv', 'repository']
+const SEVERITIES = ['critical', 'high', 'moderate', 'low', 'info']
+const worse = (a, b) => (b === undefined || (a !== undefined && SEVERITIES.indexOf(a) < SEVERITIES.indexOf(b)) ? a : b)
+
+// An advisory's rows as one: the first's by source, what it lacks from the
+// first of the rest that has it, the others' aliases, and of them all the
+// worst severity, the highest CVSS score with its own vector (else the first
+// vector), the ranges (` || `), CWEs and versions (in the order `asked` has
+// them). RustSec's kind of advisory that is not a vulnerability as such only
+// where each of them has that kind: a row without one is a vulnerability.
+function joinRows(rows, asked) {
+  const [head, ...rest] = rows.toSorted((a, b) => SOURCES.indexOf(a.source) - SOURCES.indexOf(b.source))
+  const all = [head, ...rest]
+  const ranges = [...new Set(all.map((row) => row.range).filter((range) => range !== undefined))]
+  const versions = new Set(all.flatMap((row) => row.versions))
+  const joined = {
+    ...head,
+    aliases: [...new Set(all.flatMap((row) => row.aliases))].filter((id) => id !== head.id),
+    cwe: [...new Set(all.flatMap((row) => row.cwe))],
+    versions: asked.filter((version) => versions.has(version)),
+  }
+  if (rest.some((row) => row.informational !== head.informational)) delete joined.informational
+  for (const key of ['title', 'details']) {
+    const from = joined[key] === undefined && rest.find((row) => row[key] !== undefined)
+    if (from) joined[key] = from[key]
+  }
+  const severity = all.map((row) => row.severity).reduce(worse)
+  if (severity !== undefined) joined.severity = severity
+  const scored = all.filter((row) => row.cvss !== undefined).toSorted((a, b) => b.cvss - a.cvss)[0] ?? all.find((row) => row.cvssVector !== undefined)
+  delete joined.cvss
+  delete joined.cvssVector
+  if (scored?.cvss !== undefined) joined.cvss = scored.cvss
+  if (scored?.cvssVector !== undefined) joined.cvssVector = scored.cvssVector
+  // A range of none ('') covers every version, as they then do together.
+  if (ranges.length > 0) joined.range = ranges.includes('') ? '' : ranges.join(' || ')
+  return joined
+}
+
+// One row for each advisory id on a package, where its sources answer more
+// than one: npm's registry one per range, and OSV's record of it, or its
+// repository, another for the versions they cover beyond that. Records of
+// other ids that name it as an alias stay rows of their own, each version
+// reported under one, as their sources rate them. Rows keep the place of the
+// first answered.
+function oneRowPerAdvisory(rows, asked) {
+  const byId = Map.groupBy(rows, (row) => `${row.name}\0${row.id}`)
+  return [...byId.values()].map((same) => (same.length === 1 ? same[0] : joinRows(same, asked.get(same[0].name))))
+}
+
 export async function advisories(packages, options = {}) {
-  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: optional(assertBoolean), cache: optional(assertCache) })
+  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean), details: optional(assertBoolean), osv: optional(assertBoolean), cache: optional(assertCache) })
   assert.ok(!options.repoAdvisories || options.github, 'advisories: repoAdvisories needs a github client')
   const byEcosystem = collect(packages)
   for (const ecosystem of byEcosystem.keys()) assert.ok(!ECOSYSTEMS[ecosystem].repositoryOnly || options.github, `advisories: ${ecosystem} packages need a github client`)
@@ -44,8 +95,8 @@ export async function advisories(packages, options = {}) {
     const names = [...named.keys()].toSorted()
     const asked = new Map(names.map((name) => [name, [...named.get(name).versions].toSorted(compare)]))
     const known = new Map(names.filter((name) => named.get(name).github).map((name) => [name, named.get(name).github]))
-    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, details: options.details === true, known, cache: options.cache })
-    return rows.map((row) => ({ ecosystem, ...row }))
+    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, details: options.details === true, osv: options.osv === true, known, cache: options.cache })
+    return oneRowPerAdvisory(rows.filter((row) => row.versions.length > 0), asked).map((row) => ({ ecosystem, ...row }))
   }))
-  return found.flat().filter((row) => row.versions.length > 0).toSorted((a, b) => order(a.ecosystem, b.ecosystem) || order(a.name, b.name))
+  return found.flat().toSorted((a, b) => order(a.ecosystem, b.ecosystem) || order(a.name, b.name))
 }

package/src/advisories/npm.js

@@ -6,7 +6,7 @@ import { chunks, pool } from '../pool.js'
 import { compareVersions } from '../semver.js'
 import { advisoryUrl, covered, detailsOf, isText, metrics } from './common.js'
 import { withRepositories } from './github.js'
-import { RECORDS_AT_ONCE, getVuln } from './osv.js'
+import { RECORDS_AT_ONCE, getVuln, osvRows } from './osv.js'
 import { npmRepos } from './repos.js'
 
 const BULK_URL = buildUrl(NPM_REGISTRY, ['-', 'npm', 'v1', 'security', 'advisories', 'bulk'])
@@ -52,21 +52,48 @@ async function registryAdvisories(asked) {
 
 // The registry's rows carry no text: each GHSA's is OSV's record of it,
 // GitHub's advisory database as published, asked once for the rows that
-// cover an asked version. One OSV does not have yet has none.
+// cover an asked version, but where `osv` already read it. One OSV does
+// not have yet has none.
 async function withDetails(rows) {
-  const ghsas = [...new Set(rows.filter((row) => row.ghsa && row.versions.length > 0).map((row) => row.ghsa))]
+  const asks = (row) => row.source === 'registry' && row.details === undefined
+  const ghsas = [...new Set(rows.filter((row) => asks(row) && row.ghsa && row.versions.length > 0).map((row) => row.ghsa))]
   const records = await pool(ghsas, RECORDS_AT_ONCE, (ghsa) => getVuln(ghsa).catch(recover(isNotFound, undefined)))
   const text = new Map(ghsas.map((ghsa, i) => [ghsa, records[i]?.details]))
-  return rows.map((row) => ({ ...row, ...detailsOf(text.get(row.ghsa), row.ghsa) }))
+  return rows.map((row) => (asks(row) ? { ...row, ...detailsOf(text.get(row.ghsa), row.ghsa) } : row))
 }
 
-// What `npm audit` asks the registry, one row per vulnerable range.
+// With `osv`, OSV's records of the asked versions besides the registry's
+// rows, the malicious packages' (MAL-...), which the registry has none
+// of, among them. A version a registry row reports under the same
+// advisory, the row's id one of an OSV row's ids or aliases, is left to
+// that row, which takes the OSV row's ids among its aliases, and its text
+// where it is the same record; an OSV row keeps the versions no such row
+// reports, which advisories() joins to a registry row of its own id.
+function withOsv(registry, osv) {
+  const rows = registry.map((row) => ({ ...row }))
+  const added = []
+  for (const record of osv) {
+    const ids = [record.id, ...record.aliases]
+    const same = rows.filter((row) => row.name === record.name && ids.includes(row.id) && row.versions.some((version) => record.versions.includes(version)))
+    for (const row of same) {
+      row.aliases = [...new Set([...row.aliases, ...ids])].filter((id) => id !== row.id)
+      if (record.id === row.id && record.details !== undefined) row.details = record.details
+    }
+    const versions = record.versions.filter((version) => !same.some((row) => row.versions.includes(version)))
+    if (versions.length > 0) added.push({ ...record, versions })
+  }
+  return [...rows, ...added]
+}
+
+// What `npm audit` asks the registry, one row per vulnerable range, and
+// with `osv`, what OSV has besides.
 export const NPM = {
   assertName: assertPackageName,
   assertVersion: assertPackageVersion,
   compare: compareVersions,
   advisories: async (asked, options) => {
-    const rows = await registryAdvisories(asked)
+    const [registry, osv] = await Promise.all([registryAdvisories(asked), options.osv ? osvRows({ osv: 'npm' }, asked, options) : []])
+    const rows = withOsv(registry, osv)
     return await withRepositories(options.details ? await withDetails(rows) : rows, asked, options, { ecosystem: 'npm', lookUp: npmRepos })
   },
 }

package/src/advisories/osv.js

@@ -84,9 +84,9 @@ function toAdvisory(ecosystem, name, versions, record, details) {
 // publishes comes back under each one's id, the records naming each other
 // as aliases, either way round, directly or through others: one group, in
 // which each version is reported under the first answered for it, and
-// each record has the others' ids as aliases.
-async function osvAdvisories(ecosystem, asked, options) {
-  const { osv, github, lookUp, covers } = ecosystem
+// each record has the others' ids as aliases. `osv` is OSV's name for the
+// ecosystem.
+export async function osvRows({ osv }, asked, { details }) {
   const list = [...asked].flatMap(([name, versions]) => versions.map((version) => ({ name, version })))
   const hits = new Map() // id -> name -> versions, in `list` order
   for (const chunk of chunks(list, QUERIES_PER_REQUEST)) {
@@ -118,9 +118,14 @@ async function osvAdvisories(ecosystem, asked, options) {
     const aliases = [...new Set([...record.aliases, ...group.map((other) => other.id)])].filter((id) => id !== record.id)
     for (const [name, versions] of hits.get(record.id)) {
       const rest = [...versions].filter((version) => !above.some((other) => hits.get(other.id).get(name)?.has(version)))
-      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, { ...record, aliases }, options.details))
+      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, { ...record, aliases }, details))
     }
   }
   rows.sort((a, b) => order(a.name, b.name) || order(a.id, b.id))
-  return await withRepositories(rows, asked, options, { ecosystem: github, lookUp, covers })
+  return rows
+}
+
+async function osvAdvisories(ecosystem, asked, options) {
+  const { github, lookUp, covers } = ecosystem
+  return await withRepositories(await osvRows(ecosystem, asked, options), asked, options, { ecosystem: github, lookUp, covers })
 }

package/src/http.js

@@ -26,7 +26,7 @@ const isQuery = ([key, value]) => isQueryKey(key) && (key.endsWith('[]') ? Array
 // A line break in a value would start a header of its own.
 const isHeader = ([name, value]) => /^[A-Za-z][\w-]*$/u.test(name) && matches(/^[ -~]*$/u)(value)
 const LIMITS = {
-  json: { bytes: 64 * 1024 * 1024, ms: 30_000 },
+  json: { bytes: 128 * 1024 * 1024, ms: 30_000 },
   text: { bytes: 128 * 1024 * 1024, ms: 30_000 },
   bytes: { bytes: MAX_BYTES, ms: 300_000 },
 }

package/src/npm/tarball.js

@@ -73,24 +73,28 @@ async function npmCachedVersion(name, version, given) {
   return undefined
 }
 
+const countOr = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : undefined)
+
 // The version's document: with the `dist` the caller has, npm's own cache's
 // where it matches (npmCachedVersion), and neither `cache` nor the cache
 // set is read or written; else as getVersion has it. Beside its dist, the
 // document's gitHead where that is a full commit id, and its repository,
-// homepage and bugs, in the shapes a package.json gives them. Each but
-// dist is left out where there is none.
+// homepage and bugs, in the shapes a package.json gives them; and its
+// dist's unpackedSize where that is a count. Each but dist is left out
+// where there is none.
 export async function getMeta(name, version, options = {}) {
   assertPackage('getMeta', name, version)
   assertArgs('getMeta', options, { dist: null, cache: optional(assertCache) })
   const given = options.dist === undefined ? undefined : checkedDist('getMeta', name, version, options.dist)
   const { dist, json } = (given && await npmCachedVersion(name, version, given)) ?? await getVersion('getMeta', name, version, given, options.cache)
-  const about = {
+  const said = {
     gitHead: isSha(own(json, 'gitHead')) ? json.gitHead : undefined,
     repository: linkOf(own(json, 'repository'), ['type', 'url', 'directory']),
     homepage: stringOr(own(json, 'homepage')),
     bugs: linkOf(own(json, 'bugs'), ['url', 'email']),
+    unpackedSize: countOr(own(json.dist, 'unpackedSize')),
   }
-  return { name, version, dist, ...Object.fromEntries(Object.entries(about).filter(([, value]) => value !== undefined)) }
+  return { name, version, dist, ...Object.fromEntries(Object.entries(said).filter(([, value]) => value !== undefined)) }
 }
 
 // Only the whole package's document has `time`: megabytes for some.