pkg-auth 3.2.0__tar.gz → 3.3.0__tar.gz

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.2.0
+Version: 3.3.0
 Summary: Clean-architecture auth core for multiple Python frameworks
 Author-email: Fritill <info@fritill.ae>
 License: MIT
@@ -123,6 +123,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 ## Features
 
 - **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Service token** — a service's own Keycloak token (client credentials), cached and refreshed, for calling other services.
 - **Authorization (ACL)** — database-backed users, organizations, roles, permissions, and memberships, resolved into a hot-path `AuthContext` (`role_names`, `perms`).
 - **Permission visibility** — tri-state catalog visibility (`platform_only` / `shared` / `tenant_only`).
 - **Localized descriptions** — permission descriptions stored as localized JSONB (`LocalizedText`, `ACL_DEFAULT_LOCALE`).
@@ -135,7 +136,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 
 ```
 pkg_auth/
-  authentication/             JWT validation → IdentityContext (identity only)
+  authentication/             JWT validation → IdentityContext; the service's own token
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
     application/use_cases/    Business logic (use cases)
@@ -160,5 +161,6 @@ pkg_auth/
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
+- [Service Token](docs/Service-Token.md) — call another service as this service
 - [Keycloak Admin](docs/Keycloak-Admin.md)
 - [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/README.md

@@ -75,6 +75,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 ## Features
 
 - **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Service token** — a service's own Keycloak token (client credentials), cached and refreshed, for calling other services.
 - **Authorization (ACL)** — database-backed users, organizations, roles, permissions, and memberships, resolved into a hot-path `AuthContext` (`role_names`, `perms`).
 - **Permission visibility** — tri-state catalog visibility (`platform_only` / `shared` / `tenant_only`).
 - **Localized descriptions** — permission descriptions stored as localized JSONB (`LocalizedText`, `ACL_DEFAULT_LOCALE`).
@@ -87,7 +88,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 
 ```
 pkg_auth/
-  authentication/             JWT validation → IdentityContext (identity only)
+  authentication/             JWT validation → IdentityContext; the service's own token
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
     application/use_cases/    Business logic (use cases)
