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

users/endpoints/api_admin.py

@@ -0,0 +1,167 @@
+"""Admin REST endpoints for the users module.
+
+Split out of :mod:`.api` to keep per-file complexity manageable. Mounted
+into the main ``router`` via ``include_router`` at the bottom of ``api.py``.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import status as http_status
+from simple_module_core.events import EventBus
+from simple_module_hosting.permissions import RequiresPermission
+
+from users.constants import PERM_USERS_MANAGE, sanitize_list_filters
+from users.contracts.events import RoleAssigned, UserDisabled, UserInvited
+from users.contracts.schemas import (
+    PasswordResetLink,
+    RoleAssignment,
+    UserInvite,
+    UserListItem,
+)
+from users.deps import get_event_bus, get_mailer, get_user_service
+from users.exceptions import UserNotFoundError
+from users.service import UserService
+
+admin_router = APIRouter(
+    prefix="/admin",
+    dependencies=[Depends(RequiresPermission(PERM_USERS_MANAGE))],
+    tags=["users-admin"],
+)
+
+
+@admin_router.get("", response_model=list[UserListItem])
+async def admin_list_users(
+    page: int = 1,
+    per_page: int = 20,
+    q: str | None = None,
+    status: str | None = None,
+    role: str | None = None,
+    verified: str | None = None,
+    sort: str = "email",
+    order: str = "asc",
+    service: UserService = Depends(get_user_service),
+):
+    """List all users (paginated, optional search and filters)."""
+    _status, _verified, _sort, _order = sanitize_list_filters(status, verified, sort, order)
+    items, _ = await service.list_users(
+        page=page,
+        per_page=per_page,
+        search=q,
+        status=_status,
+        role_name=role or None,
+        verified=_verified,
+        sort=_sort,
+        order=_order,
+    )
+    return items
+
+
+@admin_router.post(
+    "/invite",
+    response_model=UserListItem,
+    status_code=http_status.HTTP_201_CREATED,
+)
+async def admin_invite_user(
+    data: UserInvite,
+    request: Request,
+    bus: EventBus = Depends(get_event_bus),
+    service: UserService = Depends(get_user_service),
+    mailer=Depends(get_mailer),
+):
+    """Invite a new user by email, optionally assigning roles."""
+    invited_by = getattr(request.state, "user", None)
+    invited_by_name = invited_by.name if invited_by else "Administrator"
+    user, token = await service.invite(
+        data.email, data.full_name, data.role_names, invited_by=invited_by
+    )
+    await mailer.send_invite(user.email, token, invited_by_name)
+    await bus.publish(
+        UserInvited(
+            user_id=user.id,
+            email=user.email,
+            invited_by=(str(invited_by.id) if invited_by else None),
+        )
+    )
+    return service.to_list_item(user)
+
+
+@admin_router.patch("/{user_id}/disable", response_model=UserListItem)
+async def admin_disable_user(
+    user_id: uuid.UUID,
+    bus: EventBus = Depends(get_event_bus),
+    service: UserService = Depends(get_user_service),
+):
+    """Disable a user account (sets is_active=False and disabled_at)."""
+    try:
+        user = await service.disable(user_id)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    await bus.publish(UserDisabled(user_id=user.id))
+    return service.to_list_item(user)
+
+
+@admin_router.patch("/{user_id}/enable", response_model=UserListItem)
+async def admin_enable_user(
+    user_id: uuid.UUID,
+    service: UserService = Depends(get_user_service),
+):
+    """Re-enable a previously disabled user account."""
+    try:
+        user = await service.enable(user_id)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    return service.to_list_item(user)
+
+
+@admin_router.put("/{user_id}/roles", response_model=UserListItem)
+async def admin_set_roles(
+    user_id: uuid.UUID,
+    data: RoleAssignment,
+    request: Request,
+    bus: EventBus = Depends(get_event_bus),
+    service: UserService = Depends(get_user_service),
+):
+    """Replace a user's role assignments."""
+    assigned_by = getattr(request.state, "user", None)
+    try:
+        user = await service.set_roles(
+            user_id,
+            data.role_names,
+            assigned_by=str(assigned_by.id) if assigned_by else None,
+        )
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    for role in data.role_names:
+        await bus.publish(RoleAssigned(user_id=user.id, role_name=role))
+    return service.to_list_item(user)
+
+
+@admin_router.patch("/{user_id}/verify", response_model=UserListItem)
+async def admin_mark_verified(
+    user_id: uuid.UUID,
+    service: UserService = Depends(get_user_service),
+):
+    """Mark a user verified. Idempotent."""
+    try:
+        user = await service.mark_verified(user_id)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    return service.to_list_item(user)
+
+
+@admin_router.post("/{user_id}/reset-password-link", response_model=PasswordResetLink)
+async def admin_reset_password_link(
+    user_id: uuid.UUID,
+    request: Request,
+    service: UserService = Depends(get_user_service),
+):
+    """Generate a password-reset link for the given user (admin copy)."""
+    base_url = request.app.state.users.settings.base_url
+    try:
+        link = await service.generate_reset_link(user_id, base_url)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    return PasswordResetLink(link=link)

