"""The ``Authz`` runtime: wiring injected at application startup."""
from __future__ import annotations
import inspect
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from contextlib import asynccontextmanager
from dataclasses import dataclass
from typing import Any
from fastapi import HTTPException
from loguru import logger
from starlette.applications import Starlette
from starlette.requests import Request
from auth_middleware.authz.catalog import PermissionCatalog
from auth_middleware.authz.engine import Authorizer
from auth_middleware.authz.errors import (
ConfigurationError,
PermissionDeniedError,
ScopeNotVisibleError,
StoreUnavailableError,
)
from auth_middleware.authz.ports import AssignmentStore, StoreFactory
from auth_middleware.authz.resolvers import (
AssignmentRoleResolver,
GroupRoleResolver,
RoleResolver,
)
from auth_middleware.authz.types import (
GLOBAL_KIND,
DecisionKind,
ScopeRef,
)
from auth_middleware.settings import settings
#: Attributes the guard puts on its dependency so routes can be validated.
PERMISSION_ATTR = "__authz_permission__"
SCOPE_ATTR = "__authz_scope__"
def default_not_visible(request: Request, exc: ScopeNotVisibleError) -> Exception:
"""404, identical for "not a member" and "does not exist"."""
return HTTPException(status_code=404, detail="Not Found")
def default_denied(request: Request, exc: PermissionDeniedError) -> Exception:
"""403 naming the missing permission."""
return HTTPException(
status_code=403,
detail={"error": "forbidden", "required_permission": exc.required},
)
def default_unauthenticated(request: Request) -> Exception:
"""401 with a Bearer challenge."""
return HTTPException(
status_code=401,
detail="Not authenticated",
headers={"WWW-Authenticate": "Bearer"},
)
def default_unavailable(request: Request, exc: StoreUnavailableError) -> Exception:
"""503: the store is throttling or unreachable (an outage, not a decision)."""
return HTTPException(
status_code=503,
detail="Authorization service unavailable",
headers={"Retry-After": "1"},
)
@dataclass(frozen=True, slots=True)
class ErrorPolicy:
"""How authorization outcomes become exceptions (HTTP responses)."""
not_visible: Callable[[Request, ScopeNotVisibleError], Exception] = (
default_not_visible
)
denied: Callable[[Request, PermissionDeniedError], Exception] = default_denied
unauthenticated: Callable[[Request], Exception] = default_unauthenticated
unavailable: Callable[[Request, StoreUnavailableError], Exception] = (
default_unavailable
)
@dataclass(frozen=True, slots=True)
class DecisionEvent:
"""One authorization decision, delivered to ``AuthzHooks.on_decision``.
Carries ids and permission names only: never e-mails, tokens or claim values.
``roles`` is only filled for ``ALLOWED``: ``NOT_VISIBLE`` reveals nothing about the
scope and ``DENIED`` is raised before a context exists.
"""
kind: DecisionKind
principal_id: str
scope: ScopeRef
permission: str
roles: frozenset[str] = frozenset()
sensitive: bool = False
duration_ms: float = 0.0
request_id: str | None = None
def to_dict(self) -> dict[str, Any]:
"""Return a JSON-serialisable view."""
return {
"kind": self.kind.value,
"principal_id": self.principal_id,
"scope_kind": self.scope.kind,
"scope_id": self.scope.id,
"permission": self.permission,
"roles": sorted(self.roles),
"sensitive": self.sensitive,
"duration_ms": round(self.duration_ms, 3),
"request_id": self.request_id,
}
@dataclass(frozen=True, slots=True)
class AuthzHooks:
"""Optional callbacks."""
on_decision: Callable[[DecisionEvent], Awaitable[None] | None] | None = None
[docs]
class Authz:
"""Catalog + store wiring + error policy, held in ``app.state.authz``."""
[docs]
def __init__(
self,
*,
catalog: PermissionCatalog,
store: AssignmentStore | None,
store_factory: StoreFactory | None,
group_roles: Mapping[str, str] | None,
group_scope_kind: str,
error_policy: ErrorPolicy,
hooks: AuthzHooks,
) -> None:
self.catalog = catalog
self.error_policy = error_policy
self.hooks = hooks
self._store = store
self._store_factory = store_factory
self._group_roles = dict(group_roles) if group_roles else None
self._group_scope_kind = group_scope_kind
self._closed = False
[docs]
@classmethod
def build(
cls,
*,
catalog: PermissionCatalog,
store: AssignmentStore | None = None,
store_factory: StoreFactory | None = None,
group_roles: Mapping[str, str] | None = None,
group_scope_kind: str = GLOBAL_KIND,
error_policy: ErrorPolicy | None = None,
hooks: AuthzHooks | None = None,
) -> Authz:
"""Validate the combination of sources and build the runtime.
Exactly one of ``store`` / ``store_factory``; neither is accepted only
for a pure group-based setup (``group_roles`` given).
Raises:
ConfigurationError: Invalid combination or unknown role/scope kind.
"""
if store is not None and store_factory is not None:
raise ConfigurationError("give either store or store_factory, not both")
if store is None and store_factory is None and not group_roles:
raise ConfigurationError(
"no source of roles: give store, store_factory or group_roles"
)
if group_roles:
known = catalog.roles()
unknown = sorted(set(group_roles.values()) - known)
if unknown:
raise ConfigurationError(f"group_roles use unknown roles: {unknown}")
catalog.scope_kind(group_scope_kind)
return cls(
catalog=catalog,
store=store,
store_factory=store_factory,
group_roles=group_roles,
group_scope_kind=group_scope_kind,
error_policy=error_policy or ErrorPolicy(),
hooks=hooks or AuthzHooks(),
)
[docs]
async def authorizer_for(self, request: Request) -> Authorizer:
"""Build an :class:`Authorizer` for ``request`` (calls the factory once)."""
resolvers: list[RoleResolver] = []
if self._store_factory is not None:
store = self._store_factory(request)
if inspect.isawaitable(store):
store = await store
resolvers.append(AssignmentRoleResolver(store))
elif self._store is not None:
resolvers.append(AssignmentRoleResolver(self._store))
if self._group_roles:
resolvers.append(
GroupRoleResolver(self._group_roles, scope_kind=self._group_scope_kind)
)
return Authorizer(self.catalog, resolvers)
[docs]
@classmethod
def of(cls, request: Request) -> Authz:
"""Return the instance installed on ``request.app``.
Raises:
ConfigurationError: Not installed on this app (mounted sub-apps have
their own ``app.state``: install on each, or pass ``authz=``).
"""
authz = getattr(request.app.state, "authz", None)
if not isinstance(authz, Authz):
raise ConfigurationError("authz not installed on this app")
return authz
[docs]
def install(
self, app: Starlette, *, allow_disabled_for_development: bool = False
) -> None:
"""Attach to ``app``: ``app.state.authz``, route validation and shutdown.
Route validation runs at lifespan startup. Apps exercised without the
lifespan (a ``TestClient`` not used as a context manager) should call
:meth:`validate_routes` themselves, e.g. in an architecture test.
Raises:
ConfigurationError: ``AUTH_MIDDLEWARE_DISABLED`` is set and
``allow_disabled_for_development`` is not.
"""
if settings.AUTH_MIDDLEWARE_DISABLED:
if not allow_disabled_for_development:
raise ConfigurationError(
"AUTH_MIDDLEWARE_DISABLED is set: refusing to install "
"authorization (pass allow_disabled_for_development=True)"
)
logger.warning(
"authz installed with AUTH_MIDDLEWARE_DISABLED; guard still enforces"
)
app.state.authz = self
previous = app.router.lifespan_context
@asynccontextmanager
async def lifespan(a: Any) -> AsyncIterator[Any]:
self.validate_routes(app)
async with previous(a) as state:
try:
yield state
finally:
await self.aclose()
app.router.lifespan_context = lifespan
[docs]
def validate_routes(self, app: Starlette) -> None:
"""Check every guarded route against the catalog.
Raises:
UnknownPermissionError: A guard uses a permission not in the catalog.
ScopeKindMismatchError: A guard's scope kind differs from the permission's.
ConfigurationError: A path-based scope uses a parameter the route lacks.
"""
from auth_middleware.authz.errors import ScopeKindMismatchError
for route_path, param_names, call in _iter_guards(app):
permission = getattr(call, PERMISSION_ATTR)
spec = self.catalog.spec(permission)
source = getattr(call, SCOPE_ATTR, None)
kind = getattr(source, "kind", None)
if kind is not None and kind != spec.scope_kind:
raise ScopeKindMismatchError(
f"{route_path}: permission {permission} belongs to scope kind "
f"{spec.scope_kind}, guard uses {kind}"
)
param = getattr(source, "param", None)
if param is not None and param not in param_names:
raise ConfigurationError(
f"{route_path}: scope path parameter {param!r} not in the route"
)
[docs]
async def aclose(self) -> None:
"""Close the injected store if it exposes ``aclose()``. Idempotent."""
if self._closed:
return
self._closed = True
closer = getattr(self._store, "aclose", None)
if closer is not None:
result = closer()
if inspect.isawaitable(result):
await result
def _iter_guards(app: Any, prefix: str = "") -> Any:
"""Yield ``(path, path_param_names, dependency_callable)`` for guarded routes."""
from fastapi.routing import APIRoute
from starlette.routing import Mount
for route in getattr(app, "routes", []):
if isinstance(route, APIRoute):
names = set(route.param_convertors)
stack = [route.dependant]
while stack:
dep = stack.pop()
stack.extend(dep.dependencies)
if dep.call is not None and hasattr(dep.call, PERMISSION_ATTR):
yield prefix + route.path, names, dep.call
elif isinstance(route, Mount) and route.app is not None:
yield from _iter_guards(route.app, prefix + route.path)