sysnet-auth 0.2.0__py3-none-any.whl

auth_lib/__init__.py

@@ -0,0 +1,74 @@
+"""
+auth_lib -- sdilena autentizacni knihovna pro FastAPI mikrosluzby s Keycloackem.
+
+Distribuce (PyPi): ``sysnet-auth``. Import: ``auth_lib``.
+Python >= 3.11 (testovano az do 3.14).
+
+Verzovani:
+    Jediny zdroj pravdy je ``version`` v ``pyproject.toml``. Runtime verze
+    se cte pres ``importlib.metadata``, aby nedochazelo k drift mezi nimi.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from auth_lib.config import AuthSettings, get_settings
+from auth_lib.dependencies import (
+    get_current_user,
+    install_exception_handlers,
+)
+from auth_lib.exceptions import (
+    AuthConfigurationError,
+    AuthError,
+    InvalidTokenError,
+    MissingRoleError,
+)
+from auth_lib.jwks import JWKSClient, get_jwks_client, reset_jwks_client
+from auth_lib.models import AuthenticatedUser
+from auth_lib.observability import (
+    clear_listeners,
+    install_sysnet_logging,
+    on_jwks_refresh,
+    on_token_rejected,
+    on_token_validated,
+    remove_listener,
+)
+from auth_lib.roles import require_all_roles, require_any_role, require_role
+
+try:
+    __version__: str = _pkg_version("sysnet-auth")
+except PackageNotFoundError:
+    # Editable checkout bez instalace (napr. v nekterych CI fazich nebo
+    # primy PYTHONPATH). Nezastavujeme import, jen signalizujeme "dev".
+    __version__ = "0.0.0+dev"
+
+__all__ = [
+    # modely a vyjimky
+    "AuthenticatedUser",
+    "AuthError",
+    "AuthConfigurationError",
+    "InvalidTokenError",
+    "MissingRoleError",
+    # konfigurace
+    "AuthSettings",
+    "get_settings",
+    # FastAPI integrace
+    "get_current_user",
+    "install_exception_handlers",
+    # role guards
+    "require_role",
+    "require_all_roles",
+    "require_any_role",
+    # JWKS
+    "JWKSClient",
+    "get_jwks_client",
+    "reset_jwks_client",
+    # observability
+    "on_token_validated",
+    "on_token_rejected",
+    "on_jwks_refresh",
+    "remove_listener",
+    "clear_listeners",
+    "install_sysnet_logging",
+    # metadata
+    "__version__",
+]

auth_lib/config.py

@@ -0,0 +1,114 @@
+"""
+Konfigurace knihovny pres environment promenne.
+
+Prefix: ``AUTH_``. Pouziva pydantic-settings (pydantic v2).
+Python >= 3.11 (testovano az 3.14).
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AuthSettings(BaseSettings):
+    """Konfigurace auth_lib."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="AUTH_",
+        env_file=None,
+        case_sensitive=False,
+        extra="ignore",
+        # Vypne implicitni JSON dekodovani env stringu u kolekci -- chceme si
+        # parsing AUTH_ALGORITHMS ridit sami (podporujeme CSV i JSON).
+        enable_decoding=False,
+    )
+
+    keycloak_url: str = Field(
+        ...,
+        description="Zakladni URL Keycloaku.",
+    )
+    realm: str = Field(
+        ...,
+        description="Nazev Keycloak realm.",
+    )
+    audience: str = Field(
+        ...,
+        description="Ocekavana hodnota aud claimu.",
+    )
+    algorithms: list[str] = Field(
+        default_factory=lambda: ["RS256"],
+        description="Povolene podepisovaci algoritmy.",
+    )
+    jwks_cache_seconds: int = Field(
+        default=300,
+        ge=1,
+        description="TTL JWKS cache v sekundach.",
+    )
+    jwks_http_timeout_seconds: float = Field(
+        default=5.0,
+        gt=0,
+        description="HTTP timeout pro fetch JWKS endpointu.",
+    )
+    leeway_seconds: int = Field(
+        default=0,
+        ge=0,
+        description="Tolerance hodin (clock skew).",
+    )
+
+    resource_client: str | None = Field(
+        default=None,
+        description=(
+            "Nepovinne: pokud je uveden, AuthenticatedUser bude obsahovat i role "
+            "z resource_access.<resource_client>.roles (Keycloak client-level role)."
+        ),
+    )
+
+    kid_miss_refresh_cooldown_seconds: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Opt-in: pokud >0, pri kid miss ve fresh JWKS cache povolime 1 refresh "
+            "za tento pocet sekund (responzivnejsi reakce na rotaci klicu v Keycloaku "
+            "s kontrolovanym DoS riskem). Default 0 = vypnuto."
+        ),
+    )
+
+    @field_validator("keycloak_url")
+    @classmethod
+    def _strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+    @field_validator("algorithms", mode="before")
+    @classmethod
+    def _parse_algorithms(cls, v: object) -> object:
+        # AUTH_ALGORITHMS=RS256,RS512  nebo  AUTH_ALGORITHMS=["RS256","RS512"]
+        if isinstance(v, str):
+            s = v.strip()
+            if s.startswith("["):
+                import json
+                try:
+                    parsed = json.loads(s)
+                    if isinstance(parsed, list):
+                        return [str(x).strip() for x in parsed if str(x).strip()]
+                except json.JSONDecodeError:
+                    pass
+            parts = [p.strip().strip('"').strip("'") for p in s.split(",")]
+            return [p for p in parts if p]
+        return v
+
+    @property
+    def issuer(self) -> str:
+        return f"{self.keycloak_url}/realms/{self.realm}"
+
+    @property
+    def jwks_url(self) -> str:
+        return f"{self.issuer}/protocol/openid-connect/certs"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> AuthSettings:
+    """Vrati cachovanou instanci settings. Reset pres get_settings.cache_clear()."""
+    return AuthSettings()  # type: ignore[call-arg]

auth_lib/dependencies.py

@@ -0,0 +1,172 @@
+"""
+FastAPI integrace.
+
+Verejne API:
+    - get_current_user -- FastAPI dependency; vrati AuthenticatedUser.
+    - install_exception_handlers -- zaregistruje handlery AuthError na app.
+
+Observability:
+    - po uspesne validaci se vola observability._emit_validated(user),
+    - pri odmitnuti tokenu observability._emit_rejected(exc).
+
+Integrace se sysnet-pyutils:
+    - install_exception_handlers pouziva ``AuthError.to_error_model()``
+      (ErrorModel z sysnet-pyutils) jako telo JSON response -- unifikovany
+      format chyb napric SYSNET sluzbami.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+from fastapi import Depends, FastAPI, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from jwt import algorithms as jwt_algorithms
+
+from auth_lib.config import AuthSettings, get_settings
+from auth_lib.exceptions import (
+    AuthConfigurationError,
+    AuthError,
+    InvalidTokenError,
+)
+from auth_lib.jwks import JWKSClient, get_jwks_client
+from auth_lib.models import AuthenticatedUser
+from auth_lib.observability import _emit_rejected, _emit_validated
+
+_bearer_scheme = HTTPBearer(auto_error=False, scheme_name="BearerAuth")
+
+
+def _jwk_to_public_key(jwk: dict[str, Any]) -> Any:
+    """Prevod JWK dict -> PyJWT-kompatibilni verejny klic."""
+    kty = jwk.get("kty")
+    if kty == "RSA":
+        return jwt_algorithms.RSAAlgorithm.from_jwk(jwk)
+    if kty == "EC":
+        return jwt_algorithms.ECAlgorithm.from_jwk(jwk)
+    if kty == "oct":
+        return jwt_algorithms.HMACAlgorithm.from_jwk(jwk)
+    raise AuthConfigurationError(f"Unsupported JWK kty: {kty!r}")
+
+
+async def _decode_token(
+    token: str,
+    *,
+    settings: AuthSettings,
+    jwks_client: JWKSClient,
+) -> dict[str, Any]:
+    try:
+        header = jwt.get_unverified_header(token)
+    except jwt.PyJWTError as exc:
+        raise InvalidTokenError(f"Malformed token header: {exc}") from exc
+
+    kid = header.get("kid")
+    if not kid:
+        raise InvalidTokenError("Token header missing 'kid'")
+
+    jwk = await jwks_client.get_key(kid)
+    public_key = _jwk_to_public_key(jwk)
+
+    try:
+        claims = jwt.decode(
+            token,
+            key=public_key,
+            algorithms=settings.algorithms,
+            audience=settings.audience,
+            issuer=settings.issuer,
+            leeway=settings.leeway_seconds,
+            options={
+                "require": ["exp", "iat", "iss", "aud", "sub"],
+                "verify_signature": True,
+                "verify_exp": True,
+                "verify_iat": True,
+                "verify_iss": True,
+                "verify_aud": True,
+            },
+        )
+    except jwt.ExpiredSignatureError as exc:
+        raise InvalidTokenError("Token has expired") from exc
+    except jwt.InvalidAudienceError as exc:
+        raise InvalidTokenError("Invalid token audience") from exc
+    except jwt.InvalidIssuerError as exc:
+        raise InvalidTokenError("Invalid token issuer") from exc
+    except jwt.InvalidSignatureError as exc:
+        raise InvalidTokenError("Invalid token signature") from exc
+    except jwt.MissingRequiredClaimError as exc:
+        raise InvalidTokenError(f"Missing required claim: {exc.claim}") from exc
+    except jwt.PyJWTError as exc:
+        raise InvalidTokenError(f"Invalid token: {exc}") from exc
+
+    return claims
+
+
+async def get_current_user(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer_scheme),
+    settings: AuthSettings = Depends(get_settings),
+) -> AuthenticatedUser:
+    """FastAPI dependency -- vrati overeneho uzivatele.
+
+    Chyby:
+        - 401 pri InvalidTokenError.
+        - 500 pri AuthConfigurationError.
+
+    Pokud settings.resource_client je nastaveny, role se mergujou z:
+        realm_access.roles + resource_access.<resource_client>.roles
+    """
+    _ = request
+
+    if credentials is None or not credentials.credentials:
+        exc = InvalidTokenError("Missing Authorization bearer token")
+        _emit_rejected(exc)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=exc.detail,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    jwks_client = await get_jwks_client()
+
+    try:
+        claims = await _decode_token(
+            credentials.credentials,
+            settings=settings,
+            jwks_client=jwks_client,
+        )
+    except AuthError as exc:
+        _emit_rejected(exc)
+        headers = {"WWW-Authenticate": "Bearer"} if exc.status_code == 401 else None
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail=exc.detail,
+            headers=headers,
+        ) from exc
+
+    user = AuthenticatedUser.from_claims(
+        claims,
+        resource_client=settings.resource_client,
+    )
+    _emit_validated(user)
+    return user
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """Zaregistruje handlery custom vyjimek.
+
+    Telo JSON odpovedi ma tvar sdileneho ``sysnet_pyutils.ErrorModel``
+    ({"code": int, "message": str}) -- konzistentni format chyb napric
+    SYSNET sluzbami.
+    """
+    from fastapi.responses import JSONResponse
+
+    async def _auth_error_handler(request: Request, exc: AuthError) -> JSONResponse:
+        _ = request
+        _emit_rejected(exc)
+        headers = {"WWW-Authenticate": "Bearer"} if exc.status_code == 401 else None
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=exc.to_error_model().model_dump(),
+            headers=headers,
+        )
+
+    app.add_exception_handler(AuthError, _auth_error_handler)  # type: ignore[arg-type]

