npq 3.15.3 → 3.16.0

package/README.md

@@ -7,6 +7,16 @@ npq allows you to audit npm packages _before_ you install them
 [![Known Vulnerabilities](https://snyk.io/test/github/lirantal/npq/badge.svg)](https://snyk.io/test/github/lirantal/npq)
 [![Security Responsible Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow)](SECURITY.md)
 
+TL;DR how to use npq:
+
+```sh
+$ npx npq install express --dry-run
+```
+
+_What it does: the `npx` tool downloads and execute `npq` package, runs an install check for the `express` package and `--dry-run` means npq exists regardless of success/errors_.
+
+Here's a screenshot of npq in action:
+
 ![npq demo screenshot](.github/npq.png)
 
 Media coverage about npq:
@@ -133,7 +143,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | 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.
-| deprecation | Will show a warning if the package version being installed is deprecated. | Helps identify packages that are no longer maintained or recommended for use.
+| deprecation | Will show a warning if the package version is deprecated on npm or if its GitHub repository has been archived. | Helps identify packages that are no longer maintained or recommended for use. Set `GITHUB_TOKEN` environment variable for higher GitHub API rate limits.
 
 ### Disabling Marshalls
 

package/lib/helpers/packageRepoUtils.js

@@ -93,6 +93,85 @@ class PackageRepoUtils {
       throw new Error(`Could not find dist-tag ${packageVersion} for package ${packageName}`)
     }
   }
+
+  /**
+   * Extract GitHub owner and repo from a repository URL
+   * @param {string} repoUrl - Repository URL (e.g., "git+https://github.com/owner/repo.git")
+   * @returns {{owner: string, repo: string} | null} - Owner and repo, or null if not a GitHub URL
+   */
+  extractGitHubRepoFromUrl(repoUrl) {
+    if (!repoUrl || typeof repoUrl !== 'string') {
+      return null
+    }
+
+    // Match GitHub URLs in various formats:
+    // - git+https://github.com/owner/repo.git
+    // - https://github.com/owner/repo.git
+    // - https://github.com/owner/repo
+    // - git://github.com/owner/repo.git
+    // - git@github.com:owner/repo.git
+    const httpsPattern = /github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i
+    const match = repoUrl.match(httpsPattern)
+
+    if (match) {
+      return {
+        owner: match[1],
+        repo: match[2]
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Check if a GitHub repository is archived
+   * @param {string} owner - Repository owner
+   * @param {string} repo - Repository name
+   * @returns {Promise<boolean>} - True if archived, false otherwise
+   * @throws {Error} - On rate limit or API errors
+   */
+  async isGitHubRepoArchived(owner, repo) {
+    const headers = {
+      Accept: 'application/vnd.github.v3+json',
+      'User-Agent': 'npq-package-checker'
+    }
+
+    // Use GITHUB_TOKEN if available for higher rate limits
+    if (process.env.GITHUB_TOKEN) {
+      headers.Authorization = `token ${process.env.GITHUB_TOKEN}`
+    }
+
+    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+      headers
+    })
+
+    if (response.status === 403) {
+      const rateLimitRemaining = response.headers.get('x-ratelimit-remaining')
+      if (rateLimitRemaining === '0') {
+        throw new Error(
+          'GitHub API rate limit exceeded - deprecation marshall could not evaluate repository archive status. ' +
+            'Set GITHUB_TOKEN environment variable for higher rate limits.'
+        )
+      }
+      throw new Error(
+        `GitHub API access forbidden for ${owner}/${repo} - deprecation marshall could not evaluate repository archive status`
+      )
+    }
+
+    if (response.status === 404) {
+      // Repository doesn't exist or is private - can't determine archive status
+      return false
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `GitHub API error (${response.status}) - deprecation marshall could not evaluate repository archive status`
+      )
+    }
+
+    const data = await response.json()
+    return data.archived === true
+  }
 }
 
 module.exports = PackageRepoUtils

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/lib/marshalls/deprecation.marshall.js

@@ -42,6 +42,38 @@ class Marshall extends BaseMarshall {
     if (packageDeprecated) {
       throw new Error(`Package deprecated: ${packageDeprecated}`)
     }
+
+    // Check if the GitHub repository is archived
+    await this.checkGitHubRepoArchived(data)
+  }
+
+  /**
+   * Check if the package's GitHub repository is archived
+   * @param {object} data - Package data from npm registry
+   * @throws {Error} - If repository is archived or on API rate limit
+   */
+  async checkGitHubRepoArchived(data) {
+    const repoUrl = data.repository?.url
+
+    if (!repoUrl) {
+      return
+    }
+
+    const githubRepo = this.packageRepoUtils.extractGitHubRepoFromUrl(repoUrl)
+
+    if (!githubRepo) {
+      // @TODO: Add support for GitLab and Bitbucket repository archive detection
+      return
+    }
+
+    const isArchived = await this.packageRepoUtils.isGitHubRepoArchived(
+      githubRepo.owner,
+      githubRepo.repo
+    )
+
+    if (isArchived) {
+      throw new Error('Package repository has been archived on GitHub')
+    }
   }
 }
 

package/package.json

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