Source code for auth_middleware.authz.guards

"""FastAPI guard ``require_permission`` and the non-raising ``has_permission``."""

from __future__ import annotations

import inspect
import time
from collections.abc import Awaitable, Callable
from typing import Any

from loguru import logger
from starlette.requests import Request

from auth_middleware.authz.errors import (
    InvalidScopeError,
    PermissionDeniedError,
    ScopeNotVisibleError,
    StoreUnavailableError,
)
from auth_middleware.authz.runtime import (
    PERMISSION_ATTR,
    SCOPE_ATTR,
    Authz,
    DecisionEvent,
)
from auth_middleware.authz.scopes import GlobalScope, ScopeSource
from auth_middleware.authz.types import (
    MAX_PRINCIPAL_ID_LENGTH,
    AuthzContext,
    DecisionKind,
    Principal,
    ScopeRef,
)

AuthzSource = Authz | Callable[[Request], Authz] | None


def _resolve_authz(request: Request, authz: AuthzSource) -> Authz:
    if authz is None:
        return Authz.of(request)
    if isinstance(authz, Authz):
        return authz
    return authz(request)


async def _principal(request: Request, authz: Authz) -> Principal:
    user = getattr(request.state, "current_user", None)
    # "synthetic" is the placeholder of a disabled middleware; an empty or oversized
    # sub cannot be a real principal (and would only fail later, in the store).
    if (
        user is None
        or user.id == "synthetic"
        or not user.id
        or len(user.id) > MAX_PRINCIPAL_ID_LENGTH
    ):
        raise authz.error_policy.unauthenticated(request)
    groups = tuple(await user.groups or ())
    return Principal(id=user.id, groups=groups, email=user.email)


def _request_id(request: Request) -> str | None:
    value = getattr(request.state, "correlation_id", None) or request.headers.get(
        "x-request-id"
    )
    return str(value) if value else None


async def _emit(
    authz: Authz,
    request: Request,
    principal: Principal,
    permission: str,
    scope: ScopeRef,
    decision: DecisionKind,
    started: float,
    roles: frozenset[str] = frozenset(),
) -> None:
    """Deliver the decision to ``on_decision``.

    A failing hook is logged and swallowed: auditing must never turn an allowed
    request into a 500. An application that needs fail-closed auditing wraps its
    own dependency around this guard.
    """
    hook = authz.hooks.on_decision
    if hook is None:
        return
    try:
        event = DecisionEvent(
            kind=decision,
            principal_id=principal.id,
            scope=scope,
            permission=permission,
            roles=roles,
            sensitive=authz.catalog.spec(permission).sensitive,
            duration_ms=(time.perf_counter() - started) * 1000,
            request_id=_request_id(request),
        )
        result = hook(event)
        if inspect.isawaitable(result):
            await result
    except Exception:
        logger.opt(exception=True).error("authz on_decision hook failed (ignored)")


[docs] def require_permission( permission: str, *, scope: ScopeSource | None = None, authz: AuthzSource = None, ) -> Callable[..., Awaitable[AuthzContext]]: """Build a FastAPI dependency that enforces ``permission`` in ``scope``. The store factory is invoked lazily, when the dependency runs; FastAPI resolves the sub-dependencies of a route in declaration order, so a dependency that binds row-level security for the request must be declared before this guard. The guard never skips when ``AUTH_MIDDLEWARE_DISABLED`` is set: the synthetic user is rejected with 401. Args: permission: Permission name (a ``StrEnum`` member is accepted). scope: Where the scope comes from. Defaults to the global scope. authz: An ``Authz`` or a function of the request returning one; default ``Authz.of(request)`` (``app.state.authz``). Returns: A dependency returning the :class:`AuthzContext`. """ name = str(permission) source: ScopeSource = scope or GlobalScope() async def dependency(request: Request) -> AuthzContext: started = time.perf_counter() rt = _resolve_authz(request, authz) principal = await _principal(request, rt) try: scope_ref = await source.resolve(request) except InvalidScopeError as exc: # e.g. an id longer than 200 chars: same answer as an unknown scope. raise rt.error_policy.not_visible( request, ScopeNotVisibleError(ScopeRef(exc.kind, "invalid")) ) from None try: authorizer = await rt.authorizer_for(request) ctx = await authorizer.authorize(principal, name, scope_ref) except StoreUnavailableError as exc: raise rt.error_policy.unavailable(request, exc) from None except ScopeNotVisibleError as exc: await _emit( rt, request, principal, name, scope_ref, DecisionKind.NOT_VISIBLE, started, ) raise rt.error_policy.not_visible(request, exc) from None except PermissionDeniedError as exc: await _emit( rt, request, principal, name, scope_ref, DecisionKind.DENIED, started ) raise rt.error_policy.denied(request, exc) from None await _emit( rt, request, principal, name, scope_ref, DecisionKind.ALLOWED, started, ctx.roles, ) request.state.authz_context = ctx return ctx setattr(dependency, PERMISSION_ATTR, name) setattr(dependency, SCOPE_ATTR, source) return dependency
[docs] async def has_permission( request: Request, permission: str, scope: ScopeRef, *, authz: AuthzSource = None, ) -> bool: """Non-raising check for use inside handlers. Returns: ``True`` only if the authenticated principal holds ``permission`` in ``scope``; ``False`` for any other *request outcome* (not a member, denied, no user). Raises: AuthzError: For programming/configuration mistakes (unknown permission, scope-kind mismatch, role missing from the catalog...) and for an unavailable store: those are not answers, they are bugs or outages. """ rt = _resolve_authz(request, authz) user = getattr(request.state, "current_user", None) if user is None or user.id == "synthetic": return False principal = await _principal(request, rt) authorizer = await rt.authorizer_for(request) return await authorizer.check(principal, str(permission), scope) is ( DecisionKind.ALLOWED )
__all__: list[Any] = ["has_permission", "require_permission"]