npq 3.20.0 → 3.21.0

package/README.md

@@ -78,6 +78,16 @@ brew install npq
 npq install express
 ```
 
+### Custom registries
+
+NPQ reads standard npm registry configuration, including default and scoped registries, authentication, proxies, and TLS settings. You can also select a registry on the command line; the option is shared with the package manager used for installation:
+
+```sh
+npq install @company/tool --registry=https://artifactory.example.com/artifactory/api/npm/npm-virtual/
+```
+
+See [Custom registries](docs/feature/custom-registry.md) for `.npmrc` examples, configuration precedence, private CA setup, skipped capability behavior, and NPQ's no-fallback privacy guarantee.
+
 ### Embed in your day to day
 
 Since `npq` is a pre-step to ensure that the npm package you're installing is safe, you can safely embed it in your day-to-day `npm` usage so there's no need to remember to run `npq` explicitly.
@@ -130,15 +140,15 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | --- | --- | ---
 | age | Will show a warning for a package if its age on npm is less than 22 days | Checks a package creation date, not a specific version
 | author | Validates the resolved version’s publisher (`_npmUser`), flags a **new** maintainer on the package (first publish by that email within 21 days), **dormant maintainer** gaps (warning if over ~6 months since their last publish on that package, error if over ~9 months), and very **recent** publishes | See [docs/feature/author-marshall.md](docs/feature/author-marshall.md)
-| downloads | Will show a warning for a package if its download count in the last month is less than 20
+| downloads | Will show a warning for a package if its download count in the last month is less than 20 | Reports `not evaluated` for custom-registry packages instead of querying the public npm downloads service
 | readme | Will show a warning if a package has no README or it has been detected as a security placeholder package by npm staff
 | repo | Will show a warning if a package has been found without a valid and working repository URL | Checks the latest version for a repository URL
 | scripts | Will show a warning if a package has a pre/post install script which could potentially be malicious
 | snyk | Will show a warning if a package has been found with vulnerabilities in Snyk's database | For Snyk to work you need to either have the `snyk` npm package installed with a valid API token, or make the token available in the `SNYK_TOKEN` environment variable, and npq will use it
 | license | Will show a warning if a package has been found without a license field | Checks the latest version for a license
 | expired domains | Will show a warning if a package has been found with one of its maintainers having an email address that includes an expired domain | Checks a dependency version for a maintainer with an expired domain
-| signatures | Will compare the package's signature as it shows on the registry's pakument with the keys published on the npmjs.com registry
-| provenance | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not)
+| signatures | Will compare the package's signature as it shows on the registry's packument with signing keys published by the selected registry | Reports `not evaluated` if the selected registry does not expose signing keys
+| provenance | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not) | Reports `not evaluated` if the selected registry does not expose signing keys or attestations
 | version-maturity | Will show a warning if the specific version being installed was published less than 7 days ago | Helps identify recently published versions that may not have been reviewed by the community yet
 | newBin | Will show a warning if the package version being installed introduces a new command-line binary (via the `bin` field in `package.json`) that was not present in its previous version. | Helps identify potentially unexpected new executables being added to your `node_modules/.bin/` directory.
 | typosquatting | Will show a warning if the package name is similar to a popular package name, which could indicate a potential typosquatting attack. | Helps identify packages that may be trying to trick users into installing them by mimicking popular package names.

package/bin/npq-hero.js

@@ -12,6 +12,8 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
+const RegistryConfig = require('../lib/helpers/registryConfig')
+const RegistryClient = require('../lib/helpers/registryClient')
 
 const PACKAGE_MANAGER_TOOL = process.env.NPQ_PKG_MGR
 const DISABLE_AUTO_CONTINUE = process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true'
@@ -27,14 +29,17 @@ if (spinner) {
   spinner.start()
 }
 
-const marshall = new Marshall({
-  pkgs: cliArgs.packages,
-  progressManager: spinner,
-  promiseThrottleHelper
-})
-
-marshall
-  .process()
+RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
+  .then((registryConfig) => {
+    const registryClient = new RegistryClient(registryConfig)
+    const marshall = new Marshall({
+      pkgs: cliArgs.packages,
+      registryClient,
+      progressManager: spinner,
+      promiseThrottleHelper
+    })
+    return marshall.process()
+  })
   .then((marshallResults) => {
     if (spinner) {
       spinner.stop()
@@ -46,12 +51,20 @@ marshall
       Object.hasOwn(results, 'countErrors') &&
       Object.hasOwn(results, 'countWarnings')
     ) {
-      const { countErrors, countWarnings, useRichFormatting } = results
-      const isErrors = countErrors > 0 || countWarnings > 0
+      const {
+        countErrors,
+        countWarnings,
+        countNotEvaluated = 0,
+        useRichFormatting
+      } = results
+      const hasFindings = countErrors > 0 || countWarnings > 0
+      const hasReportableResults = hasFindings || countNotEvaluated > 0
 
-      if (isErrors) {
+      if (hasReportableResults) {
         console.log()
-        console.log('Packages with issues found:')
+        console.log(
+          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
+        )
 
         if (useRichFormatting) {
           console.log(results.resultsForPrettyPrint)
@@ -63,9 +76,10 @@ marshall
       }
 
       return {
-        anyIssues: isErrors,
+        anyIssues: hasFindings,
         countErrors,
-        countWarnings
+        countWarnings,
+        countNotEvaluated
       }
     }
     return undefined

package/bin/npq.js

@@ -15,6 +15,8 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
+const RegistryConfig = require('../lib/helpers/registryConfig')
+const RegistryClient = require('../lib/helpers/registryClient')
 
 const debug = util.debuglog('npq')
 
@@ -27,7 +29,12 @@ if (spinner) {
   spinner.start()
 }
 
-Promise.resolve()
+let registryClient
+
+RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
+  .then((registryConfig) => {
+    registryClient = new RegistryClient(registryConfig)
+  })
   .then(() => {
     if (cliArgs.packages.length === 0) {
       debug('\nNo packages specified, using project packages from package.json')
@@ -48,6 +55,7 @@ Promise.resolve()
 
     const marshall = new Marshall({
       pkgs: packages,
+      registryClient,
       progressManager: spinner,
       promiseThrottleHelper
     })
@@ -65,12 +73,20 @@ Promise.resolve()
       Object.hasOwn(results, 'countErrors') &&
       Object.hasOwn(results, 'countWarnings')
     ) {
-      const { countErrors, countWarnings, useRichFormatting } = results
-      const isErrors = countErrors > 0 || countWarnings > 0
-
-      if (isErrors) {
+      const {
+        countErrors,
+        countWarnings,
+        countNotEvaluated = 0,
+        useRichFormatting
+      } = results
+      const hasFindings = countErrors > 0 || countWarnings > 0
+      const hasReportableResults = hasFindings || countNotEvaluated > 0
+
+      if (hasReportableResults) {
         console.log()
-        console.log('Packages with issues found:')
+        console.log(
+          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
+        )
 
         if (useRichFormatting) {
           console.log(results.resultsForPrettyPrint)
@@ -82,9 +98,10 @@ Promise.resolve()
       }
 
       return {
-        anyIssues: isErrors,
+        anyIssues: hasFindings,
         countErrors,
-        countWarnings
+        countWarnings,
+        countNotEvaluated
       }
     }
     return undefined

package/lib/cli.js

@@ -20,6 +20,12 @@ const INSTALL_SUBCOMMANDS = new Set([
 ])
 
 class CliParser {
+  static registryConfigArgs(values = {}) {
+    return ['registry', 'userconfig', 'globalconfig'].flatMap((key) =>
+      values[key] ? [`--${key}=${values[key]}`] : []
+    )
+  }
+
   static isInstallSubcommand(token) {
     return INSTALL_SUBCOMMANDS.has(token)
   }
@@ -67,6 +73,9 @@ class CliParser {
       packageManager: { type: 'string' },
       pkgMgr: { type: 'string' },
       'disable-auto-continue': { type: 'boolean' },
+      registry: { type: 'string' },
+      userconfig: { type: 'string' },
+      globalconfig: { type: 'string' },
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean', short: 'v' }
     }
@@ -95,6 +104,9 @@ Options:
       --packageManager        Package Manager to use (default: npm)
       --pkgMgr                Alias for packageManager
       --disable-auto-continue Disable auto-continue countdown, always prompt
+      --registry              npm registry used for audit and install
+      --userconfig            Path to the user npm configuration file
+      --globalconfig          Path to the global npm configuration file
   -h, --help                  Show help
   -v, --version               Show version
 
@@ -127,6 +139,7 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
       plain: values.plain || false,
       disableAutoContinue:
         values['disable-auto-continue'] || process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true',
+      registryConfigArgs: this.registryConfigArgs(values),
       installSubcommandExplicit
     }
   }
@@ -140,17 +153,21 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
           type: 'string',
           short: 'i',
           default: 'install'
-        }
+        },
+        registry: { type: 'string' },
+        userconfig: { type: 'string' },
+        globalconfig: { type: 'string' }
       }
     }
 
-    const { positionals } = parseArgs(config)
+    const { values, positionals } = parseArgs(config)
 
     const earlyExitNoInstall = true
     const normalizedPackages = this._extractPackagesFromPositionals(positionals, earlyExitNoInstall)
 
     return {
-      packages: normalizedPackages
+      packages: normalizedPackages,
+      registryConfigArgs: this.registryConfigArgs(values)
     }
   }
 }

package/lib/helpers/notEvaluated.js

@@ -0,0 +1,11 @@
+'use strict'
+
+class NotEvaluated extends Error {
+  constructor(message, { capability = null } = {}) {
+    super(message)
+    this.name = 'NotEvaluated'
+    this.capability = capability
+  }
+}
+
+module.exports = NotEvaluated

package/lib/helpers/npmRegistry.js

@@ -13,57 +13,6 @@ const MISSING_TIME_CUTOFF = '2015-01-01T00:00:00.000Z'
  * This replaces pacote functionality for npq specific needs
  */
 class NpmRegistry {
-  constructor(opts = {}) {
-    this.opts = opts
-    this.registry = opts.registry || 'https://registry.npmjs.org'
-  }
-
-  /**
-   * Fetch package manifest from npm registry
-   * @param {string} packageSpec - Package name and version (e.g., 'express@4.18.2')
-   * @param {Object} options - Additional options
-   * @returns {Promise<Object>} Package manifest
-   */
-  async getManifest(packageSpec, options = {}) {
-    const spec = npa(packageSpec)
-    const escapedName = spec.escapedName
-    const packumentUrl = `${this.registry}/${escapedName}`
-
-    // Fetch packument (package metadata)
-    const response = await fetch(packumentUrl, {
-      headers: {
-        accept: 'application/json',
-        'user-agent': 'npq-npm-registry-client',
-        ...(options.headers || {})
-      }
-    })
-
-    if (!response.ok) {
-      throw new Error(`Failed to fetch package manifest: ${response.status} ${response.statusText}`)
-    }
-
-    const packument = await response.json()
-
-    // Pick the specific version
-    let version = spec.fetchSpec
-    if (version === 'latest' || !version || version === '*') {
-      version = packument['dist-tags']?.latest
-    }
-
-    if (!packument.versions || !packument.versions[version]) {
-      throw new Error(`Version ${version} not found for package ${spec.name}`)
-    }
-
-    const manifest = packument.versions[version]
-
-    // Add timing information if available
-    if (packument.time && packument.time[version]) {
-      manifest._time = packument.time[version]
-    }
-
-    return manifest
-  }
-
   /**
    * Verify package signatures using npm registry public keys
    * @param {Object} manifest - Package manifest
@@ -140,27 +89,15 @@ class NpmRegistry {
    * @param {Array} registryKeys - Public keys from npm registry
    * @returns {Promise<Object>} Verified manifest with _attestations
    */
-  async verifyAttestations(manifest, registryKeys) {
+  async verifyAttestations(manifest, registryKeys, attestations) {
     if (!manifest.dist || !manifest.dist.attestations) {
       throw new Error('Package has no attestations to verify')
     }
 
-    const attestationsPath = new URL(manifest.dist.attestations.url).pathname
-    const attestationsUrl = this.registry + attestationsPath
-
-    const response = await fetch(attestationsUrl, {
-      headers: {
-        accept: 'application/json',
-        'user-agent': 'npq-npm-registry-client'
-      }
-    })
-
-    if (!response.ok) {
-      throw new Error(`Failed to fetch attestations: ${response.status} ${response.statusText}`)
+    if (!Array.isArray(attestations)) {
+      throw new Error('Package attestations response is invalid')
     }
 
-    const { attestations } = await response.json()
-
     const bundles = attestations.map(({ predicateType, bundle }) => {
       const statement = JSON.parse(
         Buffer.from(bundle.dsseEnvelope.payload, 'base64').toString('utf8')

package/lib/helpers/packageRepoUtils.js

@@ -1,31 +1,23 @@
 'use strict'
 
 const semver = require('semver')
-const NPM_REGISTRY = 'http://registry.npmjs.org'
-const NPM_REGISTRY_API = 'https://api.npmjs.org'
+const RegistryClient = require('./registryClient')
 
 class PackageRepoUtils {
-  constructor(options = {}) {
-    this.registryUrl = options.registryUrl ? options.registryUrl : NPM_REGISTRY
-    this.registryApiUrl = options.registryApiUrl ? options.registryApiUrl : NPM_REGISTRY_API
+  constructor({ registryClient = RegistryClient.public() } = {}) {
+    this.registryClient = registryClient
     this.pkgInfoCache = {}
   }
 
-  formatPackageForUrl(pkg) {
-    return pkg.replace(/\//g, '%2F')
-  }
-
   getPackageInfo(pkg) {
-    if (this.pkgInfoCache[pkg]) {
-      return Promise.resolve(this.pkgInfoCache[pkg])
-    } else {
-      return fetch(`${this.registryUrl}/${this.formatPackageForUrl(pkg)}`)
-        .then((response) => response.json())
-        .then((data) => {
-          this.pkgInfoCache[pkg] = data
-          return data
-        })
+    const cacheKey = `${this.registryClient.registryFor(pkg)}|${pkg}`
+    if (this.pkgInfoCache[cacheKey]) {
+      return Promise.resolve(this.pkgInfoCache[cacheKey])
     }
+    return this.registryClient.getPackageInfo(pkg).then((data) => {
+      this.pkgInfoCache[cacheKey] = data
+      return data
+    })
   }
 
   getLatestVersion(pkg) {
@@ -35,9 +27,7 @@ class PackageRepoUtils {
   }
 
   getDownloadInfo(pkg) {
-    return fetch(`${this.registryApiUrl}/downloads/point/last-month/${pkg}`)
-      .then((response) => response.json())
-      .then(({ downloads }) => downloads)
+    return this.registryClient.getDownloadInfo(pkg)
   }
 
   getReadmeInfo(pkg) {

package/lib/helpers/registryClient.js

@@ -0,0 +1,206 @@
+'use strict'
+
+const npa = require('npm-package-arg')
+const npmFetch = require('npm-registry-fetch')
+const NotEvaluated = require('./notEvaluated')
+const RegistryConfig = require('./registryConfig')
+const { RegistryError } = require('./registryErrors')
+
+const PUBLIC_REGISTRY = 'https://registry.npmjs.org/'
+const OPTIONAL_STATUS = new Set([404, 405, 501])
+const CAPABILITY = Object.freeze({
+  SIGNING_KEYS: 'signing-keys',
+  ATTESTATIONS: 'attestations',
+  DOWNLOAD_COUNTS: 'download-counts'
+})
+const CAPABILITY_MESSAGE = Object.freeze({
+  [CAPABILITY.SIGNING_KEYS]: 'configured registry does not expose signing keys',
+  [CAPABILITY.ATTESTATIONS]: 'configured registry does not expose attestations',
+  [CAPABILITY.DOWNLOAD_COUNTS]:
+    'download counts are available only for the public npm registry'
+})
+
+class RegistryClient {
+  constructor(registryConfig, { fetcher = npmFetch } = {}) {
+    this.registryConfig = registryConfig
+    this.fetcher = fetcher
+    this.keyCache = new Map()
+    this.capabilityCache = new Map()
+  }
+
+  static public() {
+    return new RegistryClient(RegistryConfig.defaults())
+  }
+
+  registryFor(packageSpec) {
+    return this.registryConfig.registryFor(packageSpec)
+  }
+
+  requestOptions(packageSpec) {
+    return {
+      ...this.registryConfig.requestOptions,
+      spec: packageSpec,
+      headers: {
+        accept: 'application/json',
+        'user-agent': 'npq-npm-registry-client'
+      }
+    }
+  }
+
+  async requestJson(
+    requestPath,
+    packageSpec,
+    { capability = null, notFoundAsData = false } = {}
+  ) {
+    const registry = this.registryFor(packageSpec)
+    try {
+      return await this.fetcher.json(requestPath, this.requestOptions(packageSpec))
+    } catch (error) {
+      const statusCode = error.statusCode || error.status || null
+      if (notFoundAsData && statusCode === 404) {
+        return { error: 'Not found' }
+      }
+      if (capability && OPTIONAL_STATUS.has(statusCode)) {
+        this.capabilityCache.set(`${registry}|${capability}`, false)
+        throw new NotEvaluated(CAPABILITY_MESSAGE[capability], { capability })
+      }
+      const code =
+        statusCode === 401 || statusCode === 403
+          ? 'EREGISTRYAUTH'
+          : statusCode
+            ? 'EREGISTRYHTTP'
+            : 'EREGISTRYNETWORK'
+      throw new RegistryError(
+        statusCode === 401 || statusCode === 403
+          ? 'Registry authentication or authorization failed'
+          : statusCode
+            ? `Registry request failed with HTTP ${statusCode}`
+            : 'Registry network request failed',
+        { registry, code, statusCode, cause: error }
+      )
+    }
+  }
+
+  async getPackageInfo(packageName) {
+    const spec = npa(packageName)
+    const data = await this.requestJson(spec.escapedName, packageName, {
+      notFoundAsData: true
+    })
+    if (data && data.error === 'Not found') {
+      return data
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new RegistryError('Registry package metadata is malformed', {
+        registry: this.registryFor(packageName),
+        code: 'EREGISTRYPROTOCOL'
+      })
+    }
+    return data
+  }
+
+  async getManifest(packageSpec, packument = null) {
+    const spec = npa(packageSpec)
+    const data = packument || (await this.getPackageInfo(spec.name))
+    let version = spec.fetchSpec
+    if (!version || version === '*' || version === 'latest') {
+      version = data['dist-tags'] && data['dist-tags'].latest
+    }
+    if (!data.versions || !data.versions[version]) {
+      throw new Error(`Version ${version} not found for package ${spec.name}`)
+    }
+    return {
+      ...data.versions[version],
+      ...(data.time && data.time[version] ? { _time: data.time[version] } : {})
+    }
+  }
+
+  unavailable(capability) {
+    throw new NotEvaluated(CAPABILITY_MESSAGE[capability], { capability })
+  }
+
+  async getRegistryKeys(packageSpec) {
+    const registry = this.registryFor(packageSpec)
+    const cacheKey = `${registry}|${CAPABILITY.SIGNING_KEYS}`
+    if (this.keyCache.has(cacheKey)) {
+      return this.keyCache.get(cacheKey)
+    }
+    if (this.capabilityCache.get(cacheKey) === false) {
+      return this.unavailable(CAPABILITY.SIGNING_KEYS)
+    }
+    const response = await this.requestJson('-/npm/v1/keys', packageSpec, {
+      capability: CAPABILITY.SIGNING_KEYS
+    })
+    if (!response || !Array.isArray(response.keys)) {
+      throw new RegistryError('Registry signing-key response is malformed', {
+        registry,
+        code: 'EREGISTRYPROTOCOL'
+      })
+    }
+    if (response.keys.length === 0) {
+      this.capabilityCache.set(cacheKey, false)
+      return this.unavailable(CAPABILITY.SIGNING_KEYS)
+    }
+    const keys = response.keys.map((key) => ({
+      ...key,
+      pemkey: `-----BEGIN PUBLIC KEY-----\n${key.key}\n-----END PUBLIC KEY-----`
+    }))
+    this.keyCache.set(cacheKey, keys)
+    return keys
+  }
+
+  async getAttestations(packageSpec, manifest) {
+    const registry = this.registryFor(packageSpec)
+    const cacheKey = `${registry}|${CAPABILITY.ATTESTATIONS}`
+    if (this.capabilityCache.get(cacheKey) === false) {
+      return this.unavailable(CAPABILITY.ATTESTATIONS)
+    }
+    let requestPath
+    try {
+      const advertisedPath = new URL(manifest.dist.attestations.url).pathname
+      const registryPath = new URL(registry).pathname
+      requestPath = advertisedPath.startsWith(registryPath)
+        ? advertisedPath.slice(registryPath.length)
+        : advertisedPath.replace(/^\/+/, '')
+    } catch (error) {
+      throw new RegistryError('Package attestation URL is malformed', {
+        registry,
+        code: 'EREGISTRYPROTOCOL',
+        cause: error
+      })
+    }
+    const response = await this.requestJson(requestPath, packageSpec, {
+      capability: CAPABILITY.ATTESTATIONS
+    })
+    if (!response || !Array.isArray(response.attestations)) {
+      throw new RegistryError('Registry attestation response is malformed', {
+        registry,
+        code: 'EREGISTRYPROTOCOL'
+      })
+    }
+    if (response.attestations.length === 0) {
+      this.capabilityCache.set(cacheKey, false)
+      return this.unavailable(CAPABILITY.ATTESTATIONS)
+    }
+    return response.attestations
+  }
+
+  async getDownloadInfo(packageName) {
+    if (this.registryFor(packageName) !== PUBLIC_REGISTRY) {
+      return this.unavailable(CAPABILITY.DOWNLOAD_COUNTS)
+    }
+    const escapedName = npa(packageName).escapedName
+    const response = await this.requestJson(
+      `https://api.npmjs.org/downloads/point/last-month/${escapedName}`,
+      packageName
+    )
+    if (!response || typeof response.downloads !== 'number') {
+      throw new RegistryError('Registry download response is malformed', {
+        registry: PUBLIC_REGISTRY,
+        code: 'EREGISTRYPROTOCOL'
+      })
+    }
+    return response.downloads
+  }
+}
+
+module.exports = RegistryClient

