Glossary / Package provenance
Package provenance
Package provenance is verifiable information about how, where, and from which source a package artifact was built and published. It can help consumers connect a registry artifact to a source repository and build workflow, strengthening supply-chain auditing; provenance is evidence about origin and process, not a guarantee that code is safe.
Attestations and verification
A provenance attestation commonly identifies the artifact digest, source repository and revision, builder identity, and build invocation or workflow. npm supports provenance publication for eligible CI environments and exposes attestations for packages; npm CLI can verify registry signatures and provenance for supported registry artifacts. Exact support varies by registry, package, CLI version, and publishing setup.
Verification asks whether the attestation is authentic and whether its claims match policy: expected repository, branch/tag, builder, workflow, and source revision. A valid signature alone only says the attestation came from the asserted identity; it does not establish that the workflow was uncompromised or the source was reviewed. Consumers should compare provenance claims to trusted policy and retain artifact digests.
Engineering guidance
Publish from a controlled CI workflow with protected branches, minimal token permissions, immutable release inputs, and short-lived credentials. Verify provenance in a consumer pipeline when available and record the result. Combine it with lockfile review, vulnerability analysis, release monitoring, and reproducible or hermetic build practices where feasible.
Interview questions
- What does provenance establish? Evidence connecting a package artifact to source and a build process.
- Does valid provenance mean the package is safe? No; it authenticates claims about origin/process, not code quality or absence of compromise.
- What claims should policy inspect? Repository, revision, trusted builder/workflow, and artifact digest.
- Why short-lived CI credentials? They reduce exposure if logs, runners, or tokens are compromised.
- How does provenance fit with lockfiles? Lockfiles pin package resolution; provenance adds verifiable origin/build evidence.