xtr-security-core 3.0.0__py3-none-any.whl

xtr_security_core/__init__.py

@@ -0,0 +1,146 @@
+"""The security core for xtr applications.
+
+Users, tokens, roles, voters and the authorization decision — everything that
+needs no HTTP edge and no JSON Web Tokens. This module gathers the public
+surface so an application imports it from one place.
+"""
+
+from __future__ import annotations
+
+from .authentication import (
+    AuthenticationTrustResolver,
+    AuthenticationTrustResolverInterface,
+)
+from .authentication.token import (
+    AbstractToken,
+    NullToken,
+    TokenInterface,
+    UsernamePasswordToken,
+)
+from .authentication.token.storage import TokenStorage, TokenStorageInterface
+from .authorization import (
+    Access,
+    AccessDecision,
+    AccessDecisionManager,
+    AccessDecisionManagerInterface,
+    AccessDecisionStrategyInterface,
+    AffirmativeStrategy,
+    AuthenticatedVoter,
+    AuthorizationChecker,
+    AuthorizationCheckerInterface,
+    CacheableVoterInterface,
+    ClosureVoter,
+    ConsensusStrategy,
+    GuestAuthorizationCheckerInterface,
+    IsGrantedContext,
+    PriorityStrategy,
+    RoleHierarchyVoter,
+    RoleVoter,
+    TraceableVoter,
+    UnanimousStrategy,
+    Vote,
+    Voter,
+    VoterInterface,
+)
+from .event import AuthenticationEvent, AuthenticationSuccessEvent, VoteEvent
+from .exception import (
+    AccessDeniedError,
+    AccountExpiredError,
+    AccountStatusError,
+    AuthenticationCredentialsNotFoundError,
+    AuthenticationError,
+    AuthenticationServiceError,
+    BadCredentialsError,
+    CredentialsExpiredError,
+    CustomUserMessageAccountStatusError,
+    CustomUserMessageAuthenticationError,
+    DisabledError,
+    InsufficientAuthenticationError,
+    InvalidArgumentError,
+    LockedError,
+    SecurityError,
+    UnsupportedUserError,
+    UserNotFoundError,
+)
+from .role import RoleHierarchy, RoleHierarchyInterface
+from .user import (
+    AttributesBasedUserProviderInterface,
+    ChainUserChecker,
+    ChainUserProvider,
+    EquatableInterface,
+    InMemoryUser,
+    InMemoryUserChecker,
+    InMemoryUserProvider,
+    OidcUser,
+    PasswordUpgraderInterface,
+    UserCheckerInterface,
+    UserInterface,
+    UserProviderInterface,
+)
+
+__all__ = [
+    "AbstractToken",
+    "Access",
+    "AccessDecision",
+    "AccessDecisionManager",
+    "AccessDecisionManagerInterface",
+    "AccessDecisionStrategyInterface",
+    "AccessDeniedError",
+    "AccountExpiredError",
+    "AccountStatusError",
+    "AffirmativeStrategy",
+    "AttributesBasedUserProviderInterface",
+    "AuthenticatedVoter",
+    "AuthenticationCredentialsNotFoundError",
+    "AuthenticationError",
+    "AuthenticationEvent",
+    "AuthenticationServiceError",
+    "AuthenticationSuccessEvent",
+    "AuthenticationTrustResolver",
+    "AuthenticationTrustResolverInterface",
+    "AuthorizationChecker",
+    "AuthorizationCheckerInterface",
+    "BadCredentialsError",
+    "CacheableVoterInterface",
+    "ChainUserChecker",
+    "ChainUserProvider",
+    "ClosureVoter",
+    "ConsensusStrategy",
+    "CredentialsExpiredError",
+    "CustomUserMessageAccountStatusError",
+    "CustomUserMessageAuthenticationError",
+    "DisabledError",
+    "EquatableInterface",
+    "GuestAuthorizationCheckerInterface",
+    "InMemoryUser",
+    "InMemoryUserChecker",
+    "InMemoryUserProvider",
+    "InsufficientAuthenticationError",
+    "InvalidArgumentError",
+    "IsGrantedContext",
+    "LockedError",
+    "NullToken",
+    "OidcUser",
+    "PasswordUpgraderInterface",
+    "PriorityStrategy",
+    "RoleHierarchy",
+    "RoleHierarchyInterface",
+    "RoleHierarchyVoter",
+    "RoleVoter",
+    "SecurityError",
+    "TokenInterface",
+    "TokenStorage",
+    "TokenStorageInterface",
+    "TraceableVoter",
+    "UnanimousStrategy",
+    "UnsupportedUserError",
+    "UserCheckerInterface",
+    "UserInterface",
+    "UserNotFoundError",
+    "UserProviderInterface",
+    "UsernamePasswordToken",
+    "Vote",
+    "VoteEvent",
+    "Voter",
+    "VoterInterface",
+]