package/lib/helpers/registryConfig.js

@@ -0,0 +1,79 @@
+'use strict'
+
+const path = require('node:path')
+const Config = require('@npmcli/config')
+const npmFetch = require('npm-registry-fetch')
+const {
+  definitions,
+  flatten,
+  nerfDarts,
+  shorthands
+} = require('@npmcli/config/lib/definitions')
+const { RegistryError, sanitizeRegistryUrl } = require('./registryErrors')
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org/'
+
+function normalizeRegistry(value) {
+  const url = new URL(value || DEFAULT_REGISTRY)
+  if (!url.pathname.endsWith('/')) {
+    url.pathname += '/'
+  }
+  return url.toString()
+}
+
+class RegistryConfig {
+  constructor(requestOptions) {
+    this.requestOptions = Object.freeze({
+      ...requestOptions,
+      registry: normalizeRegistry(requestOptions.registry)
+    })
+  }
+
+  static defaults() {
+    return new RegistryConfig({ registry: DEFAULT_REGISTRY })
+  }
+
+  static async load({ argv = [], env = process.env, cwd = process.cwd() } = {}) {
+    try {
+      const registryArg = argv.find((arg) => arg.startsWith('--registry='))
+      if (registryArg) {
+        normalizeRegistry(registryArg.slice('--registry='.length))
+      }
+
+      const config = new Config({
+        npmPath: path.resolve(__dirname, '..'),
+        definitions,
+        shorthands,
+        flatten,
+        nerfDarts,
+        argv: ['node', 'npq', ...argv],
+        env,
+        cwd,
+        warn: false
+      })
+      await config.load()
+      if (!config.validate()) {
+        throw new Error('Invalid npm configuration')
+      }
+      return new RegistryConfig(config.flat)
+    } catch (error) {
+      const code =
+        error.code === 'ERR_INVALID_AUTH' ? 'EREGISTRYCONFIGAUTH' : 'EREGISTRYCONFIG'
+      const message =
+        error.code === 'ERR_INVALID_AUTH'
+          ? 'Invalid npm registry authentication configuration'
+          : `Unable to load npm registry configuration: ${error.code || error.name}`
+      throw new RegistryError(message, { code, cause: error })
+    }
+  }
+
+  registryFor(packageSpec) {
+    return normalizeRegistry(npmFetch.pickRegistry(packageSpec, this.requestOptions))
+  }
+
+  describeRegistry(packageSpec) {
+    return sanitizeRegistryUrl(this.registryFor(packageSpec))
+  }
+}
+
+module.exports = RegistryConfig

