Merge pull request 'Refactored idempotency check to observe completed status' (#116) from payments into master

Reviewed-on: #116

LiteCharms.Features.MidrandBooks.Seed/LiteCharms.Features.MidrandBooks.Seed.csproj

@@ -11,7 +11,7 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>
     <PackageReference Include="Bogus" Version="35.6.5" />
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
@@ -116,8 +116,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.7" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.4" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.MidrandBooks/Extensions/Shop.cs

@@ -1,11 +1,12 @@
 using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Browser;
 using LiteCharms.Features.MidrandBooks.Abstractions;
 
 namespace LiteCharms.Features.MidrandBooks.Extensions;
 
 public static class Shop
 {
-    public static IServiceCollection AddShopServices(this IServiceCollection services)
+    public static IServiceCollection AddShopServices(this IServiceCollection services, bool includeLocalStorage = false)
     {
         var serviceType = typeof(IService);
 
@@ -19,6 +20,9 @@ public static class Shop
 
         foreach (var coreImplementation in coreImplementations) services.AddScoped(coreImplementation);
 
+        if (includeLocalStorage)
+            services.AddScoped<LocalStorageService>();
+
         return services;
     }
 }

LiteCharms.Features.MidrandBooks/LiteCharms.Features.MidrandBooks.csproj

@@ -32,7 +32,7 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>
     <PackageReference Include="Humanizer" Version="3.0.10" />
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
@@ -136,8 +136,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.7" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.4" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->
@@ -148,6 +148,7 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="Microsoft.AspNetCore.Http" />
     <Using Include="System.Net.Sockets" />
     <Using Include="System.Text.RegularExpressions" />
     <Using Include="System.Web" />

LiteCharms.Features.MidrandBooks/Payments/CartService.cs

@@ -1,5 +1,4 @@
-using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Browser;
+using LiteCharms.Features.Browser;
 using LiteCharms.Features.Hasher;
 using LiteCharms.Features.MidrandBooks.Authors.Models;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
@@ -7,7 +6,7 @@ using LiteCharms.Features.MidrandBooks.Products.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Payments;
 
-public sealed class CartService(LocalStorageService localStorage) : IService
+public sealed class CartService(LocalStorageService localStorage)
 {
     private readonly string CartStorageKey = HashService.ToMd5Hash(nameof(Cart)).Value;
 

LiteCharms.Features.MidrandBooks/Payments/Events/Handlers/PayfastPaymentConfirmationReceivedEventHandler.cs

@@ -1,17 +1,13 @@
-using LiteCharms.Features.Api.Configuration;
-using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Mediator;
 using LiteCharms.Features.MidrandBooks.Orders;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Payments.Events.Handlers;
 
-public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, 
-    IOptions<PayfastSettings> payfastOptions, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) :
+public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) :
     INotificationHandler<PayfastPaymentConfirmationReceivedEvent>
 {
-    private readonly PayfastSettings pasfastSettings = payfastOptions.Value;
-
     public async ValueTask Handle(PayfastPaymentConfirmationReceivedEvent notification, CancellationToken cancellationToken)
     {
         using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(PayfastPaymentConfirmationReceivedEvent).Name}");
@@ -23,83 +19,34 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
         var paymentService = scope.ServiceProvider.GetRequiredService<PaymentService>();
         var payfastService = scope.ServiceProvider.GetRequiredService<PayfastService>();
 
-        var payload = notification.Payload ?? throw new Exception("Payload metadata context context is null.");
+        var payload = notification.Payload ?? throw new Exception("Payload metadata context is null.");
 
-        var dict = payload.ToParamDictionary();
-        var localSignature = PayfastService.GenerateSignature(dict, pasfastSettings.Passphrase);
+        var hashResult = hashService.DecodeLongIdHash(payload.MerchantPaymentId!);
+        if (hashResult.IsFailed) throw new Exception("Failed to decode application tracking hash key identifier.");
 
-        if (localSignature.IsFailed)
-            throw new Exception("Failed to generate local signature for incoming webhook payload.");
+        var orderResult = await orderService.GetOrderAsync(hashResult.Value, cancellationToken);
+        if (orderResult.IsFailed) throw new Exception("Target system order entity context cannot be traced.");
 
-        if (!string.Equals(localSignature.Value, payload.Signature, StringComparison.OrdinalIgnoreCase))
+        var paymentResult = await paymentService.GetOrderPaymentAsync(orderResult.Value.Id, cancellationToken);
+        if (paymentResult.IsFailed) throw new Exception("Target payment ledger entity cannot be resolved.");
+
+        var isAlreadyProcessed = await paymentService.HasLedgerEntryAsync(orderResult.Value.Id, paymentResult.Value.Id, cancellationToken);
+        if (isAlreadyProcessed.Value)
         {
-            logger.LogCritical("Incoming webhook signature verification failed. Possible payload tampering.");
+            logger.LogWarning("Webhook reference token '{Ref}' already verified. Skipping processing routines.", payload.MerchantPaymentId);
 
             return;
         }
 
-        var hashResult = hashService.DecodeLongIdHash(payload.MerchantPaymentId!);
-
-        if (hashResult.IsFailed) throw new Exception("Failed to decode application tracking hash key identifier.");
-
-        var orderResult = await orderService.GetOrderAsync(hashResult.Value, cancellationToken);
-
-        if (orderResult.IsFailed) throw new Exception("Target system order entity context cannot be traced.");
-
-        var paymentResult = await paymentService.GetOrderPaymentAsync(orderResult.Value.Id, cancellationToken);
-
-        if (paymentResult.IsFailed) throw new Exception("Target payment ledger entity cannot be resolved.");
+        var isAmountValid = payfastService.ValidatePaymentAmount(orderResult.Value.Total, payload.AmountGross);
+        if (!isAmountValid.Value)
+            throw new Exception("Security validation exception: Transaction cost variance bounds breached (Price Tampering Detected).");
 
         decimal.TryParse(payload.AmountGross, CultureInfo.InvariantCulture, out var gross);
         decimal.TryParse(payload.AmountFee, CultureInfo.InvariantCulture, out var fee);
         decimal.TryParse(payload.AmountNet, CultureInfo.InvariantCulture, out var net);
         string status = payload.PaymentStatus ?? "UNKNOWN";
 
-        var isAlreadyProcessed = await paymentService.HasLedgerEntryAsync(orderResult.Value.Id, paymentResult.Value.Id, cancellationToken);
-
-        if (isAlreadyProcessed.Value)
-        {
-            logger.LogWarning("Webhook reference token '{Ref}' already verified. Skipping validation routines.", payload.MerchantPaymentId);
-
-            return;
-        }
-
-        if (notification.PerformBackgroundChecks)
-        {
-            var isHostValid = await payfastService.ValidateReferrerIpAsync(notification.RemoteIpAddress!, notification.AllowLoopback, cancellationToken);
-
-            if (isHostValid.IsFailed)
-                throw new Exception("Security validation exception: Webhook packet source address failed cluster validation checks.");
-
-            if (!isHostValid.Value)
-                throw new Exception("Security validation exception: Webhook packet source address failed cluster validation checks.");
-
-            var isAmountValid = payfastService.ValidatePaymentAmount(orderResult.Value.Total, payload.AmountGross);
-
-            if (!isAmountValid.Value)
-                throw new Exception("Security validation exception: Transaction cost variance bounds breached.");
-
-            var paramList = new List<string>();
-
-            foreach (var kvp in dict)
-            {
-                if (!string.IsNullOrEmpty(kvp.Value))
-                {
-                    string encoded = HttpUtility.UrlEncode(kvp.Value.Trim());
-
-                    string safeValue = PayfastService.PercentEncodingRegex.Replace(encoded, m => m.Value.ToLowerInvariant());
-                    paramList.Add($"{kvp.Key}={safeValue}");
-                }
-            }
-
-            string rawParamString = string.Join("&", paramList);
-
-            var serverConfirmation = await payfastService.ValidateServerConfirmationAsync(rawParamString, isSandbox: true, cancellationToken);
-
-            if (serverConfirmation.IsFailed)
-                throw new Exception("Security validation exception: Payfast central handshake server rejected payload legitimacy.");
-        }
-
         await payfastService.WriteLedgerEntryAsync(new CreateGatewayLedgerEntry
         {
             OrderId = orderResult.Value.Id,
@@ -124,31 +71,23 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
                 CustomerId = orderResult.Value.CustomerId,
             }, cancellationToken);
 
-            if (ledgerWriteResult.IsFailed)
-                throw new Exception("Failed to write ledger entry for payment confirmation.");
+            if (ledgerWriteResult.IsFailed) throw new Exception("Failed to write ledger entry for payment confirmation.");
 
             var completePaymentResult = await paymentService.CompletePaymentAsync(paymentResult.Value.Id, PaymentStatuses.Paid, cancellationToken);
-
-            if (completePaymentResult.IsFailed)
-                throw new Exception("Failed to update payment status to 'Paid' for payment confirmation.");
+            if (completePaymentResult.IsFailed) throw new Exception("Failed to update payment status to 'Paid'.");
 
             var updateOrderResult = await orderService.UpdateOrderStatusAsync(orderResult.Value.Id, OrderStatus.Completed, cancellationToken);
-
-            if (updateOrderResult.IsFailed)
-                throw new Exception("Failed to update order status to 'Completed' for payment confirmation.");
+            if (updateOrderResult.IsFailed) throw new Exception("Failed to update order status to 'Completed'.");
 
             logger.LogInformation("Order payment verified secure and cleared successfully.");
         }
         else
         {
-            LedgerStatuses ledgerStatus;
+            LedgerStatuses ledgerStatus = status.Equals("CANCELLED", StringComparison.OrdinalIgnoreCase)
+                ? LedgerStatuses.Cancelled
+                : LedgerStatuses.Failed;
 
-            if (status.Equals("CANCELLED", StringComparison.OrdinalIgnoreCase))
-                ledgerStatus = LedgerStatuses.Cancelled;
-            else
-                ledgerStatus = LedgerStatuses.Failed;
-
-            var ledgerWriteResult = await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
+            await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
             {
                 OrderId = orderResult.Value.Id,
                 PaymentId = paymentResult.Value.Id,
@@ -157,8 +96,9 @@ public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvi
                 CustomerId = orderResult.Value.CustomerId,
             }, cancellationToken);
 
