Merge pull request 'Using IFormCollection for VerifyIncomingSignatureFromForm' (#112) from payments into master

Reviewed-on: #112

.gitignore

@@ -361,3 +361,6 @@ MigrationBackup/
 
 # Fody - auto-generated XML schema
 FodyWeavers.xsd
+/LiteCharms.Features.Tests/http/http-client.env.json
+/LiteCharms.Features.Tests/http/midrandshop-api/http-client.env.json
+/LiteCharms.Features.Tests/http/authentik/http-client.env.json

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

@@ -11,12 +11,12 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>
     <PackageReference Include="Bogus" Version="35.6.5" />
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.98">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
     <PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.5.0" />
-    <PackageReference Include="OpenTelemetry" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry" Version="1.16.0" />
     <PackageReference Include="Quartz" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins.TimeZoneConverter" Version="3.18.1" />
@@ -30,11 +30,11 @@
 
   <!-- Configuration -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Configuration" />
@@ -47,9 +47,9 @@
     <PackageReference Include="AspNetCore.HealthChecks.UI.Core" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.Data" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.InMemory.Storage" Version="9.0.0" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
@@ -58,12 +58,12 @@
 
   <!-- Open Telemetry -->
   <ItemGroup>
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.16.0" />
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.16.0" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.16.0" />
 
     <!-- Global Usings -->
     <Using Include="OpenTelemetry.Resources" />
@@ -75,13 +75,13 @@
 
   <!-- Database -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.9">
       <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.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.MidrandBooks.Seed/appsettings.json

@@ -1,6 +1,6 @@
 {
   "FeatureManagement": {
-    "CategorySeederService": true,
+    "CategorySeederService": false,
     "CustomerSeederService": false,
     "ProductsSeederService": false
   },

LiteCharms.Features.MidrandBooks.Tests/AuthorServiceFeatureTests.cs

@@ -1,7 +1,7 @@
 using LiteCharms.Features.MidrandBooks.Authors;
 using LiteCharms.Features.MidrandBooks.Authors.Models;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
 using LiteCharms.Features.Models;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/BooksServiceFeatureTests.cs

@@ -1,5 +1,5 @@
 using LiteCharms.Features.MidrandBooks.AuthorBooks;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/CategoryServiceFeatureTests.cs

@@ -1,5 +1,5 @@
 using LiteCharms.Features.MidrandBooks.Categories;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/CustomerServiceFeatureTests.cs

@@ -1,6 +1,6 @@
 using LiteCharms.Features.MidrandBooks.Customers;
 using LiteCharms.Features.MidrandBooks.Customers.Models;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

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

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>
@@ -35,19 +35,15 @@
 
   <ItemGroup>
     <ProjectReference Include="..\LiteCharms.Features.MidrandBooks\LiteCharms.Features.MidrandBooks.csproj" />
+    <ProjectReference Include="..\LiteCharms.Features.Tests.Common\LiteCharms.Features.Tests.Common.csproj" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
   </ItemGroup>
 
   <ItemGroup>
+    <Using Include="System.Net" />
     <Using Include="System.Text.Json" />
     <Using Include="System.Diagnostics" />
     <Using Include="Xunit" />
   </ItemGroup>
 
-  <ItemGroup>
-    <None Update="appsettings.json">
-      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
 </Project>

LiteCharms.Features.MidrandBooks.Tests/OrderServiceFeatureTests.cs

@@ -1,7 +1,7 @@
 using LiteCharms.Features.MidrandBooks.Orders;
 using LiteCharms.Features.MidrandBooks.Orders.Models;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
 using LiteCharms.Features.Models;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/PageServiceFeatureTests.cs

@@ -1,5 +1,5 @@
 using LiteCharms.Features.MidrandBooks.Pages;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/PayfastServiceFeatureTests.cs

@@ -0,0 +1,113 @@
+using LiteCharms.Features.MidrandBooks.Payments;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.Tests.Common;
+
+namespace LiteCharms.Features.MidrandBooks.Tests;
+
+public sealed class PayfastServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly PayfastService payfastService = fixture.Services.GetRequiredService<PayfastService>();
+
+    [IntegrationFact]
+    public async Task WriteLedgerEntryAsync_ShouldReturn_ResultWithGatewayLedgerId()
+    {
+        var request = new CreateGatewayLedgerEntry
+        {
+            OrderId = 1,
+            PaymentId = 1,
+            MerchantPaymentId = "M_REF_TEST_99",
+            PayfastPaymentId = "PF_SYS_ID_10023",
+            CustomerEmail = "buyer@litecharms.co.za",
+            AmountGross = 350.00m,
+            AmountFee = 12.50m,
+            AmountNet = 337.50m,
+            PaymentStatus = "COMPLETE"
+        };
+
+        var result = await payfastService.WriteLedgerEntryAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateReferrerIpAsync_WithValidPayfastHostIp_ShouldReturnTrue()
+    {
+        var addresses = await Dns.GetHostAddressesAsync("sandbox.payfast.co.za", fixture.CancellationToken);
+
+        string liveTargetIp = addresses.First().ToString();
+
+        var result = await payfastService.ValidateReferrerIpAsync(liveTargetIp, true, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateReferrerIpAsync_WithUntrustedIp_ShouldReturnFalse()
+    {
+        string rogueIp = "8.8.8.8";
+
+        var result = await payfastService.ValidateReferrerIpAsync(rogueIp, true, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.Value);
+    }
+
+    [IntegrationFact]
+    public void ValidatePaymentAmount_WhenWithinAllowableDelta_ShouldReturnTrue()
+    {
+        decimal systemExpectedTotal = 199.99m;
+        string gatewayClearedGross = "200.00"; // Variance is exactly R0.01
+
+        var result = payfastService.ValidatePaymentAmount(systemExpectedTotal, gatewayClearedGross);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value);
+    }
+
+    [IntegrationFact]
+    public void ValidatePaymentAmount_WhenVarianceBreachesDeltaBounds_ShouldReturnFalse()
+    {
+        decimal systemExpectedTotal = 199.99m;
+        string gatewayClearedGross = "150.00";
+
+        var result = payfastService.ValidatePaymentAmount(systemExpectedTotal, gatewayClearedGross);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateServerConfirmationAsync_WithUnrecognizedPayload_ShouldReturnFalseFromCentralGateway()
+    {
+        // Arrange - Execute against actual Payfast servers using raw mock parameters. 
+        // The server handshake will return 200 OK with string payload 'INVALID'
+        string arbitraryParameters = "merchant_id=10000000&payment_status=COMPLETE";
+
+        var result = await payfastService.ValidateServerConfirmationAsync(arbitraryParameters, isSandbox: true, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.Value);   // Handshake data rejected as fraudulent/unrecognized
+    }
+
+    [IntegrationFact]
+    public void GenerateSignature_WithStandardTelemetryData_ShouldSucceedAndHashString()
+    {
+        var telemetryPayload = new Dictionary<string, string?>
+        {
+            { "merchant_id", "10049307" },
+            { "merchant_key", "ju6navn0jcbf0" },
+            { "amount_gross", "250.00" },
+            { "item_name", "Midrand School Textbook Variant A" }
+        };
+
+        string passphrase = "oauth_test_signature_pass";
+
+        var result = PayfastService.GenerateSignature(telemetryPayload, passphrase);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(string.IsNullOrWhiteSpace(result.Value));
+        Assert.Equal(32, result.Value.Length); // MD5 outputs hex representations totaling 32 characters
+    }
+}

LiteCharms.Features.MidrandBooks.Tests/PaymentServiceFeatureTests.cs

@@ -1,6 +1,6 @@
 using LiteCharms.Features.MidrandBooks.Payments;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/ProductServiceFeatureTests.cs

@@ -1,7 +1,7 @@
 using LiteCharms.Features.MidrandBooks.Products;
 using LiteCharms.Features.MidrandBooks.Products.Models;
-using LiteCharms.Features.MidrandBooks.Tests.Common;
 using LiteCharms.Features.Models;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 

LiteCharms.Features.MidrandBooks.Tests/appsettings.json

@@ -1,28 +0,0 @@
-{
-  "BookshopS3Settings": {
-    "ServiceUrl": "http://192.168.1.177:30900",
-    "Region": "garage",
-    "BucketName": "bookshop",
-    "CdnBaseUrl": "https://bookshop.cdn.khongisa.co.za"
-  },
-  "Email": {
-    "Credentials": {
-      "Username": "shop@litecharms.co.za"
-    },
-    "Port": 465,
-    "Host": "mail.litecharms.co.za",
-    "UseSsl": true
-  },
-  "Monitoring": {
-    "ApiKey": "",
-    "Address": "http://aspire-dashboard-service.aspire.svc.cluster.local:18889",
-    "ServiceName": "LiteCharms.LeadGenerator"
-  },
-  "Logging": {
-    "LogLevel": {
-      "Default": "Information",
-      "Microsoft.AspNetCore": "Warning"
-    }
-  },
-  "AllowedHosts": "*"
-}

LiteCharms.Features.MidrandBooks/Abstractions/IMidrandBooks.cs

@@ -0,0 +1,3 @@
+namespace LiteCharms.Features.MidrandBooks.Abstractions;
+
+public interface IMidrandBooks;

LiteCharms.Features.MidrandBooks/AuthorBooks/BooksService.cs

@@ -58,6 +58,30 @@ public sealed class BooksService(IDbContextFactory<MidrandBooksDbContext> contex
         }
     }
 
+    public async ValueTask<Result<AuthorBook>> GetBookByProductIdAsync(long productId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var book = await context.Books
+                .AsNoTracking()
+                .Include(b => b.Author)
+                .Include(b => b.Product)
+                    .ThenInclude(b => b!.Prices)
+                .Include(b => b.Pages)
+                .FirstOrDefaultAsync(b => b.ProductId == productId, cancellationToken);
+
+            return book is null
+                ? Result.Fail<AuthorBook>(new Error($"Book with product ID {productId} not found"))
+                : Result.Ok(book.ToModel());
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<AuthorBook>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result<AuthorBook>> GetBookAsync(long bookId, CancellationToken cancellationToken = default)
     {
         try

LiteCharms.Features.MidrandBooks/Customers/CustomerService.cs

@@ -334,6 +334,28 @@ public sealed class CustomerService(IDbContextFactory<MidrandBooksDbContext> con
         }
     }
 
+    public async ValueTask<Result<Customer>> GetCustomerAsync(string email, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var customer = await context.Customers
+                .AsNoTracking()
+                .Include(c => c.Contacts)
+                .Include(c => c.Addresses)
+                .FirstOrDefaultAsync(c => c.Email == email, cancellationToken);
+
+            return customer is not null
+                ? Result.Ok(customer.ToModel())
+                : Result.Fail<Customer>(new Error($"Customer with email '{email}' does not exist."));
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<Customer>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result<Customer>> GetCustomerAsync(long customerId, CancellationToken cancellationToken = default)
     {
         try

LiteCharms.Features.MidrandBooks/Customers/Entities/CustomerConfiguration.cs

@@ -12,8 +12,8 @@ public sealed class CustomerConfiguration : IEntityTypeConfiguration<Customer>
         builder.Property(c => c.Company).IsRequired(false);
         builder.Property(c => c.VatNumber).IsRequired(false);
         builder.Property(c => c.Email).IsRequired();
-        builder.Property(c => c.Phone).IsRequired();
+        builder.Property(c => c.Phone).IsRequired(false);
-        builder.Property(c => c.Website).IsRequired();
+        builder.Property(c => c.Website).IsRequired(false);
         builder.Property(c => c.Enabled).HasDefaultValue(true);
 
         builder.OwnsMany(f => f.SocialMedia, b => { b.ToJson(); });

LiteCharms.Features.MidrandBooks/Extensions/Mappers.cs

@@ -6,12 +6,26 @@ using LiteCharms.Features.MidrandBooks.Orders.Models;
 using LiteCharms.Features.MidrandBooks.Pages.Models;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
 using LiteCharms.Features.MidrandBooks.Products.Models;
-using Microsoft.CodeAnalysis.CSharp.Syntax;
 
 namespace LiteCharms.Features.MidrandBooks.Extensions;
 
 public static class Mappers
 {
+    public static PaymentGatewayLedger ToModel(this Payments.Entities.PaymentGatewayLedger entity) => new()
+    {
+        Id = entity.Id,
+        CreatedAt = entity.CreatedAt,
+        CustomerEmail = entity.CustomerEmail,
+        OrderId = entity.OrderId,
+        PaymentId = entity.PaymentId,
+        MerchantPaymentId = entity.MerchantPaymentId,
+        PayfastPaymentId = entity.PayfastPaymentId,
+        PaymentStatus = entity.PaymentStatus,
+        AmountGross = entity.AmountGross,
+        AmountFee = entity.AmountFee,
+        AmountNet = entity.AmountNet        
+    };
+
     public static Refund ToModel(this Payments.Entities.Refund entity) => new()
     {
         CreatedAt = entity.CreatedAt,
@@ -30,10 +44,9 @@ public static class Mappers
         CreatedAt = entity.CreatedAt,
         CustomerId = entity.CustomerId,
         OrderId = entity.OrderId,
-        PaymentGatewayId = entity.PaymentGatewayId,
-        PaymentGatewayReference = entity.PaymentGatewayReference,
         PaymentId = entity.PaymentId,
         Status = entity.Status,
+        MerchantPaymentId = entity.MerchantPaymentId,
     };
 
     public static PaymentGateway ToModel(this Payments.Entities.PaymentGateway entity) => new()

LiteCharms.Features.MidrandBooks/Extensions/Shop.cs

@@ -1,18 +1,27 @@
 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);
 
-        var implementations = Assembly.GetExecutingAssembly().GetTypes()
+        var sharedImplementations = typeof(IFeatures).Assembly.GetTypes()
             .Where(t => serviceType.IsAssignableFrom(t) && t.IsClass && !t.IsAbstract);
 
-        foreach (var implementation in implementations) 
+        foreach (var sharedImplementation in sharedImplementations) services.AddScoped(sharedImplementation);
-            services.AddScoped(implementation);
+
+        var coreImplementations = typeof(IMidrandBooks).Assembly.GetTypes()
+            .Where(t => serviceType.IsAssignableFrom(t) && t.IsClass && !t.IsAbstract);
+
+        foreach (var coreImplementation in coreImplementations) services.AddScoped(coreImplementation);
+
+        if (includeLocalStorage)
+            services.AddScoped<LocalStorageService>();
 
         return services;
     }

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

@@ -32,11 +32,11 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>
     <PackageReference Include="Humanizer" Version="3.0.10" />
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.98">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="OpenTelemetry" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry" Version="1.16.0" />
     <PackageReference Include="Quartz" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins.TimeZoneConverter" Version="3.18.1" />
@@ -50,11 +50,11 @@
 
   <!-- Configuration -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Configuration" />
@@ -67,9 +67,9 @@
     <PackageReference Include="AspNetCore.HealthChecks.UI.Core" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.Data" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.InMemory.Storage" Version="9.0.0" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
@@ -78,12 +78,12 @@
 
   <!-- Open Telemetry -->
   <ItemGroup>
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.16.0" />
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.16.0" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.16.0" />
 
     <!-- Global Usings -->
     <Using Include="OpenTelemetry.Resources" />
@@ -95,13 +95,13 @@
 
   <!-- Database -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.9">
       <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.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->
@@ -148,6 +148,11 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="Microsoft.AspNetCore.Http" />
+    <Using Include="System.Net.Sockets" />
+    <Using Include="System.Text.RegularExpressions" />
+    <Using Include="System.Web" />
+    <Using Include="System.Net" />
     <Using Include="Humanizer" />
     <Using Include="System.Globalization" />
     <Using Include="System.Reflection" />

LiteCharms.Features.MidrandBooks/Orders/OrderService.cs

@@ -164,6 +164,27 @@ public sealed class OrderService(IDbContextFactory<MidrandBooksDbContext> contex
     public async ValueTask<Result> CancelOrderAsync(long orderId, CancellationToken cancellationToken = default) =>
         await UpdateOrderStatusAsync(orderId, OrderStatus.Cancelled, cancellationToken);
 
+    public async ValueTask<Result<Order>> GetPendingOrderAsync(long customerId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var order = await context.Orders.AsNoTracking()
+                .Where(o => o.Status == OrderStatus.Pending && o.CustomerId == customerId)
+                .OrderByDescending(o => o.Id)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            return order is not null
+                ? Result.Ok(order.ToModel())
+                : Result.Fail<Order>("Order not found.");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<Order>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result<Order>> GetOrderAsync(long orderId, CancellationToken cancellationToken = default)
     {
         try

LiteCharms.Features.MidrandBooks/Payments/CartService.cs

@@ -0,0 +1,153 @@
+using LiteCharms.Features.Browser;
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.MidrandBooks.Authors.Models;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.MidrandBooks.Products.Models;
+
+namespace LiteCharms.Features.MidrandBooks.Payments;
+
+public sealed class CartService(LocalStorageService localStorage)
+{
+    private readonly string CartStorageKey = HashService.ToMd5Hash(nameof(Cart)).Value;
+
+    public Cart ShoppingCart { get; private set; } = new();
+
+    public event Action? OnCartChanged;
+
+    public static Func<Cart, long, int> GetCartItemQuantity = (shoppingCart, productPriceId) =>
+        shoppingCart.Items.FirstOrDefault(p => p.Price!.Id == productPriceId)?.Quantity ?? 1;
+
+    public Cart GetCart() => ShoppingCart;
+
+    public void NotifyStateChanged() => OnCartChanged?.Invoke();
+
+    public async Task LoadCartFromStorageAsync()
+    {
+        var loadResult = await localStorage.GetAsync<Cart>(CartStorageKey);
+
+        if (loadResult.IsFailed) await localStorage.SaveAsync(CartStorageKey, ShoppingCart);
+
+        if (loadResult.IsSuccess) ShoppingCart = loadResult.Value;
+
+        NotifyStateChanged();
+    }
+
+    public async Task SaveCartToStorageAsync() => await localStorage.SaveAsync(CartStorageKey, ShoppingCart);
+
+    public void AddItem(ProductPrice productPrice, Product product, Author author)
+    {
+        var itemExists = false;
+
+        for (var i = 0; i < ShoppingCart.Items.Count; i++)
+        {
+            if (ShoppingCart.Items[i].Price!.Id == productPrice.Id)
+            {
+                ShoppingCart.Items[i].Quantity++;
+                ShoppingCart.Items[i].Amount += productPrice.Amount;
+
+                itemExists = true;
+
+                break;
+            }
+        }
+
+        if (!itemExists)
+            ShoppingCart.Items.Add(new CartItem
+            {
+                Product = product,
+                Author = author,
+                Price = productPrice,
+                Amount = productPrice.Amount,
+                Quantity = 1,
+            });
+
+        CalculateTotalPrice();
+        NotifyStateChanged();
+    }
+
+    public void UpdateQuantity(long productPriceId, int delta)
+    {
+        for (var i = 0; i < ShoppingCart.Items.Count; i++)
+        {
+            if (ShoppingCart.Items[i].Price!.Id == productPriceId)
+            {
+                var oldQuantity = ShoppingCart.Items[i].Quantity;
+                var pricePerUnit = ShoppingCart.Items[i].Price!.Amount;
+
+                ShoppingCart.Items[i].Quantity += delta;
+                ShoppingCart.Items[i].Amount = pricePerUnit * ShoppingCart.Items[i].Quantity;
+                break;
+            }
+        }
+
+        CalculateTotalPrice();
+        NotifyStateChanged();
+    }
+
+    public void RemoveOneItem(long productPriceId)
+    {
+        for (var i = 0; i < ShoppingCart.Items.Count; i++)
+        {
+            if (ShoppingCart.Items[i].Price!.Id == productPriceId)
+            {
+                if (ShoppingCart.Items[i].Quantity <= 1)
+                {
+                    ShoppingCart.Items.Remove(ShoppingCart.Items[i]);
+
+                    break;
+                }
+                else
+                {
+                    ShoppingCart.Items[i].Quantity--;
+                    ShoppingCart.Items[i].Amount -= ShoppingCart.Items[i].Price!.Amount;
+                }
+
+                break;
+            }
+        }
+
+        CalculateTotalPrice();
+        NotifyStateChanged();
+    }
+
+    public void RemoveAllSameItem(long productPriceId)
+    {
+        if (ShoppingCart.Items.Count == 0) return;
+
+        var item = ShoppingCart.Items.FirstOrDefault(i => i.Price?.Id == productPriceId);
+
+        if (item is not null) ShoppingCart.Items.Remove(item);
+
+        CalculateTotalPrice();
+        NotifyStateChanged();
+    }
+
+    public void Clear()
+    {
+        if(ShoppingCart.CustomerId is not null || ShoppingCart.OrderId is not null)
+        {
+            ShoppingCart.TotalAmount = 0;
+            ShoppingCart.TotalVat = 0;
+            ShoppingCart.Items.Clear();
+
+            return;
+        }
+
+        ShoppingCart = new Cart();
+
+        NotifyStateChanged();
+    }
+
+    public decimal CalculateTotalPrice()
+    {
+        if (ShoppingCart.Items.Count == 0) return 0;
+
+        var gross = ShoppingCart.Items.Sum(i => i.Amount);
+
+        if (!ShoppingCart.IsVatInclusive) ShoppingCart.TotalVat = gross * ShoppingCart.VatRate;
+
+        ShoppingCart.TotalAmount = gross + ShoppingCart.TotalVat;
+
+        return ShoppingCart.TotalAmount;
+    }
+}

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentGatewayLedger.cs

@@ -0,0 +1,11 @@
+using LiteCharms.Features.MidrandBooks.Orders.Entities;
+
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+[EntityTypeConfiguration<PaymentGatewayLedgerConfiguration, PaymentGatewayLedger>]
+public class PaymentGatewayLedger : Models.PaymentGatewayLedger
+{
+    public virtual Order? Order { get; set; }
+
+    public virtual Payment? Payment { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentGatewayLedgerConfiguration.cs

@@ -0,0 +1,30 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+public sealed class PaymentGatewayLedgerConfiguration : IEntityTypeConfiguration<PaymentGatewayLedger>
+{
+    public void Configure(EntityTypeBuilder<PaymentGatewayLedger> builder)
+    {
+        builder.ToTable("GatewayLedger");
+
+        builder.HasKey(f  => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.OrderId).IsRequired();
+        builder.Property(f => f.PaymentId).IsRequired();
+        builder.Property(f => f.PayfastPaymentId).IsRequired();
+        builder.Property(f => f.MerchantPaymentId).IsRequired();
+        builder.Property(f => f.AmountGross).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.AmountFee).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.AmountNet).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.CustomerEmail).IsRequired(false);
+
+        builder.HasOne(f => f.Order)
+            .WithMany()
+            .HasForeignKey(f => f.OrderId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        builder.HasOne(f => f.Payment)
+            .WithMany()
+            .HasForeignKey(f => f.PaymentId)
+            .OnDelete(DeleteBehavior.Cascade);
+    }
+}

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentLedger.cs

@@ -11,6 +11,4 @@ public class PaymentLedger : Models.PaymentLedger
     public virtual Order? Order { get; set; }
 
     public virtual Customer? Customer { get; set; }
-
-    public virtual PaymentGateway? Gateway { get; set; }
 }

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentLedgerConfiguration.cs

@@ -9,8 +9,7 @@ public sealed class PaymentLedgerConfiguration : IEntityTypeConfiguration<Paymen
         builder.HasKey(f => f.Id);
         builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
         builder.Property(f => f.Status).IsRequired();
-        builder.Property(f => f.PaymentGatewayReference).IsRequired(false);
+        builder.Property(f => f.MerchantPaymentId).IsRequired(false);
-        builder.Property(f => f.PaymentGatewayId).IsRequired(false);
         builder.Property(f => f.OrderId).IsRequired();
         builder.Property(f => f.CustomerId).IsRequired();
         builder.Property(f => f.PaymentId).IsRequired();
@@ -31,11 +30,5 @@ public sealed class PaymentLedgerConfiguration : IEntityTypeConfiguration<Paymen
             .WithMany()
             .IsRequired()
             .HasForeignKey(f => f.CustomerId);
-
-        builder.HasOne(f => f.Gateway)
-            .WithMany()
-            .IsRequired(false)
-            .HasForeignKey(f => f.PaymentGatewayId)
-            .OnDelete(DeleteBehavior.Cascade);
     }
 }

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

@@ -1,84 +1,164 @@
-using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Api.Configuration;
+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, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) : 
+public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, 
+    IOptions<PayfastSettings> payfastOptions, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) :
     INotificationHandler<PayfastPaymentConfirmationReceivedEvent>
 {
-    private readonly PaymentService paymentService = services.GetRequiredService<PaymentService>();
+    private readonly PayfastSettings pasfastSettings = payfastOptions.Value;
-    private readonly OrderService orderService = services.GetRequiredService<OrderService>();
-    private readonly HashService hashService = services.GetRequiredService<HashService>();
 
     public async ValueTask Handle(PayfastPaymentConfirmationReceivedEvent notification, CancellationToken cancellationToken)
     {
-        var hashResult = hashService.DecodeLongIdHash(notification.Payload?.MPaymentId!);
+        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(PayfastPaymentConfirmationReceivedEvent).Name}");
-        if (hashResult.IsFailed)
+        activity?.SetTag("event.correlation_id", notification.CorrelationId);
-        {
-            logger.LogError("Failed to decode payment ID hash: {Hash}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", hashResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to decode payment ID hash: {notification.Payload?.MPaymentId}.");
-        }
 
-        var orderResult = await orderService.GetOrderAsync(hashResult.Value, cancellationToken);
+        await using var scope = services.CreateAsyncScope();
-        if (orderResult.IsFailed)
+        var hashService = scope.ServiceProvider.GetRequiredService<HashService>();
-        {
+        var orderService = scope.ServiceProvider.GetRequiredService<OrderService>();
-            logger.LogError("Failed to retrieve order for payment ID: {PaymentId}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", orderResult.Errors.Select(e => e.Message)));
+        var paymentService = scope.ServiceProvider.GetRequiredService<PaymentService>();
-            throw new Exception($"Failed to retrieve order for payment ID: {notification.Payload?.MPaymentId}.");
+        var payfastService = scope.ServiceProvider.GetRequiredService<PayfastService>();
-        }
 
-        var paymentResult = await paymentService.GetOrderPaymentAsync(orderResult.Value.CustomerId, cancellationToken);
+        var payload = notification.Payload ?? throw new Exception("Payload metadata context context is null.");
-        if (paymentResult.IsFailed)
-        {
-            logger.LogError("Failed to retrieve payment for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", paymentResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to retrieve payment for order ID: {orderResult.Value.Id}.");
-        }
 
-        var isAlreadyProcessed = await paymentService.HasLedgerEntryAsync(orderResult.Value.Id, paymentResult.Value.Id, 1, cancellationToken);
+        var dict = payload.ToParamDictionary();
+        var localSignature = PayfastService.GenerateSignature(dict, pasfastSettings.Passphrase);
 
-        if (isAlreadyProcessed.IsFailed)
+        if (localSignature.IsFailed)
-        {
+            throw new Exception("Failed to generate local signature for incoming webhook payload.");
-            logger.LogError("Failed to check existing ledger entry for order ID: {OrderId} and payment ID: {PaymentId}. Errors: {Errors}", orderResult.Value.Id, paymentResult.Value.Id, string.Join(", ", isAlreadyProcessed.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to check existing ledger entry for order ID: {orderResult.Value.Id} and payment ID: {paymentResult.Value.Id}.");
-        }
 
-        if (isAlreadyProcessed.Value)
+        if (!string.Equals(localSignature.Value, payload.Signature, StringComparison.OrdinalIgnoreCase))
         {
-            logger.LogInformation("Payment confirmation for payment ID: {PaymentId} has already been processed. Skipping.", notification.Payload?.MPaymentId);
+            logger.LogCritical("Incoming webhook signature verification failed. Possible payload tampering.");
+
             return;
         }
 
-        var ledgerResult = await paymentService.WriteLedgerEntryAsync(new Models.CreateLedgerEntry
+        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.");
+
+        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
         {
-            CustomerId = orderResult.Value.CustomerId,
             OrderId = orderResult.Value.Id,
             PaymentId = paymentResult.Value.Id,
-            Status = LedgerStatuses.Received,
+            MerchantPaymentId = payload.MerchantPaymentId!,
-            PaymentGatewayId = 1,
+            PayfastPaymentId = payload.PaymentId,
-            PaymentGatewayReference = notification.CorrelationId,
+            CustomerEmail = payload.EmailAddress,
+            AmountFee = fee,
+            AmountGross = gross,
+            AmountNet = net,
+            PaymentStatus = status,
         }, cancellationToken);
 
-        if (ledgerResult.IsFailed)
+        if (status.Equals("COMPLETE", StringComparison.OrdinalIgnoreCase))
         {
-            logger.LogError("Failed to write ledger entry for payment ID: {PaymentId}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", ledgerResult.Errors.Select(e => e.Message)));
+            var ledgerWriteResult = await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
-            throw new Exception($"Failed to write ledger entry for payment ID: {notification.Payload?.MPaymentId}.");   
+            {
-        }
+                OrderId = orderResult.Value.Id,
+                PaymentId = paymentResult.Value.Id,
+                PaymentGatewayReference = payload.PaymentId!,
+                Status = LedgerStatuses.Completed,
+                CustomerId = orderResult.Value.CustomerId,
+            }, cancellationToken);
 
-        var paymentCompletedResult = await paymentService.CompletePaymentAsync(paymentResult.Value.Id, PaymentStatuses.Paid, cancellationToken);
+            if (ledgerWriteResult.IsFailed)
-        if (paymentCompletedResult.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.");
+
+            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.");
+
+            logger.LogInformation("Order payment verified secure and cleared successfully.");
+        }
+        else
         {
-            logger.LogError("Failed to complete payment for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", paymentCompletedResult.Errors.Select(e => e.Message)));
+            LedgerStatuses ledgerStatus;
-            throw new Exception($"Failed to complete payment for order ID: {orderResult.Value.Id}.");
+
+            if (status.Equals("CANCELLED", StringComparison.OrdinalIgnoreCase))
+                ledgerStatus = LedgerStatuses.Cancelled;
+            else
+                ledgerStatus = LedgerStatuses.Failed;
+
+            var ledgerWriteResult = await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
+            {
+                OrderId = orderResult.Value.Id,
+                PaymentId = paymentResult.Value.Id,
+                PaymentGatewayReference = payload.PaymentId!,
+                Status = ledgerStatus,
+                CustomerId = orderResult.Value.CustomerId,
+            }, cancellationToken);
+
+            logger.LogInformation("Webhook validation pipeline passed checks successfully, logged entry to ledger with status: {Status}", status);
         }
-
+        activity?.SetStatus(ActivityStatusCode.Ok);
-        var orderCompletedResult = await orderService.UpdateOrderStatusAsync(orderResult.Value.Id, OrderStatus.Completed, cancellationToken);
-        if (orderCompletedResult.IsFailed)
-        {
-            logger.LogError("Failed to update order status to Completed for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", orderCompletedResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to update order status to Completed for order ID: {orderResult.Value.Id}.");
-        }
-
-        logger.LogInformation("Received Payfast payment confirmation for payment ID: {PaymentId}", notification.Payload?.MPaymentId);
-
-        // TODO: Publish MediatR notifications or queue downstream Quartz jobs (Discord, Shipping, Customer Email, Royalties)
     }
 }

LiteCharms.Features.MidrandBooks/Payments/Events/PayfastPaymentConfirmationReceivedEvent.cs

@@ -1,5 +1,5 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Models;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Payments.Events;
 
@@ -9,14 +9,22 @@ public sealed class PayfastPaymentConfirmationReceivedEvent : EventBase, IEvent
 
     public PayfastWebhookPayload? Payload { get; set; }
 
+    public string? RemoteIpAddress { get; set; }
+
+    public bool PerformBackgroundChecks { get; set; }
+
+    public bool AllowLoopback { get; set; }
+
     public PayfastPaymentConfirmationReceivedEvent() { }
 
-    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId)
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false)
     {
         Payload = payload;
         CorrelationId = paymentId;
+        PerformBackgroundChecks = performBackgroundChecks;
+        AllowLoopback = allowLoopback;
     }
 
