@thinkingcat/auth-utils 1.0.50 → 2.0.1

package/dist/index.d.ts

@@ -1,634 +1,18 @@
-import type { JWT } from "next-auth/jwt";
-import type { Session } from "next-auth";
-import type { 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[];
-    phoneVerified?: boolean;
-    emailVerified?: boolean;
-    smsVerified?: boolean;
-    phone?: 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 (필수)
- * @param defaultRole 기본 역할 (기본값: 'ADMIN')
- * @returns 추출된 역할
- */
-export declare function extractRoleFromPayload(payload: JWTPayload, serviceId: string, defaultRole?: string): string;
-/**
- * payload에서 NextAuth JWT 객체 생성
- * @param payload JWT payload
- * @param serviceId 서비스 ID (필수)
- * @returns NextAuth JWT 객체
- */
-export declare function createNextAuthJWT(payload: JWTPayload, serviceId: string): 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 쿠키 이름 접두사 (필수)
- * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
- */
-export declare function setCustomTokens(response: ResponseLike, accessToken: string, refreshToken: string, options?: {
-    cookiePrefix?: string;
-    isProduction?: boolean;
-    cookieDomain?: string;
-}): void;
-export declare function setCustomTokens(response: ResponseLike, accessToken: string, options?: {
-    refreshToken?: string;
-    cookiePrefix?: string;
-    isProduction?: boolean;
-    cookieDomain?: string;
-}): 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 표시할 텍스트 (필수)
- * @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.req NextRequest 객체 (필수 - URL origin을 위해 필요)
- * @param options.refreshToken refresh token (선택)
- * @param options.redirectPath 리다이렉트할 경로 (HTTP 302 리다이렉트 사용)
- * @param options.text 응답 메시지 텍스트 (선택사항)
- * @param options.cookiePrefix 쿠키 이름 접두사 (필수)
- * @param options.isProduction 프로덕션 환경 여부 (기본값: false)
- * @param options.cookieDomain 쿠키 도메인 (선택)
- * @param options.serviceId 서비스 ID (필수)
- * @param options.licenseKey 라이센스 키 (필수)
- * @returns NextResponse 객체 (리다이렉트 또는 JSON 응답)
- */
-export declare function createAuthResponse(accessToken: string, secret: string, options: {
-    req: NextRequest;
-    refreshToken?: string;
-    redirectPath?: string;
-    text?: string;
-    cookiePrefix?: string;
-    isProduction?: boolean;
-    cookieDomain?: string;
-    serviceId: string;
-    licenseKey: string;
-}): Promise<NextResponse>;
-/**
- * 서비스 구독 유효성 확인 함수
- * @param services 서비스 정보 배열
- * @param serviceId 확인할 서비스 ID
- * @param ssoBaseURL SSO 서버 기본 URL (필수)
- * @returns 구독 유효성 결과
- */
-export declare function validateServiceSubscription(services: ServiceInfo[], serviceId: string, ssoBaseURL: 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>;
-export declare function verifyAndRefreshToken(req: NextRequest, secret: string, options: {
-    cookiePrefix: string;
-    serviceId: string;
-    isProduction: boolean;
-    cookieDomain?: string;
-    text?: string;
-    ssoBaseURL?: string;
-    authServiceKey?: string;
-    licenseKey: string;
-    forceRefresh?: boolean;
-}): 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): Promise<NextResponse>;
-/**
- * 인증 쿠키를 삭제하는 헬퍼 함수
- * @param response NextResponse 객체
- * @param cookiePrefix 쿠키 이름 접두사 (필수)
- * @returns NextResponse 객체
- */
-export declare function clearAuthCookies(response: NextResponse, cookiePrefix: string): NextResponse;
-/**
- * JWT에서 서비스별 역할을 추출하는 헬퍼 함수
- * @param token NextAuth JWT 객체 또는 null
- * @param serviceId 서비스 ID (필수)
- * @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 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 interface MiddlewareOptions {
-    /** NextAuth Secret (필수) */
-    secret: string;
-    /** 프로덕션 환경 여부 (필수) */
-    isProduction: boolean;
-    /** 쿠키 도메인 (선택사항) */
-    cookieDomain?: string;
-    /** NextAuth 토큰을 가져오는 함수 (선택사항) */
-    getNextAuthToken?: (req: NextRequest) => Promise<JWT | null>;
-    /** SSO 서버 기본 URL (필수) */
-    ssoBaseURL: string;
-    /** 인증 서비스 키 (선택사항) */
-    authServiceKey?: string;
-    /** 라이센스 키 (필수) */
-    licenseKey: string;
-}
-/**
- * NextAuth 쿠키 설정 생성
- * @param options 옵션
- * @param options.isProduction 프로덕션 환경 여부
- * @param options.cookieDomain 쿠키 도메인 (선택)
- * @returns NextAuth 쿠키 설정 객체
- */
-export declare function createNextAuthCookies(options: {
-    isProduction?: boolean;
-    cookieDomain?: string;
-}): {
-    sessionToken: {
-        name: string;
-        options: {
-            httpOnly: boolean;
-            sameSite: 'lax' | 'none';
-            path: string;
-            secure: boolean;
-            domain?: string;
-        };
-    };
-    callbackUrl: {
-        name: string;
-        options: {
-            sameSite: 'lax' | 'none';
-            path: string;
-            secure: boolean;
-            domain?: string;
-        };
-    };
-    csrfToken: {
-        name: string;
-        options: {
-            httpOnly: boolean;
-            sameSite: 'lax' | 'none';
-            path: string;
-            secure: boolean;
-            domain?: string;
-        };
-    };
-};
-/**
- * NextAuth 기본 설정 생성
- * @param options 옵션
- * @param options.secret NextAuth secret
- * @param options.isProduction 프로덕션 환경 여부
- * @param options.cookieDomain 쿠키 도메인 (선택)
- * @param options.signInPath 로그인 페이지 경로 (기본값: '/login')
- * @param options.errorPath 에러 페이지 경로 (기본값: '/login')
- * @param options.nextAuthUrl NextAuth URL (선택)
- * @param options.sessionMaxAge 세션 최대 유지 시간 (초, 기본값: 30일)
- * @param options.jwtMaxAge JWT 최대 유지 시간 (초, 기본값: 30일)
- * @returns NextAuth 기본 설정 객체
- */
-export declare function createNextAuthBaseConfig(options: {
-    secret: string;
-    isProduction?: boolean;
-    cookieDomain?: string;
-    signInPath?: string;
-    errorPath?: string;
-    nextAuthUrl?: string;
-    sessionMaxAge?: number;
-    jwtMaxAge?: number;
-}): {
-    session: {
-        strategy: 'jwt';
-        maxAge: number;
-    };
-    jwt: {
-        maxAge: number;
-    };
-    providers: never[];
-    url?: string;
-    pages: {
-        signIn: string;
-        error: string;
-    };
-    cookies: ReturnType<typeof createNextAuthCookies>;
-    secret: string;
-};
-/**
- * JWT 콜백에서 초기 로그인 시 토큰 생성 헬퍼
- * @param token 기존 토큰
- * @param user 사용자 정보
- * @param account 계정 정보
- * @returns 업데이트된 JWT 토큰
- */
-export declare function createInitialJWTToken(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;
-}, account?: {
-    serviceId?: string;
-} | null): JWT;
-/**
- * Session 콜백에서 빈 세션 반환 헬퍼
- * @param session 기존 세션
- * @returns 빈 세션 객체
- */
-export declare function createEmptySession(session: Session): Session;
-/**
- * Session 콜백에서 토큰 정보를 세션에 매핑하는 헬퍼
- * @param session 기존 세션
- * @param token JWT 토큰
- * @returns 업데이트된 세션
- */
-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;
-    ssoBaseURL?: string;
-    authServiceKey?: string;
-}): Promise<JWT>;
-/**
- * 쿠키에서 커스텀 토큰을 읽어서 NextAuth JWT로 변환하는 헬퍼 함수
- * NextAuth JWT 콜백에서 사용
- * @param cookieName 쿠키 이름 (예: 'checkon_access_token')
- * @param secret JWT 서명에 사용할 secret key
- * @param serviceId 서비스 ID (필수)
- * @param licenseKey 라이센스 키 (필수)
- * @returns NextAuth 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;
-    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): Promise<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): Promise<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 (필수)
- * @returns 역할 보유 여부
- */
-export declare function hasRole(token: JWT | null, role: string, serviceId: string): boolean;
-/**
- * 여러 역할 중 하나라도 가지고 있는지 확인하는 함수
- * @param token NextAuth JWT 객체
- * @param roles 확인할 역할 배열
- * @param serviceId 서비스 ID (필수)
- * @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;
-    serviceId: string;
-    isProduction: boolean;
-    cookieDomain?: string;
-    text?: string;
-    ssoBaseURL?: string;
-    authServiceKey?: string;
-    getNextAuthToken?: (req: NextRequest) => Promise<JWT | null>;
-    licenseKey: string;
-}): Promise<{
-    isAuthenticated: boolean;
-    token?: JWT | null;
-    payload?: JWTPayload;
-    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;
-    serviceId: string;
-    isProduction: boolean;
-    cookieDomain?: string;
-    text?: string;
-    ssoBaseURL?: string;
-    authServiceKey?: string;
-    licenseKey: string;
-}): Promise<{
-    isValid: boolean;
-    response?: NextResponse;
-    error?: string;
-    payload?: JWTPayload;
-    token?: JWT;
-}>;
-/**
- * 기본 미들웨어 설정을 생성하는 함수
- * @param config 커스텀 설정 (필수: serviceId 포함)
- * @param defaults 기본 설정값 (선택사항, 제공하지 않으면 최소 기본값 사용)
- * @returns 미들웨어 설정 객체
- */
-export declare function createMiddlewareConfig(config: Partial<MiddlewareConfig> & {
-    serviceId: string;
-}, defaults?: {
-    publicPaths?: string[];
-    subscriptionRequiredPaths?: string[];
-    subscriptionExemptApiPaths?: string[];
-    authApiPaths?: string[];
-    rolePaths?: Record<string, string>;
-    systemAdminRole?: string;
-    errorPath?: string;
-}): Required<Omit<MiddlewareConfig, 'serviceId'>> & Pick<MiddlewareConfig, 'serviceId'>;
-/**
- * 통합 미들웨어 핸들러 함수
- * 모든 인증, 권한, 구독 체크를 포함한 완전한 미들웨어 로직
- * @param req NextRequest 객체
- * @param config 미들웨어 설정
- * @param options 미들웨어 실행 옵션 (secret 필수)
- * @returns NextResponse 또는 null (다음 미들웨어로 진행)
- */
-export declare function handleMiddleware(req: NextRequest, config: Required<Omit<MiddlewareConfig, 'serviceId'>> & Pick<MiddlewareConfig, 'serviceId'>, options: MiddlewareOptions): Promise<NextResponse | null>;
+export * from './types/index';
+export * from './utils/logger';
+export * from './utils/crypto';
+export * from './utils/server';
+export * from './utils/redirect';
+export * from './utils/path';
+export * from './utils/license';
+export * from './core/jwt';
+export * from './core/cookies';
+export * from './core/auth-response';
+export * from './core/roles';
+export * from './core/verify';
+export * from './sso/api';
+export * from './nextauth/config';
+export * from './nextauth/callbacks';
+export * from './nextauth/session';
+export * from './middleware/config';
+export * from './middleware/handler';