xtr_security_core/authentication/__init__.py

@@ -0,0 +1,11 @@
+"""Authentication: tokens, where they are kept, and how strongly they are trusted."""
+
+from __future__ import annotations
+
+from .authentication_trust_resolver import AuthenticationTrustResolver
+from .authentication_trust_resolver_interface import AuthenticationTrustResolverInterface
+
+__all__ = [
+    "AuthenticationTrustResolver",
+    "AuthenticationTrustResolverInterface",
+]

xtr_security_core/authentication/authentication_trust_resolver.py

@@ -0,0 +1,39 @@
+"""Tells how strongly a token was authenticated."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .authentication_trust_resolver_interface import AuthenticationTrustResolverInterface
+from .token.null_token import NullToken
+
+if TYPE_CHECKING:
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+__all__ = ["AuthenticationTrustResolver"]
+
+
+@final
+class AuthenticationTrustResolver(AuthenticationTrustResolverInterface):
+    """Reads authentication strength from a token.
+
+    A token carries an authenticated user when it is neither absent nor the
+    :class:`~xtr_security_core.authentication.token.null_token.NullToken` that
+    stands for nobody. Without the remembered-me machinery this library does
+    not port, full authentication and authentication are the same question:
+    a real token is both, an anonymous one is neither.
+    """
+
+    @override
+    def is_authenticated(self, token: TokenInterface | None) -> bool:
+        """Tell whether ``token`` carries an authenticated user at all."""
+        return (
+            token is not None and not isinstance(token, NullToken) and token.get_user() is not None
+        )
+
+    @override
+    def is_full_fledged(self, token: TokenInterface | None) -> bool:
+        """Tell whether ``token`` was fully authenticated this unit of work."""
+        return self.is_authenticated(token)

xtr_security_core/authentication/authentication_trust_resolver_interface.py

@@ -0,0 +1,30 @@
+"""What tells how strongly a token was authenticated."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+__all__ = ["AuthenticationTrustResolverInterface"]
+
+
+@runtime_checkable
+class AuthenticationTrustResolverInterface(Protocol):
+    """Reads the strength of an authentication from a token.
+
+    A voter granting ``IS_AUTHENTICATED`` asks only whether anyone is behind
+    the token; one granting ``IS_AUTHENTICATED_FULLY`` asks whether they
+    authenticated this unit of work rather than being carried over. This
+    contract answers both without any voter having to know how a token was
+    made.
+    """
+
+    def is_authenticated(self, token: TokenInterface | None) -> bool:
+        """Tell whether ``token`` carries an authenticated user at all."""
+        ...
+
+    def is_full_fledged(self, token: TokenInterface | None) -> bool:
+        """Tell whether ``token`` was fully authenticated this unit of work."""
+        ...

xtr_security_core/authentication/token/__init__.py

@@ -0,0 +1,15 @@
+"""Tokens: the outcome of authentication, and where it is kept."""
+
+from __future__ import annotations
+
+from .abstract_token import AbstractToken
+from .null_token import NullToken
+from .token_interface import TokenInterface
+from .username_password_token import UsernamePasswordToken
+
+__all__ = [
+    "AbstractToken",
+    "NullToken",
+    "TokenInterface",
+    "UsernamePasswordToken",
+]

xtr_security_core/authentication/token/abstract_token.py

