Migrate Auth/Brewery/Location repositories to pure Dapper; rename Timer to RowVersion (#237)

* Integrate Spectre.Console into seed application, use async data loading

* Replace stored-procedure repositories with Dapper-based repositories

Removes the USP_* stored procedures for Auth, Location, and Brewery
data access in favour of services built with Dapper.

Adds a new Features.Locations slice and optimistic concurrency support
for the Brewery slice.

* Add new documentation for Dapper migration/database schema

* Update FluentAssertions to most recent open source ver

* Update XML doc comment in backend projects

* Modify brewery location dto to include denormalized data

* - Updated column names from 'Timer' to 'RowVersion' in schema.sql for
- Introduced new BeerPost entity and updated BreweryPost and BreweryPostLocation entities to use 'RowVersion' for concurrency.
- Modified UserAccount, UserCredential, UserVerification, City, StateProvince, and Country entities to use 'RowVersion' instead of 'Timer'.
- Updated tests and command handlers to reflect changes in concurrency token from 'Timer' to 'RowVersion'.
- Adjusted BreweryDto and BreweryDtoMapper to include 'RowVersion' and updated mapping logic accordingly.
- Ensured all repository methods and interfaces are aligned with the new concurrency handling approach.

* updates

* Add BeerStyle entity and related properties; refactor BreweryDto to remove BeerPosts

* Fix Api.Specs test failures: stale Timer column refs and missing test.user fixture

* Remove repository tests, usages of registration dto used in repo

* archive old stored procs/functions

* update stale docs

* Add instructions for generating cryptographically secure base64 secrets on macOS/Linux and Windows

web/backend/Features/Features.Auth/Commands/Login/LoginCommand.cs

@@ -1,10 +1,10 @@
 using Features.Auth.Dtos;
 using MediatR;
 
-namespace Features.Auth.Queries.Login;
+namespace Features.Auth.Commands.Login;
 
 /// <summary>
 ///     Authenticates a user using their username and password and issues new tokens. Bound directly
 ///     from the request body of <c>POST /api/auth/login</c>.
 /// </summary>
-public record LoginQuery(string Username, string Password) : IRequest<LoginPayload>;
+public record LoginCommand(string Username, string Password) : IRequest<LoginPayload>;

web/backend/Features/Features.Auth/Commands/Login/LoginHandler.cs

@@ -6,22 +6,22 @@ using Features.Auth.Services;
 using Infrastructure.PasswordHashing;
 using MediatR;
 
-namespace Features.Auth.Queries.Login;
+namespace Features.Auth.Commands.Login;
 
 /// <summary>
-///     Handles <see cref="LoginQuery" /> by verifying credentials and issuing access/refresh tokens.
+///     Handles <see cref="LoginCommand" /> by verifying credentials and issuing access/refresh tokens.
 /// </summary>
 public class LoginHandler(
     IAuthRepository authRepo,
     IPasswordInfrastructure passwordInfrastructure,
     ITokenService tokenService
-) : IRequestHandler<LoginQuery, LoginPayload>
+) : IRequestHandler<LoginCommand, LoginPayload>
 {
     /// <exception cref="UnauthorizedException">
     ///     Thrown when the username does not match any account, the account has no active credential,
     ///     or the supplied password does not match the stored hash.
     /// </exception>
-    public async Task<LoginPayload> Handle(LoginQuery request, CancellationToken cancellationToken)
+    public async Task<LoginPayload> Handle(LoginCommand request, CancellationToken cancellationToken)
     {
         UserAccount user =
             await authRepo.GetUserByUsernameAsync(request.Username)

web/backend/Features/Features.Auth/Commands/Login/LoginValidator.cs

@@ -1,8 +1,9 @@
 using FluentValidation;
 
-namespace Features.Auth.Queries.Login;
+namespace Features.Auth.Commands.Login;
 
-public class LoginValidator : AbstractValidator<LoginQuery>
+/// <summary>Validates that <see cref="LoginCommand.Username" /> and <see cref="LoginCommand.Password" /> are present.</summary>
+public class LoginValidator : AbstractValidator<LoginCommand>
 {
     public LoginValidator()
     {

web/backend/Features/Features.Auth/Commands/RefreshToken/RefreshTokenHandler.cs

@@ -11,6 +11,10 @@ namespace Features.Auth.Commands.RefreshToken;
 public class RefreshTokenHandler(ITokenService tokenService)
     : IRequestHandler<RefreshTokenCommand, LoginPayload>
 {
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the refresh token is invalid or expired, or when the user account it refers to no
+    ///     longer exists.
+    /// </exception>
     public async Task<LoginPayload> Handle(
         RefreshTokenCommand request,
         CancellationToken cancellationToken

web/backend/Features/Features.Auth/Commands/RefreshToken/RefreshTokenValidator.cs

@@ -2,6 +2,7 @@ using FluentValidation;
 
 namespace Features.Auth.Commands.RefreshToken;
 
+/// <summary>Validates that <see cref="RefreshTokenCommand.RefreshToken" /> is present.</summary>
 public class RefreshTokenValidator : AbstractValidator<RefreshTokenCommand>
 {
     public RefreshTokenValidator()

web/backend/Features/Features.Auth/Commands/RegisterUser/RegisterUserHandler.cs

@@ -34,14 +34,18 @@ public class RegisterUserHandler(
         string hashed = passwordInfrastructure.Hash(request.Password);
 
         UserAccount createdUser = await authRepo.RegisterUserAsync(
-            new UserRegistrationDto(
-                request.Username,
-                request.FirstName,
-                request.LastName,
-                request.Email,
-                request.DateOfBirth,
-                hashed
-            )
+            new UserAccount
+            {
+                Username = request.Username,
+                FirstName =  request.FirstName,
+                LastName =  request.LastName,
+                DateOfBirth =  request.DateOfBirth,
+                Email = request.Email,
+                UserCredential = new UserCredential
+                {
+                    Hash = hashed,
+                }
+            }
         );
 
         string accessToken = tokenService.GenerateAccessToken(createdUser);

web/backend/Features/Features.Auth/Commands/RegisterUser/RegisterUserValidator.cs

@@ -2,6 +2,10 @@ using FluentValidation;
 
 namespace Features.Auth.Commands.RegisterUser;
 
+/// <summary>
+///     Validates the field-level constraints on <see cref="RegisterUserCommand" />: username format and
+///     length, name lengths, email format, minimum age of 19, and password complexity.
+/// </summary>
 public class RegisterUserValidator : AbstractValidator<RegisterUserCommand>
 {
     public RegisterUserValidator()

web/backend/Features/Features.Auth/Controllers/AuthController.cs

@@ -1,9 +1,9 @@
 using Features.Auth.Commands.ConfirmUser;
+using Features.Auth.Commands.Login;
 using Features.Auth.Commands.RefreshToken;
 using Features.Auth.Commands.RegisterUser;
 using Features.Auth.Commands.ResendConfirmationEmail;
 using Features.Auth.Dtos;
-using Features.Auth.Queries.Login;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
@@ -23,6 +23,11 @@ namespace Features.Auth.Controllers;
 [Authorize(AuthenticationSchemes = "JWT")]
 public class AuthController(IMediator mediator) : ControllerBase
 {
+    /// <summary>Registers a new user account.</summary>
+    /// <remarks>
+    ///     Anonymous access. Returns 201 Created with the new account's ID, username, and issued tokens.
+    ///     Returns 409 Conflict if the username or email is already taken.
+    /// </remarks>
     [AllowAnonymous]
     [HttpPost("register")]
     public async Task<ActionResult<ResponseBody<RegistrationPayload>>> Register(
@@ -40,11 +45,15 @@ public class AuthController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Authenticates a user by username and password and issues a new access/refresh token pair.</summary>
+    /// <remarks>
+    ///     Anonymous access. Returns 200 OK with the tokens, or 401 Unauthorized if the credentials are invalid.
+    /// </remarks>
     [AllowAnonymous]
     [HttpPost("login")]
-    public async Task<ActionResult<ResponseBody<LoginPayload>>> Login([FromBody] LoginQuery query)
+    public async Task<ActionResult<ResponseBody<LoginPayload>>> Login([FromBody] LoginCommand command)
     {
-        LoginPayload payload = await mediator.Send(query);
+        LoginPayload payload = await mediator.Send(command);
         return Ok(
             new ResponseBody<LoginPayload>
             {
@@ -54,6 +63,11 @@ public class AuthController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Confirms a user account using a confirmation token.</summary>
+    /// <remarks>
+    ///     Requires a valid JWT bearer token (no <c>[AllowAnonymous]</c> override). Returns 200 OK on success,
+    ///     or 401 Unauthorized if <paramref name="token" /> is invalid or expired.
+    /// </remarks>
     [HttpPost("confirm")]
     public async Task<ActionResult<ResponseBody<ConfirmationPayload>>> Confirm(
         [FromQuery] string token
@@ -69,6 +83,12 @@ public class AuthController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Resends the account confirmation email for the given user, generating a fresh confirmation token.</summary>
+    /// <remarks>
+    ///     Requires a valid JWT bearer token (no <c>[AllowAnonymous]</c> override). Always returns 200 OK, even
+    ///     if <paramref name="userId" /> does not exist or the account is already confirmed, to avoid user
+    ///     enumeration.
+    /// </remarks>
     [HttpPost("confirm/resend")]
     public async Task<ActionResult<ResponseBody>> ResendConfirmation([FromQuery] Guid userId)
     {
@@ -76,6 +96,11 @@ public class AuthController(IMediator mediator) : ControllerBase
         return Ok(new ResponseBody { Message = "confirmation email has been resent" });
     }
 
+    /// <summary>Exchanges a valid refresh token for a new access/refresh token pair.</summary>
+    /// <remarks>
+    ///     Anonymous access. Returns 200 OK with the new tokens, or 401 Unauthorized if the refresh token is
+    ///     invalid or expired.
+    /// </remarks>
     [AllowAnonymous]
     [HttpPost("refresh")]
     public async Task<ActionResult<ResponseBody<LoginPayload>>> Refresh(

web/backend/Features/Features.Auth/DependencyInjection/FeaturesAuthServiceCollectionExtensions.cs

@@ -5,8 +5,13 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Features.Auth.DependencyInjection;
 
+/// <summary>Registers the services required by Features.Auth with the dependency injection container.</summary>
 public static class FeaturesAuthServiceCollectionExtensions
 {
+    /// <summary>
+    ///     Adds <see cref="IAuthRepository" />, <see cref="ITokenService" />, and the Argon2 password hashing
+    ///     infrastructure as scoped services.
+    /// </summary>
     public static IServiceCollection AddFeaturesAuth(this IServiceCollection services)
     {
         services.AddScoped<IAuthRepository, AuthRepository>();

web/backend/Features/Features.Auth/Dtos/UserRegistrationDto.cs

@@ -1,10 +0,0 @@
-namespace Features.Auth.Dtos;
-
-public record UserRegistrationDto(
-    string Username,
-    string FirstName,
-    string LastName,
-    string Email,
-    DateTime DateOfBirth,
-    string PasswordHash
-);

web/backend/Features/Features.Auth/Features.Auth.csproj

@@ -3,6 +3,7 @@
         <TargetFramework>net10.0</TargetFramework>
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
+
         <RootNamespace>Features.Auth</RootNamespace>
     </PropertyGroup>
 
@@ -19,4 +20,8 @@
         <ProjectReference Include="..\..\Shared\Shared.Contracts\Shared.Contracts.csproj" />
         <ProjectReference Include="..\..\Shared\Shared.Application\Shared.Application.csproj" />
     </ItemGroup>
+
+    <ItemGroup>
+      <Folder Include="Queries\" />
+    </ItemGroup>
 </Project>

web/backend/Features/Features.Auth/Repository/AuthRepository.cs

@@ -1,6 +1,7 @@
-using System.Data;
 using System.Data.Common;
+using Dapper;
 using Domain.Entities;
+using Domain.Exceptions;
 using Features.Auth.Dtos;
 using Infrastructure.Sql;
 using Microsoft.Data.SqlClient;
@@ -8,155 +9,184 @@ using Microsoft.Data.SqlClient;
 namespace Features.Auth.Repository;
 
 /// <summary>
-///     ADO.NET-based implementation of <see cref="IAuthRepository" /> backed by SQL Server stored procedures,
-///     handling user registration, credential lookup/rotation, and account verification.
+///     Dapper-based implementation of <see cref="IAuthRepository" />, handling user registration,
+///     credential lookup/rotation, and account verification.
 /// </summary>
 public class AuthRepository(ISqlConnectionFactory connectionFactory)
     : Repository<UserAccount>(connectionFactory),
         IAuthRepository
 {
-    /// <summary>
-    ///     Registers a new user account and initial credential using the <c>USP_RegisterUser</c> stored
-    ///     procedure, then fetches and returns the newly created user.
-    /// </summary>
-    /// <remarks>
-    ///     The stored procedure's scalar result (expected to be the new user's ID) is parsed defensively:
-    ///     it may be returned as a <see cref="Guid" />, a parseable <see cref="string" />, or a 16-byte array.
-    ///     If the result cannot be interpreted, <see cref="Guid.Empty" /> is used, which will cause the
-    ///     subsequent lookup to fail.
-    /// </remarks>
-    /// <exception cref="Exception">Thrown when the newly registered user cannot be retrieved after registration.</exception>
-    public async Task<UserAccount> RegisterUserAsync(UserRegistrationDto userRegistrationDto)
+    /// <inheritdoc />
+    /// <remarks>The account and credential are inserted within a single database transaction.</remarks>
+    public async Task<UserAccount> RegisterUserAsync(UserAccount ua)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
+        await using DbTransaction transaction = await connection.BeginTransactionAsync();
 
-        command.CommandText = "USP_RegisterUser";
-        command.CommandType = CommandType.StoredProcedure;
 
-        var (username, firstName, lastName, email, dateOfBirth, passwordHash) = userRegistrationDto;
+        Guid userAccountId;
 
-        AddParameter(command, "@Username", username);
-        AddParameter(command, "@FirstName", firstName);
-        AddParameter(command, "@LastName", lastName);
-        AddParameter(command, "@Email", email);
-        AddParameter(command, "@DateOfBirth", dateOfBirth);
-        AddParameter(command, "@Hash", passwordHash);
-
-        object? result = await command.ExecuteScalarAsync();
-
-        Guid userAccountId = Guid.Empty;
-        if (result != null && result != DBNull.Value)
+        try
         {
-            if (result is Guid g)
-                userAccountId = g;
-            else if (result is string s && Guid.TryParse(s, out Guid parsed))
-                userAccountId = parsed;
-            else if (result is byte[] bytes && bytes.Length == 16)
-                userAccountId = new Guid(bytes);
-            else
-                // Fallback: try to convert and parse string representation
-                try
-                {
-                    string? str = result.ToString();
-                    if (!string.IsNullOrEmpty(str) && Guid.TryParse(str, out Guid p))
-                        userAccountId = p;
-                }
-                catch
-                {
-                    userAccountId = Guid.Empty;
-                }
+            userAccountId = await connection.ExecuteScalarAsync<Guid>(
+                new CommandDefinition(
+                    """
+                    INSERT INTO dbo.UserAccount (Username, FirstName, LastName, DateOfBirth, Email)
+                    OUTPUT INSERTED.UserAccountID
+                    VALUES (@Username, @FirstName, @LastName, @DateOfBirth, @Email);
+                    """,
+                    new { ua.Username, ua.FirstName, ua.LastName, ua.DateOfBirth, ua.Email},
+                    transaction
+                )
+            );
+
+            int credentialRows = await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    INSERT INTO dbo.UserCredential (UserAccountId, Hash)
+                    VALUES (@UserAccountId, @Hash);
+                    """,
+                    new { UserAccountId = userAccountId, Hash = ua.UserCredential?.Hash },
+                    transaction
+                )
+            );
+
+            if (credentialRows == 0)
+                throw new InvalidOperationException("Failed to create user credential.");
+
+            await transaction.CommitAsync();
+        }
+        catch
+        {
+            await transaction.RollbackAsync();
+            throw;
         }
 
+        // perform round trip to get new User entity
         return await GetUserByIdAsync(userAccountId)
             ?? throw new Exception("Failed to retrieve newly registered user.");
     }
 
-    /// <summary>Retrieves a user account by email using the <c>usp_GetUserAccountByEmail</c> stored procedure.</summary>
+    /// <inheritdoc />
     public async Task<UserAccount?> GetUserByEmailAsync(string email)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "usp_GetUserAccountByEmail";
-        command.CommandType = CommandType.StoredProcedure;
-
-        AddParameter(command, "@Email", email);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        return await reader.ReadAsync() ? MapToEntity(reader) : null;
+        return await connection.QueryFirstOrDefaultAsync<UserAccount>(
+            """
+            SELECT UserAccountID, Username, FirstName, LastName, Email, CreatedAt, UpdatedAt, DateOfBirth, RowVersion
+            FROM dbo.UserAccount
+            WHERE Email = @Email
+            """,
+            new { Email = email }
+        );
     }
 
-    /// <summary>Retrieves a user account by username using the <c>usp_GetUserAccountByUsername</c> stored procedure.</summary>
+    /// <inheritdoc />
     public async Task<UserAccount?> GetUserByUsernameAsync(string username)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "usp_GetUserAccountByUsername";
-        command.CommandType = CommandType.StoredProcedure;
-
-        AddParameter(command, "@Username", username);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        return await reader.ReadAsync() ? MapToEntity(reader) : null;
+        return await connection.QueryFirstOrDefaultAsync<UserAccount>(
+            """
+            SELECT UserAccountID, Username, FirstName, LastName, Email, CreatedAt, UpdatedAt, DateOfBirth, RowVersion
+            FROM dbo.UserAccount
+            WHERE Username = @Username
+            """,
+            new { Username = username }
+        );
     }
 
-    /// <summary>
-    ///     Retrieves the active (non-revoked) credential for a user account using the
-    ///     <c>USP_GetActiveUserCredentialByUserAccountId</c> stored procedure.
-    /// </summary>
+    /// <inheritdoc />
     public async Task<UserCredential?> GetActiveCredentialByUserAccountIdAsync(Guid userAccountId)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_GetActiveUserCredentialByUserAccountId";
-        command.CommandType = CommandType.StoredProcedure;
-
-        AddParameter(command, "@UserAccountId", userAccountId);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        return await reader.ReadAsync() ? MapToCredentialEntity(reader) : null;
+        return await connection.QueryFirstOrDefaultAsync<UserCredential>(
+            """
+            SELECT UserCredentialId, UserAccountId, Hash, CreatedAt, RowVersion
+            FROM dbo.UserCredential
+            WHERE UserAccountId = @UserAccountId AND IsRevoked = 0
+            """,
+            new { UserAccountId = userAccountId }
+        );
     }
 
-    /// <summary>
-    ///     Rotates a user's credential by invalidating all existing credentials and creating a new one,
-    ///     using the <c>USP_RotateUserCredential</c> stored procedure.
-    /// </summary>
+    /// <inheritdoc />
     public async Task RotateCredentialAsync(Guid userAccountId, string newPasswordHash)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_RotateUserCredential";
-        command.CommandType = CommandType.StoredProcedure;
+        await using DbTransaction transaction = await connection.BeginTransactionAsync();
 
-        AddParameter(command, "@UserAccountId_", userAccountId);
-        AddParameter(command, "@Hash", newPasswordHash);
+        try
+        {
+            bool exists =
+                await connection.ExecuteScalarAsync<int?>(
+                    new CommandDefinition(
+                        """
+                        SELECT 1
+                        FROM dbo.UserAccount
+                        WHERE UserAccountID = @UserAccountId
+                        """,
+                        new { UserAccountId = userAccountId },
+                        transaction
+                    )
+                ) is not null;
 
-        await command.ExecuteNonQueryAsync();
+            if (!exists)
+                throw new NotFoundException("User account not found.");
+
+            await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    UPDATE dbo.UserCredential
+                    SET IsRevoked = 1, RevokedAt = GETDATE()
+                    WHERE UserAccountId = @UserAccountId
+                    """,
+                    new { UserAccountId = userAccountId },
+                    transaction
+                )
+            );
+
+            await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    INSERT INTO dbo.UserCredential (UserAccountId, Hash)
+                    VALUES (@UserAccountId, @Hash)
+                    """,
+                    new { UserAccountId = userAccountId, Hash = newPasswordHash },
+                    transaction
+                )
+            );
+
+            await transaction.CommitAsync();
+        }
+        catch
+        {
+            await transaction.RollbackAsync();
+            throw;
+        }
     }
 
-    /// <summary>Retrieves a user account by ID using the <c>usp_GetUserAccountById</c> stored procedure.</summary>
+    /// <inheritdoc />
     public async Task<UserAccount?> GetUserByIdAsync(Guid userAccountId)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "usp_GetUserAccountById";
-        command.CommandType = CommandType.StoredProcedure;
-
-        AddParameter(command, "@UserAccountId", userAccountId);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        return await reader.ReadAsync() ? MapToEntity(reader) : null;
+        return await connection.QueryFirstOrDefaultAsync<UserAccount>(
+            """
+            SELECT UserAccountID, Username, FirstName, LastName, Email, CreatedAt, UpdatedAt, DateOfBirth, RowVersion
+            FROM dbo.UserAccount
+            WHERE UserAccountID = @UserAccountId
+            """,
+            new { UserAccountId = userAccountId }
+        );
     }
 
-    /// <summary>
-    ///     Marks a user account as confirmed by creating a verification record via the
-    ///     <c>USP_CreateUserVerification</c> stored procedure. If the user is already verified, this is a
-    ///     no-op and the existing user is returned (idempotent). If a concurrent request verifies the user
-    ///     first, the resulting duplicate-key SQL exception (error 2601/2627) is swallowed.
-    /// </summary>
+    /// <inheritdoc />
+    /// <remarks>
+    ///     Confirmation is recorded by inserting a row into <c>dbo.UserVerification</c>. If a concurrent
+    ///     request verifies the same user first, the resulting duplicate-key SQL exception (error 2601/2627)
+    ///     is swallowed to keep the operation idempotent.
+    /// </remarks>
     /// <exception cref="Microsoft.Data.SqlClient.SqlException">
-    ///     Thrown when the database command fails for a reason other than
-    ///     a duplicate verification record.
+    ///     Thrown when the database command fails for a reason other than a duplicate verification record.
     /// </exception>
     public async Task<UserAccount?> ConfirmUserAccountAsync(Guid userAccountId)
     {
@@ -169,15 +199,16 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
             return user;
 
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_CreateUserVerification";
-        command.CommandType = CommandType.StoredProcedure;
-
-        AddParameter(command, "@UserAccountID_", userAccountId);
 
         try
         {
-            await command.ExecuteNonQueryAsync();
+            await connection.ExecuteAsync(
+                """
+                INSERT INTO dbo.UserVerification (UserAccountId, VerificationDateTime)
+                VALUES (@UserAccountId, GETDATE())
+                """,
+                new { UserAccountId = userAccountId }
+            );
         }
         catch (SqlException ex) when (IsDuplicateVerificationViolation(ex))
         {
@@ -188,19 +219,19 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await GetUserByIdAsync(userAccountId);
     }
 
-    /// <summary>Checks whether a user account has been verified by querying the <c>dbo.UserVerification</c> table.</summary>
+    /// <inheritdoc />
     public async Task<bool> IsUserVerifiedAsync(Guid userAccountId)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText =
-            "SELECT TOP 1 1 FROM dbo.UserVerification WHERE UserAccountID = @UserAccountID";
-        command.CommandType = CommandType.Text;
-
-        AddParameter(command, "@UserAccountID", userAccountId);
-
-        object? result = await command.ExecuteScalarAsync();
-        return result != null && result != DBNull.Value;
+        int? result = await connection.ExecuteScalarAsync<int?>(
+            """
+            SELECT TOP 1 1
+            FROM dbo.UserVerification
+            WHERE UserAccountID = @UserAccountId
+            """,
+            new { UserAccountId = userAccountId }
+        );
+        return result.HasValue;
     }
 
     /// <summary>Determines whether a <see cref="SqlException" /> is a duplicate key violation (SQL Server error 2601 or 2627).</summary>
@@ -209,67 +240,4 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         // 2601/2627 are duplicate key violations in SQL Server.
         return ex.Number == 2601 || ex.Number == 2627;
     }
-
-    protected override UserAccount MapToEntity(DbDataReader reader)
-    {
-        return new UserAccount
-        {
-            UserAccountId = reader.GetGuid(reader.GetOrdinal("UserAccountId")),
-            Username = reader.GetString(reader.GetOrdinal("Username")),
-            FirstName = reader.GetString(reader.GetOrdinal("FirstName")),
-            LastName = reader.GetString(reader.GetOrdinal("LastName")),
-            Email = reader.GetString(reader.GetOrdinal("Email")),
-            CreatedAt = reader.GetDateTime(reader.GetOrdinal("CreatedAt")),
-            UpdatedAt = reader.IsDBNull(reader.GetOrdinal("UpdatedAt"))
-                ? null
-                : reader.GetDateTime(reader.GetOrdinal("UpdatedAt")),
-            DateOfBirth = reader.GetDateTime(reader.GetOrdinal("DateOfBirth")),
-            Timer = reader.IsDBNull(reader.GetOrdinal("Timer")) ? null : (byte[])reader["Timer"],
-        };
-    }
-
-    /// <summary>
-    ///     Maps a data reader row to a UserCredential entity. The <c>Timer</c> column is mapped only if
-    ///     present in the reader's schema, allowing this method to support result sets that omit it.
-    /// </summary>
-    private static UserCredential MapToCredentialEntity(DbDataReader reader)
-    {
-        UserCredential entity = new()
-        {
-            UserCredentialId = reader.GetGuid(reader.GetOrdinal("UserCredentialId")),
-            UserAccountId = reader.GetGuid(reader.GetOrdinal("UserAccountId")),
-            Hash = reader.GetString(reader.GetOrdinal("Hash")),
-            CreatedAt = reader.GetDateTime(reader.GetOrdinal("CreatedAt")),
-        };
-
-        // Optional columns
-        bool hasTimer =
-            reader
-                .GetSchemaTable()
-                ?.Rows.Cast<DataRow>()
-                .Any(r =>
-                    string.Equals(
-                        r["ColumnName"]?.ToString(),
-                        "Timer",
-                        StringComparison.OrdinalIgnoreCase
-                    )
-                )
-            ?? false;
-
-        if (hasTimer)
-            entity.Timer = reader.IsDBNull(reader.GetOrdinal("Timer"))
-                ? null
-                : (byte[])reader["Timer"];
-
-        return entity;
-    }
-
-    /// <summary>Adds a parameter to a database command, converting <c>null</c> values to <see cref="DBNull.Value" />.</summary>
-    private static void AddParameter(DbCommand command, string name, object? value)
-    {
-        DbParameter p = command.CreateParameter();
-        p.ParameterName = name;
-        p.Value = value ?? DBNull.Value;
-        command.Parameters.Add(p);
-    }
 }

web/backend/Features/Features.Auth/Repository/IAuthRepository.cs

@@ -8,21 +8,32 @@ namespace Features.Auth.Repository;
 /// </summary>
 public interface IAuthRepository
 {
-    Task<UserAccount> RegisterUserAsync(UserRegistrationDto userRegistrationDto);
+    /// <summary>
+    ///     Registers a new user account and its initial credential as a single atomic operation, then
+    ///     returns the created account.
+    /// </summary>
+    /// <exception cref="Exception">Thrown when the newly registered user cannot be retrieved after registration.</exception>
+    Task<UserAccount> RegisterUserAsync(UserAccount ua);
 
+    /// <summary>Retrieves a user account by email, or <see langword="null" /> if none exists.</summary>
     Task<UserAccount?> GetUserByEmailAsync(string email);
 
+    /// <summary>Retrieves a user account by username, or <see langword="null" /> if none exists.</summary>
     Task<UserAccount?> GetUserByUsernameAsync(string username);
 
+    /// <summary>Retrieves the active (non-revoked) credential for a user account, or <see langword="null" /> if none exists.</summary>
     Task<UserCredential?> GetActiveCredentialByUserAccountIdAsync(Guid userAccountId);
 
     /// <summary>Rotates a user's credential by invalidating all existing credentials and creating a new one.</summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">Thrown when no account with <paramref name="userAccountId" /> exists.</exception>
     Task RotateCredentialAsync(Guid userAccountId, string newPasswordHash);
 
     /// <summary>Marks a user account as confirmed. Idempotent if the account is already verified.</summary>
     Task<UserAccount?> ConfirmUserAccountAsync(Guid userAccountId);
 
+    /// <summary>Retrieves a user account by ID, or <see langword="null" /> if none exists.</summary>
     Task<UserAccount?> GetUserByIdAsync(Guid userAccountId);
 
+    /// <summary>Determines whether a user account has been verified.</summary>
     Task<bool> IsUserVerifiedAsync(Guid userAccountId);
 }

web/backend/Features/Features.Auth/Services/ITokenService.cs

@@ -29,6 +29,7 @@ public record RefreshTokenResult(UserAccount UserAccount, string RefreshToken, s
 /// </summary>
 public static class TokenServiceExpirationHours
 {
+    /// <summary>1 hour.</summary>
     public const double AccessTokenHours = 1;
 
     /// <summary>21 days.</summary>
@@ -43,10 +44,22 @@ public static class TokenServiceExpirationHours
 /// </summary>
 public interface ITokenService
 {
+    /// <summary>
+    ///     Generates a signed access token for the given user, expiring after
+    ///     <see cref="TokenServiceExpirationHours.AccessTokenHours" /> hours.
+    /// </summary>
     string GenerateAccessToken(UserAccount user);
 
+    /// <summary>
+    ///     Generates a signed refresh token for the given user, expiring after
+    ///     <see cref="TokenServiceExpirationHours.RefreshTokenHours" /> hours.
+    /// </summary>
     string GenerateRefreshToken(UserAccount user);
 
+    /// <summary>
+    ///     Generates a signed confirmation token for the given user, expiring after
+    ///     <see cref="TokenServiceExpirationHours.ConfirmationTokenHours" /> hours.
+    /// </summary>
     string GenerateConfirmationToken(UserAccount user);
 
     /// <summary>Generates a token of the type specified by <typeparamref name="T" />.</summary>
@@ -54,12 +67,28 @@ public interface ITokenService
     string GenerateToken<T>(UserAccount user)
         where T : struct, Enum;
 
+    /// <summary>Validates an access token's signature and expiration and extracts the caller's identity.</summary>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     Task<ValidatedToken> ValidateAccessTokenAsync(string token);
 
+    /// <summary>Validates a refresh token's signature and expiration and extracts the caller's identity.</summary>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     Task<ValidatedToken> ValidateRefreshTokenAsync(string token);
 
+    /// <summary>Validates a confirmation token's signature and expiration and extracts the caller's identity.</summary>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     Task<ValidatedToken> ValidateConfirmationTokenAsync(string token);
 
     /// <summary>Validates a refresh token and issues a new access/refresh token pair for the associated user.</summary>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the refresh token is invalid or expired, or when the user account it refers to no
+    ///     longer exists.
+    /// </exception>
     Task<RefreshTokenResult> RefreshTokenAsync(string refreshTokenString);
 }

web/backend/Features/Features.Auth/Services/TokenService.cs

@@ -48,6 +48,7 @@ public class TokenService : ITokenService
             );
     }
 
+    /// <inheritdoc />
     public string GenerateAccessToken(UserAccount user)
     {
         DateTime expiresAt = DateTime.UtcNow.AddHours(TokenServiceExpirationHours.AccessTokenHours);
@@ -59,6 +60,7 @@ public class TokenService : ITokenService
         );
     }
 
+    /// <inheritdoc />
     public string GenerateRefreshToken(UserAccount user)
     {
         DateTime expiresAt = DateTime.UtcNow.AddHours(
@@ -72,6 +74,7 @@ public class TokenService : ITokenService
         );
     }
 
+    /// <inheritdoc />
     public string GenerateConfirmationToken(UserAccount user)
     {
         DateTime expiresAt = DateTime.UtcNow.AddHours(
@@ -85,12 +88,7 @@ public class TokenService : ITokenService
         );
     }
 
-    /// <summary>
-    ///     Generates a token of the kind specified by <typeparamref name="T" />, dispatching to
-    ///     <see cref="GenerateAccessToken" />, <see cref="GenerateRefreshToken" />, or
-    ///     <see cref="GenerateConfirmationToken" />.
-    /// </summary>
-    /// <typeparam name="T">Must be <see cref="TokenType" />.</typeparam>
+    /// <inheritdoc />
     /// <exception cref="InvalidOperationException">
     ///     Thrown when <typeparamref name="T" /> is not <see cref="TokenType" /> or does not resolve to a known token type.
     /// </exception>
@@ -114,33 +112,25 @@ public class TokenService : ITokenService
         };
     }
 
-    /// <exception cref="Domain.Exceptions.UnauthorizedException">
-    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
-    /// </exception>
+    /// <inheritdoc />
     public async Task<ValidatedToken> ValidateAccessTokenAsync(string token)
     {
         return await ValidateTokenInternalAsync(token, _accessTokenSecret, "access");
     }
 
-    /// <exception cref="Domain.Exceptions.UnauthorizedException">
-    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
-    /// </exception>
+    /// <inheritdoc />
     public async Task<ValidatedToken> ValidateRefreshTokenAsync(string token)
     {
         return await ValidateTokenInternalAsync(token, _refreshTokenSecret, "refresh");
     }
 
-    /// <exception cref="Domain.Exceptions.UnauthorizedException">
-    ///     Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
-    /// </exception>
+    /// <inheritdoc />
     public async Task<ValidatedToken> ValidateConfirmationTokenAsync(string token)
     {
         return await ValidateTokenInternalAsync(token, _confirmationTokenSecret, "confirmation");
     }
 
-    /// <exception cref="Domain.Exceptions.UnauthorizedException">
-    ///     Thrown when the refresh token is invalid, or when the user account it refers to no longer exists.
-    /// </exception>
+    /// <inheritdoc />
     public async Task<RefreshTokenResult> RefreshTokenAsync(string refreshTokenString)
     {
         ValidatedToken validated = await ValidateRefreshTokenAsync(refreshTokenString);