Fix password reset email flow (#142)

## Summary
- Recreate the password reset fixes on top of develop so the diff is
based on the correct target branch
- Return UserNotFoundException for unknown password-reset email requests
- Improve password reset email payload and sender validation
- Reduce reset code TTL from 10 minutes to 5 minutes
- Address CodeRabbit feedback for commit timing, row locking,
timezone-aware datetimes, settings init, and migration defaults

## Tests
- .venv\Scripts\python.exe -m pytest
wacruit\src\tests\auth\test_auth_password_reset_service.py
wacruit\src\tests\mail\test_mail_service.py
- 21 passed, 1 warning

## Notes
- Previous PR #141 was closed because its branch history was not based
on develop.
- Local .env.test OCI mail settings were not included.

Author: snu-BuMinSeong

wacruit/src/apps/auth/exceptions.py

@@ -8,7 +8,7 @@ def __init__(self):
 
 class InvalidTokenException(WacruitException):
     def __init__(self):
-        super().__init__(status_code=401, detail="잘못된 토큰입니다.")
+        super().__init__(status_code=401, detail="유효하지 않은 토큰입니다.")
 
 
 class EmailConflictException(WacruitException):
@@ -18,14 +18,14 @@ def __init__(self):
 
 class InvalidPasswordResetCodeException(WacruitException):
     def __init__(self):
-        super().__init__(status_code=400, detail="인증 번호가 올바르지 않습니다.")
+        super().__init__(status_code=400, detail="인증번호가 올바르지 않습니다.")
 
 
 class ExpiredPasswordResetCodeException(WacruitException):
     def __init__(self):
-        super().__init__(status_code=400, detail="만료된 인증 번호입니다.")
+        super().__init__(status_code=400, detail="만료된 인증번호입니다.")
 
 
 class PasswordResetCodeNotVerifiedException(WacruitException):
     def __init__(self):
-        super().__init__(status_code=400, detail="인증 번호 확인이 필요합니다.")
+        super().__init__(status_code=400, detail="인증번호 확인이 필요합니다.")

wacruit/src/apps/auth/models.py

@@ -26,7 +26,7 @@ class PasswordResetVerification(DeclarativeBase):
     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)
+    attempt_count: Mapped[int] = mapped_column(default=0, server_default="0")
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
         server_default=CURRENT_TIMESTAMP,

wacruit/src/apps/auth/repositories.py

@@ -5,6 +5,7 @@
 from pydantic import EmailStr
 from sqlalchemy.orm import Session
 
+from wacruit.src.apps.auth.exceptions import UserNotFoundException
 from wacruit.src.apps.auth.models import BlockedToken
 from wacruit.src.apps.auth.models import PasswordResetVerification
 from wacruit.src.apps.user.models import User
@@ -46,6 +47,15 @@ def replace_active_password_reset_for_email(
         expires_at: datetime,
     ) -> PasswordResetVerification:
         with self.transaction:
