@socketsecurity/lib 5.9.1 → 5.11.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.11.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.0) - 2026-03-23
+
+### Added
+
+- **http-request**: Checksum verification for secure downloads
+  - `parseChecksums(text)`: Parse checksums file text into filename→hash map
+    - Supports GNU style (`hash  filename`), BSD style (`SHA256 (file) = hash`), and single-space format
+    - Handles Windows CRLF and Unix LF line endings
+    - Returns null-prototype object to prevent prototype pollution
+  - `fetchChecksums(url, options?)`: Fetch and parse checksums from URL
+    - Supports `headers` and `timeout` options
+  - `httpDownload` now accepts `sha256` option to verify downloaded files
+    - Verification happens before atomic rename (file not saved if hash mismatches)
+    - Accepts uppercase hashes (normalized to lowercase internally)
+
+## [5.10.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.10.0) - 2026-03-14
+
+### Changed
+
+- **releases/socket-btm**: Refactored `downloadSocketBtmRelease()` API for caller-controlled download paths
+  - Tool name moved from config object to required first parameter
+  - Config object is now optional second parameter (was required)
+  - Removed automatic `/${toolName}/${platformArch}` directory nesting - callers now have full control over download directory structure
+  - All optional parameters in config types now explicitly typed as `| undefined`
+  - Migration example:
+    - Before: `downloadSocketBtmRelease({ tool: 'lief', downloadDir: 'build' })`
+    - After: `downloadSocketBtmRelease('lief', { downloadDir: 'build' })`
+  - Rationale: Previous automatic path nesting created unexpected directory structures (e.g., `build/downloaded/lief/darwin-arm64/lief/assets/`) making it impossible for callers to predict exact file locations
+
 ## [5.9.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.9.1) - 2026-03-14
 
 ### Fixed

package/dist/cache-with-ttl.js

@@ -99,7 +99,10 @@ function createTtlCache(options) {
         }
         return entry.data;
       }
-      await cacache.remove(fullKey);
+      try {
+        await cacache.remove(fullKey);
+      } catch {
+      }
     }
     return void 0;
   }
@@ -206,7 +209,10 @@ function createTtlCache(options) {
     }
     const fullKey = buildKey(key);
     memoCache.delete(fullKey);
