austial-authz 0.2.0__tar.gz

austial_authz-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

austial_authz-0.2.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "austial-authz"
+dynamic = ["version"]
+description = "Role- and permission-based access control -- @Roles, @Permissions, RolesGuard, PermissionService, object-level authorisation."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "austial-core",
+    "austial-auth",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+austial-core = { workspace = true }
+austial-auth = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_authz-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/test/authz_spec.py

@@ -0,0 +1,188 @@
+"""``austial.authz`` unit tests."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from austial.authz import (
+    AuthorizeObject,
+    InsufficientPermissionsError,
+    InsufficientRolesError,
+    Permissions,
+    PermissionService,
+    Roles,
+    RolesGuard,
+)
+from austial.common import ExecutionContext
+from austial.common.exceptions import ForbiddenException
+
+
+class _FakeCtx(ExecutionContext):
+    def __init__(self, request, controller_class, handler):
+        self._req, self._cls, self._h = request, controller_class, handler
+
+    def get_request(self):
+        return self._req
+
+    def get_class(self):
+        return self._cls
+
+    def get_handler(self):
+        return self._h
+
+
+def _principal(roles=(), permissions=()):
+    return SimpleNamespace(claims={"roles": list(roles), "permissions": list(permissions)})
+
+
+def _request(principal):
+    return SimpleNamespace(state=SimpleNamespace(user=principal))
+
+
+# PermissionService ---------------------------------------------------------
+
+
+def test_has_any_role_true_when_one_matches():
+    p = _principal(roles=("ops", "compliance"))
+    assert PermissionService.has_any_role(p, ("compliance",)) is True
+
+
+def test_has_any_role_false_on_disjoint():
+    p = _principal(roles=("ops",))
+    assert PermissionService.has_any_role(p, ("admin",)) is False
+
+
+def test_has_all_permissions_requires_every_one():
+    p = _principal(permissions=("read:invoice", "write:invoice"))
+    assert PermissionService.has_all_permissions(p, ("read:invoice",)) is True
+    assert PermissionService.has_all_permissions(p, ("read:invoice", "write:invoice")) is True
+    assert PermissionService.has_all_permissions(p, ("read:invoice", "delete:invoice")) is False
+
+
+def test_has_any_role_false_for_missing_principal():
+    assert PermissionService.has_any_role(None, ("ops",)) is False
+
+
+# RolesGuard ----------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_guard_allows_when_no_metadata_present():
+    guard = RolesGuard()
+
+    def handler():
+        pass
+
+    ctx = _FakeCtx(_request(None), object, handler)
+    assert await guard.can_activate(ctx) is True
+
+
+@pytest.mark.asyncio
+async def test_guard_rejects_without_principal_when_metadata_present():
+    guard = RolesGuard()
+
+    @Roles("ops")
+    def handler():
+        pass
+
+    ctx = _FakeCtx(_request(None), object, handler)
+    with pytest.raises(ForbiddenException):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_guard_allows_role_match():
+    guard = RolesGuard()
+
+    @Roles("ops", "admin")
+    def handler():
+        pass
+
+    ctx = _FakeCtx(_request(_principal(roles=("ops",))), object, handler)
+    assert await guard.can_activate(ctx) is True
+
+
+@pytest.mark.asyncio
+async def test_guard_rejects_role_mismatch():
+    guard = RolesGuard()
+
+    @Roles("admin")
+    def handler():
+        pass
+
+    ctx = _FakeCtx(_request(_principal(roles=("ops",))), object, handler)
+    with pytest.raises(InsufficientRolesError):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_guard_rejects_missing_permission():
+    guard = RolesGuard()
+
+    @Permissions("delete:invoice")
+    def handler():
+        pass
+
+    ctx = _FakeCtx(_request(_principal(permissions=("read:invoice",))), object, handler)
+    with pytest.raises(InsufficientPermissionsError):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_guard_runs_object_rule_last():
+    guard = RolesGuard()
+
+    def rule(principal, request):
+        return principal.claims.get("subject") == "owner"
+
+    @Roles("ops")
+    @AuthorizeObject(rule)
+    def handler():
+        pass
+
+    p_ok = _principal(roles=("ops",))
+    p_ok.claims["subject"] = "owner"
+    ctx_ok = _FakeCtx(_request(p_ok), object, handler)
+    assert await guard.can_activate(ctx_ok) is True
+
+    p_no = _principal(roles=("ops",))
+    ctx_no = _FakeCtx(_request(p_no), object, handler)
+    with pytest.raises(ForbiddenException):
+        await guard.can_activate(ctx_no)
+
+
+@pytest.mark.asyncio
+async def test_guard_merges_class_and_handler_metadata():
+    guard = RolesGuard()
+
+    @Roles("admin")
+    class Ctrl:
+        pass
+
+    @Roles("ops")
+    def handler():
+        pass
+
+    # principal with "ops" satisfies the union (any-of), not the intersection
+    ctx = _FakeCtx(_request(_principal(roles=("ops",))), Ctrl, handler)
+    assert await guard.can_activate(ctx) is True
+
+
+@pytest.mark.asyncio
+async def test_deny_undeclared_guard_rejects_handler_without_a_policy():
+    class StrictRolesGuard(RolesGuard):
+        deny_undeclared = True
+
+    def undeclared():
+        pass
+
+    @Roles("ops")
+    def declared():
+        pass
+
+    strict = StrictRolesGuard()
+    with pytest.raises(ForbiddenException):
+        await strict.can_activate(_FakeCtx(_request(_principal(roles=("ops",))), object, undeclared))
+    assert await strict.can_activate(_FakeCtx(_request(_principal(roles=("ops",))), object, declared)) is True