@preventive/upstream 1.0.0-alpha.0

package/src/advisories/index.js

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+
+import { assertArgs, assertBoolean, assertRepo, assertion, optional, sameName } from '../args.js'
+import { order } from './common.js'
+import { GITHUB, assertClient } from './github.js'
+import { NPM } from './npm.js'
+import { CARGO, COMPOSER } from './osv.js'
+
+const ECOSYSTEMS = { npm: NPM, cargo: CARGO, composer: COMPOSER, github: GITHUB }
+const byNumbers = new Intl.Collator('en', { numeric: true }).compare
+const assertEcosystem = assertion(`one of ${Object.keys(ECOSYSTEMS).join(', ')}`, (value) => typeof value === 'string' && Object.hasOwn(ECOSYSTEMS, value))
+const assertVersions = assertion('a non-empty array', (value) => Array.isArray(value) && value.length > 0)
+
+// Ecosystem → name → { versions, github? }, a name given twice merged.
+// Every package is checked before any is used.
+function collect(packages) {
+  assert.ok(typeof packages?.[Symbol.iterator] === 'function' && typeof packages !== 'string', 'advisories: packages must be an iterable of { ecosystem, name, github?, versions }')
+  const byEcosystem = new Map()
+  for (const pkg of packages) {
+    assertArgs('advisories', pkg, { ecosystem: assertEcosystem, name: null, github: optional(assertRepo), versions: assertVersions }, 'package')
+    const { assertName, assertVersion } = ECOSYSTEMS[pkg.ecosystem]
+    assertName('advisories', 'package.name', pkg.name)
+    for (const version of pkg.versions) assertVersion('advisories', 'package.versions', version)
+    assert.ok(pkg.ecosystem !== 'github' || pkg.github === undefined, 'advisories: a github package is its own repository, and takes no package.github')
+    const named = byEcosystem.get(pkg.ecosystem) ?? byEcosystem.set(pkg.ecosystem, new Map()).get(pkg.ecosystem)
+    // A repository's name is GitHub's, in any case: the first spelling stands.
+    const name = pkg.ecosystem === 'github' ? [...named.keys()].find((known) => sameName(known, pkg.name)) ?? pkg.name : pkg.name
+    const entry = named.get(name) ?? named.set(name, { versions: new Set() }).get(name)
+    assert.ok(pkg.github === undefined || entry.github === undefined || sameName(entry.github, pkg.github), `advisories: ${pkg.name} is given two repositories`)
+    entry.github ??= pkg.github
+    for (const version of pkg.versions) entry.versions.add(version)
+  }
+  return byEcosystem
+}
+
+export async function advisories(packages, options = {}) {
+  assertArgs('advisories', options, { github: optional(assertClient), repoAdvisories: optional(assertBoolean) })
+  assert.ok(!options.repoAdvisories || options.github, 'advisories: repoAdvisories needs a github client')
+  const byEcosystem = collect(packages)
+  assert.ok(!byEcosystem.has('github') || options.github, 'advisories: github packages need a github client')
+  const found = await Promise.all([...byEcosystem].map(async ([ecosystem, named]) => {
+    const { compare = byNumbers, advisories: find } = ECOSYSTEMS[ecosystem]
+    const names = [...named.keys()].toSorted()
+    const asked = new Map(names.map((name) => [name, [...named.get(name).versions].toSorted(compare)]))
+    const known = new Map(names.filter((name) => named.get(name).github).map((name) => [name, named.get(name).github]))
+    const rows = await find(asked, { github: options.github, repoAdvisories: options.repoAdvisories === true, known })
+    return rows.map((row) => ({ ecosystem, ...row }))
+  }))
+  return found.flat().filter((row) => row.versions.length > 0).toSorted((a, b) => order(a.ecosystem, b.ecosystem) || order(a.name, b.name))
+}

