feat(firewall): add operational status reads

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

tests/php/Unit/Controllers/FirewallControllerTest.php

@@ -9,11 +9,14 @@ use KTXC\Context\TenantContextInterface;
 use KTXC\Controllers\FirewallController;
 use KTXC\Service\FirewallRuleCache;
 use KTXC\Service\FirewallRuleManager;
+use KTXC\Service\FirewallStatusService;
 use KTXC\Service\FirewallLogService;
 use KTXC\Service\SystemFirewallLogService;
 use KTXC\Service\SystemFirewallRuleService;
+use KTXC\Service\SystemFirewallStatusService;
 use KTXC\Service\TenantFirewallLogService;
 use KTXC\Service\TenantFirewallRuleService;
+use KTXC\Service\TenantFirewallStatusService;
 use KTXC\Stores\FirewallStore;
 use KTXF\Event\EventDispatcherInterface;
 use KTXF\Routing\Attributes\AuthenticatedRoute;
@@ -43,7 +46,9 @@ final class FirewallControllerTest extends TestCase
             new TenantFirewallRuleService($manager, $tenant, $identity),
             new SystemFirewallRuleService($manager, $identity),
             new TenantFirewallLogService(new FirewallLogService($this->store), $tenant, $identity),
-            new SystemFirewallLogService(new FirewallLogService($this->store), $identity)
+            new SystemFirewallLogService(new FirewallLogService($this->store), $identity),
+            new TenantFirewallStatusService(new FirewallStatusService($this->store), $tenant, $identity),
+            new SystemFirewallStatusService(new FirewallStatusService($this->store), $identity)
         );
     }
 
@@ -72,6 +77,18 @@ final class FirewallControllerTest extends TestCase
         self::assertSame(400, $this->controller->systemRules(limit: '101')->getStatusCode());
     }
 
+    #[TestDox('Metric endpoints return scoped counts and stable validation errors')]
+    public function testMetrics(): void
+    {
+        $this->store->method('countBlockedRequests')->willReturn(4);
+
+        $response = $this->controller->tenantMetrics();
+        $data = json_decode($response->getContent(), true, flags: JSON_THROW_ON_ERROR);
+
+        self::assertSame(4, $data['blockedRequests']);
+        self::assertSame(400, $this->controller->systemMetrics(since: 'not-a-date')->getStatusCode());
+    }
+
     #[TestDox('Every rule endpoint declares its scope-specific read permission')]
     public function testRoutePermissions(): void
     {
@@ -83,6 +100,10 @@ final class FirewallControllerTest extends TestCase
             'systemRule' => SystemFirewallRuleService::PERMISSION_READ,
             'tenantLogs' => TenantFirewallLogService::PERMISSION_READ,
             'systemLogs' => SystemFirewallLogService::PERMISSION_READ,
+            'tenantMetrics' => TenantFirewallLogService::PERMISSION_READ,
+            'tenantConfiguration' => TenantFirewallStatusService::PERMISSION_SETTINGS_READ,
+            'systemMetrics' => SystemFirewallLogService::PERMISSION_READ,
+            'maintenanceStatus' => SystemFirewallStatusService::PERMISSION_MAINTENANCE_READ,
         ];
 
         foreach ($expected as $method => $permission) {

tests/php/Unit/Module/CoreModuleTest.php

@@ -12,6 +12,8 @@ use KTXC\Service\FirewallService;
 use KTXC\Service\SystemFirewallRuleService;
 use KTXC\Service\SystemFirewallLogService;
 use KTXC\Service\TenantFirewallLogService;
+use KTXC\Service\TenantFirewallStatusService;
+use KTXC\Service\SystemFirewallStatusService;
 use KTXC\Service\TenantFirewallRuleService;
 use KTXF\Event\DeliveryMode;
 use KTXF\Event\EventListenerRegistry;
@@ -78,5 +80,7 @@ final class CoreModuleTest extends TestCase
         self::assertArrayHasKey(TenantFirewallRuleService::PERMISSION_MANAGE, $permissions);
         self::assertArrayHasKey(TenantFirewallLogService::PERMISSION_READ, $permissions);
         self::assertArrayHasKey(SystemFirewallLogService::PERMISSION_READ, $permissions);
+        self::assertArrayHasKey(TenantFirewallStatusService::PERMISSION_SETTINGS_READ, $permissions);
+        self::assertArrayHasKey(SystemFirewallStatusService::PERMISSION_MAINTENANCE_READ, $permissions);
     }
 }

