add xmldoc comments

web/backend/Service/Service.Auth/ConfirmationService.cs

@@ -5,12 +5,28 @@ using Service.Emails;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Handles confirmation of newly registered user accounts and resending of confirmation emails.
+/// </summary>
+/// <param name="authRepository">Repository used to look up and confirm user accounts.</param>
+/// <param name="tokenService">Service used to generate and validate confirmation tokens.</param>
+/// <param name="emailService">Service used to send confirmation-related emails.</param>
 public class ConfirmationService(
     IAuthRepository authRepository,
     ITokenService tokenService,
     IEmailService emailService
 ) : IConfirmationService
 {
+    /// <summary>
+    /// Validates a confirmation token and marks the corresponding user account as confirmed.
+    /// </summary>
+    /// <param name="confirmationToken">The confirmation token issued to the user, typically delivered via email.</param>
+    /// <returns>
+    /// A <see cref="ConfirmationServiceReturn"/> containing the UTC timestamp of confirmation and the confirmed user's ID.
+    /// </returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when the confirmation token is invalid or expired, or when the associated user account cannot be found.
+    /// </exception>
     public async Task<ConfirmationServiceReturn> ConfirmUserAsync(
         string confirmationToken
     )
@@ -34,6 +50,15 @@ public class ConfirmationService(
         );
     }
 
