@socketsecurity/lib 6.0.5 → 6.0.7

package/dist/github/{fetch.js → request.js}

@@ -6,10 +6,11 @@ const require_primordials_date = require('../primordials/date.js');
 const require_primordials_json = require('../primordials/json.js');
 const require_errors_message = require('../errors/message.js');
 const require_http_request_request = require('../http-request/request.js');
+const require_env_github_status = require('../env/github-status.js');
 const require_github_errors = require('./errors.js');
 const require_github_token = require('./token.js');
 
-//#region src/github/fetch.ts
+//#region src/github/request.ts
 /**
 * @file Authenticated GitHub REST fetch. `fetchGitHub` is the single entry
 *   point that the rest of the github/ modules go through for REST calls. It
@@ -87,7 +88,7 @@ async function fetchGitHub(url, options) {
 		__proto__: null,
 		...options
 	};
-	const token = opts.token || require_github_token.getGitHubToken();
+	const token = opts.token ?? require_github_token.getGitHubToken();
 	const headers = {
 		Accept: "application/vnd.github.v3+json",
 		"User-Agent": "socket-registry-github-client",
@@ -110,6 +111,16 @@ async function fetchGitHub(url, options) {
 				throw error;
 			}
 		}
+		if (response.status >= 500) {
+			/* c8 ignore start - External status probe, non-deterministic */
+			const ghStatus = await require_env_github_status.probeGitHubStatus(4e3).catch(() => void 0);
+			/* c8 ignore stop */
+			let statusNote = "";
+			if (ghStatus) if (ghStatus.status === "unknown") statusNote = " (githubstatus.com unreachable — could not confirm platform health)";
+			else if (ghStatus.degraded) statusNote = `\nGitHub platform status at time of failure:\n${ghStatus.components.map((c) => `  ${c.name}: ${c.status}`).join("\n")}`;
+			else statusNote = "\nGitHub platform status: all monitored components operational — this may be a transient issue or a request-specific error.";
+			throw new require_primordials_error.ErrorCtor(`GitHub API error ${response.status}: ${response.statusText}.${statusNote}`);
+		}
 		throw new require_primordials_error.ErrorCtor(`GitHub API error ${response.status}: ${response.statusText}`);
 	}
 	if (response.body.byteLength === 0) throw new require_github_errors.GitHubEmptyBodyError(url);

package/dist/github/token.js

@@ -34,7 +34,7 @@ const require_env_socket_cli = require('../env/socket-cli.js');
 * @returns The first available GitHub token, or `undefined` if none found
 */
 function getGitHubToken() {
-	return /* @__PURE__ */ require_env_github.getGithubToken() || /* @__PURE__ */ require_env_github.getGhToken() || /* @__PURE__ */ require_env_socket_cli.getSocketCliGithubToken() || void 0;
+	return require_env_github.getGithubToken() || require_env_github.getGhToken() || require_env_socket_cli.getSocketCliGithubToken() || void 0;
 }
 /**
 * Get GitHub authentication token from git config. Reads the `github.token`

package/dist/github/types.d.ts

@@ -114,7 +114,7 @@ export interface GitHubTag {
          * Tagger's name.
          */
         name: string;
-    };
+    } | undefined;
     /**
      * API URL for this tag object.
      */

package/dist/globs/_internal.js

@@ -18,17 +18,15 @@ const require_node_fs_promises = require('../node/fs-promises.js');
 */
 const MATCHER_CACHE_MAX_SIZE = 100;
 const matcherCache = new require_primordials_map_set.MapCtor();
-let _fastGlob;
-let _picomatch;
-/* @__NO_SIDE_EFFECTS__ */
+let cachedFastGlob;
+let cachedPicomatch;
 function getFastGlob() {
-	if (_fastGlob === void 0) _fastGlob = /* @__PURE__ */ require("../external/fast-glob.js");
-	return _fastGlob;
+	if (cachedFastGlob === void 0) cachedFastGlob = /*@__PURE__*/ require("../external/fast-glob.js");
+	return cachedFastGlob;
 }
