Add BitLength validation for SuccinctRoles (#716)

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>

Author: rdimitrov

metadata/marshal.go

@@ -21,6 +21,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"errors"
+	"fmt"
 )
 
 // The following marshal/unmarshal methods override the default behavior for for each TUF type
@@ -522,6 +523,15 @@ func (role *SuccinctRoles) UnmarshalJSON(data []byte) error {
 	}
 	*role = SuccinctRoles(a)
 
+	// Validate BitLength: must be between 1 and 32 inclusive.
+	// - BitLength determines the number of bins as 2^BitLength
+	// - We use the leftmost BitLength bits of a SHA-256 hash (32 bits max from 4 bytes)
+	// - BitLength < 1 would result in 0 or fractional bins
+	// - BitLength > 32 would cause a negative shift value in GetRolesForTarget
+	if role.BitLength < 1 || role.BitLength > 32 {
+		return fmt.Errorf("invalid bit_length: %d, must be between 1 and 32", role.BitLength)
+	}
+
 	var dict map[string]any
 	if err := json.Unmarshal(data, &dict); err != nil {
 		return err

metadata/metadata_api_test.go

@@ -1069,3 +1069,41 @@ func TestGetRolesInSuccinctRoles(t *testing.T) {
 		assert.Equal(t, fmt.Sprintf("bin-%s", expectedBinSuffix), roleName)
 	}
 }
+
+func TestSuccinctRolesBitLengthValidation(t *testing.T) {
+	tests := []struct {
+		name      string
+		bitLength int
+		wantErr   bool
+	}{
+		{"valid minimum", 1, false},
+		{"valid typical", 8, false},
+		{"valid maximum", 32, false},
+		{"invalid zero", 0, true},
+		{"invalid negative", -1, true},
+		{"invalid too large", 33, true},
+		{"invalid very large", 100, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			jsonData := fmt.Sprintf(`{
+				"keyids": ["abc123"],
+				"threshold": 1,
+				"bit_length": %d,
+				"name_prefix": "bin"
+			}`, tt.bitLength)
+
+			var role SuccinctRoles
+			err := json.Unmarshal([]byte(jsonData), &role)
+
+			if tt.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), "invalid bit_length")
+			} else {
+				assert.NoError(t, err)
+				assert.Equal(t, tt.bitLength, role.BitLength)
+			}
+		})
+	}
+}