simple-module-users 0.0.30__tar.gz → 0.0.31__tar.gz

{simple_module_users-0.0.30 → simple_module_users-0.0.31}/.gitignore

@@ -63,3 +63,4 @@ Thumbs.db
 host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
+.verify/

{simple_module_users-0.0.30 → simple_module_users-0.0.31}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_users
-Version: 0.0.30
+Version: 0.0.31
 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.30
-Requires-Dist: simple-module-core==0.0.30
-Requires-Dist: simple-module-db==0.0.30
-Requires-Dist: simple-module-hosting==0.0.30
-Requires-Dist: simple-module-settings==0.0.30
+Requires-Dist: simple-module-auth==0.0.31
+Requires-Dist: simple-module-core==0.0.31
+Requires-Dist: simple-module-db==0.0.31
+Requires-Dist: simple-module-hosting==0.0.31
+Requires-Dist: simple-module-settings==0.0.31
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_users-0.0.30 → simple_module_users-0.0.31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.30"
+version = "0.0.31"
 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.30",
-    "simple_module_db==0.0.30",
-    "simple_module_hosting==0.0.30",
-    "simple_module_settings==0.0.30",
-    "simple_module_auth==0.0.30",
+    "simple_module_core==0.0.31",
+    "simple_module_db==0.0.31",
+    "simple_module_hosting==0.0.31",
+    "simple_module_settings==0.0.31",
+    "simple_module_auth==0.0.31",
     # 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.31/tests/test_users_bulk_invite.py