-    await cacache.remove(fullKey);
+    try {
+      await cacache.remove(fullKey);
+    } catch {
+    }
   }
   async function deleteAll(pattern) {
     const fullPrefix = pattern ? `${opts.prefix}:${pattern}` : opts.prefix;

package/dist/http-request.d.ts

@@ -409,6 +409,29 @@ export interface HttpDownloadOptions {
      * ```
      */
     timeout?: number | undefined;
+    /**
+     * Expected SHA256 hash of the downloaded file.
+     * If provided, the download will fail if the computed hash doesn't match.
+     * The hash should be a lowercase hex string (64 characters).
+     *
+     * Use `fetchChecksums()` to fetch hashes from a checksums URL, then pass
+     * the specific hash here.
+     *
+     * @example
+     * ```ts
+     * // Verify download integrity with direct hash
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+     * })
+     *
+     * // Verify using checksums from a URL
+     * const checksums = await fetchChecksums('https://example.com/checksums.txt')
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   sha256: checksums['file.zip']
+     * })
+     * ```
+     */
+    sha256?: string | undefined;
 }
 /**
  * Result of a successful file download.
@@ -435,6 +458,86 @@ export interface HttpDownloadResult {
      */
     size: number;
 }
+/**
+ * Map of filenames to their SHA256 hashes.
+ * Keys are filenames (not paths), values are lowercase hex-encoded SHA256 hashes.
+ *
+ * @example
+ * ```ts
+ * const checksums: Checksums = {
+ *   'file.zip': 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+ *   'other.tar.gz': 'abc123...'
+ * }
+ * ```
+ */
+export type Checksums = Record<string, string>;
+/**
+ * Parse a checksums file text into a filename-to-hash map.
+ *
+ * Supports standard checksums file formats:
+ * - BSD style: "SHA256 (filename) = hash"
+ * - GNU style: "hash  filename" (two spaces)
+ * - Simple style: "hash filename" (single space)
+ *
+ * Lines starting with '#' are treated as comments and ignored.
+ * Empty lines are ignored.
+ *
+ * @param text - Raw text content of a checksums file
+ * @returns Map of filenames to lowercase SHA256 hashes
+ *
+ * @example
+ * ```ts
+ * const text = `
+ * # SHA256 checksums
+ * e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  file.zip
+ * abc123def456...  other.tar.gz
+ * `
+ * const checksums = parseChecksums(text)
+ * console.log(checksums['file.zip']) // 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ * ```
+ */
+export declare function parseChecksums(text: string): Checksums;
+/**
+ * Options for fetching checksums from a URL.
+ */
+export interface FetchChecksumsOptions {
+    /**
+     * HTTP headers to send with the request.
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number | undefined;
+}
+/**
+ * Fetch and parse a checksums file from a URL.
+ *
+ * This is useful for verifying downloads from GitHub releases which typically
+ * publish a checksums.txt file alongside release assets.
+ *
+ * @param url - URL to the checksums file
+ * @param options - Request options
+ * @returns Map of filenames to lowercase SHA256 hashes
+ * @throws {Error} When the checksums file cannot be fetched
+ *
+ * @example
+ * ```ts
+ * // Fetch checksums from GitHub release
+ * const checksums = await fetchChecksums(
+ *   'https://github.com/org/repo/releases/download/v1.0.0/checksums.txt'
+ * )
+ *
+ * // Use with httpDownload
+ * await httpDownload(
+ *   'https://github.com/org/repo/releases/download/v1.0.0/tool_linux.tar.gz',
+ *   '/tmp/tool.tar.gz',
+ *   { sha256: checksums['tool_linux.tar.gz'] }
+ * )
+ * ```
+ */
+export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
 /**
  * Download a file from a URL to a local path with redirect support, retry logic, and progress callbacks.
  * Uses streaming to avoid loading entire file in memory.

package/dist/http-request.js

@@ -19,10 +19,12 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var http_request_exports = {};
 __export(http_request_exports, {
+  fetchChecksums: () => fetchChecksums,
   httpDownload: () => httpDownload,
   httpJson: () => httpJson,
   httpRequest: () => httpRequest,
-  httpText: () => httpText
+  httpText: () => httpText,
+  parseChecksums: () => parseChecksums
 });
 module.exports = __toCommonJS(http_request_exports);
 var import_fs = require("./fs.js");
@@ -34,9 +36,17 @@ function getFs() {
   }
   return _fs;
 }
+let _crypto;
 let _http;
 let _https;
 // @__NO_SIDE_EFFECTS__
+function getCrypto() {
+  if (_crypto === void 0) {
+    _crypto = require("crypto");
+  }
+  return _crypto;
+}
+// @__NO_SIDE_EFFECTS__
 function getHttp() {
   if (_http === void 0) {
     _http = require("http");
@@ -50,6 +60,40 @@ function getHttps() {
   }
   return _https;
 }
+function parseChecksums(text) {
+  const checksums = { __proto__: null };
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const bsdMatch = trimmed.match(
+      /^SHA256\s+\((.+)\)\s+=\s+([a-fA-F0-9]{64})$/
+    );
+    if (bsdMatch) {
+      checksums[bsdMatch[1]] = bsdMatch[2].toLowerCase();
+      continue;
+    }
+    const gnuMatch = trimmed.match(/^([a-fA-F0-9]{64})\s+(.+)$/);
+    if (gnuMatch) {
+      checksums[gnuMatch[2]] = gnuMatch[1].toLowerCase();
+    }
+  }
+  return checksums;
+}
+async function fetchChecksums(url, options) {
+  const { headers = {}, timeout = 3e4 } = {
+    __proto__: null,
+    ...options
+  };
+  const response = await httpRequest(url, { headers, timeout });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch checksums from ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  return parseChecksums(response.body.toString("utf8"));
+}
 async function httpDownloadAttempt(url, destPath, options) {
   const {
     followRedirects = true,
@@ -292,6 +336,7 @@ async function httpDownload(url, destPath, options) {
     progressInterval = 10,
     retries = 0,
     retryDelay = 1e3,
+    sha256,
     timeout = 12e4
   } = { __proto__: null, ...options };
   let progressCallback;
@@ -324,6 +369,19 @@ async function httpDownload(url, destPath, options) {
         onProgress: progressCallback,
         timeout
       });
+      if (sha256) {
+        const crypto = /* @__PURE__ */ getCrypto();
+        const fileContent = await fs.promises.readFile(tempPath);
+        const computedHash = crypto.createHash("sha256").update(fileContent).digest("hex");
+        if (computedHash !== sha256.toLowerCase()) {
+          await (0, import_fs.safeDelete)(tempPath);
+          throw new Error(
+            `Checksum verification failed for ${url}
+Expected: ${sha256.toLowerCase()}
+Computed: ${computedHash}`
+          );
+        }
+      }
       await fs.promises.rename(tempPath, destPath);
       return {
         path: destPath,
@@ -440,8 +498,10 @@ async function httpText(url, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  fetchChecksums,
   httpDownload,
   httpJson,
   httpRequest,
-  httpText
+  httpText,
+  parseChecksums
 });

package/dist/releases/github.js

@@ -121,7 +121,7 @@ async function downloadGitHubRelease(config) {
   }
   const path = /* @__PURE__ */ getPath();
   const resolvedDownloadDir = path.isAbsolute(downloadDir) ? downloadDir : path.join(cwd, downloadDir);
-  const binaryDir = path.join(resolvedDownloadDir, toolName, platformArch);
+  const binaryDir = resolvedDownloadDir;
   const binaryPath = path.join(binaryDir, binaryName);
   const versionPath = path.join(binaryDir, ".version");
   const fs = /* @__PURE__ */ getFs();

