npq 3.5.4 → 3.6.0

package/README.md

@@ -97,6 +97,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | 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
+| 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
 
 ### Disabling Marshalls
 
@@ -125,6 +126,7 @@ Here are all the available environment variable names for disabling specific mar
 | signatures | `MARSHALL_DISABLE_SIGNATURES` | Disable registry signature verification |
 | snyk | `MARSHALL_DISABLE_SNYK` | Disable Snyk vulnerability checks |
 | typosquatting | `MARSHALL_DISABLE_TYPOSQUATTING` | Disable typosquatting detection |
+| version-maturity | `MARSHALL_DISABLE_VERSION_MATURITY` | Disable version maturity checks |
 
 ### Run checks on package without installing it:
 

package/__tests__/marshalls.typosquatting.test.js

@@ -0,0 +1,67 @@
+const TyposquattingMarshall = require('../lib/marshalls/typosquatting.marshall')
+
+describe('Typosquatting Marshall', () => {
+  test('should remove duplicate entries from similar packages', async () => {
+    const typosquattingMarshall = new TyposquattingMarshall({
+      packageRepoUtils: null
+    })
+
+    // Mock the top packages data to include duplicates
+    const originalTopPackages = require('../data/top-packages.json')
+    
+    // Create a test package that would match multiple similar packages
+    const pkg = {
+      packageName: 'ghtml' // This should match 'html' which appears multiple times in the data
+    }
+
+    try {
+      await typosquattingMarshall.validate(pkg)
+      // If no error is thrown, the test should fail
+      expect(true).toBe(false)
+    } catch (error) {
+      // Check that the error message doesn't contain duplicate entries
+      const errorMessage = error.message
+      expect(errorMessage).toContain('Package name could be a typosquatting attempt for popular package(s):')
+      
+      // Extract the package names from the error message
+      const packagesList = errorMessage.split('popular package(s): ')[1]
+      const packages = packagesList.split(', ')
+      
+      // Check that there are no duplicates
+      const uniquePackages = [...new Set(packages)]
+      expect(packages.length).toBe(uniquePackages.length)
+      
+      // Verify that 'html' appears only once even though it exists multiple times in the data
+      const htmlCount = packages.filter(pkg => pkg === 'html').length
+      expect(htmlCount).toBe(1)
+    }
+  })
+
+  test('should not report typosquatting for packages in top packages list', async () => {
+    const typosquattingMarshall = new TyposquattingMarshall({
+      packageRepoUtils: null
+    })
+
+    // Test with a package that exists in the top packages list
+    const pkg = {
+      packageName: 'express' // This should be in the top packages list
+    }
+
+    const result = await typosquattingMarshall.validate(pkg)
+    expect(result).toEqual([])
+  })
+
+  test('should not report typosquatting for packages with no similar matches', async () => {
+    const typosquattingMarshall = new TyposquattingMarshall({
+      packageRepoUtils: null
+    })
+
+    // Test with a package that has no similar matches
+    const pkg = {
+      packageName: 'verylonganduniquenamethatdoesnotmatchanything'
+    }
+
+    const result = await typosquattingMarshall.validate(pkg)
+    expect(result).toEqual([])
+  })
+})

package/__tests__/marshalls.version-maturity.test.js

