Package Provenance

Package provenance is a signed statement, generated by a CI build platform, that names the source repository, commit, and workflow that produced a specific package file, bound to that file's hash. npm provenance and PyPI digital attestations both implement it with Sigstore. Package provenance proves where and how a package was built, not whether its code is safe.

The same record goes by several names: npm provenance on npm, digital attestations on PyPI, and build provenance in the SLSA specification. Mechanically, a CI job trades its OpenID Connect (OIDC) identity token for a short-lived Sigstore certificate that encodes its workflow identity, signs an in-toto statement containing the package file's SHA hash, and records the signature in a public transparency log. The registry stores the statement next to the file.

The most important fact about package provenance is what it leaves out. It names a commit, and it attests the hash of the file that came out of the build, but nothing in it shows that the commit produced the file. On November 3, 2026, we compared zod@4.6.7 with the commit its provenance names. 505 of its 840 files are not in that commit, including the index.js and index.cjs files Node actually loads. The build generated them. Our position: verify provenance, pin the repository and workflow you expect, and treat a change in either as a security event. Then analyze what is actually in the tarball, because the code you run is the part no one attested.

npm package provenance, usually called npm provenance, is npm's implementation of package provenance. GitHub announced it on April 19, 2023, and we explained what it does and does not check in our post on npm's provenance launch. A package gets it when a maintainer publishes from GitHub Actions or GitLab CI/CD on a cloud-hosted runner with npm CLI 9.5.0 or later, per npm's documentation. Since npm adopted trusted publishing in July 2025, the CLI also generates provenance automatically whenever a package is published through a trusted publisher.

Start with what a registry knows without provenance. npm publish packs a tarball on whatever machine runs it, and the registry stores those bytes under the publisher's credential. The repository field in package.json is a free-text claim. Nothing ties the tarball to a commit, which is what makes starjacking work: a package can point its repository field at a popular project it has nothing to do with.

Provenance adds two checks at publish time, documented in npm's provenance design notes. The registry verifies that the package name, version, and SHA-512 match the signed statement's subject. It also verifies that the repository field in package.json matches the source repository in the signing certificate. A starjacked repository field cannot carry a provenance badge.

The result is visible in the version document the registry serves for every release:

$ curl -s https://registry.npmjs.org/semver/7.8.6 \
    | jq '{gitHead, repository, _npmUser: ._npmUser | {name, trustedPublisher}, dist: .dist | {integrity, attestations}}'
{
  "gitHead": "b37b033b585ad5e575afeccadb426ea41bc6cea4",
  "repository": { "url": "git+https://github.com/npm/node-semver.git", "type": "git" },
  "_npmUser": {
    "name": "GitHub Actions",
    "trustedPublisher": { "id": "github", "oidcConfigId": "7a0c479c-0252-4ccd-81e5-c43546a76551" }
  },
  "dist": {
    "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==",
    "attestations": {
      "url": "https://registry.npmjs.org/-/npm/v1/attestations/semver@7.8.6",
      "provenance": { "predicateType": "https://slsa.dev/provenance/v1" }
    }
  }
}

The attestations URL returns two signed statements. The publish attestation, with predicate type https://github.com/npm/attestation/tree/main/specs/publish/v0.1, is signed by the registry with npm's own key and says only that npm accepted this name, version, and digest. The provenance attestation, with predicate type https://slsa.dev/provenance/v1, is signed inside the CI job and carries the build description.

