Security: enforce safe hosted controls for demo UI (#88)

PayBridge.SDK.Example/Models/DemoUiSecurityOptions.cs

@@ -0,0 +1,32 @@
+namespace PayBridge.SDK.Example.Models;
+
+public enum DemoRuntimeMode
+{
+    Mock = 0,
+    Sandbox = 1,
+    Live = 2
+}
+
+public sealed class DemoUiSecurityOptions
+{
+    public const string SectionName = "DemoUiSecurity";
+
+    // Hosted environments must require authenticated access to demo APIs.
+    public bool RequireAuthenticatedAccess { get; set; } = true;
+
+    // Shared API key for non-local environments. Keep in secure stores only.
+    public string ApiKey { get; set; } = string.Empty;
+
+    // Live mode is blocked by default and can only be enabled server-side.
+    public DemoRuntimeMode Mode { get; set; } = DemoRuntimeMode.Sandbox;
+
+    public bool AllowLiveMode { get; set; } = false;
+
+    // Basic anti-forgery guard for state-changing browser requests.
+    public bool RequireCsrfHeader { get; set; } = true;
+    public string CsrfHeaderName { get; set; } = "X-Console-CSRF";
+    public string CsrfHeaderValue { get; set; } = string.Empty;
+
+    // Global API throttling.
+    public int RequestsPerMinute { get; set; } = 60;
+}

PayBridge.SDK.Example/Program.cs

@@ -7,7 +7,12 @@
 
 using PayBridge.SDK;
 using PayBridge.SDK.Enums;
+using PayBridge.SDK.Example.Models;
+using PayBridge.SDK.Example.Services;
 using Serilog;
+using System.Runtime.InteropServices;
+using System.Security.Cryptography;
+using System.Threading.RateLimiting;
 
 // ── 1. LOGGING (optional — any ILogger provider works) ────────────────────
 //
@@ -36,6 +41,21 @@
 
 builder.Services.AddControllers();
 builder.Services.AddEndpointsApiExplorer();
+var demoUiRequestsPerMinute = builder.Configuration.GetValue<int>($"{DemoUiSecurityOptions.SectionName}:RequestsPerMinute", 60);
+builder.Services.AddRateLimiter(options =>
+{
+    options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(_ =>
+        RateLimitPartition.GetFixedWindowLimiter(
+            partitionKey: "global",
+            factory: _ => new FixedWindowRateLimiterOptions
+            {
+                PermitLimit = demoUiRequestsPerMinute,
+                Window = TimeSpan.FromMinutes(1),
+                QueueLimit = 0,
+                AutoReplenishment = true
+            }));
+    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
+});
 builder.Services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new()
@@ -54,6 +74,12 @@
         c.IncludeXmlComments(xmlPath);
 });
 
+builder.Services
+    .AddOptions<DemoUiSecurityOptions>()
+    .Bind(builder.Configuration.GetSection(DemoUiSecurityOptions.SectionName))
+    .ValidateOnStart();
+builder.Services.AddSingleton<Microsoft.Extensions.Options.IValidateOptions<DemoUiSecurityOptions>, DemoUiSecurityOptionsValidator>();
+
 // ── 3a. DATABASE (optional) ────────────────────────────────────────────────
 //
 // PayBridge can persist every transaction automatically.
@@ -126,6 +152,8 @@
 // ─────────────────────────────────────────────────────────────────────────────
 
 var app = builder.Build();
+var demoSecurity = app.Services.GetRequiredService<Microsoft.Extensions.Options.IOptions<DemoUiSecurityOptions>>().Value;
+var isHosted = !app.Environment.IsDevelopment();
 
 // ── 5. MIDDLEWARE PIPELINE ─────────────────────────────────────────────────
 
@@ -139,7 +167,77 @@
     });
 }
 