package/src/advisories/npm.js

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+
+import { assertPackageName, assertPackageVersion, isGhsa, isStrings, show } from '../args.js'
+import { NPM_REGISTRY, buildUrl, request } from '../http.js'
+import { compareVersions } from '../semver.js'
+import { covered, isText, metrics } from './common.js'
+import { withRepositories } from './github.js'
+import { npmRepos } from './repos.js'
+
+const BULK_URL = buildUrl(NPM_REGISTRY, ['-', 'npm', 'v1', 'security', 'advisories', 'bulk'])
+const NAMES_PER_REQUEST = 250
+const GHSA_PAGE = 'https://github.com/advisories/'
+
+const isRow = (row) => row && typeof row === 'object' && Number.isSafeInteger(row.id)
+  && ['url', 'severity', 'vulnerable_versions'].every((key) => typeof row[key] === 'string') && isText(row.title)
+  && (row.cwe === undefined || isStrings(row.cwe))
+
+function fromRegistry(name, row, asked) {
+  const tail = row.url.startsWith(GHSA_PAGE) ? row.url.slice(GHSA_PAGE.length) : ''
+  const ghsa = isGhsa(tail) ? tail : undefined
+  return {
+    name,
+    source: 'registry',
+    id: ghsa ?? `npm:${row.id}`,
+    ...(ghsa && { ghsa }),
+    aliases: [],
+    title: row.title,
+    ...metrics({ severity: row.severity, score: row.cvss?.score, vector: row.cvss?.vectorString, cwe: row.cwe }),
+    range: row.vulnerable_versions,
+    versions: covered(asked, row.vulnerable_versions),
+  }
+}
+
+async function registryAdvisories(asked) {
+  const names = [...asked.keys()]
+  const advisories = []
+  for (let i = 0; i < names.length; i += NAMES_PER_REQUEST) {
+    const chunk = names.slice(i, i + NAMES_PER_REQUEST)
+    const body = Object.fromEntries(chunk.map((name) => [name, asked.get(name)]))
+    const answer = await request(BULK_URL, { method: 'POST', body, as: 'json' })
+    assert.ok(answer && typeof answer === 'object' && !Array.isArray(answer), 'advisories: expected an object from the registry')
+    for (const name of Object.keys(answer)) assert.ok(Object.hasOwn(body, name), `advisories: the registry answered for ${show(name)}, which was not asked`)
+    for (const name of chunk) {
+      const rows = Object.hasOwn(answer, name) ? answer[name] : []
+      assert.ok(Array.isArray(rows) && rows.every(isRow), `advisories: malformed advisories for ${name}`)
+      advisories.push(...rows.map((row) => fromRegistry(name, row, asked.get(name))))
+    }
+  }
+  return advisories
+}
+
+// What `npm audit` asks the registry, one row per vulnerable range.
+export const NPM = {
+  assertName: assertPackageName,
+  assertVersion: assertPackageVersion,
+  compare: compareVersions,
+  advisories: async (asked, options) => await withRepositories(await registryAdvisories(asked), asked, options, { ecosystem: 'npm', lookUp: npmRepos }),
+}

