oxutils 0.1.7__py3-none-any.whl → 0.1.10__py3-none-any.whl

oxutils/permissions/models.py

@@ -0,0 +1,171 @@
+from django.conf import settings
+from django.db import models
+from django.contrib.postgres.fields import ArrayField
+from django.contrib.postgres.indexes import GinIndex
+from oxutils.models import TimestampMixin
+from .actions import expand_actions
+
+
+
+
+class Role(TimestampMixin):
+    """
+    A role.
+    """
+    slug = models.SlugField(unique=True, primary_key=True)
+    name = models.CharField(max_length=100)
+
+    def __str__(self):
+        return self.slug
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["slug"]),
+        ]
+        ordering = ["slug"]
+
+
+class Group(TimestampMixin):
+    """
+    A group of roles. for UI Template purposes.
+    """
+    slug = models.SlugField(unique=True, primary_key=True)
+    name = models.CharField(max_length=100)
+    roles = models.ManyToManyField(Role, related_name="groups")
+
+    def __str__(self):
+        return self.slug
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["slug"]),
+        ]
+        ordering = ["slug"]
+
+
+class UserGroup(TimestampMixin):
+    """
+    A user group that links users to groups.
+    """
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="user_groups",
+    )
+    group = models.ForeignKey(
+        Group,
+        on_delete=models.CASCADE,
+        related_name="user_groups",
+    )
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(fields=['user', 'group'], name='unique_user_group')
+        ]
+        indexes = [
+            models.Index(fields=['user', 'group']),
+        ]
+
+
+class RoleGrant(models.Model):
+    """
+    A grant template of permissions to a role.
+    Peut être lié à un groupe spécifique pour des comportements distincts.
+    """
+    role = models.ForeignKey(Role, on_delete=models.CASCADE, related_name="grants")
+    group = models.ForeignKey(
+        Group,
+        null=True,
+        blank=True,
+        on_delete=models.CASCADE,
+        related_name="role_grants",
+        help_text="Groupe optionnel pour des comportements spécifiques"
+    )
+
+    scope = models.CharField(max_length=100)
+    actions = ArrayField(models.CharField(max_length=5))
+    context = models.JSONField(default=dict, blank=True)
+
+    def clean(self):
+        self.actions = expand_actions(self.actions)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["role", "scope", "group"], name="unique_role_scope_group"
+            )
+        ]
+        indexes = [
+            models.Index(fields=["role"]),
+            models.Index(fields=["group"]),
+            models.Index(fields=["role", "group"]),
+        ]
+        ordering = ["role__slug", "group__slug"]
+
+    def __str__(self):
+        group_str = f"[{self.group.slug}]" if self.group else ""
+        return f"{self.role}:{self.scope}{group_str}:{self.actions}"
+
+
+    def save(self, *args, **kwargs):
+        self.clean()
+        super().save(*args, **kwargs)
+
+
+class Grant(TimestampMixin):
+    """
+    A grant of permissions to a user.
+    """
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="grants",
+    )
+
+    # traçabilité
+    role = models.ForeignKey(
+        Role,
+        null=True,
+        blank=True,
+        related_name="user_grants",
+        on_delete=models.SET_NULL,
+    )
+    
+    # Lien avec UserGroup pour tracer l'origine du grant
+    user_group = models.ForeignKey(
+        'UserGroup',
+        null=True,
+        blank=True,
+        related_name="grants",
+        on_delete=models.SET_NULL,
+    )
+
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        null=True,
+        blank=True,
+        related_name="created_grants",
+        on_delete=models.SET_NULL,
+    )
+
+    scope = models.CharField(max_length=100)
+    actions = ArrayField(models.CharField(max_length=5))
+    context = models.JSONField(default=dict, blank=True)
+
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "scope", "role", "user_group"], name="unique_user_scope_role"
+            )
+        ]
+        indexes = [
+            models.Index(fields=["user", "scope"]),
+            models.Index(fields=["user_group"]),
+            GinIndex(fields=["actions"]),
+            GinIndex(fields=["context"]),
+        ]
+        ordering = ["scope"]
+
+    def __str__(self):
+        return f"{self.user} {self.scope} {self.actions}"

oxutils/permissions/perms.py