@@ -0,0 +1,85 @@
+"""The shared base of every token: a user, fixed roles, and attributes."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from xtr_security_core.exception import InvalidArgumentError
+
+from .token_interface import TokenInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from xtr_security_core.user.user_interface import UserInterface
+
+__all__ = ["AbstractToken"]
+
+
+class AbstractToken(TokenInterface):
+    """A user, the roles fixed at creation, and a bag of attributes.
+
+    Implements :class:`~xtr_security_core.authentication.token.token_interface.TokenInterface`.
+    The roles are copied at construction and never re-read from the user, so a
+    decision made against this token reflects what authentication settled on,
+    not what the user object may report afterwards. Concrete tokens derive from
+    this and add whatever their own kind needs.
+    """
+
+    _user: UserInterface | None
+    _role_names: tuple[str, ...]
+    _attributes: dict[str, object]
+
+    def __init__(self, user: UserInterface | None = None, roles: Sequence[str] = ()) -> None:
+        """Record the user and copy the roles fixed on this token."""
+        self._user = user
+        self._role_names = tuple(roles)
+        self._attributes = {}
+
+    @override
+    def get_user(self) -> UserInterface | None:
+        """Return the authenticated user, or ``None`` for nobody."""
+        return self._user
+
+    @override
+    def get_user_identifier(self) -> str:
+        """Return the identifier of the user, or the empty string for nobody."""
+        return self._user.get_user_identifier() if self._user is not None else ""
+
+    @override
+    def get_role_names(self) -> Sequence[str]:
+        """Return the roles fixed on this token at creation."""
+        return self._role_names
+
+    @override
+    def get_attributes(self) -> Mapping[str, object]:
+        """Return a read-only snapshot of the attributes attached to this token.
+
+        The mapping is a copy taken now, so a later
+        :meth:`set_attribute` does not change a mapping already returned.
+        """
+        return MappingProxyType(dict(self._attributes))
+
+    @override
+    def get_attribute(self, name: str) -> object:
+        """Return the attribute ``name``.
+
+        Raises:
+            InvalidArgumentError: When no attribute is attached under ``name``.
+        """
+        if name not in self._attributes:
+            raise InvalidArgumentError(f'This token has no "{name}" attribute.')
+        return self._attributes[name]
+
+    @override
+    def has_attribute(self, name: str) -> bool:
+        """Tell whether an attribute is attached under ``name``."""
+        return name in self._attributes
+
+    @override
+    def set_attribute(self, name: str, value: object) -> None:
+        """Attach ``value`` under ``name``, replacing any attribute there."""
+        self._attributes[name] = value

xtr_security_core/authentication/token/null_token.py

@@ -0,0 +1,23 @@
+"""The token that stands for nobody."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .abstract_token import AbstractToken
+
+__all__ = ["NullToken"]
+
+
+@final
+class NullToken(AbstractToken):
+    """A token carrying no user and no roles: the anonymous caller.
+
+    An access decision is always made against a token; when authentication
+    settled on nobody, it is made against this one. It reports no user, no
+    identifier and no roles, so a voter reading roles simply finds none.
+    """
+
+    def __init__(self) -> None:
+        """Build the token that stands for nobody."""
+        super().__init__(user=None, roles=())

xtr_security_core/authentication/token/storage/__init__.py

@@ -0,0 +1,8 @@
+"""Where the authenticated token lives for the current unit of work."""
+
+from __future__ import annotations
+
+from .token_storage import TokenStorage
+from .token_storage_interface import TokenStorageInterface
+
+__all__ = ["TokenStorage", "TokenStorageInterface"]

xtr_security_core/authentication/token/storage/token_storage.py

