keyrunes-python-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

keyrunes_python_sdk-0.5.0/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+All notable changes to the Keyrunes Python SDK.
+
+Generated by `git-cliff` from the conventional commits — each commit body
+becomes the text of its entry. **Do not edit by hand**: the next run overwrites
+it. To change an entry, reword the commit message (`git rebase -i`); to change
+the shape, edit `cliff.toml` and run `poetry run task changelog`.
+
+## [0.5.0] - 2026-11-04
+
+### Fixed
+
+- **security**: verify self group checks against the server and pin the privileged-group set (reported by Rathnadeepan / HotWater @HotWater-015)
+
+  has_group used to answer for the authenticated user straight from the
+  JWT claims the client decoded with verify_signature=False, so a forged
+  token granted any group locally. Self checks now hit GET /api/me with
+  the bearer token and fail closed. The is_admin heuristic that granted
+  admin to any group whose name merely contained 'admin' (e.g.
+  'non-admin') is replaced by exact membership in
+  {admin, admins, superadmin}. refresh_token now sends the Authorization
+  header the server's require_jwt middleware needs (it was 401 on every
+  call). Registration/login model defaults move from 'default' to the
+  server's actual default namespace 'public'. register_admin documents
+  that server >= 0.4.2 ignores admin_key at /api/register.
+
+- **security**: build the request URL from the base instead of joining it
+
+  urljoin() lets a second argument that looks like a URL replace the base
+  completely: an endpoint of "A:" produced the relative URL "A:" and an
+  endpoint of "https://elsewhere.test/x" would have sent the request (and
+  the Authorization header) to another host. The URL is now built from the
+  configured base and the endpoint path, so an endpoint can never point the
+  request somewhere else.
+
+  The fuzz suite caught it: hypothesis stores the failing example, so the
+  invariant "an arbitrary endpoint still yields an absolute URL" is now
+  pinned by a regression test.
+
+### Documentation
+
+- **client**: put the groups comment back in English
+
+  Every comment and docstring in this SDK is in English, and this one was not.
+  It went in today with the malformed-`groups` fix, in the same session where the
+  commit messages also drifted to Portuguese — same slip, different file.
+
+- **changelog**: put cliff.toml and its output in English
+
+  Everything else in this repository is in English — code, comments, docstrings,
+  and every commit message. The `cliff.toml` written earlier today was not: a
+  Portuguese header, Portuguese group names and Portuguese comments, which put
+  eight Portuguese lines into an otherwise English generated changelog.
+
+  Group names follow Keep a Changelog, which is what the hand-written file used
+  before it was generated: Added, Fixed, Performance, Refactored, Testing,
+  Documentation, Infrastructure, Maintenance, Other.
+
+  One thing changes besides the language: a `.*` catch-all parser. Without it a
+  commit that follows no convention is dropped without a trace, and a changelog
+  that looks complete while omitting work is the failure worth guarding against.
+
+- **client**: point the register_admin deprecation at the 0.5.0 release
+
+  The docstring still advertised 0.2.2, a version that never shipped the
+  deprecation. The method is deprecated since the release that carries the
+  server 0.4.2 hardening.
+
+
+## [0.4.0] - 2026-09-15
+
+### Added
+
+- **client**: change_password, which the API served and the SDK did not expose
+
+  `POST /api/user/change-password` has been in Keyrunes all along. The SDK exposed
+  `login`, `refresh_token`, `register_user` and the group queries — and not this
+  one.
+
+  Whoever needed it built the HTTP call by hand: that is what happened downstream
+  in PlayfulLMS, and before that the conclusion was worse — reading only the SDK's
+  surface, the operation was written off as nonexistent, and the platform nearly
+  told people to change their password at the provider instead.
+
+  **Details that cost you if read wrong**
+
+  `/api/user/change-password`, and **not** `/api/change-password`: the router
+  registers the first. The handler behind the second is dead code marked
+  `#[allow(dead_code)]`, and pointing at it answers 404.
+
+  The server answers errors as **plain text** (`e.to_string()`), not JSON — treat
+  it as JSON and you get a parsing exception instead of the sentence explaining
+  what went wrong.
+
+  The error is **400**, not 401, which is why it becomes `NetworkError`: that is
+  the class this SDK already uses for everything that is not 401/403/404. Changing
+  it here would change the contract for every caller because of one endpoint. The
+  server's wording survives, which is what matters — "invalid current password"
+  and "password too short" call for opposite fixes.
+
+  Without a token it refuses **before** sending: the server decides whose password
+  it is from the token, and nothing in the body chooses that.
+
+  And the effect that closes the loop: the server clears `first_login` on a
+  change — the origin of the `requires_password_change` the login reports. It is
+  in the docstring because callers need to know there is no second call to make.
+
+  Verified against a real Keyrunes, not only against a double: register, change,
+  and then the old password refused (401) and the new one accepted (200), with
+  `first_login` cleared.
+
+### Fixed
+
+- **client**: contain a malformed `groups` instead of taking the client down
+
+  The repository's own fuzz suite found it: with `{"groups": true}` in the server
+  response, normalization raised
+  `TypeError: argument of type 'bool' is not a container or iterable`.
+
+  `data.get("groups", []) or []` handles null and empty, and **nothing else**:
+  `True or []` is `True`, which survives all the way to the `"admins" in groups`
+  just below.
+
+  A client that falls over on a malformed response is worse than one that ignores
+  it: whoever consumes the SDK sees a type error coming from inside the library,
+  far from the cause, and nothing points at the server as the origin.
+
+  Pre-existing — `git stash` and the failure stays. Detection measured: putting
+  the `or []` back fails the fuzz test.
+
+- **deps**: pyjwt 2.10.1 → 2.14.0 and idna 3.11 → 3.19 (OSV advisories)
+
+  The `safety` hook does not run on this machine — it asks for an interactive
+  login and dies with `EOF when reading a line`. Rather than skip the security
+  check and move on, the 90 versions pinned in `poetry.lock` were run against the
+  OSV database.
+
+  Two findings in the runtime tree:
+
+  - `pyjwt` 2.10.1: nine advisories, four of them high severity. In an
+    authentication library this is the dependency that matters most. Fixed in
+    2.13.0; `pyproject` already declared `^2.9.0`, so no API changes — only the
+    lock.
+  - `idna` 3.11: two moderate advisories, fixed in 3.15. Arrives through `httpx`.
+
+  After the update the runtime tree carries no known advisory. The 194 tests pass
+  unchanged.
+
+  What remains are advisories in the development tree — `authlib`, `nltk`,
+  `cryptography`, `requests`, `urllib3` — and it is worth saying where they come
+  from: **every one of them is a dependency of `safety` itself**. The scanner that
+  cannot run is also the largest source of vulnerable packages in the environment.
+  They are left alone: they are development-only, they do not ship in the
+  published package, and resolving it means deciding whether `safety` stays.
+
+### Documentation
+
+- **changelog**: record under 0.4.0 the two commits that landed after the tag
+
+  The `v0.4.0` tag sat on `chore(release): 0.4.0`, and two commits went in after
+  it: the malformed-`groups` fix and dropping `towncrier`. Since the tag was
+  **not published** (the remote does not have it), the fix can still go into 0.4.0
+  rather than forcing a 0.4.1 — and it should, because it is a `TypeError`
+  escaping the SDK.
+
+- **changelog**: generate CHANGELOG.md with git-cliff, commit body included
+
+  The changelog in this repository was written by hand. The first attempt at
+  switching to generation was measured and **thrown away**: with git-cliff's
+  default template, which uses only the subject line, the file dropped from 246 to
+  61 lines — the "what" survived and the "why" disappeared.
+
+  What fixes it is including the commit **body**. The messages here already
+  explain the decision, so the information was never only in the changelog: it was
+  duplicated. The generated file now runs to 222 lines, and every entry carries
+  the text that explains it.
+
+  Three details in `cliff.toml`, each from a defect visible in the output:
+
+  - `indent(prefix="  ", first=true, blank=false)` on the body. Without
+    `first=true` the body's first line falls outside the list item; with
+    `blank=true` the empty lines pick up two spaces and the `trailing-whitespace`
+    hook fails the commit.
+  - A postprocessor demotes to bold any `#` heading arriving inside a body —
+    indented, ATX is still a heading (it allows up to three leading spaces) and
+    would collide with the changelog's own levels. The pattern uses `[ \t]` and
+    **not** `\s`: `\s` matches `\n`, and in the first version it reached across
+    the line break and ate the changelog's own `## [0.4.0]`, which turned bold.
+  - Another postprocessor puts a blank line before each `## [version]`, because
+    `trim = true` glues the heading to the last line of the previous release.
+
+  Two sections shrink, and it is worth naming them: **0.1.0** (81 → 7 lines) was
+  an inventory of the API — the same thing the README already carries — and
+  **0.3.0** (55 → 11) loses the detail of the four contract bugs, because that
+  release's commit has a short body. The old text stays recoverable in git
+  history. From here the rule is different: the commit body is the source, so a
+  thin message makes a thin entry.
+
+  Along with it:
+
+  - `task changelog` generates and `task changelog-check` fails when the file is
+    out of date with the commits (a CI gate).
+  - `NEWS.rst` goes. It was a third changelog, in the format towncrier would
+    produce, with nothing generating it and nothing referencing it — a dead file
+    for the same reason towncrier left in the previous commit.
+
+  One honest caveat: that commit's body ends by saying "the changelog in this
+  repository is written by hand". It was true when written and stopped being true
+  now; a changelog is a historical record, and rewording the message to hide that
+  would cost rewriting already-published history.
+
+### Maintenance
+
+- **deps**: drop towncrier, declared and never configured
+
+  `towncrier` had been a dev dependency from before, **without a
+  `[tool.towncrier]` section** in `pyproject.toml`, without a `towncrier.toml` and
+  without a fragments directory. Running it fails: "the config file does not
+  contain 'version' or 'package'".
+
+  `NEWS.rst` is in the format it *would* produce, which is worse than having
+  nothing: whoever arrives concludes the file is generated and leaves it alone, or
+  tries to run the tool and finds out it cannot. That happened here today — the
+  changelog was written by hand without noticing there was a tool declared.
+
+  A declared, unused dependency is the same family as dead code. The changelog in
+  this repository is written by hand, and now `pyproject.toml` says so.
+
+
+## [0.3.1] - 2026-09-04
+
+### Fixed
+
+- **deps**: move mutmut out of the runtime dependencies; release 0.3.1
+
+  mutmut was declared in [tool.poetry.dependencies] rather than the dev group,
+  so installing this SDK pulled a mutation-testing tool and its whole tree
+  (libcst, textual, rich, setproctitle, pyyaml-ft, markdown-it-py,
+  mdit-py-plugins, mdurl, linkify-it-py, sortedcontainers) into every consumer,
+  production images included.
+
+  Nothing in keyrunes_sdk imports it, so upgrading only removes packages. The
+  wheel now declares httpx, pydantic[email] and pyjwt and nothing else.
+
+  Affected 0.2.0 and 0.3.0.
+
+
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- **client**: carry the full server identity and add refresh; release 0.3.0
+
+  Migrating a real consumer (an LMS keying its user rows off the JWT `sub`)
+  surfaced four contract bugs against a live Keyrunes server and three fields
+  the SDK was discarding.
+
+
+## [0.2.0] - 2026-09-03
+
+### Added
+
+- **tests**: add property-based, fuzz and contract suites; release 0.2.0
+
+  Add three new test suites and the tooling to measure them:
+
+  - tests/test_property_based.py (24 tests): Hypothesis invariants over base
+    URL normalization, _normalize_user id precedence and is_admin derivation,
+    JWT claim parsing, request URL construction, status-to-exception mapping
+    and model validation bounds.
+  - tests/test_fuzz.py (19 tests): hostile-input crawl of the public surface
+    asserting only KeyrunesError and pydantic ValidationError ever escape.
+  - tests/test_request_contract.py (33 tests): mocks only the httpx transport
+    so the method, URL, headers and JSON body put on the wire are asserted.
+
+  Hypothesis profiles (fast/dev/ci) are selected with HYPOTHESIS_PROFILE;
+  fast is derandomized and database-free so mutmut judges every mutant
+  against identical examples.
+
+  Two defects the new suites uncovered are fixed:
+
+  - A 2xx response with a non-JSON body raised a raw ValueError out of
+    _make_request. It is now wrapped in NetworkError.
+  - get_user, get_current_user and has_group carried unreachable
+    "except UserNotFoundError" fallbacks that re-tested a condition already
+    forced by an early return, swallowing genuine server 404s. Removed, and
+    the duplicated claims-to-User block extracted into
+    _user_from_token_claims().
+
+### Maintenance
+
+- add changelogs
+
+- update lib version in pyproject
+
+- add pypi url in README
+
+
+## [0.1.0] - 2026-01-03
+
+### Added
+
+- add organization key for keyrunes v0.2.0
+
+
+## [0.0.1] - 2025-12-08
+
+### Added
+
+- add login, register, check_admin, check_user, get_current_user features
+
+### Fixed
+
+- fix lib version
+
+### Infrastructure
+
+- fix lint errors and add pre-commit
+
+### Maintenance
+
+- add changelogs
+
+### Other
+
+- Initial commit
+
+
+<!-- generated by git-cliff -->