-            logger.LogInformation("Webhook validation pipeline passed checks successfully, logged entry to ledger with status: {Status}", status);
+            logger.LogInformation("Webhook pipeline logged non-success entry to ledger with status: {Status}", status);
         }
+
         activity?.SetStatus(ActivityStatusCode.Ok);
     }
 }

LiteCharms.Features.MidrandBooks/Payments/PayfastService.cs

@@ -48,6 +48,39 @@ public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbConte
         }
     }
 
+    public static bool VerifyIncomingSignatureFromForm(IFormCollection formCollection, string passphrase)
+    {
+        var sortedFields = new Dictionary<string, string>(StringComparer.Ordinal);
+
+        foreach (var field in formCollection)
+        {
+            sortedFields.Add(field.Key, field.Value.ToString());
+        }
+
+        if (!sortedFields.TryGetValue("signature", out var incomingSignature)) return false;
+
+        var stringBuilder = new StringBuilder();
+
+        foreach (var key in sortedFields.Keys)
+        {
+            if (key.Equals("signature", StringComparison.OrdinalIgnoreCase)) continue;
+
+            string encodedVal = HttpUtility.UrlEncode(sortedFields[key].Trim());
+            string cleanVal = PercentEncodingRegex.Replace(encodedVal, m => m.Value.ToUpperInvariant());
+
+            stringBuilder.Append($"{key}={cleanVal}&");
+        }
+
+        string encodedPassphrase = HttpUtility.UrlEncode(passphrase.Trim());
+        string safePassphrase = PercentEncodingRegex.Replace(encodedPassphrase, m => m.Value.ToUpperInvariant());
+
+        stringBuilder.Append($"passphrase={safePassphrase}");
+
+        string generatedSignature = HashService.ToMd5Hash(stringBuilder.ToString()).Value;
+
+        return incomingSignature.Equals(generatedSignature, StringComparison.OrdinalIgnoreCase);
+    }
+
     public async ValueTask<Result<bool>> ValidateReferrerIpAsync(string remoteIpAddress, bool allowLoopback = false, CancellationToken cancellationToken = default)
     {
         if(payfastOptions.Value?.ValidHosts?.Length == 0)
@@ -147,38 +180,66 @@ public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbConte
     {
         var pfOutput = new StringBuilder();
 
-        foreach (var kvp in data)
+        var mandatorySequence = GetPayfastMandatoryFieldSequence();
+
+        foreach (string key in mandatorySequence)
         {
-            if (string.IsNullOrEmpty(kvp.Value))
-                continue;
+            if (data.TryGetValue(key, out string? rawValue) && !string.IsNullOrEmpty(rawValue))
+            {
+                string encodedVal = HttpUtility.UrlEncode(rawValue.Trim());
+                string val = PercentEncodingRegex.Replace(encodedVal, m => m.Value.ToUpperInvariant());
 
-            if (kvp.Key.Equals("signature", StringComparison.OrdinalIgnoreCase))
-                continue;
-
-            string key = kvp.Key;
-
-            // 1. Payfast requires spaces to be '+' signs. HttpUtility does this perfectly.
-            string encodedVal = HttpUtility.UrlEncode(kvp.Value.Trim());
-
-            // 2. Payfast requires all OTHER percent-encoded hex arrays to be UPPERCASE (e.g., %3A instead of %3a)
-            string val = Regex.Replace(encodedVal, "%[0-9A-Fa-f]{2}", m => m.Value.ToUpperInvariant());
-
-            pfOutput.Append($"{key}={val}&");
+                pfOutput.Append($"{key}={val}&");
+            }
         }
 
-        string getString = pfOutput.Length > 0
+        var getString = pfOutput.Length > 0
             ? pfOutput.ToString()[..^1]
             : string.Empty;
 
         if (!string.IsNullOrWhiteSpace(passPhrase))
         {
-            // Apply the exact same encoding rule to your passphrase
             string encodedPassphrase = HttpUtility.UrlEncode(passPhrase.Trim());
-            string safePassphrase = Regex.Replace(encodedPassphrase, "%[0-9A-Fa-f]{2}", m => m.Value.ToUpperInvariant());
+            string safePassphrase = PercentEncodingRegex.Replace(encodedPassphrase, m => m.Value.ToUpperInvariant());
 
             getString += $"&passphrase={safePassphrase}";
         }
 
         return HashService.ToMd5Hash(getString);
     }
+
+    private static string[] GetPayfastMandatoryFieldSequence() =>
+        [
+            "merchant_id",
+            "merchant_key",
+            "return_url",
+            "cancel_url",
+            "notify_url",
+            "name_first",
+            "name_last",
+            "email_address",
+            "cell_number",
+            "m_payment_id",
+            "amount",
+            "item_name",
+            "item_description",
+            "custom_int1",
+            "custom_int2",
+            "custom_int3",
+            "custom_int4",
+            "custom_int5",
+            "custom_str1",
+            "custom_str2",
+            "custom_str3",
+            "custom_str4",
+            "custom_str5",
+            "email_confirmation",
+            "confirmation_address",
+            "payment_method",
+            "subscription_type",
+            "billing_date",
+            "recurring_amount",
+            "frequency",
+            "cycles"
+        ];
 }

