@socketsecurity/lib 5.16.0 → 5.18.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.18.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.0) - 2026-04-14
+
+### Added — dlx
+
+- Socket Firewall API check before package downloads — resolves dependency tree via `buildIdealTree`, checks all packages against `firewall-api.socket.dev/purl` in parallel, blocks on critical/high severity alerts
+
+### Changed — http-request
+
+- Default `User-Agent` header updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
+
+## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
+
+### Added — paths
+
+- `isUnixPath()` — detect MSYS/Git Bash drive letter notation (`/c/...`)
+
+### Changed — paths
+
+- `normalizePath()` now converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `fromUnixPath()` now produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
+
 ## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
 
 ### Added — paths

package/dist/constants/socket.d.ts

@@ -30,6 +30,11 @@ export declare const SOCKET_DLX_APP_NAME = "dlx";
 export declare const SOCKET_FIREWALL_APP_NAME = "sfw";
 export declare const SOCKET_REGISTRY_APP_NAME = "registry";
 export declare const SOCKET_APP_PREFIX = "_";
+// Socket.dev lib.
+export declare const SOCKET_LIB_NAME = "@socketsecurity/lib";
+export declare const SOCKET_LIB_VERSION: string;
+export declare const SOCKET_LIB_URL = "https://github.com/SocketDev/socket-lib";
+export declare const SOCKET_LIB_USER_AGENT: string;
 // Socket.dev IPC.
 export declare const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";
 // Socket.dev cache and registry.

package/dist/constants/socket.js

