regstack 0.1.0__py3-none-any.whl

regstack/routers/login.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, HTTPException, status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field
+
+from regstack.auth.jwt import TokenError
+from regstack.auth.mfa import generate_mfa_code
+from regstack.db.repositories.mfa_code_repo import MfaVerifyOutcome
+from regstack.models.mfa_code import MfaCode
+from regstack.routers._schemas import LoginRequest, TokenResponse
+from regstack.sms.base import SmsMessage
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+_INVALID = HTTPException(
+    status_code=status.HTTP_401_UNAUTHORIZED,
+    detail="Invalid email or password.",
+)
+_LOGIN_MFA_PURPOSE = "login_mfa"
+
+
+class MfaPendingResponse(BaseModel):
+    status: str = "mfa_required"
+    mfa_pending_token: str
+    expires_in: int
+    delivery: str = "sms"
+
+
+class MfaConfirmRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    mfa_pending_token: str
+    code: str = Field(min_length=4, max_length=10)
+
+
+def build_login_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.post(
+        "/login",
+        response_model=TokenResponse | MfaPendingResponse,
+        responses={
+            401: {"description": "Invalid credentials"},
+            403: {"description": "Account disabled or unverified"},
+            429: {"description": "Too many failed attempts; account temporarily locked"},
+        },
+        summary="Exchange credentials for a JWT — or start the MFA second step",
+    )
+    async def login(payload: LoginRequest):
+        decision = await rs.lockout.check(payload.email)
+        if decision.locked:
+            return JSONResponse(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                content={
+                    "detail": (
+                        "Too many failed attempts. "
+                        f"Try again in {decision.retry_after_seconds} seconds."
+                    )
+                },
+                headers={"Retry-After": str(decision.retry_after_seconds)},
+            )
+
+        user = await rs.users.get_by_email(payload.email)
+        if user is None or user.id is None:
+            await rs.lockout.record_failure(payload.email)
+            raise _INVALID
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Account is disabled.",
+            )
+        if not rs.password_hasher.verify(payload.password, user.hashed_password):
+            await rs.lockout.record_failure(payload.email)
+            raise _INVALID
+        if rs.config.require_verification and not user.is_verified:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Email address has not been verified.",
+            )
+
+        if user.is_mfa_enabled and user.phone_number:
+            return await _start_mfa_step(rs, user)
+
+        token, payload_obj = rs.jwt.encode(user.id)
+        await rs.users.set_last_login(user.id, payload_obj.iat)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("user_logged_in", user=user)
+        return TokenResponse(access_token=token, expires_in=rs.config.jwt_ttl_seconds)
+
+    @router.post(
+        "/login/mfa-confirm",
+        response_model=TokenResponse,
+        summary="Complete an MFA-required login by submitting the SMS code",
+    )
+    async def mfa_confirm(payload: MfaConfirmRequest) -> TokenResponse:
+        try:
+            user_id = _decode_mfa_token(rs, payload.mfa_pending_token)
+        except TokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="MFA token is invalid or has expired.",
+            ) from exc
+
+        result = await rs.mfa_codes.verify(user_id=user_id, kind="login_mfa", raw_code=payload.code)
+        if result.outcome is not MfaVerifyOutcome.OK:
+            raise _mfa_outcome(result)
+
+        user = await rs.users.get_by_id(user_id)
+        if user is None or user.id is None or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token does not match an active account.",
+            )
+
+        token, payload_obj = rs.jwt.encode(user.id)
+        await rs.users.set_last_login(user.id, payload_obj.iat)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("user_logged_in", user=user)
+        return TokenResponse(access_token=token, expires_in=rs.config.jwt_ttl_seconds)
+
+    return router
+
+
+async def _start_mfa_step(rs: RegStack, user) -> MfaPendingResponse:
+    raw_code, code_hash = generate_mfa_code(rs.config)
+    ttl = rs.config.sms_code_ttl_seconds
+    assert user.id is not None
+    await rs.mfa_codes.put(
+        MfaCode(
+            user_id=user.id,
+            kind="login_mfa",
+            code_hash=code_hash,
+            expires_at=rs.clock.now() + timedelta(seconds=ttl),
+            max_attempts=rs.config.sms_code_max_attempts,
+        )
+    )
+    body = rs.mail.sms_body(
+        kind="login_mfa",
+        code=raw_code,
+        ttl_minutes=max(ttl // 60, 1),
+    )
+    await rs.sms.send(
+        SmsMessage(to=user.phone_number, body=body, from_number=rs.config.sms.from_number)
+    )
+    pending_ttl = rs.config.mfa_pending_token_ttl_seconds
+    pending_token = _encode_mfa_token(rs, user.id, pending_ttl)
+    await rs.hooks.fire("mfa_login_started", user=user, code=raw_code)
+    return MfaPendingResponse(mfa_pending_token=pending_token, expires_in=pending_ttl)
+
+
+def _encode_mfa_token(rs: RegStack, user_id: str, ttl: int) -> str:
+    import secrets as _secrets
+
+    import jwt as pyjwt
+
+    from regstack.config.secrets import derive_secret
+
+    now = rs.clock.now()
+    claims: dict[str, Any] = {
+        "sub": user_id,
+        "jti": _secrets.token_urlsafe(16),
+        "iat": now.timestamp(),
+        "exp": int((now + timedelta(seconds=ttl)).timestamp()),
+        "purpose": _LOGIN_MFA_PURPOSE,
+    }
+    if rs.config.jwt_audience is not None:
+        claims["aud"] = rs.config.jwt_audience
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _LOGIN_MFA_PURPOSE)
+    return pyjwt.encode(claims, key, algorithm=rs.config.jwt_algorithm)
+
+
+def _decode_mfa_token(rs: RegStack, token: str) -> str:
+    from datetime import datetime
+
+    import jwt as pyjwt
+
+    from regstack.config.secrets import derive_secret
+
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _LOGIN_MFA_PURPOSE)
+    try:
+        claims = pyjwt.decode(
+            token,
+            key,
+            algorithms=[rs.config.jwt_algorithm],
+            audience=rs.config.jwt_audience,
+            options={
+                "require": ["sub", "exp", "iat", "jti", "purpose"],
+                "verify_exp": False,
+                "verify_iat": False,
+                "verify_nbf": False,
+            },
+        )
+    except pyjwt.PyJWTError as exc:
+        raise TokenError(str(exc)) from exc
+    if claims.get("purpose") != _LOGIN_MFA_PURPOSE:
+        raise TokenError("token purpose mismatch")
+    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"])
+
+
+def _mfa_outcome(result):
+    code = result.outcome
+    if code is MfaVerifyOutcome.MISSING:
+        detail = "No pending sign-in code — start the login flow again."
+    elif code is MfaVerifyOutcome.EXPIRED:
+        detail = "Sign-in code has expired. Try logging in again."
+    elif code is MfaVerifyOutcome.LOCKED:
+        detail = "Too many wrong attempts — start the login flow again."
+    else:
+        detail = (
+            f"Wrong code; {result.attempts_remaining} attempts remaining."
+            if result.attempts_remaining
+            else "Wrong code."
+        )
+    return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)

