feat: VerifyNpmPackage API with supplied tuf client

cli/slsa-verifier/verify.go

@@ -164,10 +164,6 @@ func verifyNpmPackageCmd() *cobra.Command {
 				fmt.Fprintf(os.Stderr, "%s: --source-versioned-tag not supported\n", FAILURE)
 				os.Exit(1)
 			}
-			if cmd.Flags().Changed("print-provenance") {
-				fmt.Fprintf(os.Stderr, "%s: --print-provenance not supported\n", FAILURE)
-				os.Exit(1)
-			}
 			if cmd.Flags().Changed("builder-id") {
 				v.BuilderID = &o.BuilderID
 			}

docs/API-Library.md

@@ -0,0 +1,87 @@
+# Api Library
+
+## Verifers
+
+We have exported functions for using slsa-verifier within your own Go 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() {
+    provBytes, builderID, err := doVerify()
+    if err != nil {
+        log.Fatalf("Verifying npm package: FAILED: %w", err)
+    }
+    fmt.Fprintf(os.Stderr, "builderID: %s\n", builderID.Name())
+    fmt.Fprintf(os.Stderr, "Verifying npm package: PASSED")
+    fmt.Printf("%s", provBytes)
+}
+
+func doVerify() ([]byte, *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, nil, fmt.Errorf("creating sigstoreTUF client: %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: all the default ClientOpts
+    // clientOpts, err := options.NewDefaultClientOpts()
+
+    // example: get the default Sigstore TUF client that the library caches
+    // client, err := apiUtils.GetDefaultSigstoreTUFClient()
+
+    // 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: supply your own default Sigstore TUF client
+    opts := sigstoreTUF.DefaultOptions()
+    client, err := sigstoreTUF.New(opts)
+    if err != nil {
+        return nil, fmt.Errorf("creating SigstoreTUF client: %w", err)
+    }
+    clientOpts := options.ClientOpts{
+        SigstoreTUFClient: client,
+    }
+    provBytes, outBuilderID, err := apiVerify.VerifyNpmPackage(context.Background(), attestations, tarballHash, provenanceOpts, builderOpts, clientOpts)
+    if err != nil {
+        return nil, nil, fmt.Errorf("Verifying npm package: FAILED: %w", err)
+    }
+    return provBytes, outBuilderID, nil
+}
+```

errors/errors.go

@@ -44,11 +44,13 @@ 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")
 	ErrorInvalidVerificationResult = errors.New("verificationResult is not PASSED")
 	ErrorMismatchVerifiedLevels    = errors.New("verified levels do not match")
 	ErrorMissingSubjectDigest      = errors.New("missing subject digest")
 	ErrorEmptyRequiredField        = errors.New("empty value in required field")
 	ErrorMismatchResourceURI       = errors.New("resource URI does not match")
 	ErrorMismatchVerifierID        = errors.New("verifier ID does not match")
 	ErrorInvalidSLSALevel          = errors.New("invalid SLSA level")
+	ErrorInvalidClientOpts         = errors.New("no more than one of options.ClientOpts should be provided")
 )

options/options.go

@@ -1,6 +1,10 @@
 package options
 
-import "crypto"
+import (
+	"crypto"
+
+	"github.com/slsa-framework/slsa-verifier/v2/verifiers/utils"
+)
 
 // ProvenanceOpts are the options for checking provenance information.
 type ProvenanceOpts struct {
@@ -65,3 +69,22 @@ type VerificationOpts struct {
 	// PublicKeyHashAlgo is the hash algorithm used to compute digest that was signed.
 	PublicKeyHashAlgo crypto.Hash
 }
+
+// ClientOpts contain clinets to be used by slsa-verifier.
+// In the future, this can include a logger and a rekor client.
+type ClientOpts struct {
+	// SigstoreTufClient is the Sigstore TUF client, used for retrieving the Npmjs public keys
+	SigstoreTUFClient utils.SigstoreTUFClient
+}
+
+// NewDefaultClientOpts returns default clients to be used by slsa-verifier.
+func NewDefaultClientOpts() (*ClientOpts, error) {
+	sigstoreTUFClient, err := utils.GetDefaultSigstoreTUFClient()
+	if err != nil {
+		return nil, err
+	}
+	opts := &ClientOpts{
+		SigstoreTUFClient: sigstoreTUFClient,
+	}
+	return opts, nil
+}

register/register.go

@@ -33,6 +33,7 @@ type SLSAVerifier interface {
 		attestations []byte, tarballHash string,
 		provenanceOpts *options.ProvenanceOpts,
 		builderOpts *options.BuilderOpts,
+		clientOpts *options.ClientOpts,
 	) ([]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,
+	clientOpts *options.ClientOpts,
 ) ([]byte, *utils.TrustedBuilderID, error) {
 	return nil, nil, serrors.ErrorNotSupported
 }

verifiers/internal/gha/npm.go

@@ -9,7 +9,7 @@ import (
 	"fmt"
 	"net/url"
 	"strings"
-	"sync/atomic"
+	"sync"
 
 	intoto "github.com/in-toto/in-toto-golang/in_toto"
 	"github.com/secure-systems-lab/go-securesystemslib/dsse"
@@ -42,7 +42,8 @@ var publishPredicates = map[string]bool{
 	publishAttestationV01: true,
 }
 var errrorInvalidAttestations = errors.New("invalid npm attestations")
-var attestationKeyAtomicValue atomic.Value
+var attestationKey string
+var attestationKeyOnce sync.Once
 
 type attestationSet struct {
 	Attestations []attestation `json:"attestations"`
@@ -68,6 +69,7 @@ type Npm struct {
 	verifiedPublishAtt    *SignedAttestation
 	provenanceAttestation *attestation
 	publishAttestation    *attestation
+	clientOpts            *options.ClientOpts
 }
 
 func (n *Npm) ProvenanceEnvelope() *dsse.Envelope {
@@ -78,12 +80,12 @@ func (n *Npm) ProvenanceLeafCertificate() *x509.Certificate {
 	return n.verifiedProvenanceAtt.SigningCert
 }
 
-func NpmNew(ctx context.Context, root *sigstoreRoot.LiveTrustedRoot, attestationBytes []byte) (*Npm, error) {
+// NpmNew creates a new Npm verifier.
+func NpmNew(ctx context.Context, root *sigstoreRoot.LiveTrustedRoot, attestationBytes []byte, clientOpts *options.ClientOpts) (*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
@@ -94,6 +96,7 @@ func NpmNew(ctx context.Context, root *sigstoreRoot.LiveTrustedRoot, attestation
 
 		provenanceAttestation: prov,
 		publishAttestation:    pub,
+		clientOpts:            clientOpts,
 	}, nil
 }
 
@@ -123,17 +126,15 @@ func extractAttestations(attestations []attestation) (*attestation, *attestation
 }
 
 // getAttestationKey retrieves the attestation key and holds it in memory.
-func getAttestationKey(npmRegistryPublicKeyID string) (string, error) {
-	value := attestationKeyAtomicValue.Load()
-	if value != nil {
-		return value.(string), nil
-	}
-	npmRegistryPublicKey, err := getKeyDataFromSigstoreTuf(npmRegistryPublicKeyID, attestationKeyUsage)
+func getAttestationKey(sigstoreTUFClient utils.SigstoreTUFClient, npmRegistryPublicKeyID string) (string, error) {
+	var err error
+	attestationKeyOnce.Do(func() {
+		attestationKey, err = getKeyDataFromSigstoreTUF(sigstoreTUFClient, npmRegistryPublicKeyID, attestationKeyUsage)
+	})
 	if err != nil {
 		return "", err
 	}
-	attestationKeyAtomicValue.Store(npmRegistryPublicKey)
-	return npmRegistryPublicKey, nil
+	return attestationKey, nil
 }
 
 func (n *Npm) verifyProvenanceAttestationSignature() error {
@@ -159,7 +160,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.clientOpts.SigstoreTUFClient, npmRegistryPublicKeyID)
 	if err != nil {
 		return err
 	}
@@ -241,13 +242,6 @@ func verifyIntotoTypes(att *SignedAttestation, predicateTypes map[string]bool, p
 	return nil
 }
 
-func (n *Npm) verifiedProvenanceBytes() ([]byte, error) {
-	// TODO(#493): prune the provenance and return only
-	// verified fields.
-	// NOTE: we currently don't verify the materials' commit sha.
-	return []byte{}, nil
-}
-
 func (n *Npm) verifyPackageName(name *string) error {
 	if name == nil {
 		return nil

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

verifiers/internal/gha/npm_sigstore_tuf_test.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
+	serrors "github.com/slsa-framework/slsa-verifier/v2/errors"
 )
 
 var (
@@ -82,19 +83,19 @@ var (
 	testTargetKeyData  = testTargetKey.PublicKey.RawBytes
 )
 
-// mockSigstoreTufClient a mock implementation of sigstoreTufClient.
-type mockSigstoreTufClient struct {
+// mockSigstoreTUFClient a mock implementation of sigstoreTUFClient.
+type mockSigstoreTUFClient struct {
 	fileContentMap map[string]string
 }
 
-// NewMockSigstoreTufClient returns an instance of the mock client,
+// newMockSigstoreTUFClient returns an instance of the mock client,
 // with fileContentMap as input and outputs of the GetTarget() method.
-func NewMockSigstoreTufClient() *mockSigstoreTufClient {
-	return &mockSigstoreTufClient{fileContentMap: mockFileContentMap}
+func newMockSigstoreTUFClient() *mockSigstoreTUFClient {
+	return &mockSigstoreTUFClient{fileContentMap: mockFileContentMap}
 }
 
-// GetTarget mock implementation of GetTarget for the mockSigstoreTufClient.
-func (c mockSigstoreTufClient) GetTarget(targetPath string) ([]byte, error) {
+// GetTarget mock implementation of GetTarget for the mockSigstoreTUFClient.
+func (c mockSigstoreTUFClient) GetTarget(targetPath string) ([]byte, error) {
 	content, exists := c.fileContentMap[targetPath]
 	if !exists {
 		return nil, fmt.Errorf("content not definied in this mock, key: %s", targetPath)
@@ -118,7 +119,7 @@ func TestGetNpmjsKeysTarget(t *testing.T) {
 		{
 			name:        "parsing non-existent registry.npmjs.org_keys.json",
 			targetPath:  "my-fake-path.json",
-			expectedErr: errorCouldNotFindTarget,
+			expectedErr: serrors.ErrorCouldNotFindTarget,
 		},
 		{
 			name:        "parsing invalid json",
@@ -128,7 +129,7 @@ func TestGetNpmjsKeysTarget(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			mockClient := NewMockSigstoreTufClient()
+			mockClient := newMockSigstoreTUFClient()
 			actualKeys, err := getNpmjsKeysTarget(mockClient, tt.targetPath)
 			if keyDataDiff := cmp.Diff(tt.expectedKeys, actualKeys, cmpopts.EquateComparable()); keyDataDiff != "" {
 				t.Errorf("expected equal values (-want +got):\n%s", keyDataDiff)
@@ -168,7 +169,7 @@ func TestGetKeyDataWithNpmjsKeysTarget(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			mockClient := NewMockSigstoreTufClient()
+			mockClient := newMockSigstoreTUFClient()
 			keys, err := getNpmjsKeysTarget(mockClient, tt.targetPath)
 			if err != nil {
 				t.Fatalf("getNpmjsKeysTarget: %v", err)