refactor(security): add typed rate-limit event

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

core/lib/Module/Module.php

@@ -14,6 +14,7 @@ use KTXC\Service\TenantFirewallStatusService;
 use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
+use KTXC\Security\Event\RateLimitExceededEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXF\Event\DeliveryMode;
 use KTXF\Event\EventListenerRegistrarInterface;
@@ -48,7 +49,7 @@ class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, M
             SecurityEvent::AUTH_SUCCESS,
             AccessDeniedEvent::class,
             BruteForceDetectedEvent::class,
-            SecurityEvent::RATE_LIMIT_EXCEEDED,
+            RateLimitExceededEvent::class,
             SecurityEvent::SUSPICIOUS_ACTIVITY,
             SecurityEvent::FIREWALL_RULE_CREATED,
             SecurityEvent::FIREWALL_RULE_EXTENDED,

core/lib/Security/Event/RateLimitExceededEvent.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXC\Security\Event;
+
+use KTXF\Event\Event;
+
+final class RateLimitExceededEvent extends Event implements SecurityRequestEventInterface
+{
+    private readonly string $reason;
+
+    public function __construct(
+        private readonly string $ipAddress,
+        private readonly int $requestCount,
+        private readonly int $windowSeconds,
+        private readonly ?string $endpoint = null,
+        ?string $tenantId = null,
+    ) {
+        if ($ipAddress === '') {
+            throw new \InvalidArgumentException('Rate-limit detection requires an IP address.');
+        }
+        if ($requestCount < 1) {
+            throw new \InvalidArgumentException('Rate-limit detection requires at least one request.');
+        }
+        if ($windowSeconds < 1) {
+            throw new \InvalidArgumentException('Rate-limit detection requires a positive window.');
+        }
+        if ($endpoint === '') {
+            throw new \InvalidArgumentException('A supplied rate-limit endpoint cannot be empty.');
+        }
+
+        $this->reason = sprintf(
+            '%d requests in %d seconds',
+            $requestCount,
+            $windowSeconds,
+        );
+
+        parent::__construct(
+            self::class,
+            [
+                'requestCount' => $requestCount,
+                'windowSeconds' => $windowSeconds,
+                'endpoint' => $endpoint,
+            ],
+            $tenantId,
+        );
+    }
+
+    public function getIpAddress(): string
+    {
+        return $this->ipAddress;
+    }
+
+    public function getRequestCount(): int
+    {
+        return $this->requestCount;
+    }
+
+    public function getWindowSeconds(): int
+    {
+        return $this->windowSeconds;
+    }
+
+    public function getEndpoint(): ?string
+    {
+        return $this->endpoint;
+    }
+
+    public function getDeviceFingerprint(): ?string
+    {
+        return null;
+    }
+
+    public function getUserAgent(): ?string
+    {
+        return null;
+    }
+
+    public function getRequestPath(): ?string
+    {
+        return $this->endpoint;
+    }
+
+    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_ERROR;
+    }
+}

core/lib/Security/Event/SecurityEvent.php

@@ -19,7 +19,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
     
     public const ACCESS_GRANTED = 'security.access.granted';
     
-    public const RATE_LIMIT_EXCEEDED = 'security.rate_limit.exceeded';
     public const SUSPICIOUS_ACTIVITY = 'security.suspicious.activity';
     
     public const IP_BLOCKED = 'security.ip.blocked';
@@ -112,30 +111,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
         );
     }
 
-    /**
-     * Create a rate limit exceeded event
-     */
-    public static function rateLimitExceeded(
-        string $ipAddress,
-        int $requestCount,
-        int $windowSeconds,
-        ?string $endpoint = null,
-        ?string $tenantId = null,
-    ): self {
-        return self::create(
-            self::RATE_LIMIT_EXCEEDED,
-            $ipAddress,
-            data: [
-                'requestCount' => $requestCount,
-                'windowSeconds' => $windowSeconds,
-                'endpoint' => $endpoint,
-            ],
-            tenantId: $tenantId,
-            requestPath: $endpoint,
-            reason: sprintf('%d requests in %d seconds', $requestCount, $windowSeconds),
-        );
-    }
-
     /**
      * Get default severity for event types
      */
@@ -149,7 +124,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
             self::AUTH_LOGOUT,
             self::TOKEN_REVOKED => self::SEVERITY_WARNING,
             
-            self::RATE_LIMIT_EXCEEDED,
             self::SUSPICIOUS_ACTIVITY => self::SEVERITY_ERROR,
             
             self::IP_BLOCKED,

core/lib/Service/FirewallService.php

@@ -13,6 +13,7 @@ use KTXC\Context\TenantContextInterface;
 use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
+use KTXC\Security\Event\RateLimitExceededEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXC\Security\Event\SecurityEventInterface;
 use KTXC\Security\Event\SecurityRequestEventInterface;
