@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/dlx/binary-cache.js

@@ -0,0 +1,212 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var binary_cache_exports = {};
+__export(binary_cache_exports, {
+  cleanDlxCache: () => cleanDlxCache,
+  getBinaryCacheMetadataPath: () => getBinaryCacheMetadataPath,
+  getDlxCachePath: () => getDlxCachePath,
+  isBinaryCacheValid: () => isBinaryCacheValid,
+  listDlxCache: () => listDlxCache,
+  readBinaryCacheMetadata: () => readBinaryCacheMetadata,
+  writeBinaryCacheMetadata: () => writeBinaryCacheMetadata
+});
+module.exports = __toCommonJS(binary_cache_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_node_fs = require("node:fs");
+var import_time = require("../constants/time");
+var import_read_json = require("../fs/read-json");
+var import_safe = require("../fs/safe");
+var import_predicates = require("../objects/predicates");
+var import_socket = require("../paths/socket");
+var import_array = require("../primordials/array");
+var import_date = require("../primordials/date");
+var import_json = require("../primordials/json");
+var import_string = require("../primordials/string");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+async function cleanDlxCache(maxAge = import_time.DLX_BINARY_CACHE_TTL) {
+  const cacheDir = getDlxCachePath();
+  const fs = (0, import_fs.getNodeFs)();
+  if (!fs.existsSync(cacheDir)) {
+    return 0;
+  }
+  let cleaned = 0;
+  const now = (0, import_date.DateNow)();
+  const path = (0, import_path.getNodePath)();
+  const entries = await fs.promises.readdir(cacheDir);
+  for (const entry of entries) {
+    const entryPath = path.join(cacheDir, entry);
+    const metaPath = getBinaryCacheMetadataPath(entryPath);
+    try {
+      if (!await (0, import_node_fs.existsSync)(entryPath)) {
+        continue;
+      }
+      const metadata = await (0, import_read_json.readJson)(metaPath, { throws: false });
+      if (!metadata || typeof metadata !== "object" || (0, import_array.ArrayIsArray)(metadata)) {
+        continue;
+      }
+      const timestamp = metadata["timestamp"];
+      const age = typeof timestamp === "number" && timestamp > 0 ? now - timestamp : Number.POSITIVE_INFINITY;
+      if (age < 0 || age > maxAge) {
+        await (0, import_safe.safeDelete)(entryPath, { force: true, recursive: true });
+        cleaned += 1;
+      }
+    } catch {
+      try {
+        const contents = await fs.promises.readdir(entryPath);
+        if (!contents.length) {
+          await (0, import_safe.safeDelete)(entryPath);
+          cleaned += 1;
+        }
+      } catch {
+      }
+    }
+  }
+  return cleaned;
+}
+function getBinaryCacheMetadataPath(cacheEntryPath) {
+  return (0, import_path.getNodePath)().join(cacheEntryPath, ".dlx-metadata.json");
+}
+const getDlxCachePath = import_socket.getSocketDlxDir;
+async function isBinaryCacheValid(cacheEntryPath, cacheTtl) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    const metaPath = getBinaryCacheMetadataPath(cacheEntryPath);
+    if (!fs.existsSync(metaPath)) {
+      return false;
+    }
+    const metadata = await (0, import_read_json.readJson)(metaPath, { throws: false });
+    if (!(0, import_predicates.isPlainObject)(metadata)) {
+      return false;
+    }
+    const now = (0, import_date.DateNow)();
+    const timestamp = metadata["timestamp"];
+    if (typeof timestamp !== "number" || timestamp <= 0) {
+      return false;
+    }
+    const age = now - timestamp;
+    if (age < 0) {
+      return false;
+    }
+    return age < cacheTtl;
+  } catch {
+    return false;
+  }
+}
+async function listDlxCache() {
+  const cacheDir = getDlxCachePath();
+  const fs = (0, import_fs.getNodeFs)();
+  if (!fs.existsSync(cacheDir)) {
+    return [];
+  }
+  const results = [];
+  const now = (0, import_date.DateNow)();
+  const path = (0, import_path.getNodePath)();
+  const entries = await fs.promises.readdir(cacheDir);
+  for (const entry of entries) {
+    const entryPath = path.join(cacheDir, entry);
+    try {
+      if (!await (0, import_node_fs.existsSync)(entryPath)) {
+        continue;
+      }
+      const metaPath = getBinaryCacheMetadataPath(entryPath);
+      const metadata = await (0, import_read_json.readJson)(metaPath, { throws: false });
+      if (!metadata || typeof metadata !== "object" || (0, import_array.ArrayIsArray)(metadata)) {
+        continue;
+      }
+      const metaObj = metadata;
+      const source = metaObj["source"];
+      const url = source?.["url"] || metaObj["url"] || "";
+      const files = await fs.promises.readdir(entryPath);
+      const binaryFile = (0, import_array.ArrayPrototypeFind)(
+        files,
+        (f) => !(0, import_string.StringPrototypeStartsWith)(f, ".")
+      );
+      if (binaryFile) {
+        const binaryPath = path.join(entryPath, binaryFile);
+        const binaryStats = await fs.promises.stat(binaryPath);
+        results.push({
+          age: now - (metaObj["timestamp"] || 0),
+          integrity: metaObj["integrity"] || "",
+          name: binaryFile,
+          size: binaryStats.size,
+          url
+        });
+      }
+    } catch {
+    }
+  }
+  return results;
+}
+async function readBinaryCacheMetadata(cacheEntryPath) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    const metaPath = getBinaryCacheMetadataPath(cacheEntryPath);
+    if (!fs.existsSync(metaPath)) {
+      return void 0;
+    }
+    const metadata = await (0, import_read_json.readJson)(metaPath, { throws: false });
+    if (!(0, import_predicates.isPlainObject)(metadata)) {
+      return void 0;
+    }
+    return metadata;
+  } catch {
+    return void 0;
+  }
+}
+async function writeBinaryCacheMetadata(cacheEntryPath, cacheKey, url, integrity, size) {
+  const metaPath = getBinaryCacheMetadataPath(cacheEntryPath);
+  const metadata = {
+    version: "1.0.0",
+    cache_key: cacheKey,
+    timestamp: (0, import_date.DateNow)(),
+    integrity,
+    size,
+    source: {
+      type: "download",
+      url
+    }
+  };
+  const fs = (0, import_fs.getNodeFs)();
+  const tmpPath = `${metaPath}.tmp.${import_node_process.default.pid}`;
+  await fs.promises.writeFile(tmpPath, (0, import_json.JSONStringify)(metadata, null, 2));
+  await fs.promises.rename(tmpPath, metaPath);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cleanDlxCache,
+  getBinaryCacheMetadataPath,
+  getDlxCachePath,
+  isBinaryCacheValid,
+  listDlxCache,
+  readBinaryCacheMetadata,
+  writeBinaryCacheMetadata
+});

