ADR-006 - System uprawnień modułu

ADR-006: System uprawnień modułu

Bezstronne, hierarchiczne system uprawnień dla modułów XOOPS umożliwiający kontrolę dostępu o rozdzielczości.

---

Status

Accepted - Wdrożone w XOOPS 2.5.x i rozszerzone w XOOPS 4.0

---

Kontekst

Oświadczenie problemu

Moduły XOOPS potrzebują elastycznych kontroli uprawnień, które pozwalają:

1. Uprawnienia na poziomie modułu - Czy użytkownik ma dostęp do tego modułu?
2. Uprawnienia na poziomie obiektu - Czy użytkownik ma dostęp do tego konkretnego elementu?
3. Uprawnienia na poziomie akcji - Czy użytkownik może wykonać tę akcję?
4. Niestandardowe uprawnienia - Czy moduły mogą zdefiniować własne uprawnienia?

Bieżący stan

XOOPS 2.5 używa systemu XoopsGroupPermission:

<?php
$perm_handler = xoops_getHandler('groupperm');
$isAllowed = $perm_handler->checkRight(
    'modulename',
    'action',
    $itemId,
    $groupId
);

Wyzwania

1. Złożone zapytania - Sprawdzenie uprawnień wymaga łączenia bazy danych
2. Ograniczona hierarchia - Trudno jest tworzyć grupy uprawnień
3. Słabe buforowanie - Brak wbudowanego buforowania uprawnień
4. Odmiany modułów - Każdy moduł wdrażany inaczej
5. Wydajność - Wiele zapytań BD do sprawdzenia uprawnień

---

Decyzja

Wdrożyć system uprawnień hierarchicznych

Utwórz ustandaryzowany, buforowany system uprawnień obsługujący:

1. Uprawnienia hierarchiczne - Dziedziczenie od grup nadrzędnych
2. Dostęp oparty na rolach - Mapowanie uprawnień na role (admin, moderator, użytkownik, gość)
3. Uprawnienia obiektów - Dokładna kontrola na element
4. Buforowanie - Buforuj uprawnienia, aby zmniejszyć zapytania
5. Niestandardowe uprawnienia - Moduły definiują swoje własne
6. Ścieżka audytu - Loguj zmiany uprawnień

Hierarchia uprawnień

Użytkownik
  └── Grupa 1 (Admin)
      └── Uprawnienie: admin_module
      └── Uprawnienie: edit_all_items
      └── Uprawnienie: delete_all_items
  └── Grupa 2 (Moderator)
      └── Uprawnienie: moderate_comments
      └── Uprawnienie: edit_own_items
  └── Grupa 3 (User)
      └── Uprawnienie: view_published_items
      └── Uprawnienie: edit_own_items
  └── Grupa 4 (Guest)
      └── Uprawnienie: view_published_items

Architektura

graph TB
    subgraph "System uprawnień"
        A["Rejestr uprawnień<br/>(Definiuj uprawnienia)"]
        B["Sprawdzacz uprawnień<br/>(Sprawdzaj dostęp)"]
        C["Cache uprawnień<br/>(Ulepsz wydajność)"]
        D["Dziennik audytu uprawnień<br/>(Śledź zmiany)"]
    end

    subgraph "Warstwa danych"
        E["Tabela uprawnień grup"]
        F["Tabela grup użytkowników"]
        G["Definicje uprawnień"]
    end

    A --> E
    B --> E
    B --> C
    C --> E
    D --> E
    F --> B

---

Core Components

1. Permission Definition

<?php
// Module defines its permissions in xoops_version.php

$modversion['permissions'] = [
    [
        'name' => 'module_view',
        'description' => 'Can view module',
        'level' => 'module',
    ],
    [
        'name' => 'item_view',
        'description' => 'Can view items',
        'level' => 'item',
    ],
    [
        'name' => 'item_create',
        'description' => 'Can create items',
        'level' => 'item',
    ],
    [
        'name' => 'item_edit',
        'description' => 'Can edit items',
        'level' => 'item',
    ],
    [
        'name' => 'item_delete',
        'description' => 'Can delete items',
        'level' => 'item',
    ],
    [
        'name' => 'admin_manage',
        'description' => 'Can manage module',
        'level' => 'admin',
    ],
];

