add xmldoc comments

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

@@ -6,10 +6,34 @@ using Microsoft.Data.SqlClient;
 
 namespace Infrastructure.Repository.Auth;
 
+/// <summary>
+/// ADO.NET-based implementation of <see cref="IAuthRepository"/> backed by SQL Server stored procedures,
+/// handling user registration, credential lookup/rotation, and account verification.
+/// </summary>
+/// <param name="connectionFactory">The factory used to create database connections.</param>
 public class AuthRepository(ISqlConnectionFactory connectionFactory)
     : Repository<Domain.Entities.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>
+    /// <param name="username">Unique username for the user</param>
+    /// <param name="firstName">User's first name</param>
+    /// <param name="lastName">User's last name</param>
+    /// <param name="email">User's email address</param>
+    /// <param name="dateOfBirth">User's date of birth</param>
+    /// <param name="passwordHash">Hashed password</param>
+    /// <returns>The newly created UserAccount with generated ID</returns>
+    /// <exception cref="Exception">Thrown when the newly registered user cannot be retrieved after registration.</exception>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount> RegisterUserAsync(
         string username,
         string firstName,
@@ -68,6 +92,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await GetUserByIdAsync(userAccountId) ?? throw new Exception("Failed to retrieve newly registered user.");
     }
 
+    /// <summary>
+    /// Retrieves a user account by email address (typically used for login) using the
+    /// <c>usp_GetUserAccountByEmail</c> stored procedure.
+    /// </summary>
+    /// <param name="email">Email address to search for</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByEmailAsync(
         string email
     )
@@ -83,6 +114,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves a user account by username (typically used for login) using the
+    /// <c>usp_GetUserAccountByUsername</c> stored procedure.
+    /// </summary>
+    /// <param name="username">Username to search for</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByUsernameAsync(
         string username
     )
@@ -98,6 +136,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves the active (non-revoked) credential for a user account using the
+    /// <c>USP_GetActiveUserCredentialByUserAccountId</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>Active UserCredential if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<UserCredential?> GetActiveCredentialByUserAccountIdAsync(
         Guid userAccountId
     )
@@ -113,6 +158,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToCredentialEntity(reader) : null;
     }
 
+    /// <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>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <param name="newPasswordHash">New hashed password</param>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task RotateCredentialAsync(
         Guid userAccountId,
         string newPasswordHash
@@ -129,6 +181,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         await command.ExecuteNonQueryAsync();
     }
 
+    /// <summary>
+    /// Retrieves a user account by ID using the <c>usp_GetUserAccountById</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByIdAsync(
         Guid userAccountId
     )
@@ -144,6 +202,15 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <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>
+    /// <param name="userAccountId">ID of the user account to confirm</param>
+    /// <returns>The confirmed <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if the user account does not exist.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails for a reason other than a duplicate verification record.</exception>
     public async Task<Domain.Entities.UserAccount?> ConfirmUserAccountAsync(
         Guid userAccountId
     )
@@ -180,6 +247,13 @@ 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 for a matching record.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>True if the user has a verification record, false otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<bool> IsUserVerifiedAsync(Guid userAccountId)
     {
         await using var connection = await CreateConnection();
@@ -194,6 +268,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return result != null && result != DBNull.Value;
     }
 
+    /// <summary>
+    /// Determines whether a <see cref="SqlException"/> represents a duplicate key violation
+    /// (SQL Server error 2601 or 2627), used to detect a concurrent duplicate verification insert.
+    /// </summary>
+    /// <param name="ex">The SQL exception to inspect.</param>
+    /// <returns>True if the exception represents a duplicate key violation, false otherwise.</returns>
     private static bool IsDuplicateVerificationViolation(SqlException ex)
     {
         // 2601/2627 are duplicate key violations in SQL Server.
@@ -204,6 +284,8 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     /// <summary>
     /// Maps a data reader row to a UserAccount entity.
     /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="Domain.Entities.UserAccount"/> instance.</returns>
     protected override Domain.Entities.UserAccount MapToEntity(
         DbDataReader reader
     )
@@ -227,8 +309,11 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     }
 
     /// <summary>
-    /// Maps a data reader row to a UserCredential entity.
+    /// 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>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="UserCredential"/> instance.</returns>
     private static UserCredential MapToCredentialEntity(DbDataReader reader)
     {
         var entity = new UserCredential
@@ -265,8 +350,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     }
 
     /// <summary>
-    /// Helper method to add a parameter to a database command.
+    /// Helper method to add a parameter to a database command, converting <c>null</c> values to
+    /// <see cref="DBNull.Value"/>.
     /// </summary>
+    /// <param name="command">The command to add the parameter to.</param>
+    /// <param name="name">The parameter name (including any prefix, e.g. "@Username").</param>
+    /// <param name="value">The parameter value, or <c>null</c> to bind <see cref="DBNull.Value"/>.</param>
     private static void AddParameter(
         DbCommand command,
         string name,

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

@@ -65,8 +65,7 @@ public interface IAuthRepository
     /// Marks a user account as confirmed.
     /// </summary>
     /// <param name="userAccountId">ID of the user account to confirm</param>
-    /// <returns>The confirmed UserAccount entity</returns>
-    /// <exception cref="UnauthorizedException">If user account not found</exception>
+    /// <returns>The confirmed UserAccount entity, or null if the user account does not exist</returns>
     Task<Domain.Entities.UserAccount?> ConfirmUserAccountAsync(Guid userAccountId);
 
     /// <summary>