⚙️ [기능추가][인증] Auth 인프라 셋업 (Firebase + JWT 자동 주입 + 토큰 자동 재발급)

[EM-H20]

📝 현재 문제점

• 현재 프로젝트에 인증 인프라가 구축되어 있지 않음
• API 호출 시 JWT 토큰을 수동으로 헤더에 주입해야 함
• 토큰 만료(401) 시 자동 재발급 로직이 없어 사용자가 강제로 재로그인해야 함
• Firebase 기반 소셜 로그인(Google/Apple) 인프라 부재

🛠️ 해결 방안 / 제안 기능

docs/AUTH_INFRA_PORTING_GUIDE.md 문서를 기반으로 검증된 Auth 인프라를 본 프로젝트에 이식

핵심 기능:

• Firebase 기반 Google/Apple 소셜 로그인
• 로그인 성공 시 백엔드로부터 JWT(access + refresh) 토큰 발급 및 안전 저장
• 모든 API 요청에 Authorization 헤더 자동 주입
• 401 발생 시 refresh token 으로 자동 재발급(reissue) 후 원 요청 재시도
• 재발급 실패 시 강제 로그아웃 처리 (Firebase signOut + 토큰 삭제 + 로그인 화면 이동)
• 동시 다발 401 발생 시 단 한 번의 reissue 만 수행하도록 요청 큐잉 (QueuedInterceptor)
• 재시도 무한 루프 방지 가드

⚙️ 작업 내용

• pubspec.yaml 의존성 추가 및 버전 동기화 (특히 retrofit: 4.7.3 핀)
• Core 레이어 이식
  • core/errors/app_exception.dart
  • core/network/api_error_response.dart
  • core/network/dio_exception_handler.dart
  • core/network/auth_interceptor.dart (_publicPaths 프로젝트별 조정)
  • core/network/dio_client.dart
  • core/storage/secure_token_storage.dart
  • core/config/env_config.dart (환경 변수 키 본 프로젝트 기준 조정)
  • core/constants/api_endpoints.dart (본 프로젝트 API 스펙 기준 작성)
• Auth Feature 이식
  • Domain: auth_result_entity, auth_repository, firebase_auth_error_handler
  • Data: firebase_auth_datasource, auth_remote_datasource, DTO 모델, auth_repository_impl
  • Presentation: auth_provider (Cold-start 토큰 복원 로직 본 프로젝트 기준 조정)
• Firebase 프로젝트 연동 설정 (google-services.json / GoogleService-Info.plist)
• 환경 변수(.env) 셋업
• 동작 검증 시나리오: 소셜 로그인 → JWT 발급 → API 자동 인증 → 401 자동 reissue → reissue 실패 시 강제 로그아웃

📋 참고 자료

• docs/AUTH_INFRA_PORTING_GUIDE.md
• 원본 repo: cops_and_robbers (Flutter 3.9.2+, Dart 3.9.2+)

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[EM-H20]

Guide by SUH-LAB

브랜치

20260504_#72_Auth_인프라_셋업_Firebase_JWT_자동_주입_토큰_자동_재발급

커밋 메시지

Auth 인프라 셋업 (Firebase + JWT 자동 주입 + 토큰 자동 재발급) : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-FE/issues/72

[EM-H20]

📌 작업 개요

이슈 #72 Auth 인프라 셋업의 최종 단계. 백엔드 OpenAPI 스펙(docs/api-docs.json) 갱신에 맞춰 로그인 DTO와 토큰 저장소를 재정렬하고, Firebase-only 임시 모드를 제거하여 백엔드 /api/auth/login 실제 연동을 활성화. AuthInterceptor를 QueuedInterceptor 패턴으로 리팩토링하고, 강제 로그아웃 콜백을 Riverpod Provider 로 역전(IoC)하여 core 모듈이 feature 모듈에 의존하지 않도록 정리.

🎯 구현 목표

• 백엔드 OpenAPI 스펙(socialType / memberId / isNewMember) 정렬
• 모든 보호 API 호출에 JWT Access Token 자동 주입
• 401 응답 시 Refresh Token 으로 재발급 → 원 요청 재시도
• 동시 다발 401 에서도 단 1회 reissue 만 수행하도록 큐잉
• 재발급 실패 시 강제 로그아웃 (Firebase signOut + 토큰 삭제 + 로그인 화면 이동)
• iOS 재설치 시 Keychain 잔존 토큰 자동 정리
• core ↔ auth 모듈 의존성 역전

✅ 구현 내용

백엔드 API 스펙 갱신

