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

@@ -6,8 +6,24 @@ namespace EnvelopeGenerator.API.Extensions
     /// <summary>
     /// Provides extension methods for extracting user information from a <see cref="ClaimsPrincipal"/>.
     /// </summary>
-    public static class ControllerExtensions
+    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>