feat(firewall): add scoped rule administration reads

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

tests/php/Unit/Controllers/FirewallControllerTest.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Controllers;
+
+use KTXC\Context\IdentityContextInterface;
+use KTXC\Context\TenantContextInterface;
+use KTXC\Controllers\FirewallController;
+use KTXC\Service\FirewallRuleCache;
+use KTXC\Service\FirewallRuleManager;
+use KTXC\Service\SystemFirewallRuleService;
+use KTXC\Service\TenantFirewallRuleService;
+use KTXC\Stores\FirewallStore;
+use KTXF\Event\EventDispatcherInterface;
+use KTXF\Routing\Attributes\AuthenticatedRoute;
+use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+#[AllowMockObjectsWithoutExpectations]
+final class FirewallControllerTest extends TestCase
+{
+    private FirewallStore $store;
+    private FirewallController $controller;
+
+    protected function setUp(): void
+    {
+        $this->store = $this->createMock(FirewallStore::class);
+        $tenant = $this->createMock(TenantContextInterface::class);
+        $tenant->method('requireIdentifier')->willReturn('tenant-a');
+        $identity = $this->createMock(IdentityContextInterface::class);
+        $identity->method('hasPermission')->willReturn(true);
+        $manager = new FirewallRuleManager(
+            $this->store,
+            new FirewallRuleCache($this->store),
+            $this->createStub(EventDispatcherInterface::class)
+        );
+        $this->controller = new FirewallController(
+            new TenantFirewallRuleService($manager, $tenant, $identity),
+            new SystemFirewallRuleService($manager, $identity)
+        );
+    }
+
+    #[TestDox('Tenant rule endpoint returns bounded paginated results')]
+    public function testTenantRules(): void
+    {
+        $this->store->expects(self::once())
+            ->method('queryRules')
+            ->with('tenant', 'tenant-a', 'active', null, null, 25, 10)
+            ->willReturn(['items' => [], 'total' => 0, 'limit' => 25, 'offset' => 10]);
+
+        $response = $this->controller->tenantRules(limit: '25', offset: '10');
+        $data = json_decode($response->getContent(), true, flags: JSON_THROW_ON_ERROR);
+
+        self::assertSame(200, $response->getStatusCode());
+        self::assertSame(25, $data['limit']);
+        self::assertSame(10, $data['offset']);
+    }
+
+    #[TestDox('Rule endpoints reject malformed and excessive pagination')]
+    public function testPaginationValidation(): void
+    {
+        $this->store->expects(self::never())->method('queryRules');
+
+        self::assertSame(400, $this->controller->tenantRules(limit: 'invalid')->getStatusCode());
+        self::assertSame(400, $this->controller->systemRules(limit: '101')->getStatusCode());
+    }
+
+    #[TestDox('Every rule endpoint declares its scope-specific read permission')]
+    public function testRoutePermissions(): void
+    {
+        $expected = [
+            'tenantRules' => TenantFirewallRuleService::PERMISSION_READ,
+            'tenantRule' => TenantFirewallRuleService::PERMISSION_READ,
+            'effectivePolicy' => TenantFirewallRuleService::PERMISSION_READ,
+            'systemRules' => SystemFirewallRuleService::PERMISSION_READ,
+            'systemRule' => SystemFirewallRuleService::PERMISSION_READ,
+        ];
+
+        foreach ($expected as $method => $permission) {
+            $attributes = (new \ReflectionMethod(FirewallController::class, $method))
+                ->getAttributes(AuthenticatedRoute::class);
+            self::assertCount(1, $attributes);
+            self::assertSame([$permission], $attributes[0]->newInstance()->permissions);
+        }
+    }
+}

tests/php/Unit/Service/FirewallRuleManagerTest.php

@@ -91,6 +91,59 @@ class FirewallRuleManagerTest extends TestCase
         self::assertFalse($this->manager->remove(FirewallRuleScope::tenant('tenant-b'), 'tenant-rule'));
     }
 