A provenance attestation is a Dead Simple Signing Envelope (DSSE) whose payload is an in-toto statement. Decoded, the statement for semver@7.8.6 reads:

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{
    "name": "pkg:npm/semver@7.8.6",
    "digest": { "sha512": "f65a52494e0c972de6aedaeec0bb3578b2bafa0cdbcea78117044d8c88c4fbd2ee0e959d61cb6b4254377a3d489608bb8249e9b134673e82cff03a421ea1c827" }
  }],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1",
      "externalParameters": {
        "workflow": { "ref": "refs/heads/main", "repository": "https://github.com/npm/node-semver", "path": ".github/workflows/release.yml" }
      },
      "internalParameters": {
        "github": { "event_name": "push", "repository_id": "1357199", "repository_owner_id": "6078720" }
      },
      "resolvedDependencies": [{
        "uri": "git+https://github.com/npm/node-semver@refs/heads/main",
        "digest": { "gitCommit": "b37b033b585ad5e575afeccadb426ea41bc6cea4" }
      }]
    },
    "runDetails": {
      "builder": { "id": "https://github.com/actions/runner/github-hosted" },
      "metadata": { "invocationId": "https://github.com/npm/node-semver/actions/runs/41486847600/attempts/1" }
    }
  }
}

Each field answers one narrow question:

The envelope is signed with a certificate from Fulcio, Sigstore's certificate authority, valid for 10 minutes, from 17:04:44 to 17:14:44 UTC on November 2, 2026. Rekor, Sigstore's transparency log, recorded the signature at 17:04:45 UTC at log index 3,644,633,127. Decoded with openssl x509 -inform der -text and trimmed, the certificate shows one detail that trips up most verification policies:

X509v3 Subject Alternative Name: critical
    URI:https://github.com/npm/node-semver/.github/workflows/release-integration.yml@refs/heads/main
1.3.6.1.4.1.57264.1.1:  https://token.actions.githubusercontent.com          # OIDC issuer
1.3.6.1.4.1.57264.1.3:  b37b033b585ad5e575afeccadb426ea41bc6cea4             # commit
1.3.6.1.4.1.57264.1.11: github-hosted                                        # runner environment
1.3.6.1.4.1.57264.1.18: https://github.com/npm/node-semver/.github/workflows/release.yml@refs/heads/main   # build config
1.3.6.1.4.1.57264.1.21: https://github.com/npm/node-semver/actions/runs/41486847600/attempts/1

The statement names release.yml. The certificate's Subject Alternative Name (SAN), the identity Sigstore actually verified, names release-integration.yml. semver's release.yml calls release-integration.yml as a reusable workflow, and that reusable workflow runs npm publish --provenance. Fulcio's OID reference records the caller separately, as the Build Config URI. A policy that copies the workflow path from the statement into the signer check rejects this legitimate release. We show that failure below.

PyPI digital attestations carry less in the signed statement and more in the certificate. PEP 740 defines the format. PyPI's digital attestations launch on November 14, 2024 arrived with more than 20,000 attestations already uploaded. Projects that publish through a trusted publisher with PyPA's official GitHub action get them by default.

PyPI attests each file, not each release. The Simple JSON API points every wheel and sdist at its own provenance object:

$ curl -s -H 'Accept: application/vnd.pypi.simple.v1+json' https://pypi.org/simple/urllib3/ \
    | jq '.files[] | select(.filename == "urllib3-2.8.0-py3-none-any.whl") | {filename, hashes, provenance}'
{
  "filename": "urllib3-2.8.0-py3-none-any.whl",
  "hashes": { "sha256": "0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3" },
  "provenance": "https://pypi.org/integrity/urllib3/2.8.0/urllib3-2.8.0-py3-none-any.whl/provenance"
}

That provenance object groups attestations by publisher. Decoded, its single bundle reads:

{
  "publisher": { "kind": "GitHub", "repository": "urllib3/urllib3", "workflow": "publish.yml", "environment": "publish" },
  "statement": {
    "_type": "https://in-toto.io/Statement/v1",
    "subject": [{ "name": "urllib3-2.8.0-py3-none-any.whl",
                  "digest": { "sha256": "0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3" } }],
    "predicateType": "https://docs.pypi.org/attestations/publish/v1",
    "predicate": null
  }
}

