chore: refactor - expose only what is needed (#5)

Author: VinnyBarton

Makefile

@@ -2,12 +2,13 @@ BINARY_NAME ?= sbom-offline-verification
 GOCACHE ?= $(CURDIR)/.gocache
 GOMODCACHE ?= $(GOCACHE)/pkg/mod
 GOEXPERIMENT ?= jsonv2
-GOFILES := $(shell find . -name "*.go")
+GOFILES := $(shell find . \( -path './.git' -o -path './.gocache' -o -path './dist' -o -path './vendor' \) -prune -o -type f -name "*.go" -print)
 GOFMT ?= gofmt "-s"
 DIST_DIR ?= dist
 IMAGE_NAME ?= secure-sbom-verification-cli
 IMAGE_TAG ?= dev
 GOVULNCHECK_SCAN ?= package
+GOLANGCI_LINT ?= golangci-lint
 
 .PHONY: test coverage build-cli docker-build tidy vulncheck goreleaser-dryrun clean
 
@@ -58,4 +59,4 @@ fmt-check:
 
 .PHONY: lint
 lint:
-	@DOCKER run --rm -v $(shell pwd):/app -w /app --env GOEXPERIMENT=jsonv2 golangci/golangci-lint:v2.8.0-alpine golangci-lint run ./...
+	@docker run --rm -v $(shell pwd):/app -w /app --env GOEXPERIMENT=jsonv2 golangci/golangci-lint:v2.8.0-alpine $(GOLANGCI_LINT) run ./...

README.md

@@ -40,6 +40,76 @@ make test
 make build-cli
 ```
 
+## Library Usage
+
+Import the module root directly:
+
+```go
+import securesbomverifier "github.com/shiftleftcyber/securesbom-verifier"
+```
+
+For CycloneDX embedded signatures:
+
+```go
+verifier := securesbomverifier.NewVerifier()
+
+result, err := verifier.VerifyCycloneDXEmbeddedVersioned(
+  signedSBOM,
+  string(publicKeyPEM),
+  securesbomverifier.VerificationV2,
+)
+```
+
+For SPDX detached signatures:
+
+```go
+verifier := securesbomverifier.NewVerifier()
+
+result, err := verifier.VerifySPDXDetachedVersioned(
+  spdxSBOM,
+  signatureB64,
+  string(publicKeyPEM),
+  securesbomverifier.VerificationV2,
+)
+if err != nil {
+  if errors.Is(err, securesbomverifier.ErrSignatureFail) {
+    // Signature did not verify.
+  }
+}
+```
+
+For digest verification, the current library API is exposed through the lower-level
+`services/digest` package rather than the root wrapper:
+
+```go
+import (
+  digestsigning "github.com/shiftleftcyber/securesbom-verifier/services/digest"
+  "github.com/shiftleftcyber/securesbom-verifier/verificationkey"
+)
+
+validated, err := digestsigning.NewValidator().ValidateVerifyDigestRequest(
+  digestsigning.VerifyDigestInput{
+    KeyID:         "offline",
+    HashAlgorithm: "sha256",
+    Digest:        digestB64,
+    Signature:     signatureB64,
+  },
+)
+if err != nil {
+  return err
+}
+
+err = digestsigning.NewCryptoVerifier().Verify(
+  &verificationkey.KeyInfo{
+    KeyID:     "offline",
+    Algorithm: "ES256",
+    PublicKey: string(publicKeyPEM),
+  },
+  validated.Digest,
+  validated.Signature,
+)
+```
+
 ## Build Note
 
 This project currently relies on `GOEXPERIMENT=jsonv2`, matching the behavior
@@ -110,8 +180,10 @@ CLI archives and a checksum file to the GitHub release.
 ## Examples
 
 See [examples/library/main.go](examples/library/main.go) for a minimal embedding
-example from another Go service, and [MIGRATION.md](MIGRATION.md) for a suggested
-next-step extraction plan from `sbom-signing-api`.
+example for CycloneDX verification, [examples/spdx-detached/main.go](examples/spdx-detached/main.go)
+for SPDX detached verification, [examples/digest/main.go](examples/digest/main.go)
+for digest verification, and [MIGRATION.md](MIGRATION.md) for a suggested next-step
+extraction plan from `sbom-signing-api`.
 
-The example program expects you to provide a signed SBOM path and a public key
-path at runtime.
+The example programs expect you to provide signed content, signatures, and/or a
+public key path at runtime depending on the verification mode.

examples/digest/main.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	digestsigning "github.com/shiftleftcyber/securesbom-verifier/services/digest"
+	"github.com/shiftleftcyber/securesbom-verifier/verificationkey"
+)
+
+func main() {
+	if len(os.Args) != 4 {
+		log.Fatalf("usage: %s <digest-base64> <signature-base64> <public-key-path>", os.Args[0])
+	}
+
+	if err := verifyDigestExample(os.Args[1], os.Args[2], os.Args[3]); err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println("verification result: signature is valid")
+}
+
+func verifyDigestExample(digestB64, signatureB64, publicKeyPath string) error {
+	pub, err := os.ReadFile(publicKeyPath)
+	if err != nil {
+		return fmt.Errorf("read public key: %w", err)
+	}
+
+	validated, err := digestsigning.NewValidator().ValidateVerifyDigestRequest(digestsigning.VerifyDigestInput{
+		KeyID:         "offline",
+		HashAlgorithm: "sha256",
+		Digest:        digestB64,
+		Signature:     signatureB64,
+	})
+	if err != nil {
+		return fmt.Errorf("validate digest request: %w", err)
+	}
+
+	err = digestsigning.NewCryptoVerifier().Verify(
+		&verificationkey.KeyInfo{
+			KeyID:     "offline",
+			Algorithm: "ES256",
+			PublicKey: string(pub),
+		},
+		validated.Digest,
+		validated.Signature,
+	)
+	if err != nil {
+		return fmt.Errorf("verify digest: %w", err)
+	}
+
+	return nil
+}

examples/library/main.go

@@ -5,7 +5,7 @@ import (
 	"log"
 	"os"
 
-	"github.com/shiftleftcyber/securesbom-verifier/application"
+	securesbomverifier "github.com/shiftleftcyber/securesbom-verifier"
 )
 
 func main() {
@@ -21,7 +21,7 @@ func main() {
 	fmt.Printf("verification result: %+v\n", result)
 }
 
-func verifyExample(sbomPath, publicKeyPath string) (*application.VerificationResult, error) {
+func verifyExample(sbomPath, publicKeyPath string) (*securesbomverifier.VerificationResult, error) {
 	sbom, err := os.ReadFile(sbomPath)
 	if err != nil {
 		return nil, fmt.Errorf("read sbom: %w", err)
@@ -32,8 +32,8 @@ func verifyExample(sbomPath, publicKeyPath string) (*application.VerificationRes
 		return nil, fmt.Errorf("read public key: %w", err)
 	}
 
-	app := application.NewVerifierApp()
-	result, err := app.VerifyCycloneDXEmbeddedVersioned(sbom, string(pub), application.VerificationV2)
+	verifier := securesbomverifier.NewVerifier()
+	result, err := verifier.VerifyCycloneDXEmbeddedVersioned(sbom, string(pub), securesbomverifier.VerificationV2)
 	if err != nil {
 		return nil, fmt.Errorf("verify: %w", err)
 	}

examples/spdx-detached/main.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	securesbomverifier "github.com/shiftleftcyber/securesbom-verifier"
+)
+
+func main() {
+	if len(os.Args) != 4 {
+		log.Fatalf("usage: %s <spdx-sbom-path> <signature> <public-key-path>", os.Args[0])
+	}
+
+	result, err := verifySPDXExample(os.Args[1], os.Args[2], os.Args[3])
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("verification result: %+v\n", result)
+}
+
+func verifySPDXExample(sbomPath, signatureB64, publicKeyPath string) (*securesbomverifier.VerificationResult, error) {
+	sbom, err := os.ReadFile(sbomPath)
+	if err != nil {
+		return nil, fmt.Errorf("read SBOM: %w", err)
+	}
+
+	pub, err := os.ReadFile(publicKeyPath)
+	if err != nil {
+		return nil, fmt.Errorf("read public key: %w", err)
+	}
+
+	verifier := securesbomverifier.NewVerifier()
+	result, err := verifier.VerifySPDXDetachedVersioned(sbom, signatureB64, string(pub), securesbomverifier.VerificationV2)
+	if err != nil {
+		return nil, fmt.Errorf("verify SPDX: %w", err)
+	}
+
+	return result, nil
+}

securesbom_verifier.go

@@ -0,0 +1,43 @@
+package securesbomverifier
+
+import "github.com/shiftleftcyber/securesbom-verifier/application"
+
+type VerificationResult = application.VerificationResult
+
+type VerificationVersion = application.VerificationVersion
+
+const (
+	VerificationV1 = application.VerificationV1
+	VerificationV2 = application.VerificationV2
+)
+
+var (
+	ErrSignatureFail = application.ErrSignatureFail
+)
+
+type Verifier struct {
+	app *application.VerifierApp
+}
+
+func NewVerifier() *Verifier {
+	return &Verifier{
+		app: application.NewVerifierApp(),
+	}
+}
+
+func (v *Verifier) VerifyCycloneDXEmbeddedVersioned(
+	signedSBOM []byte,
+	publicKeyPEM string,
+	version VerificationVersion,
+) (*VerificationResult, error) {
+	return v.app.VerifyCycloneDXEmbeddedVersioned(signedSBOM, publicKeyPEM, version)
+}
+
+func (v *Verifier) VerifySPDXDetachedVersioned(
+	sbom []byte,
+	signatureB64 string,
+	publicKeyPEM string,
+	version VerificationVersion,
+) (*VerificationResult, error) {
+	return v.app.VerifySPDXDetachedVersioned(sbom, signatureB64, publicKeyPEM, version)
+}

securesbom_verifier_test.go

@@ -0,0 +1,19 @@
+package securesbomverifier
+
+import (
+	"testing"
+
+	"github.com/shiftleftcyber/securesbom-verifier/testsupport"
+)
+
+func TestNewVerifier_RootPackageAPI(t *testing.T) {
+	signed, publicKey := testsupport.SignedCycloneDXV2(t, "ES256")
+
+	result, err := NewVerifier().VerifyCycloneDXEmbeddedVersioned(signed, publicKey, VerificationV2)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if result.Message != "signature is valid" {
+		t.Fatalf("unexpected message: %s", result.Message)
+	}
+}