공통 인증 도메인 구조 및 Kakao 로그인 확장 설계

문서 목적

• DE 지역 전용으로 묶여 있던 인증 도메인을 공통 자산으로 재편하고, KR 전용 Kakao 로그인 기능을 안전하게 통합하기 위한 설계 의도를 명시한다.
• NX 모듈 스캐폴딩, 의존성 제약, 문서 구조 재정렬 등 후속 구현이 따라야 할 기준점을 제공한다.

현재 문제 인식

• apps/dta-wi-doc/docs/domains/common/core-domains/auth 경로에만 핵심 인증 문서가 존재해 KR 서비스가 동일한 도메인 규칙을 공유하기 어렵다.
• 인증 로직이 단일 지역 내에 머물러 있어 국가별 확장(예: Kakao OAuth)이 기존 DE 빌드에 영향을 줄 수 있는 구조다.
• 공급자 추가 시 서비스 레이어가 직접 외부 클라이언트와 얽혀 테스트 격리가 어려워지고, TimeMachine 기반 시간 제어 규칙을 일관되게 적용하기 어렵다.

설계 원칙

• 공통 코어와 지역 확장 분리: 토큰 발급, 세션 유지, TimeMachine 연동은 공통 계층에서 처리하고 OAuth 공급자별 흐름은 지역화된 모듈에서 캡슐화한다.
• DI 기반 공급자 등록: AuthProvider 계약을 통해 Nest DI 토큰으로 공급자를 주입하고, 국가 코드 · 플래그 기반으로 런타임 전략을 선택한다.
• 의존성 경계 준수: libs/feature/auth/providers-kr는 KR 앱에서만 참조되도록 NX tag constraint를 설정해 타 지역 빌드에 누락된 구현이 포함되지 않도록 한다.
• 문서 일관성 확보: 공통 도메인 문서는 domains/common/core-domains/auth에 모으고, 지역 확장은 하위 경로(kr/, eu/)로 나눠 한글 기준 안내를 제공한다.

스캐폴딩 전략

• 기존 라이브러리 재사용
  • libs/feature/auth: 공통 인증 서비스와 CQRS 핸들러가 이미 존재하므로, AuthProviderRegistry 등 핵심 컴포넌트를 여기로 정리한다.
  • libs/shared/contracts-auth: DTO, 이벤트 payload, 공급자 계약 정의를 유지하고 Kakao 전용 계약이 필요하면 동일한 패턴으로 확장한다.
  • (libs/feature/auth-wir는 레거시 시스템과의 임시 통합을 위해 유지되는 코드이므로 이번 구조 재편 범위에서 제외한다.)
• 신규 라이브러리 생성(필요 시)
  • 공통 인증 인프라: nx g @nx/nest:lib --name=core-auth --directory=libs/core/auth --importPath=@core/auth --tags=scope:core,domain:auth
    • TimeMachine 어댑터, Crypto/Hash 유틸, 외부 API 클라이언트 초기화를 이곳으로 이동한다.
  • KR 전용 공급자: nx g @nx/nest:lib --name=feature-auth-kr --directory=libs/feature/auth-kr --importPath=@feature/auth-kr --tags=scope:feature,domain:auth,region:kr
    • Kakao OAuth 흐름, API 어댑터, 예외 클래스를 포함한다.
  • EU 공급자 리팩터링(선택): nx g @nx/nest:lib --name=feature-auth-eu --directory=libs/feature/auth-eu --importPath=@feature/auth-eu --tags=scope:feature,domain:auth,region:eu
    • 기존 DE 구현을 분리할 때 사용한다. 현재 구조가 유지 가능하면 기존 feature-auth 내에서 provider를 모듈화한다.
  • HTTP 어댑터/유틸(선택)
  • 추가 인프라가 필요하면 nx g @nx/js:lib --name=core-http-kakao --directory=libs/core/http-kakao --importPath=@core/http-kakao --tags=scope:core,type:http 로 생성해 Kakao 전용 REST 클라이언트를 캡슐화한다.

공급자 레지스트리 & 기본 구현

