feat: add built-in roles and user role assignment

README.md

@@ -79,6 +79,20 @@ is separate work. Existing assignments need explicit section grants for UI visib
 The old `/api/v1/permissions` route is replaced by `/api/v1/claims/permissions`.
 Frontend adaptation is separate; no database migration is required.
 
+## User Roles
+
+Identity seeds `developer`, `moderator`, and `player` at startup using the existing
+lowercase role-name convention. Seeding preserves existing role IDs and claims;
+new roles have no permission/section claims. Public registration assigns Developer.
+Existing users are not reassigned automatically.
+
+User create/update requests accept optional `roleIds` (GUID array); get-details
+returns the selected IDs. On update, an omitted/null field preserves roles and `[]`
+clears them. On administrative creation, omitted/null means no roles. Empty GUIDs,
+duplicates, and unknown role IDs are rejected before persistence. Use the existing
+roles list endpoint to populate selection options. Role changes rotate the security
+stamp and revoke the user's tokens. No database migration or new configuration is required.
+
 ## Request Validation
 
 Request DTO constructors and nullable annotations define the JSON contract and

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Create/CreateUserCommand.cs

@@ -8,4 +8,5 @@ public sealed record CreateUserCommand(
     string Password,
     bool IsConfirmed,
     IReadOnlyCollection<Claim> Claims,
-    string Status) : ICommand<Result<Guid>>;
+    string Status,
+    IReadOnlyCollection<Guid>? RoleIds = null) : ICommand<Result<Guid>>;

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Create/CreateUserCommandValidator.cs

@@ -1,4 +1,5 @@
 using PANiXiDA.TacticalHeroes.Identity.Application.Claims;
+using PANiXiDA.TacticalHeroes.Identity.Domain.Users;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.Entities.UserClaims.ValueObjects;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.Enumerations;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.ValueObjects;
@@ -32,6 +33,9 @@ public CreateUserCommandValidator()
             })
             .SetValidator(new ClaimCatalogValidator());
 
+        RuleFor(command => command.RoleIds)
+            .MustBeValidDomainValue(UserRoleAssignments.Create);
+
         RuleFor(command => command.Status)
             .MustBeValidDomainValue(UserStatus.Create);
     }

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Create/CreateUserHandler.cs

@@ -17,7 +17,8 @@ public Task<Result<Guid>> HandleAsync(
         var emailResult = Email.Create(value: command.Email);
         var userNameResult = UserName.Create(value: command.UserName);
         var statusResult = UserStatus.Create(value: command.Status);
-        var validationResult = Result.Combine(emailResult, userNameResult, statusResult);
+        var roleIdsResult = UserRoleAssignments.Create(command.RoleIds);
+        var validationResult = Result.Combine(emailResult, userNameResult, statusResult, roleIdsResult);
 
         if (validationResult.IsFailure)
         {
@@ -46,7 +47,7 @@ public Task<Result<Guid>> HandleAsync(
             userName: userNameResult.Value,
             status: statusResult.Value,
             confirmationStatus: UserConfirmationStatus.From(isConfirmed: command.IsConfirmed),
-            roleIds: [],
+            roleIds: roleIdsResult.Value,
             claims: claims);
 
         return usersRepository.AddAsync(

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/GetDetails/UserDetailsReadModel.cs

@@ -13,6 +13,8 @@ public sealed record UserDetailsReadModel(
     string StatusDisplayName,
     IReadOnlyCollection<Claim> Claims) : IReadModel
 {
+    public IReadOnlyCollection<Guid> RoleIds { get; init; } = [];
+
     public bool IsBlocked => string.Equals(
         Status,
         UserStatus.Blocked.Name,

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Update/UpdateUserCommand.cs

@@ -8,4 +8,5 @@ public sealed record UpdateUserCommand(
     string UserName,
     bool IsConfirmed,
     IReadOnlyCollection<Claim> Claims,
-    string Status) : ICommand<Result>;
+    string Status,
+    IReadOnlyCollection<Guid>? RoleIds = null) : ICommand<Result>;

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Update/UpdateUserCommandValidator.cs

@@ -33,6 +33,9 @@ public UpdateUserCommandValidator()
             })
             .SetValidator(new ClaimCatalogValidator());
 
+        RuleFor(command => command.RoleIds)
+            .MustBeValidDomainValue(UserRoleAssignments.Create);
+
         RuleFor(command => command.Status)
             .MustBeValidDomainValue(UserStatus.Create);
     }

src/Identity/PANiXiDA.TacticalHeroes.Identity.Application/Users/Update/UpdateUserHandler.cs

@@ -18,7 +18,8 @@ public Task<Result> HandleAsync(
         var emailResult = Email.Create(value: command.Email);
         var userNameResult = UserName.Create(value: command.UserName);
         var statusResult = UserStatus.Create(value: command.Status);
-        var validationResult = Result.Combine(idResult, emailResult, userNameResult, statusResult);
+        var roleIdsResult = UserRoleAssignments.Create(command.RoleIds);
+        var validationResult = Result.Combine(idResult, emailResult, userNameResult, statusResult, roleIdsResult);
 
         if (validationResult.IsFailure)
         {
@@ -47,11 +48,12 @@ public Task<Result> HandleAsync(
             userName: userNameResult.Value,
             status: statusResult.Value,
             confirmationStatus: UserConfirmationStatus.From(isConfirmed: command.IsConfirmed),
-            roleIds: [],
+            roleIds: roleIdsResult.Value,
             claims: claims);
 
         return usersRepository.UpdateAsync(
             user: user,
-            cancellationToken: cancellationToken);
+            cancellationToken: cancellationToken,
+            replaceRoles: command.RoleIds is not null);
     }
 }

