@socketsecurity/lib 6.0.8 → 6.0.10

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

@@ -2,8 +2,8 @@
 /* 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_integrity = require('../integrity.js');
 const require_http_request_request = require('./request.js');
 
 //#region src/http-request/checksum-file.ts

package/dist/http-request/download.js

@@ -168,6 +168,8 @@ async function httpDownloadAttempt(url, destPath, options) {
 			})();
 		};
 		fileStream.on("error", (error) => {
+			res.unpipe(fileStream);
+			res.destroy();
 			fileStream.destroy();
 			cleanupPartial();
 			reject(new require_primordials_error.ErrorCtor(`Failed to write file: ${error.message}`, { cause: error }));

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

@@ -13,7 +13,7 @@
  * Build an HTTP Basic `Authorization` header value from a Socket API token.
  *
  * The Socket API uses the token as the username with an empty password, so the
- * credential pair is `<token>:`. Centralized here so every fleet caller emits
+ * credential pair is `<token>:`. Centralized here so every Socket caller emits
  * the identical shape instead of hand-rolling `btoa(\`${token}:`)`.
  *
  * @example

package/dist/http-request/headers.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_primordials_number = require('../primordials/number.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_number = require('../primordials/number.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_primordials_date = require('../primordials/date.js');
 const require_primordials_globals = require('../primordials/globals.js');
@@ -24,7 +24,7 @@ const RETRY_AFTER_INT_RE = /^\d+$/;
 * Build an HTTP Basic `Authorization` header value from a Socket API token.
 *
 * The Socket API uses the token as the username with an empty password, so the
-* credential pair is `<token>:`. Centralized here so every fleet caller emits
+* credential pair is `<token>:`. Centralized here so every Socket caller emits
 * the identical shape instead of hand-rolling `btoa(\`${token}:`)`.
 *
 * @example

package/dist/http-request/request-attempt.js

@@ -118,7 +118,7 @@ async function httpRequestAttempt(url, options) {
 				let redirectHeaders = headers;
 				if (new require_primordials_url.URLCtor(url).origin !== redirectParsed.origin) {
 					redirectHeaders = { __proto__: null };
-					const stripped = new Set([
+					const stripped = /* @__PURE__ */ new Set([
 						"authorization",
 						"cookie",
 						"proxy-authenticate",
@@ -173,7 +173,9 @@ async function httpRequestAttempt(url, options) {
 				if (maxResponseSize && totalBytes > maxResponseSize) {
 					res.destroy();
 					request.destroy();
-					rejectOnce(new require_primordials_error.ErrorCtor(`Response exceeds maximum size limit (${(totalBytes / (1024 * 1024)).toFixed(2)}MB > ${(maxResponseSize / (1024 * 1024)).toFixed(2)}MB)`));
+					const sizeMB = (totalBytes / (1024 * 1024)).toFixed(2);
+					const maxMB = (maxResponseSize / (1024 * 1024)).toFixed(2);
+					rejectOnce(new require_primordials_error.ErrorCtor(`Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`));
 					return;
 				}
 				chunks.push(chunk);
@@ -213,7 +215,8 @@ async function httpRequestAttempt(url, options) {
 			});
 		});
 		request.on("error", (error) => {
-			rejectOnce(new require_primordials_error.ErrorCtor(require_http_request_errors.enrichErrorMessage(url, method, error), { cause: error }));
+			const message = require_http_request_errors.enrichErrorMessage(url, method, error);
+			rejectOnce(new require_primordials_error.ErrorCtor(message, { cause: error }));
 		});
 		request.on("timeout", () => {
 			request.destroy();

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

@@ -199,7 +199,7 @@ export interface HttpRequestOptions {
     onRetry?: ((attempt: number, error: unknown, delay: number) => boolean | number | undefined) | undefined;
     /**
      * Number of retry attempts for failed requests. Uses exponential backoff:
-     * delay = `retryDelay` * 2^attempt.
+     * delay = min(`retryDelay` * 2^attempt, `retryDelayMax`).
      *
      * @default 0
      */
@@ -211,6 +211,15 @@ export interface HttpRequestOptions {
      * @default 1000
      */
     retryDelay?: number | undefined;
+    /**
+     * Maximum delay in milliseconds for a single backoff wait. Caps the
+     * exponential growth (`retryDelay` * 2^attempt) so a high `retries` count
+     * can't produce multi-minute waits. An explicit `onRetry`-returned delay is
+     * not capped — that is the caller's deliberate choice.
+     *
+     * @default 30000
+     */
+    retryDelayMax?: number | undefined;
     /**
      * AbortSignal forwarded to the underlying `http.request` / `https.request`
      * call. Supported in Node 22+ via `node:http` request options. When both

package/dist/http-request/request.js

@@ -65,7 +65,7 @@ let node_timers_promises = require("node:timers/promises");
 *   non-retryable error happens.
 */
 async function httpRequest(url, options) {
-	const { body, ca, followRedirects = true, headers = {}, hooks, maxRedirects = 5, maxResponseSize, method = "GET", onRetry, retries = 0, retryDelay = 1e3, signal, stream = false, throwOnError = false, timeout = 3e4 } = {
+	const { body, ca, followRedirects = true, headers = {}, hooks, maxRedirects = 5, maxResponseSize, method = "GET", onRetry, retries = 0, retryDelay = 1e3, retryDelayMax = 3e4, signal, stream = false, throwOnError = false, timeout = 3e4 } = {
 		__proto__: null,
 		...options
 	};
@@ -104,7 +104,7 @@ async function httpRequest(url, options) {
 			lastError = e;
 			if (attempt === retries) break;
 			if (signal?.aborted) break;
-			const delayMs = retryDelay * 2 ** attempt;
+			const delayMs = require_primordials_math.MathMin(retryDelay * 2 ** attempt, retryDelayMax);
 			if (onRetry) {
 				const retryResult = onRetry(attempt + 1, e, delayMs);
 				if (retryResult === false) break;

package/dist/http-request/user-agent.d.ts

@@ -3,7 +3,7 @@
  *   Three-token format aligned with socket-cli's `getCliUserAgent` and
  *   coana-tech-cli's `configureAxiosUserAgent`: `<slug>/<version>
  *   node/<node-version> <platform>/<arch>` e.g. `socketsecurity-lib/6.0.0
- *   node/v22.10.0 darwin/arm64` Downstream callers (sdxgen SEA binary, fleet
+ *   node/v22.10.0 darwin/arm64` Downstream callers (sdxgen SEA binary, Socket
  *   CLIs, etc.) can identify themselves via the `SOCKET_CALLER_USER_AGENT` env
  *   var, which is appended to the lib's own UA so the server still sees the lib
  *   identifier. @example import { getSocketCallerUserAgent } from
@@ -16,7 +16,7 @@
  *
  * Used directly by socket-lib's own outbound requests (via
  * `getSocketCallerUserAgent`) and exported for sibling packages (socket-cli,
- * socket-sdk-js) so the fleet emits one canonical UA shape.
+ * socket-sdk-js) so Socket emits one canonical UA shape.
  *
  * @example
  *   ;```typescript
@@ -31,6 +31,18 @@ export declare function buildUserAgent(pkg: {
     name: string;
     version: string;
 }, caller?: string | undefined): string;
+/**
+ * Chain User-Agent fragments into a breadcrumb trail, ordered identity → hop
+ * (the immediate agent first, each forwarded caller after) so it reads
+ * left-to-right and a server's UA parser buckets by the immediate agent. Each
+ * fragment is sanitized; empties are dropped; an immediately-repeated fragment
+ * is collapsed so re-proxying doesn't stutter the same hop twice.
+ *
+ * @example
+ *   chainUserAgents(['socketsecurity-firewall-api-proxy/0.0.0', 'vlt/1.2.3'])
+ *   // 'socketsecurity-firewall-api-proxy/0.0.0 vlt/1.2.3'
+ */
+export declare function chainUserAgents(parts: ReadonlyArray<string | undefined>): string;
 /**
  * User-Agent header for socket-lib's own outbound HTTP requests.
  *
@@ -53,3 +65,12 @@ export declare function buildUserAgent(pkg: {
  *   ```
  */
 export declare function getSocketCallerUserAgent(): string;
+/**
+ * Sanitize a single User-Agent fragment for safe inclusion in an outgoing HTTP
+ * header. A caller identifier (`SOCKET_CALLER_USER_AGENT`, or a UA a proxy
+ * forwards on behalf of its client) is untrusted, so strip control chars (C0
+ * incl. CR/LF — the header- and log-injection vector — DEL, and C1), collapse
+ * internal whitespace to one space, trim, and cap length. Returns '' for
+ * nullish / blank / all-control input.
+ */
+export declare function sanitizeUserAgent(value: string | undefined): string;

package/dist/http-request/user-agent.js

@@ -2,7 +2,9 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_primordials_string = require('../primordials/string.js');
 const require_env_rewire = require('../env/rewire.js');
+const require_primordials_array = require('../primordials/array.js');
 const require_constants_socket = require('../constants/socket.js');
 const require_packages_specs = require('../packages/specs.js');
 let node_process = require("node:process");
@@ -14,20 +16,22 @@ node_process = require_runtime.__toESM(node_process);
 *   Three-token format aligned with socket-cli's `getCliUserAgent` and
 *   coana-tech-cli's `configureAxiosUserAgent`: `<slug>/<version>
 *   node/<node-version> <platform>/<arch>` e.g. `socketsecurity-lib/6.0.0
-*   node/v22.10.0 darwin/arm64` Downstream callers (sdxgen SEA binary, fleet
+*   node/v22.10.0 darwin/arm64` Downstream callers (sdxgen SEA binary, Socket
 *   CLIs, etc.) can identify themselves via the `SOCKET_CALLER_USER_AGENT` env
 *   var, which is appended to the lib's own UA so the server still sees the lib
 *   identifier. @example import { getSocketCallerUserAgent } from
 *   '@socketsecurity/lib/http-request/user-agent'
 *   request.setHeader('User-Agent', getSocketCallerUserAgent())
 */
+const MAX_USER_AGENT_LENGTH = 256;
+let cachedBaseUserAgent;
 /**
 * Compose a three-token User-Agent string from a `{ name, version }` pair,
 * optionally appending a caller-supplied identifier.
 *
 * Used directly by socket-lib's own outbound requests (via
 * `getSocketCallerUserAgent`) and exported for sibling packages (socket-cli,
-* socket-sdk-js) so the fleet emits one canonical UA shape.
+* socket-sdk-js) so Socket emits one canonical UA shape.
 *
 * @example
 *   ;```typescript
@@ -40,9 +44,27 @@ node_process = require_runtime.__toESM(node_process);
 */
 function buildUserAgent(pkg, caller) {
 	const base = `${require_packages_specs.pkgNameToSlug(pkg.name)}/${pkg.version} node/${node_process.default.version} ${node_process.default.platform}/${node_process.default.arch}`;
-	return caller ? `${base} ${caller}` : base;
+	return caller ? chainUserAgents([base, caller]) : base;
+}
+/**
+* Chain User-Agent fragments into a breadcrumb trail, ordered identity → hop
+* (the immediate agent first, each forwarded caller after) so it reads
+* left-to-right and a server's UA parser buckets by the immediate agent. Each
+* fragment is sanitized; empties are dropped; an immediately-repeated fragment
+* is collapsed so re-proxying doesn't stutter the same hop twice.
+*
+* @example
+*   chainUserAgents(['socketsecurity-firewall-api-proxy/0.0.0', 'vlt/1.2.3'])
+*   // 'socketsecurity-firewall-api-proxy/0.0.0 vlt/1.2.3'
+*/
+function chainUserAgents(parts) {
+	const trail = [];
+	for (let i = 0, { length } = parts; i < length; i += 1) {
+		const clean = sanitizeUserAgent(parts[i]);
+		if (clean && trail[trail.length - 1] !== clean) require_primordials_array.ArrayPrototypePush(trail, clean);
+	}
+	return require_primordials_array.ArrayPrototypeJoin(trail, " ");
 }
-let cachedBaseUserAgent;
 /**
 * User-Agent header for socket-lib's own outbound HTTP requests.
 *
@@ -70,9 +92,29 @@ function getSocketCallerUserAgent() {
 		version: require_constants_socket.SOCKET_LIB_VERSION
 	});
 	const caller = require_env_rewire.getEnvValue("SOCKET_CALLER_USER_AGENT");
-	return caller?.trim() ? `${cachedBaseUserAgent} ${caller}` : cachedBaseUserAgent;
+	return chainUserAgents([cachedBaseUserAgent, caller]);
+}
+/**
+* Sanitize a single User-Agent fragment for safe inclusion in an outgoing HTTP
+* header. A caller identifier (`SOCKET_CALLER_USER_AGENT`, or a UA a proxy
+* forwards on behalf of its client) is untrusted, so strip control chars (C0
+* incl. CR/LF — the header- and log-injection vector — DEL, and C1), collapse
+* internal whitespace to one space, trim, and cap length. Returns '' for
+* nullish / blank / all-control input.
+*/
+function sanitizeUserAgent(value) {
+	if (!value) return "";
+	let cleaned = "";
+	for (let i = 0, { length } = value; i < length; i += 1) {
+		const code = require_primordials_string.StringPrototypeCharCodeAt(value, i);
+		cleaned += code < 32 || code >= 127 && code <= 159 ? " " : require_primordials_string.StringPrototypeCharAt(value, i);
+	}
+	cleaned = require_primordials_string.StringPrototypeTrim(require_primordials_string.StringPrototypeReplace(cleaned, /\s+/g, " "));
+	return cleaned.length > MAX_USER_AGENT_LENGTH ? require_primordials_string.StringPrototypeTrim(require_primordials_string.StringPrototypeSlice(cleaned, 0, MAX_USER_AGENT_LENGTH)) : cleaned;
 }
 
 //#endregion
 exports.buildUserAgent = buildUserAgent;
-exports.getSocketCallerUserAgent = getSocketCallerUserAgent;
+exports.chainUserAgents = chainUserAgents;
+exports.getSocketCallerUserAgent = getSocketCallerUserAgent;
+exports.sanitizeUserAgent = sanitizeUserAgent;

package/dist/integrity.d.ts

@@ -1,18 +1,36 @@
+/**
+ * SRI-blessed hash algorithms. The W3C set; the prefix is part of the wire
+ * format, not a Socket convention.
+ */
+export type HashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+/**
+ * A cryptographic hash: an algorithm plus the digest in both encodings. Frozen,
+ * plain, self-describing — `h.algorithm` removes every "is this 256 or 512?"
+ * guess, and `h.hex` / `h.sri` are precomputed views (cheap transcodes of the
+ * digest, eager so the value stays serializable and structurally comparable).
+ */
+export interface Hash {
+    readonly algorithm: HashAlgorithm;
+    /**
+     * Lowercase hex digest (64 chars sha256, 96 sha384, 128 sha512).
+     */
+    readonly hex: string;
+    /**
+     * W3C SRI string: `<algorithm>-<base64>`.
+     */
+    readonly sri: string;
+}
+/**
+ * Anything a caller can hand verify/convert as "the expected hash": a parsed
+ * {@link Hash}, an SRI string, or a bare hex digest (algorithm inferred by
+ * length).
+ */
+export type HashInput = string | Hash;
 /**
  * Tagged union representing an expected hash.
  *
- * @example
- *   // Bare SRI (sniffed as integrity):
- *   'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
- *
- * @example
- *   // Bare sha256 hex (sniffed as checksum):
- *   'a1b2c3...'
- *
- * @example
- *   // Explicit:
- *   { type: 'integrity', value: 'sha512-...' }
- *   { type: 'checksum', value: 'a1b2c3...' }
+ * @deprecated Prefer {@link HashInput} + {@link parseHash}. Kept for the
+ *   `integrity?: HashSpec` option fields across dlx / external-tools.
  */
 export type HashSpec = string | {
     type: 'integrity';
@@ -22,15 +40,16 @@ export type HashSpec = string | {
     value: string;
 };
 /**
- * Normalized internal form. Always an object.
+ * Normalized internal form of a {@link HashSpec}. Always an object.
  */
 export interface NormalizedHash {
     type: 'integrity' | 'checksum';
     value: string;
 }
 /**
- * Both hash formats for the same bytes. Returned from downloads so callers can
- * record whichever format their config uses.
+ * Both pinned hash formats for the same bytes: the sha512 SRI we pin against
+ * and the sha256 hex upstream tools emit. Returned from downloads so callers
+ * record whichever their config uses.
  */
 export interface ComputedHashes {
     /**
@@ -43,7 +62,7 @@ export interface ComputedHashes {
     checksum: string;
 }
 /**
- * Parsed components of an integrity string.
+ * Parsed components of an SRI integrity string.
  */
 export interface ParsedIntegrity {
     /**
@@ -56,60 +75,64 @@ export interface ParsedIntegrity {
     body: string;
 }
 /**
- * Convert a sha256 hex checksum to its SRI integrity form (`sha256-<base64>`).
- * Idempotent on integrity input — call this on user-supplied data without first
- * sniffing the format.
- *
- * The default algorithm is `'sha256'` because this converts a _checksum_, and
- * checksums are sha256 by fleet convention (the GitHub-SHA256SUMS interop shape
- * its only caller, `checksum-file.ts`, parses). Do NOT flip this default to
- * sha512: this function only relabels the hex bytes, it does not re-hash, so a
- * sha512 label on a 256-bit digest would be a lie. The canonical algorithm for
- * OUR-side integrity values is sha512 — emitted by `computeHashes` as the
- * `integrity` (`sha512-<base64>`) field; sha256 is reserved for
- * upstream-SHASUMS interop and content addressing. Pass an explicit algorithm
- * if you have a hex digest from `sha384` or `sha512` (the function does not
- * verify hex length against the algorithm — caller's responsibility).
+ * Convert a hex checksum to its SRI integrity form.
  *
- * @example
- *   ;```typescript
- *   checksumToIntegrity(
- *     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
- *   )
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
- *
- *   checksumToIntegrity('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=' (idempotent)
- *   ```
+ * @deprecated Prefer `parseHash(x).sri`, which is total across all algorithms
+ *   and infers the algorithm from a bare hex digest. This shim defaults to
+ *   `'sha256'` because it only relabels the hex bytes — it does NOT re-hash, so
+ *   a sha512 label on a 256-bit digest would be a lie. Idempotent on SRI input.
  *
  * @throws TypeError when the input is neither a recognized SRI nor a hex
  *   digest.
  */
-export declare function checksumToIntegrity(input: string, algorithm?: string): string;
+export declare function checksumToIntegrity(input: string, algorithm?: HashAlgorithm): string;
+/**
+ * Compute a single {@link Hash} of `bytes`. Defaults to sha512 — the canonical
+ * trust string we pin against. Pass `'sha256'` for the upstream-interop digest.
+ *
+ * @example
+ *   ;```typescript
+ *   computeHash(bytes).sri        // 'sha512-…'  (pin this)
+ *   computeHash(bytes, 'sha256').hex  // '3620a0…' (compare to SHA256SUMS)
+ *   ```
+ */
+export declare function computeHash(bytes: NodeJS.ArrayBufferView, algorithm?: HashAlgorithm): Hash;
 /**
- * Compute both integrity (sha512 SRI) and checksum (sha256 hex) for a buffer of
- * bytes.
+ * Compute both pinned formats for `bytes`: the sha512 SRI integrity and the
+ * sha256 hex checksum. Use when a config records both (e.g.
+ * `external-tools.json`, dlx lockfiles).
  */
 export declare function computeHashes(bytes: Buffer): ComputedHashes;
 /**
- * Convert a sha256 SRI integrity string to its hex checksum form (64 lowercase
- * chars). Idempotent on checksum input.
+ * Compare two hashes for equality, ENCODING-agnostically. Parses both and —
+ * only when they share an algorithm — timing-safe compares the digests.
  *
- * Throws on `sha384` and `sha512` SRI — checksums are sha256-only by fleet
- * convention. Callers that need a hex digest for those algorithms can call
- * `parseIntegrity(sri)` and decode `.body` manually.
+ * Returns false when the algorithms differ. A sha512 and a sha256 are different
+ * functions of the same bytes: their digests are unrelated values, so they can
+ * never be "equal", and you CANNOT derive or check one against the other
+ * without the original bytes. To confirm a sha256 and a sha512 describe the
+ * same content, hash the bytes both ways (`computeHashes`) or `verifyHash` the
+ * bytes against each — there is no hash-to-hash shortcut across algorithms.
+ *
+ * What this DOES solve is the cross-ENCODING case that bites string `===`: a
+ * sha256 SRI and the same sha256 hex compare equal here.
  *
  * @example
  *   ;```typescript
- *   integrityToChecksum('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b'
- *
- *   integrityToChecksum(
- *     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
- *   )
- *   // '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b' (idempotent)
+ *   equalHashes('sha256-NiCg…', '3620a0fc…')  // true  (same digest, SRI vs hex)
+ *   equalHashes('sha512-…', '3620a0fc…')       // false (different algorithms)
  *   ```
  *
+ * @throws TypeError when either input is not a recognized hash.
+ */
+export declare function equalHashes(a: HashInput, b: HashInput): boolean;
+/**
+ * Convert an SRI integrity string to its hex checksum form.
+ *
+ * @deprecated Prefer `parseHash(x).hex`, which is total across all algorithms.
+ *   This shim is sha256-only (throws on sha384 / sha512) to preserve its
+ *   historical "checksums are sha256" contract. Idempotent on hex input.
+ *
  * @throws TypeError when the input is neither a recognized SRI nor a hex
  *   checksum, or when the input is a non-sha256 SRI.
  */
@@ -118,49 +141,75 @@ export declare function integrityToChecksum(input: string): string;
  * True when `s` is a sha256 hex checksum (exactly 64 hex chars).
  */
 export declare function isChecksum(s: string): boolean;
+/**
+ * True when `s` is a bare hex digest of a recognized length (sha256 / sha384 /
+ * sha512).
+ */
+export declare function isHex(s: string): boolean;
 /**
  * True when `s` is a W3C SRI integrity string: `sha(256|384|512)-<base64>`.
  */
 export declare function isIntegrity(s: string): boolean;
+/**
+ * Build a frozen {@link Hash} from an algorithm and a hex digest. The internal
+ * constructor — trusts its inputs (lowercases the hex, computes the SRI view);
+ * use {@link parseHash} for untrusted strings, which validates first.
+ */
+export declare function makeHash(algorithm: HashAlgorithm, hex: string): Hash;
 /**
  * Normalize a {@link HashSpec} to its canonical `{ type, value }` form.
  *
- * - Object form is trusted (its `value` is validated for shape).
- * - Bare string matching SRI → integrity.
- * - Bare string of 64 hex chars → checksum.
- * - Anything else throws TypeError.
+ * @deprecated Prefer {@link parseHash}, which returns an algorithm-tagged
+ *   {@link Hash}. Kept for callers that branch on integrity-vs-checksum type.
  *
  * @throws TypeError if the string is not a recognized format, or if an explicit
  *   object's value doesn't match its declared type.
  */
 export declare function normalizeHash(spec: HashSpec): NormalizedHash;
 /**
- * Split an integrity string into its `{ algorithm, body }` components. `body`
- * is the base64-encoded digest (everything after the algorithm + dash).
+ * Parse any {@link HashInput} into a canonical {@link Hash}. The one entry
+ * point for untrusted input — validates shape + length, then freezes.
  *
- * @example
- *   ;```typescript
- *   parseIntegrity('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // { algorithm: 'sha256', body: 'NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=' }
- *   ```
+ * - A {@link Hash} object is re-canonicalized from its `algorithm` + `hex`.
+ * - An SRI string carries its algorithm in the prefix (the body length is checked
+ *   against it).
+ * - A bare hex digest infers the algorithm from its length (64 / 96 / 128).
+ *
+ * @throws TypeError when the input is not a recognized SRI or hex digest, or
+ *   when an SRI body's length doesn't match its declared algorithm.
+ */
+export declare function parseHash(input: HashInput): Hash;
+/**
+ * Split an SRI integrity string into its `{ algorithm, body }` components.
+ * `body` is the base64-encoded digest.
  *
  * @throws Error when the input is not a valid SRI integrity string.
  */
 export declare function parseIntegrity(sri: string): ParsedIntegrity;
 /**
- * Verify computed hashes against an expected {@link NormalizedHash}. Uses
- * `crypto.timingSafeEqual` for constant-time comparison.
- *
- * @throws DlxHashMismatchError when the hash of the matching type doesn't match
- *   the expected value.
+ * Verify `bytes` against an expected hash. Reads the algorithm the expected
+ * hash declares, computes only that digest, and compares with
+ * `crypto.timingSafeEqual` — so any encoding (hex / SRI / {@link Hash}) and any
+ * algorithm (sha256 / sha384 / sha512) verifies without the caller reconciling
+ * formats first.
+ *
+ * @throws HashMismatchError when the recomputed digest doesn't match.
+ * @throws TypeError when `expected` is not a recognized hash.
  */
-export declare function verifyHash(expected: NormalizedHash, computed: ComputedHashes): void;
+export declare function verifyHash(bytes: NodeJS.ArrayBufferView, expected: HashInput): void;
 /**
- * Thrown when an expected hash doesn't match the computed hash of the
- * downloaded bytes. Carries both sides for diagnostics.
+ * Thrown when an expected hash doesn't match the computed hash of the verified
+ * bytes. Carries both sides (as {@link Hash}) for diagnostics.
  */
-export declare class DlxHashMismatchError extends Error {
-    readonly expected: NormalizedHash;
-    readonly actual: ComputedHashes;
-    constructor(expected: NormalizedHash, actual: ComputedHashes);
+export declare class HashMismatchError extends Error {
+    readonly expected: Hash;
+    readonly actual: Hash;
+    constructor(expected: Hash, actual: Hash);
 }
+/**
+ * @deprecated Renamed to {@link HashMismatchError}. Alias kept for callers that
+ *   catch the old name.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare const DlxHashMismatchError: typeof HashMismatchError;