@thinkingcat/auth-utils 1.0.4

package/dist/index.js

@@ -0,0 +1,709 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyToken = verifyToken;
+exports.extractRoleFromPayload = extractRoleFromPayload;
+exports.createNextAuthJWT = createNextAuthJWT;
+exports.encodeNextAuthToken = encodeNextAuthToken;
+exports.setCustomTokens = setCustomTokens;
+exports.setNextAuthToken = setNextAuthToken;
+exports.createRedirectHTML = createRedirectHTML;
+exports.createAuthResponse = createAuthResponse;
+exports.validateServiceSubscription = validateServiceSubscription;
+exports.refreshSSOToken = refreshSSOToken;
+exports.getRefreshTokenFromSSO = getRefreshTokenFromSSO;
+exports.verifyAndRefreshToken = verifyAndRefreshToken;
+exports.redirectToError = redirectToError;
+exports.clearAuthCookies = clearAuthCookies;
+exports.getEffectiveRole = getEffectiveRole;
+exports.requiresSubscription = requiresSubscription;
+exports.checkRoleAccess = checkRoleAccess;
+exports.redirectToSSOLogin = redirectToSSOLogin;
+exports.redirectToRoleDashboard = redirectToRoleDashboard;
+exports.isTokenExpired = isTokenExpired;
+exports.isValidToken = isValidToken;
+exports.hasRole = hasRole;
+exports.hasAnyRole = hasAnyRole;
+exports.isPublicPath = isPublicPath;
+exports.isApiPath = isApiPath;
+exports.isProtectedApiPath = isProtectedApiPath;
+exports.checkAuthentication = checkAuthentication;
+const jwt_1 = require("next-auth/jwt");
+const jose_1 = require("jose");
+const server_1 = require("next/server");
+/**
+ * 토큰 검증 및 디코딩
+ * @param accessToken JWT access token
+ * @param secret JWT 서명에 사용할 secret key
+ * @returns 검증된 payload 또는 null
+ */
+async function verifyToken(accessToken, secret) {
+    try {
+        const secretBytes = new TextEncoder().encode(secret);
+        const { payload } = await (0, jose_1.jwtVerify)(accessToken, secretBytes);
+        if (payload && typeof payload === 'object' && payload.email) {
+            return { payload: payload };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * payload에서 역할 추출 (서비스별)
+ * @param payload JWT payload
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @param defaultRole 기본 역할 (기본값: 'ADMIN')
+ * @returns 추출된 역할
+ */
+function extractRoleFromPayload(payload, serviceId = 'checkon', defaultRole = 'ADMIN') {
+    const services = payload.services || [];
+    const service = services.find((s) => s.serviceId === serviceId);
+    return service?.role || payload.role || defaultRole;
+}
+/**
+ * payload에서 NextAuth JWT 객체 생성
+ * @param payload JWT payload
+ * @param includeAcademies academies 정보 포함 여부
+ * @returns NextAuth JWT 객체
+ */
+function createNextAuthJWT(payload, includeAcademies = false) {
+    const services = payload.services || [];
+    const checkonService = services.find((s) => s.serviceId === 'checkon');
+    const effectiveRole = checkonService?.role || payload.role || 'ADMIN';
+    const jwt = {
+        id: (payload.id || payload.sub),
+        email: payload.email,
+        name: payload.name,
+        role: effectiveRole, // Role enum 타입
+        services: payload.services,
+        academies: includeAcademies
+            ? payload.academies || []
+            : [],
+        phoneVerified: payload.phoneVerified ?? false,
+        emailVerified: payload.emailVerified ?? false,
+        smsVerified: payload.smsVerified ?? false,
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60), // 30일
+    };
+    // 선택적 필드들
+    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)
+        jwt.decryptedEmail = payload.decryptedEmail;
+    if (payload.decryptedPhone)
+        jwt.decryptedPhone = payload.decryptedPhone;
+    if (payload.emailHash)
+        jwt.emailHash = payload.emailHash;
+    if (payload.maskedEmail)
+        jwt.maskedEmail = payload.maskedEmail;
+    if (payload.phoneHash)
+        jwt.phoneHash = payload.phoneHash;
+    if (payload.maskedPhone)
+        jwt.maskedPhone = payload.maskedPhone;
+    if (payload.refreshToken)
+        jwt.refreshToken = payload.refreshToken;
+    if (payload.accessToken)
+        jwt.accessToken = payload.accessToken;
+    if (payload.accessTokenExpires)
+        jwt.accessTokenExpires = payload.accessTokenExpires;
+    if (payload.serviceId)
+        jwt.serviceId = payload.serviceId;
+    return jwt;
+}
+/**
+ * NextAuth JWT를 인코딩된 세션 토큰으로 변환
+ * @param jwt NextAuth JWT 객체
+ * @param secret JWT 서명에 사용할 secret key
+ * @param maxAge 토큰 유효 기간 (초, 기본값: 30일)
+ * @returns 인코딩된 세션 토큰
+ */
+async function encodeNextAuthToken(jwt, secret, maxAge = 30 * 24 * 60 * 60) {
+    return await (0, jwt_1.encode)({
+        token: jwt,
+        secret: secret,
+        maxAge: maxAge,
+    });
+}
+function setCustomTokens(response, accessToken, optionsOrRefreshToken, options) {
+    // 옵션 파라미터 처리: refreshToken과 options를 분리
+    let refreshTokenValue;
+    let cookiePrefix;
+    let isProduction;
+    if (typeof optionsOrRefreshToken === 'string') {
+        // 기존 방식: refreshToken이 문자열로 전달된 경우
+        refreshTokenValue = optionsOrRefreshToken;
+        const { cookiePrefix: prefix = 'checkon', isProduction: prod = false, } = options || {};
+        cookiePrefix = prefix;
+        isProduction = prod;
+    }
+    else {
+        // 새로운 방식: options 객체로 전달된 경우
+        const opts = optionsOrRefreshToken || {};
+        refreshTokenValue = opts.refreshToken;
+        cookiePrefix = opts.cookiePrefix || 'checkon';
+        isProduction = opts.isProduction || false;
+    }
+    // access_token 설정
+    const accessTokenName = `${cookiePrefix}_access_token`;
+    response.cookies.delete(accessTokenName);
+    response.cookies.set(accessTokenName, accessToken, {
+        httpOnly: true,
+        secure: isProduction,
+        sameSite: isProduction ? 'none' : 'lax',
+        maxAge: 15 * 60, // 15분
+        path: '/',
+    });
+    // refresh_token 설정 (있는 경우)
+    if (refreshTokenValue) {
+        const refreshTokenName = `${cookiePrefix}_refresh_token`;
+        response.cookies.set(refreshTokenName, refreshTokenValue, {
+            httpOnly: true,
+            secure: isProduction,
+            sameSite: isProduction ? 'none' : 'lax',
+            maxAge: 30 * 24 * 60 * 60, // 30일
+            path: '/',
+        });
+    }
+}
+/**
+ * NextAuth 세션 토큰만 설정
+ * @param response NextResponse 객체
+ * @param sessionToken NextAuth session token
+ * @param options 쿠키 설정 옵션
+ * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
+ * @param options.cookieDomain 쿠키 도메인 (선택)
+ */
+function setNextAuthToken(response, sessionToken, options = {}) {
+    const { isProduction = false, cookieDomain, } = options;
+    const cookieName = isProduction
+        ? '__Secure-next-auth.session-token'
+        : 'next-auth.session-token';
+    response.cookies.delete(cookieName);
+    const cookieOptions = {
+        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 생성
+ * @param redirectPath 리다이렉트할 경로
+ * @param text 표시할 텍스트 (기본값: 'checkon')
+ * @returns HTML 문자열
+ */
+function createRedirectHTML(redirectPath, text = 'checkon') {
+    return `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>Redirecting...</title>
+        <style>
+          * { margin: 0; padding: 0; box-sizing: border-box; }
+          html, body {
+            width: 100%;
+            height: 100%;
+            overflow: hidden;
+          }
+          body {
+            display: flex;
+            align-items: flex-start;
+            justify-content: flex-start;
+            padding-left: 10%;
+            padding-top: 20%;
+            background: #fff;
+          }
+          .typing-text {
+            font-family: 'Courier New', monospace;
+            font-size: 2.5rem;
+            font-weight: bold;
+            color: #667eea;
+            letter-spacing: 0.1em;
+          }
+          .cursor {
+            display: inline-block;
+            width: 3px;
+            height: 2.5rem;
+            background-color: #667eea;
+            margin-left: 2px;
+            animation: blink 0.7s infinite;
+          }
+          @keyframes blink {
+            0%, 50% { opacity: 1; }
+            51%, 100% { opacity: 0; }
+          }
+        </style>
+      </head>
+      <body>
+        <div class="typing-text">
+          <span id="text"></span><span class="cursor"></span>
+        </div>
+        <script>
+          const text = '${text}';
+          let index = 0;
+          const speed = 100;
+          
+          function type() {
+            if (index < text.length) {
+              document.getElementById('text').textContent += text.charAt(index);
+              index++;
+              setTimeout(type, speed);
+            } else {
+              setTimeout(() => window.location.href = '${redirectPath}', 200);
+            }
+          }
+          
+          type();
+        </script>
+      </body>
+    </html>
+  `;
+}
+/**
+ * access token과 refresh token을 사용하여 완전한 인증 세션 생성
+ * @param accessToken access token
+ * @param secret JWT 서명에 사용할 secret key
+ * @param options 추가 옵션
+ * @param options.refreshToken refresh token (선택)
+ * @param options.redirectPath 리다이렉트할 경로 (기본값: 페이지 리로드)
+ * @param options.text 리다이렉트 HTML에 표시할 텍스트 (기본값: 'checkon')
+ * @param options.cookiePrefix 쿠키 이름 접두사 (기본값: 'checkon')
+ * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
+ * @param options.cookieDomain 쿠키 도메인 (선택)
+ * @returns NextResponse 객체
+ */
+async function createAuthResponse(accessToken, secret, options = {}) {
+    const { refreshToken, redirectPath, text = 'checkon', cookiePrefix = 'checkon', isProduction = false, cookieDomain, } = options;
+    // 1. 토큰 검증
+    const tokenResult = await verifyToken(accessToken, secret);
+    if (!tokenResult) {
+        throw new Error('Invalid token');
+    }
+    const { payload } = tokenResult;
+    // 2. 역할 추출
+    const role = extractRoleFromPayload(payload);
+    // 3. NextAuth JWT 생성 및 인코딩
+    const jwt = createNextAuthJWT(payload);
+    const sessionToken = await encodeNextAuthToken(jwt, secret);
+    // 4. HTML 생성
+    const html = redirectPath
+        ? createRedirectHTML(redirectPath, text)
+        : createRedirectHTML('', text).replace("window.location.href = ''", "window.location.reload()");
+    // 5. Response 생성
+    const response = new server_1.NextResponse(html, {
+        status: 200,
+        headers: {
+            'Content-Type': 'text/html',
+        },
+    });
+    // 6. 쿠키 설정
+    // 자체 토큰 설정
+    if (refreshToken) {
+        setCustomTokens(response, accessToken, refreshToken, {
+            cookiePrefix,
+            isProduction,
+        });
+    }
+    else {
+        setCustomTokens(response, accessToken, {
+            cookiePrefix,
+            isProduction,
+        });
+    }
+    // NextAuth 토큰 설정
+    if (sessionToken) {
+        setNextAuthToken(response, sessionToken, {
+            isProduction,
+            cookieDomain,
+        });
+    }
+    return response;
+}
+/**
+ * 서비스 구독 유효성 확인 함수
+ * @param services 서비스 정보 배열
+ * @param serviceId 확인할 서비스 ID
+ * @returns 구독 유효성 결과
+ */
+function validateServiceSubscription(services, serviceId) {
+    const filteredServices = services.filter(service => service.serviceId === serviceId);
+    if (filteredServices.length === 0) {
+        return {
+            isValid: false,
+            redirectUrl: `${process.env.SSO_AUTH_SERVER_URL || 'http://localhost:3000'}/services/${serviceId}?type=subscription_required`
+        };
+    }
+    const service = filteredServices[0];
+    if (service.status !== "ACTIVE") {
+        return {
+            isValid: false,
+            redirectUrl: `${process.env.SSO_AUTH_SERVER_URL || 'http://localhost:3000'}/services/${service.serviceId}?type=subscription_required`,
+            service
+        };
+    }
+    return {
+        isValid: true,
+        service
+    };
+}
+/**
+ * SSO 서버에서 refresh token을 사용하여 새로운 access token을 발급받는 함수
+ * @param refreshToken refresh token
+ * @param options 옵션
+ * @param options.ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @param options.authServiceKey 인증 서비스 키 (기본값: 환경 변수)
+ * @returns SSO refresh token 응답
+ */
+async function refreshSSOToken(refreshToken, options) {
+    const ssoBaseURL = options?.ssoBaseURL || process.env.NEXT_PUBLIC_SSO_BASE_URL || 'https://sso.thinkingcatworks.com';
+    const authServiceKey = options?.authServiceKey || process.env.AUTH_SERVICE_SECRET_KEY;
+    if (!authServiceKey) {
+        throw new Error('AUTH_SERVICE_SECRET_KEY not configured');
+    }
+    const refreshResponse = await fetch(`${ssoBaseURL}/api/sso/refresh`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-auth-service-key': authServiceKey,
+        },
+        body: JSON.stringify({ refreshToken }),
+    });
+    return await refreshResponse.json();
+}
+/**
+ * SSO 서버에서 사용자의 refresh token을 가져오는 함수
+ * @param userId 사용자 ID
+ * @param accessToken access token
+ * @param options 옵션
+ * @param options.ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @param options.authServiceKey 인증 서비스 키 (기본값: 환경 변수)
+ * @returns refresh token 또는 null
+ */
+async function getRefreshTokenFromSSO(userId, accessToken, options) {
+    const ssoBaseURL = options?.ssoBaseURL || process.env.NEXT_PUBLIC_SSO_BASE_URL || 'https://sso.thinkingcatworks.com';
+    const authServiceKey = options?.authServiceKey || process.env.AUTH_SERVICE_SECRET_KEY;
+    if (!authServiceKey) {
+        return null;
+    }
+    try {
+        const refreshResponse = await fetch(`${ssoBaseURL}/api/sso/get-refresh-token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-auth-service-key': authServiceKey,
+            },
+            body: JSON.stringify({
+                userId,
+                accessToken
+            }),
+        });
+        const refreshResult = await refreshResponse.json();
+        if (refreshResponse.ok && refreshResult.success && refreshResult.refreshToken) {
+            return refreshResult.refreshToken;
+        }
+    }
+    catch {
+        // Refresh token 실패해도 access token으로 일단 로그인 가능
+    }
+    return null;
+}
+/**
+ * 토큰 검증 및 리프레시 처리 공통 함수
+ *
+ * @param req - NextRequest 객체
+ * @param secret - JWT 서명에 사용할 secret key
+ * @param options - 옵션
+ * @param options.cookiePrefix - 쿠키 이름 접두사 (기본값: 'checkon')
+ * @param options.isProduction - 프로덕션 환경 여부 (기본값: false)
+ * @param options.cookieDomain - 쿠키 도메인 (선택)
+ * @param options.text - 리다이렉트 HTML에 표시할 텍스트 (기본값: 'checkon')
+ * @param options.ssoBaseURL - SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @param options.authServiceKey - 인증 서비스 키 (기본값: 환경 변수)
+ * @returns 검증 결과 및 필요시 리프레시된 응답
+ */
+async function verifyAndRefreshToken(req, secret, options) {
+    const { cookiePrefix = 'checkon', isProduction = false, cookieDomain, text = 'checkon', } = options || {};
+    // 1. access_token 쿠키 확인
+    const accessTokenName = `${cookiePrefix}_access_token`;
+    const accessToken = req.cookies.get(accessTokenName)?.value;
+    if (accessToken) {
+        const tokenResult = await verifyToken(accessToken, secret);
+        if (tokenResult) {
+            return { isValid: true, payload: tokenResult.payload };
+        }
+        // 토큰이 만료되었거나 유효하지 않음 (리프레시 시도)
+    }
+    // 2. 리프레시 토큰으로 갱신 시도
+    const refreshTokenName = `${cookiePrefix}_refresh_token`;
+    const refreshToken = req.cookies.get(refreshTokenName)?.value;
+    if (refreshToken) {
+        try {
+            const refreshResult = await refreshSSOToken(refreshToken, {
+                ssoBaseURL: options?.ssoBaseURL,
+                authServiceKey: options?.authServiceKey,
+            });
+            if (refreshResult.success && refreshResult.accessToken) {
+                // 토큰 갱신 성공 - createAuthResponse 사용
+                const newRefreshToken = refreshResult.refreshToken || refreshToken;
+                try {
+                    const response = await createAuthResponse(refreshResult.accessToken, secret, {
+                        refreshToken: newRefreshToken,
+                        redirectPath: '', // 리다이렉트 없이 현재 페이지 유지
+                        text,
+                        cookiePrefix,
+                        isProduction,
+                        cookieDomain,
+                    });
+                    // payload 추출을 위해 토큰 검증
+                    const tokenResult = await verifyToken(refreshResult.accessToken, secret);
+                    const payload = tokenResult?.payload;
+                    return { isValid: true, response, payload };
+                }
+                catch (error) {
+                    console.error('Failed to create auth response:', error);
+                    return { isValid: false, error: 'SESSION_CREATION_FAILED' };
+                }
+            }
+            else {
+                return { isValid: false, error: 'REFRESH_FAILED' };
+            }
+        }
+        catch (error) {
+            console.error('Token refresh error:', error);
+            return { isValid: false, error: 'REFRESH_ERROR' };
+        }
+    }
+    return { isValid: false, error: 'NO_TOKEN' };
+}
+/**
+ * 에러 페이지로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param code 에러 코드
+ * @param message 에러 메시지
+ * @param errorPath 에러 페이지 경로 (기본값: '/error')
+ * @returns NextResponse 리다이렉트 응답
+ */
+function redirectToError(req, code, message, errorPath = '/error') {
+    const url = new URL(errorPath, req.url);
+    url.searchParams.set('code', code);
+    url.searchParams.set('message', message);
+    return server_1.NextResponse.redirect(url);
+}
+/**
+ * 인증 쿠키를 삭제하는 헬퍼 함수
+ * @param response NextResponse 객체
+ * @param cookiePrefix 쿠키 이름 접두사 (기본값: 'checkon')
+ * @returns NextResponse 객체
+ */
+function clearAuthCookies(response, cookiePrefix = 'checkon') {
+    response.cookies.delete(`${cookiePrefix}_access_token`);
+    response.cookies.delete(`${cookiePrefix}_refresh_token`);
+    return response;
+}
+/**
+ * JWT에서 서비스별 역할을 추출하는 헬퍼 함수
+ * @param token NextAuth JWT 객체 또는 null
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 추출된 역할 또는 undefined
+ */
+function getEffectiveRole(token, serviceId = 'checkon') {
+    if (!token)
+        return undefined;
+    // token이 이미 JWT 객체인 경우 role을 직접 사용
+    if (token.role) {
+        return token.role;
+    }
+    // services에서 추출
+    const services = token.services || [];
+    const service = services.find((s) => s.serviceId === serviceId);
+    return service?.role;
+}
+/**
+ * 구독이 필요한 경로인지 확인하는 헬퍼 함수
+ * @param pathname 경로명
+ * @param role 사용자 역할
+ * @param subscriptionRequiredPaths 구독이 필요한 경로 배열
+ * @param systemAdminRole 시스템 관리자 역할 (기본값: 'SYSTEM_ADMIN')
+ * @returns 구독이 필요한지 여부
+ */
+function requiresSubscription(pathname, role, subscriptionRequiredPaths, systemAdminRole = 'SYSTEM_ADMIN') {
+    // 시스템 관리자는 구독 확인 제외
+    if (role === systemAdminRole) {
+        return false;
+    }
+    // 구독이 필요한 경로인지 확인
+    return subscriptionRequiredPaths.some(path => pathname.startsWith(path));
+}
+function checkRoleAccess(pathname, role, roleConfig) {
+    // 각 역할 설정을 확인
+    for (const [configRole, config] of Object.entries(roleConfig)) {
+        const isPathMatch = config.paths.some(path => pathname.startsWith(path));
+        if (isPathMatch) {
+            // 역할이 정확히 일치하거나 allowedRoles에 포함되어 있으면 허용
+            if (role === configRole || config.allowedRoles?.includes(role)) {
+                return { allowed: true };
+            }
+            // 접근 거부
+            return { allowed: false, message: config.message };
+        }
+    }
+    // 매칭되는 경로가 없으면 허용
+    return { allowed: true };
+}
+/**
+ * SSO 로그인 페이지로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param serviceId 서비스 ID
+ * @param ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @returns NextResponse 리다이렉트 응답
+ */
+function redirectToSSOLogin(req, serviceId, ssoBaseURL) {
+    const baseURL = ssoBaseURL || process.env.NEXT_PUBLIC_SSO_BASE_URL || "https://sso.thinkingcatworks.com";
+    return server_1.NextResponse.redirect(new URL(`${baseURL}/auth/login?serviceId=${serviceId}`, req.url));
+}
+/**
+ * 역할별 대시보드 경로로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param role 사용자 역할
+ * @param rolePaths 역할별 경로 설정 객체
+ * @param defaultPath 기본 경로 (기본값: '/admin')
+ * @returns NextResponse 리다이렉트 응답
+ */
+function redirectToRoleDashboard(req, role, rolePaths, defaultPath = '/admin') {
+    const redirectPath = rolePaths[role] || defaultPath;
+    return server_1.NextResponse.redirect(new URL(redirectPath, req.url));
+}
+/**
+ * 토큰이 만료되었는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @returns 만료 여부
+ */
+function isTokenExpired(token) {
+    if (!token)
+        return true;
+    if (token.exp && typeof token.exp === 'number' && token.exp < Math.floor(Date.now() / 1000)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 토큰이 유효한지 확인하는 함수 (만료 및 필수 필드 체크)
+ * @param token NextAuth JWT 객체
+ * @returns 유효성 여부
+ */
+function isValidToken(token) {
+    if (!token)
+        return false;
+    if (isTokenExpired(token))
+        return false;
+    if (!token.email || !token.id)
+        return false;
+    return true;
+}
+/**
+ * 특정 역할을 가지고 있는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @param role 확인할 역할
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 역할 보유 여부
+ */
+function hasRole(token, role, serviceId = 'checkon') {
+    if (!token)
+        return false;
+    const effectiveRole = getEffectiveRole(token, serviceId);
+    return effectiveRole === role;
+}
+/**
+ * 여러 역할 중 하나라도 가지고 있는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @param roles 확인할 역할 배열
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 역할 보유 여부
+ */
+function hasAnyRole(token, roles, serviceId = 'checkon') {
+    if (!token)
+        return false;
+    const effectiveRole = getEffectiveRole(token, serviceId);
+    return roles.includes(effectiveRole || '');
+}
+/**
+ * 공개 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @param publicPaths 공개 경로 배열
+ * @returns 공개 경로 여부
+ */
+function isPublicPath(pathname, publicPaths) {
+    return publicPaths.some(path => pathname === path || pathname.startsWith(path));
+}
+/**
+ * API 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @returns API 경로 여부
+ */
+function isApiPath(pathname) {
+    return pathname.startsWith('/api/');
+}
+/**
+ * 보호된 API 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @param exemptPaths 제외할 경로 배열
+ * @returns 보호된 API 경로 여부
+ */
+function isProtectedApiPath(pathname, exemptPaths = []) {
+    if (!isApiPath(pathname))
+        return false;
+    return !exemptPaths.some(path => pathname.startsWith(path));
+}
+/**
+ * NextAuth 토큰과 자체 토큰을 모두 확인하는 통합 인증 체크 함수
+ * @param req NextRequest 객체
+ * @param secret JWT 서명에 사용할 secret key
+ * @param options 옵션
+ * @returns 인증 결과
+ */
+async function checkAuthentication(req, secret, options) {
+    const { cookiePrefix = 'checkon', getNextAuthToken, } = options || {};
+    // 1. NextAuth 토큰 확인
+    let nextAuthToken = null;
+    if (getNextAuthToken) {
+        nextAuthToken = await getNextAuthToken(req);
+    }
+    if (nextAuthToken && isValidToken(nextAuthToken)) {
+        return {
+            isAuthenticated: true,
+            token: nextAuthToken,
+        };
+    }
+    // 2. 자체 토큰 확인
+    const authCheck = await verifyAndRefreshToken(req, secret, options);
+    if (authCheck.response) {
+        return {
+            isAuthenticated: true,
+            response: authCheck.response,
+            payload: authCheck.payload,
+        };
+    }
+    if (authCheck.isValid && authCheck.payload) {
+        return {
+            isAuthenticated: true,
+            payload: authCheck.payload,
+        };
+    }
+    return {
+        isAuthenticated: false,
+        error: authCheck.error || 'NO_TOKEN',
+    };
+}