python-general-be-lib 0.11.3__py3-none-any.whl → 0.12.1__py3-none-any.whl

general/auth/__init__.py

@@ -0,0 +1,68 @@
+"""Authentication against a Keycloak realm, shared by the backends.
+
+``KeycloakAuth`` verifies the access tokens of a realm — signature through the keys of its
+JWKS endpoint, expiry, audience, issuer — and exposes the FastAPI dependencies built on
+it; ``AuthContextMiddleware`` verifies the token once per request and publishes the user
+and the claims in ``general.context``. It needs the ``[auth]`` extra (``pyjwt[crypto]``).
+
+The public symbols are resolved lazily (PEP 562): importing this package does not import
+the modules behind them, so reaching one of them does not pay for the heavier siblings.
+The ``TYPE_CHECKING`` block is what keeps the static types — without it a type checker
+would see every symbol as ``Any``, silently, and the ``py.typed`` marker would promise
+types the consumer does not get.
+"""
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "AuthContextMiddleware",
+    "JWTModel",
+    "RealmAccessModel",
+    "JwksKeyProvider",
+    "KeycloakAuth",
+    "RoleChecker",
+]
+
+if TYPE_CHECKING:  # i type checker leggono da qui, il runtime no
+    from .jwt_model import JWTModel, RealmAccessModel
+    from .key_provider import JwksKeyProvider
+    from .keycloak_auth import KeycloakAuth, RoleChecker
+    from .middleware import AuthContextMiddleware
+
+_MODULES = {
+    "JWTModel": ".jwt_model",
+    "RealmAccessModel": ".jwt_model",
+    "JwksKeyProvider": ".key_provider",
+    "KeycloakAuth": ".keycloak_auth",
+    "RoleChecker": ".keycloak_auth",
+    "AuthContextMiddleware": ".middleware",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public symbol, importing its module on first access.
+
+    Args:
+        name (str): Name of the attribute being read.
+
+    Returns:
+        Any: The requested symbol.
+
+    Raises:
+        AttributeError: If the name is not part of the public surface.
+    """
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
+
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

general/auth/jwt_model.py

@@ -0,0 +1,92 @@
+"""Pydantic models of the claims of a Keycloak access token.
+
+``JWTModel`` declares the standard claims Keycloak puts in an access token. The claims a
+realm adds through its own mappers (``user_id``, ``partner_id``, …) do not belong here:
+each backend declares them in a subclass and passes it to ``KeycloakAuth`` as ``model``.
+"""
+
+__all__ = ["JWTModel", "RealmAccessModel"]
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class RealmAccessModel(BaseModel):
+    """Roles granted to the user, in the shape Keycloak uses for both realm and client roles.
+
+    Attributes:
+        roles (list[str]): Names of the roles. Empty when the claim carries none.
+    """
+    roles: list[str] = []
+
+
+class JWTModel(BaseModel):
+    """Standard claims of a Keycloak access token.
+
+    Every claim is optional, so a token lacking one validates anyway, and the unknown ones
+    are ignored: a realm mapper added after deployment does not break the validation. To
+    read a custom claim, declare it in a subclass.
+
+    Attributes:
+        aud (str | list[str], optional): Audience. Keycloak emits a string with one
+            audience and a list with more than one.
+        sub (str, optional): Identifier of the user in the realm.
+        realm_access (RealmAccessModel, optional): Realm roles of the user.
+        resource_access (dict[str, RealmAccessModel], optional): Client roles of the user,
+            keyed by client id.
+    """
+    model_config = ConfigDict(extra="ignore")
+
+    exp: Optional[int] = None
+    iat: Optional[int] = None
+    jti: Optional[str] = None
+    iss: Optional[str] = None
+    aud: Optional[str | list[str]] = None
+    sub: Optional[str] = None
+    typ: Optional[str] = None
+    azp: Optional[str] = None
+    session_state: Optional[str] = None
+    acr: Optional[str] = None
+    realm_access: Optional[RealmAccessModel] = None
+    resource_access: Optional[dict[str, RealmAccessModel]] = None
+    scope: Optional[str] = None
+    sid: Optional[str] = None
+    email_verified: Optional[bool] = None
+    name: Optional[str] = None
+    preferred_username: Optional[str] = None
+    given_name: Optional[str] = None
+    family_name: Optional[str] = None
+    email: Optional[str] = None
+
+    def roles_of(self, client: Optional[str] = None) -> list[str]:
+        """Return the roles of the user, empty when the token carries none.
+
+        Args:
+            client (str, optional): Client id whose roles are read from
+                ``resource_access``. When omitted, the realm roles are read from
+                ``realm_access``.
+
+        Returns:
+            list[str]: The roles, never ``None``.
+        """
+        if client is None:
+            return self.realm_access.roles if self.realm_access is not None else []
+        access = (self.resource_access or {}).get(client)
+        return access.roles if access is not None else []
+
+    def has_role(self, role: str, client: Optional[str] = None) -> bool:
+        """Tell whether the user holds a role.
+
+        Unlike ``role in jwt.realm_access.roles`` it does not raise when the token carries
+        no roles at all.
+
+        Args:
+            role (str): Name of the role.
+            client (str, optional): Client id the role belongs to. When omitted, the role
+                is looked up among the realm roles.
+
+        Returns:
+            bool: ``True`` if the user holds the role.
+        """
+        return role in self.roles_of(client)

general/auth/key_provider.py

@@ -0,0 +1,203 @@
+"""Signing keys of a Keycloak realm, read from its JWKS endpoint and cached in memory.
+
+The JWKS endpoint (``/protocol/openid-connect/certs``) publishes every active key of the
+realm with its ``kid``, and the token header names the one it was signed with: during a
+key rotation both keys are published, so no token is rejected while it happens. The
+``public_key`` field of the realm endpoint, read by the handlers this module replaces,
+carries one key only.
+"""
+
+__all__ = ["JwksKeyProvider"]
+
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Optional
+from urllib.request import urlopen
+
+try:
+    from jwt import PyJWK, PyJWKSet
+except ImportError as e:  # pragma: no cover - dipende dagli extra installati
+    raise ImportError("general.auth needs the [auth] extra: pip install 'python-general-be-lib[auth]'") from e
+
+from ..exception.crud_exceptions import ServiceUnavailableException
+
+
+class JwksKeyProvider:
+    """Thread-safe, in-memory cache of the signing keys of a realm.
+
+    The keys are fetched on the first request, and fetched again when the cache is older
+    than ``ttl`` or a token names a ``kid`` the cache does not know, which is how a key
+    rotation is picked up. Every fetch, forced ones included, is **rate limited** to one per
+    ``min_refresh_interval``: a token naming a made-up ``kid`` cannot turn each request
+    into a call to Keycloak. A failed fetch keeps the keys already cached, so an
+    unreachable Keycloak does not reject tokens it signed before going down.
+
+    Attributes:
+        jwks_url (str): URL of the JWKS endpoint.
+        ttl (float): Seconds after which the cached keys are fetched again.
+        min_refresh_interval (float): Minimum seconds between two fetch attempts.
+        timeout (float): Timeout in seconds of the HTTP request.
+    """
+    __slots__ = (
+        "jwks_url",
+        "ttl",
+        "min_refresh_interval",
+        "timeout",
+        "_fetch",
+        "_lock",
+        "_keys",
+        "_fetched_at",
+        "_last_attempt",
+    )
+
+    def __init__(
+        self,
+        jwks_url: str,
+        ttl: float = 3600,
+        min_refresh_interval: float = 30,
+        timeout: float = 5,
+        fetch: Optional[Callable[[], dict[str, Any]]] = None,
+    ):
+        """Configure the provider. Nothing is fetched until the first key is requested.
+
+        Args:
+            jwks_url (str): URL of the JWKS endpoint, ``http`` or ``https``.
+            ttl (float): Seconds after which the cached keys are fetched again.
+                Default: ``3600``.
+            min_refresh_interval (float): Minimum seconds between two fetch attempts.
+                Default: ``30``.
+            timeout (float): Timeout in seconds of the HTTP request. Default: ``5``.
+            fetch (Callable[[], dict], optional): Function returning the JWKS document,
+                in place of the HTTP request to ``jwks_url``.
+
+        Raises:
+            ValueError: If ``jwks_url`` is not an ``http(s)`` URL.
+        """
+        if not isinstance(jwks_url, str) or not jwks_url.startswith(("http://", "https://")):
+            raise ValueError(f"JwksKeyProvider: jwks_url must be an http(s) URL, got {jwks_url!r}")
+        self.jwks_url = jwks_url
+        self.ttl = ttl
+        self.min_refresh_interval = min_refresh_interval
+        self.timeout = timeout
+        self._fetch = fetch if fetch is not None else self._fetch_jwks
+        self._lock = threading.Lock()
+        self._keys: dict[Optional[str], PyJWK] = {}
+        self._fetched_at: Optional[float] = None
+        self._last_attempt: Optional[float] = None
+
+    def needs_fetch(self, kid: Optional[str]) -> bool:
+        """Tell whether resolving ``kid`` now would make an HTTP request.
+
+        It lets an async caller keep the common case, a fresh key already cached, on the
+        event loop, and move to a worker thread only the calls that would block on the
+        network.
+
+        Args:
+            kid (str, optional): Key id read from the token header.
+
+        Returns:
+            bool: ``True`` if ``get_key`` would fetch the JWKS.
+        """
+        now = time.monotonic()
+        fresh = self._fetched_at is not None and now - self._fetched_at < self.ttl
+        if fresh and self._select(kid) is not None:
+            return False
+        return self._last_attempt is None or now - self._last_attempt >= self.min_refresh_interval
+
+    def get_key(self, kid: Optional[str]) -> Optional[PyJWK]:
+        """Return the signing key named by ``kid``, fetching the JWKS when needed.
+
+        Args:
+            kid (str, optional): Key id read from the token header. A token without one is
+                accepted only while the realm publishes a single signing key.
+
+        Returns:
+            PyJWK | None: The key, or ``None`` if the realm does not publish it.
+
+        Raises:
+            ServiceUnavailableException: If no key has ever been fetched, because the
+                JWKS endpoint is unreachable.
+        """
+        if self.needs_fetch(kid):
+            with self._lock:
+                # ricontrollato sotto lock: un altro thread può aver appena fatto il fetch
+                if self.needs_fetch(kid):
+                    self._refresh()
+        if not self._keys:
+            raise ServiceUnavailableException()
+        return self._select(kid)
+
+    def refresh(self) -> bool:
+        """Fetch the JWKS now, ignoring both the TTL and the rate limit.
+
+        Meant for the startup, to fill the cache before the first request.
+
+        Returns:
+            bool: ``True`` if the fetch succeeded. On failure the keys already cached are
+            kept.
+        """
+        with self._lock:
+            return self._refresh()
+
+    def _refresh(self) -> bool:
+        """Fetch and parse the JWKS, replacing the cache only on success. Call under lock.
+
+        Returns:
+            bool: ``True`` if the fetch succeeded.
+        """
+        # `_last_attempt` si scrive a tentativo **concluso**: scritto prima, chi arriva durante
+        # il primo fetch vedrebbe il rate limit attivo e la cache vuota, e avrebbe un 503
+        # invece di aspettare sul lock l'esito del fetch in corso
+        try:
+            keys = self._parse(self._fetch())
+        except Exception as e:
+            self._last_attempt = time.monotonic()
+            logging.warning(f"JWKS fetch from {self.jwks_url} failed - {e!r}")
+            return False
+        self._keys = keys
+        self._fetched_at = self._last_attempt = time.monotonic()
+        return True
+
+    def _select(self, kid: Optional[str]) -> Optional[PyJWK]:
+        """Look ``kid`` up in the cache, without fetching.
+
+        Args:
+            kid (str, optional): Key id read from the token header.
+
+        Returns:
+            PyJWK | None: The cached key, or ``None`` if it is not there.
+        """
+        keys = self._keys
+        if kid is None:
+            return next(iter(keys.values())) if len(keys) == 1 else None
+        return keys.get(kid)
+
+    def _fetch_jwks(self) -> dict[str, Any]:
+        """Download the JWKS document from ``jwks_url``.
+
+        Returns:
+            dict[str, Any]: The parsed JSON document.
+        """
+        with urlopen(self.jwks_url, timeout=self.timeout) as response:
+            return json.load(response)
+
+    @staticmethod
+    def _parse(jwks: dict[str, Any]) -> dict[Optional[str], PyJWK]:
+        """Keep the signing keys of a JWKS document, keyed by ``kid``.
+
+        Keycloak publishes the encryption keys (``"use": "enc"``) at the same endpoint;
+        they cannot verify a signature, so they are left out.
+
+        Args:
+            jwks (dict[str, Any]): The JWKS document.
+
+        Returns:
+            dict[str | None, PyJWK]: The signing keys.
+
+        Raises:
+            PyJWKSetError: If the document holds no usable signing key.
+        """
+        signing = [key for key in jwks.get("keys", []) if key.get("use", "sig") == "sig"]
+        return {key.key_id: key for key in PyJWKSet.from_dict({"keys": signing}).keys}

general/auth/keycloak_auth.py

@@ -0,0 +1,376 @@
+"""Verification of Keycloak access tokens and the FastAPI dependencies built on it.
+
+``KeycloakAuth`` holds the configuration of one backend — realm, audience, claims model —
+and exposes what the backends used to copy in their own ``jwt_handler.py``: the bearer
+scheme, the dependency returning the verified claims, the role checks. ``RoleChecker`` is
+the role check alone, callable by hand where a dependency does not fit.
+"""
+
+__all__ = ["KeycloakAuth", "RoleChecker"]
+
+from contextvars import ContextVar
+from typing import Annotated, Any, Awaitable, Callable, Optional, Sequence, overload
+
+from fastapi import Depends, HTTPException
+from fastapi.params import Depends as DependsParam
+from fastapi.security import OAuth2PasswordBearer
+from pydantic import ValidationError
+from starlette.concurrency import run_in_threadpool
+
+try:
+    import jwt
+except ImportError as e:  # pragma: no cover - dipende dagli extra installati
+    raise ImportError("general.auth needs the [auth] extra: pip install 'python-general-be-lib[auth]'") from e
+
+from ..exception.access_exceptions import ForbiddenException, UnauthorizedException
+from ..exception.crud_exceptions import ServiceUnavailableException
+from .jwt_model import JWTModel
+from .key_provider import JwksKeyProvider
+
+# esito della verifica fatta da `AuthContextMiddleware`, letto dalla dependency `current`:
+# (auth, token, claims oppure l'eccezione). Il token sta nella tupla perché la dependency
+# riusi l'esito solo per lo stesso header che legge lei, e l'auth perché lo riusi solo
+# l'istanza che l'ha prodotto.
+_verified: ContextVar[Optional[tuple["KeycloakAuth[Any]", str, Any]]] = ContextVar("general_auth_verified", default=None)
+
+
+class RoleChecker:
+    """Check that the claims of a token grant some roles.
+
+    It is the policy alone, with no dependency injection: call it on already verified
+    claims, e.g. for a check that applies only to some requests. To guard an endpoint, use
+    ``KeycloakAuth.require_roles``, which wraps it in a dependency.
+
+    Attributes:
+        roles (frozenset[str]): Roles to look for.
+        require_all (bool): If ``True`` every role is required, otherwise one is enough.
+        client (str | None): Client id the roles belong to; ``None`` for realm roles.
+    """
+    __slots__ = "roles", "require_all", "client"
+
+    def __init__(self, *roles: str, require_all: bool = False, client: Optional[str] = None):
+        """Configure the check.
+
+        Args:
+            *roles (str): Roles to look for.
+            require_all (bool): If ``True`` every role is required, otherwise one is
+                enough. Default: ``False``.
+            client (str, optional): Client id whose roles are read from
+                ``resource_access``. When omitted, the realm roles are read.
+
+        Raises:
+            ValueError: If no role is given.
+        """
+        if not roles:
+            raise ValueError("RoleChecker needs at least one role")
+        self.roles = frozenset(roles)
+        self.require_all = require_all
+        self.client = client
+
+    def __call__(self, claims: JWTModel) -> bool:
+        """Run the check.
+
+        Args:
+            claims (JWTModel): Verified claims of the token.
+
+        Returns:
+            bool: Always ``True``: a failed check raises instead.
+
+        Raises:
+            ForbiddenException: If the roles are not granted, including when the token
+                carries no roles at all.
+        """
+        held = set(claims.roles_of(self.client))
+        granted = held >= self.roles if self.require_all else not held.isdisjoint(self.roles)
+        if not granted:
+            raise ForbiddenException("Operazione selezionata non consentita")
+        return True
+
+
+class KeycloakAuth[M: JWTModel]:
+    """Verification of the access tokens of one Keycloak realm, configured per backend.
+
+    Built once per application, it verifies signature, expiry, audience and issuer of a
+    token against the signing keys of the realm, and validates the claims into ``model``.
+    **Every** invalid token yields a 401, audience and issuer included; a 503 is left for
+    a JWKS endpoint that is unreachable while no key has been cached yet.
+
+    Attributes:
+        realm_url (str): URL of the realm, without the trailing slash.
+        issuer (str | None): Expected ``iss`` claim; ``None`` when not verified.
+        audience (list[str]): Accepted audiences; the token must name at least one.
+        algorithms (list[str]): Accepted signing algorithms.
+        leeway (float): Seconds of clock skew tolerated on ``exp`` and ``iat``.
+        model (type[M]): Model the claims are validated into.
+        user_claim (str | Callable[[M], Any]): Claim, or function of the claims,
+            identifying the user for the audit.
+        key_provider (JwksKeyProvider): Cache of the signing keys of the realm.
+        oauth2_scheme (OAuth2PasswordBearer): Bearer scheme, which also documents the
+            authentication in the OpenAPI schema.
+        bearer (Depends): Dependency on ``oauth2_scheme``, to guard a router with
+            ``dependencies=[auth.bearer]``.
+        current (Callable[..., Awaitable[M]]): Dependency returning the verified claims
+            of the request. Behind ``AuthContextMiddleware`` it reuses the verification the
+            middleware already made, error included, instead of verifying the token again.
+    """
+    __slots__ = (
+        "realm_url",
+        "issuer",
+        "audience",
+        "algorithms",
+        "leeway",
+        "model",
+        "user_claim",
+        "key_provider",
+        "oauth2_scheme",
+        "bearer",
+        "current",
+    )
+
+    realm_url: str
+    issuer: Optional[str]
+    audience: list[str]
+    algorithms: list[str]
+    leeway: float
+    model: type[M]
+    user_claim: str | Callable[[M], Any]
+    key_provider: JwksKeyProvider
+    oauth2_scheme: OAuth2PasswordBearer
+    bearer: DependsParam
+    current: Callable[..., Awaitable[M]]
+
+    # senza `model` il type checker non ha da dove ricavare M: il primo overload lo fissa a
+    # JWTModel, altrimenti chi omette il modello si vede chiedere un'annotazione
+    @overload
+    def __init__(
+        self: "KeycloakAuth[JWTModel]",
+        realm_url: str,
+        audience: str | Sequence[str],
+        *,
+        user_claim: str | Callable[[JWTModel], Any] = ...,
+        token_url: str = ...,
+        algorithms: Sequence[str] = ...,
+        issuer: Optional[str] = ...,
+        verify_issuer: bool = ...,
+        leeway: float = ...,
+        key_provider: Optional[JwksKeyProvider] = ...,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        realm_url: str,
+        audience: str | Sequence[str],
+        model: type[M],
+        user_claim: str | Callable[[M], Any] = ...,
+        token_url: str = ...,
+        algorithms: Sequence[str] = ...,
+        issuer: Optional[str] = ...,
+        verify_issuer: bool = ...,
+        leeway: float = ...,
+        key_provider: Optional[JwksKeyProvider] = ...,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        realm_url: str,
+        audience: str | Sequence[str],
+        model: type[M] = JWTModel,  # type: ignore[assignment]
+        user_claim: str | Callable[[M], Any] = "sub",
+        token_url: str = "token",
+        algorithms: Sequence[str] = ("RS256",),
+        issuer: Optional[str] = None,
+        verify_issuer: bool = True,
+        leeway: float = 0,
+        key_provider: Optional[JwksKeyProvider] = None,
+    ):
+        """Configure the verification. Nothing is fetched until ``warm_up`` or the first token.
+
+        Args:
+            realm_url (str): URL of the realm, ``{KC_URL}/realms/{realm}``, with or without
+                the trailing slash. Issuer and JWKS endpoint are derived from it.
+            audience (str | Sequence[str]): Accepted audiences, e.g.
+                ``[KC_CLIENT_ID, "account"]``.
+            model (type[M]): Model the claims are validated into; a subclass of
+                ``JWTModel`` declaring the custom claims of the realm. Default: ``JWTModel``.
+            user_claim (str | Callable[[M], Any]): Name of the claim identifying the user,
+                or a function computing it from the claims. The value is turned into a
+                string, which is the type of the audit columns. Default: ``"sub"``.
+            token_url (str): ``tokenUrl`` of the bearer scheme, the endpoint Swagger asks
+                the token to. Default: ``"token"``.
+            algorithms (Sequence[str]): Accepted signing algorithms. Default: ``("RS256",)``.
+            issuer (str, optional): Expected ``iss`` claim, in place of the one derived
+                from ``realm_url``. Needed when the backend reaches Keycloak through a URL
+                other than the public one the tokens are issued with.
+            verify_issuer (bool): If ``False`` the ``iss`` claim is not verified.
+                Default: ``True``.
+            leeway (float): Seconds of clock skew tolerated on ``exp`` and ``iat``.
+                Default: ``0``.
+            key_provider (JwksKeyProvider, optional): Cache of the signing keys, in place
+                of the one built on the JWKS endpoint of ``realm_url``.
+
+        Raises:
+            ValueError: If ``realm_url`` is not an ``http(s)`` URL, or ``audience`` or
+                ``algorithms`` are empty or hold an empty value — typically an environment
+                variable that is not set.
+        """
+        if not isinstance(realm_url, str) or not realm_url.startswith(("http://", "https://")):
+            raise ValueError(f"KeycloakAuth: realm_url must be an http(s) URL, got {realm_url!r}")
+        audiences = [audience] if isinstance(audience, str) or audience is None else list(audience)
+        if not audiences or not all(audiences):
+            raise ValueError(f"KeycloakAuth: audience must hold non-empty values, got {audience!r}")
+        if not algorithms or not all(algorithms) or isinstance(algorithms, str):
+            raise ValueError(f"KeycloakAuth: algorithms must be a non-empty sequence, got {algorithms!r}")
+
+        self.realm_url = realm_url.rstrip("/")
+        self.issuer = (issuer or self.realm_url) if verify_issuer else None
+        self.audience = audiences
+        self.algorithms = list(algorithms)
+        self.leeway = leeway
+        self.model = model
+        self.user_claim = user_claim
+        self.key_provider = key_provider or JwksKeyProvider(f"{self.realm_url}/protocol/openid-connect/certs")
+        self.oauth2_scheme = OAuth2PasswordBearer(tokenUrl=token_url)
+        self.bearer = Depends(self.oauth2_scheme)
+
+        # una closure e non un metodo: FastAPI legge la dependency dalla firma, e il default
+        # `Depends(self.oauth2_scheme)` esiste solo per istanza
+        async def current(token: Annotated[str, Depends(self.oauth2_scheme)]) -> M:
+            verified = _verified.get()
+            if verified is not None and verified[0] is self and verified[1] == token:
+                outcome = verified[2]
+                if isinstance(outcome, HTTPException):
+                    raise outcome
+                return outcome
+            return await self.adecode(token)
+
+        self.current = current
+
+    def decode(self, token: str) -> M:
+        """Verify a token and validate its claims.
+
+        It is synchronous and may block on the JWKS fetch, at most once per
+        ``min_refresh_interval`` of the key provider.
+
+        Args:
+            token (str): The encoded token, without the ``Bearer`` prefix.
+
+        Returns:
+            M: The verified claims.
+
+        Raises:
+            UnauthorizedException: If the token is expired, malformed, signed by a key the
+                realm does not publish, or its audience, issuer or claims are not valid.
+            ServiceUnavailableException: If the JWKS endpoint is unreachable and no key has
+                been cached yet.
+        """
+        key = self.key_provider.get_key(self._kid_of(token))
+        if key is None:
+            raise UnauthorizedException("Token non valido")
+        try:
+            payload = jwt.decode(
+                token,
+                key=key.key,
+                algorithms=self.algorithms,
+                audience=self.audience,
+                issuer=self.issuer,
+                leeway=self.leeway,
+                options={"require": ["exp", "iat"]},
+            )
+        except jwt.ExpiredSignatureError:
+            raise UnauthorizedException("Token scaduto")
+        except jwt.PyJWTError:
+            raise UnauthorizedException("Token non valido")
+        try:
+            return self.model.model_validate(payload)
+        except ValidationError:
+            raise UnauthorizedException("Token non valido")
+
+    async def adecode(self, token: str) -> M:
+        """Verify a token like ``decode``, without blocking the event loop.
+
+        The common case — a fresh key already cached — runs on the event loop, with no
+        thread hop; only a verification that would fetch the JWKS moves to a worker thread.
+
+        Args:
+            token (str): The encoded token, without the ``Bearer`` prefix.
+
+        Returns:
+            M: The verified claims.
+
+        Raises:
+            UnauthorizedException: As ``decode``.
+            ServiceUnavailableException: As ``decode``.
+        """
+        if self.key_provider.needs_fetch(self._kid_of(token)):
+            return await run_in_threadpool(self.decode, token)
+        return self.decode(token)
+
+    @staticmethod
+    def _kid_of(token: str) -> Optional[str]:
+        """Read the key id from the header of a token, without verifying it.
+
+        Args:
+            token (str): The encoded token.
+
+        Returns:
+            str | None: The ``kid`` of the header, ``None`` when missing.
+
+        Raises:
+            UnauthorizedException: If the header cannot be read.
+        """
+        try:
+            return jwt.get_unverified_header(token).get("kid")
+        except jwt.PyJWTError:
+            raise UnauthorizedException("Token non valido")
+
+    def user_of(self, claims: M) -> Optional[str]:
+        """Identify the user the claims belong to, as the audit columns store it.
+
+        Args:
+            claims (M): Verified claims of the token.
+
+        Returns:
+            str | None: The value of ``user_claim`` as a string, or ``None`` if missing.
+        """
+        value = self.user_claim(claims) if callable(self.user_claim) else getattr(claims, self.user_claim, None)
+        return None if value is None else str(value)
+
+    def require_roles(self, *roles: str, require_all: bool = False, client: Optional[str] = None) -> DependsParam:
+        """Build a dependency guarding an endpoint by role.
+
+        It goes through ``current``, which FastAPI resolves once per request: several role
+        checks on the same endpoint verify the token once.
+
+        Args:
+            *roles (str): Roles to look for.
+            require_all (bool): If ``True`` every role is required, otherwise one is
+                enough. Default: ``False``.
+            client (str, optional): Client id whose roles are read from
+                ``resource_access``. When omitted, the realm roles are read.
+
+        Returns:
+            Depends: The dependency, for an endpoint parameter or ``dependencies=[...]``.
+
+        Raises:
+            ValueError: If no role is given.
+        """
+        checker = RoleChecker(*roles, require_all=require_all, client=client)
+
+        # async: il controllo non blocca, e una dependency sincrona costerebbe un thread hop
+        async def check(claims: Annotated[JWTModel, Depends(self.current)]) -> bool:
+            return checker(claims)
+
+        return Depends(check)
+
+    def warm_up(self) -> None:
+        """Fetch the signing keys now, so that the first request does not wait for them.
+
+        Call it at startup, in the lifespan of the application: with several workers each
+        process has its own cache, so a call made before the workers start fills none.
+
+        Raises:
+            ServiceUnavailableException: If the JWKS endpoint cannot be reached.
+        """
+        if not self.key_provider.refresh():
+            raise ServiceUnavailableException()

general/auth/middleware.py

@@ -0,0 +1,94 @@
+"""ASGI middleware setting the context of the request from its bearer token.
+
+It verifies the token once per request and publishes the outcome: the user in
+``current_user`` (read by ``AuditMixin``), the claims in ``current_jwt``, and the result,
+error included, for the ``KeycloakAuth.current`` dependency.
+"""
+
+__all__ = ["AuthContextMiddleware"]
+
+from typing import Any
+
+from fastapi import HTTPException
+from fastapi.security.utils import get_authorization_scheme_param
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from ..context import current_jwt, current_user
+from .keycloak_auth import KeycloakAuth, _verified
+
+
+class AuthContextMiddleware:
+    """Verify the bearer token of each request and set the context from it.
+
+    It is a pure ASGI middleware, not a ``BaseHTTPMiddleware``, and it **never answers on
+    its own**: an invalid token leaves the context empty and records the error, which the
+    ``KeycloakAuth.current`` dependency raises inside the application. So the 401 goes
+    through the exception handlers and the CORS middleware, whatever the order the
+    middlewares were added in, and an endpoint without an auth dependency stays reachable
+    even with an expired token.
+
+    Attributes:
+        app (ASGIApp): The wrapped application.
+        auth (KeycloakAuth): The verification the tokens go through.
+    """
+    __slots__ = "app", "auth"
+
+    def __init__(self, app: ASGIApp, auth: KeycloakAuth[Any]):
+        """Wrap the application.
+
+        Args:
+            app (ASGIApp): The application, passed by ``add_middleware``.
+            auth (KeycloakAuth): The verification the tokens go through, the same instance
+                whose dependencies guard the endpoints.
+        """
+        self.app = app
+        self.auth = auth
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Verify the token, if any, then call the application with the context set.
+
+        Args:
+            scope (Scope): ASGI connection scope.
+            receive (Receive): ASGI receive channel.
+            send (Send): ASGI send channel.
+        """
+        token = self._bearer(scope) if scope["type"] in ("http", "websocket") else None
+        if token is None:
+            await self.app(scope, receive, send)
+            return
+
+        claims = None
+        outcome: Any
+        try:
+            claims = outcome = await self.auth.adecode(token)
+        except HTTPException as e:
+            outcome = e
+
+        user_token = current_user.set(self.auth.user_of(claims) if claims is not None else None)
+        jwt_token = current_jwt.set(claims)
+        verified_token = _verified.set((self.auth, token, outcome))
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            _verified.reset(verified_token)
+            current_jwt.reset(jwt_token)
+            current_user.reset(user_token)
+
+    @staticmethod
+    def _bearer(scope: Scope) -> str | None:
+        """Extract the bearer token from the ``Authorization`` header.
+
+        It parses the header the way ``OAuth2PasswordBearer`` does, so that the dependency
+        finds the very same token and reuses the outcome.
+
+        Args:
+            scope (Scope): ASGI connection scope.
+
+        Returns:
+            str | None: The token, or ``None`` if the header is missing or not a bearer.
+        """
+        for name, value in scope.get("headers", ()):
+            if name == b"authorization":
+                scheme, param = get_authorization_scheme_param(value.decode("latin-1"))
+                return param if scheme.lower() == "bearer" and param else None
+        return None

general/context.py

@@ -8,16 +8,20 @@ The module imports nothing from the library and nothing from SQLAlchemy, so a mi
 can set the context without paying for the data access layer.
 """
 
-__all__ = ["current_user"]
+__all__ = ["current_user", "current_jwt"]
 
 from contextvars import ContextVar
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # solo per il tipo: a runtime il modulo non importa niente della libreria
+    from .auth.jwt_model import JWTModel
 
 current_user: ContextVar[Optional[str]] = ContextVar("current_user", default=None)
 """Identifier of the user the current operation is attributed to.
 
-Read by ``AuditMixin`` to fill ``create_uid``/``write_uid``. Setting it is up to the
-consumer, typically in the authentication middleware::
+Read by ``AuditMixin`` to fill ``create_uid``/``write_uid``. ``general.auth.AuthContextMiddleware``
+sets it from the verified token; without it, setting it is up to the consumer, typically
+in its own authentication middleware::
 
     from general.context import current_user
 
@@ -29,3 +33,13 @@ consumer, typically in the authentication middleware::
 Left unset it holds ``None``, which is what ends up in the columns for the operations
 having no user behind them: scheduled jobs, migrations, a console session.
 """
+
+current_jwt: ContextVar[Optional["JWTModel"]] = ContextVar("current_jwt", default=None)
+"""Verified claims of the token of the current request.
+
+Set by ``general.auth.AuthContextMiddleware`` when the request carries a valid bearer
+token, and left ``None`` otherwise — no token, an invalid one, a job with no request
+behind it. It holds an instance of the ``model`` the ``KeycloakAuth`` was configured with,
+so code outside the dependency injection reads the claims without verifying the token
+again.
+"""

general/exception/access_exceptions.py

@@ -1,8 +1,8 @@
 """HTTP exceptions for authentication and authorization.
 
-Unlike ``crud_exceptions``, these exceptions are never raised automatically by the
-library: they are available to the authentication and authorization layers of the
-projects using it.
+Unlike ``crud_exceptions``, these exceptions are never raised by the data access layer:
+the library raises them only in ``general.auth``, for a rejected token (401) or a missing
+role (403), and they are available to the authorization logic of the projects using it.
 """
 
 __all__ = ["ForbiddenException", "UnauthorizedException"]

general/interface/repository/crud_repository.py

@@ -169,14 +169,23 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return _reduced_model(self.entity, frozenset(selected_columns))
 
     def _handle_exception(self, session: Session, e: Exception):
-        """Close the session, log the error and raise an HTTP-friendly exception.
+        """Roll back and close the session, log the error and raise an HTTP-friendly exception.
 
         An ``OperationalError`` becomes a ``ServiceUnavailableException``, a
         ``NoResultFound`` an ``EntityNotFoundException``, a ``DataError`` or an
         ``IntegrityError`` a ``BadRequestException``; any other exception is re-raised as is.
 
+        ``close`` alone already rolls back the database transaction. What the explicit
+        ``rollback`` adds is the expiry of the ORM instances: an entity still held by the
+        caller raises ``DetachedInstanceError`` on access instead of exposing values that
+        were flushed but never committed. It runs on every error, a failed SELECT included,
+        since on PostgreSQL that aborts the transaction as well. An external session is
+        rolled back and closed too, so the caller's transaction is lost. A failure of the
+        rollback itself is logged and does not replace ``e``, and the session is closed
+        anyway.
+
         Args:
-            session (Session): Session to close.
+            session (Session): Session to roll back and close.
             e (Exception): Caught exception to handle.
 
         Raises:
@@ -184,6 +193,11 @@ class CrudRepository[Entity: Base | Type[Base]]:
             EntityNotFoundException: If no record matches.
             BadRequestException: If the data is malformed or violates a constraint.
         """
+        try:
+            session.rollback()
+        except Exception:
+            # un rollback fallito non deve sostituire l'errore originale, né saltare la close
+            logging.exception("Rollback failed")
         session.close()
         logging.error(e)
         raise_http_exception(e)
@@ -195,12 +209,13 @@ class CrudRepository[Entity: Base | Type[Base]]:
             session (Session): Session to commit.
 
         Raises:
-            ServiceUnavailableException | BadRequestException: On error during the commit.
+            ServiceUnavailableException | BadRequestException: On error during the commit,
+                after rolling back and closing the session.
         """
         try:
             session.commit()
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
 
     def _flush(self, session: Session):
         """Flush the session, handling the possible exceptions.
@@ -214,12 +229,13 @@ class CrudRepository[Entity: Base | Type[Base]]:
             session (Session): Session to flush.
 
         Raises:
-            ServiceUnavailableException | BadRequestException: On error during the flush.
+            ServiceUnavailableException | BadRequestException: On error during the flush,
+                after rolling back and closing the session.
         """
         try:
             session.flush()
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
 
     def _entity_has_columns(self, *columns: str, entity: Type[Base] | Base = None) -> bool:
         """Check that every given name is a column of the entity.
@@ -441,7 +457,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
             try:
                 entity = session.get(self.entity, values)
             except Exception as e:
-                self._handle_exception(session, e)
+                self._handle_exception(session=session, e=e)
             else:
                 return [entity] if entity is not None else []
 
@@ -607,7 +623,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         try:
             session.add_all(entities)
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
         return self._return(session=session, entities=entities, keep_open=keep_open, commit=True, parsing_model=parsing_model)
 
     def update(self, session: Session = None, where: dict[str, Any] = None, returning: bool = True, parsing_model: Type[BaseModel] | BaseModel = None, **kwargs) -> list[Entity] | list[BaseModel]:
@@ -1049,9 +1065,9 @@ class CrudRepository[Entity: Base | Type[Base]]:
         """Execute a SQLAlchemy statement and return the result as it is.
 
         The method owns the error handling and nothing else: every exception goes to
-        ``_handle_exception``, which closes the session and maps the error to an HTTP
-        status. Reading the result is left to the caller, which is the only one knowing the
-        shape it needs — ``.scalars().all()`` for entities, ``.scalar()`` for an aggregate,
+        ``_handle_exception``, which rolls back and closes the session and maps the error
+        to an HTTP status. Reading the result is left to the caller, which is the only one
+        knowing the shape it needs — ``.scalars().all()`` for entities, ``.scalar()`` for an aggregate,
         ``.all()`` for the multi-column rows of a statement built with ``add_columns``,
         ``.rowcount`` for a DML without ``RETURNING``. The result is bound to the session,
         so it has to be consumed before the session is closed. ``Session.execute`` returns
@@ -1076,6 +1092,6 @@ class CrudRepository[Entity: Base | Type[Base]]:
         try:
             result = session.execute(statement=stmt, params=values)
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
         else:
             return result

{python_general_be_lib-0.11.3.dist-info → python_general_be_lib-0.12.1.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.11.3
-Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities.
+Version: 0.12.1
+Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, Keycloak JWT auth, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT
 Project-URL: Homepage, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Repository, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Changelog, https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md
-Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2
+Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2,keycloak,jwt
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -23,7 +23,10 @@ Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: geoalchemy2>=0.14.0
+Provides-Extra: auth
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "auth"
 Provides-Extra: dev
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "dev"
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-benchmark>=5; extra == "dev"
@@ -38,7 +41,7 @@ Dynamic: license-file
 
 Libreria backend general purpose per progetti Python: repository CRUD e spaziali
 su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
-**Pydantic** e utility di logging.
+**Pydantic**, autenticazione **Keycloak** e utility di logging.
 
 - Distribuzione PyPI: `python-general-be-lib`
 - Pacchetto importabile: `general`
@@ -46,6 +49,7 @@ su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
 
 ```bash
 pip install python-general-be-lib
+pip install 'python-general-be-lib[auth]'     # con l'autenticazione Keycloak (pyjwt[crypto])
 ```
 
 ```python
@@ -72,6 +76,8 @@ repo.find(active=True, order_by="name", asc=True)
 | Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
 | Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
 | Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
+| Autenticazione (extra `[auth]`) | `KeycloakAuth`, `AuthContextMiddleware`, `JWTModel`, `RoleChecker` — verifica dei token Keycloak via JWKS, dependency FastAPI, ruoli |
+| Contesto | `current_user`, `current_jwt` — utente e claim della richiesta, per l'audit |
 | Logging | `init_logger`, decorator `@log` |
 
 ---

{python_general_be_lib-0.11.3.dist-info → python_general_be_lib-0.12.1.dist-info}/RECORD

@@ -1,10 +1,15 @@
 general/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-general/context.py,sha256=ArxisBIbmij72IWKQwBfJBhmAucUGlMnEPRQnYl1A6k,1165
+general/context.py,sha256=AbASV-jPnDM-M-Nih5c9vKHFlIS0kjp8Q1yuHC34FeA,1925
 general/logger.py,sha256=MnK8ZDA9x4xhX0KcpOxTieosnFIhFVwSa8b52Q4T9tA,5039
 general/paginator_dto.py,sha256=DB2hfcrckuEiHEIORLT4EgCcnX4AYYKGlHRr-l-Q1Cw,3741
 general/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+general/auth/__init__.py,sha256=6cYCA6Ir-nnBK9z_bUfh_io3wEYjJUwHAN8mdhjtKeI,2239
+general/auth/jwt_model.py,sha256=KcopeNUPRSQOLvreoIuSo6kJybRtrmhzLoJ5oHFngGw,3447
+general/auth/key_provider.py,sha256=QsyLEZ5sYkIPchraMt-l79IvwvqLAyF84Hk-415gYjI,8012
+general/auth/keycloak_auth.py,sha256=G909oFHpFCMbj2cO9x_HUVb56RqMtKYpBVaiptPVO0o,16162
+general/auth/middleware.py,sha256=nJJHOtlpzDjYdBqgl0TD1_GQZFxKXKMlO_lECcjQdxU,3645
 general/exception/__init__.py,sha256=MZpSDUKeopct7ZqMd1g4XlNS8sM9mmXIlHTIYPOhu9c,849
-general/exception/access_exceptions.py,sha256=tNIBjxM0-5iSOXDc7Il01eb36mEk-POQGVaHhCpG278,744
+general/exception/access_exceptions.py,sha256=j5fas9f24l6a6FdKCrNMP3Djv5DD6I1LRYo3CATcMRU,826
 general/exception/crud_exceptions.py,sha256=7zA9J8KPlvK9MpHbhFEmFpdGVMcqw7hCyRGSJB4-K7U,4356
 general/exception/exception_interface.py,sha256=k7KreAYMwKPQQghkCissdu3ASZZqrRFWM1lAGzeR8sM,1294
 general/interface/__init__.py,sha256=G11sI1Oxtb-Z_-ORAuKS_Kkdwopt1uXmEXYtZEJYiLs,445
@@ -19,7 +24,7 @@ general/interface/mixin/audit_mixin.py,sha256=N2JDD9JxXDMeBqu0yAlhVWFOK3EeUA2b21
 general/interface/mixin/softdelete_mixin.py,sha256=526luzM4DBCorcq99kZ6BYqtQKKJCpnxX9rSEigfyIU,2148
 general/interface/mixin/timestamp_mixin.py,sha256=wmcIx2Y8jgVqg9A-1E61BvkcKCo52ZjKNHeKfXJmUl0,2220
 general/interface/repository/__init__.py,sha256=QQD6okLfRozC0uOZPGrwOUDKJyZTgpObvwJ3OOSJdbM,1813
-general/interface/repository/crud_repository.py,sha256=Hr7APBsN1uFqEfM78ZSIcgheg4ilvND4OMc7TBNOlcw,55962
+general/interface/repository/crud_repository.py,sha256=Z7IgLz7dtfIyzZMJO7T_IDunHH1qTDYRApdWlbMkE2A,57031
 general/interface/repository/geometry_repository.py,sha256=Fmv0qhfqumnU5fiETMMAmiB0UyG43b19jlPXQ8cJ9CU,11289
 general/interface/repository/many_to_many_repository.py,sha256=KRJ2SMUGDYNoGV-ea541wlWg0FW4NQ_Ry85aJBarmC8,11183
 general/interface/repository/view_repository.py,sha256=wxDGw7kenuVrDd9nfh7-omw2m9Jex5WzF_lhEiqPoA0,7902
@@ -35,8 +40,8 @@ general/interface/repository/handler/soft_delete_handler.py,sha256=1WD1n6q5plyJ0
 general/interface/repository/handler/statement_manager.py,sha256=JSj6K-iQJ06kLdsMTOqK62cIvR87ioOA1LmLTGpqrB0,8205
 general/utils/__init__.py,sha256=_SPe88reIZ0JxwK7mp-u_p-9c4hCcZ-daUihi0gymNk,103
 general/utils/consts.py,sha256=nE75Ud7sVuDw9K_xmIJNjL_5f_BVJmwGNPGFYc26H3Y,264
-python_general_be_lib-0.11.3.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
-python_general_be_lib-0.11.3.dist-info/METADATA,sha256=kXWrKc_wD4H6khCeqnluMKmFoD-8AopOF8m3RXISA1s,3452
-python_general_be_lib-0.11.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_general_be_lib-0.11.3.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
-python_general_be_lib-0.11.3.dist-info/RECORD,,
+python_general_be_lib-0.12.1.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
+python_general_be_lib-0.12.1.dist-info/METADATA,sha256=8T5p8u9J9MUHT1xZjRf_Ss29Y97hEeJX5wZD71aVTyI,3995
+python_general_be_lib-0.12.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_general_be_lib-0.12.1.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
+python_general_be_lib-0.12.1.dist-info/RECORD,,

{python_general_be_lib-0.11.3.dist-info → python_general_be_lib-0.12.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any