릴리스: v1.4.45 이메일 인증 및 비밀번호 재설정 추가

docs/spec.md

@@ -64,9 +64,24 @@
   - `email`: string
   - `nickname`: string
   - `passwordHash`: string
+  - `emailVerified`: boolean
   - `isAdmin`: boolean
   - `avatarSrc`: string
   - `createdAt`: number
+- `emailVerificationTokens`
+  - `id`: string
+  - `userId`: string
+  - `tokenHash`: string
+  - `expiresAt`: number
+  - `consumedAt`: number
+  - `createdAt`: number
+- `passwordResetTokens`
+  - `id`: string
+  - `userId`: string
+  - `tokenHash`: string
+  - `expiresAt`: number
+  - `consumedAt`: number
+  - `createdAt`: number
 - `games`
   - `id`: string
   - `name`: string
@@ -110,11 +125,21 @@
 ## 주요 API
 - 인증
   - `POST /api/auth/signup`
+    - 첫 관리자 계정은 바로 로그인 세션을 만들고, 이후 일반 계정은 인증 메일 발송 후 `verificationRequired` 상태를 반환한다.
   - `POST /api/auth/login`
+    - 이메일 인증이 끝나지 않은 계정은 `email_unverified`로 차단한다.
   - `POST /api/auth/logout`
   - `GET /api/auth/me`
   - `GET /api/auth/meta`
   - `POST /api/auth/profile`
+  - `POST /api/auth/email/verify`
+    - `login?verifyToken=...` 링크에서 받은 토큰으로 이메일 인증을 완료하고 바로 로그인 세션을 만든다.
+  - `POST /api/auth/email/resend`
+    - 미인증 계정의 인증 메일을 다시 발송한다.
+  - `POST /api/auth/password-reset/request`
+    - 입력한 이메일로 비밀번호 재설정 링크를 발송한다.
+  - `POST /api/auth/password-reset/confirm`
+    - `login?resetToken=...` 링크의 토큰과 새 비밀번호로 비밀번호를 재설정하고 바로 로그인 세션을 만든다.
 - 주제
   - `GET /api/topics`
   - `GET /api/topics/:topicId`
@@ -245,6 +270,20 @@
   - `TRUST_PROXY`: 프록시 홉 수
   - `SESSION_COOKIE_SECURE`: `true`면 HTTPS 전용 쿠키
   - `SESSION_COOKIE_SAME_SITE`: 기본 `lax`
+  - `APP_ORIGIN`: 이메일 인증/비밀번호 재설정 링크를 만들 때 사용할 서비스 기준 주소
+  - `SMTP_HOST`: 메일 서버 호스트, Gmail SMTP 사용 시 보통 `smtp.gmail.com`
+  - `SMTP_PORT`: 메일 서버 포트, Gmail SSL SMTP 기준 보통 `465`
+  - `SMTP_SECURE`: `true`면 SMTP SSL/TLS 연결을 사용
+  - `SMTP_USER`: 발신용 Gmail 계정
+  - `SMTP_PASS`: Gmail 앱 비밀번호
+  - `SMTP_FROM`: 실제 메일 From 주소, 비워두면 `SMTP_USER`를 기본값으로 사용한다
+
+## 회원 인증 메모
+- 첫 번째 가입 계정은 운영 초기 부트스트랩을 위해 이메일 인증 없이 바로 최고 관리자 계정으로 활성화한다.
+- 두 번째 이후 일반 회원가입은 가입 직후 로그인 세션을 만들지 않고, 인증 메일 링크를 눌러 `email_verified=1`이 된 뒤에만 로그인할 수 있게 한다.
+- 인증 메일/비밀번호 재설정 메일 토큰은 원문을 DB에 저장하지 않고 SHA-256 해시만 저장하며, 새 토큰을 발급할 때는 같은 사용자의 이전 미사용 토큰을 먼저 만료 처리한다.
+- 이메일 인증 토큰은 24시간, 비밀번호 재설정 토큰은 1시간 유효 기간을 사용한다.
+- 비밀번호 재설정 링크로 새 비밀번호를 저장한 사용자는 같은 메일 주소를 확인한 것으로 보고, 기존에 미인증 상태였더라도 저장과 함께 이메일 인증을 완료 처리한다.
 
 ## 운영 배포 메모
 - 프로덕션 컴포즈 파일은 [docker-compose.prod.yml](/Users/bicute/Desktop/zenn.dev/tier-cursor/docker-compose.prod.yml)이다.