pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/admin/helpers.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import KeycloakAdminClient
+
+
+async def _ensure_api_client(
+    kc: KeycloakAdminClient,
+    *,
+    api_client_id: str,
+) -> tuple[dict[str, Any], str]:
+    client_repr = {
+        "clientId": api_client_id,
+        "protocol": "openid-connect",
+        "publicClient": False,
+        "bearerOnly": True,
+        "standardFlowEnabled": False,
+        "implicitFlowEnabled": False,
+        "directAccessGrantsEnabled": False,
+        "serviceAccountsEnabled": False,
+        "enabled": True,
+    }
+    ensured = await kc.ensure_client(client_repr)
+
+    server_obj = await kc.get_client_by_client_id(api_client_id)
+    if not server_obj:
+        raise RuntimeError("Client ensure failed unexpectedly: cannot read back the client")
+
+    return ensured, server_obj["id"]  # (trimmed, internal_id)
+
+
+async def _ensure_roles(
+    kc: KeycloakAdminClient,
+    *,
+    internal_id: str,
+    permissions: list[str],
+    strict_roles: bool,
+) -> dict[str, int]:
+    if strict_roles:
+        return await kc.ensure_client_roles_strict(internal_id, permissions)
+    return await kc.ensure_client_roles(internal_id, permissions)
+
+
+async def _ensure_frontend_mappers(
+    kc: KeycloakAdminClient,
+    *,
+    api_client_id: str,
+    internal_api_id: str,
+    frontend_client_ids: list[str],
+    strict_audience: bool,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    audience_actions: list[dict[str, Any]] = []
+    roles_mapper_actions: list[dict[str, Any]] = []
+
+    for fe_client_id in frontend_client_ids:
+        fe = await kc.get_client_by_client_id(fe_client_id)
+        if not fe:
+            msg = f"frontend client not found in realm {kc.s.keycloak_realm}"
+            audience_actions.append(
+                {"frontend_client": fe_client_id, "created": False, "updated": False, "error": msg}
+            )
+            roles_mapper_actions.append(
+                {"frontend_client": fe_client_id, "created": False, "updated": False, "error": msg}
+            )
+            continue
+
+        res_aud = await kc.ensure_audience_mapper(
+            fe["id"],
+            api_client_id,
+            update_if_different=strict_audience,
+        )
+        audience_actions.append({"frontend_client": fe_client_id, **res_aud})
+
+        res_roles = await kc.ensure_client_roles_mapper(
+            fe["id"],
+            api_client_id,
+            update_if_different=strict_audience,
+        )
+        roles_mapper_actions.append({"frontend_client": fe_client_id, **res_roles})
+
+    return audience_actions, roles_mapper_actions
+
+
+async def _remove_frontend_mappers(
+    kc: KeycloakAdminClient,
+    *,
+    api_client_id: str,
+    remove_frontend_client_ids: list[str],
+) -> list[dict[str, Any]]:
+    removed: list[dict[str, Any]] = []
+    for fe_client_id in remove_frontend_client_ids:
+        fe = await kc.get_client_by_client_id(fe_client_id)
+        if not fe:
+            removed.append(
+                {
+                    "frontend_client": fe_client_id,
+                    "audience_removed": False,
+                    "roles_mapper_removed": False,
+                    "error": f"frontend client not found in realm {kc.s.keycloak_realm}",
+                }
+            )
+            continue
+        did_aud = await kc.remove_audience_mapper(fe["id"], api_client_id)
+        did_roles = await kc.remove_client_roles_mapper(fe["id"], api_client_id)
+        removed.append(
+            {
+                "frontend_client": fe_client_id,
+                "audience_removed": did_aud,
+                "roles_mapper_removed": did_roles,
+            }
+        )
+    return removed

pkg_auth/admin/provision_client.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Optional, Iterable, Any
+
+from .client import KeycloakAdminClient
+from .helpers import _ensure_api_client, _ensure_roles, _ensure_frontend_mappers, _remove_frontend_mappers
+from .settings import KCAdminSettings
+
+
+async def provision_keycloak_client(
+        *,
+        settings: KCAdminSettings,
+        client_id: Optional[str] = None,
+        permissions: Optional[Iterable[str]] = None,
+        frontend_client_ids: Optional[Iterable[str]] = None,
+        remove_frontend_client_ids: Optional[Iterable[str]] = None,
+        strict_roles: bool = False,
+        strict_audience: bool = False,
+) -> dict[str, Any]:
+    """
+    High-level async helper to provision a Keycloak API client.
+
+    Steps:
+      1) Ensure the API client exists (bearer-only).
+      2) Ensure client roles correspond to the provided permissions.
+      3) Ensure audience + roles mappers on frontend clients.
+      4) Optionally remove mappers for some frontend clients (strict mode).
+
+    This is the refactored version of your old `provision(...)` function.
+
+    Returns a summary dictionary with:
+      - client
+      - roles
+      - audience
+      - client_roles_mapper
+      - removed
+    """
+    api_client_id = (client_id or settings.default_api_client_id).strip()
+    desired_permissions = list(permissions or [])
+
+    fe_ids = list(frontend_client_ids or settings.frontend_client_ids)
+    remove_fe_ids = list(remove_frontend_client_ids or [])
+
+    kc = KeycloakAdminClient(settings=settings)
+    try:
+        # 1) Ensure API client exists
+        client_repr, internal_api_id = await _ensure_api_client(
+            kc,
+            api_client_id=api_client_id,
+        )
+
+        # 2) Ensure roles
+        roles_summary = await _ensure_roles(
+            kc,
+            internal_id=internal_api_id,
+            permissions=desired_permissions,
+            strict_roles=strict_roles,
+        )
+
+        # 3) Ensure audience + roles mappers for frontend clients
+        audience_actions, roles_mapper_actions = await _ensure_frontend_mappers(
+            kc,
+            api_client_id=api_client_id,
+            internal_api_id=internal_api_id,
+            frontend_client_ids=fe_ids,
+            strict_audience=strict_audience,
+        )
+
+        # 4) Optionally remove mappers for remove_frontend_client_ids
+        removed = []
+        if strict_audience and remove_fe_ids:
+            removed = await _remove_frontend_mappers(
+                kc,
+                api_client_id=api_client_id,
+                remove_frontend_client_ids=remove_fe_ids,
+            )
+
+        return {
+            "client": client_repr,
+            "roles": roles_summary,
+            "audience": audience_actions,
+            "client_roles_mapper": roles_mapper_actions,
+            "removed": removed,
+        }
+    finally:
+        await kc.close()

pkg_auth/admin/settings.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+
+@dataclass(slots=True)
+class KCAdminSettings:
+    """
+    Keycloak admin connection + wiring settings.
+
+    Host code decides how to construct this (env, config file, etc.).
+    """
+    keycloak_base_url: str
+    keycloak_admin_user: str
+    keycloak_admin_pass: str
+    keycloak_realm: str
+    verify_ssl: bool = True
+
+    # Service naming / wiring
+    app_name: Optional[str] = None
+    service_name: Optional[str] = None
+    frontend_client_ids: List[str] = field(default_factory=list)
+
+    @property
+    def base_url_slash(self) -> str:
+        b = self.keycloak_base_url.strip()
+        return b if b.endswith("/") else b + "/"
+
+    @property
+    def default_api_client_id(self) -> str:
+        name = (self.app_name or self.service_name or "service").strip()
+        return f"{name}-api"

pkg_auth/authentication/__init__.py

@@ -0,0 +1,33 @@
+"""Authentication module: JWT validation and identity projection.
+
+Public API:
+
+    IdentityContext             — frozen identity snapshot from a JWT
+    Subject, EmailAddress, RealmName  — identity value objects
+    TokenDecoder                — Protocol port for token verification
+    AuthenticateTokenUseCase    — token → IdentityContext
+    AuthenticationError, TokenExpiredError, InvalidTokenError
+"""
+from __future__ import annotations
+
+from .application.use_cases.authenticate import AuthenticateTokenUseCase
+from .domain.entities import IdentityContext
+from .domain.exceptions import (
+    AuthenticationError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from .domain.ports import TokenDecoder
+from .domain.value_objects import EmailAddress, RealmName, Subject
+
+__all__ = [
+    "IdentityContext",
+    "Subject",
+    "EmailAddress",
+    "RealmName",
+    "TokenDecoder",
+    "AuthenticateTokenUseCase",
+    "AuthenticationError",
+    "TokenExpiredError",
+    "InvalidTokenError",
+]

pkg_auth/authentication/adapters/__init__.py

@@ -0,0 +1 @@
+"""Authentication adapter implementations."""

pkg_auth/authentication/adapters/keycloak/__init__.py

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

pkg_auth/authentication/adapters/keycloak/jwt_decoder.py

@@ -0,0 +1,105 @@
+"""Keycloak JWT decoder adapter (PyJWT + JWKS fetching)."""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, List, Mapping, Optional
+
+import jwt
+from jwt.exceptions import (
+    DecodeError,
+    ExpiredSignatureError,
+    InvalidSignatureError,
+    InvalidTokenError as JWTInvalidTokenError,
+)
+from requests import Session
+
+from ...domain.exceptions import InvalidTokenError, TokenExpiredError
+from ...domain.ports import TokenDecoder
+
+
+class JWTTokenDecoder(TokenDecoder):
+    """PyJWT-based ``TokenDecoder`` implementation for Keycloak.
+
+    Knows how to:
+        - fetch JWKS from a Keycloak realm
+        - cache JWKS keys with a TTL
+        - verify the token signature, expiry, issuer, and audience
+    """
+
+    def __init__(
+        self,
+        *,
+        jwks_uri: str,
+        issuer: str,
+        audience: str,
+        cache_ttl_seconds: int = 300,
+    ) -> None:
+        self._jwks_uri = jwks_uri
+        self._issuer = issuer
+        self._audience = audience
+        self._cache_ttl = cache_ttl_seconds
+
+        self._session = Session()
+        self._jwks_keys: Optional[List[Dict[str, Any]]] = None
+        self._jwks_last_fetched: float = 0.0
+
+    def decode(self, token: str) -> Mapping[str, Any]:
+        try:
+            headers = jwt.get_unverified_header(token)
+            kid = headers.get("kid")
+
+            jwks_keys = self._fetch_jwks_keys()
+            key = next((k for k in jwks_keys if k.get("kid") == kid), None)
+
+            if key is None:
+                raise InvalidTokenError("No matching key found in JWKS")
+
+            public_key = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key))
+
+            payload: Dict[str, Any] = jwt.decode(
+                token,
+                public_key,
+                algorithms=["RS256"],
+                options={"verify_aud": False},
+                issuer=self._issuer,
+            )
+
+            aud_claim = payload.get("aud")
+            if isinstance(aud_claim, str):
+                aud_list = [aud_claim]
+            elif isinstance(aud_claim, list):
+                aud_list = list(aud_claim)
+            else:
+                aud_list = []
+
+            if self._audience not in aud_list:
+                raise InvalidTokenError(
+                    f"Invalid audience: expected {self._audience!r}, got {aud_list!r}"
+                )
+
+            return payload
+
+        except ExpiredSignatureError as exc:
+            raise TokenExpiredError("Token has expired") from exc
+        except (InvalidSignatureError, DecodeError, JWTInvalidTokenError) as exc:
+            raise InvalidTokenError(f"Invalid token: {exc}") from exc
+
+    def _fetch_jwks_keys(self) -> List[Dict[str, Any]]:
+        now = time.time()
+        if (
+            self._jwks_keys is not None
+            and (now - self._jwks_last_fetched) < self._cache_ttl
+        ):
+            return self._jwks_keys
+
+        response = self._session.get(self._jwks_uri)
+        response.raise_for_status()
+
+        body = response.json()
+        keys = body.get("keys", [])
+        if not isinstance(keys, list):
+            raise InvalidTokenError(f"JWKS endpoint returned invalid keys: {keys!r}")
+        self._jwks_keys = keys
+        self._jwks_last_fetched = now
+        return keys

