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

users/components/RolesTab.tsx

@@ -0,0 +1,72 @@
+import { Link } from '@inertiajs/react';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { TabsContent } from '@simple-module-py/ui/components/ui/tabs';
+import { Pencil, ShieldCheck } from 'lucide-react';
+
+export interface RoleItem {
+  id: string;
+  name: string;
+  description?: string | null;
+  user_count: number;
+}
+
+export function RolesTab({ roles }: { roles: RoleItem[] }) {
+  return (
+    <TabsContent value="roles">
+      <Card>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Role</TableHead>
+              <TableHead className="hidden md:table-cell">Description</TableHead>
+              <TableHead>Users</TableHead>
+              <TableHead className="text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {roles.map((role) => (
+              <TableRow key={role.id}>
+                <TableCell className="font-medium">{role.name}</TableCell>
+                <TableCell className="hidden md:table-cell text-muted-foreground text-sm">
+                  {role.description || '—'}
+                </TableCell>
+                <TableCell>
+                  <Badge variant="secondary" className="tabular-nums">
+                    {role.user_count}
+                  </Badge>
+                </TableCell>
+                <TableCell className="text-right">
+                  <Button asChild variant="ghost" size="icon-sm">
+                    <Link href={`/permissions/roles/${role.id}/edit`} aria-label="Edit role">
+                      <Pencil />
+                    </Link>
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))}
+            {roles.length === 0 && (
+              <TableRow>
+                <TableCell colSpan={4} className="h-32 text-center">
+                  <div className="flex flex-col items-center gap-2 text-muted-foreground">
+                    <ShieldCheck className="size-8" />
+                    <p>No roles defined</p>
+                  </div>
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </Card>
+    </TabsContent>
+  );
+}

users/constants.py

@@ -0,0 +1,42 @@
+"""Stable identifiers used by both the seed migration and tests."""
+
+import uuid
+
+ADMIN_ROLE_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+USER_ROLE_ID = uuid.UUID("00000000-0000-0000-0000-000000000002")
+
+# Role name strings
+ADMIN_ROLE_NAME = "admin"
+USER_ROLE_NAME = "user"
+
+# Role descriptions
+ADMIN_ROLE_DESCRIPTION = "Administrator"
+USER_ROLE_DESCRIPTION = "Standard user"
+
+# Permission identifiers
+PERM_USERS_MANAGE = "users.manage"
+PERM_USERS_SELF_PROFILE = "users.self.profile"
+
+# Session keys
+SESSION_USER_ID_KEY = "user_id"
+
+# Admin list-endpoint allowed filter/sort values
+ALLOWED_STATUS = frozenset({"active", "disabled"})
+ALLOWED_VERIFIED = frozenset({"yes", "no"})
+ALLOWED_SORT = frozenset({"email", "last_login_at", "created_at"})
+ALLOWED_ORDER = frozenset({"asc", "desc"})
+
+
+def sanitize_list_filters(
+    status: str | None,
+    verified: str | None,
+    sort: str,
+    order: str,
+) -> tuple[str | None, str | None, str, str]:
+    """Coerce unknown filter values to None/defaults."""
+    return (
+        status if status in ALLOWED_STATUS else None,
+        verified if verified in ALLOWED_VERIFIED else None,
+        sort if sort in ALLOWED_SORT else "email",
+        order if order in ALLOWED_ORDER else "asc",
+    )

users/contracts/events.py