package/src/advisories/osv.js

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict'
+
+import { assertion, isGhsa, isStrings, matches, show } from '../args.js'
+import { OSV_API, buildUrl, request } from '../http.js'
+import { pool } from '../pool.js'
+import { isExactVersion } from '../semver.js'
+import { inRange, isText, metrics, order } from './common.js'
+import { withRepositories } from './github.js'
+import { composerRepos, crateRepos } from './repos.js'
+
+const QUERY_URL = buildUrl(OSV_API, ['v1', 'querybatch'])
+const QUERIES_PER_REQUEST = 1000
+const RECORDS_AT_ONCE = 8
+const isOsvId = matches(/^(?=.{1,128}$)[A-Z][\dA-Z]*(?:-[\dA-Za-z]+)+$/u)
+const INFORMATIONAL = new Set(['unmaintained', 'unsound', 'notice'])
+
+export const CARGO = {
+  osv: 'crates.io',
+  github: 'rust',
+  lookUp: crateRepos,
+  assertName: assertion('a crate name', matches(/^[A-Za-z][\w-]{0,63}$/u)),
+  assertVersion: assertion('a semver version', matches(/^(?=.{5,256}$)(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/u)),
+  keep: (id) => id.startsWith('RUSTSEC-'), // What `cargo audit` reads; the GHSA records mirror it.
+  advisories: (asked, options) => osvAdvisories(CARGO, asked, options),
+}
+// TODO: packagist.org's API, what `composer audit` reads, also has the
+// FriendsOfPHP advisories OSV lacks; using it means matching Composer
+// version ranges here.
+export const COMPOSER = {
+  osv: 'Packagist',
+  github: 'composer',
+  lookUp: composerRepos,
+  assertName: assertion('a Composer package name', matches(/^(?=.{3,256}$)[a-z\d](?:[_.-]?[a-z\d]+)*\/[a-z\d](?:(?:[_.]|-{1,2})?[a-z\d]+)*$/u)),
+  assertVersion: assertion('a Composer release version', matches(/^(?=.{1,64}$)v?\d+(?:\.\d+){0,3}(?:[._-]?(?:stable|beta|b|RC|alpha|a|patch|pl|p)(?:[.-]?\d+)*)?$/iu)),
+  // Composer's `v1.2.3` is semver's 1.2.3; what semver cannot read at all
+  // (1.2.3.4, 1.0.0-p1) is covered by every range.
+  covers: (version, range) => {
+    const plain = version.replace(/^v/iu, '')
+    return !isExactVersion(plain) || inRange(plain, range)
+  },
+  advisories: (asked, options) => osvAdvisories(COMPOSER, asked, options),
+}
+
+async function getVuln(id) {
+  const record = await request(buildUrl(OSV_API, ['v1', 'vulns', id]), { as: 'json' })
+  assert.ok(record?.id === id, `advisories: OSV answered for ${show(record?.id)}, not ${id}`)
+  assert.ok((record.aliases === undefined || isStrings(record.aliases)) && (record.summary === undefined || isText(record.summary))
+    && (record.withdrawn === undefined || typeof record.withdrawn === 'string'), `advisories: malformed OSV record ${id}`)
+  return { ...record, aliases: (record.aliases ?? []).filter(isOsvId) }
+}
+
+function toAdvisory(ecosystem, name, versions, record) {
+  const { aliases } = record
+  const ghsas = aliases.filter(isGhsa)
+  const ghsa = isGhsa(record.id) ? record.id : (ghsas.length === 1 ? ghsas[0] : undefined)
+  const vector = record.severity?.find?.((entry) => /^CVSS_V[34]$/u.test(entry?.type))?.score
+  const affected = record.affected?.find?.((entry) => entry?.package?.ecosystem === ecosystem && entry.package.name === name)
+  const informational = affected?.database_specific?.informational
+  return {
+    name,
+    source: 'osv',
+    id: record.id,
+    ...(ghsa && { ghsa }),
+    aliases,
+    ...(record.summary && { title: record.summary }),
+    ...metrics({ severity: record.database_specific?.severity, vector, cwe: record.database_specific?.cwe_ids }),
+    ...(INFORMATIONAL.has(informational) && { informational }),
+    versions,
+  }
+}
+
+// OSV's batch query matches versions on its side, but answers ids only:
+// each record is fetched once after. A record another database also
+// publishes comes back under both ids, so one that aliases a GHSA keeps
+// only the versions that GHSA was not answered for.
+async function osvAdvisories(ecosystem, asked, options) {
+  const { osv, github, lookUp, covers, keep = () => true } = ecosystem
+  const list = [...asked].flatMap(([name, versions]) => versions.map((version) => ({ name, version })))
+  const hits = new Map() // id → name → versions, in `list` order
+  for (let i = 0; i < list.length; i += QUERIES_PER_REQUEST) {
+    const chunk = list.slice(i, i + QUERIES_PER_REQUEST)
+    const body = { queries: chunk.map(({ name, version }) => ({ package: { name, ecosystem: osv }, version })) }
+    const answer = await request(QUERY_URL, { method: 'POST', body, as: 'json' })
+    assert.ok(Array.isArray(answer?.results) && answer.results.length === chunk.length, 'advisories: expected one OSV result per query')
+    for (const [j, result] of answer.results.entries()) {
+      const { name, version } = chunk[j]
+      const vulns = result?.vulns ?? []
+      assert.ok(result && result.next_page_token === undefined && Array.isArray(vulns) && vulns.every((vuln) => isOsvId(vuln?.id)), `advisories: malformed OSV result for ${name}@${version}`)
+      for (const { id } of vulns.filter((vuln) => keep(vuln.id))) {
+        const byName = hits.get(id) ?? hits.set(id, new Map()).get(id)
+        byName.set(name, (byName.get(name) ?? new Set()).add(version))
+      }
+    }
+  }
+  const records = (await pool([...hits.keys()], RECORDS_AT_ONCE, getVuln)).filter((record) => !record.withdrawn)
+  const live = new Set(records.map((record) => record.id))
+  const rows = []
+  for (const record of records) {
+    for (const [name, versions] of hits.get(record.id)) {
+      // Only the versions a live GHSA it aliases answered for too.
+      const shadowed = isGhsa(record.id) ? [] : record.aliases.filter((alias) => isGhsa(alias) && live.has(alias)).flatMap((alias) => [...(hits.get(alias).get(name) ?? [])])
+      const rest = [...versions].filter((version) => !shadowed.includes(version))
+      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, record))
+    }
+  }
+  rows.sort((a, b) => order(a.name, b.name) || order(a.id, b.id))
+  return await withRepositories(rows, asked, options, { ecosystem: github, lookUp, covers })
+}

