simple-module-users 0.0.1__py3-none-any.whl

simple_module_users-0.0.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: simple_module_users
+Version: 0.0.1
+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
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,authentication,fastapi-users,simple-module,users
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: cachetools>=5.3
+Requires-Dist: fastapi-users[sqlalchemy]<16,>=15
+Requires-Dist: simple-module-auth==0.0.1
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# simple_module_users
+
+Email+password user management for [simple_module](https://github.com/antosubash/simple_module_python) apps. Replaces Keycloak/Auth0 for the common case: local accounts, admin invites, password reset, optional public signup. Built on `fastapi-users`.
+
+## Install
+
+```bash
+pip install simple_module_users
+```
+
+Pre-wired into any app scaffolded with `simple-module new`.
+
+## What it provides
+
+- Email + password registration, login, logout, password reset.
+- Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
+- Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
+- Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
+- `sm-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`).
+
+## Usage
+
+CLI:
+
+```bash
+uv run sm-users create-admin --email admin@example.com --password 'change-me'
+```
+
+Bootstrap-on-boot (`.env`):
+
+```
+SM_USERS_BOOTSTRAP_EMAIL=admin@example.com
+SM_USERS_BOOTSTRAP_PASSWORD=change-me
+```
+
+Program:
+
+```python
+from users.deps import CurrentUser    # type: ignore[import-not-found]
+
+@router.get("/profile")
+async def profile(user: CurrentUser):
+    return {"email": user.email}
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`, `simple_module_auth`
+- `fastapi-users[sqlalchemy]>=15,<16`, `aiosmtplib`, `cachetools`, `typer`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_users-0.0.1.dist-info/RECORD