+            # Lock the user row to serialize password reset requests per email.
+            locked_user = (
+                self.session.query(User)
+                .where(User.email == email)
+                .with_for_update()
+                .one_or_none()
+            )
+            if locked_user is None:
+                raise UserNotFoundException()
             (
                 self.session.query(PasswordResetVerification)
                 .where(
@@ -60,6 +70,9 @@ def replace_active_password_reset_for_email(
             self.session.add(verification)
         return verification
 
+    def commit(self) -> None:
+        self.session.commit()
+
     def get_latest_password_reset_verification(
         self, email: EmailStr
     ) -> PasswordResetVerification | None:

wacruit/src/apps/auth/services.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 from datetime import timedelta
+from datetime import timezone
 import secrets
 from typing import Annotated
 
@@ -22,10 +23,20 @@
 from wacruit.src.apps.user.models import User
 
 PASSWORD_RESET_CODE_LENGTH = 6
-PASSWORD_RESET_CODE_TTL_MINUTES = 10
+PASSWORD_RESET_CODE_TTL_MINUTES = 5
 PASSWORD_RESET_MAX_ATTEMPTS = 5
 
 
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _as_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
 class AuthService:
     def __init__(
         self,
@@ -90,7 +101,7 @@ def issue_token(self, user_id: int, expiration_hour: int, token_type: str) -> st
         header = {"alg": "HS256"}
         payload = {
             "sub": user_id,
-            "exp": int((datetime.now() + timedelta(hours=expiration_hour)).timestamp()),
+            "exp": int((_utc_now() + timedelta(hours=expiration_hour)).timestamp()),
             "token_type": token_type,
         }
 
@@ -105,10 +116,10 @@ def check_available_email(self, email: EmailStr) -> bool:
     def send_password_reset_email(self, email: EmailStr) -> None:
         user = self.auth_repository.get_user_by_email(email)
         if user is None:
-            return
+            raise UserNotFoundException()
 
         code = self._generate_password_reset_code()
-        now = datetime.now()
+        now = _utc_now()
         expires_at = now + timedelta(minutes=PASSWORD_RESET_CODE_TTL_MINUTES)
 
         self.auth_repository.replace_active_password_reset_for_email(
@@ -120,11 +131,12 @@ def send_password_reset_email(self, email: EmailStr) -> None:
             ),
             now,
         )
+        self.auth_repository.commit()
         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()
+        verification.verified_at = _utc_now()
         self.auth_repository.update_password_reset_verification(verification)
 
     def reset_password(self, email: EmailStr, code: str, new_password: str) -> None:
@@ -140,7 +152,7 @@ def reset_password(self, email: EmailStr, code: str, new_password: str) -> None:
             verification.id,
             email,
             PasswordService.hash_password(new_password),
-            datetime.now(),
+            _utc_now(),
         )
         if not consumed:
             raise InvalidPasswordResetCodeException()
@@ -161,8 +173,8 @@ def _get_valid_password_reset_verification(
         if verification is None or verification.used_at is not None:
             raise InvalidPasswordResetCodeException()
 
-        now = datetime.now()
-        if verification.expires_at < now:
+        now = _utc_now()
+        if _as_utc(verification.expires_at) < now:
             raise ExpiredPasswordResetCodeException()
 
         if verification.attempt_count >= PASSWORD_RESET_MAX_ATTEMPTS:

wacruit/src/apps/auth/views.py

@@ -60,7 +60,11 @@ def check_available_email(
 @v3_router.post(
     "/password-reset/email",
     status_code=200,
-    responses=responses_from(MailConfigException, MailSendFailedException),
+    responses=responses_from(
+        MailConfigException,
+        MailSendFailedException,
+        UserNotFoundException,
+    ),
 )
 def send_password_reset_email(
     req: PasswordResetEmailRequest,

wacruit/src/apps/mail/config.py

@@ -25,8 +25,8 @@ class Config(BaseSettings.Config):
         env_prefix = "EMAIL_"
         env_file = settings.env_files
 
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **values):
+        super().__init__(**values)
         secret_manager = OCISecretManager()
         if secret_manager.is_available():
             self._load_from_vault(secret_manager)

wacruit/src/apps/mail/services.py

@@ -1,3 +1,4 @@
+from html import escape
 from typing import Optional
 import uuid
 
@@ -22,15 +23,31 @@ def __init__(self) -> None:
         self._client: Optional[EmailDPClient] = None
 
     def send_password_reset_code(self, to_email: str, code: str) -> None:
-        subject = "[Waffle Studio] 비밀번호 재설정 인증 번호"
+        subject = "[Waffle Studio] 비밀번호 재설정 인증번호"
         content = (
-            "비밀번호 재설정을 위한 인증 번호입니다.\n\n"
-            f"인증 번호: {code}\n\n"
-            "인증 번호는 10분 동안 유효합니다."
+            "비밀번호 재설정을 위한 인증번호입니다.\n\n"
+            f"인증번호: {code}\n\n"
+            "인증번호는 5분 동안 유효합니다."
+        )
+        html_content = (
+            "<p>비밀번호 재설정을 위한 인증번호입니다.</p>"
+            f"<p><strong>인증번호: {escape(code)}</strong></p>"
+            "<p>인증번호는 5분 동안 유효합니다.</p>"
+        )
+        self.send_email(
+            to_email=to_email,
+            subject=subject,
+            content=content,
+            html_content=html_content,
         )
-        self.send_email(to_email=to_email, subject=subject, content=content)
 
-    def send_email(self, to_email: str, subject: str, content: str) -> None:
+    def send_email(
+        self,
+        to_email: str,
+        subject: str,
+        content: str,
+        html_content: str | None = None,
+    ) -> None:
         if not mail_config.compartment_id or not mail_config.from_email:
             raise MailConfigException()
         if not self._is_valid_from_email(mail_config.from_email):
@@ -51,6 +68,7 @@ def send_email(self, to_email: str, subject: str, content: str) -> None:
                     recipients=Recipients(to=[EmailAddress(email=to_email)]),
                     subject=subject,
                     body_text=content,
+                    body_html=html_content,
                     reply_to=(
                         [EmailAddress(email=mail_config.reply_to)]
                         if mail_config.reply_to
@@ -78,6 +96,8 @@ def _get_client(self) -> EmailDPClient:
         try:
             signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
         except Exception:  # noqa: PLW0718
+            if not (settings.is_local or settings.is_test):
+                raise
             config = oci.config.from_file()
             self._client = EmailDPClient(config, **client_kwargs)
         else:
@@ -91,8 +111,12 @@ def _get_client(self) -> EmailDPClient:
 
     def _generate_message_id(self) -> str:
         domain = mail_config.from_email.rsplit("@", 1)[-1]
-        return f"<{uuid.uuid4()}@{domain}>"
+        return f"{uuid.uuid4()}@{domain}"
 
     def _is_valid_from_email(self, email: str) -> bool:
+        if email != email.strip() or any(char.isspace() for char in email):
+            return False
+        if email.count("@") != 1:
+            return False
         local_part, separator, domain = email.partition("@")
         return bool(local_part and separator and domain and "@" not in domain)

wacruit/src/database/migrations/versions/2026_05_17_0000-2f9c8e0a1b34_add_password_reset_verification.py

@@ -24,7 +24,12 @@ def upgrade() -> None:
         sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("verified_at", sa.DateTime(timezone=True), nullable=True),
         sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("attempt_count", sa.Integer(), nullable=False),
+        sa.Column(
+            "attempt_count",
+            sa.Integer(),
+            server_default=sa.text("0"),
+            nullable=False,
+        ),
         sa.Column(
             "created_at",
             sa.DateTime(timezone=True),

wacruit/src/tests/auth/conftest.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from datetime import timezone
 
 from pydantic import EmailStr
 import pytest
@@ -13,6 +14,7 @@ class FakeAuthRepository:
     def __init__(self) -> None:
         self.users: dict[str, User] = {}
         self.verifications: list[PasswordResetVerification] = []
+        self.commit_count = 0
 
     def get_user_by_email(self, email: EmailStr) -> User | None:
         return self.users.get(str(email))
@@ -28,11 +30,14 @@ def create_password_reset_verification(
         self, verification: PasswordResetVerification
     ) -> PasswordResetVerification:
         verification.id = len(self.verifications) + 1
-        verification.created_at = datetime.now()
+        verification.created_at = datetime.now(timezone.utc)
         verification.attempt_count = verification.attempt_count or 0
         self.verifications.append(verification)
         return verification
 
+    def commit(self) -> None:
+        self.commit_count += 1
+
     def replace_active_password_reset_for_email(
         self,
         email: EmailStr,

wacruit/src/tests/auth/test_auth_password_reset_service.py

@@ -1,12 +1,14 @@
 from datetime import datetime
 from datetime import timedelta
+from datetime import timezone
 
 from pydantic import EmailStr
 import pytest
 
 from wacruit.src.apps.auth.exceptions import ExpiredPasswordResetCodeException
 from wacruit.src.apps.auth.exceptions import InvalidPasswordResetCodeException
 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.services import AuthService
 from wacruit.src.apps.common.security import PasswordService
@@ -30,6 +32,10 @@ def test_send_password_reset_email_creates_verification(
     )
     assert verification is not None
     assert PasswordService.verify_password("123456", verification.code_hash)
+    now = datetime.now(timezone.utc)
+    assert now + timedelta(minutes=4, seconds=50) < verification.expires_at
+    assert verification.expires_at < now + timedelta(minutes=5, seconds=10)
+    assert auth_repository.commit_count == 1
     assert fake_email_service.sent_password_reset_codes == [(user.email, "123456")]
 
 
@@ -53,7 +59,7 @@ def test_send_password_reset_email_replaces_active_verification(
         EmailStr(user.email)
     )
     assert first_verification is not None
-    assert first_verification.expires_at <= datetime.now()
+    assert first_verification.expires_at <= datetime.now(timezone.utc)
     assert latest_verification is not None
     assert latest_verification != first_verification
     assert PasswordService.verify_password("654321", latest_verification.code_hash)
@@ -63,14 +69,15 @@ def test_send_password_reset_email_replaces_active_verification(
     ]
 
 
-def test_send_password_reset_email_ignores_unknown_email(
+def test_send_password_reset_email_rejects_unknown_email(
     auth_service: AuthService,
     auth_repository: FakeAuthRepository,
     fake_email_service: FakeEmailService,
 ):
     email = EmailStr("unknown@email.com")
 
-    auth_service.send_password_reset_email(email)
+    with pytest.raises(UserNotFoundException):
+        auth_service.send_password_reset_email(email)
 
     assert auth_repository.get_latest_password_reset_verification(email) is None
     assert fake_email_service.sent_password_reset_codes == []
@@ -119,7 +126,7 @@ def test_verify_password_reset_code_rejects_expired_code(
     verification = PasswordResetVerification(
         email=user.email,
         code_hash=PasswordService.hash_password("123456"),
-        expires_at=datetime.now() - timedelta(minutes=1),
+        expires_at=datetime.now(timezone.utc) - timedelta(minutes=1),
     )
     auth_repository.create_password_reset_verification(verification)
 
@@ -180,7 +187,7 @@ def use_verification_before_consume(
     ) -> bool:
         verification = auth_repository.get_latest_password_reset_verification(email)
         assert verification is not None
-        verification.used_at = datetime.now()
+        verification.used_at = datetime.now(timezone.utc)
         return consume_password_reset_verification(
             verification_id,
             email,