@@ -0,0 +1,229 @@
+"""Bulk invite — many addresses per submit, with per-address outcomes.
+
+The invite form took one address at a time, so onboarding a team meant
+repeating the form once per person. Partial success is the normal case here:
+one already-registered address must not discard the rest.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+_URL = "/api/users/admin/invite/bulk"
+
+
+class TestBulkInvite:
+    async def test_invites_every_address(self, authenticated_client: httpx.AsyncClient):
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["a@example.com", "b@example.com"], "role_names": []},
+        )
+        assert resp.status_code == 200, resp.text
+        results = resp.json()["results"]
+        assert [r["email"] for r in results] == ["a@example.com", "b@example.com"]
+
+    async def test_duplicate_addresses_are_invited_once(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        """Pasting a list with a repeat should not mint two invites for it."""
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["dup@example.com", "DUP@example.com"], "role_names": []},
+        )
+        assert len(resp.json()["results"]) == 1
+
+    async def test_addresses_are_normalised_to_lowercase(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        resp = await authenticated_client.post(
+            _URL, json={"emails": ["Mixed@Example.com"], "role_names": []}
+        )
+        assert resp.json()["results"][0]["email"] == "mixed@example.com"
+
+    async def test_one_failure_does_not_discard_the_others(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        """A duplicate in a pasted list of twenty must not lose the other 19."""
+        await authenticated_client.post(
+            _URL, json={"emails": ["taken@example.com"], "role_names": []}
+        )
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["taken@example.com", "fresh@example.com"], "role_names": []},
+        )
+        assert resp.status_code == 200, resp.text
+        by_email = {r["email"]: r for r in resp.json()["results"]}
+        assert by_email["taken@example.com"]["status"] == "failed"
+        assert by_email["fresh@example.com"]["status"] in ("sent", "link")
+
+    async def test_a_failure_always_carries_a_reason(self, authenticated_client: httpx.AsyncClient):
+        """Every failed row must say why.
+
+        ``str(UserAlreadyExists())`` is empty — the reason lives in the type, not
+        the message — so passing it through rendered an address in red with a
+        blank reason beside it. Asserting the status alone is what let that ship.
+        """
+        await authenticated_client.post(
+            _URL, json={"emails": ["why@example.com"], "role_names": []}
+        )
+        resp = await authenticated_client.post(
+            _URL, json={"emails": ["why@example.com"], "role_names": []}
+        )
+        result = resp.json()["results"][0]
+        assert result["status"] == "failed"
+        assert result["detail"], "a failed address must explain itself"
+        assert "already" in result["detail"].lower()
+
+    async def test_console_mailer_hands_back_a_copyable_link(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        """The test app uses the console mailer, which delivers nothing — the
+        admin needs the link or the invite is undeliverable."""
+        resp = await authenticated_client.post(
+            _URL, json={"emails": ["linkme@example.com"], "role_names": []}
+        )
+        result = resp.json()["results"][0]
+        assert result["status"] == "link"
+        assert "/users/invite/accept?token=" in result["link"]
+
+    async def test_roles_apply_to_every_address(self, authenticated_client: httpx.AsyncClient):
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["r1@example.com", "r2@example.com"], "role_names": ["user"]},
+        )
+        assert resp.status_code == 200, resp.text
+        assert all(r["status"] in ("sent", "link") for r in resp.json()["results"])
+
+    async def test_roles_survive_a_later_failure(self, authenticated_client: httpx.AsyncClient):
+        """A failure mid-list must not roll back an earlier invite's roles.
+
+        ``invite`` only flushes its role rows; the rollback that clears failed
+        transaction state used to take them with it, so the person invited just
+        before a duplicate address ended up with none of the chosen roles.
+        """
+        await authenticated_client.post(
+            _URL, json={"emails": ["dupe@example.com"], "role_names": []}
+        )
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["kept@example.com", "dupe@example.com"], "role_names": ["admin"]},
+        )
+        assert resp.status_code == 200, resp.text
+
+        listing = await authenticated_client.get("/api/users/admin")
+        users = {u["email"]: u for u in listing.json()}
+        assert users["kept@example.com"]["roles"] == ["admin"]
+
+    async def test_a_malformed_address_does_not_reject_the_submit(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        """A typo in one line of a pasted column used to 422 the whole body,
+        leaving the admin with a generic error and no idea which line."""
+        resp = await authenticated_client.post(
+            _URL,
+            json={"emails": ["good@example.com", "not-an-address"], "role_names": []},
+        )
+        assert resp.status_code == 200, resp.text
+        by_email = {r["email"]: r for r in resp.json()["results"]}
+        assert by_email["good@example.com"]["status"] in ("sent", "link")
+        assert by_email["not-an-address"]["status"] == "failed"
+        assert "valid email" in by_email["not-an-address"]["detail"]
+
+    async def test_empty_list_is_accepted_and_does_nothing(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        resp = await authenticated_client.post(_URL, json={"emails": [], "role_names": []})
+        assert resp.status_code == 200
+        assert resp.json()["results"] == []
+
+    async def test_address_count_is_capped(self, authenticated_client: httpx.AsyncClient):
+        """One submit must not be able to mint unbounded live invite tokens."""
+        from users.admin.bulk_invite import MAX_ADDRESSES
+
+        emails = [f"bulk{i}@example.com" for i in range(MAX_ADDRESSES + 5)]
+        resp = await authenticated_client.post(_URL, json={"emails": emails, "role_names": []})
+        invited = [r for r in resp.json()["results"] if r["status"] != "failed"]
+        assert len(invited) == MAX_ADDRESSES
+
+    async def test_addresses_over_the_cap_are_reported_not_dropped(
+        self, authenticated_client: httpx.AsyncClient
+    ):
+        """Silent truncation reports "100 invites sent" while 5 people are
+        never contacted, with nothing on screen saying so."""
+        from users.admin.bulk_invite import MAX_ADDRESSES
+
+        emails = [f"over{i}@example.com" for i in range(MAX_ADDRESSES + 5)]
+        resp = await authenticated_client.post(_URL, json={"emails": emails, "role_names": []})
+        results = resp.json()["results"]
+
+        assert len(results) == MAX_ADDRESSES + 5, "every submitted address needs an outcome"
+        overflow = {r["email"]: r for r in results[-5:]}
+        assert set(overflow) == {
+            f"over{i}@example.com" for i in range(MAX_ADDRESSES, MAX_ADDRESSES + 5)
+        }
+        for result in overflow.values():
+            assert result["status"] == "failed"
+            assert "limit" in result["detail"]
+
+    async def test_requires_authentication(self, client: httpx.AsyncClient):
+        resp = await client.post(
+            _URL, json={"emails": ["x@example.com"], "role_names": []}, follow_redirects=False
+        )
+        assert resp.status_code in (302, 401, 403)
+
+
+class TestInvitePreview:
+    async def test_accept_page_names_the_invitee(
+        self, authenticated_client: httpx.AsyncClient, client: httpx.AsyncClient
+    ):
+        """The card asked for a password while identifying nobody."""
+        created = await authenticated_client.post(
+            _URL, json={"emails": ["preview@example.com"], "role_names": []}
+        )
+        link = created.json()["results"][0]["link"]
+        token = link.split("token=")[1]
+
+        resp = await client.get(
+            f"/users/invite/accept?token={token}",
+            headers={"X-Inertia": "true", "Accept": "application/json"},
+        )
+        assert resp.status_code == 200, resp.text
+        invite = resp.json()["props"]["invite"]
+        assert invite["email"] == "preview@example.com"
+        assert invite["already_accepted"] is False
+
+    @pytest.mark.parametrize("token", ["", "not-a-jwt", "a.b.c"])
+    async def test_unreadable_tokens_yield_no_preview(self, client: httpx.AsyncClient, token: str):
+        """Expired, tampered and absent all look the same here on purpose —
+        the reason belongs to the accept attempt, which validates properly."""
+        resp = await client.get(
+            f"/users/invite/accept?token={token}",
+            headers={"X-Inertia": "true", "Accept": "application/json"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["props"]["invite"] is None
+
+    async def test_preview_does_not_consume_the_invite(
+        self, authenticated_client: httpx.AsyncClient, client: httpx.AsyncClient
+    ):
+        """Viewing the page must leave the token usable — UserManager.verify
+        marks the account verified as a side effect, so the preview cannot
+        route through it."""
+        created = await authenticated_client.post(
+            _URL, json={"emails": ["unspent@example.com"], "role_names": []}
+        )
+        token = created.json()["results"][0]["link"].split("token=")[1]
+
+        for _ in range(2):
+            resp = await client.get(
+                f"/users/invite/accept?token={token}",
+                headers={"X-Inertia": "true", "Accept": "application/json"},
+            )
+            assert resp.json()["props"]["invite"]["already_accepted"] is False
+
+        accepted = await client.post(
+            "/api/users/auth/accept-invite",
+            json={"token": token, "password": "a-good-password-123"},
+        )
+        assert accepted.status_code in (200, 204), accepted.text

{simple_module_users-0.0.30 → simple_module_users-0.0.31}/tests/test_views_admin.py

@@ -129,23 +129,58 @@ class TestHasPermissionsModuleFlag:
 
 
 # ---------------------------------------------------------------------------
-# Admin create page
+# Admin add-people page (create + invite merged behind a mode switch)
 # ---------------------------------------------------------------------------
 
 
-class TestAdminCreatePage:
+class TestAdminAddPeoplePage:
     @pytest.mark.anyio
-    async def test_create_page_renders_with_roles(self, admin_client):
+    async def test_add_page_renders_with_roles(self, admin_client):
         resp = await admin_client.get(
-            "/users/admin/create",
+            "/users/admin/add",
             headers={"X-Inertia": "true", "Accept": "application/json"},
         )
         assert resp.status_code == 200
         data = resp.json()
-        assert data["component"] == "Users/Users/Create"
+        assert data["component"] == "Users/Users/AddPeople"
         assert "roles" in data["props"]
 
     @pytest.mark.anyio
-    async def test_create_page_requires_auth(self, anon_client):
-        resp = await anon_client.get("/users/admin/create", follow_redirects=False)
+    async def test_add_page_reports_whether_mail_can_be_delivered(self, admin_client):
+        """Drives the copy-link panel — the page has to know before submitting."""
+        resp = await admin_client.get(
+            "/users/admin/add",
+            headers={"X-Inertia": "true", "Accept": "application/json"},
+        )
+        assert "mailer_delivers" in resp.json()["props"]
+
+    @pytest.mark.anyio
+    async def test_no_mailer_does_not_promise_delivery(self, admin_client, app):
+        """With nothing able to send, the page must offer the copy-link panel —
+        claiming delivery is the one answer that is certainly wrong."""
+        original = app.state.users.mailer
+        app.state.users.mailer = None
+        try:
+            resp = await admin_client.get(
+                "/users/admin/add",
+                headers={"X-Inertia": "true", "Accept": "application/json"},
+            )
+            assert resp.json()["props"]["mailer_delivers"] is False
+        finally:
+            app.state.users.mailer = original
+
+    @pytest.mark.anyio
+    async def test_add_page_requires_auth(self, anon_client):
+        resp = await anon_client.get("/users/admin/add", follow_redirects=False)
         assert resp.status_code == 302
+
+    @pytest.mark.anyio
+    @pytest.mark.parametrize(
+        ("old_path", "mode"),
+        [("/users/admin/create", "create"), ("/users/admin/invite", "invite")],
+    )
+    async def test_old_urls_redirect_into_the_right_mode(self, admin_client, old_path, mode):
+        """Existing links must land on the merged form with their mode preselected."""
+        resp = await admin_client.get(old_path, follow_redirects=False)
+        assert resp.status_code == 307
+        assert resp.headers["location"] == f"/users/admin/add?mode={mode}"

{simple_module_users-0.0.30 → simple_module_users-0.0.31}/users/admin/api.py

@@ -10,6 +10,7 @@ from fastapi_users import exceptions as fa_exceptions
 from simple_module_core.events import EventBus
 from simple_module_hosting.permissions import RequiresPermission
 
+from users.admin.bulk_invite import bulk_router
 from users.admin.service import UserService
 from users.constants import PERM_USERS_MANAGE, sanitize_list_filters
 from users.contracts.events import (
@@ -40,6 +41,10 @@ admin_router = APIRouter(
     tags=["users-admin"],
 )
 
+# Bulk invite lives in its own module (this file is near the 300-line cap) but
+# mounts here so it inherits the users.manage guard above.
+admin_router.include_router(bulk_router)
+
 
 @admin_router.get("", response_model=list[UserListItem])
 async def admin_list_users(

simple_module_users-0.0.31/users/admin/bulk_invite.py

@@ -0,0 +1,219 @@
+"""Bulk invite — one submit, many addresses.
+
+The invite form took a single address, so onboarding a team meant repeating
+the same form once per person. This accepts a pasted list and reports each
+address separately: one already-registered address in a list of twenty must
+not discard the other nineteen.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+
+from fastapi import APIRouter, Depends, Request
+from fastapi_users.exceptions import UserAlreadyExists
+from pydantic import EmailStr, TypeAdapter, ValidationError
+from simple_module_core.events import EventBus
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from users.admin.service import UserService
+from users.contracts.events import UserInvited
+from users.contracts.schemas import BulkInviteResponse, BulkInviteResult, UserBulkInvite
+from users.deps import get_event_bus, get_mailer, get_user_service
+
+logger = logging.getLogger(__name__)
+
+bulk_router = APIRouter()
+
+STATUS_SENT = "sent"
+STATUS_LINK = "link"
+STATUS_FAILED = "failed"
+
+MAX_ADDRESSES = 100
+"""Enough for a team, small enough that one submit cannot mint an unbounded
+number of live invite tokens."""
+
+_EMAIL = TypeAdapter(EmailStr)
+"""Per-address validation. Deliberately not a ``list[EmailStr]`` on the request
+model: pydantic would reject the whole body over one typo, and the caller would
+get a 422 naming an index rather than the per-address outcomes this endpoint
+exists to produce."""
+
+
+def _failure_detail(exc: Exception) -> str:
+    """Human-readable reason for one address failing.
+
+    ``str(UserAlreadyExists())`` is the empty string — fastapi-users carries the
+    meaning in the exception *type*, not its message. Passing that straight
+    through renders the single most common failure as a bare red address with no
+    reason beside it, which is exactly the question the per-address results exist
+    to answer. The final fallback names the exception class rather than leaving
+    the cell blank: a class name is a poor message, but it is still a lead.
+    """
+    if isinstance(exc, UserAlreadyExists):
+        return "Already registered"
+    return str(exc) or type(exc).__name__
+
+
+def _invite_link(request: Request, token: str) -> str:
+    """Build the accept URL the admin will hand to the invitee.
+
+    Uses the module's configured ``base_url`` — the same value both mailers
+    build their links from — rather than ``request.base_url``. Behind a reverse
+    proxy without ``SM_TRUSTED_PROXY``, the request's own base URL is the
+    internal origin (``http://10.0.0.5:8000``), and this link is *only* ever
+    surfaced when mail could not be delivered, i.e. exactly when the admin has
+    to pass it on by hand. Falls back to the request when the module's settings
+    are unavailable, so the link is never simply missing.
+    """
+    services = getattr(request.app.state, "users", None)
+    configured = getattr(getattr(services, "settings", None), "base_url", "")
+    base = str(configured or request.base_url).rstrip("/")
+    return f"{base}/users/invite/accept?token={token}"
+
+
+@bulk_router.post("/invite/bulk", response_model=BulkInviteResponse)
+async def admin_bulk_invite(
+    data: UserBulkInvite,
+    request: Request,
+    bus: EventBus = Depends(get_event_bus),
+    service: UserService = Depends(get_user_service),
+    # The same request-scoped session the service was built from, taken through
+    # the dependency rather than off the service's private attribute.
+    db: AsyncSession = Depends(get_db),
+    mailer=Depends(get_mailer),
+) -> BulkInviteResponse:
+    """Invite every address in *data*, all sharing the same roles."""
+    invited_by = getattr(request.state, "user", None)
+    invited_by_name = invited_by.name if invited_by else "Administrator"
+
+    # Absent attribute means "assume it delivers" — a third-party mailer must
+    # never leak invite tokens into the response just by not declaring itself.
+    # No mailer at all delivers nothing, though: defaulting that to True sends
+    # every address down the send path, where the AttributeError surfaces to
+    # the admin as a raw "'NoneType' object has no attribute 'send_invite'".
+    # This matches what the page's ``mailer_delivers`` prop already reports.
+    delivers = mailer is not None and getattr(mailer, "delivers_email", True)
+
+    # Preserve submit order but drop repeats: pasting a list with the same
+    # address twice should not create two invites for it. A malformed address
+    # is reported like any other per-address failure rather than rejecting the
+    # submit — a typo in one line of a pasted column must not lose the column.
+    seen: set[str] = set()
+    ordered: list[str] = []
+    malformed: list[str] = []
+    for raw in data.emails:
+        email = str(raw).strip().lower()
+        if not email or email in seen:
+            continue
+        seen.add(email)
+        try:
+            _EMAIL.validate_python(email)
+        except ValidationError:
+            malformed.append(email)
+            continue
+        ordered.append(email)
+
+    # Anything past the cap is reported, never silently dropped: truncating in
+    # silence tells the admin "100 invites sent" while 50 people are never
+    # contacted, and nothing on screen says otherwise.
+    accepted, overflow = ordered[:MAX_ADDRESSES], ordered[MAX_ADDRESSES:]
+
+    results: list[BulkInviteResult] = []
+    for email in accepted:
+        try:
+            user, token = await service.invite(email, None, data.role_names, invited_by=invited_by)
+            # Make this invite durable before touching the session again. The
+            # failure path below rolls back, and the role rows the service
+            # flushed but did not commit would go with it — leaving the person
+            # invited with none of the roles the admin picked.
+            await db.commit()
+        except Exception as exc:
+            # Already-registered is the common case and reads fine as-is;
+            # anything else is logged so the admin's summary stays short.
+            logger.info("bulk invite failed for %s: %s", email, exc)
+            results.append(
+                BulkInviteResult(email=email, status=STATUS_FAILED, detail=_failure_detail(exc))
+            )
+            # Clear any failed transaction state before touching the session
+            # again. A real DB error (an IntegrityError from a concurrent
+            # signup, say) otherwise leaves every remaining address dying with
+            # PendingRollbackError — one bad row turning into total failure,
+            # the opposite of the partial success this endpoint promises.
+            # Safe to discard: every successful invite above is committed
+            # before the next one starts, so nothing durable is pending here.
+            with contextlib.suppress(Exception):
+                await db.rollback()
+            continue
+
+        if delivers:
+            try:
+                await mailer.send_invite(user.email, token, invited_by_name)
+            except Exception as exc:
+                # The account exists and the token is valid — the delivery
+                # failed. Handing back the link turns a dead end into a
+                # copy-paste, rather than stranding a half-finished invite.
+                logger.warning("invite mail failed for %s: %s", email, exc)
+                results.append(
+                    BulkInviteResult(
+                        email=email,
+                        status=STATUS_LINK,
+                        detail=str(exc),
+                        link=_invite_link(request, token),
+                    )
+                )
+            else:
+                results.append(BulkInviteResult(email=email, status=STATUS_SENT))
+        else:
+            results.append(
+                BulkInviteResult(
+                    email=email,
+                    status=STATUS_LINK,
+                    link=_invite_link(request, token),
+                )
+            )
+
+        await bus.publish(
+            UserInvited(
+                user_id=user.id,
+                email=user.email,
+                invited_by=(str(invited_by.id) if invited_by else None),
+            )
+        )
+        # Handlers are awaited inline and may write through this same
+        # request-scoped session. Commit again so a *later* address failing —
+        # and rolling back to clear the transaction — cannot take their work
+        # with it, which is what makes the "nothing durable is pending"
+        # assumption in the failure branch above actually hold.
+        #
+        # Guarded: the invite itself is already committed, so a handler writing
+        # something the DB rejects must not 500 the request and discard every
+        # per-address result collected so far — that is exactly the total
+        # failure this endpoint exists to avoid.
+        try:
+            await db.commit()
+        except Exception as exc:
+            logger.warning("post-invite handler commit failed for %s: %s", email, exc)
+            with contextlib.suppress(Exception):
+                await db.rollback()
+
+    results.extend(
+        BulkInviteResult(
+            email=email,
+            status=STATUS_FAILED,
+            detail="Not a valid email address",
+        )
+        for email in malformed
+    )
+    results.extend(
+        BulkInviteResult(
+            email=email,
+            status=STATUS_FAILED,
+            detail=f"Not attempted — over the {MAX_ADDRESSES}-address limit for one submit",
+        )
+        for email in overflow
+    )
+
+    return BulkInviteResponse(results=results)