auth_lib/exceptions.py

@@ -0,0 +1,56 @@
+"""
+Vlastni vyjimky knihovny.
+
+Integrace se sysnet-pyutils: ``AuthError.to_error_model()`` vraci
+sdileny ``sysnet_pyutils.ErrorModel`` pro konzistentni format chyb
+napric SYSNET sluzbami.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sysnet_pyutils import ErrorModel
+
+
+class AuthError(Exception):
+    """Korenova vyjimka knihovny."""
+
+    status_code: int = 500
+    default_detail: str = "Authentication error"
+
+    def __init__(self, detail: str | None = None) -> None:
+        self.detail = detail or self.default_detail
+        super().__init__(self.detail)
+
+    def to_error_model(self) -> ErrorModel:
+        """Konvertuje na sdileny SYSNET ``ErrorModel`` (code + message).
+
+        Lazy import -- pure unit testy bez sysnet-pyutils nepadnou jen
+        pri importu modulu.
+        """
+        from sysnet_pyutils import ErrorModel as _ErrorModel
+
+        return _ErrorModel(code=self.status_code, message=self.detail)
+
+
+class InvalidTokenError(AuthError):
+    """Token je neplatny -- spatny podpis, expirace, issuer, audience, format apod."""
+
+    status_code = 401
+    default_detail = "Invalid authentication token"
+
+
+class MissingRoleError(AuthError):
+    """Uzivatel je overen, ale chybi mu pozadovana role."""
+
+    status_code = 403
+    default_detail = "Insufficient permissions"
+
+
+class AuthConfigurationError(AuthError):
+    """Chybna konfigurace knihovny (chybi env, neplatny JWKS endpoint apod.)."""
+
+    status_code = 500
+    default_detail = "Authentication library misconfiguration"

auth_lib/jwks.py

@@ -0,0 +1,178 @@
+"""
+JWKS klient s async in-memory cache.
+
+Klicova rozhodnuti:
+- **Async I/O** (httpx.AsyncClient).
+- **TTL cache** s konfigurovatelnou expiraci (jwks_cache_seconds).
+- **Fresh cache je autoritativni** (bezpecne proti DoS vektoru s nahodnymi kidy).
+- **Opt-in cooldown refresh pri kid miss** (AUTH_KID_MISS_REFRESH_COOLDOWN_SECONDS)
+  -- reakce na rotaci klicu v Keycloaku pred expiraci TTL; max 1 refresh/cooldown.
+- **Single-flight lock** pod cold/stale cestou.
+- **Lazy init asyncio.Lock** -- kompat s Python 3.14, nevyzadujeme beh loopu pri
+  importu nebo konstrukci.
+- **Singleton na proces** (get_jwks_client) -- sdilena cache napric requesty.
+- **Observability hook** on_jwks_refresh(key_count) po uspesnem fetchi.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from auth_lib.config import AuthSettings, get_settings
+from auth_lib.exceptions import AuthConfigurationError, InvalidTokenError
+from auth_lib.observability import _emit_jwks_refresh
+
+
+class JWKSClient:
+    """Async klient pro JWKS endpoint s in-memory TTL cache."""
+
+    def __init__(
+        self,
+        settings: AuthSettings,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._settings = settings
+        self._external_client = http_client is not None
+        self._http_client = http_client or httpx.AsyncClient(
+            timeout=settings.jwks_http_timeout_seconds
+        )
+        self._keys_by_kid: dict[str, dict[str, Any]] = {}
+        self._expires_at: float = 0.0
+        self._last_refresh_at: float = 0.0  # pro cooldown na kid-miss refresh
+        self._lock: asyncio.Lock | None = None
+
+    @property
+    def jwks_url(self) -> str:
+        return self._settings.jwks_url
+
+    def _is_fresh(self) -> bool:
+        return bool(self._keys_by_kid) and time.monotonic() < self._expires_at
+
+    def _ensure_lock(self) -> asyncio.Lock:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        return self._lock
+
+    def _cooldown_allows_refresh(self) -> bool:
+        """Kid miss ve fresh cache -- smime zkusit refresh?
+
+        Jen kdyz je cooldown > 0 a od posledniho refreshu ubehl.
+        """
+        cooldown = self._settings.kid_miss_refresh_cooldown_seconds
+        if cooldown <= 0:
+            return False
+        return (time.monotonic() - self._last_refresh_at) >= cooldown
+
+    async def _fetch(self) -> None:
+        try:
+            resp = await self._http_client.get(self.jwks_url)
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise AuthConfigurationError(
+                f"Failed to fetch JWKS from {self.jwks_url}: {exc}"
+            ) from exc
+
+        try:
+            data = resp.json()
+            keys = data["keys"]
+            if not isinstance(keys, list):
+                raise TypeError("JWKS 'keys' is not a list")
+        except (ValueError, KeyError, TypeError) as exc:
+            raise AuthConfigurationError(
+                f"Malformed JWKS response from {self.jwks_url}: {exc}"
+            ) from exc
+
+        self._keys_by_kid = {k["kid"]: k for k in keys if "kid" in k}
+        self._expires_at = time.monotonic() + self._settings.jwks_cache_seconds
+        self._last_refresh_at = time.monotonic()
+        _emit_jwks_refresh(len(self._keys_by_kid))
+
+    async def get_key(self, kid: str) -> dict[str, Any]:
+        """Vrati JWK pro dany kid.
+
+        Logika:
+            1) Fresh cache + kid v ni -> vratime primo.
+            2) Fresh cache + kid NENI v ni:
+               - pokud cooldown povoluje, zkusime refresh pod lockem,
+               - jinak InvalidTokenError.
+            3) Stale cache -> pod lockem (double-check), fetch, pak lookup.
+        """
+        if self._is_fresh():
+            key = self._keys_by_kid.get(kid)
+            if key is not None:
+                return key
+            # Opt-in cooldown: zkusit refresh (rotace klicu pred TTL).
+            if not self._cooldown_allows_refresh():
+                raise InvalidTokenError(f"Signing key '{kid}' not found in JWKS")
+            async with self._ensure_lock():
+                # Double-check: jina korutina mohla uz refreshnout.
+                key = self._keys_by_kid.get(kid)
+                if key is not None:
+                    return key
+                if self._cooldown_allows_refresh():
+                    await self._fetch()
+                key = self._keys_by_kid.get(kid)
+                if key is None:
+                    raise InvalidTokenError(f"Signing key '{kid}' not found in JWKS")
+                return key
+
+        async with self._ensure_lock():
+            # Double-check -- jina korutina uz mohla cache naplnit.
+            if self._is_fresh():
+                key = self._keys_by_kid.get(kid)
+                if key is not None:
+                    return key
+                raise InvalidTokenError(f"Signing key '{kid}' not found in JWKS")
+
+            await self._fetch()
+
+            key = self._keys_by_kid.get(kid)
+            if key is None:
+                raise InvalidTokenError(f"Signing key '{kid}' not found in JWKS")
+            return key
+
+    async def refresh(self) -> None:
+        async with self._ensure_lock():
+            await self._fetch()
+
+    def invalidate(self) -> None:
+        self._keys_by_kid = {}
+        self._expires_at = 0.0
+
+    async def aclose(self) -> None:
+        if not self._external_client:
+            await self._http_client.aclose()
+
+
+# ------------------------------------------------------------------
+# Modulovy singleton
+# ------------------------------------------------------------------
+
+_jwks_client: JWKSClient | None = None
+_jwks_client_lock: asyncio.Lock | None = None
+
+
+async def get_jwks_client() -> JWKSClient:
+    """Vrati sdilenou instanci JWKSClient (singleton na proces)."""
+    global _jwks_client, _jwks_client_lock
+    if _jwks_client is not None:
+        return _jwks_client
+
+    if _jwks_client_lock is None:
+        _jwks_client_lock = asyncio.Lock()
+
+    async with _jwks_client_lock:
+        if _jwks_client is None:
+            _jwks_client = JWKSClient(get_settings())
+        return _jwks_client
+
+
+def reset_jwks_client() -> None:
+    """Reset singletonu - pro testy."""
+    global _jwks_client
+    _jwks_client = None

auth_lib/models.py

@@ -0,0 +1,105 @@
+"""
+Datove modely knihovny.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from sysnet_pyutils import UserType
+
+
+class AuthenticatedUser(BaseModel):
+    """Overeny uzivatel odvozeny z JWT.
+
+    Mapping claims -> atribut:
+        sub      <- sub
+        username <- preferred_username (Keycloak standard)
+        email    <- email
+        roles    <- realm_access.roles + (volitelne) resource_access.<client>.roles
+        raw      <- cely JWT payload
+
+    Konverze do sdileneho SYSNET modelu: ``to_user_type()``.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    sub: str
+    username: str | None = None
+    email: str | None = None
+    roles: list[str] = Field(default_factory=list)
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+    def has_role(self, role: str) -> bool:
+        return role in self.roles
+
+    def has_any_role(self, roles: list[str]) -> bool:
+        return any(r in self.roles for r in roles)
+
+    def has_all_roles(self, roles: list[str]) -> bool:
+        return all(r in self.roles for r in roles)
+
+    def to_user_type(self) -> UserType:
+        """Konvertuje na sdileny SYSNET model ``sysnet_pyutils.UserType``.
+
+        Mapping:
+            sub                -> identifier
+            preferred_username -> name
+            email              -> email
+            given_name         -> name_first (pokud je v claims)
+            family_name        -> name_last  (pokud je v claims)
+            name               -> name_full  (pokud je v claims)
+
+        Import `sysnet_pyutils` je lazy, aby neselhalo pouze na to_user_type()
+        v prostrredi, kde sysnet-pyutils neni dostupne (napr. v pure unit testech
+        knihovny samotne).
+        """
+        from sysnet_pyutils import UserType as _UserType
+
+        return _UserType(
+            identifier=self.sub,
+            name=self.username,
+            email=self.email,
+            name_first=self.raw.get("given_name"),
+            name_last=self.raw.get("family_name"),
+            name_full=self.raw.get("name"),
+        )
+
+    @classmethod
+    def from_claims(
+        cls,
+        claims: dict[str, Any],
+        *,
+        resource_client: str | None = None,
+    ) -> AuthenticatedUser:
+        """Poskladaji uzivatele z validovanych claimu."""
+        realm_roles: list[str] = []
+        realm_access = claims.get("realm_access") or {}
+        if isinstance(realm_access, dict):
+            realm_roles = list(realm_access.get("roles") or [])
+
+        client_roles: list[str] = []
+        if resource_client:
+            resource_access = claims.get("resource_access") or {}
+            if isinstance(resource_access, dict):
+                client_block = resource_access.get(resource_client) or {}
+                if isinstance(client_block, dict):
+                    client_roles = list(client_block.get("roles") or [])
+
+        seen: set[str] = set()
+        merged_roles: list[str] = []
+        for r in [*realm_roles, *client_roles]:
+            if r not in seen:
+                seen.add(r)
+                merged_roles.append(r)
+
+        return cls(
+            sub=str(claims["sub"]),
+            username=claims.get("preferred_username"),
+            email=claims.get("email"),
+            roles=merged_roles,
+            raw=claims,
+        )

auth_lib/observability.py

@@ -0,0 +1,128 @@
+"""
+Observability hooks.
+
+Knihovna sama nezna konkretni logging/metrics backend -- vystavuje
+jednoduchy registr callbacku, ktery si konzument zaregistruje podle
+svych potreb (Prometheus, OpenTelemetry, strukturovany log atd.).
+
+Pripravena integrace se sysnet-pyutils: ``install_sysnet_logging()``
+zaregistruje default hooky, ktere logji pres ``sysnet_pyutils.Log``
+(singleton logger sdileny napric SYSNET sluzbami).
+
+Garance:
+    - Hook volani je synchronni a best-effort -- vyjimka v hooku NIKDY
+      neprerusi validaci tokenu (knihovna ji poznamena do _HOOK_ERRORS).
+    - Poradi volani odpovida poradi registrace.
+    - Hook se da odregistrovat (remove_listener).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from auth_lib.models import AuthenticatedUser
+
+ValidatedHook = Callable[["AuthenticatedUser"], None]
+RejectedHook = Callable[[BaseException], None]
+JWKSRefreshHook = Callable[[int], None]
+
+_on_validated: list[ValidatedHook] = []
+_on_rejected: list[RejectedHook] = []
+_on_jwks_refresh: list[JWKSRefreshHook] = []
+_HOOK_ERRORS: list[BaseException] = []
+
+
+def on_token_validated(fn: ValidatedHook) -> ValidatedHook:
+    """Zaregistruje callback po uspesne validaci tokenu."""
+    _on_validated.append(fn)
+    return fn
+
+
+def on_token_rejected(fn: RejectedHook) -> RejectedHook:
+    """Zaregistruje callback pri odmitnuti tokenu."""
+    _on_rejected.append(fn)
+    return fn
+
+
+def on_jwks_refresh(fn: JWKSRefreshHook) -> JWKSRefreshHook:
+    """Zaregistruje callback po uspesnem JWKS refreshi."""
+    _on_jwks_refresh.append(fn)
+    return fn
+
+
+def remove_listener(fn: Callable[..., None]) -> None:
+    """Odebere callback ze vsech registru."""
+    for registry in (_on_validated, _on_rejected, _on_jwks_refresh):
+        if fn in registry:
+            registry.remove(fn)  # type: ignore[arg-type]
+
+
+def clear_listeners() -> None:
+    """Smaze vsechny registry (pro testy)."""
+    _on_validated.clear()
+    _on_rejected.clear()
+    _on_jwks_refresh.clear()
+    _HOOK_ERRORS.clear()
+
+
+def install_sysnet_logging() -> None:
+    """Napoji default logovaci hooky na sdileny SYSNET ``Log`` singleton.
+
+    Po zavolani bude knihovna logovat:
+        - INFO pri uspesne validaci (sub + pocet roli),
+        - WARNING pri odmitnuti tokenu (typ vyjimky + detail),
+        - INFO po JWKS refreshi (pocet klicu).
+
+    Volat typicky pri startu aplikace. Hooky jsou idempotentne pridane --
+    druhe volani neregistrace stejne hooky znovu (chrani pres atribut).
+    """
+    from sysnet_pyutils import Log
+
+    logger = Log().logger
+
+    def _on_ok(user: "AuthenticatedUser") -> None:
+        logger.info("auth_lib: token validated (sub=%s, roles=%d)", user.sub, len(user.roles))
+
+    def _on_err(exc: BaseException) -> None:
+        logger.warning("auth_lib: token rejected (%s): %s", type(exc).__name__, exc)
+
+    def _on_refresh(n: int) -> None:
+        logger.info("auth_lib: JWKS refreshed (keys=%d)", n)
+
+    # Idempotentni -- pokud uz jsou nase hooky zaregistrovane, nepridavat zas.
+    if not any(getattr(h, "_auth_lib_sysnet", False) for h in _on_validated):
+        _on_ok._auth_lib_sysnet = True  # type: ignore[attr-defined]
+        _on_err._auth_lib_sysnet = True  # type: ignore[attr-defined]
+        _on_refresh._auth_lib_sysnet = True  # type: ignore[attr-defined]
+        _on_validated.append(_on_ok)
+        _on_rejected.append(_on_err)
+        _on_jwks_refresh.append(_on_refresh)
+
+
+# ----- interni emitery (vola knihovna) --------------------------------
+
+
+def _emit_validated(user: "AuthenticatedUser") -> None:
+    for h in list(_on_validated):
+        try:
+            h(user)
+        except BaseException as exc:  # noqa: BLE001
+            _HOOK_ERRORS.append(exc)
+
+
+def _emit_rejected(exc: BaseException) -> None:
+    for h in list(_on_rejected):
+        try:
+            h(exc)
+        except BaseException as e:  # noqa: BLE001
+            _HOOK_ERRORS.append(e)
+
+
+def _emit_jwks_refresh(key_count: int) -> None:
+    for h in list(_on_jwks_refresh):
+        try:
+            h(key_count)
+        except BaseException as exc:  # noqa: BLE001
+            _HOOK_ERRORS.append(exc)

auth_lib/roles.py

@@ -0,0 +1,83 @@
+"""
+Role guards jako factory funkce pro FastAPI Depends.
+
+Design:
+    Knihovna vrací **dependency callable** (ne dekorátor na endpoint).
+    To je idiomatické pro FastAPI a umožňuje kompozici:
+
+        @app.get("/admin")
+        def only_admin(user = Depends(require_role("admin"))): ...
+
+    Výsledná dependency vrací ``AuthenticatedUser`` — můžeš tedy pokračovat
+    v handleru se jmenným přístupem (např. ``user.email``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+
+from fastapi import Depends, HTTPException
+
+from auth_lib.dependencies import get_current_user
+from auth_lib.exceptions import MissingRoleError
+from auth_lib.models import AuthenticatedUser
+
+RoleGuard = Callable[..., Awaitable[AuthenticatedUser]]
+
+
+def require_role(role: str) -> RoleGuard:
+    """Vyžádá, aby uživatel měl danou roli.
+
+    Vrací FastAPI dependency, která:
+        - vyhodí 401, pokud token chybí/nevalidní (přes ``get_current_user``),
+        - vyhodí 403, pokud role chybí,
+        - jinak vrátí ``AuthenticatedUser``.
+    """
+
+    async def _guard(
+        user: AuthenticatedUser = Depends(get_current_user),
+    ) -> AuthenticatedUser:
+        if not user.has_role(role):
+            # Konzistentní s dependencies.py: v dependency mapujeme sami.
+            raise HTTPException(
+                status_code=MissingRoleError.status_code,
+                detail=f"Missing required role: '{role}'",
+            )
+        return user
+
+    return _guard
+
+
+def require_any_role(roles: Sequence[str]) -> RoleGuard:
+    """Vyžádá alespoň jednu z uvedených rolí (OR)."""
+    required = list(roles)
+
+    async def _guard(
+        user: AuthenticatedUser = Depends(get_current_user),
+    ) -> AuthenticatedUser:
+        if not user.has_any_role(required):
+            raise HTTPException(
+                status_code=MissingRoleError.status_code,
+                detail=f"Missing any of required roles: {required}",
+            )
+        return user
+
+    return _guard
+
+
+def require_all_roles(roles: Sequence[str]) -> RoleGuard:
+    """Vyžádá všechny uvedené role (AND)."""
+    required = list(roles)
+
+    async def _guard(
+        user: AuthenticatedUser = Depends(get_current_user),
+    ) -> AuthenticatedUser:
+        if not user.has_all_roles(required):
+            missing = [r for r in required if r not in user.roles]
+            raise HTTPException(
+                status_code=MissingRoleError.status_code,
+                detail=f"Missing required roles: {missing}",
+            )
+        return user
+
+    return _guard

sysnet_auth-0.2.0.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: sysnet-auth
+Version: 0.2.0
+Summary: Sdilena autentizacni knihovna pro FastAPI mikrosluzby s Keycloack (OIDC/JWT).
+Author: SYSNET s.r.o.
+License: Proprietary
+Project-URL: Homepage, https://sysnet.cz
+Keywords: fastapi,keycloak,jwt,oidc,auth,sysnet
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pyjwt[crypto]>=2.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: sysnet-pyutils>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: cryptography>=42.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# sysnet-auth (import path: `auth_lib`)
+
+Sdílená autentizační knihovna pro FastAPI mikroslužby, které ověřují identitu uživatelů přes **Keycloak** (OIDC / JWT). Součást SYSNET ekosystému.
+
+Knihovna je záměrně úzká: neobsahuje business logiku, neukládá stav a nepřeposílá tokeny. Jediná zodpovědnost je **validace JWT** a vystavení objektu `AuthenticatedUser` dependency injection mechanismem FastAPI.
+
+---
+
+## Proč existuje
+
+V architektuře desítek mikroslužeb nechceme, aby každá z nich měla vlastní implementaci validace JWT. Rozkol v drobných detailech (kontrola audience, leeway, cachování JWKS) je snadný způsob, jak vyrobit bezpečnostní díru. `auth_lib` je **jediné místo, kde se validuje identita uživatele** — a všechny služby ji používají stejně.
+
+---
+
+## Instalace
+
+Balíček je publikovaný jako **`sysnet-auth`**, importuje se jako **`auth_lib`**
+(běžný pattern: distribuční jméno ≠ import jméno).
+
+```bash
+pip install sysnet-auth
+```
+
+```python
+from auth_lib import get_current_user, require_role
+```
+
+### Python
+
+Vyžaduje **Python ≥ 3.11**, plně testováno proti **3.11 – 3.14**.
+
+### Runtime závislosti
+
+| Balíček             | Role                                           |
+|---------------------|------------------------------------------------|
+| `fastapi`           | DI / exception handlery                        |
+| `pydantic` v2       | modely, validace                               |
+| `pydantic-settings` | konfigurace přes env                           |
+| `pyjwt[crypto]`     | dekódování + validace JWT                      |
+| `httpx`             | async HTTP klient pro JWKS endpoint            |
+| `sysnet-pyutils`    | sdílené SYSNET modely (`UserType`, `ErrorModel`, `Log`) |
+
+> **Volba JWT knihovny.** `python-jose` je od 2021 neudržovaný. Používáme **PyJWT** — aktivně udržovaný de facto standard pro JWT v Pythonu.
+
+---
+
+## Konfigurace
+
+Všechno přes environment proměnné s prefixem `AUTH_`. Pydantic-settings načte settings při prvním volání `get_settings()` a cachuje je na proces.
+
+| Proměnná                            | Default      | Popis |
+|-------------------------------------|--------------|-------|
+| `AUTH_KEYCLOAK_URL`                 | —            | Základní URL Keycloaku (`https://kc.example.cz`) |
+| `AUTH_REALM`                        | —            | Název Keycloak realm |
+| `AUTH_AUDIENCE`                     | —            | Očekávaný `aud` claim (typicky `client_id` API) |
+| `AUTH_ALGORITHMS`                   | `["RS256"]`  | Povolené podpisové algoritmy (CSV nebo JSON) |
+| `AUTH_JWKS_CACHE_SECONDS`           | `300`        | TTL JWKS cache |
+| `AUTH_JWKS_HTTP_TIMEOUT_SECONDS`    | `5.0`        | HTTP timeout pro fetch JWKS |
+| `AUTH_LEEWAY_SECONDS`               | `0`          | Tolerance hodinového rozdílu (clock skew) |
+| `AUTH_RESOURCE_CLIENT`              | `None`       | Pokud nastaveno, mergne i `resource_access.<klient>.roles` |
+| `AUTH_KID_MISS_REFRESH_COOLDOWN_SECONDS` | `0`     | Opt-in: refresh při neznámém `kid` 1× za N sekund |
+
+### Odvozené hodnoty
+
+- **Issuer:** `{AUTH_KEYCLOAK_URL}/realms/{AUTH_REALM}`
+- **JWKS URL:** `{issuer}/protocol/openid-connect/certs`
+
+---
+
+## Použití ve FastAPI
+
+### Ověřený uživatel
+
+```python
+from fastapi import Depends, FastAPI
+from auth_lib import AuthenticatedUser, get_current_user, install_exception_handlers
+
+app = FastAPI()
+install_exception_handlers(app)
+
+@app.get("/me")
+async def me(user: AuthenticatedUser = Depends(get_current_user)) -> AuthenticatedUser:
+    return user
+```
+
+### Role guard
+
+```python
+from auth_lib import require_role, require_any_role, require_all_roles
+
+@app.delete("/users/{id}")
+async def delete_user(
+    id: str,
+    user: AuthenticatedUser = Depends(require_role("admin")),
+):
+    ...
+
+@app.get("/content")
+async def list_content(
+    user: AuthenticatedUser = Depends(require_any_role(["editor", "viewer"])),
+):
+    ...
+```
+
+### Konverze do SYSNET `UserType`
+
+```python
+from auth_lib import get_current_user
+
+@app.get("/user-profile")
+async def profile(user = Depends(get_current_user)):
+    sysnet_user = user.to_user_type()   # sysnet_pyutils.UserType
+    return sysnet_user
+```
+
+Mapping: `sub → identifier`, `preferred_username → name`, `email → email`, `given_name → name_first`, `family_name → name_last`, `name → name_full`.
+
+---
+
+## Observability
+
+Knihovna neví, co je Prometheus / OpenTelemetry / strukturovaný log. Místo toho exponuje **pub-sub hooky**, které si konzument zaregistruje:
+
+```python
+from auth_lib import on_token_validated, on_token_rejected, on_jwks_refresh
+
+@on_token_validated
+def _ok(user):
+    metrics.incr("auth.ok", tags={"sub": user.sub})
+
+@on_token_rejected
+def _err(exc):
+    metrics.incr("auth.err", tags={"type": type(exc).__name__})
+
+@on_jwks_refresh
+def _jwks(n):
+    metrics.gauge("auth.jwks.keys", n)
+```
+
+Výjimka v hooku **nikdy neshodí validaci** (hooky jsou best-effort).
+
+### Rychlé zapnutí přes SYSNET logger
+
+```python
+from auth_lib import install_sysnet_logging
+install_sysnet_logging()  # zapíše INFO/WARNING přes sysnet_pyutils.Log
+```
+
+Idempotentní — druhé volání už hooky znovu neregistruje.
+
+---
+
+## Výjimky
+
+| Výjimka                  | HTTP | Kdy                                                     |
+|--------------------------|------|---------------------------------------------------------|
+| `InvalidTokenError`      | 401  | špatný podpis, expirace, `iss`, `aud`, neznámý `kid`, … |
+| `MissingRoleError`       | 403  | uživatel je ověřen, ale chybí mu role                   |
+| `AuthConfigurationError` | 500  | nedostupný JWKS, špatné URL, malformed response         |
+
+Všechny dědí z `AuthError`.
+
+`install_exception_handlers(app)` registruje handler, který vrací **`sysnet_pyutils.ErrorModel`**:
+
+```json
+{"code": 401, "message": "Token has expired"}
+```
+
+Jednotný formát chyb napříč SYSNET službami.
+
+---
+
+## JWKS caching
+
+- In-memory TTL cache (default 300 s).
+- Lazy fetch při prvním volání.
+- **Single-flight:** souběh N requestů při cold/expired cache spustí právě jeden fetch.
+- **Fresh cache je autoritativní** — kid miss = `InvalidTokenError`. Brání DoS přes náhodné kidy.
+- **Opt-in cooldown refresh** (`AUTH_KID_MISS_REFRESH_COOLDOWN_SECONDS > 0`): při kid miss ve fresh cache povolí 1 refresh za N sekund — responzivnější reakce na rotaci klíčů.
+- Lazy init `asyncio.Lock` — kompatibilní s Pythonem 3.14 (neváže lock na event loop z doby importu).
+- Žádný background task, žádný disk.
+
+---
+
+## Bezpečnostní poznámky
+
+- Ověřujeme vždy **podpis, issuer i audience**.
+- Výchozí `leeway=0`. Zapnout jen při doloženém clock skew.
+- Pouze `RS256` výchozí, `none` ani HS256 nepovolujeme bez dobrého důvodu.
+- Čteme **pouze `Authorization: Bearer`** (žádné cookies, žádné `X-*` hlavičky).
+- Tokeny se nelogují. Diagnostika přes `sub` / `jti`.
+- JWKS fetch má timeout → nedostupný Keycloak vrátí 500, ne čekání donekonečna.
+
+---
+
+## Struktura projektu
+
+```
+auth_lib/
+├── auth_lib/
+│   ├── __init__.py          # veřejné re-exporty (__all__)
+│   ├── config.py            # AuthSettings
+│   ├── exceptions.py        # AuthError + to_error_model()
+│   ├── models.py            # AuthenticatedUser + to_user_type()
+│   ├── jwks.py              # async JWKS cache + cooldown
+│   ├── dependencies.py      # get_current_user, install_exception_handlers
+│   ├── roles.py             # require_role / require_any_role / require_all_roles
+│   ├── observability.py     # hook registry + install_sysnet_logging()
+│   └── py.typed             # PEP 561 marker
+├── tests/
+├── pyproject.toml           # sysnet-auth, Python 3.11-3.14
+├── CHANGELOG.md
+├── README.md
+└── .gitignore
+```
+
+---
+
+## Testování
+
+```bash
+pip install -e ".[dev]"
+pytest --cov=auth_lib --cov-report=term-missing
+```
+
+Testy nevolají reálný Keycloak — používají vlastní RSA keypair a JWKS cache předvyplněnou odpovídajícím JWK. **58 testů, 98 % pokrytí.**
+
+---
+
+## Architektonický princip
+
+> **Tato knihovna je jediným místem, kde se řeší validace identity uživatele.**
+
+Všechny FastAPI mikroslužby ji používají jednotným způsobem. Pokud narazíš na potřebu obejít `auth_lib` (vlastní dekódování, custom validace), je to signál k úpravě `auth_lib` — ne k duplikaci logiky.

sysnet_auth-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+auth_lib/__init__.py,sha256=OstwolcHEFMatcb7xYepeZ0ivo1i1UmX3j4Tjn4GiJA,1999
+auth_lib/config.py,sha256=hNxcb4Hd2QTe-eU0HOgLbwq3GKp_MBS6vP_X5FGnhU0,3453
+auth_lib/dependencies.py,sha256=Q05mW9qXliynKJ5WdQRIMLtoEuZqpZux4Q3FLf8aqjo,5668
+auth_lib/exceptions.py,sha256=r6kbuL0NLskp4WGz4mUkwSaumqegjAbLg5p298jDzO4,1558
+auth_lib/jwks.py,sha256=eA4kF8gtUuObRfaEjpl3h6jBsrrMkymqEUZD01YSdgM,6295
+auth_lib/models.py,sha256=57Pb1B5dEdNFc2qZIopSX5uDE1ZAGDDKi7wpSG9AeBw,3366
+auth_lib/observability.py,sha256=s6Qp6V3iP3IIY3FTrGiHVB9aTf4PueMCKLxkTozEYec,4191
+auth_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auth_lib/roles.py,sha256=twsDLSC7LCeX7Qj7d5DomjHRkyxx97QagBCSoGdhpRA,2610
+sysnet_auth-0.2.0.dist-info/METADATA,sha256=-91qqgwut_nJd-noCrEhKTBJWr2D95CCUZm48m1mAHM,9748
+sysnet_auth-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sysnet_auth-0.2.0.dist-info/top_level.txt,sha256=c4jUulZJz9nOnFobWPvTXkBhWqMB01IW8gecZnRI0Lg,9
+sysnet_auth-0.2.0.dist-info/RECORD,,

sysnet_auth-0.2.0.dist-info/WHEEL

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

sysnet_auth-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auth_lib