@@ -0,0 +1,50 @@
+"""The token storage: one token per unit of work, cleared between them."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_service_contracts import ResetInterface
+
+from .token_storage_interface import TokenStorageInterface
+
+if TYPE_CHECKING:
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+__all__ = ["TokenStorage"]
+
+
+@final
+class TokenStorage(TokenStorageInterface, ResetInterface):
+    """Holds the current token, and returns to empty between units of work.
+
+    A scoped service: one instance per request, message or command, so two
+    units of work never see each other's token. It satisfies
+    :class:`~xtr_service_contracts.reset_interface.ResetInterface` — a
+    container clears it when a unit of work ends, so the next starts with no
+    token — and is weakly referenceable because it declares no ``__slots__``,
+    so instances carry the ``__weakref__`` a kernel that resets its scoped
+    services requires.
+    """
+
+    _token: TokenInterface | None
+
+    def __init__(self) -> None:
+        """Start with no token."""
+        self._token = None
+
+    @override
+    def get_token(self) -> TokenInterface | None:
+        """Return the current token, or ``None`` when none was set."""
+        return self._token
+
+    @override
+    def set_token(self, token: TokenInterface | None) -> None:
+        """Store ``token`` as the current one, or clear it with ``None``."""
+        self._token = token
+
+    @override
+    def reset(self) -> None:
+        """Forget the current token, so the next unit of work starts clean."""
+        self._token = None

xtr_security_core/authentication/token/storage/token_storage_interface.py

@@ -0,0 +1,29 @@
+"""What holds the token for the current unit of work."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_security_core.authentication.token.token_interface import TokenInterface
+
+__all__ = ["TokenStorageInterface"]
+
+
+@runtime_checkable
+class TokenStorageInterface(Protocol):
+    """The one place the authenticated token lives for a unit of work.
+
+    Authentication writes a token here; everything downstream — an access
+    decision, a facade reading the current user, a listener turning an error
+    into a response — reads it from here. Reading and writing are synchronous:
+    the token is already in hand by the time it is stored.
+    """
+
+    def get_token(self) -> TokenInterface | None:
+        """Return the current token, or ``None`` when none was set."""
+        ...
+
+    def set_token(self, token: TokenInterface | None) -> None:
+        """Store ``token`` as the current one, or clear it with ``None``."""
+        ...

xtr_security_core/authentication/token/token_interface.py

@@ -0,0 +1,56 @@
+"""What a token — the outcome of authentication — answers to."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from xtr_security_core.user.user_interface import UserInterface
+
+__all__ = ["TokenInterface"]
+
+
+@runtime_checkable
+class TokenInterface(Protocol):
+    """The result of authentication: who is calling, and what was decided about them.
+
+    A token names a user and the roles that authentication settled on. Those
+    roles are fixed when the token is created, decoupled from whatever the
+    live user object may report later, so a decision reads a stable snapshot.
+    Attributes carry extra data an authenticator or a listener attached — the
+    scopes of a bearer token, the client it was issued to.
+    """
+
+    def get_user(self) -> UserInterface | None:
+        """Return the authenticated user, or ``None`` for nobody."""
+        ...
+
+    def get_user_identifier(self) -> str:
+        """Return the identifier of the user, or the empty string for nobody."""
+        ...
+
+    def get_role_names(self) -> Sequence[str]:
+        """Return the roles fixed on this token at creation."""
+        ...
+
+    def get_attributes(self) -> Mapping[str, object]:
+        """Return every attribute attached to this token, read-only."""
+        ...
+
+    def get_attribute(self, name: str) -> object:
+        """Return the attribute ``name``.
+
+        Raises:
+            InvalidArgumentError: When no attribute is attached under ``name``.
+        """
+        ...
+
+    def has_attribute(self, name: str) -> bool:
+        """Tell whether an attribute is attached under ``name``."""
+        ...
+
+    def set_attribute(self, name: str, value: object) -> None:
+        """Attach ``value`` under ``name``, replacing any attribute there."""
+        ...

xtr_security_core/authentication/token/username_password_token.py

@@ -0,0 +1,42 @@
+"""A token naming a user, the firewall that authenticated them, and their roles."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from .abstract_token import AbstractToken
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from xtr_security_core.user.user_interface import UserInterface
+
+__all__ = ["UsernamePasswordToken"]
+
+
+@final
+class UsernamePasswordToken(AbstractToken):
+    """A user proven by a password, the firewall that did it, and the roles.
+
+    The token an authentication settles on when a user answered with a
+    password. It carries the user, the firewall (or unit of work) that
+    authenticated them, and the roles fixed at that moment — decoupled from the
+    live user's roles, as every token in this library is.
+
+    Attributes:
+        firewall_name: The firewall (or unit of work) that authenticated.
+    """
+
+    def __init__(
+        self,
+        user: UserInterface,
+        firewall_name: str,
+        roles: Sequence[str] = (),
+    ) -> None:
+        """Record the user, the firewall that authenticated them, and their roles."""
+        super().__init__(user=user, roles=roles)
+        self._firewall_name = firewall_name
+
+    def get_firewall_name(self) -> str:
+        """Return the firewall (or unit of work) that authenticated the user."""
+        return self._firewall_name

xtr_security_core/authentication_events.py

