@aikidosec/safe-chain 1.1.6 → 1.1.8

package/README.md

@@ -1,12 +1,10 @@
 # Aikido Safe Chain
 
-The Aikido Safe Chain **prevents developers from installing malware** on their workstations through npm, npx, yarn, pnpm, pnpx, bun, and bunx. It's **free** to use and does not require any token.
+The Aikido Safe Chain **prevents developers from installing malware** on their workstations while developing in the Javascript ecosystem (through npm, npx, yarn, pnpm, pnpx, bun and bunx). It's **free** to use and does not require any token.
 
-The Aikido Safe Chain wraps around the [npm cli](https://github.com/npm/cli), [npx](https://github.com/npm/cli/blob/latest/docs/content/commands/npx.md), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), [pnpx](https://pnpm.io/cli/dlx), [bun](https://bun.sh/), and [bunx](https://bun.sh/docs/cli/bunx) to provide extra checks before installing new packages. This tool will detect when a package contains malware and prompt you to exit, preventing npm, npx, yarn, pnpm, pnpx, bun, or bunx from downloading or running the malware.
+The Aikido Safe Chain wraps around the [npm cli](https://github.com/npm/cli), [npx](https://github.com/npm/cli/blob/latest/docs/content/commands/npx.md), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), [pnpx](https://pnpm.io/cli/dlx), [bun](https://bun.sh/), [bunx](https://bun.sh/docs/cli/bunx), and [pip](https://pip.pypa.io/) to provide extra checks before installing new packages. This tool will detect when a package contains malware and prompt you to exit, preventing npm, npx, yarn, pnpm, pnpx, bun, bunx, or pip/pip3 from downloading or running the malware.
 
-![demo](./docs/safe-package-manager-demo.png)
-
-Aikido Safe Chain works on Node.js version 18 and above and supports the following package managers:
+Aikido Safe Chain works on Node.js version 16 and above and supports the following package managers:
 
 - ✅ **npm**
 - ✅ **npx**
@@ -15,6 +13,8 @@ Aikido Safe Chain works on Node.js version 18 and above and supports the followi
 - ✅ **pnpx**
 - ✅ **bun**
 - ✅ **bunx**
+- ✅ **pip** (beta)
+- ✅ **pip3** (beta)
 
 # Usage
 
@@ -27,18 +27,38 @@ Installing the Aikido Safe Chain is easy. You just need 3 simple steps:
    npm install -g @aikidosec/safe-chain
    ```
 2. **Setup the shell integration** by running:
+
    ```shell
    safe-chain setup
    ```
+
+   To enable Python (pip/pip3) support (beta), use the `--include-python` flag:
+
+   ```shell
+   safe-chain setup --include-python
+   ```
+
 3. **❗Restart your terminal** to start using the Aikido Safe Chain.
-   - This step is crucial as it ensures that the shell aliases for npm, npx, yarn, pnpm, pnpx, bun, and bunx are loaded correctly. If you do not restart your terminal, the aliases will not be available.
-4. **Verify the installation** by running:
+
+   - This step is crucial as it ensures that the shell aliases for npm, npx, yarn, pnpm, pnpx, bun, bunx, and pip/pip3 are loaded correctly. If you do not restart your terminal, the aliases will not be available.
+
+4. **Verify the installation** by running one of the following commands:
+
+   For JavaScript/Node.js:
+
    ```shell
    npm install safe-chain-test
    ```
-   - The output should show that Aikido Safe Chain is blocking the installation of this package as it is flagged as malware.
 
-When running `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, or `bunx` commands, the Aikido Safe Chain will automatically check for malware in the packages you are trying to install. If any malware is detected, it will prompt you to exit the command.
+   For Python (beta):
+
+   ```shell
+   pip3 install safe-chain-pi-test
+   ```
+
+   - The output should show that Aikido Safe Chain is blocking the installation of these test packages as they are flagged as malware.
+
+When running `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, or `pip3` commands, the Aikido Safe Chain will automatically check for malware in the packages you are trying to install. It also intercepts Python module invocations for pip when available (e.g., `python -m pip install ...`, `python3 -m pip download ...`). If any malware is detected, it will prompt you to exit the command.
 
 You can check the installed version by running:
 
@@ -48,9 +68,19 @@ safe-chain --version
 
 ## How it works
 
-The Aikido Safe Chain works by running a lightweight proxy server that intercepts package downloads from the npm registry. When you run npm, npx, yarn, pnpm, pnpx, bun, or bunx commands, all package downloads are routed through this local proxy, which verifies packages in real-time against **[Aikido Intel - Open Sources Threat Intelligence](https://intel.aikido.dev/?tab=malware)**. If malware is detected in any package (including deep dependencies), the proxy blocks the download before the malicious code reaches your machine.
+### Malware Blocking
+
+The Aikido Safe Chain works by running a lightweight proxy server that intercepts package downloads from the npm registry and PyPI. When you run npm, npx, yarn, pnpm, pnpx, bun, bunx, `pip`, or `pip3` commands, all package downloads are routed through this local proxy, which verifies packages in real-time against **[Aikido Intel - Open Sources Threat Intelligence](https://intel.aikido.dev/?tab=malware)**. If malware is detected in any package (including deep dependencies), the proxy blocks the download before the malicious code reaches your machine.
+
+### Minimum package age (npm only)
+
+For npm packages, Safe Chain temporarily suppresses packages published within the last 24 hours until they have been validated against malware. This provides an additional security layer during the critical period when newly published packages are most vulnerable to containing undetected threats. You can bypass this protection for specific installs using the `--safe-chain-skip-minimum-package-age` flag.
 
-The Aikido Safe Chain integrates with your shell to provide a seamless experience when using npm, npx, yarn, pnpm, pnpx, bun, and bunx commands. It sets up aliases for these commands so that they are wrapped by the Aikido Safe Chain commands, which manage the proxy server before executing the original commands. We currently support:
+⚠️ This feature **only applies to npm-based package managers** (npm, npx, yarn, pnpm, pnpx, bun, bunx) and does not apply to PyPI/pip.
+
+### Shell Integration
+
+The Aikido Safe Chain integrates with your shell to provide a seamless experience when using npm, npx, yarn, pnpm, pnpx, bun, bunx, and pip commands. It sets up aliases for these commands so that they are wrapped by the Aikido Safe Chain commands, which manage the proxy server before executing the original commands. We currently support:
 
 - ✅ **Bash**
 - ✅ **Zsh**
@@ -82,11 +112,19 @@ You can control the output from Aikido Safe Chain using the `--safe-chain-loggin
 
 - `--safe-chain-logging=silent` - Suppresses all Aikido Safe Chain output except when malware is blocked. The package manager output is written to stdout as normal, and Safe Chain only writes a short message if it has blocked malware and causes the process to exit.
 
-Example usage:
+  Example usage:
 
-```shell
-npm install express --safe-chain-logging=silent
-```
+  ```shell
+  npm install express --safe-chain-logging=silent
+  ```
+
+- `--safe-chain-logging=verbose` - Enables detailed diagnostic output from Aikido Safe Chain. Useful for troubleshooting issues or understanding what Safe Chain is doing behind the scenes.
+
+  Example usage:
+
+  ```shell
+  npm install express --safe-chain-logging=verbose
+  ```
 
 # Usage in CI/CD
 
@@ -102,6 +140,12 @@ To use Aikido Safe Chain in CI/CD environments, run the following command after
 safe-chain setup-ci
 ```
 
+To enable Python (pip/pip3) support (beta) in CI/CD, use the `--include-python` flag:
+
+```shell
+safe-chain setup-ci --include-python
+```
+
 This automatically configures your CI environment to use Aikido Safe Chain for all package manager commands.
 
 ## Supported Platforms

package/bin/aikido-bun.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "bun";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-bunx.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "bunx";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-npm.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "npm";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-npx.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "npx";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-pip.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { main } from "../src/main.js";
+import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_PY } from "../src/config/settings.js";
+import { setCurrentPipInvocation, PIP_INVOCATIONS, PIP_PACKAGE_MANAGER } from "../src/packagemanager/pip/pipSettings.js";
+
+// Set eco system
+setEcoSystem(ECOSYSTEM_PY);
+
+// Set current invocation
+setCurrentPipInvocation(PIP_INVOCATIONS.PIP);
+
+initializePackageManager(PIP_PACKAGE_MANAGER);
+
+// Pass through only user-supplied pip args
+var exitCode = await main(process.argv.slice(2));
+process.exit(exitCode);

package/bin/aikido-pip3.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { main } from "../src/main.js";
+import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_PY } from "../src/config/settings.js";
+import { setCurrentPipInvocation, PIP_INVOCATIONS, PIP_PACKAGE_MANAGER } from "../src/packagemanager/pip/pipSettings.js";
+
+// Set eco system
+setEcoSystem(ECOSYSTEM_PY);
+
+// Set current invocation
+setCurrentPipInvocation(PIP_INVOCATIONS.PIP3);
+
+// Create package manager
+initializePackageManager(PIP_PACKAGE_MANAGER);
+
+// Pass through only user-supplied pip args
+var exitCode = await main(process.argv.slice(2));
+process.exit(exitCode);

package/bin/aikido-pnpm.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "pnpm";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-pnpx.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "pnpx";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/aikido-python.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setCurrentPipInvocation, PIP_INVOCATIONS, PIP_PACKAGE_MANAGER } from "../src/packagemanager/pip/pipSettings.js";
+import { setEcoSystem, ECOSYSTEM_PY } from "../src/config/settings.js";
+import { main } from "../src/main.js";
+
+// Set eco system
+setEcoSystem(ECOSYSTEM_PY);
+
+// Strip nodejs and wrapper script from args
+let argv = process.argv.slice(2);
+
+if (argv[0] === '-m' && (argv[1] === 'pip' || argv[1] === 'pip3')) {
+	setEcoSystem(ECOSYSTEM_PY);
+	setCurrentPipInvocation(argv[1] === 'pip3' ? PIP_INVOCATIONS.PY_PIP3 : PIP_INVOCATIONS.PY_PIP);
+	initializePackageManager(PIP_PACKAGE_MANAGER);
+
+  // Strip off the '-m pip' or '-m pip3' from the args
+  argv = argv.slice(2);
+
+  var exitCode = await main(argv);
+	process.exit(exitCode);
+} else {
+	// Forward to real python binary for non-pip flows
+	const { spawn } = await import('child_process');
+	spawn('python', argv, { stdio: 'inherit' });
+}

package/bin/aikido-python3.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setCurrentPipInvocation, PIP_INVOCATIONS, PIP_PACKAGE_MANAGER } from "../src/packagemanager/pip/pipSettings.js";
+import { setEcoSystem, ECOSYSTEM_PY } from "../src/config/settings.js";
+import { main } from "../src/main.js";
+
+// Set eco system
+setEcoSystem(ECOSYSTEM_PY);
+
+// Strip nodejs and wrapper script from args
+let argv = process.argv.slice(2);
+
+if (argv[0] === '-m' && (argv[1] === 'pip' || argv[1] === 'pip3')) {
+	setEcoSystem(ECOSYSTEM_PY);
+	setCurrentPipInvocation(argv[1] === 'pip3' ? PIP_INVOCATIONS.PY3_PIP3 : PIP_INVOCATIONS.PY3_PIP);
+	initializePackageManager(PIP_PACKAGE_MANAGER);
+
+  // Strip off the '-m pip' or '-m pip3' from the args
+	argv = argv.slice(2);
+
+  var exitCode = await main(argv);
+	process.exit(exitCode);
+} else {
+	// Forward to real python3 binary for non-pip flows
+	const { spawn } = await import('child_process');
+	spawn('python3', argv, { stdio: 'inherit' });
+}

package/bin/aikido-yarn.js

@@ -2,7 +2,9 @@
 
 import { main } from "../src/main.js";
 import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_JS } from "../src/config/settings.js";
 
+setEcoSystem(ECOSYSTEM_JS);
 const packageManagerName = "yarn";
 initializePackageManager(packageManagerName);
 var exitCode = await main(process.argv.slice(2));

package/bin/safe-chain.js

@@ -6,6 +6,7 @@ import { ui } from "../src/environment/userInteraction.js";
 import { setup } from "../src/shell-integration/setup.js";
 import { teardown } from "../src/shell-integration/teardown.js";
 import { setupCi } from "../src/shell-integration/setup-ci.js";
+import { initializeCliArguments } from "../src/config/cliArguments.js";
 
 if (process.argv.length < 3) {
   ui.writeError("No command provided. Please provide a command to execute.");
@@ -14,6 +15,8 @@ if (process.argv.length < 3) {
   process.exit(1);
 }
 
+initializeCliArguments(process.argv);
+
 const command = process.argv[2];
 
 if (command === "help" || command === "--help" || command === "-h") {
@@ -54,7 +57,12 @@ function writeHelp() {
   ui.writeInformation(
     `- ${chalk.cyan(
       "safe-chain setup"
-    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun and bunx.`
+    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun, bunx, pip and pip3.`
+  );
+  ui.writeInformation(
+    `    ${chalk.yellow(
+      "--include-python"
+    )}: Experimental: include Python package managers (pip, pip3) in the setup.`
   );
   ui.writeInformation(
     `- ${chalk.cyan(
@@ -67,9 +75,14 @@ function writeHelp() {
     )}: This will setup safe-chain for CI environments by creating shims and modifying the PATH.`
   );
   ui.writeInformation(
-    `- ${chalk.cyan(
-      "safe-chain --version"
-    )} (or ${chalk.cyan("-v")}): Display the current version of safe-chain.`
+    `    ${chalk.yellow(
+      "--include-python"
+    )}: Experimental: include Python package managers (pip, pip3) in the setup.`
+  );
+  ui.writeInformation(
+    `- ${chalk.cyan("safe-chain --version")} (or ${chalk.cyan(
+      "-v"
+    )}): Display the current version of safe-chain.`
   );
   ui.emptyLine();
 }

package/docs/shell-integration.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The shell integration automatically wraps common package manager commands (`npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`) with Aikido's security scanning functionality. This is achieved by sourcing startup scripts that define shell functions to wrap these commands with their Aikido-protected equivalents.
+The shell integration automatically wraps common package manager commands (`npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`) with Aikido's security scanning functionality. It also intercepts Python module invocations for pip when available: `python -m pip`, `python -m pip3`, `python3 -m pip`, `python3 -m pip3`. This is achieved by sourcing startup scripts that define shell functions to wrap these commands with their Aikido-protected equivalents.
 
 ## Supported Shells
 
@@ -28,7 +28,8 @@ This command:
 
 - Copies necessary startup scripts to Safe Chain's installation directory (`~/.safe-chain/scripts`)
 - Detects all supported shells on your system
-- Sources each shell's startup file to add Safe Chain functions for `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, and `bunx`
+- Sources each shell's startup file to add Safe Chain functions for `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, and `pip3`
+- Adds lightweight interceptors so `python -m pip[...]` and `python3 -m pip[...]` route through Safe Chain when invoked by name
 
 ❗ After running this command, **you must restart your terminal** for the changes to take effect. This ensures that the startup scripts are sourced correctly.
 
@@ -77,7 +78,7 @@ The system modifies the following files to source Safe Chain startup scripts:
 This means the shell functions are working but the Aikido commands aren't installed or available in your PATH:
 
 - Make sure Aikido Safe Chain is properly installed on your system
-- Verify the `aikido-npm`, `aikido-npx`, `aikido-yarn`, `aikido-pnpm`, `aikido-pnpx`, `aikido-bun`, and `aikido-bunx` commands exist
+- Verify the `aikido-npm`, `aikido-npx`, `aikido-yarn`, `aikido-pnpm`, `aikido-pnpx`, `aikido-bun`, `aikido-bunx`, `aikido-pip`, and `aikido-pip3` commands exist
 - Check that these commands are in your system's PATH
 
 ### Manual Verification
@@ -120,4 +121,29 @@ npm() {
 }
 ```
 
-Repeat this pattern for `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, and `bunx` using their respective `aikido-*` commands. After adding these functions, restart your terminal to apply the changes.
+Repeat this pattern for `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, and `pip3` using their respective `aikido-*` commands. After adding these functions, restart your terminal to apply the changes.
+
+To intercept Python module invocations for pip without altering Python itself, you can add small forwarding functions:
+
+```bash
+# Example for Bash/Zsh
+python() {
+  if [[ "$1" == "-m" && "$2" == pip* ]]; then
+    local mod="$2"; shift 2
+    if [[ "$mod" == "pip3" ]]; then aikido-pip3 "$@"; else aikido-pip "$@"; fi
+  else
+    command python "$@"
+  fi
+}
+
+python3() {
+  if [[ "$1" == "-m" && "$2" == pip* ]]; then
+    local mod="$2"; shift 2
+    if [[ "$mod" == "pip3" ]]; then aikido-pip3 "$@"; else aikido-pip "$@"; fi
+  else
+    command python3 "$@"
+  fi
+}
+```
+
+Limitations: these only apply when invoking `python`/`python3` by name. Absolute paths (e.g., `/usr/bin/python -m pip`) bypass shell functions.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@aikidosec/safe-chain",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "scripts": {
     "test": "node --test --experimental-test-module-mocks 'src/**/*.spec.js'",
     "test:watch": "node --test --watch --experimental-test-module-mocks 'src/**/*.spec.js'",
-    "lint": "oxlint --deny-warnings"
+    "lint": "oxlint --deny-warnings",
+    "typecheck": "tsc --noEmit"
   },
   "bin": {
     "aikido-npm": "bin/aikido-npm.js",
@@ -14,6 +15,10 @@
     "aikido-pnpx": "bin/aikido-pnpx.js",
     "aikido-bun": "bin/aikido-bun.js",
     "aikido-bunx": "bin/aikido-bunx.js",
+    "aikido-pip": "bin/aikido-pip.js",
+    "aikido-pip3": "bin/aikido-pip3.js",
+    "aikido-python": "bin/aikido-python.js",
+    "aikido-python3": "bin/aikido-python3.js",
     "safe-chain": "bin/safe-chain.js"
   },
   "type": "module",
@@ -30,14 +35,25 @@
   "license": "AGPL-3.0-or-later",
   "description": "The Aikido Safe Chain wraps around the [npm cli](https://github.com/npm/cli), [npx](https://github.com/npm/cli/blob/latest/docs/content/commands/npx.md), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), [pnpx](https://pnpm.io/cli/dlx), [bun](https://bun.sh/), and [bunx](https://bun.sh/docs/cli/bunx) to provide extra checks before installing new packages. This tool will detect when a package contains malware and prompt you to exit, preventing npm, npx, yarn, pnpm, pnpx, bun, or bunx from downloading or running the malware.",
   "dependencies": {
+    "certifi": "^14.5.15",
     "chalk": "5.4.1",
     "https-proxy-agent": "7.0.6",
+    "ini": "^6.0.0",
     "make-fetch-happen": "14.0.3",
     "node-forge": "1.3.1",
     "npm-registry-fetch": "18.0.2",
     "ora": "8.2.0",
     "semver": "7.7.2"
   },
+  "devDependencies": {
+    "@types/ini": "^4.1.1",
+    "@types/make-fetch-happen": "^10.0.4",
+    "@types/node": "^18.19.130",
+    "@types/npm-registry-fetch": "^8.0.9",
+    "@types/semver": "^7.7.1",
+    "@types/node-forge": "^1.3.14",
+    "typescript": "^5.9.3"
+  },
   "main": "src/main.js",
   "bugs": {
     "url": "https://github.com/AikidoSec/safe-chain/issues"

package/src/api/aikido.js

@@ -1,12 +1,27 @@
 import fetch from "make-fetch-happen";
+import { getEcoSystem, ECOSYSTEM_JS, ECOSYSTEM_PY } from "../config/settings.js";
 
-const malwareDatabaseUrl =
-  "https://malware-list.aikido.dev/malware_predictions.json";
+const malwareDatabaseUrls = {
+  [ECOSYSTEM_JS]: "https://malware-list.aikido.dev/malware_predictions.json",
+  [ECOSYSTEM_PY]: "https://malware-list.aikido.dev/malware_pypi.json",
+};
 
+/**
+ * @typedef {Object} MalwarePackage
+ * @property {string} package_name
+ * @property {string} version
+ * @property {string} reason
+ */
+
+/**
+ * @returns {Promise<{malwareDatabase: MalwarePackage[], version: string | undefined}>}
+ */
 export async function fetchMalwareDatabase() {
+  const ecosystem = getEcoSystem();
+  const malwareDatabaseUrl = malwareDatabaseUrls[/** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)];
   const response = await fetch(malwareDatabaseUrl);
   if (!response.ok) {
-    throw new Error(`Error fetching malware database: ${response.statusText}`);
+    throw new Error(`Error fetching ${ecosystem} malware database: ${response.statusText}`);
   }
 
   try {
@@ -15,18 +30,24 @@ export async function fetchMalwareDatabase() {
       malwareDatabase: malwareDatabase,
       version: response.headers.get("etag") || undefined,
     };
-  } catch (error) {
+  } catch (/** @type {any} */ error) {
     throw new Error(`Error parsing malware database: ${error.message}`);
   }
 }
 
+/**
+ * @returns {Promise<string | undefined>}
+ */
 export async function fetchMalwareDatabaseVersion() {
+  const ecosystem = getEcoSystem();
+  const malwareDatabaseUrl = malwareDatabaseUrls[/** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)];
   const response = await fetch(malwareDatabaseUrl, {
     method: "HEAD",
   });
+
   if (!response.ok) {
     throw new Error(
-      `Error fetching malware database version: ${response.statusText}`
+      `Error fetching ${ecosystem} malware database version: ${response.statusText}`
     );
   }
   return response.headers.get("etag") || undefined;

package/src/api/npmApi.js

@@ -1,6 +1,11 @@
 import * as semver from "semver";
 import * as npmFetch from "npm-registry-fetch";
 
+/**
+ * @param {string} packageName
+ * @param {string | null} [versionRange]
+ * @returns {Promise<string | null>}
+ */
 export async function resolvePackageVersion(packageName, versionRange) {
   if (!versionRange) {
     versionRange = "latest";
@@ -11,7 +16,10 @@ export async function resolvePackageVersion(packageName, versionRange) {
     return versionRange;
   }
 
-  const packageInfo = await getPackageInfo(packageName);
+  const packageInfo = (
+    /** @type {{"dist-tags"?: Record<string, string>, versions?: Record<string, unknown>} | null} */
+    await getPackageInfo(packageName)
+  );
   if (!packageInfo) {
     // It is possible that no version is found (could be a private package, or a package that doesn't exist)
     // In this case, we return null to indicate that we couldn't resolve the version
@@ -19,7 +27,7 @@ export async function resolvePackageVersion(packageName, versionRange) {
   }
 
   const distTags = packageInfo["dist-tags"];
-  if (distTags && distTags[versionRange]) {
+  if (distTags && isDistTags(distTags) && distTags[versionRange]) {
     // If the version range is a dist-tag, return the version associated with that tag
     // e.g., "latest", "next", etc.
     return distTags[versionRange];
@@ -41,6 +49,19 @@ export async function resolvePackageVersion(packageName, versionRange) {
   return null;
 }
 
+/**
+ *
+ * @param {unknown} distTags
+ * @returns {distTags is Record<string, string>}
+ */
+function isDistTags(distTags) {
+  return typeof distTags === "object";
+}
+
+/**
+ * @param {string} packageName
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
 async function getPackageInfo(packageName) {
   try {
     return await npmFetch.json(packageName);