package/src/advisories/repos.js

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { isRepo, show } from '../args.js'
+import { readCacheJSON, writeCacheJSON } from '../cache.js'
+import { CRATES_API, HttpError, PACKAGIST_REPO, buildUrl, request } from '../http.js'
+import { lookUpPackageRepo } from '../npm/repos.js'
+import { pool } from '../pool.js'
+import { githubRepoOfUrl } from '../remote.js'
+
+const TTL_MS = 30 * 24 * 60 * 60 * 1000
+const CRATES_PER_REQUEST = 100
+const CRATES_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)'
+const PACKAGES_AT_ONCE = 8
+
+// Name → its GitHub repo, or null where the registry has no such package
+// or it names no GitHub repo; any other failure throws. Only a repo found
+// is cached, for a month.
+async function cachedRepos(dir, names, fetchMissing) {
+  const repos = new Map()
+  for (const name of names) {
+    const entry = await readCacheJSON(dir, `${name}.json`)
+    const age = typeof entry?.at === 'number' ? Date.now() - entry.at : Number.NaN
+    if (age >= 0 && age <= TTL_MS && entry.name === name && isRepo(entry.github)) repos.set(name, entry.github)
+  }
+  const missing = names.filter((name) => !repos.has(name))
+  for (const [name, github] of await fetchMissing(missing)) {
+    repos.set(name, github)
+    if (github) await writeCacheJSON(dir, `${name}.json`, { at: Date.now(), name, github })
+  }
+  return repos
+}
+
+// A crate crates.io leaves out of its answer is one it does not have.
+async function fetchCrates(names) {
+  const found = new Map(names.map((name) => [name, null]))
+  for (let i = 0; i < names.length; i += CRATES_PER_REQUEST) {
+    if (i > 0) await sleep(CRATES_PACE_MS)
+    const chunk = names.slice(i, i + CRATES_PER_REQUEST)
+    const url = buildUrl(CRATES_API, ['api', 'v1', 'crates'], { 'ids[]': chunk, per_page: CRATES_PER_REQUEST })
+    const answer = await request(url, { as: 'json', headers: { 'User-Agent': USER_AGENT } })
+    assert.ok(Array.isArray(answer?.crates), 'advisories: expected a list of crates from crates.io')
+    for (const crate of answer.crates) {
+      assert.ok(chunk.includes(crate?.id), `advisories: crates.io answered for ${show(crate?.id)}, which was not asked`)
+      found.set(crate.id, githubRepoOfUrl(crate.repository) ?? null)
+    }
+  }
+  return found
+}
+
+async function fetchEach(names, fetch) {
+  const found = await pool(names, PACKAGES_AT_ONCE, fetch)
+  return new Map(names.map((name, i) => [name, found[i]]))
+}
+
+// The first version in Packagist's file is its latest, in full.
+async function fetchComposerRepo(name) {
+  const [vendor, pkg] = name.split('/')
+  const answer = await request(buildUrl(PACKAGIST_REPO, ['p2', vendor, `${pkg}.json`]), { as: 'json' }).catch((err) => {
+    if (err instanceof HttpError && err.status === 404) return null
+    throw err
+  })
+  if (answer === null) return null
+  const versions = Object.hasOwn(answer?.packages ?? {}, name) ? answer.packages[name] : undefined
+  assert.ok(Array.isArray(versions), `advisories: Packagist answered without ${name}`)
+  return githubRepoOfUrl(versions[0]?.source?.url) ?? null
+}
+
+export const crateRepos = (names) => cachedRepos('cargo/repos', names, fetchCrates)
+export const composerRepos = (names) => cachedRepos('composer/repos', names, (missing) => fetchEach(missing, fetchComposerRepo))
+export const npmRepos = (names) => fetchEach(names, async (name) => (await lookUpPackageRepo(name))?.github ?? null)

