feat: VerifyNpmPackage API with supplied tuf client

[ramonpetgrave64]

This PR

• allow supplying a SigstoreTufClient
• adds a guide on how to use in ./docs/Api-Library.md
• enables --print-provenance

Offline rekor verification already works so long as the provenance is a valid sigstore bundle, though we could consider adding an explicit option to enforce offline rekor verifification.

• https://github.com/ramonpetgrave64/slsa-verifier/blob/a2edf56f612f6ef4baef66fb07cd62988432d357/verifiers/internal/gha/provenance.go#L217-L229

Fixes #493

Testing

• manual invocation of the tool
• unit added regression tests
• used the library from another demo module, like in ./docs/Api-Library.md

Followups

• support the 1.0 provenance spec
  • https://github.com/slsa-framework/slsa-verifier/issues/614
• use a logger, rather than printing the intermediate messages, https://github.com/slsa-framework/slsa-verifier/pull/772
  • https://github.com/slsa-framework/slsa-verifier/blob/e7a8f74b9ca5838dbb2042308c889db9e73886f7/verifiers/internal/gha/verifier.go#L89

[ramonpetgrave64]

@slugclub

[ramonpetgrave64]

This is looking great, thanks so much for working on this. I have a few minor nits but overall it's looking good.

Thanks for the review! I was also looking into logging in https://github.com/slsa-framework/slsa-verifier/pull/772,

[ramonpetgrave64]

@slugclub thanks again. @ianlewis @laurentsimon , please take a look

[haydentherapper]

cc @loosebazooka

[ramonpetgrave64]

@loosebazooka

[ramonpetgrave64]

@loosebazooka

[loosebazooka]

On the sigstore clients we actually just accept a trusted_root.json as an input to the verifier -- this would require depending on sigstore-go instead of cosign and I'm not sure where we're at here. However this eliminates the need for consumers to define a whole TUF client, they may compute trusted_root.json some other way.

[haydentherapper]

I could see a need for both - a user may gather their own root material out of band, at which point they should pass that material via a trusted root file, to align with the other Sigstore clients (and sigstore-go has an API for this). A developer integrating with the API may be opinionated on TUF settings and construct their own client (or pass options).

[ramonpetgrave64]

I just don't think slsa-verifier should be involved in the lower-level details of the TUF client.

[haydentherapper]

I just don't think slsa-verifier should be involved in the lower-level details of the TUF client.

Could you say by what you mean on lower-level details? Do you mean the configuration of the TUF client?

In terms on an API, I think we could see a few different options:

• No changes, accept default - This will be for most users imo.
• Providing trust root material directly - This is useful for private deployments or private PKI, and the API take in Sigstore's trust root format. I think this would be an alternative to the proposed API that involves implementing a client that fetches targets.
• A user who wants to configure certain settings for the TUF client - This would be a user who very much understands the implementation details of TUF and wants to control caching, which I don't think is likely, but could happen. An alternative is providing a TUF client.

[ramonpetgrave64]

Could you say by what you mean on lower-level details? Do you mean the configuration of the TUF client?

I mean the trusted_root.json file, and managing potential refreshes in a long-running process.

• A user who wants to configure certain settings for the TUF client - This would be a user who very much understands the implementation details of TUF and wants to control caching, which I don't think is likely, but could happen. An alternative is providing a TUF client.

But a user still has to know how to prepare a trusted_root.json properly. Ideally, the Sigstore TUF client can handle those cache-control options and make it easy for the user.

I would rather the user instead supply the trusted_root.json to their own TUF client, and then supply that to slsa-verifier.

For the CLI, if we wanted the same kind of customization, then supplying the trusted_root.json directly makes more sense, but we may still have to worry about refreshes. We can consider that feature later if there is community ask for it.

[haydentherapper]

I think there may be some conflation of "roots". https://pkg.go.dev/github.com/sigstore/sigstore-go@v0.5.1/pkg/tuf#Options.WithRoot refers to the TUF root, as in the root of trust for the TUF metadata. The "trusted root" is the Sigstore spec-compliant file that contains all of the roots of trust for the services within Sigstore's infra.

Regarding "we may still have to worry about refreshes", in the case that someone would supply a trusted root file directly, that effectively says "bypass TUF, don't worry about keeping metadata up to date".

For a user, they could either supply a TUF client which goes and fetches a "trusted root", or they supply the "trusted root" directly bypassing TUF (if they don't maintain their own TUF repo, for example, or want offline verification).

As for TUF caching options, I think that's mostly up to the library, and I don't think we must expose that right of the bat. Some users might be opinionated, so for example in Cosign, we allow disabling the cache, but we don't expose every TUF client option.

[ramonpetgrave64]

Alright. For now, it's simpler and more flexible to the user for slsa-verifier to accept a sigstore TUF client.