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

xtr_security_http/authenticator/oidc/oidc_jwks.py

@@ -0,0 +1,87 @@
+"""The keys a third-party OIDC token is verified against, and a fixed source of them."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Protocol, cast, final, runtime_checkable
+
+from joserfc.errors import JoseError
+from joserfc.jwk import KeySet
+from typing_extensions import override
+from xtr_security_core.exception import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from joserfc._keys import KeySetSerialization
+
+__all__ = ["OidcKeySetProviderInterface", "StaticOidcKeySetProvider"]
+
+
+@runtime_checkable
+class OidcKeySetProviderInterface(Protocol):
+    """Supplies the public keys a third-party OIDC token is verified against.
+
+    A token names its key by ``kid``; the whole set is handed to the verifier,
+    which picks the one that matches. A remote provider caches the set, and
+    ``force_refresh`` asks it to fetch again — the handler does so once when a
+    token names a ``kid`` the cached set does not hold, a key rotation the
+    provider had not yet seen.
+    """
+
+    async def get_key_set(self, *, force_refresh: bool = False) -> KeySet:
+        """Return the key set a token is verified against.
+
+        Args:
+            force_refresh: Fetch a fresh set rather than answer from the cache,
+                subject to a provider's own cooldown.
+
+        Raises:
+            OidcKeySetError: When the key set cannot be fetched, discovered or
+                read.
+        """
+        ...
+
+
+@final
+class StaticOidcKeySetProvider(OidcKeySetProviderInterface):
+    """Holds a fixed key set read from a JWKS document.
+
+    For an issuer whose keys are known ahead of time and pinned in the
+    configuration, rather than fetched. The document is read once, as the
+    provider is made, so a malformed one fails here rather than at the first
+    token; :meth:`get_key_set` always answers the same set, ``force_refresh``
+    or not, since there is nowhere to refresh from.
+    """
+
+    __slots__ = ("_key_set",)
+
+    def __init__(self, jwks_json: str | Mapping[str, object]) -> None:
+        """Build the key set from ``jwks_json``, a JWKS string or mapping.
+
+        Raises:
+            InvalidArgumentError: When the document is not a readable JWK set.
+        """
+        self._key_set = _read_key_set(jwks_json)
+
+    @override
+    async def get_key_set(self, *, force_refresh: bool = False) -> KeySet:
+        """Return the fixed key set, whether or not a refresh is asked for."""
+        del force_refresh
+        return self._key_set
+
+
+def _read_key_set(jwks_json: str | Mapping[str, object]) -> KeySet:
+    """Turn a JWKS string or mapping into a joserfc key set.
+
+    Raises:
+        InvalidArgumentError: When the document is not a readable JWK set.
+    """
+    try:
+        document: object = json.loads(jwks_json) if isinstance(jwks_json, str) else dict(jwks_json)
+        if not isinstance(document, dict):
+            raise InvalidArgumentError("A JWK set document must be a JSON object.")
+        serialization = cast("KeySetSerialization", cast("object", document))
+        return KeySet.import_key_set(serialization)
+    except (JoseError, ValueError) as error:
+        raise InvalidArgumentError(f"The JWK set document could not be read: {error}") from error

xtr_security_http/authenticator/passport/__init__.py

@@ -0,0 +1,8 @@
+"""Passports and the badges they carry, produced by an authenticator."""
+
+from __future__ import annotations
+
+from .passport import Passport
+from .self_validating_passport import SelfValidatingPassport
+
+__all__ = ["Passport", "SelfValidatingPassport"]

xtr_security_http/authenticator/passport/badge/__init__.py

@@ -0,0 +1,16 @@
+"""The badges a passport carries: the user, and notes about the authentication."""
+
+from __future__ import annotations
+
+from .badge_interface import BadgeInterface
+from .password_upgrade_badge import PasswordUpgradeBadge
+from .pre_authenticated_user_badge import PreAuthenticatedUserBadge
+from .user_badge import MAX_USERNAME_LENGTH, UserBadge
+
+__all__ = [
+    "MAX_USERNAME_LENGTH",
+    "BadgeInterface",
+    "PasswordUpgradeBadge",
+    "PreAuthenticatedUserBadge",
+    "UserBadge",
+]

xtr_security_http/authenticator/passport/badge/badge_interface.py

@@ -0,0 +1,24 @@
+"""What a badge — a single fact a passport carries — answers to."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+__all__ = ["BadgeInterface"]
+
+
+@runtime_checkable
+class BadgeInterface(Protocol):
+    """One fact about an authentication, resolved before a token is made.
+
+    A passport is a bag of badges: the user's identifier, the password to
+    verify, a note that a password should be upgraded. Each badge starts
+    unresolved and is marked resolved by whoever handles it — a listener on the
+    passport-check event, or the badge itself when it needs nothing. Every
+    badge must report itself resolved by the time the check is done, or
+    authentication fails.
+    """
+
+    def is_resolved(self) -> bool:
+        """Tell whether this badge has been handled and needs nothing more."""
+        ...

