@socketsecurity/lib 5.10.0 → 5.11.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.1) - 2026-03-24
+
+### Added
+
+- **dlx/binary**: Added `sha256` option to `dlxBinary()`, `downloadBinary()`, and `downloadBinaryFile()`
+  - Enables SHA-256 checksum verification for binary downloads via httpDownload
+  - Verification happens during download (fails early if checksum mismatches)
+  - Complements existing `integrity` option (SRI sha512 format, verified post-download)
+
+## [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

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/dlx/binary.d.ts

@@ -13,6 +13,12 @@ export interface DlxBinaryOptions {
      * Expected SRI integrity hash (sha512-<base64>) for verification.
      */
     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.
+     */
+    sha256?: string | undefined;
     /**
      * Cache TTL in milliseconds (default: 7 days).
      */
@@ -127,8 +133,14 @@ export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOpt
  * 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.
  */
-export declare function downloadBinaryFile(url: string, destPath: string, integrity?: string | undefined): Promise<string>;
+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.

package/dist/dlx/binary.js

@@ -111,6 +111,7 @@ async function dlxBinary(args, options, spawnExtra) {
     force: userForce = false,
     integrity,
     name,
+    sha256,
     spawnOptions,
     url,
     yes
@@ -168,7 +169,12 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
         { cause: e }
       );
     }
-    computedIntegrity = await downloadBinaryFile(url, binaryPath, integrity);
+    computedIntegrity = await downloadBinaryFile(
+      url,
+      binaryPath,
+      integrity,
+      sha256
+    );
     const stats = await fs.promises.stat(binaryPath);
     await writeBinaryCacheMetadata(
       cacheEntryDir,
@@ -200,6 +206,7 @@ async function downloadBinary(options) {
     force = false,
     integrity,
     name,
+    sha256,
     url
   } = { __proto__: null, ...options };
   const fs = /* @__PURE__ */ getFs();
@@ -240,7 +247,8 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
     const computedIntegrity = await downloadBinaryFile(
       url,
       binaryPath,
-      integrity
+      integrity,
+      sha256
     );
     const stats = await fs.promises.stat(binaryPath);
     await writeBinaryCacheMetadata(
@@ -257,7 +265,7 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
     downloaded
   };
 }
-async function downloadBinaryFile(url, destPath, integrity) {
+async function downloadBinaryFile(url, destPath, integrity, sha256) {
   const crypto = /* @__PURE__ */ getCrypto();
   const fs = /* @__PURE__ */ getFs();
   const path = /* @__PURE__ */ getPath();
@@ -275,7 +283,7 @@ async function downloadBinaryFile(url, destPath, integrity) {
         }
       }
       try {
-        await (0, import_http_request.httpDownload)(url, destPath);
+        await (0, import_http_request.httpDownload)(url, destPath, sha256 ? { sha256 } : void 0);
       } catch (e) {
         throw new Error(
           `Failed to download binary from ${url}

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.10.0",
-  "packageManager": "pnpm@10.32.1",
+  "version": "5.11.1",
+  "packageManager": "pnpm@10.33.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [
@@ -734,7 +734,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.3.5",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.9.0",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.11.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",