+app.Use(async (context, next) =>
+{
+    context.Response.Headers["X-Content-Type-Options"] = "nosniff";
+    context.Response.Headers["X-Frame-Options"] = "DENY";
+    context.Response.Headers["Referrer-Policy"] = "no-referrer";
+    context.Response.Headers["Content-Security-Policy"] =
+        "default-src 'none'; frame-ancestors 'none'; base-uri 'none'";
+    await next();
+});
+
+app.UseRateLimiter();
+
+app.Use(async (context, next) =>
+{
+    if (!context.Request.Path.StartsWithSegments("/api"))
+    {
+        await next();
+        return;
+    }
+
+    var isProviderCallback =
+        context.Request.Path.StartsWithSegments("/api/webhook") ||
+        context.Request.Path.StartsWithSegments("/api/verify");
+
+    if (isHosted && demoSecurity.RequireAuthenticatedAccess && !isProviderCallback)
+    {
+        var suppliedApiKey = context.Request.Headers["X-Demo-Api-Key"].ToString();
+        if (!IsFixedTimeMatch(suppliedApiKey, demoSecurity.ApiKey))
+        {
+            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
+            await context.Response.WriteAsJsonAsync(new { error = "unauthorized" });
+            return;
+        }
+    }
+
+    var isStateChangingMethod =
+        HttpMethods.IsPost(context.Request.Method) ||
+        HttpMethods.IsPut(context.Request.Method) ||
+        HttpMethods.IsPatch(context.Request.Method) ||
+        HttpMethods.IsDelete(context.Request.Method);
+
+    if (isHosted && demoSecurity.RequireCsrfHeader && !isProviderCallback && isStateChangingMethod)
+    {
+        var suppliedCsrf = context.Request.Headers[demoSecurity.CsrfHeaderName].ToString();
+        if (!IsFixedTimeMatch(suppliedCsrf, demoSecurity.CsrfHeaderValue))
+        {
+            context.Response.StatusCode = StatusCodes.Status400BadRequest;
+            await context.Response.WriteAsJsonAsync(new { error = "invalid_csrf" });
+            return;
+        }
+    }
+
+    if (isHosted && demoSecurity.Mode == DemoRuntimeMode.Live && !demoSecurity.AllowLiveMode)
+    {
+        context.Response.StatusCode = StatusCodes.Status403Forbidden;
+        await context.Response.WriteAsJsonAsync(new { error = "live_mode_blocked" });
+        return;
+    }
+
+    await next();
+});
+
 app.UseHttpsRedirection();
 app.MapControllers();
 
 app.Run();
+
+static bool IsFixedTimeMatch(string supplied, string expected)
+{
+    return supplied.Length == expected.Length &&
+           CryptographicOperations.FixedTimeEquals(
+               MemoryMarshal.AsBytes(supplied.AsSpan()),
+               MemoryMarshal.AsBytes(expected.AsSpan()));
+}

PayBridge.SDK.Example/Services/DemoUiSecurityOptionsValidator.cs

@@ -0,0 +1,61 @@
+using Microsoft.Extensions.Options;
+using PayBridge.SDK.Example.Models;
+
+namespace PayBridge.SDK.Example.Services;
+
+public sealed class DemoUiSecurityOptionsValidator : IValidateOptions<DemoUiSecurityOptions>
+{
+    public ValidateOptionsResult Validate(string? name, DemoUiSecurityOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        var failures = new List<string>();
+        if (options.RequestsPerMinute < 1)
+        {
+            failures.Add("DemoUiSecurity:RequestsPerMinute must be greater than zero.");
+        }
+
+        if (options.Mode == DemoRuntimeMode.Live && !options.AllowLiveMode)
+        {
+            failures.Add("DemoUiSecurity:Mode cannot be Live unless DemoUiSecurity:AllowLiveMode is true.");
+        }
+
+        if (options.RequireAuthenticatedAccess && string.IsNullOrWhiteSpace(options.ApiKey))
+        {
+            failures.Add("DemoUiSecurity:ApiKey is required when DemoUiSecurity:RequireAuthenticatedAccess is true.");
+        }
+        else if (options.RequireAuthenticatedAccess && IsPlaceholderSecret(options.ApiKey))
+        {
+            failures.Add("DemoUiSecurity:ApiKey cannot use placeholder values in hosted mode.");
+        }
+
+        if (options.RequireCsrfHeader)
+        {
+            if (string.IsNullOrWhiteSpace(options.CsrfHeaderName))
+            {
+                failures.Add("DemoUiSecurity:CsrfHeaderName is required when DemoUiSecurity:RequireCsrfHeader is true.");
+            }
+
+            if (string.IsNullOrWhiteSpace(options.CsrfHeaderValue))
+            {
+                failures.Add("DemoUiSecurity:CsrfHeaderValue is required when DemoUiSecurity:RequireCsrfHeader is true.");
+            }
+            else if (IsPlaceholderSecret(options.CsrfHeaderValue))
+            {
+                failures.Add("DemoUiSecurity:CsrfHeaderValue cannot use placeholder values when CSRF protection is enabled.");
+            }
+        }
+
+        return failures.Count == 0
+            ? ValidateOptionsResult.Success
+            : ValidateOptionsResult.Fail(failures);
+    }
+
+    private static bool IsPlaceholderSecret(string value)
+    {
+        var trimmed = value.Trim();
+        return trimmed.StartsWith("YOUR_", StringComparison.OrdinalIgnoreCase) ||
+               trimmed.StartsWith("CHANGE_ME", StringComparison.OrdinalIgnoreCase) ||
+               trimmed.Equals("REPLACE_ME", StringComparison.OrdinalIgnoreCase);
+    }
+}

PayBridge.SDK.Example/appsettings.Development.json

