npq 3.19.6 → 3.21.0

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)
   }