-/* @__NO_SIDE_EFFECTS__ */
 function getPicomatch() {
-	if (_picomatch === void 0) _picomatch = /* @__PURE__ */ require("../external/picomatch.js");
-	return _picomatch;
+	if (cachedPicomatch === void 0) cachedPicomatch = /*@__PURE__*/ require("../external/picomatch.js");
+	return cachedPicomatch;
 }
 /**
 * Glob results are normalized to forward slashes regardless of the backend
@@ -38,7 +36,7 @@ function getPicomatch() {
 * this stays consistent with every other path-shaped string in the lib.
 */
 function normalizeGlobResults(out) {
-	for (let i = 0; i < out.length; i += 1) out[i] = /* @__PURE__ */ require_paths_normalize.normalizePath(out[i]);
+	for (let i = 0; i < out.length; i += 1) out[i] = require_paths_normalize.normalizePath(out[i]);
 	return out;
 }
 /**

package/dist/globs/match.js

@@ -2,6 +2,7 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_node_fs = require('../node/fs.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_node_fs_promises = require('../node/fs-promises.js');
 const require_globs__internal = require('./_internal.js');
 const require_promises_resolvers = require('../promises/resolvers.js');
@@ -45,7 +46,7 @@ const require_promises_resolvers = require('../promises/resolvers.js');
 */
 function canUseNodeFsGlob(options) {
 	if (!options) return true;
-	for (const key of Object.keys(options)) if (key !== "cwd" && key !== "ignore") return false;
+	for (const key of require_primordials_object.ObjectKeys(options)) if (key !== "cwd" && key !== "ignore") return false;
 	return true;
 }
 /**
@@ -57,15 +58,14 @@ function canUseNodeFsGlob(options) {
 *   console.log(files) // ['src/index.ts', 'src/utils.ts']
 *   ```
 */