package/src/args.js

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict'
+
+import { isExactVersion } from './semver.js'
+
+const isControl = (char) => char < ' ' || (char >= '\u007F' && char <= '\u009F')
+export const matches = (regex) => (value) => typeof value === 'string' && regex.test(value)
+// Bidi controls can make a log line read as something it doesn't say.
+const isBidi = (char) => (char >= '\u202A' && char <= '\u202E') || (char >= '\u2066' && char <= '\u2069')
+// A prototype's properties would be read as options without being checked.
+const isPlainObject = (value) => value != null && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+// Lone surrogates make encodeURIComponent throw.
+const isString = (value, max, allowed = '') => typeof value === 'string' && value.length <= max && value.isWellFormed()
+  && ![...value].some((char) => isControl(char) && !allowed.includes(char))
+const isLogin = matches(/^(?=.{1,39}$)[a-z\d](?:-?[a-z\d])*$/iu)
+const isRepoName = matches(/^(?!\.\.?$)[\w.-]{1,100}$/u)
+// `.git` is never in a repo's tree, and no commit should write into it.
+export const isRepoPath = (value) => isString(value, 4096) && value.split('/').every((part) => !['', '.', '..', '.git'].includes(part.toLowerCase()))
+const BAD_REF = /^$|^@$|^-|[ ~^:?*[\\]|\.\.|@\{|^\/|\/$|\/\/|(?:^|\/)\.|\.lock(?:\/|$)|\.$/u // git check-ref-format, a rule per alternative
+const isToken = matches(/^[!-~]+$/u)
+// npm's rules for existing names: capitals allowed (JSONStream), the
+// legacy `~'!()*` not.
+// npm's rule: an unscoped name starts with neither `.`, `_` nor `-`.
+const isPackageName = matches(/^(?=.{1,214}$)(?:@[\w.-]+\/[\w-]|[\dA-Za-z])[\w.-]*$/u)
+
+export function printable(text) {
+  return [...String(text)].map((char) => (isControl(char) || isBidi(char) ? `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}` : char)).join('')
+}
+
+export function show(value) {
+  if (typeof value === 'string') return printable(JSON.stringify(value))
+  return value && (typeof value === 'object' || typeof value === 'function') ? typeof value : String(value)
+}
+
+export function isRepo(value) {
+  const [owner, name, ...rest] = typeof value === 'string' ? value.split('/') : []
+  return isLogin(owner) && isRepoName(name) && rest.length === 0
+}
+
+export const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string')
+export const sameName = (a, b) => typeof a === 'string' && a.toLowerCase() === b.toLowerCase()
+export const isRefName = (value) => isString(value, 255) && !BAD_REF.test(value)
+export const isSha = matches(/^(?:[\da-f]{40}|[\da-f]{64})$/u)
+export const isGhsa = matches(/^GHSA(?:-[\da-hj-km-np-tv-z]{4}){3}$/u)
+export const assertion = (must, predicate) => (method, what, value) => assert.ok(predicate(value), `${method}: ${what} must be ${must}, got ${show(value)}`)
+export const optional = (check) => (method, what, value) => value === undefined || check(method, what, value)
+
+// A `null` in `spec` allows the key and leaves its check to the caller.
+export function assertArgs(method, options, spec, name) {
+  const label = (key) => printable(name ? `${name}.${String(key)}` : String(key))
+  assert.ok(isPlainObject(options), `${method}: ${name ?? 'options'} must be an options object, got ${show(options)}`)
+  for (const key of Reflect.ownKeys(options)) assert.ok(Object.hasOwn(spec, key), `${method}: unknown option ${label(key)}`)
+  for (const [key, check] of Object.entries(spec)) check?.(method, label(key), options[key])
+}
+
+export const assertBoolean = assertion('a boolean', (value) => typeof value === 'boolean')
+export const assertNumber = assertion('a positive integer', (value) => Number.isSafeInteger(value) && value > 0)
+export const assertLine = assertion('a non-empty single line', (value) => isString(value, 1024) && value.trim() !== '')
+// 65,536 is GitHub's own limit on a body.
+export const assertText = assertion('text with no control characters', (value) => isString(value, 65_536, '\t\n\r'))
+export const assertDirectoryPath = assertion('a directory path', (value) => isString(value, 4096) && value !== '')
+export const assertLogin = assertion('a GitHub login', isLogin)
+export const assertRepoName = assertion('a repository name', isRepoName)
+export const assertRepo = assertion('"owner/name"', isRepo)
+export const assertRef = assertion('a branch or tag name', isRefName)
+export const assertSha = assertion('a full commit sha', isSha)
+export const assertPath = assertion('a path inside a repository', isRepoPath)
+export const assertToken = assertion('a token', isToken)
+export const assertTokenOrNull = assertion('a token, or null for anonymous access', (value) => value === null || isToken(value))
+export const assertUserAgent = assertion('a printable user agent', matches(/^[ -~]*[!-~][ -~]*$/u))
+export const assertPackageName = assertion('an npm package name', isPackageName)
+export const assertPackageVersion = assertion('an exact semver version', isExactVersion)
+export const assertGhsa = assertion('a GHSA id', isGhsa)

package/src/cache.js

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict'
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+
+import { assertDirectoryPath } from './args.js'
+import { decode } from './http.js'
+
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'composer/repos'])
+
+let root
+let tmpSeq = 0
+
+export function setCacheDir(dir) {
+  assertDirectoryPath('setCacheDir', 'dir', dir)
+  root = resolve(dir)
+}
+
+// URI-encoded, so a `/` or `..` in a key stays inside one file name, then
+// `@` kept and `/` written `+`, as pnpm names its store: `@babel+core@7.29.7`.
+// encodeURIComponent writes neither `@` nor `+` bare, so no two keys meet.
+function cachePath(dir, key) {
+  assert.ok(DIRS.has(dir) && key && typeof key === 'string', `Unexpected cache entry: ${dir}`)
+  return root === undefined ? null : join(root, dir, encodeURIComponent(key).replaceAll('%40', '@').replaceAll('%2F', '+'))
+}
+
+export async function readCache(dir, key) {
+  const path = cachePath(dir, key)
+  return path && await readFile(path).then((bytes) => new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength), () => null)
+}
+
+export async function readCacheJSON(dir, key) {
+  const bytes = await readCache(dir, key)
+  try {
+    return bytes && JSON.parse(decode(bytes, key))
+  } catch {
+    return null
+  }
+}
+
+export async function writeCache(dir, key, data) {
+  const path = cachePath(dir, key)
+  if (path === null) return false
+  const tmp = `${path}.${process.pid}.${++tmpSeq}.tmp`
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(tmp, data)
+    await rename(tmp, path)
+    return true
+  } catch {
+    await rm(tmp, { force: true }).catch(() => {})
+    return false
+  }
+}
+
+export async function writeCacheJSON(dir, key, value) {
+  return await writeCache(dir, key, JSON.stringify(value))
+}

