ADR-006 - سیستم مجوز ماژول

ADR-006: سیستم مجوز ماژول

سیستم مجوز سلسله مراتبی ریز برای ماژول های XOOPS که امکان کنترل دسترسی گرانول را فراهم می کند.

---

وضعیت

پذیرفته - در XOOPS 2.5.x پیاده سازی شده و در XOOPS 4.0 گسترش یافته است

---

زمینه

بیان مشکل

ماژول‌های XOOPS به کنترل‌های مجوز انعطاف‌پذیر نیاز دارند که اجازه می‌دهد:

1. مجوزهای سطح ماژول - آیا کاربر می تواند به این ماژول دسترسی داشته باشد؟
2. مجوزهای سطح شی - آیا کاربر می تواند به این آیتم خاص دسترسی داشته باشد؟
3. مجوزهای سطح اقدام - آیا کاربر می تواند این عمل را انجام دهد؟
4. مجوزهای سفارشی - آیا ماژول ها می توانند مجوزهای خود را تعریف کنند؟

وضعیت فعلی

XOOPS 2.5 از سیستم XoopsGroupPermission استفاده می کند:

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

چالش ها

1. پرس و جوهای پیچیده - بررسی مجوز نیاز به پیوستن به پایگاه داده دارد
2. ** سلسله مراتب محدود ** - سخت برای ایجاد گروه های مجوز
3. ** ذخیره ضعیف ** - بدون ذخیره سازی مجوز داخلی
4. ** تغییرات ماژول ** - هر ماژول به طور متفاوتی اجرا می شود
5. **عملکرد ** - پرس و جوهای متعدد DB برای بررسی مجوز

---

تصمیم

سیستم مجوز سلسله مراتبی را پیاده سازی کنید

ایجاد یک سیستم مجوز استاندارد و حافظه پنهان که پشتیبانی می کند:

1. مجوزهای سلسله مراتبی - ارث از گروه های والدین
2. دسترسی مبتنی بر نقش - مجوزهای نقشه برای نقش ها (مدیر، ناظر، کاربر، مهمان)
3. اجازه های شی - کنترل ریز دانه در هر مورد
4. Caching - مجوزهای کش برای کاهش پرس و جوها
5. ** مجوزهای سفارشی ** - ماژول ها خود را تعریف می کنند
6. ** مسیر حسابرسی ** - تغییرات مجوز ورود به سیستم

سلسله مراتب مجوز

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

معماری

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

---

اجزای اصلی

1. تعریف مجوز

<?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. جستجوگر مجوز

<?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. سطوح مجوز

<?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. مجوزهای سطح شی

<?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. استفاده در کنترلرها

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

---

عواقب

اثرات مثبت

1. کنترل دانه ای - مدیریت مجوز دقیق
2. ** استاندارد ** - سازگار در ماژول ها
3. Cached - بهبود عملکرد با ذخیره سازی
4. ** قابل کنترل ** - پیگیری چه کسی چه چیزی را تغییر داده است
5. ** انعطاف پذیر ** - پشتیبانی از مجوزهای سفارشی
6. ** مقیاس پذیر ** - سلسله مراتب مجوزهای پیچیده را مدیریت می کند
7. ** قابل آزمایش ** - آسان برای تست واحد

اثرات منفی

1. ** پیچیدگی ** - کد بیشتر برای مدیریت
2. **سربار پایگاه داده ** - جداول بیشتر و پیوستن
3. ابطال کش - باید حافظه نهان در تغییرات پاک شود
4. ** منحنی یادگیری ** - توسعه دهندگان باید سیستم را درک کنند
5. ** عملکرد ** - اگر کش به درستی پیکربندی نشده باشد

خطرات و کاهش

ریسک	شدت	کاهش
مجوزهای بیش از حد پیچیده	متوسط ​​	پیش فرض های خوب، مستندات
کش داده های قدیمی	بالا	TTL، ابطال هوشمند
رگرسیون عملکرد	متوسط ​​	معیار، بهینه سازی پرس و جو
دور زدن مجوز	بالا	ممیزی امنیتی، آزمایشات

---

الگوهای طراحی مجوز

الگوی 1: مجوزهای مبتنی بر مالک

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

الگوی 2: مجوزهای مبتنی بر وضعیت

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

الگوی 3: مجوزهای مبتنی بر نقش

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

---

تصمیمات مرتبط

• ADR-001: معماری مدولار - ماژول ها مجوزها را تعریف می کنند
• ADR-004: سیستم امنیتی - بنیاد برای امنیت
• ADR-005: Middleware - می تواند مجوزها را اعمال کند

---

مراجع

مدل های مجوز

• RBAC (کنترل دسترسی مبتنی بر نقش)
• ABAC (کنترل دسترسی مبتنی بر ویژگی)
• ACL (فهرست کنترل دسترسی)

پیاده سازی

• Symfony Security
• مجوز لاراول

---

چک لیست پیاده سازی- [ ] سطوح مجوز استاندارد را تعریف کنید

• کلاس PermissionChecker را ایجاد کنید
• پیاده سازی استراتژی ذخیره سازی
• اضافه کردن گزارش حسابرسی
• ایجاد توابع کمکی
• تست های جامع بنویسید
• سند برای توسعه دهندگان
• به روز رسانی تمام ماژول ها
• بهینه سازی عملکرد
• بررسی امنیتی

---

تاریخچه نسخه

نسخه	تاریخ	تغییرات
1.0.0	2024-01-28	سند اولیه

---

#xoops #adr #مجوزها #مجوز #rbac #امنیت