xtr_security_http/authenticator/passport/badge/password_upgrade_badge.py

@@ -0,0 +1,59 @@
+"""A badge asking that a verified password be re-stored under a fresh hash."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .badge_interface import BadgeInterface
+
+if TYPE_CHECKING:
+    from xtr_security_core.user.password_upgrader_interface import PasswordUpgraderInterface
+
+__all__ = ["PasswordUpgradeBadge"]
+
+
+@final
+class PasswordUpgradeBadge(BadgeInterface):
+    """Carries the plaintext and the place to write its upgraded hash to.
+
+    Added to a passport when a password verified against an outdated hash, so
+    the migrating listener can re-hash the plaintext with the current
+    algorithm and hand it to an upgrader to store. It resolves on its own — an
+    upgrade is opportunistic, never a condition of authentication.
+
+    Attributes:
+        plaintext_password: The verified plaintext, to be re-hashed.
+        password_upgrader: Where the fresh hash is written, when one is known.
+    """
+
+    __slots__ = ("_password_upgrader", "_plaintext_password")
+
+    def __init__(
+        self,
+        plaintext_password: str,
+        password_upgrader: PasswordUpgraderInterface | None = None,
+    ) -> None:
+        """Record the plaintext and, when known, where to store its new hash."""
+        self._plaintext_password = plaintext_password
+        self._password_upgrader = password_upgrader
+
+    def get_and_erase_plaintext_password(self) -> str:
+        """Return the plaintext once, then drop it so it is not held longer."""
+        plaintext = self._plaintext_password
+        self._plaintext_password = ""
+        return plaintext
+
+    def get_password_upgrader(self) -> PasswordUpgraderInterface | None:
+        """Return the upgrader the new hash is written to, if one was set."""
+        return self._password_upgrader
+
+    def set_password_upgrader(self, password_upgrader: PasswordUpgraderInterface) -> None:
+        """Set the upgrader the migrating listener writes the new hash to."""
+        self._password_upgrader = password_upgrader
+
+    @override
+    def is_resolved(self) -> bool:
+        """Report resolved always: an upgrade never gates authentication."""
+        return True

xtr_security_http/authenticator/passport/badge/pre_authenticated_user_badge.py

@@ -0,0 +1,27 @@
+"""A badge marking a user pre-authenticated, needing no credential check."""
+
+from __future__ import annotations
+
+from typing import final
+
+from typing_extensions import override
+
+from .badge_interface import BadgeInterface
+
+__all__ = ["PreAuthenticatedUserBadge"]
+
+
+@final
+class PreAuthenticatedUserBadge(BadgeInterface):
+    """States that the user was already authenticated elsewhere.
+
+    A bearer token was verified by its handler before ever reaching a
+    passport; there are no credentials on the passport to check. This badge
+    stands for that fact — it is resolved from the moment it exists, so the
+    credentials listener knows there is nothing to verify.
+    """
+
+    @override
+    def is_resolved(self) -> bool:
+        """Report resolved always: a pre-authenticated user needs no check."""
+        return True

xtr_security_http/authenticator/passport/badge/user_badge.py

@@ -0,0 +1,163 @@
+"""The badge naming the user an authentication is for."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Final, final
+
+from typing_extensions import override
+from xtr_security_core.exception import AuthenticationServiceError
+from xtr_security_core.user.user_interface import UserInterface
+
+from .badge_interface import BadgeInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Mapping
+
+__all__ = ["MAX_USERNAME_LENGTH", "UserBadge"]
+
+MAX_USERNAME_LENGTH: Final = 4096
+"""The longest identifier a badge accepts, guarding against a runaway input."""
+
+
+@final
+class UserBadge(BadgeInterface):
+    """Names the user an authentication is for, and loads them on demand.
+
+    The identifier is what authentication proved — a username, a token's
+    ``sub``. A loader turns it into a user: passed in by the authenticator, or
+    set by a user-provider listener during the passport check. Attributes
+    carried alongside — a token's claims — are handed to the loader, so an
+    attributes-based provider can build the user from more than the identifier.
+
+    The badge resolves as soon as its loader is set; :meth:`get_user` runs the
+    loader once and caches the user. An identifier longer than
+    :data:`MAX_USERNAME_LENGTH` is refused at construction.
+    """
+
+    __slots__ = ("_attributes", "_identifier", "_user", "_user_loader")
+
+    def __init__(
+        self,
+        identifier: str,
+        user_loader: Callable[..., UserInterface | Awaitable[UserInterface]] | None = None,
+        attributes: Mapping[str, object] | None = None,
+        identifier_normalizer: Callable[[str], str] | None = None,
+    ) -> None:
+        """Record the identifier, an optional loader and the attributes.
+
+        Args:
+            identifier: What authentication proved the caller to be.
+            user_loader: Turns the identifier (and attributes) into a user;
+                a provider listener sets one during the check when omitted.
+            attributes: Extra data — a token's claims — handed to the loader.
+            identifier_normalizer: Applied to the identifier before it is
+                stored, for a provider that folds case or trims it.
+
+        Raises:
+            BadCredentialsError: When the identifier is empty.
+            InvalidArgumentError: When the identifier is longer than
+                :data:`MAX_USERNAME_LENGTH`.
+        """
+        from xtr_security_core.exception import (  # noqa: PLC0415 -- local: only the constructor validates
+            BadCredentialsError,
+            InvalidArgumentError,
+        )
+
+        if identifier_normalizer is not None:
+            identifier = identifier_normalizer(identifier)
+        if not identifier:
+            raise BadCredentialsError("The user identifier must not be empty.")
+        if len(identifier) > MAX_USERNAME_LENGTH:
+            raise InvalidArgumentError(
+                f"The user identifier is too long, {MAX_USERNAME_LENGTH} characters at most.",
+            )
+        self._identifier = identifier
+        self._user_loader = user_loader
+        self._attributes: dict[str, object] = dict(attributes) if attributes is not None else {}
+        self._user: UserInterface | None = None
+
+    def get_user_identifier(self) -> str:
+        """Return the identifier this badge names."""
+        return self._identifier
+
+    def get_loaded_user(self) -> UserInterface:
+        """Return the user :meth:`get_user` already loaded, without doing I/O.
+
+        Raises:
+            AuthenticationServiceError: When the user has not been loaded yet,
+                which a token being created before the passport check would be.
+        """
+        if self._user is None:
+            raise AuthenticationServiceError(
+                "The user badge's user has not been loaded; the passport check must run first.",
+            )
+        return self._user
+
+    def get_attributes(self) -> Mapping[str, object]:
+        """Return the attributes handed to the loader."""
+        return dict(self._attributes)
+
+    def get_user_loader(self) -> Callable[..., UserInterface | Awaitable[UserInterface]] | None:
+        """Return the loader set for this badge, or ``None``."""
+        return self._user_loader
+
+    def set_user_loader(
+        self,
+        user_loader: Callable[..., UserInterface | Awaitable[UserInterface]],
+    ) -> None:
+        """Set the loader a provider listener resolved for this badge."""
+        self._user_loader = user_loader
+
+    async def get_user(self) -> UserInterface:
+        """Load the user this badge names, once, and return it.
+
+        The loader is called with the identifier, and with the attributes when
+        it accepts a second argument. Its result is awaited when it is an
+        awaitable.
+
+        Raises:
+            AuthenticationServiceError: When no loader was set, or the loader
+                returned something that is not a user.
+            UserNotFoundError: When the loader reports no such user.
+        """
+        if self._user is not None:
+            return self._user
+        if self._user_loader is None:
+            raise AuthenticationServiceError(
+                "No user loader is set on the user badge; a user provider must set one.",
+            )
+        result = self._call_loader(self._user_loader)
+        loaded: object = await result if inspect.isawaitable(result) else result
+        if not isinstance(loaded, UserInterface):
+            raise AuthenticationServiceError("The user loader did not return a user.")
+        self._user = loaded
+        return loaded
+
+    def _call_loader(
+        self,
+        loader: Callable[..., UserInterface | Awaitable[UserInterface]],
+    ) -> object:
+        """Call ``loader`` with the identifier, and the attributes when it takes them."""
+        try:
+            signature = inspect.signature(loader)
+        except (TypeError, ValueError):
+            return loader(self._identifier)
+        positional = [
+            parameter
+            for parameter in signature.parameters.values()
+            if parameter.kind
+            in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+        takes_varargs = any(
+            parameter.kind is inspect.Parameter.VAR_POSITIONAL
+            for parameter in signature.parameters.values()
+        )
+        if len(positional) >= 2 or takes_varargs:  # noqa: PLR2004 -- identifier plus attributes
+            return loader(self._identifier, dict(self._attributes))
+        return loader(self._identifier)
+
+    @override
+    def is_resolved(self) -> bool:
+        """Tell whether a loader is set, so the user can be loaded."""
+        return self._user_loader is not None

xtr_security_http/authenticator/passport/credentials/__init__.py

@@ -0,0 +1,9 @@
+"""The credentials a passport carries for a listener to verify."""
+
+from __future__ import annotations
+
+from .credentials_interface import CredentialsInterface
+from .custom_credentials import CustomCredentials
+from .password_credentials import PasswordCredentials
+
+__all__ = ["CredentialsInterface", "CustomCredentials", "PasswordCredentials"]

xtr_security_http/authenticator/passport/credentials/credentials_interface.py

@@ -0,0 +1,21 @@
+"""What a set of credentials on a passport answers to."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from xtr_security_http.authenticator.passport.badge.badge_interface import BadgeInterface
+
+__all__ = ["CredentialsInterface"]
+
+
+@runtime_checkable
+class CredentialsInterface(BadgeInterface, Protocol):
+    """A credential to verify, carried on a passport as a badge.
+
+    A password to check, a signature to validate. It is a
+    :class:`~xtr_security_http.authenticator.passport.badge.badge_interface.BadgeInterface`
+    like any other, unresolved until the listener that knows how verifies it —
+    at which point it reports resolved and drops whatever secret it held, so a
+    credential is consumed exactly once.
+    """

xtr_security_http/authenticator/passport/credentials/custom_credentials.py

@@ -0,0 +1,64 @@
+"""A credential verified by a caller-supplied check."""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .credentials_interface import CredentialsInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+__all__ = ["CustomCredentials"]
+
+
+@final
+class CustomCredentials(CredentialsInterface):
+    """A credential whose verification an authenticator supplies as a check.
+
+    The escape hatch for a scheme the built-in credentials do not cover: the
+    check is a callable given the credentials and the resolved user, returning
+    whether they are valid — awaited when it returns an awaitable. The
+    credentials listener runs it, and a falsy result fails authentication.
+
+    Attributes:
+        checker: The callable that verifies ``credentials`` for a user.
+        credentials: The value handed to the checker.
+    """
+
+    __slots__ = ("_checker", "_credentials", "_resolved")
+
+    def __init__(
+        self,
+        checker: Callable[..., bool | Awaitable[bool]],
+        credentials: object,
+    ) -> None:
+        """Record the check and the credentials it verifies."""
+        self._checker = checker
+        self._credentials = credentials
+        self._resolved = False
+
+    async def verify(self, user: object) -> bool:
+        """Run the check for ``user`` and mark the credentials resolved.
+
+        The checker is called with the credentials and the user; a result that
+        is an awaitable is awaited. Resolving happens whatever the outcome — a
+        credential is consumed by being checked, valid or not.
+        """
+        result = self._checker(self._credentials, user)
+        if inspect.isawaitable(result):
+            result = await result
+        self._resolved = True
+        return bool(result)
+
+    def get_credentials(self) -> object:
+        """Return the credentials the checker verifies."""
+        return self._credentials
+
+    @override
+    def is_resolved(self) -> bool:
+        """Tell whether the check has run."""
+        return self._resolved

xtr_security_http/authenticator/passport/credentials/password_credentials.py

@@ -0,0 +1,51 @@
+"""A plaintext password to verify, consumed once."""
+
+from __future__ import annotations
+
+from typing import final
+
+from typing_extensions import override
+from xtr_security_core.exception import InvalidArgumentError
+
+from .credentials_interface import CredentialsInterface
+
+__all__ = ["PasswordCredentials"]
+
+
+@final
+class PasswordCredentials(CredentialsInterface):
+    """A plaintext password waiting to be verified.
+
+    Carried on a passport for the credentials listener to check against the
+    user's stored hash. Verifying it calls :meth:`mark_resolved`, which drops
+    the plaintext: it is held only until the one check that reads it, never
+    longer. Reading the plaintext after it is resolved is refused.
+    """
+
+    __slots__ = ("_password", "_resolved")
+
+    def __init__(self, password: str) -> None:
+        """Record the plaintext password to verify."""
+        self._password = password
+        self._resolved = False
+
+    def get_password(self) -> str:
+        """Return the plaintext to verify, before it is consumed.
+
+        Raises:
+            InvalidArgumentError: When the credentials are already resolved and
+                the plaintext has been dropped.
+        """
+        if self._resolved:
+            raise InvalidArgumentError("The password credentials have already been resolved.")
+        return self._password
+
+    def mark_resolved(self) -> None:
+        """Mark the credentials verified and drop the plaintext."""
+        self._resolved = True
+        self._password = ""
+
+    @override
+    def is_resolved(self) -> bool:
+        """Tell whether the credentials have been verified."""
+        return self._resolved

xtr_security_http/authenticator/passport/passport.py

@@ -0,0 +1,104 @@
+"""The bag of badges an authenticator hands to the passport check."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, TypeVar
+
+from xtr_security_core.exception import BadCredentialsError
+
+from xtr_security_http.authenticator.passport.badge.user_badge import UserBadge
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from xtr_security_core.user.user_interface import UserInterface
+
+    from .badge.badge_interface import BadgeInterface
+
+__all__ = ["Passport"]
+
+_BadgeT = TypeVar("_BadgeT", bound="BadgeInterface")
+
+
+class Passport:
+    """What an authenticator produced from a request, before a token exists.
+
+    A passport always carries a
+    :class:`~xtr_security_http.authenticator.passport.badge.user_badge.UserBadge`
+    naming the user, and any number of other badges — credentials to verify, a
+    note to upgrade a password. Listeners resolve the badges during the
+    passport check; :meth:`get_user` loads the user through the user badge.
+    Attributes are a scratch space listeners and the authenticator share while
+    building the token.
+
+    Badges are keyed by class: a passport carries at most one of each kind.
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_attributes", "_badges")
+
+    def __init__(
+        self,
+        user_badge: UserBadge,
+        badges: Iterable[BadgeInterface] = (),
+        attributes: Mapping[str, object] | None = None,
+    ) -> None:
+        """Record the user badge and any other badges, keyed by their class."""
+        self._badges: dict[type, BadgeInterface] = {}
+        _ = self.add_badge(user_badge)
+        for badge in badges:
+            _ = self.add_badge(badge)
+        self._attributes: dict[str, object] = dict(attributes) if attributes is not None else {}
+
+    def add_badge(self, badge: BadgeInterface) -> Passport:
+        """Attach ``badge``, replacing any badge of its class, and return self."""
+        self._badges[type(badge)] = badge
+        return self
+
+    def has_badge(self, badge_class: type[BadgeInterface]) -> bool:
+        """Tell whether a badge of ``badge_class`` is attached."""
+        return badge_class in self._badges
+
+    def get_badge(self, badge_class: type[_BadgeT]) -> _BadgeT | None:
+        """Return the badge of ``badge_class``, or ``None`` when none is attached."""
+        badge = self._badges.get(badge_class)
+        return badge if isinstance(badge, badge_class) else None
+
+    def get_badges(self) -> Mapping[type, BadgeInterface]:
+        """Return every badge attached, keyed by class."""
+        return dict(self._badges)
+
+    def get_user_badge(self) -> UserBadge:
+        """Return the user badge every passport carries."""
+        badge = self._badges[UserBadge]
+        assert isinstance(badge, UserBadge)  # noqa: S101 -- construction guarantees it
+        return badge
+
+    async def get_user(self) -> UserInterface:
+        """Load and return the user through the user badge."""
+        return await self.get_user_badge().get_user()
+
+    def get_attribute(self, name: str, default: object = None) -> object:
+        """Return the attribute ``name``, or ``default`` when it is not set."""
+        return self._attributes.get(name, default)
+
+    def set_attribute(self, name: str, value: object) -> None:
+        """Attach ``value`` under ``name`` on the passport."""
+        self._attributes[name] = value
+
+    def get_attributes(self) -> Mapping[str, object]:
+        """Return every attribute attached to the passport."""
+        return dict(self._attributes)
+
+    def check_if_completely_resolved(self) -> None:
+        """Raise unless every badge reports itself resolved.
+
+        Raises:
+            BadCredentialsError: When any badge is still unresolved once the
+                passport check is done — a credential nobody verified, a user
+                badge no provider gave a loader.
+        """
+        for badge in self._badges.values():
+            if not badge.is_resolved():
+                raise BadCredentialsError(
+                    f"The badge {type(badge).__name__} was not resolved by the passport check.",
+                )