Software evidence · One release at a time

How to check the provenance of an npm package release

A supplier sends a repository link and says, “That is the source of the package we shipped.” The link is a useful starting point. What you still need is a connection between the particular package version and the particular source revision. Looking at today’s repository does not finish that job.

For an npm package, inspect the provenance attached to the version under review, follow its source and build references, and record any gap. You can make this initial evidence check in public web pages without installing the package. The result should tell another reviewer exactly which release you examined and which relationship remains unverified.

Pin down the thing that was shipped

Ask for the complete package name, including any @scope, the exact version, and the registry from which it came. Keep the sender’s statement beside those details. “The latest version” gives the next reviewer a moving target; a screenshot that crops away the version creates a similar problem.

If the question concerns a particular project’s dependency, request the relevant dependency entry rather than the whole private project. An npm lockfile records the resolved dependency tree. Its entry can help establish the version being discussed. A project file supplied to you is still a source with its own date and origin; it does not by itself establish what is running on a production server.

Write the question as a relationship: “Does the provenance for package P, version V, point to the source revision cited in the release note?” That is specific enough to investigate and small enough to answer.

Follow the record, then compare the references

npm’s viewing instructions describe opening the check mark beside Version and choosing View more details. Preserve the source commit, build file, build summary, environment and public-ledger references. If npm displays a warning about an unavailable repository or commit, include it in your note.

Check that the displayed package version still matches your starting record. Open the linked source revision and compare its full identifier with the one the supplier cited. Follow the build reference far enough to see what it describes. A link to a project’s general landing page is weaker for this task than a reference to the specific recorded build.

Do not silently repair a disagreement by substituting a newer commit or a different package with a similar name. Put both values on the page. That preserves the question the evidence must answer.

SLSA’s provenance model explains the underlying distinction: build provenance traces an output to the source used to produce it. It is a different research job from deciding who originally wrote a feature, which our GitHub contribution guide covers.

Try the two-release mismatch

Fictional exercise. A delivery note names package “Harbor Parser,” version 2.4.1. A presentation says the delivered package contains a fix from revision B. The provenance record you are given for 2.4.1 points to revision A. The presenter then shows a record for version 2.4.2 pointing to B. These names, versions and observations are invented for teaching; no real package was tested.

The second record does not answer the first question. Your finding is: “The record examined for 2.4.1 points to A. The evidence connecting B concerns 2.4.2. We have not established that the delivered version includes B.” Request evidence for the delivered artifact or a corrected delivery statement.

Now suppose a reviewer finds the same fix implemented differently in A. That is new code-level evidence, and it could change the feature conclusion. It does not change which revision the provenance record names. Keeping these two findings separate makes the review easier to correct.

Use different endings for different gaps

• The relevant references agree: report the observed release-to-source connection and retain the links. Do not extend it to unrelated versions.
• No provenance was found for this version: state where you looked and what was absent. Request another traceable release record; do not manufacture an explanation for the absence.
• A reference is unavailable: preserve the message and access date. A missing page leaves a gap in your review, rather than proving what used to be there.
• The identifiers conflict: keep both exact values and ask which artifact the claim concerns before doing more comparisons.

npm explicitly cautions that established provenance does not guarantee the absence of malicious code. A documented build can produce unsafe software. A browser inspection is also not a local cryptographic verification or a reproducible rebuild; record those as unperformed if you did not do them.

Leave a release receipt

Claim and source:
Package name / registry / exact version:
How that version was identified:
Provenance page and observation time:
Source revision / build reference:
Expected revision from the claim:
Match, conflict, or missing evidence:
Next evidence needed:
Checks not performed:

Fill this receipt before collecting more screenshots. For a wider supplier investigation, attach it as one finding in a traceable OSINT report. The useful handoff is the exact unresolved connection, not an unexplained green badge.