// Default permissions by group
$modversion['group_permissions'] = [
    // Admin group gets all permissions
    '1' => [
        'module_view' => 1,
        'item_view' => 1,
        'item_create' => 1,
        'item_edit' => 1,
        'item_delete' => 1,
        'admin_manage' => 1,
    ],
    // User group
    '3' => [
        'module_view' => 1,
        'item_view' => 1,
        'item_create' => 1,
        'item_edit' => 0,
        'item_delete' => 0,
        'admin_manage' => 0,
    ],
    // Guest group
    '4' => [
        'module_view' => 1,
        'item_view' => 1,
        'item_create' => 0,
        'item_edit' => 0,
        'item_delete' => 0,
        'admin_manage' => 0,
    ],
];

2. Permission Checker

<?php
declare(strict_types=1);

namespace XoopsCore\Permission;

class PermissionChecker
{
    private PermissionCache $cache;
    private PermissionRepository $repository;

    public function hasPermission(
        User $user,
        string $permissionName,
        ?int $itemId = null
    ): bool {
        // Check cache first
        $cacheKey = "perm_{$user->getId()}_{$permissionName}_{$itemId}";
        if ($this->cache->has($cacheKey)) {
            return $this->cache->get($cacheKey);
        }

        $hasPermission = false;

        // Check all user groups
        foreach ($user->getGroups() as $group) {
            if ($this->checkGroupPermission($group, $permissionName, $itemId)) {
                $hasPermission = true;
                break;
            }
        }

        // Cache result
        $this->cache->set($cacheKey, $hasPermission, 3600);

        // Log high-level access checks
        if ($hasPermission && $this->shouldAuditLog($permissionName)) {
            $this->auditLog('PERMISSION_CHECKED', [
                'user_id' => $user->getId(),
                'permission' => $permissionName,
                'item_id' => $itemId,
                'result' => 'ALLOWED',
            ]);
        }

        return $hasPermission;
    }

    private function checkGroupPermission(
        Group $group,
        string $permissionName,
        ?int $itemId = null
    ): bool {
        $sql = 'SELECT COUNT(*) FROM ' . $this->table . '
                WHERE groupid = ?
                AND permission = ?
                AND itemid = ?
                AND granted = 1';

        $stmt = $this->db->prepare($sql);
        $stmt->execute([$group->getId(), $permissionName, $itemId ?? 0]);

        return $stmt->fetchColumn() > 0;
    }
}

3. Permission Levels

<?php
// Different permission levels with different scopes

class PermissionLevel
{
    // Module-level: Affects entire module
    public const LEVEL_MODULE = 'module';

    // Admin-level: Admin panel access
    public const LEVEL_ADMIN = 'admin';

    // Item-level: Specific objects/items
    public const LEVEL_ITEM = 'item';

    // Field-level: Specific object fields
    public const LEVEL_FIELD = 'field';

    // Action-level: Specific actions/operations
    public const LEVEL_ACTION = 'action';
}

4. Object-Level Permissions

<?php
// Fine-grained control for specific items

class Item extends XoopsObject
{
    /**
     * Check if user can view this item
     */
    public function canView(User $user): bool
    {
        // Public items anyone can view
        if ($this->getVar('status') === 'published') {
            return true;
        }

        // Owner can always view their items
        if ($this->getVar('user_id') === $user->getId()) {
            return true;
        }

        // Check group permissions
        $permChecker = xoops_getActiveModule()->getPermissionChecker();
        return $permChecker->hasPermission(
            $user,
            'item_view',
            $this->getVar('id')
        );
    }

    public function canEdit(User $user): bool
    {
        // Owner can edit their items
        if ($this->getVar('user_id') === $user->getId()) {
            return $permChecker->hasPermission($user, 'item_edit', $this->getVar('id'));
        }

        // Check if user can edit all items
        return $permChecker->hasPermission($user, 'item_edit_all', $this->getVar('id'));
    }

    public function canDelete(User $user): bool
    {
        return $permChecker->hasPermission($user, 'item_delete', $this->getVar('id'));
    }
}

5. Usage in Controllers

<?php
// Example: Article controller

class ArticleController
{
    private PermissionChecker $permChecker;

    public function view(int $id, User $user): Response
    {
        $article = $this->repository->find($id);

        // Check permission
        if (!$article->canView($user)) {
            throw new AccessDeniedException('Cannot view this article');
        }

        return new HtmlResponse($this->renderArticle($article));
    }