-    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId) =>
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false) =>
-        new(payload, paymentId);
+        new(payload, paymentId, performBackgroundChecks, allowLoopback);
 }

LiteCharms.Features.MidrandBooks/Payments/Models/Cart.cs

@@ -0,0 +1,18 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public sealed class Cart
+{
+    public long? CustomerId { get; set; }
+
+    public long? OrderId { get; set; }
+
+    public decimal TotalAmount { get; set; }
+
+    public decimal TotalVat { get; set; }
+
+    public decimal VatRate { get; set; } = 0.15m;
+
+    public bool IsVatInclusive { get; set; } = true;
+
+    public IList<CartItem> Items { get; set; } = [];
+}

LiteCharms.Features.MidrandBooks/Payments/Models/CartItem.cs

@@ -0,0 +1,17 @@
+using LiteCharms.Features.MidrandBooks.Authors.Models;
+using LiteCharms.Features.MidrandBooks.Products.Models;
+
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public sealed class CartItem
+{
+    public Author? Author { get; set; }
+
+    public Product? Product { get; set; }
+
+    public ProductPrice? Price { get; set; }
+
+    public int Quantity { get; set; }
+
+    public decimal Amount { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PayfastWebhookPayload.cs

@@ -0,0 +1,59 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public sealed class PayfastWebhookPayload
+{
+    public string? MerchantId { get; set; }
+
+    public string? MerchantKey { get; set; }
+
+    public string? Signature { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public string? ItemName { get; set; }
+
+    public string? ItemDescription { get; set; }
+
+    public string? AmountGross { get; set; }
+
+    public string? AmountFee { get; set; }
+
+    public string? AmountNet { get; set; }
+
+    public string? NameFirst { get; set; }
+
+    public string? NameLast { get; set; }
+
+    public string? EmailAddress { get; set; }
+
+    public string? CustomStr1 { get; set; }
+
+    public string? CustomInt1 { get; set; }
+
+    public string? Token { get; set; }
+
+    public IDictionary<string, string?> ToParamDictionary() => new Dictionary<string, string?>
+        (StringComparer.Ordinal)
+        {
+            { "merchant_id", MerchantId },
+            { "merchant_key", MerchantKey },
+            { "m_payment_id", MerchantPaymentId },
+            { "pf_payment_id", PaymentId },
+            { "payment_status", PaymentStatus },
+            { "item_name", ItemName },
+            { "item_description", ItemDescription },
+            { "amount_gross", AmountGross },
+            { "amount_fee", AmountFee },
+            { "amount_net", AmountNet },
+            { "custom_str1", CustomStr1 },
+            { "custom_int1", CustomInt1 },
+            { "name_first", NameFirst },
+            { "name_last", NameLast },
+            { "email_address", EmailAddress },
+            { "token", Token }
+        };
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PaymentGatewayLedger.cs

@@ -0,0 +1,26 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public class PaymentGatewayLedger
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public string? CustomerEmail { get; set; }
+
+    public long OrderId { get; set; }
+
+    public long PaymentId { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PayfastPaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public decimal AmountGross { get; set; }
+
+    public decimal AmountFee { get; set; }
+
+    public decimal AmountNet { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PaymentLedger.cs

@@ -14,7 +14,5 @@ public class PaymentLedger
 
     public long CustomerId { get; set; }
 
-    public string? PaymentGatewayReference { get; set; }
+    public string? MerchantPaymentId { get; set; }
-
-    public long? PaymentGatewayId { get; set; }
 }

LiteCharms.Features.MidrandBooks/Payments/Models/Records.cs

@@ -1,5 +1,26 @@
 namespace LiteCharms.Features.MidrandBooks.Payments.Models;
 
+public sealed record CreateGatewayLedgerEntry
+{
+    public string? CustomerEmail { get; set; }
+
+    public required long OrderId { get; set; }
+
+    public required long PaymentId { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PayfastPaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public decimal AmountGross { get; set; }
+
+    public decimal AmountFee { get; set; }
+
+    public decimal AmountNet { get; set; }
+}
+
 public sealed record UpdateRefund
 {
     public long OrderId { get; set; }

LiteCharms.Features.MidrandBooks/Payments/PayfastService.cs

@@ -0,0 +1,245 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Api.Configuration;
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.MidrandBooks.Postgres;
+
+namespace LiteCharms.Features.MidrandBooks.Payments;
+
+public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbContext> contextFactory, 
+    IOptions<PayfastSettings> payfastOptions, ILogger<PayfastService> logger, IHttpClientFactory httpClientFactory) : IService
+{
+    [GeneratedRegex(@"%[0-9A-Fa-f]{2}", RegexOptions.None, matchTimeoutMilliseconds: 1000)]
+    public static partial Regex PercentEncodingRegex { get; }
+
+    public async ValueTask<Result<long>> WriteLedgerEntryAsync(CreateGatewayLedgerEntry request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if(!await context.Orders.AnyAsync(o => o.Id == request.OrderId, cancellationToken))
+                return Result.Fail<long>("Referenced order ID does not exist in database.");
+
+            if(!await context.Payments.AnyAsync(p => p.Id == request.PaymentId, cancellationToken))
+                return Result.Fail<long>("Referenced payment ID does not exist in database.");
+
+            var entry = context.GatewayLedger.Add(new Entities.PaymentGatewayLedger
+            {
+                CustomerEmail = request.CustomerEmail,
+                OrderId = request.OrderId,
+                PaymentId = request.PaymentId,
+                MerchantPaymentId = request.MerchantPaymentId,
+                PayfastPaymentId = request.PayfastPaymentId,
+                PaymentStatus = request.PaymentStatus,
+                AmountGross = request.AmountGross,
+                AmountFee = request.AmountFee,
+                AmountNet = request.AmountNet,
+                CreatedAt = DateTime.UtcNow,                
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(entry.Entity.Id)
+                : Result.Fail<long>("Failed to save Payfast ledger entry to database.");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error("Failed to write Payfast ledger entry to database.").CausedBy(ex));
+        }
+    }
+
+    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)
+            return Result.Fail<bool>("Valid payfast hosts not configured.");
+
+        if (string.IsNullOrWhiteSpace(remoteIpAddress)) 
+            return Result.Fail<bool>("Remote IP address is null or whitespace.");
+
+        try
+        {
+            var validIps = new HashSet<IPAddress>();
+
+            foreach (var host in payfastOptions.Value!.ValidHosts!)
+            {
+                try
+                {
+                    var addresses = await Dns.GetHostAddressesAsync(host, cancellationToken);
+
+                    foreach (var addr in addresses) validIps.Add(addr);
+                }
+                catch (SocketException ex)
+                {
+                    logger.LogWarning(ex, "DNS warning: Failed to resolve Payfast node '{Host}'. It may be decommissioned or unreachable.", host);
+                }
+            }
+
+            if (IPAddress.TryParse(remoteIpAddress, out var incomingIp))
+            {
+                if (allowLoopback && IPAddress.IsLoopback(incomingIp))
+                {
+                    logger.LogInformation("Local development loopback IP '{RemoteIp}' allowed bypassing DNS verification.", remoteIpAddress);
+                    return Result.Ok(true);
+                }
+
+                bool isValid = validIps.Contains(incomingIp);
+
+                if (!isValid)
+                    logger.LogWarning("SECURITY ALERT: Webhook IP '{RemoteIp}' originated from an unlisted host schema.", remoteIpAddress);
+
+                return Result.Ok(isValid);
+            }
+
+            return Result.Fail<bool>("Invalid remote IP address format.");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<bool>(new Error("DNS Verification error while scanning Payfast IP nodes.").CausedBy(ex));
+        }
+    }
+
+    public Result<bool> ValidatePaymentAmount(decimal expectedTotal, string? amountGrossString)
+    {
+        if (!decimal.TryParse(amountGrossString, CultureInfo.InvariantCulture, out decimal grossAmount))
+            return Result.Fail<bool>("Failed to parse payment amount.");
+
+        decimal delta = Math.Abs(expectedTotal - grossAmount);
+
+        bool isAmountValid = delta <= 0.01m;
+
+        if (!isAmountValid)
+            logger.LogError("FINANCIAL DRIFT EXCEPTION: Expected order total R{Expected} but gateway cleared R{Cleared}.", expectedTotal, grossAmount);
+
+        return Result.Ok(isAmountValid);
+    }
+
+    public async ValueTask<Result<bool>> ValidateServerConfirmationAsync(string rawQueryParamString, bool isSandbox, CancellationToken ct)
+    {
+        try
+        {
+            string host = isSandbox ? "sandbox.payfast.co.za" : "www.payfast.co.za";
+            string targetUrl = $"https://{host}/eng/query/validate";
+
+            using var content = new StringContent(rawQueryParamString, Encoding.UTF8, "application/x-www-form-urlencoded");
+
+            var httpClient = httpClientFactory.CreateClient();
+
+            var response = await httpClient.PostAsync(targetUrl, content, ct);
+
+            if (!response.IsSuccessStatusCode) return Result.Fail<bool>("Failed to validate server confirmation.");
+
+            string responseText = await response.Content.ReadAsStringAsync(ct);
+
+            bool isValidated = string.Equals(responseText.Trim(), "VALID", StringComparison.OrdinalIgnoreCase);
+
+            if (!isValidated)
+                logger.LogWarning("SECURITY WARNING: Payfast back-channel returned validation response: '{Response}'", responseText);
+
+            return Result.Ok(isValidated);
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<bool>(new Error("Failed to complete back-channel cURL verification handshakes with Payfast remote endpoints.").CausedBy(ex));
+        }
+    }
+
+    public static Result<string> GenerateSignature(IDictionary<string, string?> data, string? passPhrase = null)
+    {
+        var pfOutput = new StringBuilder();
+
+        var mandatorySequence = GetPayfastMandatoryFieldSequence();
+
+        foreach (string key in mandatorySequence)
+        {
+            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());
+
+                pfOutput.Append($"{key}={val}&");
+            }
+        }
+
+        var getString = pfOutput.Length > 0
+            ? pfOutput.ToString()[..^1]
+            : string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(passPhrase))
+        {
+            string encodedPassphrase = HttpUtility.UrlEncode(passPhrase.Trim());
+            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

@@ -116,7 +116,7 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
         }
     }
 
-    public async ValueTask<Result<bool>> HasLedgerEntryAsync(long orderId, long paymentId, long gatewayId, CancellationToken cancellationToken = default)
+    public async ValueTask<Result<bool>> HasLedgerEntryAsync(long orderId, long paymentId, CancellationToken cancellationToken = default)
     {
         try
         {
@@ -124,8 +124,7 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
 
             var exists = await context.Ledger.AnyAsync(l =>
                 l.OrderId == orderId &&
-                l.PaymentId == paymentId &&
+                l.PaymentId == paymentId, cancellationToken);
-                l.PaymentGatewayId == gatewayId, cancellationToken);
 
             return Result.Ok(exists);
         }
@@ -162,8 +161,6 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
                 CreatedAt = DateTime.UtcNow,
                 CustomerId = request.CustomerId,
                 OrderId = request.OrderId,
-                PaymentGatewayId = request.PaymentGatewayId,
-                PaymentGatewayReference = request.PaymentGatewayReference,
                 PaymentId = request.PaymentId,
                 Status = request.Status,
             });