package/dist/dlx/binary-download.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Download helpers for dlx binaries — fetch tarballs from URLs, verify
+ *   integrity, cache to disk with concurrency locking.
+ *
+ *   - `downloadBinary` — high-level URL→cached-binary flow
+ *   - `downloadBinaryFile` — low-level fetch+verify with processLock Split out of
+ *     `dlx/binary.ts` for size hygiene.
+ */
+import type { DlxBinaryOptions } from './binary-types';
+/**
+ * Download a binary from a URL with caching (without execution). Similar to
+ * downloadPackage from dlx/package.
+ *
+ * Returns `{binaryPath, downloaded, integrity}`. The `integrity` field is the
+ * SRI-formatted `sha512-<base64>` hash of the cached file — computed by the
+ * downloader on first fetch, persisted to cache metadata, and re-read on
+ * subsequent cache hits. This supports the trust-on-first-use pattern:
+ *
+ * // 1. First call — caller has no pinned integrity yet. const { integrity } =
+ * await downloadBinary({ url, name: 'tool' }) // Caller writes `integrity` back
+ * to external-tools.json or similar.
+ *
+ * // 2. Subsequent calls — caller pins the integrity for verification. await
+ * downloadBinary({ url, name: 'tool', hash: integrity })
+ *
+ * @example
+ *   ```typescript
+ *   const { binaryPath, integrity } = await downloadBinary({
+ *   url: 'https://example.com/tool-linux-x64',
+ *   name: 'tool',
+ *   })
+ *   console.log(`Binary at: ${binaryPath}, pin: ${integrity}`)
+ *   ```
+ *
+ * @returns `{binaryPath, downloaded, integrity}` — binary location, whether
+ *   this call fetched (vs. cache-hit), and the computed SRI integrity for
+ *   future pinning.
+ */
+export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOptions'>): Promise<{
+    binaryPath: string;
+    downloaded: boolean;
+    integrity: string;
+}>;
+/**
+ * Download a file from a URL with integrity checking and concurrent download
+ * protection. Uses processLock to prevent multiple processes from downloading
+ * the same binary simultaneously.
+ *
+ * Supports two integrity verification methods:
+ *
+ * - Sha256: Hex SHA-256 checksum (verified inline during download via
+ *   httpDownload)
+ * - Integrity: SRI format sha512-<base64> (verified post-download)
+ *
+ * The sha256 option is preferred as it fails early during download if the
+ * checksum doesn't match.
+ *
+ * @example
+ *   ```typescript
+ *   const integrity = await downloadBinaryFile(
+ *   'https://example.com/tool-linux-x64',
+ *   '/tmp/dlx-cache/tool',
+ *   )
+ *   console.log(`Integrity: ${integrity}`)
+ *   ```
+ */
+export declare function downloadBinaryFile(url: string, destPath: string, integrity?: string | undefined, sha256?: string | undefined): Promise<string>;

