@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/dlx/detect.d.ts

@@ -1,18 +1,17 @@
 /**
- * @fileoverview Executable type detection for DLX and local filesystem paths.
- *
- * Provides utilities to detect whether a path is a Node.js package or native
- * binary executable. Supports both DLX cache paths and local filesystem paths.
- *
- * Key Functions:
- * - detectExecutableType: Generic entry point for any path
- * - detectDlxExecutableType: DLX cache specific detection
- * - detectLocalExecutableType: Local filesystem specific detection
- *
- * Detection Strategies:
- * - DLX cache: Check for node_modules/ directory
- * - Local paths: Check for package.json with bin field, then file extension
+ * @file Executable type detection for DLX and local filesystem paths. Provides
+ *   utilities to detect whether a path is a Node.js package or native binary
+ *   executable. Supports both DLX cache paths and local filesystem paths. Key
+ *   Functions:
+ *
+ *   - detectExecutableType: Generic entry point for any path
+ *   - detectDlxExecutableType: DLX cache specific detection
+ *   - detectLocalExecutableType: Local filesystem specific detection Detection
+ *     Strategies:
+ *   - DLX cache: Check for node_modules/ directory
+ *   - Local paths: Check for package.json with bin field, then file extension
  */
+export declare function packageJsonPathCacheSet(key: string, value: string | undefined): void;
 export type ExecutableType = 'package' | 'binary' | 'unknown';
 export interface ExecutableDetectionResult {
     type: ExecutableType;
@@ -21,94 +20,121 @@ export interface ExecutableDetectionResult {
     inDlxCache?: boolean;
 }
 /**
- * Detect executable type for paths in DLX cache.
- * Uses filesystem structure (node_modules/ presence).
+ * Find package.json in the directory containing the file or parent directories.
+ * Results are cached to avoid repeated directory traversal.
  *
- * @param filePath - Path within DLX cache (~/.socket/_dlx/)
- * @returns Detection result
+ * @private
+ *
+ * @param filePath - Path to search from.
+ *
+ * @returns Path to package.json if found, undefined otherwise
+ */
+export declare function findPackageJson(filePath: string): string | undefined;
+/**
+ * Read and parse package.json with caching. Results are cached to avoid
+ * repeated file reads.
+ *
+ * @private
+ *
+ * @param packageJsonPath - Path to package.json.
+ *
+ * @returns Parsed package.json or null if invalid
+ */
+export declare function readPackageJson(packageJsonPath: string): object | undefined;
+/**
+ * Detect executable type for paths in DLX cache. Uses filesystem structure
+ * (node_modules/ presence).
  *
  * @example
- * ```typescript
- * const result = detectDlxExecutableType('/tmp/.socket/_dlx/a1b2c3d4/tool')
- * console.log(result.type) // 'package' or 'binary'
- * ```
+ *   ;```typescript
+ *   const result = detectDlxExecutableType('/tmp/.socket/_dlx/a1b2c3d4/tool')
+ *   console.log(result.type) // 'package' or 'binary'
+ *   ```
+ *
+ * @param filePath - Path within DLX cache (~/.socket/_dlx/)
+ *
+ * @returns Detection result
  */
 export declare function detectDlxExecutableType(filePath: string): ExecutableDetectionResult;
 /**
- * Detect if a path is a Node.js package or native binary executable.
- * Works for both DLX cache paths and local filesystem paths.
+ * Detect if a path is a Node.js package or native binary executable. Works for
+ * both DLX cache paths and local filesystem paths.
+ *
+ * Detection strategy: 1. If in DLX cache: Use detectDlxExecutableType() 2.
+ * Otherwise: Use detectLocalExecutableType()
  *
- * Detection strategy:
- * 1. If in DLX cache: Use detectDlxExecutableType()
- * 2. Otherwise: Use detectLocalExecutableType()
+ * @example
+ *   ;```typescript
+ *   const result = detectExecutableType('/path/to/tool')
+ *   if (result.type === 'package') {
+ *     spawnNode([filePath, ...args])
+ *   } else {
+ *     spawn(filePath, args)
+ *   }
+ *   ```
  *
  * @param filePath - Path to executable (DLX cache or local filesystem)
- * @returns Detection result with type, method, and metadata
  *
- * @example
- * ```typescript
- * const result = detectExecutableType('/path/to/tool')
- * if (result.type === 'package') {
- *   spawnNode([filePath, ...args])
- * } else {
- *   spawn(filePath, args)
- * }
- * ```
+ * @returns Detection result with type, method, and metadata
  */
 export declare function detectExecutableType(filePath: string): ExecutableDetectionResult;
 /**
- * Detect executable type for local filesystem paths.
- * Uses package.json and file extension checks.
+ * Detect executable type for local filesystem paths. Uses package.json and file
+ * extension checks.
+ *
+ * @example
+ *   ;```typescript
+ *   const result = detectLocalExecutableType('/usr/local/bin/tool')
+ *   if (result.type === 'package') {
+ *     console.log('Node.js package at:', result.packageJsonPath)
+ *   }
+ *   ```
  *
  * @param filePath - Local filesystem path (not in DLX cache)
- * @returns Detection result
  *
- * @example
- * ```typescript
- * const result = detectLocalExecutableType('/usr/local/bin/tool')
- * if (result.type === 'package') {
- *   console.log('Node.js package at:', result.packageJsonPath)
- * }
- * ```
+ * @returns Detection result
  */
 export declare function detectLocalExecutableType(filePath: string): ExecutableDetectionResult;
 /**
  * Check if a file path indicates a Node.js script.
  *
- * @param filePath - Path to check
- * @returns True if file has .js, .mjs, or .cjs extension
- *
  * @example
- * ```typescript
- * isJsFilePath('index.js')   // true
- * isJsFilePath('lib.mjs')    // true
- * isJsFilePath('tool.exe')   // false
- * ```
+ *   ;```typescript
+ *   isJsFilePath('index.js') // true
+ *   isJsFilePath('lib.mjs') // true
+ *   isJsFilePath('tool.exe') // false
+ *   ```
+ *
+ * @param filePath - Path to check.
+ *
+ * @returns True if file has .js, .mjs, or .cjs extension
  */
 export declare function isJsFilePath(filePath: string): boolean;
 /**
  * Simplified helper: Is this a native binary executable?
  *
- * @param filePath - Path to check
- * @returns True if detected as native binary (not Node.js package)
- *
  * @example
- * ```typescript
- * isNativeBinary('/usr/local/bin/tool')    // true
- * isNativeBinary('/tmp/project/index.js')  // false
- * ```
+ *   ;```typescript
+ *   isNativeBinary('/usr/local/bin/tool') // true
+ *   isNativeBinary('/tmp/project/index.js') // false
+ *   ```
+ *
+ * @param filePath - Path to check.
+ *
+ * @returns True if detected as native binary (not Node.js package)
  */
 export declare function isNativeBinary(filePath: string): boolean;
 /**
  * Simplified helper: Is this a Node.js package?
  *
- * @param filePath - Path to check
- * @returns True if detected as Node.js package
- *
  * @example
- * ```typescript
- * isNodePackage('/tmp/project/index.js')   // true
- * isNodePackage('/usr/local/bin/tool')     // false
- * ```
+ *   ;```typescript
+ *   isNodePackage('/tmp/project/index.js') // true
+ *   isNodePackage('/usr/local/bin/tool') // false
+ *   ```
+ *
+ * @param filePath - Path to check.
+ *
+ * @returns True if detected as Node.js package
  */
 export declare function isNodePackage(filePath: string): boolean;

package/dist/dlx/detect.js

@@ -23,20 +23,25 @@ __export(detect_exports, {
   detectDlxExecutableType: () => detectDlxExecutableType,
   detectExecutableType: () => detectExecutableType,
   detectLocalExecutableType: () => detectLocalExecutableType,
+  findPackageJson: () => findPackageJson,
   isJsFilePath: () => isJsFilePath,
   isNativeBinary: () => isNativeBinary,
-  isNodePackage: () => isNodePackage
+  isNodePackage: () => isNodePackage,
+  packageJsonPathCacheSet: () => packageJsonPathCacheSet,
+  readPackageJson: () => readPackageJson
 });
 module.exports = __toCommonJS(detect_exports);
 var import_paths = require("./paths");
 var import_socket = require("../paths/socket");
-var import_primordials = require("../primordials");
-let _fs;
-let _path;
-const NODE_JS_EXTENSIONS = new import_primordials.SetCtor([".js", ".mjs", ".cjs"]);
+var import_date = require("../primordials/date");
+var import_json = require("../primordials/json");
+var import_map_set = require("../primordials/map-set");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+const NODE_JS_EXTENSIONS = new import_map_set.SetCtor([".js", ".mjs", ".cjs"]);
 const PACKAGE_JSON_PATH_CACHE_MAX_SIZE = 200;
 const PACKAGE_JSON_NEGATIVE_TTL_MS = 1e4;
-const packageJsonPathCache = new import_primordials.MapCtor();
+const packageJsonPathCache = new import_map_set.MapCtor();
 function packageJsonPathCacheSet(key, value) {
   if (packageJsonPathCache.has(key)) {
     packageJsonPathCache.delete(key);
@@ -48,15 +53,15 @@ function packageJsonPathCacheSet(key, value) {
   }
   packageJsonPathCache.set(key, { path: value, at: Date.now() });
 }
-const packageJsonContentCache = new import_primordials.MapCtor();
+const packageJsonContentCache = new import_map_set.MapCtor();
 function findPackageJson(filePath) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const startDir = path.dirname(path.resolve(filePath));
   const cached = packageJsonPathCache.get(startDir);
   if (cached !== void 0) {
-    if (cached.path === null) {
-      if ((0, import_primordials.DateNow)() - cached.at < PACKAGE_JSON_NEGATIVE_TTL_MS) {
+    if (cached.path === void 0) {
+      if ((0, import_date.DateNow)() - cached.at < PACKAGE_JSON_NEGATIVE_TTL_MS) {
         return void 0;
       }
       packageJsonPathCache.delete(startDir);
@@ -77,48 +82,37 @@ function findPackageJson(filePath) {
     }
     currentDir = path.dirname(currentDir);
   }
-  packageJsonPathCacheSet(startDir, null);
+  packageJsonPathCacheSet(startDir, void 0);
   return void 0;
 }
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
 function readPackageJson(packageJsonPath) {
-  const fs = /* @__PURE__ */ getFs();
+  const fs = (0, import_fs.getNodeFs)();
   let mtimeMs = 0;
   try {
     mtimeMs = fs.statSync(packageJsonPath).mtimeMs;
   } catch {
     packageJsonContentCache.delete(packageJsonPath);
-    return null;
+    return void 0;
   }
   const cached = packageJsonContentCache.get(packageJsonPath);
   if (cached !== void 0 && cached.mtimeMs === mtimeMs) {
     return cached.content;
   }
   try {
-    const content = (0, import_primordials.JSONParse)(fs.readFileSync(packageJsonPath, "utf8"));
+    const content = (0, import_json.JSONParse)(fs.readFileSync(packageJsonPath, "utf8"));
     packageJsonContentCache.set(packageJsonPath, { mtimeMs, content });
     return content;
   } catch {
-    packageJsonContentCache.set(packageJsonPath, { mtimeMs, content: null });
-    return null;
+    packageJsonContentCache.set(packageJsonPath, {
+      mtimeMs,
+      content: void 0
+    });
+    return void 0;
   }
 }
 function detectDlxExecutableType(filePath) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const dlxDir = (0, import_socket.getSocketDlxDir)();
   const absolutePath = path.resolve(filePath);
   const relativePath = path.relative(dlxDir, absolutePath);
@@ -170,7 +164,7 @@ function detectLocalExecutableType(filePath) {
   };
 }
 function isJsFilePath(filePath) {
-  const path = /* @__PURE__ */ getPath();
+  const path = (0, import_path.getNodePath)();
   const ext = path.extname(filePath).toLowerCase();
   return NODE_JS_EXTENSIONS.has(ext);
 }
@@ -185,7 +179,10 @@ function isNodePackage(filePath) {
   detectDlxExecutableType,
   detectExecutableType,
   detectLocalExecutableType,
+  findPackageJson,
   isJsFilePath,
   isNativeBinary,
-  isNodePackage
+  isNodePackage,
+  packageJsonPathCacheSet,
+  readPackageJson
 });

package/dist/dlx/dir.d.ts

@@ -1,48 +1,50 @@
-/** @fileoverview Directory management utilities for DLX installations. */
+/**
+ * @file Directory management utilities for DLX installations.
+ */
 /**
  * Clear all DLX package installations.
  *
  * @example
- * ```typescript
- * await clearDlx()
- * ```
+ *   ;```typescript
+ *   await clearDlx()
+ *   ```
  */
 export declare function clearDlx(): Promise<void>;
 /**
  * Clear all DLX package installations synchronously.
  *
  * @example
- * ```typescript
- * clearDlxSync()
- * ```
+ *   ;```typescript
+ *   clearDlxSync()
+ *   ```
  */
 export declare function clearDlxSync(): void;
 /**
  * Check if the DLX directory exists.
  *
  * @example
- * ```typescript
- * if (dlxDirExists()) {
- *   console.log('DLX directory is present')
- * }
- * ```
+ *   ;```typescript
+ *   if (dlxDirExists()) {
+ *     console.log('DLX directory is present')
+ *   }
+ *   ```
  */
 export declare function dlxDirExists(): boolean;
 /**
  * Ensure the DLX directory exists, creating it if necessary.
  *
  * @example
- * ```typescript
- * await ensureDlxDir()
- * ```
+ *   ;```typescript
+ *   await ensureDlxDir()
+ *   ```
  */
 export declare function ensureDlxDir(): Promise<void>;
 /**
  * Ensure the DLX directory exists synchronously, creating it if necessary.
  *
  * @example
- * ```typescript
- * ensureDlxDirSync()
- * ```
+ *   ;```typescript
+ *   ensureDlxDirSync()
+ *   ```
  */
 export declare function ensureDlxDirSync(): void;

package/dist/dlx/dir.js

@@ -27,21 +27,14 @@ __export(dir_exports, {
   ensureDlxDirSync: () => ensureDlxDirSync
 });
 module.exports = __toCommonJS(dir_exports);
-var import_fs = require("../fs");
+var import_safe = require("../fs/safe");
 var import_socket = require("../paths/socket");
-var import_promises = require("../promises");
+var import_iterate = require("../promises/iterate");
+var import_fs = require("../node/fs");
 var import_packages = require("./packages");
-let _fs;
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
 async function clearDlx() {
   const packages = await (0, import_packages.listDlxPackagesAsync)();
-  await (0, import_promises.pEach)(packages, (pkg) => (0, import_packages.removeDlxPackage)(pkg));
+  await (0, import_iterate.pEach)(packages, (pkg) => (0, import_packages.removeDlxPackage)(pkg));
 }
 function clearDlxSync() {
   const packages = (0, import_packages.listDlxPackages)();
@@ -50,14 +43,14 @@ function clearDlxSync() {
   }
 }
 function dlxDirExists() {
-  const fs = /* @__PURE__ */ getFs();
+  const fs = (0, import_fs.getNodeFs)();
   return fs.existsSync((0, import_socket.getSocketDlxDir)());
 }
 async function ensureDlxDir() {
-  await (0, import_fs.safeMkdir)((0, import_socket.getSocketDlxDir)());
+  await (0, import_safe.safeMkdir)((0, import_socket.getSocketDlxDir)());
 }
 function ensureDlxDirSync() {
-  (0, import_fs.safeMkdirSync)((0, import_socket.getSocketDlxDir)());
+  (0, import_safe.safeMkdirSync)((0, import_socket.getSocketDlxDir)());
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/dlx/firewall.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Socket Firewall integration for dlx installs.
+ *
+ *   - `npmPurl` — build a PURL string for an npm package
+ *   - `checkFirewallPurls` — scan an Arborist ideal tree against the public
+ *     Socket Firewall API; throws if any dep is critical/high Split out of
+ *     `dlx/package.ts` so the firewall logic + PURL helper can be reused by
+ *     other dlx flows without dragging in the install orchestrator.
+ */
+import Arborist from '../external/@npmcli/arborist';
+/**
+ * Check all resolved packages in an Arborist ideal tree against the Socket
+ * Firewall API (public, no auth required). Throws if any dependency has
+ * critical or high severity alerts.
+ *
+ * @private
+ *
+ * @param arb - Arborist instance with populated idealTree.
+ * @param requestedPackage - Top-level package name (for error messages)
+ */
+export declare function checkFirewallPurls(arb: InstanceType<typeof Arborist>, requestedPackage: string): Promise<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;

package/dist/dlx/firewall.js

@@ -0,0 +1,107 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var firewall_exports = {};
+__export(firewall_exports, {
+  checkFirewallPurls: () => checkFirewallPurls,
+  npmPurl: () => npmPurl
+});
+module.exports = __toCommonJS(firewall_exports);
+var import_convenience = require("../http-request/convenience");
+var import_user_agent = require("../http-request/user-agent");
+var import_error = require("../primordials/error");
+var import_map_set = require("../primordials/map-set");
+var import_promise = require("../primordials/promise");
+var import_string = require("../primordials/string");
+const FIREWALL_API_URL = "https://firewall-api.socket.dev/purl";
+const FIREWALL_TIMEOUT = 1e4;
+const FIREWALL_BLOCK_SEVERITIES = new import_map_set.SetCtor([
+  "critical",
+  "high"
+]);
+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 (0, import_promise.PromiseAllSettled)(
+    purls.map(async ({ name, purl, version }) => {
+      try {
+        const data = await (0, import_convenience.httpJson)(
+          `${FIREWALL_API_URL}/${encodeURIComponent(purl)}`,
+          {
+            headers: { "User-Agent": (0, import_user_agent.getSocketCallerUserAgent)() },
+            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 import_error.ErrorCtor(
+      `Socket Firewall blocked installation of "${requestedPackage}".
+The following dependencies have security alerts:
+${details}
+
+Visit https://socket.dev for more information.`
+    );
+  }
+}
+function npmPurl(name, version) {
+  const encoded = (0, import_string.StringPrototypeStartsWith)(name, "@") ? `%40${(0, import_string.StringPrototypeSlice)(name, 1)}` : name;
+  const encodedVersion = (0, import_string.StringPrototypeReplace)(version, /\+/g, "%2B");
+  return `pkg:npm/${encoded}@${encodedVersion}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkFirewallPurls,
+  npmPurl
+});