LiteCharms.Features.MidrandBooks/Postgres/MidrandBooksDbContext.cs

@@ -48,4 +48,6 @@ public sealed class MidrandBooksDbContext(DbContextOptions<MidrandBooksDbContext
     public DbSet<PaymentGateway> Gateways => Set<PaymentGateway>();
 
     public DbSet<PaymentLedger> Ledger => Set<PaymentLedger>();
+
+    public DbSet<PaymentGatewayLedger> GatewayLedger => Set<PaymentGatewayLedger>();
 }

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260602202421_AddedPaymentGatewayLedger.cs

@@ -0,0 +1,108 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddedPaymentGatewayLedger : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropForeignKey(
+                name: "FK_Ledger_Gateways_PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.DropIndex(
+                name: "IX_Ledger_PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.DropColumn(
+                name: "PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.RenameColumn(
+                name: "PaymentGatewayReference",
+                table: "Ledger",
+                newName: "MerchantPaymentId");
+
+            migrationBuilder.CreateTable(
+                name: "GatewayLedger",
+                columns: table => new
+                {
+                    Id = table.Column<long>(type: "bigint", nullable: false)
+                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
+                    CreatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false, defaultValueSql: "now()"),
+                    CustomerEmail = table.Column<string>(type: "text", nullable: true),
+                    OrderId = table.Column<long>(type: "bigint", nullable: false),
+                    PaymentId = table.Column<long>(type: "bigint", nullable: false),
+                    MerchantPaymentId = table.Column<string>(type: "text", nullable: true),
+                    PayfastPaymentId = table.Column<string>(type: "text", nullable: false),
+                    PaymentStatus = table.Column<string>(type: "text", nullable: true),
+                    AmountGross = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false),
+                    AmountFee = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false),
+                    AmountNet = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_GatewayLedger", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_GatewayLedger_Orders_OrderId",
+                        column: x => x.OrderId,
+                        principalTable: "Orders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_GatewayLedger_Payments_PaymentId",
+                        column: x => x.PaymentId,
+                        principalTable: "Payments",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GatewayLedger_OrderId",
+                table: "GatewayLedger",
+                column: "OrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GatewayLedger_PaymentId",
+                table: "GatewayLedger",
+                column: "PaymentId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "GatewayLedger");
+
+            migrationBuilder.RenameColumn(
+                name: "MerchantPaymentId",
+                table: "Ledger",
+                newName: "PaymentGatewayReference");
+
+            migrationBuilder.AddColumn<long>(
+                name: "PaymentGatewayId",
+                table: "Ledger",
+                type: "bigint",
+                nullable: true);
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_PaymentGatewayId",
+                table: "Ledger",
+                column: "PaymentGatewayId");
+
+            migrationBuilder.AddForeignKey(
+                name: "FK_Ledger_Gateways_PaymentGatewayId",
+                table: "Ledger",
+                column: "PaymentGatewayId",
+                principalTable: "Gateways",
+                principalColumn: "Id",
+                onDelete: ReferentialAction.Cascade);
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260602205838_AddedPayfastPaymentIdToPaymentGatewayLedger.cs

