@thinkingcat/auth-utils 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
-# @thinkingcat/auth-token-utils
+# @thinkingcat/auth-utils
 
-ThinkingCat SSO 서비스를 위한 인증 토큰 유틸리티 패키지입니다. JWT 토큰 검증, NextAuth 세션 생성, 쿠키 설정 등의 기능을 제공합니다.
+ThinkingCat SSO 서비스를 위한 인증 유틸리티 패키지입니다. JWT 토큰 검증, NextAuth 세션 생성, 쿠키 설정, 역할 기반 접근 제어, 미들웨어 헬퍼 등의 광범위한 인증 기능을 제공합니다.
 
 ## 📑 목차 (Table of Contents)
 
@@ -35,19 +35,19 @@ ThinkingCat SSO 서비스를 위한 인증 토큰 유틸리티 패키지입니
 ### npm 사용
 
 ```bash
-npm install @thinkingcat/auth-token-utils
+npm install @thinkingcat/auth-utils
 ```
 
 ### yarn 사용
 
 ```bash
-yarn add @thinkingcat/auth-token-utils
+yarn add @thinkingcat/auth-utils
 ```
 
 ### pnpm 사용
 
 ```bash
-pnpm add @thinkingcat/auth-token-utils
+pnpm add @thinkingcat/auth-utils
 ```
 
 ## 📋 요구사항 (Requirements)
@@ -63,13 +63,13 @@ pnpm add @thinkingcat/auth-token-utils
 npm에 배포된 패키지를 사용할 때는 **별도의 설정이 필요하지 않습니다**. 바로 사용할 수 있습니다.
 
 ```bash
-npm install @thinkingcat/auth-token-utils
+npm install @thinkingcat/auth-utils
 ```
 
 ```json
 {
   "dependencies": {
-    "@thinkingcat/auth-token-utils": "^1.0.0"
+    "@thinkingcat/auth-utils": "^1.0.4"
   }
 }
 ```
@@ -87,7 +87,7 @@ npm install @thinkingcat/auth-token-utils
 ```typescript
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  transpilePackages: ["@thinkingcat/auth-token-utils"],
+  transpilePackages: ["@thinkingcat/auth-utils"],
   // ... 기타 설정
 };
 
@@ -107,7 +107,7 @@ module.exports = nextConfig;
 ```json
 {
   "dependencies": {
-    "@thinkingcat/auth-token-utils": "^1.0.0"
+    "@thinkingcat/auth-utils": "^1.0.4"
   }
 }
 ```
@@ -134,7 +134,7 @@ import {
   ServiceInfo,
   ResponseLike,
   JWTPayload,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 ```
 
 ### 2. 환경 변수 설정
@@ -158,6 +158,12 @@ COOKIE_DOMAIN=.yourdomain.com  # 선택사항
 5. **쿠키 설정**: 자체 토큰 및 NextAuth 토큰 쿠키 설정
 6. **리다이렉트 HTML**: 클라이언트 리다이렉트용 HTML 생성
 7. **완전한 인증 응답**: 모든 인증 단계를 한 번에 처리
+8. **미들웨어 헬퍼**: 에러 리다이렉트, 쿠키 삭제, SSO 로그인 리다이렉트 등
+9. **역할 기반 접근 제어**: 경로별 역할 검증 및 접근 제어
+10. **구독 검증**: 서비스 구독 상태 확인
+11. **토큰 유효성 검사**: 토큰 만료 및 유효성 확인
+12. **경로 체크**: 공개 경로, API 경로, 보호된 경로 확인
+13. **통합 인증 체크**: NextAuth와 자체 토큰을 모두 확인하는 통합 함수
 
 ## 🔧 API 레퍼런스
 
