refactor: introduce declarative permission pattern for authorization

Replace procedural authorization logic with a declarative Permission/Policy pattern.
This improves code clarity, maintainability, and testability.

Key changes:
- Add Permission abstraction and concrete implementations (IsSelf, IsSuperior, etc.)
- Add composite permissions (AnyOf, AllOf) for complex authorization rules
- Extend AuthorizationService with declarative authorize() method
- Refactor ChangePasswordInteractor and GrantAdminInteractor to use new pattern

The old procedural methods are retained for backward compatibility.
This change demonstrates Clean Architecture principles by improving
the application layer abstractions without affecting other layers.

Author: ppravdin

src/app/application/commands/change_password.py

@@ -1,7 +1,7 @@
 import logging
 from dataclasses import dataclass
 
-from app.application.common.exceptions.authorization import AuthorizationError
+from app.application.common.permissions import AnyOf, IsSelf, IsSuperior
 from app.application.common.ports.transaction_manager import (
     TransactionManager,
 )
@@ -65,16 +65,12 @@ async def __call__(self, request_data: ChangePasswordRequest) -> None:
         if user is None:
             raise UserNotFoundByUsernameError(username)
 
-        try:
-            self._authorization_service.authorize_for_self(
-                current_user.id_,
-                target_id=user.id_,
-            )
-        except AuthorizationError:
-            self._authorization_service.authorize_for_subordinate_role(
-                current_user.role,
-                target_role=user.role,
-            )
+        # Declarative authorization: can change own or subordinate's password
+        self._authorization_service.authorize(
+            current_user,
+            AnyOf(IsSelf(), IsSuperior()),
+            target_user=user,
+        )
 
         self._user_service.change_password(user, password)
         await self._transaction_manager.commit()

src/app/application/commands/grant_admin.py

@@ -1,6 +1,7 @@
 import logging
 from dataclasses import dataclass
 
+from app.application.common.permissions import CanManageRole
 from app.application.common.ports.transaction_manager import (
     TransactionManager,
 )
@@ -56,9 +57,11 @@ async def __call__(self, request_data: GrantAdminRequest) -> None:
         )
 
         current_user = await self._current_user_service.get_current_user()
-        self._authorization_service.authorize_for_subordinate_role(
-            current_user.role,
-            target_role=UserRole.ADMIN,
+
+        # Declarative authorization: only users who can manage ADMIN role
+        self._authorization_service.authorize(
+            current_user,
+            CanManageRole(UserRole.ADMIN),
         )
 
         username = Username(request_data.username)

src/app/application/common/permissions.py

@@ -0,0 +1,78 @@
+"""Permission policies for declarative authorization."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from app.application.common.services.authorization import SUBORDINATE_ROLES
+from app.domain.entities.user import User
+from app.domain.enums.user_role import UserRole
+
+
+class Permission(ABC):
+    """Base class for a permission policy."""
+
+    @abstractmethod
+    def is_satisfied_by(self, current_user: User, **kwargs: Any) -> bool:
+        """Check if the permission is satisfied for the given user and context."""
+        ...
+
+
+class IsSelf(Permission):
+    """Permission that checks if the user is acting on themselves."""
+
+    def is_satisfied_by(
+        self, current_user: User, *, target_user: User, **kwargs: Any
+    ) -> bool:
+        """Check if current user is the same as target user."""
+        _ = kwargs  # Unused but required for interface
+        return current_user.id_ == target_user.id_
+
+
+class IsSuperior(Permission):
+    """Permission that checks if the user has a superior role over the target."""
+
+    def is_satisfied_by(
+        self, current_user: User, *, target_user: User, **kwargs: Any
+    ) -> bool:
+        """Check if current user's role is superior to target user's role."""
+        _ = kwargs  # Unused but required for interface
+        allowed_roles = SUBORDINATE_ROLES.get(current_user.role, set())
+        return target_user.role in allowed_roles
+
+
+class AnyOf(Permission):
+    """Composite permission that is satisfied if ANY sub-permission is satisfied."""
+
+    def __init__(self, *permissions: Permission) -> None:
+        """Initialize with a list of permissions to check."""
+        self._permissions = permissions
+
+    def is_satisfied_by(self, current_user: User, **kwargs: Any) -> bool:
+        """Check if any of the sub-permissions is satisfied."""
+        return any(p.is_satisfied_by(current_user, **kwargs) for p in self._permissions)
+
+
+class AllOf(Permission):
+    """Composite permission that is satisfied if ALL sub-permissions are satisfied."""
+
+    def __init__(self, *permissions: Permission) -> None:
+        """Initialize with a list of permissions to check."""
+        self._permissions = permissions
+
+    def is_satisfied_by(self, current_user: User, **kwargs: Any) -> bool:
+        """Check if all of the sub-permissions are satisfied."""
+        return all(p.is_satisfied_by(current_user, **kwargs) for p in self._permissions)
+
+
+class CanManageRole(Permission):
+    """Permission that checks if the user can manage a specific role."""
+
+    def __init__(self, target_role: UserRole) -> None:
+        """Initialize with the role to manage."""
+        self._target_role = target_role
+
+    def is_satisfied_by(self, current_user: User, **kwargs: Any) -> bool:
+        """Check if current user can manage the target role."""
+        _ = kwargs  # Unused but required for interface
+        allowed_roles = SUBORDINATE_ROLES.get(current_user.role, set())
+        return self._target_role in allowed_roles

src/app/application/common/services/authorization.py

@@ -1,11 +1,15 @@
 from collections.abc import Mapping
-from typing import Final
+from typing import TYPE_CHECKING, Any, Final
 
 from app.application.common.constants import AUTHZ_NOT_AUTHORIZED
 from app.application.common.exceptions.authorization import AuthorizationError
 from app.domain.enums.user_role import UserRole
 from app.domain.value_objects.user_id import UserId
 
+if TYPE_CHECKING:
+    from app.application.common.permissions import Permission
+    from app.domain.entities.user import User
+
 SUBORDINATE_ROLES: Final[Mapping[UserRole, set[UserRole]]] = {
     UserRole.SUPER_ADMIN: {UserRole.ADMIN, UserRole.USER},
     UserRole.ADMIN: {UserRole.USER},
@@ -14,6 +18,20 @@
 
 
 class AuthorizationService:
+    def authorize(
+        self,
+        current_user: "User",
+        permission: "Permission",
+        **kwargs: Any,
+    ) -> None:
+        """
+        Authorize action using declarative permission policy.
+
+        :raises AuthorizationError: If permission is not satisfied
+        """
+        if not permission.is_satisfied_by(current_user, **kwargs):
+            raise AuthorizationError(AUTHZ_NOT_AUTHORIZED)
+
     def authorize_for_self(
         self,
         current_user_id: UserId,