Feature/auth password reset with OCI Email SDK (#139)

## 변경 사항

- 비밀번호 찾기/재설정 API 3종 추가
  - `POST /api/v3/auth/password-reset/email`
  - `POST /api/v3/auth/password-reset/verify`
  - `POST /api/v3/auth/password-reset`
- 비밀번호 재설정 인증번호 저장용 `password_reset_verification` 테이블 추가
- OCI Email Delivery SDK 기반 메일 전송 서비스 추가
- 인증번호 생성, 해시 저장, 만료 처리, 시도 횟수 제한, 사용 완료 처리 로직 추가
- 비밀번호 재설정 서비스 테스트 및 메일 SDK payload 테스트 추가

## 구현 상세

- 인증번호 원문은 DB에 저장하지 않고 `PasswordService`로 해시하여 저장합니다.
- 인증번호 유효 시간은 10분입니다.
- 인증번호 검증 실패는 최대 5회까지 허용합니다.
- 존재하지 않는 이메일로 인증번호 전송 요청이 들어와도 계정 존재 여부가 노출되지 않도록 정상 응답합니다.
- 메일 발송은 SMTP credential 없이
`oci.email_data_plane.EmailDPClient.submit_email()`을 사용합니다.
- Instance Principal signer 생성이 실패할 때만 로컬 OCI
config(`oci.config.from_file()`)로 fallback합니다.
- 비밀번호 재설정 인증번호는 DB에 먼저 저장된 뒤 메일로 발송되어, 저장 실패 시 검증 불가능한 코드가 발송되지 않습니다.

## 필요한 운영 설정

OCI Email Delivery를 설정한 뒤 아래 secret/env 값을 등록해야 합니다.

```text
email_compartment_id
email_from_email
email_from_name        # optional
email_reply_to         # optional
email_service_endpoint # optional

---------

Co-authored-by: 문재영 <152019282+mjy926@users.noreply.github.com>

Author: snu-BuMinSeong

wacruit/src/apps/auth/__init__.py

@@ -1 +1,3 @@
 from .views import v3_router as router
+
+__all__ = ["router"]

wacruit/src/apps/auth/exceptions.py

@@ -14,3 +14,18 @@ def __init__(self):
 class EmailConflictException(WacruitException):
     def __init__(self):
         super().__init__(status_code=409, detail="이미 존재하는 이메일입니다.")
+
+
+class InvalidPasswordResetCodeException(WacruitException):
+    def __init__(self):
+        super().__init__(status_code=400, detail="인증 번호가 올바르지 않습니다.")
+
+
+class ExpiredPasswordResetCodeException(WacruitException):
+    def __init__(self):
+        super().__init__(status_code=400, detail="만료된 인증 번호입니다.")
+
+
+class PasswordResetCodeNotVerifiedException(WacruitException):
+    def __init__(self):
+        super().__init__(status_code=400, detail="인증 번호 확인이 필요합니다.")

wacruit/src/apps/auth/models.py

@@ -1,5 +1,10 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime
 from sqlalchemy.orm import Mapped
+from sqlalchemy.orm import mapped_column
 
+from wacruit.src.apps.common.sql import CURRENT_TIMESTAMP
 from wacruit.src.database.base import DeclarativeBase
 from wacruit.src.database.base import intpk
 from wacruit.src.database.base import str255
@@ -10,3 +15,19 @@ class BlockedToken(DeclarativeBase):
 
     id: Mapped[intpk]
     token: Mapped[str255]
+
+
+class PasswordResetVerification(DeclarativeBase):
+    __tablename__ = "password_reset_verification"
+
+    id: Mapped[intpk]
+    email: Mapped[str255] = mapped_column(index=True)
+    code_hash: Mapped[str255]
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    attempt_count: Mapped[int] = mapped_column(default=0)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=CURRENT_TIMESTAMP,
+    )

wacruit/src/apps/auth/repositories.py

@@ -1,13 +1,15 @@
+from datetime import datetime
 from typing import Annotated
 
 from fastapi import Depends
 from pydantic import EmailStr
 from sqlalchemy.orm import Session
 
 from wacruit.src.apps.auth.models import BlockedToken
+from wacruit.src.apps.auth.models import PasswordResetVerification
 from wacruit.src.apps.user.models import User
-from wacruit.src.database.connection import get_db_session
 from wacruit.src.database.connection import Transaction
+from wacruit.src.database.connection import get_db_session
 
 
 class AuthRepository:
@@ -25,6 +27,107 @@ def get_user_by_email(self, email: EmailStr) -> User | None:
     def get_user_by_id(self, user_id: int) -> User | None:
         return self.session.query(User).where(User.id == user_id).first()
 
+    def update_user(self, user: User) -> User:
+        with self.transaction:
+            self.session.merge(user)
+        return user
+
+    def create_password_reset_verification(
+        self, verification: PasswordResetVerification
+    ) -> PasswordResetVerification:
+        with self.transaction:
+            self.session.add(verification)
+        return verification
+
+    def replace_active_password_reset_for_email(
+        self,
+        email: EmailStr,
+        verification: PasswordResetVerification,
+        expires_at: datetime,
+    ) -> PasswordResetVerification:
+        with self.transaction:
+            (
+                self.session.query(PasswordResetVerification)
+                .where(
+                    PasswordResetVerification.email == email,
+                    PasswordResetVerification.used_at.is_(None),
+                )
+                .update(
+                    {PasswordResetVerification.expires_at: expires_at},
+                    synchronize_session="fetch",
+                )
+            )
+            self.session.add(verification)
+        return verification
+
+    def get_latest_password_reset_verification(
+        self, email: EmailStr
+    ) -> PasswordResetVerification | None:
+        return (
+            self.session.query(PasswordResetVerification)
+            .where(PasswordResetVerification.email == email)
+            .order_by(
+                PasswordResetVerification.created_at.desc(),
+                PasswordResetVerification.id.desc(),
+            )
+            .first()
+        )
+
+    def update_password_reset_verification(
+        self, verification: PasswordResetVerification
+    ) -> PasswordResetVerification:
+        with self.transaction:
+            self.session.merge(verification)
+        return verification
+
+    def consume_password_reset_verification(
+        self,
+        verification_id: int,
+        email: EmailStr,
+        password_hash: str,
+        used_at: datetime,
+    ) -> bool:
+        with self.transaction:
+            verification = (
+                self.session.query(PasswordResetVerification)
+                .where(
+                    PasswordResetVerification.id == verification_id,
+                    PasswordResetVerification.email == email,
+                )
+                .with_for_update()
+                .first()
+            )
+            if verification is None or verification.used_at is not None:
+                return False
+
+            user = (
+                self.session.query(User)
+                .where(User.email == email)
+                .with_for_update()
+                .first()
+            )
+            if user is None:
+                return False
+
+            user.password = password_hash
+            verification.used_at = used_at
+        return True
+
+    def expire_unused_password_reset_verifications(
+        self, email: EmailStr, expires_at: datetime
+    ) -> None:
+        verifications = (
+            self.session.query(PasswordResetVerification)
+            .where(
+                PasswordResetVerification.email == email,
+                PasswordResetVerification.used_at.is_(None),
+            )
+            .all()
+        )
+        with self.transaction:
+            for verification in verifications:
+                verification.expires_at = expires_at
+
     def is_blocked_token(self, token: str) -> bool:
         result = (
             self.session.query(BlockedToken).where(BlockedToken.token == token).first()

wacruit/src/apps/auth/schemas.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel
 from pydantic import EmailStr
+from pydantic import Field
 
 
 class LoginRequest(BaseModel):
@@ -14,3 +15,18 @@ class TokenResponse(BaseModel):
 
 class UserCheckRequest(BaseModel):
     email: EmailStr
+
+
+class PasswordResetEmailRequest(BaseModel):
+    email: EmailStr
+
+
+class PasswordResetVerifyRequest(BaseModel):
+    email: EmailStr
+    code: str = Field(..., min_length=6, max_length=6)
+
+
+class PasswordResetRequest(BaseModel):
+    email: EmailStr
+    code: str = Field(..., min_length=6, max_length=6)
+    new_password: str = Field(..., min_length=8, max_length=50)

wacruit/src/apps/auth/services.py

@@ -1,29 +1,41 @@
 from datetime import datetime
 from datetime import timedelta
+import secrets
 from typing import Annotated
 
-from authlib.jose import jwt
 from authlib.jose import JWTClaims
+from authlib.jose import jwt
 from authlib.jose.errors import JoseError
 from fastapi import Depends
 from pydantic import EmailStr
 
+from wacruit.src.apps.auth.exceptions import ExpiredPasswordResetCodeException
+from wacruit.src.apps.auth.exceptions import InvalidPasswordResetCodeException
 from wacruit.src.apps.auth.exceptions import InvalidTokenException
+from wacruit.src.apps.auth.exceptions import PasswordResetCodeNotVerifiedException
 from wacruit.src.apps.auth.exceptions import UserNotFoundException
+from wacruit.src.apps.auth.models import PasswordResetVerification
 from wacruit.src.apps.auth.repositories import AuthRepository
-from wacruit.src.apps.common.security import get_token_secret
 from wacruit.src.apps.common.security import PasswordService
+from wacruit.src.apps.common.security import get_token_secret
+from wacruit.src.apps.mail.services import EmailService
 from wacruit.src.apps.user.models import User
 
+PASSWORD_RESET_CODE_LENGTH = 6
+PASSWORD_RESET_CODE_TTL_MINUTES = 10
+PASSWORD_RESET_MAX_ATTEMPTS = 5
+
 
 class AuthService:
     def __init__(
         self,
         auth_repository: Annotated[AuthRepository, Depends()],
         token_secret: Annotated[str, Depends(get_token_secret)],
+        email_service: Annotated[EmailService, Depends()],
     ) -> None:
         self.auth_repository = auth_repository
         self.token_secret = token_secret
+        self.email_service = email_service
 
     def get_user_by_id(self, user_id: int) -> User | None:
         return self.auth_repository.get_user_by_id(user_id)
@@ -89,3 +101,76 @@ def check_available_email(self, email: EmailStr) -> bool:
         if user:
             return False
         return True
+
+    def send_password_reset_email(self, email: EmailStr) -> None:
+        user = self.auth_repository.get_user_by_email(email)
+        if user is None:
+            return
+
+        code = self._generate_password_reset_code()
+        now = datetime.now()
+        expires_at = now + timedelta(minutes=PASSWORD_RESET_CODE_TTL_MINUTES)
+
+        self.auth_repository.replace_active_password_reset_for_email(
+            email,
+            PasswordResetVerification(
+                email=email,
+                code_hash=PasswordService.hash_password(code),
+                expires_at=expires_at,
+            ),
+            now,
+        )
+        self.email_service.send_password_reset_code(str(email), code)
+
+    def verify_password_reset_code(self, email: EmailStr, code: str) -> None:
+        verification = self._get_valid_password_reset_verification(email, code)
+        verification.verified_at = datetime.now()
+        self.auth_repository.update_password_reset_verification(verification)
+
+    def reset_password(self, email: EmailStr, code: str, new_password: str) -> None:
+        verification = self._get_valid_password_reset_verification(email, code)
+        if verification.verified_at is None:
+            raise PasswordResetCodeNotVerifiedException()
+
+        user = self.auth_repository.get_user_by_email(email)
+        if user is None:
+            raise UserNotFoundException()
+
+        consumed = self.auth_repository.consume_password_reset_verification(
+            verification.id,
+            email,
+            PasswordService.hash_password(new_password),
+            datetime.now(),
+        )
+        if not consumed:
+            raise InvalidPasswordResetCodeException()
+
+    def _generate_password_reset_code(self) -> str:
+        max_value = 10**PASSWORD_RESET_CODE_LENGTH
+        return str(secrets.randbelow(max_value)).zfill(PASSWORD_RESET_CODE_LENGTH)
+
+    def _get_valid_password_reset_verification(
+        self, email: EmailStr, code: str
+    ) -> PasswordResetVerification:
+        if not code.isdigit():
+            raise InvalidPasswordResetCodeException()
+
+        verification = self.auth_repository.get_latest_password_reset_verification(
+            email
+        )
+        if verification is None or verification.used_at is not None:
+            raise InvalidPasswordResetCodeException()
+
+        now = datetime.now()
+        if verification.expires_at < now:
+            raise ExpiredPasswordResetCodeException()
+
+        if verification.attempt_count >= PASSWORD_RESET_MAX_ATTEMPTS:
+            raise InvalidPasswordResetCodeException()
+
+        if not PasswordService.verify_password(code, verification.code_hash):
+            verification.attempt_count += 1
+            self.auth_repository.update_password_reset_verification(verification)
+            raise InvalidPasswordResetCodeException()
+
+        return verification