component_framework.adapters.django_permissions

  1"""Django FBV decorators for component access control.
  2
  3These decorators always return JSON responses (401/403), never redirects,
  4making them safe for HTMX/fetch consumers.
  5"""
  6
  7import functools
  8
  9try:
 10    from django.http import HttpRequest, JsonResponse
 11except ImportError as e:
 12    from . import _require_extra
 13
 14    raise _require_extra("django", "django") from e
 15
 16
 17def login_required_component(view_func):
 18    """
 19    Decorator that requires the user to be authenticated.
 20
 21    Returns a JSON 401 response (never a redirect) for unauthenticated requests.
 22
 23    Usage::
 24
 25        from component_framework.adapters.django_permissions import login_required_component
 26
 27        urlpatterns = [
 28            path("components/<str:name>/", login_required_component(component_view)),
 29        ]
 30    """
 31
 32    @functools.wraps(view_func)
 33    def wrapper(request: HttpRequest, *args, **kwargs):
 34        user = getattr(request, "user", None)
 35        if not user or not user.is_authenticated:
 36            return JsonResponse({"error": "Authentication required"}, status=401)
 37        return view_func(request, *args, **kwargs)
 38
 39    return wrapper
 40
 41
 42def permission_required_component(perm: str | list[str]):
 43    """
 44    Decorator factory that requires the user to hold specific Django permissions.
 45
 46    Returns a JSON 403 response (never a redirect) if permission is denied.
 47
 48    Args:
 49        perm: A permission string (e.g. ``"myapp.change_model"``) or list of
 50              permission strings. When a list is given, the user must hold *all*
 51              permissions.
 52
 53    Usage::
 54
 55        from component_framework.adapters.django_permissions import permission_required_component
 56
 57        urlpatterns = [
 58            path(
 59                "components/<str:name>/",
 60                permission_required_component("myapp.change_model")(component_view),
 61            ),
 62        ]
 63    """
 64    perms: list[str] = [perm] if isinstance(perm, str) else list(perm)
 65
 66    def decorator(view_func):
 67        @functools.wraps(view_func)
 68        def wrapper(request: HttpRequest, *args, **kwargs):
 69            user = getattr(request, "user", None)
 70            if not user or not user.is_authenticated:
 71                return JsonResponse({"error": "Authentication required"}, status=401)
 72            if not all(user.has_perm(p) for p in perms):
 73                return JsonResponse({"error": "Permission denied"}, status=403)
 74            return view_func(request, *args, **kwargs)
 75
 76        return wrapper
 77
 78    return decorator
 79
 80
 81def staff_required_component(view_func):
 82    """
 83    Decorator that requires the user to be a staff member.
 84
 85    Returns a JSON 403 response (never a redirect) for non-staff requests.
 86
 87    Usage::
 88
 89        from component_framework.adapters.django_permissions import staff_required_component
 90
 91        urlpatterns = [
 92            path("components/<str:name>/", staff_required_component(component_view)),
 93        ]
 94    """
 95
 96    @functools.wraps(view_func)
 97    def wrapper(request: HttpRequest, *args, **kwargs):
 98        user = getattr(request, "user", None)
 99        if not user or not user.is_authenticated:
100            return JsonResponse({"error": "Authentication required"}, status=401)
101        if not user.is_staff:
102            return JsonResponse({"error": "Staff access required"}, status=403)
103        return view_func(request, *args, **kwargs)
104
105    return wrapper