@preventive/upstream 1.2.0 → 1.4.0

package/cocoapods.d.ts

@@ -0,0 +1,33 @@
+// The name is asserted to be a root's as Podfile.lock writes it, printable
+// ASCII but for spaces, parentheses, slashes and backslashes, with no `.`
+// first; the version one of Pod::Version's; and the checksum 40 lowercase
+// hex digits, before any request or cache path. The cache is setCacheDir's
+// (npm.js).
+
+export { HttpError } from './npm.js'
+
+// A version's podspec from trunk, the JSON CocoaPods reads, whole, in
+// memory, as the CDN serves it under Specs/<a>/<b>/<c>/<name>/<version>/,
+// the first three hex digits of the md5 of the name: the files of
+// CocoaPods/Specs, so a pod from https://github.com/CocoaPods/Specs.git
+// too. Trunk says nothing of what a podspec hashes to, so `checksum` is
+// required: its sha1, as Podfile.lock records it in SPEC CHECKSUMS. The
+// bytes are checked against it, whether they were downloaded (before they
+// are cached) or read from a cache. The CDN's redirect to jsDelivr is
+// followed, as the bytes are checked whoever answers.
+//
+// A podspec is not fixed once trunk has it: `pod trunk deprecate` adds a
+// field to the latest version's. So one is cached by its checksum as well
+// as its version, and a lockfile written before such a change has a
+// checksum no download matches any longer, which throws.
+//
+// CocoaPods' own spec repos are read first, and never written: that path
+// in each directory under $CP_REPOS_DIR, else $CP_HOME_DIR/repos, else
+// `~/.cocoapods/repos`. A file there that does not match is passed over.
+// One in setCacheDir's cache that does not match throws. A cached podspec
+// that matches is answered with no request at all.
+//
+// What the pod is built from is not trunk's, and is not fetched here: a
+// commit of a GitHub repo, as a podspec's `source` or CHECKOUT OPTIONS
+// may name, is github.js's getRepoTarball's.
+export function getPodspec(name: string, version: string, checksum: string): Promise<Uint8Array>

package/cocoapods.js

@@ -0,0 +1,2 @@
+export { getPodspec } from './src/cocoapods.js'
+export { HttpError } from './src/http.js'

package/github.d.ts

