npq 3.17.0 → 3.19.0

package/README.md

@@ -130,7 +130,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | Marshall Name | Description | Notes
 | --- | --- | ---
 | 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 | Will show a warning if a package has been found without an author field | Checks the latest version for an author
+| 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
 | 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
@@ -139,7 +139,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | 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
+| 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)
 | 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/lib/marshalls/author.marshall.js

@@ -3,9 +3,9 @@
 /**
  * Author Marshall - Package Publisher Security Checks
  *
- * This marshall performs two distinct security checks related to package publishing:
+ * This marshall performs three security checks related to package publishing:
  *
- * 1. NEW AUTHOR CHECK (lines 65-80)
+ * 1. NEW AUTHOR CHECK
  *    Detects if this is the first version ever published by this user for this package.
  *    - Condition: No prior versions exist from this user, OR the current version is their first.
  *    - Only flags if the version was published recently (≤21 days ago).
@@ -13,7 +13,15 @@
  *      compromise or malicious takeover. However, if the "first" version is old (e.g., 10 years),
  *      it's not a current risk.
  *
- * 2. VERSION RECENCY CHECK (lines 91-106)
+ * 2. DORMANT MAINTAINER CHECK
+ *    Detects if the same maintainer (_npmUser email) had a prior publish on this package,
+ *    then a long gap before the current version.
+ *    - Gap > ~9 months: Error
+ *    - Gap > ~6 months (and ≤9 months): Warning
+ *    - Strict boundaries: exactly 183 or 274 days does not cross the next tier.
+ *    - Rationale: Long-inactive accounts publishing again can indicate compromise or neglected keys.
+ *
+ * 3. VERSION RECENCY CHECK
  *    Detects if the current version being installed was published very recently.
  *    - ≤7 days: Throws an Error (high risk)
  *    - ≤30 days: Throws a Warning (moderate risk)
@@ -21,9 +29,7 @@
  *    - Rationale: Very recently published versions haven't had time for community review
  *      and could contain undiscovered malicious code. This is independent of author history.
  *
- * These two checks are complementary:
- * - Check 1 focuses on WHO published (author trustworthiness)
- * - Check 2 focuses on WHEN it was published (version maturity)
+ * Checks run in order (1 → 2 → 3); the first thrown Error or Warning ends validation.
  */
 
 const BaseMarshall = require('./baseMarshall')
@@ -31,6 +37,44 @@ const Warning = require('../helpers/warning')
 const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'author'