LiteCharms.Features.MidrandBooks/Payments/PaymentService.cs

@@ -123,8 +123,7 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
             await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
 
             var exists = await context.Ledger.AnyAsync(l =>
-                l.OrderId == orderId &&
-                l.PaymentId == paymentId, cancellationToken);
+                l.OrderId == orderId && l.PaymentId == paymentId && l.Status == LedgerStatuses.Completed, cancellationToken);
 
             return Result.Ok(exists);
         }
@@ -162,7 +161,8 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
                 CustomerId = request.CustomerId,
                 OrderId = request.OrderId,
                 PaymentId = request.PaymentId,
-                Status = request.Status,
+                MerchantPaymentId = request.PaymentGatewayReference,
+                Status = request.Status,                
             });
 
             return await context.SaveChangesAsync(cancellationToken) > 0

LiteCharms.Features.TechShop/LiteCharms.Features.TechShop.csproj

@@ -136,8 +136,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.7" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.4" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.Tests.Common/appsettings.json

@@ -4,8 +4,6 @@
     "ValidHosts": [
       "www.payfast.co.za",
       "sandbox.payfast.co.za",
-      "w1w.payfast.co.za",
-      "w2w.payfast.co.za",
       "ips.payfast.co.za",
       "api.payfast.co.za",
       "payment.payfast.io"

LiteCharms.Features/Api/TokenService.cs

@@ -1,11 +1,10 @@
-using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Api.Configuration;
+using LiteCharms.Features.Api.Configuration;
 using LiteCharms.Features.Api.Models;
 using LiteCharms.Features.Api.Sdk;
 
 namespace LiteCharms.Features.Api;
 
-public sealed class TokenService(IConnectApi connectApi, IOptions<LiteCharmsClientSettings> clientOptions) : IService
+public sealed class TokenService(IConnectApi connectApi, IOptions<LiteCharmsClientSettings> clientOptions)
 {
     private readonly LiteCharmsClientSettings clientSettings = clientOptions.Value;
 

LiteCharms.Features/Browser/LocalStorageService.cs

@@ -1,8 +1,6 @@
-using LiteCharms.Features.Abstractions;
+namespace LiteCharms.Features.Browser;
 
-namespace LiteCharms.Features.Browser;
-
-public sealed class LocalStorageService(ProtectedLocalStorage storage) : IService
+public sealed class LocalStorageService(ProtectedLocalStorage storage)
 {
     public async ValueTask<Result> DeleteAsync(string key)
     {

LiteCharms.Features/Extensions/Api.cs

@@ -46,6 +46,8 @@ public static class Api
                 options.Retry.BackoffType = Polly.DelayBackoffType.Exponential;
             });
 
+        services.AddScoped<TokenService>();
+
         return services;
     }
 

LiteCharms.Features/LiteCharms.Features.csproj

@@ -79,7 +79,7 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>    
     <PackageReference Include="Hashids.net" Version="1.7.0" />    
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>    
@@ -183,8 +183,8 @@
   
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.7" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.4" />
     
     <!-- global Usings -->
     <Using Include="Amazon.S3" />