npq 3.21.3 → 3.22.0

package/README.md

@@ -146,7 +146,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 | Will warn when a maintainer email domain does not resolve in public DNS; inconclusive DNS failures are reported as not evaluated | DNS non-resolution is a risk signal, not proof that the 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 +265,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/helpers/maintainerDomain.js

@@ -0,0 +1,77 @@
+'use strict'
+
+const { isIP } = require('node:net')
+const { domainToASCII } = require('node:url')
+
+const SPECIAL_USE_SUFFIXES = new Set([
+  'alt',
+  'corp',
+  'example',
+  'home',
+  'internal',
+  'invalid',
+  'local',
+  'localhost',
+  'mail',
+  'onion',
+  'test'
+])
+const RESERVED_HOSTS = new Set([
+  'example.com',
+  'example.net',
+  'example.org',
+  'home.arpa',
+  'in-addr.arpa',
+  'ip6.arpa'
+])
+
+function hasReservedSuffix(hostname, suffixes) {
+  return [...suffixes].some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`))
+}
+
+function normalizeMaintainerDomain(maintainerEmail) {
+  const atIndex = typeof maintainerEmail === 'string' ? maintainerEmail.lastIndexOf('@') : -1
+  const hasOneAtSign = atIndex > 0 && maintainerEmail.indexOf('@') === atIndex
+  const emailDomain = atIndex > 0 ? maintainerEmail.slice(atIndex + 1).trim() : ''
+
+  if (!hasOneAtSign || !emailDomain || /\s/.test(emailDomain)) {
+    return null
+  }
+
+  const hostname = emailDomain.replace(/\.$/, '').toLowerCase()
+  const bracketedIp = hostname.match(/^\[(.*)\]$/)
+  if (isIP(bracketedIp ? bracketedIp[1] : hostname)) {
+    return null
+  }
+
+  const asciiHostname = domainToASCII(hostname).toLowerCase()
+  const labels = asciiHostname.split('.')
+  const labelsAreValid = labels.every(
+    (label) =>
+      label.length > 0 &&
+      label.length <= 63 &&
+      /^[a-z0-9-]+$/.test(label) &&
+      !label.startsWith('-') &&
+      !label.endsWith('-')
+  )
+
+  if (
+    !asciiHostname ||
+    isIP(asciiHostname) ||
+    asciiHostname.length > 253 ||
+    labels.length < 2 ||
+    !labelsAreValid ||
+    hasReservedSuffix(asciiHostname, SPECIAL_USE_SUFFIXES) ||
+    hasReservedSuffix(asciiHostname, RESERVED_HOSTS)
+  ) {
+    return null
+  }
+
+  return asciiHostname
+}
+
+function isSimpleMaintainerDomain(domain) {
+  return domain.split('.').length === 2
+}
+
+module.exports = { isSimpleMaintainerDomain, normalizeMaintainerDomain }

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

@@ -4,6 +4,11 @@ const BaseMarshall = require('./baseMarshall')
 const { marshallCategories } = require('./constants')
 const NotEvaluated = require('../helpers/notEvaluated')
 const Warning = require('../helpers/warning')
+const {
+  isSimpleMaintainerDomain,
+  normalizeMaintainerDomain
+} = require('../helpers/maintainerDomain')
+const { defaultRdapClient, rdapStatuses } = require('../helpers/rdapClient')
 const { Resolver } = require('dns/promises')
 
 const dns = new Resolver()
@@ -16,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() {
@@ -36,17 +42,9 @@ class Marshall extends BaseMarshall {
     const emailDomains = new Map()
     let invalidMaintainers = 0
     for (const maintainerInfo of maintainersAccounts) {
-      const maintainerEmail = maintainerInfo && maintainerInfo.email
-      const atIndex = typeof maintainerEmail === 'string' ? maintainerEmail.lastIndexOf('@') : -1
-      const emailDomain =
-        atIndex > 0
-          ? maintainerEmail
-              .slice(atIndex + 1)
-              .trim()
-              .toLowerCase()
-          : ''
-
-      if (!emailDomain || emailDomain.includes('@') || /\s/.test(emailDomain)) {
+      const emailDomain = normalizeMaintainerDomain(maintainerInfo && maintainerInfo.email)
+
+      if (!emailDomain) {
         invalidMaintainers += 1
         continue
       }
@@ -62,7 +60,7 @@ class Marshall extends BaseMarshall {
     const resolutionResults = await Promise.allSettled(
       domains.map((emailDomain) => this.dnsResolver.resolve(emailDomain, 'NS'))
     )
-    const suspectedDomains = []
+    const simpleMissingDomains = []
     const incompleteDomains = []
 
     resolutionResults.forEach((result, index) => {
@@ -78,20 +76,68 @@ class Marshall extends BaseMarshall {
         errorCode || '<unknown>'
       )
 
-      if (errorCode === 'ENOTFOUND') {
-        suspectedDomains.push(domain)
+      if (errorCode === 'ENOTFOUND' && isSimpleMaintainerDomain(domain)) {
+        simpleMissingDomains.push(domain)
       } else {
         incompleteDomains.push(domain)
       }
     })
 
+    const topLevelDomains = [
+      ...new Set(simpleMissingDomains.map((domain) => domain.split('.')[1]))
+    ].sort()
+    const topLevelResults = await Promise.allSettled(
+      topLevelDomains.map((domain) => this.dnsResolver.resolve(domain, 'NS'))
+    )
+    const publicTopLevelDomains = new Set()
+
+    topLevelResults.forEach((result, index) => {
+      const domain = topLevelDomains[index]
+      if (result.status === 'fulfilled') {
+        publicTopLevelDomains.add(domain)
+        return
+      }
+
+      this.debug(
+        '\nUnable to verify public top-level domain %s with code %s',
+        domain,
+        (result.reason && result.reason.code) || '<unknown>'
+      )
+    })
+
+    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'
@@ -104,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.3",
+  "version": "3.22.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",