[Auth] 비밀번호 재설정·가입 약관 동의 이력 구현

[hywznn]

한 줄 요약

Figma 회원가입·비밀번호 찾기 화면이 실제로 안전하게 동작하도록 비밀번호 재설정 API와 가입 약관 동의 이력을 구현합니다.

화면 기준

• Figma [PWF] Prototype-WireFrame-3rd의 04_Authentication & Onboarding
• 비밀번호 찾기 → 메일 안내 → 새 비밀번호 입력 → 완료
• 회원가입의 서비스 이용약관·개인정보 처리방침 필수 동의와 마케팅 선택 동의
• 세부 요청·응답 필드는 Notion API 명세를 기준으로 합니다.

소유 API와 변경 계약

• POST /api/v1/auth/password-reset-requests
• POST /api/v1/auth/password-resets
• 기존 POST /api/v1/auth/signup에 약관 동의 version·결과 저장 규칙 추가

회원가입 성공 후 자동 로그인하지 않습니다. Client가 성공 화면으로 이동한 뒤 기존 POST /api/v1/auth/login을 별도로 호출합니다.

비밀번호 재설정 흐름

1. 사용자가 이메일을 입력합니다.
2. 계정 존재 여부와 관계없이 동일한 202 Accepted 응답을 반환합니다.
3. 존재하는 활성 계정이면 일회용 원본 token을 생성하고 DB에는 hash만 저장합니다.
4. 메일에는 만료시간이 있는 재설정 링크를 전달합니다.
5. 새 비밀번호가 정책을 통과하면 token을 사용 처리하고 비밀번호 hash를 교체합니다.
6. 기존 Refresh Token을 모두 폐기하여 다른 기기의 로그인 세션도 종료합니다.

회원가입 동의 이력

기존 가입 요청에 다음 의미의 동의 정보를 추가합니다. 최종 DTO 이름은 OpenAPI와 Notion에서 한 번만 확정합니다.

• 필수: 서비스 이용약관 동의 여부와 version
• 필수: 개인정보 처리방침 동의 여부와 version
• 선택: 마케팅 정보 수신 동의 여부와 version
• 서버 저장: companyId, userId, 동의 종류, version, 동의 여부, 동의 시각, requestId
• 필수 동의가 없거나 현재 지원하지 않는 version이면 가입을 거부합니다.
• 체크박스 값만 user_account에 덮어쓰지 않고 동의 변경 이력을 별도 record로 남깁니다.

초보자용 구현 순서

1. 비밀번호 재설정 token과 동의 이력용 Flyway migration을 작성합니다.
2. token 생성·hash·만료 검증을 application Port로 분리합니다.
3. 메일 발송은 PasswordResetNotificationPort 뒤에 두어 Provider를 교체할 수 있게 합니다.
4. 두 재설정 Controller와 Service를 구현합니다.
5. 회원가입 DTO·Service에 동의 검증과 이력 저장을 연결합니다.
6. 성공 후 Refresh Token 전체 폐기와 감사로그를 연결합니다.
7. OpenAPI 예시와 정상·만료·재사용·rate limit·동시 요청 테스트를 작성합니다.

보안 규칙

• 등록되지 않은 이메일인지 응답 시간·본문·상태코드로 구분할 수 없게 합니다.
• 원본 token, 새 비밀번호, 이메일 원문을 일반 로그와 Issue에 남기지 않습니다.
• token은 일회용·만료 필수이며 DB에는 hash만 저장합니다.
• 재전송에는 cooldown과 사용자·IP 기준 rate limit을 적용합니다.
• 비밀번호는 기존 정책에 맞춰 BCrypt/Argon2 hash만 저장합니다.
• 개발용 메일 Adapter도 원본 token을 운영 로그에 출력하지 않습니다.

완료 조건

• 존재/미존재 이메일 요청이 같은 외부 응답을 반환합니다.
• 만료·위조·이미 사용한 token이 거부됩니다.
• 비밀번호 변경 후 기존 Refresh Token이 모두 무효화됩니다.
• 필수 약관 미동의와 잘못된 version의 가입이 거부됩니다.
• 선택 동의를 하지 않아도 가입할 수 있습니다.
• 동의 version·시각·actor와 보안 감사로그를 확인할 수 있습니다.
• 타 사업장 데이터가 섞이지 않고 OpenAPI·통합 테스트가 있습니다.

이번 이슈에서 하지 않는 것

• 회원가입 직후 자동 로그인
• 소셜 로그인
• 실제 개인정보 원문을 포함하는 메일
• 관리자용 약관 편집 화면
• SMS 비밀번호 재설정

관계

• 선행 완료: [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Auth] 사업장 회원가입·초기 ADMIN 계정 생성 API 구현 #43
• 연계: [Settings] 사업장 설정 조회·수정 API 구현 #16
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

현재 구현 상태 (2026-08-07)

PR #100으로 비밀번호 재설정 API, token hash·만료·1회 사용, 기존 Refresh Token 폐기, 약관 동의 이력과 보안 테스트를 구현했습니다.

현재 실제 메일 Provider가 없어 안전한 NoOp Adapter를 사용합니다. 따라서 API와 보안 흐름은 준비됐지만 사용자가 재설정 링크를 실제 이메일로 받는 화면 E2E는 아직 완료되지 않았습니다.

• 실제 메일 Provider Adapter 연결
• 재설정 메일 수신부터 새 비밀번호 로그인까지 사용자 E2E 확인