src/Identity/PANiXiDA.TacticalHeroes.Identity.Domain/Roles/RoleNames.cs

@@ -0,0 +1,12 @@
+using System.Collections.Immutable;
+
+namespace PANiXiDA.TacticalHeroes.Identity.Domain.Roles;
+
+public static class RoleNames
+{
+    public const string Developer = "developer";
+    public const string Moderator = "moderator";
+    public const string Player = "player";
+
+    public static ImmutableArray<string> All { get; } = [Developer, Moderator, Player];
+}

src/Identity/PANiXiDA.TacticalHeroes.Identity.Domain/Users/Abstractions/IUsersRepository.cs

@@ -9,7 +9,8 @@ Task<Result<Guid>> AddAsync(
 
     Task<Result> UpdateAsync(
         User user,
-        CancellationToken cancellationToken);
+        CancellationToken cancellationToken,
+        bool replaceRoles = true);
 
     Task<Result> DeleteAsync(
         Guid id,

src/Identity/PANiXiDA.TacticalHeroes.Identity.Domain/Users/UserRoleAssignments.cs

@@ -0,0 +1,30 @@
+using PANiXiDA.TacticalHeroes.Identity.Domain.Roles;
+
+namespace PANiXiDA.TacticalHeroes.Identity.Domain.Users;
+
+public static class UserRoleAssignments
+{
+    public static Result<IReadOnlyCollection<RoleId>> Create(IReadOnlyCollection<Guid>? values)
+    {
+        var roleIds = new List<RoleId>();
+        var seen = new HashSet<Guid>();
+        foreach (var value in values ?? [])
+        {
+            if (!seen.Add(value))
+            {
+                return Result.Failure<IReadOnlyCollection<RoleId>>(
+                    error: Error.Validation(message: "Role IDs must be unique.").WithField(nameof(User.RoleIds)));
+            }
+
+            var result = RoleId.Create(value);
+            if (result.IsFailure)
+            {
+                return Result.Failure<IReadOnlyCollection<RoleId>>(errors: result.Errors);
+            }
+
+            roleIds.Add(result.Value);
+        }
+
+        return Result.Success<IReadOnlyCollection<RoleId>>(value: roleIds);
+    }
+}

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/IdentityProvider/DependencyInjection/IdentityProviderServiceCollectionExtensions.cs

@@ -37,6 +37,7 @@ public static IServiceCollection AddIdentityProvider(
             .ValidateOnStart();
 
         serviceCollection.AddScoped<IUserCredentialsService, UserCredentialsService>();
+        serviceCollection.AddScoped<IdentityRoleSeeder>();
         serviceCollection.AddScoped<IdentityProviderApplicationSeeder>();
         serviceCollection.AddHostedService<IdentityProviderApplicationSeederHostedService>();
         serviceCollection.AddDataProtection()

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/IdentityProvider/Seeding/IdentityProviderApplicationSeederHostedService.cs

@@ -10,6 +10,8 @@ internal sealed class IdentityProviderApplicationSeederHostedService(
     public async Task StartAsync(CancellationToken cancellationToken)
     {
         await using var scope = serviceScopeFactory.CreateAsyncScope();
+        var roleSeeder = scope.ServiceProvider.GetRequiredService<IdentityRoleSeeder>();
+        await roleSeeder.SeedAsync(cancellationToken);
         var seeder = scope.ServiceProvider.GetRequiredService<IdentityProviderApplicationSeeder>();
 
         await seeder.SeedAsync(cancellationToken);

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/IdentityProvider/Seeding/IdentityRoleSeeder.cs

@@ -0,0 +1,35 @@
+using Microsoft.AspNetCore.Identity;
+
+using PANiXiDA.TacticalHeroes.Identity.Domain.Roles;
+using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Roles.Write.DbModels;
+
+namespace PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Seeding;
+
+internal sealed class IdentityRoleSeeder(RoleManager<ApplicationRole> roleManager, TimeProvider timeProvider)
+{
+    public async Task SeedAsync(CancellationToken cancellationToken)
+    {
+        foreach (var name in RoleNames.All)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (await roleManager.FindByNameAsync(name) is not null)
+            {
+                continue;
+            }
+
+            var nowUtc = timeProvider.GetUtcNow().UtcDateTime;
+            var result = await roleManager.CreateAsync(new ApplicationRole
+            {
+                Id = Guid.CreateVersion7(),
+                Name = name,
+                CreatedAt = nowUtc,
+                UpdatedAt = nowUtc
+            });
+            if (!result.Succeeded)
+            {
+                var errors = string.Join(", ", result.Errors.Select(error => error.Description));
+                throw new InvalidOperationException($"Could not seed role '{name}': {errors}");
+            }
+        }
+    }
+}

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/IdentityProvider/Services/UserCredentialsService.cs

@@ -4,12 +4,14 @@
 
 using PANiXiDA.TacticalHeroes.Identity.Application.Auth.Abstractions;
 using PANiXiDA.TacticalHeroes.Identity.Application.Auth.Login;
+using PANiXiDA.TacticalHeroes.Identity.Domain.Roles;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.Enumerations;
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.ValueObjects;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Claims;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Mappers;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Options.IdentityProvider;
+using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Roles.Write.DbModels;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.DbModels;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.Mappers;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.Queries;
@@ -18,6 +20,7 @@ namespace PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Servi
 
 public sealed class UserCredentialsService(
     UserManager<ApplicationUser> userManager,
+    RoleManager<ApplicationRole> roleManager,
     IOpenIddictTokenManager tokenManager,
     IOptions<IdentityProviderOptions> options,
     IAggregateTracker aggregateTracker,
@@ -39,7 +42,20 @@ public async Task<Result<Guid>> RegisterAsync(
             return Result.Failure<Guid>(errors: validationResult.Errors);
         }
 
+        var developerRole = await roleManager.FindByNameAsync(RoleNames.Developer);
+        if (developerRole is null)
+        {
+            return Result.Failure<Guid>(error: Error.NotFound(message: "Developer role was not found."));
+        }
+
+        var roleIdResult = RoleId.Create(value: developerRole.Id);
+        if (roleIdResult.IsFailure)
+        {
+            return Result.Failure<Guid>(errors: roleIdResult.Errors);
+        }
+
         var user = User.Register(email: emailResult.Value, userName: userNameResult.Value);
+        user.AssignRole(roleIdResult.Value);
         var nowUtc = timeProvider.GetUtcNow().UtcDateTime;
         var applicationUser = ApplicationUserMapper.ToDbModel(
             user: user,

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/Persistence/Features/Users/Read/GetDetails/UserDetailsReadModelMapper.cs

@@ -15,14 +15,17 @@
         return query.Select(user => new UserDetailsReadModel(
             Id: user.Id,
             Email: user.Email,
             UserName: user.UserName!,
             IsConfirmed: user.EmailConfirmed,
             Status: user.Status,
             StatusDisplayName: UserStatus.FromName(name: user.Status).DisplayName,
             Claims: user.Claims
                 .Select(claim => new Claim(
                     type: claim.ClaimType!,
                     value: claim.ClaimValue!))
-                .ToArray()));
+                .ToArray())
+        {
+            RoleIds = user.Roles.Select(role => role.RoleId).ToArray()
+        });
     }
 }

src/Identity/PANiXiDA.TacticalHeroes.Identity.Infrastructure/Persistence/Features/Users/Write/UsersRepository.cs

@@ -6,6 +6,7 @@
 using PANiXiDA.TacticalHeroes.Identity.Domain.Users.Enumerations;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.IdentityProvider.Mappers;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Core;
+using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Roles.Write.DbModels;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.DbModels;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.Mappers;
 using PANiXiDA.TacticalHeroes.Identity.Infrastructure.Persistence.Features.Users.Write.Queries;
@@ -25,6 +26,12 @@ public async Task<Result<Guid>> AddAsync(
         string password,
         CancellationToken cancellationToken)
     {
+        var rolesResult = await ValidateRolesAsync(user, cancellationToken);
+        if (rolesResult.IsFailure)
+        {
+            return Result.Failure<Guid>(errors: rolesResult.Errors);
+        }
+
         var nowUtc = timeProvider.GetUtcNow().UtcDateTime;
         var applicationUser = ApplicationUserMapper.ToDbModel(
             user: user,
@@ -45,7 +52,8 @@ public async Task<Result<Guid>> AddAsync(
 
     public async Task<Result> UpdateAsync(
         User user,
-        CancellationToken cancellationToken)
+        CancellationToken cancellationToken,
+        bool replaceRoles = true)
     {
         var applicationUser = await userManager.Users
             .WithAuthorizationGraph()
@@ -56,6 +64,16 @@ public async Task<Result> UpdateAsync(
             return UserNotFound();
         }
 
+        if (replaceRoles)
+        {
+            var rolesResult = await ValidateRolesAsync(user, cancellationToken);
+            if (rolesResult.IsFailure)
+            {
+                return rolesResult;
+            }
+        }
+
+        var rolesChanged = replaceRoles && SyncRoles(applicationUser, user);
         ApplicationUserMapper.MapToDbModel(
             user: user,
             dbModel: applicationUser,
@@ -64,12 +82,14 @@ public async Task<Result> UpdateAsync(
             applicationUser: applicationUser,
             user: user);
 
-        if (user.Status.IsBlocked)
+        if (user.Status.IsBlocked || rolesChanged)
         {
             await RevokeAllTokensAsync(user.Id.Value, cancellationToken);
         }
 
-        var identityResult = await userManager.UpdateAsync(applicationUser);
+        var identityResult = rolesChanged
+            ? await userManager.UpdateSecurityStampAsync(applicationUser)
+            : await userManager.UpdateAsync(applicationUser);
 
         if (!identityResult.Succeeded)
         {
@@ -164,6 +184,46 @@ private async Task RevokeAllTokensAsync(
         await tokenManager.RevokeBySubjectAsync(id.ToString(), cancellationToken);
     }
 
+    private async Task<Result> ValidateRolesAsync(User user, CancellationToken cancellationToken)
+    {
+        var roleIds = user.RoleIds.Select(roleId => roleId.Value).ToArray();
+        if (roleIds.Length == 0)
+        {
+            return Result.Success();
+        }
+
+        var count = await dbContext.Set<ApplicationRole>()
+            .CountAsync(role => roleIds.Contains(role.Id), cancellationToken);
+        if (count != roleIds.Length)
+        {
+            return Result.Failure(error: Error.Validation(message: "One or more roles were not found.")
+                .WithField(nameof(User.RoleIds)));
+        }
+
+        return Result.Success();
+    }
+
+    private bool SyncRoles(ApplicationUser applicationUser, User user)
+    {
+        var roleIds = user.RoleIds.Select(roleId => roleId.Value).ToHashSet();
+        if (roleIds.SetEquals(applicationUser.Roles.Select(role => role.RoleId)))
+        {
+            return false;
+        }
+
+        foreach (var currentRole in applicationUser.Roles.Where(role => !roleIds.Contains(role.RoleId)).ToArray())
+        {
+            dbContext.Set<ApplicationUserRole>().Remove(currentRole);
+        }
+
+        foreach (var roleId in roleIds.Where(id => applicationUser.Roles.All(role => role.RoleId != id)))
+        {
+            applicationUser.Roles.Add(new ApplicationUserRole { UserId = applicationUser.Id, RoleId = roleId });
+        }
+
+        return true;
+    }
+
     private void SyncClaims(
         ApplicationUser applicationUser,
         User user)

src/Identity/PANiXiDA.TacticalHeroes.Identity.Presentation/Features/Users/Create/CreateUserRequest.cs

@@ -8,4 +8,5 @@ public sealed record CreateUserRequest(
     string Password,
     bool IsConfirmed,
     IReadOnlyCollection<Claim> Claims,
-    string Status);
+    string Status,
+    IReadOnlyCollection<Guid>? RoleIds = null);