• 파일: docs/api-docs.json (+606 / -18)
• 변경 내용: 백엔드 OpenAPI 스펙 전면 갱신. LoginRequest 필드를 socialType + idToken 2개로 축소, LoginResponse에 memberId / isNewMember 도입
• 이유: 이전 스펙의 socialPlatform / userId / isNewUser / fcmToken 등이 모두 변경됨에 따라 클라이언트 DTO 재정렬 기반 마련

백엔드 OpenAPI 스펙 정렬 (필드 리네이밍)

• 파일:
  • lib/features/auth/data/models/login_request_model.dart
  • lib/features/auth/data/models/login_response_model.dart
  • lib/features/auth/domain/entities/auth_result_entity.dart
  • lib/features/auth/domain/repositories/auth_repository.dart
  • lib/features/auth/domain/usecases/sign_in_with_google_usecase.dart
  • lib/features/auth/domain/usecases/sign_in_with_apple_usecase.dart
• 변경 내용:
  • socialPlatform → socialType (enum: KAKAO / GOOGLE / APPLE)
  • userId → memberId (백엔드 식별자, int64)
  • isNewUser → isNewMember
  • LoginRequestModel 에서 fcmToken / deviceType / deviceId 필드 제거
• 이유: 백엔드가 받지 않는 필드를 전송하지 않도록 정리. 게스트 모드 식별을 위한 sentinel 값 kGuestMemberId = -1 도입

토큰 저장소 Provider 화 및 신규 필드 추가

• 파일: lib/core/storage/secure_token_storage.dart (+ .g.dart 신규)
• 변경 내용:
  • @Riverpod(keepAlive: true) secureTokenStorageProvider 도입
  • saveMemberId / getMemberId / saveIsNewMember / getIsNewMember 메서드 추가
  • clearTokensIfReinstalled() 추가 — SharedPreferences 플래그로 신규 설치 감지 후 Keychain 토큰 정리
• 이유: iOS Keychain 은 앱 삭제 후에도 데이터가 잔존 → 재설치 시 만료된 토큰으로 요청이 발생하던 문제 해결. 또한 코어 인프라가 Provider 화되어 인터셉터 콜백에서 안전 접근 가능

AuthInterceptor → QueuedInterceptor 리팩토링

• 파일: lib/core/network/auth_interceptor.dart (+38 / -115)
• 변경 내용:
  • 기존 Interceptor + 수동 lock(_isRefreshing) + _pendingRequests 큐 → QueuedInterceptor 패턴으로 단순화
  • 재시도 요청을 _plainDio.fetch() 로 수행 (큐 교착 방지)
  • _isRetry extra 플래그로 무한 재시도 루프 차단
  • 401 시 백엔드 RFC 7807 detail 메시지를 강제 로그아웃 콜백에 전달
• 이유: QueuedInterceptor 가 async onRequest 작업이 끝날 때까지 후속 요청을 자동 큐잉 → 동시 401 처리가 자연스러워짐. 일반 Interceptor 의 async void 문제(토큰 주입 전 요청 출발)도 제거

Dio Client 에 강제 로그아웃 콜백 IoC

• 파일: lib/core/network/dio_client.dart (+ .g.dart 신규)
• 변경 내용:
  • dioProvider 를 @Riverpod(keepAlive: true) 로 도입
  • forceLogoutCallbackNotifierProvider 추가 — auth 모듈이 콜백 등록/해제
  • forceLogoutMessageProvider 추가 — 로그인 화면이 1회 소비할 에러 메시지
  • typedef ForceLogoutFn = Future<void> Function({String? message})
• 이유: core 모듈이 auth feature 에 의존하지 않도록 의존성 역전. 콜백은 auth 모듈에서 등록, core 는 호출만 수행

Auth Repository 실제 백엔드 연동

• 파일: lib/features/auth/data/repositories/auth_repository_impl.dart (+55 / -98)
• 변경 내용:
  • Firebase-only 임시 모드 제거 (TODO 블록 + 죽은 import 정리)
  • Firebase 소셜 로그인 → idToken 획득 → /api/auth/login 호출 → JWT + memberId + isNewMember 저장 흐름 구현
  • provider: 'GOOGLE' → socialType: 'GOOGLE' 인자 통일
• 이유: 백엔드 스펙이 확정되어 실제 연동 활성화 가능. 기존 Firebase-only 분기는 더 이상 필요 없음

AuthProvider 정리 및 강제 로그아웃 콜백 등록

