oxutils 0.1.6__py3-none-any.whl → 0.1.14__py3-none-any.whl

oxutils/permissions/management/commands/load_permission_preset.py

@@ -0,0 +1,112 @@
+from typing import Any
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+
+from oxutils.permissions.utils import load_preset
+
+
+class Command(BaseCommand):
+    """
+    Commande de management Django pour charger un preset de permissions.
+    
+    Usage:
+        python manage.py load_permission_preset
+        python manage.py load_permission_preset --dry-run
+        python manage.py load_permission_preset --force
+        python manage.py load_permission_preset --dry-run --force
+    """
+    
+    help = "Charge un preset de permissions depuis settings.PERMISSION_PRESET"
+
+    def add_arguments(self, parser) -> None:
+        """
+        Ajoute les arguments de la commande.
+        
+        Args:
+            parser: ArgumentParser de Django
+        """
+        parser.add_argument(
+            '--dry-run',
+            action='store_true',
+            help='Simule le chargement sans créer les objets en base de données',
+        )
+        parser.add_argument(
+            '--force',
+            action='store_true',
+            help='Force le chargement même si des rôles existent déjà en base',
+        )
+
+    @transaction.atomic
+    def handle(self, *args: Any, **options: Any) -> None:
+        """
+        Exécute la commande de chargement du preset.
+        
+        Args:
+            *args: Arguments positionnels
+            **options: Options de la commande
+            
+        Raises:
+            CommandError: Si le preset n'est pas défini ou est invalide
+        """
+        dry_run = options.get('dry_run', False)
+        force = options.get('force', False)
+        
+        if dry_run:
+            self.stdout.write(
+                self.style.WARNING('Mode DRY-RUN activé - Aucune modification ne sera effectuée')
+            )
+        
+        if force:
+            self.stdout.write(
+                self.style.WARNING('Mode FORCE activé - Les rôles existants seront ignorés')
+            )
+        
+        try:
+            # Charger le preset
+            self.stdout.write('Chargement du preset de permissions...')
+            
+            if dry_run:
+                # En mode dry-run, on utilise un savepoint pour rollback
+                sid = transaction.savepoint()
+            
+            stats = load_preset(force=force)
+            
+            if dry_run:
+                # Rollback en mode dry-run
+                transaction.savepoint_rollback(sid)
+            
+            # Afficher les statistiques
+            self.stdout.write(
+                self.style.SUCCESS('\n✓ Preset chargé avec succès!')
+            )
+            self.stdout.write(f"  • Rôles créés: {stats['roles']}")
+            self.stdout.write(f"  • Groupes créés: {stats['groups']}")
+            self.stdout.write(f"  • Role grants créés: {stats['role_grants']}")
+            
+            if dry_run:
+                self.stdout.write(
+                    self.style.WARNING('\nAucune modification effectuée (mode dry-run)')
+                )
+            
+        except AttributeError as e:
+            raise CommandError(
+                f"Erreur de configuration: {str(e)}\n"
+                "Assurez-vous que PERMISSION_PRESET est défini dans vos settings Django."
+            )
+        
+        except PermissionError as e:
+            raise CommandError(
+                f"{str(e)}\n"
+                "Utilisez --force pour forcer le chargement malgré les rôles existants."
+            )
+        
+        except (KeyError, ValueError) as e:
+            raise CommandError(
+                f"Erreur dans le preset: {str(e)}\n"
+                "Vérifiez la structure de votre PERMISSION_PRESET."
+            )
+        
+        except Exception as e:
+            raise CommandError(
+                f"Erreur inattendue lors du chargement du preset: {str(e)}"
+            )

oxutils/permissions/migrations/0001_initial.py

