@preventive/upstream 1.0.0-alpha.3 → 1.0.0-alpha.4

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/advisories.d.ts

@@ -6,28 +6,32 @@ import type { Client, RepoName } from './github.js'
 export { HttpError } from './npm.js'
 
 // As purl and stasis name them.
-export type Ecosystem = 'npm' | 'cargo' | 'composer' | 'github'
+export type Ecosystem = 'npm' | 'cargo' | 'composer' | 'soldeer' | 'github'
 
 export interface Package {
   ecosystem: Ecosystem
-  // An npm package name, a crate name, a Composer `vendor/name`, or for
-  // `github`, the repository `owner/name` itself.
+  // An npm package name, a crate name, a Composer `vendor/name`, a Soldeer
+  // project name, or for `github`, the repository `owner/name` itself.
   name: string
   // Its GitHub repository, where the caller knows it (package.json,
   // Cargo.toml, installed.json), for `repoAdvisories` to ask without
-  // looking it up; not for `github` packages, which are their own.
+  // looking it up, and for a `soldeer` package, to ask instead of the one
+  // Soldeer names; not for `github` packages, which are their own.
   github?: RepoName
   // npm and `github`: semver; `github` also takes a branch name or 0.0.0,
   // which every range covers. cargo: semver, build metadata allowed.
   // composer: a release (`v1.2.3`, `1.2.3.4`, `2.0.0-RC1`), dev versions
-  // refused; one semver cannot read is covered by every range.
+  // refused; one semver cannot read is covered by every range. soldeer: as
+  // soldeer.lock has it; one semver cannot read (a bare number, a commit)
+  // is covered by every range.
   versions: string[]
 }
 
 export interface AdvisoryOptions {
-  // The client every GitHub request goes through. Required for `github`
-  // packages, whose repository's published advisories are their only
-  // source, and for `repoAdvisories`; by itself it asks nothing else.
+  // The client every GitHub request goes through. Required for `soldeer`
+  // and `github` packages, whose repository's published advisories are
+  // their only source, and for `repoAdvisories`; by itself it asks nothing
+  // else.
   github?: Client
   // Also asks each npm, cargo and composer package's GitHub repository
   // for its published advisories, which it has before GitHub reviews them
@@ -43,13 +47,18 @@ export interface Advisory {
   ecosystem: Ecosystem
   name: string
   // `registry`: npm's, as `npm audit` has it, one row per vulnerable
-  // range. `osv`: RustSec for cargo, OSV's Packagist records for composer.
+  // range. `osv`: OSV's records for cargo and composer, RustSec's, GitHub's
+  // and malicious packages' (MAL-…) among them; of the records naming each
+  // other as aliases, directly or through others, a version is reported
+  // under one only: RustSec's, else the GHSA, else the first by id. Each
+  // has the others' ids among its aliases.
   // `repository`: published on the package's repository, one row per
   // range, holding only the versions the others' answer does not report
-  // under that GHSA.
+  // under that GHSA. The only source for `soldeer` and `github`, where
+  // every range counts, whichever package it names.
   source: 'registry' | 'osv' | 'repository'
-  // A GHSA, RUSTSEC-…, DRUPAL-CORE-…, or npm:<id> for a registry row
-  // without a GHSA.
+  // A GHSA, RUSTSEC-…, MAL-…, DRUPAL-CORE-… or another OSV id, or
+  // npm:<id> for a registry row without a GHSA.
   id: string
   // The id itself, or an OSV record's one GHSA alias.
   ghsa?: string
@@ -75,8 +84,10 @@ export interface Advisory {
 // Every package, and every one of its versions, is checked against its
 // ecosystem's rules before the first request; a name given twice is
 // merged, and must not name two repositories. npm is asked 250 names a
-// request, OSV 1000 versions; a repository gone, renamed or blocked adds
-// nothing. Any other failure, a malformed answer, or one about something
-// not asked, throws: nothing is left out quietly. Sorted by ecosystem and
-// name. Versions are matched by npm's semver, from the npm beside node.
+// request, OSV 1000 versions, Soldeer one project; a project Soldeer does
+// not have or that names no GitHub repository, and a repository gone,
+// renamed or blocked, add nothing. Any other failure, a malformed answer,
+// or one about something not asked, throws: nothing is left out quietly.
+// Sorted by ecosystem and name. Versions are matched by npm's semver, from
+// the npm beside node.
 export function advisories(packages: Iterable<Package>, options?: AdvisoryOptions): Promise<Advisory[]>

package/cargo.d.ts

@@ -1,11 +1,16 @@
 // Hand-written against cargo.js; a change to either belongs with the other.
 //
-// The name is asserted to be a crate name, the version an exact semver
+// A name is asserted to be a crate name, a version an exact semver
 // version, and a checksum 64 lowercase hex digits, before any request or
 // cache path. The cache is setCacheDir's (npm.js).
 
 export { HttpError } from './npm.js'
 
+// Reads crates.io's index for that version and throws unless its sha256
+// is the one given, as for a checksum read off Cargo.lock. The index is
+// read on every call; nothing is cached.
+export function verifyChecksum(name: string, version: string, checksum: string): Promise<void>
+
 // A published version's .crate, whole, in memory. `checksum` is its
 // sha256 as Cargo.lock records it; without one, crates.io's index is read
 // for it on every call, cached crate or not. Either way the bytes are
@@ -17,3 +22,15 @@ export { HttpError } from './npm.js'
 // `~/.cargo`. A file there that does not match is passed over. One in
 // setCacheDir's cache that does not match throws.
 export function getCrate(name: string, version: string, checksum?: string): Promise<Uint8Array>
+
+// What resolveCrateRepos maps each resolved name to: `owner/name`, the
+// GitHub repo the crate's `repository` on crates.io names.
+export interface CrateRepo {
+  github: string
+}
+// Fail-soft, as npm.js's resolvePackageRepos: a crate crates.io does not
+// have, one naming no GitHub repo, and those of a request that fails are
+// absent from the map. crates.io is asked a hundred names a request, a
+// second apart, as it asks; a repo found is cached for a month, and
+// `cachedOnly` answers from that cache alone and never fetches.
+export function resolveCrateRepos(crateNames: Iterable<string>, options?: { cachedOnly?: boolean }): Promise<Map<string, CrateRepo>>

package/cargo.js

@@ -1,2 +1,3 @@
-export { getCrate } from './src/cargo.js'
+export { getCrate, verifyChecksum } from './src/cargo/crate.js'
+export { resolveCrateRepos } from './src/cargo/repos.js'
 export { HttpError } from './src/http.js'

package/github.d.ts

@@ -65,16 +65,20 @@ export interface Client {
   getRepoFile(options: { repo: RepoName; path: string; ref?: string }): Promise<string>
   // The head of `branch`, or of the default branch without one.
   getRepoHead(options: { repo: RepoName; branch?: string }): Promise<{ branch: string; oid: string }>
+  // The commit `tag` names: GitHub's ref for exactly that tag, an annotated
+  // one's tag object followed to the commit, through up to 8 tags of tags.
+  // Refused for a tag on anything but a commit.
+  getRepoTag(options: { repo: RepoName; tag: string }): Promise<{ tag: string; oid: string }>
   // The repo's gzipped tarball at the full commit `sha`, whole, in memory:
   // 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>
-  // The id of the tree at `path`, a directory, 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, each hashed back to its
-  // id. Refused where `path` is no directory.
-  getRepoTreeId(options: { repo: RepoName; sha: string; path?: string }): Promise<string>
+  // 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,
+  // each hashed back to its id. Refused where `directory` is none.
+  getRepoTreeId(options: { repo: RepoName; sha: string; directory?: string }): Promise<string>
   // The gzipped tarball of a tree, the repo's own or any subdirectory's, by
   // its id, whole, in memory: GitHub's, its files under one top directory.
   // Its files are hashed back into git's tree and the id must be `tree`,
@@ -90,13 +94,19 @@ export interface Client {
   // has; that repo still gets a tree already cached, pointers and all.
   getRepoTreeTarball(options: { repo: RepoName; tree: string }): Promise<Uint8Array>
   // The repository's published security advisories, as GitHub's
-  // repository advisory objects. One page of 100: GitHub pages this list
-  // by cursor, so a repository with a full page is refused.
+  // 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
+  // error.
   listRepoAdvisories(options: { repo: RepoName }): Promise<any[]>
-  // The entries of the directory at `path` in the full commit `sha`, or of
-  // its root, 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; path?: string }): Promise<RepoDirEntry[]>
+  // The entries of `directory` in the full commit `sha`, or of its root,
+  // 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 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
+  // of 100 is an error, as is a tag with no commit.
+  listRepoTags(options: { repo: RepoName; maxPages?: number }): Promise<{ tag: string; oid: string }[]>
   // Every page of `GET /user/repos`, as GitHub's repository objects; more
   // than `maxPages` (100 by default) pages of 100 is an error.
   listUserRepos(options?: { maxPages?: number }): Promise<any[]>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "Minimal npm, crates.io and Soldeer registry clients, a GitHub client, and a git checkout reader: the calls we use, nothing more",
   "type": "module",
   "exports": {
@@ -42,6 +42,8 @@
     }
   },
   "files": [
+    "LICENSE-APACHE",
+    "LICENSE-MIT",
     "advisories.d.ts",
     "advisories.js",
     "cargo.d.ts",
@@ -68,7 +70,8 @@
     "src/advisories/repos.js",
     "src/args.js",
     "src/cache.js",
-    "src/cargo.js",
+    "src/cargo/crate.js",
+    "src/cargo/repos.js",
     "src/download.js",
     "src/git.js",
     "src/github/client.js",
@@ -90,7 +93,7 @@
   "scripts": {
     "test": "node --test ./tests/*.test.js"
   },
-  "license": "MIT",
+  "license": "MIT OR Apache-2.0",
   "author": {
     "name": "Nikita Skovoroda",
     "email": "chalkerx@gmail.com",

package/src/advisories/common.js

@@ -1,5 +1,5 @@
 import { isStrings, matches } from '../args.js'
-import { satisfies, validRange } from '../semver.js'
+import { satisfies, valid, validRange } from '../semver.js'
 
 export const order = (a, b) => (a > b) - (a < b)
 
@@ -8,9 +8,13 @@ const SEMVER = { includePrerelease: true, loose: true }
 
 export const inRange = (version, range) => satisfies(version, range, SEMVER)
 
-// The asked versions a range `covers`. One semver cannot read covers them
-// all: a missed advisory is worse than a spare one.
-export const covered = (asked, range, covers = inRange) => (validRange(range, SEMVER) === null ? [...asked] : asked.filter((version) => covers(version, range)))
+// A version semver cannot read may be in any range. Whatever it reads is
+// a version, `v1.2.3` and `1.2.3+build` included.
+export const mayBeInRange = (version, range) => valid(version) === null || inRange(version, range)
+
+// The asked versions a range `covers`. One semver cannot read, range or
+// version, covers them all: a missed advisory is worse than a spare one.
+export const covered = (asked, range, covers = mayBeInRange) => (validRange(range, SEMVER) === null ? [...asked] : asked.filter((version) => covers(version, range)))
 
 // Remote text, as long as it is well-formed; anything else is refused as
 // malformed by whoever reads it.

package/src/advisories/github.js

@@ -1,11 +1,11 @@
 import assert from 'node:assert/strict'
 
-import { assertRepo, assertion, isGhsa, isRefName, isStrings } from '../args.js'
+import { assertRepo, assertSoldeerName, assertSoldeerVersion, assertion, isGhsa, isRefName, isStrings } from '../args.js'
 import { isGone } from '../github/client.js'
 import { recover } from '../http.js'
 import { pool } from '../pool.js'
-import { valid } from '../semver.js'
-import { covered, inRange, isText, metrics } from './common.js'
+import { covered, isText, mayBeInRange, metrics } from './common.js'
+import { soldeerRepos } from './repos.js'
 
 const REPOS_AT_ONCE = 4
 
@@ -59,6 +59,12 @@ async function repositoryAdvisories(github, asked, { repoOf, takes = () => true,
   return [...rows.values()]
 }
 
+// Each asked name's repository: as given, `known`, or else looked up.
+async function reposOf(asked, known, lookUp) {
+  const found = await lookUp([...asked.keys()].filter((name) => !known.has(name)))
+  return (name) => known.get(name) ?? found.get(name)
+}
+
 // A maintainer's advisory is on the repository before GitHub reviews it
 // into the databases the registries answer from. With `repoAdvisories`,
 // each package's repository, `known` or else looked up, adds what it
@@ -67,22 +73,32 @@ async function repositoryAdvisories(github, asked, { repoOf, takes = () => true,
 export async function withRepositories(rows, asked, { github, repoAdvisories, known }, { ecosystem, lookUp, covers }) {
   if (!repoAdvisories) return rows
   const reported = new Set(rows.flatMap((row) => [row.id, row.ghsa, ...row.aliases].filter(isGhsa).flatMap((id) => row.versions.map((version) => `${row.name} ${id} ${version}`))))
-  const found = await lookUp([...asked.keys()].filter((name) => !known.has(name)))
-  const repoOf = (name) => known.get(name) ?? found.get(name)
+  const repoOf = await reposOf(asked, known, lookUp)
   const takes = (name, pkg) => pkg?.ecosystem === ecosystem && pkg.name === name
   const added = await repositoryAdvisories(github, asked, { repoOf, takes, covers })
   return [...rows, ...added.map((row) => ({ ...row, versions: row.versions.filter((version) => !reported.has(`${row.name} ${row.id} ${version}`)) }))]
 }
 
 // stasis versions a repository with no version of its own by its branch,
-// or 0.0.0: every range covers those. Whatever semver reads is a version,
-// `v1.2.3` and `1.2.3+build` included.
-const coversPlaceholder = (version, range) => version === '0.0.0' || valid(version) === null || inRange(version, range)
+// or 0.0.0: every range covers those.
+const coversPlaceholder = (version, range) => version === '0.0.0' || mayBeInRange(version, range)
 
 // Dependencies that are GitHub repositories themselves: every range their
 // own published advisories list counts, whichever package it names.
 export const GITHUB = {
+  repositoryOnly: true,
   assertName: assertRepo,
   assertVersion: assertion('a version or a branch name', isRefName),
   advisories: (asked, { github }) => repositoryAdvisories(github, asked, { repoOf: (repo) => repo, covers: coversPlaceholder }),
 }
+
+// Soldeer packages, which no advisory database has: the repository each
+// is published from, as given or else as Soldeer's project names it, is
+// their only source, and every range its advisories list counts, whichever
+// package it names (often the npm package the same release went out as).
+export const SOLDEER = {
+  repositoryOnly: true,
+  assertName: assertSoldeerName,
+  assertVersion: assertSoldeerVersion,
+  advisories: async (asked, { github, known }) => await repositoryAdvisories(github, asked, { repoOf: await reposOf(asked, known, soldeerRepos) }),
+}

package/src/advisories/index.js

@@ -2,11 +2,11 @@ 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 { GITHUB, SOLDEER, 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 ECOSYSTEMS = { npm: NPM, cargo: CARGO, composer: COMPOSER, soldeer: SOLDEER, 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)
@@ -37,7 +37,7 @@ 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')
+  for (const ecosystem of byEcosystem.keys()) assert.ok(!ECOSYSTEMS[ecosystem].repositoryOnly || options.github, `advisories: ${ecosystem} 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()

package/src/advisories/osv.js

@@ -13,6 +13,12 @@ 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'])
+// Of the records that publish one advisory, the first answered for a
+// version stands for the rest on it: RustSec's, what `cargo audit` reads
+// and GitHub mirrors, then the GHSA, then any other (MAL-…), then by id.
+const rank = (id) => (id.startsWith('RUSTSEC-') ? 0 : (isGhsa(id) ? 1 : 2))
+const first = (a, b) => rank(a.id) - rank(b.id) || order(a.id, b.id)
+const named = (a, b) => a.aliases.includes(b.id) || b.aliases.includes(a.id)
 
 export const CARGO = {
   osv: 'crates.io',
@@ -20,7 +26,6 @@ export const CARGO = {
   lookUp: crateRepos,
   assertName: assertCrateName,
   assertVersion: assertCrateVersion,
-  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
@@ -70,11 +75,13 @@ function toAdvisory(ecosystem, name, versions, record) {
 }
 
 // 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.
+// each record is fetched once after. An advisory more than one database
+// publishes comes back under each one's id, the records naming each other
+// as aliases, either way round, directly or through others: one group, in
+// which each version is reported under the first answered for it, and
+// each record has the others' ids as aliases.
 async function osvAdvisories(ecosystem, asked, options) {
-  const { osv, github, lookUp, covers, keep = () => true } = ecosystem
+  const { osv, github, lookUp, covers } = ecosystem
   const list = [...asked].flatMap(([name, versions]) => versions.map((version) => ({ name, version })))
   const hits = new Map() // id → name → versions, in `list` order
   for (const chunk of chunks(list, QUERIES_PER_REQUEST)) {
@@ -85,21 +92,28 @@ async function osvAdvisories(ecosystem, asked, options) {
       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))) {
+      for (const { id } of vulns) {
         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 groups = new Map()
+  for (const record of records) {
+    if (groups.has(record)) continue
+    const group = [record]
+    for (const member of group) group.push(...records.filter((other) => !group.includes(other) && named(member, other)))
+    for (const member of group) groups.set(member, group)
+  }
   const rows = []
   for (const record of records) {
+    const group = groups.get(record)
+    const above = group.filter((other) => first(other, record) < 0)
+    const aliases = [...new Set([...record.aliases, ...group.map((other) => other.id)])].filter((id) => id !== record.id)
     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))
+      const rest = [...versions].filter((version) => !above.some((other) => hits.get(other.id).get(name)?.has(version)))
+      if (rest.length > 0) rows.push(toAdvisory(osv, name, rest, { ...record, aliases }))
     }
   }
   rows.sort((a, b) => order(a.name, b.name) || order(a.id, b.id))

package/src/advisories/repos.js

@@ -1,16 +1,13 @@
 import assert from 'node:assert/strict'
-import { setTimeout as sleep } from 'node:timers/promises'
 
 import { isRepo, show } from '../args.js'
 import { readRecord, writeRecord } from '../cache.js'
-import { CRATES_API, PACKAGIST_REPO, buildUrl, isNotFound, recover, request } from '../http.js'
+import { lookUpCrateRepos } from '../cargo/repos.js'
+import { PACKAGIST_REPO, SOLDEER_API, buildUrl, isNotFound, recover, request } from '../http.js'
 import { lookUpPackageRepo } from '../npm/repos.js'
-import { chunks, pool } from '../pool.js'
+import { pool } from '../pool.js'
 import { githubRepoOfUrl } from '../remote.js'
 
-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
@@ -30,22 +27,6 @@ async function cachedRepos(dir, names, fetchMissing) {
   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 (const [i, chunk] of chunks(names, CRATES_PER_REQUEST).entries()) {
-    if (i > 0) await sleep(CRATES_PACE_MS)
-    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]]))
@@ -61,6 +42,15 @@ async function fetchComposerRepo(name) {
   return githubRepoOfUrl(versions[0]?.source?.url) ?? null
 }
 
-export const crateRepos = (names) => cachedRepos('cargo/repos', names, fetchCrates)
+// Soldeer answers a project it does not have with an empty list.
+async function fetchSoldeerRepo(name) {
+  const answer = await request(buildUrl(SOLDEER_API, ['api', 'v1', 'project'], { project_name: name }), { as: 'json' })
+  assert.ok(Array.isArray(answer?.data), `advisories: expected a list of projects from Soldeer for ${name}`)
+  for (const project of answer.data) assert.ok(project?.name === name, `advisories: Soldeer answered for ${show(project?.name)}, not ${name}`)
+  return githubRepoOfUrl(answer.data[0]?.github_url) ?? null
+}
+
+export const crateRepos = (names) => lookUpCrateRepos('advisories', names)
 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)
+export const soldeerRepos = (names) => cachedRepos('soldeer/repos', names, (missing) => fetchEach(missing, fetchSoldeerRepo))

package/src/args.js

@@ -15,7 +15,9 @@ 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
+// git check-ref-format, a rule per alternative. A tag's name may be `@` or
+// start with `-`; a branch's may not.
+const BAD_REF = /^$|[ ~^:?*[\\]|\.\.|@\{|^\/|\/$|\/\/|(?:^|\/)\.|\.lock(?:\/|$)|\.$/u
 const isToken = matches(/^[!-~]+$/u)
 // npm's rules for existing names: capitals allowed (JSONStream), the
 // legacy `~'!()*` not.
@@ -38,7 +40,8 @@ export function isRepo(value) {
 
 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 isTagName = (value) => isString(value, 255) && !BAD_REF.test(value)
+export const isRefName = (value) => isTagName(value) && !/^(?:@$|-)/u.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)}`)
@@ -62,6 +65,7 @@ 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 assertTagName = assertion('a tag name', isTagName)
 export const assertSha = assertion('a full commit sha', isSha)
 export const isSha1 = matches(/^[\da-f]{40}$/u)
 export const assertTreeId = assertion('a full tree id', isSha1)
@@ -74,5 +78,11 @@ export const assertPackageVersion = assertion('an exact semver version', isExact
 export const assertGhsa = assertion('a GHSA id', isGhsa)
 export const assertCrateName = assertion('a crate name', matches(/^[A-Za-z][\w-]{0,63}$/u))
 export const assertCrateVersion = 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))
+// Soldeer's own rule for a name: 3 to 100 of lowercase letters, digits and
+// `-`, starting with one of them or `@`, ending with a letter or digit.
+export const assertSoldeerName = assertion('a Soldeer package name', matches(/^(?=.{3,100}$)[@\da-z][\da-z-]*[\da-z]$/u))
+// 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))
 // As Cargo.lock and soldeer.lock write a checksum.
 export const assertSha256 = assertion('a sha256 in lowercase hex', matches(/^[\da-f]{64}$/u))

package/src/cache.js

@@ -6,7 +6,7 @@ import { dirname, join, resolve } from 'node:path'
 import { assertDirectoryPath } from './args.js'
 import { MAX_BYTES, decode } from './http.js'
 
-const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/zips', 'github/trees'])
+const DIRS = new Set(['npm/repos', 'npm/tarballs', 'cargo/repos', 'cargo/crates', 'composer/repos', 'soldeer/repos', 'soldeer/zips', 'github/trees'])
 const RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000 // A link only moves on a transfer or rename, and GitHub redirects those.
 
 let root

package/src/{cargo.js → cargo/crate.js}

@@ -3,16 +3,16 @@ import { readdir } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
-import { assertCrateName, assertCrateVersion, assertSha256, printable, show } from './args.js'
-import { verifiedDownload } from './download.js'
-import { CRATES_INDEX, CRATES_STATIC, buildUrl, encodeSegment, request } from './http.js'
+import { assertCrateName, assertCrateVersion, assertSha256, printable, show } from '../args.js'
+import { verifiedDownload } from '../download.js'
+import { CRATES_INDEX, CRATES_STATIC, buildUrl, encodeSegment, request } from '../http.js'
 
 const DIR = 'cargo/crates' // No expiry: crates.io never takes a version twice.
 
 // The sparse index, what cargo reads: a file per crate, by its lowercased
 // name under 1/, 2/, 3/<first letter>/ or <1st-2nd>/<3rd-4th>/, with a
 // JSON line per version, `cksum` the .crate's sha256.
-async function getChecksum(name, version) {
+async function getChecksum(method, name, version) {
   const lower = name.toLowerCase()
   const prefix = lower.length < 3 ? [String(lower.length)] : lower.length === 3 ? ['3', lower[0]] : [lower.slice(0, 2), lower.slice(2, 4)]
   const text = await request(buildUrl(CRATES_INDEX, [...prefix, lower]), { as: 'text' })
@@ -20,13 +20,13 @@ async function getChecksum(name, version) {
     try {
       return JSON.parse(line)
     } catch {
-      assert.fail(`getCrate: the index for ${name} has a line that is not JSON: ${printable(line.slice(0, 200))}`)
+      assert.fail(`${method}: the index for ${name} has a line that is not JSON: ${printable(line.slice(0, 200))}`)
     }
   }
   const entry = text.split('\n').filter(Boolean).map(parse).find((candidate) => candidate?.vers === version)
-  assert.ok(entry, `getCrate: the index has no ${name}@${version}`)
-  assert.ok(entry.name === name, `getCrate: the index answered for ${show(entry.name)}, not ${name}`)
-  assertSha256('getCrate', 'the index cksum', entry.cksum)
+  assert.ok(entry, `${method}: the index has no ${name}@${version}`)
+  assert.ok(entry.name === name, `${method}: the index answered for ${show(entry.name)}, not ${name}`)
+  assertSha256(method, 'the index cksum', entry.cksum)
   return entry.cksum
 }
 
@@ -37,11 +37,22 @@ async function localPaths(name, version) {
   return (await readdir(root).catch(() => [])).map((registry) => join(root, registry, `${name}-${version}.crate`))
 }
 
+function assertCrate(method, name, version) {
+  assertCrateName(method, 'name', name)
+  assertCrateVersion(method, 'version', version)
+}
+
+export async function verifyChecksum(name, version, checksum) {
+  assertCrate('verifyChecksum', name, version)
+  assertSha256('verifyChecksum', 'checksum', checksum)
+  const cksum = await getChecksum('verifyChecksum', name, version)
+  assert.ok(cksum === checksum, `verifyChecksum: ${name}@${version} is ${cksum} on crates.io, not ${checksum}`)
+}
+
 export async function getCrate(name, version, checksum) {
-  assertCrateName('getCrate', 'name', name)
-  assertCrateVersion('getCrate', 'version', version)
+  assertCrate('getCrate', name, version)
   if (checksum !== undefined) assertSha256('getCrate', 'checksum', checksum)
-  const expected = checksum ?? await getChecksum(name, version)
+  const expected = checksum ?? await getChecksum('getCrate', name, version)
   const locate = () => buildUrl(CRATES_STATIC, ['crates', name, `${name}-${encodeSegment(version)}.crate`])
   return await verifiedDownload({ method: 'getCrate', dir: DIR, what: `${name}@${version}`, ext: 'crate', algorithm: 'sha256', expected, local: await localPaths(name, version), locate })
 }

package/src/cargo/repos.js

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { assertArgs, assertBoolean, assertCrateName, isRepo, optional, show } from '../args.js'
+import { readRecord, writeRecord } from '../cache.js'
+import { CRATES_API, buildUrl, request } from '../http.js'
+import { chunks } from '../pool.js'
+import { githubRepoOfUrl } from '../remote.js'
+
+const DIR = 'cargo/repos'
+const PER_REQUEST = 100
+const PACE_MS = 1000 // crates.io asks for a request a second at most, and a user agent.
+const USER_AGENT = '@preventive/upstream (https://github.com/PreventiveMeasures/libraries)'
+
+// One request for up to a hundred crates: each name → the GitHub repo its
+// `repository` names, or null where it names none. A crate crates.io
+// leaves out of its answer is one it does not have, null too.
+async function askCrates(method, names) {
+  const url = buildUrl(CRATES_API, ['api', 'v1', 'crates'], { 'ids[]': names, per_page: PER_REQUEST })
+  const answer = await request(url, { as: 'json', headers: { 'User-Agent': USER_AGENT } })
+  assert.ok(Array.isArray(answer?.crates), `${method}: expected a list of crates from crates.io`)
+  const found = new Map(names.map((name) => [name, null]))
+  for (const crate of answer.crates) {
+    assert.ok(names.includes(crate?.id), `${method}: crates.io answered for ${show(crate?.id)}, which was not asked`)
+    found.set(crate.id, githubRepoOfUrl(crate.repository) ?? null)
+  }
+  return found
+}
+
+// Name → its GitHub repo, or null where crates.io has no such crate or it
+// names no GitHub repo, through the cache: only a repo found is cached,
+// for a month. A failed request throws, or with `soft` leaves its names
+// out; `cachedOnly` asks nothing.
+export async function lookUpCrateRepos(method, names, { soft = false, cachedOnly = false } = {}) {
+  const repos = new Map()
+  for (const name of names) {
+    const entry = await readRecord(DIR, name)
+    if (isRepo(entry?.github)) repos.set(name, entry.github)
+  }
+  if (cachedOnly) return repos
+  for (const [i, chunk] of chunks(names.filter((name) => !repos.has(name)), PER_REQUEST).entries()) {
+    if (i > 0) await sleep(PACE_MS)
+    const answer = await askCrates(method, chunk).catch((error) => {
+      if (soft) return new Map()
+      throw error
+    })
+    for (const [name, github] of answer) {
+      repos.set(name, github)
+      if (github) await writeRecord(DIR, name, { github })
+    }
+  }
+  return repos
+}
+
+export async function resolveCrateRepos(crateNames, options = {}) {
+  assert.ok(typeof crateNames?.[Symbol.iterator] === 'function' && typeof crateNames !== 'string', 'resolveCrateRepos: crateNames must be an iterable of names')
+  assertArgs('resolveCrateRepos', options, { cachedOnly: optional(assertBoolean) })
+  const names = [...new Set(crateNames)]
+  for (const name of names) assertCrateName('resolveCrateRepos', 'name', name)
+  const repos = await lookUpCrateRepos('resolveCrateRepos', names, { soft: true, cachedOnly: options.cachedOnly })
+  return new Map(names.flatMap((name) => (repos.get(name) ? [[name, { github: repos.get(name) }]] : [])))
+}

package/src/github/client.js

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict'
 
 import { assertArgs, assertToken, assertTokenOrNull, assertUserAgent, optional } from '../args.js'
-import { GITHUB_API, HttpError, buildUrl, request } from '../http.js'
+import { GITHUB_API, HttpError, buildUrl, request, requestWithHeaders } 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 })
+export const callWithHeaders = (headers, url, options) => requestWithHeaders(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)

package/src/github/read.js

@@ -2,11 +2,11 @@ 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, assertTreeId, isSha, isSha1, optional, sameName, show } from '../args.js'
+import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
 import { decode, encodeSegment } from '../http.js'
 import { gitTreeOfListing } from '../tree.js'
-import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
+import { api, bindMethods, call, callWithHeaders, clientHeaders, isGone, repoApi } from './client.js'
 
 const PER_PAGE = 100
 const MAX_PAGES = 100
@@ -22,6 +22,24 @@ async function* pages(method, headers, pageUrl, maxPages = MAX_PAGES) {
   }
 }
 
+// A list GitHub pages by a cursor instead: the `after` of each page's
+// Link header `next` link, the one thing read off the link, so the next
+// page is asked of the list `pageUrl` names, wherever the link points. A
+// next link proves a page more.
+async function* cursorPages(method, headers, pageUrl, maxPages = MAX_PAGES) {
+  const paging = { per_page: PER_PAGE }
+  for (let page = 1; ; page++) {
+    const answer = await callWithHeaders(headers, pageUrl(paging))
+    assert.ok(Array.isArray(answer.body), `${method}: expected an array for page ${page}`)
+    yield answer.body
+    const next = /<([^>]*)>\s*;\s*rel="next"/u.exec(answer.headers.get('link') ?? '')?.[1]
+    if (next === undefined) return
+    paging.after = URL.parse(next)?.searchParams.get('after')
+    assert.ok(paging.after, `${method}: page ${page} links the next with no cursor`)
+    assert.ok(page < maxPages, `${method}: more than ${maxPages} pages`)
+  }
+}
+
 const paginate = async (...args) => (await Array.fromAsync(pages(...args))).flat()
 const getCurrentUser = (headers) => call(headers, api(['user']))
 
@@ -48,6 +66,32 @@ export async function getRepoHead(headers, options) {
   return { branch: ref, oid: data.object.sha }
 }
 
+async function getRepoTag(headers, options) {
+  assertArgs('getRepoTag', options, { repo: assertRepo, tag: assertTagName })
+  const { repo, tag } = options
+  const ref = await call(headers, repoApi(repo, ['git', 'ref', 'tags', encodeSegment(tag)]))
+  assert.ok(ref?.ref === `refs/tags/${tag}`, `getRepoTag: GitHub answered for ${show(ref?.ref)}, not ${show(`refs/tags/${tag}`)}`)
+  let { object } = ref
+  for (let hops = 0; object?.type === 'tag' && isSha(object.sha) && hops < 8; hops++) {
+    const annotated = await call(headers, repoApi(repo, ['git', 'tags', object.sha]))
+    assert.ok(annotated?.sha === object.sha, `getRepoTag: GitHub answered for another tag object than ${object.sha}`)
+    object = annotated.object
+  }
+  assert.ok(object?.type === 'commit' && isSha(object.sha), `getRepoTag: ${repo} has no commit for tag ${show(tag)}`)
+  return { tag, oid: object.sha }
+}
+
+// GitHub lists each tag with the commit it names, an annotated one's too.
+async function listRepoTags(headers, options) {
+  assertArgs('listRepoTags', options, { repo: assertRepo, maxPages: optional(assertNumber) })
+  const { repo, maxPages } = options
+  const tags = await paginate('listRepoTags', headers, (paging) => repoApi(repo, ['tags'], paging), maxPages)
+  return tags.map((entry) => {
+    assert.ok(isTagName(entry?.name) && isSha(entry.commit?.sha), `listRepoTags: GitHub listed ${show(entry?.name)} in ${repo}, which is no tag name with a commit`)
+    return { tag: entry.name, oid: entry.commit.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,
@@ -113,12 +157,13 @@ async function listTree(method, headers, repo, tree) {
 }
 
 async function treeAt(method, headers, options) {
-  assertArgs(method, options, { repo: assertRepo, sha: assertSha, path: optional(assertPath) })
-  const { repo, sha, path } = options
+  assertArgs(method, options, { repo: assertRepo, sha: assertSha, directory: optional(assertPath), path: optional(assertPath) })
+  assert.ok(options.directory === undefined || options.path === undefined, `${method}: directory and path are one option, pass directory alone`)
+  const { repo, sha, directory = options.path } = options
   let tree = await commitTree(method, headers, repo, sha)
-  for (const name of path?.split('/') ?? []) {
+  for (const name of directory?.split('/') ?? []) {
     const entry = (await listTree(method, headers, repo, tree)).find((candidate) => candidate.path === name)
-    assert.ok(entry?.type === 'tree', `${method}: ${repo}@${sha} has no directory at ${show(path)}`)
+    assert.ok(entry?.type === 'tree', `${method}: ${repo}@${sha} has no directory at ${show(directory)}`)
     tree = entry.sha
   }
   return tree
@@ -168,15 +213,12 @@ async function getAdvisory(headers, options) {
   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
+  const { repo } = options
+  const pageUrl = (paging) => repoApi(repo, ['security-advisories'], { state: 'published', ...paging })
+  return (await Array.fromAsync(cursorPages('listRepoAdvisories', headers, pageUrl))).flat()
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/http.js

@@ -101,22 +101,27 @@ export async function readBody(res, limit, { truncate = false } = {}) {
   return new Uint8Array(await new Blob(chunks).arrayBuffer(), 0, Math.min(size, limit))
 }
 
+function parse(bytes, url, as) {
+  if (as === 'bytes') return bytes
+  const text = decode(bytes, url)
+  if (as === 'text') return text
+  try {
+    return JSON.parse(text)
+  } catch (cause) {
+    throw new Error(`Malformed JSON from ${url}: ${printable(text.slice(0, 200))}`, { cause })
+  }
+}
+
 // Read as the caller says, not by content type, which proxies drop or
-// rewrite.
-export async function request(url, options) {
+// rewrite; answered with the response's headers.
+export async function requestWithHeaders(url, options) {
   const res = await send(url, options)
   if (!res.ok) {
     // A stream decode holds back a character cut at the limit rather than refusing it.
     const text = await readBody(res, 4096, { truncate: true }).then((bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes, { stream: true })).catch(() => '')
     throw new HttpError(res.status, `${options.method ?? 'GET'} ${url} ${res.status}: ${printable(text)}`)
   }
-  const bytes = await readBody(res, LIMITS[options.as].bytes)
-  if (options.as === 'bytes') return bytes
-  const text = decode(bytes, url)
-  if (options.as === 'text') return text
-  try {
-    return JSON.parse(text)
-  } catch (cause) {
-    throw new Error(`Malformed JSON from ${url}: ${printable(text.slice(0, 200))}`, { cause })
-  }
+  return { body: parse(await readBody(res, LIMITS[options.as].bytes), url, options.as), headers: res.headers }
 }
+
+export const request = async (url, options) => (await requestWithHeaders(url, options)).body

package/src/soldeer.js

@@ -1,16 +1,10 @@
 import assert from 'node:assert/strict'
 
-import { assertSha256, assertion, matches, show } from './args.js'
+import { assertSha256, assertSoldeerName, assertSoldeerVersion, show } from './args.js'
 import { verifiedDownload } from './download.js'
 import { SOLDEER_API, SOLDEER_REVISIONS, buildUrl, request } from './http.js'
 
 const DIR = 'soldeer/zips' // No expiry: the registry refuses a version it already has.
-// Soldeer's own rule for a name: 3 to 100 of lowercase letters, digits and
-// `-`, starting with one of them or `@`, ending with a letter or digit.
-const assertName = assertion('a Soldeer package name', matches(/^(?=.{3,100}$)[@\da-z][\da-z-]*[\da-z]$/u))
-// 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.
-const assertVersion = assertion('letters, digits, `.`, `_`, `+` and `-`', matches(/^(?=.{1,128}$)[\dA-Za-z][\w.+-]*$/u))
 
 // Where the registry keeps the version's zip; it says nothing of what the
 // zip hashes to.
@@ -26,8 +20,8 @@ async function zipUrl(name, version) {
 // The registry has no hash to check a zip against, so the caller brings
 // one, as soldeer.lock records it.
 export async function getZip(name, version, checksum) {
-  assertName('getZip', 'name', name)
-  assertVersion('getZip', 'version', version)
+  assertSoldeerName('getZip', 'name', name)
+  assertSoldeerVersion('getZip', 'version', version)
   assertSha256('getZip', 'checksum', checksum)
   return await verifiedDownload({ method: 'getZip', dir: DIR, what: `${name}@${version}`, ext: 'zip', algorithm: 'sha256', expected: checksum, locate: () => zipUrl(name, version) })
 }