package/lib/helpers/registryErrors.js

@@ -0,0 +1,32 @@
+'use strict'
+
+function sanitizeRegistryUrl(value) {
+  try {
+    const url = new URL(value)
+    url.username = ''
+    url.password = ''
+    url.search = ''
+    url.hash = ''
+    return url.toString()
+  } catch {
+    return 'configured registry'
+  }
+}
+
+class RegistryError extends Error {
+  constructor(
+    message,
+    { registry = null, code = 'EREGISTRY', statusCode = null, cause = null } = {}
+  ) {
+    const sanitizedRegistry = registry ? sanitizeRegistryUrl(registry) : null
+    super(sanitizedRegistry ? `${message} (${sanitizedRegistry})` : message, {
+      cause: cause || undefined
+    })
+    this.name = 'RegistryError'
+    this.code = code
+    this.statusCode = statusCode
+    this.registry = sanitizedRegistry
+  }
+}
+
+module.exports = { RegistryError, sanitizeRegistryUrl }

package/lib/helpers/reportResults.js

@@ -108,6 +108,7 @@ function reportResults(marshallResults, { plain = false } = {}) {
 
   let countErrors = 0
   let countWarnings = 0
+  let countNotEvaluated = 0
   let countPackages = results.length
 
   results.forEach((result, index) => {
@@ -219,11 +220,33 @@ function reportResults(marshallResults, { plain = false } = {}) {
       })
     }
 
+    if (result.notEvaluated && result.notEvaluated.length > 0) {
+      result.notEvaluated.forEach((entryArray) => {
+        countNotEvaluated += entryArray.length
+        entryArray.forEach((entry) => {
+          const topicRich = styleText(
+            ['cyan'],
+            entry.categoryFriendlyName.padEnd(maxTextLength, ' ')
+          )
+          const iconRich = styleText(['cyan'], '○')
+          const wrappedMessage = wrapTextWithIndent(
+            entry.message,
+            maxMessageWidth,
+            indentString
+          )
+          resultsForPrettyPrint +=
+            `\n ${prefixRich} ${iconRich} ${topicRich} ${separatorRich} ${wrappedMessage} `
+          resultsForPlainTextPrint +=
+            `\n  NOT EVALUATED: ${entry.categoryFriendlyName} - ${entry.message}`
+        })
+      })
+    }
+
     // Close rich formatting box
     resultsForPrettyPrint += `\n ${styleText(['dim'], '└─')}`
   })
 
