feat: VerifyNpmPackage API with supplied tuf client

cli/slsa-verifier/main_regression_test.go

@@ -1775,8 +1775,6 @@ func Test_runVerifyNpmPackage(t *testing.T) {
 	for _, tt := range tests {
 		tt := tt // Re-initializing variable so it is not changed while executing the closure below
 		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
 			artifactPath := filepath.Clean(filepath.Join(TEST_DIR, "npm", "gha", tt.artifact))
 			attestationsPath := fmt.Sprintf("%s.json", artifactPath)
 			cmd := verify.VerifyNpmPackageCommand{

docs/API-Library.md

@@ -0,0 +1,77 @@
+# Api Library
+
+## Verifers
+
+We have exported functions for using slsa-verifier within your own golang packages
+
+- slsa-verifier/verifiers/verifier.go
+
+### Npmjs
+
+With `VerifyNpmPackageWithSigstoreTUFClient`, you can pass in your own TUF client with custom options.
+For example, use the embedded TUF root with `sigstoreTUF.DefaultOptions().WithForceCache()`.
+
+Example:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	sigstoreTUF "github.com/sigstore/sigstore-go/pkg/tuf"
+	options "github.com/slsa-framework/slsa-verifier/v2/options"
+	apiVerify "github.com/slsa-framework/slsa-verifier/v2/verifiers"
+	apiUtils "github.com/slsa-framework/slsa-verifier/v2/verifiers/utils"
+)
+
+func main() {
+	builderID, err := doVerify()
+	if err != nil {
+		log.Fatalf("Verifying npm package: FAILED: %w", err)
+	}
+	fmt.Printf("builderID: %s\nVerifying npm package: PASSED", builderID.Name())
+}
+
+func doVerify() (*apiUtils.TrustedBuilderID, error) {
+	packageVersion := "0.1.127"
+	packageName := "@ianlewis/actions-test"
+	builderID := "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_nodejs_slsa3.yml"
+	attestations, err := os.ReadFile("attestations.json")
+	if err != nil {
+		return nil, fmt.Errorf("reading attestations file: %w", err)
+	}
+	tarballHash := "ab786dbef723164a605e55ff0ebe83f8e879159bd411980d4423c9b1646b858a537b4bc4d494fc8f71195db715e5c5e9ab4b8809f8b1b399cd30ac053d180ba7"
+	provenanceOpts := &options.ProvenanceOpts{
+		ExpectedSourceURI:      "github.com/ianlewis/actions-test",
+		ExpectedDigest:         "ab786dbef723164a605e55ff0ebe83f8e879159bd411980d4423c9b1646b858a537b4bc4d494fc8f71195db715e5c5e9ab4b8809f8b1b399cd30ac053d180ba7",
+		ExpectedPackageName:    &packageName,
+		ExpectedPackageVersion: &packageVersion,
+	}
+	builderOpts := &options.BuilderOpts{
+		ExpectedID: &builderID,
+	}
+	// example: force using the embedded root, without going online for a refresh
+	// opts := sigstoreTUF.DefaultOptions().WithForceCache()
+	// example: supply your own root
+	// opts := sigstoreTUF.DefaultOptions().WithRoot([]byte(`{"signed":{"_type":"root","spec_version":"1.0","version":9,"expires":"2024-09-12T06:53:10Z","keys":{"1e1d65ce98b10 ...`)).WithForceCache()
+	// example: use our uility method for making a client
+	// client, err := apiUtils.NewSigstoreTUFClient()
+	opts := sigstoreTUF.DefaultOptions()
+	client, err := sigstoreTUF.New(opts)
+	if err != nil {
+		return nil, fmt.Errorf("creating SigstoreTUF client: %w", err)
+	}
+	verifierOptioners := []options.VerifierOptioner{
+		options.WithSigstoreTUFClient(client),
+	}
+	_, outBuilderID, err := apiVerify.VerifyNpmPackageWithSigstoreTUFClient(context.Background(), attestations, tarballHash, provenanceOpts, builderOpts, verifierOptioners...)
+	if err != nil {
+		return nil, fmt.Errorf("Verifying npm package: FAILED: %w", err)
+	}
+	return outBuilderID, nil
+}
+```

errors/errors.go

@@ -44,4 +44,5 @@ var (
 	ErrorInvalidHash               = errors.New("invalid hash")
 	ErrorNotPresent                = errors.New("not present")
 	ErrorInvalidPublicKey          = errors.New("invalid public key")
+	ErrorCouldNotFindTarget        = errors.New("could not get the target from the tuf root")
 )

options/options.go

@@ -1,5 +1,9 @@
 package options
 
+import (
+	apiUtils "github.com/slsa-framework/slsa-verifier/v2/verifiers/utils"
+)
+
 // ProvenanceOpts are the options for checking provenance information.
 type ProvenanceOpts struct {
 	// ExpectedBranch is the expected branch (github_ref or github_base_ref) in
@@ -37,3 +41,21 @@ type BuilderOpts struct {
 	// ExpectedBuilderID is the builderID passed in from the user to be verified
 	ExpectedID *string
 }
+
+// VerifierOpts are the options for the verifier, created with the VerifierOptioner functions.
+// In the future, this can include a logger and a rekor client,
+// or be a standalone argument to the verifier functions.
+type VerifierOpts struct {
+	// SigstoreTufClient is the Sigstore TUF client, used for retrieving the Npmjs public keys
+	SigstoreTUFClient apiUtils.SigstoreTUFClient
+}
+
+// VerifierOptioner is a function that sets options for the verifier.
+type VerifierOptioner func(opt *VerifierOpts)
+
+// WithSigstoreTUFClient sets the Sigstore TUF client for the verifier.
+func WithSigstoreTUFClient(sigstoreTUFClient apiUtils.SigstoreTUFClient) VerifierOptioner {
+	return func(opt *VerifierOpts) {
+		opt.SigstoreTUFClient = sigstoreTUFClient
+	}
+}

register/register.go

@@ -33,6 +33,7 @@ type SLSAVerifier interface {
 		attestations []byte, tarballHash string,
 		provenanceOpts *options.ProvenanceOpts,
 		builderOpts *options.BuilderOpts,
+		verifierOptioners ...options.VerifierOptioner,
 	) ([]byte, *utils.TrustedBuilderID, error)
 }
 

verifiers/internal/gcb/verifier.go

@@ -44,6 +44,7 @@ func (v *GCBVerifier) VerifyNpmPackage(ctx context.Context,
 	attestations []byte, tarballHash string,
 	provenanceOpts *options.ProvenanceOpts,
 	builderOpts *options.BuilderOpts,
+	verifierOptioners ...options.VerifierOptioner,
 ) ([]byte, *utils.TrustedBuilderID, error) {
 	return nil, nil, serrors.ErrorNotSupported
 }

verifiers/internal/gha/npm.go

@@ -13,6 +13,7 @@ import (
 
 	intoto "github.com/in-toto/in-toto-golang/in_toto"
 	"github.com/secure-systems-lab/go-securesystemslib/dsse"
+	sigstoreTUF "github.com/sigstore/sigstore-go/pkg/tuf"
 	serrors "github.com/slsa-framework/slsa-verifier/v2/errors"
 	"github.com/slsa-framework/slsa-verifier/v2/options"
 	"github.com/slsa-framework/slsa-verifier/v2/verifiers/internal/gha/slsaprovenance"
@@ -32,6 +33,9 @@ const (
 var errrorInvalidAttestations = errors.New("invalid npm attestations")
 var attestationKeyAtomicValue atomic.Value
 
+// cache the default Sigstore TUF client.
+var defaultSigstoreTUFClientAtomicValue atomic.Value
+
 type attestationSet struct {
 	Attestations []attestation `json:"attestations"`
 }
@@ -56,6 +60,7 @@ type Npm struct {
 	verifiedPublishAtt    *SignedAttestation
 	provenanceAttestation *attestation
 	publishAttestation    *attestation
+	verifierOpts          *options.VerifierOpts
 }
 
 func (n *Npm) ProvenanceEnvelope() *dsse.Envelope {
@@ -66,25 +71,62 @@ func (n *Npm) ProvenanceLeafCertificate() *x509.Certificate {
 	return n.verifiedProvenanceAtt.SigningCert
 }
 
-func NpmNew(ctx context.Context, root *TrustedRoot, attestationBytes []byte) (*Npm, error) {
+// NpmNew creates a new Npm verifier.
+func NpmNew(ctx context.Context, root *TrustedRoot, attestationBytes []byte, verifierOptioners ...options.VerifierOptioner) (*Npm, error) {
 	var aSet attestationSet
 	if err := json.Unmarshal(attestationBytes, &aSet); err != nil {
 		return nil, fmt.Errorf("%w: json.Unmarshal: %v", errrorInvalidAttestations, err)
 	}
-
 	prov, pub, err := extractAttestations(aSet.Attestations)
 	if err != nil {
 		return nil, err
 	}
+	verifierOpts, err := getVerifierOpts(verifierOptioners...)
+	if err != nil {
+		return nil, err
+	}
 	return &Npm{
 		ctx:  ctx,
 		root: root,
 
 		provenanceAttestation: prov,
 		publishAttestation:    pub,
+		verifierOpts:          verifierOpts,
 	}, nil
 }
 
+// getDefaultSigstoreTUFClient returns the default Sigstore TUF client.
+func getDefaultSigstoreTUFClient() (utils.SigstoreTUFClient, error) {
+	value := defaultSigstoreTUFClientAtomicValue.Load()
+	if value != nil {
+		return value.(utils.SigstoreTUFClient), nil
+	}
+	sigstoreTUFClient, err := sigstoreTUF.DefaultClient()
+	if err != nil {
+		return nil, err
+	}
+	defaultSigstoreTUFClientAtomicValue.Store(sigstoreTUFClient)
+	return sigstoreTUFClient, nil
+}
+
+// getVerifierOpts returns the verifier options, adding missing options with default values.
+func getVerifierOpts(verifierOptioners ...options.VerifierOptioner) (*options.VerifierOpts, error) {
+	// Set the verifier options.
+	verifierOpts := &options.VerifierOpts{}
+	for _, optioner := range verifierOptioners {
+		optioner(verifierOpts)
+	}
+	// Set the Sigstore TUF client, if not set.
+	if verifierOpts.SigstoreTUFClient == nil {
+		sigstoreTUFClient, err := getDefaultSigstoreTUFClient()
+		if err != nil {
+			return nil, err
+		}
+		verifierOpts.SigstoreTUFClient = sigstoreTUFClient
+	}
+	return verifierOpts, nil
+}
+
 func extractAttestations(attestations []attestation) (*attestation, *attestation, error) {
 	if len(attestations) < 2 {
 		return nil, nil, fmt.Errorf("%w: invalid number of attestations: %v", errrorInvalidAttestations, len(attestations))
@@ -111,12 +153,12 @@ func extractAttestations(attestations []attestation) (*attestation, *attestation
 }
 
 // getAttestationKey retrieves the attestation key and holds it in memory.
-func getAttestationKey(npmRegistryPublicKeyID string) (string, error) {
+func getAttestationKey(sigstoreTUFClient utils.SigstoreTUFClient, npmRegistryPublicKeyID string) (string, error) {
 	value := attestationKeyAtomicValue.Load()
 	if value != nil {
 		return value.(string), nil
 	}
-	npmRegistryPublicKey, err := getKeyDataFromSigstoreTuf(npmRegistryPublicKeyID, attestationKeyUsage)
+	npmRegistryPublicKey, err := getKeyDataFromSigstoreTUF(sigstoreTUFClient, npmRegistryPublicKeyID, attestationKeyUsage)
 	if err != nil {
 		return "", err
 	}
@@ -147,7 +189,7 @@ func (n *Npm) verifyPublishAttestationSignature() error {
 
 	// Retrieve the key material.
 	// We found the associated public key in the TUF root, so now we can trust this KeyID.
-	npmRegistryPublicKey, err := getAttestationKey(npmRegistryPublicKeyID)
+	npmRegistryPublicKey, err := getAttestationKey(n.verifierOpts.SigstoreTUFClient, npmRegistryPublicKeyID)
 	if err != nil {
 		return err
 	}

verifiers/internal/gha/npm_sigstore_tuf.go

@@ -6,7 +6,8 @@ import (
 	"fmt"
 	"time"
 
-	sigstoreTuf "github.com/sigstore/sigstore-go/pkg/tuf"
+	serrors "github.com/slsa-framework/slsa-verifier/v2/errors"
+	"github.com/slsa-framework/slsa-verifier/v2/verifiers/utils"
 )
 
 const (
@@ -16,7 +17,6 @@ const (
 
 var (
 	errorMissingNpmjsKeyIDKeyUsage = errors.New("could not find a key with the specified 'keyId' and 'keyUsage'")
-	errorCouldNotFindTarget        = errors.New("could not get the target from the tuf root")
 	errorCouldNotParseKeys         = errors.New("could not parse keys file content")
 )
 
@@ -38,27 +38,13 @@ type validFor struct {
 	Start time.Time `json:"start"`
 }
 
-type sigstoreTufClient interface {
-	GetTarget(target string) ([]byte, error)
-}
-
-// newSigstoreTufClient gets a Sigstore TUF client, which itself is a wrapper around the official TUF client.
-func newSigstoreTufClient() (*sigstoreTuf.Client, error) {
-	opts := sigstoreTuf.DefaultOptions()
-	client, err := sigstoreTuf.New(opts)
-	if err != nil {
-		return nil, fmt.Errorf("creating SigstoreTuf client: %w", err)
-	}
-	return client, nil
-}
-
 // getNpmjsKeysTarget will fetch and parse the keys.json file in Sigstore's root for npmjs
 // The inner TUF client will verify this "blob" is signed with correct delegate TUF roles
 // https://github.com/sigstore/root-signing/blob/5fd11f7ec0a993b0f20c335b33e53cfffb986b2e/repository/repository/targets/registry.npmjs.org/7a8ec9678ad824cdccaa7a6dc0961caf8f8df61bc7274189122c123446248426.keys.json#L4
-func getNpmjsKeysTarget(client sigstoreTufClient, targetPath string) (*npmjsKeysTarget, error) {
+func getNpmjsKeysTarget(client utils.SigstoreTUFClient, targetPath string) (*npmjsKeysTarget, error) {
 	blob, err := client.GetTarget(targetPath)
 	if err != nil {
-		return nil, fmt.Errorf("%w: %w", errorCouldNotFindTarget, err)
+		return nil, fmt.Errorf("%w: %w", serrors.ErrorCouldNotFindTarget, err)
 	}
 	var keys npmjsKeysTarget
 	if err := json.Unmarshal(blob, &keys); err != nil {
@@ -79,18 +65,15 @@ func getKeyDataWithNpmjsKeysTarget(keys *npmjsKeysTarget, keyID, keyUsage string
 	return "", fmt.Errorf("%w: 'keyId': %q, 'keyUsage':%q", errorMissingNpmjsKeyIDKeyUsage, keyID, keyUsage)
 }
 
-// getKeyDataFromSigstoreTuf retrieves the keyfile from sigstore's TUF root, parses the file and returns the target key's material.
+// getKeyDataFromSigstoreTUF retrieves the keyfile from sigstore's TUF root, parses the file and returns the target key's material.
 // See documentation for getNpmjsKeysTarget
 //
 // example params:
 //
-//	keyID: "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"
-//	keyUsage: "npm:attestations"
-func getKeyDataFromSigstoreTuf(keyID, keyUsage string) (string, error) {
-	client, err := newSigstoreTufClient()
-	if err != nil {
-		return "", err
-	}
+//	 client: sigstoreTUFClient
+//		keyID: "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"
+//		keyUsage: "npm:attestations"
+func getKeyDataFromSigstoreTUF(client utils.SigstoreTUFClient, keyID, keyUsage string) (string, error) {
 	keys, err := getNpmjsKeysTarget(client, targetPath)
 	if err != nil {
 		return "", err