npq 3.18.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

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/package.json

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