@packall/core 0.1.0 → 0.3.0

package/src/integrity.ts

@@ -1,121 +1,165 @@
-/**
- * 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
-  }
-}
+/**
+ * Checksum verification for downloaded tarballs.
+ *
+ * A failed check discards the download rather than warning and carrying on —
+ * see `notes/requirements.md` § FR-9 for why that strictness is a requirement
+ * rather than a preference.
+ *
+ * Built on Effect's `Crypto` service rather than `node:crypto` directly. The
+ * four digests `Crypto` offers — SHA-1, SHA-256, SHA-384, SHA-512 — are exactly
+ * the four npm publishes, so nothing is given up, and the same verification
+ * then runs unchanged against WebCrypto in a browser. Parsing stays here
+ * because the subset of Subresource Integrity npm actually emits is small and
+ * entirely mechanical; `ssri` would be a dependency for a regex.
+ */
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import type { PlatformError } from "effect/PlatformError";
+
+/**
+ * The digests npm publishes, mapped to what `Crypto.digest` calls them.
+ *
+ * Doubles as the supported-algorithm list: an SRI token whose algorithm is not
+ * a key here is one we cannot check, and is dropped during parsing.
+ */
+const digestAlgorithmByName = {
+	sha512: "SHA-512",
+	sha384: "SHA-384",
+	sha256: "SHA-256",
+	sha1: "SHA-1",
+} as const satisfies Record<string, Crypto.DigestAlgorithm>;
+
+/** An algorithm this module can verify against. */
+export type IntegrityAlgorithm = keyof typeof digestAlgorithmByName;
+
+const isSupported = (algorithm: string): algorithm is IntegrityAlgorithm =>
+	Object.hasOwn(digestAlgorithmByName, algorithm);
+
+/** One parsed SRI hash. */
+export type IntegrityHash = {
+	readonly algorithm: IntegrityAlgorithm;
+	/** Base64 digest, exactly as written in the SRI string. */
+	readonly digest: string;
+};
+
+/**
+ * Parses an SRI string such as `sha512-abc...==`.
+ *
+ * npm permits several space-separated hashes; we keep every one we can verify
+ * and ignore algorithms we cannot.
+ */
+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 (!isSupported(algorithm) || digest.length === 0) continue;
+		hashes.push({ algorithm, digest });
+	}
+	return hashes;
+};
+
+const digestBytes = (
+	data: Uint8Array,
+	algorithm: IntegrityAlgorithm,
+): Effect.Effect<Uint8Array, PlatformError, Crypto.Crypto> =>
+	Effect.gen(function* () {
+		const crypto = yield* Crypto.Crypto;
+		return yield* crypto.digest(digestAlgorithmByName[algorithm], data);
+	});
+
+/** Computes the base64 digest of some bytes under one algorithm. */
+export const digestOf = (
+	data: Uint8Array,
+	algorithm: IntegrityAlgorithm,
+): Effect.Effect<string, PlatformError, Crypto.Crypto> =>
+	Effect.map(digestBytes(data, algorithm), Encoding.encodeBase64);
+
+/** Computes the hex digest of some bytes — the form legacy `shasum` uses. */
+export const hexDigestOf = (
+	data: Uint8Array,
+	algorithm: IntegrityAlgorithm,
+): Effect.Effect<string, PlatformError, Crypto.Crypto> =>
+	Effect.map(digestBytes(data, algorithm), Encoding.encodeHex);
+
+/** 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.
+ *
+ * Written by hand rather than with `node:crypto`'s `timingSafeEqual`, which
+ * needs `Buffer` and would pin this module to Node. Both digests here are
+ * public knowledge, so the timing property is close to theatre — but it costs
+ * four lines, and the alternative is explaining in a review why it was dropped.
+ */
+const digestsEqual = (a: string, b: string): boolean => {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) {
+		difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	}
+	return difference === 0;
+};
+
+/**
+ * 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 },
+): Effect.Effect<VerificationResult, PlatformError, Crypto.Crypto> =>
+	Effect.gen(function* () {
+		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) => strengthByAlgorithm[b.algorithm] - strengthByAlgorithm[a.algorithm],
+			);
+			if (best === undefined) {
+				return {
+					_tag: "Unverifiable",
+					reason: `no supported algorithm in "${dist.integrity}"`,
+				};
+			}
+
+			const actual = yield* 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 = yield* 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 strengthByAlgorithm = {
+	sha512: 4,
+	sha384: 3,
+	sha256: 2,
+	sha1: 1,
+} as const satisfies Record<IntegrityAlgorithm, number>;

package/src/layout.ts

@@ -7,27 +7,29 @@
  *     @babel/core/-/core-7.24.0.tgz
  *
  * That is not an Artifactory convention — it is the path structure in every
- * `dist.tarball` URL npm publishes, which is why the same tree imports into
- * Artifactory, Nexus and Verdaccio without translation. Note that a scoped
- * package's file name drops the scope: `@babel/core` becomes `core-7.24.0.tgz`
- * under an `@babel/core/-/` directory.
+ * `dist.tarball` URL npm publishes. See `notes/requirements.md` § FR-12 for
+ * what that buys.
+ *
+ * The one shape worth noticing before editing anything here: a scoped
+ * package's file name drops the scope, so `@babel/core` becomes
+ * `core-7.24.0.tgz` under an `@babel/core/-/` directory.
  */
 
 /** Splits `@scope/name` into its parts. `scope` is undefined when unscoped. */
 export const splitName = (
-  name: string
+	name: string,
 ): { readonly scope: string | undefined; readonly bare: string } => {
-  if (!name.startsWith("@")) return { scope: undefined, bare: name }
-  const slash = name.indexOf("/")
-  if (slash === -1) return { scope: undefined, bare: name }
-  return { scope: name.slice(0, slash), bare: name.slice(slash + 1) }
-}
+	if (!name.startsWith("@")) return { scope: undefined, bare: name };
+	const slash = name.indexOf("/");
+	if (slash === -1) return { scope: undefined, bare: name };
+	return { scope: name.slice(0, slash), bare: name.slice(slash + 1) };
+};
 
 /** `@babel/core` + `7.24.0` -> `core-7.24.0.tgz` */
 export const tarballFileName = (name: string, version: string): string => {
-  const { bare } = splitName(name)
-  return `${bare}-${version}.tgz`
-}
+	const { bare } = splitName(name);
+	return `${bare}-${version}.tgz`;
+};
 
 /**
  * The path of one package tarball within a bundle, using `/` separators
@@ -35,29 +37,61 @@ export const tarballFileName = (name: string, version: string): string => {
  * are always POSIX.
  */
 export const packagePath = (name: string, version: string): string =>