@@ -283,7 +284,7 @@ class FirewallService
             AuthenticationFailedEvent::class => FirewallLogObject::EVENT_AUTH_FAILURE,
             SecurityEvent::AUTH_SUCCESS => FirewallLogObject::EVENT_ACCESS_CHECK,
             BruteForceDetectedEvent::class => FirewallLogObject::EVENT_BRUTE_FORCE,
-            SecurityEvent::RATE_LIMIT_EXCEEDED => FirewallLogObject::EVENT_RATE_LIMIT,
+            RateLimitExceededEvent::class => FirewallLogObject::EVENT_RATE_LIMIT,
             AccessDeniedEvent::class => FirewallLogObject::EVENT_RULE_MATCH,
             SecurityEvent::SUSPICIOUS_ACTIVITY => FirewallLogObject::EVENT_SUSPICIOUS,
             SecurityEvent::FIREWALL_RULE_CREATED => FirewallLogObject::EVENT_RULE_CREATED,

tests/php/Unit/Event/RateLimitExceededEventTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Event;
+
+use KTXC\Security\Event\RateLimitExceededEvent;
+use KTXC\Security\Event\SecurityEvent;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+final class RateLimitExceededEventTest extends TestCase
+{
+    #[Test]
+    #[TestDox('Rate-limit state is typed and complete at construction')]
+    public function constructsTypedState(): void
+    {
+        $event = new RateLimitExceededEvent(
+            '203.0.113.10',
+            101,
+            60,
+            '/login',
+            'tenant-a',
+        );
+
+        self::assertSame(RateLimitExceededEvent::class, $event->getName());
+        self::assertSame('203.0.113.10', $event->getIpAddress());
+        self::assertSame(101, $event->getRequestCount());
+        self::assertSame(60, $event->getWindowSeconds());
+        self::assertSame('/login', $event->getEndpoint());
+        self::assertSame('/login', $event->getRequestPath());
+        self::assertSame('tenant-a', $event->getTenantId());
+        self::assertSame('101 requests in 60 seconds', $event->getReason());
+        self::assertSame(SecurityEvent::SEVERITY_ERROR, $event->getSeverity());
+    }
+
+    #[Test]
+    #[TestDox('Rate-limit detection rejects invalid measurements')]
+    public function rejectsInvalidMeasurements(): void
+    {
+        foreach ([
+            ['', 101, 60, '/login'],
+            ['203.0.113.10', 0, 60, '/login'],
+            ['203.0.113.10', 101, 0, '/login'],
+            ['203.0.113.10', 101, 60, ''],
+        ] as $arguments) {
+            try {
+                new RateLimitExceededEvent(...$arguments);
+                self::fail('Invalid rate-limit measurements were accepted.');
+            } catch (\InvalidArgumentException) {
+                $this->addToAssertionCount(1);
+            }
+        }
+    }
+}

tests/php/Unit/Event/SecurityEventTest.php

@@ -21,7 +21,7 @@ final class SecurityEventTest extends TestCase
         );
         self::assertSame(
             SecurityEvent::SEVERITY_ERROR,
-            (new SecurityEvent(SecurityEvent::RATE_LIMIT_EXCEEDED))->getSeverity(),
+            (new SecurityEvent(SecurityEvent::SUSPICIOUS_ACTIVITY))->getSeverity(),
         );
         self::assertSame(
             SecurityEvent::SEVERITY_CRITICAL,

tests/php/Unit/Module/CoreModuleTest.php

@@ -19,6 +19,7 @@ use KTXC\Event\EventListenerRegistry;
 use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
+use KTXC\Security\Event\RateLimitExceededEvent;
 use KTXC\Security\Event\SecurityEvent;
 use KTXF\Event\DeliveryMode;
 use PHPUnit\Framework\Attributes\Test;
@@ -47,7 +48,7 @@ final class CoreModuleTest extends TestCase
         foreach ([
             AccessDeniedEvent::class,
             BruteForceDetectedEvent::class,
-            SecurityEvent::RATE_LIMIT_EXCEEDED,
+            RateLimitExceededEvent::class,
             SecurityEvent::SUSPICIOUS_ACTIVITY,
             SecurityEvent::FIREWALL_RULE_CREATED,
             SecurityEvent::FIREWALL_RULE_EXTENDED,

tests/php/Unit/Service/FirewallServiceTest.php

@@ -13,6 +13,7 @@ use KTXC\Models\Tenant\TenantConfiguration;
 use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
+use KTXC\Security\Event\RateLimitExceededEvent;
 use KTXC\Service\FirewallService;
 use KTXC\Service\FirewallRuleCache;
 use KTXC\Service\FirewallRuleManager;
@@ -294,7 +295,7 @@ class FirewallServiceTest extends TestCase
                     && $metadata['windowSeconds'] === 60;
             }))
             ->willReturnArgument(0);
-        $event = \KTXC\Security\Event\SecurityEvent::rateLimitExceeded(
+        $event = new RateLimitExceededEvent(
             '203.0.113.10',
             101,
             60,