Verifying npm Package Provenance Before You Depend on It

You want assurance that a dependency's published tarball actually came from its claimed source repository and CI, not a hijacked account. This page shows how to check npm provenance attestations before trusting a package.

Exact symptoms and error messages

# a package with no provenance gives you no build-origin guarantee
$ npm view some-lib dist.attestations
undefined

Root cause analysis

Provenance is a signed attestation, generated by CI via OIDC, that ties a published tarball to a specific source commit and build. A package without it offers no cryptographic link between the code on GitHub and the tarball on the registry, so an account compromise can publish anything. Verifying provenance is the consumer side of the publisher defenses in Supply-Chain Security Hardening and Adding SLSA Provenance to Package Releases.

Provenance is a signed attestation generated by CI via OIDC that binds a published tarball to a specific source commit and build workflow. Without it, there is no cryptographic link between the code you can read on GitHub and the tarball the registry serves — so a compromised maintainer account, or a registry-side tampering, can publish anything under a trusted name and you have no way to detect it. Verifying provenance is how a consumer regains that link.

What provenance does not prove is that the code is benign. It confirms origin and integrity — this tarball really came from that source and build, unmodified — not intent. A malicious-but-authentic author can still publish signed, provenance-backed malware. Provenance defends against account hijacks and supply-chain tampering, which is a large and important class of attack, but it is one layer among several rather than a guarantee of safety.

Resolution and configuration patch

Check for and verify attestations before adopting a dependency:

# Does the package publish provenance?
npm view some-lib dist.attestations
# Verify the signed attestations for what you have installed
npm audit signatures

Prefer dependencies that publish provenance, and treat a missing attestation on a security-critical package as a reason to pin and review.

CLI validation and debug commands

# Verify signatures/attestations across the installed tree
npm audit signatures
# Inspect the provenance's source repo and commit
npm view some-lib --json | jq '.dist.attestations'

Prevention and CI guardrails

• Prefer dependencies that publish provenance for security-critical code.
• Run npm audit signatures in CI to verify attestations on install.
• Pin and review packages that lack provenance before depending on them.
• Publish provenance for your own packages so consumers can verify you in turn.

Verifying attestations across your dependency tree

Checking one package by hand does not scale; the practical move is to verify signatures and attestations across everything you have installed, as a CI step. npm audit signatures walks the installed tree and verifies registry signatures and provenance attestations, failing when verification does not hold.

# Verify registry signatures and provenance for the whole tree
npm audit signatures

Run it in CI so a package that loses its expected signature — or whose attestation does not verify — fails the build rather than shipping silently. For security-critical dependencies specifically, prefer ones that publish provenance, and treat a missing attestation on such a package as a reason to pin the version and review before adopting. The goal is to make provenance verification a routine gate, not a manual spot-check you do once and forget.

Publishing your own provenance

Verification has a mirror obligation: publish provenance for your own packages so your consumers can verify you in turn. With OIDC-based publishing from CI, the registry attaches an attestation tying your tarball to its source and build, and consumers running npm audit signatures see it verified.

    permissions:
      id-token: write
    steps:
      - run: npm publish --provenance

Granting the workflow id-token: write and publishing with --provenance is usually the whole change — and it doubles as the token-free publishing path, since the OIDC identity replaces a standing token. Publishing provenance is how you participate in the same chain of trust you rely on when consuming: you verify your dependencies, and you give your consumers the means to verify you, which is what makes the ecosystem-wide guarantee actually hold.

Frequently Asked Questions

Does provenance prove the code is safe?

No — it proves the tarball came from the claimed source and CI build, not that the code is benign. It defends against account hijacks and tampering, not against a malicious-but-authentic author.

How do I verify provenance in CI?

Run npm audit signatures, which verifies registry signatures and provenance attestations for your installed packages, and fail the job if verification fails on a package you require.

Does provenance prove a package is safe?

No — it proves the tarball came from the claimed source and build, unmodified. It defends against account hijacks and tampering, not against a malicious-but-authentic author. Treat it as one layer of defense, not a safety guarantee.

How do I verify provenance across all my dependencies?

Run npm audit signatures in CI. It walks the installed tree and verifies registry signatures and provenance attestations, failing the build when verification does not hold — a routine gate rather than a manual spot-check.

How do I publish provenance for my own package?

Publish from CI with id-token: write permission and npm publish --provenance. The registry attaches an attestation tying the tarball to its source and build, which also removes the need for a standing publish token.

Related

• Supply-Chain Security Hardening — the broader supply-chain defenses this control is part of.

← Supply-Chain Security Hardening