@preventive/triage 1.0.0-alpha.36 → 1.0.0-alpha.38

package/server-managed/npm-risk.ts

@@ -0,0 +1,177 @@
+// What calls for a look at an npm version, as risk tells it (risk/), for the
+// managed viewer: risk is asked on the server alone, its records kept where
+// each belongs by its type (risk/npm/registry.js, assess.js):
+//
+// - `risk/npm/assessments`, what of an assessment holds whatever the time:
+//   a public package's in the public npm cache, as its pretty-printed files
+//   are (storage-payload.ts PUBLIC_CACHE), by a hash of its key; a private
+//   one's in this instance's memory alone.
+// - `risk/npm/versions`, what a version's document says, which npm never
+//   changes once published: a public package's in the database's upstream
+//   cache table, shared by every instance; a private one's in memory.
+// - `risk/npm/packages`, `risk/npm/public`, `risk/npm/advisories` and
+//   `risk/npm/downloads`, kept an hour or a day by risk itself: in memory.
+// - `npm/tarballs`: none asked, as tarballs are read as the viewer's loads
+//   read them, kept where they keep them (npm-loads.ts loadNpmTarball), and
+//   an assessment kept needs none.
+//
+// What memory keeps is held to 2,000 records and 64 MiB as JSON, the first
+// kept going first.
+//
+// A cache failure is a miss, never a failed assessment. Packages' documents
+// are read as every other npm document here is, within their bounds and
+// shared budget (npm-packages.ts readNpmPackument), and tarballs as the
+// viewer's loads read them, bounded as they arrive and among the loads made
+// at once. Assessments made at once are bounded as those loads are, each
+// unpacking up to two tarballs: one past them is refused as busy.
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { buffer } from 'node:stream/consumers'
+import type { CacheStore } from '@preventive/upstream/npm.js'
+import { DEFAULT_MINIMUM_RELEASE_AGE, type NpmAssessment, assessNpm } from '../risk/index.js'
+import { CacheMissError, type CacheStorage } from './cache-storage.ts'
+import { loadNpmTarball } from './npm-loads.ts'
+import { NpmPackageError, type NpmVersionDocument, readNpmPackument, readNpmVersion } from './npm-packages.ts'
+import { npmPackageScope } from '../common/managed/npm-packages.js'
+import type { UpstreamCacheStore } from './upstream-cache.ts'
+
+const MEMORY_ENTRIES = 2000
+// As npm-loads.ts MAX_ACTIVE_LOADS.
+const MAX_ACTIVE_ASSESSMENTS = 4
+// Of them, those no reader waits on (`spare`), such as a scan's: the rest are
+// left for readers.
+export const MAX_SPARE_ASSESSMENTS = 2
+let assessing = 0
+// What memory holds at most, by its records' length as JSON: the first kept
+// go first past it, and a record past an eighth of it isn't kept at all.
+const MEMORY_LENGTH = 64 * 1024 * 1024
+let memoryLength = 0
+const memory = new Map<string, { value: unknown; length: number }>()
+function forget(key: string) {
+  const kept = memory.get(key)
+  if (!kept) return
+  memory.delete(key)
+  memoryLength -= kept.length
+}
+function remember(key: string, value: unknown) {
+  forget(key)
+  const length = JSON.stringify(value)?.length ?? 0
+  if (length > MEMORY_LENGTH / 8) return
+  memory.set(key, { value, length })
+  memoryLength += length
+  while (memory.size > MEMORY_ENTRIES || memoryLength > MEMORY_LENGTH) forget(memory.keys().next().value!)
+}
+
+const hashed = (type: string, key: string) => `risk/${createHash('sha256').update(`${type}\0${key}`).digest('hex')}`
+
+export interface NpmRiskStores {
+  db: UpstreamCacheStore
+  npmCache?: CacheStorage | undefined
+  debug?: boolean | undefined
+}
+
+// Risk's cache for one package: `isPublic` whether anyone can read it, so
+// that what is kept of it can be shared.
+export function npmRiskCache({ db, npmCache, debug }: NpmRiskStores, isPublic: boolean): CacheStore {
+  const warn = (what: string, error: unknown) => { if (debug) console.warn(`managed: risk cache ${what} failed:`, error) }
+  return {
+    async read(type, key) {
+      if (type === 'npm/tarballs') return null
+      try {
+        if (isPublic && type === 'risk/npm/assessments' && npmCache) return JSON.parse((await buffer((await npmCache.open(hashed(type, key))).stream)).toString('utf8'))
+        if (isPublic && type === 'risk/npm/versions') { const value = await db.getUpstreamCacheEntry(`${type}/${key}`); return value === null ? null : JSON.parse(value) }
+      } catch (error) { if (!(error instanceof CacheMissError)) warn('read', error); return null }
+      return memory.get(`${isPublic ? '' : 'private\0'}${type}\0${key}`)?.value ?? null
+    },
+    async write(type, key, value) {
+      if (type === 'npm/tarballs') return
+      try {
+        if (isPublic && type === 'risk/npm/assessments' && npmCache) { await npmCache.put(hashed(type, key), Buffer.from(JSON.stringify(value))); return }
+        if (isPublic && type === 'risk/npm/versions') { await db.setUpstreamCacheEntry(`${type}/${key}`, JSON.stringify(value), Date.now()); return }
+      } catch (error) { warn('write', error); return }
+      remember(`${isPublic ? '' : 'private\0'}${type}\0${key}`, value)
+    },
+  }
+}
+
+// A version's tarball as the viewer's loads read it (npm-loads.ts), its bytes
+// held to the integrity its reader's document names: given up on, and the
+// load released, once `signal` aborts, the load going on for its other
+// readers, so that a reader gone holds no assessment's place.
+async function tarballOf(doc: NpmVersionDocument | undefined, signal: AbortSignal): Promise<Uint8Array> {
+  if (!doc) throw new NpmPackageError(502, 'upstream-invalid')
+  signal.throwIfAborted()
+  const load = loadNpmTarball(doc)
+  let onAbort = () => {}
+  const aborted = new Promise<never>((_, reject) => { onAbort = () => reject(signal.reason); signal.addEventListener('abort', onAbort, { once: true }) })
+  try { return await Promise.race([load.result, aborted]) } finally {
+    signal.removeEventListener('abort', onAbort)
+    load.release()
+  }
+}
+
+// The version `doc` names assessed against `old`'s, where given, each as the
+// reader's readNpmVersion read it, or against the one risk picks of its
+// versions (`'pick'`, assessNpm `oldVersion: true`), its document read as the
+// open version's is where its tarball is wanted: trusted however new and however few
+// download it where a team lists its scope (`teamScoped`), its own packages;
+// else held to risk's minimum release age and flagged as unpopular. A new
+// dependency on a package of a scope a team lists (`ownScope`, asked once a
+// scope) is told no tier nor age, as an own package. Its
+// documents are read with npm's token where the reader may have it
+// (`privileged`, as readNpmVersion), its dependencies' without; what is kept
+// of it is shared only where neither version is private, and OSV is asked of
+// its advisories only where it isn't, a private package's name never sent to
+// OSV, as it never is to Socket (http.ts). A `spare` one, no
+// reader waiting on it, is made only within MAX_SPARE_ASSESSMENTS, and tells
+// its dependencies without asking npm of their packages (assessNpm
+// `dependencies`), nor its advisories, which a scan asks of a lockfile's
+// packages at once (repository-risk.ts).
+export function npmRisk(doc: NpmVersionDocument, old: NpmVersionDocument | 'pick' | null,
+  { teamScoped, ownScope = () => Promise.resolve(false), fromEmpty = false, privileged, signal, spare = false, ...stores }: NpmRiskStores & { teamScoped: boolean;
+    ownScope?: (scope: string) => Promise<boolean>; fromEmpty?: boolean; privileged: boolean; signal: AbortSignal; spare?: boolean }): Promise<NpmAssessment> {
+  const scopes = new Map<string, Promise<boolean>>()
+  const owned = (name: string) => {
+    const scope = npmPackageScope(name)
+    if (scope === null) return false
+    if (!scopes.has(scope)) scopes.set(scope, ownScope(scope))
+    return scopes.get(scope)!
+  }
+  const given = old === 'pick' ? null : old
+  const documentOf = async (version: string) => [doc, given].find(read => read?.version === version) ?? await readNpmVersion(doc.name, version, privileged, signal) ?? undefined
+  return bounded(spare, () => assessNpm(doc.name, doc.version, { oldVersion: old === 'pick' ? true : old?.version ?? null, fromEmpty,
+    minimumReleaseAge: teamScoped ? 0 : DEFAULT_MINIMUM_RELEASE_AGE,
+    popularity: !teamScoped, cache: npmRiskCache(stores, !doc.private && !given?.private), signal, dependencies: !spare, advisories: !spare, osv: !doc.private, owned,
+    packument: (name, { authorized }) => readNpmPackument(name, privileged && authorized, signal),
+    tarball: async (_name, version) => tarballOf(await documentOf(version), signal) }))
+}
+
+// An assessment made within MAX_ACTIVE_ASSESSMENTS, a `spare` one within
+// MAX_SPARE_ASSESSMENTS, all across the server; one past them refused as
+// busy (`npm-busy`).
+async function bounded(spare: boolean, assess: () => Promise<NpmAssessment>): Promise<NpmAssessment> {
+  if (assessing >= (spare ? MAX_SPARE_ASSESSMENTS : MAX_ACTIVE_ASSESSMENTS)) throw new NpmPackageError(429, 'npm-busy')
+  assessing++
+  try { return await assess() } finally { assessing-- }
+}
+
+// A version npm has no document of, as risk tells one npm removed, as it
+// removes every one it finds malware in (assessNpm): its package taken down
+// by npm, as a scan's (`spare`), and its advisories of malware, npm's and,
+// where anyone can read its package, OSV's, which alone has some of those
+// npm removed (nx's), a private package's name never sent to OSV. Its
+// package's document read anonymously, else with npm's token where the
+// reader may have it (`privileged`), and kept as a private package's is; no
+// tarball read, nothing of the version being left. Spare, within
+// MAX_SPARE_ASSESSMENTS as a scan's others are. An NpmRiskError where
+// nothing tells of it.
+export function npmRiskRemoved(name: string, version: string,
+  { teamScoped, privileged, signal, ...stores }: NpmRiskStores & { teamScoped: boolean; privileged: boolean; signal: AbortSignal }): Promise<NpmAssessment> {
+  return bounded(true, async () => {
+    const open = await readNpmPackument(name, false, signal)
+    return assessNpm(name, version, { minimumReleaseAge: teamScoped ? 0 : DEFAULT_MINIMUM_RELEASE_AGE, popularity: false, downloads: false, dependencies: false,
+      osv: open !== null, cache: npmRiskCache(stores, false), signal,
+      packument: (read, { authorized }) => read === name && open ? Promise.resolve(open) : readNpmPackument(read, privileged && authorized, signal),
+      tarball: () => Promise.reject(new NpmPackageError(502, 'upstream-invalid')) })
+  })
+}

