add xmldoc comments

web/backend/Infrastructure/Infrastructure.PasswordHashing/Argon2Infrastructure.cs

@@ -4,6 +4,9 @@ using Konscious.Security.Cryptography;
 
 namespace Infrastructure.PasswordHashing;
 
+/// <summary>
+/// Hashes and verifies passwords using the Argon2id algorithm via Konscious.Security.Cryptography.
+/// </summary>
 public class Argon2Infrastructure : IPasswordInfrastructure
 {
     private const int SaltSize = 16; // 128-bit
@@ -11,6 +14,16 @@ public class Argon2Infrastructure : IPasswordInfrastructure
     private const int ArgonIterations = 4;
     private const int ArgonMemoryKb = 65536; // 64MB
 
+    /// <summary>
+    /// Hashes a plaintext password using Argon2id with a newly generated 128-bit cryptographically
+    /// random salt, 4 iterations, 64MB of memory, and a degree of parallelism equal to the number of
+    /// available processors (minimum 1).
+    /// </summary>
+    /// <param name="password">The plaintext password to hash.</param>
+    /// <returns>
+    /// A string of the form <c>"{base64Salt}:{base64Hash}"</c> containing the salt and the resulting
+    /// 256-bit hash, suitable for storage and later verification.
+    /// </returns>
     public string Hash(string password)
     {
         var salt = RandomNumberGenerator.GetBytes(SaltSize);
@@ -26,6 +39,20 @@ public class Argon2Infrastructure : IPasswordInfrastructure
         return $"{Convert.ToBase64String(salt)}:{Convert.ToBase64String(hash)}";
     }
 
+    /// <summary>
+    /// Verifies a plaintext password against a stored salt/hash string by recomputing the Argon2id
+    /// hash with the extracted salt and comparing it to the stored hash using a fixed-time comparison
+    /// to mitigate timing attacks.
+    /// </summary>
+    /// <param name="password">The plaintext password to verify.</param>
+    /// <param name="stored">
+    /// The stored string of the form <c>"{base64Salt}:{base64Hash}"</c> previously produced by <see cref="Hash"/>.
+    /// </param>
+    /// <returns>
+    /// <c>true</c> if the password matches the stored hash; <c>false</c> if it does not match, the stored
+    /// string is malformed (e.g. not in the expected two-part format, or not valid base64), or any other
+    /// error occurs while verifying.
+    /// </returns>
     public bool Verify(string password, string stored)
     {
         try

web/backend/Infrastructure/Infrastructure.PasswordHashing/IPasswordInfrastructure.cs

@@ -1,7 +1,22 @@
 namespace Infrastructure.PasswordHashing;
 
+/// <summary>
+/// Service for hashing and verifying user passwords.
+/// </summary>
 public interface IPasswordInfrastructure
 {
+    /// <summary>
+    /// Hashes a plaintext password, generating a new random salt.
+    /// </summary>
+    /// <param name="password">The plaintext password to hash.</param>
+    /// <returns>A string encoding both the salt and the resulting hash, suitable for storage.</returns>
     public string Hash(string password);
+
+    /// <summary>
+    /// Verifies a plaintext password against a previously stored hash.
+    /// </summary>
+    /// <param name="password">The plaintext password to verify.</param>
+    /// <param name="stored">The stored salt/hash string previously produced by <see cref="Hash"/>.</param>
+    /// <returns><c>true</c> if the password matches the stored hash; otherwise <c>false</c>.</returns>
     public bool Verify(string password, string stored);
 }