package/src/git.js

@@ -0,0 +1,58 @@
+import { readFile, realpath, stat } from 'node:fs/promises'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+
+import { assertDirectoryPath, isRefName, isSha } from './args.js'
+import { githubRepoOfUrl } from './remote.js'
+
+const ORIGIN = '[remote "origin"]\n\turl = ' // As git writes it. Only `owner/name` leaves here: the URL may carry a token.
+const read = (path) => readFile(path, 'utf8').catch(() => null)
+const isDirectory = async (path) => (await stat(path).catch(() => null))?.isDirectory() ?? false
+
+// A `.git` file points at the real git dir (worktrees, submodules), and a
+// worktree keeps its refs and config in the dir `commondir` names.
+async function findGitDirs(start) {
+  for (let dir = start; ; dir = dirname(dir)) {
+    const dotGit = join(dir, '.git')
+    const info = await stat(dotGit).catch(() => null)
+    if (info?.isDirectory()) return { root: dir, gitDir: dotGit, commonDir: dotGit }
+    if (info?.isFile()) {
+      const pointer = /^gitdir: (?<path>.+)$/u.exec((await read(dotGit))?.trim() ?? '')?.groups.path
+      if (!pointer) return null
+      const gitDir = resolve(dir, pointer)
+      if (!await isDirectory(gitDir)) return null
+      const common = (await read(join(gitDir, 'commondir')))?.trim()
+      return { root: dir, gitDir, commonDir: common ? resolve(gitDir, common) : gitDir }
+    }
+    if (dirname(dir) === dir) return null
+  }
+}
+
+async function headCommit(gitDir, commonDir) {
+  const head = (await read(join(gitDir, 'HEAD')))?.trim()
+  if (isSha(head)) return head
+  // Checked before it is joined to a path, so `ref: ../../x` can't read
+  // outside the git dir.
+  const ref = /^ref: (?<ref>refs\/\S+)$/u.exec(head ?? '')?.groups.ref
+  if (!isRefName(ref)) return null
+  const loose = (await read(join(commonDir, ...ref.split('/'))))?.trim()
+  if (isSha(loose)) return loose
+  const lines = (await read(join(commonDir, 'packed-refs')))?.split('\n').map((line) => line.trim().split(' ')) ?? []
+  return lines.find(([sha, name, ...rest]) => name === ref && rest.length === 0 && isSha(sha))?.[0] ?? null
+}
+
+async function originGitHub(commonDir) {
+  const config = `\n${await read(join(commonDir, 'config')) ?? ''}`
+  const at = config.indexOf(`\n${ORIGIN}`)
+  return at === -1 ? undefined : githubRepoOfUrl(config.slice(at + 1 + ORIGIN.length).split('\n')[0].trim())
+}
+
+export async function findGitCheckout(dir) {
+  assertDirectoryPath('findGitCheckout', 'dir', dir)
+  const start = await realpath(resolve(dir)).catch(() => null)
+  const dirs = start && await isDirectory(start) ? await findGitDirs(start) : null
+  if (dirs === null) return {}
+  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 }) }
+}