@@ -0,0 +1,36 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddedPayfastPaymentIdToPaymentGatewayLedger : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "MerchantPaymentId",
+                table: "GatewayLedger",
+                type: "text",
+                nullable: false,
+                defaultValue: "",
+                oldClrType: typeof(string),
+                oldType: "text",
+                oldNullable: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "MerchantPaymentId",
+                table: "GatewayLedger",
+                type: "text",
+                nullable: true,
+                oldClrType: typeof(string),
+                oldType: "text");
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260612210020_OnlyEmailIsMandatoryOnCustomer.cs

@@ -0,0 +1,54 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class OnlyEmailIsMandatoryOnCustomer : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "Website",
+                table: "Customers",
+                type: "text",
+                nullable: true,
+                oldClrType: typeof(string),
+                oldType: "text");
+
+            migrationBuilder.AlterColumn<string>(
+                name: "Phone",
+                table: "Customers",
+                type: "text",
+                nullable: true,
+                oldClrType: typeof(string),
+                oldType: "text");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "Website",
+                table: "Customers",
+                type: "text",
+                nullable: false,
+                defaultValue: "",
+                oldClrType: typeof(string),
+                oldType: "text",
+                oldNullable: true);
+
+            migrationBuilder.AlterColumn<string>(
+                name: "Phone",
+                table: "Customers",
+                type: "text",
+                nullable: false,
+                defaultValue: "",
+                oldClrType: typeof(string),
+                oldType: "text",
+                oldNullable: true);
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/MidrandBooksDbContextModelSnapshot.cs