@@ -112,5 +113,6 @@ pkg_auth/
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
+- [Service Token](docs/Service-Token.md) — call another service as this service
 - [Keycloak Admin](docs/Keycloak-Admin.md)
 - [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pkg-auth"
-version = "3.2.0"
+version = "3.3.0"
 description = "Clean-architecture auth core for multiple Python frameworks"
 readme = "README.md"
 requires-python = ">=3.10"

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/src/pkg_auth/authentication/__init__.py

@@ -6,7 +6,7 @@ Public API:
     Subject, EmailAddress, RealmName  — identity value objects
     TokenDecoder                — Protocol port for token verification
     AuthenticateTokenUseCase    — token → IdentityContext
-    AuthenticationError, TokenExpiredError, InvalidTokenError
+    AuthenticationError, TokenExpiredError, InvalidTokenError, ServiceTokenError
 """
 from __future__ import annotations
 
@@ -15,6 +15,7 @@ from .domain.entities import IdentityContext
 from .domain.exceptions import (
     AuthenticationError,
     InvalidTokenError,
+    ServiceTokenError,
     TokenExpiredError,
 )
 from .domain.ports import TokenDecoder
@@ -30,4 +31,5 @@ __all__ = [
     "AuthenticationError",
     "TokenExpiredError",
     "InvalidTokenError",
+    "ServiceTokenError",
 ]

pkg_auth-3.3.0/src/pkg_auth/authentication/adapters/keycloak/__init__.py

@@ -0,0 +1,12 @@
+"""Keycloak adapters: JWT verification and this service's own token."""
+from __future__ import annotations
+
+from .jwt_decoder import JWTTokenDecoder
+from .service_token import ServiceCredentials, ServiceTokenAuth, ServiceTokenProvider
+
+__all__ = [
+    "JWTTokenDecoder",
+    "ServiceCredentials",
+    "ServiceTokenAuth",
+    "ServiceTokenProvider",
+]

pkg_auth-3.3.0/src/pkg_auth/authentication/adapters/keycloak/service_token.py

@@ -0,0 +1,210 @@
+"""This service's own Keycloak token (client-credentials grant), for calling other services."""
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, AsyncGenerator, Callable, Generator, Mapping, Optional, Tuple
+
+import httpx
+
+from ...domain.exceptions import ServiceTokenError
+
+_ENV_NAMES = (
+    "KEYCLOAK_BASE_URL",
+    "KEYCLOAK_REALM",
+    "KEYCLOAK_CLIENT_ID",
+    "KEYCLOAK_CLIENT_SECRET",
+)
+
+
+@dataclass(frozen=True)
+class ServiceCredentials:
+    """Where and as whom a service asks Keycloak for its own token."""
+
+    token_url: str
+    client_id: str
+    client_secret: str = field(repr=False)
+
+    @classmethod
+    def for_realm(
+        cls, *, base_url: str, realm: str, client_id: str, client_secret: str
+    ) -> "ServiceCredentials":
+        token_url = f"{base_url.rstrip('/')}/realms/{realm}/protocol/openid-connect/token"
+        return cls(token_url=token_url, client_id=client_id, client_secret=client_secret)
+
+    @classmethod
+    def from_env(cls, environ: Optional[Mapping[str, str]] = None) -> "ServiceCredentials":
+        """Read ``KEYCLOAK_BASE_URL``, ``KEYCLOAK_REALM``, ``KEYCLOAK_CLIENT_ID``
+        and ``KEYCLOAK_CLIENT_SECRET``; raise ``ValueError`` naming every one unset."""
+        env = os.environ if environ is None else environ
+        values = {name: (env.get(name) or "").strip() for name in _ENV_NAMES}
+        missing = [name for name, value in values.items() if not value]
+        if missing:
+            raise ValueError(f"service token needs {', '.join(missing)}")
+        return cls.for_realm(
+            base_url=values["KEYCLOAK_BASE_URL"],
+            realm=values["KEYCLOAK_REALM"],
+            client_id=values["KEYCLOAK_CLIENT_ID"],
+            client_secret=values["KEYCLOAK_CLIENT_SECRET"],
+        )
+
+
+class ServiceTokenProvider:
+    """Fetches, caches and refreshes this service's token.
+
+    One instance per process, shared by sync and async callers. A cached
+    token is reused until ``refresh_margin_seconds`` before it expires (or
+    half its lifetime, for tokens shorter than twice the margin), so a call
+    never goes out with a token that dies in flight.
+    """
+
+    def __init__(
+        self,
+        credentials: ServiceCredentials,
+        *,
+        refresh_margin_seconds: float = 30.0,
+        timeout_seconds: float = 10.0,
+        clock: Callable[[], float] = time.monotonic,
+        transport: Optional[httpx.BaseTransport] = None,
+        async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self._credentials = credentials
+        self._margin = refresh_margin_seconds
+        self._timeout = timeout_seconds
+        self._clock = clock
+        self._transport = transport
+        self._async_transport = async_transport
+
+        self._token: Optional[str] = None
+        self._refresh_at = 0.0
+        self._sync_lock = threading.Lock()
+        self._async_lock: Optional[asyncio.Lock] = None
+
+    @classmethod
+    def from_env(
+        cls, environ: Optional[Mapping[str, str]] = None, **kwargs: Any
+    ) -> "ServiceTokenProvider":
+        return cls(ServiceCredentials.from_env(environ), **kwargs)
+
+    @property
+    def client_id(self) -> str:
+        return self._credentials.client_id
+
+    def get_token(self) -> str:
+        token = self._cached()
+        if token is not None:
+            return token
+        with self._sync_lock:
+            token = self._cached()
+            if token is not None:
+                return token
+            with httpx.Client(timeout=self._timeout, transport=self._transport) as client:
+                try:
+                    response = client.post(**self._request())
+                except httpx.HTTPError as exc:
+                    raise self._unreachable(exc) from exc
+            return self._store(response)
+
+    async def aget_token(self) -> str:
+        token = self._cached()
+        if token is not None:
+            return token
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        async with self._async_lock:
+            token = self._cached()
+            if token is not None:
+                return token
+            async with httpx.AsyncClient(
+                timeout=self._timeout, transport=self._async_transport
+            ) as client:
+                try:
+                    response = await client.post(**self._request())
+                except httpx.HTTPError as exc:
+                    raise self._unreachable(exc) from exc
+            return self._store(response)
+
+    def invalidate(self) -> None:
+        """Drop the cached token; the next call fetches a new one."""
+        self._token = None
+        self._refresh_at = 0.0
+
+    def _cached(self) -> Optional[str]:
+        token = self._token
+        if token is not None and self._clock() < self._refresh_at:
+            return token
+        return None
+
+    def _request(self) -> dict[str, Any]:
+        return {
+            "url": self._credentials.token_url,
+            "data": {
+                "grant_type": "client_credentials",
+                "client_id": self._credentials.client_id,
+                "client_secret": self._credentials.client_secret,
+            },
+        }
+
+    def _unreachable(self, exc: Exception) -> ServiceTokenError:
+        return ServiceTokenError(
+            f"could not reach Keycloak for client {self._credentials.client_id!r}: {exc}"
+        )
+
+    def _store(self, response: httpx.Response) -> str:
+        token, expires_in = self._parse(response)
+        lifetime = max(float(expires_in), 0.0)
+        self._token = token
+        self._refresh_at = self._clock() + lifetime - min(self._margin, lifetime / 2)
+        return token
+
+    def _parse(self, response: httpx.Response) -> Tuple[str, Any]:
+        client_id = self._credentials.client_id
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if not isinstance(body, dict):
+            body = {}
+        if response.status_code != 200:
+            reason = body.get("error_description") or body.get("error") or response.text[:200]
+            raise ServiceTokenError(
+                f"Keycloak refused a token for client {client_id!r}: "
+                f"HTTP {response.status_code} {reason}"
+            )
+        token = body.get("access_token")
+        if not isinstance(token, str) or not token:
+            raise ServiceTokenError(f"Keycloak returned no access_token for client {client_id!r}")
+        return token, body.get("expires_in", 60)
+
+
+class ServiceTokenAuth(httpx.Auth):
+    """``httpx`` auth that sends the service token and, on a 401, fetches a
+    fresh one and retries once (the cached token may have been revoked)."""
+
+    requires_request_body = True
+
+    def __init__(self, provider: ServiceTokenProvider) -> None:
+        self._provider = provider
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._provider.get_token()}"
+        response = yield request
+        if response.status_code == 401:
+            self._provider.invalidate()
+            request.headers["Authorization"] = f"Bearer {self._provider.get_token()}"
+            yield request
+
+    async def async_auth_flow(
+        self, request: httpx.Request
+    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        request.headers["Authorization"] = f"Bearer {await self._provider.aget_token()}"
+        response = yield request
+        if response.status_code == 401:
+            self._provider.invalidate()
+            request.headers["Authorization"] = f"Bearer {await self._provider.aget_token()}"
+            yield request

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/src/pkg_auth/authentication/domain/exceptions.py

@@ -16,3 +16,7 @@ class TokenExpiredError(AuthenticationError):
 
 class InvalidTokenError(AuthenticationError):
     """Token is malformed, has an invalid signature, or fails verification."""
+
+
+class ServiceTokenError(AuthenticationError):
+    """Keycloak did not issue this service's own (client-credentials) token."""

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/src/pkg_auth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.2.0
+Version: 3.3.0
 Summary: Clean-architecture auth core for multiple Python frameworks
 Author-email: Fritill <info@fritill.ae>
 License: MIT
@@ -123,6 +123,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 ## Features
 
 - **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Service token** — a service's own Keycloak token (client credentials), cached and refreshed, for calling other services.
 - **Authorization (ACL)** — database-backed users, organizations, roles, permissions, and memberships, resolved into a hot-path `AuthContext` (`role_names`, `perms`).
 - **Permission visibility** — tri-state catalog visibility (`platform_only` / `shared` / `tenant_only`).
 - **Localized descriptions** — permission descriptions stored as localized JSONB (`LocalizedText`, `ACL_DEFAULT_LOCALE`).
@@ -135,7 +136,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 
 ```
 pkg_auth/
-  authentication/             JWT validation → IdentityContext (identity only)
+  authentication/             JWT validation → IdentityContext; the service's own token
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
     application/use_cases/    Business logic (use cases)
@@ -160,5 +161,6 @@ pkg_auth/
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
+- [Service Token](docs/Service-Token.md) — call another service as this service
 - [Keycloak Admin](docs/Keycloak-Admin.md)
 - [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.2.0 → pkg_auth-3.3.0}/src/pkg_auth.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ src/pkg_auth/authentication/__init__.py
 src/pkg_auth/authentication/adapters/__init__.py
 src/pkg_auth/authentication/adapters/keycloak/__init__.py
 src/pkg_auth/authentication/adapters/keycloak/jwt_decoder.py
+src/pkg_auth/authentication/adapters/keycloak/service_token.py
 src/pkg_auth/authentication/application/__init__.py
 src/pkg_auth/authentication/application/use_cases/__init__.py
 src/pkg_auth/authentication/application/use_cases/authenticate.py

pkg_auth-3.2.0/src/pkg_auth/authentication/adapters/keycloak/__init__.py

@@ -1,6 +0,0 @@
-"""Keycloak JWT decoder adapter."""
-from __future__ import annotations
-
-from .jwt_decoder import JWTTokenDecoder
-
-__all__ = ["JWTTokenDecoder"]