@@ -0,0 +1,112 @@
+# Generated by Django 5.2.9 on 2025-12-27 10:49
+
+import django.contrib.postgres.fields
+import django.contrib.postgres.indexes
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Role',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Date and time when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Date and time when this record was last updated')),
+                ('slug', models.SlugField(primary_key=True, serialize=False, unique=True)),
+                ('name', models.CharField(max_length=100)),
+            ],
+            options={
+                'indexes': [models.Index(fields=['slug'], name='permissions_slug_ae4163_idx')],
+            },
+        ),
+        migrations.CreateModel(
+            name='Group',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Date and time when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Date and time when this record was last updated')),
+                ('slug', models.SlugField(primary_key=True, serialize=False, unique=True)),
+                ('name', models.CharField(max_length=100)),
+                ('roles', models.ManyToManyField(related_name='groups', to='permissions.role')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='UserGroup',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Date and time when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Date and time when this record was last updated')),
+                ('group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='user_groups', to='permissions.group')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='user_groups', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Grant',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Date and time when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Date and time when this record was last updated')),
+                ('scope', models.CharField(max_length=100)),
+                ('actions', django.contrib.postgres.fields.ArrayField(base_field=models.CharField(max_length=5), size=None)),
+                ('context', models.JSONField(blank=True, default=dict)),
+                ('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='created_grants', to=settings.AUTH_USER_MODEL)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='grants', to=settings.AUTH_USER_MODEL)),
+                ('role', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='grants', to='permissions.role')),
+                ('user_group', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='grants', to='permissions.usergroup')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='RoleGrant',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('scope', models.CharField(max_length=100)),
+                ('actions', django.contrib.postgres.fields.ArrayField(base_field=models.CharField(max_length=5), size=None)),
+                ('context', models.JSONField(blank=True, default=dict)),
+                ('group', models.ForeignKey(blank=True, help_text='Groupe optionnel pour des comportements spécifiques', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='role_grants', to='permissions.group')),
+                ('role', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='grants', to='permissions.role')),
+            ],
+            options={
+                'indexes': [models.Index(fields=['role'], name='permissions_role_id_382ed4_idx'), models.Index(fields=['group'], name='permissions_group_i_465f8d_idx'), models.Index(fields=['role', 'group'], name='permissions_role_id_0818de_idx')],
+                'constraints': [models.UniqueConstraint(fields=('role', 'scope', 'group'), name='unique_role_scope_group')],
+            },
+        ),
+        migrations.AddIndex(
+            model_name='usergroup',
+            index=models.Index(fields=['user', 'group'], name='permissions_user_id_f1ff5d_idx'),
+        ),
+        migrations.AddConstraint(
+            model_name='usergroup',
+            constraint=models.UniqueConstraint(fields=('user', 'group'), name='unique_user_group'),
+        ),
+        migrations.AddIndex(
+            model_name='grant',
+            index=models.Index(fields=['user', 'scope'], name='permissions_user_id_8a615b_idx'),
+        ),
+        migrations.AddIndex(
+            model_name='grant',
+            index=models.Index(fields=['user_group'], name='permissions_user_gr_ec61ff_idx'),
+        ),
+        migrations.AddIndex(
+            model_name='grant',
+            index=django.contrib.postgres.indexes.GinIndex(fields=['actions'], name='permissions_actions_541150_gin'),
+        ),
+        migrations.AddIndex(
+            model_name='grant',
+            index=django.contrib.postgres.indexes.GinIndex(fields=['context'], name='permissions_context_7b1c0e_gin'),
+        ),
+        migrations.AddConstraint(
+            model_name='grant',
+            constraint=models.UniqueConstraint(fields=('user', 'scope', 'role', 'user_group'), name='unique_user_scope_role'),
+        ),
+    ]

oxutils/permissions/migrations/0002_alter_grant_role.py

@@ -0,0 +1,19 @@
+# Generated by Django 5.2.9 on 2025-12-29 09:04
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('permissions', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='grant',
+            name='role',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='user_grants', to='permissions.role'),
+        ),
+    ]

oxutils/permissions/migrations/0003_alter_grant_options_alter_group_options_and_more.py

