add xmldoc comments

web/backend/Infrastructure/Infrastructure.Jwt/ITokenInfrastructure.cs

@@ -2,8 +2,19 @@ using System.Security.Claims;
 
 namespace Infrastructure.Jwt;
 
+/// <summary>
+/// Service for generating and validating JSON Web Tokens (JWTs) used for authentication.
+/// </summary>
 public interface ITokenInfrastructure
 {
+    /// <summary>
+    /// Generates a signed JWT for the given user.
+    /// </summary>
+    /// <param name="userId">The unique identifier of the user the token is issued for.</param>
+    /// <param name="username">The username of the user, included as a claim.</param>
+    /// <param name="expiry">The date and time at which the token expires.</param>
+    /// <param name="secret">The symmetric secret used to sign the token.</param>
+    /// <returns>The serialized, signed JWT string.</returns>
     string GenerateJwt(
         Guid userId,
         string username,
@@ -11,5 +22,12 @@ public interface ITokenInfrastructure
         string secret
     );
 
+    /// <summary>
+    /// Validates a JWT and returns the resulting claims principal.
+    /// </summary>
+    /// <param name="token">The JWT string to validate.</param>
+    /// <param name="secret">The symmetric secret used to verify the token's signature.</param>
+    /// <returns>A <see cref="ClaimsPrincipal"/> representing the validated token's claims.</returns>
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">Thrown when the token is invalid, expired, or fails validation.</exception>
     Task<ClaimsPrincipal> ValidateJwtAsync(string token, string secret);
 }

web/backend/Infrastructure/Infrastructure.Jwt/JwtInfrastructure.cs

@@ -7,8 +7,24 @@ using Domain.Exceptions;
 
 namespace Infrastructure.Jwt;
 
+/// <summary>
+/// Generates and validates HMAC-SHA256 signed JWTs using <see cref="JsonWebTokenHandler"/>.
+/// </summary>
 public class JwtInfrastructure : ITokenInfrastructure
 {
+    /// <summary>
+    /// Generates a signed JWT containing the user's ID, username, issued-at time, expiry time,
+    /// and a unique token identifier (JTI), signed using HMAC-SHA256 with the provided secret.
+    /// </summary>
+    /// <remarks>
+    /// Sets the following registered claims: <c>sub</c> (userId), <c>unique_name</c> (username),
+    /// <c>iat</c> (current UTC time), <c>exp</c> (expiry), and <c>jti</c> (a newly generated GUID).
+    /// </remarks>
+    /// <param name="userId">The unique identifier of the user the token is issued for.</param>
+    /// <param name="username">The username of the user, included as a claim.</param>
+    /// <param name="expiry">The date and time at which the token expires.</param>
+    /// <param name="secret">The symmetric secret used to sign the token (encoded as UTF-8 bytes).</param>
+    /// <returns>The serialized, signed JWT string.</returns>
     public string GenerateJwt(
         Guid userId,
         string username,
@@ -47,6 +63,17 @@ public class JwtInfrastructure : ITokenInfrastructure
     }
 
 
+    /// <summary>
+    /// Validates a JWT's signature and lifetime (issuer and audience validation are disabled),
+    /// using the provided secret as the HMAC-SHA256 symmetric signing key.
+    /// </summary>
+    /// <param name="token">The JWT string to validate.</param>
+    /// <param name="secret">The symmetric secret used to verify the token's signature (encoded as UTF-8 bytes).</param>
+    /// <returns>A <see cref="ClaimsPrincipal"/> wrapping the validated token's claims identity.</returns>
+    /// <exception cref="UnauthorizedException">
+    /// Thrown when the token is invalid, has no claims identity, is expired, or otherwise fails validation
+    /// (including when validation itself throws, e.g. due to a malformed token or signature mismatch).
+    /// </exception>
     public async Task<ClaimsPrincipal> ValidateJwtAsync(
         string token,
         string secret