Add "OrDefault" methods for user claim retrieval

Introduce new extension methods in `ControllerExtensions` to safely extract user information from a `ClaimsPrincipal`. Updated methods for ID, username, surname, given name, and email to return `null` if not found, enhancing flexibility. Updated `EnvelopeReceiverController` to utilize these new methods for improved handling of absent user claims.

EnvelopeGenerator.GeneratorAPI/Controllers/ControllerExtensions.cs

@@ -3,26 +3,60 @@ using System.Security.Claims;
 
 namespace EnvelopeGenerator.GeneratorAPI.Controllers
 {
+    /// <summary>
+    /// Provides extension methods for extracting user information from a <see cref="ClaimsPrincipal"/>.
+    /// </summary>
     public static class ControllerExtensions
     {
+        /// <summary>
+        /// Attempts to retrieve the user's ID from the claims. Returns null if the ID is not found or invalid.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The user's ID as an integer, or null if not found or invalid.</returns>
         public static int? GetIdOrDefault(this ClaimsPrincipal user)
             => int.TryParse(user.FindFirstValue(ClaimTypes.NameIdentifier) ?? user.FindFirstValue("sub"), out int result)
                 ? result : null;
 
+        /// <summary>
+        /// Retrieves the user's ID from the claims. Throws an exception if the ID is missing or invalid.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The user's ID as an integer.</returns>
+        /// <exception cref="InvalidOperationException">Thrown if the user ID claim is missing or invalid.</exception>
         public static int GetId(this ClaimsPrincipal user)
             => user.GetIdOrDefault()
             ?? throw new InvalidOperationException("User ID claim is missing or invalid. This may indicate a misconfigured or forged JWT token.");
 
-        public static string? GetUsername(this ClaimsPrincipal user)
+        /// <summary>
+        /// Retrieves the username from the claims, if available.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The username as a string, or null if not found.</returns>
+        public static string? GetUsernameOrDefault(this ClaimsPrincipal user)
             => user.FindFirst(ClaimTypes.Name)?.Value;
-        
+
-        public static string? GetName(this ClaimsPrincipal user)
+        /// <summary>
+        /// Retrieves the user's surname (last name) from the claims, if available.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The surname as a string, or null if not found.</returns>
+        public static string? GetNameOrDefault(this ClaimsPrincipal user)
             => user.FindFirst(ClaimTypes.Surname)?.Value;
-        
+
-        public static string? GetPrename(this ClaimsPrincipal user)
+        /// <summary>
+        /// Retrieves the user's given name (first name) from the claims, if available.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The given name as a string, or null if not found.</returns>
+        public static string? GetPrenameOrDefault(this ClaimsPrincipal user)
             => user.FindFirst(ClaimTypes.GivenName)?.Value;
-        
+
-        public static string? GetEmail(this ClaimsPrincipal user)
+        /// <summary>
+        /// Retrieves the user's email address from the claims, if available.
+        /// </summary>
+        /// <param name="user">The <see cref="ClaimsPrincipal"/> representing the user.</param>
+        /// <returns>The email address as a string, or null if not found.</returns>
+        public static string? GetEmailOrDefault(this ClaimsPrincipal user)
             => user.FindFirst(ClaimTypes.Email)?.Value;
     }
 }

EnvelopeGenerator.GeneratorAPI/Controllers/EnvelopeReceiverController.cs

@@ -86,12 +86,12 @@ public class EnvelopeReceiverController : ControllerBase
     {
         try
         {
-            var username = User.GetUsername();
+            var username = User.GetUsernameOrDefault();
 
             if (username is null)
             {
                 _logger.LogError(@"Envelope Receiver dto cannot be sent because username claim is null. Potential authentication and authorization error. The value of other claims are [id: {id}], [username: {username}], [name: {name}], [prename: {prename}], [email: {email}].",
-                    User.GetId(), User.GetUsername(), User.GetName(), User.GetPrename(), User.GetEmail());
+                    User.GetId(), User.GetUsernameOrDefault(), User.GetNameOrDefault(), User.GetPrenameOrDefault(), User.GetEmailOrDefault());
                 return StatusCode(StatusCodes.Status500InternalServerError);
             }