The predicate is null. There is no SLSA build definition and no commit in the statement. The commit b1d30ab61fe0db8f11092805e8c5ac43e091064a, the ref refs/tags/2.8.0, and the deployment environment publish exist only in the Fulcio certificate's extensions, issued at 19:29:31 UTC on September 15, 2026. A PyPI verifier has to read the certificate to learn what an npm verifier reads from the statement. The guarantee is the same: this file came out of this repository's publish.yml, running on that commit.

Verifying a package's provenance takes four checks. The signature must chain to Sigstore's trust root. The transparency log must have recorded it while the certificate was valid. The subject digest must equal the hash of the file you downloaded. The signer must be the identity you expected. Tools do the first three. The fourth is policy, and it is the only one that says anything about who built the package.

On npm, the built-in check is npm audit signatures. Per npm's design notes, it verifies the attestation against the installed name, version, and tarball, confirms the registry accepted the publish, chains the certificate to Sigstore's root, and checks the Rekor timestamp. It does not compare the signer with any expected identity. Nothing else in the client verifies provenance at all. We read npm 12.2.1, the latest release as of November 2026, and its fetcher pacote 22.0.1: the only code path that sets verifyAttestations: true is the one behind npm audit signatures. npm install never verifies attestations.

npm audit signatures failed in our sandbox with "Failed to download", because it could not reach Sigstore's The Update Framework (TUF) repository, which distributes the trust root. So we verified the semver@7.8.6 bundle offline with the @sigstore/verify library npm ships, using the trusted root npm bundles as its seed. We tried four identity policies:

// verify.cjs: run from a directory holding att.json, the attestations response for semver@7.8.6
const N = '/opt/node22/lib/node_modules/npm/node_modules/';
const { Verifier, toSignedEntity, toTrustMaterial } = require(N + '@sigstore/verify');
const { bundleFromJSON } = require(N + '@sigstore/bundle');
const { TrustedRoot } = require(N + '@sigstore/protobuf-specs');
const seeds = require(N + '@sigstore/tuf/seeds.json');
const root = JSON.parse(Buffer.from(Object.values(seeds)[0].targets['trusted_root.json'], 'base64'));
const verifier = new Verifier(toTrustMaterial(TrustedRoot.fromJSON(root)));
const att = require('./att.json').attestations.find(a => a.predicateType.includes('slsa'));
const entity = toSignedEntity(bundleFromJSON(att.bundle));
const wf = (repo, file) => ({
  subjectAlternativeName: `https://github.com/${repo}/.github/workflows/${file}@refs/heads/main`,
  extensions: { issuer: 'https://token.actions.githubusercontent.com' },
});
for (const [label, policy] of [
  ['no policy', undefined],
  ['predicate workflow path', wf('npm/node-semver', 'release.yml')],
  ['signer workflow', wf('npm/node-semver', 'release-integration.yml')],
  ['lookalike repo', wf('npm/node-semvar', 'release-integration.yml')],
]) {
  try { verifier.verify(entity, policy); console.log(`${label}: OK`); }
  catch (e) { console.log(`${label}: FAIL ${e.code}`); }
}

no policy: OK
predicate workflow path: FAIL UNTRUSTED_SIGNER_ERROR
signer workflow: OK
lookalike repo: FAIL UNTRUSTED_SIGNER_ERROR

The first line is the one npm audit signatures gives you: valid for any identity Fulcio ever certified. The second line is the reusable-workflow trap from the certificate above. The third line is a correct policy. The fourth line is the policy doing its job against a one-letter lookalike.

On PyPI, the pypi-attestations CLI refuses to verify without an expected identity. We downloaded the urllib3 wheel, confirmed its SHA-256 matches the attested digest, and ran it three ways, offline against the provenance object fetched above, saved as provenance.json:

$ pypi-attestations verify pypi --offline --provenance-file provenance.json \
    urllib3-2.8.0-py3-none-any.whl
Provenance signed by a repository, but no repository URL provided; use '--repository'

$ pypi-attestations verify pypi --offline --provenance-file provenance.json \
    --repository https://github.com/urllib3/urllib4 urllib3-2.8.0-py3-none-any.whl
