ADR-006 - Sistema de Permisos de Módulos

ADR-006: Sistema de Permisos de Módulos

Sistema de permisos granular y jerárquico para módulos XOOPS que permite control de acceso granular.

---

Estado

Aceptado - Implementado en XOOPS 2.5.x y extendido en XOOPS 4.0

---

Contexto

Declaración del Problema

Los módulos XOOPS necesitan controles de permisos flexibles que permitan:

1. Permisos a nivel de módulo - ¿Puede el usuario acceder a este módulo?
2. Permisos a nivel de objeto - ¿Puede el usuario acceder a este elemento específico?
3. Permisos a nivel de acción - ¿Puede el usuario realizar esta acción?
4. Permisos personalizados - ¿Pueden los módulos definir sus propios permisos?

Estado Actual

XOOPS 2.5 usa el sistema XoopsGroupPermission:

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

Desafíos

1. Consultas Complejas - Las verificaciones de permisos requieren uniones de base de datos
2. Jerarquía Limitada - Difícil crear grupos de permisos
3. Caché Pobre - Sin caché de permisos incorporado
4. Variaciones de Módulos - Cada módulo se implementa de manera diferente
5. Rendimiento - Múltiples consultas de BD para verificaciones de permisos

---

Decisión

Implementar Sistema de Permisos Jerárquico

Crear un sistema de permisos estandarizado y en caché que admita:

1. Permisos Jerárquicos - Herencia de grupos principales
2. Acceso Basado en Roles - Mapear permisos a roles (admin, moderador, usuario, invitado)
3. Permisos de Objeto - Control granular por elemento
4. Caché - Cachear permisos para reducir consultas
5. Permisos Personalizados - Los módulos definen los suyos
6. Rastro de Auditoría - Registrar cambios de permisos

Jerarquía de Permisos

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

Architecture

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

---

Core Components

1. Permission Definition

<?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. Permission Checker

<?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. Permission Levels

<?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. Object-Level 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. Usage 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]);
    }
}

---

Consecuencias

Efectos Positivos

1. Control Granular - Gestión de permisos afinada
2. Estandarizado - Consistente entre módulos
3. En Caché - Rendimiento mejorado con caché
4. Auditable - Rastrear quién cambió qué
5. Flexible - Apoye permisos personalizados
6. Escalable - Maneja jerarquías de permisos complejas
7. Testeable - Fácil de hacer pruebas unitarias

Efectos Negativos

1. Complejidad - Más código que gestionar
2. Sobrecarga de Base de Datos - Más tablas y uniones
3. Invalidación de Caché - Debe limpiar caché en cambios
4. Curva de Aprendizaje - Los desarrolladores deben entender el sistema
5. Rendimiento - Si la caché no está configurada correctamente

Riesgos y Mitigaciones

Riesgo	Severidad	Mitigación
Permisos demasiado complejos	Media	Buenos valores predeterminados, documentación
Datos de caché obsoletos	Alta	TTL, invalidación inteligente
Regresión de rendimiento	Media	Punto de referencia, optimizar consultas
Bypass de permisos	Alta	Auditoría de seguridad, pruebas

---

Patrones de Diseño de Permisos

Patrón 1: Permisos Basados en Propietario

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

Patrón 2: Permisos Basados en Estado

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

Patrón 3: Permisos Basados en Roles

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

---

Decisiones Relacionadas

• ADR-001: Arquitectura Modular - Los módulos definen permisos
• ADR-004: Sistema de Seguridad - Fundación de seguridad
• ADR-005: Middleware - Puede aplicar permisos

---

Referencias

Modelos de Permisos

• RBAC (Control de Acceso Basado en Roles)
• ABAC (Control de Acceso Basado en Atributos)
• ACL (Lista de Control de Acceso)

Implementación

• Seguridad de Symfony
• Autorización de Laravel

---

Lista de Verificación de Implementación

• Definir niveles de permisos estándar
• Crear clase PermissionChecker
• Implementar estrategia de caché
• Agregar registro de auditoría
• Crear funciones auxiliares
• Escribir pruebas completas
• Documentar para desarrolladores
• Actualizar todos los módulos
• Optimización de rendimiento
• Revisión de seguridad

---

Historial de Versiones

Versión	Fecha	Cambios
1.0.0	2024-01-28	Documento inicial

---

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