@@ -0,0 +1,56 @@
+users/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+users/backend.py,sha256=JYmJjwoe3iTO40IdrIPvjzpslNkT89UQI9hVJDX5-wA,2996
+users/bootstrap.py,sha256=NKTp-qw7uazjKMeMpCRLCUgGbkXqGRdVicdy8Kv66fA,9083
+users/cli.py,sha256=UD0o050mmaNdeTefYQBEEryHDNPB4k-diVPxd72j6Bc,2305
+users/constants.py,sha256=lKII5lU8EM5c2M2O0fDlj6pZ7UN0rfNjKcbYmc8vkzk,1246
+users/db_adapter.py,sha256=U1UbyIdEE5yFout1hBjjwT3cFA25A6Smg5HX8PTUuPg,1669
+users/deps.py,sha256=Ti39DK-gjOLIIKBFCFQStvauroYcbjrY6bXn6jJ99ws,2573
+users/exceptions.py,sha256=lnOCg4hrzsSl7KAaki7Mvg2jaCjabMQp38uos_nV4JA,567
+users/manager.py,sha256=lgpi1eKbbLkrFDYimdXsX7rrsR3J3_JC4g7yksGlH5w,6124
+users/middleware.py,sha256=wJ6rupwnYG-dBB4z8DB35XsPi6zPx55BQKo1tUqGOC4,5421
+users/module.py,sha256=yrLPIfU3xM1Loak1aGXyvWqomccirkmN9h2U8RcCn-4,5115
+users/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+users/rate_limit.py,sha256=g8TaHxqdM23LCvQfCW3KVW0IST-r0pQ09ynjNroBzf0,2061
+users/roles_cache.py,sha256=gHcgHTcQm74dBxyyMiQqTS7z2p5HNstwqbouaoadYFA,1979
+users/service.py,sha256=RaW8qy5tlefyX6BwWE_lPTJDkQo4mTrSTU5Tp-mGPg0,8871
+users/settings.py,sha256=AXNZCw7l1UDpQMsFGHdoxYSMulOdno33BOzWpP5h3Og,4140
+users/state.py,sha256=ihONMTdR7LCmt231RH9MLQieONwbBg_I1x8u81h17tc,1133
+users/components/IndexFilters.tsx,sha256=5wjAlbOwOI1nJTfdVcUuRLAWlG6sVGP5WekKLBdGRy4,2093
+users/components/RolesTab.tsx,sha256=bBPgUHLosZ7wcBFkT86AjbHEvtUc_MEjblyQmfHD7MI,2473
+users/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+users/contracts/events.py,sha256=ertB61rTpShVH6DdRkoymox90vMmnby0pPe2HAfF0fI,508
+users/contracts/schemas.py,sha256=axGqx7EbNDKZhCYQ5QJcz8zDIiL0zO_br9MhYOX5aE8,1952
+users/endpoints/__init__.py,sha256=8CGquvVRhTQoa3d18azmSlckXCNnOuoQiKPpaOsKiSQ,52
+users/endpoints/api.py,sha256=rWNuha1VlwsPINCR4B_h4-EgUISWBlcCJBIUAOyUp0k,8821
+users/endpoints/api_admin.py,sha256=LspB4futZjjJ_M2mgFORTk4tZ8fwGyymyVEmkfVzrfw,5546
+users/endpoints/views.py,sha256=Jf8F1hOLyOkmm6m4EyaxFHhUzPUnJCmHR_GNYyRTrBA,7852
+users/mailer/__init__.py,sha256=HgojsPCXbV___Qy4NOdAq0xBPhT8GAqykaH4-Q4gQo0,1056
+users/mailer/console.py,sha256=TMSIKWmWktjBg4O7tXr6Xo9EynEeTY_QLuqFESSr0rw,996
+users/mailer/smtp.py,sha256=0U7p14uys3akvC0QTqbun-0-iYxY6sG6Yex7K4hynAc,2654
+users/mailer/templates/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+users/mailer/templates/invite.txt,sha256=Krcaoc4Ezq9p6RWJaTzBdtM4JHrxCpbEZWEa5nwSaxo,54
+users/mailer/templates/reset_password.txt,sha256=sCsjxTF8EEMBRxAKjnuoXSynf6sSCuaCJ7wM_4jZRM8,32
+users/mailer/templates/verify_email.txt,sha256=V5ifrNvKT_ZcmpBcPEtvVOSdrh0a_xR01xDZ8t11JnQ,30
+users/models/__init__.py,sha256=ZJWV3OEZn56VqXY_pX7NX8d2NiIUWqt10A3n62UsLLU,693
+users/models/_base.py,sha256=UjYBWvdszy3KENo2Ti8YijRskVfooIdWzhsaMjdIocY,255
+users/models/access_token.py,sha256=tbwSRLCM5jgr_e8guhECCOe1b7B1ydqksd2y5FAl0mM,1002
+users/models/role.py,sha256=STghKPw_MPABnTRWa_o0ClAQV-Yquf4c6o6VeSg3vnw,1050
+users/models/user.py,sha256=GCBHgP-nIXdjelxWjwtkW8XQTlz5UBbtm2qokLoba3I,2346
+users/models/user_role.py,sha256=WPVaeRIsQnbunP65JJ2RgBhsL94s0G0pTqggn7YUvsA,1142
+users/pages/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+users/pages/AcceptInvite.tsx,sha256=R-QD3AkDiiX5YQCdDzcNPhILeFkRNpUhv1QVjWu43ek,3583
+users/pages/ForgotPassword.tsx,sha256=fcyqHqVnqbxFlOnaYt7AcGhkHUKSl0pCz3ieStxalgc,2936
+users/pages/Login.tsx,sha256=zl1jyVZeiyilDtEs9MjOWlM8DwfphfjoZwTDnlo6W_A,6121
+users/pages/Profile.tsx,sha256=hb6dk8uP0Zq6256-c87W5zAabVOke4yl4knlgTTAtRM,3649
+users/pages/Register.tsx,sha256=r_4kYwGiwMlPgqeyeCcHcI47J6C81SDE5lHIKujV-ug,5168
+users/pages/ResetPassword.tsx,sha256=auDD4W2t5a-9cO5fd-QDlGEMwPzs0rD9dzLMRilTc_M,3711
+users/pages/VerifyEmail.tsx,sha256=Nv4ay5iYtmSZrFkJ3PN7uN211RWg0Ra-A6iGm53zK4c,3206
+users/pages/Users/Edit.tsx,sha256=EGT1hLoDkgB8Xmi8SGTBuyOxmmYljZXKNNL07jxAcYQ,10339
+users/pages/Users/Index.tsx,sha256=NpCwM_G4PMSzEGkteZ0gNp7S1yPlSEehvxu2gpGK184,10965
+users/pages/Users/Invite.tsx,sha256=LqMiy194Wd5gyy60VdxqM8n_iLeZOiZ84xDL_KwIGaA,4658
+users/package.json,sha256=M39G_TMKeQb4su8uWboYLWmWX9UyzoXMWyuvFzfL0HY,373
+simple_module_users-0.0.1.dist-info/METADATA,sha256=ZDeHczXBw-qoVI-ar6L8JqV5W2e718TNR9bAd54c1TI,3198
+simple_module_users-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+simple_module_users-0.0.1.dist-info/entry_points.txt,sha256=u_1H-mTaMW2PH6gTZztp_m3uYEYS6thtiocaO2X5j9w,93
+simple_module_users-0.0.1.dist-info/licenses/LICENSE,sha256=Yn66lhLklsF5p7pa85_ksQrJ79Q-FgOaUAHevLBjer4,1068
+simple_module_users-0.0.1.dist-info/RECORD,,