@@ -17,7 +17,7 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
         {
 #pragma warning disable 612, 618
             modelBuilder
-                .HasAnnotation("ProductVersion", "10.0.8")
+                .HasAnnotation("ProductVersion", "10.0.9")
                 .HasAnnotation("Relational:MaxIdentifierLength", 63);
 
             NpgsqlModelBuilderExtensions.UseIdentityByDefaultColumns(modelBuilder);
@@ -309,7 +309,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                         .HasDefaultValue(true);
 
                     b.Property<string>("Phone")
-                        .IsRequired()
                         .HasColumnType("text");
 
                     b.Property<DateTime?>("UpdatedAt")
@@ -321,7 +320,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                         .HasColumnType("text");
 
                     b.Property<string>("Website")
-                        .IsRequired()
                         .HasColumnType("text");
 
                     b.HasKey("Id");
@@ -615,6 +613,60 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.ToTable("Gateways", (string)null);
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGatewayLedger", b =>
+                {
+                    b.Property<long>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<decimal>("AmountFee")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<decimal>("AmountGross")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<decimal>("AmountNet")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<string>("CustomerEmail")
+                        .HasColumnType("text");
+
+                    b.Property<string>("MerchantPaymentId")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<long>("OrderId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("PayfastPaymentId")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<long>("PaymentId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("PaymentStatus")
+                        .HasColumnType("text");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("OrderId");
+
+                    b.HasIndex("PaymentId");
+
+                    b.ToTable("GatewayLedger", (string)null);
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentLedger", b =>
                 {
                     b.Property<long>("Id")
@@ -631,15 +683,12 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Property<long>("CustomerId")
                         .HasColumnType("bigint");
 
+                    b.Property<string>("MerchantPaymentId")
+                        .HasColumnType("text");
+
                     b.Property<long>("OrderId")
                         .HasColumnType("bigint");
 
-                    b.Property<long?>("PaymentGatewayId")
-                        .HasColumnType("bigint");
-
-                    b.Property<string>("PaymentGatewayReference")
-                        .HasColumnType("text");
-
                     b.Property<long>("PaymentId")
                         .HasColumnType("bigint");
 
@@ -652,8 +701,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
 
                     b.HasIndex("OrderId");
 
-                    b.HasIndex("PaymentGatewayId");
-
                     b.HasIndex("PaymentId");
 
                     b.ToTable("Ledger", (string)null);
@@ -1062,6 +1109,25 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Navigation("Order");
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGatewayLedger", b =>
+                {
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Orders.Entities.Order", "Order")
+                        .WithMany()
+                        .HasForeignKey("OrderId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", "Payment")
+                        .WithMany()
+                        .HasForeignKey("PaymentId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Order");
+
+                    b.Navigation("Payment");
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentLedger", b =>
                 {
                     b.HasOne("LiteCharms.Features.MidrandBooks.Customers.Entities.Customer", "Customer")
@@ -1076,11 +1142,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                         .OnDelete(DeleteBehavior.Cascade)
                         .IsRequired();
 
-                    b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGateway", "Gateway")
-                        .WithMany()
-                        .HasForeignKey("PaymentGatewayId")
-                        .OnDelete(DeleteBehavior.Cascade);
-
                     b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", "Payment")
                         .WithMany()
                         .HasForeignKey("PaymentId")
@@ -1089,8 +1150,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
 
                     b.Navigation("Customer");
 
-                    b.Navigation("Gateway");
-
                     b.Navigation("Order");
 
                     b.Navigation("Payment");

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

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>

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

@@ -36,7 +36,7 @@
 
   <!-- Quartz Scheduler-->
   <ItemGroup>
-    <PackageReference Include="OpenTelemetry" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry" Version="1.16.0" />
     <PackageReference Include="Quartz" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins.TimeZoneConverter" Version="3.18.1" />
@@ -50,11 +50,11 @@
 
   <!-- Configuration -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Configuration" />
@@ -67,9 +67,9 @@
     <PackageReference Include="AspNetCore.HealthChecks.UI.Core" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.Data" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.InMemory.Storage" Version="9.0.0" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
@@ -78,12 +78,12 @@
 
   <!-- Open Telemetry -->
   <ItemGroup>
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.16.0" />
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.16.0" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.16.0" />
 
     <!-- Global Usings -->
     <Using Include="OpenTelemetry.Resources" />
@@ -95,17 +95,17 @@
 
   <!-- Database -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
+    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.2" />
 
     <!-- Global Usings -->
     <Using Include="Npgsql" />
@@ -116,8 +116,8 @@
 
   <!-- Email -->
   <ItemGroup>
-    <PackageReference Include="MailKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.0" />
-    <PackageReference Include="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MimeKit" Version="4.17.0" />
 
     <!-- Global Usings-->
     <Using Include="MimeKit" />
@@ -136,8 +136,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.Tests.Common/Fixture.cs

@@ -1,7 +1,7 @@
 using LiteCharms.Features.Extensions;
 using LiteCharms.Features.MidrandBooks.Extensions;
 
-namespace LiteCharms.Features.MidrandBooks.Tests.Common;
+namespace LiteCharms.Features.Tests.Common;
 
 public class Fixture : IDisposable
 {
@@ -25,15 +25,19 @@ public class Fixture : IDisposable
             .Build();
 
         Services = new ServiceCollection()
-            .AddMediator()
             .AddLogging()
+            .AddMediator()
             .AddEmailServiceBus()
             .AddGarageS3(Configuration)
             .AddMidrandShopDatabase(Configuration)
             .AddEmailServices(Configuration)
             .AddSingleton(Configuration)
             .AddShopServices()
-            .BuildServiceProvider();
+            .AddHashServices(Configuration)
+            .AddLiteCharmsApiSecurity(Configuration)
+            .AddSecurityApiSdk(Configuration)
+            .AddPayfastServices(Configuration)
+            .BuildServiceProvider(); ;
 
         Mediator = Services.GetRequiredService<IMediator>();
     }

LiteCharms.Features.Tests.Common/IntegrationFactAttribute.cs

@@ -1,4 +1,4 @@
-namespace LiteCharms.Features.MidrandBooks.Tests.Common;
+namespace LiteCharms.Features.Tests.Common;
 
 public class IntegrationFactAttribute : FactAttribute
 {

LiteCharms.Features.Tests.Common/LiteCharms.Features.Tests.Common.csproj

@@ -0,0 +1,76 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>0521f45a-eba0-457f-bb5e-c3680f65d8b1</UserSecretsId>
+  </PropertyGroup>
+
+  <!-- xUnit -->
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="10.0.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>    
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    
+    <Using Include="Xunit.Abstractions" />
+  </ItemGroup>
+
+  <!-- Mediator -->
+  <ItemGroup>
+    <PackageReference Include="Mediator.Abstractions" Version="3.0.2" />
+    <PackageReference Include="Mediator.SourceGenerator" Version="3.0.2">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+
+    <Using Include="Mediator" />
+  </ItemGroup>
+  
+  <!-- Microsoft -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.CommandLine" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Options" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.9" />
+    
+    <Using Include="Microsoft.Extensions.DependencyInjection" />
+    <Using Include="Microsoft.Extensions.Configuration" />
+  </ItemGroup>
+
+  <!-- Shared Usings -->
+  <ItemGroup>
+    <Using Include="System.Net" />
+    <Using Include="System.Text.Json" />
+    <Using Include="System.Diagnostics" />
+    <Using Include="System.Reflection" />
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\LiteCharms.Features.MidrandBooks\LiteCharms.Features.MidrandBooks.csproj" />
+    <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="appsettings.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

LiteCharms.Features.Tests.Common/appsettings.json

@@ -1,16 +1,32 @@
 {
+  "PayfastSettings": {
+    "CheckoutUrl": "https://sandbox.payfast.co.za/eng/process",
+    "ValidHosts": [
+      "www.payfast.co.za",
+      "sandbox.payfast.co.za",
+      "ips.payfast.co.za",
+      "api.payfast.co.za",
+      "payment.payfast.io"
+    ]
+  },
+  "LiteCharmsSettings": {
+    "Authority": "https://sts.security.khongisa.co.za",
+    "Audience": "midrandbooks-api"
+  },
+  "LiteCharmsClientSettings": {
+    "Authority": "https://sts.security.khongisa.co.za",
+    "GrantType": "client_credentials",
+    "Scope": "midrandbooks-api"
+  },
+  "HasherSettings": {
+    "MinHashLength": 11
+  },
   "BookshopS3Settings": {
     "ServiceUrl": "http://192.168.1.177:30900",
     "Region": "garage",
     "BucketName": "bookshop",
     "CdnBaseUrl": "https://bookshop.cdn.khongisa.co.za"
   },
-  "BookshopQuotesS3Settings": {
-    "ServiceUrl": "http://192.168.1.177:30900",
-    "Region": "garage",
-    "BucketName": "bookshop.quotes",
-    "CdnBaseUrl": "https://bookshop.quotes.cdn.khongisa.co.za"
-  },
   "Email": {
     "Credentials": {
       "Username": "shop@litecharms.co.za"
@@ -20,7 +36,6 @@
     "UseSsl": true
   },
   "Monitoring": {
-    "ApiKey": "",
     "Address": "http://aspire-dashboard-service.aspire.svc.cluster.local:18889",
     "ServiceName": "LiteCharms.LeadGenerator"
   },

LiteCharms.Features.Tests/Fixture.cs

@@ -1,36 +0,0 @@
-using LiteCharms.Features.Extensions;
-
-namespace LiteCharms.Features.Tests;
-
-public class Fixture : IDisposable
-{
-    public IConfiguration Configuration { get; set; }
-
-    public IServiceProvider Services { get; set; }
-
-    public IMediator Mediator { get; set; }
-
-    public Fixture()
-    {
-        Configuration = new ConfigurationBuilder()
-            .SetBasePath(Directory.GetCurrentDirectory())
-            .AddUserSecrets<Fixture>()
-            .AddJsonFile(Path.Combine(Directory.GetCurrentDirectory(), "appsettings.json"), optional: true, reloadOnChange: true)
-            .AddEnvironmentVariables()
-            .Build();
-
-        Services = new ServiceCollection()            
-            .AddMediator()
-            .AddLogging()            
-            .AddEmailServiceBus()
-            .AddGarageS3(Configuration)
-            .AddEmailServices(Configuration)
-            .AddSingleton(Configuration)
-            .AddHashServices(Configuration)
-            .BuildServiceProvider();
-
-        Mediator = Services.GetRequiredService<IMediator>();
-    }
-
-    public void Dispose() { }
-}

LiteCharms.Features.Tests/HashServiceFeatureTests.cs

@@ -1,13 +1,11 @@
 using LiteCharms.Features.Hasher;
-using LiteCharms.Features.Models;
+using LiteCharms.Features.Tests.Common;
-using static LiteCharms.Features.Extensions.Hash;
 
 namespace LiteCharms.Features.Tests;
 
 public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
 {
     private readonly HashService hashService = fixture.Services.GetRequiredService<HashService>();
-    private readonly string payfastPassphrase = fixture.Configuration.GetSection("HasherSettings:PayfastPassphrase").Value!;
 
     [Fact]
     public void StringToSha256Hash_Should_GenerateHash()
@@ -62,28 +60,6 @@ public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
         Assert.Equal(expectedMd5Lowercase, result.Value);
     }
 
-    [Fact]
-    public void VerifyPayfastWebhookSignature_Should_GenerateHash()
-    {
-        var paymentId = hashService.HashEncodeLongId(1001).Value;
-
-        var payload = new PayfastWebhookPayload
-        {
-            Amount = "350.00",
-            ItemName = "System Architecture Book",
-            MPaymentId = paymentId,            
-        };
-
-        var rawPayload = payload.ToRawPayfastPayload(payfastPassphrase);
-
-        var generatedSignature = HashService.ToMd5Hash(rawPayload).Value;
-
-        var result = hashService.VerifyPayfastWebhookSignature(payload, generatedSignature);
-
-        Assert.True(result.IsSuccess);
-        Assert.True(result.Value);
-    }
-
     [Fact]
     public void HashEncodeHex_Should_GenerateHash()
     {

LiteCharms.Features.Tests/LiteCharms.Features.Tests.csproj

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>
@@ -31,11 +31,13 @@
     <Using Include="System.Text" />
     <Using Include="Mediator" />
     <Using Include="Xunit.Abstractions" />
+    <Using Include="Microsoft.Extensions.Options" />
     <Using Include="Microsoft.Extensions.DependencyInjection" />
     <Using Include="Microsoft.Extensions.Configuration" />
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\LiteCharms.Features.Tests.Common\LiteCharms.Features.Tests.Common.csproj" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
   </ItemGroup>
 
@@ -43,10 +45,4 @@
     <Using Include="Xunit" />
   </ItemGroup>
 
-  <ItemGroup>
-    <None Update="appsettings.json">
-      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
 </Project>

LiteCharms.Features.Tests/LiteCharmsApiFeatureTests.cs

@@ -0,0 +1,19 @@
+using LiteCharms.Features.Api;
+using LiteCharms.Features.Tests.Common;
+
+namespace LiteCharms.Features.Tests;
+
+public sealed class LiteCharmsApiFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly TokenService tokenService = fixture.Services.GetRequiredService<TokenService>();
+
+    [IntegrationFact]
+    public async Task TokenService_GenerateTokenAsync_ShouldReturn_TokenInResult()
+    {
+        var result = await tokenService.GenerateAsync(fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.NotNull(result.Value);
+        Assert.NotEmpty(result.Value.AccessToken!);
+    }
+}

LiteCharms.Features.Tests/PayfastFeatureTests.cs

@@ -0,0 +1,18 @@
+using LiteCharms.Features.Api.Configuration;
+using LiteCharms.Features.Tests.Common;
+
+namespace LiteCharms.Features.Tests;
+
+public sealed class PayfastFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly PayfastSettings payfastSettings = fixture.Services.GetRequiredService<IOptions<PayfastSettings>>().Value;
+
+    [IntegrationFact]
+    public void PayfastSettings_ShouldFail_IfNotLoaded()
+    {
+        Assert.NotEmpty(payfastSettings.CheckoutUrl!);
+        Assert.NotEmpty(payfastSettings.MerchantId!);
+        Assert.NotEmpty(payfastSettings.MerchantKey!);
+        Assert.NotEmpty(payfastSettings.Passphrase!);
+    }
+}

LiteCharms.Features.Tests/S3ServiceFeatureTests.cs

@@ -1,4 +1,5 @@
 using LiteCharms.Features.S3.Abstractions;
+using LiteCharms.Features.Tests.Common;
 
 namespace LiteCharms.Features.Tests;
 

LiteCharms.Features.Tests/http/litecharms/app.http

@@ -0,0 +1,6 @@
+### Authentik Token Request (Service Account Explicit)
+POST {{authority}}/connect/token
+Content-Type: application/x-www-form-urlencoded
+Accept-Encoding: identity
+
+grant_type={{grantType}}&client_id={{clientId}}&client_secret={{clientSecret}}&scope={{scope}}

LiteCharms.Features.Tests/http/litecharms/http-client.env.json

@@ -0,0 +1,9 @@
+{
+  "uat": {
+    "authority": "https://sts.security.khongisa.co.za",
+    "grantType": "client_credentials",
+    "clientId": "midrandbooks-api-scaler-uat",
+    "clientSecret": "secret_0a8dc1f99061590a52b1272db3a1871d2761c79fbd058b2a968911029e4b208a",
+    "scope": "midrandbooks-api"
+  }
+}

LiteCharms.Features.Tests/http/midrandshop-api/app.http

@@ -0,0 +1,8 @@
+## Payfast Payment Confirmation
+# This endpoint is used by Payfast to confirm the payment status of a transaction. 
+# It receives a POST request with the payment details and updates the order status accordingly.
+
+POST {{baseUrl}}/v1/payments/payfast/confirm
+Content-Type: application/x-www-form-urlencoded
+
+amount={{amount}}&item_name={{item_name}}&m_payment_id={{paymentId}}&signature={{signature}}

LiteCharms.Features/Abstractions/IEndpoint.cs

@@ -0,0 +1,6 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IEndpoint
+{
+    void Map(IEndpointRouteBuilder builder);
+}

LiteCharms.Features/Abstractions/IFeatures.cs

@@ -0,0 +1,3 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IFeatures;

LiteCharms.Features/Abstractions/IJobOrchestrator.cs

@@ -0,0 +1,12 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IJobOrchestrator
+{
+    ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+        where TNotification : IEvent;
+
+    ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
+        where TNotification : IEvent;
+
+    ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default);
+}

LiteCharms.Features/Api/ApiVersionTargetAttribute.cs

@@ -0,0 +1,7 @@
+namespace LiteCharms.Features.Api;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class ApiVersionTargetAttribute(int majorVersion) : Attribute
+{
+    public int MajorVersion { get; } = majorVersion;
+}

LiteCharms.Features/Api/Configuration/LiteCharmsClientSettings.cs

@@ -0,0 +1,14 @@
+namespace LiteCharms.Features.Api.Configuration;
+
+public sealed class LiteCharmsClientSettings
+{
+    public string? Authority { get; set; }
+
+    public string? GrantType { get; set; }
+
+    public string? ClientId { get; set; }
+
+    public string? ClientSecret { get; set; }
+
+    public string? Scope { get; set; }
+}

LiteCharms.Features/Api/Configuration/LiteCharmsSettings.cs

@@ -0,0 +1,12 @@
+namespace LiteCharms.Features.Api.Configuration;
+
+public sealed class LiteCharmsSettings
+{
+    public string? Authority { get; set; }
+
+    public string? ClientId { get; set; }
+
+    public string? ClientSecret { get; set; }
+
+    public string? Audience { get; set; }
+}

LiteCharms.Features/Api/Configuration/PayfastSettings.cs

@@ -0,0 +1,14 @@
+namespace LiteCharms.Features.Api.Configuration;
+
+public sealed class PayfastSettings
+{
+    public string? CheckoutUrl { get; set; }
+
+    public string? Passphrase { get; set; }
+
+    public string? MerchantId { get; set; }
+
+    public string? MerchantKey { get; set; }
+
+    public string[]? ValidHosts { get; set; }
+}

LiteCharms.Features/Api/Models/TokenErrorResponse.cs

@@ -0,0 +1,13 @@
+namespace LiteCharms.Features.Api.Models;
+
+public sealed class TokenErrorResponse
+{
+    [JsonPropertyName("error")]
+    public string? Error { get; set; }
+
+    [JsonPropertyName("error_description")]
+    public string? ErrorDescription { get; set; }
+
+    [JsonPropertyName("error_uri")]
+    public string? ErrorUri { get; set; }
+}

LiteCharms.Features/Api/Models/TokenRequest.cs

@@ -0,0 +1,20 @@
+namespace LiteCharms.Features.Api.Models;
+
+public sealed class TokenRequest
+{
+    [JsonPropertyName("grant_type")]
+    [AliasAs("grant_type")]
+    public string? GrantType { get; set; }
+
+    [JsonPropertyName("client_id")]
+    [AliasAs("client_id")]
+    public string? ClientId { get; set; }
+
+    [JsonPropertyName("client_secret")]
+    [AliasAs("client_secret")]
+    public string? ClientSecret { get; set; }
+
+    [JsonPropertyName("scope")]
+    [AliasAs("scope")]
+    public string? Scope { get; set; }
+}

LiteCharms.Features/Api/Models/TokenResponse.cs

@@ -0,0 +1,17 @@
+namespace LiteCharms.Features.Api.Models;
+
+public sealed class TokenResponse
+{
+    [JsonPropertyName("access_token")]
+    public string? AccessToken { get; set; }
+
+    [JsonPropertyName("expires_in")]
+    public int ExpiresIn { get; set; }
+
+    [JsonPropertyName("token_type")]
+    public string? TokenType { get; set; }
+
+    [JsonPropertyName("scope")]
+    public string? Scope { get; set; }
+}
+

LiteCharms.Features/Api/OpenApiBearerSecuritySchemeTransformer.cs

@@ -0,0 +1,16 @@
+namespace LiteCharms.Features.Api;
+
+public sealed class OpenApiBearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var bearerScheme = new OpenApiSecurityScheme
+        {
+            Type = SecuritySchemeType.Http,
+            Scheme = "bearer",
+            Description = "JWT Authorization header using the Bearer scheme",
+        };
+
+        document.AddComponent("Bearer", bearerScheme);
+    }
+}

LiteCharms.Features/Api/Sdk/IConnectApi.cs

@@ -0,0 +1,10 @@
+using LiteCharms.Features.Api.Models;
+
+namespace LiteCharms.Features.Api.Sdk;
+
+public interface IConnectApi
+{
+    [Post("/connect/token")]
+    ValueTask<HttpResponseMessage> GetToken([Body(BodySerializationMethod.UrlEncoded)] TokenRequest request, 
+        CancellationToken cancellationToken = default);
+}

LiteCharms.Features/Api/TokenService.cs

@@ -0,0 +1,66 @@
+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)
+{
+    private readonly LiteCharmsClientSettings clientSettings = clientOptions.Value;
+
+    public async Task<Result<TokenResponse>> GenerateAsync(CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var request = new TokenRequest
+            {
+                ClientId = clientSettings.ClientId,
+                ClientSecret = clientSettings.ClientSecret,
+                GrantType = clientSettings.GrantType,
+                Scope = clientSettings.Scope,
+            };
+
+            using var response = await connectApi.GetToken(request, cancellationToken);
+
+            var contentRaw = await response.Content.ReadAsStringAsync(cancellationToken);
+
+            if (string.IsNullOrWhiteSpace(contentRaw))
+                return Result.Fail(new Error($"The authentication endpoint returned an empty payload. Status code: {response.StatusCode}"));
+
+            if (response.IsSuccessStatusCode)
+            {
+                var tokenResponse = JsonSerializer.Deserialize<TokenResponse>(contentRaw);
+
+                return !string.IsNullOrWhiteSpace(tokenResponse?.AccessToken)
+                    ? Result.Ok(tokenResponse)
+                    : Result.Fail<TokenResponse>(new Error("Authentication succeeded, but no access token was found in the response payload."));
+            }
+
+            try
+            {
+                var errorResult = JsonSerializer.Deserialize<TokenErrorResponse>(contentRaw);
+
+                if (errorResult != null)
+                {
+                    string summary = $"{errorResult.Error}: {errorResult.ErrorDescription}";
+
+                    return Result.Fail(new Error(summary));
+                }
+            }
+            catch
+            {
+                return Result.Fail(new Error($"Authentication failed: {contentRaw}"));
+            }
+
+            return Result.Fail(new Error($"Authentication failed with status code: {response.StatusCode}"));
+        }
+        catch (OperationCanceledException ex)
+        {
+            return Result.Fail(new Error("The token generation request was canceled.").CausedBy(ex));
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+}

LiteCharms.Features/Browser/LocalStorageService.cs

@@ -0,0 +1,78 @@
+namespace LiteCharms.Features.Browser;
+
+public sealed class LocalStorageService(ProtectedLocalStorage storage)
+{
+    public async ValueTask<Result> DeleteAsync(string key)
+    {
+        try
+        {
+            await storage.DeleteAsync(key);
+
+            return Result.Ok();
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result> SaveAsync(string key, string value)
+    {
+        try
+        {
+            await storage.SetAsync(key, value);
+
+            return Result.Ok();
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result> SaveAsync<TValue>(string key, TValue value) where TValue : class
+    {
+        try
+        {
+            await storage.SetAsync(key, value);
+
+            return Result.Ok();
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<string>> GetAsync(string key)
+    {
+        try
+        {
+            var retrieval = await storage.GetAsync<string>(key);
+
+            return retrieval.Success && !string.IsNullOrWhiteSpace(retrieval.Value)
+                ? Result.Ok(retrieval.Value)
+                : Result.Fail($"Could not find object by key {key}");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<TValue>> GetAsync<TValue>(string key) where TValue : class
+    {
+        try
+        {
+            var retrieval = await storage.GetAsync<TValue>(key);
+
+            return retrieval.Success && retrieval.Value is not null
+                ? Result.Ok(retrieval.Value)
+                : Result.Fail($"Could not find object by key {key}");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+}

LiteCharms.Features/Email/Models/EmailEnquiryModel.cs

@@ -7,25 +7,25 @@ public sealed class EmailEnquiryModel
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Full Name")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Full Name")]
     public string? FullName { get; set; }
 
     [Required]
     [EmailAddress]
     [MinLength(5)]
     [MaxLength(255)]
-    [Display(Name = "Email Address")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Email Address")]
     public string? EmailAddress { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Subject")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Subject")]
     public string? EmailSubject { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(2000)]
-    [Display(Name = "Message")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Message")]
     public string? Message { get; set; }
 }

LiteCharms.Features/Enums.cs

@@ -19,6 +19,7 @@ public enum LedgerStatuses : int
     Cancelled = 4,
     Failed = 5,
     Partial = 6,
+    Completed = 7,
 }
 
 public enum PaymentStatuses : int

LiteCharms.Features/Extensions/Api.cs

@@ -0,0 +1,249 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Api;
+using LiteCharms.Features.Api.Configuration;
+using LiteCharms.Features.Api.Sdk;
+
+namespace LiteCharms.Features.Extensions;
+
+public static class Api
+{
+    public const string Books = nameof(Books);
+    public const string Payments = nameof(Payments);
+
+    public static IServiceCollection AddPayfastServices(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(PayfastSettings));
+
+        services.Configure<PayfastSettings>(configSection);
+
+        return services;
+    }
+    
+    public static IServiceCollection AddSecurityApiSdk(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(LiteCharmsClientSettings));
+
+        var authOptions = new LiteCharmsClientSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<LiteCharmsClientSettings>(configSection);
+
+        if (string.IsNullOrWhiteSpace(authOptions.Authority))
+            return services;
+
+        if (!authOptions.Authority.EndsWith("/", StringComparison.Ordinal)) authOptions.Authority += "/";
+
+        services.AddRefitClient<IConnectApi>()
+            .ConfigureHttpClient(config =>
+            {
+                config.BaseAddress = new Uri(authOptions.Authority);
+                config.Timeout = TimeSpan.FromSeconds(15);
+            })
+            .AddStandardResilienceHandler(options =>
+            {
+                options.Retry.MaxRetryAttempts = 3;
+                options.Retry.Delay = TimeSpan.FromSeconds(1);
+                options.Retry.BackoffType = Polly.DelayBackoffType.Exponential;
+            });
+
+        services.AddScoped<TokenService>();
+
+        return services;
+    }
+
+    public static IServiceCollection AddLiteCharmsWebSecurity(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(LiteCharmsSettings));
+
+        var authOptions = new LiteCharmsSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<LiteCharmsSettings>(configSection);
+
+        services.AddAuthentication(options =>
+        {
+            options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+            options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
+        })
+        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme)
+        .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
+        {
+            options.Authority = authOptions.Authority;
+
+            options.ClientId = authOptions.ClientId;
+            options.ClientSecret = authOptions.ClientSecret;
+            options.ResponseType = "code";
+
+            options.SaveTokens = true;
+            options.GetClaimsFromUserInfoEndpoint = true;
+
+            options.Scope.Clear();
+            options.Scope.Add("openid");
+            options.Scope.Add("profile");
+            options.Scope.Add("email");
+
+            options.Events = new OpenIdConnectEvents
+            {
+                OnRedirectToIdentityProviderForSignOut = context =>
+                {
+                    var idToken = context.ProtocolMessage.IdTokenHint;
+
+                    if (string.IsNullOrEmpty(idToken))
+                    {
+                        var tokens = context.Properties.GetTokens();
+                        var idTokenItem = tokens.FirstOrDefault(t => string.Equals(t.Name, "id_token", StringComparison.Ordinal));
+
+                        if (idTokenItem != null) context.ProtocolMessage.IdTokenHint = idTokenItem.Value;
+                    }
+
+                    return Task.CompletedTask;
+                },
+            };
+        });
+
+        services.AddCascadingAuthenticationState();
+
+        return services;
+    }
+
+    public static IServiceCollection AddLiteCharmsApiSecurity(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(LiteCharmsSettings));
+
+        var authOptions = new LiteCharmsSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<LiteCharmsSettings>(configSection);
+
+        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(options =>
+            {
+                options.Authority = authOptions.Authority;
+                options.Audience = authOptions.Audience;
+                options.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidIssuer = authOptions.Authority,
+                    ValidateAudience = true,
+                    ValidateIssuer = true,
+                };
+            });
+
+        services.AddAuthorization();
+
+        return services;
+    }
+
+    public static WebApplication AddSecurityEndpoints(this WebApplication app)
+    {
+        app.MapGet("/login", async (HttpContext context, string redirectUri = "/") =>
+        {
+            await context.ChallengeAsync(OpenIdConnectDefaults.AuthenticationScheme, new AuthenticationProperties
+            {
+                RedirectUri = redirectUri,
+            });
+        });
+
+        app.MapGet("/logout", async (HttpContext context) =>
+        {
+            var idToken = await context.GetTokenAsync("id_token");
+
+            var authProperties = new AuthenticationProperties { RedirectUri = "/", };
+
+            if (!string.IsNullOrEmpty(idToken)) 
+                authProperties.Parameters.Add("id_token_hint", idToken);
+
+            await context.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme, authProperties);
+            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+        });
+
+        return app;
+    }
+
+    public static IServiceCollection AddApiServices(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddHttpClient();
+
+        services.AddApiVersioning(options =>
+        {
+            options.DefaultApiVersion = new ApiVersion(1);
+            options.ReportApiVersions = true;
+            options.AssumeDefaultVersionWhenUnspecified = true;
+            options.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(),
+                new QueryStringApiVersionReader("version"),
+                new QueryStringApiVersionReader("version"),
+                new MediaTypeApiVersionReader("version"));
+        })
+        .AddApiExplorer(options =>
+        {
+            options.GroupNameFormat = "'v'VVV";
+            options.SubstituteApiVersionInUrl = true;
+        });
+
+        var urls = configuration["ASPNETCORE_URLS"] ?? configuration["Urls"];
+        var healthUrl = "http://localhost:8080/health";
+
+        if (!string.IsNullOrWhiteSpace(urls))
+        {
+            string firstUrl = urls.Split(';').FirstOrDefault(s => s.Contains("http://"))!
+                .Replace("0.0.0.0", "localhost")
+                .Replace("*", "localhost")
+                .Replace("+", "localhost");
+
+            healthUrl = $"{firstUrl.TrimEnd('/')}/health";
+        }
+
+        services.AddHealthChecksUI(setup =>
+        {
+            setup.SetNotifyUnHealthyOneTimeUntilChange();
+            setup.AddHealthCheckEndpoint("primary, heal", healthUrl);
+            setup.SetHeaderText("Midrand Books");
+        })
+        .AddInMemoryStorage();
+
+        services.AddOutputCache(options =>
+        {
+            options.AddBasePolicy(builder => builder.Cache());
+            options.DefaultExpirationTimeSpan = TimeSpan.FromSeconds(10);
+        });
+
+        services.AddOpenApi(options => options.AddDocumentTransformer<OpenApiBearerSecuritySchemeTransformer>());
+
+        return services;
+    }
+
+    public static IApplicationBuilder MapEndpoints(this WebApplication app, IDictionary<int, RouteGroupBuilder> versionGroups)
+    {
+        var endpoints = app.Services.GetRequiredService<IEnumerable<IEndpoint>>();
+
+        foreach (var endpoint in endpoints)
+        {
+            var versionAttributes = endpoint.GetType().GetCustomAttributes<ApiVersionTargetAttribute>().ToList();
+
+            if (versionAttributes.Count != 0)
+            {
+                foreach (var attr in versionAttributes)
+                    if (versionGroups.TryGetValue(attr.MajorVersion, out var targetGroup))
+                        endpoint.Map(targetGroup);
+            }
+            else
+                endpoint.Map(app);
+        }
+
+        return app;
+    }
+
+    public static IServiceCollection AddEndpoints(this IServiceCollection services, Assembly assembly)
+    {
+        ServiceDescriptor[] discriptors = [.. assembly.DefinedTypes
+            .Where(t => t is { IsInterface: false, IsAbstract: false })
+            .Where(t => t.IsAssignableTo(typeof(IEndpoint)))
+            .Select(t => ServiceDescriptor.Transient(typeof(IEndpoint), t))];
+
+        services.TryAddEnumerable(discriptors);
+
+        return services;
+    }
+
+    public static string ToEndpointName(this Type target, string? annotation = "") =>
+        $"{target.Name.Replace("Endpoint", string.Empty)}{annotation}".ToLower(CultureInfo.CurrentCulture);
+}

LiteCharms.Features/Extensions/Hash.cs

@@ -1,6 +1,5 @@
 using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Hasher.Configuration;
-using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Extensions;
 
@@ -21,82 +20,4 @@ public static class Hash
 
         return services;
     }    
-
-    public static string ToRawPayfastPayload(this PayfastWebhookPayload input, string passphrase)
-    {
-        var parameters = new List<string>();
-
-        if (!string.IsNullOrWhiteSpace(input.Amount))
-            parameters.Add($"amount={WebUtility.UrlEncode(input.Amount)}");
-
-        if (!string.IsNullOrWhiteSpace(input.ItemName))
-            parameters.Add($"item_name={WebUtility.UrlEncode(input.ItemName)}");
-
-        if (!string.IsNullOrWhiteSpace(input.MPaymentId))
-            parameters.Add($"m_payment_id={WebUtility.UrlEncode(input.MPaymentId)}");
-
-        string payload = string.Join("&", parameters);
-
-        if (!string.IsNullOrWhiteSpace(passphrase))
-            payload += $"&passphrase={WebUtility.UrlEncode(passphrase)}";
-
-        return payload;
-    }
-
-    public static (PayfastWebhookPayload Payload, string Passphrase) FromRawPayfastPayload(this string rawPayload)
-    {
-        string passphrase = string.Empty;
-        var payload = new PayfastWebhookPayload();
-
-        if (string.IsNullOrWhiteSpace(rawPayload)) return (payload, passphrase);
-
-        var segments = rawPayload.Split('&', StringSplitOptions.RemoveEmptyEntries);
-
-        foreach (var segment in segments)
-        {
-            int delimiterIndex = segment.IndexOf('=');
-            if (delimiterIndex == -1)
-                continue;
-
-            string key = segment[..delimiterIndex].Trim();
-            string rawValue = segment[(delimiterIndex + 1)..];
-
-            string decodedValue = WebUtility.UrlDecode(rawValue);
-
-            switch (key.ToLowerInvariant())
-            {
-                case "amount":
-                    payload.Amount = decodedValue;
-                    break;
-                case "item_name":
-                    payload.ItemName = decodedValue;
-                    break;
-                case "m_payment_id":
-                    payload.MPaymentId = decodedValue;
-                    break;
-                case "passphrase":
-                    passphrase = decodedValue;
-                    break;
-            }
-        }
-
-        return (payload, passphrase);
-    }
-
-    public static (PayfastWebhookPayload Payload, string Passphrase) FromRawPayfastPayload(this IFormCollection form)
-    {
-        string passphrase = string.Empty;
-        var payload = new PayfastWebhookPayload();
-
-        if (form.IsNullOrEmpty()) return (payload, passphrase);
-
-        payload = new PayfastWebhookPayload
-        {
-            Amount = form.TryGetValue("amount", out var amountValues) ? amountValues.ToString() : null,
-            ItemName = form.TryGetValue("item_name", out var itemValues) ? itemValues.ToString() : null,
-            MPaymentId = form.TryGetValue("m_payment_id", out var paymentIdValues) ? paymentIdValues.ToString() : null,
-        };
-
-        return (payload, passphrase);
-    }
 }

LiteCharms.Features/Extensions/Quartz.cs

@@ -1,5 +1,5 @@
-using LiteCharms.Features.Quartz;
+using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Quartz.Abstractions;
+using LiteCharms.Features.Quartz;
 using static LiteCharms.Features.Extensions.Postgres;
 
 namespace LiteCharms.Features.Extensions;

LiteCharms.Features/Hasher/HashService.cs

@@ -1,14 +1,10 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Hasher.Configuration;
-using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Hasher;
 
-public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings> options) : IService
+public sealed partial class HashService(IHashids hasher) : IService
 {
-    private readonly HasherSettings settings = options.Value;
+    [GeneratedRegex(@"\A\b[0-9a-fA-F]+\b\Z", RegexOptions.None, matchTimeoutMilliseconds: 100)]
-
-    [GeneratedRegex(@"\A\b[0-9a-fA-F]+\b\Z")]
     private static partial Regex HexHashRegex { get; }
 
     [GeneratedRegex(@"\A[0-9a-fA-F]{32}\Z", RegexOptions.None, matchTimeoutMilliseconds: 100)]
@@ -41,44 +37,6 @@ public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings
         return Result.Ok(Convert.ToHexString(bytes).ToLowerInvariant());
     }
 
-    public Result<bool> VerifyPayfastWebhookSignature(PayfastWebhookPayload payload, string incomingSignature)
-    {
-        try
-        {
-            if (string.IsNullOrWhiteSpace(incomingSignature))
-                return Result.Fail<bool>("Validation failed: Missing signature string parameter.");
-
-            var parameters = new List<string>();
-
-            if (!string.IsNullOrWhiteSpace(payload.Amount))
-                parameters.Add($"amount={WebUtility.UrlEncode(payload.Amount)}");
-
-            if (!string.IsNullOrWhiteSpace(payload.ItemName))
-                parameters.Add($"item_name={WebUtility.UrlEncode(payload.ItemName)}");
-
-            if (!string.IsNullOrWhiteSpace(payload.MPaymentId))
-                parameters.Add($"m_payment_id={WebUtility.UrlEncode(payload.MPaymentId)}");
-
-            string signatureString = string.Join("&", parameters);
-
-            if (!string.IsNullOrWhiteSpace(settings.PayfastPassphrase))
-                signatureString += $"&passphrase={WebUtility.UrlEncode(settings.PayfastPassphrase)}";
-
-            var localHashResult = ToMd5Hash(signatureString);
-
-            if (!localHashResult.IsSuccess)
-                return Result.Fail<bool>(localHashResult.Errors);
-
-            bool isValid = string.Equals(localHashResult.Value, incomingSignature, StringComparison.OrdinalIgnoreCase);
-
-            return Result.Ok(isValid);
-        }
-        catch (Exception ex)
-        {
-            return Result.Fail<bool>(new Error("An error occurred during Payfast MD5 verification.").CausedBy(ex));
-        }
-    }
-
     public Result<string> HashEncodeHex(string input) => string.IsNullOrWhiteSpace(input) || !HexHashRegex.IsMatch(input)
             ? Result.Fail<string>("Input must be a valid hexadecimal string.")
             : Result.Ok(hasher.EncodeHex(input));

LiteCharms.Features/LiteCharms.Features.csproj

@@ -29,14 +29,61 @@
     <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <!-- Security (IODC)-->
+  <ItemGroup>
+    <PackageReference Include="IdentityModel.AspNetCore" Version="4.3.0" />
+    <PackageReference Include="IdentityModel.AspNetCore.OAuth2introspection" Version="6.2.0" />
+    <PackageReference Include="IdentityServer4.AccessTokenValidation" Version="3.0.1" />
+    <PackageReference Include="IdentityModel" Version="6.2.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" Version="10.0.9" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Http.Polly" Version="10.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="10.7.0" />
+    <PackageReference Include="Polly" Version="8.7.0" />
+    <PackageReference Include="Polly.Extensions" Version="8.7.0" />
+
+    <Using Include="Microsoft.AspNetCore.Authentication" />
+    <Using Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" />
+    <Using Include="Microsoft.AspNetCore.Authentication.Cookies" />
+    <Using Include="IdentityModel.AspNetCore.OAuth2Introspection" />
+    <Using Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
+  </ItemGroup>
+
+  <!-- API SDK Composer-->
+  <ItemGroup>
+    <PackageReference Include="Refit.HttpClientFactory" Version="11.0.1" />
+
+    <Using Include="Refit" />
+  </ItemGroup>
+
+  <!-- API Versioning -->
+  <ItemGroup>
+    <PackageReference Include="AccessTokenClient.Extensions" Version="5.1.0" />
+    <PackageReference Include="Asp.Versioning.Abstractions" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Http" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0" />
+
+    <Using Include="Asp.Versioning" />
+  </ItemGroup>
+
+  <!-- API Documentation -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.16.3" />
+
+    <Using Include="Scalar.AspNetCore" />
+    <Using Include="Microsoft.OpenApi" />
+    <Using Include="Microsoft.AspNetCore.OpenApi" />
+  </ItemGroup>
+
   <!-- Quartz Scheduler-->
   <ItemGroup>    
     <PackageReference Include="Hashids.net" Version="1.7.0" />    
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.96">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.102">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>    
-    <PackageReference Include="OpenTelemetry" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry" Version="1.16.0" />
     <PackageReference Include="Quartz" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins" Version="3.18.1" />
     <PackageReference Include="Quartz.Plugins.TimeZoneConverter" Version="3.18.1" />
@@ -50,11 +97,11 @@
 
   <!-- Configuration -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Configuration" />
@@ -67,9 +114,9 @@
     <PackageReference Include="AspNetCore.HealthChecks.UI.Core" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.Data" Version="9.0.0" />
     <PackageReference Include="AspNetCore.HealthChecks.UI.InMemory.Storage" Version="9.0.0" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.9" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />    
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />    
-    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="10.0.9" />
 
     <!-- Global Usings -->
     <Using Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
@@ -78,12 +125,12 @@
 
   <!-- Open Telemetry -->
   <ItemGroup>
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.16.0" />
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.16.0" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.16.0" />
 
     <!-- Global Usings -->
     <Using Include="OpenTelemetry.Resources" />
@@ -95,17 +142,17 @@
 
   <!-- Database -->
   <ItemGroup>
-    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.8" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.8">
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.9">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
+    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.2" />
 
     <!-- Global Usings -->
     <Using Include="Npgsql" />
@@ -116,8 +163,8 @@
   
   <!-- Email -->
   <ItemGroup>
-    <PackageReference Include="MailKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.0" />
-    <PackageReference Include="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MimeKit" Version="4.17.0" />
     
     <!-- Global Usings-->
     <Using Include="MimeKit" />
@@ -136,8 +183,8 @@
   
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.6" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24.3" />
     
     <!-- global Usings -->
     <Using Include="Amazon.S3" />
@@ -147,6 +194,12 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage" />
+    <Using Include="System.Text.Json.Serialization" />
+    <Using Include="System.Reflection" />
+    <Using Include="Microsoft.Extensions.DependencyInjection.Extensions" />
+    <Using Include="Microsoft.AspNetCore.Routing" />
+    <Using Include="System.Web" />
     <Using Include="Microsoft.IdentityModel.Tokens" />
     <Using Include="Microsoft.AspNetCore.Http" />
     <Using Include="HashidsNet" />

LiteCharms.Features/Models/PayfastWebhookPayload.cs

@@ -1,8 +0,0 @@
-namespace LiteCharms.Features.Models;
-
-public sealed class PayfastWebhookPayload
-{
-    public string? Amount { get; set; }
-    public string? ItemName { get; set; }
-    public string? MPaymentId { get; set; }
-}

LiteCharms.Features/Quartz/Abstractions/IJobOrchestrator.cs

@@ -1,12 +0,0 @@
-using LiteCharms.Features.Abstractions;
-
-namespace LiteCharms.Features.Quartz.Abstractions;
-
-public interface IJobOrchestrator
-{
-    Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
-        where TNotification : IEvent;
-
-    Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
-        where TNotification : IEvent;
-}

LiteCharms.Features/Quartz/JobOrchestrator.cs

@@ -1,11 +1,10 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Quartz.Abstractions;
 
 namespace LiteCharms.Features.Quartz;
 
 public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOrchestrator
 {
-    public async Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+    public async ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "onetime-jobs";
@@ -19,6 +18,7 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
             .WithDescription($"Correlation ID: {notification.CorrelationId}")
             .UsingJobData(new JobDataMap { ["Payload"] = JsonSerializer.Serialize(notification) })
             .DisallowConcurrentExecution()
+            .RequestRecovery()
             .Build();
 
         var trigger = global::Quartz.TriggerBuilder.Create()
@@ -29,7 +29,7 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
         await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
 
-    public async Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
+    public async ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "scheduled-jobs";
@@ -63,4 +63,25 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
         else
             await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
+
+    public async ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default)
+    {
+        var scheduler = await schedulerFactory.GetScheduler(cancellationToken);
+
+        var jobKeyName = string.Empty;
+        var jobGroup = string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(correlationId))
+        {
+            jobKeyName = $"{eventName.ToLower(CultureInfo.InvariantCulture)}-{correlationId.ToLower(CultureInfo.InvariantCulture)}";
+            jobGroup = "onetime-jobs";
+        }
+        else
+        {
+            jobKeyName = eventName.ToLower(CultureInfo.InvariantCulture);
+            jobGroup = "scheduled-jobs";
+        }
+
+        return await scheduler.Interrupt(JobKey.Create(jobKeyName, jobGroup), cancellationToken);
+    }
 }

