docs: update authentication documentation to reflect current implementation

Author: gracefullight

docs/AUTH.ko.md

@@ -31,24 +31,28 @@ sequenceDiagram
 ### 1. 백엔드 (FastAPI - `apps/api/`)
 
 **필수 파일:**
+
 - `src/lib/auth.py` - JWE 토큰 생성/검증, OAuth 검증
 - `src/auth/router.py` - 인증 endpoint
 - `src/users/model.py` - User DB 모델
 - `src/lib/dependencies.py` - 인증용 dependency injection
 
 **핵심 함수:**
+
 - `create_access_token(user_id)` - 만료 1시간의 JWE access token 생성
 - `create_refresh_token(user_id)` - 만료 7일의 JWE refresh token 생성
 - `decode_token(token)` - JWE 토큰 검증 및 payload 추출
 - `verify_oauth_token(provider, token)` - OAuth 토큰 재검증 (Google/GitHub/Facebook)
 - `get_current_user(request)` - Authorization header에서 사용자 추출
 
 **Endpoints:**
+
 - `POST /api/auth/login` - OAuth 로그인
 - `POST /api/auth/refresh` - 토큰 갱신
 - `POST /api/auth/logout` - 로그아웃
 
 **보안:**
+
 - JWE 암호화 (A256GCM)
 - Access Token: 만료 1시간
 - Refresh Token: 만료 7일
@@ -57,11 +61,14 @@ sequenceDiagram
 ### 2. 프론트엔드 (Next.js - `apps/web/`)
 
 **필수 파일:**
+
 - `src/lib/auth.ts` - Better Auth 서버 설정 (OAuth providers)
-- `src/lib/auth-client.ts` - API client (Orval 자동 생성, 토큰 관리)
+- `src/lib/auth-client.ts` - Better Auth 클라이언트 및 토큰 교환 로직
+- `src/lib/api-client.ts` - HTTP 클라이언트 및 토큰 관리 (interceptors)
 - `src/app/api/auth/[...all]/route.ts` - Better Auth route handler
 
 **핵심 동작/함수:**
+
 - Better Auth OAuth 로그인 (signIn.social)
 - OAuth → 백엔드 JWT 교환 (자동)
 - Authorization header 자동 주입
@@ -70,20 +77,23 @@ sequenceDiagram
 - 로그아웃 시 토큰 정리
 
 **보안:**
+
 - localStorage 저장 (prefix: `fullstack_`)
 - JWE 토큰 (백엔드 발급)
 - Authorization header 자동 설정
 
 ## 토큰 관리
 
 ### Access Token
+
 - **형식:** JWE (JSON Web Encryption)
 - **알고리즘:** A256GCM (AES-256-GCM)
 - **만료:** 1시간
 - **저장 위치:** `localStorage.fullstack_access_token`
 - **사용:** API 요청 시 `Authorization: Bearer {token}` header
 
 ### Refresh Token
+
 - **형식:** JWE
 - **알고리즘:** A256GCM
 - **만료:** 7일
@@ -171,17 +181,20 @@ Backend: Logout processing (client token invalidation if needed)
 ## 보안 기능
 
 ### 1. JWE 암호화
+
 - **완전 암호화:** payload 전체를 암호화
 - **알고리즘:** A256GCM (AES-256-GCM)
 - **장점:** (일반적인 JWT(JWS)와 달리) payload가 노출되지 않음
 - **Authentication Tag (authTag):** 무결성(Integrity) 보장 및 위변조 탐지
 
 ### 2. Stateless 특성
+
 - **서버 세션 없음:** 세션 상태를 서버에 저장할 필요 없음
 - **확장 용이:** 로드 밸런싱이 쉬움
 - **스케일 아웃:** 서버 증설이 쉬움
 
 ### 3. 토큰 만료 전략
+
 - **Access Token:** 짧은 만료(1시간) - 보안 최적화
 - **Refresh Token:** 긴 만료(7일) - 사용자 편의성
 - **Auto Refresh:** 만료 시 자동 갱신
@@ -215,14 +228,6 @@ DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/app
 
 # Better Auth (OAuth only)
 BETTER_AUTH_URL=http://localhost:3000
-
-# OAuth Providers (optional)
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
-FACEBOOK_CLIENT_ID=
-FACEBOOK_CLIENT_SECRET=
 ```
 
 ### 프론트엔드 (apps/web/.env)
@@ -247,9 +252,11 @@ FACEBOOK_CLIENT_SECRET=
 ## API Endpoints
 
 ### POST /api/auth/login
+
 **목적:** OAuth token을 백엔드 JWT로 교환
 
 **Request Body:**
+
 ```json
 {
   "provider": "google" | "github" | "facebook",
@@ -260,6 +267,7 @@ FACEBOOK_CLIENT_SECRET=
 ```
 
 **Response:**
+
 ```json
 {
   "access_token": "<JWE encrypted access token>",
@@ -269,16 +277,19 @@ FACEBOOK_CLIENT_SECRET=
 ```
 
 ### POST /api/auth/refresh
+
 **목적:** refresh token으로 새로운 access token 발급
 
 **Request Body:**
+
 ```json
 {
   "refresh_token": "<JWE encrypted refresh token>"
 }
 ```
 
 **Response:**
+
 ```json
 {
   "access_token": "<JWE encrypted new access token>",
@@ -288,27 +299,36 @@ FACEBOOK_CLIENT_SECRET=
 ```
 
 ### POST /api/auth/logout
+
 **목적:** 클라이언트 측 토큰 정리
 
 **Response:** 204 No Content
 
-## Orval 자동 생성 API Client
+## 클라이언트 토큰 관리
 
 ### auth.ts
+
 Better Auth 서버 설정을 담당하는 파일입니다.
 
 ### auth-client.ts
-FastAPI schema로부터 Orval이 자동 생성한 API client입니다.
+
+Better Auth 클라이언트 초기화 및 OAuth 토큰을 백엔드 JWE 토큰으로 교환하는 로직을 담당합니다.
+
+### api-client.ts
+
+토큰 자동 주입 및 갱신을 위한 interceptor가 설정된 수동 Axios 인스턴스입니다.
 
 **핵심 함수:**
+
 - `exchangeOAuthForBackendJwt()` - OAuth → 백엔드 JWT 자동 교환
 - `setAccessToken()` - access token 저장
 - `setRefreshToken()` - refresh token 저장
 - `clearTokens()` - 전체 토큰 정리
 - `hasBackendAccessToken()` - 백엔드 토큰 존재 여부 확인
 
 **자동 기능:**
-- Authorization header 자동 주입
+
+- Authorization header 자동 주입 (`apiClient` interceptor)
 - 401 에러 발생 시 자동 토큰 갱신
 - 재시도 큐 관리
 - In-memory 토큰 저장 (Map + localStorage)
@@ -326,18 +346,22 @@ FastAPI schema로부터 Orval이 자동 생성한 API client입니다.
 ## 주요 장점
 
 ### 1. 성능 개선
+
 - Better Auth 서버 호출 감소 (~50-100ms 절감)
 - 백엔드 부하 감소
 
 ### 2. 확장성
+
 - 서버 상태가 없어서 손쉬운 스케일링
 - 로드 밸런싱 용이
 
 ### 3. 모바일 친화적
+
 - Authorization header 방식은 모바일에 최적
 - cookie 기반 인증보다 단순
 
 ### 4. 보안 강화
+
 - JWE 암호화로 데이터 노출 방지
 - 짧은 access token 만료 시간