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

users/service.py

@@ -0,0 +1,257 @@
+"""UserService — admin operations delegating to the DB and UserManager."""
+
+from __future__ import annotations
+
+import secrets
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import delete, func, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from users.contracts.schemas import RoleListItem, UserCreate, UserListItem
+from users.exceptions import UserNotFoundError
+from users.manager import UserManager
+from users.models import Role, User, UserRole
+
+
+class UserService:
+    def __init__(
+        self,
+        db: AsyncSession,
+        user_manager: UserManager,
+    ) -> None:
+        self._db = db
+        self._manager = user_manager
+
+    # ── Helpers ─────────────────────────────────────────────────
+
+    async def _resolve_roles(self, role_names: list[str]) -> list[Role]:
+        """Return Role ORM objects matching the given names."""
+        if not role_names:
+            return []
+        result = await self._db.execute(select(Role).where(Role.name.in_(role_names)))
+        return list(result.scalars().all())
+
+    def to_list_item(self, user: User) -> UserListItem:
+        """Build the DTO from a User with roles already eager-loaded."""
+        return UserListItem(
+            id=user.id,
+            email=user.email,
+            full_name=user.full_name,
+            is_active=user.is_active,
+            is_verified=user.is_verified,
+            disabled_at=user.disabled_at,
+            last_login_at=user.last_login_at,
+            created_at=user.created_at,
+            roles=[r.name for r in user.roles],
+        )
+
+    async def list_roles(self) -> list[RoleListItem]:
+        stmt = (
+            select(Role, func.count(UserRole.user_id))
+            .outerjoin(UserRole, UserRole.role_id == Role.id)
+            .group_by(Role.id)
+            .order_by(Role.name)
+        )
+        result = await self._db.execute(stmt)
+        return [
+            RoleListItem(
+                id=role.id,
+                name=role.name,
+                description=role.description,
+                user_count=user_count,
+            )
+            for role, user_count in result.all()
+        ]
+
+    async def _get_user_with_roles(self, user_id: uuid.UUID) -> User | None:
+        result = await self._db.execute(
+            select(User).where(User.id == user_id).options(selectinload(User.roles))
+        )
+        return result.scalar_one_or_none()
+
+    async def _require_user(self, user_id: uuid.UUID) -> User:
+        """Fetch a user with roles eager-loaded, or raise UserNotFoundError."""
+        user = await self._get_user_with_roles(user_id)
+        if user is None:
+            raise UserNotFoundError(user_id)
+        return user
+
+    # ── Public API ───────────────────────────────────────────────
+
+    async def list_users(
+        self,
+        *,
+        page: int = 1,
+        per_page: int = 20,
+        search: str | None = None,
+        status: str | None = None,
+        role_name: str | None = None,
+        verified: str | None = None,
+        sort: str = "email",
+        order: str = "asc",
+    ) -> tuple[list[UserListItem], int]:
+        """Returns (items, total_count). last_login_at sort always uses NULLS LAST."""
+        stmt = select(User).options(selectinload(User.roles))
+        count_stmt = select(func.count()).select_from(User)
+
+        conditions = []
+
+        if search:
+            pattern = f"%{search}%"
+            conditions.append(
+                or_(
+                    User.email.ilike(pattern),
+                    User.full_name.ilike(pattern),
+                )
+            )
+
+        if status == "active":
+            conditions.append(User.is_active.is_(True))
+        elif status == "disabled":
+            conditions.append(User.is_active.is_(False))
+
+        if verified == "yes":
+            conditions.append(User.is_verified.is_(True))
+        elif verified == "no":
+            conditions.append(User.is_verified.is_(False))
+
+        if role_name is not None:
+            subq = (
+                select(UserRole.user_id)
+                .join(Role, Role.id == UserRole.role_id)
+                .where(Role.name == role_name)
+            )
+            conditions.append(User.id.in_(subq))
+
+        for cond in conditions:
+            stmt = stmt.where(cond)
+            count_stmt = count_stmt.where(cond)
+
+        total = (await self._db.execute(count_stmt)).scalar_one()
+
+        sort_col_map = {
+            "email": User.email,
+            "last_login_at": User.last_login_at,
+            "created_at": User.created_at,
+        }
+        sort_col = sort_col_map.get(sort, User.email)
+
+        if sort == "last_login_at":
+            order_clause = (
+                sort_col.desc().nulls_last()  # type: ignore[union-attr]
+                if order == "desc"
+                else sort_col.asc().nulls_last()  # type: ignore[union-attr]
+            )
+        else:
+            order_clause = (
+                sort_col.desc() if order == "desc" else sort_col.asc()  # type: ignore[union-attr]
+            )
+
+        stmt = stmt.order_by(order_clause).offset((page - 1) * per_page).limit(per_page)
+        rows = (await self._db.execute(stmt)).scalars().all()
+
+        items = [self.to_list_item(u) for u in rows]
+        return items, total
+
+    async def invite(
+        self,
+        email: str,
+        full_name: str | None,
+        role_names: list[str],
+        *,
+        invited_by: User | None = None,
+    ) -> tuple[User, str]:
+        """Creates unverified user + random unusable password, assigns roles,
+        mints a verification token. Returns (user, token)."""
+        password = secrets.token_urlsafe(32)
+        user_create = UserCreate(
+            email=email,
+            password=password,
+            full_name=full_name,
+            is_active=True,
+            is_verified=False,
+        )
+        user = await self._manager.create(user_create, safe=False)
+
+        # Assign roles
+        roles = await self._resolve_roles(role_names)
+        invited_by_str = str(invited_by.id) if invited_by else None
+        for role in roles:
+            self._db.add(
+                UserRole(
+                    user_id=user.id,
+                    role_id=role.id,
+                    assigned_by=invited_by_str,
+                )
+            )
+        if roles:
+            await self._db.flush()
+            await self._db.refresh(user, attribute_names=["roles"])
+
+        token = await self._manager.generate_verification_token(user)
+        return user, token
+
+    async def disable(self, user_id: uuid.UUID) -> User:
+        user = await self._require_user(user_id)
+        user.disabled_at = datetime.now(UTC)
+        user.is_active = False
+        await self._db.flush()
+        return user
+
+    async def enable(self, user_id: uuid.UUID) -> User:
+        user = await self._require_user(user_id)
+        user.disabled_at = None
+        user.is_active = True
+        await self._db.flush()
+        return user
+
+    async def mark_verified(self, user_id: uuid.UUID) -> User:
+        user = await self._require_user(user_id)
+        if not user.is_verified:
+            user.is_verified = True
+            await self._db.flush()
+        return user
+
+    async def set_roles(
+        self,
+        user_id: uuid.UUID,
+        role_names: list[str],
+        *,
+        assigned_by: str | None = None,
+    ) -> User:
+        user = await self._require_user(user_id)
+
+        # Delete all existing role assignments for this user
+        await self._db.execute(delete(UserRole).where(UserRole.user_id == user_id))
+
+        # Insert new role assignments
+        roles = await self._resolve_roles(role_names)
+        for role in roles:
+            self._db.add(
+                UserRole(
+                    user_id=user_id,
+                    role_id=role.id,
+                    assigned_by=assigned_by,
+                )
+            )
+
+        await self._db.flush()
+        await self._db.refresh(user, attribute_names=["roles"])
+        return user
+
+    async def generate_reset_link(self, user_id: uuid.UUID, base_url: str) -> str:
+        """Build an admin-copyable password-reset URL. No email side-effect."""
+        user = await self._require_user(user_id)
+
+        token = await self._manager.generate_reset_password_token(user)
+        return f"{base_url.rstrip('/')}/users/reset-password?token={token}"
+
+    async def get_with_roles(self, user_id: uuid.UUID) -> User | None:
+        return await self._get_user_with_roles(user_id)
+
+    async def get_list_item(self, user_id: uuid.UUID) -> UserListItem:
+        user = await self._require_user(user_id)
+        return self.to_list_item(user)

