ADR-006 - Modulemachtigingssysteem

ADR-006: Modulemachtigingssysteem

Fijnmazig, hiërarchisch toestemmingssysteem voor XOOPS-modules, waardoor granulaire toegangscontrole mogelijk is.

---

Status

Geaccepteerd - Geïmplementeerd in XOOPS 2.5.x en uitgebreid in XOOPS 4.0

---

Context

Probleemverklaring

XOOPS-modules hebben flexibele toestemmingscontroles nodig die het volgende mogelijk maken:

1. Machtigingen op moduleniveau - Heeft de gebruiker toegang tot deze module?
2. Machtigingen op objectniveau - Heeft de gebruiker toegang tot dit specifieke item?
3. Machtigingen op actieniveau - Kan de gebruiker deze actie uitvoeren?
4. Aangepaste machtigingen - Kunnen modules hun eigen machtigingen definiëren?

Huidige status

XOOPS 2.5 gebruikt het XoopsGroupPermission-systeem:

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

Uitdagingen

1. Complexe zoekopdrachten - Voor toestemmingscontroles zijn database-joins vereist
2. Beperkte hiërarchie - Moeilijk om machtigingsgroepen te maken
3. Slechte caching - Geen ingebouwde caching van rechten
4. Modulevariaties - Elke module implementeert anders
5. Prestaties - Meerdere DB-query’s voor toestemmingscontroles

---

Besluit

Implementeer een hiërarchisch machtigingssysteem

Creëer een gestandaardiseerd, in de cache opgeslagen toestemmingssysteem ter ondersteuning van:

1. Hierarchische machtigingen - Overerving van bovenliggende groepen
2. Op rollen gebaseerde toegang - Wijs machtigingen toe aan rollen (beheerder, moderator, gebruiker, gast)
3. Objectmachtigingen - Fijnmazige controle per item
4. Caching - Cachemachtigingen om het aantal zoekopdrachten te verminderen
5. Aangepaste machtigingen - Modules definiëren hun eigen machtigingen
6. Audit Trail - Wijzigingen in rechten registreren

Toestemmingshiërarchie

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

Architectuur

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

---

Kerncomponenten

1. Toestemmingsdefinitie

<?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. Toestemmingscontrole

<?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. Toestemmingsniveaus

<?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. Machtigingen op objectniveau

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

---

Gevolgen

Positieve effecten

1. Granulaire controle - Verfijnd machtigingsbeheer
2. Gestandaardiseerd - Consistent in alle modules
3. In cache opgeslagen - Verbeterde prestaties met caching
4. Audieerbaar - Houd bij wie wat heeft gewijzigd
5. Flexibel - Ondersteun aangepaste machtigingen
6. Schaalbaar - verwerkt complexe machtigingshiërarchieën
7. Testbaar - Eenvoudig te testen

Negatieve effecten

1. Complexiteit - Meer code om te beheren
2. Database-overhead - Meer tabellen en joins
3. Cache-invalidatie - De cache moet bij wijzigingen worden gewist
4. Leercurve - Ontwikkelaars moeten het systeem begrijpen
5. Prestaties - Als de cache niet correct is geconfigureerd

Risico’s en oplossingen

Risico	Ernst	Mitigatie
Te complexe machtigingen	Middel	Goede standaardinstellingen, documentatie
Oude gegevens in cache opslaan	Hoog	TTL, slimme invalidatie
Prestatieregressie	Middel	Benchmarken, zoekopdrachten optimaliseren
Toestemming omzeilen	Hoog	Beveiligingsaudit, tests

---

Toestemmingsontwerppatronen

Patroon 1: Op eigenaar gebaseerde machtigingen

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

Patroon 2: Op status gebaseerde machtigingen

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

Patroon 3: Op rollen gebaseerde machtigingen

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

---

Gerelateerde beslissingen

• ADR-001: Modulaire architectuur - Modules definiëren machtigingen
• ADR-004: Beveiligingssysteem - Basis voor beveiliging
• ADR-005: Middleware - Kan machtigingen afdwingen

---

Referenties

Toestemmingsmodellen

• RBAC (op rollen gebaseerde toegangscontrole)
• ABAC (op attributen gebaseerde toegangscontrole)
• ACL (toegangscontrolelijst)

Implementatie

• Symfony-beveiliging
• Laravel-autorisatie

---

Implementatiechecklist

• Definieer standaard machtigingsniveaus
• PermissionChecker-klasse maken
• Cachingstrategie implementeren
• Auditlogboek toevoegen
• Helperfuncties maken
• Schrijf uitgebreide tests
• Document voor ontwikkelaars
• Update alle modules
• Prestatieoptimalisatie
• Beveiligingsonderzoek

---

Versiegeschiedenis

Versie	Datum	Wijzigingen
1.0.0	28-01-2024	Oorspronkelijk document

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