@thinkingcat/auth-utils 1.0.14 → 1.0.16

package/README.md

@@ -60,7 +60,7 @@ npm install @thinkingcat/auth-utils
 ```json
 {
   "dependencies": {
-    "@thinkingcat/auth-utils": "^1.0.12"
+    "@thinkingcat/auth-utils": "^1.0.16"
   }
 }
 ```
@@ -140,6 +140,15 @@ import {
   handleMiddleware,
   verifyAndRefreshTokenWithNextAuth,
 
+  // NextAuth 설정 및 콜백
+  createNextAuthBaseConfig,
+  createNextAuthCookies,
+  handleJWTCallback,
+  createInitialJWTToken,
+  createEmptySession,
+  mapTokenToSession,
+  getJWTFromCustomTokenCookie,
+
   // 라이센스
   checkLicenseKey,
 
@@ -249,7 +258,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 +266,6 @@ NextAuth와 호환되는 JWT 객체를 생성합니다.
 
 - `payload`: 원본 JWT payload (JWTPayload 타입)
 - `serviceId`: 서비스 ID (필수)
-- `includeAcademies`: academies 정보 포함 여부 (기본값: false)
 
 **반환값:**
 
@@ -266,8 +274,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 +529,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 +1247,6 @@ interface JWTPayload {
   // 서비스 정보
   services?: ServiceInfo[];
 
-  // 학원 정보
-  academies?: Array<{
-    id: string;
-    name: string;
-    role: string;
-  }>;
-
   // 인증 상태
   phoneVerified?: boolean;
   emailVerified?: boolean;
@@ -1101,8 +1254,6 @@ interface JWTPayload {
 
   // 선택적 필드
   phone?: string;
-  academyId?: string;
-  academyName?: string;
   isPasswordReset?: boolean;
   decryptedEmail?: string;
   decryptedPhone?: string;
@@ -1308,7 +1459,7 @@ const response = await handleMiddleware(req, middlewareConfig, {
 ## 📦 패키지 정보
 
 - **패키지명**: `@thinkingcat/auth-utils`
-- **버전**: `1.0.12`
+- **버전**: `1.0.16`
 - **라이선스**: MIT
 - **저장소**: npm registry
 

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 객체
@@ -438,17 +430,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 +475,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;
@@ -116,10 +117,9 @@ 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';
@@ -129,9 +129,6 @@ function createNextAuthJWT(payload, serviceId, includeAcademies = false) {
         name: payload.name,
         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 +138,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)
@@ -736,28 +729,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 +749,49 @@ 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) {
+        console.log('[JWT Callback] Token received:', {
+            hasId: !!token.id,
+            hasEmail: !!token.email,
+            hasRole: !!token.role,
+            tokenKeys: Object.keys(token),
+        });
+    }
+    // 1. 초기 로그인 시 (providers를 통한 로그인)
+    if (account && user) {
+        return createInitialJWTToken(token, user, account);
+    }
+    // 2. 이미 토큰에 정보가 있으면 그대로 사용
+    if (token.id) {
+        return token;
+    }
+    // 3. 토큰에 id가 없는 경우 - 커스텀 토큰 쿠키에서 정보 읽기
+    if (secret && licenseKey && serviceId) {
+        const cookieNameToUse = cookieName || `${serviceId}_access_token`;
+        const jwt = await getJWTFromCustomTokenCookie(cookieNameToUse, secret, serviceId, licenseKey);
+        if (jwt) {
+            return jwt;
+        }
+    }
+    return token;
+}
 /**
  * 쿠키에서 커스텀 토큰을 읽어서 NextAuth JWT로 변환하는 헬퍼 함수
  * NextAuth JWT 콜백에서 사용
@@ -774,10 +799,9 @@ 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) {
     try {
         const { cookies } = await Promise.resolve().then(() => __importStar(require('next/headers')));
         const cookieStore = await cookies();
@@ -791,7 +815,7 @@ async function getJWTFromCustomTokenCookie(cookieName, secret, serviceId, licens
             return null;
         }
         const { payload } = tokenResult;
-        const jwt = createNextAuthJWT(payload, serviceId, includeAcademies);
+        const jwt = createNextAuthJWT(payload, serviceId);
         return jwt;
     }
     catch (error) {
@@ -1203,7 +1227,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);
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingcat/auth-utils",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Authentication utilities for ThinkingCat SSO services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",