@effectstream/binary-checksum

Shared fail-closed SHA-256 verification for the packages/binaries/* wrappers.

Those packages download a prebuilt binary and then execute it. bin-wrapper has no integrity support and discards the archive after extracting, so the only thing left to check is the extracted file. This module is that check.

import { verifyBinaryChecksum } from '@effectstream/binary-checksum';
import { CHECKSUMS } from './checksums.js';

const flavour = verifyBinaryChecksum({
  binaryPath: bin.path(),
  checksums: CHECKSUMS,
  packageName: 'grafana-loki',
  skipEnvVar: 'GRAFANA_LOKI_SKIP_CHECKSUM',
  version: '3.5.8',
});

Throws if the digest is not pinned. Returns the matched platform key, or undefined when the skip variable is set to exactly 1.

Verify before you exec

bin.run() resolves the binary and executes it, so calling it before verifying defeats the point. Download explicitly, verify, then run:

if (!fs.existsSync(bin.path())) await bin.download();
verifyBinaryChecksum({ /* ... */ });
await bin.run(['--version']);

Watch for anything that mutates the binary between extraction and execution. bitcoin-core ad-hoc signs on Apple Silicon, which changes the hash, so there verification has to happen first and cannot be repeated afterwards.

Digests are matched as a set

Not looked up by the running platform. Asset selection in bin-wrapper goes through os-filter-obj and the arch package, whose reported architecture has not always agreed with os.arch(): [email protected] had no notion of arm64 at all, so every Mac silently ran the x86_64 build under Rosetta. Set membership is immune to that whole class of mismatch, including deliberate emulation, while still proving the file is one of the pinned builds. The matched key is returned for logging rather than enforced.

An empty table is an error

Passing {} throws rather than accepting anything. A forgotten regeneration after a version bump would otherwise turn a fail-closed guard into a silent no-op, which is the failure this module exists to prevent.

What a pinned digest does and does not prove

Digests are generated by scripts/generate-binary-checksums.ts, which records provenance per entry:

• upstream-verified means the archive was matched against a checksum the vendor publishes before the binary inside it was hashed. The digest traces to the vendor.
• self-recorded means no upstream manifest was available. The digest pins the artifact against later mutation and says nothing about whether it was good in the first place. Worth having, but do not mistake it for the stronger claim.