@@ -0,0 +1,30 @@
+"""The names the core security events are dispatched and listened to under.
+
+Each event is keyed by its qualified class name (the repository's convention,
+:func:`~xtr_event_dispatcher_contracts.event_name_of`). A subscriber listens to
+one of these constants rather than importing the event class only to name it.
+
+Only the core events live here — the success of an authentication, and a
+voter's vote. The events raised at the HTTP edge are named by
+:mod:`xtr_security_http.security_events`.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from xtr_event_dispatcher_contracts import event_name_of
+
+from .event.authentication_success_event import AuthenticationSuccessEvent
+from .event.vote_event import VoteEvent
+
+__all__ = [
+    "AUTHENTICATION_SUCCESS",
+    "VOTE",
+]
+
+#: Dispatched once a token has been created for an authenticated user.
+AUTHENTICATION_SUCCESS: Final[str] = event_name_of(AuthenticationSuccessEvent)
+
+#: Dispatched by a traceable voter each time the voter it wraps answers.
+VOTE: Final[str] = event_name_of(VoteEvent)

xtr_security_core/authorization/__init__.py

@@ -0,0 +1,55 @@
+"""Authorization: voters, strategies, the decision manager and the checkers over them."""
+
+from __future__ import annotations
+
+from .access_decision import AccessDecision
+from .access_decision_manager import AccessDecisionManager
+from .access_decision_manager_interface import AccessDecisionManagerInterface
+from .authorization_checker import AuthorizationChecker
+from .authorization_checker_interface import AuthorizationCheckerInterface
+from .guest_authorization_checker_interface import GuestAuthorizationCheckerInterface
+from .is_granted_context import IsGrantedContext
+from .strategy import (
+    AccessDecisionStrategyInterface,
+    AffirmativeStrategy,
+    ConsensusStrategy,
+    PriorityStrategy,
+    UnanimousStrategy,
+)
+from .voter import (
+    Access,
+    AuthenticatedVoter,
+    CacheableVoterInterface,
+    ClosureVoter,
+    RoleHierarchyVoter,
+    RoleVoter,
+    TraceableVoter,
+    Vote,
+    Voter,
+    VoterInterface,
+)
+
+__all__ = [
+    "Access",
+    "AccessDecision",
+    "AccessDecisionManager",
+    "AccessDecisionManagerInterface",
+    "AccessDecisionStrategyInterface",
+    "AffirmativeStrategy",
+    "AuthenticatedVoter",
+    "AuthorizationChecker",
+    "AuthorizationCheckerInterface",
+    "CacheableVoterInterface",
+    "ClosureVoter",
+    "ConsensusStrategy",
+    "GuestAuthorizationCheckerInterface",
+    "IsGrantedContext",
+    "PriorityStrategy",
+    "RoleHierarchyVoter",
+    "RoleVoter",
+    "TraceableVoter",
+    "UnanimousStrategy",
+    "Vote",
+    "Voter",
+    "VoterInterface",
+]

xtr_security_core/authorization/access_decision.py

@@ -0,0 +1,46 @@
+"""The record of one access decision: its votes and its outcome."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .voter.access import Access
+
+if TYPE_CHECKING:
+    from .voter.vote import Vote
+
+__all__ = ["AccessDecision"]
+
+
+@dataclass(slots=True)
+class AccessDecision:
+    """What was decided, by which strategy, and every vote behind it.
+
+    A decision is not only a yes or no: it is the votes that produced it. The
+    manager fills one of these as the voters answer, so a refusal can be
+    explained — the :attr:`message` reads the denying voters' reasons. A nested
+    decision made while one is in progress shares the same record, so its votes
+    are gathered here too.
+
+    Attributes:
+        is_granted: The outcome, once the manager has decided.
+        votes: Every vote cast, in the order they were cast.
+        strategy: The name of the strategy that decided, once set.
+    """
+
+    is_granted: bool = False
+    votes: list[Vote] = field(default_factory=list)
+    strategy: str | None = None
+
+    @property
+    def message(self) -> str:
+        """A short account of the decision: granted, or why it was denied."""
+        if self.is_granted:
+            return "Access granted."
+        reasons = [
+            reason for vote in self.votes if vote.result is Access.DENIED for reason in vote.reasons
+        ]
+        if reasons:
+            return "Access denied. " + " ".join(reasons)
+        return "Access denied."