• libs/core/auth는 AuthProviderRegistry와 AuthProvider 인터페이스를 제공해 지역별 공급자를 동적으로 등록한다. 공통 도메인 모듈(FeatureAuthModule)은 region:common 태그를 사용해 어느 지역에서도 의존할 수 있도록 했다.
• libs/feature/auth는 공급자-불문 공통 로직과 ExternalAuthService를 제공해 인가 URL 생성 및 코드 교환을 애플리케이션 계층에 노출한다.
• libs/feature/auth-kr은 KakaoAuthProvider를 제공하며, core-http-kakao의 KakaoOAuthHttpClient를 통해 Kakao API 연동과 idempotency 검증을 담당한다.
• libs/feature/auth-eu는 비밀번호 기반 인증을 담당하는 PasswordAuthProvider와 de/EU 전용 정책을 나타내는 EuAuthProvider를 등록해 기존 EU 흐름을 모듈 단위로 구성한다.
• 신규 공급자 모듈은 OnModuleInit에서 AuthProviderRegistry에 자신을 등록해 애플리케이션 초기화 시 자동으로 탐색된다.

Kakao OAuth 설정 요약

• 환경 설정은 auth.oauth.kakao 네임스페이스에서 관리하며, 최소 clientId, redirectUri를 지정해야 한다.
• 선택적으로 clientSecret, scopes, authorizationUrl, prompt, responseType, additionalParams를 정의해 Kakao Developers 콘솔 설정과 일치시킨다.
• FeatureAuthKrModule는 CoreConfigModule, CoreLoggingModule, CoreHttpKakaoModule을 임포트해 공급자 등록과 HTTP 호출, 로깅을 초기화한다.

Kakao 로그인 공급자 설계

• AuthProvider 인터페이스에 initiate, exchangeCode, linkUser, issueTokens 같은 공통 메서드를 선언해 Kakao 구현이 DE 공급자와 동일한 계약을 따른다.
• libs/feature/auth-kr은 Kakao SDK/REST 클라이언트를 어댑터로 감싸고, TimeMachineService를 주입받아 토큰 만료 시간 계산을 결정적으로 만든다.
• Access Token 발급 시 Redis 기반 idempotency 키를 활용해 카카오 사용자 연결 이벤트의 중복 처리를 예방한다.
• 실패 시 도메인 전용 예외(KakaoAuthProviderException)를 던져 상위 레이어가 locale에 따라 메시지를 매핑할 수 있게 한다.

국가별 주입 흐름

1. libs/feature/auth의 AuthModule에서 AuthProviderRegistry를 AuthProvider[] 배열로 구성한다.
2. DE 앱(apps/dta-wide-api, apps/dta-wir-api-universal의 DE 설정)은 EU 공급자 모듈만 임포트한다.
3. KR 앱 구성에서는 providers-kr 모듈을 추가하고, feature flag 또는 countryCode로 Kakao 전략을 선택하도록 팩토리를 설정한다.
4. 테스트에서는 공급자 모듈을 목(fakes)으로 대체하고, TimeMachine 스텁을 이용해 토큰 만료 및 이벤트 발행 타이밍을 검증한다.

문서 구조 재배치

• 공통 개요: apps/dta-wi-doc/docs/domains/common/core-domains/auth/index.md
• 지역 확장: apps/dta-wi-doc/docs/domains/common/core-domains/auth/index.md, apps/dta-wi-doc/docs/domains/kr/core-domains/auth/overview.md
• 기존 DE 문서의 핵심 내용(도메인 모델, 요구 사항 등)은 공통 섹션으로 승격하고, DE 특화 내용은 eu/ 경로로 이동한다.
• Kakao 문서에는 OAuth 플로우, 정책 상 제약, TimeMachine 조작 포인트, Redis 중복 제거 시나리오를 명확히 기록한다.

NX 태그 제약 방안

• nx.json의 depConstraints에 다음 규칙을 추가한다.
  • region:kr 태그를 가진 라이브러리는 region:kr, region:common, scope:shared, scope:core 태그만 참조한다.
  • 공통 feature-auth는 region:common 태그를 사용해 지역별 모듈이 안전하게 의존하도록 하고, 공급자는 DI로 주입한다.
• 이를 통해 DE 빌드 파이프라인에서 Kakao가 실수로 번들되지 않도록 보호하고, CI에서 의존성 위반을 즉시 감지한다.

후속 작업 제안

• 공통 인증 구조로의 전환과 Kakao 공급자 구현을 두 단계의 백로그 태스크로 등록해 리뷰를 분리한다.
• 스캐폴딩 후 libs/feature/auth에 대한 단위 테스트와 KR 통합 테스트를 추가하고, yarn test:features 파이프라인에 Kakao 플로우를 포함한다.
• 문서 재배치가 완료되면 DE 문서 트리에서 중복 항목을 제거하고, 링크 업데이트를 검증한다.