@@ -0,0 +1,32 @@
+"""Public events published by the users module."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class UserRegistered(Event):
+    user_id: uuid.UUID
+    email: str
+
+
+@dataclass
+class UserInvited(Event):
+    user_id: uuid.UUID
+    email: str
+    invited_by: str | None
+
+
+@dataclass
+class UserDisabled(Event):
+    user_id: uuid.UUID
+
+
+@dataclass
+class RoleAssigned(Event):
+    user_id: uuid.UUID
+    role_name: str

users/contracts/schemas.py

@@ -0,0 +1,85 @@
+"""Public request/response schemas for the users module."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from fastapi_users.schemas import CreateUpdateDictModel
+from pydantic import ConfigDict, EmailStr
+from sqlmodel import SQLModel
+
+
+class UserRead(CreateUpdateDictModel, SQLModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    email: EmailStr
+    is_active: bool = True
+    is_superuser: bool = False
+    is_verified: bool = False
+    full_name: str | None = None
+    tenant_id: str | None = None
+    disabled_at: datetime | None = None
+    last_login_at: datetime | None = None
+
+
+class UserCreate(CreateUpdateDictModel, SQLModel):
+    email: EmailStr
+    password: str
+    is_active: bool | None = True
+    is_superuser: bool | None = False
+    is_verified: bool | None = False
+    full_name: str | None = None
+
+
+class UserUpdate(CreateUpdateDictModel, SQLModel):
+    password: str | None = None
+    email: EmailStr | None = None
+    is_active: bool | None = None
+    is_superuser: bool | None = None
+    is_verified: bool | None = None
+    full_name: str | None = None
+
+
+# Admin + invite + self profile
+class UserInvite(SQLModel):
+    email: EmailStr
+    full_name: str | None = None
+    role_names: list[str] = []
+
+
+class UserListItem(SQLModel):
+    id: uuid.UUID
+    email: EmailStr
+    full_name: str | None = None
+    is_active: bool
+    is_verified: bool
+    disabled_at: datetime | None = None
+    last_login_at: datetime | None = None
+    created_at: datetime | None = None
+    roles: list[str] = []
+
+
+class RoleListItem(SQLModel):
+    id: uuid.UUID
+    name: str
+    description: str | None = None
+    user_count: int = 0
+
+
+class RoleAssignment(SQLModel):
+    role_names: list[str]
+
+
+class AcceptInviteRequest(SQLModel):
+    token: str
+    password: str
+
+
+class PasswordResetLink(SQLModel):
+    link: str
+
+
+class SelfProfileUpdate(SQLModel):
+    full_name: str | None = None

users/db_adapter.py

@@ -0,0 +1,48 @@
+"""SQLAlchemyUserDatabase subclass that eager-loads roles."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from fastapi import Depends
+from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase
+from fastapi_users_db_sqlalchemy.access_token import SQLAlchemyAccessTokenDatabase
+from simple_module_db.deps import get_db
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from users.models import User, UserAccessToken
+
+
+class UserDatabaseWithRoles(SQLAlchemyUserDatabase):
+    """Always eager-load User.roles so fastapi-users can read role names
+    without triggering implicit async lazy-loads."""
+
+    async def get(self, id):
+        stmt = (
+            select(self.user_table)
+            .where(self.user_table.id == id)
+            .options(selectinload(self.user_table.roles))
+        )
+        return (await self.session.execute(stmt)).scalar_one_or_none()
+
+    async def get_by_email(self, email):
+        stmt = (
+            select(self.user_table)
+            .where(func.lower(self.user_table.email) == email.lower())
+            .options(selectinload(self.user_table.roles))
+        )
+        return (await self.session.execute(stmt)).scalar_one_or_none()
+
+
+async def get_user_db(
+    session: AsyncSession = Depends(get_db),
+) -> AsyncGenerator[UserDatabaseWithRoles, None]:
+    yield UserDatabaseWithRoles(session, User)
+
+
+async def get_access_token_db(
+    session: AsyncSession = Depends(get_db),
+) -> AsyncGenerator[SQLAlchemyAccessTokenDatabase[UserAccessToken], None]:
+    yield SQLAlchemyAccessTokenDatabase(session, UserAccessToken)

users/deps.py

@@ -0,0 +1,83 @@
+"""Public dependencies and the FastAPIUsers instance.
+
+Cookie transport and auth backend are constructed at import time with
+dev-safe defaults (cookie_secure=False, dev cookie name). UsersModule.on_startup
+overrides the cookie params from the real UsersSettings once app.state is
+populated — CookieTransport's cookie fields are mutable on the instance.
+
+The singleton is here rather than in register_routes because
+``current_active_user`` and ``current_superuser`` are decorator-factories
+that must be resolvable at import time for route-handler signatures.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING
+
+from fastapi import Depends, Request
+from fastapi_users import FastAPIUsers
+from simple_module_core.events import EventBus
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from users.backend import build_auth_backend, build_cookie_transport
+from users.db_adapter import (
+    UserDatabaseWithRoles,
+    get_access_token_db,
+    get_user_db,
+)
+from users.manager import UserManager, get_user_manager
+from users.models import User
+
+if TYPE_CHECKING:
+    from users.service import UserService
+
+# Dev-safe singleton — UsersModule patches cookie params at startup.
+_cookie_transport = build_cookie_transport(
+    cookie_name="sm_auth",
+    cookie_max_age_seconds=60 * 60 * 24 * 14,
+    cookie_secure=False,  # host flips True in production via register_routes
+    cookie_samesite="lax",
+)
+auth_backend = build_auth_backend(_cookie_transport)
+
+fastapi_users = FastAPIUsers[User, uuid.UUID](get_user_manager, [auth_backend])
+
+current_active_user = fastapi_users.current_user(active=True)
+current_superuser = fastapi_users.current_user(active=True, superuser=True)
+
+
+def get_mailer(request: Request):
+    """Return the mailer from app.state.users (built in UsersModule.on_startup)."""
+    return request.app.state.users.mailer
+
+
+def get_event_bus(request: Request) -> EventBus:
+    """Return the event bus from app.state.sm."""
+    return request.app.state.sm.event_bus
+
+
+async def get_user_service(
+    db: AsyncSession = Depends(get_db),
+    user_manager: UserManager = Depends(get_user_manager),
+) -> UserService:
+    from users.service import UserService
+
+    return UserService(db, user_manager)
+
+
+__all__ = [
+    "UserDatabaseWithRoles",
+    "UserManager",
+    "auth_backend",
+    "current_active_user",
+    "current_superuser",
+    "fastapi_users",
+    "get_access_token_db",
+    "get_event_bus",
+    "get_mailer",
+    "get_user_db",
+    "get_user_manager",
+    "get_user_service",
+]

users/endpoints/__init__.py

@@ -0,0 +1 @@
+"""REST and view endpoints for the users module."""

users/endpoints/api.py

@@ -0,0 +1,227 @@
+"""REST API endpoints for the users module.
+
+Structure:
+  /api/users/auth/login    — wrapper with rate limit
+  /api/users/auth/*        — fastapi-users routers (register/reset/verify/logout)
+  /api/users/auth/accept-invite — custom (verify + set password + login)
+  /api/users/me            — self profile
+  /api/users/admin/*       — admin REST (RequiresPermission('users.manage'))
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from fastapi.security import OAuth2PasswordRequestForm
+from fastapi_users import exceptions as fu_exceptions
+
+from users.constants import SESSION_USER_ID_KEY
+from users.contracts.schemas import (
+    AcceptInviteRequest,
+    SelfProfileUpdate,
+    UserCreate,
+    UserRead,
+    UserUpdate,
+)
+from users.deps import (
+    auth_backend,
+    fastapi_users,
+    get_user_manager,
+)
+from users.endpoints.api_admin import admin_router
+from users.manager import UserManager
+from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+# ── Rate limit ───────────────────────────────────────────────────────────────
+
+
+def get_rate_limiter(request: Request) -> LoginRateLimiter:
+    """Return the per-app LoginRateLimiter built in UsersModule.on_startup."""
+    return request.app.state.users.rate_limiter
+
+
+def _client_ip(request: Request) -> str:
+    return request.client.host if request.client else "unknown"
+
+
+async def enforce_auth_throughput_limit(request: Request) -> None:
+    """FastAPI dependency that rejects the request with 429 when this IP has
+    exhausted its attempts budget on shared auth side-effect endpoints.
+
+    Applied to forgot-password / register / accept-invite / request-verify-token,
+    which otherwise allow unlimited email or account-creation spam.
+    """
+    limiter: ThroughputLimiter = request.app.state.users.auth_throughput_limiter
+    key = f"{request.url.path}::{_client_ip(request)}"
+    if not limiter.check_and_record(key):
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many attempts — try again later",
+        )
+
+
+async def require_signup_enabled(request: Request) -> None:
+    """Gate the register endpoint at request time on ``allow_signup``.
+
+    Mounting stays unconditional so settings reloads don't need to rebuild
+    the router. When signup is disabled we return 404 so the endpoint
+    appears absent (matches the view-side behaviour at ``/users/register``).
+    """
+    if not request.app.state.users.settings.allow_signup:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+
+# ── Wrapper login ────────────────────────────────────────────────────────────
+
+
+@router.post("/auth/login", status_code=204)
+async def login(
+    request: Request,
+    response: Response,
+    credentials: OAuth2PasswordRequestForm = Depends(),
+    user_manager: UserManager = Depends(get_user_manager),
+    strategy=Depends(auth_backend.get_strategy),
+    limiter: LoginRateLimiter = Depends(get_rate_limiter),
+):
+    """Rate-limited login wrapper. Sets sm_auth cookie + session user_id."""
+    key = f"{credentials.username.lower()}::{request.client.host if request.client else 'unknown'}"
+    if limiter.is_locked(key):
+        raise HTTPException(status_code=429, detail="Too many attempts — try again later")
+
+    try:
+        user = await user_manager.authenticate(credentials)
+    except fu_exceptions.UserNotExists:
+        user = None
+
+    if user is None or not user.is_active:
+        limiter.record_failure(key)
+        raise HTTPException(status_code=400, detail="LOGIN_BAD_CREDENTIALS")
+
+    if not user.is_verified:
+        # Match fastapi-users' own behavior when requires_verification=True
+        raise HTTPException(status_code=400, detail="LOGIN_USER_NOT_VERIFIED")
+
+    limiter.reset(key)
+    # Fire the login hook (updates last_login_at)
+    await user_manager.on_after_login(user, request, response)
+    # Set fastapi-users' cookie via auth_backend.login
+    login_response = await auth_backend.login(strategy, user)
+    # Bridge the session cookie — AuthMiddleware reads this to identify the user
+    request.session[SESSION_USER_ID_KEY] = str(user.id)
+    return login_response
+
+
+# ── Mount fastapi-users stock routers ────────────────────────────────────────
+
+# The stock auth router (login + logout) is mounted at /auth-inner so its
+# logout and other endpoints remain accessible. Our wrapper at /auth/login
+# shadows the stock login endpoint. Logout is exposed via /auth-inner/logout.
+auth_inner = fastapi_users.get_auth_router(auth_backend, requires_verification=True)
+router.include_router(auth_inner, prefix="/auth-inner")
+
+
+def register_auth_routes(api_router: APIRouter) -> None:
+    """Mount all auth routes.
+
+    The stock fastapi-users routers (reset/verify/register) ship POST endpoints
+    that trigger email side-effects or account creation. We wrap them with the
+    throughput limiter so an attacker can't spam password-reset emails or mint
+    accounts indefinitely. ``router`` itself is left unwrapped because its
+    rate-limited endpoints apply the dep themselves (login via LoginRateLimiter,
+    accept-invite via ``enforce_auth_throughput_limit``).
+
+    The register router is always mounted; ``require_signup_enabled`` gates
+    it at request time so ``allow_signup`` is hot-reloadable.
+    """
+    api_router.include_router(router)
+    api_router.include_router(
+        fastapi_users.get_reset_password_router(),
+        prefix="/auth",
+        tags=["users-auth"],
+        dependencies=[Depends(enforce_auth_throughput_limit)],
+    )
+    api_router.include_router(
+        fastapi_users.get_verify_router(UserRead),
+        prefix="/auth",
+        tags=["users-auth"],
+        dependencies=[Depends(enforce_auth_throughput_limit)],
+    )
+    api_router.include_router(
+        fastapi_users.get_register_router(UserRead, UserCreate),
+        prefix="/auth",
+        tags=["users-auth"],
+        dependencies=[
+            Depends(require_signup_enabled),
+            Depends(enforce_auth_throughput_limit),
+        ],
+    )
+
+
+# ── Accept-invite (verify + set password + login, one shot) ─────────────────
+
+
+@router.post(
+    "/auth/accept-invite",
+    status_code=204,
+    dependencies=[Depends(enforce_auth_throughput_limit)],
+)
+async def accept_invite(
+    body: AcceptInviteRequest,
+    request: Request,
+    response: Response,
+    user_manager: UserManager = Depends(get_user_manager),
+    strategy=Depends(auth_backend.get_strategy),
+):
+    """Verify an invite token, set the user's password, and log them in."""
+    try:
+        user = await user_manager.verify(body.token, request=request)
+    except (fu_exceptions.InvalidVerifyToken, fu_exceptions.UserAlreadyVerified):
+        raise HTTPException(status_code=400, detail="INVITE_BAD_TOKEN") from None
+
+    try:
+        await user_manager.update(
+            UserUpdate(password=body.password),
+            user,
+            request=request,
+        )
+    except fu_exceptions.InvalidPasswordException as e:
+        raise HTTPException(status_code=400, detail=f"INVALID_PASSWORD: {e.reason}") from e
+
+    await user_manager.on_after_login(user, request, response)
+    login_response = await auth_backend.login(strategy, user)
+    request.session[SESSION_USER_ID_KEY] = str(user.id)
+    return login_response
+
+
+# ── Self profile ─────────────────────────────────────────────────────────────
+
+
+@router.get("/me", response_model=UserRead)
+async def read_me(user=Depends(fastapi_users.current_user(active=True))):
+    """Return the currently authenticated user's profile."""
+    return user
+
+
+@router.patch("/me", response_model=UserRead)
+async def update_me(
+    data: SelfProfileUpdate,
+    request: Request,
+    user=Depends(fastapi_users.current_user(active=True)),
+    user_manager: UserManager = Depends(get_user_manager),
+):
+    """Update the currently authenticated user's profile."""
+    return await user_manager.update(
+        UserUpdate(**data.model_dump(exclude_unset=True)),
+        user,
+        request=request,
+    )
+
+
+# ── Admin REST — defined in api_admin.py, mounted here ──────────────────────
+
+router.include_router(admin_router)