@@ -0,0 +1,95 @@
+from typing import Optional
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpRequest
+from ninja_extra.permissions import BasePermission
+from ninja_extra.controllers import ControllerBase
+
+from oxutils.permissions.utils import str_check
+
+
+
+class ScopePermission(BasePermission):
+    """
+    Permission class for checking user permissions using the string format.
+    
+    Format: "<scope>:<actions>:<group>?key=value"
+    
+    Example:
+        @api_controller('/articles', permissions=[ScopePermission('articles:w:staff')])
+        class ArticleController:
+            pass
+    """
+
+    def __init__(self, perm: str, ctx: Optional[dict] = None):
+        """
+        Initialize the permission checker.
+        
+        Args:
+            perm: Permission string in format "<scope>:<actions>:<group>?context"
+        """
+        self.perm = perm
+        self.ctx = ctx if ctx else dict()
+
+    def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool:
+        """
+        Check if the user has the required permission.
+        
+        Args:
+            request: HTTP request object
+            controller: Controller instance
+            
+        Returns:
+            True if user has permission, False otherwise
+        """
+        return str_check(request.user, self.perm, **self.ctx)
+
+
+def access_manager(actions: str):
+    """
+    Factory function for creating ScopePermission instances for access manager.
+    
+    Builds a permission string from settings:
+    - ACCESS_MANAGER_SCOPE: The scope to check
+    - ACCESS_MANAGER_GROUP: Optional group filter
+    - ACCESS_MANAGER_CONTEXT: Optional context dict converted to query params
+    
+    Args:
+        actions: Actions required (e.g., 'r', 'rw', 'rwd')
+        
+    Returns:
+        ScopePermission instance configured with access manager settings
+        
+    Raises:
+        ImproperlyConfigured: If required settings are missing
+        
+    Example:
+        @api_controller('/access', permissions=[access_manager('w')])
+        class AccessController:
+            pass
+    """
+    # Validate required settings
+    if not hasattr(settings, 'ACCESS_MANAGER_SCOPE'):
+        raise ImproperlyConfigured(
+            'ACCESS_MANAGER_SCOPE is not defined. '
+            'Add ACCESS_MANAGER_SCOPE = "access" to your settings.'
+        )
+    
+    # Build base permission string: scope:actions
+    perm = f"{settings.ACCESS_MANAGER_SCOPE}:{actions}"
+    
+    # Add group if defined and not None
+    if hasattr(settings, 'ACCESS_MANAGER_GROUP') and settings.ACCESS_MANAGER_GROUP is not None:
+        perm += f":{settings.ACCESS_MANAGER_GROUP}"
+    
+    # Get context if defined and not empty
+    context = {}
+    if hasattr(settings, 'ACCESS_MANAGER_CONTEXT') and settings.ACCESS_MANAGER_CONTEXT:
+        context = settings.ACCESS_MANAGER_CONTEXT
+        if not isinstance(context, dict):
+            raise ImproperlyConfigured(
+                'ACCESS_MANAGER_CONTEXT must be a dictionary. '
+                f'Got {type(context).__name__} instead.'
+            )
+    
+    return ScopePermission(perm, context)

oxutils/permissions/queryset.py

