@thinkingcat/auth-utils 1.0.16 → 1.0.18

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.16"
+    "@thinkingcat/auth-utils": "^1.0.17"
   }
 }
 ```
@@ -557,7 +588,7 @@ import { createNextAuthBaseConfig } from "@thinkingcat/auth-utils";
 
 const baseConfig = createNextAuthBaseConfig({
   secret: process.env.NEXTAUTH_SECRET!,
-  isProduction: process.env.NODE_ENV === 'production',
+  isProduction: process.env.NODE_ENV === "production",
   cookieDomain: process.env.COOKIE_DOMAIN,
   signInPath: "/login",
   errorPath: "/login",
@@ -595,7 +626,7 @@ JWT 콜백을 위한 통합 헬퍼 함수입니다. 초기 로그인, 토큰 갱
 - `options.secret`: NextAuth secret (커스텀 토큰 읽기용)
 - `options.licenseKey`: 라이센스 키 (커스텀 토큰 읽기용)
 - `options.serviceId`: 서비스 ID (커스텀 토큰 읽기용)
-- `options.cookieName`: 커스텀 토큰 쿠키 이름 (기본값: '{serviceId}_access_token')
+- `options.cookieName`: 커스텀 토큰 쿠키 이름 (기본값: '{serviceId}\_access_token')
 - `options.debug`: 디버깅 로그 출력 여부 (기본값: false)
 
 **반환값:**
@@ -1459,10 +1490,32 @@ const response = await handleMiddleware(req, middlewareConfig, {
 ## 📦 패키지 정보
 
 - **패키지명**: `@thinkingcat/auth-utils`
-- **버전**: `1.0.16`
+- **버전**: `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

@@ -1,4 +1,4 @@
-import { JWT } from "next-auth/jwt";
+import type { JWT } from "next-auth/jwt";
 import type { Session } from "next-auth";
 import { NextResponse, NextRequest } from 'next/server';
 export interface ResponseLike {
@@ -224,6 +224,7 @@ export declare function verifyAndRefreshToken(req: NextRequest, secret: string,
     ssoBaseURL?: string;
     authServiceKey?: string;
     licenseKey: string;
+    forceRefresh?: boolean;
 }): Promise<{
     isValid: boolean;
     response?: NextResponse;

package/dist/index.js

@@ -71,10 +71,27 @@ exports.checkAuthentication = checkAuthentication;
 exports.verifyAndRefreshTokenWithNextAuth = verifyAndRefreshTokenWithNextAuth;
 exports.createMiddlewareConfig = createMiddlewareConfig;
 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);
@@ -82,6 +99,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
@@ -126,7 +162,7 @@ function createNextAuthJWT(payload, serviceId) {
     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,
         phoneVerified: payload.phoneVerified ?? false,
@@ -170,11 +206,48 @@ function createNextAuthJWT(payload, serviceId) {
  * @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 함수를 동적 import로 사용 (Edge Runtime 호환)
+        const { encode } = await Promise.resolve().then(() => __importStar(require('next-auth/jwt')));
+        return await 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를 분리
@@ -233,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 생성
@@ -345,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,
@@ -376,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 서비스 정보 배열
@@ -472,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);
@@ -492,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 {
@@ -515,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: '',
@@ -528,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 객체
@@ -602,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',
@@ -616,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 }),
@@ -630,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 }),
@@ -640,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 }),
@@ -767,29 +865,37 @@ async function handleJWTCallback(token, user, account, options) {
     const { secret, licenseKey, serviceId, cookieName, debug = false, } = options || {};
     // 디버깅 로그
     if (debug) {
-        console.log('[JWT Callback] Token received:', {
+        debugLog('handleJWTCallback', 'Token received:', {
             hasId: !!token.id,
             hasEmail: !!token.email,
             hasRole: !!token.role,
-            tokenKeys: Object.keys(token),
         });
     }
     // 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;
 }
 /**
@@ -802,27 +908,34 @@ async function handleJWTCallback(token, user, account, options) {
  * @returns NextAuth JWT 객체 또는 null
  */
 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);
+        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');
@@ -848,6 +961,9 @@ function checkRoleAccess(pathname, role, roleConfig) {
     // 매칭되는 경로가 없으면 허용
     return { allowed: true };
 }
+// ============================================================================
+// REDIRECT FUNCTIONS
+// ============================================================================
 /**
  * SSO 로그인 페이지로 리다이렉트하는 헬퍼 함수
  * @param req NextRequest 객체
@@ -870,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 객체
@@ -923,6 +1042,9 @@ function hasAnyRole(token, roles, serviceId) {
     const effectiveRole = getEffectiveRole(token, serviceId);
     return roles.includes(effectiveRole || '');
 }
+// ============================================================================
+// PATH UTILITIES
+// ============================================================================
 /**
  * 공개 경로인지 확인하는 함수
  * @param pathname 경로명
@@ -951,6 +1073,9 @@ function isProtectedApiPath(pathname, exemptPaths = []) {
         return false;
     return !exemptPaths.some(path => pathname.startsWith(path));
 }
+// ============================================================================
+// AUTHENTICATION CHECK FUNCTIONS
+// ============================================================================
 /**
  * NextAuth 토큰과 자체 토큰을 모두 확인하는 통합 인증 체크 함수
  * @param req NextRequest 객체
@@ -999,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 포함)
@@ -1081,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');
@@ -1092,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 });
@@ -1101,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)) {
@@ -1133,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);
@@ -1143,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;
@@ -1152,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,
@@ -1164,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);
                 }
@@ -1265,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.16",
-  "description": "Authentication utilities for ThinkingCat SSO services",
+  "version": "1.0.18",
+  "description": "Authentication utilities for ThinkingCat SSO services with conditional logging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -40,6 +40,3 @@
     ".env.example"
   ]
 }
-
-
-