From 8187924a8ced1a59ab4e8d831cf324a41f9c784d Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Fri, 30 Jan 2026 13:06:40 +0100
Subject: [PATCH] Add EnvelopeAuthExtensions for envelope claim handling

Introduces EnvelopeAuthExtensions with helper methods to retrieve envelope-specific claims from ClaimsPrincipal and to sign in envelope receivers using cookie authentication. Supports extracting envelope and receiver details via claims for authentication flows.
---
 .../Extensions/EnvelopeAuthExtensions.cs      | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 EnvelopeGenerator.GeneratorAPI/Extensions/EnvelopeAuthExtensions.cs

diff --git a/EnvelopeGenerator.GeneratorAPI/Extensions/EnvelopeAuthExtensions.cs b/EnvelopeGenerator.GeneratorAPI/Extensions/EnvelopeAuthExtensions.cs
new file mode 100644
index 00000000..48b2edb6
--- /dev/null
+++ b/EnvelopeGenerator.GeneratorAPI/Extensions/EnvelopeAuthExtensions.cs
@@ -0,0 +1,87 @@
+using System.Security.Claims;
+using EnvelopeGenerator.Application.Common.Dto.EnvelopeReceiver;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication.Cookies;
+
+namespace EnvelopeGenerator.GeneratorAPI.Extensions;
+
+/// <summary>
+/// Provides helper methods for working with envelope-specific authentication claims.
+/// </summary>
+public static class EnvelopeAuthExtensions
+{
+    /// <summary>
+    /// Retrieves a claim value by type.
+    /// </summary>
+    /// <param name="user">The current claims principal.</param>
+    /// <param name="claimType">The claim type to resolve.</param>
+    /// <returns>The claim value or null when missing.</returns>
+    public static string? GetClaimValue(this ClaimsPrincipal user, string claimType) => user.FindFirstValue(claimType);
+
+    /// <summary>
+    /// Gets the authenticated envelope UUID from the claims.
+    /// </summary>
+    public static string? GetAuthEnvelopeUuid(this ClaimsPrincipal user) => user.FindFirstValue(ClaimTypes.NameIdentifier);
+
+    /// <summary>
+    /// Gets the authenticated receiver signature from the claims.
+    /// </summary>
+    public static string? GetAuthReceiverSignature(this ClaimsPrincipal user) => user.FindFirstValue(ClaimTypes.Hash);
+
+    /// <summary>
+    /// Gets the authenticated receiver display name from the claims.
+    /// </summary>
+    public static string? GetAuthReceiverName(this ClaimsPrincipal user) => user.FindFirstValue(ClaimTypes.Name);
+
+    /// <summary>
+    /// Gets the authenticated receiver email address from the claims.
+    /// </summary>
+    public static string? GetAuthReceiverMail(this ClaimsPrincipal user) => user.FindFirstValue(ClaimTypes.Email);
+
+    /// <summary>
+    /// Gets the authenticated envelope title from the claims.
+    /// </summary>
+    public static string? GetAuthEnvelopeTitle(this ClaimsPrincipal user) => user.FindFirstValue(EnvelopeClaimTypes.Title);
+
+    /// <summary>
+    /// Gets the authenticated envelope identifier from the claims.
+    /// </summary>
+    public static int? GetAuthEnvelopeId(this ClaimsPrincipal user)
+    {
+        var envIdStr = user.FindFirstValue(EnvelopeClaimTypes.Id);
+        return int.TryParse(envIdStr, out var envId) ? envId : null;
+    }
+
+    /// <summary>
+    /// Signs in an envelope receiver using cookie authentication and attaches envelope claims.
+    /// </summary>
+    /// <param name="context">The current HTTP context.</param>
+    /// <param name="envelopeReceiver">Envelope receiver DTO to extract claims from.</param>
+    /// <param name="receiverRole">Role to attach to the authentication ticket.</param>
+    public static async Task SignInEnvelopeAsync(this HttpContext context, EnvelopeReceiverDto envelopeReceiver, string receiverRole)
+    {
+        var claims = new List<Claim>
+        {
+            new(ClaimTypes.NameIdentifier, envelopeReceiver.Envelope!.Uuid),
+            new(ClaimTypes.Hash, envelopeReceiver.Receiver!.Signature),
+            new(ClaimTypes.Name, envelopeReceiver.Name ?? string.Empty),
+            new(ClaimTypes.Email, envelopeReceiver.Receiver.EmailAddress),
+            new(EnvelopeClaimTypes.Title, envelopeReceiver.Envelope.Title),
+            new(EnvelopeClaimTypes.Id, envelopeReceiver.Envelope.Id.ToString()),
+            new(ClaimTypes.Role, receiverRole)
+        };
+
+        var claimsIdentity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
+
+        var authProperties = new AuthenticationProperties
+        {
+            AllowRefresh = false,
+            IsPersistent = false
+        };
+
+        await context.SignInAsync(
+            CookieAuthenticationDefaults.AuthenticationScheme,
+            new ClaimsPrincipal(claimsIdentity),
+            authProperties);
+    }
+}