regstack/routers/logout.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, Depends, Request, status
+
+from regstack.auth.jwt import TokenError
+from regstack.routers._schemas import MessageResponse
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+def build_logout_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.post(
+        "/logout",
+        response_model=MessageResponse,
+        status_code=status.HTTP_200_OK,
+        summary="Revoke the current bearer token",
+    )
+    async def logout(
+        request: Request,
+        _user=Depends(rs.deps.current_user()),
+    ) -> MessageResponse:
+        # Re-decode the token (the dep already validated it) to grab jti+exp
+        # so we can record the revocation. The auth header was already proven
+        # well-formed; this decode cannot raise.
+        auth = request.headers.get("authorization", "")
+        token = auth.split(" ", 1)[1] if " " in auth else ""
+        try:
+            payload = rs.jwt.decode(token)
+        except TokenError:
+            return MessageResponse(message="Logged out.")
+        await rs.blacklist.revoke(payload.jti, payload.exp)
+        return MessageResponse(message="Logged out.")
+
+    return router

regstack/routers/password.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+from regstack.auth.jwt import TokenError
+from regstack.routers._schemas import MessageResponse, PasswordStr
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+_PASSWORD_RESET_PURPOSE = "password_reset"
+
+
+class ForgotPasswordRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: EmailStr
+
+
+class ResetPasswordRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    token: str
+    new_password: PasswordStr = Field(alias="new_password")
+
+
+def build_password_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.post(
+        "/forgot-password",
+        response_model=MessageResponse,
+        status_code=status.HTTP_202_ACCEPTED,
+        summary="Request a password-reset link (always succeeds)",
+    )
+    async def forgot(payload: ForgotPasswordRequest) -> MessageResponse:
+        if not rs.config.enable_password_reset:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Password reset is disabled for this application.",
+            )
+
+        # Anti-enumeration: same response regardless of whether the user exists.
+        ack = MessageResponse(
+            message="If an account exists for that email, a reset link has been sent."
+        )
+        user = await rs.users.get_by_email(payload.email)
+        if user is None or user.id is None or not user.is_active:
+            return ack
+
+        ttl = rs.config.password_reset_token_ttl_seconds
+        token, _ = rs.jwt.encode(
+            user.id,
+            purpose=_PASSWORD_RESET_PURPOSE,
+            ttl_seconds=ttl,
+        )
+        url = _reset_url(rs, token)
+        message = rs.mail.password_reset(
+            to=user.email,
+            full_name=user.full_name,
+            url=url,
+            ttl_minutes=max(ttl // 60, 1),
+        )
+        await rs.email.send(message)
+        await rs.hooks.fire("password_reset_requested", user=user, url=url)
+        return ack
+
+    @router.post(
+        "/reset-password",
+        response_model=MessageResponse,
+        summary="Consume a password-reset link and set a new password",
+    )
+    async def reset(payload: ResetPasswordRequest) -> MessageResponse:
+        if not rs.config.enable_password_reset:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Password reset is disabled for this application.",
+            )
+
+        try:
+            token_payload = rs.jwt.decode(payload.token, purpose=_PASSWORD_RESET_PURPOSE)
+        except TokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Reset token is invalid or has expired.",
+            ) from exc
+
+        user = await rs.users.get_by_id(token_payload.sub)
+        if user is None or user.id is None or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Reset token does not match an active account.",
+            )
+
+        new_hash = rs.password_hasher.hash(payload.new_password)
+        # update_password also bumps tokens_invalidated_after, which bulk-revokes
+        # every outstanding session — this is essential after a reset because a
+        # stolen session token would otherwise outlive the password change.
+        await rs.users.update_password(user.id, new_hash)
+        await rs.lockout.clear(user.email)
+        await rs.hooks.fire("password_reset_completed", user=user)
+        return MessageResponse(message="Password has been reset. Please sign in.")
+
+    return router
+
+
+def _reset_url(rs: RegStack, token: str) -> str:
+    base = str(rs.config.base_url).rstrip("/")
+    return f"{base}/reset-password?token={token}"
+
+
+__all__ = ["ForgotPasswordRequest", "ResetPasswordRequest", "build_password_router"]