simple_module_users-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_users-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+sm-users = users.cli:app
+
+[simple_module]
+users = users.module:UsersModule

simple_module_users-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

users/backend.py

@@ -0,0 +1,85 @@
+"""Auth backend — cookie transport + DB access-token strategy.
+
+The AuthenticationBackend is constructed once at import time in ``deps.py``
+with dev-safe defaults so ``fastapi_users.current_user(...)`` — which is
+captured by route-handler ``Depends(...)`` signatures at import time — has
+a stable instance to bind against.
+
+Real settings are applied at startup via :func:`reconfigure_cookie_transport`,
+which updates the singleton's ``CookieTransport`` fields in place. Because
+this reaches into fastapi-users' instance state, the package's major version
+is pinned narrowly in pyproject.toml.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import Depends
+from fastapi_users.authentication import AuthenticationBackend, CookieTransport
+from fastapi_users.authentication.strategy.db import (
+    AccessTokenDatabase,
+    DatabaseStrategy,
+)
+
+from users.db_adapter import get_access_token_db
+from users.models import UserAccessToken
+
+if TYPE_CHECKING:
+    from users.settings import UsersSettings
+
+_TOKEN_LIFETIME_SECONDS = 60 * 60 * 24 * 14  # 14 days
+_AUTH_BACKEND_NAME = "cookie"
+
+
+def build_cookie_transport(
+    cookie_name: str,
+    cookie_max_age_seconds: int,
+    cookie_secure: bool,
+    cookie_samesite: str,
+) -> CookieTransport:
+    return CookieTransport(
+        cookie_name=cookie_name,
+        cookie_max_age=cookie_max_age_seconds,
+        cookie_secure=cookie_secure,
+        cookie_httponly=True,
+        cookie_samesite=cookie_samesite,  # type: ignore[arg-type]
+    )
+
+
+def get_database_strategy(
+    access_token_db: AccessTokenDatabase[UserAccessToken] = Depends(get_access_token_db),
+    lifetime_seconds: int = _TOKEN_LIFETIME_SECONDS,
+) -> DatabaseStrategy:
+    return DatabaseStrategy(access_token_db, lifetime_seconds=lifetime_seconds)
+
+
+def build_auth_backend(
+    cookie_transport: CookieTransport,
+) -> AuthenticationBackend:
+    return AuthenticationBackend(
+        name=_AUTH_BACKEND_NAME,
+        transport=cookie_transport,
+        get_strategy=get_database_strategy,
+    )
+
+
+def reconfigure_cookie_transport(
+    backend: AuthenticationBackend,
+    settings: UsersSettings,
+) -> None:
+    """Apply production cookie config to an already-constructed backend.
+
+    Called from ``UsersModule.on_startup`` once the real ``UsersSettings``
+    is available on ``app.state``. This is the one place that depends on
+    fastapi-users' ``CookieTransport`` field names; any upstream rename
+    surfaces here rather than scattered across the codebase.
+    """
+    transport = backend.transport
+    assert isinstance(transport, CookieTransport), (
+        f"users auth_backend.transport must be a CookieTransport, got {type(transport)!r}"
+    )
+    transport.cookie_name = settings.cookie_name
+    transport.cookie_max_age = settings.cookie_max_age_seconds
+    transport.cookie_secure = settings.cookie_secure
+    transport.cookie_samesite = settings.cookie_samesite  # type: ignore[assignment] # ty: ignore[invalid-assignment]

users/bootstrap.py

@@ -0,0 +1,246 @@
+"""Shared admin-creation logic used by the CLI and env-var auto-bootstrap."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from fastapi_users.password import PasswordHelper
+from simple_module_core.dotenv import parse_dotenv
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from users.constants import (
+    ADMIN_ROLE_DESCRIPTION,
+    ADMIN_ROLE_ID,
+    ADMIN_ROLE_NAME,
+    USER_ROLE_DESCRIPTION,
+    USER_ROLE_ID,
+    USER_ROLE_NAME,
+)
+from users.models import Role, User, UserRole
+from users.settings import UsersSettings
+
+# Maps a UsersSettings attribute to the env var that seeds it on first boot.
+# Shared between the bootstrap function and the test fixture that isolates it.
+BOOTSTRAP_ENV_KEYS: dict[str, str] = {
+    "bootstrap_email": "SM_USERS_BOOTSTRAP_EMAIL",
+    "bootstrap_password": "SM_USERS_BOOTSTRAP_PASSWORD",
+    "bootstrap_user_email": "SM_USERS_BOOTSTRAP_USER_EMAIL",
+    "bootstrap_user_password": "SM_USERS_BOOTSTRAP_USER_PASSWORD",
+}
+
+logger = logging.getLogger("users.bootstrap")
+
+_EVT_CREATED = "users.bootstrap.created"
+_EVT_UPDATED = "users.bootstrap.updated"
+_EVT_NOOP = "users.bootstrap.noop"
+_EVT_USER_NOOP = "users.bootstrap.user_noop"
+_EVT_USER_CREATED = "users.bootstrap.user_created"
+_EVT_FAILED = "users.bootstrap.failed"
+
+
+@dataclass
+class CreateAdminResult:
+    user: User
+    created: bool  # False when admin already existed and we just ensured the role
+
+
+async def create_admin(
+    db: AsyncSession,
+    *,
+    email: str,
+    password: str,
+    full_name: str | None = None,
+    force: bool = False,
+) -> CreateAdminResult:
+    """Create or update an admin user. Idempotent by default.
+
+    - If no user with this email exists: create one with is_active=True,
+      is_verified=True, is_superuser=True; hash the password; ensure the
+      'admin' Role row exists (create from ADMIN_ROLE_ID if missing);
+      insert UserRole.
+    - If the user exists and force=True: update the password and ensure the
+      admin role is attached.
+    - If the user exists and force=False: return created=False without
+      changing the password.
+    """
+    existing = (
+        await db.execute(select(User).where(func.lower(User.email) == email.lower()))
+    ).scalar_one_or_none()
+
+    # Look up by name first (works on both Postgres and SQLite regardless of UUID
+    # storage format), then fall back to id-based lookup in case name was changed.
+    admin_role = (
+        await db.execute(select(Role).where(Role.name == ADMIN_ROLE_NAME))
+    ).scalar_one_or_none()
+    if admin_role is None:
+        admin_role = (
+            await db.execute(select(Role).where(Role.id == ADMIN_ROLE_ID))
+        ).scalar_one_or_none()
+    if admin_role is None:
+        # The seed migration (e3ce9754e6dc) inserts this row, so in a real
+        # deployment we should never hit this branch. Kept as a safety net for
+        # tests (where `create_all` runs without data migrations) and for
+        # scenarios where someone ran `alembic downgrade` past the seed
+        # revision but not past the schema revision.
+        admin_role = Role(
+            id=ADMIN_ROLE_ID, name=ADMIN_ROLE_NAME, description=ADMIN_ROLE_DESCRIPTION
+        )
+        db.add(admin_role)
+        await db.flush()
+
+    hasher = PasswordHelper()
+    if existing is None:
+        user = User(
+            email=email,
+            hashed_password=hasher.hash(password),
+            is_active=True,
+            is_verified=True,
+            is_superuser=True,
+            full_name=full_name,
+        )
+        db.add(user)
+        await db.flush()
+        db.add(UserRole(user_id=user.id, role_id=admin_role.id))
+        await db.commit()
+        await db.refresh(user)
+        logger.info(_EVT_CREATED, extra={"email": email, "id": str(user.id)})
+        return CreateAdminResult(user=user, created=True)
+
+    if force:
+        existing.hashed_password = hasher.hash(password)
+        existing.is_active = True
+        existing.is_verified = True
+        existing.is_superuser = True
+        if full_name is not None:
+            existing.full_name = full_name
+        existing_link = (
+            await db.execute(
+                select(UserRole).where(
+                    UserRole.user_id == existing.id, UserRole.role_id == admin_role.id
+                )
+            )
+        ).scalar_one_or_none()
+        if existing_link is None:
+            db.add(UserRole(user_id=existing.id, role_id=admin_role.id))
+        await db.commit()
+        logger.info(_EVT_UPDATED, extra={"email": email, "id": str(existing.id)})
+        return CreateAdminResult(user=existing, created=False)
+
+    logger.info(_EVT_NOOP, extra={"email": email, "id": str(existing.id)})
+    return CreateAdminResult(user=existing, created=False)
+
+
+async def create_standard_user(
+    db: AsyncSession,
+    *,
+    email: str,
+    password: str,
+    full_name: str | None = None,
+) -> CreateAdminResult:
+    """Create a non-admin user with the 'user' role. Idempotent (noop if exists).
+
+    Unlike ``create_admin`` this is not meant to be called from the CLI — it's
+    used by the env-var bootstrap to seed a second account for dev/testing.
+    """
+    existing = (
+        await db.execute(select(User).where(func.lower(User.email) == email.lower()))
+    ).scalar_one_or_none()
+    if existing is not None:
+        logger.info(_EVT_USER_NOOP, extra={"email": email, "id": str(existing.id)})
+        return CreateAdminResult(user=existing, created=False)
+
+    user_role = (
+        await db.execute(select(Role).where(Role.name == USER_ROLE_NAME))
+    ).scalar_one_or_none()
+    if user_role is None:
+        user_role = (
+            await db.execute(select(Role).where(Role.id == USER_ROLE_ID))
+        ).scalar_one_or_none()
+    if user_role is None:
+        # Safety net — the seed migration normally inserts this row.
+        user_role = Role(id=USER_ROLE_ID, name=USER_ROLE_NAME, description=USER_ROLE_DESCRIPTION)
+        db.add(user_role)
+        await db.flush()
+
+    user = User(
+        email=email,
+        hashed_password=PasswordHelper().hash(password),
+        is_active=True,
+        is_verified=True,
+        is_superuser=False,
+        full_name=full_name,
+    )
+    db.add(user)
+    await db.flush()
+    db.add(UserRole(user_id=user.id, role_id=user_role.id))
+    await db.commit()
+    await db.refresh(user)
+    logger.info(_EVT_USER_CREATED, extra={"email": email, "id": str(user.id)})
+    return CreateAdminResult(user=user, created=True)
+
+
+async def _user_table_is_empty(db: AsyncSession) -> bool:
+    count = (await db.execute(select(func.count()).select_from(User))).scalar_one()
+    return count == 0
+
+
+def _read_dotenv_bootstrap_vars() -> dict[str, str]:
+    """Return SM_USERS_BOOTSTRAP_* entries from ``.env`` (ignore everything else).
+
+    ``UsersSettings`` deliberately doesn't use ``env_file`` — runtime fields
+    come from the DB, and pulling the whole ``.env`` in would re-expose every
+    SMTP/cookie/token secret as an env knob. So we re-read ``.env`` just for
+    the four documented seed keys.
+    """
+    wanted = set(BOOTSTRAP_ENV_KEYS.values())
+    return {k: v for k, v in parse_dotenv().items() if k in wanted}
+
+
+async def bootstrap_admin_from_env(app: FastAPI) -> None:
+    """On-startup hook: create admin from env vars iff users table is empty.
+
+    Resolves each of the four bootstrap fields in order: ``UsersSettings``
+    (tests), then ``os.environ`` (docker/systemd), then ``.env`` (documented
+    dev path). If the admin email or password is still blank, returns
+    silently — same if the users table already has rows (so restarts don't
+    try to re-bootstrap).
+
+    Optionally also creates a non-admin user from
+    ``SM_USERS_BOOTSTRAP_USER_EMAIL`` + ``SM_USERS_BOOTSTRAP_USER_PASSWORD`` —
+    useful in dev for testing non-admin flows alongside the admin account.
+    """
+    settings: UsersSettings = app.state.users.settings
+    dotenv_vars = _read_dotenv_bootstrap_vars()
+    resolved = {
+        attr: getattr(settings, attr) or os.environ.get(env_key) or dotenv_vars.get(env_key, "")
+        for attr, env_key in BOOTSTRAP_ENV_KEYS.items()
+    }
+    email = resolved["bootstrap_email"]
+    password = resolved["bootstrap_password"]
+    user_email = resolved["bootstrap_user_email"]
+    user_password = resolved["bootstrap_user_password"]
+
+    if not email or not password:
+        return
+
+    session_factory = app.state.sm.db.session_factory
+    async with session_factory() as session:
+        if not await _user_table_is_empty(session):
+            logger.debug("users.bootstrap.skipped (users table non-empty)")
+            return
+
+        try:
+            await create_admin(session, email=email, password=password)
+            if user_email and user_password:
+                await create_standard_user(
+                    session,
+                    email=user_email,
+                    password=user_password,
+                )
+        except Exception:
+            logger.exception(_EVT_FAILED)
+            raise

