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

package/server-managed/npm-packages.ts

@@ -0,0 +1,454 @@
+// The managed npm package viewer: a published version's files, read from the
+// registry's tarball, for the Overview and Code tabs the bundle view shows.
+//
+// Anyone with workspace access may read a public package. A private one also
+// needs NPM_TOKEN on the server, and a reader with access to it: an admin or
+// manager, or a member of a visible team listing its scope (team-npm-scopes.ts).
+// For everyone else, a version is public only when the registry answers for
+// it without credentials, asked on every request and never from a cache:
+// upstream's caches, which bundle builds fill using the token, hold no
+// answer here. Its tarball may come from them (npm-loads.ts), as only bytes
+// matching the integrity that anonymous answer gives are served; else it is
+// read without credentials too, and held to that integrity.
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { rm } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { ArchiveError, type Entry, unpack } from '@preventive/archive/tar.js'
+import { isExactVersion } from '@preventive/upstream/semver.js'
+import { isNpmPackageName, isNpmPackageSpec, npmPackageScope } from '../common/managed/npm-packages.js'
+import type { Role } from '../common/managed/roles.ts'
+import { npmManifest, npmVersionFields, plainObject, stringRecord } from './npm-manifest.ts'
+import { keepJson, readKeptJson, upstreamCachePath } from './upstream-cache.ts'
+
+export { npmManifest, plainObject }
+
+export const NPM_REGISTRY = 'https://registry.npmjs.org'
+const VERSION_DOCUMENT_BYTES = 8 * 1024 * 1024
+// Abbreviated packuments of packages with thousands of versions run to tens of MiB.
+const PACKUMENT_BYTES = 64 * 1024 * 1024
+// What registry documents being read at once may hold, each counted at its
+// limit until it is read and parsed: four packuments, or 32 version documents.
+const MAX_DOCUMENT_BYTES = 4 * PACKUMENT_BYTES
+// What a package may unpack to: the files' bytes and their count; the tar
+// stream holding them is bounded in npm-loads.ts. A repository directory's
+// are its own (repository-code.ts).
+export const MAX_NPM_PACKAGE_BYTES = 64 * 1024 * 1024
+export const MAX_NPM_PACKAGE_FILES = 20_000
+// The entries its tar stream may hold, read before any is counted as a file:
+// a directory's too, though npm packs none.
+export const MAX_NPM_TAR_ENTRIES = 2 * MAX_NPM_PACKAGE_FILES
+// What the files may take as the viewer's JSON. Escaping grows a text up to
+// six times (a control character becomes `\u0001`), so it is counted before
+// anything is serialized.
+export const MAX_NPM_JSON_LENGTH = 96 * 1024 * 1024
+export class NpmPackageError extends Error {
+  status: number
+  constructor(status: number, code: string) { super(code); this.status = status }
+}
+
+// Who reads, as the session has it now: the role, and the scopes of the
+// visible teams they are a member of, where those count (npmScopesCount).
+export interface NpmReader { role: Role; scopes: ReadonlySet<string>; userId: string }
+
+// Whether a reader may have a package read with the server's token.
+export function canReadPrivateNpm(reader: NpmReader, name: string): boolean {
+  if (reader.role === 'admin' || reader.role === 'manage') return true
+  const scope = npmPackageScope(name)
+  return scope !== null && reader.scopes.has(scope)
+}
+
+// Whether a reader's team scopes count for any of `names`, as
+// canReadPrivateNpm reads them: a scoped one, read by someone below manager.
+export const npmScopesCount = (role: Role, names: readonly string[]): boolean =>
+  role !== 'admin' && role !== 'manage' && names.some(name => npmPackageScope(name) !== null)
+
+export const npmToken = () => process.env['NPM_TOKEN'] || null
+
+// Whether a read of `name` that npm answers none anonymously is asked again
+// with the server's token: by a reader with private access (`privileged`),
+// where there is a token and the package is scoped, as npm's private packages
+// always are. Else the anonymous answer is the reader's.
+export const npmTokenReads = (name: string, privileged: boolean): boolean => privileged && npmToken() !== null && npmPackageScope(name) !== null
+
+function registryUrl(name: string, spec?: string): string {
+  return `${NPM_REGISTRY}/${name}${spec === undefined ? '' : `/${encodeURIComponent(spec)}`}`
+}
+
+// What an upstream (npm's registry and APIs, Socket, GitHub) answers, read
+// whole: null where it says it has none (`absent`, 404 unless said). Asked
+// without redirects, and given up on after `ms`, 30 seconds unless said, or
+// once `signal` aborts, its abort rethrown as it is; a 502 where it can't be
+// asked, answers otherwise or stops, and `upstream-too-large` past `limit`
+// bytes (readLimited). `answered` sees the response first, its status and
+// headers.
+export async function askUpstream(url: string, { limit, ms = 30_000, signal, absent = [404], answered, ...init }: Omit<RequestInit, 'signal'>
+  & { limit: number; ms?: number; signal?: AbortSignal; absent?: number[]; answered?: (res: Response) => void }): Promise<Buffer | null> {
+  try {
+    const res = await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.any([AbortSignal.timeout(ms), ...signal ? [signal] : []]) })
+    answered?.(res)
+    if (absent.includes(res.status)) { await res.body?.cancel(); return null }
+    if (!res.ok) { await res.body?.cancel(); throw new NpmPackageError(502, 'upstream-unavailable') }
+    return await readLimited(res, limit)
+  } catch (err) {
+    if (signal?.aborted || err instanceof NpmPackageError) throw err
+    throw new NpmPackageError(502, 'upstream-unavailable')
+  }
+}
+
+// The same, read as JSON (by `parse`, as one line of ndjson): a 502
+// `upstream-invalid` where it isn't.
+export async function askUpstreamJson(url: string, options: Parameters<typeof askUpstream>[1], parse = (text: string): unknown => JSON.parse(text)): Promise<unknown> {
+  const body = await askUpstream(url, options)
+  if (body === null) return null
+  try { return parse(body.toString('utf8')) } catch { throw new NpmPackageError(502, 'upstream-invalid') }
+}
+
+export async function readLimited(res: Response, limit: number): Promise<Buffer> {
+  const declared = Number(res.headers.get('content-length'))
+  if (declared > limit) { await res.body?.cancel(); throw new NpmPackageError(502, 'upstream-too-large') }
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of res.body ?? []) {
+    size += chunk.byteLength
+    if (size > limit) throw new NpmPackageError(502, 'upstream-too-large')
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+// A registry document, or null where the registry has none for this caller:
+// 404, or 401/403 as it answers some private packages asked anonymously.
+// Credentials go only with `token`; nothing is cached on either side, but for
+// public whole documents (publicWholeDocument).
+async function registryDocument(url: string, { token, accept, limit, signal }: { token: string | null; accept: string; limit: number; signal: AbortSignal }): Promise<Record<string, unknown> | null> {
+  const json = await askUpstreamJson(url, { headers: { accept, ...(token ? { authorization: `Bearer ${token}` } : {}) }, limit, signal, absent: [401, 403, 404] })
+  if (json === null || plainObject(json)) return json
+  throw new NpmPackageError(502, 'upstream-invalid')
+}
+
+// Where public packages' whole documents are kept, off Vercel: the upstream
+// cache dir, set at startup (index.ts); null keeps none.
+let documentCache: string | null = null
+export const setNpmDocumentCache = (dir: string | null) => { documentCache = dir === null ? null : resolve(dir) }
+
+// A package's whole document as npm answers anyone (`url` its own), kept on
+// disk where the server keeps them (setNpmDocumentCache) with npm's ETag, and
+// asked for again each time with it: npm answers 304, and nothing more, while
+// it is unchanged. Null where npm has none for anyone, nothing then kept.
+async function publicWholeDocument(name: string, url: string, { limit, signal }: { limit: number; signal: AbortSignal }): Promise<Record<string, unknown> | null> {
+  const path = documentCache === null ? null : upstreamCachePath(documentCache, 'npm/packuments', `${name}.json.gz`)
+  const kept = path === null ? null : await readKeptJson(path, limit)
+  let etag: string | null = null, status = 0
+  const body = await askUpstream(url, { headers: { accept: 'application/json', ...kept && { 'if-none-match': kept.etag } }, limit, signal, absent: [304, 401, 403, 404],
+    answered: res => { status = res.status; etag = res.headers.get('etag') } })
+  if (status === 304 && kept) return kept.json
+  if (body === null) {
+    if (path !== null && kept) await rm(path, { force: true }).catch(() => {})
+    return null
+  }
+  let json: unknown
+  try { json = JSON.parse(body.toString('utf8')) } catch { throw new NpmPackageError(502, 'upstream-invalid') }
+  if (!plainObject(json)) throw new NpmPackageError(502, 'upstream-invalid')
+  if (path !== null && etag !== null) await keepJson(path, etag, body)
+  return json
+}
+
+// Whole documents being asked of npm as anyone asks, by URL and limit:
+// readers asking for one meanwhile share it, as opening a version asks for
+// its package's for its versions, its advisories and its risk at once; each
+// gives up on it alone once its own signal aborts, and it is given up on once
+// they all have. None is asked with the token. Read alike by every reader,
+// none changing it.
+const wholeAsks = new Map<string, { asked: Promise<Record<string, unknown> | null>; controller: AbortController; readers: number }>()
+
+function sharedWholeDocument(name: string, url: string, { limit, signal }: { limit: number; signal: AbortSignal }): Promise<Record<string, unknown> | null> {
+  if (signal.aborted) return Promise.reject(signal.reason)
+  const key = `${url} ${limit}`
+  let ask = wholeAsks.get(key)
+  if (!ask) {
+    const controller = new AbortController()
+    const created = { asked: publicWholeDocument(name, url, { limit, signal: controller.signal }), controller, readers: 0 }
+    const settle = () => { if (wholeAsks.get(key) === created) wholeAsks.delete(key) }
+    created.asked.then(settle, settle)
+    wholeAsks.set(key, ask = created)
+  }
+  const held = ask
+  held.readers++
+  return new Promise((answer, fail) => {
+    let left = false
+    const leave = () => {
+      if (left) return false
+      left = true
+      held.readers--
+      signal.removeEventListener('abort', onAbort)
+      return true
+    }
+    const onAbort = () => {
+      if (!leave()) return
+      if (held.readers === 0) {
+        if (wholeAsks.get(key) === held) wholeAsks.delete(key)
+        held.controller.abort(signal.reason)
+      }
+      fail(signal.reason)
+    }
+    const answered = (json: Record<string, unknown> | null) => { if (leave()) answer(json) }
+    const failed = (err: unknown) => { if (leave()) fail(err) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    held.asked.then(answered, failed)
+  })
+}
+
+// Asked anonymously first, unless its caller knows npm has none for anyone
+// (`anonymous` false): a reader without private access stops there. One
+// with it asks again with the token where npmTokenReads says so, and the
+// answer is private. A whole document (`whole`) anyone may read is kept
+// (publicWholeDocument), and asked once for those asking at once
+// (sharedWholeDocument).
+async function readDocument(name: string, url: string, privileged: boolean,
+  { whole = false, anonymous = true, ...options }: { accept: string; limit: number; signal: AbortSignal; whole?: boolean; anonymous?: boolean }) {
+  const open = anonymous ? whole ? await sharedWholeDocument(name, url, options) : await registryDocument(url, { ...options, token: null }) : null
+  if (open) return { json: open, private: false }
+  if (!npmTokenReads(name, privileged)) return null
+  const json = await registryDocument(url, { ...options, token: npmToken() })
+  return json ? { json, private: true } : null
+}
+
+let documentBytes = 0
+
+// A `spare` read, one no reader waits on, is made only where it leaves room
+// for two of the largest documents more: readers' own reads come first.
+async function withDocumentBudget<T>(limit: number, read: () => Promise<T>, spare = false): Promise<T> {
+  if (documentBytes + limit + (spare ? 2 * PACKUMENT_BYTES : 0) > MAX_DOCUMENT_BYTES) throw new NpmPackageError(429, 'npm-busy')
+  documentBytes += limit
+  try { return await read() } finally { documentBytes -= limit }
+}
+
+export interface NpmVersionDocument {
+  name: string
+  version: string
+  private: boolean
+  // `shasum`, the tarball's sha1 in hex, where npm tells it: held, with the
+  // integrity, to the tarball its files are read from (npm-loads.ts).
+  dist: { tarball: string; integrity: string; shasum: string | null; unpackedSize: number | null; fileCount: number | null }
+  manifest: Record<string, unknown>
+}
+
+const count = (value: unknown) => Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : null
+
+// The version `json`, a document of package `name`, tells of.
+function versionDocument(name: string, json: Record<string, unknown>, isPrivate: boolean): NpmVersionDocument {
+  const dist = json['dist']
+  if (json['name'] !== name || typeof json['version'] !== 'string' || !isNpmPackageSpec(json['version']) || !plainObject(dist)
+      || typeof dist['tarball'] !== 'string' || typeof dist['integrity'] !== 'string'
+      || (dist['shasum'] !== undefined && typeof dist['shasum'] !== 'string')) throw new NpmPackageError(502, 'upstream-invalid')
+  return {
+    name, version: json['version'], private: isPrivate,
+    dist: { tarball: dist['tarball'], integrity: dist['integrity'], shasum: typeof dist['shasum'] === 'string' ? dist['shasum'] : null,
+      unpackedSize: count(dist['unpackedSize']), fileCount: count(dist['fileCount']) },
+    manifest: npmManifest(json),
+  }
+}
+
+// Where public versions' documents are kept, of the fields read of them
+// (npm-manifest.ts npmVersionFields), as the database keeps them (npm-kept.ts).
+export interface NpmVersionStore {
+  read(name: string, version: string): Promise<{ at: number; json: Record<string, unknown> } | null>
+  // Those of `versions` kept, by `name@version`, in one read.
+  readMany?(versions: { name: string; version: string }[]): Promise<Map<string, { at: number; json: Record<string, unknown> }>>
+  write(name: string, version: string, json: Record<string, unknown>): Promise<void>
+}
+
+// The version a spec names, a dist-tag resolved by the registry, with its
+// dist. Null where the registry has none for this reader. With `store`, an
+// exact version kept there for less than a day (VERSION_KEPT_MS) is read from
+// it, not asked of npm, and a public one npm answers is kept. npm never
+// changes a version's files, but its document can change: a deprecation, the
+// package made private (a scoped one can be), the version removed (which whoever
+// reads it from a store learns elsewhere too: risk does). A day bounds each.
+// One kept with no shasum, as none was before it was kept (npmVersionFields),
+// is asked of npm again, which tells one of each version.
+export const VERSION_KEPT_MS = 24 * 60 * 60_000
+export function readNpmVersion(name: string, spec: string, privileged: boolean, signal: AbortSignal, store?: NpmVersionStore): Promise<NpmVersionDocument | null> {
+  if (!isNpmPackageName(name) || !isNpmPackageSpec(spec)) return Promise.reject(new NpmPackageError(400, 'bad-package'))
+  // A kept one is read within the same budget as npm's answer.
+  return withDocumentBudget(VERSION_DOCUMENT_BYTES, async () => {
+    const kept = store && isExactVersion(spec) ? await store.read(name, spec) : null
+    const keptDist = kept?.json['dist']
+    if (kept && Date.now() - kept.at < VERSION_KEPT_MS && plainObject(keptDist) && typeof keptDist['shasum'] === 'string') {
+      try { return versionDocument(name, kept.json, false) } catch {}
+    }
+    const found = await readDocument(name, registryUrl(name, spec), privileged, { accept: 'application/json', limit: VERSION_DOCUMENT_BYTES, signal })
+    if (!found) return null
+    const doc = versionDocument(name, found.json, found.private)
+    if (store && !found.private) await store.write(name, doc.version, npmVersionFields(found.json))
+    return doc
+  })
+}
+
+// `store`, where it reads many at once, with the exact ones of `versions`
+// read from it in one read, for readNpmVersion to read each of those from as
+// it asks: a version and the one it is compared with, read together.
+export function readTogether(store: NpmVersionStore, versions: { name: string; version: string }[]): NpmVersionStore {
+  const exact = versions.filter(({ version }) => isExactVersion(version))
+  if (!store.readMany || exact.length < 2) return store
+  const keys = new Set(exact.map(({ name, version }) => `${name}@${version}`))
+  const kept = store.readMany(exact)
+  return { ...store, async read(name, version) {
+    const key = `${name}@${version}`
+    return keys.has(key) ? (await kept).get(key) ?? null : store.read(name, version)
+  } }
+}
+
+// The package's dist-tags and versions, newest published first, from its
+// abbreviated document; with `times`, from its whole one, which alone has
+// when each was published, `times` by version (ISO dates), and `created`,
+// when its first version was, one since unpublished among them: the earliest
+// time it lists, which npm's own `created` can postdate, as a placeholder's
+// does for a package npm took down. With `spare`, as a read no reader waits
+// on (withDocumentBudget). Null where the registry has none for this reader.
+export function readNpmVersions(name: string, privileged: boolean, signal: AbortSignal, { times = false, spare = false } = {}) {
+  if (!isNpmPackageName(name)) return Promise.reject(new NpmPackageError(400, 'bad-package'))
+  return withDocumentBudget(PACKUMENT_BYTES, async () => {
+    const accept = times ? 'application/json' : 'application/vnd.npm.install-v1+json'
+    const found = await readDocument(name, registryUrl(name), privileged, { accept, limit: PACKUMENT_BYTES, signal, whole: times })
+    if (!found) return null
+    const { json } = found
+    if (json['name'] !== name || !plainObject(json['versions'])) throw new NpmPackageError(502, 'upstream-invalid')
+    const versions = Object.keys(json['versions']).filter(isNpmPackageSpec).toReversed()
+    const distTags = Object.fromEntries(Object.entries(stringRecord(json['dist-tags']) ?? {}).filter(([, version]) => versions.includes(version)))
+    const listed = { name, private: found.private, distTags, versions }
+    if (!times) return listed
+    const time = stringRecord(json['time']) ?? {}
+    const published = Object.fromEntries(versions.filter(version => isPublishTime(time[version])).map(version => [version, time[version]!]))
+    for (const [version, at] of Object.entries(published)) publishTimes.set(`${name}@${version}`, at)
+    while (publishTimes.size > PUBLISH_TIMES) publishTimes.delete(publishTimes.keys().next().value!)
+    const listedAt = Object.entries(time).filter(([key, at]) => key !== 'modified' && isPublishTime(at)).map(([, at]) => at)
+    const created = listedAt.reduce<string | null>((first, at) => first === null || Date.parse(at) < Date.parse(first) ? at : first, null)
+    return { ...listed, times: published, created }
+  }, spare)
+}
+
+// A package's whole document as npm has it for this reader, for risk
+// (npm-risk.ts), within the bounds and budget every document read here is
+// held to; null where npm has none for this reader, or the name is none npm
+// takes. With `anonymous` false, where npm is known to have none for anyone,
+// it is asked only with the token (readDocument).
+export function readNpmPackument(name: string, privileged: boolean, signal: AbortSignal, { anonymous = true } = {}): Promise<Record<string, unknown> | null> {
+  if (!isNpmPackageName(name)) return Promise.resolve(null)
+  return withDocumentBudget(PACKUMENT_BYTES, async () => (await readDocument(name, registryUrl(name), privileged,
+    { accept: 'application/json', limit: PACKUMENT_BYTES, signal, whole: true, anonymous }))?.json ?? null)
+}
+
+const isPublishTime = (value: string | undefined) => typeof value === 'string' && value.length <= 40 && !Number.isNaN(Date.parse(value))
+
+// When each version was published, by `name@version`, as whole documents read
+// with `times` have said: a version keeps its time once published, so it is
+// kept for as long as the server runs, the first noted going first past a
+// bound, and answered only with the version, once its reader's access is.
+const PUBLISH_TIMES = 100_000
+const publishTimes = new Map<string, string>()
+
+// Where public versions' publish times are kept beyond the instance, as the
+// database keeps them (npm-kept.ts npmPublishTimeStore).
+export interface NpmPublishTimeStore {
+  read(name: string, version: string): Promise<string | null>
+  write(name: string, version: string, at: string): Promise<void>
+}
+
+// When `doc` was published: as noted here, else as `store` keeps a public
+// version's, so that another instance, or this one restarted, has it before
+// it reads the whole document again. The store is read once, at once, beside
+// whatever its caller reads meanwhile, a failure read as none; `read` looks
+// here again as it is asked, as the whole document read meanwhile may have
+// noted it by then, and `keep` keeps there the time noted here where it read
+// none.
+export function npmPublishTime(doc: Pick<NpmVersionDocument, 'name' | 'version' | 'private'>, store?: NpmPublishTimeStore) {
+  const noted = () => publishTimes.get(`${doc.name}@${doc.version}`) ?? null
+  const kept = store && !doc.private ? store.read(doc.name, doc.version).catch(() => null) : Promise.resolve(null)
+  return {
+    read: async (): Promise<string | null> => noted() ?? await kept ?? noted(),
+    async keep() {
+      const at = noted()
+      if (at !== null && store && !doc.private && await kept === null) await store.write(doc.name, doc.version, at)
+    },
+  }
+}
+
+export interface NpmPackageFile { path: string; bytes: Uint8Array }
+
+// How a tar stream is read (readNpmTar): how far its symlinks may climb above
+// it, and the entries, files and bytes it may hold, a package's unless given.
+export interface TarReading { symlinksAbove?: number; maxEntries?: number; maxFiles?: number; maxBytes?: number }
+
+// The regular files of a tar stream, by package path: npm drops the first
+// component (`package/`, or whatever the archive used), and a file at the top
+// is not extracted. The stream is read by @preventive/archive, which refuses
+// one malformed, a name or a symlink that would climb out of it -- a symlink
+// past `symlinksAbove` levels above it, none unless given -- and a name
+// repeated as another entry, and gives up past `maxEntries` before reading
+// on; a file under another top directory at the same path replaces an
+// earlier one, as extraction would. Directories, links and devices hold no
+// file content and are skipped.
+export function readNpmTar(tar: Uint8Array, { symlinksAbove = 0, maxEntries = MAX_NPM_TAR_ENTRIES, maxFiles = MAX_NPM_PACKAGE_FILES,
+  maxBytes = MAX_NPM_PACKAGE_BYTES }: TarReading = {}): NpmPackageFile[] {
+  let entries: Entry[]
+  try { entries = unpack(tar, { maxEntries, symlinksAbove }) }
+  catch (err) {
+    if (err instanceof ArchiveError) throw err.limited ? new NpmPackageError(413, 'package-too-large') : new NpmPackageError(422, 'bad-tarball')
+    throw err
+  }
+  const files = new Map<string, Uint8Array>()
+  let total = 0
+  for (const { name, type, data } of entries) {
+    const slash = name.indexOf('/')
+    if ((type !== 'file' && type !== 'contiguous-file') || slash === -1) continue
+    const path = name.slice(slash + 1)
+    total += data.length - (files.get(path)?.length ?? 0)
+    files.set(path, data)
+    if (files.size > maxFiles || total > maxBytes) throw new NpmPackageError(413, 'package-too-large')
+  }
+  return [...files].map(([path, bytes]) => ({ path, bytes })).toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+// A file's text, or null for bytes that are not UTF-8 text.
+export function npmFileText(bytes: Uint8Array): string | null {
+  if (bytes.includes(0)) return null
+  try { return utf8.decode(bytes) } catch { return null }
+}
+
+// A string's length in JSON: quotes, backslashes and the control characters
+// with a short escape take two characters, the other control characters six.
+function jsonLength(text: string): number {
+  let length = text.length + 2
+  for (let i = 0; i < text.length; i++) {
+    const code = text.codePointAt(i)!
+    if (code === 0x22 || code === 0x5c) length += 1
+    else if (code < 0x20) length += code >= 0x08 && code <= 0x0d && code !== 0x0b ? 1 : 5
+  }
+  return length
+}
+
+// A row's brackets, size, null and digest, past its strings.
+const ROW_LENGTH = 80
+
+// The files as the viewer gets them: `[path, bytes, text]`, text null for a
+// file that is not UTF-8, which instead carries its bytes' sha256, so a
+// comparison of two versions tells a changed one from an unchanged one. They
+// may take `maxLength` characters of JSON, a package's unless given.
+export function npmFileRows(files: NpmPackageFile[], maxLength = MAX_NPM_JSON_LENGTH): ([string, number, string] | [string, number, null, string])[] {
+  let length = 0
+  return files.map(({ path, bytes }) => {
+    const text = npmFileText(bytes)
+    length += ROW_LENGTH + jsonLength(path) + (text === null ? 0 : jsonLength(text))
+    if (length > maxLength) throw new NpmPackageError(413, 'package-too-large')
+    return text === null ? [path, bytes.byteLength, null, `sha256-${createHash('sha256').update(bytes).digest('base64')}`] : [path, bytes.byteLength, text]
+  })
+}
+
+// The tarball's filename as `npm pack` writes it.
+export function npmTarballFilename(name: string, version: string): string {
+  return `${name.replace(/^@/u, '').replace('/', '-')}-${version}.tgz`
+}

package/server-managed/npm-provenance.ts

@@ -0,0 +1,123 @@
+// npm's provenance for a public version (npm-packages.ts npmManifest marks
+// one that has it): the SLSA statement npm's registry keeps beside it,
+// saying where the version was built: from which repository and commit, by
+// which workflow, on which builder, in which run, with its entry in
+// Sigstore's transparency log. Only a statement naming this version's
+// tarball (its name, version and sha512 digest) is read; its signature isn't
+// checked here, as npm checks it when the version is published. npm is asked
+// without the server's token, and only about a version it answers for
+// without one (http.ts), each answer kept as npm-insights.ts keeps its own.
+import { Buffer } from 'node:buffer'
+import { kept } from './kept.ts'
+import { NPM_REGISTRY, askUpstreamJson, plainObject } from './npm-packages.ts'
+
+const ATTESTATIONS_API = `${NPM_REGISTRY}/-/npm/v1/attestations`
+const ATTESTATIONS_BYTES = 1024 * 1024
+// SLSA's v1 statement, as npm writes it now, and v0.2, as it first did.
+const SLSA = /^https:\/\/slsa\.dev\/provenance\/v(?:1|0\.2)$/u
+const COMMIT = /^[0-9a-f]{40}$/u
+const GITHUB_REPOSITORY = /^https:\/\/github\.com\/([\w.-]+\/[\w.-]+)$/u
+
+// Where a version was built: its source `repository` (an https URL) and
+// `commit`, the `workflow` file and the `ref` it ran on, the `builder` and
+// the `run` (an https URL), its transparency log entry (`logIndex`), and
+// whose runner built it (`runner`: `github-hosted`, `gitlab-hosted` or
+// `self-hosted`, as its signing certificate says); each null where they
+// don't say.
+export interface NpmProvenance {
+  repository: string; commit: string | null; workflow: string | null; ref: string | null
+  builder: string | null; run: string | null; logIndex: number | null; runner: string | null
+}
+
+const text = (value: unknown) => typeof value === 'string' && value !== '' && value.length <= 2048 ? value : null
+const https = (value: unknown) => {
+  const url = text(value)
+  try { return url && new URL(url).protocol === 'https:' ? url : null } catch { return null }
+}
+// `git+https://github.com/org/repo@refs/heads/main` → the repository and
+// ref; GitLab's names no ref (`git+https://gitlab.com/group/project`).
+function sourceOf(uri: unknown) {
+  const match = /^git\+(https:\/\/[^@\s]+?)(?:\.git)?(?:@(.+))?$/u.exec(text(uri) ?? '')
+  return match ? { repository: https(match[1]), ref: match[2] ?? null } : { repository: null, ref: null }
+}
+// What `keys` lead to in `value`, through objects and arrays.
+const field = (value: unknown, ...keys: string[]): unknown =>
+  keys.reduce<unknown>((at, key) => plainObject(at) || Array.isArray(at) ? (at as Record<string, unknown>)[key] : undefined, value)
+
+// What a statement says of the build, as v1 or v0.2 says it; null where it
+// names no source repository.
+function readStatement(predicateType: string, predicate: unknown): NpmProvenance | null {
+  if (predicateType.endsWith('v1')) {
+    const workflow = field(predicate, 'buildDefinition', 'externalParameters', 'workflow')
+    const source = field(predicate, 'buildDefinition', 'resolvedDependencies', '0')
+    const repository = https(field(workflow, 'repository')) ?? sourceOf(field(source, 'uri')).repository
+    if (!repository) return null
+    const commit = text(field(source, 'digest', 'gitCommit'))
+    return {
+      repository, commit: commit && COMMIT.test(commit) ? commit : null, workflow: text(field(workflow, 'path')),
+      ref: text(field(workflow, 'ref')) ?? sourceOf(field(source, 'uri')).ref, builder: https(field(predicate, 'runDetails', 'builder', 'id')),
+      run: https(field(predicate, 'runDetails', 'metadata', 'invocationId')), logIndex: null, runner: null,
+    }
+  }
+  const config = field(predicate, 'invocation', 'configSource')
+  const { repository, ref } = sourceOf(field(config, 'uri'))
+  if (!repository) return null
+  const commit = text(field(config, 'digest', 'sha1'))
+  // Its run: GitLab's job URL, or GitHub's as `<run id>-<attempt>`.
+  const invocation = field(predicate, 'metadata', 'buildInvocationId')
+  const run = /^(\d+)-(\d+)$/u.exec(text(invocation) ?? '')
+  const github = GITHUB_REPOSITORY.exec(repository)?.[1]
+  return {
+    repository, commit: commit && COMMIT.test(commit) ? commit : null, workflow: text(field(config, 'entryPoint')), ref,
+    builder: https(field(predicate, 'builder', 'id')),
+    run: https(invocation) ?? (run && github ? `https://github.com/${github}/actions/runs/${run[1]}/attempts/${run[2]}` : null), logIndex: null, runner: null,
+  }
+}
+
+// Fulcio's Runner Environment extension (1.3.6.1.4.1.57264.1.11) in the
+// certificate that signed it: its OID, then its value, a short UTF8String
+// in an OCTET STRING, as the CI's token gave it. A builder's id doesn't
+// tell GitLab's own runners from a project's.
+const RUNNER_ENVIRONMENT = Buffer.from('060a2b0601040183bf30010b', 'hex')
+function runnerOf(bundle: unknown): string | null {
+  const raw = field(bundle, 'verificationMaterial', 'certificate', 'rawBytes') ?? field(bundle, 'verificationMaterial', 'x509CertificateChain', 'certificates', '0', 'rawBytes')
+  if (typeof raw !== 'string') return null
+  const der = Buffer.from(raw, 'base64')
+  const at = der.indexOf(RUNNER_ENVIRONMENT) + RUNNER_ENVIRONMENT.length
+  if (at < RUNNER_ENVIRONMENT.length || der[at] !== 0x04 || der[at + 2] !== 0x0c || der[at + 1] !== der[at + 3]! + 2) return null
+  return text(der.subarray(at + 4, at + 4 + der[at + 3]!).toString('utf8'))
+}
+
+async function askProvenance(name: string, version: string, integrity: string): Promise<NpmProvenance | null> {
+  const json = await askUpstreamJson(`${ATTESTATIONS_API}/${name.replace('/', '%2f')}@${encodeURIComponent(version)}`,
+    { headers: { accept: 'application/json' }, limit: ATTESTATIONS_BYTES })
+  if (json === null) return null
+  const attestations: unknown[] = Array.isArray(field(json, 'attestations')) ? field(json, 'attestations') as unknown[] : []
+  const slsa = attestations.find(item => SLSA.test(text(field(item, 'predicateType')) ?? ''))
+  if (!slsa) return null
+  // The statement, whatever its length (the answer is bounded as a whole),
+  // unlike the fields read out of it.
+  const payload = field(slsa, 'bundle', 'dsseEnvelope', 'payload')
+  let statement: unknown
+  try { statement = JSON.parse(Buffer.from(typeof payload === 'string' ? payload : '', 'base64').toString('utf8')) } catch { return null }
+  // Only one naming this version's tarball: its purl, and its digest as the
+  // version's integrity has it.
+  const purl = `pkg:npm/${name.replace(/^@/u, '%40')}@${version}`
+  const digest = /^sha512-(.+)$/u.exec(integrity)?.[1]
+  const subjects: unknown[] = Array.isArray(field(statement, 'subject')) ? field(statement, 'subject') as unknown[] : []
+  if (!digest || !subjects.some(subject => field(subject, 'name') === purl && field(subject, 'digest', 'sha512') === Buffer.from(digest, 'base64').toString('hex'))) return null
+  const provenance = readStatement(text(field(slsa, 'predicateType'))!, field(statement, 'predicate'))
+  const logIndex = Number(field(slsa, 'bundle', 'verificationMaterial', 'tlogEntries', '0', 'logIndex'))
+  return provenance && { ...provenance, logIndex: Number.isSafeInteger(logIndex) && logIndex >= 0 ? logIndex : null, runner: runnerOf(field(slsa, 'bundle')) }
+}
+
+const provenances = kept<NpmProvenance | null>(1000)
+
+// npm's provenance for a version of a public package, its tarball's
+// `integrity` as the registry has it; null where npm keeps none for it.
+export function npmProvenance(name: string, version: string, integrity: string): Promise<NpmProvenance | null> {
+  return provenances(`${name}@${version}`, () => askProvenance(name, version, integrity))
+}
+
+// One kept, asking for nothing; undefined where none is.
+export const keptNpmProvenance = (name: string, version: string) => provenances.peek(`${name}@${version}`)