@preventive/upstream 1.0.0-alpha.9 → 1.0.0

package/src/cache.js

@@ -3,12 +3,22 @@ import { constants } from 'node:fs'
 import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { gunzip, gzip } from 'node:zlib'
 
-import { assertCacheName, assertDirectoryPath, isRepo } from './args.js'
+import { assertCacheName, assertDirectoryPath, assertion, isRepo } from './args.js'
 import { MAX_BYTES, decode } from './http.js'
+import { pool } from './pool.js'
 
-const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'npm/versions', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees', 'github/advisories'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
+const RECORDS_AT_ONCE = 8
+// JSON filed gzipped, as `<name>.json.gz`: a listing carries each
+// advisory's full text, Markdown that compresses well, and a version
+// document all npm has of that version.
+const GZIP_DIRS = new Set(['github/advisories', 'npm/versions'])
+const compress = promisify(gzip)
+const decompress = promisify(gunzip)
 
 // An environment variable may hold anything: only an absolute path is one.
 const absolute = (path) => (typeof path === 'string' && isAbsolute(path) ? path : undefined)
@@ -95,10 +105,12 @@ export async function readCache(dir, key) {
   return path && await readRegularFile(path)
 }
 
-export async function readCacheJSON(dir, key) {
+// With `compressed`, the file is decompressed first, to no more than a file
+// read; one that is not gzip, fails its CRC, or runs past that, is a miss.
+export async function readCacheJSON(dir, key, { compressed = false } = {}) {
   const bytes = await readCache(dir, key)
   try {
-    return bytes && JSON.parse(decode(bytes, key))
+    return bytes && JSON.parse(decode(compressed ? await decompress(bytes, { maxOutputLength: MAX_BYTES }) : bytes, key))
   } catch {
     return null
   }
@@ -119,33 +131,74 @@ export async function writeCache(dir, key, data) {
   }
 }
 
-export async function writeCacheJSON(dir, key, value) {
-  return await writeCache(dir, key, JSON.stringify(value))
+export async function writeCacheJSON(dir, key, value, { compressed = false } = {}) {
+  const json = JSON.stringify(value)
+  return await writeCache(dir, key, compressed ? await compress(json) : json)
 }
 
-export async function readRecord(dir, name) {
-  const record = await readCacheJSON(dir, `${name}.json`)
+// A call's `cache` option: a store of the caller's, with read and write,
+// to keep what the call caches in place of the cache set; or false, for
+// the cache set to be read and nothing written. `cache` below is that.
+export const assertCache = assertion('false, or a store with read and write', (value) => value === false || (typeof value?.read === 'function' && typeof value?.write === 'function'))
+
+// What is kept as `dir` and `name`: in a `cache` store, else in the cache
+// set, as `fromDisk` and `toDisk` read and write it.
+async function read(dir, name, cache, fromDisk) {
+  assert.ok(DIRS.has(dir), `Unexpected cache entry: ${dir}`)
+  return cache ? await cache.read(dir, name) : await fromDisk()
+}
+
+async function write(dir, name, value, cache, toDisk) {
+  assert.ok(DIRS.has(dir), `Unexpected cache entry: ${dir}`)
+  if (cache === false) return false
+  if (!cache) return await toDisk()
+  await cache.write(dir, name, value)
+  return true
+}
+
+// JSON, as it is in a store, and in the cache set gzipped where `dir` is.
+const jsonFile = (dir, name) => (GZIP_DIRS.has(dir) ? { file: `${name}.json.gz`, compressed: true } : { file: `${name}.json` })
+
+export function readJSON(dir, name, cache) {
+  const { file, compressed } = jsonFile(dir, name)
+  return read(dir, name, cache, () => readCacheJSON(dir, file, { compressed }))
+}
+
+export function writeJSON(dir, name, value, cache) {
+  const { file, compressed } = jsonFile(dir, name)
+  return write(dir, name, value, cache, () => writeCacheJSON(dir, file, value, { compressed }))
+}
+
+// Bytes, in the cache set as `file`. A store may keep what it is given and
+// answer what it keeps, so bytes cross it as a copy each way; what it
+// answers that is not bytes is none.
+export async function readBytes(dir, name, file, cache) {
+  const bytes = await read(dir, name, cache, () => readCache(dir, file))
+  if (!(bytes instanceof Uint8Array)) return null
+  return cache ? new Uint8Array(bytes) : bytes
+}
+
+export const writeBytes = (dir, name, file, bytes, cache) => write(dir, name, cache ? new Uint8Array(bytes) : bytes, cache, () => writeCache(dir, file, bytes))
+
+// A record, kept as readJSON and writeJSON keep it, for `ttl`.
+export async function readRecord(dir, name, cache, ttl = RECORD_TTL_MS) {
+  const record = await readJSON(dir, name, cache)
   const age = typeof record?.at === 'number' ? Date.now() - record.at : Number.NaN
-  const fresh = age >= 0 && age <= RECORD_TTL_MS // An entry from the future is not fresh forever.
+  const fresh = age >= 0 && age <= ttl // An entry from the future is not fresh forever.
   return fresh && record.name === name ? record : null
 }
 
-export const writeRecord = (dir, name, value) => writeCacheJSON(dir, `${name}.json`, { at: Date.now(), name, ...value })
+export const writeRecord = (dir, name, value, cache) => writeJSON(dir, name, { at: Date.now(), name, ...value }, cache)
 
-// Name → the GitHub repo cached for it, for those of `names` that have one.
-export async function readRepos(dir, names) {
-  const repos = new Map()
-  for (const name of names) {
-    const entry = await readRecord(dir, name)
-    if (isRepo(entry?.github)) repos.set(name, entry.github)
-  }
-  return repos
+// Name -> the GitHub repo kept for it (readRecord), for those of `names`
+// that have one.
+export async function readRepos(dir, names, cache) {
+  const entries = await pool(names, RECORDS_AT_ONCE, (name) => readRecord(dir, name, cache))
+  return new Map(names.flatMap((name, i) => (isRepo(entries[i]?.github) ? [[name, entries[i].github]] : [])))
 }
 
-// An answer into `repos`, and into the cache where it found a repo.
-export async function addRepos(dir, repos, answer) {
-  for (const [name, github] of answer) {
-    repos.set(name, github)
-    if (github) await writeRecord(dir, name, { github })
-  }
+// An answer into `repos`, and kept (writeRecord) where it found a repo.
+export async function addRepos(dir, repos, answer, cache) {
+  for (const [name, github] of answer) repos.set(name, github)
+  await pool([...answer].filter(([, github]) => github), RECORDS_AT_ONCE, ([name, github]) => writeRecord(dir, name, { github }, cache))
 }

package/src/cargo/repos.js

@@ -12,7 +12,7 @@ const PER_REQUEST = 100
 const PACE_MS = 1000 // crates.io asks for a request a second at most, and a user agent.
 const USER_AGENT = '@preventive/upstream (https://github.com/PreventiveMeasures/libraries)'
 
-// One request for up to a hundred crates: each name → the GitHub repo its
+// One request for up to a hundred crates: each name -> the GitHub repo its
 // `repository` names, or null where it names none. A crate crates.io
 // leaves out of its answer is one it does not have, null too.
 async function askCrates(method, names) {
@@ -27,12 +27,12 @@ async function askCrates(method, names) {
   return found
 }
 
-// Name → its GitHub repo, or null where crates.io has no such crate or it
-// names no GitHub repo, through the cache: only a repo found is cached,
-// for a month. A failed request throws, or with `soft` leaves its names
-// out; `cachedOnly` asks nothing.
-export async function lookUpCrateRepos(method, names, { soft = false, cachedOnly = false } = {}) {
-  const repos = await readRepos(DIR, names)
+// Name -> its GitHub repo, or null where crates.io has no such crate or it
+// names no GitHub repo, through the cache, or a `cache` store (readRecord):
+// only a repo found is kept, for a month. A failed request throws, or with
+// `soft` leaves its names out; `cachedOnly` asks nothing.
+export async function lookUpCrateRepos(method, names, { soft = false, cachedOnly = false, cache } = {}) {
+  const repos = await readRepos(DIR, names, cache)
   if (cachedOnly) return repos
   for (const [i, chunk] of chunks(names.filter((name) => !repos.has(name)), PER_REQUEST).entries()) {
     if (i > 0) await sleep(PACE_MS)
@@ -40,7 +40,7 @@ export async function lookUpCrateRepos(method, names, { soft = false, cachedOnly
       if (soft) return new Map()
       throw error
     })
-    await addRepos(DIR, repos, answer)
+    await addRepos(DIR, repos, answer, cache)
   }
   return repos
 }

package/src/download.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { createHash } from 'node:crypto'
 
-import { ourCachePaths, readCache, readRegularFile, writeCache } from './cache.js'
+import { ourCachePaths, readBytes, readRegularFile, writeBytes } from './cache.js'
 import { request } from './http.js'
 import { gitTreeOfTarball } from './tree.js'
 
@@ -18,9 +18,10 @@ const DIGESTS = {
 // caller gives, never a disk; without it nothing is read. From `local`,
 // other tools' caches, and with `ours` our default cache and stasis's,
 // whether set or not (read, never written; a mismatch is passed over),
-// else the cache set (a mismatch throws), else what `locate` answers,
-// checked and then cached.
-export async function verifiedDownload({ method, dir, what, ext, algorithm, expected, local = [], ours = false, locate, options = {}, list }) {
+// else the cache set, or a `cache` store in its place (readBytes; a
+// mismatch throws), else what `locate` answers, checked and then kept as
+// writeBytes keeps it.
+export async function verifiedDownload({ method, dir, what, ext, algorithm, expected, local = [], ours = false, cache, locate, options = {}, list }) {
   assert.ok(Object.hasOwn(DIGESTS, algorithm) && typeof expected === 'string' && expected !== '', `${method}: nothing to check ${what} against`)
   const digest = (bytes) => DIGESTS[algorithm](bytes, { expected, list })
   const key = `${what}.${ext}`
@@ -33,10 +34,10 @@ export async function verifiedDownload({ method, dir, what, ext, algorithm, expe
     assert.ok(actual === expected, `${method}: integrity mismatch for ${what} from ${from}: expected ${expected}, got ${actual}`)
     return bytes
   }
-  const cached = await readCache(dir, key)
-  if (cached) return await check(cached, 'the cache')
+  const cached = await readBytes(dir, what, key, cache)
+  if (cached) return await check(cached, cache ? 'the store' : 'the cache')
   const url = await locate()
   const bytes = await check(await request(url, { ...options, as: 'bytes' }), url)
-  await writeCache(dir, key, bytes)
+  await writeBytes(dir, what, key, bytes, cache)
   return bytes
 }

package/src/git.js

@@ -54,5 +54,5 @@ export async function findGitCheckout(dir) {
   const directory = relative(dirs.root, start).split(sep).join('/')
   const github = await originGitHub(dirs.commonDir)
   const commit = await headCommit(dirs.gitDir, dirs.commonDir)
-  return { ...(github && { github }), ...(directory && { directory }), ...(github && { url: `https://github.com/${github}` }), ...(commit && { commit }) }
+  return { ...(github && { github }), directory, ...(github && { url: `https://github.com/${github}` }), ...(commit && { commit }) }
 }

package/src/npm/cacache.js

@@ -0,0 +1,44 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+
+import { readRegularFile } from '../cache.js'
+
+// npm's cache, cacache as npm 5 and later keep it: a response by the URL
+// it answered, under the key `make-fetch-happen:request-cache:<url>`. The
+// index has a file for each key's sha256, of lines `<sha1>\t<entry>`, each
+// entry's sha1 of its own JSON: the last whole one for the key counts, and
+// one with no integrity is one deleted. The content is filed by its
+// sha512, and checked against it.
+const KEY = 'make-fetch-happen:request-cache:'
+const digest = (algorithm, data, encoding) => createHash(algorithm).update(data).digest(encoding)
+const shard = (hex) => [hex.slice(0, 2), hex.slice(2, 4), hex.slice(4)]
+const decoder = new TextDecoder('utf-8')
+
+async function lastEntry(root, key) {
+  const bytes = await readRegularFile(join(root, 'index-v5', ...shard(digest('sha256', key, 'hex'))))
+  let entry = null
+  for (const line of bytes ? decoder.decode(bytes).split('\n') : []) {
+    const tab = line.indexOf('\t')
+    const json = line.slice(tab + 1)
+    if (tab < 0 || digest('sha1', json, 'hex') !== line.slice(0, tab)) continue
+    try {
+      const parsed = JSON.parse(json)
+      if (parsed?.key === key) entry = parsed
+    } catch {
+      // A line cut short, or written over: passed over, as npm passes it.
+    }
+  }
+  return entry
+}
+
+// The body npm keeps for `url`, beside what it kept of the response, or
+// null: none kept, one deleted, or content gone or not its sha512.
+export async function readNpmCached(root, url) {
+  const entry = await lastEntry(root, `${KEY}${url}`)
+  const integrity = typeof entry?.integrity === 'string' ? entry.integrity : ''
+  const sha512 = /(?:^|\s)sha512-([\d+/A-Za-z]+={0,2})(?=[\s?]|$)/u.exec(integrity)?.[1]
+  if (sha512 === undefined) return null
+  const body = await readRegularFile(join(root, 'content-v2', 'sha512', ...shard(Buffer.from(sha512, 'base64').toString('hex'))))
+  return body && digest('sha512', body, 'base64') === sha512 ? { body, metadata: entry.metadata } : null
+}

package/src/npm/registry.js

@@ -3,16 +3,22 @@ import assert from 'node:assert/strict'
 import { show } from '../args.js'
 import { NPM_REGISTRY, buildUrl, request } from '../http.js'
 
+// The first of these that is set and not empty.
+const npmToken = () => process.env.PREVENTIVE_MEASURES_NPM_TOKEN || process.env.STASIS_NPM_TOKEN || process.env.NPM_TOKEN
+
 // Private packages are always scoped.
 export function withNpmToken(name, url, options = {}) {
   const method = options.method ?? 'GET'
-  assert.ok(method === 'GET' && `${new URL(url)}` === url && url.startsWith(`${NPM_REGISTRY}/${name}/`), `Unexpected request for ${name}: ${method} ${url}`)
-  const token = process.env.NPM_TOKEN
+  const own = url === `${NPM_REGISTRY}/${name}` || url.startsWith(`${NPM_REGISTRY}/${name}/`)
+  assert.ok(method === 'GET' && `${new URL(url)}` === url && own, `Unexpected request for ${name}: ${method} ${url}`)
+  const token = npmToken()
   return token && name.startsWith('@') ? { ...options, method, headers: { ...options.headers, Authorization: `Bearer ${token}` } } : options
 }
 
-export async function getDocument(method, name, spec) {
-  const url = buildUrl(NPM_REGISTRY, [...name.split('/'), spec])
+// A version's document, or with no `spec` the whole package's, every
+// version's and `time`.
+export async function getDocument(method, name, ...spec) {
+  const url = buildUrl(NPM_REGISTRY, [...name.split('/'), ...spec])
   const json = await request(url, withNpmToken(name, url, { as: 'json' }))
   assert.ok(json?.name === name, `${method}: the registry answered for ${show(json?.name)}, not ${name}`)
   return json

package/src/npm/repos.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
 
-import { assertNames, assertPackageName, assertRepo, isRepo } from '../args.js'
+import { assertNames, assertPackageName, assertion, isRepo, optional } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
 import { isNotFound, recover } from '../http.js'
 import { assertRepoDirectory, getRepo, isRepoDirectory } from '../package.js'
@@ -10,8 +10,18 @@ import { getDocument } from './registry.js'
 const DIR = 'npm/repos'
 const CONCURRENCY = 8
 // Stamped on each entry, and raised when getRepo would answer differently:
-// 2 is `repository` taking precedence over `bugs`.
-const VERSION = 2
+// 2 is `repository` taking precedence over `bugs`; 3 the shorthand dropping
+// a `.git`, URLs read past whitespace, and `repository.directory`'s `\` read
+// as `/`; 4 a declared root answered as `''`, no directory declared left
+// out (unknown) rather than read as the root, and a declared directory's
+// empty and `.` parts dropped.
+const VERSION = 4
+
+// A slug a lookup gives: getRepo answers no repo ending in `.git`, the
+// suffix it drops (withoutDotGit; `.GIT` it keeps, and so does this).
+const isLookedUpRepo = (github) => isRepo(github) && !github.endsWith('.git')
+// A write takes no slug a read would discard: whatever it writes reads back.
+const assertLookedUpRepo = assertion('"owner/name" with no trailing ".git"', isLookedUpRepo)
 
 // `latest`, not the full packument, which is megabytes of version history.
 const fetchRepo = async (method, name) => getRepo(await getDocument(method, name, 'latest'))
@@ -24,22 +34,24 @@ export async function getGitHub(name) {
 }
 
 // An entry under another VERSION was resolved by other rules, and may
-// name the repo a stale tracker does: a miss, as is one without
-// `directory`, which would read as a package at the repo root.
+// name a repo getRepo no longer would (a stale tracker's, or a shorthand's
+// with its `.git`, or the root where a package declared no directory): a
+// miss, as is one naming a repo or a directory no lookup gives. One without
+// `directory` is a package whose place in its repo is unknown.
 export async function readPackageRepoCache(name) {
   assertPackageName('readPackageRepoCache', 'name', name)
   const entry = await readRecord(DIR, name)
-  if (entry?.v !== VERSION || !isRepo(entry.github) || !isRepoDirectory(entry.directory)) return null
-  return { github: entry.github, ...(entry.directory && { directory: entry.directory }) }
+  if (entry?.v !== VERSION || !isLookedUpRepo(entry.github) || (entry.directory !== undefined && !isRepoDirectory(entry.directory))) return null
+  return { github: entry.github, ...(entry.directory !== undefined && { directory: entry.directory }) }
 }
 
 // Only resolved repos are cached: a 404, a rate limit and a package with
 // no repo link fail alike.
-export async function writePackageRepoCache(name, github, directory = '') {
+export async function writePackageRepoCache(name, github, directory) {
   assertPackageName('writePackageRepoCache', 'name', name)
-  assertRepo('writePackageRepoCache', 'github', github)
-  assertRepoDirectory('writePackageRepoCache', 'directory', directory)
-  return await writeRecord(DIR, name, { v: VERSION, github, directory })
+  assertLookedUpRepo('writePackageRepoCache', 'github', github)
+  optional(assertRepoDirectory)('writePackageRepoCache', 'directory', directory)
+  return await writeRecord(DIR, name, { v: VERSION, github, ...(directory !== undefined && { directory }) })
 }
 
 export async function resolvePackageRepos(packageNames, options = {}) {
@@ -50,11 +62,11 @@ export async function resolvePackageRepos(packageNames, options = {}) {
 
 // Through the cache. Null for a package the registry does not have, or
 // one naming no GitHub repo; any other failure throws.
-export async function lookUpPackageRepo(name) {
+async function lookUpPackageRepo(name) {
   const stored = await readPackageRepoCache(name)
   if (stored) return stored
   const { github, directory } = await fetchRepo('lookUpPackageRepo', name).catch(recover(isNotFound, {}))
   if (!github) return null
   await writePackageRepoCache(name, github, directory)
-  return { github, ...(directory && { directory }) }
+  return { github, ...(directory !== undefined && { directory }) }
 }

package/src/npm/tarball.js

@@ -1,39 +1,16 @@
-import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
-import { assertArgs, assertPackage, assertion, matches, show } from '../args.js'
+import { assertArgs, assertPackage, assertPackageName, isPlainObject, isSha, optional } from '../args.js'
+import { assertCache } from '../cache.js'
 import { verifiedDownload } from '../download.js'
-import { NPM_REGISTRY, buildUrl } from '../http.js'
+import { NPM_REGISTRY, decode } from '../http.js'
+import { readNpmCached } from './cacache.js'
 import { getDocument, withNpmToken } from './registry.js'
+import { checkedDist, getVersion, matchingDist } from './versions.js'
 
 const DIR = 'npm/tarballs' // No expiry: the registry never takes a version twice.
-// One sha512 and nothing else, as the registry writes it: a sha1, a second
-// hash or an option is refused rather than trusted. 64 bytes leave the
-// last character before `==` two bits, so only A, Q, g or w is canonical.
-const assertIntegrity = assertion('"sha512-" and a base64 sha512', matches(/^sha512-[\dA-Za-z+/]{85}[AQgw]==$/u))
-
-// `{ tarball, integrity }` and nothing else, the tarball exactly the
-// registry's own URL for that version. Each field is read once, and only
-// as the object's own, into a copy that is checked and used from then on:
-// the caller's object can change while a request is out, and a field on
-// its prototype is not one it has.
-function checkedDist(method, name, version, dist) {
-  assertArgs(method, dist, { tarball: null, integrity: null }, 'dist')
-  const [tarball, integrity] = ['tarball', 'integrity'].map((key) => (Object.hasOwn(dist, key) ? dist[key] : undefined))
-  assertIntegrity(method, 'dist.integrity', integrity)
-  const segments = name.split('/')
-  const expected = buildUrl(NPM_REGISTRY, [...segments, '-', `${segments.at(-1)}-${version}.tgz`])
-  assert.ok(tarball === expected, `${method}: dist.tarball must be ${expected}, got ${show(tarball)}`)
-  return { tarball, integrity }
-}
-
-async function getDist(method, name, version) {
-  const json = await getDocument(method, name, version)
-  assert.ok(json.version === version, `${method}: the registry answered for ${name}@${show(json.version)}, not ${name}@${version}`)
-  return checkedDist(method, name, version, { tarball: json.dist?.tarball, integrity: json.dist?.integrity })
-}
 
 // Where npm keeps its cache, short of an .npmrc moving it: npm_config_cache,
 // as npm sets it for what it runs, else npm's default. On Windows, npm 4
@@ -53,23 +30,108 @@ function localPaths(name, version, integrity) {
   return [...npm, join(homedir(), '.audit/cache/tgz', `${name.replace(/^@/u, '').replace('/', ':')}-${version}.tgz`)]
 }
 
-export async function getMeta(name, version) {
+// verifyDist's and getTarball's options: `cache` alone.
+const assertOptions = (method, options) => assertArgs(method, options, { cache: optional(assertCache) })
+
+const own = (object, key) => (Object.hasOwn(object, key) ? object[key] : undefined)
+const stringOr = (value) => (typeof value === 'string' ? value : undefined)
+
+// A string as it is, or an object's strings under `keys`, the rest undefined:
+// none where it is neither, or names none of them.
+function linkOf(value, keys) {
+  if (typeof value === 'string') return value
+  if (!isPlainObject(value)) return undefined
+  const link = Object.fromEntries(keys.map((key) => [key, stringOr(own(value, key))]))
+  return keys.some((key) => link[key] !== undefined) ? link : undefined
+}
+
+const mediaType = (value) => (typeof value === 'string' ? value.split(';')[0].trim().toLowerCase() : undefined)
+
+function jsonOf(bytes, from) {
+  try {
+    return JSON.parse(decode(bytes, from))
+  } catch {
+    return undefined
+  }
+}
+
+// A version as npm's own cache keeps it, where it keeps its name's full
+// packument, as npm 10 and later fetch it, whose entry for the version
+// matches `given` (matchingDist): that entry is the version's document. An
+// abbreviated packument, as earlier npm fetches, has none of the rest
+// getMeta answers, and is passed over.
+async function npmCachedVersion(name, version, given) {
+  const url = `${NPM_REGISTRY}/${name.replace('/', '%2f')}`
+  for (const root of npmCacheDirs()) {
+    const cached = await readNpmCached(join(root, '_cacache'), url)
+    if (!cached || mediaType(cached.metadata?.resHeaders?.['content-type']) !== 'application/json') continue
+    const packument = jsonOf(cached.body, url)
+    const json = packument?.name === name && isPlainObject(packument.versions) ? own(packument.versions, version) : undefined
+    const dist = matchingDist('getMeta', name, version, json, given)
+    if (dist) return { dist, json }
+  }
+  return 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.
+export async function getMeta(name, version, options = {}) {
   assertPackage('getMeta', name, version)
-  return { name, version, dist: await getDist('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 = {
+    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']),
+  }
+  return { name, version, dist, ...Object.fromEntries(Object.entries(about).filter(([, value]) => value !== undefined)) }
+}
+
+// Only the whole package's document has `time`: megabytes for some.
+const PUBLISHED = /^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d)(?:\.(\d{1,3}))?Z$/u
+const record = (value) => (isPlainObject(value) ? value : {})
+
+// A time toISOString writes back as given, its milliseconds padded: none
+// Date.parse moves, as it moves 2018-02-29 to March.
+function readTime(value) {
+  const match = typeof value === 'string' ? PUBLISHED.exec(value) : null
+  if (match === null) return undefined
+  const iso = `${match[1]}.${(match[2] ?? '').padEnd(3, '0')}Z`
+  const parsed = Date.parse(iso)
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === iso ? iso : undefined
+}
+
+export async function getPublishTimes(name) {
+  assertPackageName('getPublishTimes', 'name', name)
+  const json = await getDocument('getPublishTimes', name)
+  const time = record(json.time)
+  const times = new Map()
+  for (const version of Object.keys(record(json.versions))) {
+    const at = readTime(Object.hasOwn(time, version) ? time[version] : undefined)
+    if (at !== undefined) times.set(version, at)
+  }
+  return times
 }
 
-export async function verifyDist(name, version, dist) {
+export async function verifyDist(name, version, dist, options = {}) {
   assertPackage('verifyDist', name, version)
-  const given = checkedDist('verifyDist', name, version, dist)
-  const { integrity } = await getDist('verifyDist', name, version)
-  assert.ok(given.integrity === integrity, `verifyDist: ${name}@${version} is ${integrity} on the registry, not ${given.integrity}`)
+  assertOptions('verifyDist', options)
+  await getVersion('verifyDist', name, version, checkedDist('verifyDist', name, version, dist), options.cache)
 }
 
 // Without `dist`, the version document is read every time, cache or not:
 // bytes from a cache are checked against the registry's integrity, never
 // against anything a cache itself holds.
-export async function getTarball(name, version, dist) {
+export async function getTarball(name, version, dist, options = {}) {
   assertPackage('getTarball', name, version)
-  const { tarball, integrity } = dist === undefined ? await getDist('getTarball', name, version) : checkedDist('getTarball', name, version, dist)
-  return await verifiedDownload({ method: 'getTarball', dir: DIR, what: `${name}@${version}`, ext: 'tgz', algorithm: 'sha512', expected: integrity, local: localPaths(name, version, integrity), ours: true, locate: () => tarball, options: withNpmToken(name, tarball) })
+  assertOptions('getTarball', options)
+  const { cache } = options
+  const { tarball, integrity } = dist === undefined ? (await getVersion('getTarball', name, version, undefined, cache)).dist : checkedDist('getTarball', name, version, dist)
+  return await verifiedDownload({ method: 'getTarball', dir: DIR, what: `${name}@${version}`, ext: 'tgz', algorithm: 'sha512', expected: integrity, local: localPaths(name, version, integrity), ours: true, cache, locate: () => tarball, options: withNpmToken(name, tarball) })
 }

package/src/npm/versions.js

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict'
+
+import { assertArgs, assertion, matches, show } from '../args.js'
+import { readJSON, writeJSON } from '../cache.js'
+import { NPM_REGISTRY, buildUrl, isNotFound, recover } from '../http.js'
+import { getDocument } from './registry.js'
+
+const DIR = 'npm/versions' // No expiry: the registry never takes a version twice, nor changes its dist.
+// One sha512 and nothing else, as the registry writes it: a sha1, a second
+// hash or an option is refused rather than trusted. 64 bytes leave the
+// last character before `==` two bits, so only A, Q, g or w is canonical.
+const assertIntegrity = assertion('"sha512-" and a base64 sha512', matches(/^sha512-[\dA-Za-z+/]{85}[AQgw]==$/u))
+
+// `{ tarball, integrity }` and nothing else, the tarball exactly the
+// registry's own URL for that version. Each field is read once, and only
+// as the object's own, into a copy that is checked and used from then on:
+// the caller's object can change while a request is out, and a field on
+// its prototype is not one it has.
+export function checkedDist(method, name, version, dist) {
+  assertArgs(method, dist, { tarball: null, integrity: null }, 'dist')
+  const [tarball, integrity] = ['tarball', 'integrity'].map((key) => (Object.hasOwn(dist, key) ? dist[key] : undefined))
+  assertIntegrity(method, 'dist.integrity', integrity)
+  const segments = name.split('/')
+  const expected = buildUrl(NPM_REGISTRY, [...segments, '-', `${segments.at(-1)}-${version}.tgz`])
+  assert.ok(tarball === expected, `${method}: dist.tarball must be ${expected}, got ${show(tarball)}`)
+  return { tarball, integrity }
+}
+
+const distOf = (method, name, version, json) => checkedDist(method, name, version, { tarball: json.dist?.tarball, integrity: json.dist?.integrity })
+
+// Whether a version document is one to keep, or to take as kept: for that
+// name and version, with a dist that passes.
+function isKeepable(method, name, version, json) {
+  if (json?.name !== name || json.version !== version) return false
+  try {
+    distOf(method, name, version, json)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// A version's document as `cache` keeps it (readJSON), or none.
+async function keptDocument(method, name, version, cache) {
+  const json = await readJSON(DIR, `${name}@${version}`, cache)
+  return isKeepable(method, name, version, json) ? json : undefined
+}
+
+// The registry's document, kept whole in `cache` once it is keepable; one
+// whose dist is refused is answered all the same.
+async function keepDocument(method, name, version, json, cache) {
+  assert.ok(json.version === version, `${method}: the registry answered for ${name}@${show(json.version)}, not ${name}@${version}`)
+  if (isKeepable(method, name, version, json)) await writeJSON(DIR, `${name}@${version}`, json, cache)
+  return json
+}
+
+const fetchDocument = async (method, name, version, cache) => await keepDocument(method, name, version, await getDocument(method, name, version), cache)
+
+// A version's document, kept or else fetched, for what is not an
+// integrity: a package's repo (advisories.js), as trusted as setCacheDir's
+// repo records are. Null where the registry does not have that version:
+// its 404 alone, never a failure of the cache's.
+export async function getVersionDocument(method, name, version, cache) {
+  const kept = await keptDocument(method, name, version, cache)
+  if (kept) return kept
+  const json = await getDocument(method, name, version).catch(recover(isNotFound, null))
+  return json && await keepDocument(method, name, version, json, cache)
+}
+
+// The dist of a version document a cache answers, where it is that
+// version's, its dist passes, and its tarball and integrity are `given`'s
+// (checkedDist): a cache never supplies a dist, only confirms one.
+export function matchingDist(method, name, version, json, given) {
+  if (!isKeepable(method, name, version, json)) return undefined
+  const dist = distOf(method, name, version, json)
+  return dist.integrity === given.integrity && dist.tarball === given.tarball ? dist : undefined
+}
+
+// A version's document, and its dist checked. A kept document is read only
+// for a caller that already has a dist, `given`, and answers with no
+// request where it matches (matchingDist). Else, or without one, the
+// registry is asked, and its document, kept in place of any other, throws
+// where it does not.
+export async function getVersion(method, name, version, given, cache) {
+  if (given !== undefined) {
+    const kept = await readJSON(DIR, `${name}@${version}`, cache)
+    const dist = matchingDist(method, name, version, kept, given)
+    if (dist) return { dist, json: kept }
+  }
+  const json = await fetchDocument(method, name, version, cache)
+  const dist = distOf(method, name, version, json)
+  if (given !== undefined) {
+    assert.ok(dist.integrity === given.integrity, `${method}: ${name}@${version} is ${dist.integrity} on the registry, not ${given.integrity}`)
+    assert.ok(dist.tarball === given.tarball, `${method}: ${name}@${version} is at ${dist.tarball} on the registry, not ${given.tarball}`)
+  }
+  return { dist, json }
+}