regstack/routers/phone.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, ConfigDict, Field
+
+from regstack.auth.jwt import TokenError
+from regstack.auth.mfa import generate_mfa_code
+from regstack.db.repositories.mfa_code_repo import MfaVerifyOutcome
+from regstack.models.mfa_code import MfaCode
+from regstack.models.user import BaseUser, UserPublic
+from regstack.routers._schemas import MessageResponse
+from regstack.sms.base import SmsMessage, is_valid_e164
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+_PHONE_SETUP_PURPOSE = "phone_setup"
+
+
+class PhoneStartRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    phone_number: str = Field(min_length=4, max_length=20)
+    current_password: str
+
+
+class PhoneConfirmRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    pending_token: str
+    code: str = Field(min_length=4, max_length=10)
+
+
+class PhoneStartResponse(BaseModel):
+    status: str = "code_sent"
+    pending_token: str
+    expires_in: int
+
+
+class PhoneDisableRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    current_password: str
+
+
+def build_phone_router(rs: RegStack) -> APIRouter:
+    router = APIRouter(prefix="/phone", tags=["regstack-phone"])
+
+    @router.post(
+        "/start",
+        response_model=PhoneStartResponse,
+        status_code=status.HTTP_202_ACCEPTED,
+        summary="Send a verification code to a new phone number",
+    )
+    async def start(
+        payload: PhoneStartRequest,
+        user: BaseUser = Depends(rs.deps.current_user()),
+    ) -> PhoneStartResponse:
+        if not is_valid_e164(payload.phone_number):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Phone number must be in E.164 format (e.g. +14155552671).",
+            )
+        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
+        raw_code, code_hash = generate_mfa_code(rs.config)
+        ttl = rs.config.sms_code_ttl_seconds
+        await rs.mfa_codes.put(
+            MfaCode(
+                user_id=user.id,
+                kind="phone_setup",
+                code_hash=code_hash,
+                expires_at=rs.clock.now() + timedelta(seconds=ttl),
+                max_attempts=rs.config.sms_code_max_attempts,
+            )
+        )
+
+        body = rs.mail.sms_body(
+            kind="phone_setup",
+            code=raw_code,
+            ttl_minutes=max(ttl // 60, 1),
+        )
+        await rs.sms.send(
+            SmsMessage(
+                to=payload.phone_number,
+                body=body,
+                from_number=rs.config.sms.from_number,
+            )
+        )
+
+        pending_ttl = rs.config.mfa_pending_token_ttl_seconds
+        token = _encode_phone_setup_token(rs, user.id, payload.phone_number, pending_ttl)
+        await rs.hooks.fire(
+            "phone_setup_started",
+            user=user,
+            phone=payload.phone_number,
+            code=raw_code,
+        )
+        return PhoneStartResponse(pending_token=token, expires_in=pending_ttl)
+
+    @router.post(
+        "/confirm",
+        response_model=UserPublic,
+        summary="Confirm a phone-setup code and enable SMS 2FA",
+    )
+    async def confirm(payload: PhoneConfirmRequest) -> UserPublic:
+        try:
+            user_id, phone = _decode_phone_setup_token(rs, payload.pending_token)
+        except TokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Pending token is invalid or has expired.",
+            ) from exc
+
+        result = await rs.mfa_codes.verify(
+            user_id=user_id, kind="phone_setup", raw_code=payload.code
+        )
+        if result.outcome is not MfaVerifyOutcome.OK:
+            raise _outcome_to_http(result)
+
+        user = await rs.users.get_by_id(user_id)
+        if user is None or user.id is None or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token does not match an active account.",
+            )
+        await rs.users.set_phone(user.id, phone)
+        await rs.users.set_mfa_enabled(user.id, is_mfa_enabled=True)
+        user.phone_number = phone
+        user.is_mfa_enabled = True
+        await rs.hooks.fire("mfa_enabled", user=user)
+        return UserPublic.from_user(user)
+
+    @router.delete(
+        "",
+        response_model=MessageResponse,
+        summary="Disable SMS 2FA and clear the phone number",
+    )
+    async def disable(
+        payload: PhoneDisableRequest,
+        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.",
+            )
+        assert user.id is not None
+        await rs.users.set_phone(user.id, None)
+        await rs.users.set_mfa_enabled(user.id, is_mfa_enabled=False)
+        await rs.mfa_codes.delete(user_id=user.id)
+        await rs.hooks.fire("mfa_disabled", user=user)
+        return MessageResponse(message="SMS 2FA disabled.")
+
+    return router
+
+
+def _encode_phone_setup_token(rs: RegStack, user_id: str, phone: str, ttl: int) -> str:
+    import secrets as _secrets
+    from datetime import timedelta
+
+    import jwt as pyjwt
+
+    from regstack.config.secrets import derive_secret
+
+    now = rs.clock.now()
+    claims = {
+        "sub": user_id,
+        "jti": _secrets.token_urlsafe(16),
+        "iat": now.timestamp(),
+        "exp": int((now + timedelta(seconds=ttl)).timestamp()),
+        "purpose": _PHONE_SETUP_PURPOSE,
+        "phone": phone,
+    }
+    if rs.config.jwt_audience is not None:
+        claims["aud"] = rs.config.jwt_audience
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _PHONE_SETUP_PURPOSE)
+    return pyjwt.encode(claims, key, algorithm=rs.config.jwt_algorithm)
+
+
+def _decode_phone_setup_token(rs: RegStack, token: str) -> tuple[str, str]:
+    from datetime import datetime
+
+    import jwt as pyjwt
+
+    from regstack.config.secrets import derive_secret
+
+    key = derive_secret(rs.config.jwt_secret.get_secret_value(), _PHONE_SETUP_PURPOSE)
+    try:
+        claims = pyjwt.decode(
+            token,
+            key,
+            algorithms=[rs.config.jwt_algorithm],
+            audience=rs.config.jwt_audience,
+            options={
+                "require": ["sub", "exp", "iat", "jti", "purpose", "phone"],
+                "verify_exp": False,
+                "verify_iat": False,
+                "verify_nbf": False,
+            },
+        )
+    except pyjwt.PyJWTError as exc:
+        raise TokenError(str(exc)) from exc
+    if claims.get("purpose") != _PHONE_SETUP_PURPOSE:
+        raise TokenError("token purpose mismatch")
+    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["phone"])
+
+
+def _outcome_to_http(result):
+    code = result.outcome
+    if code is MfaVerifyOutcome.MISSING:
+        detail = "No pending verification code — request a new one."
+    elif code is MfaVerifyOutcome.EXPIRED:
+        detail = "Verification code has expired. Request a new one."
+    elif code is MfaVerifyOutcome.LOCKED:
+        detail = "Too many wrong attempts — request a new code."
+    else:
+        detail = (
+            f"Wrong code; {result.attempts_remaining} attempts remaining."
+            if result.attempts_remaining
+            else "Wrong code."
+        )
+    return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)
+
+
+__all__ = [
+    "PhoneConfirmRequest",
+    "PhoneDisableRequest",
+    "PhoneStartRequest",
+    "PhoneStartResponse",
+    "build_phone_router",
+]