{keyrunes_python_sdk-0.4.0 → keyrunes_python_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keyrunes-python-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python SDK for Keyrunes Authorization System
 License: AGPL
 License-File: LICENSE

{keyrunes_python_sdk-0.4.0 → keyrunes_python_sdk-0.5.0}/keyrunes_sdk/client.py

@@ -2,7 +2,6 @@
 
 import os
 from typing import Any, Dict, List, Optional
-from urllib.parse import urljoin
 
 import httpx
 import jwt
@@ -42,6 +41,12 @@ ENDPOINT_REFRESH_TOKEN = "/api/refresh-token"
 #: ``#[allow(dead_code)]``. Pointing at it answers 404.
 ENDPOINT_CHANGE_PASSWORD = "/api/user/change-password"
 
+#: Group names that carry administrative rights in the Keyrunes server.
+#: Matching is EXACT: a substring test ("admin" in g.lower()) used to treat
+#: "non-admin" or "billing-admin-viewer" as privileged — a user created in
+#: any such group passed ``@require_admin``.
+PRIVILEGED_GROUPS = frozenset({"admin", "admins", "superadmin"})
+
 
 class KeyrunesClient:
     """
@@ -102,6 +107,7 @@ class KeyrunesClient:
         data: Optional[Dict[str, Any]] = None,
         params: Optional[Dict[str, Any]] = None,
         use_auth: bool = True,
+        headers: Optional[Dict[str, str]] = None,
     ) -> Dict[str, Any]:
         """
         Make HTTP request to Keyrunes API.
@@ -112,6 +118,11 @@ class KeyrunesClient:
             data: Request body data
             params: Query parameters
             use_auth: Whether to include authentication header
+            headers: Extra per-call headers. An ``Authorization`` given here
+                wins over the stored client token — used by
+                ``refresh_token``, which must authenticate with the token
+                being exchanged even when the client already holds another
+                one.
 
         Returns:
             Response JSON data
@@ -121,11 +132,11 @@ class KeyrunesClient:
             AuthenticationError: If authentication fails (401)
             AuthorizationError: If authorization fails (403)
         """
-        url = urljoin(self.base_url + "/", endpoint.lstrip("/"))
-        headers = {}
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        request_headers: Dict[str, str] = dict(headers or {})
 
-        if use_auth and self._token:
-            headers["Authorization"] = f"Bearer {self._token}"
+        if use_auth and self._token and "Authorization" not in request_headers:
+            request_headers["Authorization"] = f"Bearer {self._token}"
 
         try:
             response = self._client.request(
@@ -133,7 +144,7 @@ class KeyrunesClient:
                 url=url,
                 json=data,
                 params=params,
-                headers=headers,
+                headers=request_headers,
             )
 
             if response.status_code == 401:
@@ -182,10 +193,11 @@ class KeyrunesClient:
         )
         normalized["username"] = data.get("username", "")
         normalized["email"] = data.get("email", "")
-        # `or []` trata nulo e vazio, e **não** trata o resto: com
-        # ``{"groups": true}`` o valor sobrevivia como ``True``, e o
-        # ``"admins" in groups`` logo abaixo estourava ``TypeError`` — o cliente
-        # caía em vez de conter uma resposta malformada. Achado pelo fuzzer.
+        # `or []` handles null and empty and **nothing else**: with
+        # ``{"groups": true}`` the value survived as ``True``, and the
+        # ``"admins" in groups`` just below raised ``TypeError`` — the client
+        # fell over instead of containing a malformed response. Found by the
+        # fuzz suite.
         raw_groups = data.get("groups")
         normalized["groups"] = (
             list(raw_groups) if isinstance(raw_groups, list) else []
@@ -194,10 +206,13 @@ class KeyrunesClient:
         normalized["is_active"] = data.get("is_active", True)
         groups = normalized["groups"]
         is_admin_flag = data.get("is_admin", False)
-        has_admin_group = "admins" in groups or "superadmin" in groups
-        has_admin_in_name = any("admin" in str(g).lower() for g in groups)
-        normalized["is_admin"] = (
-            is_admin_flag or has_admin_group or has_admin_in_name
+        # Exact membership only. The previous heuristic (`"admin" in
+        # str(g).lower()`) granted admin privileges to any group whose name
+        # merely *contained* "admin" — "non-admin", "billing-admin-viewer"
+        # and friends all unlocked @require_admin. "admins" stays in the set
+        # because server fixtures still seed that legacy spelling.
+        normalized["is_admin"] = bool(is_admin_flag) or any(
+            isinstance(g, str) and g in PRIVILEGED_GROUPS for g in groups
         )
         # Carried through untouched so a caller can key its own records off the
         # same identifier the JWT ``sub`` uses, rather than off ``id``.
@@ -400,6 +415,16 @@ class KeyrunesClient:
         """
         Register a new admin user.
 
+        .. deprecated:: 0.5.0
+            Since Keyrunes server 0.4.2 (C11-008 remediation) ``POST
+            /api/register`` **ignores** ``admin_key`` and never promotes the
+            registrant: the endpoint only ever creates a normal user.
+            Administrators must be created through an authenticated
+            ``POST /api/admin/user`` (with the caller's JWT) or through the
+            server's CLI bootstrap. This method is kept so existing code
+            still calls a registered endpoint, but do not expect the
+            returned user to hold any privilege.
+
         Args:
             username: Username (3-50 characters)
             email: Admin email address
@@ -471,10 +496,17 @@ class KeyrunesClient:
         )
 
         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
+            # SECURITY: the JWT held by this client was decoded with
+            # ``verify_signature=False`` — anyone can mint one claiming any
+            # group. The claims said nothing about whether the server still
+            # accepts this token, so the answer comes from ``/api/me``,
+            # which only a live, valid token can query. Fail closed: a 404
+            # from the server means no access, it does not raise.
+            try:
+                user = self.get_current_user(force_refresh=True)
+            except UserNotFoundError:
+                return False
+            return group_id in user.groups
 
         try:
             response = self._make_request(
@@ -628,11 +660,15 @@ class KeyrunesClient:
         if not current:
             raise InvalidTokenError("No token available to refresh.")
 
+        # The server binds the refreshed identity to the token in the
+        # Authorization header (require_jwt middleware) and ignores the body
+        # since the 0.4.1 fix. Authenticate with the token being exchanged.
         response = self._make_request(
             "POST",
             ENDPOINT_REFRESH_TOKEN,
             data={"token": current},
             use_auth=False,
+            headers={"Authorization": f"Bearer {current}"},
         )
 
         refreshed = self._parse_token_response(response)

{keyrunes_python_sdk-0.4.0 → keyrunes_python_sdk-0.5.0}/keyrunes_sdk/decorators.py

@@ -3,7 +3,7 @@
 from functools import wraps
 from typing import Any, Callable, Optional
 
-from keyrunes_sdk.client import KeyrunesClient
+from keyrunes_sdk.client import PRIVILEGED_GROUPS, KeyrunesClient
 from keyrunes_sdk.exceptions import AuthorizationError, UserNotFoundError
 
 
@@ -218,11 +218,14 @@ def require_admin(
                     if keyrunes_client._token_data
                     else []
                 )
-                is_admin = (
-                    "admins" in groups
-                    or "superadmin" in groups
-                    or any("admin" in str(g).lower() for g in groups)
-                )
+                # Exact membership only. The old heuristic treated ANY
+                # group whose name contained the substring "admin"
+                # ("non-admin", "billing-admin-viewer") as admin — a
+                # group-name collision silently granted privileges.
+                # KeyRunes' own names are "admin" and "superadmin";
+                # "admins" is kept because deployments and the SDK
+                # fixtures historically use it.
+                is_admin = any(g in PRIVILEGED_GROUPS for g in groups)
                 if not is_admin:
                     raise AuthorizationError(
                         f"User '{user_id}' does not have admin privileges."

{keyrunes_python_sdk-0.4.0 → keyrunes_python_sdk-0.5.0}/keyrunes_sdk/models.py

@@ -85,7 +85,9 @@ class UserRegistration(BaseModel):
     )
     email: EmailStr = Field(..., description="User email")
     password: str = Field(..., min_length=8, description="Password")
-    namespace: str = Field("default", description="User namespace")
+    # The server's default tenant is "public", not "default"; a payload that
+    # registered into "default" created a stray namespace nobody configured.
+    namespace: str = Field("public", description="User namespace")
     attributes: Dict[str, Any] = Field(
         default_factory=dict, description="Additional attributes"
     )
@@ -102,11 +104,12 @@ class LoginCredentials(BaseModel):
 
     identity: str = Field(..., description="Username or email")
     password: str = Field(..., description="Password")
-    namespace: str = Field("default", description="User namespace")
+    # "public" is the server's default tenant; see UserRegistration.namespace.
+    namespace: str = Field("public", description="User namespace")
 
     @classmethod
     def from_username(
-        cls, username: str, password: str, namespace: str = "default"
+        cls, username: str, password: str, namespace: str = "public"
     ) -> "LoginCredentials":
         """Create from username parameter (for backward compatibility)."""
         return cls(identity=username, password=password, namespace=namespace)

{keyrunes_python_sdk-0.4.0 → keyrunes_python_sdk-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "keyrunes-python-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Python SDK for Keyrunes Authorization System"
 authors = ["keyrunes <contact@singularjourney.host>"]
 maintainers = ["jonatasoli <contact@jonatasoli.dev>"]
@@ -121,5 +121,7 @@ publish = "poetry build && twine check dist/* && poetry publish"
 version-patch = "poetry version patch"
 version-minor = "poetry version minor"
 version-major = "poetry version major"
+changelog = "git cliff -o CHANGELOG.md"
+changelog-check = "git cliff -o /dev/stdout | diff -q - CHANGELOG.md"
 all = "poetry run task format && poetry run task lint && poetry run task type-check && poetry run task test"
 ci = "poetry run task lint && poetry run task type-check && poetry run task test"

keyrunes_python_sdk-0.4.0/CHANGELOG.md

@@ -1,271 +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.4.0] - 2026-09-15
-
-### Added
-
-- `KeyrunesClient.change_password(current_password, new_password)`, wrapping
-  `POST /api/user/change-password`. The server has served this endpoint all
-  along; the SDK exposed `login`, `refresh_token`, `register_user` and the group
-  queries, and not this one. Anyone who needed it built the HTTP call by hand —
-  which is what happened downstream, after first concluding from the SDK's
-  surface that the operation did not exist at all.
-
-  Three details the endpoint carries, and each one bites if read wrong:
-
-  - it lives at `/api/user/change-password`, **not** `/api/change-password` —
-    the router registers the first, and the handler behind the second is dead
-    code marked `#[allow(dead_code)]`, so pointing at it answers 404;
-  - it answers errors as **plain text** (`e.to_string()`), not JSON, and with
-    status **400** rather than 401 — so this client raises `NetworkError`, the
-    same class it already uses for every non-401/403/404 status, and preserves
-    the server's own wording, because "invalid current password" and "password
-    too short" call for opposite fixes;
-  - changing the password clears the account's `first_login` flag server-side,
-    which is what `requires_password_change` reports at login. There is no
-    second call to make.
-
-  Without a token the client refuses before sending: the server decides whose
-  password it is from the token, and nothing in the body chooses that.
-
-### Fixed
-
-- A malformed `groups` field in a server response no longer crashes the client.
-  `get_current_user` and `check_user` called `list(data["groups"])` on whatever
-  came back; a JSON `true`, a number, or `null` raised `TypeError: 'bool' object
-  is not iterable` out of the SDK, from a line that reads like a safe coercion.
-  Anything that is not a JSON array is now read as no groups. Found by the fuzz
-  suite, and it predates this release — `git stash` confirmed it on the previous
-  tag.
-
-### Security
-
-- `pyjwt` 2.10.1 → 2.14.0 and `idna` 3.11 → 3.19 in the lockfile. Both are
-  runtime dependencies (`idna` arrives through `httpx`), and OSV reports known
-  advisories against the pinned versions — nine for `pyjwt`, four of them high.
-  The declared constraint was already `^2.9.0`, so this is a lockfile refresh
-  with no API change; the 194 tests pass unchanged.
-
-### Removed
-
-- `towncrier` left the dev dependencies. It was declared and never configured:
-  no `[tool.towncrier]` section, no `newsfragments/` directory, and this
-  changelog was written by hand. A tool nobody runs still gets installed,
-  resolved, and audited on every environment build.
-
-## [0.3.1] - 2026-09-04
-
-### Fixed
-
-- `mutmut` is no longer a runtime dependency. It was declared in
-  `[tool.poetry.dependencies]` instead of the dev group, so installing this SDK
-  pulled a mutation-testing tool and its whole tree — `libcst`, `textual`,
-  `rich`, `setproctitle`, `pyyaml-ft`, `markdown-it-py`, `mdit-py-plugins`,
-  `mdurl`, `linkify-it-py`, `sortedcontainers` — into every consumer, including
-  production images. Affected 0.2.0 and 0.3.0; nothing in the library imported
-  it, so upgrading only removes packages.
-
-## [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).