package/server-managed/pretty-print.ts

@@ -0,0 +1,352 @@
+// Minified files pretty-printed for the Code tab (GET /api/bundles/:id/pretty
+// one file at a time, GET /api/npm/pretty all a version's at once), and the
+// files that changed between two bundles or versions for Compare (the same
+// with `other`, or `otherVersion`), named by path and content hash, formatted
+// with oxfmt once and kept Brotli-encoded by that hash: a bundle's in its
+// cache directory (so only made from, and read by readers of, that bundle), a
+// public npm version's under `cache/npm/`; a private version's are never
+// kept. Access is the caller's to check.
+import { Buffer } from 'node:buffer'
+import { Readable } from 'node:stream'
+import { promisify } from 'node:util'
+import { brotliDecompress } from 'node:zlib'
+import { format } from '@preventive/compare/pretty.js'
+import { computeFileHash } from '@preventive/report'
+import { FILE_HASH } from '../common/bundle-metadata.js'
+import { bundleCompareFiles } from '../common/bundle-compare-inputs.js'
+import { bundlePackageDirs, bundleSourcesAsMap } from '../common/bundle-sources.js'
+import { MAX_PRETTY_BYTES, needsPrettyPrint, prettyExtension } from '../common/pretty-print.js'
+import type { OpenedBlob } from './blob-store.ts'
+import { type BundleCacheStorage, readBundleDetails } from './bundle-cache.ts'
+import type { BundleStore } from './bundle-store.ts'
+import { encodeBrotli } from './brotli.ts'
+import { CacheMissError, type CacheStorage } from './cache-storage.ts'
+import type { ManagedBundle, ManagedDb } from './db.ts'
+import { loadNpmFiles } from './npm-loads.ts'
+import { type NpmVersionDocument, npmFileText } from './npm-packages.ts'
+
+// Part of every kept copy's name; bumped when what the formatter writes for
+// the same file changes, or what its check lets through, so copies written
+// before are no longer read.
+const PRETTY_VERSION = 3
+// Formats running at once per process, each holding its file's syntax tree,
+// and those waiting their turn past them (a version's files are formatted one
+// after another, beside other readers'), any more refused.
+const MAX_ACTIVE_FORMATS = 2
+const MAX_WAITING_FORMATS = 16
+
+export class PrettyError extends Error {
+  status: number
+  constructor(status: number, code: string) { super(code); this.status = status }
+}
+
+export interface PrettyRequest { path: string; hash: string; extension: string }
+
+// One of a version's files pretty-printed (npmAll), named by `source`, the
+// hash of the file it was formatted from: its copy's text, or why it has
+// none, as a PrettyError tells it.
+export type PrettyLine = { path: string; source: string; text: string } | { path: string; source: string; error: string; status: number }
+
+// Which of a comparison's two its files are of: the bundle or version asked
+// about, or the `other`.
+type Side = 'base' | 'other'
+
+// One of a comparison's changed files pretty-printed (compared), as a
+// version's is, with the side it is of.
+export type ComparedLine = PrettyLine & { side: Side }
+
+// A side of a comparison: its files that can be formatted, with their texts,
+// and every one of its files' hashes, by path; its packages' directories by
+// path, as a bundle records them (bundlePackageDirs), or null where it
+// records none; the copy kept for one, or null; and one made, kept where the
+// side keeps copies.
+export interface ComparedSide {
+  side: Side
+  files: Array<PrettyRequest & { text: string }>
+  hashes: Map<string, string>
+  packageDirs: Map<string, string> | null
+  kept(request: PrettyRequest): Promise<OpenedBlob | null>
+  made(request: PrettyRequest, text: string): Promise<OpenedBlob>
+}
+
+// The file a request's `path` and `hash` name, or null for one that can't be
+// formatted.
+export function prettyRequest(params: URLSearchParams): PrettyRequest | null {
+  const path = params.get('path') ?? ''
+  const extension = prettyExtension(path), hash = params.get('hash') ?? ''
+  return extension !== null && FILE_HASH.test(hash) ? { path, hash, extension } : null
+}
+
+// A copy's name: its file's hash in hex, with the extension it was parsed by.
+const prettyFile = ({ hash, extension }: PrettyRequest) =>
+  `pretty-v${PRETTY_VERSION}/${Buffer.from(hash.slice('sha512-'.length), 'base64').toString('hex')}.${extension}.br`
+
+let activeFormats = 0
+const waitingFormats: Array<() => void> = []
+
+// The text formatted and Brotli-encoded, where @preventive/compare's checks
+// find formatting changed only its layout: refused as `unsupported` where it
+// has no check for the kind of file, `unformattable` or `pretty-mismatch`.
+export async function prettyBody(text: string, extension: string): Promise<Buffer> {
+  if (Buffer.byteLength(text) > MAX_PRETTY_BYTES) throw new PrettyError(413, 'file-too-large')
+  if (activeFormats < MAX_ACTIVE_FORMATS) activeFormats++
+  else if (waitingFormats.length >= MAX_WAITING_FORMATS) throw new PrettyError(429, 'pretty-busy')
+  else await new Promise<void>(resolve => { waitingFormats.push(resolve) })
+  let result
+  try { result = await format(text, extension) }
+  finally {
+    const next = waitingFormats.shift()
+    if (next) next()
+    else activeFormats--
+  }
+  if ('error' in result) {
+    if (result.error === 'pretty-mismatch') console.warn(`managed: pretty-printing a .${extension} file changed more than its layout; not served`)
+    throw new PrettyError(422, result.error)
+  }
+  return encodeBrotli(Buffer.from(result.code))
+}
+
+const opened = (body: Buffer): OpenedBlob => ({ size: body.byteLength, stream: Readable.from([body]) })
+
+const decompress = promisify(brotliDecompress)
+
+// A pretty-printed copy's text, from its Brotli-encoded bytes.
+export async function prettyText(copy: OpenedBlob): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of copy.stream) chunks.push(chunk as Buffer)
+  return (await decompress(Buffer.concat(chunks))).toString()
+}
+
+// Every file of a version that needs pretty-printing (needsPrettyPrint), read
+// in one load of its files, in path order.
+async function npmPrintable(doc: NpmVersionDocument): Promise<Array<PrettyRequest & { text: string }>> {
+  const load = loadNpmFiles(doc)
+  const files: Array<PrettyRequest & { text: string }> = []
+  try {
+    for (const { path, bytes } of await load.result) {
+      const extension = prettyExtension(path)
+      if (extension === null || bytes.byteLength > MAX_PRETTY_BYTES) continue
+      const text = npmFileText(bytes)
+      if (text !== null && needsPrettyPrint(path, text)) files.push({ path, hash: await computeFileHash(bytes), extension, text })
+    }
+  } finally { load.release() }
+  return files.toSorted((a, b) => (a.path < b.path ? -1 : 1))
+}
+
+// A file's line (PrettyLine): the text of its copy, as `copy` has it, or why
+// it has none.
+async function prettyLine({ path, hash }: PrettyRequest, copy: () => Promise<OpenedBlob>): Promise<PrettyLine> {
+  try { return { path, source: hash, text: await prettyText(await copy()) } }
+  catch (err) {
+    if (!(err instanceof PrettyError)) throw err
+    return { path, source: hash, error: err.message, status: err.status }
+  }
+}
+
+// The files that changed between two sides, pretty-printed: each side's
+// formattable files the other has another text at the path of, or, where it
+// has none there, none of their text at a path of its own (a file renamed, or
+// moved with its tree, unchanged, has it there; a copy at a path both have is
+// not one), by the paths each side has them at. Those are both of the pairs
+// the viewer diffs but where it pairs files otherwise (among copies of one
+// text, across packages), whose copies it asks for alone. As they are
+// iterated, in path order, the base's first where both have one: those kept,
+// at once; then the rest, formatted one after another, the minified before
+// the others (needsPrettyPrint), as the viewer prints those unasked.
+export function compared(sides: readonly [ComparedSide, ComparedSide]): AsyncGenerator<ComparedLine> {
+  // Each side's texts at the paths the other hasn't: where a file moved has its own.
+  const moved = sides.map((own, i) => new Set([...own.hashes].filter(([path]) => !sides[1 - i]!.hashes.has(path)).map(([, hash]) => hash)))
+  const changed = sides.flatMap((own, i) => {
+    const other = sides[1 - i]!.hashes
+    return own.files.filter(({ path, hash }) => (other.has(path) ? other.get(path) !== hash : !moved[1 - i]!.has(hash))).map(file => ({ own, file }))
+  }).toSorted((a, b) => (a.file.path < b.file.path ? -1 : a.file.path > b.file.path ? 1 : 0))
+  return (async function* () {
+    const unkept: typeof changed = []
+    for (const { own, file } of changed) {
+      const copy = await own.kept(file)
+      if (copy) yield { side: own.side, ...await prettyLine(file, () => Promise.resolve(copy)) }
+      else unkept.push({ own, file })
+    }
+    const minified = new Map(unkept.map(({ file }) => [file, needsPrettyPrint(file.path, file.text)]))
+    for (const { own, file } of unkept.toSorted((a, b) => Number(minified.get(b.file)) - Number(minified.get(a.file)))) {
+      yield { side: own.side, ...await prettyLine(file, () => own.made(file, file.text)) }
+    }
+  })()
+}
+
+// Jobs by key, readers asking for one while it runs sharing it.
+function sharing<T>(): (key: string, make: () => Promise<T>) => Promise<T> {
+  const pending = new Map<string, Promise<T>>()
+  return (key, make) => {
+    let job = pending.get(key)
+    if (!job) pending.set(key, job = make().finally(() => pending.delete(key)))
+    return job
+  }
+}
+
+// Work done one job at a time, in the order asked.
+function serial(): <T>(work: () => Promise<T>) => Promise<T> {
+  let queue = Promise.resolve()
+  return work => {
+    const job = queue.then(work)
+    queue = job.then(() => undefined, () => undefined)
+    return job
+  }
+}
+
+async function keep(put: () => Promise<void>) {
+  try { await put() } catch (err) { console.warn('managed: pretty-print cache write failed:', err) }
+}
+
+// A copy kept, or null where none is.
+async function kept(open: () => Promise<OpenedBlob>): Promise<OpenedBlob | null> {
+  try { return await open() }
+  catch (err) { if (err instanceof CacheMissError) return null; throw err }
+}
+
+// A side's files that can be formatted, with their texts, and every one of
+// its files' hashes by path, from their paths and contents: texts, or bytes,
+// read as text where they are.
+async function sideFiles(entries: Iterable<[string, string | Uint8Array]>): Promise<Pick<ComparedSide, 'files' | 'hashes'>> {
+  const files: ComparedSide['files'] = [], hashes = new Map<string, string>()
+  for (const [path, content] of entries) {
+    const hash = await computeFileHash(content)
+    hashes.set(path, hash)
+    const extension = prettyExtension(path)
+    if (extension === null || (typeof content === 'string' ? Buffer.byteLength(content) : content.byteLength) > MAX_PRETTY_BYTES) continue
+    const text = typeof content === 'string' ? content : npmFileText(content)
+    if (text !== null) files.push({ path, hash, extension, text })
+  }
+  return { files, hashes }
+}
+
+// A bundle's side, from its details: its files, as sideFiles reads them,
+// within a reason `scope` as Compare reads them there (bundleCompareFiles),
+// and its packages' directories.
+async function bundleSide(details: Parameters<typeof bundlePackageDirs>[0], scope: string): Promise<Pick<ComparedSide, 'files' | 'hashes' | 'packageDirs'>> {
+  const scoped = scope ? new Set(bundleCompareFiles(details, scope).keys()) : null, sources = bundleSourcesAsMap(details)
+  return { ...await sideFiles(scoped ? [...sources].filter(([path]) => scoped.has(path)) : sources), packageDirs: bundlePackageDirs(details) }
+}
+
+// A version's files by path, from one load of them.
+async function npmFiles(doc: NpmVersionDocument): Promise<Array<[string, Uint8Array]>> {
+  const load = loadNpmFiles(doc)
+  try { return (await load.result).map(({ path, bytes }) => [path, bytes]) }
+  finally { load.release() }
+}
+
+// Removes the public npm copies of every version before PRETTY_VERSION, which
+// nothing reads any more, for maintenance: once a process, again where
+// removing them failed. A bundle's earlier copies go with the bundle.
+export function stalePrettyRemover(npm: CacheStorage): (signal?: AbortSignal) => Promise<void> {
+  let removed = false
+  return async signal => {
+    if (removed) return
+    for (let version = 1; version < PRETTY_VERSION; version++) {
+      if (signal?.aborted) return
+      await npm.delete(`pretty-v${version}`)
+    }
+    removed = true
+  }
+}
+
+export function createPrettyCache(bundles: BundleCacheStorage, npm: CacheStorage, db: Pick<ManagedDb, 'getBundle'>, store: BundleStore) {
+  // Copies being made; readers asking for one meanwhile share it.
+  const shared = sharing<Buffer>()
+  // Bundles are read one at a time: reading one decodes all of it.
+  const enqueue = serial()
+  function bundleDetails(record: ManagedBundle) {
+    return enqueue(async () => {
+      const details = await readBundleDetails(record, store)
+      if (!details) throw new PrettyError(422, 'bundle-unavailable')
+      return details
+    })
+  }
+  // A bundle's file pretty-printed from the text `read` reads, and kept in
+  // its cache.
+  function bundleCopy(record: ManagedBundle, request: PrettyRequest, read: () => Promise<string>): Promise<Buffer> {
+    const file = prettyFile(request)
+    return shared(`bundle ${record.id} ${file}`, async () => {
+      const body = await prettyBody(await read(), request.extension)
+      // As for its metadata (bundle-cache.ts): a bundle deleted meanwhile
+      // keeps no copy, nor does one deleted while it was written.
+      if (!await db.getBundle(record.id)) throw new PrettyError(404, 'no-bundle')
+      await keep(() => bundles.put(record.id, file, body))
+      if (!await db.getBundle(record.id)) {
+        await bundles.delete(record.id)
+        throw new PrettyError(404, 'no-bundle')
+      }
+      return body
+    })
+  }
+  // A version's file pretty-printed, `read` reading its text (and checking
+  // it is the file named): from the copy kept for a public version, else
+  // made, and kept for a public one.
+  async function npmCopy(doc: NpmVersionDocument, request: PrettyRequest, read: () => Promise<string>): Promise<OpenedBlob> {
+    const file = prettyFile(request)
+    if (!doc.private) {
+      try { return await npm.open(file) }
+      catch (err) { if (!(err instanceof CacheMissError)) throw err }
+    }
+    return opened(await shared(doc.private ? `npm ${doc.dist.integrity} ${file}` : `npm ${file}`, async () => {
+      const body = await prettyBody(await read(), request.extension)
+      if (!doc.private) await keep(() => npm.put(file, body))
+      return body
+    }))
+  }
+  return {
+    async bundle(record: ManagedBundle, request: PrettyRequest): Promise<OpenedBlob> {
+      const copy = await kept(() => bundles.open(record.id, prettyFile(request)))
+      if (copy) return copy
+      return opened(await bundleCopy(record, request, async () => {
+        const text = bundleSourcesAsMap(await bundleDetails(record)).get(request.path)
+        if (text === undefined) throw new PrettyError(404, 'no-file')
+        if (await computeFileHash(text) !== request.hash) throw new PrettyError(409, 'hash-mismatch')
+        return text
+      }))
+    },
+    // The version's file, from its files loaded as the viewer's are (and
+    // held to the same few loads at once).
+    npm(doc: NpmVersionDocument, request: PrettyRequest): Promise<OpenedBlob> {
+      return npmCopy(doc, request, async () => {
+        const load = loadNpmFiles(doc)
+        let text: string | null
+        try {
+          const bytes = (await load.result).find(entry => entry.path === request.path)?.bytes
+          if (!bytes) throw new PrettyError(404, 'no-file')
+          if (await computeFileHash(bytes) !== request.hash) throw new PrettyError(409, 'hash-mismatch')
+          text = npmFileText(bytes)
+        } finally { load.release() }
+        if (text === null) throw new PrettyError(422, 'unformattable')
+        return text
+      })
+    },
+    // Every file of the version that needs pretty-printing (npmPrintable),
+    // read before this resolves; then, as they are iterated, each
+    // pretty-printed as `npm` has it, one after another.
+    async npmAll(doc: NpmVersionDocument): Promise<AsyncGenerator<PrettyLine>> {
+      const files = await npmPrintable(doc)
+      return (async function* () {
+        for (const { text, ...request } of files) yield await prettyLine(request, () => npmCopy(doc, request, () => Promise.resolve(text)))
+      })()
+    },
+    // Two bundles' sides, or two versions', as a comparison reads them, read
+    // before this resolves: for the files that changed between them
+    // pretty-printed (compared), and their diffs with renamed names hidden
+    // (rename-diff.ts renamedPairs); a bundle's within a reason `scope`
+    // where one is asked for, as Compare reads it then.
+    async bundleSides(base: ManagedBundle, other: ManagedBundle, scope = ''): Promise<[ComparedSide, ComparedSide]> {
+      const sideOf = async (record: ManagedBundle, side: Side): Promise<ComparedSide> => ({ side, ...await bundleSide(await bundleDetails(record), scope),
+        kept: request => kept(() => bundles.open(record.id, prettyFile(request))),
+        made: async (request, text) => opened(await bundleCopy(record, request, () => Promise.resolve(text))) })
+      return [await sideOf(base, 'base'), await sideOf(other, 'other')]
+    },
+    async npmSides(base: NpmVersionDocument, other: NpmVersionDocument): Promise<[ComparedSide, ComparedSide]> {
+      const sideOf = async (doc: NpmVersionDocument, side: Side): Promise<ComparedSide> => ({ side, ...await sideFiles(await npmFiles(doc)), packageDirs: null,
+        kept: request => (doc.private ? Promise.resolve(null) : kept(() => npm.open(prettyFile(request)))),
+        made: (request, text) => npmCopy(doc, request, () => Promise.resolve(text)) })
+      return [await sideOf(base, 'base'), await sideOf(other, 'other')]
+    },
+  }
+}
+export type PrettyCache = ReturnType<typeof createPrettyCache>