@socketsecurity/lib 5.28.0 → 6.0.1

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 '../process/spawn/child';
+import type { SpawnOptions } from '../process/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);

package/dist/dlx/binary.d.ts

@@ -1,285 +1,56 @@
-/** @fileoverview DLX binary execution utilities for Socket ecosystem. */
-import { getSocketDlxDir } from '../paths/socket';
-import { spawn } from '../spawn';
-import type { HashSpec } from './integrity';
-import type { SpawnExtra, SpawnOptions } from '../spawn';
-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.
+ * @file DLX binary execution utilities for Socket ecosystem. High-level entry
+ *   points for downloading standalone URL-hosted binaries (not npm packages —
+ *   see `./package` for those) and executing them with cross-platform shell
+ *   handling.
  *
- * 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;
-    };
-}
-/**
- * Clean expired entries from the DLX cache.
- *
- * @example
- * ```typescript
- * // Remove cache entries older than the default TTL
- * const removed = await cleanDlxCache()
- *
- * // Remove entries older than 1 hour
- * const removed2 = await cleanDlxCache(60 * 60 * 1000)
- * ```
+ *   - `dlxBinary` — download (if needed) + execute
+ *   - `executeBinary` — execute an already-cached binary Supporting surface lives
+ *     in sibling leaves and is re-exported here so existing `dlx/binary`
+ *     importers keep working unchanged:
+ *   - lazy `node:fs` / `node:path` / `node:crypto` + LRU cache — `./_internal`
+ *   - types — `./binary-types`
+ *   - on-disk cache metadata — `./binary-cache`
+ *   - download + integrity verification — `./binary-download`
  */
-export declare function cleanDlxCache(maxAge?: number): Promise<number>;
+import { spawn } from '../process/spawn/child';
+import type { DlxBinaryOptions, DlxBinaryResult } from './binary-types';
+import type { SpawnExtra, SpawnOptions } from '../process/spawn/types';
 /**
  * Download and execute a binary from a URL with caching.
  *
  * @example
- * ```typescript
- * const result = await dlxBinary(['--version'], {
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * await result.spawnPromise
- * ```
+ *   ;```typescript
+ *   const result = await dlxBinary(['--version'], {
+ *     url: 'https://example.com/tool-linux-x64',
+ *     name: 'tool',
+ *   })
+ *   await result.spawnPromise
+ *   ```
  */
 export declare function dlxBinary(args: readonly string[] | string[], options?: DlxBinaryOptions | undefined, spawnExtra?: SpawnExtra | undefined): Promise<DlxBinaryResult>;
 /**
- * Download a binary from a URL with caching (without execution).
- * Similar to downloadPackage from dlx-package.
- *
- * @returns Object containing the path to the cached binary and whether it was downloaded
- *
- * @example
- * ```typescript
- * const { binaryPath, downloaded } = await downloadBinary({
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * console.log(`Binary at: ${binaryPath}, fresh: ${downloaded}`)
- * ```
- */
-export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOptions'>): Promise<{
-    binaryPath: string;
-    downloaded: boolean;
-}>;
-/**
- * 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.
- * Internal helper function for downloading binary files.
- *
- * 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.
+ * Execute a cached binary without re-downloading. Similar to executePackage
+ * from dlx/package. Binary must have been previously downloaded via
+ * downloadBinary or dlxBinary.
  *
  * @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>;
-/**
- * Execute a cached binary without re-downloading.
- * Similar to executePackage from dlx-package.
- * Binary must have been previously downloaded via downloadBinary or dlxBinary.
+ *   ;```typescript
+ *   const { binaryPath } = await downloadBinary({
+ *     url: 'https://example.com/tool-linux-x64',
+ *     name: 'tool',
+ *   })
+ *   const result = executeBinary(binaryPath, ['--help'])
+ *   ```
  *
  * @param binaryPath Path to the cached binary (from downloadBinary result)
- * @param args Arguments to pass to the binary
- * @param spawnOptions Spawn options for execution
- * @param spawnExtra Extra spawn configuration
- * @returns The spawn promise for the running process
+ * @param args Arguments to pass to the binary.
+ * @param spawnOptions Spawn options for execution.
+ * @param spawnExtra Extra spawn configuration.
  *
- * @example
- * ```typescript
- * const { binaryPath } = await downloadBinary({
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * const result = executeBinary(binaryPath, ['--help'])
- * ```
+ * @returns The spawn promise for the running process
  */
 export declare function executeBinary(binaryPath: string, args: readonly string[] | string[], spawnOptions?: SpawnOptions | undefined, spawnExtra?: SpawnExtra | undefined): ReturnType<typeof spawn>;
-/**
- * Get metadata file path for a cached binary.
- *
- * @example
- * ```typescript
- * const metaPath = getBinaryCacheMetadataPath('/tmp/dlx-cache/a1b2c3d4')
- * // '/tmp/dlx-cache/a1b2c3d4/.dlx-metadata.json'
- * ```
- */
-export declare function getBinaryCacheMetadataPath(cacheEntryPath: string): string;
-/**
- * Get the DLX binary cache directory path.
- * Alias of `getSocketDlxDir` — DLX binary cache uses the same directory
- * as dlx-package for unified DLX storage.
- *
- * @example
- * ```typescript
- * const cachePath = getDlxCachePath()
- * ```
- */
-export declare const getDlxCachePath: typeof getSocketDlxDir;
-/**
- * Check if a cached binary is still valid.
- *
- * @example
- * ```typescript
- * const ttl = 7 * 24 * 60 * 60 * 1000
- * const valid = await isBinaryCacheValid('/tmp/dlx-cache/a1b2c3d4', ttl)
- * if (!valid) {
- *   // Re-download the binary
- * }
- * ```
- */
-export declare function isBinaryCacheValid(cacheEntryPath: string, cacheTtl: number): Promise<boolean>;
-/**
- * Get information about cached binaries.
- *
- * @example
- * ```typescript
- * const entries = await listDlxCache()
- * for (const entry of entries) {
- *   console.log(`${entry.name}: ${entry.size} bytes`)
- * }
- * ```
- */
-export declare function listDlxCache(): Promise<Array<{
-    age: number;
-    integrity: string;
-    name: string;
-    size: number;
-    url: string;
-}>>;
-/**
- * Write metadata for a cached binary.
- * Uses unified schema shared with C++ decompressor and CLI dlxBinary.
- * Schema documentation: See DlxMetadata interface in this file (exported).
- *
- * @example
- * ```typescript
- * await writeBinaryCacheMetadata(
- *   '/tmp/dlx-cache/a1b2c3d4',
- *   'a1b2c3d4',
- *   'https://example.com/tool',
- *   'sha512-abc123...',
- *   15000000
- * )
- * ```
- */
-export declare function writeBinaryCacheMetadata(cacheEntryPath: string, cacheKey: string, url: string, integrity: string, size: number): Promise<void>;
+export { cleanDlxCache, getBinaryCacheMetadataPath, getDlxCachePath, isBinaryCacheValid, listDlxCache, writeBinaryCacheMetadata, } from './binary-cache';
+export { downloadBinary, downloadBinaryFile } from './binary-download';
+export type { DlxBinaryOptions, DlxBinaryResult, DlxMetadata, } from './binary-types';