@socketsecurity/lib 5.17.0 → 5.18.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.17.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.16.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",