pkg_auth/authentication/application/__init__.py

@@ -0,0 +1 @@
+"""Authentication application layer (use cases)."""

pkg_auth/authentication/application/use_cases/__init__.py

@@ -0,0 +1 @@
+"""Authentication use cases."""

pkg_auth/authentication/application/use_cases/authenticate.py

@@ -0,0 +1,91 @@
+"""Authenticate use case: token → IdentityContext."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from ...domain.entities import IdentityContext
+from ...domain.exceptions import (
+    AuthenticationError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from ...domain.ports import TokenDecoder
+from ...domain.value_objects import EmailAddress, RealmName, Subject
+
+
+@dataclass(slots=True)
+class AuthenticateTokenUseCase:
+    """Decode a token via the injected ``TokenDecoder`` and project its
+    claims into an :class:`IdentityContext`.
+
+    This use case knows nothing about authorization, organizations, or
+    permissions. It is the single entry point for "who is making this
+    request?" — nothing more.
+    """
+
+    token_decoder: TokenDecoder
+
+    def execute(self, token: str) -> IdentityContext:
+        """Authenticate a token and return the identity it represents.
+
+        Raises:
+            TokenExpiredError: token's ``exp`` claim is in the past.
+            InvalidTokenError: missing or malformed ``sub``, bad signature,
+                or any other verification failure.
+            AuthenticationError: unexpected decoder failure.
+        """
+        try:
+            claims = self.token_decoder.decode(token)
+        except (TokenExpiredError, InvalidTokenError):
+            raise
+        except Exception as exc:
+            raise AuthenticationError(f"Token validation failed: {exc}") from exc
+
+        return self._build_identity(claims)
+
+    @staticmethod
+    def _build_identity(claims: Mapping[str, Any]) -> IdentityContext:
+        sub = claims.get("sub")
+        if not isinstance(sub, str) or not sub:
+            raise InvalidTokenError("Token is missing required `sub` claim")
+
+        email_raw = claims.get("email")
+        email: EmailAddress | None = None
+        if isinstance(email_raw, str) and "@" in email_raw:
+            email = EmailAddress(email_raw)
+
+        realm: RealmName | None = None
+        iss = claims.get("iss")
+        if isinstance(iss, str) and "/realms/" in iss:
+            realm = RealmName(iss.rsplit("/realms/", 1)[-1])
+
+        session_id_raw = claims.get("sid") or claims.get("session_state")
+        session_id: str | None = (
+            session_id_raw if isinstance(session_id_raw, str) else None
+        )
+
+        return IdentityContext(
+            subject=Subject(sub),
+            email=email,
+            email_verified=bool(claims.get("email_verified") or False),
+            full_name=_str_or_none(claims.get("name")),
+            first_name=_str_or_none(claims.get("given_name")),
+            last_name=_str_or_none(claims.get("family_name")),
+            preferred_username=_str_or_none(claims.get("preferred_username")),
+            realm=realm,
+            session_id=session_id,
+            issued_at=_int_or_none(claims.get("iat")),
+            expires_at=_int_or_none(claims.get("exp")),
+            auth_time=_int_or_none(claims.get("auth_time")),
+        )
+
+
+def _str_or_none(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _int_or_none(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    return value if isinstance(value, int) else None

pkg_auth/authentication/domain/__init__.py

@@ -0,0 +1 @@
+"""Authentication domain layer (entities, value objects, ports, exceptions)."""

pkg_auth/authentication/domain/entities.py

@@ -0,0 +1,50 @@
+"""Identity context — the validated output of token authentication.
+
+This is the only entity exposed by the authentication module. It carries
+identity and session metadata; it does NOT carry authorization rights.
+Authorization is derived per-(user, organization) by the
+``pkg_auth.authorization`` module from a real ACL database.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .value_objects import EmailAddress, RealmName, Subject
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityContext:
+    """Identity and session metadata for an authenticated principal.
+
+    Built from JWT claims by :class:`AuthenticateTokenUseCase`. Frozen
+    because it's a snapshot of the token at the moment of validation —
+    it never mutates after construction.
+
+    The ``subject`` field is required: a JWT without a ``sub`` claim is
+    rejected as ``InvalidTokenError`` before this object is built.
+    """
+
+    subject: Subject
+    email: EmailAddress | None = None
+    email_verified: bool = False
+
+    full_name: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    preferred_username: str | None = None
+
+    realm: RealmName | None = None
+    session_id: str | None = None
+    issued_at: int | None = None
+    expires_at: int | None = None
+    auth_time: int | None = None
+
+    @property
+    def email_str(self) -> str | None:
+        """The email as a plain string, or ``None`` if unset."""
+        return str(self.email) if self.email is not None else None
+
+    @property
+    def subject_str(self) -> str:
+        """The subject as a plain string."""
+        return str(self.subject)

