Source code for auth_middleware.authz.service

"""Assignment service: where an application enforces its rules around who holds what."""

from __future__ import annotations

import asyncio
import weakref
from collections.abc import Awaitable, Callable, Sequence
from dataclasses import dataclass
from typing import Literal

from loguru import logger

from auth_middleware.authz.catalog import PermissionCatalog
from auth_middleware.authz.errors import ScopeKindMismatchError, UnknownRoleError
from auth_middleware.authz.ports import AssignmentAdmin, AssignmentStore
from auth_middleware.authz.types import Assignment, NewAssignment, ScopeRef


@dataclass(frozen=True, slots=True)
class AssignmentChange:
    """A change about to happen (or that happened) to an assignment."""

    kind: Literal["assign", "change_role", "revoke"]
    principal_id: str
    scope: ScopeRef
    old: Assignment | None
    new_role: str | None


BeforeChange = Callable[[AssignmentChange], Awaitable[None]]
AfterChange = Callable[[AssignmentChange, Assignment], Awaitable[None]]


[docs] class AssignmentService: """Validated writes over an :class:`AssignmentAdmin`, with application hooks. The library ships no domain rule: an application plugs its own into ``before_change`` (raise to veto; nothing is written) and ``after_change`` (cache invalidation, audit, notifications). Example, the "last owner" rule:: async def last_owner(change: AssignmentChange) -> None: leaving = change.kind == "revoke" or ( change.kind == "change_role" and change.new_role != "OWNER" ) if leaving and change.old and change.old.role == "OWNER": owners = [ a for a in await service.members(change.scope) if a.role == "OWNER" and a.status.value == "active" ] if len(owners) <= 1: raise LastOwnerRequiredError() service = AssignmentService(admin, catalog, before_change=[last_owner]) Changes of one scope are serialised **within this process** (the veto hooks and the write run under a per-scope lock), so concurrent requests cannot both pass the same check. Several processes/instances still race (two owners revoking each other on different servers): enforce hard invariants in the store as well (a constraint or transaction of your own adapter). A role is bound to a scope kind through its permissions: every permission of the role must belong to the kind of the scope it is assigned in. Args: admin: The write side of a store. catalog: Used to validate roles. before_change: Veto hooks, run in order before any write. after_change: Hooks run in order after a successful write. """
[docs] def __init__( self, admin: AssignmentAdmin, catalog: PermissionCatalog, *, before_change: Sequence[BeforeChange] = (), after_change: Sequence[AfterChange] = (), ) -> None: self._admin = admin self._catalog = catalog # One change at a time per scope *in this process*: makes check-then-act # veto hooks (last owner...) safe against concurrent requests here. Other # processes still race; enforce hard invariants in the store as well. self._locks: weakref.WeakValueDictionary[tuple[str, str], asyncio.Lock] = ( weakref.WeakValueDictionary() ) self._before = tuple(before_change) self._after = tuple(after_change)
def _lock_for(self, scope: ScopeRef) -> asyncio.Lock: key = (scope.kind, scope.id) lock = self._locks.get(key) if lock is None: lock = self._locks[key] = asyncio.Lock() return lock def _validate_role(self, role: str, scope: ScopeRef) -> None: if role not in self._catalog.roles(): raise UnknownRoleError(f"unknown role: {role}") for permission in self._catalog.permissions_for(role): kind = self._catalog.spec(permission).scope_kind if kind != scope.kind: raise ScopeKindMismatchError( f"role {role} grants {permission} (scope kind {kind}); " f"cannot be assigned in a {scope.kind} scope" ) async def _old(self, principal_id: str, scope: ScopeRef) -> Assignment | None: if isinstance(self._admin, AssignmentStore): return await self._admin.get_assignment(principal_id, scope) for item in await self._admin.list_for_scope(scope): if item.principal_id == principal_id: return item return None async def _run( self, kind: Literal["assign", "change_role", "revoke"], principal_id: str, scope: ScopeRef, new_role: str | None, write: Callable[[], Awaitable[Assignment]], ) -> Assignment: # The state the hooks judge (``old``) is read inside the scope lock, together # with the write, so two changes of one scope cannot interleave here. async with self._lock_for(scope): change = AssignmentChange( kind, principal_id, scope, await self._old(principal_id, scope), new_role, ) for hook in self._before: await hook(change) written = await write() # The write is done: every after_change hook runs (cache invalidation must # not be skipped because an earlier hook failed); the first error is re-raised. first_error: Exception | None = None for after in self._after: try: await after(change, written) except Exception as exc: logger.opt(exception=True).error("after_change hook failed") first_error = first_error or exc if first_error is not None: raise first_error return written
[docs] async def assign(self, principal_id: str, scope: ScopeRef, role: str) -> Assignment: """Give ``principal_id`` ``role`` in ``scope``. Raises: UnknownRoleError: Role not in the catalog. ScopeKindMismatchError: Role belongs to another scope kind. RevisionConflictError: Already actively assigned. """ self._validate_role(role, scope) return await self._run( "assign", principal_id, scope, role, lambda: self._admin.assign(NewAssignment(principal_id, scope, role)), )
[docs] async def change_role( self, principal_id: str, scope: ScopeRef, role: str, *, expected_revision: int ) -> Assignment: """Change the role of an active assignment (optimistic concurrency).""" self._validate_role(role, scope) return await self._run( "change_role", principal_id, scope, role, lambda: self._admin.change_role( principal_id, scope, role, expected_revision=expected_revision ), )
[docs] async def revoke( self, principal_id: str, scope: ScopeRef, *, expected_revision: int ) -> Assignment: """Revoke an active assignment (optimistic concurrency).""" return await self._run( "revoke", principal_id, scope, None, lambda: self._admin.revoke( principal_id, scope, expected_revision=expected_revision ), )
[docs] async def members(self, scope: ScopeRef) -> Sequence[Assignment]: """Return every assignment of ``scope``.""" return await self._admin.list_for_scope(scope)