Add docstrings, address review comments

Signed-off-by: Marcela Melara <marcela.melara@intel.com>

scai-gen/cmd/assert.go

@@ -96,7 +96,7 @@ func genAttrAssertion(_ *cobra.Command, args []string) error {
 
 	aa, err := generators.NewSCAIAssertion(attribute, target, conditions, evidence)
 	if err != nil {
-		return fmt.Errorf("error generating SCAI attribute assertion: %w", err)
+		return fmt.Errorf("unable to generate SCAI attribute assertion: %w", err)
 	}
 
 	return fileio.WritePbToFile(aa, outFile, false)

scai-gen/cmd/rd.go

@@ -162,12 +162,12 @@ func genRdFromFile(_ *cobra.Command, args []string) error {
 
 	annotations, err := readAnnotations(annotationsFile)
 	if err != nil {
-		return fmt.Errorf("error reading annotations file: %w", err)
+		return fmt.Errorf("unable to read annotations file: %w", err)
 	}
 
 	rd, err := generators.NewRdForFile(filename, name, uri, hashAlg, withContent, mediaType, downloadLocation, annotations)
 	if err != nil {
-		return fmt.Errorf("error generating RD: %w", err)
+		return fmt.Errorf("unable to generate RD: %w", err)
 	}
 
 	return fileio.WritePbToFile(rd, outFile, false)
@@ -183,12 +183,12 @@ func genRdForRemote(_ *cobra.Command, args []string) error {
 
 	annotations, err := readAnnotations(annotationsFile)
 	if err != nil {
-		return fmt.Errorf("error reading annotations file: %w", err)
+		return fmt.Errorf("unable to read annotations file: %w", err)
 	}
 
 	rd, err := generators.NewRdForRemote(remoteURI, name, hashAlg, digest, downloadLocation, annotations)
 	if err != nil {
-		return fmt.Errorf("error generating RD: %w", err)
+		return fmt.Errorf("unable to generate RD: %w", err)
 	}
 
 	return fileio.WritePbToFile(rd, outFile, false)

scai-gen/cmd/report.go

@@ -91,7 +91,7 @@ func genAttrReport(_ *cobra.Command, args []string) error {
 
 	ar, err := generators.NewSCAIReport(attrAsserts, producer)
 	if err != nil {
-		return fmt.Errorf("error generating SCAI Report: %w", err)
+		return fmt.Errorf("unable to generate SCAI Report: %w", err)
 	}
 
 	// then, plug the Report into an in-toto Statement
@@ -117,7 +117,7 @@ func genAttrReport(_ *cobra.Command, args []string) error {
 
 	statement, err := generators.NewStatement([]*ita.ResourceDescriptor{subject}, "https://in-toto.io/attestation/scai/attribute-report/v0.2", reportStruct)
 	if err != nil {
-		return fmt.Errorf("error generating in-toto Statement: %w", err)
+		return fmt.Errorf("unable to generate in-toto Statement: %w", err)
 	}
 
 	return fileio.WritePbToFile(statement, outFile, prettyPrint)

scai-gen/pkg/generators/scai.go

@@ -8,6 +8,8 @@ import (
 	"google.golang.org/protobuf/types/known/structpb"
 )
 
+// Generates a SCAI v0 AttributeAssertion struct.
+// Throws an error if the resulting AttributeAssertion does not meet the spec.
 func NewSCAIAssertion(attribute string, target *ita.ResourceDescriptor, conditions *structpb.Struct, evidence *ita.ResourceDescriptor) (*scai.AttributeAssertion, error) {
 	aa := &scai.AttributeAssertion{
 		Attribute:  attribute,
@@ -24,6 +26,8 @@ func NewSCAIAssertion(attribute string, target *ita.ResourceDescriptor, conditio
 	return aa, nil
 }
 
+// Generates a SCAI v0 AttributeReport struct to be used as an in-toto attestation predicate.
+// Throws an error if the resulting AttributeReport does not meet the spec.
 func NewSCAIReport(attrAssertions []*scai.AttributeAssertion, producer *ita.ResourceDescriptor) (*scai.AttributeReport, error) {
 	ar := &scai.AttributeReport{
 		Attributes: attrAssertions,

scai-gen/pkg/generators/v1.go

@@ -12,7 +12,9 @@ import (
 	"google.golang.org/protobuf/types/known/structpb"
 )
 
-func NewRdForFile(filename string, name string, uri string, hashAlg string, withContent bool, mediaType string, downloadLocation string, annotations *structpb.Struct) (*ita.ResourceDescriptor, error) {
+// Generates an in-toto Attestation Framework v1 ResourceDescriptor for a local file, including its digest (default sha256).
+// Throws an error if the resulting ResourceDescriptor does not meet the spec.
+func NewRdForFile(filename, name, uri, hashAlg string, withContent bool, mediaType, downloadLocation string, annotations *structpb.Struct) (*ita.ResourceDescriptor, error) {
 	fileBytes, err := os.ReadFile(filename)
 	if err != nil {
 		return nil, fmt.Errorf("error reading resource file: %w", err)
@@ -55,17 +57,12 @@ func NewRdForFile(filename string, name string, uri string, hashAlg string, with
 	return rd, nil
 }
 
-func NewRdForRemote(name string, uri string, hashAlg string, digest string, downloadLocation string, annotations *structpb.Struct) (*ita.ResourceDescriptor, error) {
+// Generates an in-toto Attestation Framework v1 ResourceDescriptor for a remote resource identified by a name or URI).
+// Does not check if the URI resolves to a valid remote location.
+// Throws an error if the resulting ResourceDescriptor does not meet the spec.
+func NewRdForRemote(name, uri, hashAlg, digest, downloadLocation string, annotations *structpb.Struct) (*ita.ResourceDescriptor, error) {
 	digestSet := make(map[string]string)
-	if len(digest) > 0 {
-		// the in-toto spec expects a hex-encoded string in DigestSets
-		// https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md
-		_, err := hex.DecodeString(digest)
-		if err != nil {
-			return nil, fmt.Errorf("digest is not valid hex-encoded string: %w", err)
-		}
-
-		// we can assume that we have both variables set at this point
+	if len(hashAlg) > 0 && len(digest) > 0 {
 		digestSet = map[string]string{hashAlg: strings.ToLower(digest)}
 	}
 
@@ -85,6 +82,8 @@ func NewRdForRemote(name string, uri string, hashAlg string, digest string, down
 	return rd, nil
 }
 
+// Generates an in-toto Attestation Framework v1 Statement including a given predicate.
+// Throws an error if the resulting Statement does not meet the spec.
 func NewStatement(subjects []*ita.ResourceDescriptor, predicateType string, predicate *structpb.Struct) (*ita.Statement, error) {
 	statement := &ita.Statement{
 		Type:          ita.StatementTypeUri,