Provenance should be more prominent

[Jack-Works]

Currently, the provenance is listed under the readme, IMO it should be in the sidebar.

[feelepxyz]

@Jack-Works appreciate the feedback! We're thinking of ways to improve this.

[ljharb]

@JoshuaBrest the only thing it verifies is the publish location (which, for github, includes a repo and a github action workflow file/sha)

[feelepxyz]

the npm website's badge says "build provenance" which is the problematic claim

This is a fair point and maybe we should say something like Published and signed on 🤔

@JoshuaBrest the only thing it verifies is the publish location (which, for github, includes a repo and a github action workflow file/sha)

It might be helpful to dig into the details a bit here. npm provenance is leveraging claims from the OIDC ID token that CI/CD providers like Actions and GitLab expose as part of a workflow/pipeline job. This contains signed metadata about the triggering event. For example, you have a workflow that publishes when you push to a branch. The provenance will include this metadata about the triggering event that kicked off the job that published the package.

If you have a basic workflow that just runs actions/checkout and npm publish you will be building and publishing from the exact source commit that's linked. But as always, there are many many ways of doing something funky, like checking out a different commit/branch, or run a build script that downloads stuff and injects it in the package.

Provenance does not make any guarantees about what happens during build, not does it protect against source code compromise which is often a pre-requisite for these types of attacks. What it gives you is a verifiable pointer to the originating trigger/workflow that published the package. This should be seen as an "identity", similar to who the maintainer is.

This gives you another signal to trust vs just that a authorized maintainer published the package. An attacker would now need to take over both your npm account and github account! This is only getting harder with maintainers adopting 2FA, turning on branch protections etc.

Take create-next-app for example. If you know that vercel maintain it you would expect the package to come from a repo like vercel/create-next-app (in this case it's a monorepo vercel/next.js). If suddenly it comes from a different user/org, there's cause for concern, and with provenance we have a way of detecting these types of changes.

[feelepxyz]

Additionally, if the package does not have provenance, there should be a box like this.

I'm not sure we want to go down this road for packages that don't have provenance as this would penalise legacy packages that don't need/require any updates (something @ljharb pointed out previously). Take lodash as an example, it's pretty stable and was last released 2 years ago.

What I'm envisioning are more ways of working with provenance as a trusted identity for a package, e.g. warn when it changes when updating dependencies, allow users to have policies that enforce it for certain packages, or block unexpected changes during publish/force additional verification to change.

[ljharb]

Since you're publishing from github with a stored npm secret, in fact it means they'd only need to take over your github account (which lets them bypass branch protections in most cases), not your npm account.

[JoshuaBrest]

What I'm envisioning are more ways of working with provenance as a trusted identity for a package, e.g. warn when it changes when updating dependencies, allow users to have policies that enforce it for certain packages, or block unexpected changes during publish/force additional verification to change.

Maybe only show for for newly updated/created packages. @feelepxyz

[panva]

I've learned (from a private discussion with @MylesBorins) that publishing with provenance cross checks the URLs (at the very least repository?) in package.json.

This means that the same check mark can be placed next to the repository sidebar section as well.

Edit: I would definitely appreciate a check list of cross checks the publishing does listed somewhere because this point wasn't apparent from the announcement or the docs on npmjs.

[feelepxyz]

@panva yeah we're thinking of ways to make this information easier to find and tying this to the repo could make sense.

I would definitely appreciate a check list of cross checks the publishing does listed somewhere

👍 we might codify this in a spec eventually, but for now, the registry does the following checks before accepting a publish with provenance:

• Verifies the provenance attestation is for the particular package, name and tarball shasum being published (this info is in the signed attestation subject) (open the Attestation drawer to see the subject on this page)
• Verifies the provenance details (repo, ref, sha etc) match what's in the signing certificate, and what was signed by the CI/CD system (check the values in the Public Key Certificate here)
• Verifies the repository in package.json is set and matches the one in the signed provenance attestation
• Verifies the signed provenance bundle using sigstore-js verify: https://github.com/sigstore/sigstore-js/#verifybundle-payload-options (checks it was signed by Sigstore, was signed during publish etc)
• Verifies the CI/CD system is supported (currently GitHub Actions, soon GitLab and hopefully others)

[feelepxyz]

When you run npm audit signatures on installed packages with provenance we run the following checks:

• Verifies the provenance attestation is for the particular package, name and tarball shasum that was installed (this info is in the signed attestation subject) (open the Attestation drawer to see the subject on this page)
• Verifies the signed provenance bundle using sigstore-js verify: https://github.com/sigstore/sigstore-js/#verifybundle-payload-options (checks it was signed by Sigstore, was signed during publish etc)
• Verifies the npm registry accepted the publish with provenance (indirectly asserting all the above checks)

[carmithershman]

Hello @feelepxyz, can you please point me to a documentation of how to add integration to npm --provenance as CI/CD and registries vendor? I would like to look into this

[feelepxyz]

@carmithershman yes I'm planning to write something up integrating provenance into a registry vendor, I'll let you know when we have an early draft. We've also got a work in progress document for CI/CD vendors that I'm hoping we can share soon, maybe next week.

[carmithershman]

Hi Philip Thank you, I am waiting for your update Best Regards Carmit Hershman

…

On Fri, May 5, 2023 at 6:05 PM Philip Harrison ***@***.***> wrote: @carmithershman <https://github.com/carmithershman> yes I'm planning to write something up integrating provenance into a registry vendor, I'll let you know when we have an early draft. We've also got a work in progress document for CI/CD vendors that I'm hoping we can share soon, maybe next week. — Reply to this email directly, view it on GitHub <https://github.com/npm/feedback/discussions/908#discussioncomment-5817060>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A6GUMYD74ORN6EALW2VQ2U3XEUJMFANCNFSM6AAAAAAXEOHV2E> . You are receiving this because you were mentioned.Message ID: ***@***.***>