simple-module-users 0.0.33__tar.gz → 0.0.35__tar.gz

{simple_module_users-0.0.33 → simple_module_users-0.0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_users
-Version: 0.0.33
+Version: 0.0.35
 Summary: Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -24,11 +24,11 @@ Requires-Python: >=3.12
 Requires-Dist: aiosmtplib>=3.0
 Requires-Dist: cachetools>=5.3
 Requires-Dist: fastapi-users[oauth,sqlalchemy]<16,>=15
-Requires-Dist: simple-module-auth==0.0.33
-Requires-Dist: simple-module-core==0.0.33
-Requires-Dist: simple-module-db==0.0.33
-Requires-Dist: simple-module-hosting==0.0.33
-Requires-Dist: simple-module-settings==0.0.33
+Requires-Dist: simple-module-auth==0.0.35
+Requires-Dist: simple-module-core==0.0.35
+Requires-Dist: simple-module-db==0.0.35
+Requires-Dist: simple-module-hosting==0.0.35
+Requires-Dist: simple-module-settings==0.0.35
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 
@@ -53,6 +53,7 @@ Pre-wired into any app scaffolded with `smpy new`.
 - `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
+- Demo mode — one-click, read-only shared **admin** and **standard user** accounts on the sign-in card, for public showcase instances.
 
 ## Usage
 
@@ -85,6 +86,33 @@ async def profile(user: CurrentUser):
 - `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_settings`, `simple_module_auth`
 - `fastapi-users[sqlalchemy,oauth]>=15,<16`, `aiosmtplib`, `cachetools`, `typer`
 
+## Demo mode
+
+For hosting a public showcase instance. Set under **/admin/settings/ → Users**:
+
+```
+demo_mode        = true
+demo_admin_email = demo-admin@example.com
+demo_user_email  = demo-user@example.com
+demo_read_only   = true    # default — keep it on
+```
+
+The sign-in card grows one button per configured account — **Explore as an
+administrator** and **Explore as a standard user** — each posting to
+`POST /api/users/auth/demo/{role}`. Neither account's password reaches the
+browser. Two accounts because the admin surface is what the framework is for
+and the end-user app is what you build with it; a visitor can switch between
+them without signing out. Blank either email to offer only the other; that
+closes its route too, not just its button.
+
+Both accounts are seeded (and reconciled) at boot and on every settings
+reload, and while `demo_read_only` is on, `DemoReadOnlyMiddleware` refuses
+every unsafe HTTP method from either demo session — everyone else on the
+instance is unaffected. A standing banner tells the visitor they are in a demo.
+
+Full detail, including the `demo_read_only = false` warning, is in
+[docs/modules/users.md](../../docs/modules/users.md#demo-mode-hosting-a-showcase-instance).
+
 ## Social sign-in (Google, GitHub, Microsoft, OIDC)
 
 OAuth providers are configured in the admin UI at **/settings/modules → Users**

{simple_module_users-0.0.33 → simple_module_users-0.0.35}/README.md

@@ -19,6 +19,7 @@ Pre-wired into any app scaffolded with `smpy new`.
 - `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
+- Demo mode — one-click, read-only shared **admin** and **standard user** accounts on the sign-in card, for public showcase instances.
 
 ## Usage
 
@@ -51,6 +52,33 @@ async def profile(user: CurrentUser):
 - `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_settings`, `simple_module_auth`
 - `fastapi-users[sqlalchemy,oauth]>=15,<16`, `aiosmtplib`, `cachetools`, `typer`
 
+## Demo mode
+
+For hosting a public showcase instance. Set under **/admin/settings/ → Users**:
+
+```
+demo_mode        = true
+demo_admin_email = demo-admin@example.com
+demo_user_email  = demo-user@example.com
+demo_read_only   = true    # default — keep it on
+```
+
+The sign-in card grows one button per configured account — **Explore as an
+administrator** and **Explore as a standard user** — each posting to
+`POST /api/users/auth/demo/{role}`. Neither account's password reaches the
+browser. Two accounts because the admin surface is what the framework is for
+and the end-user app is what you build with it; a visitor can switch between
+them without signing out. Blank either email to offer only the other; that
+closes its route too, not just its button.
+
+Both accounts are seeded (and reconciled) at boot and on every settings
+reload, and while `demo_read_only` is on, `DemoReadOnlyMiddleware` refuses
+every unsafe HTTP method from either demo session — everyone else on the
+instance is unaffected. A standing banner tells the visitor they are in a demo.
+
+Full detail, including the `demo_read_only = false` warning, is in
+[docs/modules/users.md](../../docs/modules/users.md#demo-mode-hosting-a-showcase-instance).
+
 ## Social sign-in (Google, GitHub, Microsoft, OIDC)
 
 OAuth providers are configured in the admin UI at **/settings/modules → Users**

{simple_module_users-0.0.33 → simple_module_users-0.0.35}/package.json

@@ -6,14 +6,14 @@
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@inertiajs/react": "^2.0.0",
+    "@inertiajs/react": "^3.7.0",
     "@simple-module-py/ui": "*"
   },
   "devDependencies": {
     "@simple-module-py/tsconfig": "*"
   },
   "dependencies": {
-    "lucide-react": "^1.28.0",
-    "sonner": "^2.0.7"
+    "lucide-react": "^1.43.0",
+    "sonner": "^2.0.8"
   }
 }

