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

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

tests/php/Unit/Event/BruteForceDetectedEventTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Event;
+
+use KTXC\Security\Event\BruteForceDetectedEvent;
+use KTXC\Security\Event\SecurityEvent;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+final class BruteForceDetectedEventTest extends TestCase
+{
+    #[Test]
+    #[TestDox('Brute-force detection state is typed and complete at construction')]
+    public function constructsTypedState(): void
+    {
+        $event = new BruteForceDetectedEvent(
+            '203.0.113.10',
+            5,
+            300,
+            'tenant-a',
+        );
+
+        self::assertSame(BruteForceDetectedEvent::class, $event->getName());
+        self::assertSame('203.0.113.10', $event->getIpAddress());
+        self::assertSame(5, $event->getFailureCount());
+        self::assertSame(300, $event->getWindowSeconds());
+        self::assertSame('tenant-a', $event->getTenantId());
+        self::assertSame('5 failed attempts in 300 seconds', $event->getReason());
+        self::assertSame(
+            ['failureCount' => 5, 'windowSeconds' => 300],
+            $event->getData(),
+        );
+        self::assertSame(SecurityEvent::SEVERITY_CRITICAL, $event->getSeverity());
+    }
+
+    #[Test]
+    #[TestDox('Brute-force detection rejects invalid measurements')]
+    public function rejectsInvalidMeasurements(): void
+    {
+        foreach ([
+            ['', 5, 300],
+            ['203.0.113.10', 0, 300],
+            ['203.0.113.10', 5, 0],
+        ] as $arguments) {
+            try {
+                new BruteForceDetectedEvent(...$arguments);
+                self::fail('Invalid brute-force measurements were accepted.');
+            } catch (\InvalidArgumentException) {
+                $this->addToAssertionCount(1);
+            }
+        }
+    }
+}

tests/php/Unit/Module/CoreModuleTest.php

@@ -17,6 +17,7 @@ use KTXC\Service\SystemFirewallStatusService;
 use KTXC\Service\TenantFirewallRuleService;
 use KTXC\Event\EventListenerRegistry;
 use KTXC\Security\Event\AuthenticationFailedEvent;
+use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXF\Event\DeliveryMode;
 use PHPUnit\Framework\Attributes\Test;
@@ -43,6 +44,7 @@ final class CoreModuleTest extends TestCase
         );
         self::assertSame([], $registry->listeners(AuthenticationFailedEvent::class, DeliveryMode::Deferred));
         foreach ([
+            BruteForceDetectedEvent::class,
             SecurityEvent::RATE_LIMIT_EXCEEDED,
             SecurityEvent::SUSPICIOUS_ACTIVITY,
             SecurityEvent::FIREWALL_RULE_CREATED,

tests/php/Unit/Service/FirewallServiceTest.php

@@ -11,6 +11,7 @@ use KTXC\Models\Firewall\FirewallRuleObject;
 use KTXC\Models\Firewall\FirewallLogObject;
 use KTXC\Models\Tenant\TenantConfiguration;
 use KTXC\Security\Event\AuthenticationFailedEvent;
+use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Service\FirewallService;
 use KTXC\Service\FirewallRuleCache;
 use KTXC\Service\FirewallRuleManager;
@@ -496,13 +497,18 @@ class FirewallServiceTest extends TestCase
 
         $publishedTenants = [];
         $lifecycleOrigin = null;
+        $bruteForceEvent = null;
         $this->events->expects($this->exactly(3))
             ->method('dispatch')
             ->willReturnCallback(static function (\KTXF\Event\Event $event) use (
                 &$publishedTenants,
-                &$lifecycleOrigin
+                &$lifecycleOrigin,
+                &$bruteForceEvent,
             ): void {
                 $publishedTenants[] = $event->getTenantId();
+                if ($event instanceof BruteForceDetectedEvent) {
+                    $bruteForceEvent = $event;
+                }
                 if ($event->getName() === \KTXC\Security\Event\SecurityEvent::FIREWALL_RULE_CREATED) {
                     $lifecycleOrigin = $event->get('origin');
                 }
@@ -512,6 +518,10 @@ class FirewallServiceTest extends TestCase
         $this->service->handleAuthFailure($event);
 
         self::assertSame(['tenant-event', 'tenant-event', 'tenant-event'], $publishedTenants);
+        self::assertInstanceOf(BruteForceDetectedEvent::class, $bruteForceEvent);
+        self::assertSame('203.0.113.10', $bruteForceEvent->getIpAddress());
+        self::assertSame(5, $bruteForceEvent->getFailureCount());
+        self::assertSame(300, $bruteForceEvent->getWindowSeconds());
         self::assertSame(FirewallRuleManager::ORIGIN_AUTOMATIC, $lifecycleOrigin);
     }