tests/php/Unit/Service/FirewallStatusServicesTest.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Service;
+
+use KTXC\Context\IdentityContextInterface;
+use KTXC\Context\TenantContextInterface;
+use KTXC\Models\Tenant\TenantConfiguration;
+use KTXC\Service\FirewallStatusService;
+use KTXC\Service\SystemFirewallLogService;
+use KTXC\Service\SystemFirewallStatusService;
+use KTXC\Service\TenantFirewallLogService;
+use KTXC\Service\TenantFirewallStatusService;
+use KTXC\Stores\FirewallStore;
+use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+#[AllowMockObjectsWithoutExpectations]
+final class FirewallStatusServicesTest extends TestCase
+{
+    #[TestDox('Tenant metrics and configuration derive their tenant context')]
+    public function testTenantStatus(): void
+    {
+        $store = $this->createMock(FirewallStore::class);
+        $tenant = $this->createStub(TenantContextInterface::class);
+        $tenant->method('requireIdentifier')->willReturn('tenant-a');
+        $tenant->method('configuration')->willReturn(
+            (new TenantConfiguration())->jsonDeserialize([
+                'firewall' => ['enabled' => false, 'maxAuthFailures' => 8],
+            ])
+        );
+        $identity = $this->createStub(IdentityContextInterface::class);
+        $identity->method('hasPermission')->willReturn(true);
+        $store->expects(self::once())
+            ->method('countBlockedRequests')
+            ->with('tenant-a', self::isInstanceOf(\DateTimeImmutable::class))
+            ->willReturn(7);
+        $service = new TenantFirewallStatusService(new FirewallStatusService($store), $tenant, $identity);
+
+        self::assertSame(7, $service->metrics('2026-08-01T00:00:00+00:00')['blockedRequests']);
+        self::assertFalse($service->configuration()['enabled']);
+        self::assertSame(8, $service->configuration()['maxAuthFailures']);
+    }
+
+    #[TestDox('System metrics and maintenance status expose operational state')]
+    public function testSystemStatus(): void
+    {
+        $store = $this->createMock(FirewallStore::class);
+        $identity = $this->createStub(IdentityContextInterface::class);
+        $identity->method('hasPermission')->willReturn(true);
+        $store->expects(self::once())
+            ->method('countSystemBlockedRequests')
+            ->with('tenant-a', null)
+            ->willReturn(12);
+        $store->method('maintenanceStatus')->willReturn(['status' => 'success']);
+        $service = new SystemFirewallStatusService(new FirewallStatusService($store), $identity);
+
+        self::assertSame(12, $service->metrics('tenant-a')['blockedRequests']);
+        self::assertSame('success', $service->maintenanceStatus()['status']);
+    }
+
+    #[TestDox('Maintenance reports an explicit state before its first run')]
+    public function testNeverRunStatus(): void
+    {
+        $store = $this->createStub(FirewallStore::class);
+
+        self::assertSame('never_run', (new FirewallStatusService($store))->maintenanceStatus()['status']);
+    }
+
+    #[TestDox('Status reads require their dedicated permissions')]
+    public function testPermissions(): void
+    {
+        $store = $this->createMock(FirewallStore::class);
+        $identity = $this->createStub(IdentityContextInterface::class);
+        $identity->method('hasPermission')->willReturn(false);
+        $tenant = $this->createStub(TenantContextInterface::class);
+        $store->expects(self::never())->method('countBlockedRequests');
+        $store->expects(self::never())->method('maintenanceStatus');
+
+        try {
+            (new TenantFirewallStatusService(new FirewallStatusService($store), $tenant, $identity))->metrics();
+            self::fail('Tenant metrics should be rejected.');
+        } catch (\RuntimeException $error) {
+            self::assertStringContainsString(TenantFirewallLogService::PERMISSION_READ, $error->getMessage());
+        }
+
+        $this->expectExceptionMessage(SystemFirewallStatusService::PERMISSION_MAINTENANCE_READ);
+        (new SystemFirewallStatusService(new FirewallStatusService($store), $identity))->maintenanceStatus();
+    }
+
+    #[TestDox('Metrics reject invalid dates before querying storage')]
+    public function testMetricValidation(): void
+    {
+        $store = $this->createMock(FirewallStore::class);
+        $store->expects(self::never())->method('countSystemBlockedRequests');
+        $this->expectException(\InvalidArgumentException::class);
+
+        (new FirewallStatusService($store))->systemMetrics(null, 'not-a-date');
+    }
+}