ADR-006 - Sustav dopuštenja modula

ADR-006: Sustav dopuštenja modula

Fini, hijerarhijski sustav dopuštenja za XOOPS modules koji omogućuje granularnu kontrolu pristupa.

---

Status

Prihvaćeno - Implementirano u XOOPS 2.5.x i prošireno u XOOPS 4.0

---

Kontekst

Izjava problema

XOOPS modules treba fleksibilne kontrole dopuštenja koje omogućuju:

1. dozvole na razini modula - Može li korisnik pristupiti ovom modulu?
2. dozvole na razini objekta - Može li korisnik pristupiti ovoj određenoj stavci?
3. dozvole na razini radnje - Može li korisnik izvršiti ovu radnju?
4. Prilagođena dopuštenja - Može li modules definirati vlastita dopuštenja?

Trenutno stanje

XOOPS 2.5 koristi sustav XoopsGroupPermission:

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

Izazovi

1. Složeni upiti - Provjere dopuštenja zahtijevaju pridruživanje bazi podataka
2. Ograničena hijerarhija - Teško je stvoriti grupe dopuštenja
3. Loše predmemoriranje - Nema ugrađenog predmemoriranja dozvola
4. Varijacije modula - Svaki se modul implementira drugačije
5. Performanse - višestruki DB upiti za provjere dopuštenja

---

Odluka

Implementirajte hijerarhijski sustav dopuštenja

Stvorite standardizirani sustav dopuštenja cached koji podržava:

1. Hijerarhijske dozvole - nasljeđe od nadređenih grupa
2. Pristup temeljen na ulogama - Mapirajte dopuštenja za uloge (admin, moderator, korisnik, gost)
3. dozvole za objekte - precizna kontrola po stavci
4. Caching - dozvole za predmemoriju radi smanjenja upita
5. Prilagođena dopuštenja - moduli sami definiraju svoje
6. Revizijski trag - Zabilježite promjene dopuštenja

Hijerarhija dopuštenja

User
  └── Group 1 (Admin)
      └── Permission: admin_module
      └── Permission: edit_all_items
      └── Permission: delete_all_items
  └── Group 2 (Moderator)
      └── Permission: moderate_comments
      └── Permission: edit_own_items
  └── Group 3 (User)
      └── Permission: view_published_items
      └── Permission: edit_own_items
  └── Group 4 (Guest)
      └── Permission: view_published_items

Arhitektura

graph TB
    subgraph "Permission System"
        A["Permission Registry<br/>(Define permissions)"]
        B["Permission Checker<br/>(Check access)"]
        C["Permission Cache<br/>(Improve performance)"]
        D["Permission Audit Log<br/>(Track changes)"]
    end

    subgraph "Data Layer"
        E["Group Permissions Table"]
        F["User Groups Table"]
        G["Permission Definitions"]
    end

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

---

Osnovne komponente

1. Definicija dopuštenja

<?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. Provjera dopuštenja

<?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. Razine dopuštenja

<?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. dozvole na razini objekta

<?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. Upotreba u kontrolerima

<?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]);
    }
}

---

Posljedice

Pozitivni učinci

1. Granularna kontrola - fino podešeno upravljanje dozvolama
2. Standardizirano - Dosljedno u modules
3. Cached - Poboljšana izvedba s predmemorijom
4. Auditable - Pratite tko je što promijenio
5. Fleksibilno - Podržava prilagođena dopuštenja
6. Skalabilno - Rukuje složenim hijerarhijama dozvola
7. Provjerljivo - Jednostavan za jedinično testiranje

Negativni učinci

1. Složenost - Više koda za upravljanje
2. Preopterećenje baze podataka - Više tablica i spojeva
3. Poništenje predmemorije - Mora izbrisati cache pri promjenama
4. Krivulja učenja - Programeri moraju razumjeti sustav
5. Performanse - Ako cache nije ispravno konfiguriran

Rizici i ublažavanja

Rizik	Ozbiljnost	Ublažavanje
Pretjerano složene dozvole	Srednje	Dobre zadane postavke, dokumentacija
predmemorija zastarjelih podataka	Visoko	TTL, pametno poništenje
Regresija izvedbe	Srednje	Benchmark, optimizirajte upite
Zaobilaženje dopuštenja	Visoko	Sigurnosna revizija, testovi

---

Obrasci dizajna dopuštenja

Uzorak 1: Dopuštenja temeljena na vlasniku

<?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();
}

Uzorak 2: dozvole temeljene na statusu

<?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;
    }
}

Uzorak 3: Dopuštenja temeljena na ulogama

<?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);
}

---

Povezane odluke- ADR-001: Modularna arhitektura - moduli definiraju dopuštenja

• ADR-004: Sigurnosni sustav - Temelj sigurnosti
• ADR-005: Middleware - Može nametnuti dopuštenja

---

Reference

Modeli dopuštenja

• RBAC (Kontrola pristupa temeljena na ulogama)
• ABAC (Kontrola pristupa temeljena na atributima)
• ACL (Lista kontrole pristupa)

Implementacija

• Sigurnost Symfony
• Laravel autorizacija

---

Kontrolni popis implementacije

• Definirajte standardne razine dopuštenja
• Stvorite PermissionChecker class
• Implementirajte strategiju predmemoriranja
• Dodaj revizijsko bilježenje
• Stvaranje pomoćnih funkcija
• Napišite iscrpne testove
• Dokument za programere
• Ažurirajte sve modules
• Optimizacija performansi
• Sigurnosni pregled

---

Povijest verzija

Verzija	Datum	Promjene
1.0.0	2024-01-28	Inicijalni dokument

---

#xoops #adr #dozvole #autorizacija #rbac #sigurnost