users/settings.py

@@ -0,0 +1,99 @@
+"""Users module settings — DB-backed via ``register_module_settings``.
+
+Construction no longer reads ``SM_USERS_*`` environment variables. Values
+come from pydantic defaults at boot, then get hydrated from the DB by the
+hosting lifespan before module ``on_startup`` runs. Runtime changes go
+through ``settings.reload.apply_changes_and_reload``.
+
+The one remaining env read is ``SM_ENVIRONMENT``, consulted by the
+``@model_validator`` to refuse placeholder token secrets in production —
+that's a host-level setting, not a users-module field.
+"""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+
+_PLACEHOLDER_RESET_SECRET = "dev-reset-token-secret-change-me"
+_PLACEHOLDER_VERIFY_SECRET = "dev-verify-token-secret-change-me"
+
+
+class UsersSettings(BaseSettings):
+    """Local user management configuration."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    # Self-service signup
+    allow_signup: bool = False
+    require_verification: bool = True
+
+    # Token secrets — MUST be set in production. Dev default is a deterministic
+    # placeholder that's obvious in logs so it can't be mistaken for a real key.
+    reset_password_token_secret: str = "dev-reset-token-secret-change-me"
+    verification_token_secret: str = "dev-verify-token-secret-change-me"
+    reset_password_token_lifetime_seconds: int = 60 * 60  # 1 hour
+    verification_token_lifetime_seconds: int = 60 * 60 * 24 * 7  # 7 days
+
+    # Cookie (fastapi-users AuthenticationBackend)
+    cookie_name: str = "sm_auth"
+    cookie_max_age_seconds: int = 60 * 60 * 24 * 14  # 14 days
+    cookie_secure: bool = True  # flipped False in dev by the module at startup
+    cookie_samesite: str = "lax"
+
+    # Mailer
+    mailer: str = Field(default="console", pattern="^(console|smtp)$")
+    base_url: str = "http://localhost:8000"
+    smtp_host: str = ""
+    smtp_port: int = 587
+    smtp_username: str = ""
+    smtp_password: str = ""
+    smtp_from: str = "no-reply@localhost"
+    smtp_tls: bool = True
+
+    # Rate limit (login — failure-based lockout)
+    login_rate_limit_failures: int = 5
+    login_rate_limit_window_seconds: int = 300
+    login_rate_limit_cooldown_seconds: int = 900
+
+    # Rate limit (auth side-effects: forgot-password, register, accept-invite,
+    # request-verify-token). Counts every attempt per IP per window.
+    auth_rate_limit_attempts: int = 10
+    auth_rate_limit_window_seconds: int = 300
+
+    # Bootstrap (env-var auto-create users on first boot)
+    bootstrap_email: str = ""
+    bootstrap_password: str = ""
+    # Optional second seed user with the "user" role — handy in dev for
+    # testing non-admin flows without logging out/in repeatedly.
+    bootstrap_user_email: str = ""
+    bootstrap_user_password: str = ""
+
+    @model_validator(mode="after")
+    def _forbid_placeholder_token_secrets_in_production(self) -> UsersSettings:
+        """Fail boot if the reset/verify token secrets are still placeholders.
+
+        Both are HMAC keys for fastapi-users JWTs. A well-known default lets
+        an attacker mint password-reset or email-verification tokens for any
+        user. The environment is read from ``SM_ENVIRONMENT`` (host setting)
+        so this check has no runtime coupling to the hosting package.
+        """
+        env = os.environ.get("SM_ENVIRONMENT", "development")
+        if env in NON_PROD_ENVIRONMENTS:
+            return self
+        bad = []
+        if self.reset_password_token_secret == _PLACEHOLDER_RESET_SECRET:
+            bad.append("RESET_PASSWORD_TOKEN_SECRET")
+        if self.verification_token_secret == _PLACEHOLDER_VERIFY_SECRET:
+            bad.append("VERIFICATION_TOKEN_SECRET")
+        if bad:
+            names = ", ".join(bad)
+            raise ValueError(
+                f"users.{names} must be set to non-default value(s) when "
+                f"SM_ENVIRONMENT={env!r}. Generate with "
+                "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
+            )
+        return self

users/state.py

@@ -0,0 +1,33 @@
+"""Module-scoped state container for the users module.
+
+Stored as ``app.state.users`` by :meth:`UsersModule.register_settings` (for
+fields available at that phase) and populated the rest of the way during
+:meth:`UsersModule.on_startup` (for fields that depend on the DB or other
+framework services).
+
+Not frozen — ``on_startup`` needs to set fields that aren't available at
+``register_settings`` time. Convention: set once during boot, treat as
+read-only after.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from users.mailer import Mailer
+    from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+    from users.roles_cache import RoleSummary
+    from users.settings import UsersSettings
+
+
+@dataclass
+class UsersState:
+    """Users-module singletons. Single slot at ``app.state.users``."""
+
+    settings: UsersSettings
+    mailer: Mailer | None = None
+    rate_limiter: LoginRateLimiter | None = None
+    auth_throughput_limiter: ThroughputLimiter | None = None
+    roles_cache: list[RoleSummary] = field(default_factory=list)