austial-authz 0.2.0__py3-none-any.whl

austial/authz/__init__.py

@@ -0,0 +1,41 @@
+"""``austial.authz`` -- role- and permission-based access control.
+
+Provides ``@Roles(*names)`` and ``@Permissions(*names)`` metadata decorators,
+``RolesGuard`` (rejects requests whose authenticated principal lacks the required
+roles/permissions), ``PermissionService`` (programmatic checks from services and
+background jobs), and ``@AuthorizeObject(rule)`` (object-level authorisation --
+inject the loaded object into the guard's context so the rule can inspect
+ownership, tenant, status, etc. before the handler runs).
+
+The framework enforces "does this principal have the claim?" -- product code
+decides "what roles does this user have?" by populating the JWT's ``roles`` and
+``permissions`` claims at login time.
+"""
+
+from austial.authz.authz_module import AuthzModule
+from austial.authz.decorators import (
+    AUTHORIZE_OBJECT_METADATA,
+    PERMISSIONS_METADATA,
+    ROLES_METADATA,
+    AuthorizeObject,
+    Permissions,
+    Roles,
+)
+from austial.authz.errors import InsufficientPermissionsError, InsufficientRolesError
+from austial.authz.permission_service import ObjectAuthorizationRule, PermissionService
+from austial.authz.roles_guard import RolesGuard
+
+__all__ = [
+    "AUTHORIZE_OBJECT_METADATA",
+    "AuthzModule",
+    "AuthorizeObject",
+    "InsufficientPermissionsError",
+    "InsufficientRolesError",
+    "ObjectAuthorizationRule",
+    "PERMISSIONS_METADATA",
+    "PermissionService",
+    "Permissions",
+    "ROLES_METADATA",
+    "Roles",
+    "RolesGuard",
+]

austial/authz/authz_module.py

@@ -0,0 +1,19 @@
+"""``AuthzModule.for_root(...)`` -- provides ``RolesGuard`` and ``PermissionService``."""
+
+from __future__ import annotations
+
+from austial.authz.permission_service import PermissionService
+from austial.authz.roles_guard import RolesGuard
+from austial.common.decorators.modules import Module
+from austial.core.dynamic_module import DynamicModule
+
+
+@Module()
+class AuthzModule:
+    @staticmethod
+    def for_root(*, is_global: bool = True) -> DynamicModule:
+        return DynamicModule(
+            module=AuthzModule,
+            providers=[RolesGuard, PermissionService],
+            exports=[RolesGuard, PermissionService],
+        )

austial/authz/decorators.py

