npq 3.15.2 → 3.15.4

package/lib/marshalls/author.marshall.js

@@ -1,5 +1,31 @@
 'use strict'
 
+/**
+ * Author Marshall - Package Publisher Security Checks
+ *
+ * This marshall performs two distinct security checks related to package publishing:
+ *
+ * 1. NEW AUTHOR CHECK (lines 65-80)
+ *    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).
+ *    - Rationale: A brand new publisher on an established package could indicate account
+ *      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)
+ *    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)
+ *    - Only applies if version is ≤45 days old.
+ *    - 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)
+ */
+
 const BaseMarshall = require('./baseMarshall')
 const Warning = require('../helpers/warning')
 const { marshallCategories } = require('./constants')
@@ -18,16 +44,19 @@ class Marshall extends BaseMarshall {
   }
 
   /**
-   * What do we check?
-   * 1. Who is the user who published the package? in the pakument's `_npmUser` field
-   * 2. Is this the first time we see this user publishing a package?
-   *   If so, halt and report.
-   * 3. Start from first version to latest version and check if they published
-   *   the package before.
-   *   If they did, and the difference between this published version date and
-   *   first is more than 30 days then halt and report.
-   * @param {*} pkg
-   * @returns
+   * Validates package author and version recency for security risks.
+   *
+   * Performs two 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:
+   *    - 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)
    */
   async validate(pkg) {
     // @TODO move some of these utility functions about first package version
@@ -40,7 +69,7 @@ class Marshall extends BaseMarshall {
     )
 
     // @TODO fix to work for both explicit versions (1.0.0) and also
-    // for dis-tags (latest)
+    // for dist-tags (latest)
     const npmUser = pakument.versions[packageVersion]._npmUser
     if (!npmUser || !npmUser.email) {
       throw new Error('Could not determine publishing user for this package version')
@@ -88,32 +117,23 @@ class Marshall extends BaseMarshall {
       // )
     }
 
-    const firstPublishedDateString = pakument.time[firstVersionForUser.version]
-
     // get date in ms
-    const currentDate = new Date()
-    const dateDiffInMsVersionPublished = currentDate - new Date(versionPublishedDateString)
+    const dateDiffInMsVersionPublished = new Date() - new Date(versionPublishedDateString)
     let dateDiffVersionPublished = 0
     if (dateDiffInMsVersionPublished > 0) {
       dateDiffVersionPublished = Math.round(dateDiffInMsVersionPublished / (1000 * 60 * 60 * 24))
     }
 
     if (dateDiffVersionPublished <= 45) {
-      const dateDiffInMs = new Date(versionPublishedDateString) - new Date(firstPublishedDateString)
-      let dateDiffInDays = 0
-      if (dateDiffInMs > 0) {
-        dateDiffInDays = Math.round(dateDiffInMs / (1000 * 60 * 60 * 24))
-      }
-
-      if (dateDiffInDays <= 7) {
+      if (dateDiffVersionPublished <= 7) {
         throw new Error(
-          `The user ${npmUser.name} <${npmUser.email}> published this package for the first time only ${dateDiffInDays} days ago`
+          `This version was published only ${dateDiffVersionPublished} days ago by ${npmUser.name} <${npmUser.email}>`
         )
       }
 
-      if (dateDiffInDays <= 30) {
+      if (dateDiffVersionPublished <= 30) {
         throw new Warning(
-          `The user ${npmUser.name} <${npmUser.email}> published this package for the first time only ${dateDiffInDays} days ago`
+          `This version was published only ${dateDiffVersionPublished} days ago by ${npmUser.name} <${npmUser.email}>`
         )
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.15.2",
+  "version": "3.15.4",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "fastest-levenshtein": "^1.0.16",
-    "npm-package-arg": "^13.0.0",
+    "npm-package-arg": "^13.0.2",
     "semver": "^7.7.3",
     "sigstore": "^3.1.0",
     "ssri": "^12.0.0"