ADR-006 - module İzin Sistemi

ADR-006: module İzin Sistemi

Ayrıntılı erişim kontrolü sağlayan XOOPS modülleri için ayrıntılı, hiyerarşik izin sistemi.

---

Durum

Kabul edildi - XOOPS 2.5.x’te uygulandı ve XOOPS 4.0’da genişletildi

---

Bağlam

Sorun Bildirimi

XOOPS modülleri aşağıdakilere izin veren esnek izin kontrollerine ihtiyaç duyar:

1. module düzeyinde permissions - user bu modüle erişebilir mi?
2. Nesne düzeyinde permissions - user bu belirli öğeye erişebilir mi?
3. İşlem düzeyindeki permissions - user bu işlemi gerçekleştirebilir mi?
4. Özel permissions - modules kendi izinlerini tanımlayabilir mi?

Mevcut Durum

XOOPS 2.5, XoopsGroupPermission sistemini kullanır:

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

Zorluklar

1. Karmaşık Sorgular - İzin kontrolleri database birleştirmelerini gerektirir
2. Sınırlı Hiyerarşi - İzin grupları oluşturmak zor
3. Kötü Önbelleğe Alma - Yerleşik izinli önbelleğe alma yok
4. module Varyasyonları - Her module farklı şekilde uygulanır
5. Performans - İzin kontrolleri için birden fazla database sorgusu

---

Karar

Hiyerarşik İzin Sistemini Uygulayın

Aşağıdakileri destekleyen standartlaştırılmış, önbelleğe alınmış bir izin sistemi oluşturun:

1. Hiyerarşik permissions - Üst gruplardan devralma
2. Rol Tabanlı Erişim - İzinleri rollere (yönetici, moderatör, user, misafir) eşleyin
3. Nesne İzinleri - Öğe başına ayrıntılı kontrol
4. Önbelleğe alma - Sorguları azaltmak için cache izinleri
5. Özel permissions - modules kendi izinlerini tanımlar
6. Denetim İzleme - İzin değişikliklerini günlüğe kaydedin

İzin Hiyerarşisi

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

Mimarlık

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

---

Temel Bileşenler

1. İzin Tanımı

<?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. İzin Denetleyicisi

<?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. İzin Seviyeleri

<?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. Nesne Düzeyinde 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. Denetleyicilerde Kullanım

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

---

Sonuçlar

Olumlu Etkiler

1. Ayrıntılı Kontrol - İnce ayarlı izin yönetimi
2. Standartlaştırılmış - modules arasında tutarlı
3. Önbelleğe Alındı - Önbelleğe almayla iyileştirilmiş performans
4. Denetlenebilir - Kimin neyi değiştirdiğini takip edin
5. Esnek - Özel izinleri destekler
6. Ölçeklenebilir - Karmaşık izin hiyerarşilerini yönetir
7. Test edilebilir - Birim testi kolay

Olumsuz Etkiler

1. Karmaşıklık - Yönetilecek daha fazla kod
2. database Ek Yükü - Daha fazla tablo ve birleştirme
3. cache Geçersiz Kılma - Değişikliklerde cache temizlenmelidir
4. Öğrenim Eğrisi - Geliştiricilerin sistemi anlamaları gerekir
5. Performans - cache düzgün şekilde yapılandırılmamışsa

Riskler ve Azaltmalar

Risk	Şiddet	Azaltma
Aşırı karmaşık permissions	Orta	İyi varsayılanlar, belgeler
Eski verileri önbelleğe al	Yüksek	TTL, Smarty geçersiz kılma
Performans regresyonu	Orta	Sorguları kıyaslayın, optimize edin
İzin atlama	Yüksek	Güvenlik denetimi, testler

---

İzin Tasarım Modelleri

Model 1: Sahip Tabanlı 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();
}

Desen 2: Duruma Dayalı 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;
    }
}

Desen 3: Rol Tabanlı 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);
}

---

İlgili Kararlar

• ADR-001: Modüler Mimari - modules izinleri tanımlar
• ADR-004: Güvenlik Sistemi - Güvenliğin temeli
• ADR-005: Ara yazılım - İzinleri uygulayabilir

---

Referanslar

İzin Modelleri

• RBAC (Rol Tabanlı Erişim Kontrolü)
• ABAC (Özellik Tabanlı Erişim Kontrolü)
• ACL (Erişim Kontrol Listesi)

Uygulama

• Symfony Güvenliği
• Laravel Yetkilendirmesi

---

Uygulama Kontrol Listesi

• Standart izin düzeylerini tanımlayın
• PermissionChecker sınıfını oluştur
• Önbelleğe alma stratejisini uygulayın
• Denetim günlüğü ekle
• Yardımcı işlevler oluşturun
• Kapsamlı testler yazın
• Geliştiriciler için belge
• Tüm modülleri güncelle
• Performans optimizasyonu
• Güvenlik incelemesi

---

Sürüm Geçmişi

Sürüm	Tarih	Değişiklikler
1.0.0	2024-01-28	İlk belge

---

#xoops #adr #permissions #yetkilendirme #rbac #güvenlik