npm-Provenance-Checker

What provenance proves

A tarball on the npm registry says nothing about where it came from: anyone who holds a publish token can upload anything under a package's name. npm provenance closes that gap. When a package is published from a supported CI system with npm publish --provenance — or through trusted publishing, where the CI job authenticates with OpenID Connect instead of a long-lived token — the CI job signs a statement of how the tarball was built, and the registry stores it next to the version. Since then, every version with provenance can be traced to the repository, the workflow file and the commit that produced it.

The checker asks the registry for two documents, exactly as npm audit signatures does: the version's metadata (registry.npmjs.org/<name>/<version>) and its attestations (registry.npmjs.org/-/npm/v1/attestations/<name>@<version>). The registry allows both requests from any web page, so your browser makes them itself; nothing passes through our server. A dist-tag such as latest is resolved to its exact version first.

Three signatures, one tarball

• The registry signature. Every version's dist.signatures holds an ECDSA signature by the registry over name@version:integrity, made with one of the keys npm publishes. The checker verifies it with a snapshot of those keys taken from the Sigstore TUF repository, and notes when the signing key has since been retired.
• The publish attestation. An in-toto statement signed with the registry's attestation key: npm vouches that this name and version, with this tarball digest, were published. It is a Sigstore bundle whose verification material is the key, not a certificate.
• The build provenance. An in-toto statement with a SLSA provenance v1 predicate, in a Sigstore bundle signed through Fulcio by the CI workflow itself and logged in Rekor. The checker verifies the bundle completely — certificate chain, transparency-log inclusion, signed timestamps, DSSE signature — against the committed Sigstore public-good root.

Both statements must name the package (pkg:npm/<name>@<version>) and the SHA-512 digest of the tarball from the version's integrity. Then the checker compares the build provenance with the certificate that signed it — repository, commit, ref, run and workflow must agree on both sides — and with the package: the repository the build ran in must be the one package.json declares, and a gitHead that differs from the built commit is flagged. A version without attestations is reported as published without provenance: nothing is wrong with it, but nothing links it to source code either.

The full bundles behind the attestations can be pasted into the Sigstore bundle verifier, and the statements read in detail with the in-toto attestation viewer. If npm audit signatures reports an invalid registry signature, or publishing with provenance fails with “Automatic provenance generation not supported for provider”, those pages explain why. How provenance fits into signing releases in general is the subject of Signing releases with Sigstore.