@socketsecurity/lib 6.0.7 → 6.0.9

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 fleet 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,54 +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.
+ * Convert a hex checksum to its SRI integrity form.
  *
- * The default algorithm is `'sha256'` because that's the fleet's checksum
- * convention; 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).
+ * @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?: 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
- *   checksumToIntegrity(
- *     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
- *   )
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
- *
- *   checksumToIntegrity('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=' (idempotent)
+ *   computeHash(bytes).sri        // 'sha512-…'  (pin this)
+ *   computeHash(bytes, 'sha256').hex  // '3620a0…' (compare to SHA256SUMS)
  *   ```
- *
- * @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 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.
  */
@@ -112,49 +141,73 @@ 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.
+ */
+export declare const DlxHashMismatchError: typeof HashMismatchError;

package/dist/integrity.js

@@ -5,94 +5,129 @@ const require_runtime = require('./_virtual/_rolldown/runtime.js');
 const require_crypto_hash = require('./crypto/hash.js');
 const require_primordials_buffer = require('./primordials/buffer.js');
 const require_primordials_error = require('./primordials/error.js');
+const require_primordials_object = require('./primordials/object.js');
+const require_primordials_string = require('./primordials/string.js');
 let node_crypto = require("node:crypto");
 node_crypto = require_runtime.__toESM(node_crypto);
 
 //#region src/integrity.ts
 /**
-* @file Integrity + checksum helpers. The fleet uses two named hash flavors:
-*
-*   - **integrity** — W3C Subresource Integrity string:
-*     `sha(256|384|512)-<base64>`. The same shape the npm registry returns and
-*     the `<script integrity>` HTML attribute accepts. Algorithm is embedded.
-*   - **checksum** — sha256 hex digest, exactly 64 lowercase chars. The shape
-*     produced by `shasum -a 256` and used in GitHub-release SHA256SUMS files.
-*     Conversion is direction-specific so the names read in English:
-*     `checksumToIntegrity(hex)` and `integrityToChecksum(sri)`. Both are
-*     idempotent on the destination format (pass an SRI to
-*     `checksumToIntegrity`, get the same SRI back) so callers can apply them
-*     without first sniffing the input shape. "SSRI" is just another name for
-*     Subresource Integrity — this module is the only one that should mention
-*     it, and only inside `parseIntegrity` to extract the embedded algorithm +
-*     body.
+* @file Integrity + checksum helpers. One concept — a {@link Hash} (algorithm +
+*   digest) — in two encodings:
+*
+*   - **hex** — lowercase hex digest (`shasum -a 256` / GitHub `SHA256SUMS`).
+*   - **sri** — W3C Subresource Integrity `sha(256|384|512)-<base64>` (npm
+*     `dist.integrity`, the `<script integrity>` attribute). Both are views of
+*     the same digest. The algorithm is EXPLICIT on every `Hash` — never
+*     inferred from which function produced it or sniffed from a string's
+*     shape. `verifyHash(bytes, expected)` honors whatever algorithm the
+*     expected hash declares, so a sha256 `SHA256SUMS` digest and a sha512 npm
+*     integrity both "just verify" with no manual conversion. Role split (see
+*     `docs/hash-algorithms.md`, unchanged): we PIN sha512 (`computeHash`
+*     default, `computeHashes().integrity`); sha256 is the upstream-interop
+*     shape (`fetchChecksumFile`, `computeHashes().checksum`). The two only
+*     meet at verify-upstream-256 → pin-512. Algorithms are never flipped —
+*     relabeling a 256-bit digest as sha512 would be a lie, and you can't
+*     re-hash without the bytes. "SSRI" is just another name for Subresource
+*     Integrity — only this module should mention it, inside `parseIntegrity`.
 */
 const INTEGRITY_RE = /^(sha(?:256|384|512))-([A-Za-z0-9+/]+=*)$/;
+const HEX_RE = /^[a-f0-9]+$/i;
 const CHECKSUM_RE = /^[a-f0-9]{64}$/i;
+const ALGORITHM_HEX_LENGTH = {
+	sha256: 64,
+	sha384: 96,
+	sha512: 128
+};
+const HEX_LENGTH_TO_ALGORITHM = {
+	64: "sha256",
+	96: "sha384",
+	128: "sha512"
+};
 /**
-* 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 that's the fleet's checksum
-* convention; 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).
-*
-* @example
-*   ;```typescript
-*   checksumToIntegrity(
-*     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
-*   )
-*   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
+* Convert a hex checksum to its SRI integrity form.
 *
-*   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.
 */
 function checksumToIntegrity(input, algorithm = "sha256") {
 	if (isIntegrity(input)) return input;
-	if (!/^[a-f0-9]+$/i.test(input)) throw new require_primordials_error.TypeErrorCtor(`checksumToIntegrity: expected a hex digest or SRI string, got: ${input}`);
-	return `${algorithm}-${require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(input, "hex"), "base64")}`;
+	if (!HEX_RE.test(input)) throw new require_primordials_error.TypeErrorCtor(`checksumToIntegrity: expected a hex digest or SRI string, got: ${input}`);
+	return makeHash(algorithm, input).sri;
+}
+/**
+* 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)
+*   ```
+*/
+function computeHash(bytes, algorithm = "sha512") {
+	return makeHash(algorithm, require_crypto_hash.hash(algorithm, bytes, "hex"));
 }
 /**
-* 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).
 */
 function computeHashes(bytes) {
 	return {
-		integrity: `sha512-${require_crypto_hash.hash("sha512", bytes, "base64")}`,
-		checksum: require_crypto_hash.hash("sha256", bytes, "hex")
+		integrity: computeHash(bytes, "sha512").sri,
+		checksum: computeHash(bytes, "sha256").hex
 	};
 }
 /**
-* 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.
+*/
+function equalHashes(a, b) {
+	const aHash = parseHash(a);
+	const bHash = parseHash(b);
+	if (aHash.algorithm !== bHash.algorithm) return false;
+	const aBuf = require_primordials_buffer.BufferFrom(aHash.hex, "hex");
+	const bBuf = require_primordials_buffer.BufferFrom(bHash.hex, "hex");
+	return aBuf.length === bBuf.length && node_crypto.default.timingSafeEqual(aBuf, bBuf);
+}
+/**
+* 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.
 */
 function integrityToChecksum(input) {
 	if (isChecksum(input)) return input;
 	const parsed = parseIntegrity(input);
-	if (parsed.algorithm !== "sha256") throw new require_primordials_error.TypeErrorCtor(`integrityToChecksum: ${parsed.algorithm} integrity has no 64-hex-char checksum form — checksums are sha256-only by fleet convention.`);
+	if (parsed.algorithm !== "sha256") throw new require_primordials_error.TypeErrorCtor(`integrityToChecksum: ${parsed.algorithm} integrity has no 64-hex-char checksum form — checksums are sha256-only by fleet convention. Use parseHash(x).hex for any algorithm.`);
 	return require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(parsed.body, "base64"), "hex");
 }
 /**
@@ -102,18 +137,36 @@ function isChecksum(s) {
 	return CHECKSUM_RE.test(s);
 }
 /**
+* True when `s` is a bare hex digest of a recognized length (sha256 / sha384 /
+* sha512).
+*/
+function isHex(s) {
+	return HEX_RE.test(s) && HEX_LENGTH_TO_ALGORITHM[s.length] !== void 0;
+}
+/**
 * True when `s` is a W3C SRI integrity string: `sha(256|384|512)-<base64>`.
 */
 function isIntegrity(s) {
 	return INTEGRITY_RE.test(s);
 }
 /**
+* 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.
+*/
+function makeHash(algorithm, hex) {
+	const lowerHex = require_primordials_string.StringPrototypeToLowerCase(hex);
+	return require_primordials_object.ObjectFreeze({
+		algorithm,
+		hex: lowerHex,
+		sri: `${algorithm}-${require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(lowerHex, "hex"), "base64")}`
+	});
+}
+/**
 * 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.
@@ -148,14 +201,37 @@ function normalizeHash(spec) {
 	throw new require_primordials_error.TypeErrorCtor(`normalizeHash: unrecognized hash format. Expected SRI integrity ("sha(256|384|512)-<base64>") or sha256 hex checksum (64 hex chars), got: ${spec}`);
 }
 /**
-* 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.
+*/
+function parseHash(input) {
+	if (typeof input === "object" && input !== null) return makeHash(input.algorithm, input.hex);
+	const sriMatch = INTEGRITY_RE.exec(input);
+	if (sriMatch) {
+		const algorithm = sriMatch[1];
+		const hex = require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(sriMatch[2], "base64"), "hex");
+		const expectedLength = ALGORITHM_HEX_LENGTH[algorithm];
+		if (hex.length !== expectedLength) throw new require_primordials_error.TypeErrorCtor(`parseHash: ${algorithm} SRI body decodes to ${hex.length} hex chars, expected ${expectedLength}: ${input}`);
+		return makeHash(algorithm, hex);
+	}
+	if (HEX_RE.test(input)) {
+		const algorithm = HEX_LENGTH_TO_ALGORITHM[input.length];
+		if (algorithm === void 0) throw new require_primordials_error.TypeErrorCtor(`parseHash: hex digest is ${input.length} chars; expected 64 (sha256), 96 (sha384), or 128 (sha512): ${input}`);
+		return makeHash(algorithm, input);
+	}
+	throw new require_primordials_error.TypeErrorCtor(`parseHash: expected an SRI string ("sha(256|384|512)-<base64>") or a hex digest, got: ${input}`);
+}
+/**
+* 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.
 */