package/dist/dlx/binary-download.js

@@ -0,0 +1,216 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var binary_download_exports = {};
+__export(binary_download_exports, {
+  downloadBinary: () => downloadBinary,
+  downloadBinaryFile: () => downloadBinaryFile
+});
+module.exports = __toCommonJS(binary_download_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_platform = require("../constants/platform");
+var import_time = require("../constants/time");
+var import_hash = require("../crypto/hash");
+var import_safe = require("../fs/safe");
+var import_download = require("../http-request/download");
+var import_normalize = require("../paths/normalize");
+var import_lock_instance = require("../process/lock-instance");
+var import_cache = require("./cache");
+var import_integrity = require("../integrity");
+var import_error = require("../primordials/error");
+var import_crypto = require("../node/crypto");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_binary_cache = require("./binary-cache");
+async function downloadBinary(options) {
+  const {
+    cacheTtl = import_time.DLX_BINARY_CACHE_TTL,
+    force = false,
+    hash: hashSpec,
+    integrity: rawIntegrity,
+    name,
+    sha256: rawSha256,
+    url
+  } = { __proto__: null, ...options };
+  let integrity = rawIntegrity;
+  let sha256 = rawSha256;
+  if (hashSpec !== void 0) {
+    const normalized = (0, import_integrity.normalizeHash)(hashSpec);
+    if (normalized.type === "integrity") {
+      integrity = normalized.value;
+    } else {
+      sha256 = normalized.value;
+    }
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  const cacheDir = (0, import_binary_cache.getDlxCachePath)();
+  const binaryName = name || `binary-${import_node_process.default.platform}-${(0, import_platform.getArch)()}`;
+  const spec = `${url}:${binaryName}`;
+  const cacheKey = (0, import_cache.generateCacheKey)(spec);
+  const cacheEntryDir = path.join(cacheDir, cacheKey);
+  const binaryPath = (0, import_normalize.normalizePath)(path.join(cacheEntryDir, binaryName));
+  let downloaded = false;
+  let actualIntegrity = "";
+  if (!force && fs.existsSync(cacheEntryDir) && await (0, import_binary_cache.isBinaryCacheValid)(cacheEntryDir, cacheTtl)) {
+    downloaded = false;
+    const cachedMeta = await (0, import_binary_cache.readBinaryCacheMetadata)(cacheEntryDir);
+    if (cachedMeta?.integrity) {
+      actualIntegrity = cachedMeta.integrity;
+    } else {
+      const fileBuffer = await fs.promises.readFile(binaryPath);
+      actualIntegrity = `sha512-${(0, import_hash.hash)("sha512", fileBuffer, "base64")}`;
+    }
+  } else {
+    try {
+      await (0, import_safe.safeMkdir)(cacheEntryDir);
+    } catch (e) {
+      const code = e.code;
+      if (code === "EACCES" || code === "EPERM") {
+        throw new import_error.ErrorCtor(
+          `Permission denied creating binary cache directory: ${cacheEntryDir}
+Please check directory permissions or run with appropriate access.`,
+          { cause: e }
+        );
+      }
+      if (code === "EROFS") {
+        throw new import_error.ErrorCtor(
+          `Cannot create binary cache directory on read-only filesystem: ${cacheEntryDir}
+Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`,
+          { cause: e }
+        );
+      }
+      throw new import_error.ErrorCtor(
+        `Failed to create binary cache directory: ${cacheEntryDir}`,
+        { cause: e }
+      );
+    }
+    actualIntegrity = await downloadBinaryFile(
+      url,
+      binaryPath,
+      integrity,
+      sha256
+    );
+    const stats = await fs.promises.stat(binaryPath);
+    await (0, import_binary_cache.writeBinaryCacheMetadata)(
+      cacheEntryDir,
+      cacheKey,
+      url,
+      actualIntegrity,
+      stats.size
+    );
+    downloaded = true;
+  }
+  return {
+    binaryPath,
+    downloaded,
+    integrity: actualIntegrity
+  };
+}
+async function downloadBinaryFile(url, destPath, integrity, sha256) {
+  const crypto = (0, import_crypto.getNodeCrypto)();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  const cacheEntryDir = path.dirname(destPath);
+  const lockPath = path.join(cacheEntryDir, "concurrency.lock");
+  const verifyIntegrity = async (actualIntegrity) => {
+    if (!integrity) {
+      return;
+    }
+    const integrityMatch = actualIntegrity.length === integrity.length && crypto.timingSafeEqual(
+      Buffer.from(actualIntegrity),
+      Buffer.from(integrity)
+    );
+    if (!integrityMatch) {
+      await (0, import_safe.safeDelete)(destPath);
+      throw new import_error.ErrorCtor(
+        `Integrity mismatch: expected ${integrity}, got ${actualIntegrity}`
+      );
+    }
+  };
+  const verifyCachedSha256 = async (fileBuffer) => {
+    if (!sha256) {
+      return;
+    }
+    const actualSha256 = (0, import_hash.hash)("sha256", fileBuffer, "hex");
+    const sha256Match = actualSha256.length === sha256.length && crypto.timingSafeEqual(
+      Buffer.from(actualSha256),
+      Buffer.from(sha256.toLowerCase())
+    );
+    if (!sha256Match) {
+      await (0, import_safe.safeDelete)(destPath);
+      throw new import_error.ErrorCtor(
+        `SHA-256 mismatch: expected ${sha256}, got ${actualSha256}`
+      );
+    }
+  };
+  return await import_lock_instance.processLock.withLock(
+    lockPath,
+    async () => {
+      if (fs.existsSync(destPath)) {
+        const stats = await fs.promises.stat(destPath);
+        if (stats.size > 0) {
+          const fileBuffer2 = await fs.promises.readFile(destPath);
+          const actualIntegrity2 = `sha512-${(0, import_hash.hash)("sha512", fileBuffer2, "base64")}`;
+          await verifyIntegrity(actualIntegrity2);
+          await verifyCachedSha256(fileBuffer2);
+          return actualIntegrity2;
+        }
+      }
+      try {
+        await (0, import_download.httpDownload)(url, destPath, sha256 ? { sha256 } : void 0);
+      } catch (e) {
+        throw new import_error.ErrorCtor(
+          `Failed to download binary from ${url}
+Destination: ${destPath}
+Check your internet connection or verify the URL is accessible.`,
+          { cause: e }
+        );
+      }
+      const fileBuffer = await fs.promises.readFile(destPath);
+      const actualIntegrity = `sha512-${(0, import_hash.hash)("sha512", fileBuffer, "base64")}`;
+      await verifyIntegrity(actualIntegrity);
+      if (!import_platform.WIN32) {
+        await fs.promises.chmod(destPath, 493);
+      }
+      return actualIntegrity;
+    },
+    {
+      // Align with npm npx locking strategy.
+      staleMs: 5e3,
+      touchIntervalMs: 2e3
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  downloadBinary,
+  downloadBinaryFile
+});

package/dist/dlx/binary-resolution.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Binary resolution for installed dlx packages.
+ *
+ *   - `findBinaryPath` — pick the right binary entry from package.json `bin`
+ *   - `makePackageBinsExecutable` — chmod all bin entries to 0o755 on Unix
+ *   - `resolveBinaryPath` — Windows wrapper (.cmd/.bat/.ps1/.exe) lookup Split
+ *     out of `dlx/package.ts` for size hygiene. The cache used by
+ *     `resolveBinaryPath` lives in `_internal.ts` so both this leaf and any
+ *     direct consumers (`binaryPathCacheSet`) share one source.
+ */
+/**
+ * Find the binary path for an installed package. Uses npm's bin resolution
+ * strategy with user-friendly fallbacks. Resolves platform-specific wrappers
+ * (.cmd, .ps1, etc.) on Windows.
+ *
+ * Resolution strategy (cherry-picked from libnpmexec): 1. Use npm's
+ * getBinFromManifest (handles aliases and standard cases) 2. Fall back to
+ * user-provided binaryName if npm's strategy fails 3. Try last segment of
+ * package name as final fallback 4. Use first binary as last resort.
+ *
+ * @example
+ *   ```typescript
+ *   const binPath = findBinaryPath('/tmp/.socket/_dlx/a1b2c3d4', 'prettier')
+ *   console.log(`Binary: ${binPath}`)
+ *   ```
+ */
+export declare function findBinaryPath(packageDir: string, packageName: string, binaryName?: string): string;
+/**
+ * Make all binaries in an installed package executable. Reads the package.json
+ * bin field and makes all binaries executable (chmod 0o755). Handles both
+ * single binary (string) and multiple binaries (object) formats.
+ *
+ * Aligns with npm's approach: - Uses 0o755 permission (matches npm's cmd-shim)
+ * - Reads bin field from package.json (matches npm's bin-links and libnpmexec)
+ * - Handles both string and object bin formats.
+ *
+ * References: - npm cmd-shim:
+ * https://github.com/npm/cmd-shim/blob/main/lib/index.js - npm
+ * getBinFromManifest:
+ * https://github.com/npm/libnpmexec/blob/main/lib/get-bin-from-manifest.js.
+ *
+ * @example
+ *   ;```typescript
+ *   makePackageBinsExecutable('/tmp/.socket/_dlx/a1b2c3d4', 'prettier')
+ *   ```
+ */
+export declare function makePackageBinsExecutable(packageDir: string, packageName: string): void;
+/**
+ * Resolve binary path with cross-platform wrapper support. On Windows, checks
+ * for .cmd, .bat, .ps1, .exe wrappers in order. On Unix, uses path directly.
+ *
+ * Aligns with npm/npx binary resolution strategy.
+ *
+ * @example
+ *   ;```typescript
+ *   const resolved = resolveBinaryPath('/tmp/.socket/_dlx/a1b2c3d4/prettier')
+ *   // On Windows: may resolve to '.cmd' or '.ps1' wrapper
+ *   // On Unix: returns the path unchanged
+ *   ```
+ */
+export declare function resolveBinaryPath(basePath: string): string;