@@ -7,6 +7,17 @@
     }
   },
 
+  "DemoUiSecurity": {
+    "RequireAuthenticatedAccess": false,
+    "ApiKey": "",
+    "Mode": "Sandbox",
+    "AllowLiveMode": false,
+    "RequireCsrfHeader": false,
+    "CsrfHeaderName": "X-Console-CSRF",
+    "CsrfHeaderValue": "",
+    "RequestsPerMinute": 120
+  },
+
   "PaymentGatewayConfig": {
     "WebhookTimestampToleranceSeconds": 300,
     "EnabledGateways": [],

PayBridge.SDK.Example/appsettings.json

@@ -33,6 +33,17 @@
     "PayBridgeDbContext": "YOUR_PAYBRIDGE_CONNECTION_STRING"
   },
 
+  "DemoUiSecurity": {
+    "RequireAuthenticatedAccess": true,
+    "ApiKey": "",
+    "Mode": "Sandbox",
+    "AllowLiveMode": false,
+    "RequireCsrfHeader": true,
+    "CsrfHeaderName": "X-Console-CSRF",
+    "CsrfHeaderValue": "",
+    "RequestsPerMinute": 60
+  },
+
   "PaymentGatewayConfig": {
     "WebhookTimestampToleranceSeconds": 300,
     /*

PayBridge.SDK.Test/Unit/DemoUiSecurityOptionsValidatorTests.cs

@@ -0,0 +1,105 @@
+using FluentAssertions;
+using PayBridge.SDK.Example.Models;
+using PayBridge.SDK.Example.Services;
+using Xunit;
+
+namespace PayBridge.SDK.Test.Unit;
+
+[Trait("Category", "Unit")]
+public class DemoUiSecurityOptionsValidatorTests
+{
+    [Fact]
+    public void Validate_rejects_live_mode_when_not_explicitly_enabled()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+        options.Mode = DemoRuntimeMode.Live;
+        options.AllowLiveMode = false;
+
+        var result = validator.Validate(null, options);
+
+        result.Failed.Should().BeTrue();
+        result.Failures.Should().Contain(item => item.Contains("Mode cannot be Live"));
+    }
+
+    [Fact]
+    public void Validate_rejects_missing_api_key_when_hosted_access_is_required()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+        options.RequireAuthenticatedAccess = true;
+        options.ApiKey = string.Empty;
+
+        var result = validator.Validate(null, options);
+
+        result.Failed.Should().BeTrue();
+        result.Failures.Should().Contain(item => item.Contains("ApiKey is required"));
+    }
+
+    [Fact]
+    public void Validate_rejects_placeholder_api_key_when_hosted_access_is_required()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+        options.RequireAuthenticatedAccess = true;
+        options.ApiKey = "YOUR_DEMO_API_KEY";
+
+        var result = validator.Validate(null, options);
+
+        result.Failed.Should().BeTrue();
+        result.Failures.Should().Contain(item => item.Contains("ApiKey cannot use placeholder"));
+    }
+
+    [Fact]
+    public void Validate_rejects_missing_csrf_values_when_csrf_protection_is_enabled()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+        options.RequireCsrfHeader = true;
+        options.CsrfHeaderName = string.Empty;
+        options.CsrfHeaderValue = string.Empty;
+
+        var result = validator.Validate(null, options);
+
+        result.Failed.Should().BeTrue();
+        result.Failures.Should().Contain(item => item.Contains("CsrfHeaderName is required"));
+        result.Failures.Should().Contain(item => item.Contains("CsrfHeaderValue is required"));
+    }
+
+    [Fact]
+    public void Validate_rejects_placeholder_csrf_value_when_csrf_protection_is_enabled()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+        options.RequireCsrfHeader = true;
+        options.CsrfHeaderValue = "YOUR_DEMO_CSRF_TOKEN";
+
+        var result = validator.Validate(null, options);
+
+        result.Failed.Should().BeTrue();
+        result.Failures.Should().Contain(item => item.Contains("CsrfHeaderValue cannot use placeholder"));
+    }
+
+    [Fact]
+    public void Validate_accepts_secure_sandbox_defaults()
+    {
+        var validator = new DemoUiSecurityOptionsValidator();
+        var options = NewOptions();
+
+        var result = validator.Validate(null, options);
+
+        result.Succeeded.Should().BeTrue();
+    }
+
+    private static DemoUiSecurityOptions NewOptions() => new()
+    {
+        RequireAuthenticatedAccess = true,
+        ApiKey = "demo-api-key",
+        Mode = DemoRuntimeMode.Sandbox,
+        AllowLiveMode = false,
+        RequireCsrfHeader = true,
+        CsrfHeaderName = "X-Console-CSRF",
+        CsrfHeaderValue = "csrf-token",
+        RequestsPerMinute = 60
+    };
+}