Allow for dynamic assignment of roles to users (#2467)

* allow dynamic assignment and removal of roles to users and groups

* task regenerate

* fix lint

* add nolint:mnd

Author: adelowo

.task/checksum/generate-openapi-smart

@@ -1 +1 @@
-a5ea6f046fb222aad2d3c0483d6da270
+4abf710d89257e2084a17b0a12a192cb

common/openapi/models.go

@@ -17,14 +17,11 @@ import (
 	"github.com/theopenlane/core/common/enums"
 	"github.com/theopenlane/core/common/models"
 	"github.com/theopenlane/core/common/storagetypes"
+	fgamodel "github.com/theopenlane/core/fga/model"
 
 	"github.com/theopenlane/utils/passwd"
 )
 
-const (
-	exampleFindingsCount = 5
-)
-
 // ExampleProvider interface allows response models to provide their own examples
 // This eliminates the need for separate Example* variables and static switch statements
 type ExampleProvider interface {
@@ -2392,28 +2389,28 @@ var ExampleProductCatalogReply = ProductCatalogReply{
 		Version: "v0.0.1",
 		SHA:     "12a4a1212888e9316a16826ba074b37230b4b7ba903cd8d7e627e4a8d03a6211",
 		Modules: map[string]models.Feature{
-			string(models.CatalogComplianceModule): models.Feature{
+			string(models.CatalogComplianceModule): {
 				Audience: "public",
-				Billing: models.Billing{Prices: []models.ItemPrice{models.ItemPrice{
+				Billing: models.Billing{Prices: []models.ItemPrice{{
 					Interval:   "month",
 					LookupKey:  "price_compliance_monthly",
 					Nickname:   "price_compliance_monthly",
 					PriceID:    "price_1S3qX6JIzM4Pa2ZcRtuinRdG",
-					UnitAmount: int64(45000),
-				}, models.ItemPrice{
+					UnitAmount: int64(45000), //nolint:mnd
+				}, {
 					Interval:   "year",
 					LookupKey:  "price_compliance_annually",
 					Nickname:   "price_compliance_annually",
 					PriceID:    "price_1S3qX7JIzM4Pa2ZchMVxiS1l",
-					UnitAmount: int64(500000),
+					UnitAmount: int64(500000), //nolint:mnd
 				}}},
 				Description:          "Core Compliance Automation and Standards Library",
 				DisplayName:          "Core Compliance Module",
 				IncludeWithTrial:     true,
 				LookupKey:            "compliance_module",
 				MarketingDescription: "Automate evidence collection and task tracking to simplify SOC 2, ISO 27001, and other certification workflows",
 				ProductID:            "prod_SzqDyAvxP2D7fA",
-				Usage:                &models.Usage{EvidenceStorageGB: int64(25000)},
+				Usage:                &models.Usage{EvidenceStorageGB: int64(25000)}, //nolint:mnd
 			},
 		}},
 }
@@ -2524,34 +2521,41 @@ var ExampleScopesRequest = ScopesRequest{}
 var ExampleScopesReply = ScopesReply{
 	Reply: rout.Reply{Success: true},
 	Scopes: map[string][]string{
-		"internal_policy": []string{"read", "write", "delete"},
-		"procedure":       []string{"read", "write", "delete"},
-		"control":         []string{"read", "write", "delete"},
+		"internal_policy": {"read", "write", "delete"},
+		"procedure":       {"read", "write", "delete"},
+		"control":         {"read", "write", "delete"},
 	},
 }
 
 // =========
 // Roles
 // =========
 
+// OrganizationRole contains certain metadata for a role that can be assigned to users.
+type OrganizationRole struct {
+	ID          string `json:"id" description:"The role relation ID" example:"policy_manager"`
+	Name        string `json:"name" description:"The display name for the role" example:"Policy Manager"`
+	Description string `json:"description" description:"The role description" example:"Manage all policies and procedures"`
+}
+
 // RolesRequest contains roles that can be assigned to users on top of org roles
 type RolesRequest struct{}
 
 // RolesReply holds the fields that are sent on a response to the `/roles` endpoint
 type RolesReply struct {
 	// Reply is the reply value.
 	rout.Reply
-	// Scopes is a list of roles that can be assigned
-	Roles []string `json:"roles,omitempty" description:"A map of object types to operations that can be set for an API Token"`
+	// Roles is a list of organization responsibility roles that can be assigned.
+	Roles []OrganizationRole `json:"roles,omitempty" description:"Organization roles and responsibilities that can be assigned"`
 }
 
-// ExampleResponse returns an example ScopesReply for OpenAPI documentation
+// ExampleResponse returns an example RolesReply for OpenAPI documentation
 func (r *RolesReply) ExampleResponse() any {
-	return ExampleScopesReply
+	return ExampleRolesReply
 }
 
 // Validate ensures the required fields are set on the RolesRequest
-func (r *ScopesReply) Validate() error {
+func (r *RolesRequest) Validate() error {
 	return nil
 }
 
@@ -2561,9 +2565,101 @@ var ExampleRolesRequest = RolesRequest{}
 // ExampleRolesReply is an example of a successful `/roles` response for OpenAPI documentation
 var ExampleRolesReply = RolesReply{
 	Reply: rout.Reply{Success: true},
-	Roles: []string{
-		"compliance_manager",
-		"risk_manager",
-		"policy_manager",
+	Roles: []OrganizationRole{
+		{
+			ID:          "policy_manager",
+			Name:        "Policy Manager",
+			Description: "Can manage all policies and procedures",
+		},
+		{
+			ID:          "risk_manager",
+			Name:        "Risk Manager",
+			Description: "Can manage risks, vulnerabilities, and findings",
+		},
+	},
+}
+
+// OrganizationRolesRequest contains functional roles that can be assigned to users or groups in addition to their base level org role such as member, admin, etc.
+type OrganizationRolesRequest struct {
+	OrganizationID string   `json:"organization_id,omitempty" description:"The ID of the organization to assign roles in. Defaults to the authenticated organization." example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+	Role           string   `json:"role" description:"The organization responsibility role to assign" example:"policy_manager"`
+	UserIDs        []string `json:"user_ids,omitempty" description:"User IDs to assign the role to"`
+	GroupIDs       []string `json:"group_ids,omitempty" description:"Group IDs to assign the role to"`
+}
+
+// OrganizationRolesReply contains the newly assigned/removed role.
+type OrganizationRolesReply struct {
+	rout.Reply
+	OrganizationID string `json:"organization_id" description:"The ID of the organization the role was applied to" example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+	Role           string `json:"role" description:"The organization responsibility role" example:"policy_manager"`
+}
+
+// AccountRolesMeRequest contains no input; it uses the authenticated caller.
+type AccountRolesMeRequest struct{}
+
+// AccountRolesMeReply holds the organization responsibility roles assigned to the authenticated caller.
+type AccountRolesMeReply struct {
+	rout.Reply
+	Roles          []OrganizationRole `json:"roles" description:"Organization responsibility roles assigned to the authenticated caller"`
+	OrganizationID string             `json:"organization_id" description:"The ID of the organization the roles apply to" example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+}
+
+func (r *OrganizationRolesRequest) Validate() error {
+	if r.Role == "" {
+		return rout.NewMissingRequiredFieldError("role")
+	}
+
+	ok, err := fgamodel.IsOrganizationRole(r.Role)
+	if err != nil {
+		return err
+	}
+
+	if !ok {
+		return rout.InvalidField("role")
+	}
+
+	if len(r.UserIDs) == 0 && len(r.GroupIDs) == 0 {
+		return rout.NewMissingRequiredFieldError("user_ids or group_ids")
+	}
+
+	return nil
+}
+
+func (r *AccountRolesMeRequest) Validate() error {
+	return nil
+}
+
+func (r *OrganizationRolesReply) ExampleResponse() any {
+	return ExampleOrganizationRolesReply
+}
+
+func (r *AccountRolesMeReply) ExampleResponse() any {
+	return ExampleAccountRolesMeReply
+}
+
+var ExampleOrganizationRolesRequest = OrganizationRolesRequest{
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
+	Role:           "policy_manager",
+	UserIDs:        []string{"01J4EXD5MM60CX4YNYN0DEE3Y1"},
+	GroupIDs:       []string{"01J4EXD5MM60CX4YNYN0DEE3Y2"},
+}
+
+var ExampleOrganizationRolesReply = OrganizationRolesReply{
+	Reply:          rout.Reply{Success: true},
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
+	Role:           "policy_manager",
+}
+
+var ExampleAccountRolesMeRequest = AccountRolesMeRequest{}
+
+var ExampleAccountRolesMeReply = AccountRolesMeReply{
+	Reply: rout.Reply{Success: true},
+	Roles: []OrganizationRole{
+		{
+			ID:          "policy_manager",
+			Name:        "Policy Manager",
+			Description: "Can manage all policies and procedures",
+		},
 	},
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
 }

fga/generate/modelparse/parse.go

@@ -8,17 +8,25 @@ import (
 )
 
 type RoleInfo struct {
-	ViewRoles    map[string][]string
-	CrudRoles    map[string][]string
-	InheritRoles map[string][]string
-	CreateRoles  map[string][]string
+	ViewRoles         map[string][]string
+	CrudRoles         map[string][]string
+	InheritRoles      map[string][]string
+	CreateRoles       map[string][]string
+	OrganizationRoles []OrganizationRole
+}
+
+type OrganizationRole struct {
+	ID          string
+	Name        string
+	Description string
 }
 
 const (
 	crudAnnotation    = "# @crud:"
 	viewAnnotation    = "# @view:"
 	inheritAnnotation = "# @inherit:"
 	createAnnotation  = "# @create:"
+	roleAnnotation    = "# @role:"
 )
 
 // ParseRoleAnnotations parses relevant annotations and role line from roles/roles.fga to determine which objects to add the roles to
@@ -28,34 +36,51 @@ func ParseRoleAnnotations(rolesFile string) (*RoleInfo, error) {
 		return nil, err
 	}
 
+	return ParseRoleAnnotationsData(data)
+}
+
+func ParseRoleAnnotationsData(data []byte) (*RoleInfo, error) {
 	lines := strings.Split(string(data), "\n")
 
 	crudMap := make(map[string][]string)
 	viewMap := make(map[string][]string)
 	inheritMap := make(map[string][]string)
 	createMap := make(map[string][]string)
+	organizationRoles := []OrganizationRole{}
 
 	var pendingCrud, pendingView, pendingInherit, pendingCreate []string
+	var pendingRoleName, pendingRoleDescription string
 
 	isSeparator := func(c rune) bool {
 		return c == ',' || c == ';' || c == ' '
 	}
 	for _, line := range lines {
 		line = strings.TrimSpace(line)
-		if strings.HasPrefix(line, crudAnnotation) {
-			pendingCrud = strings.FieldsFunc(strings.TrimPrefix(line, crudAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, crudAnnotation); ok {
+			pendingCrud = strings.FieldsFunc(annotationValue, isSeparator)
+		}
+
+		if annotationValue, ok := strings.CutPrefix(line, viewAnnotation); ok {
+			pendingView = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, viewAnnotation) {
-			pendingView = strings.FieldsFunc(strings.TrimPrefix(line, viewAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, inheritAnnotation); ok {
+			pendingInherit = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, inheritAnnotation) {
-			pendingInherit = strings.FieldsFunc(strings.TrimPrefix(line, inheritAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, createAnnotation); ok {
+			pendingCreate = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, createAnnotation) {
-			pendingCreate = strings.FieldsFunc(strings.TrimPrefix(line, createAnnotation), isSeparator)
+		// roles are defined as "# @role: Group Manager | Manage organization groups"
+		if annotationValue, ok := strings.CutPrefix(line, roleAnnotation); ok {
+			parts := strings.SplitN(strings.TrimSpace(annotationValue), "|", 2) //nolint:mnd
+			pendingRoleName = strings.TrimSpace(parts[0])
+			pendingRoleDescription = ""
+
+			if len(parts) == 2 { //nolint:mnd
+				pendingRoleDescription = strings.TrimSpace(parts[1])
+			}
 		}
 
 		if strings.HasPrefix(line, "define ") {
@@ -77,21 +102,32 @@ func ParseRoleAnnotations(rolesFile string) (*RoleInfo, error) {
 				}
 
 				inheritMap[role] = append(inheritMap[role], pendingInherit...)
+
+				if pendingRoleName != "" {
+					organizationRoles = append(organizationRoles, OrganizationRole{
+						ID:          role,
+						Name:        pendingRoleName,
+						Description: pendingRoleDescription,
+					})
+				}
 			}
 
 			// reset pending annotations after processing a role definition
 			pendingCrud = nil
 			pendingView = nil
 			pendingInherit = nil
 			pendingCreate = nil
+			pendingRoleName = ""
+			pendingRoleDescription = ""
 		}
 	}
 
 	return &RoleInfo{
-		CrudRoles:    crudMap,
-		ViewRoles:    viewMap,
-		InheritRoles: inheritMap,
-		CreateRoles:  createMap,
+		CrudRoles:         crudMap,
+		ViewRoles:         viewMap,
+		InheritRoles:      inheritMap,
+		CreateRoles:       createMap,
+		OrganizationRoles: organizationRoles,
 	}, nil
 }