@@ -89,6 +89,17 @@ export interface Client {
   // `node_modules`, of packages installed. A symlink is no file. Refused
   // where a path found is one getRepoFile does not take, such as one with a
   // control character in it.
+  // How `head` stands to `base` in the repo (each a full commit sha, or a
+  // branch or tag name), as GitHub's compare tells it: `ahead` where `base`
+  // is in `head`'s history, `behind` the other way round, `identical`, or
+  // `diverged`; with the commits each has that the other hasn't, and their
+  // merge base. Refused unless the status agrees with those counts, the
+  // merge base is `base` where `head` is ahead of it or the same, and the
+  // base GitHub compared is `base` where that is a commit. GitHub answers
+  // for a commit of any fork of the repo too, through the repo's own name:
+  // whether one is the repo's own is whether a ref of the repo (its default
+  // branch, say) is ahead of it or the same.
+  compareCommits(options: { repo: RepoName; base: string; head: string }): Promise<{ status: 'ahead' | 'behind' | 'identical' | 'diverged'; aheadBy: number; behindBy: number; mergeBase: string }>
   findRepoLockfiles(options: { repo: RepoName; sha: string; directory?: string }): Promise<{ lockfiles: RepoLockfile[]; projects: RepoProjectFile[] }>
   // An advisory by its GHSA id. With `repo`, that repository's published
   // copy: the maintainer's latest text, there before GitHub reviews it,
@@ -127,7 +138,7 @@ export interface Client {
   // getRepoTreeTarball's for the tree GitHub names for that commit, asked
   // on every call, cached or not. So its top directory is named for the
   // tree, and files marked `export-subst` are as committed, not rewritten.
-  getRepoTarball(options: { repo: RepoName; sha: string }): Promise<Uint8Array>
+  getRepoTarball(options: { repo: RepoName; sha: string; symlinksAbove?: number }): Promise<Uint8Array>
   // The id of the tree at `directory`, `/`-separated as npm's is, in the
   // full commit `sha`, or of its root without one: from the tree GitHub
   // names for the commit, down GitHub's listings a directory at a time,
@@ -153,7 +164,13 @@ export interface Client {
   // a repo set to include Git LFS objects in archives, which replace the
   // pointers git has; that repo still gets a tree already cached, pointers
   // and all.
-  getRepoTreeTarball(options: { repo: RepoName; tree: string }): Promise<Uint8Array>
+  // It is read as @preventive/archive reads a tarball, and refused for
+  // anything it refuses: a pax record repeated, a name or a symlink that
+  // climbs out of it, an absolute symlink. `symlinksAbove` lets a symlink
+  // climb that many levels above the tarball's root, none unless given: a
+  // subdirectory's, its links reaching the repo's root as a monorepo
+  // package's LICENSE does, needs as many as it is deep, less one.
+  getRepoTreeTarball(options: { repo: RepoName; tree: string; symlinksAbove?: number }): Promise<Uint8Array>
   // The repository's published security advisories, as GitHub's
   // repository advisory objects: every page of 100, each found by the
   // cursor in the one before's Link header. More than 100 pages is an
@@ -163,6 +180,10 @@ export interface Client {
   // found as getRepoTreeId finds it: GitHub's listing, hashed back to the
   // tree's id, so none is left out or changed.
   listRepoDir(options: { repo: RepoName; sha: string; directory?: string }): Promise<RepoDirEntry[]>
+  // Every page of the repo's branches, as GitHub lists them, each with the
+  // commit at its head; more than `maxPages` (100 by default) pages of 100
+  // is an error, as is a branch with no commit.
+  listRepoBranches(options: { repo: RepoName; maxPages?: number }): Promise<{ branch: string; oid: string }[]>
   // Every page of the repo's tags, as GitHub lists them, each with the
   // commit GitHub names for it, an annotated tag's included, which
   // getRepoTag checks is one; more than `maxPages` (100 by default) pages

package/npm.d.ts

@@ -37,11 +37,12 @@ export const defaultCacheDir: string | undefined
 // with no request. Point it only at storage that
 // nothing less trusted than the caller can write, never a cache shared
 // with or restored from lower-trust jobs. Tarballs, crates (cargo.js), zips
-// (soldeer.js) and tree tarballs (github.js) don't rely on this, since
-// they are checked against their integrity on every call; and the version
-// documents kept here (getMeta) never supply an integrity, only confirm
-// one a caller gives (verifyDist, and getMeta with a `dist`). A call's `cache` option, where it has
-// one, keeps what it caches elsewhere, or writes none of it here.
+// (soldeer.js), podspecs (cocoapods.js) and tree tarballs (github.js) don't
+// rely on this, since they are checked against their integrity on every
+// call; and the version documents kept here (getMeta) never supply an
+// integrity, only confirm one a caller gives (verifyDist, and getMeta with
+// a `dist`). A call's `cache` option, where it has one, keeps what it
+// caches elsewhere, or writes none of it here.
 export function setCacheDir(dir?: string | false): void
 
 // A store of the caller's, a database's say, for what would otherwise be

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.2.0",
-  "description": "Minimal npm, crates.io, Soldeer, GitHub and git checkout clients",
+  "version": "1.4.0",
+  "description": "Minimal npm, crates.io, Soldeer, CocoaPods trunk, GitHub and git checkout clients",
   "type": "module",
   "exports": {
     "./advisories.js": {
@@ -12,6 +12,10 @@
       "types": "./cargo.d.ts",
       "default": "./cargo.js"
     },
+    "./cocoapods.js": {
+      "types": "./cocoapods.d.ts",
+      "default": "./cocoapods.js"
+    },
     "./github.js": {
       "types": "./github.d.ts",
       "default": "./github.js"
@@ -52,6 +56,8 @@
     "advisories.js",
     "cargo.d.ts",
     "cargo.js",
+    "cocoapods.d.ts",
+    "cocoapods.js",
     "github.d.ts",
     "github.js",
     "git.d.ts",
@@ -79,6 +85,7 @@
     "src/cache.js",
     "src/cargo/crate.js",
     "src/cargo/repos.js",
+    "src/cocoapods.js",
     "src/download.js",
     "src/git.js",
     "src/github/client.js",
@@ -124,6 +131,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@preventive/archive": "^1.2.0"
+  },
   "peerDependencies": {
     "semver": "^7.5.2"
   },

package/src/advisories/common.js

@@ -38,7 +38,7 @@ export function detailsOf(text, id) {
   return { details: text }
 }
 
-const SEVERITIES = new Set(['critical', 'high', 'moderate', 'low', 'info'])
+export const SEVERITIES = ['critical', 'high', 'moderate', 'low', 'info']
 const isCvssVector = matches(/^CVSS:[34]\.\d(?:\/[A-Z]{1,4}:[A-Z]{1,2})+$/u)
 const isCwe = matches(/^CWE-\d{1,6}$/u)
 
@@ -48,7 +48,7 @@ const isCwe = matches(/^CWE-\d{1,6}$/u)
 export function metrics({ severity, score, vector, cwe }) {
   const word = typeof severity === 'string' ? severity.toLowerCase().replace(/^medium$/u, 'moderate') : undefined
   return {
-    ...(SEVERITIES.has(word) && { severity: word }),
+    ...(SEVERITIES.includes(word) && { severity: word }),
     ...(typeof score === 'number' && score > 0 && score <= 10 && { cvss: score }),
     ...(isCvssVector(vector) && { cvssVector: vector }),
     cwe: isStrings(cwe) ? cwe.filter(isCwe) : [],

package/src/advisories/index.js

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 
 import { assertArgs, assertBoolean, assertRepo, assertion, isIterable, optional, sameName } from '../args.js'
 import { assertCache } from '../cache.js'
-import { order } from './common.js'
+import { SEVERITIES, order } from './common.js'
 import { GITHUB, SOLDEER, assertClient } from './github.js'
 import { NPM } from './npm.js'
 import { CARGO, COMPOSER } from './osv.js'
@@ -37,7 +37,6 @@ function collect(packages) {
 // Which of an advisory's rows stands for it: npm's registry's, then OSV's,
 // then its repository's.
 const SOURCES = ['registry', 'osv', 'repository']
-const SEVERITIES = ['critical', 'high', 'moderate', 'low', 'info']
 const worse = (a, b) => (b === undefined || (a !== undefined && SEVERITIES.indexOf(a) < SEVERITIES.indexOf(b)) ? a : b)
 
 // An advisory's rows as one: the first's by source, what it lacks from the

package/src/args.js

@@ -68,6 +68,7 @@ export function assertNames(method, what, names, options, assertName) {
 
 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 assertLevels = assertion('a whole number of levels', (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'))
@@ -98,6 +99,12 @@ export const assertSoldeerName = assertion('a Soldeer package name', matches(/^(
 // Soldeer takes any version but an empty one. Its registry has semver
 // (`5.7.0-rc.0`, `1.0.2-solc-0.8-simulate`), bare numbers and commit hashes.
 export const assertSoldeerVersion = assertion('letters, digits, `.`, `_`, `+` and `-`', matches(/^(?=.{1,128}$)[\dA-Za-z][\w.+-]*$/u))
+// A root's name as Podfile.lock has it, and @preventive/lockfile reads it:
+// printable ASCII but for spaces, parentheses, slashes and backslashes, no
+// `.` first, which the spec linter refuses, and 1024 characters at most.
+const assertPodName = assertion('a pod\'s root name', matches(/^(?=.{1,1024}$)(?!\.)[!-'*-.0-[\]-~]+$/u))
+// Pod::Version's pattern, as Podfile.lock writes a version.
+const assertPodVersion = assertion('a CocoaPods version', matches(/^(?=.{1,256}$)\d+(?:\.[\dA-Za-z-]+)*(?:\+[\dA-Za-z.-]+)?$/u))
 // A package's name and version, as a registry's getters take them.
 const assertNameVersion = (assertName, assertVersion) => (method, name, version) => {
   assertName(method, 'name', name)
@@ -106,5 +113,8 @@ const assertNameVersion = (assertName, assertVersion) => (method, name, version)
 export const assertCrate = assertNameVersion(assertCrateName, assertCrateVersion)
 export const assertPackage = assertNameVersion(assertPackageName, assertPackageVersion)
 export const assertSoldeerPackage = assertNameVersion(assertSoldeerName, assertSoldeerVersion)
+export const assertPod = assertNameVersion(assertPodName, assertPodVersion)
 // As Cargo.lock and soldeer.lock write a checksum.
 export const assertSha256 = assertion('a sha256 in lowercase hex', matches(/^[\da-f]{64}$/u))
+// As Podfile.lock writes a podspec's checksum.
+export const assertSha1 = assertion('a sha1 in lowercase hex', isSha1)

package/src/cache.js

@@ -10,7 +10,7 @@ import { assertCacheName, assertDirectoryPath, assertion, isRepo } from './args.
 import { MAX_BYTES, decode } from './http.js'
 import { pool } from './pool.js'
 
-const DIRS = new Set(['npm/repos', 'npm/tarballs', 'npm/versions', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees', 'github/advisories'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'npm/versions', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'cocoapods/podspecs', 'github/trees', 'github/advisories'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
 const RECORDS_AT_ONCE = 8
 // JSON filed gzipped, as `<name>.json.gz`: a listing carries each

package/src/cocoapods.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto'
+import { readdir } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import { assertPod, assertSha1 } from './args.js'
+import { verifiedDownload } from './download.js'
+import { COCOAPODS_CDN, buildUrl, encodeSegment } from './http.js'
+
+// No expiry, but kept by checksum as well: trunk refuses a version it
+// already has, yet rewrites a podspec it has, as `pod trunk deprecate`
+// adds a field to the latest version's.
+const DIR = 'cocoapods/podspecs'
+
+// Where a spec repo keeps a version's podspec: under a directory each for
+// the first three hex digits of the md5 of the name, as
+// Pod::Source::Metadata shards trunk, and CocoaPods/Specs with it.
+function specPath(name, version) {
+  const shard = createHash('md5').update(name).digest('hex').slice(0, 3)
+  return ['Specs', ...shard, name, version, `${name}.podspec.json`]
+}
+
+// CocoaPods' spec repos, a directory each under $CP_REPOS_DIR, else
+// $CP_HOME_DIR/repos, else ~/.cocoapods/repos: `trunk` with the podspecs
+// it read off the CDN as they were served, `master` a clone of
+// CocoaPods/Specs, others a team's own. os.homedir() throws where there is
+// no home directory to be found.
+async function localPaths(name, version) {
+  const { CP_REPOS_DIR, CP_HOME_DIR } = process.env
+  let root
+  try {
+    root = resolve(CP_REPOS_DIR || join(CP_HOME_DIR || join(homedir(), '.cocoapods'), 'repos'))
+  } catch {
+    return []
+  }
+  return (await readdir(root).catch(() => [])).map((repo) => join(root, repo, ...specPath(name, version)))
+}
+
+// Trunk has no hash to check a podspec against, so the caller brings one,
+// as Podfile.lock records it. The CDN redirects to jsDelivr, which is
+// followed: whoever answers, the bytes are held to the checksum.
+export async function getPodspec(name, version, checksum) {
+  assertPod('getPodspec', name, version)
+  assertSha1('getPodspec', 'checksum', checksum)
+  const what = `${name}@${version}`
+  const locate = () => buildUrl(COCOAPODS_CDN, specPath(name, version).map(encodeSegment))
+  return await verifiedDownload({
+    method: 'getPodspec', dir: DIR, what, entry: `${what}-${checksum}`, ext: 'podspec.json', algorithm: 'sha1', expected: checksum,
+    local: await localPaths(name, version), locate, options: { redirect: 'follow' },
+  })
+}

package/src/download.js

@@ -6,11 +6,13 @@ import { request } from './http.js'
 import { gitTreeOfTarball } from './tree.js'
 
 // A hash as each registry writes it: npm's integrity, one sha512 in base64
-// after `sha512-`; crates.io's and Soldeer's checksum, a sha256 in hex; a
-// git tree id for a tarball of that tree.
+// after `sha512-`; crates.io's and Soldeer's checksum, a sha256 in hex;
+// Podfile.lock's checksum of a podspec, a sha1 in hex; a git tree id for a
+// tarball of that tree.
 const DIGESTS = {
   sha512: (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`,
   sha256: (bytes) => createHash('sha256').update(bytes).digest('hex'),
+  sha1: (bytes) => createHash('sha1').update(bytes).digest('hex'),
   tree: gitTreeOfTarball,
 }
 
@@ -20,11 +22,12 @@ const DIGESTS = {
 // whether set or not (read, never written; a mismatch is passed over),
 // else the cache set, or a `cache` store in its place (readBytes; a
 // mismatch throws), else what `locate` answers, checked and then kept as
-// writeBytes keeps it.
-export async function verifiedDownload({ method, dir, what, ext, algorithm, expected, local = [], ours = false, cache, locate, options = {}, list }) {
+// writeBytes keeps it, as `entry`, `what` unless given. A tree's `list`
+// and `symlinksAbove` are gitTreeOfTarball's.
+export async function verifiedDownload({ method, dir, what, entry = what, ext, algorithm, expected, local = [], ours = false, cache, locate, options = {}, list, symlinksAbove }) {
   assert.ok(Object.hasOwn(DIGESTS, algorithm) && typeof expected === 'string' && expected !== '', `${method}: nothing to check ${what} against`)
-  const digest = (bytes) => DIGESTS[algorithm](bytes, { expected, list })
-  const key = `${what}.${ext}`
+  const digest = (bytes) => DIGESTS[algorithm](bytes, { expected, list, symlinksAbove })
+  const key = `${entry}.${ext}`
   for (const path of ours ? [...local, ...ourCachePaths(dir, key)] : local) {
     const bytes = await readRegularFile(path)
     if (bytes && await digest(bytes) === expected) return bytes
@@ -34,10 +37,10 @@ export async function verifiedDownload({ method, dir, what, ext, algorithm, expe
     assert.ok(actual === expected, `${method}: integrity mismatch for ${what} from ${from}: expected ${expected}, got ${actual}`)
     return bytes
   }
-  const cached = await readBytes(dir, what, key, cache)
+  const cached = await readBytes(dir, entry, key, cache)
   if (cached) return await check(cached, cache ? 'the store' : 'the cache')
   const url = await locate()
   const bytes = await check(await request(url, { ...options, as: 'bytes' }), url)
-  await writeBytes(dir, what, key, bytes, cache)
+  await writeBytes(dir, entry, key, bytes, cache)
   return bytes
 }

package/src/git.js

@@ -52,7 +52,6 @@ export async function findGitCheckout(dir) {
   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)
+  const [github, commit] = await Promise.all([originGitHub(dirs.commonDir), headCommit(dirs.gitDir, dirs.commonDir)])
   return { ...(github && { github }), directory, ...(github && { url: `https://github.com/${github}` }), ...(commit && { commit }) }
 }

package/src/github/read.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
 
-import { assertArgs, assertBoolean, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isRepo, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
+import { assertArgs, assertBoolean, assertGhsa, assertLevels, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, assertion, isRefName, isRepo, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
 import { HttpError, decode, encodeSegment, requestWithHeaders } from '../http.js'
 import { FORMATS, lockfileOf, projectFormats } from '../lockfiles.js'
@@ -111,6 +111,49 @@ async function listRepoTags(headers, options) {
   })
 }
 
+// GitHub lists each branch with the commit at its head.
+async function listRepoBranches(headers, options) {
+  assertArgs('listRepoBranches', options, { repo: assertRepo, maxPages: optional(assertNumber) })
+  const { repo, maxPages } = options
+  const branches = await paginate('listRepoBranches', headers, (paging) => repoApi(repo, ['branches'], paging), maxPages)
+  return branches.map((entry) => {
+    assert.ok(isRefName(entry?.name) && isSha(entry.commit?.sha), `listRepoBranches: GitHub listed ${show(entry?.name)} in ${repo}, which is no branch name with a commit`)
+    return { branch: entry.name, oid: entry.commit.sha }
+  })
+}
+
+const assertRevision = assertion('a full commit sha, or a branch or tag name', (value) => isSha(value) || isRefName(value))
+// What GitHub's compare says of the counts it gives with it.
+const COMPARED = {
+  ahead: (ahead, behind) => ahead > 0 && behind === 0,
+  behind: (ahead, behind) => ahead === 0 && behind > 0,
+  identical: (ahead, behind) => ahead === 0 && behind === 0,
+  diverged: (ahead, behind) => ahead > 0 && behind > 0,
+}
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0
+
+// How `head` stands to `base` in the repo, as GitHub's compare tells it:
+// `ahead` where `base` is in `head`'s history, `behind` the other way round,
+// `identical`, or `diverged`; with the commits each has that the other
+// hasn't, and their merge base. Refused unless the status agrees with those
+// counts, the merge base is `base` where `head` is ahead of it or the same,
+// and the base GitHub compared is `base` where that is a commit. GitHub
+// answers for a commit of any fork of the repo too: whether one is the
+// repo's own is whether a ref of the repo has it in its history.
+async function compareCommits(headers, options) {
+  assertArgs('compareCommits', options, { repo: assertRepo, base: assertRevision, head: assertRevision })
+  const { repo, base, head } = options
+  const body = await call(headers, repoApi(repo, ['compare', `${encodeSegment(base)}...${encodeSegment(head)}`], { per_page: 1 }))
+  const { status, ahead_by: aheadBy, behind_by: behindBy } = body ?? {}
+  const baseCommit = body?.base_commit?.sha
+  const mergeBase = body?.merge_base_commit?.sha
+  assert.ok(Object.hasOwn(COMPARED, status) && isCount(aheadBy) && isCount(behindBy) && COMPARED[status](aheadBy, behindBy),
+    `compareCommits: GitHub compared ${repo} ${base}...${head} as ${show(status)}, ${show(aheadBy)} ahead and ${show(behindBy)} behind`)
+  assert.ok(isSha(baseCommit) && isSha(mergeBase) && (!isSha(base) || baseCommit === base) && (!['ahead', 'identical'].includes(status) || mergeBase === baseCommit),
+    `compareCommits: GitHub compared ${repo} ${base}...${head} from ${show(baseCommit)}, merge base ${show(mergeBase)}`)
+  return { status, aheadBy, behindBy, mergeBase }
+}
+
 // 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,
@@ -137,14 +180,15 @@ async function getRepoFile(headers, options) {
 // with nothing in it or the LF blob of a file marked `eol=crlf`, comes
 // from GitHub's listings of the trees, which the id checks as well: a
 // directory at a time, as a recursive listing of a large tree is cut short.
-async function treeTarball(method, headers, repo, tree) {
+// Its symlinks climb no more than `symlinksAbove` levels above its root.
+async function treeTarball(method, headers, repo, tree, symlinksAbove) {
   const listings = new Map()
   const list = (sha) => {
     if (!listings.has(sha)) listings.set(sha, call(headers, repoApi(repo, ['git', 'trees', sha])).then((listing) => (Array.isArray(listing?.tree) ? listing.tree : [])))
     return listings.get(sha)
   }
   const locate = () => repoApi(repo, ['tarball', tree])
-  return await verifiedDownload({ method, dir: 'github/trees', what: tree, ext: 'tgz', algorithm: 'tree', expected: tree, locate, options: { headers, redirect: 'follow' }, list })
+  return await verifiedDownload({ method, dir: 'github/trees', what: tree, ext: 'tgz', algorithm: 'tree', expected: tree, locate, options: { headers, redirect: 'follow' }, list, symlinksAbove })
 }
 
 async function commitTree(method, headers, repo, sha) {
@@ -157,15 +201,15 @@ async function commitTree(method, headers, repo, sha) {
 // now. Its tree's tarball, not its own, in which `git archive` rewrites the
 // files marked `export-subst`.
 async function getRepoTarball(headers, options) {
-  assertArgs('getRepoTarball', options, { repo: assertRepo, sha: assertSha })
-  const { repo, sha } = options
+  assertArgs('getRepoTarball', options, { repo: assertRepo, sha: assertSha, symlinksAbove: optional(assertLevels) })
+  const { repo, sha, symlinksAbove } = options
   const tree = await commitTree('getRepoTarball', headers, repo, sha)
-  return await treeTarball('getRepoTarball', headers, repo, tree)
+  return await treeTarball('getRepoTarball', headers, repo, tree, symlinksAbove)
 }
 
 async function getRepoTreeTarball(headers, options) {
-  assertArgs('getRepoTreeTarball', options, { repo: assertRepo, tree: assertTreeId })
-  return await treeTarball('getRepoTreeTarball', headers, options.repo, options.tree)
+  assertArgs('getRepoTreeTarball', options, { repo: assertRepo, tree: assertTreeId, symlinksAbove: optional(assertLevels) })
+  return await treeTarball('getRepoTreeTarball', headers, options.repo, options.tree, options.symlinksAbove)
 }
 
 // Not recursive: GitHub cuts short a recursive listing of a large tree.
@@ -304,5 +348,5 @@ async function listRepoAdvisories(headers, options) {
   return (await Array.fromAsync(cursorPages('listRepoAdvisories', headers, pageUrl))).flat()
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, findRepoLockfiles, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, listRepoBranches, compareCommits, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, findRepoLockfiles, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/http.js

@@ -15,9 +15,10 @@ export const CRATES_INDEX = 'https://index.crates.io'
 export const CRATES_STATIC = 'https://static.crates.io'
 export const SOLDEER_API = 'https://api.soldeer.xyz'
 export const SOLDEER_REVISIONS = 'https://soldeer-revisions.s3.amazonaws.com'
+export const COCOAPODS_CDN = 'https://cdn.cocoapods.org'
 export const MAX_BYTES = 512 * 1024 * 1024
 
-const ORIGINS = new Set([NPM_REGISTRY, GITHUB_API, OSV_API, CRATES_API, PACKAGIST_REPO, CRATES_INDEX, CRATES_STATIC, SOLDEER_API, SOLDEER_REVISIONS])
+const ORIGINS = new Set([NPM_REGISTRY, GITHUB_API, OSV_API, CRATES_API, PACKAGIST_REPO, CRATES_INDEX, CRATES_STATIC, SOLDEER_API, SOLDEER_REVISIONS, COCOAPODS_CDN])
 const isSegment = matches(/^(?!\.\.?$)(?:[\w.~@-]|%[\dA-F]{2})+$/u)
 const isQueryKey = matches(/^[a-z_]+(?:\[\])?$/u)
 const isQueryValue = (value) => (typeof value === 'string' && value !== '') || (Number.isSafeInteger(value) && value >= 0)

package/src/npm/cacache.js

@@ -13,6 +13,7 @@ import { readRegularFile } from '../cache.js'
 const KEY = 'make-fetch-happen:request-cache:'
 const digest = (algorithm, data, encoding) => createHash(algorithm).update(data).digest(encoding)
 const shard = (hex) => [hex.slice(0, 2), hex.slice(2, 4), hex.slice(4)]
+export const contentPath = (cache, sha512) => join(cache, 'content-v2', 'sha512', ...shard(Buffer.from(sha512, 'base64').toString('hex')))
 const decoder = new TextDecoder('utf-8')
 
 async function lastEntry(root, key) {
@@ -39,6 +40,6 @@ export async function readNpmCached(root, url) {
   const integrity = typeof entry?.integrity === 'string' ? entry.integrity : ''
   const sha512 = /(?:^|\s)sha512-([\d+/A-Za-z]+={0,2})(?=[\s?]|$)/u.exec(integrity)?.[1]
   if (sha512 === undefined) return null
-  const body = await readRegularFile(join(root, 'content-v2', 'sha512', ...shard(Buffer.from(sha512, 'base64').toString('hex'))))
+  const body = await readRegularFile(contentPath(root, sha512))
   return body && digest('sha512', body, 'base64') === sha512 ? { body, metadata: entry.metadata } : null
 }

package/src/npm/tarball.js

@@ -1,4 +1,3 @@
-import { Buffer } from 'node:buffer'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
@@ -6,7 +5,7 @@ import { assertArgs, assertPackage, assertPackageName, isPlainObject, isSha, opt
 import { assertCache } from '../cache.js'
 import { verifiedDownload } from '../download.js'
 import { NPM_REGISTRY, decode } from '../http.js'
-import { readNpmCached } from './cacache.js'
+import { contentPath, readNpmCached } from './cacache.js'
 import { getDocument, withNpmToken } from './registry.js'
 import { checkedDist, getVersion, matchingDist } from './versions.js'
 
@@ -25,8 +24,7 @@ function npmCacheDirs() {
 // npm 5+ (cacache) files a tarball by its sha512, npm 4 and before as
 // <name>/<version>/package.tgz; ~/.audit as <org>:<name>-<version>.tgz.
 function localPaths(name, version, integrity) {
-  const hex = Buffer.from(integrity.slice('sha512-'.length), 'base64').toString('hex')
-  const npm = npmCacheDirs().flatMap((root) => [join(root, '_cacache/content-v2/sha512', hex.slice(0, 2), hex.slice(2, 4), hex.slice(4)), join(root, name, version, 'package.tgz')])
+  const npm = npmCacheDirs().flatMap((root) => [contentPath(join(root, '_cacache'), integrity.slice('sha512-'.length)), join(root, name, version, 'package.tgz')])
   return [...npm, join(homedir(), '.audit/cache/tgz', `${name.replace(/^@/u, '').replace('/', ':')}-${version}.tgz`)]
 }
 
@@ -117,7 +115,7 @@ export async function getPublishTimes(name) {
   const time = record(json.time)
   const times = new Map()
   for (const version of Object.keys(record(json.versions))) {
-    const at = readTime(Object.hasOwn(time, version) ? time[version] : undefined)
+    const at = readTime(own(time, version))
     if (at !== undefined) times.set(version, at)
   }
   return times

package/src/tree.js

@@ -1,56 +1,34 @@
 import { Buffer } from 'node:buffer'
 import { createHash } from 'node:crypto'
-import { gunzipSync } from 'node:zlib'
+
+import { CompressionError, decompress } from '@preventive/archive/compression.js'
+import { ArchiveError, unpackStream } from '@preventive/archive/tar.js'
 
 import { isSha1, matches } from './args.js'
 import { withAttributes, writtenWithCrlf } from './attributes.js'
 
-const BLOCK = 512
 const MAX_UNPACKED_BYTES = 2 ** 30
-// Only what git writes is read: anything else, a pax `size` or a mode of
-// 0000, would be extracted as it is not hashed. Modes are as its umask,
-// 002 or 022, leaves them: a file 0664 or 0644, 0775 or 0755 executable;
-// a directory 0775 or 0755; a symlink 0777.
+// Read by @preventive/archive, which holds a tarball to its checks -- each
+// header's checksum and fields, the padding and the end, pax records of
+// which none repeats, names and link targets that stay within it, no name
+// twice as another entry -- and past those to only what git writes:
+// anything else, a pax `size` or a mode of 0000, would be extracted as it
+// is not hashed. POSIX ustar headers, as under GNU's magic a reader that
+// knows none takes GNU's own bytes for a name's prefix, their numbers as
+// octal digits; no extended header but an entry's own pax one; type flags
+// and modes as stored. Modes are as
+// its umask, 002 or 022, leaves them: a file 0664 or 0644, 0775 or 0755
+// executable; a directory 0775 or 0755; a symlink 0777.
 const PAX_KEYS = new Set(['path', 'linkpath'])
 const MODES = { 0: [0o664, 0o644, 0o775, 0o755], 2: [0o777], 5: [0o775, 0o755] }
+// The extended headers git does not write, by the type a tar names them by.
+const FLAGS = { global: 'g', longname: 'L', longlink: 'K' }
 // The top directory is not hashed, so it is held to GitHub's name for it,
 // owner-repo-id: another, `..\..`, `C:` or a Windows device such as
 // `con.txt`, could take an extractor elsewhere.
 const isTop = matches(/^(?!(?:con|prn|aux|nul|com\d|lpt\d)(?:\.|$))[\da-z][\w.-]*$/iu)
 
-// Names are kept as latin1 strings, a char per byte, so they sort and hash
-// as the bytes git has.
-const field = (header, start, end) => {
-  const bytes = header.subarray(start, end)
-  const nul = bytes.indexOf(0)
-  return Buffer.from(nul === -1 ? bytes : bytes.subarray(0, nul)).toString('latin1')
-}
-const octal = (header, start, end) => {
-  const text = field(header, start, end).trim()
-  return /^[0-7]{1,12}$/u.test(text) ? Number.parseInt(text, 8) : Number.NaN
-}
 export const objectId = (type, content) => createHash('sha1').update(`${type} ${content.length}\0`).update(content).digest()
-const checksum = (header) => header.reduce((sum, byte, i) => sum + (i >= 148 && i < 156 ? 32 : byte), 0)
-const isZero = (bytes) => bytes.every((byte) => byte === 0)
-
-// `<length> <key>=<value>\n`, the length counting the whole record. A NUL
-// would end a path for an extractor, and a name in a tree for git.
-function paxRecords(body) {
-  const text = Buffer.from(body).toString('latin1')
-  const records = new Map()
-  for (let at = 0; at < text.length;) {
-    const space = text.indexOf(' ', at)
-    const length = text.slice(at, space)
-    const end = at + Number(length)
-    if (!/^[1-9]\d*$/u.test(length) || end > text.length || text[end - 1] !== '\n') return null
-    const record = text.slice(space + 1, end - 1)
-    const equals = record.indexOf('=')
-    if (equals < 1 || record.includes('\0')) return null
-    records.set(record.slice(0, equals), record.slice(equals + 1))
-    at = end
-  }
-  return records
-}
 
 // Git keeps no empty directory: in a tarball, one is a submodule. Each as
 // [the directory holding it, its name, its path].
@@ -73,6 +51,8 @@ function treeId(dir) {
 const EMPTY_TREE = objectId('tree', Buffer.alloc(0)).toString('hex')
 const isName = matches(/^[^\0/]+$/u)
 const isEntry = (entry) => isName(entry?.path) && isSha1(entry.sha)
+// Names are kept as latin1 strings of their UTF-8, a char per byte, so they
+// sort and hash as the bytes git has.
 const nameOf = (path) => Buffer.from(path).toString('latin1')
 const subtree = (sha) => ({ mode: '40000', id: Buffer.from(sha, 'hex') })
 
@@ -139,6 +119,35 @@ async function mend(dir, sha, listed, base = '', above = []) {
   }
 }
 
+// One entry of a tarball into `root`, the tree being built, whose top
+// directory is `top`, the first entry's: a reason where git writes no such
+// entry there, else nothing.
+function take(root, { storedName, storedLinkname, typeflag, storedMode, uid, gid, uname, gname, data, pax, extended, magic, octal }, top) {
+  const path = nameOf(storedName)
+  const flag = extended.find(({ kind }) => kind !== 'pax')
+  if (flag !== undefined) return `no tree: an entry of type ${JSON.stringify(FLAGS[flag.kind])}`
+  if (magic !== 'ustar' || extended.some((header) => header.magic !== 'ustar')) return 'no tree: a header that is not POSIX ustar'
+  const other = [...pax.keys()].find((key) => !PAX_KEYS.has(key))
+  if (other !== undefined) return `no tree: a pax record git does not write, ${JSON.stringify(other)}`
+  if (!Object.hasOwn(MODES, typeflag)) return `no tree: an entry of type ${JSON.stringify(typeflag)}`
+  const asGitWrites = MODES[typeflag].includes(storedMode) && path.endsWith('/') === (typeflag === '5')
+    && uid === 0 && gid === 0 && uname === 'root' && gname === 'root'
+    && octal && extended.every((header) => header.octal)
+  if (!asGitWrites) return `no tree: a header git does not write, ${JSON.stringify(path)}`
+  const [first, ...parts] = path.replace(/\/$/u, '').split('/')
+  const name = typeflag === '5' ? null : parts.pop()
+  if (!isTop(first) || first !== top || name === undefined || [...parts, name].some((part) => ['', '.', '..'].includes(part))) return `no tree: an entry outside one top directory, ${JSON.stringify(path)}`
+  let dir = root
+  for (const part of parts) {
+    if (!dir.has(part)) dir.set(part, new Map())
+    dir = dir.get(part)
+    if (!(dir instanceof Map)) return `no tree: a file where a directory is, ${JSON.stringify(path)}`
+  }
+  if (name === null) return
+  if (dir.has(name)) return `no tree: ${JSON.stringify(path)} twice`
+  dir.set(name, typeflag === '0' ? { mode: storedMode & 0o100 ? '100755' : '100644', id: objectId('blob', data), body: data } : { mode: '120000', id: objectId('blob', Buffer.from(storedLinkname)) })
+}
+
 // The id of the git tree a gzipped tarball holds, as `git archive` writes
 // one, under a single top directory: a file's mode is its exec bit, a
 // symlink's blob its target. What a tarball cannot show comes from `list`,
@@ -147,62 +156,31 @@ async function mend(dir, sha, listed, base = '', above = []) {
 // commit for an empty directory, and, where the id comes out otherwise, the
 // subtrees with nothing in them it leaves out and the blobs of the files it
 // wrote with CRLF for `eol=crlf`. The id is `expected` only if those are
-// right. Where there is no such tree, a reason, never an id.
-export async function gitTreeOfTarball(gzipped, { expected, list } = {}) {
-  let bytes
+// right. Where there is no such tree, a reason, never an id. A symlink may
+// climb `symlinksAbove` levels above the tarball's root, none unless given,
+// as @preventive/archive lets it: a subtree's, linking to the tree's root
+// as a monorepo package's LICENSE does, as many as it is deep, less one.
+export async function gitTreeOfTarball(gzipped, { expected, list, symlinksAbove = 0 } = {}) {
+  let tar
   try {
-    bytes = gunzipSync(gzipped, { maxOutputLength: MAX_UNPACKED_BYTES })
-  } catch {
-    return 'no tree: not gzip, or larger than 1 GiB unpacked'
+    tar = await decompress(gzipped, 'gzip', { limit: MAX_UNPACKED_BYTES })
+  } catch (error) {
+    if (error instanceof CompressionError) return 'no tree: not gzip, or larger than 1 GiB unpacked'
+    throw error
   }
   const root = new Map()
   let top
-  let pax = null
-  for (let at = 0; ;) {
-    const header = bytes.subarray(at, at + BLOCK)
-    if (header.length < BLOCK) return 'no tree: the tarball is cut short'
-    if (isZero(header)) {
-      if (!isZero(bytes.subarray(at))) return 'no tree: data after the end of the tarball'
-      break
-    }
-    if (Buffer.from(header.subarray(257, 265)).toString('latin1') !== 'ustar\u000000') return 'no tree: a header that is not POSIX ustar'
-    if (octal(header, 148, 156) !== checksum(header)) return 'no tree: a header that fails its checksum'
-    const size = octal(header, 124, 136)
-    const body = bytes.subarray(at + BLOCK, at + BLOCK + size)
-    if (body.length !== size) return 'no tree: the tarball is cut short'
-    at += BLOCK + Math.ceil(size / BLOCK) * BLOCK
-    const type = String.fromCodePoint(header[156])
-    if (type === 'x') {
-      const records = paxRecords(body)
-      if (records === null) return 'no tree: a malformed pax header'
-      const other = [...records.keys()].find((key) => !PAX_KEYS.has(key))
-      if (other !== undefined) return `no tree: a pax record git does not write, ${JSON.stringify(other)}`
-      if (pax !== null) return 'no tree: two pax headers for one entry'
-      pax = records
-      continue
-    }
-    const prefix = field(header, 345, 500)
-    const path = pax?.get('path') ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100))
-    const target = pax?.get('linkpath') ?? field(header, 157, 257)
-    pax = null
-    if (!Object.hasOwn(MODES, type)) return `no tree: an entry of type ${JSON.stringify(type)}`
-    const mode = octal(header, 100, 108)
-    const asGitWrites = MODES[type].includes(mode) && (type === '0' || size === 0) && path.endsWith('/') === (type === '5')
-      && octal(header, 108, 116) === 0 && octal(header, 116, 124) === 0 && field(header, 265, 297) === 'root' && field(header, 297, 329) === 'root'
-    if (!asGitWrites) return `no tree: a header git does not write, ${JSON.stringify(path)}`
-    const [first, ...parts] = path.replace(/\/$/u, '').split('/')
-    top ??= first
-    const name = type === '5' ? null : parts.pop()
-    if (!isTop(first) || first !== top || name === undefined || [...parts, name].some((part) => ['', '.', '..'].includes(part))) return `no tree: an entry outside one top directory, ${JSON.stringify(path)}`
-    let dir = root
-    for (const part of parts) {
-      if (!dir.has(part)) dir.set(part, new Map())
-      dir = dir.get(part)
-      if (!(dir instanceof Map)) return `no tree: a file where a directory is, ${JSON.stringify(path)}`
+  // An entry at a time, each taken into the tree as it is read, its data a
+  // view of the tar: a header that repeats an earlier one, which git never
+  // writes, is refused where it stands, so no run of them is held.
+  try {
+    for await (const entry of unpackStream([tar], { symlinksAbove })) {
+      const reason = take(root, entry, top ??= nameOf(entry.storedName).split('/')[0])
+      if (reason !== undefined) return reason
     }
-    if (name === null) continue
-    if (dir.has(name)) return `no tree: ${JSON.stringify(path)} twice`
-    dir.set(name, type === '0' ? { mode: mode & 0o100 ? '100755' : '100644', id: objectId('blob', body), body } : { mode: '120000', id: objectId('blob', Buffer.from(target, 'latin1')) })
+  } catch (error) {
+    if (error instanceof ArchiveError) return `no tree: ${error.message}`
+    throw error
   }
   if (top === undefined) return 'no tree: an empty tarball'
   const listed = async (sha) => (list && isSha1(sha) ? await list(sha) : [])