refactor(security): add typed brute-force detection event

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

core/lib/Module/Module.php

@@ -12,6 +12,7 @@ use KTXC\Service\TenantFirewallLogService;
 use KTXC\Service\TenantFirewallRuleService;
 use KTXC\Service\TenantFirewallStatusService;
 use KTXC\Security\Event\AuthenticationFailedEvent;
+use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXF\Event\DeliveryMode;
 use KTXF\Event\EventListenerRegistrarInterface;
@@ -45,7 +46,7 @@ class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, M
         foreach ([
             SecurityEvent::AUTH_SUCCESS,
             SecurityEvent::ACCESS_DENIED,
-            SecurityEvent::BRUTE_FORCE_DETECTED,
+            BruteForceDetectedEvent::class,
             SecurityEvent::RATE_LIMIT_EXCEEDED,
             SecurityEvent::SUSPICIOUS_ACTIVITY,
             SecurityEvent::FIREWALL_RULE_CREATED,

core/lib/Security/Event/BruteForceDetectedEvent.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXC\Security\Event;
+
+use KTXF\Event\Event;
+
+final class BruteForceDetectedEvent extends Event implements SecurityRequestEventInterface
+{
+    private readonly string $reason;
+
+    public function __construct(
+        private readonly string $ipAddress,
+        private readonly int $failureCount,
+        private readonly int $windowSeconds,
+        ?string $tenantId = null,
+    ) {
+        if ($ipAddress === '') {
+            throw new \InvalidArgumentException('Brute-force detection requires an IP address.');
+        }
+        if ($failureCount < 1) {
+            throw new \InvalidArgumentException('Brute-force detection requires at least one failure.');
+        }
+        if ($windowSeconds < 1) {
+            throw new \InvalidArgumentException('Brute-force detection requires a positive window.');
+        }
+
+        $this->reason = sprintf(
+            '%d failed attempts in %d seconds',
+            $failureCount,
+            $windowSeconds,
+        );
+
+        parent::__construct(
+            self::class,
+            ['failureCount' => $failureCount, 'windowSeconds' => $windowSeconds],
+            $tenantId,
+        );
+    }
+
+    public function getIpAddress(): string
+    {
+        return $this->ipAddress;
+    }
+
+    public function getFailureCount(): int
+    {
+        return $this->failureCount;
+    }
+
+    public function getWindowSeconds(): int
+    {
+        return $this->windowSeconds;
+    }
+
+    public function getDeviceFingerprint(): ?string
+    {
+        return null;
+    }
+
+    public function getUserAgent(): ?string
+    {
+        return null;
+    }
+
+    public function getRequestPath(): ?string
+    {
+        return null;
+    }
+
+    public function getRequestMethod(): ?string
+    {
+        return null;
+    }
+
+    public function getUserId(): ?string
+    {
+        return null;
+    }
+
+    public function getReason(): string
+    {
+        return $this->reason;
+    }
+
+    public function getSeverity(): int
+    {
+        return SecurityEvent::SEVERITY_CRITICAL;
+    }
+}

core/lib/Security/Event/SecurityEvent.php

@@ -20,7 +20,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
     public const ACCESS_DENIED = 'security.access.denied';
     public const ACCESS_GRANTED = 'security.access.granted';
     
-    public const BRUTE_FORCE_DETECTED = 'security.brute_force.detected';
     public const RATE_LIMIT_EXCEEDED = 'security.rate_limit.exceeded';
     public const SUSPICIOUS_ACTIVITY = 'security.suspicious.activity';
     
@@ -114,24 +113,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
         );
     }
 
-    /**
-     * Create a brute force detection event
-     */
-    public static function bruteForceDetected(
-        string $ipAddress,
-        int $failureCount,
-        int $windowSeconds,
-        ?string $tenantId = null,
-    ): self {
-        return self::create(
-            self::BRUTE_FORCE_DETECTED,
-            $ipAddress,
-            data: ['failureCount' => $failureCount, 'windowSeconds' => $windowSeconds],
-            tenantId: $tenantId,
-            reason: sprintf('%d failed attempts in %d seconds', $failureCount, $windowSeconds),
-        );
-    }
-
     /**
      * Create a rate limit exceeded event
      */
@@ -196,7 +177,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
             self::RATE_LIMIT_EXCEEDED,
             self::SUSPICIOUS_ACTIVITY => self::SEVERITY_ERROR,
             
-            self::BRUTE_FORCE_DETECTED,
             self::IP_BLOCKED,
             self::DEVICE_BLOCKED => self::SEVERITY_CRITICAL,
             

core/lib/Service/FirewallService.php

@@ -11,6 +11,7 @@ use KTXC\Models\Firewall\FirewallLogObject;
 use KTXC\Stores\FirewallStore;
 use KTXC\Context\TenantContextInterface;
 use KTXC\Security\Event\AuthenticationFailedEvent;
+use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXC\Security\Event\SecurityEventInterface;
 use KTXC\Security\Event\SecurityRequestEventInterface;
@@ -200,7 +201,7 @@ class FirewallService
         int $blockDuration
     ): void {
         // Publish brute force event
-        $event = SecurityEvent::bruteForceDetected(
+        $event = new BruteForceDetectedEvent(
             $ipAddress,
             $failureCount,
             $windowSeconds,
@@ -280,7 +281,7 @@ class FirewallService
         return match ($eventName) {
             AuthenticationFailedEvent::class => FirewallLogObject::EVENT_AUTH_FAILURE,
             SecurityEvent::AUTH_SUCCESS => FirewallLogObject::EVENT_ACCESS_CHECK,
-            SecurityEvent::BRUTE_FORCE_DETECTED => FirewallLogObject::EVENT_BRUTE_FORCE,
+            BruteForceDetectedEvent::class => FirewallLogObject::EVENT_BRUTE_FORCE,
             SecurityEvent::RATE_LIMIT_EXCEEDED => FirewallLogObject::EVENT_RATE_LIMIT,
             SecurityEvent::ACCESS_DENIED => FirewallLogObject::EVENT_RULE_MATCH,
             SecurityEvent::SUSPICIOUS_ACTIVITY => FirewallLogObject::EVENT_SUSPICIOUS,