@thinkingcat/auth-utils 1.0.4

package/README.md

@@ -0,0 +1,950 @@
+# @thinkingcat/auth-token-utils
+
+ThinkingCat SSO 서비스를 위한 인증 토큰 유틸리티 패키지입니다. JWT 토큰 검증, NextAuth 세션 생성, 쿠키 설정 등의 기능을 제공합니다.
+
+## 📑 목차 (Table of Contents)
+
+- [📦 설치 (Installation)](#-설치-installation)
+- [📋 요구사항 (Requirements)](#-요구사항-requirements)
+- [⚙️ Next.js 설정 (Next.js Configuration)](#️-nextjs-설정-nextjs-configuration)
+- [🚀 빠른 시작 (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)
+- [💡 사용 시나리오](#-사용-시나리오)
+  - [시나리오 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)
+
+### npm 사용
+
+```bash
+npm install @thinkingcat/auth-token-utils
+```
+
+### yarn 사용
+
+```bash
+yarn add @thinkingcat/auth-token-utils
+```
+
+### pnpm 사용
+
+```bash
+pnpm add @thinkingcat/auth-token-utils
+```
+
+## 📋 요구사항 (Requirements)
+
+- **Next.js**: >= 13.0.0
+- **Node.js**: >= 18.0.0
+- **TypeScript**: 권장 (타입 지원)
+
+## ⚙️ Next.js 설정 (Next.js Configuration)
+
+### npm에 배포된 패키지를 사용하는 경우 (권장)
+
+npm에 배포된 패키지를 사용할 때는 **별도의 설정이 필요하지 않습니다**. 바로 사용할 수 있습니다.
+
+```bash
+npm install @thinkingcat/auth-token-utils
+```
+
+```json
+{
+  "dependencies": {
+    "@thinkingcat/auth-token-utils": "^1.0.0"
+  }
+}
+```
+
+**설정 불필요**: npm에 배포된 패키지는 이미 빌드되어 있으므로 `next.config.ts`에 추가 설정이 필요 없습니다.
+
+### 로컬 패키지를 사용하는 경우 (개발 중)
+
+로컬 패키지(`file:../packages/auth-token-utils`)를 사용하는 경우, Next.js가 모듈을 찾지 못하는 오류가 발생할 수 있습니다.
+
+**해결 방법 1: transpilePackages 추가 (권장)**
+
+`next.config.ts`에 다음 설정을 추가하세요:
+
+```typescript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["@thinkingcat/auth-token-utils"],
+  // ... 기타 설정
+};
+
+module.exports = nextConfig;
+```
+
+**왜 필요한가?**
+
+- Next.js는 기본적으로 `node_modules`의 패키지를 트랜스파일하지 않습니다
+- 로컬 패키지를 사용할 때는 Next.js가 소스 코드를 직접 처리해야 할 수 있습니다
+- `transpilePackages`는 Next.js에게 해당 패키지를 트랜스파일하라고 지시합니다
+
+**해결 방법 2: npm에 배포된 버전 사용 (가장 안정적)**
+
+로컬 패키지 대신 npm에 배포된 버전을 사용하면 설정이 필요 없습니다:
+
+```json
+{
+  "dependencies": {
+    "@thinkingcat/auth-token-utils": "^1.0.0"
+  }
+}
+```
+
+**권장사항**:
+
+- **프로덕션 환경**: npm에 배포된 버전 사용 (설정 불필요)
+- **개발 환경**: 로컬 패키지 사용 시 `transpilePackages` 추가
+
+## 🚀 빠른 시작 (Quick Start)
+
+### 1. 기본 import
+
+```typescript
+import {
+  verifyToken,
+  extractRoleFromPayload,
+  createNextAuthJWT,
+  encodeNextAuthToken,
+  setCustomTokens,
+  setNextAuthToken,
+  createRedirectHTML,
+  createAuthResponse,
+  ServiceInfo,
+  ResponseLike,
+  JWTPayload,
+} from "@thinkingcat/auth-token-utils";
+```
+
+### 2. 환경 변수 설정
+
+`.env.local` 파일에 다음 환경 변수를 설정하세요:
+
+```env
+NEXTAUTH_SECRET=your-secret-key-here
+NODE_ENV=production  # 또는 development
+COOKIE_DOMAIN=.yourdomain.com  # 선택사항
+```
+
+## 📚 주요 기능 (Features)
+
+이 패키지는 다음 기능을 제공합니다:
+
+1. **토큰 검증**: JWT access token 검증 및 디코딩
+2. **역할 추출**: payload에서 서비스별 역할 추출
+3. **NextAuth JWT 생성**: NextAuth 호환 JWT 객체 생성
+4. **세션 토큰 인코딩**: NextAuth 세션 토큰 생성
+5. **쿠키 설정**: 자체 토큰 및 NextAuth 토큰 쿠키 설정
+6. **리다이렉트 HTML**: 클라이언트 리다이렉트용 HTML 생성
+7. **완전한 인증 응답**: 모든 인증 단계를 한 번에 처리
+
+## 🔧 API 레퍼런스
+
+### 1. `verifyToken(accessToken: string, secret: string)`
+
+JWT access token을 검증하고 디코딩합니다.
+
+**파라미터:**
+
+- `accessToken`: 검증할 JWT 토큰
+- `secret`: JWT 서명에 사용할 secret key
+
+**반환값:**
+
+- 성공: `{ payload: JWTPayload }`
+- 실패: `null`
+
+**사용 예시:**
+
+```typescript
+const secret = process.env.NEXTAUTH_SECRET!;
+const result = await verifyToken(accessToken, secret);
+
+if (result) {
+  const { payload } = result;
+  console.log("User email:", payload.email);
+  console.log("User ID:", payload.sub || payload.id);
+} else {
+  console.log("Invalid token");
+}
+```
+
+### 2. `extractRoleFromPayload(payload: JWTPayload, serviceId?: string, defaultRole?: string)`
+
+payload에서 특정 서비스의 역할을 추출합니다.
+
+**파라미터:**
+
+- `payload`: JWT payload 객체 (JWTPayload 타입)
+- `serviceId`: 서비스 ID (기본값: 'checkon')
+- `defaultRole`: 기본 역할 (기본값: 'ADMIN')
+
+**반환값:**
+
+- 추출된 역할 문자열
+
+**사용 예시:**
+
+```typescript
+const role = extractRoleFromPayload(payload, "checkon", "ADMIN");
+// 'ADMIN', 'TEACHER', 'STUDENT' 등
+```
+
+### 3. `createNextAuthJWT(payload: JWTPayload, includeAcademies?: boolean)`
+
+NextAuth와 호환되는 JWT 객체를 생성합니다.
+
+**파라미터:**
+
+- `payload`: 원본 JWT payload (JWTPayload 타입)
+- `includeAcademies`: academies 정보 포함 여부 (기본값: false)
+
+**반환값:**
+
+- NextAuth JWT 객체
+
+**사용 예시:**
+
+```typescript
+const jwt = createNextAuthJWT(payload, true);
+// academies 정보가 포함된 JWT 객체
+```
+
+### 4. `encodeNextAuthToken(jwt: JWT, secret: string, maxAge?: number)`
+
+NextAuth JWT 객체를 인코딩된 세션 토큰으로 변환합니다.
+
+**파라미터:**
+
+- `jwt`: NextAuth JWT 객체
+- `secret`: JWT 서명에 사용할 secret key
+- `maxAge`: 토큰 유효 기간 (초, 기본값: 30일)
+
+**반환값:**
+
+- 인코딩된 세션 토큰 문자열
+
+**사용 예시:**
+
+```typescript
+const secret = process.env.NEXTAUTH_SECRET!;
+const jwt = createNextAuthJWT(payload);
+const sessionToken = await encodeNextAuthToken(jwt, secret);
+```
+
+### 5. `setCustomTokens(response: ResponseLike, accessToken: string, optionsOrRefreshToken?, options?)`
+
+자체 토큰(access token, refresh token)만 쿠키에 설정합니다.
+
+**파라미터:**
+
+- `response`: NextResponse 객체 (또는 ResponseLike 인터페이스를 구현한 객체)
+- `accessToken`: access token 문자열
+- `optionsOrRefreshToken`:
+  - 문자열인 경우: refresh token
+  - 객체인 경우: 옵션 객체 `{ refreshToken?, cookiePrefix?, isProduction? }`
+- `options`: 옵션 객체 (refreshToken이 문자열로 전달된 경우)
+
+**옵션:**
+
+- `cookiePrefix`: 쿠키 이름 접두사 (기본값: 'checkon')
+- `isProduction`: 프로덕션 환경 여부 (기본값: false)
+- `refreshToken`: refresh token (옵션 객체 내부에 포함 가능)
+
+**사용 예시:**
+
+**방법 1: refreshToken이 있는 경우**
+
+```typescript
+setCustomTokens(response, accessToken, refreshToken, {
+  cookiePrefix: "myservice",
+  isProduction: process.env.NODE_ENV === "production",
+});
+```
+
+**방법 2: refreshToken이 없는 경우**
+
+```typescript
+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?)`
+
+NextAuth 세션 토큰만 쿠키에 설정합니다.
+
+**파라미터:**
+
+- `response`: NextResponse 객체
+- `sessionToken`: NextAuth 세션 토큰
+- `options`: 옵션 객체
+
+**옵션:**
+
+- `isProduction`: 프로덕션 환경 여부 (기본값: false)
+- `cookieDomain`: 쿠키 도메인 (선택사항)
+
+**사용 예시:**
+
+```typescript
+setNextAuthToken(response, sessionToken, {
+  isProduction: process.env.NODE_ENV === "production",
+  cookieDomain: process.env.COOKIE_DOMAIN,
+});
+```
+
+**설정되는 쿠키:**
+
+- 개발: `next-auth.session-token`
+- 프로덕션: `__Secure-next-auth.session-token`
+- 유효 기간: 30일
+
+### 7. `createRedirectHTML(redirectPath: string, text?: string)`
+
+클라이언트 리다이렉트용 HTML을 생성합니다.
+
+**파라미터:**
+
+- `redirectPath`: 리다이렉트할 경로
+- `text`: 표시할 텍스트 (기본값: 'checkon')
+
+**반환값:**
+
+- HTML 문자열
+
+**사용 예시:**
+
+```typescript
+const html = createRedirectHTML("/dashboard", "checkon");
+return new NextResponse(html, {
+  status: 200,
+  headers: { "Content-Type": "text/html" },
+});
+```
+
+### 8. `createAuthResponse(accessToken: string, secret: string, options?)`
+
+완전한 인증 세션을 생성합니다. 토큰 검증부터 쿠키 설정까지 모든 과정을 처리합니다.
+
+**파라미터:**
+
+- `accessToken`: access token
+- `secret`: JWT 서명에 사용할 secret key
+- `options`: 옵션 객체
+
+**옵션:**
+
+- `refreshToken`: refresh token (선택)
+- `redirectPath`: 리다이렉트할 경로 (선택)
+- `text`: 리다이렉트 HTML에 표시할 텍스트 (기본값: 'checkon')
+- `cookiePrefix`: 쿠키 이름 접두사 (기본값: 'checkon')
+- `isProduction`: 프로덕션 환경 여부 (기본값: false)
+- `cookieDomain`: 쿠키 도메인 (선택)
+
+**반환값:**
+
+- NextResponse 객체
+
+**사용 예시:**
+
+```typescript
+const secret = process.env.NEXTAUTH_SECRET!;
+const response = await createAuthResponse(accessToken, secret, {
+  refreshToken: refreshToken,
+  redirectPath: "/dashboard",
+  text: "checkon",
+  cookiePrefix: "checkon",
+  isProduction: process.env.NODE_ENV === "production",
+  cookieDomain: process.env.COOKIE_DOMAIN,
+});
+```
+
+## 💡 사용 시나리오
+
+### 시나리오 1: 자체 토큰만 사용하는 서비스
+
+SSO에서 받은 토큰을 자체 쿠키에만 저장하는 경우:
+
+#### 1-1. URL 파라미터로 토큰을 받는 경우 (초기 로그인)
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import {
+  verifyToken,
+  setCustomTokens,
+  createRedirectHTML,
+  JWTPayload,
+} from "@thinkingcat/auth-token-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);
+
+  // 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,
+    headers: { "Content-Type": "text/html" },
+  });
+
+  setCustomTokens(response, tokenParam, {
+    cookiePrefix: "myservice",
+    isProduction: process.env.NODE_ENV === "production",
+  });
+
+  return response;
+}
+```
+
+#### 1-2. 쿠키에서 토큰을 읽어서 검증하는 경우 (이미 로그인된 상태)
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { verifyToken, JWTPayload } from "@thinkingcat/auth-token-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 세션만 사용하는 경우:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import {
+  verifyToken,
+  createNextAuthJWT,
+  encodeNextAuthToken,
+  setNextAuthToken,
+} from "@thinkingcat/auth-token-utils";
+
+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);
+
+  if (!tokenResult) {
+    return NextResponse.redirect("/login");
+  }
+
+  const { payload } = tokenResult;
+  const jwt = createNextAuthJWT(payload);
+  const sessionToken = await encodeNextAuthToken(jwt, secret);
+
+  const response = NextResponse.redirect("/dashboard");
+  setNextAuthToken(response, sessionToken, {
+    isProduction: process.env.NODE_ENV === "production",
+    cookieDomain: process.env.COOKIE_DOMAIN,
+  });
+
+  return response;
+}
+```
+
+### 시나리오 3: 자체 토큰 + NextAuth 모두 사용 (check-on 예시)
+
+자체 토큰과 NextAuth 세션을 모두 사용하는 경우:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import {
+  verifyToken,
+  extractRoleFromPayload,
+  createNextAuthJWT,
+  encodeNextAuthToken,
+  setCustomTokens,
+  setNextAuthToken,
+  createRedirectHTML,
+} from "@thinkingcat/auth-token-utils";
+
+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 isProduction = process.env.NODE_ENV === "production";
+
+  // 1. 토큰 검증
+  const tokenResult = await verifyToken(tokenParam, secret);
+  if (!tokenResult) {
+    return NextResponse.redirect("/login");
+  }
+
+  const { payload } = tokenResult;
+
+  // 2. 역할 추출
+  const role = extractRoleFromPayload(payload, "checkon", "ADMIN");
+
+  // 3. Refresh token 가져오기 (SSO API 호출 등)
+  let refreshToken = "";
+  // ... refreshToken 가져오는 로직 ...
+
+  // 4. NextAuth JWT 생성 및 인코딩
+  const jwt = createNextAuthJWT(payload);
+  const sessionToken = await encodeNextAuthToken(jwt, secret);
+
+  // 5. 역할별 리다이렉트 경로 결정
+  const redirectPath = role === "ADMIN" ? "/admin" : "/dashboard";
+  const html = createRedirectHTML(redirectPath, "checkon");
+
+  const response = new NextResponse(html, {
+    status: 200,
+    headers: { "Content-Type": "text/html" },
+  });
+
+  // 6. 자체 토큰 설정
+  setCustomTokens(response, tokenParam, refreshToken, {
+    cookiePrefix: "checkon",
+    isProduction,
+  });
+
+  // 7. NextAuth 토큰 설정
+  setNextAuthToken(response, sessionToken, {
+    isProduction,
+    cookieDomain: process.env.COOKIE_DOMAIN,
+  });
+
+  return response;
+}
+```
+
+### 시나리오 4: Middleware에서 사용
+
+Next.js Middleware에서 토큰 검증 및 리프레시:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import {
+  verifyToken,
+  setCustomTokens,
+  setNextAuthToken,
+  createNextAuthJWT,
+  encodeNextAuthToken,
+} from "@thinkingcat/auth-token-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,
+          });
+
+          return response;
+        }
+      }
+    }
+  }
+
+  // 인증 실패 - 로그인 페이지로 리다이렉트
+  return NextResponse.redirect(new URL("/login", req.url));
+}
+```
+
+## 🔒 보안 고려사항
+
+### ⚠️ 중요 사항
+
+1. **Secret Key 관리**
+
+   - `NEXTAUTH_SECRET`은 반드시 환경 변수로 관리하세요
+   - 절대 코드에 하드코딩하지 마세요
+   - 프로덕션과 개발 환경에서 다른 secret을 사용하세요
+
+2. **쿠키 보안**
+
+   - 프로덕션 환경에서는 `isProduction: true`를 설정하세요
+   - `secure: true`로 설정되어 HTTPS에서만 전송됩니다
+   - `httpOnly: true`로 설정되어 JavaScript에서 접근할 수 없습니다
+
+3. **토큰 검증**
+   - 모든 토큰은 사용 전에 반드시 `verifyToken`으로 검증하세요
+   - 검증 실패 시 적절한 에러 처리를 하세요
+
+## 📝 타입 정의
+
+### `JWTPayload`
+
+JWT 토큰의 payload 타입입니다.
+
+```typescript
+interface JWTPayload {
+  // 표준 JWT 필드
+  sub?: string; // Subject (사용자 ID)
+  id?: string; // 사용자 ID
+  email: string; // 이메일
+  name: string; // 이름
+  role?: string; // 역할
+  iat?: number; // Issued At
+  exp?: number; // Expiration Time
+
+  // 서비스 정보
+  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;
+  emailHash?: string;
+  maskedEmail?: string;
+  phoneHash?: string;
+  maskedPhone?: string;
+  refreshToken?: string;
+  accessToken?: string;
+  accessTokenExpires?: number;
+  serviceId?: string;
+
+  // 기타 필드
+  [key: string]: unknown;
+}
+```
+
+### `ServiceInfo`
+
+```typescript
+interface ServiceInfo {
+  serviceId: string;
+  role: string;
+  joinedAt: string;
+  lastAccessAt?: string;
+  expiredAt?: string;
+  status: string;
+}
+```
+
+### SSO API 응답 타입
+
+#### `SSOUpsertResponse`
+
+```typescript
+interface SSOUpsertResponse {
+  success: boolean;
+  message?: string;
+  user?: {
+    id: string;
+    email: string;
+    name: string;
+  };
+}
+```
+
+#### `SSOErrorResponse`
+
+```typescript
+interface SSOErrorResponse {
+  error: string;
+  message?: string;
+}
+```
+
+#### `SSORefreshTokenResponse`
+
+```typescript
+interface SSORefreshTokenResponse {
+  success: boolean;
+  accessToken?: string;
+  refreshToken?: string;
+  user?: {
+    id: string;
+    email: string;
+    name: string;
+  };
+  error?: string;
+}
+```
+
+#### `SSOGetRefreshTokenResponse`
+
+```typescript
+interface SSOGetRefreshTokenResponse {
+  success: boolean;
+  refreshToken?: string;
+  error?: string;
+}
+```
+
+#### `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-token-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
+interface ResponseLike {
+  cookies: {
+    delete(name: string): void;
+    set(
+      name: string,
+      value: string,
+      options?: {
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "strict" | "lax" | "none";
+        maxAge?: number;
+        path?: string;
+        domain?: string;
+      }
+    ): void;
+  };
+}
+```
+
+## 🐛 문제 해결 (Troubleshooting)
+
+### 문제 1: "Cannot find module '@thinkingcat/auth-token-utils'"
+
+**해결 방법:**
+
+```bash
+# 패키지 재설치
+npm install @thinkingcat/auth-token-utils
+
+# 또는 node_modules 삭제 후 재설치
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### 문제 2: 타입 오류 "NextResponse is not assignable to ResponseLike"
+
+**해결 방법:**
+`ResponseLike` 인터페이스는 NextResponse와 호환됩니다. 타입 단언이 필요하지 않습니다. 만약 오류가 발생한다면 패키지 버전을 확인하세요.
+
+### 문제 3: 토큰 검증 실패
+
+**확인 사항:**
+
+- `NEXTAUTH_SECRET`이 올바르게 설정되었는지 확인
+- 토큰이 만료되지 않았는지 확인
+- 토큰 형식이 올바른지 확인
+
+### 문제 4: 쿠키가 설정되지 않음
+
+**확인 사항:**
+
+- `isProduction` 옵션이 올바르게 설정되었는지 확인
+- 브라우저 개발자 도구에서 쿠키 설정 확인
+- 도메인 및 경로 설정 확인
+
+## 📦 패키지 정보
+
+- **패키지명**: `@thinkingcat/auth-token-utils`
+- **버전**: `1.0.0`
+- **라이선스**: MIT
+- **저장소**: npm registry
+
+## 🤝 기여 (Contributing)
+
+이슈나 개선 사항이 있으면 GitHub 이슈를 등록해주세요.
+
+## 📄 라이선스 (License)
+
+MIT License
+
+---
+
+**Made with ❤️ by ThinkingCat**