{simple_module_users-0.0.33 → simple_module_users-0.0.35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.33"
+version = "0.0.35"
 description = "Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps"
 readme = "README.md"
 license = "MIT"
@@ -21,11 +21,11 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.33",
-    "simple_module_db==0.0.33",
-    "simple_module_hosting==0.0.33",
-    "simple_module_settings==0.0.33",
-    "simple_module_auth==0.0.33",
+    "simple_module_core==0.0.35",
+    "simple_module_db==0.0.35",
+    "simple_module_hosting==0.0.35",
+    "simple_module_settings==0.0.35",
+    "simple_module_auth==0.0.35",
     # Pinned to a narrow range: `deps.py` relies on mutating CookieTransport
     # fields after construction (see reconfigure_cookie_transport in backend.py).
     # Bumping the major version requires re-checking those field names.

simple_module_users-0.0.35/tests/_demo_support.py

@@ -0,0 +1,33 @@
+"""Fixtures for the demo-account tests, shared by the seeding and guard suites.
+
+Loaded as a pytest plugin from ``conftest.py`` — same mechanism as
+``_middleware_support``. Not named ``test_*`` so pytest does not collect it.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from _users_app_builders import _build_users_app
+from users.demo import ensure_demo_users
+
+DEMO_ADMIN_EMAIL = "demo-admin@example.com"
+DEMO_USER_EMAIL = "demo-user@example.com"
+
+
+@pytest.fixture
+async def demo_app(monkeypatch):
+    """A users app with demo mode on and both demo accounts seeded."""
+    application, ctx = await _build_users_app(monkeypatch, allow_signup=False)
+    application.state.users.settings.demo_mode = True
+    await ensure_demo_users(application)
+    yield application
+    await ctx.__aexit__(None, None, None)
+
+
+@pytest.fixture
+async def demo_client(demo_app):
+    """Anonymous client against ``demo_app`` — it signs itself in via a button."""
+    transport = httpx.ASGITransport(app=demo_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+        yield client

{simple_module_users-0.0.33 → simple_module_users-0.0.35}/tests/conftest.py

@@ -162,4 +162,4 @@ async def users_db(users_app) -> AsyncGenerator[AsyncSession, None]:
 
 # Fixtures consumed by the users.middleware unit tests live in
 # _middleware_support.py (imported as a pytest plugin below).
-pytest_plugins = ["_middleware_support"]
+pytest_plugins = ["_middleware_support", "_demo_support"]

simple_module_users-0.0.35/tests/test_activity_summary.py

@@ -0,0 +1,111 @@
+"""Every activity line comes out of a catalog, not out of an f-string.
+
+The card used to build its sentences in Python — ``f"{verb} {kind} {label}"``
+from an English verb table — so the "Recent activity" list read as English in
+every locale and no translation could reach it. Neither lint check could see
+it: they only parse ``.tsx``.
+
+These tests translate with a stub that echoes ``key(args)`` instead of copy, so
+an assertion here fails the moment a sentence is assembled locally again — an
+f-string would produce prose where the stub produces a key.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from simple_module_core import AuditLink, AuditLinkRegistry
+from users.admin.recent_activity import _kind_of, _summarise
+
+
+class _EchoTranslator:
+    """Stands in for ``Translator``, rendering the key and its arguments."""
+
+    def t(self, key: str, **params: Any) -> str:
+        rendered = ", ".join(f"{name}={value}" for name, value in sorted(params.items()))
+        return f"{key}({rendered})"
+
+
+class _KeylessTranslator(_EchoTranslator):
+    """A translator with an empty catalog: ``t`` echoes the key back."""
+
+    def t(self, key: str, **params: Any) -> str:
+        return key
+
+
+T = _EchoTranslator()
+
+
+class TestSummaryKeys:
+    def test_a_create_reads_from_the_created_key(self) -> None:
+        assert _summarise(T, "create", "setting", "smtp_host", []) == (
+            "users.recent_activity.summary.created(kind=setting, label=smtp_host)"
+        )
+
+    def test_every_spelling_of_one_action_shares_a_key(self) -> None:
+        """Writers disagree on "delete"/"deleted"; the reader should not."""
+        assert _summarise(T, "delete", "file", "x", []) == _summarise(T, "deleted", "file", "x", [])
+
+    def test_an_unknown_action_keeps_its_verb_as_an_argument(self) -> None:
+        """Inventing a translation for a verb only one writer uses is a guess."""
+        assert _summarise(T, "archive", "file", "x", []) == (
+            "users.recent_activity.summary.other(action=Archive, kind=file, label=x)"
+        )
+
+    def test_named_fields_are_one_argument_not_a_locally_joined_sentence(self) -> None:
+        summary = _summarise(T, "update", "user", "Ada", [{"field": "email"}, {"field": "roles"}])
+        assert summary == (
+            "users.recent_activity.summary.changed_fields(fields=email, roles, label=Ada)"
+        )
+
+    def test_a_long_field_list_becomes_a_count(self) -> None:
+        changes = [{"field": name} for name in ("a", "b", "c", "d")]
+        assert _summarise(T, "update", "user", "Ada", changes) == (
+            "users.recent_activity.summary.changed_count(count=4, label=Ada)"
+        )
+
+    def test_an_update_with_no_recorded_fields_falls_back_to_the_plain_verb(self) -> None:
+        assert _summarise(T, "update", "user", "Ada", None) == (
+            "users.recent_activity.summary.updated(kind=user, label=Ada)"
+        )
+
+    def test_a_missing_catalog_entry_leaves_no_trailing_space(self) -> None:
+        """The key echoes back verbatim; nothing here appends a stray gap."""
+        assert _summarise(_KeylessTranslator(), "create", "setting", "x", []) == (
+            "users.recent_activity.summary.created"
+        )
+
+
+class TestKindOf:
+    def _registry(self, link: AuditLink) -> AuditLinkRegistry:
+        registry = AuditLinkRegistry()
+        registry.register(link)
+        return registry
+
+    def test_the_links_label_key_is_translated(self) -> None:
+        registry = self._registry(
+            AuditLink(
+                entity_type="Setting",
+                url_template="/s/{id}",
+                label="Setting",
+                label_key="settings.audit.setting",
+            )
+        )
+        assert _kind_of(T, registry, "Setting") == "settings.audit.setting()"
+
+    def test_an_unresolved_key_falls_back_to_the_english_label(self) -> None:
+        registry = self._registry(
+            AuditLink(
+                entity_type="Setting",
+                url_template="/s/{id}",
+                label="Setting",
+                label_key="settings.audit.setting",
+            )
+        )
+        assert _kind_of(_KeylessTranslator(), registry, "Setting") == "setting"
+
+    def test_a_type_no_module_claims_reads_as_its_class_name(self) -> None:
+        assert _kind_of(T, AuditLinkRegistry(), "Unclaimed") == "unclaimed"
+
+    def test_no_registry_at_all_is_survivable(self) -> None:
+        assert _kind_of(T, None, "Unclaimed") == "unclaimed"

simple_module_users-0.0.35/tests/test_bearer_token_expiry.py

@@ -0,0 +1,265 @@
+"""A bearer credential lasts as long as it was issued for — not thirty days.
+
+``_TOKEN_LIFETIME_SECONDS`` is one number for the whole process, because
+``current_user`` resolves its strategy from the shared backend and cannot vary
+it per request. It has to be the widest window any sign-in asks for, so every
+other credential inherited it: an ordinary sign-in wrote an ``sm_auth`` cookie
+whose ``Max-Age`` said fourteen days while the row behind it was accepted for
+thirty, and ``/api/users/auth/token`` returned ``expires_in=900`` for a row good
+for a month. ``Max-Age`` is browser-enforced only — a cookie lifted off disk is
+replayed without one.
+
+Each row now carries its own deadline and the ``session_version`` it was minted
+under, and both bearer read paths enforce them: ``ExpiringDatabaseStrategy``
+(which backs ``fastapi_users.current_user``) and ``UsersAuthProvider
+._resolve_bearer`` (which backs ``AuthMiddleware``).
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import httpx
+import pytest
+from sqlalchemy import select
+from users.models import User, UserAccessToken
+
+_LOGIN = "/api/users/auth/login"
+_TOKEN = "/api/users/auth/token"
+_ME = "/api/users/me"
+_CREDS = {"username": "admin@example.com", "password": "AdminPass1!"}
+
+
+async def _tokens(app) -> list[UserAccessToken]:
+    async with app.state.sm.db.session_factory() as session:
+        return list((await session.execute(select(UserAccessToken))).scalars())
+
+
+async def _only_token(app) -> UserAccessToken:
+    rows = await _tokens(app)
+    assert len(rows) == 1, f"expected exactly one access token, got {len(rows)}"
+    return rows[0]
+
+
+def _seconds_out(row: UserAccessToken) -> float:
+    """How far ``expires_at`` sits from ``created_at``, in seconds."""
+    created, expires = row.created_at, row.expires_at
+    created = created.replace(tzinfo=UTC) if created.tzinfo is None else created
+    expires = expires.replace(tzinfo=UTC) if expires.tzinfo is None else expires
+    return (expires - created).total_seconds()
+
+
+def _bearer(app, token: str) -> httpx.AsyncClient:
+    """A client presenting the row as an ``Authorization: Bearer`` header.
+
+    Read by ``UsersAuthProvider._resolve_bearer`` through ``AuthMiddleware``.
+    """
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://testserver",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+
+
+async def _expire_all(app) -> None:
+    """Push every row's deadline into the past, leaving ``created_at`` alone."""
+    async with app.state.sm.db.session_factory() as session:
+        for row in (await session.execute(select(UserAccessToken))).scalars():
+            row.expires_at = datetime.now(UTC) - timedelta(seconds=1)
+        await session.commit()
+
+
+async def _expire(app, token: str) -> None:
+    """Push a row's deadline into the past, leaving ``created_at`` alone.
+
+    The point of the test: the row is well inside the thirty-day read ceiling
+    and must still be refused, because the window it was *issued* for has run
+    out.
+    """
+    async with app.state.sm.db.session_factory() as session:
+        row = await session.get(UserAccessToken, token)
+        row.expires_at = datetime.now(UTC) - timedelta(seconds=1)
+        await session.commit()
+
+
+class TestTheRowLastsWhatWasPromised:
+    @pytest.mark.anyio
+    async def test_an_ordinary_sign_in_gets_the_cookie_window(self, users_app, anon_client):
+        """Not the thirty-day ceiling. This is the whole bug: the `Max-Age` said
+        fourteen days and the row behind it was honoured for thirty."""
+        assert (await anon_client.post(_LOGIN, data=_CREDS)).status_code == 204
+
+        settings = users_app.state.users.settings
+        assert _seconds_out(await _only_token(users_app)) == pytest.approx(
+            settings.cookie_max_age_seconds, abs=5
+        )
+
+    @pytest.mark.anyio
+    async def test_keep_me_signed_in_gets_the_longer_window(self, users_app, anon_client):
+        """The checkbox still has to mean what it says."""
+        assert (
+            await anon_client.post(_LOGIN, data={**_CREDS, "remember": "true"})
+        ).status_code == 204
+
+        settings = users_app.state.users.settings
+        assert _seconds_out(await _only_token(users_app)) == pytest.approx(
+            settings.remember_me_max_age_seconds, abs=5
+        )
+
+    @pytest.mark.anyio
+    async def test_the_token_endpoint_honours_its_own_expires_in(self, users_app, anon_client):
+        """It advertised 15 minutes and minted a row good for a month, so a
+        client that honoured `expires_in` re-authenticated every 15 minutes
+        while the token it discarded stayed valid."""
+        resp = await anon_client.post(
+            _TOKEN, json={"email": "admin@example.com", "password": "AdminPass1!"}
+        )
+        assert resp.status_code == 200, resp.text
+        advertised = resp.json()["expires_in"]
+
+        settings = users_app.state.users.settings
+        assert advertised == settings.bearer_token_lifetime_seconds
+        assert _seconds_out(await _only_token(users_app)) == pytest.approx(advertised, abs=5)
+
+
+class TestAnExpiredRowStopsAuthenticating:
+    @pytest.mark.anyio
+    async def test_the_cookie_strategy_path_refuses_it(self, users_app, anon_client):
+        """`fastapi_users.current_user`, via ExpiringDatabaseStrategy.
+
+        ``/api/users/me`` is the probe because it depends on ``current_user``,
+        which is what reads the ``sm_auth`` row. The row stays well inside the
+        thirty-day read ceiling — only the deadline it was issued for has passed.
+        """
+        assert (await anon_client.post(_LOGIN, data=_CREDS)).status_code == 204
+        assert (await anon_client.get(_ME)).status_code == 200
+
+        await _expire_all(users_app)
+        assert (await anon_client.get(_ME)).status_code == 401
+
+    @pytest.mark.anyio
+    async def test_the_provider_path_refuses_it(self, users_app, anon_client):
+        """`UsersAuthProvider._resolve_bearer`, via AuthMiddleware."""
+        from users.provider import UsersAuthProvider
+
+        resp = await anon_client.post(
+            _TOKEN, json={"email": "admin@example.com", "password": "AdminPass1!"}
+        )
+        token = resp.json()["access_token"]
+        scope = {"app": users_app}
+
+        provider = UsersAuthProvider()
+        assert await provider._resolve_bearer(scope, token) is not None
+        await _expire(users_app, token)
+        assert await provider._resolve_bearer(scope, token) is None
+
+
+class TestAPasswordChangeStrandsBearerTokens:
+    """`change_my_password` bumped `session_version` and stranded every session,
+    while every bearer token minted before it kept working — including any an
+    attacker who knew the old password had already collected."""
+
+    @pytest.mark.anyio
+    async def test_a_version_bump_strands_a_token_on_both_paths(self, users_app, anon_client):
+        from users.provider import UsersAuthProvider, forget_session_version
+
+        # One row per path: the sign-in writes the `sm_auth` row `current_user`
+        # reads, and `/auth/token` mints the one the Bearer header carries.
+        assert (await anon_client.post(_LOGIN, data=_CREDS)).status_code == 204
+        minted = await anon_client.post(
+            _TOKEN, json={"email": "admin@example.com", "password": "AdminPass1!"}
+        )
+        token = minted.json()["access_token"]
+        provider = UsersAuthProvider()
+        scope = {"app": users_app}
+
+        assert (await anon_client.get(_ME)).status_code == 200
+        assert await provider._resolve_bearer(scope, token) is not None
+
+        async with users_app.state.sm.db.session_factory() as session:
+            user = (
+                await session.execute(select(User).where(User.email == "admin@example.com"))
+            ).scalar_one()
+            user.session_version = int(user.session_version or 0) + 1
+            await session.commit()
+            forget_session_version(user.id)
+
+        assert (await anon_client.get(_ME)).status_code == 401
+        assert await provider._resolve_bearer(scope, token) is None
+
+    @pytest.mark.anyio
+    async def test_changing_the_password_deletes_the_rows(self, users_app, anon_client):
+        """The stamped counter already strands them; deleting is what stops a
+        stolen token resolving a row at all, and stops the refresh tokens
+        minting fresh ones behind it."""
+        assert (await anon_client.post(_LOGIN, data=_CREDS)).status_code == 204
+        assert await _tokens(users_app)
+
+        resp = await anon_client.post(
+            "/api/users/me/password",
+            json={"current_password": "AdminPass1!", "new_password": "NewAdminPass1!"},
+        )
+        assert resp.status_code == 204, resp.text
+        assert await _tokens(users_app) == []
+
+
+class TestTheMintedCounterIsCurrent:
+    @pytest.mark.anyio
+    async def test_a_refresh_carries_the_accounts_counter(self, users_app, anon_client):
+        """A refresh token outlives the access tokens it mints, so the account
+        is re-read rather than trusted from the row."""
+        resp = await anon_client.post(
+            _TOKEN, json={"email": "admin@example.com", "password": "AdminPass1!"}
+        )
+        refresh = resp.json()["refresh_token"]
+
+        async with users_app.state.sm.db.session_factory() as session:
+            user = (
+                await session.execute(select(User).where(User.email == "admin@example.com"))
+            ).scalar_one()
+            user.session_version = 42
+            await session.commit()
+
+        rotated = await anon_client.post(
+            "/api/users/auth/token/refresh", json={"refresh_token": refresh}
+        )
+        assert rotated.status_code == 200, rotated.text
+
+        async with users_app.state.sm.db.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(UserAccessToken).where(
+                        UserAccessToken.token == rotated.json()["access_token"]
+                    )
+                )
+            ).scalar_one()
+            assert row.session_version == 42
+
+    @pytest.mark.anyio
+    async def test_a_refresh_for_a_deactivated_account_is_refused(self, users_app, anon_client):
+        resp = await anon_client.post(
+            _TOKEN, json={"email": "admin@example.com", "password": "AdminPass1!"}
+        )
+        refresh = resp.json()["refresh_token"]
+
+        async with users_app.state.sm.db.session_factory() as session:
+            user = (
+                await session.execute(select(User).where(User.email == "admin@example.com"))
+            ).scalar_one()
+            user.is_active = False
+            await session.commit()
+
+        rotated = await anon_client.post(
+            "/api/users/auth/token/refresh", json={"refresh_token": refresh}
+        )
+        assert rotated.status_code == 401
+
+
+class TestTheModelDefault:
+    def test_a_row_built_directly_still_gets_a_deadline(self):
+        """The mint paths always stamp one; the default keeps a caller that
+        builds the model by hand from minting a credential that never expires."""
+        row = UserAccessToken(token="t", user_id=uuid.uuid4())
+        assert row.expires_at is not None
+        assert _seconds_out(row) == pytest.approx(30 * 24 * 60 * 60, abs=5)