LiteCharms.Features/Quartz/MediatorJob.cs

@@ -8,6 +8,9 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 {
     public async Task Execute(IJobExecutionContext context)
     {
+        if (context.Recovering)
+            Trace.WriteLine($"CRITICAL RECOVERY: Resurrecting job '{typeof(TNotification).Name}' after a previous cluster node crashed mid-execution.");
+
         var data = context.MergedJobDataMap["Payload"] as string;
 
         if (string.IsNullOrWhiteSpace(data))
@@ -21,17 +24,28 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 
         if (notification is null)
         {
-            Trace.WriteLine("Notification could not be JSon converted from data string, job ended");
+            Trace.WriteLine("Notification could not be Json converted from data string, job ended");
 
             return;
         }
 
-        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(TNotification).Name}");
+        using var activity = MediatorTelemetry.Source.StartActivity(typeof(TNotification).Name);
 
         activity?.SetTag("event.correlation_id", notification.CorrelationId);
 
-        await mediator.Publish(notification, context.CancellationToken);
+        try
+        {
+            await mediator.Publish(notification, context.CancellationToken);
 
-        Trace.WriteLine("Job published");
+            Trace.WriteLine("Job published successfully");
+        }
+        catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested)
+        {
+            Trace.WriteLine($"Job '{typeof(TNotification).Name}' was gracefully interrupted by the cluster control plane.");
+            
+            activity?.SetStatus(ActivityStatusCode.Ok);
+
+            return;
+        }
     }
 }