-/* @__NO_SIDE_EFFECTS__ */
 async function glob(patterns, options) {
 	const normalizedIgnore = require_globs__internal.normalizeIgnorePatterns(options?.ignore);
 	/* c8 ignore start */
-	if (canUseNodeFsGlob(options)) return require_globs__internal.normalizeGlobResults(await require_promises_resolvers.fromAsync((/* @__PURE__ */ require_node_fs_promises.getNodeFsPromises()).glob(patterns, {
+	if (canUseNodeFsGlob(options)) return require_globs__internal.normalizeGlobResults(await require_promises_resolvers.fromAsync(require_node_fs_promises.getNodeFsPromises().glob(patterns, {
 		...options?.cwd ? { cwd: options.cwd } : {},
 		...normalizedIgnore ? { exclude: normalizedIgnore } : {}
 	})));
-	return require_globs__internal.normalizeGlobResults(await (/* @__PURE__ */ require_globs__internal.getFastGlob()).glob(patterns, {
+	return require_globs__internal.normalizeGlobResults(await require_globs__internal.getFastGlob().glob(patterns, {
 		...options,
 		...normalizedIgnore ? { ignore: normalizedIgnore } : {}
 	}));
@@ -80,15 +80,14 @@ async function glob(patterns, options) {
 *   console.log(files) // ['package.json', 'tsconfig.json']
 *   ```
 */
-/* @__NO_SIDE_EFFECTS__ */
 function globSync(patterns, options) {
 	const normalizedIgnore = require_globs__internal.normalizeIgnorePatterns(options?.ignore);
 	/* c8 ignore start */
-	if (canUseNodeFsGlob(options)) return require_globs__internal.normalizeGlobResults([...(/* @__PURE__ */ require_node_fs.getNodeFs()).globSync(patterns, {
+	if (canUseNodeFsGlob(options)) return require_globs__internal.normalizeGlobResults([...require_node_fs.getNodeFs().globSync(patterns, {
 		...options?.cwd ? { cwd: options.cwd } : {},
 		...normalizedIgnore ? { exclude: normalizedIgnore } : {}
 	})]);
-	return require_globs__internal.normalizeGlobResults((/* @__PURE__ */ require_globs__internal.getFastGlob()).globSync(patterns, {
+	return require_globs__internal.normalizeGlobResults(require_globs__internal.getFastGlob().globSync(patterns, {
 		...options,
 		...normalizedIgnore ? { ignore: normalizedIgnore } : {}
 	}));

package/dist/globs/matcher.d.ts

@@ -30,9 +30,9 @@ import type { Pattern } from './types';
  *   ```
  */
 export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
-    dot?: boolean;
-    nocase?: boolean;
-    ignore?: string[];
+    dot?: boolean | undefined;
+    nocase?: boolean | undefined;
+    ignore?: string[] | undefined;
 }): (path: string) => boolean;
 /**
  * Resolve `path.matchesGlob` (or `undefined` if the runtime predates it).

package/dist/globs/matcher.js

@@ -3,8 +3,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_string = require('../primordials/string.js');
 const require_primordials_array = require('../primordials/array.js');
-const require_primordials_object = require('../primordials/object.js');
 const require_primordials_json = require('../primordials/json.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_globs__internal = require('./_internal.js');
 
 //#region src/globs/matcher.ts
@@ -14,8 +14,8 @@ const require_globs__internal = require('./_internal.js');
 *   `path.matchesGlob` for the rare case where the caller wants strict
 *   (`nocase: false`, `dot: false`) matching.
 */
-let _matchesGlob;
-let _matchesGlobProbed = false;
+let matchesGlobCache;
+let matchesGlobProbed = false;
 /**
 * Return a glob-matcher function, memoized by pattern + options.
 *
@@ -40,13 +40,12 @@ let _matchesGlobProbed = false;
 *   const isSource = getGlobMatcher(['src/**', '!**\/*.test.ts'])
 *   ```
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getGlobMatcher(glob, options) {
 	const patterns = require_primordials_array.ArrayIsArray(glob) ? glob : [glob];
-	const sortedPatterns = [...patterns].sort();
-	const sortedOptions = options ? require_primordials_object.ObjectKeys(options).sort().map((k) => {
+	const sortedPatterns = [...patterns].toSorted();
+	const sortedOptions = options ? require_primordials_object.ObjectKeys(options).toSorted().map((k) => {
 		const value = options[k];
-		return `${k}:${require_primordials_json.JSONStringify(require_primordials_array.ArrayIsArray(value) ? [...value].sort() : value)}`;
+		return `${k}:${require_primordials_json.JSONStringify(require_primordials_array.ArrayIsArray(value) ? [...value].toSorted() : value)}`;
 	}).join(",") : "";
 	const key = `${sortedPatterns.join("|")}:${sortedOptions}`;
 	const existing = require_globs__internal.matcherCache.get(key);
@@ -64,7 +63,7 @@ function getGlobMatcher(glob, options) {
 	let matcher;
 	/* c8 ignore start */
 	if (patterns.length === 1 && !require_primordials_string.StringPrototypeStartsWith(patterns[0], "!") && options !== void 0 && options.nocase === false && options.dot === false && (options.ignore === void 0 || options.ignore.length === 0)) {
-		const matchesGlob = /* @__PURE__ */ getMatchesGlob();
+		const matchesGlob = getMatchesGlob();
 		if (matchesGlob !== void 0) {
 			const pattern = patterns[0];
 			matcher = (p) => matchesGlob(p, pattern);
@@ -80,7 +79,7 @@ function getGlobMatcher(glob, options) {
 			...options,
 			...negativePatterns.length > 0 ? { ignore: negativePatterns } : {}
 		};
-		matcher = (/* @__PURE__ */ require_globs__internal.getPicomatch())(positivePatterns.length > 0 ? positivePatterns : patterns, matchOptions);
+		matcher = require_globs__internal.getPicomatch()(positivePatterns.length > 0 ? positivePatterns : patterns, matchOptions);
 	}
 	require_globs__internal.matcherCache.set(key, matcher);
 	return matcher;
@@ -94,16 +93,15 @@ function getGlobMatcher(glob, options) {
 *
 * @internal
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getMatchesGlob() {
-	if (!_matchesGlobProbed) {
+	if (!matchesGlobProbed) {
 		const fn = (/* @__PURE__ */ require("node:path")).matchesGlob;
 		/* c8 ignore start */
-		if (typeof fn === "function") _matchesGlob = fn;
+		if (typeof fn === "function") matchesGlobCache = fn;
 		/* c8 ignore stop */
-		_matchesGlobProbed = true;
+		matchesGlobProbed = true;
 	}
-	return _matchesGlob;
+	return matchesGlobCache;
 }
 
 //#endregion

package/dist/globs/stream.js

@@ -23,7 +23,6 @@ const require_paths_globs = require('../paths/globs.js');
 *   }
 *   ```
 */
-/* @__NO_SIDE_EFFECTS__ */
 function globStreamLicenses(dirname, options) {
 	const { ignore: ignoreOpt, ignoreOriginals, recursive, ...globOptions } = {
 		__proto__: null,
@@ -31,7 +30,7 @@ function globStreamLicenses(dirname, options) {
 	};
 	const ignore = [...require_primordials_array.ArrayIsArray(ignoreOpt) ? require_globs__internal.normalizeIgnorePatterns(ignoreOpt) : require_globs_defaults.defaultIgnore, "**/*.{cjs,cts,js,json,mjs,mts,ts}"];
 	if (ignoreOriginals) ignore.push(require_paths_globs.LICENSE_ORIGINAL_GLOB_RECURSIVE);
-	return (/* @__PURE__ */ require_globs__internal.getFastGlob()).globStream([recursive ? require_paths_globs.LICENSE_GLOB_RECURSIVE : require_paths_globs.LICENSE_GLOB], {
+	return require_globs__internal.getFastGlob().globStream([recursive ? require_paths_globs.LICENSE_GLOB_RECURSIVE : require_paths_globs.LICENSE_GLOB], {
 		__proto__: null,
 		absolute: true,
 		caseSensitiveMatch: false,

package/dist/globs/types.d.ts

@@ -6,30 +6,30 @@
  */
 export type Pattern = string;
 export interface FastGlobOptions {
-    absolute?: boolean;
-    baseNameMatch?: boolean;
-    braceExpansion?: boolean;
-    caseSensitiveMatch?: boolean;
-    concurrency?: number;
-    cwd?: string;
-    deep?: number;
-    dot?: boolean;
-    extglob?: boolean;
-    followSymbolicLinks?: boolean;
-    fs?: unknown;
-    globstar?: boolean;
-    ignore?: string[];
-    ignoreFiles?: string[];
-    markDirectories?: boolean;
-    objectMode?: boolean;
-    onlyDirectories?: boolean;
-    onlyFiles?: boolean;
-    stats?: boolean;
-    suppressErrors?: boolean;
-    throwErrorOnBrokenSymbolicLink?: boolean;
-    unique?: boolean;
+    absolute?: boolean | undefined;
+    baseNameMatch?: boolean | undefined;
+    braceExpansion?: boolean | undefined;
+    caseSensitiveMatch?: boolean | undefined;
+    concurrency?: number | undefined;
+    cwd?: string | undefined;
+    deep?: number | undefined;
+    dot?: boolean | undefined;
+    extglob?: boolean | undefined;
+    followSymbolicLinks?: boolean | undefined;
+    fs?: unknown | undefined;
+    globstar?: boolean | undefined;
+    ignore?: string[] | undefined;
+    ignoreFiles?: string[] | undefined;
+    markDirectories?: boolean | undefined;
+    objectMode?: boolean | undefined;
+    onlyDirectories?: boolean | undefined;
+    onlyFiles?: boolean | undefined;
+    stats?: boolean | undefined;
+    suppressErrors?: boolean | undefined;
+    throwErrorOnBrokenSymbolicLink?: boolean | undefined;
+    unique?: boolean | undefined;
 }
 export interface GlobOptions extends FastGlobOptions {
-    ignoreOriginals?: boolean;
-    recursive?: boolean;
+    ignoreOriginals?: boolean | undefined;
+    recursive?: boolean | undefined;
 }

package/dist/http-request/_internal.d.ts

@@ -2,7 +2,7 @@
  * @file Private lazy loaders for the Node.js modules used by the
  *   `http-request/*` leaves. The `_` prefix keeps this module out of the
  *   generated package.json `exports` map (the `dist/**\/_*` ignore pattern in
- *   `scripts/fix/generate-package-exports.mts` filters it out), so it is not
+ *   `scripts/post-build/make-package-exports.mts` filters it out), so it is not
  *   part of the public surface — it exists only as a re-export shim so existing
  *   siblings keep working unchanged. New code should import the canonical
  *   helpers directly:

package/dist/http-request/browser.js

@@ -1,7 +1,15 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_math = require('../primordials/math.js');
+const require_primordials_string = require('../primordials/string.js');
+const require_primordials_array = require('../primordials/array.js');
+const require_primordials_date = require('../primordials/date.js');
+const require_primordials_json = require('../primordials/json.js');
+const require_primordials_promise = require('../primordials/promise.js');
 const require_http_request_browser_fetch = require('./browser-fetch.js');
+const require_primordials_headers = require('../primordials/headers.js');
 
 //#region src/http-request/browser.ts
 /**
@@ -75,7 +83,7 @@ async function attempt(url, options) {
 	if (options.followRedirects === false) init.redirect = "manual";
 	const { signal, cleanup } = combineSignals(options.signal, options.timeout);
 	if (signal) init.signal = signal;
-	const startedAt = Date.now();
+	const startedAt = require_primordials_date.DateNow();
 	if (options.hooks?.onRequest) options.hooks.onRequest({
 		method,
 		url,
@@ -85,13 +93,13 @@ async function attempt(url, options) {
 	try {
 		const response = await require_http_request_browser_fetch.doFetch(url, init);
 		const buffer = await response.arrayBuffer();
-		if (options.maxResponseSize !== void 0 && buffer.byteLength > options.maxResponseSize) throw new Error(`Response body (${buffer.byteLength} bytes) exceeds maxResponseSize (${options.maxResponseSize})`);
-		const body = new Uint8Array(buffer);
+		if (options.maxResponseSize !== void 0 && buffer.byteLength > options.maxResponseSize) throw new require_primordials_error.ErrorCtor(`Response body (${buffer.byteLength} bytes) exceeds maxResponseSize (${options.maxResponseSize})`);
+		const body = new require_primordials_array.Uint8ArrayCtor(buffer);
 		const headers = headersToRecord(response.headers);
 		if (options.hooks?.onResponse) options.hooks.onResponse({
 			method,
 			url,
-			duration: Date.now() - startedAt,
+			duration: require_primordials_date.DateNow() - startedAt,
 			status: response.status,
 			statusText: response.statusText,
 			headers
@@ -110,15 +118,15 @@ async function attempt(url, options) {
 				return decodeText(body);
 			},
 			json() {
-				return JSON.parse(decodeText(body));
+				return require_primordials_json.JSONParse(decodeText(body));
 			}
 		};
 	} catch (err) {
 		if (options.hooks?.onResponse) options.hooks.onResponse({
 			method,
 			url,
-			duration: Date.now() - startedAt,
-			error: err instanceof Error ? err : new Error(String(err))
+			duration: require_primordials_date.DateNow() - startedAt,
+			error: err instanceof Error ? err : new require_primordials_error.ErrorCtor(String(err))
 		});
 		throw err;
 	} finally {
@@ -130,8 +138,8 @@ function decodeText(bytes) {
 }
 function headersToRecord(headers) {
 	const out = {};
-	headers.forEach((value, key) => {
-		out[key.toLowerCase()] = value;
+	require_primordials_headers.HeadersPrototypeForEach(headers, (value, key) => {
+		out[require_primordials_string.StringPrototypeToLowerCase(key)] = value;
 	});
 	return out;
 }
@@ -166,7 +174,7 @@ async function httpRequest(url, options) {
 	for (let i = 0; i < maxAttempts; i++) try {
 		const response = await attempt(url, opts);
 		if (response.status >= 500 && i + 1 < maxAttempts) {
-			await sleep(baseDelay * Math.pow(2, i));
+			await sleep(baseDelay * require_primordials_math.MathPow(2, i));
 			continue;
 		}
 		if (opts.throwOnError && !response.ok) throw new HttpResponseError(response);
@@ -175,11 +183,11 @@ async function httpRequest(url, options) {
 		lastError = err;
 		if (err instanceof HttpResponseError) throw err;
 		if (i + 1 < maxAttempts) {
-			await sleep(baseDelay * Math.pow(2, i));
+			await sleep(baseDelay * require_primordials_math.MathPow(2, i));
 			continue;
 		}
 	}
-	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error(`HTTP request to ${url} failed`);
+	throw lastError instanceof Error ? lastError : new require_primordials_error.ErrorCtor(`HTTP request to ${url} failed`);
 }
 /**
 * GET / POST a text endpoint. Throws `HttpResponseError` on non-2xx.
@@ -191,7 +199,7 @@ async function httpText(url, options) {
 	})).text();
 }
 function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+	return new require_primordials_promise.PromiseCtor((resolve) => setTimeout(resolve, ms));
 }
 
 //#endregion

package/dist/http-request/checksum-file.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file Checksum file fetching + parsing for download verification.
+ *   `parseChecksumFile` understands the three common text-file shapes:
+ *
+ *   - BSD style: `SHA256 (filename) = hash`
+ *   - GNU style: `hash filename` (two spaces)
+ *   - Simple: `hash filename` (single space) Comment lines (`#…`) and blank lines
+ *     are skipped. Each hex digest is converted to an SRI integrity string
+ *     (`sha256-<base64>=`) so callers always work in the same format as
+ *     `external-tools.json` and other integrity-string consumers.
+ *     `fetchChecksumFile` is the URL helper — fetches via `httpRequest` and
+ *     runs the body through `parseChecksumFile`.
+ */
+import type { ChecksumFile, FetchChecksumFileOptions } from './download-types';
+/**
+ * Fetch and parse a checksums file from a URL.
+ *
+ * Returns a map of filenames to SRI integrity strings (`sha256-<base64>=`).
+ * Feed `httpDownload({ sha256 })` by converting back to hex via
+ * `integrityToChecksum()`; pass the SRI string through verbatim to consumers
+ * that accept SRI directly.
+ *
+ * @example
+ *   ;```ts
+ *   import { integrityToChecksum } from '@socketsecurity/lib/integrity'
+ *
+ *   const sums = await fetchChecksumFile(
+ *     'https://github.com/org/repo/releases/download/v1.0.0/checksums.txt',
+ *   )
+ *   await httpDownload(url, '/tmp/tool.tar.gz', {
+ *     sha256: integrityToChecksum(sums['tool_linux.tar.gz']!),
+ *   })
+ *   ```
+ */
+export declare function fetchChecksumFile(url: string, options?: FetchChecksumFileOptions | undefined): Promise<ChecksumFile>;
+/**
+ * Parse a checksums file text into a filename-to-integrity 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. Each 64-char hex digest is converted to an SRI integrity string so
+ * the result is uniform regardless of source format.
+ *
+ * @example
+ *   ;```ts
+ *   const sums = parseChecksumFile(
+ *     'e3b0c44...  file.zip\nSHA256 (other.tar.gz) = abc123...\n',
+ *   )
+ *   // sums['file.zip'] === 'sha256-47DEQpj8HBSa+/...'
+ *   ```
+ */
+export declare function parseChecksumFile(text: string): ChecksumFile;

package/dist/http-request/checksum-file.js

@@ -0,0 +1,95 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_integrity = require('../integrity.js');
+const require_primordials_string = require('../primordials/string.js');
+const require_http_request_request = require('./request.js');
+
+//#region src/http-request/checksum-file.ts
+/**
+* @file Checksum file fetching + parsing for download verification.
+*   `parseChecksumFile` understands the three common text-file shapes:
+*
+*   - BSD style: `SHA256 (filename) = hash`
+*   - GNU style: `hash filename` (two spaces)
+*   - Simple: `hash filename` (single space) Comment lines (`#…`) and blank lines
+*     are skipped. Each hex digest is converted to an SRI integrity string
+*     (`sha256-<base64>=`) so callers always work in the same format as
+*     `external-tools.json` and other integrity-string consumers.
+*     `fetchChecksumFile` is the URL helper — fetches via `httpRequest` and
+*     runs the body through `parseChecksumFile`.
+*/
+const CHECKSUM_BSD_RE = /^SHA256\s+\((.+)\)\s+=\s+([a-fA-F0-9]{64})$/;
+const CHECKSUM_GNU_RE = /^([a-fA-F0-9]{64})\s+(.+)$/;
+/**
+* Fetch and parse a checksums file from a URL.
+*
+* Returns a map of filenames to SRI integrity strings (`sha256-<base64>=`).
+* Feed `httpDownload({ sha256 })` by converting back to hex via
+* `integrityToChecksum()`; pass the SRI string through verbatim to consumers
+* that accept SRI directly.
+*
+* @example
+*   ;```ts
+*   import { integrityToChecksum } from '@socketsecurity/lib/integrity'
+*
+*   const sums = await fetchChecksumFile(
+*     'https://github.com/org/repo/releases/download/v1.0.0/checksums.txt',
+*   )
+*   await httpDownload(url, '/tmp/tool.tar.gz', {
+*     sha256: integrityToChecksum(sums['tool_linux.tar.gz']!),
+*   })
+*   ```
+*/
+async function fetchChecksumFile(url, options) {
+	const { ca, headers = {}, timeout = 3e4 } = {
+		__proto__: null,
+		...options
+	};
+	const response = await require_http_request_request.httpRequest(url, {
+		ca,
+		headers,
+		timeout
+	});
+	if (!response.ok) throw new require_primordials_error.ErrorCtor(`Failed to fetch checksums from ${url}: ${response.status} ${response.statusText}`);
+	return parseChecksumFile(response.body.toString("utf8"));
+}
+/**
+* Parse a checksums file text into a filename-to-integrity 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. Each 64-char hex digest is converted to an SRI integrity string so
+* the result is uniform regardless of source format.
+*
+* @example
+*   ;```ts
+*   const sums = parseChecksumFile(
+*     'e3b0c44...  file.zip\nSHA256 (other.tar.gz) = abc123...\n',
+*   )
+*   // sums['file.zip'] === 'sha256-47DEQpj8HBSa+/...'
+*   ```
+*/
+function parseChecksumFile(text) {
+	const result = { __proto__: null };
+	for (const line of require_primordials_string.StringPrototypeSplit(text, "\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || require_primordials_string.StringPrototypeStartsWith(trimmed, "#")) continue;
+		const bsdMatch = CHECKSUM_BSD_RE.exec(trimmed);
+		if (bsdMatch) {
+			result[bsdMatch[1]] = require_integrity.checksumToIntegrity(bsdMatch[2].toLowerCase());
+			continue;
+		}
+		const gnuMatch = CHECKSUM_GNU_RE.exec(trimmed);
+		if (gnuMatch) result[gnuMatch[2]] = require_integrity.checksumToIntegrity(gnuMatch[1].toLowerCase());
+	}
+	return result;
+}
+
+//#endregion
+exports.fetchChecksumFile = fetchChecksumFile;
+exports.parseChecksumFile = parseChecksumFile;

package/dist/http-request/download-types.d.ts

@@ -3,7 +3,7 @@
  *   `http-request/types.ts` for size hygiene.
  *
  *   - `HttpDownloadOptions` / `HttpDownloadResult` — file-download surface
- *   - `Checksums` / `FetchChecksumsOptions` — checksum-file helpers
+ *   - `ChecksumFile` / `FetchChecksumFileOptions` — checksum-file helpers
  */
 import type { IncomingHttpHeaders } from 'node:http';
 import type { Logger } from '../logger/node';
@@ -136,23 +136,14 @@ export interface HttpDownloadOptions {
      * 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.
+     * Pair with `fetchChecksumFile()` + `integrityToChecksum()` when working from
+     * a checksums URL, since `fetchChecksumFile()` returns SRI strings.
      *
      * @example
      *   ;```ts
-     *   // Verify download integrity with direct hash
+     *   // Verify download with a sha256 hex digest
      *   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: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
      *   })
      *   ```
      */
@@ -189,23 +180,24 @@ export interface HttpDownloadResult {
     statusText: string;
 }
 /**
- * Map of filenames to their SHA256 hashes. Keys are filenames (not paths),
- * values are lowercase hex-encoded SHA256 hashes.
+ * Map of filenames to SRI integrity strings (`sha256-<base64>=`). Returned by
+ * `parseChecksumFile` / `fetchChecksumFile`. Pass through
+ * `integrityToChecksum()` to feed `httpDownload({ sha256 })`, or pass the SRI
+ * string directly to consumers that accept SRI.
  *
  * @example
  *   ;```ts
- *   const checksums: Checksums = {
- *     'file.zip':
- *       'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
- *     'other.tar.gz': 'abc123...',
+ *   const sums: ChecksumFile = {
+ *     'file.zip': 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=',
+ *     'other.tar.gz': 'sha256-...',
  *   }
  *   ```
  */
-export type Checksums = Record<string, string>;
+export type ChecksumFile = Record<string, string>;
 /**
- * Options for fetching checksums from a URL.
+ * Options for fetching a checksum file from a URL.
  */
-export interface FetchChecksumsOptions {
+export interface FetchChecksumFileOptions {
     /**
      * Custom CA certificates for TLS connections. See `HttpRequestOptions.ca` for
      * details.