users/endpoints/views.py

@@ -0,0 +1,220 @@
+"""Inertia view routes for the users module."""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+from starlette.responses import RedirectResponse
+
+from users.constants import PERM_USERS_MANAGE, sanitize_list_filters
+from users.deps import get_user_service
+from users.exceptions import UserNotFoundError
+from users.roles_cache import get_roles_cache
+from users.service import UserService
+
+router = APIRouter()
+
+# Inertia page identifiers
+_PAGE_LOGIN = "Users/Login"
+_PAGE_REGISTER = "Users/Register"
+_PAGE_FORGOT_PASSWORD = "Users/ForgotPassword"
+_PAGE_RESET_PASSWORD = "Users/ResetPassword"
+_PAGE_VERIFY_EMAIL = "Users/VerifyEmail"
+_PAGE_ACCEPT_INVITE = "Users/AcceptInvite"
+_PAGE_PROFILE = "Users/Profile"
+_PAGE_ADMIN_INDEX = "Users/Users/Index"
+_PAGE_ADMIN_INVITE = "Users/Users/Invite"
+_PAGE_ADMIN_EDIT = "Users/Users/Edit"
+
+
+async def _roles_payload(app) -> list[dict[str, str]]:
+    """Shape roles-cache entries for Inertia props."""
+    return [{"id": r.id, "name": r.name} for r in await get_roles_cache(app)]
+
+
+# ── Public auth pages ───────────────────────────────────────────
+
+
+@router.get("/login", response_model=None)
+async def login_page(request: Request, inertia: InertiaDep) -> InertiaResponse:
+    users_settings = request.app.state.users.settings
+    # In development only, surface the bootstrap credentials as click-to-fill
+    # buttons so manual QA doesn't need to retype them. Never exposed in
+    # production, regardless of whether the vars are set.
+    dev_accounts: list[dict[str, str]] = []
+    if request.app.state.sm.settings.is_development:
+        admin_email = users_settings.bootstrap_email or os.environ.get(
+            "SM_USERS_BOOTSTRAP_EMAIL", ""
+        )
+        admin_password = users_settings.bootstrap_password or os.environ.get(
+            "SM_USERS_BOOTSTRAP_PASSWORD", ""
+        )
+        if admin_email and admin_password:
+            dev_accounts.append(
+                {"label": "Admin", "email": admin_email, "password": admin_password}
+            )
+        user_email = users_settings.bootstrap_user_email or os.environ.get(
+            "SM_USERS_BOOTSTRAP_USER_EMAIL", ""
+        )
+        user_password = users_settings.bootstrap_user_password or os.environ.get(
+            "SM_USERS_BOOTSTRAP_USER_PASSWORD", ""
+        )
+        if user_email and user_password:
+            dev_accounts.append({"label": "User", "email": user_email, "password": user_password})
+    return await inertia.render(
+        _PAGE_LOGIN,
+        {"allow_signup": users_settings.allow_signup, "dev_accounts": dev_accounts},
+    )
+
+
+@router.post("/logout", response_model=None)
+async def logout(request: Request) -> RedirectResponse:
+    """Clear the session + auth cookie. POST-only to resist cross-site `<img>`
+    logout attacks — the menu's logout link submits this as an Inertia form."""
+    request.session.clear()
+    cookie_name = request.app.state.users.settings.cookie_name
+    # 303 forces the follow-up to GET — Inertia treats the redirect as a full
+    # navigation rather than replaying the POST.
+    response = RedirectResponse("/", status_code=303)
+    response.delete_cookie(cookie_name, path="/")
+    return response
+
+
+@router.get("/register", response_model=None)
+async def register_page(request: Request, inertia: InertiaDep) -> InertiaResponse:
+    if not request.app.state.users.settings.allow_signup:
+        raise HTTPException(status_code=404)
+    return await inertia.render(_PAGE_REGISTER, {})
+
+
+@router.get("/forgot-password", response_model=None)
+async def forgot_password_page(inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(_PAGE_FORGOT_PASSWORD, {})
+
+
+@router.get("/reset-password", response_model=None)
+async def reset_password_page(inertia: InertiaDep, token: str = "") -> InertiaResponse:
+    return await inertia.render(_PAGE_RESET_PASSWORD, {"token": token})
+
+
+@router.get("/verify", response_model=None)
+async def verify_page(inertia: InertiaDep, token: str = "") -> InertiaResponse:
+    return await inertia.render(_PAGE_VERIFY_EMAIL, {"token": token})
+
+
+@router.get("/invite/accept", response_model=None)
+async def accept_invite_page(inertia: InertiaDep, token: str = "") -> InertiaResponse:
+    return await inertia.render(_PAGE_ACCEPT_INVITE, {"token": token})
+
+
+# ── Authenticated pages ─────────────────────────────────────────
+
+
+@router.get("/me", response_model=None)
+async def profile_page(inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(_PAGE_PROFILE, {})
+
+
+# ── Admin pages ─────────────────────────────────────────────────
+
+
+@router.get(
+    "/admin",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_USERS_MANAGE))],
+)
+async def admin_index(
+    request: Request,
+    inertia: InertiaDep,
+    service: UserService = Depends(get_user_service),
+    page: int = 1,
+    per_page: int = 20,
+    q: str | None = None,
+    status: str | None = None,
+    role: str | None = None,
+    verified: str | None = None,
+    sort: str = "email",
+    order: str = "asc",
+) -> InertiaResponse:
+    clean_status, clean_verified, clean_sort, clean_order = sanitize_list_filters(
+        status, verified, sort, order
+    )
+    users, total = await service.list_users(
+        page=page,
+        per_page=per_page,
+        search=q,
+        status=clean_status,
+        role_name=role or None,
+        verified=clean_verified,
+        sort=clean_sort,
+        order=clean_order,
+    )
+    roles = await service.list_roles()
+    return await inertia.render(
+        _PAGE_ADMIN_INDEX,
+        {
+            "users": [u.model_dump(mode="json") for u in users],
+            "pagination": {"page": page, "per_page": per_page, "total": total},
+            "query": q or "",
+            "roles": [r.model_dump(mode="json") for r in roles],
+            "filters": {
+                "status": clean_status or "all",
+                "role": role or "",
+                "verified": clean_verified or "all",
+                "sort": clean_sort,
+                "order": clean_order,
+            },
+        },
+    )
+
+
+@router.get(
+    "/admin/invite",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_USERS_MANAGE))],
+)
+async def admin_invite_page(
+    request: Request,
+    inertia: InertiaDep,
+) -> InertiaResponse:
+    return await inertia.render(
+        _PAGE_ADMIN_INVITE,
+        {
+            "roles": await _roles_payload(request.app),
+        },
+    )
+
+
+@router.get(
+    "/admin/{user_id}",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_USERS_MANAGE))],
+)
+async def admin_edit_page(
+    user_id: str,
+    request: Request,
+    inertia: InertiaDep,
+    service: UserService = Depends(get_user_service),
+) -> InertiaResponse:
+    try:
+        uid = uuid.UUID(user_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404) from exc
+    try:
+        user_item = await service.get_list_item(uid)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404) from None
+    has_permissions = any(m.meta.name == "Permissions" for m in request.app.state.sm.modules)
+    return await inertia.render(
+        _PAGE_ADMIN_EDIT,
+        {
+            "user": user_item.model_dump(mode="json"),
+            "roles": await _roles_payload(request.app),
+            "has_permissions_module": has_permissions,
+        },
+    )