package/dist/releases/socket-btm.d.ts

@@ -13,25 +13,23 @@ export interface SocketBtmAssetConfig {
     /** @internal Discriminator fields */
     bin?: never;
     /** Working directory (defaults to process.cwd()). */
-    cwd?: string;
+    cwd?: string | undefined;
     /** Download destination directory. @default 'build/downloaded' */
-    downloadDir?: string;
+    downloadDir?: string | undefined;
     /** @internal Discriminator fields */
     libc?: never;
     /** Output filename. @default resolved asset name */
-    output?: string;
+    output?: string | undefined;
     /** Suppress log messages. @default false */
-    quiet?: boolean;
+    quiet?: boolean | undefined;
     /** Remove macOS quarantine attribute after download. @default false */
-    removeMacOSQuarantine?: boolean;
+    removeMacOSQuarantine?: boolean | undefined;
     /** Specific release tag to download. */
-    tag?: string;
+    tag?: string | undefined;
     /** @internal Discriminator fields */
     targetArch?: never;
     /** @internal Discriminator fields */
     targetPlatform?: never;
-    /** Tool/package name for directory structure and release matching. */
-    tool: string;
 }
 /**
  * Configuration for downloading socket-btm binary releases.
@@ -40,25 +38,23 @@ export interface SocketBtmBinaryConfig {
     /** @internal Discriminator field */
     asset?: never;
     /** Binary/executable name (without extension). @default tool */
-    bin?: string;
+    bin?: string | undefined;
     /** Working directory (defaults to process.cwd()). */
-    cwd?: string;
+    cwd?: string | undefined;
     /** Download destination directory. @default 'build/downloaded' */
-    downloadDir?: string;
+    downloadDir?: string | undefined;
     /** Linux libc variant. Auto-detected if not specified. */
-    libc?: Libc;
+    libc?: Libc | undefined;
     /** Suppress log messages. @default false */
-    quiet?: boolean;
+    quiet?: boolean | undefined;
     /** Remove macOS quarantine attribute after download. @default true */
-    removeMacOSQuarantine?: boolean;
+    removeMacOSQuarantine?: boolean | undefined;
     /** Specific release tag to download. */
-    tag?: string;
+    tag?: string | undefined;
     /** Target architecture (defaults to current arch). */
-    targetArch?: Arch;
+    targetArch?: Arch | undefined;
     /** Target platform (defaults to current platform). */
-    targetPlatform?: Platform;
-    /** Tool/package name for directory structure and release matching. */
-    tool: string;
+    targetPlatform?: Platform | undefined;
 }
 /**
  * Configuration for downloading socket-btm releases (binary or asset).
@@ -74,10 +70,11 @@ export declare function detectLibc(): Libc | undefined;
 /**
  * Download a release from socket-btm.
  *
- * @param config - Download configuration
+ * @param tool - Tool/package name for release matching (e.g., 'lief', 'curl')
+ * @param options - Download configuration
  * @returns Path to the downloaded file
  */
-export declare function downloadSocketBtmRelease(config: SocketBtmReleaseConfig): Promise<string>;
+export declare function downloadSocketBtmRelease(tool: string, options: SocketBtmReleaseConfig | undefined): Promise<string>;
 /**
  * Get asset name for a socket-btm binary.
  *

package/dist/releases/socket-btm.js

@@ -69,16 +69,17 @@ function detectLibc() {
     return "glibc";
   }
 }
-async function downloadSocketBtmRelease(config) {
-  const { cwd, downloadDir, quiet = false, tag, tool } = config;
+async function downloadSocketBtmRelease(tool, options) {
+  const config = Object.assign(/* @__PURE__ */ Object.create(null), options);
+  const { cwd, downloadDir, quiet = false, tag } = config;
   const toolPrefix = `${tool}-`;
   let downloadConfig;
-  if ("asset" in config) {
-    const {
-      asset,
-      output,
-      removeMacOSQuarantine = false
-    } = config;
+  if (options && "asset" in options) {
+    const assetConfig = Object.assign(
+      /* @__PURE__ */ Object.create(null),
+      options
+    );
+    const { asset, output, removeMacOSQuarantine = false } = assetConfig;
     let resolvedAsset;
     let resolvedTag = tag;
     const isExactMatch = typeof asset === "string" && !asset.includes("*");
@@ -127,13 +128,17 @@ async function downloadSocketBtmRelease(config) {
       removeMacOSQuarantine
     };
   } else {
+    const binaryConfig = Object.assign(
+      /* @__PURE__ */ Object.create(null),
+      options
+    );
     const {
       bin,
       libc = detectLibc(),
       removeMacOSQuarantine = true,
       targetArch = (0, import_platform.getArch)(),
       targetPlatform = (0, import_platform.getPlatform)()
-    } = config;
+    } = binaryConfig;
     const baseName = bin || tool;
     const assetName = getBinaryAssetName(
       baseName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.9.1",
+  "version": "5.11.0",
   "packageManager": "pnpm@10.32.1",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",