package/src/github/client.js

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict'
+
+import { assertArgs, assertToken, assertTokenOrNull, assertUserAgent, optional } from '../args.js'
+import { GITHUB_API, HttpError, buildUrl, request } from '../http.js'
+
+export const api = (segments, query) => buildUrl(GITHUB_API, segments, query)
+export const repoApi = (repo, segments = [], query) => api(['repos', ...repo.split('/'), ...segments], query)
+export const call = (headers, url, options) => request(url, { as: 'json', headers, ...options })
+// A repository renamed (a redirect, refused), deleted or blocked, not a
+// failure that could pass.
+export const isGone = (err) => err instanceof HttpError && [301, 404, 410, 451].includes(err.status)
+
+// `null` is explicit anonymous access, so a forgotten token is an error.
+export function clientHeaders(method, options, anonymous) {
+  assertArgs(method, options, { token: anonymous ? assertTokenOrNull : assertToken, userAgent: optional(assertUserAgent) })
+  const { token, userAgent = '@preventive/upstream' } = options
+  return {
+    ...(token !== null && { Authorization: `Bearer ${token}` }),
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': userAgent,
+  }
+}
+
+// All async, so a bad argument is always a rejection, never a throw.
+export function bindMethods(headers, methods) {
+  return Object.fromEntries(Object.entries(methods).map(([name, fn]) => [name, async (...args) => {
+    assert.ok(args.length < fn.length, `${name}: unexpected arguments`)
+    return await fn(headers, ...args)
+  }]))
+}

package/src/github/read.js

