bazis-users 2.3.2__tar.gz → 2.4.0__tar.gz

{bazis_users-2.3.2 → bazis_users-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bazis-users
-Version: 2.3.2
+Version: 2.4.0
 Summary: User management module for Bazis framework.
 Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
 Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
@@ -17,7 +17,7 @@ Classifier: Framework :: Django
 Classifier: Framework :: FastAPI
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: bazis>=2.3.1
+Requires-Dist: bazis>=2.4.0
 Requires-Dist: python-multipart>=0.0.18
 Requires-Dist: PyJWT>=2.10
 Provides-Extra: test

bazis_users-2.4.0/bazis/contrib/users/AGENTS.md

@@ -0,0 +1,61 @@
+# bazis-users — guide for AI agents
+
+Users and authentication by session JWT for Bazis: the user model, the token endpoint,
+and the route base classes that know the current user. Use it whenever an API has users;
+bazis-permit (permissions) and bazis-authing (login flows) build on it.
+
+## Setup
+
+1. A project app with the user model (the package does not create the table itself):
+
+   ```python
+   # users/models.py
+   from bazis.contrib.users.models_abstract import AnonymousUserAbstract, UserAbstract
+   from bazis.core.models_abstract import JsonApiMixin, UuidMixin
+
+   class User(JsonApiMixin, UuidMixin, UserAbstract):
+       pass
+
+   class AnonymousUser(AnonymousUserAbstract):
+       pass
+
+   # users/apps.py
+   from bazis.contrib.users.apps import UsersConfig as UsersConfigBase
+
+   class UsersConfig(UsersConfigBase):
+       name = 'users'
+   ```
+
+2. `BS_INSTALLED_APPS='["users", ...]'`, `BS_AUTH_USER_MODEL=users.User`,
+   `BS_AUTH_ANONYMOUS_USER_MODEL=users.models.AnonymousUser`.
+3. Optionally register the user routes: `router.register('bazis.contrib.users.router')`
+   (`/user/`). With them a user sees and changes only himself, staff create, list and
+   delete users, and only a superuser changes `is_staff`, `is_superuser`, `is_active`.
+   Projects with bazis-permit protect users with a `PermitRouteBase` route instead.
+
+## Authentication
+
+- `POST BAZIS_OPENAPI_TOKEN_URL` (default `/api/openapi-token/`, OAuth2 password form)
+  returns `{"access_token": ..., "token_type": "bearer"}`; Swagger uses it.
+- The token is read from `Authorization: Bearer`, or the query parameter or the cookie
+  named `BAZIS_AUTH_COOKIE_NAME` (default `bazis_auth`). It is an HMAC JWT signed with
+  `SECRET_KEY` with `sub` (username), `iat` and `exp` (`BAZIS_JWT_SESSION_LIFETIME`
+  seconds). A token without
+  `exp` is anonymous; an expired or invalid token is 401.
+- `user.jwt_build()` builds a token (e.g. after a custom login).
+
+## Routes
+
+- `UserRouteBase` (`bazis.contrib.users.routes_abstract`): `self.inject.user` is the user
+  or the anonymous user; the filter context gets `_user`. Base class for routes that need
+  the user (bazis-permit routes extend it).
+- `UserRequiredRouteBase`: the same, for routes that require authentication.
+- FastAPI dependencies in `bazis.contrib.users.service`: `get_user_optional`,
+  `get_user_required`, `get_token_data`.
+
+## Rules
+
+- A user must never be able to change his own groups, permissions or staff flags: keep
+  those fields out of the update schemas of custom user routes, or check them in
+  `hook_after_update` as `UserRouteSet` does.
+- Check `bazis_doctor` after changing the user model (`users.E001`).

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis/contrib/users/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.3.2'
-__version_tuple__ = version_tuple = (2, 3, 2)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
 
-__commit_id__ = commit_id = 'gfa5e68bf1'
+__commit_id__ = commit_id = 'gd67874105'

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis/contrib/users/apps.py

@@ -26,3 +26,7 @@ class UsersConfig(BaseConfig):
 
     name = 'bazis.contrib.users'
     verbose_name = _('Users')
+
+    def ready(self):
+        super().ready()
+        from . import checks  # noqa: F401  registers the system checks

bazis_users-2.4.0/bazis/contrib/users/bazis_manifest.toml

@@ -0,0 +1,45 @@
+# What the package is for and how to use it, for tools and AI agents (see AGENTS.md).
+# `import` paths and `check` ids are verified by tests/test_manifest.py.
+
+[package]
+name = "bazis-users"
+summary = "users, session JWT authentication and routes that know the current user"
+solves = [
+    "user accounts and login by username and password",
+    "authentication by JWT (header, query parameter or cookie)",
+    "routes that need the current user or require authentication",
+]
+requires = ["bazis"]
+pairs_well = ["bazis-permit", "bazis-authing", "bazis-author"]
+
+[[extension_points]]
+name = "UserAbstract"
+import = "bazis.contrib.users.models_abstract.UserAbstract"
+use_when = "the user model of the project (with JsonApiMixin, UuidMixin)"
+
+[[extension_points]]
+name = "UsersConfig"
+import = "bazis.contrib.users.apps.UsersConfig"
+use_when = "the AppConfig of the project app that holds the user model"
+
+[[extension_points]]
+name = "UserRouteBase"
+import = "bazis.contrib.users.routes_abstract.UserRouteBase"
+use_when = "a route that needs the current user (self.inject.user)"
+
+[[extension_points]]
+name = "UserRequiredRouteBase"
+import = "bazis.contrib.users.routes_abstract.UserRequiredRouteBase"
+use_when = "a route that requires authentication"
+
+[[extension_points]]
+name = "get_user_required"
+import = "bazis.contrib.users.service.get_user_required"
+use_when = "a FastAPI dependency for the authenticated user in a custom endpoint"
+
+[[pitfalls]]
+text = "the user model must inherit UserAbstract and be set in BS_AUTH_USER_MODEL"
+check = "users.E001"
+
+[[pitfalls]]
+text = "groups, permissions and is_staff must not be writable by the user himself"

bazis_users-2.4.0/bazis/contrib/users/checks.py

@@ -0,0 +1,48 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Django system checks of bazis-users (see `manage.py bazis_doctor`).
+"""
+
+from django.contrib.auth import get_user_model
+from django.core.checks import Error, register
+from django.core.exceptions import ImproperlyConfigured
+
+
+@register()
+def check_user_model(app_configs, **kwargs):
+    """
+    The session tokens and the user routes need the user model of bazis-users.
+    """
+    from .models_abstract import UserAbstract
+
+    try:
+        user_model = get_user_model()
+    except ImproperlyConfigured as err:
+        return [
+            Error(str(err), hint='Set BS_AUTH_USER_MODEL to an installed model.', id='users.E001')
+        ]
+    if not issubclass(user_model, UserAbstract):
+        return [
+            Error(
+                f'The user model {user_model._meta.label} does not inherit UserAbstract.',
+                hint=(
+                    'Inherit the user model from bazis.contrib.users.models_abstract.UserAbstract '
+                    'and set BS_AUTH_USER_MODEL to it.'
+                ),
+                id='users.E001',
+            )
+        ]
+    return []

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis/contrib/users/routes.py

@@ -23,6 +23,7 @@ from fastapi.security import OAuth2PasswordRequestForm
 from starlette.status import HTTP_401_UNAUTHORIZED
 
 from bazis.core.app import app
+from bazis.core.errors import JsonApi403Exception
 from bazis.core.routes_abstract.initial import inject_make
 from bazis.core.routes_abstract.jsonapi import JsonapiRouteBase
 from bazis.core.schemas import CrudApiAction, SchemaFields, SchemaInclusion, SchemaInclusions
@@ -81,6 +82,52 @@ class UserRouteSet(JsonapiRouteBase):
         ),
     }
 
+    #: the fields only a superuser can set
+    privileged_fields = ('is_staff', 'is_superuser', 'is_active')
+
+    def get_queryset(self):
+        """
+        A user who is not staff sees and changes only himself.
+        """
+        queryset = super().get_queryset()
+        if not self.inject.user.is_staff:
+            queryset = queryset.filter(pk=self.inject.user.pk)
+        return queryset
+
+    def check_privileged_fields(self, item, before: dict):
+        if self.inject.user.is_superuser:
+            return
+        for field in self.privileged_fields:
+            if getattr(item, field) != before[field]:
+                raise JsonApi403Exception(detail=str(_('Only a superuser can change %s')) % field)
+
+    def hook_before_create(self, item):
+        if not self.inject.user.is_staff:
+            raise JsonApi403Exception()
+        super().hook_before_create(item)
+
+    def hook_after_create(self, item):
+        # inside the transaction: the error rolls the creation back
+        super().hook_after_create(item)
+        self.check_privileged_fields(
+            item, {'is_staff': False, 'is_superuser': False, 'is_active': True}
+        )
+
+    def hook_before_update(self, item):
+        super().hook_before_update(item)
+        # the data is not applied yet
+        self._privileged_before = {field: getattr(item, field) for field in self.privileged_fields}
+
+    def hook_after_update(self, item):
+        # inside the transaction: the error rolls the change back
+        super().hook_after_update(item)
+        self.check_privileged_fields(item, self._privileged_before)
+
+    def destroy(self, item_id: str):
+        if not self.inject.user.is_staff:
+            raise JsonApi403Exception()
+        return super().destroy(item_id)
+
     inclusions = {
         CrudApiAction.RETRIEVE: SchemaInclusions(
             origin={

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis_users.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bazis-users
-Version: 2.3.2
+Version: 2.4.0
 Summary: User management module for Bazis framework.
 Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
 Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
@@ -17,7 +17,7 @@ Classifier: Framework :: Django
 Classifier: Framework :: FastAPI
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: bazis>=2.3.1
+Requires-Dist: bazis>=2.4.0
 Requires-Dist: python-multipart>=0.0.18
 Requires-Dist: PyJWT>=2.10
 Provides-Extra: test

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis_users.egg-info/SOURCES.txt

@@ -8,10 +8,13 @@ pytest.ini
 .github/workflows/release.yml
 .github/workflows/tests.yml
 .github/workflows/update-licenses.yml
+bazis/contrib/users/AGENTS.md
 bazis/contrib/users/__init__.py
 bazis/contrib/users/_version.py
 bazis/contrib/users/admin_abstract.py
 bazis/contrib/users/apps.py
+bazis/contrib/users/bazis_manifest.toml
+bazis/contrib/users/checks.py
 bazis/contrib/users/conf.py
 bazis/contrib/users/middleware.py
 bazis/contrib/users/models.py
@@ -52,6 +55,7 @@ docs/_templates/custom-module-template.rst
 docs/releases/2.3.0.md
 docs/releases/2.3.1.md
 docs/releases/2.3.2.md
+docs/releases/2.4.0.md
 sample/manage.py
 sample/project.env
 sample/pyproject.toml
@@ -87,6 +91,8 @@ sample/users/migrations/__init__.py
 tests/__init__.py
 tests/conftest.py
 tests/factories.py
+tests/test_manifest.py
 tests/test_protected.py
 tests/test_tokens.py
+tests/test_user_access.py
 tests/test_users.py

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis_users.egg-info/requires.txt

@@ -1,4 +1,4 @@
-bazis>=2.3.1
+bazis>=2.4.0
 python-multipart>=0.0.18
 PyJWT>=2.10
 

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis_users.egg-info/scm_file_list.json

@@ -8,9 +8,12 @@
     ".gitignore",
     "CLAUDE.md",
     "README.md",
+    "bazis/contrib/users/AGENTS.md",
     "bazis/contrib/users/__init__.py",
     "bazis/contrib/users/admin_abstract.py",
     "bazis/contrib/users/apps.py",
+    "bazis/contrib/users/bazis_manifest.toml",
+    "bazis/contrib/users/checks.py",
     "bazis/contrib/users/conf.py",
     "bazis/contrib/users/locale/en/LC_MESSAGES/django.mo",
     "bazis/contrib/users/locale/en/LC_MESSAGES/django.po",
@@ -41,6 +44,7 @@
     "docs/releases/2.3.0.md",
     "docs/releases/2.3.1.md",
     "docs/releases/2.3.2.md",
+    "docs/releases/2.4.0.md",
     "docs/requirements.txt",
     "docs/settings.py",
     "docs/structure.rst",
@@ -81,8 +85,10 @@
     "tests/__init__.py",
     "tests/conftest.py",
     "tests/factories.py",
+    "tests/test_manifest.py",
     "tests/test_protected.py",
     "tests/test_tokens.py",
+    "tests/test_user_access.py",
     "tests/test_users.py"
   ]
 }

{bazis_users-2.3.2 → bazis_users-2.4.0}/bazis_users.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "2.3.2",
+  "tag": "2.4.0",
   "distance": 0,
-  "node": "gfa5e68bf11f081b876fbfebf90cdac9a6b124dcb",
+  "node": "gd67874105fc4269a9dafbb50167cb91ed2720884",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-01"

bazis_users-2.4.0/docs/releases/2.4.0.md

@@ -0,0 +1,20 @@
+# bazis-users 2.4.0
+
+Requires Bazis 2.4.
+
+## Security
+
+- **Any authenticated user could take over any account through the user routes**
+  (`bazis.contrib.users.router`, `UserRouteSet`): list all users, change any user,
+  including his password (`raw_password`) and `is_staff` / `is_superuser`, and delete
+  users. Now a user who is not staff sees and changes only himself; only staff create and
+  delete users; only a superuser changes `is_staff`, `is_superuser` and `is_active`
+  (403 otherwise). Projects that let users manage other users through these routes must
+  give them staff status.
+
+## Tools and AI agents
+
+- The package ships `AGENTS.md` (how to set up users and authentication) and
+  `bazis_manifest.toml` for tools and AI agents (see `docs/agents.md` of Bazis).
+- New system check `users.E001`: the user model does not inherit `UserAbstract`
+  (`manage.py bazis_doctor`).

{bazis_users-2.3.2 → bazis_users-2.4.0}/pyproject.toml

@@ -33,7 +33,7 @@ classifiers = [
     "Framework :: FastAPI",
 ]
 dependencies = [
-    "bazis>=2.3.1",
+    "bazis>=2.4.0",
     "python-multipart>=0.0.18",
     "PyJWT>=2.10",
 ]

bazis_users-2.4.0/tests/test_manifest.py

@@ -0,0 +1,35 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from bazis.contrib.users.checks import check_user_model
+from bazis.core.introspect import packages, validate_manifest
+
+
+def test_manifest_is_valid():
+    assert validate_manifest('bazis.contrib.users') == []
+
+
+def test_manifest_is_found():
+    users = {it['name']: it for it in packages()}['bazis-users']
+    assert users['module'] == 'bazis.contrib.users'
+    assert users['manifest']['package']['name'] == 'bazis-users'
+
+
+def test_user_model_check(monkeypatch):
+    assert check_user_model(None) == []
+
+    from django.contrib.auth.models import Group
+
+    monkeypatch.setattr('bazis.contrib.users.checks.get_user_model', lambda: Group)
+    assert [it.id for it in check_user_model(None)] == ['users.E001']

bazis_users-2.4.0/tests/test_user_access.py

@@ -0,0 +1,113 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+from bazis_test_utils.utils import get_api_client
+
+from bazis.contrib.users import get_user_model
+
+
+User = get_user_model()
+
+
+def _patch(user, **attributes) -> dict:
+    return {
+        'data': {
+            'id': str(user.id),
+            'type': 'users.user',
+            'bs:action': 'change',
+            'attributes': attributes,
+        }
+    }
+
+
+@pytest.fixture
+def people():
+    superuser = User.objects.create_superuser('root', password='weak_password_1')
+    staff = User.objects.create_user('staff', password='weak_password_2', is_staff=True)
+    user = User.objects.create_user('user', password='weak_password_3')
+    other = User.objects.create_user('other', password='weak_password_4')
+    return superuser, staff, user, other
+
+
+@pytest.mark.django_db(transaction=True)
+def test_user_sees_and_changes_only_himself(sample_app, people):
+    """
+    Any authenticated user could list, change (including the password) and delete any
+    user through the user routes.
+    """
+    _, _, user, other = people
+    client = get_api_client(sample_app, user.jwt_build())
+
+    response = client.get('/api/v1/users/user/')
+    assert [it['id'] for it in response.json()['data']] == [str(user.id)]
+    assert client.get(f'/api/v1/users/user/{other.id}/').status_code == 404
+
+    response = client.patch(
+        f'/api/v1/users/user/{other.id}/', json_data=_patch(other, raw_password='hijacked1')
+    )
+    assert response.status_code == 404
+    other.refresh_from_db()
+    assert other.check_password('weak_password_4')
+
+    response = client.patch(f'/api/v1/users/user/{user.id}/', json_data=_patch(user, first_name='Me'))
+    assert response.status_code == 200
+
+    assert client.delete(f'/api/v1/users/user/{user.id}/').status_code == 403
+    assert User.objects.filter(id=user.id).exists()
+
+
+@pytest.mark.django_db(transaction=True)
+@pytest.mark.parametrize('field', ['is_staff', 'is_superuser', 'is_active'])
+def test_only_superuser_changes_privileges(sample_app, people, field):
+    superuser, staff, user, _ = people
+    value = field != 'is_active'
+
+    for actor in (user, staff):
+        response = get_api_client(sample_app, actor.jwt_build()).patch(
+            f'/api/v1/users/user/{user.id}/', json_data=_patch(user, **{field: value})
+        )
+        assert response.status_code == 403
+        user.refresh_from_db()
+        assert getattr(user, field) is not value
+
+    response = get_api_client(sample_app, superuser.jwt_build()).patch(
+        f'/api/v1/users/user/{user.id}/', json_data=_patch(user, **{field: value})
+    )
+    assert response.status_code == 200
+    user.refresh_from_db()
+    assert getattr(user, field) is value
+
+
+@pytest.mark.django_db(transaction=True)
+def test_only_staff_creates_users(sample_app, people):
+    _, staff, user, _ = people
+    payload = {
+        'data': {
+            'type': 'users.user',
+            'bs:action': 'add',
+            'attributes': {'username': 'new', 'raw_password': 'weak_password_5'},
+        }
+    }
+    response = get_api_client(sample_app, user.jwt_build()).post('/api/v1/users/user/', json_data=payload)
+    assert response.status_code == 403
+
+    payload['data']['attributes']['is_superuser'] = True
+    response = get_api_client(sample_app, staff.jwt_build()).post('/api/v1/users/user/', json_data=payload)
+    assert response.status_code == 403
+    assert not User.objects.filter(username='new').exists()
+
+    del payload['data']['attributes']['is_superuser']
+    response = get_api_client(sample_app, staff.jwt_build()).post('/api/v1/users/user/', json_data=payload)
+    assert response.status_code == 201