LiteCharms.Features/Quartz/RetryJobListener.cs

@@ -12,6 +12,9 @@ public sealed class RetryJobListener : IJobListener
 
     public async Task JobWasExecuted(IJobExecutionContext context, JobExecutionException? jobException, CancellationToken cancellationToken = default)
     {
+        if (context.CancellationToken.IsCancellationRequested)
+            return;
+
         if (jobException is not null && context.RefireCount < RetryCount)
             jobException.RefireImmediately = true;
     }

LiteCharmsShared.slnx

@@ -12,6 +12,7 @@
     <Project Path="LiteCharms.Features.MidrandBooks.Seed/LiteCharms.Features.MidrandBooks.Seed.csproj" Id="aa80643a-28dc-431f-b163-053a94e5c77c" />
     <Project Path="LiteCharms.Features.MidrandBooks.Tests/LiteCharms.Features.MidrandBooks.Tests.csproj" Id="cac2f738-dbb5-4538-8565-3c2bd6f65259" />
     <Project Path="LiteCharms.Features.TechShop.Tests/LiteCharms.Features.TechShop.Tests.csproj" Id="0e0967c2-7f28-4668-a387-2fc437ab066f" />
+    <Project Path="LiteCharms.Features.Tests.Common/LiteCharms.Features.Tests.Common.csproj" Id="d4ada579-b898-44ff-82f4-de3171c21600" />
     <Project Path="LiteCharms.Features.Tests/LiteCharms.Features.Tests.csproj" Id="0696323f-7148-4ab9-9145-68b7b5df5415" />
   </Folder>
 </Solution>