npq 3.21.4 → 3.22.1

package/README.md

@@ -130,6 +130,7 @@ NPQ_PKG_MGR=pnpm npx npq install fastify
 
 ```bash
 alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
+pnpm --filter workspace... add express
 ```
 
 Note: `npq` by default will offload all commands and their arguments to the `npm` (or other package manager as specified) after it finished its due-diligence checks for the respective packages.
@@ -146,7 +147,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | 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 | Normalizes and checks complete maintainer email hosts, warning only when a simple two-label domain does not resolve but its public top-level domain does | Multipart and otherwise inconclusive DNS failures are reported as not evaluated; non-resolution is not proof that a domain is expired or available
+| expired domains | Normalizes and checks complete maintainer email hosts, then corroborates a simple two-label DNS failure through authoritative RDAP before warning | Multipart and otherwise inconclusive results are reported as not evaluated; see [expired-domain marshall documentation](docs/feature/expired-domains.md)
 | 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
@@ -265,7 +266,7 @@ When auto-continue is disabled, npq will always prompt for explicit confirmation
 
 5. **Why is NPQ connecting to external domains like gmail.com or personal websites during installation?**
 
-* This is not telemetry. NPQ does not collect any usage data. When auditing a package, NPQ fetches the maintainers/authors of the dependency and checks their email addresses to verify they are valid and not associated with expired domains. Expired domains can be abused by attackers for account takeover (ATO) attacks to compromise packages with malicious versions. Hence, NPQ may make DNS requests to domains like `gmail.com` or personal domains found in maintainer emails. Additionally, NPQ makes HTTP requests to `osv.dev` to fetch security vulnerability data (or uses Snyk if configured, as a prioritized option).
+* This is not telemetry. NPQ does not collect any usage data. When auditing a package, NPQ fetches the maintainers/authors of the dependency and checks their email addresses to verify they are valid and not associated with expired domains. Expired domains can be abused by attackers for account takeover (ATO) attacks to compromise packages with malicious versions. Hence, NPQ may make DNS requests to domains like `gmail.com` or personal domains found in maintainer emails. After a simple two-label domain returns NXDOMAIN and its top-level domain resolves, NPQ may fetch the official IANA RDAP bootstrap and query the selected authoritative HTTPS RDAP service, sending only the normalized two-label domain. Additionally, NPQ makes HTTP requests to `osv.dev` to fetch security vulnerability data (or uses Snyk if configured, as a prioritized option).
 
 ## Documentation
 

package/lib/cli.js

@@ -3,6 +3,7 @@
 const { parseArgs } = require('node:util')
 const npa = require('npm-package-arg')
 const pkg = require('../package.json')