• 파일: lib/features/auth/presentation/providers/auth_provider.dart
• 변경 내용:
  • secureTokenStorageProvider / dioProvider 정의를 core 모듈로 이전 (중복 제거)
  • AuthNotifier.build() 진입 시 forceLogoutCallbackNotifierProvider.register(...) 호출
  • 콜백 본문: Firebase signOut → 토큰 삭제 → forceLogoutMessageProvider 에 백엔드 메시지 저장 → AuthNotifier.forceLogout() 으로 라우터 리다이렉트 트리거
  • kGuestMemberId 상수 도입 (게스트 모드 sentinel)
• 이유: feature 가 core 인프라에 콜백을 주입하는 IoC 완성. 재발급 실패 시 사용자에게 백엔드 에러 메시지를 스낵바로 표시 가능

AuthCancelledException 추가

• 파일: lib/core/errors/app_exception.dart
• 변경 내용: AuthException 하위로 AuthCancelledException 추가
• 이유: 사용자가 소셜 로그인 다이얼로그를 취소한 경우를 비-에러로 구분 처리

앱 시작 시 Keychain 잔존 토큰 정리

• 파일: lib/main.dart (+10)
• 변경 내용: Firebase 초기화 후 SecureTokenStorage().clearTokensIfReinstalled() 호출. try/catch 로 감싸 실패해도 앱 시작은 진행
• 이유: iOS 재설치 시 만료된 Refresh Token 으로 인한 401 → 강제 로그아웃 루프를 방지

🔧 주요 변경사항 상세

QueuedInterceptor 동작 흐름

[보호 API] → onRequest: Bearer Token 주입 → 요청 전송
   └ 401 응답
       └ onError: refreshToken 으로 /api/auth/reissue 호출
           ├ 성공 → 새 토큰 저장 → _plainDio.fetch(원 요청, _isRetry=true) → resolve
           ├ 401 → handleForceLogout(detail) → next(err)
           └ 기타 실패 → handleForceLogout() → next(err)

특이사항:

• _plainDio 는 인터셉터가 없는 별도 Dio. reissue 호출 시 인터셉터 재진입을 막아 이중 강제 로그아웃 방지
• _isRetry extra 플래그가 set 된 요청은 401 이어도 재발급 시도하지 않음 (루프 차단)
• _publicPaths (login / reissue / checkNickname) 는 토큰 주입 자체를 건너뜀

의존성 역전 구조

core/network/dio_client.dart
  ├─ dioProvider                          (core 정의)
  ├─ forceLogoutCallbackNotifierProvider  (core 정의, 빈 콜백)
  └─ forceLogoutMessageProvider           (core 정의)
              ▲ register / consume
              │
features/auth/presentation/providers/auth_provider.dart
  └─ AuthNotifier.build()
      → forceLogoutCallbackNotifierProvider.register(...)

특이사항:

• core 가 auth 를 import 하지 않음. auth 가 core 의 NotifierProvider 에 콜백을 주입
• forceLogoutMessageProvider 는 LoginScreen 에서 1회 소비(consume) 후 null 로 초기화

📦 의존성 변경

없음 — 기존 패키지(dio, flutter_riverpod, riverpod_annotation, flutter_secure_storage, shared_preferences) 만 사용

🧪 테스트 및 검증

• flutter analyze 통과 확인 필요
• 시나리오:
  • 신규 설치 후 Google / Apple 로그인 → JWT 저장 및 라우팅
  • Access Token 만료 상태에서 보호 API 호출 → 자동 reissue 후 응답 수신
  • Refresh Token 만료 상태에서 보호 API 호출 → 강제 로그아웃 + 백엔드 detail 메시지 스낵바
  • 동시 다발 401 → reissue 단 1회만 발생 (네트워크 로그 확인)
  • iOS 앱 삭제 후 재설치 → 잔존 토큰 자동 정리 → 로그인 화면 진입

📌 참고사항

• 게스트 모드 식별 sentinel kGuestMemberId = -1. 실제 회원 식별이 필요한 곳에서는 AuthResultEntity.isGuest 플래그를 먼저 확인할 것
• forceLogoutMessageProvider 는 LoginScreen 진입 시 read → 스낵바 → null 로 reset 패턴으로 사용
• 이전 보고서(20260504_#72_Auth_인프라_셋업_Firebase_JWT_자동_재발급.md)는 설계/구현 단계 문서. 본 보고서는 최종 커밋 기준
• 커밋 분리:
  • 71694d4 docs : 백엔드 API 스펙 갱신 #72
  • a7778e9 feat : Auth 인프라 셋업 - JWT 자동 주입 및 토큰 자동 재발급 #72