refactor(security): add typed access-denied event

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

core/lib/Module/Module.php

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

core/lib/Security/Event/AccessDeniedEvent.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXC\Security\Event;
+
+use KTXC\Models\Firewall\FirewallRuleObject;
+use KTXF\Event\Event;
+
+final class AccessDeniedEvent extends Event implements SecurityRequestEventInterface
+{
+    public function __construct(
+        private readonly string $ipAddress,
+        private readonly string $ruleId,
+        private readonly string $ruleScope,
+        private readonly ?string $deviceFingerprint = null,
+        private readonly ?string $reason = null,
+        ?string $tenantId = null,
+        ?string $identityId = null,
+    ) {
+        if ($ipAddress === '') {
+            throw new \InvalidArgumentException('Access denial requires an IP address.');
+        }
+        if ($ruleId === '') {
+            throw new \InvalidArgumentException('Access denial requires a firewall rule ID.');
+        }
+        if (!in_array($ruleScope, [FirewallRuleObject::SCOPE_SYSTEM, FirewallRuleObject::SCOPE_TENANT], true)) {
+            throw new \InvalidArgumentException('Access denial requires a valid firewall rule scope.');
+        }
+
+        parent::__construct(
+            self::class,
+            ['ruleId' => $ruleId, 'ruleScope' => $ruleScope, 'reason' => $reason],
+            $tenantId,
+            $identityId,
+        );
+    }
+
+    public function getIpAddress(): string
+    {
+        return $this->ipAddress;
+    }
+
+    public function getRuleId(): string
+    {
+        return $this->ruleId;
+    }
+
+    public function getRuleScope(): string
+    {
+        return $this->ruleScope;
+    }
+
+    public function getDeviceFingerprint(): ?string
+    {
+        return $this->deviceFingerprint;
+    }
+
+    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_WARNING;
+    }
+}

core/lib/Security/Event/SecurityEvent.php

@@ -17,7 +17,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
     public const TOKEN_REFRESH = 'security.token.refresh';
     public const TOKEN_REVOKED = 'security.token.revoked';
     
-    public const ACCESS_DENIED = 'security.access.denied';
     public const ACCESS_GRANTED = 'security.access.granted';
     
     public const RATE_LIMIT_EXCEEDED = 'security.rate_limit.exceeded';
@@ -137,29 +136,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
         );
     }
 
-    /**
-     * Create an access denied event
-     */
-    public static function accessDenied(
-        string $ipAddress,
-        ?string $deviceFingerprint = null,
-        ?string $ruleId = null,
-        ?string $ruleScope = null,
-        ?string $reason = null,
-        ?string $tenantId = null,
-        ?string $identityId = null,
-    ): self {
-        return self::create(
-            self::ACCESS_DENIED,
-            $ipAddress,
-            $deviceFingerprint,
-            ['ruleId' => $ruleId, 'ruleScope' => $ruleScope, 'reason' => $reason],
-            $tenantId,
-            $identityId,
-            reason: $reason,
-        );
-    }
-
     /**
      * Get default severity for event types
      */
@@ -170,7 +146,6 @@ final class SecurityEvent extends Event implements SecurityRequestEventInterface
             self::ACCESS_GRANTED,
             self::TOKEN_REFRESH => self::SEVERITY_INFO,
             
-            self::ACCESS_DENIED,
             self::AUTH_LOGOUT,
             self::TOKEN_REVOKED => self::SEVERITY_WARNING,
             

core/lib/Service/FirewallService.php

@@ -10,6 +10,7 @@ use KTXC\Models\Firewall\FirewallRuleObject;
 use KTXC\Models\Firewall\FirewallLogObject;
 use KTXC\Stores\FirewallStore;
 use KTXC\Context\TenantContextInterface;
+use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Security\Event\SecurityEvent;
@@ -283,7 +284,7 @@ class FirewallService
             SecurityEvent::AUTH_SUCCESS => FirewallLogObject::EVENT_ACCESS_CHECK,
             BruteForceDetectedEvent::class => FirewallLogObject::EVENT_BRUTE_FORCE,
             SecurityEvent::RATE_LIMIT_EXCEEDED => FirewallLogObject::EVENT_RATE_LIMIT,
-            SecurityEvent::ACCESS_DENIED => FirewallLogObject::EVENT_RULE_MATCH,
+            AccessDeniedEvent::class => FirewallLogObject::EVENT_RULE_MATCH,
             SecurityEvent::SUSPICIOUS_ACTIVITY => FirewallLogObject::EVENT_SUSPICIOUS,
             SecurityEvent::FIREWALL_RULE_CREATED => FirewallLogObject::EVENT_RULE_CREATED,
             SecurityEvent::FIREWALL_RULE_EXTENDED => FirewallLogObject::EVENT_RULE_EXTENDED,
