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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_users
-Version: 0.0.34
+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.34
-Requires-Dist: simple-module-core==0.0.34
-Requires-Dist: simple-module-db==0.0.34
-Requires-Dist: simple-module-hosting==0.0.34
-Requires-Dist: simple-module-settings==0.0.34
+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.34 → 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.34 → 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.34 → simple_module_users-0.0.35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.34"
+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.34",
-    "simple_module_db==0.0.34",
-    "simple_module_hosting==0.0.34",
-    "simple_module_settings==0.0.34",
-    "simple_module_auth==0.0.34",
+    "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.34 → 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_demo_account.py

@@ -0,0 +1,182 @@
+"""Demo accounts: how they are configured, seeded, and entered.
+
+Two of the ways the feature can fail open live here — buttons that appear when
+no account is configured, and an endpoint that signs someone in when the
+feature is off. The third, a demo session that is allowed to write, is
+``test_demo_guard``.
+"""
+
+from __future__ import annotations
+
+from _demo_support import DEMO_ADMIN_EMAIL, DEMO_USER_EMAIL
+from sqlalchemy import select
+from users.constants import ADMIN_ROLE_NAME, USER_ROLE_NAME
+from users.demo import (
+    DemoAccount,
+    ensure_demo_users,
+    reconcile_demo_user,
+    resolve_demo_account,
+    resolve_demo_accounts,
+)
+from users.models import Role, User, UserRole
+from users.settings import UsersSettings
+
+
+def _settings(**overrides) -> UsersSettings:
+    base = {
+        "reset_password_token_secret": "test-reset-secret-32-bytes-xxxxx",
+        "verification_token_secret": "test-verify-secret-32-bytes-xxxxx",
+    }
+    return UsersSettings(**base, **overrides)
+
+
+# ── resolve_demo_accounts ───────────────────────────────────────────────────
+
+
+def test_demo_is_off_by_default():
+    assert resolve_demo_accounts(_settings()) == ()
+
+
+def test_both_accounts_are_offered_admin_first():
+    """Admin first: it is the surface someone evaluating the framework came
+    to see, and button order is the only thing that says so."""
+    accounts = resolve_demo_accounts(_settings(demo_mode=True))
+
+    assert [a.role for a in accounts] == [ADMIN_ROLE_NAME, USER_ROLE_NAME]
+    assert [a.email for a in accounts] == [DEMO_ADMIN_EMAIL, DEMO_USER_EMAIL]
+
+
+def test_blanking_one_email_offers_only_the_other():
+    accounts = resolve_demo_accounts(_settings(demo_mode=True, demo_admin_email="  "))
+
+    assert [a.role for a in accounts] == [USER_ROLE_NAME]
+
+
+def test_blanking_both_emails_reads_as_off_not_as_an_error():
+    """A half-finished edit in the admin UI must not break the sign-in page."""
+    assert (
+        resolve_demo_accounts(_settings(demo_mode=True, demo_admin_email="", demo_user_email=""))
+        == ()
+    )
+
+
+def test_resolve_by_role_finds_each_account():
+    settings = _settings(demo_mode=True)
+
+    assert resolve_demo_account(settings, ADMIN_ROLE_NAME).email == DEMO_ADMIN_EMAIL
+    assert resolve_demo_account(settings, USER_ROLE_NAME).email == DEMO_USER_EMAIL
+    assert resolve_demo_account(settings, "superuser") is None
+
+
+def test_read_only_is_the_default_posture():
+    assert _settings(demo_mode=True).demo_read_only is True
+
+
+# ── seeding ─────────────────────────────────────────────────────────────────
+
+
+async def _row(app, email: str) -> User | None:
+    async with app.state.sm.db.session_factory() as session:
+        return (await session.execute(select(User).where(User.email == email))).scalar_one_or_none()
+
+
+async def _role_names(app, user_id) -> list[str]:
+    async with app.state.sm.db.session_factory() as session:
+        return list(
+            (
+                await session.execute(
+                    select(Role.name)
+                    .join(UserRole, UserRole.role_id == Role.id)
+                    .where(UserRole.user_id == user_id)
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+
+async def test_ensure_demo_users_seeds_both_accounts(users_app):
+    users_app.state.users.settings.demo_mode = True
+
+    ids = await ensure_demo_users(users_app)
+
+    assert len(ids) == 2
+    assert users_app.state.users.demo_user_ids == ids
+    admin = await _row(users_app, DEMO_ADMIN_EMAIL)
+    user = await _row(users_app, DEMO_USER_EMAIL)
+    assert admin is not None and admin.is_superuser
+    assert user is not None and not user.is_superuser
+    assert all(row.is_active and row.is_verified for row in (admin, user))
+
+
+async def test_each_account_gets_its_own_role(users_app):
+    users_app.state.users.settings.demo_mode = True
+    await ensure_demo_users(users_app)
+
+    admin = await _row(users_app, DEMO_ADMIN_EMAIL)
+    user = await _row(users_app, DEMO_USER_EMAIL)
+    assert await _role_names(users_app, admin.id) == [ADMIN_ROLE_NAME]
+    assert await _role_names(users_app, user.id) == [USER_ROLE_NAME]
+
+
+async def test_a_blank_password_still_produces_usable_accounts(users_app):
+    """The buttons do not need passwords; the rows still need hashes."""
+    users_app.state.users.settings.demo_mode = True
+    await ensure_demo_users(users_app)
+
+    assert (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
+    assert (await _row(users_app, DEMO_USER_EMAIL)).hashed_password
+
+
+async def test_a_generated_password_is_not_re_rolled_on_every_boot(users_app):
+    """Re-hashing a secret nobody can use would write an audit entry per
+    worker per restart, for no gain."""
+    users_app.state.users.settings.demo_mode = True
+    await ensure_demo_users(users_app)
+    first = (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
+
+    await ensure_demo_users(users_app)
+
+    assert (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password == first
+
+
+async def test_a_configured_password_is_reapplied(users_app):
+    """Changing a demo password in the admin UI has to take effect."""
+    users_app.state.users.settings.demo_mode = True
+    await ensure_demo_users(users_app)
+    first = (await _row(users_app, DEMO_USER_EMAIL)).hashed_password
+
+    users_app.state.users.settings.demo_user_password = "a-published-demo-password"
+    await ensure_demo_users(users_app)
+
+    assert (await _row(users_app, DEMO_USER_EMAIL)).hashed_password != first
+
+
+async def test_demo_off_clears_the_cached_ids(users_app):
+    users_app.state.users.settings.demo_mode = True
+    await ensure_demo_users(users_app)
+    users_app.state.users.settings.demo_mode = False
+
+    assert await ensure_demo_users(users_app) == ()
+    assert users_app.state.users.demo_user_ids == ()
+
+
+async def test_repointing_an_email_demotes_the_account_that_held_it(users_app):
+    """An address that served as the demo admin and is then configured as the
+    demo user must lose the admin grant, or the demotion is cosmetic."""
+    shared = "demo@example.com"
+    async with users_app.state.sm.db.session_factory() as session:
+        user = await reconcile_demo_user(
+            session,
+            DemoAccount(role=ADMIN_ROLE_NAME, email=shared, password="x", full_name="Demo"),
+        )
+        assert user.is_superuser
+        await reconcile_demo_user(
+            session,
+            DemoAccount(role=USER_ROLE_NAME, email=shared, password="x", full_name="Demo"),
+        )
+
+    assert await _role_names(users_app, user.id) == [USER_ROLE_NAME]
+    async with users_app.state.sm.db.session_factory() as session:
+        refreshed = await session.get(User, user.id)
+    assert not refreshed.is_superuser

simple_module_users-0.0.35/tests/test_demo_guard.py

@@ -0,0 +1,178 @@
+"""``DemoReadOnlyMiddleware`` — what a shared demo session may and may not do.
+
+Split from the configuration and entry suites because this is the security
+boundary: every test here is a way the guard could fail open.
+"""
+
+from __future__ import annotations
+
+import httpx
+from users.constants import ADMIN_ROLE_NAME, SESSION_USER_ID_KEY, USER_ROLE_NAME
+from users.demo import SESSION_DEMO_KEY
+from users.demo_guard import DEMO_READ_ONLY_DETAIL
+
+
+def _demo_route(role: str) -> str:
+    return f"/api/users/auth/demo/{role}"
+
+
+def _client(app, session_payload: dict) -> httpx.AsyncClient:
+    """A client carrying a forged session cookie for ``session_payload``."""
+    from simple_module_test import forge_session_cookie
+
+    cookie = forge_session_cookie(str(app.state.sm.settings.secret_key), session_payload)
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://testserver",
+        cookies={"session": cookie},
+    )
+
+
+# ── both demo sessions are read-only ────────────────────────────────────────
+
+
+async def test_the_admin_demo_cannot_write(demo_client):
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+
+    res = await demo_client.patch("/api/users/me", json={"full_name": "Owned"})
+    assert res.status_code == 403
+    assert res.json()["detail"] == DEMO_READ_ONLY_DETAIL
+
+
+async def test_the_user_demo_cannot_write(demo_client):
+    await demo_client.post(_demo_route(USER_ROLE_NAME))
+
+    res = await demo_client.patch("/api/users/me", json={"full_name": "Owned"})
+    assert res.status_code == 403
+    assert res.json()["detail"] == DEMO_READ_ONLY_DETAIL
+
+
+async def test_the_admin_demo_cannot_reach_the_admin_write_routes(demo_app):
+    """The showcase admin may browse /admin/*, never mutate through it — that
+    is the whole reason an admin demo is safe to publish."""
+    target = demo_app.state.users.demo_user_ids[0]
+    async with _client(
+        demo_app, {SESSION_USER_ID_KEY: str(target), SESSION_DEMO_KEY: True}
+    ) as client:
+        res = await client.delete(f"/api/users/admin/{target}")
+
+    assert res.status_code == 403
+    assert res.json()["detail"] == DEMO_READ_ONLY_DETAIL
+
+
+async def test_a_demo_session_can_still_read(demo_client):
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+    assert (await demo_client.get("/api/users/me")).status_code == 200
+
+
+async def test_a_demo_session_can_still_sign_out(demo_client):
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+    assert (await demo_client.post("/api/users/auth/logout")).status_code == 204
+
+
+async def test_an_unstamped_session_on_a_demo_account_still_blocks(demo_app):
+    """The stamp is sufficient, not necessary.
+
+    Matching on the user ids too is what catches a visitor who signed in with
+    a published demo password through the ordinary form — that session never
+    passes through a demo endpoint, so it carries no stamp.
+    """
+    payload = {SESSION_USER_ID_KEY: str(demo_app.state.users.demo_user_ids[1])}
+    assert SESSION_DEMO_KEY not in payload
+
+    async with _client(demo_app, payload) as client:
+        res = await client.patch("/api/users/me", json={"full_name": "Owned"})
+
+    assert res.status_code == 403
+
+
+async def test_an_inertia_write_gets_a_hard_redirect_not_a_raw_403(demo_client):
+    """Inertia renders a non-Inertia body as a modal — on a showcase instance
+    that reads as a crash. The protocol's own answer is 409 + Location."""
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+
+    res = await demo_client.patch(
+        "/api/users/me",
+        json={"full_name": "Owned"},
+        headers={"X-Inertia": "true", "Referer": "http://testserver/users/me"},
+    )
+
+    assert res.status_code == 409
+    assert res.headers["X-Inertia-Location"] == "http://testserver/users/me"
+
+
+# ── it leaves everyone else alone ───────────────────────────────────────────
+
+
+async def test_writes_are_allowed_when_read_only_is_off(demo_app, demo_client):
+    demo_app.state.users.settings.demo_read_only = False
+    await demo_client.post(_demo_route(USER_ROLE_NAME))
+
+    res = await demo_client.patch("/api/users/me", json={"full_name": "Explorer"})
+    assert res.status_code == 200
+
+
+async def test_the_guard_leaves_real_accounts_alone(demo_app):
+    """A real administrator on a demo instance is doing real work.
+
+    Goes through an admin route rather than ``/api/users/me``: that one
+    authenticates off the fastapi-users cookie, which a forged session cookie
+    does not carry, so a 401 there would prove nothing about the guard.
+    """
+    from _demo_support import DEMO_USER_EMAIL
+    from _users_app_builders import _make_admin_user
+
+    admin = await _make_admin_user(demo_app)
+    async with _client(demo_app, {SESSION_USER_ID_KEY: str(admin.id)}) as client:
+        res = await client.patch(
+            f"/api/users/admin/{demo_app.state.users.demo_user_ids[1]}",
+            json={"email": DEMO_USER_EMAIL, "full_name": "Renamed By A Real Admin"},
+        )
+
+    assert res.status_code == 200
+
+
+# ── ways out of a demo session ──────────────────────────────────────────────
+
+
+async def test_a_demo_session_can_sign_in_as_a_real_user_and_gets_its_writes_back(
+    demo_app, demo_client
+):
+    """Signing in as yourself is how you stop being the demo.
+
+    Two failures met here. Refusing the sign-in POST stranded anyone whose
+    browser still carried the stamp — including a lapsed demo session, which
+    ``_forget`` leaves anonymous but still marked — with no reachable way back
+    in short of clearing cookies. And a stamp that survived the sign-in would
+    hand the guard to the real account that replaced it.
+    """
+    from _users_app_builders import _make_admin_user
+
+    admin = await _make_admin_user(demo_app)
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+
+    signed_in = await demo_client.post(
+        "/api/users/auth/login",
+        data={"username": admin.email, "password": "AdminPass1!", "remember": "false"},
+    )
+    assert signed_in.status_code == 204
+
+    res = await demo_client.patch("/api/users/me", json={"full_name": "A Real Admin"})
+    assert res.status_code == 200
+
+
+async def test_demo_sessions_stay_read_only_after_demo_mode_is_switched_off(demo_app, demo_client):
+    """Withdrawing the offer must not promote the sessions already handed out.
+
+    ``demo_mode = False`` stops the buttons; it does not expire the cookies, so
+    a guard that keyed on it would hand every live demo visitor a writable
+    superuser on the way out.
+    """
+    await demo_client.post(_demo_route(ADMIN_ROLE_NAME))
+    demo_app.state.users.settings.demo_mode = False
+    demo_app.state.users.demo_user_ids = ()
+
+    res = await demo_client.patch("/api/users/me", json={"full_name": "Owned"})
+
+    assert res.status_code == 403
+    assert res.json()["detail"] == DEMO_READ_ONLY_DETAIL