@@ -0,0 +1,194 @@
+'use strict'
+
+const Marshall = require('../lib/marshalls/version-maturity.marshall')
+
+describe('Version Maturity Marshall', () => {
+  test('should have the correct title', () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: null
+    })
+
+    expect(testMarshall.title()).toEqual('Checking version maturity')
+  })
+
+  test('should throw error for recently published version (same day)', async () => {
+    const now = new Date()
+    const hoursAgo = new Date(now.getTime() - 2 * 60 * 60 * 1000) // 2 hours ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': hoursAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 2 hours ago) - consider waiting for community review'
+    )
+  })
+
+  test('should throw error for recently published version (within threshold)', async () => {
+    const now = new Date()
+    const daysAgo = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000) // 3 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': daysAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 3 days ago) - consider waiting for community review'
+    )
+  })
+
+  test('should throw error for version published exactly 1 day ago', async () => {
+    const now = new Date()
+    const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000) // 1 day ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': oneDayAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 1 day ago) - consider waiting for community review'
+    )
+  })
+
+  test('should pass for version published beyond threshold', async () => {
+    const now = new Date()
+    const weekAgo = new Date(now.getTime() - 8 * 24 * 60 * 60 * 1000) // 8 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': weekAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    const result = await testMarshall.validate({
+      packageName: 'test-package',
+      packageVersion: '1.0.0'
+    })
+
+    expect(result).toEqual({
+      packageName: 'test-package',
+      packageVersion: '1.0.0'
+    })
+  })
+
+  test('should throw error when package time information is missing', async () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({})
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow('could not determine package version information')
+  })
+
+  test('should throw error when version release date is missing', async () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '2.0.0': new Date().toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow('could not determine release date for version 1.0.0')
+  })
+
+  test('should handle version aliases correctly', async () => {
+    const now = new Date()
+    const daysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000) // 2 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.2.3': daysAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: (packageName, packageVersion) => {
+          if (packageVersion === 'latest') {
+            return Promise.resolve('1.2.3')
+          }
+          return Promise.resolve(packageVersion)
+        }
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: 'latest'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 2 days ago) - consider waiting for community review'
+    )
+  })
+})

package/lib/marshalls/typosquatting.marshall.js

@@ -41,9 +41,11 @@ class Marshall extends BaseMarshall {
       }
 
       if (similarPackages.length > 0) {
+        // Remove duplicates from similarPackages array
+        const uniqueSimilarPackages = [...new Set(similarPackages)]
         return reject(
           new Error(
-            `Package name could be a typosquatting attempt for popular package(s): ${similarPackages.join(
+            `Package name could be a typosquatting attempt for popular package(s): ${uniqueSimilarPackages.join(
               ', '
             )}`
           )

package/lib/marshalls/version-maturity.marshall.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const BaseMarshall = require('./baseMarshall')
+const { marshallCategories } = require('./constants')
+
+const MARSHALL_NAME = 'version_maturity'
+const VERSION_AGE_THRESHOLD = 7 // specified in days
+
+class Marshall extends BaseMarshall {
+  constructor(options) {
+    super(options)
+    this.name = MARSHALL_NAME
+    this.categoryId = marshallCategories.PackageHealth.id
+  }
+
+  title() {
+    return 'Checking version maturity'
+  }
+
+  validate(pkg) {
+    let packageData = null
+    return this.packageRepoUtils
+      .getPackageInfo(pkg.packageName)
+      .then((data) => {
+        if (data && data.time) {
+          packageData = data
+          return pkg
+        } else {
+          throw new Error('could not determine package version information')
+        }
+      })
+      .then((pkg) => {
+        return this.packageRepoUtils.getSemVer(pkg.packageName, pkg.packageVersion)
+      })
+      .then((versionResolved) => {
+        const versionReleaseDate = packageData.time[versionResolved]
+
+        if (!versionReleaseDate) {
+          throw new Error(`could not determine release date for version ${versionResolved}`)
+        }
+
+        const versionDateDiff = new Date() - new Date(versionReleaseDate)
+        const versionDateDiffInDays = Math.round(versionDateDiff / (1000 * 60 * 60 * 24))
+
+        if (versionDateDiffInDays < VERSION_AGE_THRESHOLD) {
+          let timeAgoText = 'days'
+          let timeAgoNumber = versionDateDiffInDays
+
+          if (versionDateDiffInDays === 0) {
+            timeAgoText = 'hours'
+            const versionDateDiffInHours = Math.round(versionDateDiff / (1000 * 60 * 60))
+            timeAgoNumber = versionDateDiffInHours
+          } else if (versionDateDiffInDays === 1) {
+            timeAgoText = 'day'
+          }
+
+          throw new Error(
+            `detected a recently published version (published ${timeAgoNumber} ${timeAgoText} ago) - consider waiting for community review`
+          )
+        }
+
+        return pkg
+      })
+  }
+}
+
+module.exports = Marshall

package/package.json

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