@@ -321,13 +322,13 @@ class FirewallService
         ?string $deviceFingerprint,
         FirewallRuleObject $rule
     ): void {
-        $event = SecurityEvent::accessDenied(
+        $event = new AccessDeniedEvent(
-            $ipAddress,
+            ipAddress: $ipAddress,
-            $deviceFingerprint,
+            ruleId: $rule->getId(),
-            $rule->getId(),
+            ruleScope: $rule->getScope(),
-            $rule->getScope(),
+            deviceFingerprint: $deviceFingerprint,
-            $rule->getReason(),
+            reason: $rule->getReason(),
-            $this->tenantContext->identifier(),
+            tenantId: $this->tenantContext->identifier(),
         );
         $this->events->dispatch($event);
     }

tests/php/Unit/Event/AccessDeniedEventTest.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Event;
+
+use KTXC\Models\Firewall\FirewallRuleObject;
+use KTXC\Security\Event\AccessDeniedEvent;
+use KTXC\Security\Event\SecurityEvent;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+final class AccessDeniedEventTest extends TestCase
+{
+    #[Test]
+    #[TestDox('Access-denial state is typed and complete at construction')]
+    public function constructsTypedState(): void
+    {
+        $event = new AccessDeniedEvent(
+            '203.0.113.10',
+            'rule-a',
+            FirewallRuleObject::SCOPE_TENANT,
+            'device-a',
+            'Blocked by policy',
+            'tenant-a',
+            'identity-a',
+        );
+
+        self::assertSame(AccessDeniedEvent::class, $event->getName());
+        self::assertSame('203.0.113.10', $event->getIpAddress());
+        self::assertSame('device-a', $event->getDeviceFingerprint());
+        self::assertSame('rule-a', $event->getRuleId());
+        self::assertSame(FirewallRuleObject::SCOPE_TENANT, $event->getRuleScope());
+        self::assertSame('Blocked by policy', $event->getReason());
+        self::assertSame('tenant-a', $event->getTenantId());
+        self::assertSame('identity-a', $event->getIdentityId());
+        self::assertSame(SecurityEvent::SEVERITY_WARNING, $event->getSeverity());
+    }
+
+    #[Test]
+    #[TestDox('Access denial rejects incomplete rule context')]
+    public function rejectsIncompleteRuleContext(): void
+    {
+        foreach ([
+            ['', 'rule-a', FirewallRuleObject::SCOPE_TENANT],
+            ['203.0.113.10', '', FirewallRuleObject::SCOPE_TENANT],
+            ['203.0.113.10', 'rule-a', 'unknown'],
+        ] as $arguments) {
+            try {
+                new AccessDeniedEvent(...$arguments);
+                self::fail('Incomplete access-denial context was accepted.');
+            } catch (\InvalidArgumentException) {
+                $this->addToAssertionCount(1);
+            }
+        }
+    }
+}

tests/php/Unit/Module/CoreModuleTest.php

@@ -16,6 +16,7 @@ use KTXC\Service\TenantFirewallStatusService;
 use KTXC\Service\SystemFirewallStatusService;
 use KTXC\Service\TenantFirewallRuleService;
 use KTXC\Event\EventListenerRegistry;
+use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Security\Event\SecurityEvent;
@@ -44,6 +45,7 @@ final class CoreModuleTest extends TestCase
         );
         self::assertSame([], $registry->listeners(AuthenticationFailedEvent::class, DeliveryMode::Deferred));
         foreach ([
+            AccessDeniedEvent::class,
             BruteForceDetectedEvent::class,
             SecurityEvent::RATE_LIMIT_EXCEEDED,
             SecurityEvent::SUSPICIOUS_ACTIVITY,

tests/php/Unit/Service/FirewallServiceTest.php

@@ -10,6 +10,7 @@ use KTXC\Http\Request\RequestContext;
 use KTXC\Models\Firewall\FirewallRuleObject;
 use KTXC\Models\Firewall\FirewallLogObject;
 use KTXC\Models\Tenant\TenantConfiguration;
+use KTXC\Security\Event\AccessDeniedEvent;
 use KTXC\Security\Event\AuthenticationFailedEvent;
 use KTXC\Security\Event\BruteForceDetectedEvent;
 use KTXC\Service\FirewallService;
@@ -86,7 +87,15 @@ class FirewallServiceTest extends TestCase
 
         $this->store->expects($this->once())->method('listSystemRules')->willReturn([$systemBlock]);
         $this->store->expects($this->once())->method('listRules')->with('tenant-a')->willReturn([$tenantAllow]);
-        $this->events->expects($this->once())->method('dispatch');
+        $this->events->expects($this->once())
+            ->method('dispatch')
+            ->with(self::callback(static function ($event): bool {
+                return $event instanceof AccessDeniedEvent
+                    && $event->getIpAddress() === '203.0.113.10'
+                    && $event->getRuleId() === 'system-block'
+                    && $event->getRuleScope() === FirewallRuleObject::SCOPE_SYSTEM
+                    && $event->getReason() === 'system-block';
+            }));
 
         $result = $this->service->analyze('203.0.113.10');
 
@@ -226,13 +235,12 @@ class FirewallServiceTest extends TestCase
                     && $log->getEventType() === FirewallLogObject::EVENT_RULE_MATCH;
             }))
             ->willReturnArgument(0);
-        $event = \KTXC\Security\Event\SecurityEvent::accessDenied(
+        $event = new AccessDeniedEvent(
-            '203.0.113.10',
+            ipAddress: '203.0.113.10',
-            null,
+            ruleId: 'tenant-rule',
-            'tenant-rule',
+            ruleScope: FirewallRuleObject::SCOPE_TENANT,
-            FirewallRuleObject::SCOPE_TENANT,
+            reason: 'Tenant block',
-            'Tenant block',
+            tenantId: 'tenant-a',
-            'tenant-a',
         );
 
         $this->service->logSecurityEvent($event);
@@ -250,12 +258,11 @@ class FirewallServiceTest extends TestCase
                     && $log->getRuleScope() === FirewallRuleObject::SCOPE_SYSTEM;
             }))
             ->willReturnArgument(0);
-        $event = \KTXC\Security\Event\SecurityEvent::accessDenied(
+        $event = new AccessDeniedEvent(
-            '203.0.113.10',
+            ipAddress: '203.0.113.10',
-            null,
+            ruleId: 'system-rule',
-            'system-rule',
+            ruleScope: FirewallRuleObject::SCOPE_SYSTEM,
-            FirewallRuleObject::SCOPE_SYSTEM,
+            reason: 'System block',
-            'System block'
         );
 
         $this->service->logSecurityEvent($event);