@socketsecurity/lib 5.27.0 → 6.0.0

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;

package/dist/dlx/binary-resolution.js

@@ -0,0 +1,164 @@
+"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_resolution_exports = {};
+__export(binary_resolution_exports, {
+  findBinaryPath: () => findBinaryPath,
+  makePackageBinsExecutable: () => makePackageBinsExecutable,
+  resolveBinaryPath: () => resolveBinaryPath
+});
+module.exports = __toCommonJS(binary_resolution_exports);
+var import_platform = require("../constants/platform");
+var import_read_json = require("../fs/read-json");
+var import_libnpmexec = __toESM(require("../external/libnpmexec"));
+var import_normalize = require("../paths/normalize");
+var import_error = require("../primordials/error");
+var import_object = require("../primordials/object");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_internal = require("./_internal");
+function findBinaryPath(packageDir, packageName, binaryName) {
+  const path = (0, import_path.getNodePath)();
+  const installedDir = (0, import_normalize.normalizePath)(
+    path.join(packageDir, "node_modules", packageName)
+  );
+  const pkgJsonPath = path.join(installedDir, "package.json");
+  const pkgJson = (0, import_read_json.readJsonSync)(pkgJsonPath);
+  const bin = pkgJson["bin"];
+  let binName;
+  let binPath;
+  if (typeof bin === "string") {
+    binPath = bin;
+  } else if (typeof bin === "object" && bin !== null) {
+    const binObj = bin;
+    const binKeys = (0, import_object.ObjectKeys)(binObj);
+    if (binKeys.length === 1) {
+      binName = binKeys[0];
+      binPath = binObj[binName];
+    } else {
+      try {
+        const { getBinFromManifest } = import_libnpmexec.default;
+        binName = getBinFromManifest({
+          name: packageName,
+          bin: binObj,
+          _id: `${packageName}@${pkgJson.version || "unknown"}`
+        });
+        binPath = binObj[binName];
+      } catch {
+        const lastSegment = packageName.split("/").pop() ?? packageName;
+        const candidates = [
+          binaryName,
+          lastSegment,
+          packageName.replace(/^@[^/]+\//, "")
+        ].filter(Boolean);
+        for (const candidate of candidates) {
+          if (candidate && binObj[candidate]) {
+            binName = candidate;
+            binPath = binObj[candidate];
+            break;
+          }
+        }
+        if (!binPath && binKeys.length > 0) {
+          binName = binKeys[0];
+          binPath = binObj[binName];
+        }
+      }
+    }
+  }
+  if (!binPath) {
+    throw new import_error.ErrorCtor(`No binary found for package "${packageName}"`);
+  }
+  const rawPath = (0, import_normalize.normalizePath)(path.join(installedDir, binPath));
+  return resolveBinaryPath(rawPath);
+}
+function makePackageBinsExecutable(packageDir, packageName) {
+  if (import_platform.WIN32) {
+    return;
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  const installedDir = (0, import_normalize.normalizePath)(
+    path.join(packageDir, "node_modules", packageName)
+  );
+  const pkgJsonPath = path.join(installedDir, "package.json");
+  try {
+    const pkgJson = (0, import_read_json.readJsonSync)(pkgJsonPath);
+    const bin = pkgJson["bin"];
+    if (!bin) {
+      return;
+    }
+    const binPaths = [];
+    if (typeof bin === "string") {
+      binPaths.push(bin);
+    } else if (typeof bin === "object" && bin !== null) {
+      const binObj = bin;
+      binPaths.push(...(0, import_object.ObjectValues)(binObj));
+    }
+    for (const binPath of binPaths) {
+      const fullPath = (0, import_normalize.normalizePath)(path.join(installedDir, binPath));
+      if (fs.existsSync(fullPath)) {
+        try {
+          fs.chmodSync(fullPath, 493);
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+}
+function resolveBinaryPath(basePath) {
+  if (!import_platform.WIN32) {
+    return basePath;
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  const cached = import_internal.binaryPathCache.get(basePath);
+  if (cached) {
+    if (fs.existsSync(cached)) {
+      (0, import_internal.binaryPathCacheSet)(basePath, cached);
+      return cached;
+    }
+    import_internal.binaryPathCache.delete(basePath);
+  }
+  const extensions = [".cmd", ".bat", ".ps1", ".exe", ""];
+  for (const ext of extensions) {
+    const testPath = basePath + ext;
+    if (fs.existsSync(testPath)) {
+      (0, import_internal.binaryPathCacheSet)(basePath, testPath);
+      return testPath;
+    }
+  }
+  return basePath;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findBinaryPath,
+  makePackageBinsExecutable,
+  resolveBinaryPath
+});

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

@@ -0,0 +1,144 @@
+/**
+ * @file Public option / result interfaces for dlx binary operations. Split out
+ *   of `dlx/binary.ts` so consumers can import these types without pulling in
+ *   the implementation.
+ *
+ *   - `DlxBinaryOptions` — options for `dlxBinary` / `downloadBinary`
+ *   - `DlxBinaryResult` — what `dlxBinary` returns
+ *   - `DlxMetadata` — on-disk metadata schema for a cached binary
+ */
+import type { HashSpec } from '../integrity';
+import type { spawn } from '../spawn/spawn';
+import type { SpawnOptions } from '../spawn/types';
+export interface DlxBinaryOptions {
+    /**
+     * URL to download the binary from.
+     */
+    url: string;
+    /**
+     * Optional name for the cached binary (defaults to URL hash).
+     */
+    name?: string | undefined;
+    /**
+     * Expected hash for verification. Accepts either:
+     *
+     * - A bare sha512 SRI string (`sha512-<base64>`), sniffed as integrity.
+     * - A bare sha256 hex string (64 hex chars), sniffed as checksum.
+     * - An explicit `{ type: 'integrity' | 'checksum', value }` object.
+     *
+     * This is the preferred field. `integrity` and `sha256` remain as lower-level
+     * escapes; if both `hash` and one of those is set, `hash` wins for the
+     * matching flavor.
+     */
+    hash?: HashSpec | undefined;
+    /**
+     * Expected SRI integrity hash (sha512-<base64>) for verification. Lower-level
+     * alternative to `hash`.
+     */
+    integrity?: string | undefined;
+    /**
+     * Expected SHA-256 hex checksum for verification. Passed to httpDownload for
+     * inline verification during download. This is more secure than post-download
+     * verification as it fails early. Lower-level alternative to `hash`.
+     */
+    sha256?: string | undefined;
+    /**
+     * Cache TTL in milliseconds (default: 7 days).
+     */
+    cacheTtl?: number | undefined;
+    /**
+     * Force re-download even if cached. Aligns with npm/npx --force flag.
+     */
+    force?: boolean | undefined;
+    /**
+     * Skip confirmation prompts (auto-approve). Aligns with npx --yes/-y flag.
+     */
+    yes?: boolean | undefined;
+    /**
+     * Suppress output (quiet mode). Aligns with npx --quiet/-q and pnpm
+     * --silent/-s flags.
+     */
+    quiet?: boolean | undefined;
+    /**
+     * Additional spawn options.
+     */
+    spawnOptions?: SpawnOptions | undefined;
+}
+export interface DlxBinaryResult {
+    /**
+     * Path to the cached binary.
+     */
+    binaryPath: string;
+    /**
+     * Whether the binary was newly downloaded.
+     */
+    downloaded: boolean;
+    /**
+     * The spawn promise for the running process.
+     */
+    spawnPromise: ReturnType<typeof spawn>;
+}
+/**
+ * Metadata structure for cached binaries (.dlx-metadata.json). Unified schema
+ * shared across TypeScript (dlxBinary) and C++ stub extractor.
+ *
+ * Fields:
+ *
+ * - Version: Schema version (currently "1.0.0")
+ * - Cache_key: First 16 chars of SHA-512 hash (matches directory name)
+ * - Timestamp: Unix timestamp in milliseconds
+ * - Integrity: SRI hash (sha512-<base64>, aligned with npm)
+ * - Size: Size of cached binary in bytes
+ * - Source: Origin information
+ *
+ *   - Type: "download" | "extract" | "package"
+ *   - Url: Download URL (if type is "download")
+ *   - Path: Source binary path (if type is "extract")
+ *   - Spec: Package spec (if type is "package")
+ * - Update_check: Update checking metadata (optional)
+ *
+ *   - Last_check: Timestamp of last update check
+ *   - Last_notification: Timestamp of last user notification
+ *   - Latest_known: Latest known version string
+ *
+ * Example:
+ *
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "cache_key": "a1b2c3d4e5f67890",
+ *   "timestamp": 1730332800000,
+ *   "integrity": "sha512-abc123base64...",
+ *   "size": 15000000,
+ *   "source": {
+ *     "type": "download",
+ *     "url": "https://example.com/binary"
+ *   },
+ *   "update_check": {
+ *     "last_check": 1730332800000,
+ *     "last_notification": 1730246400000,
+ *     "latest_known": "2.1.0"
+ *   }
+ * }
+ * ```
+ *
+ * @internal This interface documents the metadata file format.
+ */
+export interface DlxMetadata {
+    version: string;
+    cache_key: string;
+    timestamp: number;
+    integrity: string;
+    size: number;
+    source?: {
+        type: 'download' | 'extract' | 'package';
+        url?: string;
+        path?: string;
+        spec?: string;
+    };
+    update_check?: {
+        last_check: number;
+        last_notification: number;
+        latest_known: string;
+    };
+}

package/dist/dlx/binary-types.js

@@ -0,0 +1,18 @@
+"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 __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 binary_types_exports = {};
+module.exports = __toCommonJS(binary_types_exports);