A lockfile entry for a dependency includes a field like integrity: sha512-abc123.... What is this value used for during npm install, and what specific class of attack or failure does it guard against?

## What the field actually pins To understand what the integrity field does, it helps to separate two things a lockfile pins: **the version identifier** and **the actual bytes** behind that identifier. Pinning a version number (e.g. a package at version 4.17.21) tells the installer which release to fetch, but it implicitly trusts that whoever serves you a package claiming to be that version is actually giving you the real, unmodified content. The integrity field closes that trust gap: it's a cryptographic hash (commonly SHA-512, base64-encoded, in the `sha512-<hash>` format borrowed from the W3C Subresource Integrity spec used for script-tag integrity attributes on the web) computed over the exact tarball bytes the very first time that version was resolved and written into the lockfile. On every future install -- whether on a teammate's laptop, a CI runner, or a production build server -- the package manager 1. fetches the tarball, 2. computes the same hash function over what it received, 3. and compares the result byte-for-byte against the value recorded in the lockfile. Any mismatch causes the install to fail hard rather than silently proceeding with different code than what was tested and reviewed. ## Where the supply chain can break This exists because the supply chain between 'the code the maintainer published' and 'the code actually installed on your machine' has several places to get compromised or corrupted, and a bare version number cannot detect any of them. - A **network man-in-the-middle** could tamper with a tarball in transit (mitigated already by HTTPS, but defense in depth matters). - A **corporate proxy, internal mirror, or CDN edge node** could serve stale, corrupted, or maliciously modified bytes due to a caching bug or an actual compromise. - A **registry** itself, in a worst-case breach, could have an attacker overwrite or substitute contents. - And more mundanely, **network transfers** can simply get truncated or corrupted, which a hash check catches as reliably as it catches malice. In all these cases, the integrity hash is what actually verifies 'the bytes I'm about to run are the bytes that were reviewed and pinned,' whereas the version string alone only verifies 'the label matches.' ## Why the check is nearly free The trade-off here is nearly one-sided in favor of having the check -- it's cheap to compute, adds negligible install time, and its only real 'cost' is that it makes certain operational shortcuts impossible: you can't quietly swap a package's contents behind a fixed version-plus-hash pair without the lockfile catching it, which is occasionally inconvenient for internal package hosting setups that expect to mutate an 'already published' internal version (a bad practice the hash check actively discourages, correctly). The place engineers do get bitten is when the hash algorithm or format itself changes across ecosystem versions or package manager migrations -- older lockfiles used different integrity string formats before wide SHA-512 adoption, and mixing lockfile formats or migrating between package managers can produce integrity mismatches or force a full re-resolution, which is confusing if you don't know the format changed rather than the package. ## When an integrity check fails in the wild Failure modes in production typically look like a build suddenly failing with an integrity-check-failed error with no code change on your side. - **The most common innocent cause** is a corporate or CI-side package registry mirror/cache serving a different tarball than the public registry -- for instance, an internal proxy that cached an old or differently-built artifact under the same version tag before the lockfile was regenerated against the real registry. - **The most serious cause** is an actual supply-chain compromise: a well-known real-world pattern is registry account takeover, where an attacker publishes a malicious patch under a maintainer's compromised credentials. If the target version is genuinely new and unpinned, integrity hashing doesn't save you (you'd lock in the malicious hash on first install), but it absolutely protects everyone else who's already locked to the prior good version from silently picking up the compromised bytes under a version they thought was already vetted. This is exactly the mechanism that limited blast radius for consumers who had a lockfile pinning a version predating a compromise, in several publicized npm supply-chain incidents, and weren't the ones triggering a fresh resolve of the malicious release.