@@ -0,0 +1,33 @@
+# Generated by Django 5.2.9 on 2025-12-29 13:28
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('permissions', '0002_alter_grant_role'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='grant',
+            options={'ordering': ['scope']},
+        ),
+        migrations.AlterModelOptions(
+            name='group',
+            options={'ordering': ['slug']},
+        ),
+        migrations.AlterModelOptions(
+            name='role',
+            options={'ordering': ['slug']},
+        ),
+        migrations.AlterModelOptions(
+            name='rolegrant',
+            options={'ordering': ['role__slug', 'group__slug']},
+        ),
+        migrations.AddIndex(
+            model_name='group',
+            index=models.Index(fields=['slug'], name='permissions_slug_ed0901_idx'),
+        ),
+    ]

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,201 @@
+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)
+
+
+class ScopeAnyPermission(BasePermission):
+    """
+    Permission class for checking if user has at least one of multiple permissions.
+    
+    Vérifie si l'utilisateur possède au moins une des permissions fournies.
+    Utilise any_permission_check pour une vérification optimisée en une seule requête.
+    
+    Example:
+        @api_controller('/articles', permissions=[
+            ScopeAnyPermission('articles:r', 'articles:w:staff', 'articles:d:admin')
+        ])
+        class ArticleController:
+            # User needs either read access, OR staff write access, OR admin delete access
+            pass
+    """
+
+    def __init__(self, *perms: str):
+        """
+        Initialize the permission checker with multiple permission strings.
+        
+        Args:
+            *perms: Variable number of permission strings in format "<scope>:<actions>:<group>?context"
+        """
+        if not perms:
+            raise ValueError("At least one permission string must be provided")
+        self.perms = perms
+
+    def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool:
+        """
+        Check if the user has at least one of the required permissions.
+        
+        Args:
+            request: HTTP request object
+            controller: Controller instance
+            
+        Returns:
+            True if user has at least one permission, False otherwise
+        """
+        from oxutils.permissions.caches import cache_any_permission_check
+        return cache_any_permission_check(request.user, *self.perms)
+
+
+class ScopeAnyActionPermission(BasePermission):
+    """
+    Permission class for checking if user has at least one of multiple actions on a scope.
+    
+    Vérifie si l'utilisateur possède au moins une des actions requises pour un scope donné.
+    La chaîne d'actions contient plusieurs actions dont au moins une est requise.
+    
+    Example:
+        @api_controller('/articles', permissions=[
+            ScopeAnyActionPermission('articles:rwd:staff')
+        ])
+        class ArticleController:
+            # User needs read OR write OR delete access on articles in staff group
+            pass
+            
+        @api_controller('/invoices', permissions=[
+            ScopeAnyActionPermission('invoices:rw?tenant_id=123')
+        ])
+        class InvoiceController:
+            # User needs read OR write access on invoices with tenant_id=123
+            pass
+    """
+
+    def __init__(self, perm: str, ctx: Optional[dict] = None):
+        """
+        Initialize the permission checker with a permission string.
+        
+        Args:
+            perm: Permission string in format "<scope>:<actions>:<group>?context"
+                  where actions contains multiple characters (e.g., 'rwd' for read OR write OR delete)
+            ctx: Optional additional context dict
+        """
+        if not perm:
+            raise ValueError("Permission string must be provided")
+        
+        self.perm = perm
+        self.ctx = ctx if ctx else dict()
+
+    def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool:
+        """
+        Check if the user has at least one of the required actions.
+        
+        Args:
+            request: HTTP request object
+            controller: Controller instance
+            
+        Returns:
+            True if user has at least one action, False otherwise
+        """
+        from oxutils.permissions.caches import cache_any_action_check
+        from oxutils.permissions.utils import parse_permission
+        
+        scope, actions, group, query_context = parse_permission(self.perm)
+        final_context = {**query_context, **self.ctx}
+        
+        return cache_any_action_check(
+            request.user,
+            scope,
+            actions,
+            group,
+            **final_context
+        )
+
+
+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)