@thinkingcat/auth-utils 1.0.6 → 1.0.9

package/README.md

@@ -10,25 +10,16 @@ ThinkingCat SSO 서비스를 위한 인증 유틸리티 패키지입니다. JWT
 - [🚀 빠른 시작 (Quick Start)](#-빠른-시작-quick-start)
 - [📚 주요 기능 (Features)](#-주요-기능-features)
 - [🔧 API 레퍼런스](#-api-레퍼런스)
-  - [1. verifyToken](#1-verifytokenaccesstoken-string-secret-string)
-  - [2. extractRoleFromPayload](#2-extractrolefrompayloadpayload-jwtpayload-serviceid-string-defaultrole-string)
-  - [3. createNextAuthJWT](#3-createnextauthjwtpayload-jwtpayload-includeacademies-boolean)
-  - [4. encodeNextAuthToken](#4-encodenextauthtokenjwt-jwt-secret-string-maxage-number)
-  - [5. setCustomTokens](#5-setcustomtokensresponse-responselike-accesstoken-string-optionsorrefreshtoken-options)
-  - [6. setNextAuthToken](#6-setnextauthtokenresponse-responselike-sessiontoken-string-options)
-  - [7. createRedirectHTML](#7-createredirecthtmlredirectpath-string-text-string)
-  - [8. createAuthResponse](#8-createauthresponseaccesstoken-string-secret-string-options)
+  - [토큰 검증 및 생성](#토큰-검증-및-생성)
+  - [쿠키 관리](#쿠키-관리)
+  - [역할 및 접근 제어](#역할-및-접근-제어)
+  - [SSO 통합](#sso-통합)
+  - [미들웨어](#미들웨어)
 - [💡 사용 시나리오](#-사용-시나리오)
-  - [시나리오 1: 자체 토큰만 사용하는 서비스](#시나리오-1-자체-토큰만-사용하는-서비스)
-  - [시나리오 2: NextAuth만 사용하는 서비스](#시나리오-2-nextauth만-사용하는-서비스)
-  - [시나리오 3: 자체 토큰 + NextAuth 모두 사용 (check-on 예시)](#시나리오-3-자체-토큰--nextauth-모두-사용-check-on-예시)
-  - [시나리오 4: Middleware에서 사용](#시나리오-4-middleware에서-사용)
 - [🔒 보안 고려사항](#-보안-고려사항)
 - [📝 타입 정의](#-타입-정의)
 - [🐛 문제 해결 (Troubleshooting)](#-문제-해결-troubleshooting)
 - [📦 패키지 정보](#-패키지-정보)
-- [🤝 기여 (Contributing)](#-기여-contributing)
-- [📄 라이선스 (License)](#-라이선스-license)
 
 ## 📦 설치 (Installation)
 
@@ -69,7 +60,7 @@ npm install @thinkingcat/auth-utils
 ```json
 {
   "dependencies": {
-    "@thinkingcat/auth-utils": "^1.0.4"
+    "@thinkingcat/auth-utils": "^1.0.8"
   }
 }
 ```
@@ -94,28 +85,9 @@ const nextConfig = {
 module.exports = nextConfig;
 ```
 
-**왜 필요한가?**
-
-- Next.js는 기본적으로 `node_modules`의 패키지를 트랜스파일하지 않습니다
-- 로컬 패키지를 사용할 때는 Next.js가 소스 코드를 직접 처리해야 할 수 있습니다
-- `transpilePackages`는 Next.js에게 해당 패키지를 트랜스파일하라고 지시합니다
-
 **해결 방법 2: npm에 배포된 버전 사용 (가장 안정적)**
 
-로컬 패키지 대신 npm에 배포된 버전을 사용하면 설정이 필요 없습니다:
-
-```json
-{
-  "dependencies": {
-    "@thinkingcat/auth-utils": "^1.0.4"
-  }
-}
-```
-
-**권장사항**:
-
-- **프로덕션 환경**: npm에 배포된 버전 사용 (설정 불필요)
-- **개발 환경**: 로컬 패키지 사용 시 `transpilePackages` 추가
+로컬 패키지 대신 npm에 배포된 버전을 사용하면 설정이 필요 없습니다.
 
 ## 🚀 빠른 시작 (Quick Start)
 
@@ -123,30 +95,83 @@ module.exports = nextConfig;
 
 ```typescript
 import {
+  // 토큰 검증 및 생성
   verifyToken,
   extractRoleFromPayload,
   createNextAuthJWT,
   encodeNextAuthToken,
+
+  // 쿠키 관리
   setCustomTokens,
   setNextAuthToken,
+  clearAuthCookies,
+
+  // 리다이렉트 및 응답
   createRedirectHTML,
   createAuthResponse,
+  redirectToError,
+  redirectToSSOLogin,
+  redirectToRoleDashboard,
+
+  // 역할 및 접근 제어
+  getEffectiveRole,
+  hasRole,
+  hasAnyRole,
+  checkRoleAccess,
+  requiresSubscription,
+
+  // 경로 체크
+  isPublicPath,
+  isApiPath,
+  isProtectedApiPath,
+
+  // 토큰 유효성 검사
+  isTokenExpired,
+  isValidToken,
+
+  // SSO 통합
+  refreshSSOToken,
+  getRefreshTokenFromSSO,
+  verifyTokenFromSSO,
+  validateServiceSubscription,
+
+  // 미들웨어
+  createMiddlewareConfig,
+  handleMiddleware,
+  verifyAndRefreshTokenWithNextAuth,
+  
+  // 라이센스
+  checkLicenseKey,
+
+  // 타입
   ServiceInfo,
   ResponseLike,
   JWTPayload,
+  MiddlewareConfig,
+  MiddlewareOptions,
 } from "@thinkingcat/auth-utils";
 ```
 
-### 2. 환경 변수 설정
+### 2. 라이센스 키 설정 (선택사항)
 
-`.env.local` 파일에 다음 환경 변수를 설정하세요:
+라이센스 키를 사용하려면 `.env.local` 파일에 다음 환경 변수를 설정하세요:
 
 ```env
-NEXTAUTH_SECRET=your-secret-key-here
-NODE_ENV=production  # 또는 development
-COOKIE_DOMAIN=.yourdomain.com  # 선택사항
+# 단일 라이센스 키 (가장 간단)
+LICENSE_KEY=TC-checkon-XXXX-XXXX
+
+# 또는 여러 서비스별 키 목록
+LICENSE_KEYS={"checkon":"TC-checkon-XXXX-XXXX","renton":"TC-renton-YYYY-YYYY"}
 ```
 
+**중요**:
+
+- 라이센스 키는 선택사항입니다. 제공하지 않으면 라이센스 검증을 건너뜁니다.
+- `LICENSE_KEY` 환경 변수를 설정하면 함수 호출 시 자동으로 사용됩니다.
+- 함수 파라미터로 `licenseKey`를 전달하면 환경 변수보다 우선합니다.
+- 다른 환경 변수(NEXTAUTH_SECRET, SSO_BASE_URL 등)는 이 패키지를 사용하는 애플리케이션에서 관리합니다.
+- `.env.example` 파일을 참조하여 라이센스 키 설정 방법을 확인하세요.
+
 ## 📚 주요 기능 (Features)
 
 이 패키지는 다음 기능을 제공합니다:
@@ -164,10 +189,14 @@ COOKIE_DOMAIN=.yourdomain.com  # 선택사항
 11. **토큰 유효성 검사**: 토큰 만료 및 유효성 확인
 12. **경로 체크**: 공개 경로, API 경로, 보호된 경로 확인
 13. **통합 인증 체크**: NextAuth와 자체 토큰을 모두 확인하는 통합 함수
+14. **미들웨어 통합**: 완전한 미들웨어 핸들러 함수 제공
+15. **설정 관리**: 미들웨어 설정 생성 및 관리 함수
 
 ## 🔧 API 레퍼런스
 
-### 1. `verifyToken(accessToken: string, secret: string)`
+### 토큰 검증 및 생성
+
+#### `verifyToken(accessToken: string, secret: string, licenseKey: string)`
 
 JWT access token을 검증하고 디코딩합니다.
 
@@ -175,6 +204,7 @@ JWT access token을 검증하고 디코딩합니다.
 
 - `accessToken`: 검증할 JWT 토큰
 - `secret`: JWT 서명에 사용할 secret key
+- `licenseKey`: 라이센스 키 (필수)
 
 **반환값:**
 
@@ -185,7 +215,8 @@ JWT access token을 검증하고 디코딩합니다.
 
 ```typescript
 const secret = process.env.NEXTAUTH_SECRET!;
-const result = await verifyToken(accessToken, secret);
+const licenseKey = process.env.LICENSE_KEY!;
+const result = await verifyToken(accessToken, secret, licenseKey);
 
 if (result) {
   const { payload } = result;
@@ -196,14 +227,14 @@ if (result) {
 }
 ```
 
-### 2. `extractRoleFromPayload(payload: JWTPayload, serviceId?: string, defaultRole?: string)`
+#### `extractRoleFromPayload(payload: JWTPayload, serviceId: string, defaultRole?: string)`
 
 payload에서 특정 서비스의 역할을 추출합니다.
 
 **파라미터:**
 
 - `payload`: JWT payload 객체 (JWTPayload 타입)
-- `serviceId`: 서비스 ID (기본값: 'checkon')
+- `serviceId`: 서비스 ID (필수)
 - `defaultRole`: 기본 역할 (기본값: 'ADMIN')
 
 **반환값:**
@@ -213,17 +244,18 @@ payload에서 특정 서비스의 역할을 추출합니다.
 **사용 예시:**
 
 ```typescript
-const role = extractRoleFromPayload(payload, "checkon", "ADMIN");
+const role = extractRoleFromPayload(payload, "myservice", "ADMIN");
 // 'ADMIN', 'TEACHER', 'STUDENT' 등
 ```
 
-### 3. `createNextAuthJWT(payload: JWTPayload, includeAcademies?: boolean)`
+#### `createNextAuthJWT(payload: JWTPayload, serviceId: string, includeAcademies?: boolean)`
 
 NextAuth와 호환되는 JWT 객체를 생성합니다.
 
 **파라미터:**
 
 - `payload`: 원본 JWT payload (JWTPayload 타입)
+- `serviceId`: 서비스 ID (필수)
 - `includeAcademies`: academies 정보 포함 여부 (기본값: false)
 
 **반환값:**
@@ -233,11 +265,11 @@ NextAuth와 호환되는 JWT 객체를 생성합니다.
 **사용 예시:**
 
 ```typescript
-const jwt = createNextAuthJWT(payload, true);
+const jwt = createNextAuthJWT(payload, "myservice", true);
 // academies 정보가 포함된 JWT 객체
 ```
 
-### 4. `encodeNextAuthToken(jwt: JWT, secret: string, maxAge?: number)`
+#### `encodeNextAuthToken(jwt: JWT, secret: string, maxAge?: number)`
 
 NextAuth JWT 객체를 인코딩된 세션 토큰으로 변환합니다.
 
@@ -255,11 +287,13 @@ NextAuth JWT 객체를 인코딩된 세션 토큰으로 변환합니다.
 
 ```typescript
 const secret = process.env.NEXTAUTH_SECRET!;
-const jwt = createNextAuthJWT(payload);
+const jwt = createNextAuthJWT(payload, "myservice");
 const sessionToken = await encodeNextAuthToken(jwt, secret);
 ```
 
-### 5. `setCustomTokens(response: ResponseLike, accessToken: string, optionsOrRefreshToken?, options?)`
+### 쿠키 관리
+
+#### `setCustomTokens(response: ResponseLike, accessToken: string, optionsOrRefreshToken?, options?)`
 
 자체 토큰(access token, refresh token)만 쿠키에 설정합니다.
 
@@ -274,46 +308,32 @@ const sessionToken = await encodeNextAuthToken(jwt, secret);
 
 **옵션:**
 
-- `cookiePrefix`: 쿠키 이름 접두사 (기본값: 'checkon')
+- `cookiePrefix`: 쿠키 이름 접두사 (필수)
 - `isProduction`: 프로덕션 환경 여부 (기본값: false)
 - `refreshToken`: refresh token (옵션 객체 내부에 포함 가능)
 
 **사용 예시:**
 
-**방법 1: refreshToken이 있는 경우**
-
 ```typescript
+// 방법 1: refreshToken이 있는 경우
 setCustomTokens(response, accessToken, refreshToken, {
   cookiePrefix: "myservice",
   isProduction: process.env.NODE_ENV === "production",
 });
-```
-
-**방법 2: refreshToken이 없는 경우**
 
-```typescript
+// 방법 2: refreshToken이 없는 경우
 setCustomTokens(response, accessToken, {
   cookiePrefix: "myservice",
   isProduction: process.env.NODE_ENV === "production",
 });
 ```
 
-**방법 3: 옵션 객체에 refreshToken 포함**
-
-```typescript
-setCustomTokens(response, accessToken, {
-  refreshToken: refreshToken,
-  cookiePrefix: "myservice",
-  isProduction: true,
-});
-```
-
 **설정되는 쿠키:**
 
 - `{cookiePrefix}_access_token`: 15분 유효
 - `{cookiePrefix}_refresh_token`: 30일 유효 (있는 경우)
 
-### 6. `setNextAuthToken(response: ResponseLike, sessionToken: string, options?)`
+#### `setNextAuthToken(response: ResponseLike, sessionToken: string, options?)`
 
 NextAuth 세션 토큰만 쿠키에 설정합니다.
 
@@ -343,14 +363,384 @@ setNextAuthToken(response, sessionToken, {
 - 프로덕션: `__Secure-next-auth.session-token`
 - 유효 기간: 30일
 
-### 7. `createRedirectHTML(redirectPath: string, text?: string)`
+#### `clearAuthCookies(response: NextResponse, cookiePrefix: string)`
+
+인증 쿠키를 삭제합니다.
+
+**파라미터:**
+
+- `response`: NextResponse 객체
+- `cookiePrefix`: 쿠키 이름 접두사 (필수)
+
+**사용 예시:**
+
+```typescript
+const response = NextResponse.redirect("/login");
+clearAuthCookies(response, "myservice");
+return response;
+```
+
+### 역할 및 접근 제어
+
+#### `getEffectiveRole(payload: JWTPayload, serviceId: string, defaultRole?: string)`
+
+payload에서 유효한 역할을 가져옵니다.
+
+**파라미터:**
+
+- `payload`: JWT payload 객체
+- `serviceId`: 서비스 ID (필수)
+- `defaultRole`: 기본 역할 (기본값: 'ADMIN')
+
+**반환값:**
+
+- 역할 문자열
+
+#### `hasRole(payload: JWTPayload, serviceId: string, role: string)`
+
+payload에 특정 역할이 있는지 확인합니다.
+
+**파라미터:**
+
+- `payload`: JWT payload 객체
+- `serviceId`: 서비스 ID (필수)
+- `role`: 확인할 역할
+
+**반환값:**
+
+- `boolean`
+
+#### `hasAnyRole(payload: JWTPayload, serviceId: string, roles: string[])`
+
+payload에 여러 역할 중 하나라도 있는지 확인합니다.
+
+**파라미터:**
+
+- `payload`: JWT payload 객체
+- `serviceId`: 서비스 ID (필수)
+- `roles`: 확인할 역할 배열
+
+**반환값:**
+
+- `boolean`
+
+#### `checkRoleAccess(pathname: string, role: string, config: RoleAccessConfig[])`
+
+경로에 대한 역할 접근 권한을 확인합니다.
+
+**파라미터:**
+
+- `pathname`: 경로
+- `role`: 사용자 역할
+- `config`: 역할 접근 설정 배열
+
+**반환값:**
+
+- `{ allowed: boolean; message?: string }`
+
+#### `requiresSubscription(pathname: string, role: string, subscriptionRequiredPaths: string[], systemAdminRole?: string)`
+
+경로가 구독이 필요한지 확인합니다.
+
+**파라미터:**
+
+- `pathname`: 경로
+- `role`: 사용자 역할
+- `subscriptionRequiredPaths`: 구독이 필요한 경로 배열
+- `systemAdminRole`: 시스템 관리자 역할 (선택사항)
+
+**반환값:**
+
+- `boolean`
+
+### SSO 통합
+
+#### `refreshSSOToken(refreshToken: string, options: { ssoBaseURL: string; authServiceKey?: string })`
+
+SSO 서버에서 refresh token을 사용하여 새로운 access token을 발급받습니다.
+
+**파라미터:**
+
+- `refreshToken`: refresh token
+- `options.ssoBaseURL`: SSO 서버 기본 URL (필수)
+- `options.authServiceKey`: 인증 서비스 키 (선택사항)
+
+**반환값:**
+
+- `SSORefreshTokenResponse`
+
+**사용 예시:**
+
+```typescript
+const result = await refreshSSOToken(refreshToken, {
+  ssoBaseURL: process.env.SSO_BASE_URL!,
+  authServiceKey: process.env.AUTH_SERVICE_SECRET_KEY,
+});
+```
+
+#### `getRefreshTokenFromSSO(userId: string, accessToken: string, options: { ssoBaseURL: string; authServiceKey?: string })`
+
+SSO 서버에서 사용자의 refresh token을 가져옵니다.
+
+**파라미터:**
+
+- `userId`: 사용자 ID
+- `accessToken`: access token
+- `options.ssoBaseURL`: SSO 서버 기본 URL (필수)
+- `options.authServiceKey`: 인증 서비스 키 (선택사항)
+
+**반환값:**
+
+- `string | null`
+
+#### `verifyTokenFromSSO(accessToken: string, options: { ssoBaseURL: string; authServiceKey?: string })`
+
+SSO 서버에서 토큰을 검증합니다.
+
+**파라미터:**
+
+- `accessToken`: access token
+- `options.ssoBaseURL`: SSO 서버 기본 URL (필수)
+- `options.authServiceKey`: 인증 서비스 키 (선택사항)
+
+**반환값:**
+
+- `Promise<{ isValid: boolean; payload?: JWTPayload }>`
+
+#### `validateServiceSubscription(services: ServiceInfo[], serviceId: string, ssoBaseURL: string)`
+
+서비스 구독 상태를 확인합니다.
+
+**파라미터:**
+
+- `services`: 서비스 정보 배열
+- `serviceId`: 서비스 ID
+- `ssoBaseURL`: SSO 서버 기본 URL (필수)
+
+**반환값:**
+
+- `{ isValid: boolean; redirectUrl?: string }`
+
+### 미들웨어
+
+#### `createMiddlewareConfig(config: Partial<MiddlewareConfig> & { serviceId: string }, defaults?)`
+
+미들웨어 설정을 생성합니다.
+
+**파라미터:**
+
+- `config`: 미들웨어 설정 객체 (serviceId 필수)
+- `defaults`: 기본 설정값 (선택사항)
+
+**반환값:**
+
+- 완전한 미들웨어 설정 객체
+
+**사용 예시:**
+
+```typescript
+import { createMiddlewareConfig } from "@thinkingcat/auth-utils";
+
+const middlewareConfig = createMiddlewareConfig({
+  serviceId: "myservice",
+  publicPaths: ["/login", "/register"],
+  roleAccessConfig: [
+    {
+      paths: ["/admin"],
+      role: "ADMIN",
+      message: "관리자만 접근할 수 있습니다.",
+    },
+  ],
+});
+```
+
+#### `handleMiddleware(req: NextRequest, config: MiddlewareConfig, options: MiddlewareOptions)`
+
+통합 미들웨어 핸들러 함수입니다. 모든 인증, 권한, 구독 체크를 포함합니다.
+
+**파라미터:**
+
+- `req`: NextRequest 객체
+- `config`: 미들웨어 설정 (createMiddlewareConfig로 생성)
+- `options`: 미들웨어 실행 옵션
+
+**옵션:**
+
+- `secret`: NextAuth Secret (필수)
+- `isProduction`: 프로덕션 환경 여부 (필수)
+- `cookieDomain`: 쿠키 도메인 (선택사항)
+- `getNextAuthToken`: NextAuth 토큰을 가져오는 함수 (선택사항)
+- `ssoBaseURL`: SSO 서버 기본 URL (필수)
+- `authServiceKey`: 인증 서비스 키 (선택사항)
+
+**반환값:**
+
+- NextResponse 또는 null (다음 미들웨어로 진행)
+
+**사용 예시:**
+
+```typescript
+import { withAuth } from "next-auth/middleware";
+import { NextRequest, NextResponse } from "next/server";
+import { getToken } from "next-auth/jwt";
+import {
+  createMiddlewareConfig,
+  handleMiddleware,
+} from "@thinkingcat/auth-utils";
+
+const middlewareConfig = createMiddlewareConfig({
+  serviceId: "myservice",
+  publicPaths: ["/login", "/register"],
+  roleAccessConfig: [
+    {
+      paths: ["/admin"],
+      role: "ADMIN",
+      message: "관리자만 접근할 수 있습니다.",
+    },
+  ],
+});
+
+export default withAuth(
+  async function middleware(req: NextRequest) {
+    const response = await handleMiddleware(req, middlewareConfig, {
+      secret: process.env.NEXTAUTH_SECRET!,
+      isProduction: process.env.NODE_ENV === "production",
+      cookieDomain: process.env.COOKIE_DOMAIN,
+      ssoBaseURL: process.env.SSO_BASE_URL!,
+      getNextAuthToken: async (req: NextRequest) => {
+        return await getToken({ req, secret: process.env.NEXTAUTH_SECRET! });
+      },
+      authServiceKey: process.env.AUTH_SERVICE_SECRET_KEY,
+    });
+    return response || NextResponse.next();
+  },
+  {
+    callbacks: {
+      authorized: () => true,
+    },
+  }
+);
+```
+
+#### `verifyAndRefreshTokenWithNextAuth(req: NextRequest, secret: string, cookiePrefix: string, serviceId: string, options: { ssoBaseURL: string; authServiceKey?: string; getNextAuthToken?: (req: NextRequest) => Promise<JWT | null> })`
+
+NextAuth 토큰을 먼저 확인하고, 없으면 자체 토큰을 확인하고 필요시 리프레시합니다.
+
+**파라미터:**
+
+- `req`: NextRequest 객체
+- `secret`: JWT 서명에 사용할 secret key
+- `cookiePrefix`: 쿠키 이름 접두사
+- `serviceId`: 서비스 ID (필수)
+- `options`: 옵션 객체
+
+**반환값:**
+
+- `Promise<{ isValid: boolean; payload?: JWTPayload; error?: string }>`
+
+### 경로 체크
+
+#### `isPublicPath(pathname: string, publicPaths: string[])`
+
+경로가 공개 경로인지 확인합니다.
+
+**파라미터:**
+
+- `pathname`: 경로
+- `publicPaths`: 공개 경로 배열
+
+**반환값:**
+
+- `boolean`
+
+#### `isApiPath(pathname: string)`
+
+경로가 API 경로인지 확인합니다.
+
+**파라미터:**
+
+- `pathname`: 경로
+
+**반환값:**
+
+- `boolean`
+
+#### `isProtectedApiPath(pathname: string, authApiPaths: string[])`
+
+경로가 보호된 API 경로인지 확인합니다.
+
+**파라미터:**
+
+- `pathname`: 경로
+- `authApiPaths`: 인증이 필요한 API 경로 배열
+
+**반환값:**
+
+- `boolean`
+
+### 토큰 유효성 검사
+
+#### `isTokenExpired(token: JWT | null)`
+
+토큰이 만료되었는지 확인합니다.
+
+**파라미터:**
+
+- `token`: JWT 객체 또는 null
+
+**반환값:**
+
+- `boolean`
+
+#### `isValidToken(token: JWT | null)`
+
+토큰이 유효한지 확인합니다.
+
+**파라미터:**
+
+- `token`: JWT 객체 또는 null
+
+**반환값:**
+
+- `boolean`
+
+### 라이센스 검증
+
+#### `checkLicenseKey(licenseKey: string)`
+
+라이센스 키를 검증합니다.
+
+**파라미터:**
+
+- `licenseKey`: 라이센스 키 (필수)
+
+**반환값:**
+
+- 없음 (유효하지 않으면 에러 발생)
+
+**사용 예시:**
+
+```typescript
+import { checkLicenseKey } from "@thinkingcat/auth-utils";
+
+try {
+  checkLicenseKey(process.env.LICENSE_KEY!);
+  console.log("라이센스 키가 유효합니다");
+} catch (error) {
+  console.error("라이센스 키 검증 실패:", error);
+}
+```
+
+### 리다이렉트 및 응답
+
+#### `createRedirectHTML(redirectPath: string, text: string)`
 
 클라이언트 리다이렉트용 HTML을 생성합니다.
 
 **파라미터:**
 
 - `redirectPath`: 리다이렉트할 경로
-- `text`: 표시할 텍스트 (기본값: 'checkon')
+- `text`: 표시할 텍스트 (필수)
 
 **반환값:**
 
@@ -359,14 +749,14 @@ setNextAuthToken(response, sessionToken, {
 **사용 예시:**
 
 ```typescript
-const html = createRedirectHTML("/dashboard", "checkon");
+const html = createRedirectHTML("/dashboard", "myservice");
 return new NextResponse(html, {
   status: 200,
   headers: { "Content-Type": "text/html" },
 });
 ```
 
-### 8. `createAuthResponse(accessToken: string, secret: string, options?)`
+#### `createAuthResponse(accessToken: string, secret: string, options)`
 
 완전한 인증 세션을 생성합니다. 토큰 검증부터 쿠키 설정까지 모든 과정을 처리합니다.
 
@@ -380,10 +770,11 @@ return new NextResponse(html, {
 
 - `refreshToken`: refresh token (선택)
 - `redirectPath`: 리다이렉트할 경로 (선택)
-- `text`: 리다이렉트 HTML에 표시할 텍스트 (기본값: 'checkon')
-- `cookiePrefix`: 쿠키 이름 접두사 (기본값: 'checkon')
+- `text`: 리다이렉트 HTML에 표시할 텍스트 (선택사항, serviceId가 기본값)
+- `cookiePrefix`: 쿠키 이름 접두사 (선택사항, serviceId가 기본값)
 - `isProduction`: 프로덕션 환경 여부 (기본값: false)
 - `cookieDomain`: 쿠키 도메인 (선택)
+- `serviceId`: 서비스 ID (필수)
 
 **반환값:**
 
@@ -396,55 +787,86 @@ const secret = process.env.NEXTAUTH_SECRET!;
 const response = await createAuthResponse(accessToken, secret, {
   refreshToken: refreshToken,
   redirectPath: "/dashboard",
-  text: "checkon",
-  cookiePrefix: "checkon",
+  text: "myservice",
+  cookiePrefix: "myservice",
   isProduction: process.env.NODE_ENV === "production",
   cookieDomain: process.env.COOKIE_DOMAIN,
+  serviceId: "myservice", // 필수
 });
 ```
 
+#### `redirectToError(req: NextRequest, errorType: string, message: string, errorPath?: string)`
+
+에러 페이지로 리다이렉트합니다.
+
+**파라미터:**
+
+- `req`: NextRequest 객체
+- `errorType`: 에러 타입
+- `message`: 에러 메시지
+- `errorPath`: 에러 페이지 경로 (기본값: '/error')
+
+**반환값:**
+
+- NextResponse 리다이렉트 응답
+
+#### `redirectToSSOLogin(req: NextRequest, serviceId: string, ssoBaseURL: string)`
+
+SSO 로그인 페이지로 리다이렉트합니다.
+
+**파라미터:**
+
+- `req`: NextRequest 객체
+- `serviceId`: 서비스 ID
+- `ssoBaseURL`: SSO 서버 기본 URL (필수)
+
+**반환값:**
+
+- NextResponse 리다이렉트 응답
+
+#### `redirectToRoleDashboard(req: NextRequest, role: string, rolePaths: Record<string, string>, defaultPath?: string)`
+
+역할별 대시보드 경로로 리다이렉트합니다.
+
+**파라미터:**
+
+- `req`: NextRequest 객체
+- `role`: 사용자 역할
+- `rolePaths`: 역할별 경로 매핑
+- `defaultPath`: 기본 경로 (기본값: '/admin')
+
+**반환값:**
+
+- NextResponse 리다이렉트 응답
+
 ## 💡 사용 시나리오
 
 ### 시나리오 1: 자체 토큰만 사용하는 서비스
 
 SSO에서 받은 토큰을 자체 쿠키에만 저장하는 경우:
 
-#### 1-1. URL 파라미터로 토큰을 받는 경우 (초기 로그인)
-
 ```typescript
 import { NextRequest, NextResponse } from "next/server";
 import {
   verifyToken,
   setCustomTokens,
   createRedirectHTML,
-  JWTPayload,
 } from "@thinkingcat/auth-utils";
 
 export async function GET(req: NextRequest) {
-  // URL 파라미터에서 토큰 가져오기 (초기 로그인 시)
   const tokenParam = req.nextUrl.searchParams.get("token");
-
   if (!tokenParam) {
     return NextResponse.redirect("/login");
   }
 
-  // 1. 토큰 검증 (중요: 모든 토큰은 사용 전에 반드시 검증해야 합니다)
   const secret = process.env.NEXTAUTH_SECRET!;
-  const tokenResult = await verifyToken(tokenParam, secret);
+  const licenseKey = process.env.LICENSE_KEY!;
+  const tokenResult = await verifyToken(tokenParam, secret, licenseKey);
 
-  // 2. 검증 실패 시 로그인 페이지로 리다이렉트
   if (!tokenResult) {
-    console.error("Token verification failed");
     return NextResponse.redirect("/login");
   }
 
-  // 3. 검증된 payload 확인 (선택적: 사용자 정보가 필요한 경우)
-  const { payload } = tokenResult;
-  console.log("Authenticated user:", payload.email);
-
-  // 4. 검증된 토큰을 쿠키에 저장
-  // 주의: verifyToken이 성공했다는 것은 토큰이 유효하고 서명이 올바르다는 의미입니다
-  // 따라서 원본 토큰을 안전하게 쿠키에 저장할 수 있습니다
   const html = createRedirectHTML("/dashboard", "myservice");
   const response = new NextResponse(html, {
     status: 200,
@@ -460,71 +882,6 @@ export async function GET(req: NextRequest) {
 }
 ```
 
-#### 1-2. 쿠키에서 토큰을 읽어서 검증하는 경우 (이미 로그인된 상태)
-
-```typescript
-import { NextRequest, NextResponse } from "next/server";
-import { verifyToken, JWTPayload } from "@thinkingcat/auth-utils";
-
-export async function GET(req: NextRequest) {
-  const secret = process.env.NEXTAUTH_SECRET!;
-
-  // 1. 쿠키에서 토큰 가져오기 (이미 로그인된 경우)
-  const cookieToken = req.cookies.get("myservice_access_token")?.value;
-
-  if (!cookieToken) {
-    // 토큰이 없으면 로그인 페이지로 리다이렉트
-    return NextResponse.redirect("/login");
-  }
-
-  // 2. 쿠키의 토큰 검증 (중요: 쿠키의 토큰도 반드시 검증해야 합니다)
-  const tokenResult = await verifyToken(cookieToken, secret);
-
-  if (!tokenResult) {
-    // 검증 실패 시 쿠키 삭제하고 로그인 페이지로 리다이렉트
-    const response = NextResponse.redirect("/login");
-    response.cookies.delete("myservice_access_token");
-    response.cookies.delete("myservice_refresh_token");
-    return response;
-  }
-
-  // 3. 검증 성공 - 사용자 정보 사용
-  const { payload } = tokenResult;
-  console.log("Authenticated user:", payload.email);
-
-  // 4. 정상 응답 반환
-  return NextResponse.json({
-    success: true,
-    user: {
-      email: payload.email,
-      name: payload.name,
-    },
-  });
-}
-```
-
-**토큰 검증 로직 설명:**
-
-1. **`verifyToken(token, secret)`**:
-
-   - JWT 토큰의 서명을 검증합니다
-   - 토큰이 만료되지 않았는지 확인합니다
-   - 토큰의 형식이 올바른지 확인합니다
-   - 검증 성공 시 `{ payload: JWTPayload }` 반환
-   - 검증 실패 시 `null` 반환
-
-2. **토큰 소스별 처리**:
-
-   - **URL 파라미터**: 초기 로그인 시 SSO에서 받은 토큰을 검증 후 쿠키에 저장
-   - **쿠키**: 이미 로그인된 상태에서 쿠키의 토큰을 검증하여 사용
-   - **중요**: 쿠키에 저장된 토큰도 매번 검증해야 합니다 (토큰이 만료되었을 수 있음)
-
-3. **검증 후 처리**:
-   - 검증이 성공하면 토큰이 유효하다는 것이 보장됩니다
-   - URL 파라미터로 받은 토큰은 검증 후 쿠키에 저장할 수 있습니다
-   - 쿠키에서 읽은 토큰은 검증 후 사용할 수 있습니다
-   - 필요시 `payload`에서 사용자 정보를 추출하여 사용할 수 있습니다
-
 ### 시나리오 2: NextAuth만 사용하는 서비스
 
 NextAuth 세션만 사용하는 경우:
@@ -540,20 +897,20 @@ import {
 
 export async function GET(req: NextRequest) {
   const tokenParam = req.nextUrl.searchParams.get("token");
-
   if (!tokenParam) {
     return NextResponse.redirect("/login");
   }
 
   const secret = process.env.NEXTAUTH_SECRET!;
-  const tokenResult = await verifyToken(tokenParam, secret);
+  const licenseKey = process.env.LICENSE_KEY!;
+  const tokenResult = await verifyToken(tokenParam, secret, licenseKey);
 
   if (!tokenResult) {
     return NextResponse.redirect("/login");
   }
 
   const { payload } = tokenResult;
-  const jwt = createNextAuthJWT(payload);
+  const jwt = createNextAuthJWT(payload, "myservice");
   const sessionToken = await encodeNextAuthToken(jwt, secret);
 
   const response = NextResponse.redirect("/dashboard");
@@ -566,7 +923,7 @@ export async function GET(req: NextRequest) {
 }
 ```
 
-### 시나리오 3: 자체 토큰 + NextAuth 모두 사용 (check-on 예시)
+### 시나리오 3: 자체 토큰 + NextAuth 모두 사용
 
 자체 토큰과 NextAuth 세션을 모두 사용하는 경우:
 
@@ -584,49 +941,38 @@ import {
 
 export async function GET(req: NextRequest) {
   const tokenParam = req.nextUrl.searchParams.get("token");
-
   if (!tokenParam) {
     return NextResponse.redirect("/login");
   }
 
   const secret = process.env.NEXTAUTH_SECRET!;
+  const licenseKey = process.env.LICENSE_KEY!;
   const isProduction = process.env.NODE_ENV === "production";
 
-  // 1. 토큰 검증
-  const tokenResult = await verifyToken(tokenParam, secret);
+  const tokenResult = await verifyToken(tokenParam, secret, licenseKey);
   if (!tokenResult) {
     return NextResponse.redirect("/login");
   }
 
   const { payload } = tokenResult;
+  const role = extractRoleFromPayload(payload, "myservice", "ADMIN");
 
-  // 2. 역할 추출
-  const role = extractRoleFromPayload(payload, "checkon", "ADMIN");
-
-  // 3. Refresh token 가져오기 (SSO API 호출 등)
-  let refreshToken = "";
-  // ... refreshToken 가져오는 로직 ...
-
-  // 4. NextAuth JWT 생성 및 인코딩
-  const jwt = createNextAuthJWT(payload);
+  const jwt = createNextAuthJWT(payload, "myservice");
   const sessionToken = await encodeNextAuthToken(jwt, secret);
 
-  // 5. 역할별 리다이렉트 경로 결정
   const redirectPath = role === "ADMIN" ? "/admin" : "/dashboard";
-  const html = createRedirectHTML(redirectPath, "checkon");
+  const html = createRedirectHTML(redirectPath, "myservice");
 
   const response = new NextResponse(html, {
     status: 200,
     headers: { "Content-Type": "text/html" },
   });
 
-  // 6. 자체 토큰 설정
-  setCustomTokens(response, tokenParam, refreshToken, {
-    cookiePrefix: "checkon",
+  setCustomTokens(response, tokenParam, {
+    cookiePrefix: "myservice",
     isProduction,
   });
 
-  // 7. NextAuth 토큰 설정
   setNextAuthToken(response, sessionToken, {
     isProduction,
     cookieDomain: process.env.COOKIE_DOMAIN,
@@ -636,71 +982,60 @@ export async function GET(req: NextRequest) {
 }
 ```
 
-### 시나리오 4: Middleware에서 사용
+### 시나리오 4: 미들웨어에서 통합 사용
 
-Next.js Middleware에서 토큰 검증 및 리프레시:
+Next.js Middleware에서 통합 미들웨어 핸들러 사용:
 
 ```typescript
+import { withAuth } from "next-auth/middleware";
 import { NextRequest, NextResponse } from "next/server";
+import { getToken } from "next-auth/jwt";
 import {
-  verifyToken,
-  setCustomTokens,
-  setNextAuthToken,
-  createNextAuthJWT,
-  encodeNextAuthToken,
+  createMiddlewareConfig,
+  handleMiddleware,
 } from "@thinkingcat/auth-utils";
 
-export async function middleware(req: NextRequest) {
-  const secret = process.env.NEXTAUTH_SECRET!;
-  const isProduction = process.env.NODE_ENV === "production";
-
-  // 1. 자체 토큰 확인
-  const accessToken = req.cookies.get("checkon_access_token")?.value;
-
-  if (accessToken) {
-    const tokenResult = await verifyToken(accessToken, secret);
-
-    if (tokenResult) {
-      // 토큰이 유효함
-      return NextResponse.next();
-    }
-
-    // 토큰이 만료됨 - 리프레시 시도
-    const refreshToken = req.cookies.get("checkon_refresh_token")?.value;
-
-    if (refreshToken) {
-      // SSO API로 토큰 리프레시
-      // ... refreshSSOToken 호출 ...
-
-      if (newAccessToken) {
-        const newTokenResult = await verifyToken(newAccessToken, secret);
-
-        if (newTokenResult) {
-          const { payload } = newTokenResult;
-          const jwt = createNextAuthJWT(payload);
-          const sessionToken = await encodeNextAuthToken(jwt, secret);
-
-          const response = NextResponse.next();
-
-          setCustomTokens(response, newAccessToken, {
-            cookiePrefix: "checkon",
-            isProduction,
-          });
-
-          setNextAuthToken(response, sessionToken, {
-            isProduction,
-            cookieDomain: process.env.COOKIE_DOMAIN,
-          });
+const middlewareConfig = createMiddlewareConfig({
+  serviceId: "myservice",
+  publicPaths: ["/login", "/register", "/api/public"],
+  subscriptionRequiredPaths: ["/premium"],
+  roleAccessConfig: [
+    {
+      paths: ["/admin"],
+      role: "ADMIN",
+      message: "관리자만 접근할 수 있습니다.",
+    },
+  ],
+  rolePaths: {
+    ADMIN: "/admin",
+    USER: "/dashboard",
+  },
+});
 
-          return response;
-        }
-      }
-    }
+export default withAuth(
+  async function middleware(req: NextRequest) {
+    const response = await handleMiddleware(req, middlewareConfig, {
+      secret: process.env.NEXTAUTH_SECRET!,
+      isProduction: process.env.NODE_ENV === "production",
+      cookieDomain: process.env.COOKIE_DOMAIN,
+      ssoBaseURL: process.env.SSO_BASE_URL!,
+      getNextAuthToken: async (req: NextRequest) => {
+        return await getToken({ req, secret: process.env.NEXTAUTH_SECRET! });
+      },
+      authServiceKey: process.env.AUTH_SERVICE_SECRET_KEY,
+    });
+    return response || NextResponse.next();
+  },
+  {
+    callbacks: {
+      authorized: () => true,
+    },
   }
+);
 
-  // 인증 실패 - 로그인 페이지로 리다이렉트
-  return NextResponse.redirect(new URL("/login", req.url));
-}
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
 ```
 
 ## 🔒 보안 고려사항
@@ -720,9 +1055,15 @@ export async function middleware(req: NextRequest) {
    - `httpOnly: true`로 설정되어 JavaScript에서 접근할 수 없습니다
 
 3. **토큰 검증**
+
    - 모든 토큰은 사용 전에 반드시 `verifyToken`으로 검증하세요
    - 검증 실패 시 적절한 에러 처리를 하세요
 
+4. **환경 변수**
+   - 이 패키지는 환경 변수를 직접 읽지 않습니다
+   - 모든 값은 함수 파라미터로 전달해야 합니다
+   - 하드코딩된 값(서비스 ID, URL 등)이 없도록 주의하세요
+
 ## 📝 타입 정의
 
 ### `JWTPayload`
@@ -789,31 +1130,48 @@ interface ServiceInfo {
 }
 ```
 
-### SSO API 응답 타입
+### `MiddlewareConfig`
+
+```typescript
+interface MiddlewareConfig {
+  serviceId: string;
+  publicPaths: string[];
+  subscriptionRequiredPaths: string[];
+  subscriptionExemptApiPaths: string[];
+  authApiPaths: string[];
+  roleAccessConfig: RoleAccessConfig[];
+  rolePaths: Record<string, string>;
+  systemAdminRole: string;
+  errorPath: string;
+}
+```
 
-#### `SSOUpsertResponse`
+### `MiddlewareOptions`
 
 ```typescript
-interface SSOUpsertResponse {
-  success: boolean;
-  message?: string;
-  user?: {
-    id: string;
-    email: string;
-    name: string;
-  };
+interface MiddlewareOptions {
+  secret: string;
+  isProduction: boolean;
+  cookieDomain?: string;
+  getNextAuthToken?: (req: NextRequest) => Promise<JWT | null>;
+  ssoBaseURL: string;
+  authServiceKey?: string;
 }
 ```
 
-#### `SSOErrorResponse`
+### `RoleAccessConfig`
 
 ```typescript
-interface SSOErrorResponse {
-  error: string;
+interface RoleAccessConfig {
+  paths: string[];
+  role: string;
+  allowedRoles?: string[];
   message?: string;
 }
 ```
 
+### SSO API 응답 타입
+
 #### `SSORefreshTokenResponse`
 
 ```typescript
@@ -840,44 +1198,6 @@ interface SSOGetRefreshTokenResponse {
 }
 ```
 
-#### `SSORegisterResponse`
-
-```typescript
-interface SSORegisterResponse {
-  success: boolean;
-  message?: string;
-  user?: {
-    id: string;
-    email: string;
-    name: string;
-  };
-}
-```
-
-### 사용 예시
-
-```typescript
-import type {
-  SSOUpsertResponse,
-  SSOErrorResponse,
-  SSORefreshTokenResponse,
-  SSOGetRefreshTokenResponse,
-  SSORegisterResponse,
-} from "@thinkingcat/auth-utils";
-
-// SSO API 호출 시 타입 사용
-const response = await fetch("/api/sso/refresh", {
-  method: "POST",
-  body: JSON.stringify({ refreshToken }),
-});
-
-const result = (await response.json()) as SSORefreshTokenResponse;
-if (result.success && result.accessToken) {
-  // 타입 안전하게 사용
-  console.log(result.accessToken);
-}
-```
-
 ### `ResponseLike`
 
 ```typescript
@@ -936,10 +1256,35 @@ npm install
 - 브라우저 개발자 도구에서 쿠키 설정 확인
 - 도메인 및 경로 설정 확인
 
+### 문제 5: "ssoBaseURL is required" 에러
+
+**해결 방법:**
+모든 SSO 관련 함수는 `ssoBaseURL`을 필수 파라미터로 받습니다. 환경 변수에서 값을 가져와서 전달하세요:
+
+```typescript
+const ssoBaseURL = process.env.SSO_BASE_URL!;
+if (!ssoBaseURL) {
+  throw new Error("SSO_BASE_URL environment variable is required");
+}
+```
+
+### 문제 6: "cookiePrefix is required" 에러
+
+**해결 방법:**
+`setCustomTokens`와 `clearAuthCookies` 함수는 `cookiePrefix`를 필수 파라미터로 받습니다. 서비스 ID를 사용하거나 명시적으로 전달하세요:
+
+```typescript
+const cookiePrefix = "myservice"; // 서비스별로 변경
+setCustomTokens(response, accessToken, {
+  cookiePrefix, // 필수
+  isProduction: true,
+});
+```
+
 ## 📦 패키지 정보
 
 - **패키지명**: `@thinkingcat/auth-utils`
-- **버전**: `1.0.4`
+- **버전**: `1.0.8`
 - **라이선스**: MIT
 - **저장소**: npm registry