feat(firewall): add scoped rule administration reads

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-08-03 22:05:00 -04:00
parent 4ee91a7918
commit 74696bbeb3
9 changed files with 486 additions and 0 deletions
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXC\Controllers;
+
+use KTXC\Http\Response\JsonResponse;
+use KTXC\Service\SystemFirewallRuleService;
+use KTXC\Service\TenantFirewallRuleService;
+use KTXF\Controller\ControllerAbstract;
+use KTXF\Routing\Attributes\AuthenticatedRoute;
+
+final class FirewallController extends ControllerAbstract
+{
+    public function __construct(
+        private readonly TenantFirewallRuleService $tenantRules,
+        private readonly SystemFirewallRuleService $systemRules,
+    ) {
+    }
+
+    #[AuthenticatedRoute(
+        '/firewall/rules',
+        name: 'firewall.tenant.rules.list',
+        permissions: [TenantFirewallRuleService::PERMISSION_READ],
+    )]
+    public function tenantRules(
+        string $status = 'active',
+        ?string $type = null,
+        ?string $action = null,
+        string $limit = '50',
+        string $offset = '0'
+    ): JsonResponse {
+        return $this->queryResponse(
+            fn(int $parsedLimit, int $parsedOffset): array => $this->tenantRules->queryRules(
+                $status,
+                $type,
+                $action,
+                $parsedLimit,
+                $parsedOffset
+            ),
+            $limit,
+            $offset
+        );
+    }
+
+    #[AuthenticatedRoute(
+        '/firewall/rules/{ruleId}',
+        name: 'firewall.tenant.rules.fetch',
+        permissions: [TenantFirewallRuleService::PERMISSION_READ],
+    )]
+    public function tenantRule(string $ruleId): JsonResponse
+    {
+        return $this->ruleResponse($this->tenantRules->fetchRule($ruleId));
+    }
+
+    #[AuthenticatedRoute(
+        '/firewall/effective-policy',
+        name: 'firewall.tenant.policy.effective',
+        permissions: [TenantFirewallRuleService::PERMISSION_READ],
+    )]
+    public function effectivePolicy(): JsonResponse
+    {
+        return new JsonResponse($this->tenantRules->effectivePolicy());
+    }
+
+    #[AuthenticatedRoute(
+        '/firewall/system/rules',
+        name: 'firewall.system.rules.list',
+        permissions: [SystemFirewallRuleService::PERMISSION_READ],
+    )]
+    public function systemRules(
+        string $status = 'active',
+        ?string $type = null,
+        ?string $action = null,
+        string $limit = '50',
+        string $offset = '0'
+    ): JsonResponse {
+        return $this->queryResponse(
+            fn(int $parsedLimit, int $parsedOffset): array => $this->systemRules->queryRules(
+                $status,
+                $type,
+                $action,
+                $parsedLimit,
+                $parsedOffset
+            ),
+            $limit,
+            $offset
+        );
+    }
+
+    #[AuthenticatedRoute(
+        '/firewall/system/rules/{ruleId}',
+        name: 'firewall.system.rules.fetch',
+        permissions: [SystemFirewallRuleService::PERMISSION_READ],
+    )]
+    public function systemRule(string $ruleId): JsonResponse
+    {
+        return $this->ruleResponse($this->systemRules->fetchRule($ruleId));
+    }
+
+    private function queryResponse(callable $query, string $limit, string $offset): JsonResponse
+    {
+        try {
+            if (!ctype_digit($limit) || !ctype_digit($offset)) {
+                throw new \InvalidArgumentException('Pagination values must be non-negative integers.');
+            }
+            return new JsonResponse($query((int)$limit, (int)$offset));
+        } catch (\InvalidArgumentException $error) {
+            return new JsonResponse(['error' => $error->getMessage()], JsonResponse::HTTP_BAD_REQUEST);
+        }
+    }
+
+    private function ruleResponse(?\JsonSerializable $rule): JsonResponse
+    {
+        if ($rule === null) {
+            return new JsonResponse(['error' => 'Firewall rule not found.'], JsonResponse::HTTP_NOT_FOUND);
+        }
+
+        return new JsonResponse($rule);
+    }
+}
@@ -11,6 +11,8 @@ use KTXF\Event\SecurityEvent;

 final class FirewallRuleManager
 {
+    public const QUERY_STATUSES = ['active', 'disabled', 'expired', 'all'];
+    public const MAX_QUERY_LIMIT = 100;
    public const ORIGIN_MANUAL = 'manual';
    public const ORIGIN_AUTOMATIC = 'automatic';

@@ -28,6 +30,60 @@ final class FirewallRuleManager
            : $this->store->listRules($scope->tenantId, $activeOnly);
    }