@@ -412,7 +418,7 @@ import {
   setCustomTokens,
   createRedirectHTML,
   JWTPayload,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 
 export async function GET(req: NextRequest) {
   // URL 파라미터에서 토큰 가져오기 (초기 로그인 시)
@@ -458,7 +464,7 @@ export async function GET(req: NextRequest) {
 
 ```typescript
 import { NextRequest, NextResponse } from "next/server";
-import { verifyToken, JWTPayload } from "@thinkingcat/auth-token-utils";
+import { verifyToken, JWTPayload } from "@thinkingcat/auth-utils";
 
 export async function GET(req: NextRequest) {
   const secret = process.env.NEXTAUTH_SECRET!;
@@ -530,7 +536,7 @@ import {
   createNextAuthJWT,
   encodeNextAuthToken,
   setNextAuthToken,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 
 export async function GET(req: NextRequest) {
   const tokenParam = req.nextUrl.searchParams.get("token");
@@ -574,7 +580,7 @@ import {
   setCustomTokens,
   setNextAuthToken,
   createRedirectHTML,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 
 export async function GET(req: NextRequest) {
   const tokenParam = req.nextUrl.searchParams.get("token");
@@ -642,7 +648,7 @@ import {
   setNextAuthToken,
   createNextAuthJWT,
   encodeNextAuthToken,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 
 export async function middleware(req: NextRequest) {
   const secret = process.env.NEXTAUTH_SECRET!;
@@ -857,7 +863,7 @@ import type {
   SSORefreshTokenResponse,
   SSOGetRefreshTokenResponse,
   SSORegisterResponse,
-} from "@thinkingcat/auth-token-utils";
+} from "@thinkingcat/auth-utils";
 
 // SSO API 호출 시 타입 사용
 const response = await fetch("/api/sso/refresh", {
@@ -896,13 +902,13 @@ interface ResponseLike {
 
 ## 🐛 문제 해결 (Troubleshooting)
 
-### 문제 1: "Cannot find module '@thinkingcat/auth-token-utils'"
+### 문제 1: "Cannot find module '@thinkingcat/auth-utils'"
 
 **해결 방법:**
 
 ```bash
 # 패키지 재설치
-npm install @thinkingcat/auth-token-utils
+npm install @thinkingcat/auth-utils
 
 # 또는 node_modules 삭제 후 재설치
 rm -rf node_modules package-lock.json
@@ -932,8 +938,8 @@ npm install
 
 ## 📦 패키지 정보
 
-- **패키지명**: `@thinkingcat/auth-token-utils`
-- **버전**: `1.0.0`
+- **패키지명**: `@thinkingcat/auth-utils`
+- **버전**: `1.0.4`
 - **라이선스**: MIT
 - **저장소**: npm registry
 

package/dist/index.d.ts

@@ -291,6 +291,29 @@ export interface RoleAccessConfig {
         allowedRoles?: string[];
     };
 }
+/**
+ * 미들웨어 설정 인터페이스
+ */
+export interface MiddlewareConfig {
+    /** 공개 접근 가능한 경로 배열 */
+    publicPaths?: string[];
+    /** 구독이 필요한 경로 배열 */
+    subscriptionRequiredPaths?: string[];
+    /** 구독 상태 확인을 제외할 API 경로 배열 */
+    subscriptionExemptApiPaths?: string[];
+    /** 인증 관련 API 경로 배열 */
+    authApiPaths?: string[];
+    /** 역할별 대시보드 경로 객체 */
+    rolePaths?: Record<string, string>;
+    /** 역할 기반 접근 제어 설정 */
+    roleAccessConfig?: RoleAccessConfig;
+    /** 서비스 ID */
+    serviceId?: string;
+    /** 시스템 관리자 역할명 (기본값: 'SYSTEM_ADMIN') */
+    systemAdminRole?: string;
+    /** 에러 페이지 경로 (기본값: '/error') */
+    errorPath?: string;
+}
 export declare function checkRoleAccess(pathname: string, role: string, roleConfig: RoleAccessConfig): {
     allowed: boolean;
     message?: string;
@@ -382,3 +405,31 @@ export declare function checkAuthentication(req: NextRequest, secret: string, op
     response?: NextResponse;
     error?: string;
 }>;
+/**
+ * NextAuth 토큰과 자체 토큰을 모두 확인하는 미들웨어용 함수
+ * NextAuth 토큰이 있으면 바로 통과, 없으면 자체 토큰을 확인
+ * @param req NextRequest 객체
+ * @param nextAuthToken NextAuth JWT 토큰 (null 가능)
+ * @param secret JWT 서명에 사용할 secret key
+ * @param options 옵션
+ * @returns 인증 결과
+ */
+export declare function verifyAndRefreshTokenWithNextAuth(req: NextRequest, nextAuthToken: JWT | null, secret: string, options?: {
+    cookiePrefix?: string;
+    isProduction?: boolean;
+    cookieDomain?: string;
+    text?: string;
+    ssoBaseURL?: string;
+    authServiceKey?: string;
+}): Promise<{
+    isValid: boolean;
+    response?: NextResponse;
+    error?: string;
+    payload?: JWTPayload;
+}>;
+/**
+ * 기본 미들웨어 설정을 생성하는 함수
+ * @param config 커스텀 설정 (선택사항)
+ * @returns 미들웨어 설정 객체
+ */
+export declare function createMiddlewareConfig(config?: Partial<MiddlewareConfig>): Required<Omit<MiddlewareConfig, 'serviceId'>> & Pick<MiddlewareConfig, 'serviceId'>;

package/dist/index.js

@@ -27,6 +27,8 @@ exports.isPublicPath = isPublicPath;
 exports.isApiPath = isApiPath;
 exports.isProtectedApiPath = isProtectedApiPath;
 exports.checkAuthentication = checkAuthentication;
+exports.verifyAndRefreshTokenWithNextAuth = verifyAndRefreshTokenWithNextAuth;
+exports.createMiddlewareConfig = createMiddlewareConfig;
 const jwt_1 = require("next-auth/jwt");
 const jose_1 = require("jose");
 const server_1 = require("next/server");
@@ -707,3 +709,86 @@ async function checkAuthentication(req, secret, options) {
         error: authCheck.error || 'NO_TOKEN',
     };
 }
+/**
+ * NextAuth 토큰과 자체 토큰을 모두 확인하는 미들웨어용 함수
+ * NextAuth 토큰이 있으면 바로 통과, 없으면 자체 토큰을 확인
+ * @param req NextRequest 객체
+ * @param nextAuthToken NextAuth JWT 토큰 (null 가능)
+ * @param secret JWT 서명에 사용할 secret key
+ * @param options 옵션
+ * @returns 인증 결과
+ */
+async function verifyAndRefreshTokenWithNextAuth(req, nextAuthToken, secret, options) {
+    // 1. NextAuth 토큰이 있고 유효하면 통과
+    if (nextAuthToken && isValidToken(nextAuthToken)) {
+        return { isValid: true };
+    }
+    // 2. 자체 토큰 확인 및 리프레시
+    const authCheck = await verifyAndRefreshToken(req, secret, options);
+    return authCheck;
+}
+/**
+ * 기본 미들웨어 설정을 생성하는 함수
+ * @param config 커스텀 설정 (선택사항)
+ * @returns 미들웨어 설정 객체
+ */
+function createMiddlewareConfig(config) {
+    const defaultConfig = {
+        publicPaths: [
+            '/robots.txt',
+            '/sitemap.xml',
+            '/ads.txt',
+            '/images',
+            '/login',
+            '/register',
+            '/forgot-password',
+            '/reset-password',
+            '/about',
+            '/pricing',
+            '/support',
+            '/terms',
+            '/privacy',
+            '/refund',
+            '/error',
+        ],
+        subscriptionRequiredPaths: [
+            '/admin',
+            '/teacher',
+            '/student',
+            '/personal',
+        ],
+        subscriptionExemptApiPaths: [
+            '/api/auth',
+            '/api/sso',
+            '/api/admin/subscription',
+            '/api/admin/payment-methods',
+        ],
+        authApiPaths: [
+            '/api/auth/send-verification',
+            '/api/auth/verify-code',
+            '/api/auth/verify-user',
+            '/api/auth/select-academy',
+        ],
+        rolePaths: {
+            SYSTEM_ADMIN: '/system',
+            ADMIN: '/admin',
+            TEACHER: '/teacher',
+            STUDENT: '/student',
+        },
+        roleAccessConfig: {},
+        systemAdminRole: 'SYSTEM_ADMIN',
+        errorPath: '/error',
+        serviceId: config?.serviceId,
+    };
+    // 커스텀 설정으로 병합
+    return {
+        ...defaultConfig,
+        ...config,
+        publicPaths: config?.publicPaths || defaultConfig.publicPaths,
+        subscriptionRequiredPaths: config?.subscriptionRequiredPaths || defaultConfig.subscriptionRequiredPaths,
+        subscriptionExemptApiPaths: config?.subscriptionExemptApiPaths || defaultConfig.subscriptionExemptApiPaths,
+        authApiPaths: config?.authApiPaths || defaultConfig.authApiPaths,
+        rolePaths: config?.rolePaths || defaultConfig.rolePaths,
+        roleAccessConfig: config?.roleAccessConfig || defaultConfig.roleAccessConfig,
+    };
+}

package/package.json

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