+const { parsePackageManagerArguments } = require('./helpers/packageManagerArgumentParser')
 
 const INSTALL_SUBCOMMANDS = new Set([
   'install',
@@ -145,22 +146,11 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
   }
 
   static parseArgsMinimal() {
-    const config = {
-      allowPositionals: true,
-      strict: false,
-      options: {
-        install: {
-          type: 'string',
-          short: 'i',
-          default: 'install'
-        },
-        registry: { type: 'string' },
-        userconfig: { type: 'string' },
-        globalconfig: { type: 'string' }
-      }
-    }
-
-    const { values, positionals } = parseArgs(config)
+    const packageManager = process.env.NPQ_PKG_MGR || 'npm'
+    const { values, positionals } = parsePackageManagerArguments({
+      packageManager,
+      args: process.argv.slice(2)
+    })
 
     const earlyExitNoInstall = true
     const normalizedPackages = this._extractPackagesFromPositionals(positionals, earlyExitNoInstall)

package/lib/helpers/packageManagerArgumentParser.js

@@ -0,0 +1,39 @@
+'use strict'
+
+const { parseArgs } = require('node:util')
+
+const BASE_OPTIONS = {
+  install: {
+    type: 'string',
+    short: 'i',
+    default: 'install'
+  },
+  registry: { type: 'string' },
+  userconfig: { type: 'string' },
+  globalconfig: { type: 'string' }
+}
+
+function parsePackageManagerArguments({ packageManager, args }) {
+  const options =
+    packageManager === 'pnpm'
+      ? {
+          ...BASE_OPTIONS,
+          filter: { type: 'string', short: 'F', multiple: true },
+          'filter-prod': { type: 'string', multiple: true }
+        }
+      : BASE_OPTIONS
+
+  const config = {
+    allowPositionals: true,
+    strict: false,
+    options
+  }
+
+  if (args !== undefined) {
+    config.args = args
+  }
+
+  return parseArgs(config)
+}
+
+module.exports.parsePackageManagerArguments = parsePackageManagerArguments

package/lib/helpers/rdapClient.js

@@ -0,0 +1,146 @@
+'use strict'
+
+const IANA_DNS_BOOTSTRAP_URL = 'https://data.iana.org/rdap/dns.json'
+const DEFAULT_TIMEOUT_MS = 3000
+
+const rdapStatuses = Object.freeze({
+  Registered: 'registered',
+  NotFound: 'not-found',
+  Inconclusive: 'inconclusive'
+})
+
+function isHttpsUrl(value) {
+  try {
+    return new URL(value).protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+class RdapClient {
+  constructor({
+    fetcher = globalThis.fetch,
+    bootstrapUrl = IANA_DNS_BOOTSTRAP_URL,
+    timeoutMs = DEFAULT_TIMEOUT_MS
+  } = {}) {
+    this.fetcher = fetcher
+    this.bootstrapUrl = bootstrapUrl
+    this.timeoutMs = timeoutMs
+    this.bootstrapPromise = null
+    this.domainPromises = new Map()
+  }
+
+  lookup(domain) {
+    const normalizedDomain = domain.toLowerCase()
+    if (!this.domainPromises.has(normalizedDomain)) {
+      this.domainPromises.set(
+        normalizedDomain,
+        this.lookupUncached(normalizedDomain).catch((error) => ({
+          status: rdapStatuses.Inconclusive,
+          reason: error && (error.code || error.name || error.message)
+        }))
+      )
+    }
+
+    return this.domainPromises.get(normalizedDomain)
+  }
+
+  async lookupUncached(domain) {
+    const bootstrap = await this.getBootstrap()
+    const endpoint = this.findEndpoint(bootstrap, domain)
+
+    if (!endpoint) {
+      return { status: rdapStatuses.Inconclusive, reason: 'bootstrap-unavailable' }
+    }
+
+    const baseUrl = endpoint.endsWith('/') ? endpoint : `${endpoint}/`
+    const lookupUrl = new URL(`domain/${encodeURIComponent(domain)}`, baseUrl).toString()
+    const response = await this.request(lookupUrl)
+
+    if (response.status === 404) {
+      return { status: rdapStatuses.NotFound }
+    }
+
+    if (!response.ok) {
+      return { status: rdapStatuses.Inconclusive, reason: `http-${response.status}` }
+    }
+
+    const body = await response.json()
+    if (!body || body.objectClassName !== 'domain') {
+      return { status: rdapStatuses.Inconclusive, reason: 'invalid-response' }
+    }
+
+    return { status: rdapStatuses.Registered }
+  }
+
+  getBootstrap() {
+    if (!this.bootstrapPromise) {
+      this.bootstrapPromise = this.loadBootstrap()
+    }
+
+    return this.bootstrapPromise
+  }
+
+  async loadBootstrap() {
+    if (!isHttpsUrl(this.bootstrapUrl)) {
+      throw new Error('RDAP bootstrap URL must use HTTPS')
+    }
+
+    const response = await this.request(this.bootstrapUrl)
+    if (!response.ok) {
+      throw new Error(`RDAP bootstrap request failed with HTTP ${response.status}`)
+    }
+
+    const bootstrap = await response.json()
+    if (!bootstrap || !Array.isArray(bootstrap.services)) {
+      throw new Error('RDAP bootstrap response is invalid')
+    }
+
+    return bootstrap
+  }
+
+  findEndpoint(bootstrap, domain) {
+    const tld = domain.split('.').pop().toLowerCase()
+
+    for (const service of bootstrap.services) {
+      if (!Array.isArray(service) || !Array.isArray(service[0]) || !Array.isArray(service[1])) {
+        continue
+      }
+
+      const handlesTld = service[0].some(
+        (candidate) => typeof candidate === 'string' && candidate.toLowerCase() === tld
+      )
+      if (!handlesTld) {
+        continue
+      }
+
+      return service[1].find((candidate) => typeof candidate === 'string' && isHttpsUrl(candidate))
+    }
+
+    return undefined
+  }
+
+  request(url) {
+    if (!isHttpsUrl(url)) {
+      throw new Error('RDAP requests must use HTTPS')
+    }
+
+    return this.fetcher(url, {
+      headers: {
+        accept: 'application/rdap+json, application/json'
+      },
+      redirect: 'error',
+      signal: AbortSignal.timeout(this.timeoutMs)
+    })
+  }
+}
+
+const defaultRdapClient = new RdapClient()
+
+module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  IANA_DNS_BOOTSTRAP_URL,
+  RdapClient,
+  defaultRdapClient,
+  rdapStatuses
+}

package/lib/marshalls/expiredDomains.marshall.js

@@ -8,6 +8,7 @@ const {
   isSimpleMaintainerDomain,
   normalizeMaintainerDomain
 } = require('../helpers/maintainerDomain')
+const { defaultRdapClient, rdapStatuses } = require('../helpers/rdapClient')
 const { Resolver } = require('dns/promises')
 
 const dns = new Resolver()
@@ -20,6 +21,7 @@ class Marshall extends BaseMarshall {
     this.name = MARSHALL_NAME
     this.categoryId = marshallCategories.PackageHealth.id
     this.dnsResolver = options.dnsResolver || dns
+    this.rdapClient = options.rdapClient || defaultRdapClient
   }
 
   title() {
@@ -103,21 +105,39 @@ class Marshall extends BaseMarshall {
       )
     })
 
-    const suspectedDomains = simpleMissingDomains.filter((domain) => {
+    const rdapCandidateDomains = simpleMissingDomains.filter((domain) => {
       const isPublic = publicTopLevelDomains.has(domain.split('.')[1])
       if (!isPublic) {
         incompleteDomains.push(domain)
       }
       return isPublic
     })
+    const rdapResults = await Promise.allSettled(
+      rdapCandidateDomains.map((domain) => this.rdapClient.lookup(domain))
+    )
+    const corroboratedDomains = []
+
+    rdapResults.forEach((result, index) => {
+      const domain = rdapCandidateDomains[index]
+      if (result.status === 'rejected' || !result.value) {
+        incompleteDomains.push(domain)
+        return
+      }
+
+      if (result.value.status === rdapStatuses.NotFound) {
+        corroboratedDomains.push(domain)
+      } else if (result.value.status !== rdapStatuses.Registered) {
+        incompleteDomains.push(domain)
+      }
+    })
 
     const incompleteCount =
       invalidMaintainers +
       incompleteDomains.reduce((count, domain) => count + emailDomains.get(domain), 0)
-    if (suspectedDomains.length > 0) {
-      const domainNoun = suspectedDomains.length === 1 ? 'domain' : 'domains'
-      const resolveVerb = suspectedDomains.length === 1 ? 'does' : 'do'
-      let message = `Maintainer ${domainNoun} ${suspectedDomains.join(', ')} ${resolveVerb} not resolve in public DNS and may warrant investigation.`
+    if (corroboratedDomains.length > 0) {
+      const domainNoun = corroboratedDomains.length === 1 ? 'domain' : 'domains'
+      const resolveVerb = corroboratedDomains.length === 1 ? 'does' : 'do'
+      let message = `Maintainer ${domainNoun} ${corroboratedDomains.join(', ')} ${resolveVerb} not resolve in public DNS, and RDAP found no active registration; account takeover may be possible.`
 
       if (incompleteCount > 0) {
         const recordNoun = incompleteCount === 1 ? 'record' : 'records'
@@ -130,7 +150,7 @@ class Marshall extends BaseMarshall {
     if (incompleteCount > 0) {
       const recordNoun = incompleteCount === 1 ? 'record' : 'records'
       throw new NotEvaluated(
-        `${incompleteCount} maintainer ${recordNoun} could not be evaluated because DNS or email data was incomplete`
+        `${incompleteCount} maintainer ${recordNoun} could not be evaluated because DNS, RDAP, or email data was incomplete`
       )
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.21.4",
+  "version": "3.22.1",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",