-  `${name}/-/${tarballFileName(name, version)}`
+	`${name}/-/${tarballFileName(name, version)}`;
 
 /** File name of the manifest that ships inside every bundle. */
-export const MANIFEST_FILE = "bundle-manifest.json"
+export const MANIFEST_FILE = "bundle-manifest.json";
 
 /** File name of the short import guide that ships inside every bundle. */
-export const README_FILE = "IMPORT.md"
+export const README_FILE = "IMPORT.md";
 
 /**
  * Name of the archive produced for one root spec in `per-spec` layout.
  *
- * Scoped names are flattened (`@babel/core` -> `babel-core`) because a `/` in a
- * file name is not a thing, and `@` confuses enough shells and web UIs to be
- * worth avoiding.
+ * It is the spec, with the one character a file name cannot hold taken out:
+ * `@types/react@19.2.18` becomes `@types-react@19.2.18.tgz`. So the name of the
+ * file answers the question somebody has when they are looking at a directory
+ * of them — which package, and which version — in the notation they would have
+ * typed to ask for it.
+ *
+ * The version is joined with `@` rather than `-` for the same reason. A
+ * hyphen made `foo-bar-1.0.0` ambiguous by eye: package `foo` at `bar-1.0.0`,
+ * or `foo-bar` at `1.0.0`? npm's own syntax has no such problem, because a
+ * package name may not contain `@` beyond its scope.
+ *
+ * **The scope's `@` stays**, and it is the difference between a correct bundle
+ * and a quietly incomplete one.
+ *
+ * Dropping it — which this did, matching what `npm pack` produces — meant
+ * `@something/somewhat` and `something-somewhat` were both
+ * `something-somewhat-1.0.0.tgz`. Two different packages, one path: the second
+ * landed on the first, and the run reported two artifacts for the one file that
+ * survived. A bundle short a package, called complete, found at the far end of
+ * an air gap.
+ *
+ * Keeping the `@` makes that impossible by construction rather than by a check,
+ * because an unscoped npm name may not begin with one. It is also the more
+ * honest name: the scope is part of what the package *is*, and a directory of
+ * archives that has forgotten which ones were scoped is a directory somebody
+ * has to cross-reference against a manifest.
+ *
+ * It does not make every collision impossible — `@a/b-c` and `@a-b/c` still
+ * meet — so `assertDistinctOutputs` still runs. That pair is pathological; the
+ * scoped-against-unscoped one is `@babel/core` beside `babel-core`, which is a
+ * real migration somebody could be bundling.
+ *
+ * The leading `@` is safe here in a way it is not inside the archive: tar's
+ * splice convention applies to the *file list* it is given, which is what
+ * `archive.ts` guards with `./`. This is the output path, not an entry.
  */
 export const perSpecArchiveName = (name: string, version: string): string => {
-  const { scope, bare } = splitName(name)
-  const prefix = scope === undefined ? bare : `${scope.slice(1)}-${bare}`
-  return `${prefix}-${version}.tgz`
-}
+	const { scope, bare } = splitName(name);
+	const prefix = scope === undefined ? bare : `${scope}-${bare}`;
+	return `${prefix}@${version}.tgz`;
+};
 
 /** Name of the archive produced in `single` layout. */
-export const singleArchiveName = (base = "bundle"): string => `${base}.tgz`
+export const singleArchiveName = (base = "bundle"): string => `${base}.tgz`;
 
 /**
  * The import guide written into each bundle.
@@ -66,11 +100,11 @@ export const singleArchiveName = (base = "bundle"): string => `${base}.tgz`
  * restricted network and does not want prose.
  */
 export const importGuide = (options: {
-  readonly packageCount: number
-  readonly createdAt: string
-  readonly toolVersion: string
+	readonly packageCount: number;
+	readonly createdAt: string;
+	readonly toolVersion: string;
 }): string =>
-  `# Importing this bundle
+	`# Importing this bundle
 
 ${options.packageCount} package tarball(s), laid out exactly as an npm registry serves them:
 
@@ -100,4 +134,4 @@ Publish each tarball individually:
 
 Every entry in ${MANIFEST_FILE} carries the integrity string the source registry
 advertised, and each tarball was checked against it at download time.
-`
+`;