-  const maxTextLength = 'Total packages:'.length
+  const maxTextLength = 'Total not evaluated:'.length
 
   // Rich formatting summary
   summaryForPrettyPrint += `\n\n${styleText(['bold'], 'Summary:')}\n`
@@ -239,6 +262,10 @@ function reportResults(marshallResults, { plain = false } = {}) {
     ['yellow', 'bold'],
     String(countWarnings)
   )}`
+  summaryForPrettyPrint += `\n - ${'Total not evaluated:'.padEnd(maxTextLength, ' ')} ${styleText(
+    ['cyan'],
+    String(countNotEvaluated)
+  )}`
   summaryForPrettyPrint += `\n`
 
   // Plain text summary
@@ -246,11 +273,13 @@ function reportResults(marshallResults, { plain = false } = {}) {
   summaryForPlainTextPrint += `\n - Total packages: ${countPackages}`
   summaryForPlainTextPrint += `\n - Total errors: ${countErrors}`
   summaryForPlainTextPrint += `\n - Total warnings: ${countWarnings}`
+  summaryForPlainTextPrint += `\n - Total not evaluated: ${countNotEvaluated}`
   summaryForPlainTextPrint += `\n`
 
   return {
     countErrors,
     countWarnings,
+    countNotEvaluated,
     resultsForPrettyPrint,
     resultsForJSON,
     resultsForPlainTextPrint,
@@ -267,7 +296,8 @@ function marshallResultsToIssuesPerPackage(results) {
     const issues = {
       pkg,
       errors: [],
-      warnings: []
+      warnings: [],
+      notEvaluated: []
     }
     for (const marshall of allMarshallResultsList) {
       for (const value of Object.values(marshall)) {
@@ -294,9 +324,22 @@ function marshallResultsToIssuesPerPackage(results) {
 
           issues.warnings.push(marshallWarnings)
         }
+        if (value.notEvaluated && value.notEvaluated.length > 0) {
+          const skippedChecks = value.notEvaluated.map((entry) => ({
+            marshall: value.marshall,
+            categoryId: value.categoryId,
+            categoryFriendlyName: marshallCategories[value.categoryId].title,
+            ...entry
+          }))
+          issues.notEvaluated.push(skippedChecks)
+        }
       }
     }
-    if (issues.errors.length > 0 || issues.warnings.length > 0) {
+    if (
+      issues.errors.length > 0 ||
+      issues.warnings.length > 0 ||
+      issues.notEvaluated.length > 0
+    ) {
       issuesPerPackage.push(issues)
     }
   }

package/lib/marshall.js

@@ -3,12 +3,20 @@
 // const util = require('node:util')
 const Marshalls = require('./marshalls')
 const PackageRepoUtils = require('./helpers/packageRepoUtils')
+const RegistryClient = require('./helpers/registryClient')
 // const { marshallCategories } = require('./marshalls/constants')
 
 class Marshall {
   constructor(options = {}) {
-    this.pkgs = options ? options.pkgs : null
-    this.packageRepoUtils = new PackageRepoUtils()
+    options = options || {}
+    this.pkgs = options.pkgs || null
+    this.registryClient =
+      options.registryClient ||
+      options.packageRepoUtils?.registryClient ||
+      RegistryClient.public()
+    this.packageRepoUtils =
+      options.packageRepoUtils ||
+      new PackageRepoUtils({ registryClient: this.registryClient })
     this.progressManager = options.progressManager || null
     this.promiseThrottleHelper = options.promiseThrottleHelper || null
   }
@@ -56,7 +64,8 @@ class Marshall {
     const allPackages = Array.isArray(pkg) ? pkg : [pkg]
     const config = {
       pkgs: this.createPackageVersionMaps(allPackages),
-      packageRepoUtils: packageRepoUtils
+      packageRepoUtils: packageRepoUtils,
+      registryClient: this.registryClient
     }
     return Marshalls.tasks(config, this.progressManager)
   }

package/lib/marshalls/baseMarshall.js

@@ -2,6 +2,8 @@
 
 const semver = require('semver')
 const util = require('node:util')
+const NotEvaluated = require('../helpers/notEvaluated')
+const { RegistryError } = require('../helpers/registryErrors')
 const Warning = require('../helpers/warning')
 const { marshallCategories } = require('./constants')
 
@@ -9,6 +11,7 @@ class BaseMarshall {
   constructor(options) {
     this.debug = util.debuglog('npq')
     this.packageRepoUtils = options.packageRepoUtils
+    this.registryClient = options.registryClient
     this.categoryId = marshallCategories.PackageHealth.id
   }
 
@@ -19,6 +22,7 @@ class BaseMarshall {
       status: null,
       errors: [],
       warnings: [],
+      notEvaluated: [],
       data: {},
       marshall: this.name,
       categoryId: this.categoryId
@@ -42,13 +46,22 @@ class BaseMarshall {
         return data
       })
       .catch((err) => {
-        this.setMessage(
-          {
-            pkg: pkg.packageString,
-            message: err.message
-          },
-          Boolean(err instanceof Warning)
-        )
+        if (err instanceof RegistryError) {
+          throw err
+        }
+
+        const message = {
+          pkg: pkg.packageString,
+          message: err.message
+        }
+
+        if (err instanceof NotEvaluated) {
+          this.setNotEvaluated(message)
+          return undefined
+        }
+
+        this.setMessage(message, Boolean(err instanceof Warning))
+        return undefined
       })
   }
 
@@ -69,6 +82,13 @@ class BaseMarshall {
     })
   }
 
+  setNotEvaluated(msg) {
+    this.ctx.marshalls[this.name].notEvaluated.push({
+      pkg: msg.pkg,
+      message: msg.message
+    })
+  }
+
   /**
    * Resolves a package version string to an actual semver version
    * Handles dist-tags (latest, beta, etc.) and direct semver versions

package/lib/marshalls/index.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { RegistryError } = require('../helpers/registryErrors')
 
 class Marshalls {
   static async collectMarshalls() {
@@ -20,7 +21,8 @@ class Marshalls {
     }
 
     const config = {
-      packageRepoUtils: options.packageRepoUtils
+      packageRepoUtils: options.packageRepoUtils,
+      registryClient: options.registryClient
     }
 
     const marshallTasks = marshalls.reduce((prev, curr) => {
@@ -96,6 +98,7 @@ class Marshalls {
               status: null,
               errors: [{ pkg: options.pkgs[index].packageName, message: 'Package not found' }],
               warnings: [],
+              notEvaluated: [],
               data: {},
               categoryId: 'PackageHealth'
             }
@@ -119,7 +122,8 @@ class Marshalls {
     const packagesToProcess = options.pkgs
     if (packagesToProcess.length > 0) {
       const marshallTasks = await Marshalls.buildMarshallTasks(marshalls, {
-        packageRepoUtils: options.packageRepoUtils
+        packageRepoUtils: options.packageRepoUtils,
+        registryClient: options.registryClient
       })
 
       for (const marshall of marshallTasks) {
@@ -130,6 +134,9 @@ class Marshalls {
           })
           marshallResults.push(res.marshalls)
         } catch (error) {
+          if (error instanceof RegistryError) {
+            throw error
+          }
           console.error(`Error running task ${marshall.title}:`, error)
         }
       }

package/lib/marshalls/provenance.marshall.js

@@ -4,6 +4,8 @@ const semver = require('semver')
 const BaseMarshall = require('./baseMarshall')
 const NpmRegistry = require('../helpers/npmRegistry')
 const Warning = require('../helpers/warning')
+const NotEvaluated = require('../helpers/notEvaluated')
+const { RegistryError } = require('../helpers/registryErrors')
 const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'provenance'
@@ -88,115 +90,80 @@ class Marshall extends BaseMarshall {
     }
   }
 
-  validate(pkg) {
+  async validate(pkg) {
     const validationMetadata = {}
-    const npmRegistry = new NpmRegistry({
-      registry: 'https://registry.npmjs.org'
-    })
-
-    return this.packageRepoUtils
-      .getPackageInfo(pkg.packageName)
-      .then(async (packageInfo) => {
-        const packageName = packageInfo.name
-
-        // Use the resolvePackageVersion method to handle version ranges properly
-        const packageVersion = await this.resolvePackageVersion(
-          pkg.packageName,
-          pkg.packageVersion,
-          packageInfo
-        )
+    const verifier = new NpmRegistry()
+
+    try {
+      const packageInfo = await this.packageRepoUtils.getPackageInfo(pkg.packageName)
+      validationMetadata.name = packageInfo.name
+      validationMetadata.version = await this.resolvePackageVersion(
+        pkg.packageName,
+        pkg.packageVersion,
+        packageInfo
+      )
+      validationMetadata.packageInfo = packageInfo
 
-        validationMetadata.name = packageName
-        validationMetadata.version = packageVersion
-        validationMetadata.packageInfo = packageInfo
-
-        if (!validationMetadata.version) {
-          throw new Error('Unable to find version or dist-tag for package')
-        }
-
-        return validationMetadata
-      })
-      .then((validationMetadata) => {
-        return this.fetchRegistryKeys().then((keys) => {
-          return npmRegistry
-            .getManifest(`${validationMetadata.name}@${validationMetadata.version}`)
-            .then((manifest) => npmRegistry.verifyAttestations(manifest, keys))
-        })
-      })
-      .then((metadata) => {
-        if (!metadata || !metadata._attestations) {
-          this.throwIfProvenanceRegression(validationMetadata)
-          throw new Warning('the package was published without any attestations')
-        }
-
-        const attestations = metadata._attestations
-        return attestations
-      })
-      .catch((error) => {
-        // We can ignore this type of error, false positive
-        // See: https://github.com/lirantal/npq/issues/329
-        if (error.code === 'EATTESTATIONVERIFY' && error.message.includes('malformed checkpoint')) {
-          return []
-        }
-
-        if (
-          error instanceof Error &&
-          error.message === 'Unable to find version or dist-tag for package'
-        ) {
-          throw error
-        }
-
-        if (
-          error instanceof Warning &&
-          (error.message.includes('Error fetching registry keys') ||
-            error.message === 'the package was published without any attestations')
-        ) {
-          throw error
-        }
-
-        if (shouldConsiderProvenanceRegression(error)) {
-          this.throwIfProvenanceRegression(validationMetadata)
-        }
-
-        if (error.message.includes('Package has no attestations to verify')) {
-          throw new Warning(
-            `Unable to verify provenance: the package was published without any attestations`
-          )
-        }
-
-        this.debug(
-          '\nUnable to verify provenance for package %s@%s: %s',
-          validationMetadata.name,
-          validationMetadata.version,
-          error.message
+      if (!validationMetadata.version) {
+        throw new Error('Unable to find version or dist-tag for package')
+      }
+
+      const manifest = await this.registryClient.getManifest(
+        `${pkg.packageName}@${validationMetadata.version}`,
+        packageInfo
+      )
+      let metadata
+      if (!manifest.dist || !manifest.dist.attestations) {
+        metadata = await verifier.verifyAttestations(manifest, [], null)
+      } else {
+        const [keys, attestations] = await Promise.all([
+          this.registryClient.getRegistryKeys(pkg.packageName),
+          this.registryClient.getAttestations(pkg.packageName, manifest)
+        ])
+        metadata = await verifier.verifyAttestations(manifest, keys, attestations)
+      }
+
+      if (!metadata || !metadata._attestations) {
+        this.throwIfProvenanceRegression(validationMetadata)
+        throw new Warning('the package was published without any attestations')
+      }
+      return metadata._attestations
+    } catch (error) {
+      if (error instanceof NotEvaluated || error instanceof RegistryError) {
+        throw error
+      }
+      if (error.code === 'EATTESTATIONVERIFY' && error.message.includes('malformed checkpoint')) {
+        return []
+      }
+      if (
+        error instanceof Error &&
+        error.message === 'Unable to find version or dist-tag for package'
+      ) {
+        throw error
+      }
+      if (
+        error instanceof Warning &&
+        error.message === 'the package was published without any attestations'
+      ) {
+        throw error
+      }
+      if (shouldConsiderProvenanceRegression(error)) {
+        this.throwIfProvenanceRegression(validationMetadata)
+      }
+      if (error.message.includes('Package has no attestations to verify')) {
+        throw new Warning(
+          'Unable to verify provenance: the package was published without any attestations'
         )
-        throw new Warning(`Unable to verify provenance`)
-      })
-  }
+      }
 
-  fetchRegistryKeys() {
-    const registryHost = 'https://registry.npmjs.org'
-    const registryKeysEndpoint = '/-/npm/v1/keys'
-
-    const registryKeysUrl = `${registryHost}${registryKeysEndpoint}`
-    return fetch(registryKeysUrl)
-      .then((response) => {
-        return response.json()
-      })
-      .then((response) => {
-        const registryKeys = response.keys
-
-        return registryKeys.map((key) => ({
-          ...key,
-          pemkey: `-----BEGIN PUBLIC KEY-----\n${key.key}\n-----END PUBLIC KEY-----`
-        }))
-      })
-      .then((keys) => {
-        return keys
-      })
-      .catch((error) => {
-        throw new Warning(`Error fetching registry keys: ${error.message}`)
-      })
+      this.debug(
+        '\nUnable to verify provenance for package %s@%s: %s',
+        validationMetadata.name,
+        validationMetadata.version,
+        error.message
+      )
+      throw new Warning('Unable to verify provenance')
+    }
   }
 }
 

package/lib/marshalls/signatures.marshall.js

@@ -3,12 +3,12 @@
 const BaseMarshall = require('./baseMarshall')
 const Warning = require('../helpers/warning')
 const NpmRegistry = require('../helpers/npmRegistry')
+const NotEvaluated = require('../helpers/notEvaluated')
+const { RegistryError } = require('../helpers/registryErrors')
 const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'signatures'
 
-let registryKeysCache = null
-
 class Marshall extends BaseMarshall {
   constructor(options) {
     super(options)
@@ -20,83 +20,44 @@ class Marshall extends BaseMarshall {
     return 'Verifying registry signatures for package'
   }
 
-  validate(pkg) {
-    const npmRegistry = new NpmRegistry({
-      registry: 'https://registry.npmjs.org'
-    })
-
-    return this.packageRepoUtils
-      .getPackageInfo(pkg.packageName)
-      .then(async (packageInfo) => {
-        // Resolve version range to specific version
-        const resolvedVersion = await this.resolvePackageVersion(
-          pkg.packageName,
-          pkg.packageVersion,
-          packageInfo
-        )
+  async validate(pkg) {
+    const verifier = new NpmRegistry()
 
-        if (!resolvedVersion) {
-          throw new Error(
-            `Unable to resolve version ${pkg.packageVersion} for package ${pkg.packageName}`
-          )
-        }
+    try {
+      const packageInfo = await this.packageRepoUtils.getPackageInfo(pkg.packageName)
+      const resolvedVersion = await this.resolvePackageVersion(
+        pkg.packageName,
+        pkg.packageVersion,
+        packageInfo
+      )
 
-        return { packageInfo, resolvedVersion }
-      })
-      .then(({ resolvedVersion }) => {
-        return this.fetchRegistryKeys().then((keys) => {
-          return npmRegistry
-            .getManifest(`${pkg.packageName}@${resolvedVersion}`)
-            .then((manifest) => npmRegistry.verifySignatures(manifest, keys))
-        })
-      })
-      .then((metadata) => {
-        return metadata
-      })
-      .catch((error) => {
-        // Handle specific error cases
-        if (
-          error.message &&
-          error.message.includes('but the corresponding public key has expired')
-        ) {
-          // if the error is about an expired key, we throw a warning
-          // instead of an error, so that the process can continue
-          throw new Warning(`Package is signed with an expired key`)
-        }
-
-        throw new Warning(`Unable to verify package signature on registry: ${error.message}`)
-      })
-  }
+      if (!resolvedVersion) {
+        throw new Error(
+          `Unable to resolve version ${pkg.packageVersion} for package ${pkg.packageName}`
+        )
+      }
 
-  fetchRegistryKeys() {
-    if (registryKeysCache) {
-      return Promise.resolve(registryKeysCache)
+      const manifest = await this.registryClient.getManifest(
+        `${pkg.packageName}@${resolvedVersion}`,
+        packageInfo
+      )
+      if (!manifest.dist || !manifest.dist.signatures) {
+        return await verifier.verifySignatures(manifest, [])
+      }
+      const keys = await this.registryClient.getRegistryKeys(pkg.packageName)
+      return await verifier.verifySignatures(manifest, keys)
+    } catch (error) {
+      if (error instanceof NotEvaluated || error instanceof RegistryError) {
+        throw error
+      }
+      if (
+        error.message &&
+        error.message.includes('but the corresponding public key has expired')
+      ) {
+        throw new Warning('Package is signed with an expired key')
+      }
+      throw new Warning(`Unable to verify package signature on registry: ${error.message}`)
     }
-
-    const registryHost = 'https://registry.npmjs.org'
-    const registryKeysEndpoint = '/-/npm/v1/keys'
-
-    const registryKeysUrl = `${registryHost}${registryKeysEndpoint}`
-    return fetch(registryKeysUrl)
-      .then((response) => {
-        return response.json()
-      })
-      .then((response) => {
-        const registryKeys = response.keys
-
-        return registryKeys.map((key) => ({
-          ...key,
-          pemkey: `-----BEGIN PUBLIC KEY-----\n${key.key}\n-----END PUBLIC KEY-----`
-        }))
-      })
-      .then((keys) => {
-        // save it in the cached singleton object
-        registryKeysCache = keys
-        return keys
-      })
-      .catch((error) => {
-        throw new Warning(`Error fetching registry keys: ${error.message}`)
-      })
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",
@@ -43,7 +43,9 @@
     "access": "public"
   },
   "dependencies": {
+    "@npmcli/config": "^10.10.0",
     "npm-package-arg": "^13.0.2",
+    "npm-registry-fetch": "^19.1.1",
     "semver": "^7.7.4",
     "sigstore": "^4.1.0",
     "ssri": "^13.0.1"