Verification failed: provenance was signed by repository "urllib3/urllib3", expected "urllib3/urllib4"

$ pypi-attestations verify pypi --offline --provenance-file provenance.json \
    --repository https://github.com/urllib3/urllib3 urllib3-2.8.0-py3-none-any.whl
OK: urllib3-2.8.0-py3-none-any.whl

That design choice is the right one: PyPI's tool will not let you skip the identity check, and npm's will not let you run it. For artifacts outside registries, gh attestation verify plays the same role for GitHub artifact attestations, and its --signer-workflow flag pins the reusable workflow that signed.

Package provenance is a chain of custody with two signed links. In forensics, a chain of custody documents every hand that held a piece of evidence between collection and court. Package provenance signs the commit going into the build and the digest coming out. Everything in between is attested only as "this workflow ran on this commit."

The figure traces semver@7.8.6 through five stages. Stage 1 is the source commit, npm/node-semver at b37b033b on refs/heads/main: the repository, ref, and commit SHA the run was triggered on are signed. Stage 2 is the build job, which runs checkout, cache restore, dependency install, compile, and npm pack: the workflow file, run ID, and hosted runner are signed, which proves the job ran, but what each step did, the dependency and cache contents, any extra checkouts, and every file the build generated are not attested. Stage 3 is the tarball, semver-7.8.6.tgz with SHA-512 f65a5249…a1c827: its digest is signed as the statement subject. Stage 4 is the registry, which checks at publish time that the digest matches the subject and that package.json's repository field matches the certificate. Stage 5 is your install: as of npm 12.2.1, npm install never verifies attestations, and the opt-in npm audit signatures checks the certificate chain and digest but not the signer identity.

So we asked the question provenance does not answer: does the tarball contain what the commit contains? The check is short. Download the tarball, check out the commit its provenance names, and hash every file:

# compare.py: classify each file in an npm tarball against the provenance commit
import hashlib, os, sys
tarball_dir, source_dir = sys.argv[1], sys.argv[2]  # tar xzf *.tgz; git checkout <gitCommit>
counts = {"identical": 0, "differs": 0, "tarball-only": 0}
for root, _, files in os.walk(tarball_dir):
    for name in files:
        rel = os.path.relpath(os.path.join(root, name), tarball_dir)
        src = os.path.join(source_dir, rel)
        if not os.path.exists(src):
            counts["tarball-only"] += 1
        elif hashlib.sha256(open(src, "rb").read()).digest() == hashlib.sha256(open(os.path.join(root, name), "rb").read()).digest():
            counts["identical"] += 1
        else:
            counts["differs"] += 1
print(counts)

$ python3 compare.py semver/package node-semver@b37b033
{'identical': 54, 'differs': 0, 'tarball-only': 0}
$ python3 compare.py zod/package zod@b500a2ee/packages/zod
{'identical': 335, 'differs': 0, 'tarball-only': 505}

semver has no build step. All 54 files in semver@7.8.6 are byte-identical to commit b37b033b, so the provenance and the source together tell you exactly what you install. zod is TypeScript compiled at release. Of the 840 files in zod@4.6.7, 335 match commit b500a2ee byte for byte: the README, the license, package.json, and the TypeScript sources under src/. The other 505 are not in the commit at all: 124 .js files, 124 .cjs files, 248 type declarations (.d.ts and .d.cts), and 9 nested package.json files. package.json points import at ./index.js and require at ./index.cjs. Every line of zod that Node executes is in the 505.

That is normal for any package with a build step, and it is why the only full check is a rebuild. vlt's reproduce launch in February 2025 brought a tool that clones the attested commit, rebuilds, and compares integrity hashes. When vlt tested 5,000 high-impact npm packages, 5.78% reproduced and only 3.72% had provenance. Reproducibility, the stronger check, was already more common than provenance.