    public function edit(int $id, User $user): Response
    {
        $article = $this->repository->find($id);

        // Check permission
        if (!$article->canEdit($user)) {
            throw new AccessDeniedException('Cannot edit this article');
        }

        // Handle form submission
        if ($this->request->isMethod('POST')) {
            $article->setVar('title', $this->request->getPost('title'));
            $article->setVar('content', $this->request->getPost('content'));
            $this->repository->insert($article);

            $this->auditLog('ARTICLE_EDITED', ['id' => $id, 'user_id' => $user->getId()]);

            // Invalidate permission cache
            $this->permChecker->clearCache($user->getId());

            return new RedirectResponse('/article/' . $id);
        }

        return new HtmlResponse($this->renderForm($article));
    }

    public function delete(int $id, User $user): Response
    {
        $article = $this->repository->find($id);

        if (!$article->canDelete($user)) {
            throw new AccessDeniedException('Cannot delete this article');
        }

        $this->repository->delete($article);

        $this->auditLog('ARTICLE_DELETED', ['id' => $id, 'user_id' => $user->getId()]);

        // Invalidate cache
        $this->permChecker->clearCache($user->getId());

        return new JsonResponse(['success' => true]);
    }
}

---

Consequences

Positive Effects

1. Granular Control - Fine-tuned permission management
2. Standardized - Consistent across modules
3. Cached - Improved performance with caching
4. Auditable - Track who changed what
5. Flexible - Support custom permissions
6. Scalable - Handles complex permission hierarchies
7. Testable - Easy to unit test

Negative Effects

1. Complexity - More code to manage
2. Database Overhead - More tables and joins
3. Cache Invalidation - Must clear cache on changes
4. Learning Curve - Developers must understand system
5. Performance - If cache not properly configured

Risks and Mitigations

Risk	Severity	Mitigation
Overly complex permissions	Medium	Good defaults, documentation
Cache stale data	High	TTL, smart invalidation
Performance regression	Medium	Benchmark, optimize queries
Permission bypass	High	Security audit, tests

---

Permission Design Patterns

Pattern 1: Owner-Based Permissions

<?php
// User can edit their own items but not others'

public function canEdit(User $user): bool
{
    // Owner can always edit
    if ($this->isOwner($user)) {
        return true;
    }

    // Check group permissions for editing others' items
    return $this->permChecker->hasPermission($user, 'edit_all_items');
}

private function isOwner(User $user): bool
{
    return $this->getVar('user_id') === $user->getId();
}

Pattern 2: Status-Based Permissions

<?php
// Different permissions based on status

public function canView(User $user): bool
{
    switch ($this->getVar('status')) {
        case 'published':
            // Anyone with module permission can view
            return $this->permChecker->hasPermission($user, 'item_view');

        case 'draft':
            // Only owner or admin can view
            return $this->isOwner($user) ||
                   $this->permChecker->hasPermission($user, 'admin_manage');

        case 'archived':
            // Only admin can view
            return $this->permChecker->hasPermission($user, 'admin_manage');

        default:
            return false;
    }
}

Pattern 3: Role-Based Permissions

<?php
// Check against specific roles

public function hasAdminRole(User $user): bool
{
    return $user->getGroups()->contains('admin_group');
}

public function hasModeratorRole(User $user): bool
{
    return $user->getGroups()->contains('moderator_group') ||
           $this->hasAdminRole($user);
}

public function canModerate(User $user): bool
{
    return $this->hasModeratorRole($user);
}

---

Related Decisions

• ADR-001: Modular Architecture - Modules define permissions
• ADR-004: Security System - Foundation for security
• ADR-005: Middleware - Can enforce permissions

---

References

Permission Models

• RBAC (Role-Based Access Control)
• ABAC (Attribute-Based Access Control)
• ACL (Access Control List)

Implementation

• Symfony Security
• Laravel Authorization

---

Implementation Checklist

• Define standard permission levels
• Create PermissionChecker class
• Implement caching strategy
• Add audit logging
• Create helper functions
• Write comprehensive tests
• Document for developers
• Update all modules
• Performance optimization
• Security review

---

Version History

Version	Date	Changes
1.0.0	2024-01-28	Initial document

---

#xoops #adr #permissions #authorization #rbac #security