@@ -0,0 +1,124 @@
+import assert from 'node:assert/strict'
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+
+import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, isSha, optional, sameName, show } from '../args.js'
+import { decode, encodeSegment } from '../http.js'
+import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
+
+const PER_PAGE = 100
+const MAX_PAGES = 100
+
+// A list of exactly `maxPages` full pages is whole only if the next is empty.
+async function* pages(method, headers, pageUrl, maxPages = MAX_PAGES) {
+  for (let page = 1; ; page++) {
+    const body = await call(headers, pageUrl({ per_page: PER_PAGE, page }))
+    assert.ok(Array.isArray(body), `${method}: expected an array for page ${page}`)
+    assert.ok(page <= maxPages || body.length === 0, `${method}: more than ${maxPages} pages`)
+    yield body
+    if (body.length < PER_PAGE) return
+  }
+}
+
+const paginate = async (...args) => (await Array.fromAsync(pages(...args))).flat()
+const getCurrentUser = (headers) => call(headers, api(['user']))
+
+// No default for `options`: bindMethods counts it to refuse extra arguments.
+async function listUserRepos(headers, options) {
+  assertArgs('listUserRepos', options === undefined ? {} : options, { maxPages: optional(assertNumber) })
+  return await paginate('listUserRepos', headers, (paging) => api(['user', 'repos'], { ...paging, sort: 'full_name' }), options?.maxPages)
+}
+
+async function getRepo(headers, options) {
+  assertArgs('getRepo', options, { repo: assertRepo })
+  const info = await call(headers, repoApi(options.repo))
+  assert.ok(sameName(info?.full_name, options.repo), `getRepo: answered for ${show(info?.full_name)}, not ${options.repo}`)
+  return info
+}
+
+export async function getRepoHead(headers, options) {
+  assertArgs('getRepoHead', options, { repo: assertRepo, branch: optional(assertRef) })
+  const { repo, branch } = options
+  const ref = branch ?? (await getRepo(headers, { repo })).default_branch
+  assertRef('getRepoHead', 'default branch', ref)
+  const data = await call(headers, repoApi(repo, ['git', 'ref', 'heads', encodeSegment(ref)]))
+  assert.ok(isSha(data?.object?.sha), `getRepoHead: no commit sha for ${repo}@${ref}`)
+  return { branch: ref, oid: data.object.sha }
+}
+
+// GitHub's object for the path first: a directory, symlink or submodule is
+// refused rather than read as a file's text. Up to 1 MB the object holds
+// the content; past it, `encoding: none`, and the blob it names is read,
+// which a push to the ref since cannot change. Either way the bytes must
+// hash to that blob.
+async function getRepoFile(headers, options) {
+  assertArgs('getRepoFile', options, { repo: assertRepo, path: assertPath, ref: optional(assertRef) })
+  const { repo, path, ref } = options
+  const url = repoApi(repo, ['contents', ...path.split('/').map(encodeSegment)], ref === undefined ? {} : { ref })
+  const file = await call(headers, url)
+  assert.ok(file?.type === 'file' && file.path === path && Number.isSafeInteger(file.size) && isSha(file.sha), `getRepoFile: ${repo} has no file at ${show(path)}`)
+  assert.ok(file.encoding === 'none' || (file.encoding === 'base64' && /^[\dA-Za-z+/=\n]*$/u.test(file.content ?? '')), `getRepoFile: unexpected encoding for ${show(path)}`)
+  const bytes = file.encoding === 'none'
+    ? await call({ ...headers, Accept: 'application/vnd.github.raw' }, repoApi(repo, ['git', 'blobs', file.sha]), { as: 'bytes' })
+    : Buffer.from(file.content, 'base64')
+  const blob = createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')
+  assert.ok(bytes.length === file.size && blob === file.sha, `getRepoFile: ${show(path)} came back as blob ${blob}, not ${file.sha}`)
+  return decode(bytes, url)
+}
+
+// The one request that follows a redirect, to codeload.github.com. A full
+// sha only, so the bytes are that commit's, not wherever a ref points now.
+async function getRepoTarball(headers, options) {
+  assertArgs('getRepoTarball', options, { repo: assertRepo, sha: assertSha })
+  return await call(headers, repoApi(options.repo, ['tarball', options.sha]), { as: 'bytes', redirect: 'follow' })
+}
+
+async function getPullRequest(headers, options) {
+  assertArgs('getPullRequest', options, { repo: assertRepo, number: assertNumber })
+  const { repo, number } = options
+  const pr = await call(headers, repoApi(repo, ['pulls', String(number)]))
+  const base = pr?.base?.repo?.full_name
+  assert.ok(pr?.number === number && sameName(base, repo), `getPullRequest: answered for ${show(base)}#${show(pr?.number)}, not ${repo}#${number}`)
+  assert.ok(typeof pr.title === 'string' && pr.title.trim() !== '', `getPullRequest: ${repo}#${number} has no title`)
+  assert.ok(['open', 'closed'].includes(pr.state) && typeof pr.merged === 'boolean', `getPullRequest: ${repo}#${number} has no state`)
+  const status = pr.merged ? 'merged' : (pr.state === 'closed' ? 'closed' : (pr.draft === true ? 'draft' : 'open'))
+  return { title: pr.title, status }
+}
+
+async function getCollaboratorPermission(headers, options) {
+  assertArgs('getCollaboratorPermission', options, { repo: assertRepo, username: assertLogin })
+  const { repo, username } = options
+  const body = await call(headers, repoApi(repo, ['collaborators', username, 'permission']))
+  const login = body?.user?.login
+  assert.ok(typeof body?.permission === 'string' && sameName(login, username), `getCollaboratorPermission: answered for ${show(login)}, not ${username}`)
+  return body
+}
+
+// The repository's copy is the maintainer's latest text, there from the
+// start; the global database has it only once GitHub has reviewed it, and
+// is the fallback for a repository that is gone, not for one that failed.
+async function getAdvisory(headers, options) {
+  assertArgs('getAdvisory', options, { ghsa: assertGhsa, repo: optional(assertRepo) })
+  const { ghsa, repo } = options
+  const global = () => call(headers, api(['advisories', ghsa]))
+  const advisory = await (repo === undefined ? global() : call(headers, repoApi(repo, ['security-advisories', ghsa])).catch((err) => {
+    if (!isGone(err)) throw err
+    return global()
+  }))
+  assert.ok(advisory?.ghsa_id === ghsa, `getAdvisory: answered for ${show(advisory?.ghsa_id)}, not ${ghsa}`)
+  assert.ok(advisory.state === undefined || advisory.state === 'published', `getAdvisory: ${ghsa} is ${show(advisory.state)}, not published`)
+  return advisory
+}
+
+// One page: GitHub pages this list by a cursor in the Link header, which
+// `call` does not read, so a full page is refused rather than cut short.
+async function listRepoAdvisories(headers, options) {
+  assertArgs('listRepoAdvisories', options, { repo: assertRepo })
+  const list = await call(headers, repoApi(options.repo, ['security-advisories'], { state: 'published', per_page: PER_PAGE }))
+  assert.ok(Array.isArray(list), `listRepoAdvisories: expected an array for ${options.repo}`)
+  assert.ok(list.length < PER_PAGE, `listRepoAdvisories: ${options.repo} has ${PER_PAGE} or more published advisories, more than a page`)
+  return list
+}
+
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)