Download the tarball from your mirror, compute its sha512 digest, encode it in base64, and compare it with the integrity value in package-lock.json for that package. If they match, the mirror served the same bytes your lockfile recorded. If they differ, stop, because either the file changed or the lockfile entry did.
What the field means
The lockfile documentation says the integrity field is a checksum for the downloaded artifact that npm unpacked at that location, in the standard subresource integrity format, using sha512 or sha1. npm uses it to confirm that content matches what was recorded when the entry was written. Normal installs do this automatically, so a manual check is for investigations and for building trust in a new mirror.
Prefer entries with sha512. The sha1 form exists for older entries and is weaker.
A manual check
- Find the package entry in package-lock.json and copy its resolved URL and integrity value.
- Download the tarball from your mirror with a tool that does not alter it.
- Compute the digest and compare.
curl -sSLO https://mirror.example.internal/lodash/-/lodash-4.17.21.tgz
openssl dgst -sha512 -binary lodash-4.17.21.tgz | openssl base64 -A
grep -A2 '"node_modules/lodash"' package-lock.json | grep integrity
The integrity value begins with the algorithm name and a dash, then the base64 digest. Compare only the digest part. The version in the example is illustrative, so substitute a package from your own lockfile.
Make the comparison meaningful
A match tells you the mirror's copy equals what the lockfile recorded. It does not say that the recorded file was good. Consider where the lockfile entry came from. If the entry was created while pointed at a poisoned source, the hash faithfully records the poison. So also compare against upstream.
| Comparison | What a match proves |
|---|---|
| Mirror copy versus lockfile | The mirror serves what you recorded |
| Mirror copy versus upstream copy | The mirror did not alter the file |
| Lockfile entry versus a clean past commit | The entry was not changed in a recent edit |
For the second row, download the same version straight from the public registry and compare digests. Equal digests mean the mirror is faithful for that file.
When to run it
Run it when you change mirror software, when an advisory mentions registry tampering, or when a lockfile diff changes an integrity value without a version change. That last case deserves a question in code review, because a legitimate update changes the version too.
Review lockfile diffs
Integrity changes in a pull request are easy to skim past. Ask for a short note whenever a hash changes alone. A related post covers lockfile integrity in the audit workflow.
Where Safeguard fits
Safeguard's pull request gates and SBOM scanning can surface dependency changes for reviewers. A free scan is at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
See how a gate presents a dependency change for review, then picture an integrity-only change appearing the same way.
Quick check
Does npm already do this on every install?
Yes, it verifies content against the recorded integrity. The manual check helps investigations and mirror trust.
What if the hashes differ?
Do not install. Compare with upstream, check recent lockfile commits and tell the mirror owner.
Sources
Last reviewed: 19 October 2026.