users/exceptions.py

@@ -0,0 +1,18 @@
+"""Domain-level exceptions raised by the users module.
+
+Kept internal to the module — callers in the endpoints layer translate these
+into HTTP responses. Not re-exported via ``contracts/`` because no other
+module catches them today. Promote to contracts if that changes.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+
+class UserNotFoundError(Exception):
+    """Raised when a user lookup by id/email returns nothing."""
+
+    def __init__(self, user_id: uuid.UUID) -> None:
+        super().__init__(f"User {user_id} not found")
+        self.user_id = user_id

users/mailer/__init__.py

@@ -0,0 +1,33 @@
+"""Mailer interface and factory — pick console/smtp from settings."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from users.settings import UsersSettings
+
+
+@runtime_checkable
+class Mailer(Protocol):
+    async def send_verification(self, email: str, token: str) -> None: ...
+    async def send_password_reset(self, email: str, token: str) -> None: ...
+    async def send_invite(self, email: str, token: str, invited_by_name: str) -> None: ...
+
+
+def build_mailer(settings: UsersSettings) -> Mailer:
+    if settings.mailer == "smtp":
+        from users.mailer.smtp import SmtpMailer
+
+        return SmtpMailer(
+            host=settings.smtp_host,
+            port=settings.smtp_port,
+            username=settings.smtp_username,
+            password=settings.smtp_password,
+            from_address=settings.smtp_from,
+            use_tls=settings.smtp_tls,
+            base_url=settings.base_url,
+        )
+
+    from users.mailer.console import ConsoleMailer
+
+    return ConsoleMailer(base_url=settings.base_url)

