KR Kakao 인증 요구사항 명세서

1. 기능 요구사항

AUTH-KR-FR-001: 시스템은 Kakao OAuth 2.0 Authorization Code Grant를 사용해야 한다.
AUTH-KR-FR-002: InitiateKakaoAuthCommand 실행 시 state, nonce, requestedScopes를 생성하고 Redis(기본 TTL 10분)에 저장해야 한다.
AUTH-KR-FR-003: CompleteKakaoAuthCommand는 Kakao authorization code를 교환하여 access/refresh 토큰을 수신해야 한다.
AUTH-KR-FR-004: authorization code 교환 실패 시 도메인 예외(KakaoAuthorizationCodeExpiredError, KakaoProviderUnavailableError 등)를 발생시켜야 한다.

AUTH-KR-FR-005: Kakao 사용자 ID는 ExternalIdentityLink Aggregate를 통해 내부 사용자와 연결되어야 한다.
AUTH-KR-FR-006: 신규 사용자 연결 시 UserProvisionRequiredEvent를 발행해 프로비저닝 워크플로를 트리거해야 한다.
AUTH-KR-FR-013: 신규 사용자 분기에서는 검증된 appToken에 프로비저닝 상태를 매핑하고, 온보딩 완료 시점까지 JWT 세션을 발급하지 않아야 한다.
AUTH-KR-FR-007: 동일 Kakao 사용자 ID가 다른 계정에 연결되려 하면 KakaoIdentityAlreadyLinkedError를 반환해야 한다.
AUTH-KR-FR-008: 연결 해제 요청 시 ExternalAuthUnlinkedEvent를 발행하고 토큰을 폐기해야 한다.

AUTH-KR-FR-009: JWT 액세스/리프레시 토큰 발급은 공통 Auth Core의 IssueSessionService(JWT 발급기)를 통해 수행해야 한다.
AUTH-KR-FR-010: JWT 만료 시간은 TimeMachine 기준으로 계산되어야 한다.
AUTH-KR-FR-011: 로그인 성공, 신규 연결, 갱신 실패 등 주요 이벤트는 Event Bus로 발행되어야 한다.
AUTH-KR-FR-012: Redis idempotency 키를 사용해 동일 콜백이 재처리되지 않도록 해야 한다.

AUTH-KR-NFR-001 (Availability): Kakao API 장애 시 Circuit Breaker와 지수 백오프 전략을 적용하고, 3회 연속 실패 시 사용자에게 지역화된 오류를 반환해야 한다.
AUTH-KR-NFR-002 (Performance): 인가 요청~콜백 왕복 지연 시간은 95% 구간에서 4초 이하를 유지해야 한다. Redis 접근은 한 플로우당 2회 이하로 제한한다.
AUTH-KR-NFR-003 (Observability): 모든 명령/이벤트/외부 API 호출에는 Trace ID를 부여하고, 실패 로그에는 AUTH_KAKAO_* 태그를 포함해야 한다.
AUTH-KR-NFR-004 (Configurability): 모든 설정은 auth.oauth.kakao.* 네임스페이스로 로드되어야 하며, feature flag로 런타임 토글이 가능해야 한다.

AUTH-KR-CS-001: Kakao 사용자 ID는 암호화된 KakaoUserId Value Object로 저장하고, 30일 이상 미사용 시 비식별화 프로세스를 실행해야 한다.
AUTH-KR-CS-002: state 불일치 또는 만료 시 인증 흐름을 즉시 중단하고 KakaoStateMismatchError를 발생시켜야 한다.
AUTH-KR-CS-003: OAuth 토큰(JWT 포함)은 TimeMachine 기준 만료 시간을 저장하며, 만료 5분 전 한 번만 갱신을 시도해야 한다.
AUTH-KR-CS-004: 모든 감사 로그에는 TimeMachine에서 제공하는 권한 있는 시각이 포함되어야 한다.
AUTH-KR-CS-005: Kakao 앱 키는 플랫폼별로 분리되어야 한다. 백엔드 REST OAuth 호출은 REST API 키만 사용하고, 모바일(Android/iOS) “카카오로 로그인하기” 버튼은 네이티브 앱 키만 사용해야 한다.

AC ID	설명	검증 방법
AC-KR-001	인가 URL 요청 시 state/nonce가 생성되고 Redis에 TTL과 함께 저장된다.	`ExternalAuthService` 단위 테스트(Redis 목)
AC-KR-002	authorization code 교환 실패가 도메인 예외로 변환된다.	Kakao HTTP 클라이언트 목 테스트
AC-KR-003	신규 사용자 연결 시 `UserProvisionRequiredEvent`가 발행된다.	이벤트 핸들러 단위 테스트
AC-KR-004	로그인 성공 시 JWT 만료 시간이 TimeMachine 기준으로 기록된다.	TimeMachine 스텁 통합 테스트
AC-KR-005	동일 콜백이 중복 도착해도 idempotency 키로 재처리가 차단된다.	Redis 키 재사용 통합 테스트
AC-KR-006	REST API 키와 네이티브 앱 키가 각각 서버 시크릿과 모바일 빌드 설정으로 분리 관리된다.	환경 설정 검증(Cloud Run Secret 및 모바일 빌드 설정 점검)
AC-KR-007	`appToken` 기반 프로비저닝 pending 상태는 TTL 내 1회만 소비되고, 제출 후 재사용되지 않는다.	`KakaoIdentityLinkService` 단위 테스트

libs/feature/auth-kr 단위 테스트에서 Authorization Flow, 토큰 갱신, 실패 경로를 목킹한다.
yarn test:features 통합 테스트에 Kakao happy path, 중복 콜백, feature flag 비활성화 시나리오를 포함한다.
apps/dta-wir-api-universal e2e 테스트에서 KR 지역 설정 기반 엔드포인트(/auth/oauth/kakao, /callback, /unlink)를 검증한다.
TimeMachine과 Redis idempotency 동작 검증을 위한 스텁/목 전략을 문서화한다.