@packall/core 0.0.1 → 0.1.0

package/src/{Integrity.ts → integrity.ts}

@@ -1,122 +1,121 @@
-/**
- * Checksum verification for downloaded tarballs.
- *
- * A bundle is a supply-chain artifact that gets imported wholesale into a
- * corporate registry, so "the bytes I got are the bytes the registry promised"
- * is the one property worth being strict about. A failed check discards the
- * download rather than warning and carrying on.
- *
- * Implemented directly against `node:crypto` rather than pulling in `ssri`,
- * because the subset of Subresource Integrity that npm actually publishes is
- * small and entirely mechanical.
- */
-import { createHash, timingSafeEqual } from "node:crypto"
-
-/** One parsed SRI hash. */
-export interface IntegrityHash {
-  readonly algorithm: string
-  /** Base64 digest, exactly as written in the SRI string. */
-  readonly digest: string
-}
-
-const SUPPORTED = new Set(["sha512", "sha384", "sha256", "sha1"])
-
-/**
- * Parses an SRI string such as `sha512-abc...==`.
- *
- * npm permits several space-separated hashes; we keep every one we can verify
- * and ignore algorithms Node does not implement.
- */
-export const parseIntegrity = (integrity: string): ReadonlyArray<IntegrityHash> => {
-  const hashes: Array<IntegrityHash> = []
-  for (const token of integrity.trim().split(/\s+/)) {
-    if (token.length === 0) continue
-    const dash = token.indexOf("-")
-    if (dash <= 0) continue
-    const algorithm = token.slice(0, dash).toLowerCase()
-    const digest = token.slice(dash + 1)
-    if (!SUPPORTED.has(algorithm) || digest.length === 0) continue
-    hashes.push({ algorithm, digest })
-  }
-  return hashes
-}
-
-/** Computes the base64 digest of some bytes under one algorithm. */
-export const digestOf = (data: Uint8Array, algorithm: string): string =>
-  createHash(algorithm).update(data).digest("base64")
-
-/** Computes the hex digest of some bytes — the form legacy `shasum` uses. */
-export const hexDigestOf = (data: Uint8Array, algorithm: string): string =>
-  createHash(algorithm).update(data).digest("hex")
-
-/** Result of checking a download. */
-export type VerificationResult =
-  /** Verified against at least one checksum. */
-  | { readonly _tag: "Verified"; readonly using: string }
-  /** The registry advertised no checksum we could use. */
-  | { readonly _tag: "Unverifiable"; readonly reason: string }
-  /** A checksum was present and did not match. */
-  | { readonly _tag: "Mismatch"; readonly expected: string; readonly actual: string }
-
-/** Constant-time comparison of two digest strings of equal length. */
-const digestsEqual = (a: string, b: string): boolean => {
-  const left = Buffer.from(a)
-  const right = Buffer.from(b)
-  // `timingSafeEqual` throws on unequal lengths, which is itself a mismatch.
-  return left.length === right.length && timingSafeEqual(left, right)
-}
-
-/**
- * Checks bytes against whichever checksums the registry supplied.
- *
- * SRI is preferred; `shasum` is the fallback for versions published before
- * integrity strings existed. If the registry gave us neither, that is reported
- * as `Unverifiable` rather than silently treated as a pass — the caller decides
- * whether to tolerate it.
- */
-export const verify = (
-  data: Uint8Array,
-  dist: { readonly integrity?: string | undefined; readonly shasum?: string | undefined }
-): VerificationResult => {
-  if (dist.integrity !== undefined && dist.integrity.length > 0) {
-    const hashes = parseIntegrity(dist.integrity)
-    if (hashes.length === 0) {
-      return { _tag: "Unverifiable", reason: `no supported algorithm in "${dist.integrity}"` }
-    }
-    // Strongest first, so a mismatch is reported against the best hash present.
-    const ordered = [...hashes].sort(
-      (a, b) => strength(b.algorithm) - strength(a.algorithm)
-    )
-    const best = ordered[0]!
-    const actual = digestOf(data, best.algorithm)
-    return digestsEqual(actual, best.digest)
-      ? { _tag: "Verified", using: best.algorithm }
-      : {
-          _tag: "Mismatch",
-          expected: `${best.algorithm}-${best.digest}`,
-          actual: `${best.algorithm}-${actual}`
-        }
-  }
-
-  if (dist.shasum !== undefined && dist.shasum.length > 0) {
-    const actual = hexDigestOf(data, "sha1")
-    return digestsEqual(actual.toLowerCase(), dist.shasum.toLowerCase())
-      ? { _tag: "Verified", using: "sha1" }
-      : { _tag: "Mismatch", expected: `sha1-${dist.shasum}`, actual: `sha1-${actual}` }
-  }
-
-  return { _tag: "Unverifiable", reason: "registry advertised no integrity or shasum" }
-}
-
-const strength = (algorithm: string): number => {
-  switch (algorithm) {
-    case "sha512":
-      return 4
-    case "sha384":
-      return 3
-    case "sha256":
-      return 2
-    default:
-      return 1
-  }
-}
+/**
+ * Checksum verification for downloaded tarballs.
+ *
+ * A bundle is a supply-chain artifact that gets imported wholesale into a
+ * corporate registry, so "the bytes I got are the bytes the registry promised"
+ * is the one property worth being strict about. A failed check discards the
+ * download rather than warning and carrying on.
+ *
+ * Implemented directly against `node:crypto` rather than pulling in `ssri`,
+ * because the subset of Subresource Integrity that npm actually publishes is
+ * small and entirely mechanical.
+ */
+import { createHash, timingSafeEqual } from "node:crypto"
+
+/** One parsed SRI hash. */
+export type IntegrityHash = {
+  readonly algorithm: string
+  /** Base64 digest, exactly as written in the SRI string. */
+  readonly digest: string
+}
+
+const SUPPORTED = new Set(["sha512", "sha384", "sha256", "sha1"])
+
+/**
+ * Parses an SRI string such as `sha512-abc...==`.
+ *
+ * npm permits several space-separated hashes; we keep every one we can verify
+ * and ignore algorithms Node does not implement.
+ */
+export const parseIntegrity = (integrity: string): ReadonlyArray<IntegrityHash> => {
+  const hashes: Array<IntegrityHash> = []
+  for (const token of integrity.trim().split(/\s+/)) {
+    if (token.length === 0) continue
+    const dash = token.indexOf("-")
+    if (dash <= 0) continue
+    const algorithm = token.slice(0, dash).toLowerCase()
+    const digest = token.slice(dash + 1)
+    if (!SUPPORTED.has(algorithm) || digest.length === 0) continue
+    hashes.push({ algorithm, digest })
+  }
+  return hashes
+}
+
+/** Computes the base64 digest of some bytes under one algorithm. */
+export const digestOf = (data: Uint8Array, algorithm: string): string =>
+  createHash(algorithm).update(data).digest("base64")
+
+/** Computes the hex digest of some bytes — the form legacy `shasum` uses. */
+export const hexDigestOf = (data: Uint8Array, algorithm: string): string =>
+  createHash(algorithm).update(data).digest("hex")
+
+/** Result of checking a download. */
+export type VerificationResult =
+  /** Verified against at least one checksum. */
+  | { readonly _tag: "Verified"; readonly using: string }
+  /** The registry advertised no checksum we could use. */
+  | { readonly _tag: "Unverifiable"; readonly reason: string }
+  /** A checksum was present and did not match. */
+  | { readonly _tag: "Mismatch"; readonly expected: string; readonly actual: string }
+
+/** Constant-time comparison of two digest strings of equal length. */
+const digestsEqual = (a: string, b: string): boolean => {
+  const left = Buffer.from(a)
+  const right = Buffer.from(b)
+  // `timingSafeEqual` throws on unequal lengths, which is itself a mismatch.
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+/**
+ * Checks bytes against whichever checksums the registry supplied.
+ *
+ * SRI is preferred; `shasum` is the fallback for versions published before
+ * integrity strings existed. If the registry gave us neither, that is reported
+ * as `Unverifiable` rather than silently treated as a pass — the caller decides
+ * whether to tolerate it.
+ */
+export const verify = (
+  data: Uint8Array,
+  dist: { readonly integrity?: string | undefined; readonly shasum?: string | undefined }
+): VerificationResult => {
+  if (dist.integrity !== undefined && dist.integrity.length > 0) {
+    // Strongest first, so a mismatch is reported against the best hash present.
+    const [best] = parseIntegrity(dist.integrity).toSorted(
+      (a, b) => strength(b.algorithm) - strength(a.algorithm)
+    )
+    if (best === undefined) {
+      return { _tag: "Unverifiable", reason: `no supported algorithm in "${dist.integrity}"` }
+    }
+
+    const actual = digestOf(data, best.algorithm)
+    return digestsEqual(actual, best.digest)
+      ? { _tag: "Verified", using: best.algorithm }
+      : {
+          _tag: "Mismatch",
+          expected: `${best.algorithm}-${best.digest}`,
+          actual: `${best.algorithm}-${actual}`
+        }
+  }
+
+  if (dist.shasum !== undefined && dist.shasum.length > 0) {
+    const actual = hexDigestOf(data, "sha1")
+    return digestsEqual(actual.toLowerCase(), dist.shasum.toLowerCase())
+      ? { _tag: "Verified", using: "sha1" }
+      : { _tag: "Mismatch", expected: `sha1-${dist.shasum}`, actual: `sha1-${actual}` }
+  }
+
+  return { _tag: "Unverifiable", reason: "registry advertised no integrity or shasum" }
+}
+
+const strength = (algorithm: string): number => {
+  switch (algorithm) {
+    case "sha512":
+      return 4
+    case "sha384":
+      return 3
+    case "sha256":
+      return 2
+    default:
+      return 1
+  }
+}