"""The authorizer: generic version of a "membership -> role -> permission" check."""
from __future__ import annotations
from collections.abc import Sequence
from typing import Any
from loguru import logger
from auth_middleware.authz.catalog import PermissionCatalog
from auth_middleware.authz.errors import (
PermissionDeniedError,
ScopeKindMismatchError,
ScopeNotVisibleError,
)
from auth_middleware.authz.resolvers import RoleResolver
from auth_middleware.authz.types import (
AuthzContext,
DecisionKind,
Principal,
ScopeRef,
)
[docs]
class Authorizer:
"""Decides whether a principal holds a permission in a scope.
Resolvers run **sequentially in declaration order**, never concurrently:
stores may share one database session, which is not safe for concurrent use.
"""
[docs]
def __init__(
self, catalog: PermissionCatalog, resolvers: Sequence[RoleResolver]
) -> None:
"""
Args:
catalog: The permission catalog.
resolvers: Role resolvers, consulted in order.
"""
self._catalog = catalog
self._resolvers = tuple(resolvers)
[docs]
async def authorize(
self, principal: Principal, permission: str, scope: ScopeRef
) -> AuthzContext:
"""Authorize or raise.
Algorithm:
1. ``catalog.spec(permission)`` (unknown -> ``UnknownPermissionError``).
2. The permission's scope kind must equal ``scope.kind``
(else ``ScopeKindMismatchError``).
3. Ask every resolver; union the roles and merge attributes (later
resolvers win on key clashes).
4. No result: ``ScopeNotVisibleError`` if the scope kind hides
existence, else ``PermissionDeniedError``.
5. Permission not in the union of the roles' permissions ->
``PermissionDeniedError``.
6. Return the :class:`AuthzContext`.
Raises:
UnknownPermissionError: Programming error.
ScopeKindMismatchError: Programming error.
ScopeNotVisibleError: Principal has no active assignment in scope.
PermissionDeniedError: Principal lacks the permission.
"""
permission = str(permission)
spec = self._catalog.spec(permission)
if spec.scope_kind != scope.kind:
raise ScopeKindMismatchError(
f"permission {permission} belongs to scope kind {spec.scope_kind}, "
f"not {scope.kind}"
)
roles: set[str] = set()
attributes: dict[str, Any] = {}
found = False
for resolver in self._resolvers:
result = await resolver.resolve(principal, scope)
if result is None:
continue
found = True
roles |= result.roles
attributes.update(result.attributes)
if not found:
if self._catalog.scope_kind(scope.kind).hide_existence:
raise ScopeNotVisibleError(scope)
raise PermissionDeniedError(permission, scope)
known = self._catalog.roles()
if not roles <= known:
# A stored role that left the catalog grants nothing (deny by default)
# instead of turning every request of that principal into a 500.
logger.warning(
"assignment with a role missing from the catalog: {}",
sorted(roles - known),
)
roles &= known
granted: frozenset[str] = frozenset().union(
*(self._catalog.permissions_for(r) for r in roles)
)
if permission not in granted:
raise PermissionDeniedError(permission, scope)
return AuthzContext(principal, scope, frozenset(roles), granted, attributes)
[docs]
async def check(
self, principal: Principal, permission: str, scope: ScopeRef
) -> DecisionKind:
"""Return the decision kind without raising for the three outcomes."""
try:
await self.authorize(principal, permission, scope)
except ScopeNotVisibleError:
return DecisionKind.NOT_VISIBLE
except PermissionDeniedError:
return DecisionKind.DENIED
return DecisionKind.ALLOWED