keyrunes-python-sdk 0.0.1__tar.gz → 0.2.0__tar.gz

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.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

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: keyrunes-python-sdk
-Version: 0.0.1
+Version: 0.2.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.0.1 → keyrunes_python_sdk-0.2.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.0.1 → keyrunes_python_sdk-0.2.0}/keyrunes_sdk/__init__.py

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

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/keyrunes_sdk/client.py

@@ -1,5 +1,6 @@
 """Keyrunes API Client."""
 
+import os
 from typing import Any, Dict, List, Optional
 from urllib.parse import urljoin
 
@@ -38,6 +39,8 @@ class KeyrunesClient:
         base_url: Base URL of the Keyrunes API
             (e.g., "https://keyrunes.example.com")
         api_key: Optional API key for authentication
+        organization_key: Optional Organization Key (required for v0.2.0+)
+            If not provided, looks for KEYRUNES_ORG_KEY env var
         timeout: Request timeout in seconds (default: 30)
 
     Example:
@@ -50,11 +53,16 @@ class KeyrunesClient:
         self,
         base_url: str,
         api_key: Optional[str] = None,
+        organization_key: Optional[str] = None,
         timeout: int = 30,
     ) -> None:
         """Initialize Keyrunes client."""
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key
+        # Prioritize explicit argument, then env var
+        self.organization_key = organization_key or os.getenv(
+            "KEYRUNES_ORG_KEY"
+        )
         self.timeout = timeout
         self._token: Optional[str] = None
         self._token_data: Optional[Dict[str, Any]] = None
@@ -63,6 +71,11 @@ class KeyrunesClient:
         if api_key:
             self._client.headers.update({"X-API-Key": api_key})
 
+        if self.organization_key:
+            self._client.headers.update(
+                {"X-Organization-Key": self.organization_key}
+            )
+
     def _make_request(
         self,
         method: str,
@@ -124,7 +137,12 @@ class KeyrunesClient:
                     )
                 raise NetworkError(f"Request failed: {error_msg}")
 
-            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:
@@ -154,6 +172,21 @@ class KeyrunesClient:
         )
         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.
@@ -190,13 +223,16 @@ class KeyrunesClient:
             user=user_model,
         )
 
-    def login(self, username: str, password: str) -> Token:
+    def login(
+        self, username: str, password: str, namespace: str = "public"
+    ) -> Token:
         """
         Authenticate user and obtain access token.
 
         Args:
             username: Username or email
             password: User password
+            namespace: User namespace (default: "public")
 
         Returns:
             Token object containing access token and user info
@@ -206,10 +242,14 @@ class KeyrunesClient:
 
         Example:
             >>> client = KeyrunesClient("https://keyrunes.example.com")
-            >>> token = client.login("user@example.com", "password123")
+            >>> token = client.login(
+            ...     "user@example.com", "password123", namespace="public"
+            ... )
             >>> client.set_token(token.access_token)
         """
-        credentials = LoginCredentials(identity=username, password=password)
+        credentials = LoginCredentials(
+            identity=username, password=password, namespace=namespace
+        )
         response = self._make_request(
             "POST",
             "/api/login",
@@ -228,7 +268,12 @@ class KeyrunesClient:
         return token
 
     def register_user(
-        self, username: str, email: str, password: str, **attributes: Any
+        self,
+        username: str,
+        email: str,
+        password: str,
+        namespace: str = "public",
+        **attributes: Any,
     ) -> User:
         """
         Register a new user.
@@ -237,6 +282,7 @@ class KeyrunesClient:
             username: Username (3-50 characters)
             email: User email address
             password: Password (minimum 8 characters)
+            namespace: User namespace (default: "public")
             **attributes: Additional user attributes
 
         Returns:
@@ -251,6 +297,7 @@ class KeyrunesClient:
             ...     username="newuser",
             ...     email="newuser@example.com",
             ...     password="securepass123",
+            ...     namespace="my-app",
             ...     department="Engineering"
             ... )
         """
@@ -258,6 +305,7 @@ class KeyrunesClient:
             username=username,
             email=email,
             password=password,
+            namespace=namespace,
             attributes=attributes,
         )
         response = self._make_request(
@@ -283,6 +331,7 @@ class KeyrunesClient:
         email: str,
         password: str,
         admin_key: str,
+        namespace: str = "public",
         **attributes: Any,
     ) -> User:
         """
@@ -293,6 +342,7 @@ class KeyrunesClient:
             email: Admin email address
             password: Password (minimum 8 characters)
             admin_key: Admin registration key
+            namespace: User namespace (default: "public")
             **attributes: Additional user attributes
 
         Returns:
@@ -316,6 +366,7 @@ class KeyrunesClient:
             email=email,
             password=password,
             admin_key=admin_key,
+            namespace=namespace,
             attributes=attributes,
         )
         response = self._make_request(
@@ -378,13 +429,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"
             )
@@ -417,33 +463,12 @@ 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
+        # 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) -> User:
         """