users/cli.py

@@ -0,0 +1,75 @@
+"""Command-line entry points for the users module.
+
+Exposed via ``sm-users`` (see pyproject.toml [project.scripts]).
+
+    sm-users create-admin --email a@b.test --password sekret [--full-name Me]
+    sm-users create-admin --email a@b.test --password new --force
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+import typer
+from simple_module_hosting.settings import Settings
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+from users.bootstrap import create_admin
+
+app = typer.Typer(help="Users module administration.", no_args_is_help=True)
+
+
+@app.callback()
+def _main() -> None:
+    """Users module administration CLI."""
+
+
+@app.command("create-admin")
+def create_admin_cli(
+    email: str = typer.Option(..., "--email", "-e"),
+    password: str = typer.Option(..., "--password", "-p", prompt=True, hide_input=True),
+    full_name: str | None = typer.Option(None, "--full-name"),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Update the password even if this admin already exists.",
+    ),
+) -> None:
+    """Create (or update, with --force) an admin user."""
+    logging.basicConfig(level=logging.INFO)
+
+    async def _run() -> int:
+        settings = Settings()
+        engine = create_async_engine(settings.database_url)
+        # IMPORTANT: matches the module's own session factory
+        factory = async_sessionmaker(engine, expire_on_commit=False)
+        try:
+            async with factory() as session:
+                result = await create_admin(
+                    session,
+                    email=email,
+                    password=password,
+                    full_name=full_name,
+                    force=force,
+                )
+            if result.created:
+                typer.echo(f"Created admin {email} (id={result.user.id})")
+            elif force:
+                typer.echo(f"Updated admin {email} (id={result.user.id})")
+            else:
+                typer.echo(
+                    f"User {email} already exists. Pass --force to reset password.",
+                    err=True,
+                )
+                return 1
+            return 0
+        finally:
+            await engine.dispose()
+
+    sys.exit(asyncio.run(_run()))
+
+
+if __name__ == "__main__":
+    app()

users/components/IndexFilters.tsx

@@ -0,0 +1,72 @@
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@simple-module-py/ui/components/ui/select';
+
+export interface Filters {
+  status: 'all' | 'active' | 'disabled';
+  role: string;
+  verified: 'all' | 'yes' | 'no';
+  sort: 'email' | 'last_login_at' | 'created_at';
+  order: 'asc' | 'desc';
+}
+
+interface IndexFiltersProps {
+  filters: Filters;
+  roles: string[];
+  onChange: (next: Partial<Filters>) => void;
+}
+
+export function IndexFilters({ filters, roles, onChange }: IndexFiltersProps) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <Select
+        value={filters.status}
+        onValueChange={(v) => onChange({ status: v as Filters['status'] })}
+      >
+        <SelectTrigger size="sm" className="w-32">
+          <SelectValue placeholder="Status" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All statuses</SelectItem>
+          <SelectItem value="active">Active</SelectItem>
+          <SelectItem value="disabled">Disabled</SelectItem>
+        </SelectContent>
+      </Select>
+
+      <Select
+        value={filters.role || 'all'}
+        onValueChange={(v) => onChange({ role: v === 'all' ? '' : v })}
+      >
+        <SelectTrigger size="sm" className="w-36">
+          <SelectValue placeholder="Role" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All roles</SelectItem>
+          {roles.map((r) => (
+            <SelectItem key={r} value={r}>
+              {r}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+
+      <Select
+        value={filters.verified}
+        onValueChange={(v) => onChange({ verified: v as Filters['verified'] })}
+      >
+        <SelectTrigger size="sm" className="w-32">
+          <SelectValue placeholder="Verified" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All</SelectItem>
+          <SelectItem value="yes">Verified</SelectItem>
+          <SelectItem value="no">Unverified</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}