regstack 0.1.0__py3-none-any.whl

regstack/models/user.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+from regstack.models._objectid import ObjectIdStr
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+PasswordStr = Annotated[str, Field(min_length=8, max_length=128)]
+
+
+class BaseUser(BaseModel):
+    """Persisted user document.
+
+    The default field set covers what both winebox and putplace need today.
+    Hosts add their own fields by subclassing or by registering an extension
+    mixin via ``RegStack.extend_user_model``.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    email: EmailStr
+    hashed_password: str
+    is_active: bool = True
+    is_verified: bool = False
+    is_superuser: bool = False
+    full_name: str | None = None
+    phone_number: str | None = None
+    is_mfa_enabled: bool = False
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    last_login: datetime | None = None
+    tokens_invalidated_after: datetime | None = None
+
+    @property
+    def is_admin(self) -> bool:
+        """Alias kept for parity with putplace's ``is_admin`` field name."""
+        return self.is_superuser
+
+    def to_mongo(self) -> dict[str, Any]:
+        data = self.model_dump(by_alias=True, exclude_none=True)
+        if data.get("_id") is None:
+            data.pop("_id", None)
+        return data
+
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    email: EmailStr
+    password: PasswordStr
+    full_name: str | None = Field(default=None, max_length=200)
+
+    @field_validator("password")
+    @classmethod
+    def _strip(cls, v: str) -> str:
+        return v
+
+
+class UserUpdate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    full_name: str | None = Field(default=None, max_length=200)
+
+
+class UserPublic(BaseModel):
+    """Safe-to-serialise projection of a user (no password hash)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(alias="_id")
+    email: EmailStr
+    is_active: bool
+    is_verified: bool
+    is_superuser: bool
+    full_name: str | None = None
+    phone_number: str | None = None
+    is_mfa_enabled: bool = False
+    created_at: datetime
+    last_login: datetime | None = None
+
+    @classmethod
+    def from_user(cls, user: BaseUser) -> UserPublic:
+        if user.id is None:
+            raise ValueError("Cannot serialise a user without an id")
+        return cls(
+            _id=user.id,
+            email=user.email,
+            is_active=user.is_active,
+            is_verified=user.is_verified,
+            is_superuser=user.is_superuser,
+            full_name=user.full_name,
+            phone_number=user.phone_number,
+            is_mfa_enabled=user.is_mfa_enabled,
+            created_at=user.created_at,
+            last_login=user.last_login,
+        )

regstack/routers/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+
+from regstack.routers.account import build_account_router
+from regstack.routers.admin import build_admin_router
+from regstack.routers.login import build_login_router
+from regstack.routers.logout import build_logout_router
+from regstack.routers.password import build_password_router
+from regstack.routers.phone import build_phone_router
+from regstack.routers.register import build_register_router
+from regstack.routers.verify import build_verify_router
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+def build_router(rs: RegStack) -> APIRouter:
+    """Compose the JSON router that hosts mount via ``app.include_router``."""
+    router = APIRouter(tags=["regstack"])
+    router.include_router(build_register_router(rs))
+    router.include_router(build_verify_router(rs))
+    router.include_router(build_login_router(rs))
+    router.include_router(build_logout_router(rs))
+    router.include_router(build_account_router(rs))
+    if rs.config.enable_password_reset:
+        router.include_router(build_password_router(rs))
+    if rs.config.enable_sms_2fa:
+        router.include_router(build_phone_router(rs))
+    if rs.config.enable_admin_router:
+        router.include_router(build_admin_router(rs))
+    return router
+
+
+__all__ = ["build_admin_router", "build_router"]

regstack/routers/_schemas.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+PasswordStr = Annotated[str, Field(min_length=8, max_length=128)]
+
+
+class LoginRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: EmailStr
+    password: PasswordStr
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    expires_in: int
+
+
+class MessageResponse(BaseModel):
+    message: str
+
+
+class PendingResponse(BaseModel):
+    """Returned when registration starts a verification flow rather than
+    creating a logged-in user immediately. The host can use this to redirect
+    to a "check your email" page.
+    """
+
+    status: str = "pending_verification"
+    email: EmailStr
+    expires_at: str  # ISO-8601 UTC, JSON-friendly

regstack/routers/account.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+import jwt as pyjwt
+from fastapi import APIRouter, Body, Depends, HTTPException, status
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+from regstack.auth.jwt import TokenError
+from regstack.config.secrets import derive_secret
+from regstack.db.repositories.user_repo import UserAlreadyExistsError
+from regstack.models.user import BaseUser, UserPublic
+from regstack.routers._schemas import MessageResponse, PasswordStr
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+_EMAIL_CHANGE_PURPOSE = "email_change"
+_NEW_EMAIL_CLAIM = "new_email"
+
+
+class ChangePasswordRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    current_password: str
+    new_password: PasswordStr
+
+
+class ChangeEmailRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    new_email: EmailStr
+    current_password: str
+
+
+class ConfirmEmailChangeRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    token: str
+
+
+class DeleteAccountRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    current_password: str
+
+
+class UpdateProfileRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    full_name: str | None = Field(default=None, max_length=200)
+
+
+def build_account_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.get(
+        "/me",
+        response_model=UserPublic,
+        summary="Return the authenticated user",
+    )
+    async def me(user: BaseUser = Depends(rs.deps.current_user())) -> UserPublic:
+        return UserPublic.from_user(user)
+
+    @router.patch(
+        "/me",
+        response_model=UserPublic,
+        summary="Update the authenticated user's profile fields",
+    )
+    async def update_me(
+        payload: UpdateProfileRequest,
+        user: BaseUser = Depends(rs.deps.current_user()),
+    ) -> UserPublic:
+        assert user.id is not None
+        await rs.users.set_full_name(user.id, payload.full_name)
+        user.full_name = payload.full_name
+        return UserPublic.from_user(user)
+
+    @router.post(
+        "/change-password",
+        response_model=MessageResponse,
+        summary="Change the authenticated user's password (revokes existing sessions)",
+    )
+    async def change_password(
+        payload: ChangePasswordRequest,
+        user: BaseUser = Depends(rs.deps.current_user()),
+    ) -> MessageResponse:
+        if not rs.password_hasher.verify(payload.current_password, user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect.",
+            )
+        if rs.password_hasher.verify(payload.new_password, user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New password must differ from the current password.",
+            )
+
+        new_hash = rs.password_hasher.hash(payload.new_password)
+        assert user.id is not None
+        await rs.users.update_password(user.id, new_hash)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("password_changed", user=user)
+        return MessageResponse(message="Password changed. Existing sessions have been signed out.")
+
+    @router.post(
+        "/change-email",
+        response_model=MessageResponse,
+        status_code=status.HTTP_202_ACCEPTED,
+        summary="Request an email-address change (sends confirmation to new address)",
+    )
+    async def change_email(
+        payload: ChangeEmailRequest,
+        user: BaseUser = Depends(rs.deps.current_user()),
+    ) -> MessageResponse:
+        if payload.new_email.lower() == user.email.lower():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New email is the same as the current email.",
+            )
+        if not rs.password_hasher.verify(payload.current_password, user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect.",
+            )
+        clash = await rs.users.get_by_email(payload.new_email)
+        if clash is not None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="That email address is already in use.",
+            )
+
+        assert user.id is not None
+        ttl = rs.config.email_change_token_ttl_seconds
+        token = _encode_email_change_token(rs, user.id, payload.new_email, ttl)
+        url = _email_change_url(rs, token)
+        message = rs.mail.email_change(
+            to=payload.new_email,
+            full_name=user.full_name,
+            url=url,
+            ttl_minutes=max(ttl // 60, 1),
+        )
+        await rs.email.send(message)
+        await rs.hooks.fire(
+            "email_change_requested",
+            user=user,
+            new_email=payload.new_email,
+            url=url,
+        )
+        return MessageResponse(
+            message="A confirmation link has been sent to the new email address."
+        )
+
+    @router.post(
+        "/confirm-email-change",
+        response_model=UserPublic,
+        summary="Consume an email-change token and swap the address",
+    )
+    async def confirm_email_change(payload: ConfirmEmailChangeRequest) -> UserPublic:
+        try:
+            user_id, new_email = _decode_email_change_token(rs, payload.token)
+        except TokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token is invalid or has expired.",
+            ) from exc
+
+        user = await rs.users.get_by_id(user_id)
+        if user is None or not user.is_active or user.id is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token does not match an active account.",
+            )
+
+        try:
+            await rs.users.update_email(user.id, new_email)
+        except UserAlreadyExistsError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="That email address is already in use.",
+            ) from exc
+
+        previous_email = user.email
+        user.email = new_email
+        await rs.lockout.clear(previous_email)
+        await rs.hooks.fire("email_changed", user=user, previous_email=previous_email)
+        return UserPublic.from_user(user)
+
+    @router.delete(
+        "/account",
+        response_model=MessageResponse,
+        summary="Permanently delete the authenticated user's account",
+    )
+    async def delete_account(
+        payload: Annotated[DeleteAccountRequest, Body()],
+        user: BaseUser = Depends(rs.deps.current_user()),
+    ) -> MessageResponse:
+        if not rs.config.enable_account_deletion:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Account deletion is disabled for this application.",
+            )
+        if not rs.password_hasher.verify(payload.current_password, user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect.",
+            )
+
+        assert user.id is not None
+        await rs.users.delete(user.id)
+        await rs.pending.delete_by_email(user.email)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("user_deleted", user=user)
+        return MessageResponse(message="Account deleted.")
+
+    return router
+
+
+def _encode_email_change_token(rs: RegStack, user_id: str, new_email: str, ttl: int) -> str:
+    """Mint a JWT carrying both ``sub=user_id`` and a ``new_email`` claim.
+
+    Goes through pyjwt directly (rather than ``rs.jwt.encode``) because we
+    need a custom claim. Same per-purpose key derivation though, so this
+    token is unforgeable from a session token.
+    """
+    import secrets as _secrets
+
+    now = rs.clock.now()
+    from datetime import timedelta
+
+    payload: dict[str, Any] = {
+        "sub": user_id,
+        "jti": _secrets.token_urlsafe(16),
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(seconds=ttl)).timestamp()),
+        "purpose": _EMAIL_CHANGE_PURPOSE,
+        _NEW_EMAIL_CLAIM: new_email,
+    }
+    if rs.config.jwt_audience is not None:
+        payload["aud"] = rs.config.jwt_audience
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _EMAIL_CHANGE_PURPOSE)
+    return pyjwt.encode(payload, key, algorithm=rs.config.jwt_algorithm)
+
+
+def _decode_email_change_token(rs: RegStack, token: str) -> tuple[str, str]:
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _EMAIL_CHANGE_PURPOSE)
+    try:
+        claims = pyjwt.decode(
+            token,
+            key,
+            algorithms=[rs.config.jwt_algorithm],
+            audience=rs.config.jwt_audience,
+            options={
+                "require": ["sub", "exp", "iat", "jti", "purpose", _NEW_EMAIL_CLAIM],
+                "verify_exp": False,
+                "verify_iat": False,
+                "verify_nbf": False,
+            },
+        )
+    except pyjwt.PyJWTError as exc:
+        raise TokenError(str(exc)) from exc
+
+    if claims.get("purpose") != _EMAIL_CHANGE_PURPOSE:
+        raise TokenError("token purpose mismatch")
+
+    from datetime import datetime
+
+    now = rs.clock.now()
+    exp = datetime.fromtimestamp(int(claims["exp"]), tz=now.tzinfo)
+    if now >= exp:
+        raise TokenError("Token has expired")
+
+    return str(claims["sub"]), str(claims[_NEW_EMAIL_CLAIM])
+
+
+def _email_change_url(rs: RegStack, token: str) -> str:
+    base = str(rs.config.base_url).rstrip("/")
+    return f"{base}/confirm-email-change?token={token}"

regstack/routers/admin.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query, status
+from pydantic import BaseModel, ConfigDict, Field
+
+from regstack.auth.tokens import generate_verification_token
+from regstack.models.pending_registration import PendingRegistration
+from regstack.models.user import BaseUser, UserPublic
+from regstack.routers._schemas import MessageResponse
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+class AdminUserUpdate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    is_active: bool | None = None
+    is_superuser: bool | None = None
+    full_name: str | None = Field(default=None, max_length=200)
+
+
+class AdminStats(BaseModel):
+    total_users: int
+    active_users: int
+    verified_users: int
+    superusers: int
+    pending_registrations: int
+
+
+class UserListResponse(BaseModel):
+    items: list[UserPublic]
+    total: int
+    skip: int
+    limit: int
+
+
+def build_admin_router(rs: RegStack) -> APIRouter:
+    router = APIRouter(prefix="/admin", tags=["regstack-admin"])
+
+    @router.get(
+        "/stats",
+        response_model=AdminStats,
+        summary="Aggregate counts for the admin dashboard",
+    )
+    async def stats(_admin: BaseUser = Depends(rs.deps.current_admin())) -> AdminStats:
+        total = await rs.users.count()
+        active = await rs.users.count(filter_={"is_active": True})
+        verified = await rs.users.count(filter_={"is_verified": True})
+        supers = await rs.users.count(filter_={"is_superuser": True})
+        pending = await rs.pending._collection.count_documents({})  # type: ignore[attr-defined]
+        return AdminStats(
+            total_users=total,
+            active_users=active,
+            verified_users=verified,
+            superusers=supers,
+            pending_registrations=pending,
+        )
+
+    @router.get(
+        "/users",
+        response_model=UserListResponse,
+        summary="List users (paginated)",
+    )
+    async def list_users(
+        skip: Annotated[int, Query(ge=0)] = 0,
+        limit: Annotated[int, Query(ge=1, le=200)] = 50,
+        _admin: BaseUser = Depends(rs.deps.current_admin()),
+    ) -> UserListResponse:
+        users = await rs.users.list_paged(skip=skip, limit=limit)
+        total = await rs.users.count()
+        return UserListResponse(
+            items=[UserPublic.from_user(u) for u in users],
+            total=total,
+            skip=skip,
+            limit=limit,
+        )
+
+    @router.get(
+        "/users/{user_id}",
+        response_model=UserPublic,
+        summary="Fetch a single user by id",
+    )
+    async def get_user(
+        user_id: str = Path(...),
+        _admin: BaseUser = Depends(rs.deps.current_admin()),
+    ) -> UserPublic:
+        user = await _require_user(rs, user_id)
+        return UserPublic.from_user(user)
+
+    @router.patch(
+        "/users/{user_id}",
+        response_model=UserPublic,
+        summary="Update mutable user flags",
+    )
+    async def update_user(
+        payload: AdminUserUpdate,
+        user_id: str = Path(...),
+        _admin: BaseUser = Depends(rs.deps.current_admin()),
+    ) -> UserPublic:
+        user = await _require_user(rs, user_id)
+        assert user.id is not None
+
+        if payload.is_active is not None:
+            await rs.users.set_active(user.id, is_active=payload.is_active)
+            user.is_active = payload.is_active
+            if payload.is_active is False:
+                # A disabled user should not retain a live session.
+                await rs.users.set_tokens_invalidated_after(user.id, rs.clock.now())
+        if payload.is_superuser is not None:
+            await rs.users.set_superuser(user.id, is_superuser=payload.is_superuser)
+            user.is_superuser = payload.is_superuser
+        if payload.full_name is not None:
+            await rs.users.set_full_name(user.id, payload.full_name)
+            user.full_name = payload.full_name
+        return UserPublic.from_user(user)
+
+    @router.delete(
+        "/users/{user_id}",
+        response_model=MessageResponse,
+        summary="Permanently delete a user",
+    )
+    async def delete_user(
+        user_id: str = Path(...),
+        _admin: BaseUser = Depends(rs.deps.current_admin()),
+    ) -> MessageResponse:
+        user = await _require_user(rs, user_id)
+        assert user.id is not None
+        await rs.users.delete(user.id)
+        await rs.pending.delete_by_email(user.email)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("user_deleted", user=user)
+        return MessageResponse(message=f"User {user.email} deleted.")
+
+    @router.post(
+        "/users/{user_id}/resend-verification",
+        response_model=MessageResponse,
+        status_code=status.HTTP_202_ACCEPTED,
+        summary="Re-send a verification email for an unverified user",
+    )
+    async def admin_resend_verification(
+        user_id: str = Path(...),
+        _admin: BaseUser = Depends(rs.deps.current_admin()),
+    ) -> MessageResponse:
+        user = await _require_user(rs, user_id)
+        if user.is_verified:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="User is already verified.",
+            )
+
+        # Move the user to a pending registration row so the standard verify
+        # endpoint completes the flow. Less special-case code, one path.
+        raw, token_hash = generate_verification_token()
+        ttl = rs.config.verification_token_ttl_seconds
+        pending = PendingRegistration(
+            email=user.email,
+            hashed_password=user.hashed_password,
+            full_name=user.full_name,
+            token_hash=token_hash,
+            expires_at=rs.clock.now() + timedelta(seconds=ttl),
+        )
+        await rs.pending.upsert(pending)
+
+        base = str(rs.config.base_url).rstrip("/")
+        url = f"{base}/verify?token={raw}"
+        message = rs.mail.verification(to=user.email, full_name=user.full_name, url=url)
+        await rs.email.send(message)
+        await rs.hooks.fire("verification_requested", email=user.email, url=url)
+        return MessageResponse(message=f"Verification email sent to {user.email}.")
+
+    return router
+
+
+async def _require_user(rs: RegStack, user_id: str) -> BaseUser:
+    user = await rs.users.get_by_id(user_id)
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found.",
+        )
+    return user
+
+
+__all__ = ["AdminStats", "AdminUserUpdate", "UserListResponse", "build_admin_router"]