@@ -0,0 +1,92 @@
+from typing import Any
+from django.db import models
+from django.db.models import Q
+from django.contrib.auth.models import AbstractBaseUser
+
+from .models import Grant
+
+
+class PermissionQuerySet(models.QuerySet):
+    """
+    QuerySet personnalisé pour filtrer des objets selon les permissions d'un utilisateur.
+    Permet de filtrer des querysets en fonction des grants de permissions.
+    """
+
+    def allowed_for(
+        self,
+        user: AbstractBaseUser,
+        scope: str,
+        required_actions: list[str],
+        **context: Any
+    ) -> "PermissionQuerySet":
+        """
+        Filtre les objets si l'utilisateur a les permissions requises.
+        Vérifie l'existence d'un grant valide avant de retourner le queryset.
+        
+        Args:
+            user: L'utilisateur dont on vérifie les permissions
+            scope: Le scope à vérifier (ex: 'articles', 'users')
+            required_actions: Liste des actions requises (ex: ['r'], ['w', 'r'])
+            **context: Contexte additionnel pour filtrer (ex: tenant_id=123)
+            
+        Returns:
+            QuerySet complet si autorisé, QuerySet vide sinon
+            
+        Example:
+            >>> Article.objects.allowed_for(user, 'articles', ['r'])
+            >>> Article.objects.allowed_for(user, 'articles', ['w'], tenant_id=123)
+        """
+        # Construire le filtre pour vérifier l'existence d'un grant
+        grant_filter = Q(
+            user__pk=user.pk,
+            scope=scope,
+            actions__contains=list(required_actions),
+        )
+        
+        # Ajouter les filtres de contexte si fournis
+        if context:
+            grant_filter &= Q(context__contains=context)
+        
+        # Si un grant existe, retourner le queryset complet, sinon vide
+        if Grant.objects.filter(grant_filter).exists():
+            return self
+        return self.none()
+
+    def denied_for(
+        self,
+        user: AbstractBaseUser,
+        scope: str,
+        required_actions: list[str],
+        **context: Any
+    ) -> "PermissionQuerySet":
+        """
+        Filtre les objets si l'utilisateur N'A PAS les permissions requises.
+        Inverse de allowed_for.
+        
+        Args:
+            user: L'utilisateur dont on vérifie les permissions
+            scope: Le scope à vérifier
+            required_actions: Liste des actions requises
+            **context: Contexte additionnel pour filtrer
+            
+        Returns:
+            QuerySet complet si NON autorisé, QuerySet vide si autorisé
+            
+        Example:
+            >>> Article.objects.denied_for(user, 'articles', ['w'])
+        """
+        # Construire le filtre pour vérifier l'existence d'un grant
+        grant_filter = Q(
+            user__pk=user.pk,
+            scope=scope,
+            actions__contains=list(required_actions),
+        )
+        
+        # Ajouter les filtres de contexte si fournis
+        if context:
+            grant_filter &= Q(context__contains=context)
+        
+        # Si un grant existe, retourner vide, sinon le queryset complet
+        if Grant.objects.filter(grant_filter).exists():
+            return self.none()
+        return self

oxutils/permissions/schemas.py