@@ -34,6 +34,10 @@ __export(socket_exports, {
   SOCKET_FIREWALL_APP_NAME: () => SOCKET_FIREWALL_APP_NAME,
   SOCKET_GITHUB_ORG: () => SOCKET_GITHUB_ORG,
   SOCKET_IPC_HANDSHAKE: () => SOCKET_IPC_HANDSHAKE,
+  SOCKET_LIB_NAME: () => SOCKET_LIB_NAME,
+  SOCKET_LIB_URL: () => SOCKET_LIB_URL,
+  SOCKET_LIB_USER_AGENT: () => SOCKET_LIB_USER_AGENT,
+  SOCKET_LIB_VERSION: () => SOCKET_LIB_VERSION,
   SOCKET_OVERRIDE_SCOPE: () => SOCKET_OVERRIDE_SCOPE,
   SOCKET_PRICING_URL: () => SOCKET_PRICING_URL,
   SOCKET_PUBLIC_API_KEY: () => SOCKET_PUBLIC_API_KEY,
@@ -71,6 +75,10 @@ const SOCKET_DLX_APP_NAME = "dlx";
 const SOCKET_FIREWALL_APP_NAME = "sfw";
 const SOCKET_REGISTRY_APP_NAME = "registry";
 const SOCKET_APP_PREFIX = "_";
+const SOCKET_LIB_NAME = "@socketsecurity/lib";
+const SOCKET_LIB_VERSION = "5.18.0";
+const SOCKET_LIB_URL = "https://github.com/SocketDev/socket-lib";
+const SOCKET_LIB_USER_AGENT = `socketsecurity-lib/${SOCKET_LIB_VERSION} (${SOCKET_LIB_URL})`;
 const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";
 const CACHE_SOCKET_API_DIR = "socket-api";
 const REGISTRY = "registry";
@@ -92,6 +100,10 @@ const REGISTRY_SCOPE_DELIMITER = "__";
   SOCKET_FIREWALL_APP_NAME,
   SOCKET_GITHUB_ORG,
   SOCKET_IPC_HANDSHAKE,
+  SOCKET_LIB_NAME,
+  SOCKET_LIB_URL,
+  SOCKET_LIB_USER_AGENT,
+  SOCKET_LIB_VERSION,
   SOCKET_OVERRIDE_SCOPE,
   SOCKET_PRICING_URL,
   SOCKET_PUBLIC_API_KEY,

package/dist/dlx/package.d.ts

@@ -181,6 +181,14 @@ export declare function findBinaryPath(packageDir: string, packageName: string,
  * ```
  */
 export declare function makePackageBinsExecutable(packageDir: string, packageName: string): void;
+/**
+ * Build a PURL string for an npm package.
+ * Follows the PURL spec for the npm type:
+ *   - Scoped: `@scope/pkg` → `pkg:npm/%40scope/pkg@version`
+ *   - Unscoped: `pkg` → `pkg:npm/pkg@version`
+ *
+ */
+export declare function npmPurl(name: string, version: string): string;
 /**
  * Parse package spec into name and version using npm-package-arg.
  * Examples:

package/dist/dlx/package.js

@@ -35,18 +35,21 @@ __export(package_exports, {
   executePackage: () => executePackage,
   findBinaryPath: () => findBinaryPath,
   makePackageBinsExecutable: () => makePackageBinsExecutable,
+  npmPurl: () => npmPurl,
   parsePackageSpec: () => parsePackageSpec,
   resolveBinaryPath: () => resolveBinaryPath
 });
 module.exports = __toCommonJS(package_exports);
 var import_platform = require("../constants/platform");
+var import_socket = require("../constants/socket");
 var import_cache = require("./cache");
 var import_arborist = __toESM(require("../external/@npmcli/arborist"));
 var import_libnpmexec = __toESM(require("../external/libnpmexec"));
 var import_npm_package_arg = __toESM(require("../external/npm-package-arg"));
 var import_fs = require("../fs");
+var import_http_request = require("../http-request");
 var import_normalize = require("../paths/normalize");
-var import_socket = require("../paths/socket");
+var import_socket2 = require("../paths/socket");
 var import_process_lock = require("../process-lock");
 var import_spawn = require("../spawn");
 let _fs;
@@ -110,7 +113,7 @@ async function ensurePackageInstalled(packageName, packageSpec, force) {
   const fs = /* @__PURE__ */ getFs();
   const path = /* @__PURE__ */ getPath();
   const cacheKey = (0, import_cache.generateCacheKey)(packageSpec);
-  const packageDir = (0, import_normalize.normalizePath)(path.join((0, import_socket.getSocketDlxDir)(), cacheKey));
+  const packageDir = (0, import_normalize.normalizePath)(path.join((0, import_socket2.getSocketDlxDir)(), cacheKey));
   const installedDir = (0, import_normalize.normalizePath)(
     path.join(packageDir, "node_modules", packageName)
   );
@@ -150,7 +153,7 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
         const arb = new import_arborist.default({
           path: packageDir,
           // Use Socket's shared cacache directory (~/.socket/_cacache).
-          cache: (0, import_socket.getSocketCacacheDir)(),
+          cache: (0, import_socket2.getSocketCacacheDir)(),
           // Skip devDependencies (production-only like npx).
           omit: ["dev"],
           // Security: Skip install/preinstall/postinstall scripts to prevent arbitrary code execution.
@@ -164,8 +167,13 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
           // Suppress output (unneeded for ephemeral dlx installs).
           silent: true
         });
-        await arb.reify({ save: true, add: [packageSpec] });
+        await arb.buildIdealTree({ add: [packageSpec] });
+        await checkFirewallPurls(arb, packageName);
+        await arb.reify({ save: true });
       } catch (e) {
+        if (e instanceof Error && e.message.startsWith("Socket Firewall blocked")) {
+          throw e;
+        }
         const code = e.code;
         if (code === "E404" || code === "ETARGET") {
           throw new Error(
@@ -295,6 +303,76 @@ function makePackageBinsExecutable(packageDir, packageName) {
   } catch {
   }
 }
+const FIREWALL_API_URL = "https://firewall-api.socket.dev/purl";
+const FIREWALL_TIMEOUT = 1e4;
+const FIREWALL_BLOCK_SEVERITIES = /* @__PURE__ */ new Set([
+  "critical",
+  "high"
+]);
+function npmPurl(name, version) {
+  const encoded = name.startsWith("@") ? `%40${name.slice(1)}` : name;
+  const encodedVersion = version.replace(/\+/g, "%2B");
+  return `pkg:npm/${encoded}@${encodedVersion}`;
+}
+async function checkFirewallPurls(arb, requestedPackage) {
+  const idealTree = arb.idealTree;
+  if (!idealTree) {
+    return;
+  }
+  const purls = [];
+  for (const node of idealTree.inventory.values()) {
+    if (node.isProjectRoot) {
+      continue;
+    }
+    const { name, version } = node.package;
+    if (!name || !version) {
+      continue;
+    }
+    purls.push({ purl: npmPurl(name, version), name, version });
+  }
+  if (purls.length === 0) {
+    return;
+  }
+  const blocked = [];
+  await Promise.allSettled(
+    purls.map(async ({ name, purl, version }) => {
+      try {
+        const data = await (0, import_http_request.httpJson)(
+          `${FIREWALL_API_URL}/${encodeURIComponent(purl)}`,
+          {
+            headers: { "User-Agent": import_socket.SOCKET_LIB_USER_AGENT },
+            timeout: FIREWALL_TIMEOUT,
+            retries: 1,
+            retryDelay: 500
+          }
+        );
+        const blocking = (data.alerts ?? []).filter(
+          (a) => a.severity && FIREWALL_BLOCK_SEVERITIES.has(a.severity)
+        );
+        if (blocking.length > 0) {
+          blocked.push({
+            name,
+            version,
+            alerts: blocking.map(
+              (a) => `${a.severity}: ${a.type ?? a.key ?? "unknown"}`
+            )
+          });
+        }
+      } catch {
+      }
+    })
+  );
+  if (blocked.length > 0) {
+    const details = blocked.map((b) => `  ${b.name}@${b.version}: ${b.alerts.join(", ")}`).join("\n");
+    throw new Error(
+      `Socket Firewall blocked installation of "${requestedPackage}".
+The following dependencies have security alerts:
+${details}
+
+Visit https://socket.dev for more information.`
+    );
+  }
+}
 function parsePackageSpec(spec) {
   try {
     const parsed = (0, import_npm_package_arg.default)(spec);
@@ -345,6 +423,7 @@ function resolveBinaryPath(basePath) {
   executePackage,
   findBinaryPath,
   makePackageBinsExecutable,
+  npmPurl,
   parsePackageSpec,
   resolveBinaryPath
 });

package/dist/http-request.js

@@ -32,6 +32,7 @@ __export(http_request_exports, {
   sanitizeHeaders: () => sanitizeHeaders
 });
 module.exports = __toCommonJS(http_request_exports);
+var import_socket = require("./constants/socket");
 var import_fs = require("./fs.js");
 let _fs;
 // @__NO_SIDE_EFFECTS__
@@ -287,7 +288,7 @@ async function httpRequestAttempt(url, options) {
   const startTime = Date.now();
   const streamHeaders = body && typeof body === "object" && "getHeaders" in body && typeof body.getHeaders === "function" ? body.getHeaders() : void 0;
   const mergedHeaders = {
-    "User-Agent": "socket-registry/1.0",
+    "User-Agent": import_socket.SOCKET_LIB_USER_AGENT,
     ...streamHeaders,
     ...headers
   };

package/dist/paths/normalize.d.ts

@@ -142,43 +142,70 @@ export declare function isPath(pathLike: string | Buffer | URL): boolean;
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isRelative(pathLike: string | Buffer | URL): boolean;
 /**
- * Convert Unix-style POSIX paths (MSYS/Git Bash format) back to native Windows paths.
+ * Check if a path uses MSYS/Git Bash Unix-style drive letter notation.
  *
- * This is the inverse of {@link toUnixPath}. MSYS-style paths use `/c/` notation
- * for drive letters, which PowerShell and cmd.exe cannot resolve. This function
- * converts them back to native Windows format.
+ * Detects paths in the format `/c/...` where a single letter after the leading
+ * slash represents a Windows drive letter. These paths are produced by MSYS2,
+ * Git Bash, and `command -v` on Windows.
+ *
+ * Detection rules:
+ * - Must start with `/` followed by a single ASCII letter (a-z, A-Z)
+ * - The letter must be followed by `/` or be at the end of the string
+ * - Examples: `/c/tools/bin`, `/d/projects`, `/c`
+ * - Non-matches: `/tmp`, `/usr/local`, `C:/Windows`
+ *
+ * @param {string | Buffer | URL} pathLike - The path to check
+ * @returns {boolean} `true` if the path uses MSYS drive letter notation
+ *
+ * @example
+ * ```typescript
+ * // MSYS drive letter paths
+ * isUnixPath('/c/tools/bin')         // true
+ * isUnixPath('/d/projects/app')       // true
+ * isUnixPath('/c')                    // true
+ * isUnixPath('/C/Windows')            // true
+ *
+ * // Not MSYS drive paths
+ * isUnixPath('/tmp/build')            // false
+ * isUnixPath('/usr/local/bin')        // false
+ * isUnixPath('C:/Windows')            // false
+ * isUnixPath('./relative')            // false
+ * isUnixPath('')                      // false
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isUnixPath(pathLike: string | Buffer | URL): boolean;
+/**
+ * Convert Unix-style POSIX paths to native Windows paths.
+ *
+ * This is the inverse of {@link toUnixPath}. On Windows, MSYS-style paths use
+ * `/c/` notation for drive letters and forward slashes, which PowerShell and
+ * cmd.exe cannot resolve. This function converts them to native Windows format
+ * with backslashes and proper drive letters.
  *
  * Conversion rules:
- * - On Windows: Converts Unix drive notation to Windows drive letters
- *   - `/c/path/to/file` becomes `C:/path/to/file`
- *   - `/d/projects/app` becomes `D:/projects/app`
+ * - On Windows: Converts drive notation and separators to native format
+ *   - `/c/path/to/file` becomes `C:\path\to\file`
+ *   - `/d/projects/app` becomes `D:\projects\app`
+ *   - Forward slashes become backslashes
  *   - Drive letters are always uppercase in the output
- * - On Unix: Returns the path unchanged (passes through normalization)
- *
- * This is particularly important for:
- * - GitHub Actions runners where `command -v` returns MSYS paths
- * - Tools like sfw that need to resolve real binary paths on Windows
- * - Scripts that receive paths from Git Bash but need to pass them to native Windows tools
+ * - On Unix: Returns the normalized path unchanged (forward slashes preserved)
  *
  * @param {string | Buffer | URL} pathLike - The MSYS/Unix-style path to convert
- * @returns {string} Native Windows path (e.g., `C:/path/to/file`) or normalized Unix path
+ * @returns {string} Native Windows path (e.g., `C:\path\to\file`) or normalized Unix path
  *
  * @example
  * ```typescript
- * // MSYS drive letter paths
- * fromUnixPath('/c/projects/app/file.txt')    // 'C:/projects/app/file.txt'
- * fromUnixPath('/d/projects/foo/bar')         // 'D:/projects/foo/bar'
+ * // MSYS drive letter paths (Windows)
+ * fromUnixPath('/c/projects/app/file.txt')    // 'C:\\projects\\app\\file.txt'
+ * fromUnixPath('/d/projects/foo/bar')         // 'D:\\projects\\foo\\bar'
+ * fromUnixPath('/c')                          // 'C:\\'
  *
- * // Non-drive Unix paths (unchanged)
- * fromUnixPath('/tmp/build/output')           // '/tmp/build/output'
- * fromUnixPath('/usr/local/bin')              // '/usr/local/bin'
- *
- * // Already Windows paths (unchanged)
- * fromUnixPath('C:/Windows/System32')         // 'C:/Windows/System32'
+ * // Forward-slash paths (Windows)
+ * fromUnixPath('C:/Windows/System32')         // 'C:\\Windows\\System32'
  *
- * // Edge cases
- * fromUnixPath('/c')                          // 'C:/'
- * fromUnixPath('')                            // '.'
+ * // Unix (unchanged, forward slashes preserved)
+ * fromUnixPath('/tmp/build/output')           // '/tmp/build/output'
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
@@ -196,6 +223,7 @@ export declare function fromUnixPath(pathLike: string | Buffer | URL): string;
  * - Returns `.` for empty or collapsed paths
  *
  * Special handling:
+ * - MSYS drive letters (Windows only): `/c/path` becomes `C:/path`
  * - UNC paths: Maintains double leading slashes for `//server/share` format
  * - Windows namespaces: Preserves `//./` and `//?/` prefixes
  * - Leading `..` segments: Preserved in relative paths without prefix
@@ -222,6 +250,10 @@ export declare function fromUnixPath(pathLike: string | Buffer | URL): string;
  * normalizePath('C:\\Users\\username\\file.txt') // 'C:/Users/username/file.txt'
  * normalizePath('foo\\bar\\baz')                 // 'foo/bar/baz'
  *
+ * // MSYS drive letters (Windows only)
+ * normalizePath('/c/projects/app')              // 'C:/projects/app' (on Windows)
+ * normalizePath('/d/tools/bin')                 // 'D:/tools/bin' (on Windows)
+ *
  * // UNC paths
  * normalizePath('\\\\server\\share\\file')   // '//server/share/file'
  *

package/dist/paths/normalize.js

@@ -24,6 +24,7 @@ __export(normalize_exports, {
   isNodeModules: () => isNodeModules,
   isPath: () => isPath,
   isRelative: () => isRelative,
+  isUnixPath: () => isUnixPath,
   normalizePath: () => normalizePath,
   pathLikeToString: () => pathLikeToString,
   relativeResolve: () => relativeResolve,
@@ -41,6 +42,7 @@ const CHAR_LOWERCASE_A = 97;
 const CHAR_LOWERCASE_Z = 122;
 const CHAR_UPPERCASE_A = 65;
 const CHAR_UPPERCASE_Z = 90;
+const msysDriveRegExp = /^\/([a-zA-Z])(\/|$)/;
 const slashRegExp = /[/\\]/;
 const nodeModulesPathRegExp = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
 // @__NO_SIDE_EFFECTS__
@@ -67,6 +69,15 @@ function getUrl() {
   }
   return _url;
 }
+function msysDriveToNative(normalized) {
+  if (import_platform.WIN32) {
+    return normalized.replace(
+      msysDriveRegExp,
+      (_, letter, sep) => `${letter.toUpperCase()}:${sep || "/"}`
+    );
+  }
+  return normalized;
+}
 // @__NO_SIDE_EFFECTS__
 function isNodeModules(pathLike) {
   const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
@@ -131,13 +142,15 @@ function isRelative(pathLike) {
   return !/* @__PURE__ */ isAbsolute(filepath);
 }
 // @__NO_SIDE_EFFECTS__
+function isUnixPath(pathLike) {
+  const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
+  return typeof filepath === "string" && msysDriveRegExp.test(filepath);
+}
+// @__NO_SIDE_EFFECTS__
 function fromUnixPath(pathLike) {
   const normalized = /* @__PURE__ */ normalizePath(pathLike);
   if (import_platform.WIN32) {
-    return normalized.replace(
-      /^\/([a-zA-Z])(\/|$)/,
-      (_, letter, sep) => `${letter.toUpperCase()}:${sep || "/"}`
-    );
+    return normalized.replace(/\//g, "\\");
   }
   return normalized;
 }
@@ -219,7 +232,7 @@ function normalizePath(pathLike) {
     if (segment === "..") {
       return prefix ? prefix.slice(0, -1) || "/" : "..";
     }
-    return prefix + segment;
+    return msysDriveToNative(prefix + segment);
   }
   let collapsed = "";
   let segmentCount = 0;
@@ -300,7 +313,7 @@ function normalizePath(pathLike) {
   if (collapsed.length === 0) {
     return prefix || ".";
   }
-  return prefix + collapsed;
+  return msysDriveToNative(prefix + collapsed);
 }
 // @__NO_SIDE_EFFECTS__
 function pathLikeToString(pathLike) {
@@ -465,6 +478,7 @@ function toUnixPath(pathLike) {
   isNodeModules,
   isPath,
   isRelative,
+  isUnixPath,
   normalizePath,
   pathLikeToString,
   relativeResolve,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.16.0",
+  "version": "5.18.0",
   "packageManager": "pnpm@11.0.0-rc.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -737,7 +737,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.4.1",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.15.0",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.17.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",