ADR-006 - Sistem dovoljenj za module

ADR-006: Sistem dovoljenj za module

Drobnozrnat, hierarhični sistem dovoljenj za module XOOPS, ki omogoča zrnat nadzor dostopa.

---

Status

Sprejeto - Implementirano v XOOPS 2.5.x in razširjeno v XOOPS 4.0

---

Kontekst

Izjava o problemu

Moduli XOOPS potrebujejo prilagodljive kontrole dovoljenj, ki omogočajo:

1. Dovoljenja na ravni modula - Ali lahko uporabnik dostopa do tega modula?
2. Dovoljenja na ravni objekta - Ali lahko uporabnik dostopa do tega določenega elementa?
3. Dovoljenja na ravni dejanja - Ali lahko uporabnik izvede to dejanje?
4. Dovoljenja po meri - Ali lahko moduli določijo lastna dovoljenja?

Trenutno stanje

XOOPS 2.5 uporablja sistem XoopsGroupPermission:

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

Izzivi

1. Zapletene poizvedbe - Preverjanje dovoljenj zahteva združevanje z bazo podatkov
2. Omejena hierarhija - Težko je ustvariti skupine dovoljenj
3. Slabo predpomnjenje - Ni vgrajenega predpomnjenja dovoljenj
4. Različice modulov - Vsak modul se izvaja drugače
5. Zmogljivost - Več poizvedb DB za preverjanje dovoljenj

---

Odločitev

Izvedite hierarhični sistem dovoljenj

Ustvarite standardiziran, predpomnjen sistem dovoljenj, ki podpira:

1. Hierarhična dovoljenja - dedovanje od nadrejenih skupin
2. Dostop na podlagi vlog - Preslikava dovoljenj na vloge (skrbnik, moderator, uporabnik, gost)
3. Dovoljenja za objekte - Natančen nadzor na element
4. Caching - Dovoljenja za predpomnilnik za zmanjšanje poizvedb
5. Dovoljenja po meri - Moduli določijo svoje
6. Revizijska sled - Beležite spremembe dovoljenj

Hierarhija dovoljenj

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 dovoljenja

<?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. Preverjevalnik dovoljenj

<?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. Ravni dovoljenj

<?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. Dovoljenja na ravni 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. Uporaba v krmilnikih

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

---

Posledice

Pozitivni učinki

1. Granular Control - natančno nastavljeno upravljanje dovoljenj
2. Standardizirano – dosledno med moduli
3. Cached - Izboljšano delovanje s predpomnjenjem
4. Auditable - Sledite, kdo je kaj spremenil
5. Prilagodljiv - Podpora za dovoljenja po meri
6. Razširljivo – obravnava zapletene hierarhije dovoljenj
7. Testable - Preprosto testiranje enote

Negativni učinki

1. Zapletenost – več kode za upravljanje
2. Nadgradnja baze podatkov - Več tabel in združevanj
3. Razveljavitev predpomnilnika - ob spremembah mora počistiti predpomnilnik
4. Krivulja učenja - Razvijalci morajo razumeti sistem
5. Zmogljivost - če predpomnilnik ni pravilno konfiguriran

Tveganja in ublažitve

Tveganje	Resnost	Ublažitev
Preveč zapletena dovoljenja	Srednje	Dobre privzete vrednosti, dokumentacija
Predpomnilnik zastarelih podatkov	Visok	TTL, pametna razveljavitev
Regresija uspešnosti	Srednje	Primerjava, optimizirajte poizvedbe
Obhod dovoljenj	Visok	Varnostna revizija, testi

---

Vzorci oblikovanja dovoljenj

Vzorec 1: Dovoljenja na podlagi lastnika

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

Vzorec 2: Dovoljenja na podlagi stanja

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

Vzorec 3: Dovoljenja na podlagi vlog

<?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 odločitve

• ADR-001: Modularna arhitektura - Moduli določajo dovoljenja
• ADR-004: Varnostni sistem - Temelj za varnost
• ADR-005: vmesna programska oprema - lahko uveljavlja dovoljenja

---

Reference

Modeli dovoljenj

• RBAC (Nadzor dostopa na podlagi vlog)
• ABAC (Nadzor dostopa na podlagi atributov)
• ACL (Seznam za nadzor dostopa)

Izvedba

• Varnost Symfony
• Pooblastilo Laravel

---

Kontrolni seznam za izvedbo

• Določite standardne ravni dovoljenj
• Ustvari razred PermissionChecker
• Izvedite strategijo predpomnjenja
• Dodaj revizijsko beleženje
• Ustvarite pomožne funkcije
• Napišite obsežne teste
• Dokument za razvijalce
• Posodobi vse module
• Optimizacija zmogljivosti
• Varnostni pregled

---

Zgodovina različic

Različica	Datum	Spremembe
1.0.0	2024-01-28	Začetni dokument

---

#XOOPS #adr #dovoljenja #avtorizacija #rbac #varnost