@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/dlx/arborist.js

@@ -30,6 +30,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var arborist_exports = {};
 __export(arborist_exports, {
+  getBaseArboristOptions: () => getBaseArboristOptions,
+  readSingleDependency: () => readSingleDependency,
+  readTopLevelFromIdealTree: () => readTopLevelFromIdealTree,
   safeIdealTree: () => safeIdealTree,
   safeReify: () => safeReify,
   writeSafeNpmrc: () => writeSafeNpmrc
@@ -37,24 +40,13 @@ __export(arborist_exports, {
 module.exports = __toCommonJS(arborist_exports);
 var import_arborist = __toESM(require("../external/@npmcli/arborist"));
 var import_socket = require("../paths/socket");
-var import_primordials = require("../primordials");
-let _fs;
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
-let _path;
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
-function getBaseArboristOptions(installPath, quiet) {
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+function getBaseArboristOptions(installPath, options) {
   return {
     __proto__: null,
     path: installPath,
@@ -65,17 +57,17 @@ function getBaseArboristOptions(installPath, quiet) {
     progress: false,
     save: false,
     saveBundle: false,
-    silent: quiet
+    silent: options.quiet
   };
 }
 function readSingleDependency(packageJsonPath) {
-  const fs = /* @__PURE__ */ getFs();
+  const fs = (0, import_fs.getNodeFs)();
   const raw = fs.readFileSync(packageJsonPath, "utf8");
-  const pkg = (0, import_primordials.JSONParse)(raw);
+  const pkg = (0, import_json.JSONParse)(raw);
   const deps = pkg.dependencies ?? {};
-  const names = (0, import_primordials.ObjectKeys)(deps);
+  const names = (0, import_object.ObjectKeys)(deps);
   if (names.length !== 1) {
-    throw new import_primordials.ErrorCtor(
+    throw new import_error.ErrorCtor(
       `safeIdealTree expects exactly one top-level dependency in ${packageJsonPath}, found ${names.length}`
     );
   }
@@ -85,7 +77,7 @@ function readTopLevelFromIdealTree(tree, targetName) {
   const root = tree;
   const inventory = root?.inventory;
   if (!inventory || typeof inventory.values !== "function") {
-    throw new import_primordials.ErrorCtor("Arborist idealTree missing inventory");
+    throw new import_error.ErrorCtor("Arborist idealTree missing inventory");
   }
   for (const node of inventory.values()) {
     if (node.isProjectRoot) {
@@ -93,7 +85,7 @@ function readTopLevelFromIdealTree(tree, targetName) {
     }
     if (node.name === targetName && node.depth === 1) {
       if (!node.version || !node.integrity) {
-        throw new import_primordials.ErrorCtor(
+        throw new import_error.ErrorCtor(
           `Arborist idealTree node for ${targetName} missing version/integrity`
         );
       }
@@ -104,19 +96,19 @@ function readTopLevelFromIdealTree(tree, targetName) {
       };
     }
   }
-  throw new import_primordials.ErrorCtor(
+  throw new import_error.ErrorCtor(
     `Arborist idealTree inventory has no top-level node for ${targetName}`
   );
 }
 async function safeIdealTree(options) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const { before, path: installPath, quiet = true } = options;
   const targetName = readSingleDependency(
     path.join(installPath, "package.json")
   );
   const arb = new import_arborist.default({
-    ...getBaseArboristOptions(installPath, quiet),
+    ...getBaseArboristOptions(installPath, { quiet }),
     ...before !== void 0 ? { before } : {},
     packageLockOnly: true,
     save: true
@@ -133,20 +125,20 @@ async function safeIdealTree(options) {
 async function safeReify(options) {
   const { packageLock = true, path: installPath, quiet = true } = options;
   const arb = new import_arborist.default({
-    ...getBaseArboristOptions(installPath, quiet),
+    ...getBaseArboristOptions(installPath, { quiet }),
     packageLock
   });
   await arb.reify();
 }
 async function writeSafeNpmrc(installPath, options) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const { minReleaseDays, minReleaseMins } = {
     __proto__: null,
     ...options
   };
   if (minReleaseDays !== void 0 && minReleaseMins !== void 0) {
-    throw new import_primordials.ErrorCtor(
+    throw new import_error.ErrorCtor(
       "writeSafeNpmrc: minReleaseDays and minReleaseMins are mutually exclusive"
     );
   }
@@ -159,10 +151,10 @@ async function writeSafeNpmrc(installPath, options) {
     "progress=false"
   ];
   if (minReleaseDays !== void 0) {
-    (0, import_primordials.ArrayPrototypePush)(lines, `min-release-age=${minReleaseDays}`);
+    (0, import_array.ArrayPrototypePush)(lines, `min-release-age=${minReleaseDays}`);
   }
   if (minReleaseMins !== void 0) {
-    (0, import_primordials.ArrayPrototypePush)(lines, `minimum-release-age=${minReleaseMins}`);
+    (0, import_array.ArrayPrototypePush)(lines, `minimum-release-age=${minReleaseMins}`);
   }
   await fs.promises.writeFile(
     path.join(installPath, ".npmrc"),
@@ -172,6 +164,9 @@ async function writeSafeNpmrc(installPath, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  getBaseArboristOptions,
+  readSingleDependency,
+  readTopLevelFromIdealTree,
   safeIdealTree,
   safeReify,
   writeSafeNpmrc

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

@@ -0,0 +1,108 @@
+/**
+ * @file On-disk cache metadata helpers for dlx binaries.
+ *
+ *   - `getDlxCachePath` — root of the binary cache (alias of getSocketDlxDir)
+ *   - `getBinaryCacheMetadataPath` — path to a cache entry's .dlx-metadata.json
+ *   - `isBinaryCacheValid` — TTL-based liveness check
+ *   - `writeBinaryCacheMetadata` — atomic write of cache metadata
+ *   - `cleanDlxCache` — TTL-based eviction sweep
+ *   - `listDlxCache` — enumerate cached binaries with their metadata Split out of
+ *     `dlx/binary.ts` for size hygiene.
+ */
+import { getSocketDlxDir } from '../paths/socket';
+import type { DlxMetadata } from './binary-types';
+/**
+ * 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)
+ *   ```
+ */
+export declare function cleanDlxCache(maxAge?: number): Promise<number>;
+/**
+ * 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;
+}>>;
+/**
+ * Read the DlxMetadata for a cached binary. Returns `undefined` when the
+ * metadata file is missing, unreadable, or doesn't match the expected shape.
+ * Useful for callers that want to recover the integrity / size / source URL of
+ * an already-cached download without re-fetching.
+ *
+ * @example
+ *   ```typescript
+ *   const meta = await readBinaryCacheMetadata(cacheEntryDir)
+ *   if (meta) {
+ *   console.log(`Pinned integrity: ${meta.integrity}`)
+ *   }
+ *   ```
+ */
+export declare function readBinaryCacheMetadata(cacheEntryPath: string): Promise<DlxMetadata | undefined>;
+/**
+ * Write metadata for a cached binary. Uses unified schema shared with C++
+ * decompressor and CLI dlxBinary.
+ *
+ * @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>;

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>;