@@ -0,0 +1,56 @@
+"""``@Roles(...)``, ``@Permissions(...)``, ``@AuthorizeObject(rule)`` -- metadata
+decorators the ``RolesGuard`` reads.
+
+Semantics:
+
+- ``@Roles(*names)`` -- caller must hold **any** of the listed roles.
+- ``@Permissions(*names)`` -- caller must hold **all** of the listed permissions.
+- ``@AuthorizeObject(rule)`` -- takes a callable ``(principal, request) -> bool``.
+  Runs after roles/permissions succeed, so it is the object-level gate.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import get_metadata, set_metadata
+
+ROLES_METADATA = "austial:authz:roles"
+PERMISSIONS_METADATA = "austial:authz:permissions"
+AUTHORIZE_OBJECT_METADATA = "austial:authz:authorize_object"
+
+
+def Roles(*roles: str) -> Callable:  # noqa: N802
+    """Require the principal to hold ANY of the given roles."""
+
+    def decorator(target):
+        existing = tuple(get_metadata(ROLES_METADATA, target, ()))
+        set_metadata(ROLES_METADATA, existing + tuple(roles))(target)
+        return target
+
+    return decorator
+
+
+def Permissions(*permissions: str) -> Callable:  # noqa: N802
+    """Require the principal to hold ALL of the given permissions."""
+
+    def decorator(target):
+        existing = tuple(get_metadata(PERMISSIONS_METADATA, target, ()))
+        set_metadata(PERMISSIONS_METADATA, existing + tuple(permissions))(target)
+        return target
+
+    return decorator
+
+
+def AuthorizeObject(rule: Callable[[Any, Any], bool]) -> Callable:  # noqa: N802
+    """Attach an object-level authorisation callable to a handler.
+
+    ``rule(principal, request) -> bool`` runs after role/permission checks pass.
+    Returning ``False`` (or raising) rejects the request."""
+
+    def decorator(target):
+        set_metadata(AUTHORIZE_OBJECT_METADATA, rule)(target)
+        return target
+
+    return decorator

austial/authz/errors.py

@@ -0,0 +1,19 @@
+"""Authorisation-specific exceptions -- 403 with sub-types for observability."""
+
+from __future__ import annotations
+
+from austial.common.exceptions import ForbiddenException
+
+
+class InsufficientRolesError(ForbiddenException):
+    def __init__(self, required: tuple[str, ...], actual: tuple[str, ...]):
+        super().__init__(f"Missing required role(s): {list(required)}")
+        self.required = required
+        self.actual = actual
+
+
+class InsufficientPermissionsError(ForbiddenException):
+    def __init__(self, required: tuple[str, ...], actual: tuple[str, ...]):
+        super().__init__(f"Missing required permission(s): {list(required)}")
+        self.required = required
+        self.actual = actual

austial/authz/permission_service.py

@@ -0,0 +1,55 @@
+"""``PermissionService`` -- programmatic role/permission checks.
+
+Use from services or background jobs where a decorator is inconvenient. Also
+carries the type alias used by ``@AuthorizeObject``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.common.decorators.injectable import Injectable
+
+# ``(principal, request_or_context) -> bool``. Product code implements the rule.
+ObjectAuthorizationRule = Callable[[Any, Any], bool]
+
+
+@Injectable()
+class PermissionService:
+    @staticmethod
+    def has_any_role(principal: Any, roles: tuple[str, ...]) -> bool:
+        """True if ``principal.claims['roles']`` intersects ``roles``. Missing
+        claim => False."""
+        actual = _actual_roles(principal)
+        return any(r in actual for r in roles)
+
+    @staticmethod
+    def has_all_permissions(principal: Any, permissions: tuple[str, ...]) -> bool:
+        """True if every requested permission is in ``principal.claims['permissions']``."""
+        actual = _actual_permissions(principal)
+        return all(p in actual for p in permissions)
+
+    @staticmethod
+    def get_roles(principal: Any) -> tuple[str, ...]:
+        return _actual_roles(principal)
+
+    @staticmethod
+    def get_permissions(principal: Any) -> tuple[str, ...]:
+        return _actual_permissions(principal)
+
+
+def _actual_roles(principal: Any) -> tuple[str, ...]:
+    if principal is None or not hasattr(principal, "claims"):
+        return ()
+    claims = principal.claims or {}
+    value = claims.get("roles", ()) if isinstance(claims, dict) else ()
+    return tuple(value) if isinstance(value, list | tuple) else ()
+
+
+def _actual_permissions(principal: Any) -> tuple[str, ...]:
+    if principal is None or not hasattr(principal, "claims"):
+        return ()
+    claims = principal.claims or {}
+    value = claims.get("permissions", ()) if isinstance(claims, dict) else ()
+    return tuple(value) if isinstance(value, list | tuple) else ()

austial/authz/roles_guard.py

