What the integrity field in package-lock.json actually protects

The integrity field in package-lock.json is a hash of the package tarball. It lets npm detect a download that differs from the one you locked, such as a tampered mirror or a swapped file. It does not tell you the package was safe when you locked it.

What is stored

For each package, the npm lockfile documentation lists three fields:

• version, the version found in package.json.
• resolved, the place where the package was actually resolved from. For registry packages this is a tarball URL.
• integrity, a sha512 or sha1 string for the artifact that was unpacked at that location, in Subresource Integrity format.

The docs also say the file is intended to be committed to source repositories so that teammates, deployments and CI install the same dependencies. Lockfile versions differ by npm release; lockfiles from npm v7 use version 2, and version 3 is used by npm v9 and above.

What it protects against

1. Changed content at the same address. If the file at a resolved URL changes after you locked it, the hash no longer matches and the install fails.
2. A compromised mirror or cache. A proxy that serves a modified tarball for a locked version is caught the same way.
3. Accidental corruption. Truncated or damaged downloads fail rather than install quietly.

What it does not protect against

1. A bad version locked on day one. The hash records whatever you downloaded. If that tarball was malicious, the lock now guarantees you get the malicious tarball.
2. A malicious lockfile change. If a pull request edits the resolved URL and the integrity together, the install will succeed against the attacker's file. Integrity checks compare the file with the lock, and the lock is the thing under attack.
3. A compromised maintainer account. A genuinely published but harmful new version has a perfectly valid hash.
4. Weak hashes. The docs allow sha1 values. Treat sha512 as the norm and look into any entry that lacks it.

A lockfile diff review routine

When a pull request touches the lockfile:

1. Look at which packages were added. Does each have a reason?
2. Check resolved hosts. Anything other than your expected registry or mirror needs an explanation.
3. Look for changed integrity values on an unchanged version. That is unusual and worth a question.
4. Look for packages that moved from a registry URL to a git or tarball URL.
5. Compare the changes against the package.json diff. Large lockfile changes with a tiny manifest change deserve a second look.
6. Run a dependency scan on the new set before approving.

Automation

Some of that routine is easy to script: list resolved hosts, flag non sha512 entries, flag URL scheme changes. Leave the judgment calls to a person.

Safeguard scans dependencies on pull requests and can enforce policies, which suits the last step in the routine.

Quick check

Sources

• package-lock.json documentation

Last reviewed: 19 October 2026.