@@ -465,29 +490,12 @@ class KeyrunesClient:
             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)
+            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
+        # The claims shortcut above already handled every case where the token
+        # could answer, so a 404 here is a genuine miss and is propagated.
+        response = self._make_request("GET", "/api/users/me")
+        return self._normalize_user(response)
 
     def get_user_groups(self, user_id: Optional[str] = None) -> List[str]:
         """

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/keyrunes_sdk/config.py

@@ -69,6 +69,7 @@ class _GlobalConfig:
         self,
         base_url: str,
         api_key: Optional[str] = None,
+        organization_key: Optional[str] = None,
         timeout: int = 30,
     ) -> KeyrunesClient:
         """
@@ -77,6 +78,7 @@ class _GlobalConfig:
         Args:
             base_url: Base URL of the Keyrunes API
             api_key: Optional API key for authentication
+            organization_key: Optional Organization Key (required for v0.2.0+)
             timeout: Request timeout in seconds (default: 30)
 
         Returns:
@@ -91,7 +93,10 @@ class _GlobalConfig:
             ... )
         """
         client = KeyrunesClient(
-            base_url=base_url, api_key=api_key, timeout=timeout
+            base_url=base_url,
+            api_key=api_key,
+            organization_key=organization_key,
+            timeout=timeout,
         )
         self.set_client(client)
         return client
@@ -133,6 +138,7 @@ def get_config() -> _GlobalConfig:
 def configure(
     base_url: str,
     api_key: Optional[str] = None,
+    organization_key: Optional[str] = None,
     timeout: int = 30,
 ) -> KeyrunesClient:
     """
@@ -145,6 +151,7 @@ def configure(
     Args:
         base_url: Base URL of the Keyrunes API
         api_key: Optional API key for authentication
+        organization_key: Optional Organization Key (required for v0.2.0+)
         timeout: Request timeout in seconds (default: 30)
 
     Returns:
@@ -167,6 +174,7 @@ def configure(
     return _config.configure(
         base_url=base_url,
         api_key=api_key,
+        organization_key=organization_key,
         timeout=timeout,
     )
 

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/keyrunes_sdk/models.py

@@ -64,6 +64,7 @@ class UserRegistration(BaseModel):
     )
     email: EmailStr = Field(..., description="User email")
     password: str = Field(..., min_length=8, description="Password")
+    namespace: str = Field("default", description="User namespace")
     attributes: Dict[str, Any] = Field(
         default_factory=dict, description="Additional attributes"
     )
@@ -80,11 +81,14 @@ class LoginCredentials(BaseModel):
 
     identity: str = Field(..., description="Username or email")
     password: str = Field(..., description="Password")
+    namespace: str = Field("default", description="User namespace")
 
     @classmethod
-    def from_username(cls, username: str, password: str) -> "LoginCredentials":
+    def from_username(
+        cls, username: str, password: str, namespace: str = "default"
+    ) -> "LoginCredentials":
         """Create from username parameter (for backward compatibility)."""
-        return cls(identity=username, password=password)
+        return cls(identity=username, password=password, namespace=namespace)
 
 
 class GroupCheck(BaseModel):

{keyrunes_python_sdk-0.0.1 → keyrunes_python_sdk-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "keyrunes-python-sdk"
-version = "0.0.1"
+version = "0.2.0"
 description = "Python SDK for Keyrunes Authorization System"
 authors = ["keyrunes <contact@singularjourney.host>"]
 maintainers = ["jonatasoli <contact@jonatasoli.dev>"]
@@ -33,6 +33,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"
@@ -40,12 +41,15 @@ pytest-cov = "^4.1.0"
 pytest-mock = "^3.11.1"
 factory-boy = "^3.3.0"
 faker = "^19.0.0"
-black = "^23.7.0"
+black = "^25.12.0"
 isort = "^5.12.0"
 flake8 = "^6.1.0"
 mypy = "^1.5.0"
 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"]
@@ -64,6 +68,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']