@thinkingcat/auth-utils 1.0.14 → 1.0.17

package/README.md

@@ -6,6 +6,7 @@ ThinkingCat SSO 서비스를 위한 인증 유틸리티 패키지입니다. JWT
 
 - [📦 설치 (Installation)](#-설치-installation)
 - [📋 요구사항 (Requirements)](#-요구사항-requirements)
+- [🐛 디버깅 (Debugging)](#-디버깅-debugging)
 - [⚙️ Next.js 설정 (Next.js Configuration)](#️-nextjs-설정-nextjs-configuration)
 - [🚀 빠른 시작 (Quick Start)](#-빠른-시작-quick-start)
 - [📚 주요 기능 (Features)](#-주요-기능-features)
@@ -47,6 +48,36 @@ pnpm add @thinkingcat/auth-utils
 - **Node.js**: >= 18.0.0
 - **TypeScript**: 권장 (타입 지원)
 
+## 🐛 디버깅 (Debugging)
+
+이 패키지는 조건부 로깅 시스템을 사용합니다. 기본적으로 프로덕션 환경에서는 로그가 출력되지 않으며, 개발 환경에서만 로그가 출력됩니다.
+
+### 디버그 로그 활성화
+
+환경 변수 `AUTH_UTILS_DEBUG=true`를 설정하여 모든 환경에서 디버그 로그를 활성화할 수 있습니다:
+
+```bash
+# .env.local 또는 환경 변수 설정
+AUTH_UTILS_DEBUG=true
+```
+
+### 로그 출력 조건
+
+- `NODE_ENV === 'development'`: 자동으로 로그 출력
+- `AUTH_UTILS_DEBUG === 'true'`: 모든 환경에서 로그 출력
+- 그 외: 로그 출력 안 함 (성능 최적화)
+
+### 디버그 로그 예시
+
+```typescript
+// 개발 환경 또는 AUTH_UTILS_DEBUG=true일 때만 출력됨
+[handleMiddleware] Processing: /admin
+[verifyAndRefreshToken] Checking refresh: { hasRefreshToken: true, forceRefresh: false }
+[createAuthResponse] JWT created: { hasId: true, hasEmail: true, hasRole: true }
+```
+
+이 기능으로 프로덕션 환경에서 불필요한 로그 출력을 방지하여 성능을 최적화합니다.
+
 ## ⚙️ Next.js 설정 (Next.js Configuration)
 
 ### npm에 배포된 패키지를 사용하는 경우 (권장)
@@ -60,7 +91,7 @@ npm install @thinkingcat/auth-utils
 ```json
 {
   "dependencies": {
-    "@thinkingcat/auth-utils": "^1.0.12"
+    "@thinkingcat/auth-utils": "^1.0.17"
   }
 }
 ```
@@ -140,6 +171,15 @@ import {
   handleMiddleware,
   verifyAndRefreshTokenWithNextAuth,
 
+  // NextAuth 설정 및 콜백
+  createNextAuthBaseConfig,
+  createNextAuthCookies,
+  handleJWTCallback,
+  createInitialJWTToken,
+  createEmptySession,
+  mapTokenToSession,
+  getJWTFromCustomTokenCookie,
+
   // 라이센스
   checkLicenseKey,
 
@@ -249,7 +289,7 @@ const role = extractRoleFromPayload(payload, "myservice", "ADMIN");
 // 'ADMIN', 'TEACHER', 'STUDENT' 등
 ```
 
-#### `createNextAuthJWT(payload: JWTPayload, serviceId: string, includeAcademies?: boolean)`
+#### `createNextAuthJWT(payload: JWTPayload, serviceId: string)`
 
 NextAuth와 호환되는 JWT 객체를 생성합니다.
 
@@ -257,7 +297,6 @@ NextAuth와 호환되는 JWT 객체를 생성합니다.
 
 - `payload`: 원본 JWT payload (JWTPayload 타입)
 - `serviceId`: 서비스 ID (필수)
-- `includeAcademies`: academies 정보 포함 여부 (기본값: false)
 
 **반환값:**
 
@@ -266,8 +305,7 @@ NextAuth와 호환되는 JWT 객체를 생성합니다.
 **사용 예시:**
 
 ```typescript
-const jwt = createNextAuthJWT(payload, "myservice", true);
-// academies 정보가 포함된 JWT 객체
+const jwt = createNextAuthJWT(payload, "myservice");
 ```
 
 #### `encodeNextAuthToken(jwt: JWT, secret: string, maxAge?: number)`
@@ -522,6 +560,159 @@ SSO 서버에서 토큰을 검증합니다.
 
 - `{ isValid: boolean; redirectUrl?: string }`
 
+### NextAuth 설정 및 콜백
+
+#### `createNextAuthBaseConfig(options)`
+
+NextAuth 기본 설정을 생성합니다.
+
+**파라미터:**
+
+- `options.secret`: NextAuth secret (필수)
+- `options.isProduction`: 프로덕션 환경 여부 (기본값: false)
+- `options.cookieDomain`: 쿠키 도메인 (선택)
+- `options.signInPath`: 로그인 페이지 경로 (기본값: '/login')
+- `options.errorPath`: 에러 페이지 경로 (기본값: '/login')
+- `options.nextAuthUrl`: NextAuth URL (선택)
+- `options.sessionMaxAge`: 세션 최대 유지 시간 (초, 기본값: 30일)
+- `options.jwtMaxAge`: JWT 최대 유지 시간 (초, 기본값: 30일)
+
+**반환값:**
+
+- NextAuth 기본 설정 객체
+
+**사용 예시:**
+
+```typescript
+import { createNextAuthBaseConfig } from "@thinkingcat/auth-utils";
+
+const baseConfig = createNextAuthBaseConfig({
+  secret: process.env.NEXTAUTH_SECRET!,
+  isProduction: process.env.NODE_ENV === "production",
+  cookieDomain: process.env.COOKIE_DOMAIN,
+  signInPath: "/login",
+  errorPath: "/login",
+  nextAuthUrl: process.env.NEXTAUTH_URL,
+});
+
+export const authOptions: NextAuthOptions = {
+  ...baseConfig,
+  // ... 기타 설정
+};
+```
+
+#### `createNextAuthCookies(options)`
+
+NextAuth 쿠키 설정을 생성합니다.
+
+**파라미터:**
+
+- `options.isProduction`: 프로덕션 환경 여부 (기본값: false)
+- `options.cookieDomain`: 쿠키 도메인 (선택)
+
+**반환값:**
+
+- NextAuth 쿠키 설정 객체
+
+#### `handleJWTCallback(token, user?, account?, options?)`
+
+JWT 콜백을 위한 통합 헬퍼 함수입니다. 초기 로그인, 토큰 갱신, 커스텀 토큰 읽기를 모두 처리합니다.
+
+**파라미터:**
+
+- `token`: 기존 JWT 토큰
+- `user`: 사용자 정보 (초기 로그인 시)
+- `account`: 계정 정보 (초기 로그인 시)
+- `options.secret`: NextAuth secret (커스텀 토큰 읽기용)
+- `options.licenseKey`: 라이센스 키 (커스텀 토큰 읽기용)
+- `options.serviceId`: 서비스 ID (커스텀 토큰 읽기용)
+- `options.cookieName`: 커스텀 토큰 쿠키 이름 (기본값: '{serviceId}\_access_token')
+- `options.debug`: 디버깅 로그 출력 여부 (기본값: false)
+
+**반환값:**
+
+- 업데이트된 JWT 토큰
+
+**사용 예시:**
+
+```typescript
+import { handleJWTCallback } from "@thinkingcat/auth-utils";
+
+async jwt({ token, user, account }) {
+  return handleJWTCallback(
+    token,
+    user ? {
+      id: user.id,
+      email: user.email,
+      role: user.role,
+      // ... 기타 사용자 정보
+    } : null,
+    account,
+    {
+      secret: process.env.NEXTAUTH_SECRET!,
+      licenseKey: process.env.LICENSE_KEY!,
+      serviceId: 'myservice',
+      cookieName: 'myservice_access_token',
+      debug: true,
+    }
+  );
+}
+```
+
+#### `createInitialJWTToken(token, user, account?)`
+
+JWT 콜백에서 초기 로그인 시 토큰 생성 헬퍼입니다.
+
+**파라미터:**
+
+- `token`: 기존 토큰
+- `user`: 사용자 정보
+- `account`: 계정 정보 (선택)
+
+**반환값:**
+
+- 업데이트된 JWT 토큰
+
+#### `createEmptySession(session)`
+
+Session 콜백에서 빈 세션 반환 헬퍼입니다.
+
+**파라미터:**
+
+- `session`: 기존 세션
+
+**반환값:**
+
+- 빈 세션 객체
+
+#### `mapTokenToSession(session, token)`
+
+Session 콜백에서 토큰 정보를 세션에 매핑하는 헬퍼입니다.
+
+**파라미터:**
+
+- `session`: 기존 세션
+- `token`: JWT 토큰
+
+**반환값:**
+
+- 업데이트된 세션
+
+#### `getJWTFromCustomTokenCookie(cookieName, secret, serviceId, licenseKey)`
+
+쿠키에서 커스텀 토큰을 읽어서 NextAuth JWT로 변환하는 헬퍼 함수입니다.
+
+**파라미터:**
+
+- `cookieName`: 쿠키 이름 (예: 'checkon_access_token')
+- `secret`: JWT 서명에 사용할 secret key
+- `serviceId`: 서비스 ID (필수)
+- `licenseKey`: 라이센스 키 (필수)
+
+**반환값:**
+
+- NextAuth JWT 객체 또는 null
+
 ### 미들웨어
 
 #### `createMiddlewareConfig(config: Partial<MiddlewareConfig> & { serviceId: string }, defaults?)`
@@ -1087,13 +1278,6 @@ interface JWTPayload {
   // 서비스 정보
   services?: ServiceInfo[];
 
-  // 학원 정보
-  academies?: Array<{
-    id: string;
-    name: string;
-    role: string;
-  }>;
-
   // 인증 상태
   phoneVerified?: boolean;
   emailVerified?: boolean;
@@ -1101,8 +1285,6 @@ interface JWTPayload {
 
   // 선택적 필드
   phone?: string;
-  academyId?: string;
-  academyName?: string;
   isPasswordReset?: boolean;
   decryptedEmail?: string;
   decryptedPhone?: string;
@@ -1308,10 +1490,32 @@ const response = await handleMiddleware(req, middlewareConfig, {
 ## 📦 패키지 정보
 
 - **패키지명**: `@thinkingcat/auth-utils`
-- **버전**: `1.0.12`
+- **버전**: `1.0.17`
 - **라이선스**: MIT
 - **저장소**: npm registry
 
+## 📝 변경 이력 (Changelog)
+
+### v1.0.17 (2024-11-15)
+
+**새로운 기능:**
+
+- 조건부 로깅 시스템 추가 (`debugLog`, `debugError`)
+- 환경 변수 `AUTH_UTILS_DEBUG` 지원
+- 프로덕션 환경에서 로그 출력 최적화
+
+**개선 사항:**
+
+- 코드 구조 개선 (15개 기능별 섹션으로 그룹화)
+- 중복 코드 제거 (`deleteNextAuthSessionCookie`, `clearAllAuthCookies` 헬퍼 추가)
+- 로그 메시지 간소화 및 가독성 향상
+- 불필요한 주석 제거
+
+**성능 최적화:**
+
+- 프로덕션 환경에서 로그 출력 비활성화로 성능 향상
+- 조건부 로깅으로 런타임 오버헤드 감소
+
 ## 🤝 기여 (Contributing)
 
 이슈나 개선 사항이 있으면 GitHub 이슈를 등록해주세요.

package/dist/index.d.ts

@@ -69,17 +69,10 @@ export interface JWTPayload {
     iat?: number;
     exp?: number;
     services?: ServiceInfo[];
-    academies?: Array<{
-        id: string;
-        name: string;
-        role: string;
-    }>;
     phoneVerified?: boolean;
     emailVerified?: boolean;
     smsVerified?: boolean;
     phone?: string;
-    academyId?: string;
-    academyName?: string;
     isPasswordReset?: boolean;
     decryptedEmail?: string;
     decryptedPhone?: string;
@@ -114,10 +107,9 @@ export declare function extractRoleFromPayload(payload: JWTPayload, serviceId: s
  * payload에서 NextAuth JWT 객체 생성
  * @param payload JWT payload
  * @param serviceId 서비스 ID (필수)
- * @param includeAcademies academies 정보 포함 여부
  * @returns NextAuth JWT 객체
  */
-export declare function createNextAuthJWT(payload: JWTPayload, serviceId: string, includeAcademies?: boolean): JWT;
+export declare function createNextAuthJWT(payload: JWTPayload, serviceId: string): JWT;
 /**
  * NextAuth JWT를 인코딩된 세션 토큰으로 변환
  * @param jwt NextAuth JWT 객체
@@ -232,6 +224,7 @@ export declare function verifyAndRefreshToken(req: NextRequest, secret: string,
     ssoBaseURL?: string;
     authServiceKey?: string;
     licenseKey: string;
+    forceRefresh?: boolean;
 }): Promise<{
     isValid: boolean;
     response?: NextResponse;
@@ -438,17 +431,44 @@ export declare function createEmptySession(session: Session): Session;
  * Session 콜백에서 토큰 정보를 세션에 매핑하는 헬퍼
  * @param session 기존 세션
  * @param token JWT 토큰
- * @param options 옵션
- * @param options.primaryAcademy 기본 학원 정보 (선택)
  * @returns 업데이트된 세션
  */
-export declare function mapTokenToSession(session: Session, token: JWT, options?: {
-    primaryAcademy?: {
-        id: string;
-        name: string;
-        role: string;
-    } | null;
-}): Session;
+export declare function mapTokenToSession(session: Session, token: JWT): Session;
+/**
+ * JWT 콜백을 위한 통합 헬퍼 함수
+ * 초기 로그인, 토큰 갱신, 커스텀 토큰 읽기를 모두 처리
+ * @param token 기존 JWT 토큰
+ * @param user 사용자 정보 (초기 로그인 시)
+ * @param account 계정 정보 (초기 로그인 시)
+ * @param options 옵션
+ * @param options.secret NextAuth secret (커스텀 토큰 읽기용)
+ * @param options.licenseKey 라이센스 키 (커스텀 토큰 읽기용)
+ * @param options.serviceId 서비스 ID (커스텀 토큰 읽기용)
+ * @param options.cookieName 커스텀 토큰 쿠키 이름 (기본값: '{serviceId}_access_token')
+ * @param options.debug 디버깅 로그 출력 여부 (기본값: false)
+ * @returns 업데이트된 JWT 토큰
+ */
+export declare function handleJWTCallback(token: JWT, user?: {
+    id: string;
+    email?: string | null;
+    emailHash?: string | null;
+    maskedEmail?: string | null;
+    phoneHash?: string | null;
+    maskedPhone?: string | null;
+    role?: string;
+    phone?: string | null;
+    decryptedEmail?: string | null;
+    decryptedPhone?: string | null;
+    refreshToken?: string | null;
+} | null, account?: {
+    serviceId?: string;
+} | null, options?: {
+    secret?: string;
+    licenseKey?: string;
+    serviceId?: string;
+    cookieName?: string;
+    debug?: boolean;
+}): Promise<JWT>;
 /**
  * 쿠키에서 커스텀 토큰을 읽어서 NextAuth JWT로 변환하는 헬퍼 함수
  * NextAuth JWT 콜백에서 사용
@@ -456,10 +476,9 @@ export declare function mapTokenToSession(session: Session, token: JWT, options?
  * @param secret JWT 서명에 사용할 secret key
  * @param serviceId 서비스 ID (필수)
  * @param licenseKey 라이센스 키 (필수)
- * @param includeAcademies academies 정보 포함 여부 (기본값: false)
  * @returns NextAuth JWT 객체 또는 null
  */
-export declare function getJWTFromCustomTokenCookie(cookieName: string, secret: string, serviceId: string, licenseKey: string, includeAcademies?: boolean): Promise<JWT | null>;
+export declare function getJWTFromCustomTokenCookie(cookieName: string, secret: string, serviceId: string, licenseKey: string): Promise<JWT | null>;
 export declare function checkLicenseKey(licenseKey: string): Promise<void>;
 export declare function checkRoleAccess(pathname: string, role: string, roleConfig: RoleAccessConfig): {
     allowed: boolean;

package/dist/index.js

@@ -54,6 +54,7 @@ exports.createNextAuthBaseConfig = createNextAuthBaseConfig;
 exports.createInitialJWTToken = createInitialJWTToken;
 exports.createEmptySession = createEmptySession;
 exports.mapTokenToSession = mapTokenToSession;
+exports.handleJWTCallback = handleJWTCallback;
 exports.getJWTFromCustomTokenCookie = getJWTFromCustomTokenCookie;
 exports.checkLicenseKey = checkLicenseKey;
 exports.checkRoleAccess = checkRoleAccess;
@@ -73,7 +74,25 @@ exports.handleMiddleware = handleMiddleware;
 const jwt_1 = require("next-auth/jwt");
 const jose_1 = require("jose");
 const server_1 = require("next/server");
-// Edge Runtime 호환을 위해 Web Crypto API 사용
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * 조건부 로깅 유틸리티 (환경 변수 AUTH_UTILS_DEBUG=true 시에만 로그 출력)
+ */
+function debugLog(context, ...args) {
+    if (process.env.AUTH_UTILS_DEBUG === 'true' || process.env.NODE_ENV === 'development') {
+        console.log(`[${context}]`, ...args);
+    }
+}
+function debugError(context, ...args) {
+    if (process.env.AUTH_UTILS_DEBUG === 'true' || process.env.NODE_ENV === 'development') {
+        console.error(`[${context}]`, ...args);
+    }
+}
+/**
+ * Edge Runtime 호환을 위해 Web Crypto API 사용
+ */
 async function createHashSHA256(data) {
     const encoder = new TextEncoder();
     const dataBuffer = encoder.encode(data);
@@ -81,6 +100,25 @@ async function createHashSHA256(data) {
     const hashArray = Array.from(new Uint8Array(hashBuffer));
     return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
 }
+/**
+ * NextAuth 세션 토큰 쿠키를 삭제하는 헬퍼 함수
+ */
+function deleteNextAuthSessionCookie(response, isProduction) {
+    const cookieName = isProduction
+        ? '__Secure-next-auth.session-token'
+        : 'next-auth.session-token';
+    response.cookies.delete(cookieName);
+}
+/**
+ * 모든 인증 관련 쿠키를 삭제하는 헬퍼 함수
+ */
+function clearAllAuthCookies(response, cookiePrefix, isProduction) {
+    clearAuthCookies(response, cookiePrefix);
+    deleteNextAuthSessionCookie(response, isProduction);
+}
+// ============================================================================
+// JWT CORE FUNCTIONS
+// ============================================================================
 /**
  * 토큰 검증 및 디코딩
  * @param accessToken JWT access token
@@ -116,22 +154,18 @@ function extractRoleFromPayload(payload, serviceId, defaultRole = 'ADMIN') {
  * payload에서 NextAuth JWT 객체 생성
  * @param payload JWT payload
  * @param serviceId 서비스 ID (필수)
- * @param includeAcademies academies 정보 포함 여부
  * @returns NextAuth JWT 객체
  */
-function createNextAuthJWT(payload, serviceId, includeAcademies = false) {
+function createNextAuthJWT(payload, serviceId) {
     const services = payload.services || [];
     const service = services.find((s) => s.serviceId === serviceId);
     const effectiveRole = service?.role || payload.role || 'ADMIN';
     const jwt = {
         id: (payload.id || payload.sub),
         email: payload.email,
-        name: payload.name,
+        name: (payload.name || payload.email || 'User'), // name이 없으면 email 또는 기본값 사용
         role: effectiveRole, // Role enum 타입 (string으로 캐스팅)
         services: payload.services,
-        academies: includeAcademies
-            ? payload.academies || []
-            : [],
         phoneVerified: payload.phoneVerified ?? false,
         emailVerified: payload.emailVerified ?? false,
         smsVerified: payload.smsVerified ?? false,
@@ -141,10 +175,6 @@ function createNextAuthJWT(payload, serviceId, includeAcademies = false) {
     // 선택적 필드들
     if (payload.phone)
         jwt.phone = payload.phone;
-    if (payload.academyId)
-        jwt.academyId = payload.academyId;
-    if (payload.academyName)
-        jwt.academyName = payload.academyName;
     if (payload.isPasswordReset)
         jwt.isPasswordReset = payload.isPasswordReset;
     if (payload.decryptedEmail)
@@ -177,11 +207,47 @@ function createNextAuthJWT(payload, serviceId, includeAcademies = false) {
  * @returns 인코딩된 세션 토큰
  */
 async function encodeNextAuthToken(jwt, secret, maxAge = 30 * 24 * 60 * 60) {
-    return await (0, jwt_1.encode)({
-        token: jwt,
-        secret: secret,
-        maxAge: maxAge,
-    });
+    try {
+        // next-auth/jwt의 encode 함수 사용 (Node.js 런타임에서만 작동)
+        return await (0, jwt_1.encode)({
+            token: jwt,
+            secret: secret,
+            maxAge: maxAge,
+        });
+    }
+    catch (error) {
+        // Edge Runtime에서 encode가 작동하지 않을 수 있으므로
+        // jose의 EncryptJWT를 사용하여 JWE 토큰 생성 (NextAuth가 기대하는 형식)
+        debugLog('encodeNextAuthToken', 'encode failed, using EncryptJWT fallback');
+        // NextAuth는 secret을 SHA-256 해시하여 32바이트 키로 사용
+        // jose의 EncryptJWT는 'dir' 알고리즘에서 Uint8Array 키를 직접 사용
+        const secretHash = await createHashSHA256(secret);
+        // SHA-256 해시는 64자 hex 문자열이므로, 32바이트로 변환
+        const keyBytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            keyBytes[i] = parseInt(secretHash.slice(i * 2, i * 2 + 2), 16);
+        }
+        const now = Math.floor(Date.now() / 1000);
+        // EncryptJWT를 사용하여 JWE 토큰 생성
+        // NextAuth는 'dir' 키 관리와 'A256GCM' 암호화를 사용
+        // 'dir' 알고리즘은 Uint8Array 키를 직접 사용
+        try {
+            const token = await new jose_1.EncryptJWT(jwt)
+                .setProtectedHeader({
+                alg: 'dir', // Direct key agreement
+                enc: 'A256GCM' // AES-256-GCM encryption
+            })
+                .setIssuedAt(now)
+                .setExpirationTime(now + maxAge)
+                .setJti(crypto.randomUUID())
+                .encrypt(keyBytes);
+            return token;
+        }
+        catch (encryptError) {
+            debugError('encodeNextAuthToken', 'EncryptJWT also failed:', encryptError);
+            throw new Error(`Failed to encode NextAuth token: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
 }
 function setCustomTokens(response, accessToken, optionsOrRefreshToken, options) {
     // 옵션 파라미터 처리: refreshToken과 options를 분리
@@ -240,21 +306,15 @@ function setCustomTokens(response, accessToken, optionsOrRefreshToken, options)
  */
 function setNextAuthToken(response, sessionToken, options = {}) {
     const { isProduction = false, cookieDomain, } = options;
-    const cookieName = isProduction
-        ? '__Secure-next-auth.session-token'
-        : 'next-auth.session-token';
+    // createNextAuthCookies와 동일한 로직 사용
+    const cookies = createNextAuthCookies({ isProduction, cookieDomain });
+    const cookieName = cookies.sessionToken.name;
     response.cookies.delete(cookieName);
-    const cookieOptions = {
+    response.cookies.set(cookieName, sessionToken, {
+        ...cookies.sessionToken.options,
         httpOnly: true,
-        secure: isProduction,
-        sameSite: 'lax',
         maxAge: 30 * 24 * 60 * 60, // 30일
-        path: '/',
-    };
-    if (cookieDomain) {
-        cookieOptions.domain = cookieDomain;
-    }
-    response.cookies.set(cookieName, sessionToken, cookieOptions);
+    });
 }
 /**
  * 리다이렉트용 HTML 생성
@@ -352,25 +412,29 @@ async function createAuthResponse(accessToken, secret, options) {
         throw new Error('Invalid token');
     }
     const { payload } = tokenResult;
-    // 2. 역할 추출
-    const role = extractRoleFromPayload(payload, serviceId);
-    // 3. NextAuth JWT 생성 및 인코딩
+    // 2. NextAuth JWT 생성
     const jwt = createNextAuthJWT(payload, serviceId);
-    const sessionToken = await encodeNextAuthToken(jwt, secret);
-    // 4. HTML 생성
+    debugLog('createAuthResponse', 'JWT created:', {
+        hasId: !!jwt.id,
+        hasEmail: !!jwt.email,
+        hasRole: !!jwt.role,
+    });
+    // 3. NextAuth 세션 토큰 생성 전략
+    // NextAuth의 JWT 콜백이 custom tokens를 읽어서 자동으로 NextAuth 세션을 생성
+    debugLog('createAuthResponse', 'Custom tokens will be set, NextAuth JWT callback will handle session creation');
+    // 5. HTML 생성
     const displayText = text || serviceId;
     const html = redirectPath
         ? createRedirectHTML(redirectPath, displayText)
         : createRedirectHTML('', displayText).replace("window.location.href = ''", "window.location.reload()");
-    // 5. Response 생성
+    // 6. Response 생성
     const response = new server_1.NextResponse(html, {
         status: 200,
         headers: {
             'Content-Type': 'text/html',
         },
     });
-    // 6. 쿠키 설정
-    // 자체 토큰 설정
+    // 4. 쿠키 설정
     if (refreshToken) {
         setCustomTokens(response, accessToken, refreshToken, {
             cookiePrefix,
@@ -383,15 +447,12 @@ async function createAuthResponse(accessToken, secret, options) {
             isProduction,
         });
     }
-    // NextAuth 토큰 설정
-    if (sessionToken) {
-        setNextAuthToken(response, sessionToken, {
-            isProduction,
-            cookieDomain,
-        });
-    }
+    debugLog('createAuthResponse', 'Custom tokens set successfully');
     return response;
 }
+// ============================================================================
+// SSO INTEGRATION FUNCTIONS
+// ============================================================================
 /**
  * 서비스 구독 유효성 확인 함수
  * @param services 서비스 정보 배열
@@ -479,12 +540,16 @@ async function getRefreshTokenFromSSO(userId, accessToken, options) {
     }
     return null;
 }
+// ============================================================================
+// TOKEN REFRESH & VERIFICATION FUNCTIONS
+// ============================================================================
 async function verifyAndRefreshToken(req, secret, options) {
-    const { cookiePrefix, serviceId, isProduction, cookieDomain, text, ssoBaseURL, authServiceKey, } = options;
+    const { cookiePrefix, serviceId, isProduction, cookieDomain, text, ssoBaseURL, authServiceKey, forceRefresh = false, } = options;
     // 1. access_token 쿠키 확인
+    // forceRefresh가 true이면 access token이 있어도 refresh를 시도
     const accessTokenName = `${cookiePrefix}_access_token`;
     const accessToken = req.cookies.get(accessTokenName)?.value;
-    if (accessToken) {
+    if (accessToken && !forceRefresh) {
         try {
             const secretBytes = new TextEncoder().encode(secret);
             const { payload } = await (0, jose_1.jwtVerify)(accessToken, secretBytes);
@@ -499,15 +564,25 @@ async function verifyAndRefreshToken(req, secret, options) {
     // 리프레시 토큰으로 갱신 시도
     const refreshTokenName = `${cookiePrefix}_refresh_token`;
     const refreshToken = req.cookies.get(refreshTokenName)?.value;
+    debugLog('verifyAndRefreshToken', 'Checking refresh:', {
+        hasRefreshToken: !!refreshToken,
+        forceRefresh,
+    });
     if (refreshToken) {
         try {
             if (!ssoBaseURL || !authServiceKey) {
+                debugLog('verifyAndRefreshToken', 'SSO config missing');
                 return { isValid: false, error: 'SSO_CONFIG_MISSING' };
             }
+            debugLog('verifyAndRefreshToken', 'Attempting token refresh...');
             const refreshResult = await refreshSSOToken(refreshToken, {
                 ssoBaseURL,
                 authServiceKey,
             });
+            debugLog('verifyAndRefreshToken', 'Refresh result:', {
+                success: refreshResult.success,
+                hasAccessToken: !!refreshResult.accessToken,
+            });
             if (refreshResult.success && refreshResult.accessToken) {
                 const newRefreshToken = refreshResult.refreshToken || refreshToken;
                 try {
@@ -522,6 +597,7 @@ async function verifyAndRefreshToken(req, secret, options) {
                     catch {
                         // 토큰 검증 실패
                     }
+                    debugLog('verifyAndRefreshToken', 'Creating auth response...');
                     const response = await createAuthResponse(refreshResult.accessToken, secret, {
                         refreshToken: newRefreshToken,
                         redirectPath: '',
@@ -535,21 +611,29 @@ async function verifyAndRefreshToken(req, secret, options) {
                     return { isValid: true, response, payload };
                 }
                 catch (error) {
-                    console.error('Failed to create auth response:', error);
+                    debugError('verifyAndRefreshToken', 'Failed to create auth response:', error);
                     return { isValid: false, error: 'SESSION_CREATION_FAILED' };
                 }
             }
             else {
-                return { isValid: false, error: 'REFRESH_FAILED' };
+                debugLog('verifyAndRefreshToken', 'Refresh failed, clearing all cookies');
+                const response = server_1.NextResponse.next();
+                clearAllAuthCookies(response, options.cookiePrefix, options.isProduction);
+                return { isValid: false, response, error: 'REFRESH_FAILED' };
             }
         }
         catch (error) {
-            console.error('Token refresh error:', error);
-            return { isValid: false, error: 'REFRESH_ERROR' };
+            debugError('verifyAndRefreshToken', 'Token refresh error:', error);
+            const response = server_1.NextResponse.next();
+            clearAllAuthCookies(response, options.cookiePrefix, options.isProduction);
+            return { isValid: false, response, error: 'REFRESH_ERROR' };
         }
     }
     return { isValid: false, error: 'NO_TOKEN' };
 }
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
 /**
  * 에러 페이지로 리다이렉트하는 헬퍼 함수
  * @param req NextRequest 객체
@@ -609,6 +693,9 @@ function requiresSubscription(pathname, role, subscriptionRequiredPaths, systemA
     // 구독이 필요한 경로인지 확인
     return subscriptionRequiredPaths.some(path => pathname.startsWith(path));
 }
+// ============================================================================
+// NEXTAUTH CONFIGURATION FUNCTIONS
+// ============================================================================
 // 유효한 라이센스 키 해시 목록
 const VALID_LICENSE_KEY_HASHES = new Set([
     '73bce4f3b64804c255cdab450d759a8b53038f9edb59ae42d9988b08dfd007e2',
@@ -623,12 +710,16 @@ const VALID_LICENSE_KEY_HASHES = new Set([
 function createNextAuthCookies(options) {
     const { isProduction = false, cookieDomain } = options;
     const isSecure = isProduction;
+    // cookieDomain이 설정되어 있으면 같은 도메인/서브도메인 간 쿠키 공유를 위해 'lax' 사용
+    // cookieDomain이 없고 프로덕션 환경이면 크로스 도메인을 위해 'none' 사용
+    // 개발 환경이면 항상 'lax' 사용
+    const sameSiteValue = cookieDomain ? 'lax' : (isSecure ? 'none' : 'lax');
     return {
         sessionToken: {
             name: isSecure ? `__Secure-next-auth.session-token` : `next-auth.session-token`,
             options: {
                 httpOnly: true,
-                sameSite: isSecure ? 'none' : 'lax',
+                sameSite: sameSiteValue,
                 path: '/',
                 secure: isSecure,
                 ...(cookieDomain && { domain: cookieDomain }),
@@ -637,7 +728,7 @@ function createNextAuthCookies(options) {
         callbackUrl: {
             name: isSecure ? `__Secure-next-auth.callback-url` : `next-auth.callback-url`,
             options: {
-                sameSite: isSecure ? 'none' : 'lax',
+                sameSite: sameSiteValue,
                 path: '/',
                 secure: isSecure,
                 ...(cookieDomain && { domain: cookieDomain }),
@@ -647,7 +738,7 @@ function createNextAuthCookies(options) {
             name: isSecure ? `__Secure-next-auth.csrf-token` : `next-auth.csrf-token`,
             options: {
                 httpOnly: true,
-                sameSite: isSecure ? 'none' : 'lax',
+                sameSite: sameSiteValue,
                 path: '/',
                 secure: isSecure,
                 ...(cookieDomain && { domain: cookieDomain }),
@@ -736,28 +827,17 @@ function createEmptySession(session) {
  * Session 콜백에서 토큰 정보를 세션에 매핑하는 헬퍼
  * @param session 기존 세션
  * @param token JWT 토큰
- * @param options 옵션
- * @param options.primaryAcademy 기본 학원 정보 (선택)
  * @returns 업데이트된 세션
  */
-function mapTokenToSession(session, token, options) {
+function mapTokenToSession(session, token) {
     if (!session.user) {
         return session;
     }
-    const { primaryAcademy } = options || {};
     const user = session.user;
     user.id = token.id;
     user.email = token.email;
     user.name = token.name;
-    user.role = primaryAcademy?.role || token.role;
-    user.academyId = primaryAcademy?.id;
-    user.academyName = primaryAcademy?.name;
-    if (token.academies && Array.isArray(token.academies)) {
-        user.academies = token.academies.map((ua) => ({
-            id: ua.id,
-            name: ua.name,
-        }));
-    }
+    user.role = token.role;
     user.smsVerified = token.smsVerified;
     user.emailVerified = token.emailVerified;
     user.phone = token.phone;
@@ -767,6 +847,57 @@ function mapTokenToSession(session, token, options) {
     user.decryptedPhone = token.decryptedPhone;
     return session;
 }
+/**
+ * JWT 콜백을 위한 통합 헬퍼 함수
+ * 초기 로그인, 토큰 갱신, 커스텀 토큰 읽기를 모두 처리
+ * @param token 기존 JWT 토큰
+ * @param user 사용자 정보 (초기 로그인 시)
+ * @param account 계정 정보 (초기 로그인 시)
+ * @param options 옵션
+ * @param options.secret NextAuth secret (커스텀 토큰 읽기용)
+ * @param options.licenseKey 라이센스 키 (커스텀 토큰 읽기용)
+ * @param options.serviceId 서비스 ID (커스텀 토큰 읽기용)
+ * @param options.cookieName 커스텀 토큰 쿠키 이름 (기본값: '{serviceId}_access_token')
+ * @param options.debug 디버깅 로그 출력 여부 (기본값: false)
+ * @returns 업데이트된 JWT 토큰
+ */
+async function handleJWTCallback(token, user, account, options) {
+    const { secret, licenseKey, serviceId, cookieName, debug = false, } = options || {};
+    // 디버깅 로그
+    if (debug) {
+        debugLog('handleJWTCallback', 'Token received:', {
+            hasId: !!token.id,
+            hasEmail: !!token.email,
+            hasRole: !!token.role,
+        });
+    }
+    // 1. 초기 로그인 시 (providers를 통한 로그인)
+    if (account && user) {
+        debugLog('handleJWTCallback', 'Initial login, creating token from user data');
+        return createInitialJWTToken(token, user, account);
+    }
+    // 2. 이미 토큰에 정보가 있으면 그대로 사용
+    if (token.id) {
+        debugLog('handleJWTCallback', 'Token already has id, using existing token');
+        return token;
+    }
+    // 3. 토큰에 id가 없는 경우 - 커스텀 토큰 쿠키에서 정보 읽기
+    debugLog('handleJWTCallback', 'Token has no id, checking custom token cookie');
+    if (secret && licenseKey && serviceId) {
+        const cookieNameToUse = cookieName || `${serviceId}_access_token`;
+        const jwt = await getJWTFromCustomTokenCookie(cookieNameToUse, secret, serviceId, licenseKey);
+        if (jwt) {
+            debugLog('handleJWTCallback', 'Successfully created JWT from custom token cookie');
+            return jwt;
+        }
+        debugLog('handleJWTCallback', 'Failed to create JWT from custom token cookie');
+    }
+    else {
+        debugLog('handleJWTCallback', 'Missing required parameters for custom token reading');
+    }
+    debugLog('handleJWTCallback', 'Returning original token');
+    return token;
+}
 /**
  * 쿠키에서 커스텀 토큰을 읽어서 NextAuth JWT로 변환하는 헬퍼 함수
  * NextAuth JWT 콜백에서 사용
@@ -774,31 +905,37 @@ function mapTokenToSession(session, token, options) {
  * @param secret JWT 서명에 사용할 secret key
  * @param serviceId 서비스 ID (필수)
  * @param licenseKey 라이센스 키 (필수)
- * @param includeAcademies academies 정보 포함 여부 (기본값: false)
  * @returns NextAuth JWT 객체 또는 null
  */
-async function getJWTFromCustomTokenCookie(cookieName, secret, serviceId, licenseKey, includeAcademies = false) {
+async function getJWTFromCustomTokenCookie(cookieName, secret, serviceId, licenseKey) {
+    debugLog('getJWTFromCustomTokenCookie', `Reading cookie: ${cookieName}`);
     try {
         const { cookies } = await Promise.resolve().then(() => __importStar(require('next/headers')));
         const cookieStore = await cookies();
         const accessToken = cookieStore.get(cookieName)?.value;
         if (!accessToken) {
+            debugLog('getJWTFromCustomTokenCookie', 'No access token found in cookies');
             return null;
         }
         await checkLicenseKey(licenseKey);
         const tokenResult = await verifyToken(accessToken, secret);
         if (!tokenResult) {
+            debugLog('getJWTFromCustomTokenCookie', 'Token verification failed');
             return null;
         }
         const { payload } = tokenResult;
-        const jwt = createNextAuthJWT(payload, serviceId, includeAcademies);
+        const jwt = createNextAuthJWT(payload, serviceId);
+        debugLog('getJWTFromCustomTokenCookie', 'JWT created successfully from custom token');
         return jwt;
     }
     catch (error) {
-        console.error(`[getJWTFromCustomTokenCookie] Failed to read ${cookieName}:`, error);
+        debugError('getJWTFromCustomTokenCookie', `Failed to read ${cookieName}:`, error);
         return null;
     }
 }
+// ============================================================================
+// LICENSE & AUTHORIZATION FUNCTIONS
+// ============================================================================
 async function checkLicenseKey(licenseKey) {
     if (!licenseKey || licenseKey.length < 10) {
         throw new Error('License key is required');
@@ -824,6 +961,9 @@ function checkRoleAccess(pathname, role, roleConfig) {
     // 매칭되는 경로가 없으면 허용
     return { allowed: true };
 }
+// ============================================================================
+// REDIRECT FUNCTIONS
+// ============================================================================
 /**
  * SSO 로그인 페이지로 리다이렉트하는 헬퍼 함수
  * @param req NextRequest 객체
@@ -846,6 +986,9 @@ function redirectToRoleDashboard(req, role, rolePaths, defaultPath = '/admin') {
     const redirectPath = rolePaths[role] || defaultPath;
     return server_1.NextResponse.redirect(new URL(redirectPath, req.url));
 }
+// ============================================================================
+// TOKEN VALIDATION UTILITIES
+// ============================================================================
 /**
  * 토큰이 만료되었는지 확인하는 함수
  * @param token NextAuth JWT 객체
@@ -899,6 +1042,9 @@ function hasAnyRole(token, roles, serviceId) {
     const effectiveRole = getEffectiveRole(token, serviceId);
     return roles.includes(effectiveRole || '');
 }
+// ============================================================================
+// PATH UTILITIES
+// ============================================================================
 /**
  * 공개 경로인지 확인하는 함수
  * @param pathname 경로명
@@ -927,6 +1073,9 @@ function isProtectedApiPath(pathname, exemptPaths = []) {
         return false;
     return !exemptPaths.some(path => pathname.startsWith(path));
 }
+// ============================================================================
+// AUTHENTICATION CHECK FUNCTIONS
+// ============================================================================
 /**
  * NextAuth 토큰과 자체 토큰을 모두 확인하는 통합 인증 체크 함수
  * @param req NextRequest 객체
@@ -975,12 +1124,59 @@ async function checkAuthentication(req, secret, options) {
  * @returns 인증 결과
  */
 async function verifyAndRefreshTokenWithNextAuth(req, nextAuthToken, secret, options) {
-    if (nextAuthToken && isValidToken(nextAuthToken)) {
+    const { cookiePrefix, isProduction } = options;
+    // NextAuth 세션 토큰 쿠키 확인
+    const nextAuthSessionTokenCookieName = isProduction
+        ? '__Secure-next-auth.session-token'
+        : 'next-auth.session-token';
+    const hasNextAuthSessionTokenCookie = !!req.cookies.get(nextAuthSessionTokenCookieName)?.value;
+    // NextAuth 토큰 확인
+    const hasValidNextAuthToken = nextAuthToken && isValidToken(nextAuthToken);
+    // Access token 확인
+    const accessTokenName = `${cookiePrefix}_access_token`;
+    const accessToken = req.cookies.get(accessTokenName)?.value;
+    let hasValidAccessToken = false;
+    if (accessToken) {
+        try {
+            const secretBytes = new TextEncoder().encode(secret);
+            const { payload } = await (0, jose_1.jwtVerify)(accessToken, secretBytes);
+            if (payload && typeof payload === 'object' && payload.email) {
+                hasValidAccessToken = true;
+            }
+        }
+        catch {
+            // 토큰 검증 실패
+        }
+    }
+    // Refresh token 확인
+    const refreshTokenName = `${cookiePrefix}_refresh_token`;
+    const refreshToken = req.cookies.get(refreshTokenName)?.value;
+    debugLog('verifyAndRefreshTokenWithNextAuth', 'Token status:', {
+        hasNextAuthCookie: hasNextAuthSessionTokenCookie,
+        hasValidNextAuth: hasValidNextAuthToken,
+        hasValidAccess: hasValidAccessToken,
+        hasRefresh: !!refreshToken,
+    });
+    // NextAuth 토큰 또는 access token 중 하나라도 유효하면 통과
+    if (hasValidNextAuthToken || hasValidAccessToken) {
+        debugLog('verifyAndRefreshTokenWithNextAuth', 'At least one token is valid');
         return { isValid: true };
     }
-    const authCheck = await verifyAndRefreshToken(req, secret, options);
-    return authCheck;
+    // 둘 다 없으면 refresh token으로 갱신 시도
+    if (refreshToken) {
+        debugLog('verifyAndRefreshTokenWithNextAuth', 'No valid tokens, attempting refresh');
+        const authCheck = await verifyAndRefreshToken(req, secret, {
+            ...options,
+            forceRefresh: true,
+        });
+        return authCheck;
+    }
+    debugLog('verifyAndRefreshTokenWithNextAuth', 'No tokens available');
+    return { isValid: false, error: 'NO_TOKEN' };
 }
+// ============================================================================
+// MIDDLEWARE CONFIGURATION & HANDLER
+// ============================================================================
 /**
  * 기본 미들웨어 설정을 생성하는 함수
  * @param config 커스텀 설정 (필수: serviceId 포함)
@@ -1057,6 +1253,7 @@ async function handleMiddleware(req, config, options) {
     try {
         const pathname = req.nextUrl.pathname;
         const { secret, isProduction, cookieDomain, getNextAuthToken, licenseKey } = options;
+        debugLog('handleMiddleware', `Processing: ${pathname}`);
         await checkLicenseKey(licenseKey);
         if (!config.serviceId) {
             throw new Error('serviceId is required in middleware config');
@@ -1068,7 +1265,6 @@ async function handleMiddleware(req, config, options) {
             token = await getNextAuthToken(req);
         }
         else {
-            // 기본적으로 secret을 사용하여 토큰 가져오기
             try {
                 const { getToken } = await Promise.resolve().then(() => __importStar(require('next-auth/jwt')));
                 token = await getToken({ req, secret });
@@ -1077,7 +1273,12 @@ async function handleMiddleware(req, config, options) {
                 // NextAuth가 없으면 null 유지
             }
         }
+        debugLog('handleMiddleware', 'Token status:', {
+            hasToken: !!token,
+            hasId: !!token?.id,
+        });
         const effectiveRole = getEffectiveRole(token, serviceId);
+        debugLog('handleMiddleware', `Effective role: ${effectiveRole || 'none'}`);
         // 1. API 요청 처리
         if (pathname.startsWith('/api/')) {
             if (config.authApiPaths.includes(pathname)) {
@@ -1109,6 +1310,7 @@ async function handleMiddleware(req, config, options) {
         if (pathname === '/') {
             const tokenParam = req.nextUrl.searchParams.get('token');
             if (tokenParam) {
+                debugLog('handleMiddleware', 'Processing SSO token from query parameter');
                 try {
                     // 1. 토큰 검증
                     const tokenResult = await verifyToken(tokenParam, secret);
@@ -1119,6 +1321,7 @@ async function handleMiddleware(req, config, options) {
                     // 2. 역할 추출
                     const defaultRole = Object.keys(config.rolePaths)[0] || 'ADMIN';
                     const tokenRole = extractRoleFromPayload(payload, serviceId, defaultRole);
+                    debugLog('handleMiddleware', `Extracted role: ${tokenRole}`);
                     // 3. Refresh token 가져오기 (서버 간 통신)
                     const userId = payload.sub || payload.userId || '';
                     const ssoBaseURL = options.ssoBaseURL;
@@ -1128,6 +1331,7 @@ async function handleMiddleware(req, config, options) {
                         : '';
                     // 4. 자체 토큰 생성 및 쿠키 설정
                     const redirectPath = config.rolePaths[tokenRole] || config.rolePaths[defaultRole] || '/admin';
+                    debugLog('handleMiddleware', `Creating auth response, redirect to: ${redirectPath}`);
                     const response = await createAuthResponse(tokenParam, secret, {
                         refreshToken: refreshToken || undefined,
                         redirectPath,
@@ -1140,8 +1344,8 @@ async function handleMiddleware(req, config, options) {
                     });
                     return response;
                 }
-                catch {
-                    // 토큰 검증 실패 시 SSO 로그인으로 리다이렉트
+                catch (error) {
+                    debugError('handleMiddleware', 'Error processing token:', error);
                     const ssoBaseURL = options.ssoBaseURL;
                     return redirectToSSOLogin(req, serviceId, ssoBaseURL);
                 }
@@ -1203,7 +1407,7 @@ async function handleMiddleware(req, config, options) {
                 const tokenResult = await verifyToken(accessToken, secret);
                 if (tokenResult) {
                     const { payload } = tokenResult;
-                    finalToken = createNextAuthJWT(payload, serviceId, true); // academies 포함
+                    finalToken = createNextAuthJWT(payload, serviceId);
                 }
             }
         }
@@ -1241,10 +1445,10 @@ async function handleMiddleware(req, config, options) {
                 return server_1.NextResponse.redirect(subscriptionCheck.redirectUrl);
             }
         }
-        return null; // 다음 미들웨어로 진행
+        return null;
     }
     catch (error) {
-        console.error('Middleware error:', error);
+        debugError('handleMiddleware', 'Middleware error:', error);
         return redirectToError(req, 'INTERNAL_ERROR', '서버 오류가 발생했습니다.', config.errorPath);
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thinkingcat/auth-utils",
-  "version": "1.0.14",
-  "description": "Authentication utilities for ThinkingCat SSO services",
+  "version": "1.0.17",
+  "description": "Authentication utilities for ThinkingCat SSO services with conditional logging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {