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

users/manager.py

@@ -0,0 +1,146 @@
+"""UserManager — handles lifecycle hooks + custom verification-token helper."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from fastapi import Depends, Request
+from fastapi_users import BaseUserManager, UUIDIDMixin, exceptions
+from fastapi_users.jwt import generate_jwt
+
+from users.contracts.events import UserRegistered
+from users.db_adapter import UserDatabaseWithRoles, get_user_db
+from users.mailer import Mailer
+from users.models import User
+
+if TYPE_CHECKING:
+    from users.settings import UsersSettings
+
+
+class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
+    """Customizes password validation, token secrets, and lifecycle emails."""
+
+    # Secrets and lifetimes pulled from settings at construction time so
+    # subclasses of UserManager work in tests without full app startup.
+    def __init__(
+        self,
+        user_db: UserDatabaseWithRoles,
+        mailer: Mailer,
+        settings: UsersSettings,
+    ) -> None:
+        super().__init__(user_db)
+        self.mailer = mailer
+        self.reset_password_token_secret = settings.reset_password_token_secret
+        self.verification_token_secret = settings.verification_token_secret
+        self.reset_password_token_lifetime_seconds = settings.reset_password_token_lifetime_seconds
+        self.verification_token_lifetime_seconds = settings.verification_token_lifetime_seconds
+
+    # ── Password policy ──────────────────────────────────────
+
+    async def validate_password(self, password: str, user) -> None:
+        if len(password) < 8:
+            raise exceptions.InvalidPasswordException(
+                reason="Password must be at least 8 characters"
+            )
+        if password.lower() in user.email.lower():
+            raise exceptions.InvalidPasswordException(reason="Password cannot contain your email")
+        if password.isdigit():
+            raise exceptions.InvalidPasswordException(reason="Password cannot be all numbers")
+
+    # ── Lifecycle hooks ──────────────────────────────────────
+
+    async def on_after_register(self, user: User, request: Request | None = None) -> None:
+        await self._publish_user_registered(user, request)
+        if not user.is_verified:
+            # Kicks off on_after_request_verify, which sends the email
+            await self.request_verify(user, request)
+
+    async def _publish_user_registered(self, user: User, request: Request | None) -> None:
+        """Emit ``UserRegistered`` on the app-wide event bus.
+
+        CLI bootstrap and unit tests instantiate the manager without a
+        request, so there's no app context from which to reach the bus —
+        publication is best-effort in those cases.
+        """
+        if request is None:
+            return
+        await request.app.state.sm.event_bus.publish(
+            UserRegistered(user_id=user.id, email=user.email)
+        )
+
+    async def on_after_forgot_password(
+        self, user: User, token: str, request: Request | None = None
+    ) -> None:
+        await self.mailer.send_password_reset(user.email, token)
+
+    async def on_after_request_verify(
+        self, user: User, token: str, request: Request | None = None
+    ) -> None:
+        await self.mailer.send_verification(user.email, token)
+
+    async def on_after_login(
+        self, user: User, request: Request | None = None, response=None
+    ) -> None:
+        user.last_login_at = datetime.now(UTC)
+        await self.user_db.update(user, {"last_login_at": user.last_login_at})
+
+    # ── Token helpers (no email side-effect) ─────────────────
+
+    async def generate_verification_token(self, user: User) -> str:
+        """Mint a verify-audience JWT without firing on_after_request_verify.
+
+        Used by the admin-invite flow: the verify-token primitive is reused
+        for invites, but the email template differs. request_verify() couples
+        token generation with email send — this decouples them.
+        """
+        token_data = {
+            "sub": str(user.id),
+            "email": user.email,
+            "aud": self.verification_token_audience,
+        }
+        return generate_jwt(
+            token_data,
+            self.verification_token_secret,
+            self.verification_token_lifetime_seconds,
+        )
+
+    async def generate_reset_password_token(self, user: User) -> str:
+        """Mint a reset-audience JWT without firing on_after_forgot_password.
+
+        Shape matches ``BaseUserManager.forgot_password``: the payload includes
+        ``password_fgpt`` (a bcrypt of the current hashed_password) so the token
+        invalidates when the password changes. Used by the admin
+        reset-password-link endpoint, where the admin copies the link instead
+        of triggering an email.
+
+        The fingerprint must be bcrypt-style because the stock
+        ``reset_password`` path in fastapi-users verifies it with
+        ``password_helper.verify_and_update``. Bcrypt is CPU-bound (~100ms at
+        default rounds) so we offload it to a worker thread — otherwise a
+        single admin action would stall the event loop for other requests.
+        """
+        fingerprint = await asyncio.to_thread(self.password_helper.hash, user.hashed_password)
+        token_data = {
+            "sub": str(user.id),
+            "password_fgpt": fingerprint,
+            "aud": self.reset_password_token_audience,
+        }
+        return generate_jwt(
+            token_data,
+            self.reset_password_token_secret,
+            self.reset_password_token_lifetime_seconds,
+        )
+
+
+async def get_user_manager(
+    request: Request,
+    user_db: UserDatabaseWithRoles = Depends(get_user_db),
+):
+    """FastAPI dependency — pulls mailer and settings off app.state."""
+    users = request.app.state.users
+    mailer = users.mailer
+    settings = users.settings
+    yield UserManager(user_db, mailer, settings)

users/middleware.py

@@ -0,0 +1,143 @@
+"""Local-user auth middleware — replaces the Keycloak session reader.
+
+Reads ``session["user_id"]``, loads the User row with eagerly-loaded roles,
+builds a UserContext, and sets ``request.state.user`` + the
+``current_user_id`` ContextVar consumed by DB audit listeners.
+
+The resolved ``UserContext`` is cached in the signed session cookie under
+``session["user_ctx"]`` so subsequent requests skip the DB lookup. The cache
+is refreshed when the session is cleared (logout / rotation) or when the
+cached payload is missing/invalid. Trade-off: admin-side changes (role
+assignment, disable/enable) do not take effect until the affected user's
+session is recreated (re-login or session expiry); acceptable for this app.
+
+Registered via ``UsersModule.register_middleware``.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+
+from auth.contracts.schemas import UserContext
+from simple_module_db.listeners import current_user_id
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+from starlette.requests import Request
+from starlette.responses import RedirectResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from users.constants import SESSION_USER_ID_KEY
+from users.models import User
+
+logger = logging.getLogger(__name__)
+
+SESSION_USER_CTX_KEY = "user_ctx"
+_SESSION_USER_ID_KEY = SESSION_USER_ID_KEY
+_SESSION_NEXT_KEY = "next"
+_SCOPE_HTTP = "http"
+_LOGIN_REDIRECT = "/users/login"
+
+# Paths that don't require authentication.
+PUBLIC_PATHS = (
+    "/users/login",
+    "/users/register",
+    "/users/forgot-password",
+    "/users/reset-password",
+    "/users/verify",
+    "/users/invite/accept",
+    "/api/users/auth/",
+    "/api/users/register",
+    "/health",
+    "/static/",
+    "/api/docs",
+    "/api/redoc",
+    "/openapi.json",
+    "/i18n/",
+)
+EXACT_PUBLIC_PATHS = ("/",)
+
+
+class AuthMiddleware:
+    """Redirect unauthenticated users to /users/login.
+
+    On cache hit (``session["user_ctx"]`` present), skips the DB entirely.
+    On cache miss, loads the user with roles, validates active/enabled, and
+    writes the resolved context back to the session.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        path = scope["path"]
+        is_public = any(path.startswith(p) for p in PUBLIC_PATHS) or path in EXACT_PUBLIC_PATHS
+
+        session = scope["session"]
+        raw_user_id = session.get(_SESSION_USER_ID_KEY)
+
+        user_ctx: UserContext | None = None
+        if raw_user_id:
+            user_id_str = str(raw_user_id)
+            # Fast path — rebuild from the signed session cookie.
+            user_ctx = UserContext.from_session_dict(session.get(SESSION_USER_CTX_KEY))
+            if user_ctx is None or user_ctx.id != user_id_str:
+                try:
+                    user_uuid = uuid.UUID(user_id_str)
+                except (ValueError, TypeError):
+                    logger.warning("Invalid user_id in session: %r", raw_user_id)
+                    session.pop(_SESSION_USER_ID_KEY, None)
+                    session.pop(SESSION_USER_CTX_KEY, None)
+                    user_ctx = None
+                else:
+                    user_ctx = await self._load_user(scope, user_uuid)
+                    if user_ctx is None:
+                        # User was deleted / disabled since session creation.
+                        session.pop(_SESSION_USER_ID_KEY, None)
+                        session.pop(SESSION_USER_CTX_KEY, None)
+                    else:
+                        session[SESSION_USER_CTX_KEY] = user_ctx.to_session_dict()
+
+        if user_ctx is None and not is_public:
+            request = Request(scope)
+            session[_SESSION_NEXT_KEY] = str(request.url)
+            response = RedirectResponse(_LOGIN_REDIRECT, status_code=302)
+            await response(scope, receive, send)
+            return
+
+        if user_ctx is not None:
+            request = Request(scope)
+            request.state.user = user_ctx
+            token = current_user_id.set(user_ctx.id)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                current_user_id.reset(token)
+            return
+
+        await self.app(scope, receive, send)
+
+    async def _load_user(self, scope: Scope, user_id: uuid.UUID) -> UserContext | None:
+        """Open a fresh session from app.state.db and load the User + roles.
+
+        Returns a UserContext, or None if the user doesn't exist or is
+        disabled/inactive. The session is closed on exit; we never commit
+        (read-only).
+        """
+        try:
+            session_factory = scope["app"].state.sm.db.session_factory
+            async with session_factory() as db_session:
+                stmt = select(User).where(User.id == user_id).options(selectinload(User.roles))
+                user = (await db_session.execute(stmt)).scalar_one_or_none()
+                if user is None:
+                    return None
+                if not user.is_active or user.disabled_at is not None:
+                    return None
+                return UserContext.from_user(user)
+        except Exception:
+            logger.exception("Failed to load user %s from DB; treating as unauthenticated", user_id)
+            return None

users/models/__init__.py

@@ -0,0 +1,24 @@
+"""SQLModel tables for the users module — one entity per file under this package.
+
+Existing imports like ``from users.models import User`` keep working via the
+re-exports below.
+"""
+
+from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase
+from fastapi_users_db_sqlalchemy.access_token import SQLAlchemyAccessTokenDatabase
+
+from users.models._base import Base
+from users.models.access_token import UserAccessToken
+from users.models.role import Role
+from users.models.user import User
+from users.models.user_role import UserRole
+
+__all__ = [
+    "Base",
+    "Role",
+    "SQLAlchemyAccessTokenDatabase",
+    "SQLAlchemyUserDatabase",
+    "User",
+    "UserAccessToken",
+    "UserRole",
+]

users/models/_base.py

@@ -0,0 +1,9 @@
+"""Shared Base for the users module's tables.
+
+Lives in its own module so individual entity files can import it without
+triggering a package ``__init__`` cycle.
+"""
+
+from simple_module_db.base import create_module_base
+
+Base = create_module_base("users")

users/models/access_token.py

@@ -0,0 +1,33 @@
+"""Access-token table backing fastapi-users' DatabaseStrategy.
+
+Column surface mirrors fastapi-users' ``SQLAlchemyBaseAccessTokenTableUUID``
+so the ``SQLAlchemyAccessTokenDatabase`` adapter binds to it without
+inheriting from the upstream base class.
+"""
+
+import uuid
+from datetime import datetime
+
+from fastapi_users_db_sqlalchemy.generics import GUID, TIMESTAMPAware, now_utc
+from sqlmodel import Field
+
+from users.models._base import Base
+
+
+class UserAccessToken(Base, table=True):  # ty: ignore[unsupported-base]
+    """fastapi-users DatabaseStrategy-backed access tokens."""
+
+    __tablename__ = "users_access_token"
+
+    token: str = Field(max_length=43, primary_key=True)
+    created_at: datetime = Field(
+        default_factory=now_utc,
+        sa_type=TIMESTAMPAware(timezone=True),
+        index=True,
+    )
+    user_id: uuid.UUID = Field(
+        sa_type=GUID,
+        foreign_key="users_user.id",
+        ondelete="CASCADE",
+        index=True,  # PostgreSQL does not auto-index FKs
+    )

users/models/role.py

@@ -0,0 +1,34 @@
+"""Role table — a named role that holds permission strings."""
+
+# NOTE: intentionally no ``from __future__ import annotations`` — SQLModel
+# Relationship resolution requires runtime annotations.
+
+import uuid
+
+from fastapi_users_db_sqlalchemy.generics import GUID
+from simple_module_db.mixins import AuditMixin
+from sqlmodel import Field, Relationship
+
+from users.models._base import Base
+from users.models.user import User
+from users.models.user_role import UserRole
+
+
+class Role(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """A named role that can hold a set of permission strings."""
+
+    __tablename__ = "users_role"
+
+    id: uuid.UUID = Field(
+        default_factory=uuid.uuid4,
+        sa_type=GUID,
+        primary_key=True,
+    )
+    name: str = Field(max_length=64, unique=True, index=True)
+    description: str | None = Field(default=None, max_length=255)
+
+    users: list[User] = Relationship(
+        link_model=UserRole,
+        back_populates="roles",
+        sa_relationship_kwargs={"lazy": "noload"},
+    )

users/models/user.py

@@ -0,0 +1,67 @@
+"""Local user table.
+
+Column surface mirrors fastapi-users' ``SQLAlchemyBaseUserTableUUID`` so the
+``SQLAlchemyUserDatabase`` adapter binds to it without inheriting from the
+upstream base class (which uses SQLAlchemy ``Mapped`` and is incompatible with
+SQLModel's metaclass).
+"""
+
+# NOTE: intentionally no ``from __future__ import annotations`` — SQLModel
+# Relationship resolution requires runtime annotations (not stringified ones)
+# for forward references like ``list["Role"]`` to work correctly.
+
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from fastapi_users_db_sqlalchemy.generics import GUID
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import DateTime, Index, text
+from sqlmodel import Field, Relationship
+
+from users.models._base import Base
+from users.models.user_role import UserRole
+
+if TYPE_CHECKING:
+    # Resolved at runtime by SQLModel via the string forward ref;
+    # this import only feeds the type checker.
+    from users.models.role import Role
+
+
+class User(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Local user. Column surface mirrors fastapi-users' SQLAlchemyBaseUserTableUUID."""
+
+    __tablename__ = "users_user"
+
+    id: uuid.UUID = Field(
+        default_factory=uuid.uuid4,
+        sa_type=GUID,
+        primary_key=True,
+    )
+    email: str = Field(max_length=320, unique=True, index=True)
+    hashed_password: str = Field(max_length=1024)
+    is_active: bool = Field(default=True)
+    is_superuser: bool = Field(default=False)
+    is_verified: bool = Field(default=False)
+
+    full_name: str | None = Field(default=None, max_length=255)
+    tenant_id: str | None = Field(default=None, max_length=50, index=True)
+    disabled_at: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),
+    )
+    last_login_at: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),
+        index=True,
+    )
+
+    roles: list["Role"] = Relationship(
+        link_model=UserRole,
+        back_populates="users",
+        sa_relationship_kwargs={"lazy": "noload"},
+    )
+
+    # Functional index so the ``lower(email)`` predicate used by
+    # ``UserDatabaseWithRoles.get_by_email`` can be served from an index.
+    __table_args__ = (Index("ix_users_user_email_lower", text("lower(email)")),)

users/models/user_role.py

@@ -0,0 +1,39 @@
+"""Association table linking users and roles."""
+
+import uuid
+from datetime import datetime
+
+from fastapi_users_db_sqlalchemy.generics import GUID, now_utc
+from sqlalchemy import DateTime, Index
+from sqlmodel import Field
+
+from users.models._base import Base
+
+
+class UserRole(Base, table=True):  # ty: ignore[unsupported-base]
+    """Association table between users and roles."""
+
+    __tablename__ = "users_user_role"
+
+    user_id: uuid.UUID = Field(
+        sa_type=GUID,
+        foreign_key="users_user.id",
+        ondelete="CASCADE",
+        primary_key=True,
+    )
+    role_id: uuid.UUID = Field(
+        sa_type=GUID,
+        foreign_key="users_role.id",
+        ondelete="CASCADE",
+        primary_key=True,
+    )
+    assigned_at: datetime = Field(
+        default_factory=now_utc,
+        sa_type=DateTime(timezone=True),
+    )
+    assigned_by: str | None = Field(default=None, max_length=255)
+
+    # The composite PK covers ``user_id``-first lookups; add a standalone
+    # index on ``role_id`` for reverse lookups — PostgreSQL does not
+    # auto-index FKs.
+    __table_args__ = (Index("ix_users_user_role_role_id", "role_id"),)

users/module.py

@@ -0,0 +1,155 @@
+"""Users module — local-account authentication and user management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from users.constants import (
+    ADMIN_ROLE_NAME,
+    PERM_USERS_MANAGE,
+    PERM_USERS_SELF_PROFILE,
+    USER_ROLE_NAME,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+_MODULE_DEPENDENCY_AUTH = "Auth"
+
+# Menu URLs
+_URL_USERS_ADMIN = "/users/admin"
+_URL_USERS_ME = "/users/me"
+_URL_USERS_LOGOUT = "/users/logout"
+
+# Menu icons
+_ICON_USERS = "users"
+_ICON_USER = "user"
+_ICON_LOG_OUT = "log-out"
+
+
+class UsersModule(ModuleBase):
+    meta = ModuleMeta(
+        name="Users",
+        route_prefix="/api/users",
+        view_prefix="/users",
+        depends_on=[_MODULE_DEPENDENCY_AUTH],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
+        from auth.contracts.schemas import UserContext
+
+        from users.settings import UsersSettings
+        from users.state import UsersState
+
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(app, "users", UsersSettings, lambda s: UsersState(settings=s))
+
+        def serialize_principal(user: UserContext) -> dict:
+            return {
+                "id": user.id,
+                "name": user.name,
+                "email": user.email,
+                "roles": user.roles,
+            }
+
+        app.state.principal_serializer = serialize_principal
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            "Users",
+            [PERM_USERS_MANAGE, PERM_USERS_SELF_PROFILE],
+        )
+        registry.map_role(USER_ROLE_NAME, [PERM_USERS_SELF_PROFILE])
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        # Admin-only user management
+        registry.add(
+            MenuItem(
+                label="Users",
+                url=_URL_USERS_ADMIN,
+                icon=_ICON_USERS,
+                order=30,
+                section=MenuSection.SIDEBAR,
+                roles=[ADMIN_ROLE_NAME],
+            )
+        )
+        # Self-service: profile + logout live in the user dropdown.
+        registry.add(
+            MenuItem(
+                label="Profile",
+                url=_URL_USERS_ME,
+                icon=_ICON_USER,
+                order=990,
+                section=MenuSection.USER_DROPDOWN,
+            )
+        )
+        registry.add(
+            MenuItem(
+                label="Logout",
+                url=_URL_USERS_LOGOUT,
+                icon=_ICON_LOG_OUT,
+                order=999,
+                section=MenuSection.USER_DROPDOWN,
+                method="post",
+            )
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from users.endpoints.api import register_auth_routes
+        from users.endpoints.views import router as views
+
+        # The register router is always mounted; its `allow_signup` gate lives
+        # on a per-request dependency, so toggling the setting at runtime takes
+        # effect without needing to remount.
+        register_auth_routes(api_router)
+        view_router.include_router(views)
+
+    def register_middleware(self, app: FastAPI) -> None:
+        from users.middleware import AuthMiddleware
+
+        app.add_middleware(AuthMiddleware)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        """Build the mailer, rate limiter, and apply production cookie params."""
+        import asyncio
+
+        from users.backend import reconfigure_cookie_transport
+        from users.bootstrap import bootstrap_admin_from_env
+        from users.deps import auth_backend
+        from users.mailer import build_mailer
+        from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+        from users.roles_cache import refresh_roles_cache
+
+        state = app.state.users
+        s = state.settings
+        state.mailer = build_mailer(s)
+        state.rate_limiter = LoginRateLimiter(
+            max_failures=s.login_rate_limit_failures,
+            window_seconds=s.login_rate_limit_window_seconds,
+            cooldown_seconds=s.login_rate_limit_cooldown_seconds,
+        )
+        state.auth_throughput_limiter = ThroughputLimiter(
+            max_attempts=s.auth_rate_limit_attempts,
+            window_seconds=s.auth_rate_limit_window_seconds,
+        )
+
+        reconfigure_cookie_transport(auth_backend, s)
+
+        await asyncio.gather(
+            bootstrap_admin_from_env(app),
+            refresh_roles_cache(app),
+        )

users/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/users",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Users module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}