@@ -168,41 +244,55 @@ function parseIntegrity(sri) {
 	};
 }
 /**
-* Verify computed hashes against an expected {@link NormalizedHash}. Uses
-* `crypto.timingSafeEqual` for constant-time comparison.
+* 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 DlxHashMismatchError when the hash of the matching type doesn't match
-*   the expected value.
+* @throws HashMismatchError when the recomputed digest doesn't match.
+* @throws TypeError when `expected` is not a recognized hash.
 */
-function verifyHash(expected, computed) {
-	const actual = expected.type === "integrity" ? computed.integrity : computed.checksum;
-	const expectedBuf = require_primordials_buffer.BufferFrom(expected.value);
-	const actualBuf = require_primordials_buffer.BufferFrom(actual);
-	if (expectedBuf.length !== actualBuf.length || !node_crypto.default.timingSafeEqual(expectedBuf, actualBuf)) throw new DlxHashMismatchError(expected, computed);
+function verifyHash(bytes, expected) {
+	const expectedHash = parseHash(expected);
+	const actualHash = computeHash(bytes, expectedHash.algorithm);
+	const expectedBuf = require_primordials_buffer.BufferFrom(expectedHash.hex, "hex");
+	const actualBuf = require_primordials_buffer.BufferFrom(actualHash.hex, "hex");
+	if (expectedBuf.length !== actualBuf.length || !node_crypto.default.timingSafeEqual(expectedBuf, actualBuf)) throw new HashMismatchError(expectedHash, actualHash);
 }
 /**
-* 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.
 */
-var DlxHashMismatchError = class extends Error {
+var HashMismatchError = class extends Error {
 	expected;
 	actual;
 	constructor(expected, actual) {
-		const actualValue = expected.type === "integrity" ? actual.integrity : actual.checksum;
-		super(`Hash mismatch (${expected.type}): expected ${expected.value}, got ${actualValue}`);
-		this.name = "DlxHashMismatchError";
+		super(`Hash mismatch (${expected.algorithm}): expected ${expected.sri}, got ${actual.sri}`);
+		this.name = "HashMismatchError";
 		this.expected = expected;
 		this.actual = actual;
 	}
 };
+/**
+* @deprecated Renamed to {@link HashMismatchError}. Alias kept for callers that
+*   catch the old name.
+*/
+const DlxHashMismatchError = HashMismatchError;
 
 //#endregion
 exports.DlxHashMismatchError = DlxHashMismatchError;
+exports.HashMismatchError = HashMismatchError;
 exports.checksumToIntegrity = checksumToIntegrity;
+exports.computeHash = computeHash;
 exports.computeHashes = computeHashes;
+exports.equalHashes = equalHashes;
 exports.integrityToChecksum = integrityToChecksum;
 exports.isChecksum = isChecksum;
+exports.isHex = isHex;
 exports.isIntegrity = isIntegrity;
+exports.makeHash = makeHash;
 exports.normalizeHash = normalizeHash;
+exports.parseHash = parseHash;
 exports.parseIntegrity = parseIntegrity;
 exports.verifyHash = verifyHash;