The diff matters because of how pipelines get compromised. In the openapi-react-query-codegen compromise on August 28, 2026, all ten malicious versions carried valid npm provenance naming commit d42d1733, the clean v3.0.2 commit. The release workflow ran on issue_comment, so GitHub recorded the default branch as the trigger, and then a step checked out a stranger's fork. The tarballs carried a 5.6 MB 3FWCvzduYZg.js loader and a malicious binding.gyp that are not in the commit their provenance names. A tarball-to-commit diff would have listed both files. In a package that compiles its code, they would have appeared alongside hundreds of legitimate build outputs, so only a rebuild separates them cleanly.

Package provenance proves that a specific CI workflow, running on a specific commit, produced a file with a specific hash. It also proves nobody changed that file after the build, on the registry or on any mirror. Forging it means compromising Sigstore, the CI provider's OIDC issuer, or the transparency log.

Package provenance does not prove the source was what the maintainers intended, that the build's inputs were clean, or that every step in the job was trustworthy. PyPI's attestation security model says it directly: "An attestation will tell you where a PyPI package came from, but not whether you should trust it."

The keyv and cacheable compromise on August 4, 2026 sits entirely outside what provenance can see. keyv@6.0.0 shipped with a passing attestation because the legitimate release workflow built source that was already trojanized. A provenance check could not flag it, and a tarball-to-commit diff would not help either, because the workflow faithfully built the trojanized source it was given. The contents told the story: the package's dist/ output was byte-identical to the clean 6.0.0-rc.1 build, and the only changes were package.json and two new files, a setup.mjs preinstall loader and a 728 KB Math_Symbol.js payload. Socket's malware detection flagged keyv@6.0.0 about six minutes after publication by analyzing those files, as we documented in our write-up of the keyv attack. Our conclusion there still holds: provenance attests build integrity, not source integrity.

The deeper failure mode is a compromised CI job. Any code that runs inside a job holding an OIDC grant can obtain the same signing identity as the release step, which is why GitHub Actions security is now part of every package's provenance.

Provenance is necessary but not sufficient, and it still earns its keep after an incident. In the Ultralytics compromise, the attestations on the malicious PyPI releases carried signed timestamps and source references that helped researchers confirm GitHub Actions cache poisoning. Security researcher Adnan Khan, who analyzed the attack, put the limit precisely: "Attestation only creates a tamper-proof guarantee between an artifact and a build job + commit."

Four mechanisms compete to answer "can I trust where this package came from?" Each answers a different question:

The verdict: use package provenance as the default origin check for anything built in public CI, and pin the repository and signer workflow per package. Use code signing where the build happens off public CI or must stay private. Use reproducible builds for packages critical enough to justify a rebuild, because only a rebuild connects the attested commit to the bytes you run. Treat a software bill of materials as an inventory, not an origin claim. None of the four tells you what the code does, which is why content analysis sits on top of all of them.

Provenance is most useful as a baseline that should not change. A package that has shipped from the same repository and workflow for years and suddenly publishes without provenance, or from a different workflow, deserves the scrutiny you would give a new maintainer. That pattern is the signature of a maintainer account takeover with a stolen token: the attacker can publish, but not from the project's CI. pnpm's trustPolicy: no-downgrade setting checks this at install time, flagging a version whose publishing method is weaker than that of earlier releases, as we covered when pnpm 11.5 added staged-publish support.

Requiring provenance everywhere is not yet practical. We checked the latest release of 30 widely used npm packages on November 3, 2026. 13 carried provenance and 14 were published through a trusted publisher. prettier@3.9.10 was trusted-published without provenance. lodash, typescript, eslint, @types/node, and 12 others had neither. Provenance also has hard prerequisites: npm requires a cloud-hosted runner and a public repository, so a package built on self-hosted infrastructure cannot have it. A missing attestation is a weak signal. A lost attestation is a strong one.

Registries now record two facts about every attested release: the commit that went into the build and the hash that came out. Neither npm nor PyPI checks that one produces the other. Until a registry rebuilds from the attested commit, or at least records whether an independent rebuild matched, package provenance tells you where to look. Reading what is there is still your job.