+    #[TestDox('Rule queries retain scope, filters, and bounded pagination')]
+    public function testRuleQuery(): void
+    {
+        $result = ['items' => [], 'total' => 0, 'limit' => 25, 'offset' => 50];
+        $this->store->expects(self::once())
+            ->method('queryRules')
+            ->with(
+                FirewallRuleObject::SCOPE_TENANT,
+                'tenant-a',
+                'disabled',
+                FirewallRuleObject::TYPE_IP,
+                FirewallRuleObject::ACTION_BLOCK,
+                25,
+                50
+            )
+            ->willReturn($result);
+
+        self::assertSame($result, $this->manager->query(
+            FirewallRuleScope::tenant('tenant-a'),
+            'disabled',
+            FirewallRuleObject::TYPE_IP,
+            FirewallRuleObject::ACTION_BLOCK,
+            25,
+            50
+        ));
+    }
+
+    #[TestDox('Rule queries reject invalid filters and excessive pages')]
+    public function testRuleQueryValidation(): void
+    {
+        $this->store->expects(self::never())->method('queryRules');
+        $this->expectException(\InvalidArgumentException::class);
+
+        $this->manager->query(FirewallRuleScope::system(), 'active', null, null, 101);
+    }
+
+    #[TestDox('Effective policy keeps system and tenant rule sets distinct')]
+    public function testEffectivePolicy(): void
+    {
+        $system = (new FirewallRuleObject())->setScope(FirewallRuleObject::SCOPE_SYSTEM);
+        $tenant = (new FirewallRuleObject())
+            ->setScope(FirewallRuleObject::SCOPE_TENANT)
+            ->setTenantId('tenant-a');
+        $this->store->method('listSystemRules')->willReturn([$system]);
+        $this->store->method('listRules')->with('tenant-a')->willReturn([$tenant]);
+
+        $policy = $this->manager->effectivePolicy('tenant-a');
+
+        self::assertSame([$system], $policy['system']);
+        self::assertSame([$tenant], $policy['tenant']);
+        self::assertSame('system_block', $policy['precedence'][0]);
+    }
+
     #[TestDox('Rule mutations invalidate the shared enforcement cache')]
     public function testCacheInvalidation(): void
     {

tests/php/Unit/Service/FirewallRuleServicesTest.php

@@ -57,6 +57,39 @@ class FirewallRuleServicesTest extends TestCase
         $this->systemService()->blockIp('203.0.113.10');
     }
 
+    #[TestDox('Read operations require their scope-specific permission')]
+    public function testReadPermissions(): void
+    {
+        $this->identity->method('hasPermission')->willReturn(false);
+        $this->store->expects(self::never())->method('queryRules');
+
+        try {
+            $this->tenantService()->queryRules();
+            self::fail('Tenant read should have been rejected.');
+        } catch (\RuntimeException $error) {
+            self::assertStringContainsString(TenantFirewallRuleService::PERMISSION_READ, $error->getMessage());
+        }
+
+        $this->expectExceptionMessage(SystemFirewallRuleService::PERMISSION_READ);
+        $this->systemService()->queryRules();
+    }
+
+    #[TestDox('Tenant reads derive ownership and effective policy from context')]
+    public function testTenantReads(): void
+    {
+        $this->allow(TenantFirewallRuleService::PERMISSION_READ);
+        $this->tenant->method('requireIdentifier')->willReturn('tenant-a');
+        $this->store->expects(self::once())
+            ->method('queryRules')
+            ->with(FirewallRuleObject::SCOPE_TENANT, 'tenant-a', 'active', null, null, 50, 0)
+            ->willReturn(['items' => [], 'total' => 0, 'limit' => 50, 'offset' => 0]);
+        $this->store->method('listSystemRules')->willReturn([]);
+        $this->store->method('listRules')->with('tenant-a')->willReturn([]);
+
+        self::assertSame(0, $this->tenantService()->queryRules()['total']);
+        self::assertSame([], $this->tenantService()->effectivePolicy()['system']);
+    }
+
     #[TestDox('Tenant management derives scope from tenant context')]
     public function testTenantScope(): void
     {