@@ -0,0 +1,276 @@
+from typing import Any, Optional
+from datetime import datetime
+from ninja import Schema
+from pydantic import field_validator
+
+from .actions import ACTIONS
+
+
+def validate_actions_list(actions: list[str]) -> list[str]:
+    """
+    Valide qu'une liste d'actions contient uniquement des actions valides.
+    
+    Args:
+        actions: Liste des actions à valider
+        
+    Returns:
+        La liste d'actions si valide
+        
+    Raises:
+        ValueError: Si des actions invalides sont présentes
+    """
+    invalid_actions = [a for a in actions if a not in ACTIONS]
+    if invalid_actions:
+        raise ValueError(
+            f"Actions invalides: {invalid_actions}. "
+            f"Actions valides: {ACTIONS}"
+        )
+    return actions
+
+
+class RoleSchema(Schema):
+    """
+    Schéma pour un rôle.
+    """
+    slug: str
+    name: str
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class RoleCreateSchema(Schema):
+    """
+    Schéma pour la création d'un rôle.
+    """
+    slug: str
+    name: str
+
+
+class RoleUpdateSchema(Schema):
+    """
+    Schéma pour la mise à jour d'un rôle.
+    """
+    name: Optional[str] = None
+
+
+class GroupSchema(Schema):
+    """
+    Schéma pour un groupe.
+    """
+    slug: str
+    name: str
+    roles: list[RoleSchema] = []
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class GroupCreateSchema(Schema):
+    """
+    Schéma pour la création d'un groupe.
+    """
+    slug: str
+    name: str
+    roles: list[str] = []
+
+
+class GroupUpdateSchema(Schema):
+    """
+    Schéma pour la mise à jour d'un groupe.
+    """
+    name: Optional[str] = None
+    roles: Optional[list[str]] = None
+
+
+class RoleGrantSchema(Schema):
+    """
+    Schéma pour un role grant.
+    """
+    id: int
+    role: RoleSchema
+    scope: str
+    actions: list[str]
+    context: dict[str, Any] = {}
+
+    class Config:
+        from_attributes = True
+
+
+class RoleGrantCreateSchema(Schema):
+    """
+    Schéma pour la création d'un role grant.
+    """
+    role: str
+    scope: str
+    actions: list[str]
+    context: dict[str, Any] = {}
+    
+    @field_validator('actions')
+    @classmethod
+    def validate_actions(cls, v: list[str]) -> list[str]:
+        """Valide que toutes les actions sont valides."""
+        return validate_actions_list(v)
+
+
+class RoleGrantUpdateSchema(Schema):
+    """
+    Schéma pour la mise à jour d'un role grant.
+    """
+    actions: Optional[list[str]] = None
+    context: Optional[dict[str, Any]] = None
+    
+    @field_validator('actions')
+    @classmethod
+    def validate_actions(cls, v: Optional[list[str]]) -> Optional[list[str]]:
+        """Valide que toutes les actions sont valides."""
+        if v is not None:
+            return validate_actions_list(v)
+        return v
+
+
+class GrantSchema(Schema):
+    """
+    Schéma pour un grant utilisateur.
+    """
+    id: int
+    user_id: int
+    role: Optional[RoleSchema] = None
+    scope: str
+    actions: list[str]
+    context: dict[str, Any] = {}
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class GrantCreateSchema(Schema):
+    """
+    Schéma pour la création d'un grant utilisateur.
+    """
+    user_id: int
+    scope: str
+    actions: list[str]
+    context: dict[str, Any] = {}
+    role: Optional[str] = None
+    
+    @field_validator('actions')
+    @classmethod
+    def validate_actions(cls, v: list[str]) -> list[str]:
+        """Valide que toutes les actions sont valides."""
+        return validate_actions_list(v)
+
+
+class GrantUpdateSchema(Schema):
+    """
+    Schéma pour la mise à jour d'un grant utilisateur.
+    """
+    actions: Optional[list[str]] = None
+    context: Optional[dict[str, Any]] = None
+    role: Optional[str] = None
+    
+    @field_validator('actions')
+    @classmethod
+    def validate_actions(cls, v: Optional[list[str]]) -> Optional[list[str]]:
+        """Valide que toutes les actions sont valides."""
+        if v is not None:
+            return validate_actions_list(v)
+        return v
+
+
+class PermissionCheckSchema(Schema):
+    """
+    Schéma pour une requête de vérification de permissions.
+    """
+    user_id: int
+    scope: str
+    required_actions: list[str]
+    context: dict[str, Any] = {}
+    
+    @field_validator('required_actions')
+    @classmethod
+    def validate_actions(cls, v: list[str]) -> list[str]:
+        """Valide que toutes les actions sont valides."""
+        return validate_actions_list(v)
+
+
+class PermissionCheckResponseSchema(Schema):
+    """
+    Schéma pour la réponse d'une vérification de permissions.
+    """
+    allowed: bool
+    user_id: int
+    scope: str
+    required_actions: list[str]
+
+
+class AssignRoleSchema(Schema):
+    """
+    Schéma pour assigner un rôle à un utilisateur.
+    """
+    user_id: int
+    role: str
+    by_user_id: Optional[int] = None
+
+
+class RevokeRoleSchema(Schema):
+    """
+    Schéma pour révoquer un rôle d'un utilisateur.
+    """
+    user_id: int
+    role: str
+
+
+class AssignGroupSchema(Schema):
+    """
+    Schéma pour assigner un groupe à un utilisateur.
+    """
+    user_id: int
+    group: str
+
+
+class RevokeGroupSchema(Schema):
+    """
+    Schéma pour révoquer un groupe d'un utilisateur.
+    """
+    user_id: int
+    group: str
+
+
+class OverrideGrantSchema(Schema):
+    """
+    Schéma pour modifier un grant en retirant des actions.
+    """
+    user_id: int
+    scope: str
+    remove_actions: list[str]
+    
+    @field_validator('remove_actions')
+    @classmethod
+    def validate_actions(cls, v: list[str]) -> list[str]:
+        """Valide que toutes les actions sont valides."""
+        return validate_actions_list(v)
+
+
+class GroupSyncResponseSchema(Schema):
+    """
+    Schéma pour la réponse de la synchronisation d'un groupe.
+    """
+    users_synced: int
+    grants_updated: int
+
+
+class PresetLoadResponseSchema(Schema):
+    """
+    Schéma pour la réponse du chargement d'un preset.
+    """
+    roles_created: int
+    groups_created: int
+    role_grants_created: int
+    message: str = "Preset chargé avec succès"