pkg_auth/authentication/domain/exceptions.py

@@ -0,0 +1,18 @@
+"""Authentication exceptions.
+
+Authorization-related exceptions live in
+``pkg_auth.authorization.domain.exceptions`` (added in M2).
+"""
+from __future__ import annotations
+
+
+class AuthenticationError(Exception):
+    """Base for all authentication failures."""
+
+
+class TokenExpiredError(AuthenticationError):
+    """The token's ``exp`` claim is in the past."""
+
+
+class InvalidTokenError(AuthenticationError):
+    """Token is malformed, has an invalid signature, or fails verification."""

pkg_auth/authentication/domain/ports.py

@@ -0,0 +1,26 @@
+"""Authentication domain ports (Protocols)."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Protocol
+
+
+class TokenDecoder(Protocol):
+    """Port for decoding an access token into a claims mapping.
+
+    Implementations live in the adapters layer (e.g.
+    :class:`pkg_auth.authentication.adapters.keycloak.JWTTokenDecoder`).
+    """
+
+    def decode(self, token: str) -> Mapping[str, Any]:
+        """Decode and verify the given token.
+
+        Implementations must:
+            - verify the signature
+            - check the ``exp`` claim
+            - validate the issuer and audience
+
+        Raises:
+            TokenExpiredError: when the ``exp`` claim is in the past.
+            InvalidTokenError: for any other validation failure.
+        """
+        ...

pkg_auth/authentication/domain/value_objects.py

@@ -0,0 +1,42 @@
+"""Identity value objects (subject, email, realm name)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Subject:
+    """The IdP subject identifier (Keycloak ``sub`` claim).
+
+    Kept as a distinct type so it isn't accidentally treated as an
+    internal user primary key.
+    """
+
+    value: str
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddress:
+    """An email address with light validation."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if "@" not in self.value:
+            raise ValueError(f"Invalid email address: {self.value!r}")
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class RealmName:
+    """A Keycloak realm name extracted from an issuer URL."""
+
+    value: str
+
+    def __str__(self) -> str:
+        return self.value