+    /// <summary>
+    /// Resends the account confirmation email to a user, generating a fresh confirmation token.
+    /// </summary>
+    /// <param name="userId">The unique identifier of the user requesting the resend.</param>
+    /// <returns>A task that completes once the operation has finished.</returns>
+    /// <remarks>
+    /// Returns silently without sending an email if the user does not exist (to prevent user enumeration)
+    /// or if the user's account is already verified.
+    /// </remarks>
     public async Task ResendConfirmationEmailAsync(Guid userId)
     {
         var user = await authRepository.GetUserByIdAsync(userId);

web/backend/Service/Service.Auth/IConfirmationService.cs

@@ -3,11 +3,30 @@ using Infrastructure.Repository.Auth;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Represents the result of successfully confirming a user account.
+/// </summary>
+/// <param name="ConfirmedAt">The UTC date and time at which the account was confirmed.</param>
+/// <param name="UserId">The unique identifier of the confirmed user.</param>
 public record ConfirmationServiceReturn(DateTime ConfirmedAt, Guid UserId);
 
+/// <summary>
+/// Defines operations for confirming user accounts and resending confirmation emails.
+/// </summary>
 public interface IConfirmationService
 {
+    /// <summary>
+    /// Validates a confirmation token and confirms the corresponding user account.
+    /// </summary>
+    /// <param name="confirmationToken">The confirmation token issued to the user.</param>
+    /// <returns>A <see cref="ConfirmationServiceReturn"/> describing the confirmed account.</returns>
     Task<ConfirmationServiceReturn> ConfirmUserAsync(string confirmationToken);
+
+    /// <summary>
+    /// Resends the account confirmation email for the specified user.
+    /// </summary>
+    /// <param name="userId">The unique identifier of the user requesting the resend.</param>
+    /// <returns>A task that completes once the operation has finished.</returns>
     Task ResendConfirmationEmailAsync(Guid userId);
 
 }

web/backend/Service/Service.Auth/ILoginService.cs

@@ -2,12 +2,28 @@ using Domain.Entities;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Represents the result of a successful login attempt.
+/// </summary>
+/// <param name="UserAccount">The authenticated user's account.</param>
+/// <param name="RefreshToken">The issued refresh token.</param>
+/// <param name="AccessToken">The issued access token.</param>
 public record LoginServiceReturn(
     UserAccount UserAccount,
     string RefreshToken,
     string AccessToken
 );
+
+/// <summary>
+/// Defines the operation for authenticating a user with a username and password.
+/// </summary>
 public interface ILoginService
 {
+    /// <summary>
+    /// Authenticates a user using their username and password and issues new tokens.
+    /// </summary>
+    /// <param name="username">The username of the account to authenticate.</param>
+    /// <param name="password">The plain-text password to verify against the stored credential.</param>
+    /// <returns>A <see cref="LoginServiceReturn"/> containing the authenticated user and issued tokens.</returns>
     Task<LoginServiceReturn> LoginAsync(string username, string password);
 }

web/backend/Service/Service.Auth/IRegisterService.cs

@@ -2,14 +2,45 @@ using Domain.Entities;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Represents the result of a user registration attempt.
+/// </summary>
 public record RegisterServiceReturn
 {
+    /// <summary>
+    /// Gets a value indicating whether tokens were issued for the newly created account.
+    /// <c>false</c> when token generation failed, in which case <see cref="AccessToken"/> and
+    /// <see cref="RefreshToken"/> are empty.
+    /// </summary>
     public bool IsAuthenticated { get; init; } = false;
+
+    /// <summary>
+    /// Gets a value indicating whether the registration confirmation email was sent successfully.
+    /// </summary>
     public bool EmailSent { get; init; } = false;
+
+    /// <summary>
+    /// Gets the user account that was created.
+    /// </summary>
     public UserAccount UserAccount { get; init; }
+
+    /// <summary>
+    /// Gets the issued access token, or an empty string if authentication was not completed.
+    /// </summary>
     public string AccessToken { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the issued refresh token, or an empty string if authentication was not completed.
+    /// </summary>
     public string RefreshToken { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Initializes a new instance representing a successful registration with issued tokens.
+    /// </summary>
+    /// <param name="userAccount">The newly created user account.</param>
+    /// <param name="accessToken">The issued access token.</param>
+    /// <param name="refreshToken">The issued refresh token.</param>
+    /// <param name="emailSent">Whether the confirmation email was sent successfully.</param>
     public RegisterServiceReturn(
         UserAccount userAccount,
         string accessToken,
@@ -24,14 +55,27 @@ public record RegisterServiceReturn
         RefreshToken = refreshToken;
     }
 
+    /// <summary>
+    /// Initializes a new instance representing a registration where tokens could not be issued.
+    /// </summary>
+    /// <param name="userAccount">The newly created user account.</param>
     public RegisterServiceReturn(UserAccount userAccount)
     {
         UserAccount = userAccount;
     }
 }
 
+/// <summary>
+/// Defines the operation for registering a new user account.
+/// </summary>
 public interface IRegisterService
 {
+    /// <summary>
+    /// Registers a new user account with the given password.
+    /// </summary>
+    /// <param name="userAccount">The user account details to register.</param>
+    /// <param name="password">The plain-text password to hash and store for the new account.</param>
+    /// <returns>A <see cref="RegisterServiceReturn"/> describing the outcome of the registration.</returns>
     Task<RegisterServiceReturn> RegisterAsync(
         UserAccount userAccount,
         string password

web/backend/Service/Service.Auth/ITokenService.cs

@@ -7,40 +7,119 @@ using Infrastructure.Repository.Auth;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Identifies the kind of token being generated or validated.
+/// </summary>
 public enum TokenType
 {
+    /// <summary>A short-lived token used to authorize API requests.</summary>
     AccessToken,
+    /// <summary>A long-lived token used to obtain new access tokens.</summary>
     RefreshToken,
+    /// <summary>A short-lived token used to confirm a user's email/account.</summary>
     ConfirmationToken,
 }
 
+/// <summary>
+/// Represents the result of successfully validating a token.
+/// </summary>
+/// <param name="UserId">The unique identifier of the user the token belongs to.</param>
+/// <param name="Username">The username extracted from the token's claims.</param>
+/// <param name="Principal">The <see cref="ClaimsPrincipal"/> produced from the validated token.</param>
 public record ValidatedToken(Guid UserId, string Username, ClaimsPrincipal Principal);
 
+/// <summary>
+/// Represents the result of refreshing a user's session.
+/// </summary>
+/// <param name="UserAccount">The user account associated with the refreshed session.</param>
+/// <param name="RefreshToken">The newly issued refresh token.</param>
+/// <param name="AccessToken">The newly issued access token.</param>
 public record RefreshTokenResult(
     UserAccount UserAccount,
     string RefreshToken,
     string AccessToken
 );
 
+/// <summary>
+/// Defines the expiration windows, in hours, for each type of token issued by <see cref="ITokenService"/>.
+/// </summary>
 public static class TokenServiceExpirationHours
 {
+    /// <summary>The expiration window, in hours, for access tokens.</summary>
     public const double AccessTokenHours = 1;
+    /// <summary>The expiration window, in hours, for refresh tokens (21 days).</summary>
     public const double RefreshTokenHours = 504; // 21 days
+    /// <summary>The expiration window, in hours, for confirmation tokens (30 minutes).</summary>
     public const double ConfirmationTokenHours = 0.5; // 30 minutes
 }
 
+/// <summary>
+/// Defines operations for generating and validating JWTs used for access, refresh, and account confirmation.
+/// </summary>
 public interface ITokenService
 {
+    /// <summary>
+    /// Generates a new access token for the given user.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed access token string.</returns>
     string GenerateAccessToken(UserAccount user);
+
+    /// <summary>
+    /// Generates a new refresh token for the given user.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed refresh token string.</returns>
     string GenerateRefreshToken(UserAccount user);
+
+    /// <summary>
+    /// Generates a new confirmation token for the given user.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed confirmation token string.</returns>
     string GenerateConfirmationToken(UserAccount user);
+
+    /// <summary>
+    /// Generates a token of the type specified by <typeparamref name="T"/>, which must be <see cref="TokenType"/>.
+    /// </summary>
+    /// <typeparam name="T">The enum type identifying which kind of token to generate. Must be <see cref="TokenType"/>.</typeparam>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed token string corresponding to the requested token type.</returns>
     string GenerateToken<T>(UserAccount user) where T : struct, Enum;
+
+    /// <summary>
+    /// Validates an access token.
+    /// </summary>
+    /// <param name="token">The access token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
     Task<ValidatedToken> ValidateAccessTokenAsync(string token);
+
+    /// <summary>
+    /// Validates a refresh token.
+    /// </summary>
+    /// <param name="token">The refresh token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
     Task<ValidatedToken> ValidateRefreshTokenAsync(string token);
+
+    /// <summary>
+    /// Validates a confirmation token.
+    /// </summary>
+    /// <param name="token">The confirmation token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
     Task<ValidatedToken> ValidateConfirmationTokenAsync(string token);
+
+    /// <summary>
+    /// Validates a refresh token and issues a new access/refresh token pair for the associated user.
+    /// </summary>
+    /// <param name="refreshTokenString">The refresh token string to validate and exchange.</param>
+    /// <returns>A <see cref="RefreshTokenResult"/> containing the user and newly issued tokens.</returns>
     Task<RefreshTokenResult> RefreshTokenAsync(string refreshTokenString);
 }
 
+/// <summary>
+/// Default implementation of <see cref="ITokenService"/> that generates and validates JWTs
+/// for access, refresh, and confirmation flows using secrets read from environment variables.
+/// </summary>
 public class TokenService : ITokenService
 {
     private readonly ITokenInfrastructure _tokenInfrastructure;
@@ -50,6 +129,16 @@ public class TokenService : ITokenService
     private readonly string _refreshTokenSecret;
     private readonly string _confirmationTokenSecret;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="TokenService"/>, loading the access, refresh, and
+    /// confirmation token signing secrets from environment variables.
+    /// </summary>
+    /// <param name="tokenInfrastructure">The infrastructure component used to generate and validate JWTs.</param>
+    /// <param name="authRepository">Repository used to look up user accounts during token refresh.</param>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when any of the <c>ACCESS_TOKEN_SECRET</c>, <c>REFRESH_TOKEN_SECRET</c>, or
+    /// <c>CONFIRMATION_TOKEN_SECRET</c> environment variables are not set.
+    /// </exception>
     public TokenService(
         ITokenInfrastructure tokenInfrastructure,
         IAuthRepository authRepository
@@ -68,24 +157,53 @@ public class TokenService : ITokenService
             ?? throw new InvalidOperationException("CONFIRMATION_TOKEN_SECRET environment variable is not set");
     }
 
+    /// <summary>
+    /// Generates an access token for the given user, signed with the access token secret and
+    /// expiring after <see cref="TokenServiceExpirationHours.AccessTokenHours"/> hours.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed access token string.</returns>
     public string GenerateAccessToken(UserAccount user)
     {
         var expiresAt = DateTime.UtcNow.AddHours(TokenServiceExpirationHours.AccessTokenHours);
         return _tokenInfrastructure.GenerateJwt(user.UserAccountId, user.Username, expiresAt, _accessTokenSecret);
     }
 
+    /// <summary>
+    /// Generates a refresh token for the given user, signed with the refresh token secret and
+    /// expiring after <see cref="TokenServiceExpirationHours.RefreshTokenHours"/> hours.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed refresh token string.</returns>
     public string GenerateRefreshToken(UserAccount user)
     {
         var expiresAt = DateTime.UtcNow.AddHours(TokenServiceExpirationHours.RefreshTokenHours);
         return _tokenInfrastructure.GenerateJwt(user.UserAccountId, user.Username, expiresAt, _refreshTokenSecret);
     }
 
+    /// <summary>
+    /// Generates a confirmation token for the given user, signed with the confirmation token secret and
+    /// expiring after <see cref="TokenServiceExpirationHours.ConfirmationTokenHours"/> hours.
+    /// </summary>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed confirmation token string.</returns>
     public string GenerateConfirmationToken(UserAccount user)
     {
         var expiresAt = DateTime.UtcNow.AddHours(TokenServiceExpirationHours.ConfirmationTokenHours);
         return _tokenInfrastructure.GenerateJwt(user.UserAccountId, user.Username, expiresAt, _confirmationTokenSecret);
     }
 
+    /// <summary>
+    /// Generates a token of the kind specified by <typeparamref name="T"/>, dispatching to
+    /// <see cref="GenerateAccessToken"/>, <see cref="GenerateRefreshToken"/>, or
+    /// <see cref="GenerateConfirmationToken"/> based on the corresponding <see cref="TokenType"/> value.
+    /// </summary>
+    /// <typeparam name="T">The enum type identifying which kind of token to generate. Must be <see cref="TokenType"/>.</typeparam>
+    /// <param name="user">The user account to generate the token for.</param>
+    /// <returns>The signed token string corresponding to the requested token type.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <typeparamref name="T"/> is not <see cref="TokenType"/> or does not resolve to a known token type.
+    /// </exception>
     public string GenerateToken<T>(UserAccount user) where T : struct, Enum
     {
         if (typeof(T) != typeof(TokenType))
@@ -105,15 +223,51 @@ public class TokenService : ITokenService
         };
     }
 
+    /// <summary>
+    /// Validates an access token against the access token secret.
+    /// </summary>
+    /// <param name="token">The access token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     public async Task<ValidatedToken> ValidateAccessTokenAsync(string token)
         => await ValidateTokenInternalAsync(token, _accessTokenSecret, "access");
 
+    /// <summary>
+    /// Validates a refresh token against the refresh token secret.
+    /// </summary>
+    /// <param name="token">The refresh token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     public async Task<ValidatedToken> ValidateRefreshTokenAsync(string token)
         => await ValidateTokenInternalAsync(token, _refreshTokenSecret, "refresh");
 
+    /// <summary>
+    /// Validates a confirmation token against the confirmation token secret.
+    /// </summary>
+    /// <param name="token">The confirmation token string to validate.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when the token is missing required claims, has a malformed user ID, or otherwise fails validation.
+    /// </exception>
     public async Task<ValidatedToken> ValidateConfirmationTokenAsync(string token)
         => await ValidateTokenInternalAsync(token, _confirmationTokenSecret, "confirmation");
 
+    /// <summary>
+    /// Performs the shared validation logic for access, refresh, and confirmation tokens:
+    /// validates the JWT signature/expiration, then extracts and parses the user ID and username claims.
+    /// </summary>
+    /// <param name="token">The token string to validate.</param>
+    /// <param name="secret">The secret key to validate the token's signature against.</param>
+    /// <param name="tokenType">A human-readable label (e.g. "access", "refresh", "confirmation") used in error messages.</param>
+    /// <returns>A <see cref="ValidatedToken"/> describing the token's claims.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when required claims are missing, the user ID claim is not a valid <see cref="Guid"/>,
+    /// or the underlying token validation fails for any other reason (e.g. expired or invalid signature).
+    /// </exception>
     private async Task<ValidatedToken> ValidateTokenInternalAsync(string token, string secret, string tokenType)
     {
         try
@@ -141,6 +295,15 @@ public class TokenService : ITokenService
         }
     }
 
+    /// <summary>
+    /// Validates the given refresh token, looks up the associated user, and issues a fresh
+    /// access/refresh token pair.
+    /// </summary>
+    /// <param name="refreshTokenString">The refresh token string to validate and exchange.</param>
+    /// <returns>A <see cref="RefreshTokenResult"/> containing the user and newly issued tokens.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    /// Thrown when the refresh token is invalid, or when the user account it refers to no longer exists.
+    /// </exception>
     public async Task<RefreshTokenResult> RefreshTokenAsync(string refreshTokenString)
     {
         var validated = await ValidateRefreshTokenAsync(refreshTokenString);

web/backend/Service/Service.Auth/LoginService.cs

@@ -6,12 +6,28 @@ using Infrastructure.Repository.Auth;
 namespace Service.Auth;
 
 
+/// <summary>
+/// Handles authenticating users by verifying their credentials and issuing access/refresh tokens.
+/// </summary>
+/// <param name="authRepo">Repository used to look up user accounts and their active credentials.</param>
+/// <param name="passwordInfrastructure">Infrastructure component used to verify a plain-text password against a stored hash.</param>
+/// <param name="tokenService">Service used to generate access and refresh tokens for an authenticated user.</param>
 public class LoginService(
     IAuthRepository authRepo,
     IPasswordInfrastructure passwordInfrastructure,
     ITokenService tokenService
 ) : ILoginService
 {
+    /// <summary>
+    /// Authenticates a user by username and password, issuing a new access and refresh token on success.
+    /// </summary>
+    /// <param name="username">The username of the account to authenticate.</param>
+    /// <param name="password">The plain-text password to verify against the stored credential.</param>
+    /// <returns>A <see cref="LoginServiceReturn"/> containing the authenticated user and issued tokens.</returns>
+    /// <exception cref="Domain.Exceptions.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<LoginServiceReturn> LoginAsync(
         string username,
         string password

web/backend/Service/Service.Auth/RegisterService.cs

@@ -9,6 +9,14 @@ using Service.Emails;
 
 namespace Service.Auth;
 
+/// <summary>
+/// Handles registration of new user accounts, including uniqueness validation, password hashing,
+/// token issuance, and sending the registration confirmation email.
+/// </summary>
+/// <param name="authRepo">Repository used to check for existing users and persist the new account.</param>
+/// <param name="passwordInfrastructure">Infrastructure component used to hash the user's plain-text password.</param>
+/// <param name="tokenService">Service used to generate access, refresh, and confirmation tokens.</param>
+/// <param name="emailService">Service used to send the registration confirmation email.</param>
 public class RegisterService(
     IAuthRepository authRepo,
     IPasswordInfrastructure passwordInfrastructure,
@@ -16,6 +24,13 @@ public class RegisterService(
     IEmailService emailService
 ) : IRegisterService
 {
+    /// <summary>
+    /// Verifies that no existing user account has the same username or email as the given account.
+    /// </summary>
+    /// <param name="userAccount">The candidate user account whose username and email should be checked for uniqueness.</param>
+    /// <exception cref="Domain.Exceptions.ConflictException">
+    /// Thrown when an existing account already has the same username or email address.
+    /// </exception>
     private async Task ValidateUserDoesNotExist(UserAccount userAccount)
     {
         // Check if user already exists
@@ -32,6 +47,21 @@ public class RegisterService(
         }
     }
 
+    /// <summary>
+    /// Registers a new user account: validates uniqueness, hashes the password, persists the account,
+    /// issues access/refresh/confirmation tokens, and attempts to send the registration confirmation email.
+    /// </summary>
+    /// <param name="userAccount">The user account details to register.</param>
+    /// <param name="password">The plain-text password to hash and store for the new account.</param>
+    /// <returns>
+    /// A <see cref="RegisterServiceReturn"/> describing the outcome. If token generation fails, the
+    /// returned value has <see cref="RegisterServiceReturn.IsAuthenticated"/> set to <c>false</c> and no tokens.
+    /// Otherwise tokens are populated and <see cref="RegisterServiceReturn.EmailSent"/> reflects whether the
+    /// confirmation email was sent successfully (failures to send the email are swallowed and do not fail registration).
+    /// </returns>
+    /// <exception cref="Domain.Exceptions.ConflictException">
+    /// Thrown when an existing account already has the same username or email address.
+    /// </exception>
     public async Task<RegisterServiceReturn> RegisterAsync(
         UserAccount userAccount,
         string password