+const DORMANT_MAINTAINER_WARNING_DAYS = Math.round(365.25 / 2) // ~6 months (183)
+const DORMANT_MAINTAINER_ERROR_DAYS = Math.round(365.25 * 0.75) // ~9 months (274)
+
+/**
+ * Latest publish time (ms) for `email` on this package strictly before `packageVersion`'s time.
+ * @returns {number|null}
+ */
+function findLastPriorPublishTimeMsForEmail(pakument, packageVersion, email) {
+  const currentTimeStr = pakument.time && pakument.time[packageVersion]
+  if (!currentTimeStr || typeof currentTimeStr !== 'string') {
+    return null
+  }
+  const currentMs = Date.parse(currentTimeStr)
+  if (Number.isNaN(currentMs)) {
+    return null
+  }
+
+  let bestMs = null
+  for (const v of Object.keys(pakument.versions || {})) {
+    const t = pakument.time && pakument.time[v]
+    if (!t || typeof t !== 'string') {
+      continue
+    }
+    const ver = pakument.versions[v]
+    if (!ver || !ver._npmUser || ver._npmUser.email !== email) {
+      continue
+    }
+    const priorMs = Date.parse(t)
+    if (Number.isNaN(priorMs) || priorMs >= currentMs) {
+      continue
+    }
+    if (bestMs === null || priorMs > bestMs) {
+      bestMs = priorMs
+    }
+  }
+
+  return bestMs
+}
 
 class Marshall extends BaseMarshall {
   constructor(options) {
@@ -46,17 +90,18 @@ class Marshall extends BaseMarshall {
   /**
    * Validates package author and version recency for security risks.
    *
-   * Performs two checks:
+   * Performs three checks:
    * 1. New Author Check: Flags if this is the user's first publish of this package
    *    AND the version was published within the last 21 days.
-   * 2. Version Recency Check: Flags recently published versions regardless of author:
+   * 2. Dormant Maintainer Check: Prior publish by same email with a long gap before this release.
+   * 3. Version Recency Check: Flags recently published versions regardless of author:
    *    - Error if ≤7 days old
    *    - Warning if ≤30 days old
    *
    * @param {Object} pkg - Package info with packageName and packageVersion
    * @returns {string} The version's publish date string if all checks pass
-   * @throws {Error} If security risk is detected (new author or very recent version)
-   * @throws {Warning} If moderate risk is detected (version 8-30 days old)
+   * @throws {Error} If security risk is detected
+   * @throws {Warning} If moderate risk is detected
    */
   async validate(pkg) {
     // @TODO move some of these utility functions about first package version
@@ -117,6 +162,32 @@ class Marshall extends BaseMarshall {
       // )
     }
 
+    const priorPublishMs = findLastPriorPublishTimeMsForEmail(
+      pakument,
+      packageVersion,
+      npmUser.email
+    )
+    if (priorPublishMs !== null && versionPublishedDateString) {
+      const currentMs = Date.parse(versionPublishedDateString)
+      if (!Number.isNaN(currentMs)) {
+        const gapMs = currentMs - priorPublishMs
+        let gapDays = 0
+        if (gapMs > 0) {
+          gapDays = Math.round(gapMs / (1000 * 60 * 60 * 24))
+        }
+        if (gapDays > DORMANT_MAINTAINER_ERROR_DAYS) {
+          throw new Error(
+            `The maintainer ${npmUser.name} <${npmUser.email}> had not published this package for ${gapDays} days before this release (more than 9 months dormant)`
+          )
+        }
+        if (gapDays > DORMANT_MAINTAINER_WARNING_DAYS) {
+          throw new Warning(
+            `The maintainer ${npmUser.name} <${npmUser.email}> had not published this package for ${gapDays} days before this release (more than 6 months dormant)`
+          )
+        }
+      }
+    }
+
     // get date in ms
     const dateDiffInMsVersionPublished = new Date() - new Date(versionPublishedDateString)
     let dateDiffVersionPublished = 0

package/lib/marshalls/provenance.marshall.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// const semver = require('semver')
+const semver = require('semver')
 const BaseMarshall = require('./baseMarshall')
 const NpmRegistry = require('../helpers/npmRegistry')
 const Warning = require('../helpers/warning')
@@ -8,6 +8,62 @@ const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'provenance'
 
+/**
+ * Newest semver older than installedVersion whose packument entry includes dist.attestations.
+ * Uses only packageInfo already returned by getPackageInfo (no extra HTTP).
+ */
+function findNewestPriorVersionWithDistAttestations(packageInfo, installedVersion) {
+  if (!packageInfo?.versions || !semver.valid(installedVersion)) {
+    return null
+  }
+
+  const older = Object.keys(packageInfo.versions)
+    .filter((v) => semver.valid(v) && semver.lt(v, installedVersion))
+    .sort(semver.rcompare)
+
+  for (const v of older) {
+    if (packageInfo.versions[v]?.dist?.attestations) {
+      return v
+    }
+  }
+
+  return null
+}
+
+/**
+ * Whether this error means the resolved version did not yield verifiable provenance,
+ * as opposed to infrastructure failures (manifest fetch, keys, attestations URL fetch).
+ */
+function shouldConsiderProvenanceRegression(error) {
+  const msg = error && typeof error.message === 'string' ? error.message : ''
+  if (!msg) {
+    return false
+  }
+
+  if (msg.includes('Package has no attestations to verify')) {
+    return true
+  }
+
+  // Malformed checkpoint (#329) is handled in validate() before this runs.
+  if (error.code === 'EATTESTATIONVERIFY') {
+    return true
+  }
+
+  if (
+    error.code === 'EMISSINGSIGNATUREKEY' ||
+    error.code === 'EEXPIREDSIGNATUREKEY' ||
+    error.code === 'EATTESTATIONSUBJECT'
+  ) {
+    return true
+  }
+
+  if (msg.includes('failed to verify attestation')) {
+    return true
+  }
+
+  return false
+}
+
 class Marshall extends BaseMarshall {
   constructor(options) {
     super(options)
@@ -19,6 +75,19 @@ class Marshall extends BaseMarshall {
     return 'Verifying package provenance'
   }
 
+  throwIfProvenanceRegression(validationMetadata) {
+    const prior = findNewestPriorVersionWithDistAttestations(
+      validationMetadata.packageInfo,
+      validationMetadata.version
+    )
+
+    if (prior) {
+      throw new Error(
+        `Provenance regression detected: published version ${prior} includes npm provenance metadata, but ${validationMetadata.name}@${validationMetadata.version} does not (or it could not be verified).`
+      )
+    }
+  }
+
   validate(pkg) {
     const validationMetadata = {}
     const npmRegistry = new NpmRegistry({
@@ -56,6 +125,7 @@ class Marshall extends BaseMarshall {
       })
       .then((metadata) => {
         if (!metadata || !metadata._attestations) {
+          this.throwIfProvenanceRegression(validationMetadata)
           throw new Warning('the package was published without any attestations')
         }
 
@@ -67,114 +137,42 @@ class Marshall extends BaseMarshall {
         // See: https://github.com/lirantal/npq/issues/329
         if (error.code === 'EATTESTATIONVERIFY' && error.message.includes('malformed checkpoint')) {
           return []
-        } else {
-          if (error.message.includes('Package has no attestations to verify')) {
-            throw new Warning(
-              `Unable to verify provenance: the package was published without any attestations`
-            )
-          } else {
-            this.debug(
-              '\nUnable to verify provenance for package %s@%s: %s',
-              validationMetadata.name,
-              validationMetadata.version,
-              error.message
-            )
-            throw new Warning(`Unable to verify provenance`)
-          }
         }
-      })
-  }
-
-  /*
-  async checkProvenanceRegression(validationMetadata) {
-    const { packageInfo, name, version } = validationMetadata
-    
-    if (!packageInfo || !packageInfo.versions) {
-      return // Cannot check regression without version information
-    }
-
-    const allVersions = Object.keys(packageInfo.versions)
-    const validVersions = allVersions.filter(v => semver.valid(v))
-    
-    if (validVersions.length === 0) {
-      return // No valid versions to compare
-    }
 
-    // Get all versions older than the target version
-    const olderVersions = validVersions
-      .filter(v => semver.lt(v, version))
-      .sort(semver.rcompare) // Sort descending, newest first
-
-    if (olderVersions.length === 0) {
-      return // No older versions to check
-    }
-
-    // Check if any older versions had provenance
-    let hasProvenanceRegressionDetected = false
-    const versionWithProvenance = []
-
-    // NOTE: Going back all versions and fetching their manifest to check provenance
-    // is going to be very slow. We can limit this function to go back just 2-3 versions
-    // and then stop there
-    for (const olderVersion of olderVersions) {
-      try {
-        const keys = await this.fetchRegistryKeys()
-        const metadata = await pacote.manifest(`${name}@${olderVersion}`, {
-          verifyAttestations: true,
-          registry: 'https://registry.npmjs.org',
-          '//registry.npmjs.org/:_keys': keys
-        })
-
-        if (metadata && metadata._attestations) {
-          versionWithProvenance.push(olderVersion)
-          hasProvenanceRegressionDetected = true
+        if (
+          error instanceof Error &&
+          error.message === 'Unable to find version or dist-tag for package'
+        ) {
+          throw error
         }
-      } catch (error) {
-        // Ignore errors for older versions as they might not have provenance
-        // We only care if they successfully had provenance before
-        continue
-      }
-    }
-
-    // If older versions had provenance, check if current version lacks it
-    if (hasProvenanceRegressionDetected) {
-      try {
-        const keys = await this.fetchRegistryKeys()
-        const currentMetadata = await pacote.manifest(`${name}@${version}`, {
-          verifyAttestations: true,
-          registry: 'https://registry.npmjs.org',
-          '//registry.npmjs.org/:_keys': keys
-        })
 
-        if (!currentMetadata || !currentMetadata._attestations) {
-          const latestVersionWithProvenance = versionWithProvenance[0] // First is the newest
-          throw new Error(
-            `Provenance regression detected: Previous version ${latestVersionWithProvenance} had provenance attestations, but version ${version} does not. This represents a security downgrade.`
-          )
-        }
-      } catch (error) {
-        // If it's our custom error, re-throw it
-        if (error.message.includes('Provenance regression detected')) {
+        if (
+          error instanceof Warning &&
+          (error.message.includes('Error fetching registry keys') ||
+            error.message === 'the package was published without any attestations')
+        ) {
           throw error
         }
-        
-        // If it's a verification error, the current version lacks valid provenance
-        if (error.code === 'EATTESTATIONVERIFY' || error.message.includes('attestations')) {
-          const latestVersionWithProvenance = versionWithProvenance[0]
-          throw new Error(
-            `Provenance regression detected: Previous version ${latestVersionWithProvenance} had provenance attestations, but version ${version} does not. This represents a security downgrade.`
+
+        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`
           )
         }
-        
-        // For other errors, treat as if current version lacks provenance
-        const latestVersionWithProvenance = versionWithProvenance[0]
-        throw new Error(
-          `Provenance regression detected: Previous version ${latestVersionWithProvenance} had provenance attestations, but version ${version} does not. This represents a security downgrade.`
+
+        this.debug(
+          '\nUnable to verify provenance for package %s@%s: %s',
+          validationMetadata.name,
+          validationMetadata.version,
+          error.message
         )
-      }
-    }
+        throw new Warning(`Unable to verify provenance`)
+      })
   }
-  */
 
   fetchRegistryKeys() {
     const registryHost = 'https://registry.npmjs.org'

package/package.json

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