+    public function query(
+        FirewallRuleScope $scope,
+        string $status = 'active',
+        ?string $type = null,
+        ?string $action = null,
+        int $limit = 50,
+        int $offset = 0
+    ): array {
+        if (!in_array($status, self::QUERY_STATUSES, true)) {
+            throw new \InvalidArgumentException('Invalid rule status filter.');
+        }
+        if ($type !== null && !in_array($type, [
+            FirewallRuleObject::TYPE_IP,
+            FirewallRuleObject::TYPE_IP_RANGE,
+            FirewallRuleObject::TYPE_DEVICE,
+        ], true)) {
+            throw new \InvalidArgumentException('Invalid rule type filter.');
+        }
+        if ($action !== null && !in_array($action, [
+            FirewallRuleObject::ACTION_ALLOW,
+            FirewallRuleObject::ACTION_BLOCK,
+        ], true)) {
+            throw new \InvalidArgumentException('Invalid rule action filter.');
+        }
+        if ($limit < 1 || $limit > self::MAX_QUERY_LIMIT || $offset < 0) {
+            throw new \InvalidArgumentException('Pagination requires limit 1-100 and offset 0 or greater.');
+        }
+
+        return $this->store->queryRules(
+            $scope->scope,
+            $scope->tenantId,
+            $status,
+            $type,
+            $action,
+            $limit,
+            $offset
+        );
+    }
+
+    public function fetch(FirewallRuleScope $scope, string $ruleId): ?FirewallRuleObject
+    {
+        return $this->ownedRule($scope, $ruleId);
+    }
+
+    /** @return array{precedence: string[], system: FirewallRuleObject[], tenant: FirewallRuleObject[]} */
+    public function effectivePolicy(string $tenantId): array
+    {
+        return [
+            'precedence' => ['system_block', 'tenant_allow', 'tenant_block', 'system_allow', 'default_allow'],
+            'system' => $this->store->listSystemRules(),
+            'tenant' => $this->store->listRules($tenantId),
+        ];
+    }
+
    public function blockIp(
        FirewallRuleScope $scope,
        string $ipAddress,
@@ -24,6 +24,23 @@ final class SystemFirewallRuleService
        return $this->rules->list(FirewallRuleScope::system(), $activeOnly);
    }

+    public function queryRules(
+        string $status = 'active',
+        ?string $type = null,
+        ?string $action = null,
+        int $limit = 50,
+        int $offset = 0
+    ): array {
+        $this->requirePermission(self::PERMISSION_READ);
+        return $this->rules->query(FirewallRuleScope::system(), $status, $type, $action, $limit, $offset);
+    }
+
+    public function fetchRule(string $ruleId): ?FirewallRuleObject
+    {
+        $this->requirePermission(self::PERMISSION_READ);
+        return $this->rules->fetch(FirewallRuleScope::system(), $ruleId);
+    }
+
    public function blockIp(string $ip, ?string $reason = null, ?int $durationSeconds = null): FirewallRuleObject
    {
        $this->requirePermission(self::PERMISSION_MANAGE);
@@ -26,6 +26,29 @@ final class TenantFirewallRuleService
        return $this->rules->list($this->scope(), $activeOnly);
    }

+    public function queryRules(
+        string $status = 'active',
+        ?string $type = null,
+        ?string $action = null,
+        int $limit = 50,
+        int $offset = 0
+    ): array {
+        $this->requirePermission(self::PERMISSION_READ);
+        return $this->rules->query($this->scope(), $status, $type, $action, $limit, $offset);
+    }
+
+    public function fetchRule(string $ruleId): ?FirewallRuleObject
+    {
+        $this->requirePermission(self::PERMISSION_READ);
+        return $this->rules->fetch($this->scope(), $ruleId);
+    }
+
+    public function effectivePolicy(): array
+    {
+        $this->requirePermission(self::PERMISSION_READ);
+        return $this->rules->effectivePolicy($this->tenant->requireIdentifier());
+    }
+
    public function blockIp(string $ip, ?string $reason = null, ?int $durationSeconds = null): FirewallRuleObject
    {
        $this->requirePermission(self::PERMISSION_MANAGE);
@@ -46,6 +46,10 @@ class FirewallStore
                ['scope' => 1, 'tenantId' => 1, 'type' => 1, 'value' => 1, 'action' => 1, 'enabled' => 1, 'expiresAt' => 1],
                ['name' => 'rules_exact_lookup']
            ),
+            $rules->createIndex(
+                ['scope' => 1, 'tenantId' => 1, 'createdAt' => -1],
+                ['name' => 'rules_browse']
+            ),
            $logs->createIndex(
                ['tenantId' => 1, 'ipAddress' => 1, 'eventType' => 1, 'timestamp' => -1],
                ['name' => 'logs_auth_failures']
@@ -73,6 +77,61 @@ class FirewallStore
    // Rule Operations
    // ========================================

+    /**
+     * Query rules within one ownership scope.
+     *
+     * @return array{items: FirewallRuleObject[], total: int, limit: int, offset: int}
+     */
+    public function queryRules(
+        string $scope,
+        ?string $tenantId,
+        string $status,
+        ?string $type,
+        ?string $action,
+        int $limit,
+        int $offset
+    ): array {
+        $filter = [
+            'scope' => $scope,
+            'tenantId' => $scope === FirewallRuleObject::SCOPE_SYSTEM ? null : $tenantId,
+        ];
+        $now = self::bsonDate(new \DateTimeImmutable());
+        if ($status === 'active') {
+            $filter['enabled'] = true;
+            $filter['$or'] = [
+                ['expiresAt' => null],
+                ['expiresAt' => ['$gt' => $now]],
+            ];
+        } elseif ($status === 'disabled') {
+            $filter['enabled'] = false;
+        } elseif ($status === 'expired') {
+            $filter['expiresAt'] = ['$ne' => null, '$lte' => $now];
+        }
+        if ($type !== null) {
+            $filter['type'] = $type;
+        }
+        if ($action !== null) {
+            $filter['action'] = $action;
+        }
+
+        $collection = $this->dataStore->selectCollection(self::RULES_COLLECTION);
+        $items = [];
+        foreach ($collection->find($filter, [
+            'sort' => ['createdAt' => -1, '_id' => -1],
+            'limit' => $limit,
+            'skip' => $offset,
+        ]) as $entry) {
+            $items[] = (new FirewallRuleObject())->jsonDeserialize((array)$entry);
+        }
+
+        return [
+            'items' => $items,
+            'total' => $collection->countDocuments($filter),
+            'limit' => $limit,
+            'offset' => $offset,
+        ];
+    }
+
    /**
     * List all rules for a tenant
     */