users/mailer/console.py

@@ -0,0 +1,27 @@
+"""Console mailer — logs tokenized links for local development."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("users.mailer")
+
+
+class ConsoleMailer:
+    def __init__(self, base_url: str) -> None:
+        self._base = base_url.rstrip("/")
+
+    async def send_verification(self, email: str, token: str) -> None:
+        link = f"{self._base}/users/verify?token={token}"
+        logger.info("users.verify.email", extra={"to": email, "link": link})
+
+    async def send_password_reset(self, email: str, token: str) -> None:
+        link = f"{self._base}/users/reset-password?token={token}"
+        logger.info("users.reset.email", extra={"to": email, "link": link})
+
+    async def send_invite(self, email: str, token: str, invited_by_name: str) -> None:
+        link = f"{self._base}/users/invite/accept?token={token}"
+        logger.info(
+            "users.invite.email",
+            extra={"to": email, "link": link, "invited_by": invited_by_name},
+        )

users/mailer/smtp.py

@@ -0,0 +1,77 @@
+"""SMTP mailer — sends emails via aiosmtplib with Jinja2 templates."""
+
+from __future__ import annotations
+
+import importlib.resources
+from email.message import EmailMessage
+
+import aiosmtplib
+import jinja2
+
+
+def _load_template_env() -> jinja2.Environment:
+    """Build a Jinja2 Environment pointed at the bundled templates directory."""
+    templates_path = importlib.resources.files(__package__) / "templates"
+    return jinja2.Environment(
+        loader=jinja2.FileSystemLoader(str(templates_path)),
+        autoescape=False,
+    )
+
+
+# Resolve the template directory at import time — deterministic, async-safe,
+# and the filesystem path is known by then anyway.
+_template_env: jinja2.Environment = _load_template_env()
+
+
+class SmtpMailer:
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        username: str,
+        password: str,
+        from_address: str,
+        use_tls: bool,
+        base_url: str,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._username = username
+        self._password = password
+        self._from = from_address
+        self._use_tls = use_tls
+        self._base = base_url.rstrip("/")
+
+    async def send_verification(self, email: str, token: str) -> None:
+        link = f"{self._base}/users/verify?token={token}"
+        template = _template_env.get_template("verify_email.txt")
+        body = template.render(link=link)
+        await self._send(email, "Verify your email address", body)
+
+    async def send_password_reset(self, email: str, token: str) -> None:
+        link = f"{self._base}/users/reset-password?token={token}"
+        template = _template_env.get_template("reset_password.txt")
+        body = template.render(link=link)
+        await self._send(email, "Reset your password", body)
+
+    async def send_invite(self, email: str, token: str, invited_by_name: str) -> None:
+        link = f"{self._base}/users/invite/accept?token={token}"
+        template = _template_env.get_template("invite.txt")
+        body = template.render(link=link, invited_by_name=invited_by_name)
+        await self._send(email, f"You've been invited by {invited_by_name}", body)
+
+    async def _send(self, to: str, subject: str, body: str) -> None:
+        message = EmailMessage()
+        message["From"] = self._from
+        message["To"] = to
+        message["Subject"] = subject
+        message.set_content(body)
+
+        await aiosmtplib.send(
+            message,
+            hostname=self._host,
+            port=self._port,
+            username=self._username or None,
+            password=self._password or None,
+            use_tls=self._use_tls,
+        )

users/mailer/templates/invite.txt

@@ -0,0 +1 @@
+{{ invited_by_name }} invited you. Accept: {{ link }}

users/mailer/templates/reset_password.txt

@@ -0,0 +1 @@
+Reset your password: {{ link }}

users/mailer/templates/verify_email.txt

@@ -0,0 +1 @@
+Verify your email: {{ link }}