keyrunes-python-sdk 0.1.0__tar.gz → 0.3.0__tar.gz

keyrunes_python_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- `User.user_id`, carrying the internal identifier Keyrunes puts in the JWT
+  `sub` claim. It is a different value from `User.id` (the external UUID), and
+  a consumer that keys its own records off `sub` needs it; before this release
+  it was discarded during normalization and could only be recovered by
+  re-parsing the token.
+- `User.namespace`, `User.organization_id` and `User.first_login`, all of which
+  the server returns and normalization used to drop.
+- `Token.requires_password_change`, so a login that must be followed by a
+  password change can be detected without reading the raw response.
+- `KeyrunesClient.refresh_token()`, wrapping `POST /api/refresh-token`. It
+  accepts an explicit token or falls back to the client's current one, raises
+  `InvalidTokenError` when neither is available, and adopts the refreshed
+  token the way `login()` does.
+- `get_current_user(force_refresh=True)`, which always asks the server. The
+  claims shortcut reads a token the SDK never verified, so it cannot answer
+  "is this token still accepted"; a caller validating a token needs the round
+  trip.
+- `KeyrunesError.status_code`, carrying the HTTP status when the error came
+  from a response rather than from the transport. Without it a caller cannot
+  tell "the server refused this request" (4xx) from "the server or the network
+  failed" (5xx, or no response at all), and both are raised as `NetworkError`.
+- `register_user(group=...)`, sent as a top-level field.
+- A `py.typed` marker (PEP 561). The package was already fully typed, but
+  without the marker a consumer running mypy saw every SDK import as
+  untyped.
+
+### Fixed
+
+- `get_current_user()` asked for `/api/users/me`, which the Keyrunes router
+  does not expose — the real route is `/api/me`, so the call answered 404
+  against a live server whenever the claims shortcut did not cover it. The
+  endpoint is now a named constant, `ENDPOINT_ME`.
+- `register_user()` and `register_admin()` required the response to be
+  `{"user": {...}}`, but `POST /api/register` answers with the bare user
+  object. Every registration against a real server failed with "Unexpected
+  response format". Both shapes are now accepted.
+- Extra keyword arguments to `register_user()` were nested under `attributes`,
+  so a `group` never reached the server, which reads it as a top-level field.
+  `group` is now an explicit parameter placed at the top level; other keyword
+  attributes keep nesting under `attributes`.
+
+### Testing
+
+- Test count raised from 159 to 189.
+
+### Notes
+
+- Every added field is optional with a backwards-compatible default, and
+  `User.id` keeps its existing precedence (`id` → `user_id` → `external_id`).
+  Code written against 0.2.0 keeps working unchanged.
+
+## [0.2.0] - 2026-09-03
+
+### Added
+
+- Property-based test suite (`tests/test_property_based.py`, 24 tests) built on
+  Hypothesis, covering base URL normalization, `_normalize_user` id precedence
+  and `is_admin` derivation, JWT claim parsing, request URL construction, HTTP
+  status to exception mapping, and model validation bounds.
+- Input fuzzing ("spider") suite (`tests/test_fuzz.py`, 19 tests) that crawls the
+  public surface with hostile payloads and asserts that only `KeyrunesError` and
+  pydantic `ValidationError` ever escape, and that nothing panics or leaks a raw
+  `ValueError`/`TypeError`.
+- Request contract suite (`tests/test_request_contract.py`, 33 tests) that mocks
+  only the httpx transport, so the method, URL, headers and JSON body actually
+  put on the wire are asserted for every endpoint.
+- Hypothesis profiles in `tests/conftest.py` (`fast`, `dev`, `ci`) selected via
+  the `HYPOTHESIS_PROFILE` environment variable. `fast` is derandomized and
+  database-free so mutation runs judge every mutant against identical examples.
+- `[tool.mutmut]` configuration in `pyproject.toml` for mutation testing.
+- `hypothesis` added as a development dependency.
+
+### Fixed
+
+- A 2xx response carrying a non-JSON body raised a raw `ValueError` out of
+  `KeyrunesClient._make_request`. It is now wrapped in `NetworkError`, so the
+  documented exception contract holds for malformed responses.
+
+### Changed
+
+- Extracted the duplicated "build a `User` from JWT claims" block into
+  `KeyrunesClient._user_from_token_claims()`.
+
+### Removed
+
+- Unreachable `except UserNotFoundError` fallbacks in `get_user`,
+  `get_current_user` and `has_group`. Each re-tested a condition that had
+  already forced an early return, so a 404 from the server was being swallowed
+  instead of propagated.
+
+### Testing
+
+- Test count raised from 83 to 159.
+- Mutation score (mutmut) raised from 44% (294/669 mutants killed) to 72%
+  (387/537). The remaining survivors are predominantly equivalent mutants that
+  only alter error message prose.
+
+## [0.1.0] - 2025-12-03
+
+### Adicionado
+
+#### Funcionalidades Core
+- Cliente `KeyrunesClient` completo para interação com Keyrunes API
+- Autenticação com login de usuário e admin
+- Registro de usuário e admin com validação
+- Verificação de pertencimento a grupos
+- Obtenção de informações de usuários
+
+#### Decorators
+- `@require_group()` - Decorator para verificar grupos de usuários
+- `@require_admin()` - Decorator para verificar privilégios de admin
+- Suporte para múltiplos grupos (ANY ou ALL)
+- Sistema de client global para uso sem passar client explicitamente
+
+#### Modelos Pydantic
+- `User` - Modelo de usuário com validação
+- `Token` - Modelo de token JWT
+- `Group` - Modelo de grupo
+- `UserRegistration` - Dados de registro de usuário
+- `AdminRegistration` - Dados de registro de admin
+- `LoginCredentials` - Credenciais de login
+- `GroupCheck` - Resultado de verificação de grupo
+
+#### Exceções Customizadas
+- `KeyrunesError` - Exceção base
+- `AuthenticationError` - Erro de autenticação
+- `AuthorizationError` - Erro de autorização
+- `GroupNotFoundError` - Grupo não encontrado
+- `UserNotFoundError` - Usuário não encontrado
+- `InvalidTokenError` - Token inválido
+- `NetworkError` - Erro de rede
+
+#### Sistema de Configuração Global
+- `configure()` - Configura client global
+- `get_global_client()` - Obtém client global
+- `clear_global_client()` - Limpa client global
+- Thread-safe com Lock
+
+#### Desenvolvimento e Testes
+- Docker Compose completo com Keyrunes, PostgreSQL e Redis
+- 78 testes com 99% de cobertura
+- Testes usando pytest, factory-boy e faker
+- Exemplos práticos de uso
+- Makefile com comandos úteis
+- Configuração completa de CI/CD
+
+#### Documentação
+- README.md completo com exemplos
+- TESTING.md com guia de testes
+- Docstrings em todas as funções
+- Type hints completos
+- Exemplos práticos em `examples/`
+
+### Detalhes Técnicos
+
+- Python 3.8.1+ compatível
+- Gerenciamento com Poetry
+- Validação com Pydantic 2.0
+- Type hints completos
+- Thread-safe
+- Context manager support
+
+### Testes
+
+- 78 testes implementados
+- 99% de cobertura de código
+- Testes unitários e de integração
+- Factories com factory-boy
+- Dados fake com Faker
+
+### Ferramentas de Desenvolvimento
+
+- Black para formatação
+- isort para organização de imports
+- flake8 para linting
+- mypy para type checking
+- pytest para testes
+
+## [Unreleased]
+
+### Planejado
+
+- Suporte para refresh token automático
+- Cache de verificações de grupo
+- Suporte para OIDC
+- Integração com FastAPI
+- Integração com Flask
+- Integração com Django
+- Mais exemplos práticos
+- Documentação com Sphinx
+- Publicação no PyPI
+
+---
+
+Para mais detalhes sobre cada versão, veja os [releases no GitHub](https://github.com/jonatasoli/keyurnes-sdk-python-dark/releases).

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: keyrunes-python-sdk
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python SDK for Keyrunes Authorization System
 License: AGPL
+License-File: LICENSE
 Keywords: keyrunes,authorization,rbac,abac,security,authentication,permissions
 Author: keyrunes
 Author-email: contact@singularjourney.host
@@ -17,12 +18,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: mutmut (>=3.7.0,<4.0.0)
 Requires-Dist: pydantic[email] (>=2.0.0,<3.0.0)
 Requires-Dist: pyjwt (>=2.9.0,<3.0.0)
 Project-URL: Documentation, https://github.com/jonatasoli/keyrunes-python-sdk#readme
@@ -33,11 +35,12 @@ Description-Content-Type: text/markdown
 # Keyrunes SDK Python Client
 
 [![Tests](https://github.com/Keyrunes/keyrunes-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Keyrunes/keyrunes-python-sdk/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/Keyrunes/keyrunes-python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/Keyrunes/keyrunes-python-sdk)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+
 Python SDK for integration with the [Keyrunes Authorization System](https://github.com/Keyrunes/keyrunes), a modern high-performance authorization system built in Rust.
+[Pypi](https://pypi.org/project/keyrunes-python-sdk/)
 
 ## Features
 

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/README.md

@@ -1,11 +1,12 @@
 # Keyrunes SDK Python Client
 
 [![Tests](https://github.com/Keyrunes/keyrunes-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Keyrunes/keyrunes-python-sdk/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/Keyrunes/keyrunes-python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/Keyrunes/keyrunes-python-sdk)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+
 Python SDK for integration with the [Keyrunes Authorization System](https://github.com/Keyrunes/keyrunes), a modern high-performance authorization system built in Rust.
+[Pypi](https://pypi.org/project/keyrunes-python-sdk/)
 
 ## Features
 

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/__init__.py

@@ -1,6 +1,6 @@
 """Keyrunes SDK - Python client for Keyrunes Authorization System."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 from keyrunes_sdk.client import KeyrunesClient
 from keyrunes_sdk.config import (

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/client.py

@@ -11,6 +11,7 @@ from keyrunes_sdk.exceptions import (
     AuthenticationError,
     AuthorizationError,
     GroupNotFoundError,
+    InvalidTokenError,
     NetworkError,
     UserNotFoundError,
 )
@@ -23,6 +24,17 @@ from keyrunes_sdk.models import (
     UserRegistration,
 )
 
+#: Where the server answers "who is this token". The Keyrunes router exposes
+#: this as ``/api/me``; there is no ``/api/users/me``.
+#: Creates a user; answers with the bare user object.
+ENDPOINT_REGISTER = "/api/register"
+
+#: Where the server answers "who is this token".
+ENDPOINT_ME = "/api/me"
+
+#: Exchanges a still-valid token for a fresh one.
+ENDPOINT_REFRESH_TOKEN = "/api/refresh-token"
+
 
 class KeyrunesClient:
     """
@@ -135,9 +147,17 @@ class KeyrunesClient:
                     error_msg = (
                         response.text or f"HTTP {response.status_code} error"
                     )
-                raise NetworkError(f"Request failed: {error_msg}")
+                raise NetworkError(
+                    f"Request failed: {error_msg}",
+                    status_code=response.status_code,
+                )
 
-            result: Dict[str, Any] = response.json()
+            try:
+                result: Dict[str, Any] = response.json()
+            except (ValueError, TypeError) as e:
+                raise NetworkError(
+                    f"Malformed JSON in response from {url}: {str(e)}"
+                )
             return result
 
         except httpx.RequestError as e:
@@ -165,8 +185,32 @@ class KeyrunesClient:
         normalized["is_admin"] = (
             is_admin_flag or has_admin_group or has_admin_in_name
         )
+        # Carried through untouched so a caller can key its own records off the
+        # same identifier the JWT ``sub`` uses, rather than off ``id``.
+        raw_user_id = data.get("user_id")
+        normalized["user_id"] = (
+            str(raw_user_id) if raw_user_id is not None else None
+        )
+        normalized["namespace"] = data.get("namespace")
+        normalized["organization_id"] = data.get("organization_id")
+        normalized["first_login"] = bool(data.get("first_login", False))
         return User(**normalized)
 
+    def _user_from_token_claims(self) -> User:
+        """Build a :class:`User` out of the claims carried by the JWT.
+
+        Only called once ``self._token_data`` is known to be populated.
+        """
+        token_data = self._token_data or {}
+        return self._normalize_user(
+            {
+                "id": str(token_data.get("sub", "")),
+                "username": token_data.get("username", ""),
+                "email": token_data.get("email", ""),
+                "groups": token_data.get("groups", []),
+            }
+        )
+
     def _parse_token_response(self, payload: Dict[str, Any]) -> Token:
         """
         Accept both legacy and current API token responses.
@@ -201,6 +245,9 @@ class KeyrunesClient:
             expires_in=payload.get("expires_in"),
             refresh_token=payload.get("refresh_token"),
             user=user_model,
+            requires_password_change=bool(
+                payload.get("requires_password_change", False)
+            ),
         )
 
     def login(
@@ -247,12 +294,36 @@ class KeyrunesClient:
             self._token_data = None
         return token
 
+    @staticmethod
+    def _registration_payload(response: Any) -> Dict[str, Any]:
+        """Pull the user object out of a registration response.
+
+        ``POST /api/register`` answers with the bare user object. Some
+        deployments wrap it as ``{"user": {...}}``, so both are accepted.
+        """
+        if not isinstance(response, dict):
+            raise NetworkError(
+                "Unexpected response format for user registration."
+            )
+
+        wrapped = response.get("user")
+        if isinstance(wrapped, dict) and wrapped:
+            return wrapped
+
+        # A bare user object is identified by carrying an identifier; anything
+        # else is a response shape this SDK does not understand.
+        if response.get("id") or response.get("user_id"):
+            return response
+
+        raise NetworkError("Unexpected response format for user registration.")
+
     def register_user(
         self,
         username: str,
         email: str,
         password: str,
         namespace: str = "public",
+        group: Optional[str] = None,
         **attributes: Any,
     ) -> User:
         """
@@ -263,6 +334,8 @@ class KeyrunesClient:
             email: User email address
             password: Password (minimum 8 characters)
             namespace: User namespace (default: "public")
+            group: Group to place the new user in. Sent as a top-level field,
+                which is where the server reads it from.
             **attributes: Additional user attributes
 
         Returns:
@@ -288,22 +361,18 @@ class KeyrunesClient:
             namespace=namespace,
             attributes=attributes,
         )
+        data = registration.model_dump()
+        if group is not None:
+            data["group"] = group
+
         response = self._make_request(
             "POST",
-            "/api/register",
-            data=registration.model_dump(),
+            ENDPOINT_REGISTER,
+            data=data,
             use_auth=False,
         )
 
-        user_payload = (
-            response.get("user") if isinstance(response, dict) else None
-        )
-        if not user_payload:
-            raise NetworkError(
-                "Unexpected response format for user registration."
-            )
-
-        return self._normalize_user(user_payload)
+        return self._normalize_user(self._registration_payload(response))
 
     def register_admin(
         self,
@@ -351,20 +420,12 @@ class KeyrunesClient:
         )
         response = self._make_request(
             "POST",
-            "/api/register",
+            ENDPOINT_REGISTER,
             data=registration.model_dump(),
             use_auth=False,
         )
 
-        user_payload = (
-            response.get("user") if isinstance(response, dict) else None
-        )
-        if not user_payload:
-            raise NetworkError(
-                "Unexpected response format for admin registration."
-            )
-
-        return self._normalize_user(user_payload)
+        return self._normalize_user(self._registration_payload(response))
 
     def has_group(self, user_id: str, group_id: str) -> bool:
         """
@@ -409,13 +470,8 @@ class KeyrunesClient:
             check = GroupCheck(**response)
             return check.has_access
         except UserNotFoundError:
-            if token_user_id and str(user_id) == token_user_id:
-                groups = (
-                    self._token_data.get("groups", [])
-                    if self._token_data
-                    else []
-                )
-                return group_id in groups
+            # The self-lookup above already returned for the authenticated
+            # user, so reaching here always means a genuine miss.
             raise GroupNotFoundError(
                 f"Group '{group_id}' not found or user not in group"
             )
@@ -448,38 +504,25 @@ class KeyrunesClient:
         )
 
         if token_user_id and str(user_id) == token_user_id and self._token_data:
-            token_data = self._token_data
-            user_data = {
-                "id": str(token_data.get("sub", "")),
-                "username": token_data.get("username", ""),
-                "email": token_data.get("email", ""),
-                "groups": token_data.get("groups", []),
-            }
-            return self._normalize_user(user_data)
+            return self._user_from_token_claims()
 
-        try:
-            response = self._make_request("GET", f"/api/users/{user_id}")
-            return self._normalize_user(response)
-        except UserNotFoundError:
-            if (
-                token_user_id
-                and str(user_id) == token_user_id
-                and self._token_data
-            ):
-                token_data = self._token_data
-                user_data = {
-                    "id": str(token_data.get("sub", "")),
-                    "username": token_data.get("username", ""),
-                    "email": token_data.get("email", ""),
-                    "groups": token_data.get("groups", []),
-                }
-                return self._normalize_user(user_data)
-            raise
-
-    def get_current_user(self) -> User:
+        # The claims shortcut above already handled the authenticated user, so
+        # a 404 here is always a genuine miss and is propagated as such.
+        response = self._make_request("GET", f"/api/users/{user_id}")
+        return self._normalize_user(response)
+
+    def get_current_user(self, force_refresh: bool = False) -> User:
         """
         Get currently authenticated user information.
 
+        Args:
+            force_refresh: Ask the server even when the token's own claims
+                could answer. Required whenever the answer is used to decide
+                whether the token is still good: the claims shortcut reads a
+                token the SDK never verified, so it says nothing about whether
+                the server still accepts it (revoked, expired, or signed with
+                another key).
+
         Returns:
             User object for authenticated user
 
@@ -495,30 +538,11 @@ class KeyrunesClient:
         if not self._token:
             raise AuthenticationError("Not authenticated. Please login first.")
 
-        if self._token_data:
-            token_data = self._token_data
-            user_data = {
-                "id": str(token_data.get("sub", "")),
-                "username": token_data.get("username", ""),
-                "email": token_data.get("email", ""),
-                "groups": token_data.get("groups", []),
-            }
-            return self._normalize_user(user_data)
+        if self._token_data and not force_refresh:
+            return self._user_from_token_claims()
 
-        try:
-            response = self._make_request("GET", "/api/users/me")
-            return self._normalize_user(response)
-        except UserNotFoundError:
-            if self._token_data:
-                token_data = self._token_data
-                user_data = {
-                    "id": str(token_data.get("sub", "")),
-                    "username": token_data.get("username", ""),
-                    "email": token_data.get("email", ""),
-                    "groups": token_data.get("groups", []),
-                }
-                return self._normalize_user(user_data)
-            raise
+        response = self._make_request("GET", ENDPOINT_ME)
+        return self._normalize_user(response)
 
     def get_user_groups(self, user_id: Optional[str] = None) -> List[str]:
         """
@@ -565,6 +589,44 @@ class KeyrunesClient:
         except Exception:
             self._token_data = None
 
+    def refresh_token(self, token: Optional[str] = None) -> Token:
+        """
+        Exchange a still-valid token for a fresh one.
+
+        Args:
+            token: Token to exchange. Defaults to the client's current token.
+
+        Returns:
+            Token object carrying the new access token.
+
+        Raises:
+            InvalidTokenError: If no token is available to exchange
+            AuthenticationError: If the server rejects the token
+            NetworkError: If the request fails
+
+        Example:
+            >>> client = KeyrunesClient("https://keyrunes.example.com")
+            >>> client.set_token("eyJhbGciOiJIUzI1NiIs...")
+            >>> refreshed = client.refresh_token()
+            >>> client.set_token(refreshed.access_token)
+        """
+        current = token or self._token
+        if not current:
+            raise InvalidTokenError("No token available to refresh.")
+
+        response = self._make_request(
+            "POST",
+            ENDPOINT_REFRESH_TOKEN,
+            data={"token": current},
+            use_auth=False,
+        )
+
+        refreshed = self._parse_token_response(response)
+        # Refreshing is only ever useful if the client keeps using the result,
+        # so adopt it the way login() does.
+        self.set_token(refreshed.access_token)
+        return refreshed
+
     def clear_token(self) -> None:
         """
         Clear authentication token.

keyrunes_python_sdk-0.3.0/keyrunes_sdk/exceptions.py

@@ -0,0 +1,62 @@
+"""Custom exceptions for Keyrunes SDK."""
+
+from typing import Optional
+
+
+class KeyrunesError(Exception):
+    """Base exception for all Keyrunes SDK errors.
+
+    Args:
+        message: Human-readable description.
+        status_code: HTTP status the server answered with, when the error came
+            from a response rather than from the transport. Callers use it to
+            tell "the server refused this request" (4xx, the caller's problem)
+            from "the server or the network failed" (5xx or no response at
+            all), which otherwise look identical.
+    """
+
+    def __init__(
+        self, message: str = "", status_code: Optional[int] = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(KeyrunesError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class AuthorizationError(KeyrunesError):
+    """Raised when authorization fails."""
+
+    pass
+
+
+class GroupNotFoundError(KeyrunesError):
+    """Raised when a group is not found."""
+
+    pass
+
+
+class UserNotFoundError(KeyrunesError):
+    """Raised when a user is not found."""
+
+    pass
+
+
+class InvalidTokenError(KeyrunesError):
+    """Raised when token is invalid or expired."""
+
+    pass
+
+
+class NetworkError(KeyrunesError):
+    """Raised when a request fails.
+
+    ``status_code`` is set when the server answered and the response was an
+    error; it is ``None`` when the request never got a response.
+    """
+
+    pass

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/models.py

@@ -28,6 +28,23 @@ class User(BaseModel):
     is_admin: bool = Field(
         False, description="Whether user has admin privileges"
     )
+    # Keyrunes answers with two identifiers: ``id`` is the external UUID and
+    # ``user_id`` is the internal integer the JWT carries as ``sub``. ``id``
+    # above keeps its historical precedence; this field is kept alongside it so
+    # a caller that keys its own records off ``sub`` can reach that value
+    # without re-parsing the token.
+    user_id: Optional[str] = Field(
+        None, description="Internal user identifier, as carried by the JWT sub"
+    )
+    namespace: Optional[str] = Field(
+        None, description="Namespace (tenant) the user belongs to"
+    )
+    organization_id: Optional[Any] = Field(
+        None, description="Organization the user belongs to"
+    )
+    first_login: bool = Field(
+        False, description="Whether the user has yet to complete a first login"
+    )
 
 
 class Group(BaseModel):
@@ -54,6 +71,10 @@ class Token(BaseModel):
     )
     refresh_token: Optional[str] = Field(None, description="Refresh token")
     user: Optional[User] = Field(None, description="User information")
+    requires_password_change: bool = Field(
+        False,
+        description="Whether the server wants the password changed before use",
+    )
 
 
 class UserRegistration(BaseModel):

{keyrunes_python_sdk-0.1.0 → keyrunes_python_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "keyrunes-python-sdk"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python SDK for Keyrunes Authorization System"
 authors = ["keyrunes <contact@singularjourney.host>"]
 maintainers = ["jonatasoli <contact@jonatasoli.dev>"]
@@ -25,7 +25,9 @@ classifiers = [
     "Topic :: System :: Systems Administration :: Authentication/Directory",
 ]
 packages = [{include = "keyrunes_sdk"}]
-include = ["LICENSE", "README.md", "CHANGELOG.md"]
+# `py.typed` marks the package as typed (PEP 561); without it a consumer
+# running mypy sees every SDK import as untyped.
+include = ["LICENSE", "README.md", "CHANGELOG.md", "keyrunes_sdk/py.typed"]
 exclude = ["tests", "examples", "docs", "*.pyc", "__pycache__"]
 
 [tool.poetry.dependencies]
@@ -33,6 +35,7 @@ python = ">=3.10.1,<4.0"
 pydantic = {extras = ["email"], version = "^2.0.0"}
 pyjwt = "^2.9.0"
 httpx = "^0.28.1"
+mutmut = "^3.7.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"
@@ -48,6 +51,7 @@ taskipy = "^1.12.0"
 towncrier = "^25.8.0"
 pre-commit = "^4.5.1"
 safety = "^3.7.0"
+hypothesis = "^6.0"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
@@ -66,6 +70,17 @@ addopts = [
     "-v",
 ]
 
+[tool.mutmut]
+# Mutation testing. Only the library is mutated; the test suite is the oracle.
+source_paths = ["keyrunes_sdk"]
+do_not_mutate = [
+    "keyrunes_sdk/__init__.py",
+]
+# The project-wide addopts turn on coverage, which roughly doubles the runtime
+# of every one of the hundreds of per-mutant test runs.
+pytest_add_cli_args = ["--no-cov", "-p", "no:cacheprovider", "-x", "-q"]
+pytest_add_cli_args_test_selection = ["tests/"]
+
 [tool.black]
 line-length = 80
 target-version = ['py312']

keyrunes_python_sdk-0.1.0/CHANGELOG.md

@@ -1,105 +0,0 @@
-# Changelog
-
-Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
-
-O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
-e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
-
-## [0.1.0] - 2025-12-03
-
-### Adicionado
-
-#### Funcionalidades Core
-- Cliente `KeyrunesClient` completo para interação com Keyrunes API
-- Autenticação com login de usuário e admin
-- Registro de usuário e admin com validação
-- Verificação de pertencimento a grupos
-- Obtenção de informações de usuários
-
-#### Decorators
-- `@require_group()` - Decorator para verificar grupos de usuários
-- `@require_admin()` - Decorator para verificar privilégios de admin
-- Suporte para múltiplos grupos (ANY ou ALL)
-- Sistema de client global para uso sem passar client explicitamente
-
-#### Modelos Pydantic
-- `User` - Modelo de usuário com validação
-- `Token` - Modelo de token JWT
-- `Group` - Modelo de grupo
-- `UserRegistration` - Dados de registro de usuário
-- `AdminRegistration` - Dados de registro de admin
-- `LoginCredentials` - Credenciais de login
-- `GroupCheck` - Resultado de verificação de grupo
-
-#### Exceções Customizadas
-- `KeyrunesError` - Exceção base
-- `AuthenticationError` - Erro de autenticação
-- `AuthorizationError` - Erro de autorização
-- `GroupNotFoundError` - Grupo não encontrado
-- `UserNotFoundError` - Usuário não encontrado
-- `InvalidTokenError` - Token inválido
-- `NetworkError` - Erro de rede
-
-#### Sistema de Configuração Global
-- `configure()` - Configura client global
-- `get_global_client()` - Obtém client global
-- `clear_global_client()` - Limpa client global
-- Thread-safe com Lock
-
-#### Desenvolvimento e Testes
-- Docker Compose completo com Keyrunes, PostgreSQL e Redis
-- 78 testes com 99% de cobertura
-- Testes usando pytest, factory-boy e faker
-- Exemplos práticos de uso
-- Makefile com comandos úteis
-- Configuração completa de CI/CD
-
-#### Documentação
-- README.md completo com exemplos
-- TESTING.md com guia de testes
-- Docstrings em todas as funções
-- Type hints completos
-- Exemplos práticos em `examples/`
-
-### Detalhes Técnicos
-
-- Python 3.8.1+ compatível
-- Gerenciamento com Poetry
-- Validação com Pydantic 2.0
-- Type hints completos
-- Thread-safe
-- Context manager support
-
-### Testes
-
-- 78 testes implementados
-- 99% de cobertura de código
-- Testes unitários e de integração
-- Factories com factory-boy
-- Dados fake com Faker
-
-### Ferramentas de Desenvolvimento
-
-- Black para formatação
-- isort para organização de imports
-- flake8 para linting
-- mypy para type checking
-- pytest para testes
-
-## [Unreleased]
-
-### Planejado
-
-- Suporte para refresh token automático
-- Cache de verificações de grupo
-- Suporte para OIDC
-- Integração com FastAPI
-- Integração com Flask
-- Integração com Django
-- Mais exemplos práticos
-- Documentação com Sphinx
-- Publicação no PyPI
-
----
-
-Para mais detalhes sobre cada versão, veja os [releases no GitHub](https://github.com/jonatasoli/keyurnes-sdk-python-dark/releases).

keyrunes_python_sdk-0.1.0/keyrunes_sdk/exceptions.py

@@ -1,43 +0,0 @@
-"""Custom exceptions for Keyrunes SDK."""
-
-
-class KeyrunesError(Exception):
-    """Base exception for all Keyrunes SDK errors."""
-
-    pass
-
-
-class AuthenticationError(KeyrunesError):
-    """Raised when authentication fails."""
-
-    pass
-
-
-class AuthorizationError(KeyrunesError):
-    """Raised when authorization fails."""
-
-    pass
-
-
-class GroupNotFoundError(KeyrunesError):
-    """Raised when a group is not found."""
-
-    pass
-
-
-class UserNotFoundError(KeyrunesError):
-    """Raised when a user is not found."""
-
-    pass
-
-
-class InvalidTokenError(KeyrunesError):
-    """Raised when token is invalid or expired."""
-
-    pass
-
-
-class NetworkError(KeyrunesError):
-    """Raised when network request fails."""
-
-    pass