Refactor ControllerExtensions to SenderClaimExtensions

Renamed the extension class for claims handling and added a private GetRequiredClaimOfSender method for ClaimsPrincipal. This method throws a detailed exception when a required claim is missing, improving error reporting and debugging.

EnvelopeGenerator.API/Extensions/SenderClaimExtensions.cs

@@ -0,0 +1,78 @@
+using Microsoft.AspNetCore.Mvc;
+using System.Security.Claims;
+
+namespace EnvelopeGenerator.API.Extensions
+{
+    /// <summary>
+    /// Provides extension methods for extracting user information from a <see cref="ClaimsPrincipal"/>.
+    /// </summary>
+    public static class SenderClaimExtensions
+    {
+        private static string GetRequiredClaimOfSender(this ClaimsPrincipal user, string claimType)
+        {
+            var value = user.FindFirstValue(claimType);
+            if (value is not null)
+            {
+                return value;
+            }
+
+            var identity = user.Identity;
+            var principalName = identity?.Name ?? "(anonymous)";
+            var authType = identity?.AuthenticationType ?? "(none)";
+            var availableClaims = string.Join(", ", user.Claims.Select(c => $"{c.Type}={c.Value}"));
+            var message = $"Required claim '{claimType}' is missing for user '{principalName}' (auth: {authType}). Available claims: [{availableClaims}].";
+            throw new InvalidOperationException(message);
+        }
+
+        /// <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.");
+
+        /// <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;
+
+        /// <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;
+
+        /// <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;
+
+        /// <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;
+    }
+}