@thinkingcat/auth-utils 1.0.4

package/dist/index.d.ts

@@ -0,0 +1,384 @@
+import { JWT } from "next-auth/jwt";
+import { NextResponse, NextRequest } from 'next/server';
+export 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;
+    };
+}
+export interface ServiceInfo {
+    serviceId: string;
+    role: string;
+    joinedAt: string;
+    lastAccessAt?: string;
+    expiredAt?: string;
+    status: string;
+}
+export interface SSOUpsertResponse {
+    success: boolean;
+    message?: string;
+    user?: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+export interface SSOErrorResponse {
+    error: string;
+    message?: string;
+}
+export interface SSORefreshTokenResponse {
+    success: boolean;
+    accessToken?: string;
+    refreshToken?: string;
+    user?: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    error?: string;
+}
+export interface SSOGetRefreshTokenResponse {
+    success: boolean;
+    refreshToken?: string;
+    error?: string;
+}
+export interface SSORegisterResponse {
+    success: boolean;
+    message?: string;
+    user?: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+export interface JWTPayload {
+    sub?: string;
+    id?: string;
+    email: string;
+    name: string;
+    role?: string;
+    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;
+    emailHash?: string;
+    maskedEmail?: string;
+    phoneHash?: string;
+    maskedPhone?: string;
+    refreshToken?: string;
+    accessToken?: string;
+    accessTokenExpires?: number;
+    serviceId?: string;
+    [key: string]: unknown;
+}
+/**
+ * 토큰 검증 및 디코딩
+ * @param accessToken JWT access token
+ * @param secret JWT 서명에 사용할 secret key
+ * @returns 검증된 payload 또는 null
+ */
+export declare function verifyToken(accessToken: string, secret: string): Promise<{
+    payload: JWTPayload;
+} | null>;
+/**
+ * payload에서 역할 추출 (서비스별)
+ * @param payload JWT payload
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @param defaultRole 기본 역할 (기본값: 'ADMIN')
+ * @returns 추출된 역할
+ */
+export declare function extractRoleFromPayload(payload: JWTPayload, serviceId?: string, defaultRole?: string): string;
+/**
+ * payload에서 NextAuth JWT 객체 생성
+ * @param payload JWT payload
+ * @param includeAcademies academies 정보 포함 여부
+ * @returns NextAuth JWT 객체
+ */
+export declare function createNextAuthJWT(payload: JWTPayload, includeAcademies?: boolean): JWT;
+/**
+ * NextAuth JWT를 인코딩된 세션 토큰으로 변환
+ * @param jwt NextAuth JWT 객체
+ * @param secret JWT 서명에 사용할 secret key
+ * @param maxAge 토큰 유효 기간 (초, 기본값: 30일)
+ * @returns 인코딩된 세션 토큰
+ */
+export declare function encodeNextAuthToken(jwt: JWT, secret: string, maxAge?: number): Promise<string>;
+/**
+ * 자체 토큰만 설정 (access token, refresh token)
+ * @param response NextResponse 객체
+ * @param accessToken access token
+ * @param refreshToken refresh token (선택)
+ * @param options 쿠키 설정 옵션
+ * @param options.cookiePrefix 쿠키 이름 접두사 (기본값: 'checkon')
+ * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
+ */
+export declare function setCustomTokens(response: ResponseLike, accessToken: string, refreshToken: string, options?: {
+    cookiePrefix?: string;
+    isProduction?: boolean;
+}): void;
+export declare function setCustomTokens(response: ResponseLike, accessToken: string, options?: {
+    refreshToken?: string;
+    cookiePrefix?: string;
+    isProduction?: boolean;
+}): void;
+/**
+ * NextAuth 세션 토큰만 설정
+ * @param response NextResponse 객체
+ * @param sessionToken NextAuth session token
+ * @param options 쿠키 설정 옵션
+ * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
+ * @param options.cookieDomain 쿠키 도메인 (선택)
+ */
+export declare function setNextAuthToken(response: ResponseLike, sessionToken: string, options?: {
+    isProduction?: boolean;
+    cookieDomain?: string;
+}): void;
+/**
+ * 리다이렉트용 HTML 생성
+ * @param redirectPath 리다이렉트할 경로
+ * @param text 표시할 텍스트 (기본값: 'checkon')
+ * @returns HTML 문자열
+ */
+export declare function createRedirectHTML(redirectPath: string, text?: string): string;
+/**
+ * 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 객체
+ */
+export declare function createAuthResponse(accessToken: string, secret: string, options?: {
+    refreshToken?: string;
+    redirectPath?: string;
+    text?: string;
+    cookiePrefix?: string;
+    isProduction?: boolean;
+    cookieDomain?: string;
+}): Promise<NextResponse>;
+/**
+ * 서비스 구독 유효성 확인 함수
+ * @param services 서비스 정보 배열
+ * @param serviceId 확인할 서비스 ID
+ * @returns 구독 유효성 결과
+ */
+export declare function validateServiceSubscription(services: ServiceInfo[], serviceId: string): {
+    isValid: boolean;
+    redirectUrl?: string;
+    service?: ServiceInfo;
+};
+/**
+ * SSO 서버에서 refresh token을 사용하여 새로운 access token을 발급받는 함수
+ * @param refreshToken refresh token
+ * @param options 옵션
+ * @param options.ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @param options.authServiceKey 인증 서비스 키 (기본값: 환경 변수)
+ * @returns SSO refresh token 응답
+ */
+export declare function refreshSSOToken(refreshToken: string, options?: {
+    ssoBaseURL?: string;
+    authServiceKey?: string;
+}): Promise<SSORefreshTokenResponse>;
+/**
+ * SSO 서버에서 사용자의 refresh token을 가져오는 함수
+ * @param userId 사용자 ID
+ * @param accessToken access token
+ * @param options 옵션
+ * @param options.ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @param options.authServiceKey 인증 서비스 키 (기본값: 환경 변수)
+ * @returns refresh token 또는 null
+ */
+export declare function getRefreshTokenFromSSO(userId: string, accessToken: string, options?: {
+    ssoBaseURL?: string;
+    authServiceKey?: string;
+}): Promise<string | 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 검증 결과 및 필요시 리프레시된 응답
+ */
+export declare function verifyAndRefreshToken(req: NextRequest, secret: string, options?: {
+    cookiePrefix?: string;
+    isProduction?: boolean;
+    cookieDomain?: string;
+    text?: string;
+    ssoBaseURL?: string;
+    authServiceKey?: string;
+}): Promise<{
+    isValid: boolean;
+    response?: NextResponse;
+    payload?: JWTPayload;
+    error?: string;
+}>;
+/**
+ * 에러 페이지로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param code 에러 코드
+ * @param message 에러 메시지
+ * @param errorPath 에러 페이지 경로 (기본값: '/error')
+ * @returns NextResponse 리다이렉트 응답
+ */
+export declare function redirectToError(req: NextRequest, code: string, message: string, errorPath?: string): NextResponse;
+/**
+ * 인증 쿠키를 삭제하는 헬퍼 함수
+ * @param response NextResponse 객체
+ * @param cookiePrefix 쿠키 이름 접두사 (기본값: 'checkon')
+ * @returns NextResponse 객체
+ */
+export declare function clearAuthCookies(response: NextResponse, cookiePrefix?: string): NextResponse;
+/**
+ * JWT에서 서비스별 역할을 추출하는 헬퍼 함수
+ * @param token NextAuth JWT 객체 또는 null
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 추출된 역할 또는 undefined
+ */
+export declare function getEffectiveRole(token: JWT | null, serviceId?: string): string | undefined;
+/**
+ * 구독이 필요한 경로인지 확인하는 헬퍼 함수
+ * @param pathname 경로명
+ * @param role 사용자 역할
+ * @param subscriptionRequiredPaths 구독이 필요한 경로 배열
+ * @param systemAdminRole 시스템 관리자 역할 (기본값: 'SYSTEM_ADMIN')
+ * @returns 구독이 필요한지 여부
+ */
+export declare function requiresSubscription(pathname: string, role: string, subscriptionRequiredPaths: string[], systemAdminRole?: string): boolean;
+/**
+ * 역할 기반 접근 제어 헬퍼 함수
+ * @param pathname 경로명
+ * @param role 사용자 역할
+ * @param roleConfig 역할별 경로 설정 객체
+ * @returns 접근 허용 여부 및 메시지
+ */
+export interface RoleAccessConfig {
+    [role: string]: {
+        paths: string[];
+        message: string;
+        allowedRoles?: string[];
+    };
+}
+export declare function checkRoleAccess(pathname: string, role: string, roleConfig: RoleAccessConfig): {
+    allowed: boolean;
+    message?: string;
+};
+/**
+ * SSO 로그인 페이지로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param serviceId 서비스 ID
+ * @param ssoBaseURL SSO 서버 기본 URL (기본값: 환경 변수 또는 기본값)
+ * @returns NextResponse 리다이렉트 응답
+ */
+export declare function redirectToSSOLogin(req: NextRequest, serviceId: string, ssoBaseURL?: string): NextResponse;
+/**
+ * 역할별 대시보드 경로로 리다이렉트하는 헬퍼 함수
+ * @param req NextRequest 객체
+ * @param role 사용자 역할
+ * @param rolePaths 역할별 경로 설정 객체
+ * @param defaultPath 기본 경로 (기본값: '/admin')
+ * @returns NextResponse 리다이렉트 응답
+ */
+export declare function redirectToRoleDashboard(req: NextRequest, role: string, rolePaths: Record<string, string>, defaultPath?: string): NextResponse;
+/**
+ * 토큰이 만료되었는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @returns 만료 여부
+ */
+export declare function isTokenExpired(token: JWT | null): boolean;
+/**
+ * 토큰이 유효한지 확인하는 함수 (만료 및 필수 필드 체크)
+ * @param token NextAuth JWT 객체
+ * @returns 유효성 여부
+ */
+export declare function isValidToken(token: JWT | null): boolean;
+/**
+ * 특정 역할을 가지고 있는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @param role 확인할 역할
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 역할 보유 여부
+ */
+export declare function hasRole(token: JWT | null, role: string, serviceId?: string): boolean;
+/**
+ * 여러 역할 중 하나라도 가지고 있는지 확인하는 함수
+ * @param token NextAuth JWT 객체
+ * @param roles 확인할 역할 배열
+ * @param serviceId 서비스 ID (기본값: 'checkon')
+ * @returns 역할 보유 여부
+ */
+export declare function hasAnyRole(token: JWT | null, roles: string[], serviceId?: string): boolean;
+/**
+ * 공개 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @param publicPaths 공개 경로 배열
+ * @returns 공개 경로 여부
+ */
+export declare function isPublicPath(pathname: string, publicPaths: string[]): boolean;
+/**
+ * API 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @returns API 경로 여부
+ */
+export declare function isApiPath(pathname: string): boolean;
+/**
+ * 보호된 API 경로인지 확인하는 함수
+ * @param pathname 경로명
+ * @param exemptPaths 제외할 경로 배열
+ * @returns 보호된 API 경로 여부
+ */
+export declare function isProtectedApiPath(pathname: string, exemptPaths?: string[]): boolean;
+/**
+ * NextAuth 토큰과 자체 토큰을 모두 확인하는 통합 인증 체크 함수
+ * @param req NextRequest 객체
+ * @param secret JWT 서명에 사용할 secret key
+ * @param options 옵션
+ * @returns 인증 결과
+ */
+export declare function checkAuthentication(req: NextRequest, secret: string, options?: {
+    cookiePrefix?: string;
+    isProduction?: boolean;
+    cookieDomain?: string;
+    text?: string;
+    ssoBaseURL?: string;
+    authServiceKey?: string;
+    getNextAuthToken?: (req: NextRequest) => Promise<JWT | null>;
+}): Promise<{
+    isAuthenticated: boolean;
+    token?: JWT | null;
+    payload?: JWTPayload;
+    response?: NextResponse;
+    error?: string;
+}>;