@@ -0,0 +1,78 @@
+"""``RolesGuard`` -- checks ``@Roles``, ``@Permissions``, then ``@AuthorizeObject``.
+
+Order matters: cheap claim checks first, expensive object-level rule last.
+Reads the authenticated principal from ``request.state.user`` (set by
+``AuthGuard``). No principal + no metadata => allow (the route is public
+w.r.t. authz) unless ``deny_undeclared`` is set. No principal + metadata => 403.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.authz.decorators import (
+    AUTHORIZE_OBJECT_METADATA,
+    PERMISSIONS_METADATA,
+    ROLES_METADATA,
+)
+from austial.authz.errors import InsufficientPermissionsError, InsufficientRolesError
+from austial.authz.permission_service import PermissionService
+from austial.common.decorators.injectable import Injectable
+from austial.common.exceptions import ForbiddenException
+from austial.common.guards.base import CanActivate, ExecutionContext
+from austial.core.metadata import get_metadata
+
+
+def _merge(handler_meta: tuple[Any, ...], class_meta: tuple[Any, ...]) -> tuple[Any, ...]:
+    """Union of class-level and handler-level metadata (both apply)."""
+    return tuple(dict.fromkeys(class_meta + handler_meta))
+
+
+@Injectable()
+class RolesGuard(CanActivate):
+    #: Deny-by-default. ``False`` (the default) lets a handler that declares no ``@Roles``,
+    #: ``@Permissions`` or ``@AuthorizeObject`` through, so a forgotten decorator is silently open to
+    #: every authenticated caller. A product that wants "every route must declare a policy" subclasses
+    #: and sets ``True``: an undeclared handler is then a 403 (the subclass lets ``@Public`` routes
+    #: through first).
+    deny_undeclared: bool = False
+
+    async def can_activate(self, context: ExecutionContext) -> bool:
+        handler = context.get_handler()
+        controller = context.get_class()
+
+        required_roles = _merge(
+            tuple(get_metadata(ROLES_METADATA, handler, ())),
+            tuple(get_metadata(ROLES_METADATA, controller, ())),
+        )
+        required_perms = _merge(
+            tuple(get_metadata(PERMISSIONS_METADATA, handler, ())),
+            tuple(get_metadata(PERMISSIONS_METADATA, controller, ())),
+        )
+        object_rule = get_metadata(AUTHORIZE_OBJECT_METADATA, handler, None) or get_metadata(
+            AUTHORIZE_OBJECT_METADATA, controller, None
+        )
+
+        if not required_roles and not required_perms and object_rule is None:
+            if self.deny_undeclared:
+                raise ForbiddenException("No access policy declared for this route")
+            return True
+
+        request = context.get_request()
+        principal = getattr(request.state, "user", None)
+        if principal is None:
+            # metadata requires something, no principal => fail closed
+            raise ForbiddenException("Authentication required")
+
+        if required_roles and not PermissionService.has_any_role(principal, required_roles):
+            raise InsufficientRolesError(required_roles, PermissionService.get_roles(principal))
+
+        if required_perms and not PermissionService.has_all_permissions(principal, required_perms):
+            raise InsufficientPermissionsError(required_perms, PermissionService.get_permissions(principal))
+
+        if object_rule is not None:
+            ok = object_rule(principal, request)
+            if not ok:
+                raise ForbiddenException("Object authorisation denied")
+
+        return True

austial_authz-0.2.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: austial-authz
+Version: 0.2.0
+Summary: Role- and permission-based access control -- @Roles, @Permissions, RolesGuard, PermissionService, object-level authorisation.
+Requires-Python: >=3.11
+Requires-Dist: austial-auth
+Requires-Dist: austial-common
+Requires-Dist: austial-core

austial_authz-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+austial/authz/__init__.py,sha256=cdWh0ZEtg81C5HDJhabu2BhB1RvkWe5AWQ6VNASI6X0,1475
+austial/authz/authz_module.py,sha256=Elgv2SI9dUiSoP10sUVWzvAuUO76Lj4thTayrfY11q0,637
+austial/authz/decorators.py,sha256=G4G6oPT9r4sTgY3ESyG5yCj8t9SLooIOIrMgH0-Cm9g,1867
+austial/authz/errors.py,sha256=SSt5U3CyQVpu47-CH_ya9FD3clzQqIMAVzVVRlzyx5A,711
+austial/authz/permission_service.py,sha256=VqcqIALw4nfDYHxL8LYjXCWCTxcT_mm0GruW_FX5ers,1984
+austial/authz/roles_guard.py,sha256=bXAqphlTlJIpKrabsTV7oWyVgEN9halOkmnR6VYxCIk,3430
+austial_authz-0.2.0.dist-info/METADATA,sha256=pnM07TFWggIjCrG82FF1IDSP6bNp0iQPh0XMn5Wd-LA,302
+austial_authz-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+austial_authz-0.2.0.dist-info/RECORD,,

austial_authz-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any