@point3/logto-module 1.0.0

package/client/m2m-client.ts

@@ -0,0 +1,428 @@
+/**
+ * Logto M2M(Machine-to-Machine) 클라이언트
+ * - Logto API의 M2M 인증 및 사용자/역할 관리 기능 제공
+ * - NestJS DI 시스템에 등록됨
+ * 
+ * @author
+ */
+
+import {
+    Inject,
+    Injectable,
+    Global,
+    LoggerService,
+} from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+
+import {
+    LogtoConfig,
+    GrantType,
+} from "./config";
+import {
+    AccessToken,
+    LogtoTokenVerifier,
+    LogtoTokenVerifierToken,
+} from "../token";
+import {
+    LogtoOAuthRESTTemplate,
+    LogtoPasswordAlgorithm,
+    LogtoRole,
+    LogtoRoleResponse,
+    LogtoUser,
+    LogtoUserResponse,
+    VerificationMethodType,
+    LogtoLoggerServiceToken
+} from "./types";
+import { p3Values, axiosAdapter } from "point3-common-tool";
+import {
+    UserMissingRequiredFieldsError,
+    UserNotFoundError,
+    MultipleUsersFoundError,
+} from "../errors";
+
+// DI 토큰
+export const LogtoM2MClientToken = Symbol.for("LogtoM2MClient");
+
+/**
+ * LogtoM2MClient
+ *
+ * Logto M2M(Machine-to-Machine) 인증 및 사용자/역할 관리를 위한 클라이언트 서비스입니다.
+ * NestJS DI 환경에서 사용되며, 서버 간 통신 및 자동화된 시스템에서 Logto API를 활용할 때 사용합니다.
+ *
+ * 주요 역할:
+ *   - M2M 인증을 통한 AccessToken 발급 및 관리
+ *   - 역할(Role) 생성, 조회, 사용자 역할 할당
+ *   - 사용자(User) 생성, 조회, 수정, 정지/해제, 삭제 등 관리
+ *   - 인증코드 발송 및 검증, 비밀번호 변경 등 부가 기능 제공
+ *
+ * 사용 예시:
+ *   const client = new LogtoM2MClient(...);
+ *   await client.fetchAccessToken();
+ *   const roles = await client.getRoles();
+ *   const userId = await client.createUser(user);
+ *   await client.assignRoleToUser(userId, roleId);
+ *   ...
+ */
+@Global()
+@Injectable()
+export class LogtoM2MClient {
+    private logtoConfig: LogtoConfig;
+    private accessToken?: AccessToken;
+
+    // /oidc 엔드포인트용 REST 템플릿
+    private readonly authRestTemplate: axiosAdapter.RESTTemplate;
+    // /api 엔드포인트용 REST 템플릿
+    private readonly apiRestTemplate: axiosAdapter.RESTTemplate;
+
+    constructor(
+        @Inject(ConfigService)
+        private readonly configService: ConfigService,
+
+        @Inject(LogtoTokenVerifierToken)
+        private readonly tokenVerifier: LogtoTokenVerifier,
+
+        @Inject(LogtoLoggerServiceToken)
+        private readonly logger: LoggerService,
+    ) {
+        // 환경변수 기반 Logto 설정
+        this.logtoConfig = {
+            endpoint: this.configService.get<string>('LOGTO_AUTH_ENDPOINT')!,
+            appId: this.configService.get<string>('LOGTO_M2M_CLIENT_ID')!,
+            appSecret: this.configService.get<string>('LOGTO_M2M_CLIENT_SECRET')!,
+            scopes: ['all'],
+            resources: [this.configService.get<string>('LOGTO_M2M_RESOURCE')!],
+            grantType: GrantType.ClientCredentials,
+        };
+
+        // 인증용 REST 템플릿 초기화
+        this.authRestTemplate = new LogtoOAuthRESTTemplate(
+            this.logger,
+            this.logtoConfig.endpoint,
+        );
+        this.authRestTemplate.setBasic(this.logtoConfig.appId, this.logtoConfig.appSecret);
+
+        // API용 REST 템플릿 초기화
+        this.apiRestTemplate = new LogtoOAuthRESTTemplate(
+            this.logger,
+            this.configService.get<string>('LOGTO_M2M_API_URL'),
+        );
+    }
+
+    // =========================
+    // 1. 토큰 관리
+    // =========================
+
+    /**
+     * AccessToken을 발급받아 저장 및 API 템플릿에 Bearer로 설정
+     */
+    async fetchAccessToken(): Promise<void> {
+        const params = new URLSearchParams();
+        params.set('grant_type', this.logtoConfig.grantType);
+        params.set('scope', this.logtoConfig.scopes!.join(' '));
+        params.set('resource', this.logtoConfig.resources!.join(' '));
+
+        const response = await this.authRestTemplate.post<{
+            access_token: string;
+            expires_in: number;
+        }>('/token', params.toString(), {
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        });
+
+        const { access_token, expires_in } = response.data;
+        const payload = await this.tokenVerifier.verifyToken(access_token);
+
+        this.accessToken = new AccessToken(
+            payload.sub,
+            access_token,
+            expires_in,
+        );
+        this.apiRestTemplate.setBearer(access_token);
+    }
+
+    /**
+     * 유효한 AccessToken 반환 (만료 시 자동 갱신)
+     * @private
+     */
+    private async getAccessToken(): Promise<string> {
+        if (!this.accessToken || this.accessToken.isExpired()) {
+            await this.fetchAccessToken();
+        }
+        return this.accessToken!.token;
+    }
+
+    // =========================
+    // 2. 역할(Role) 관리
+    // =========================
+
+    /**
+     * 모든 역할 목록 조회
+     */
+    async getRoles(): Promise<LogtoRoleResponse[]> {
+        await this.getAccessToken();
+        const response = await this.apiRestTemplate.get<LogtoRoleResponse[]>('/roles');
+        return response.data;
+    }
+
+    /**
+     * 역할 이름으로 역할 조회
+     * @param name 역할 이름
+     */
+    async getRoleByName(name: string): Promise<LogtoRoleResponse> {
+        await this.getAccessToken();
+        const params = new URLSearchParams();
+        params.set('search.name', name);
+        const response = await this.apiRestTemplate.get<LogtoRoleResponse[]>(
+            `/roles?${params.toString()}`,
+        );
+        return response.data[0];
+    }
+
+    /**
+     * 역할 생성 (이미 존재하면 기존 역할 반환)
+     * @param role 역할 정보
+     */
+    async createRole(role: LogtoRole): Promise<LogtoRoleResponse> {
+        await this.getAccessToken();
+        const body = {
+            name: role.name,
+            description: role.description,
+            type: role.type,
+        };
+
+        const response = await this.apiRestTemplate.post<LogtoRoleResponse>(
+            '/roles',
+            body,
+        );
+
+        if (response instanceof axiosAdapter.ValidationError) {
+            if (response.code === 'role.name_in_use') {
+                this.logger.error(
+                    `이미 존재하는 역할: ${response.code}`,
+                    this.constructor.name,
+                );
+                return this.getRoleByName(role.name);
+            }
+            throw response;
+        }
+
+        return response.data;
+    }
+
+    /**
+     * 사용자에게 역할 할당
+     * @param userId 사용자 ID
+     * @param roleId 역할 ID
+     */
+    async assignRoleToUser(userId: string, roleId: string): Promise<void> {
+        await this.getAccessToken();
+        const body = { roleIds: [roleId] };
+        await this.apiRestTemplate.post(`/users/${userId}/roles`, body);
+        this.logger.log(
+            `사용자에 역할 할당: ${userId}`,
+            this.constructor.name,
+        );
+    }
+
+    // =========================
+    // 3. 사용자(User) 관리
+    // =========================
+
+    /**
+     * 사용자 생성
+     * @param user 사용자 정보
+     * @returns 생성된 사용자 ID
+     */
+    async createUser(user: LogtoUser): Promise<string> {
+        await this.getAccessToken();
+
+        if (user.username && user.primaryEmail && user.password && user.primaryPhone && user.name) {
+            user.passwordAlgorithm = user.passwordAlgorithm ?? LogtoPasswordAlgorithm.Argon2i;
+            const response = await this.apiRestTemplate.post<{ id: string }>('/users', user);
+            return response.data.id;
+        }
+
+        this.logger.error(`필수 필드 누락`, this.constructor.name);
+        throw new UserMissingRequiredFieldsError();
+    }
+
+    /**
+     * 사용자 customData.clientId 정보 업데이트
+     * @param userId 사용자 ID
+     * @param clientId 고객사 ID
+     */
+    async updateUserClientInfo(
+        userId: string,
+        clientId?: string,
+    ): Promise<void> {
+        await this.getAccessToken();
+        await this.apiRestTemplate.patch(`/users/${userId}`, {
+            customData: { clientId },
+        });
+    }
+
+    /**
+     * 사용자 ID로 사용자 정보 조회
+     * @param id 사용자 ID
+     */
+    async getUser(id: string): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+        const response = await this.apiRestTemplate.get<LogtoUserResponse>(`/users/${id}`);
+        return response.data;
+    }
+
+    /**
+     * 이메일+휴대폰으로 사용자 단일 조회 (여러명/없음 예외 처리)
+     * @param email 이메일
+     * @param phone 휴대폰번호
+     */
+    async getUsersByEmailAndPhone(
+        email: string,
+        phone: string,
+    ): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+
+        const params = new URLSearchParams();
+        params.set('search.primaryEmail', email);
+        params.set('search.primaryPhone', generatePhoneNumberWithCountryCode('82', phone));
+        params.set('joint', 'and');
+        params.set('mode.primaryEmail', 'exact');
+        params.set('mode.primaryPhone', 'exact');
+
+        const response = await this.apiRestTemplate.get<LogtoUserResponse[]>(
+            `/users?${params.toString()}`,
+        );
+        const logtoUsers = response.data;
+
+        if (logtoUsers.length === 1) {
+            return logtoUsers[0];
+        }
+        if (logtoUsers.length === 0) {
+            this.logger.error(`사용자 없음: email=${email}, phone=${phone}`, this.constructor.name);
+            throw new UserNotFoundError(email, phone);
+        }
+        this.logger.error(`여러 사용자 발견: email=${email}, phone=${phone}`, this.constructor.name);
+        this.logger.error(JSON.stringify(logtoUsers), this.constructor.name);
+        throw new MultipleUsersFoundError(email, phone);
+    }
+
+    /**
+     * username으로 사용자 단일 조회
+     * @param username 사용자명
+     */
+    async getUserByUsername(username: string): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+
+        const params = new URLSearchParams();
+        params.set('search.username', username);
+        params.set('mode.username', 'exact');
+
+        const response = await this.apiRestTemplate.get<LogtoUserResponse[]>(
+            `/users?${params.toString()}`,
+        );
+        return response.data[0];
+    }
+
+    /**
+     * 사용자 정지
+     * @param userId 사용자 ID
+     */
+    async suspendUser(userId: string): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+        const response = await this.apiRestTemplate.patch<LogtoUserResponse>(
+            `/users/${userId}/is-suspended`,
+            { isSuspended: true },
+        );
+        return response.data;
+    }
+
+    /**
+     * 사용자 삭제
+     * @param userId 사용자 ID
+     */
+    async deleteUser(userId: string): Promise<void> {
+        await this.getAccessToken();
+        await this.apiRestTemplate.delete(`/users/${userId}`);
+    }
+
+    /**
+     * 사용자 정지 해제
+     * @param userId 사용자 ID
+     */
+    async unsuspendUser(userId: string): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+        const response = await this.apiRestTemplate.patch<LogtoUserResponse>(
+            `/users/${userId}/is-suspended`,
+            { isSuspended: false },
+        );
+        return response.data;
+    }
+
+    /**
+     * 인증코드 발송 (이메일/휴대폰)
+     * @param identifier 이메일 또는 휴대폰
+     */
+    async sendVerificationCode(
+        identifier: p3Values.PhoneNumber | p3Values.Email,
+    ): Promise<void> {
+        await this.getAccessToken();
+
+        // VerificationMethodType.email/phone은 클래스(static)로 정의되어 있음
+        const method =
+            identifier instanceof VerificationMethodType.email
+                ? "email"
+                : "phone";
+
+        await this.apiRestTemplate.post('/verification-codes', {
+            [method]: identifier.toString(),
+        });
+    }
+
+    /**
+     * 인증코드 검증
+     * @param identifier 이메일 또는 휴대폰
+     * @param code 인증코드
+     */
+    async verifyCode(
+        identifier: p3Values.PhoneNumber | p3Values.Email,
+        code: string,
+    ): Promise<void> {
+        await this.getAccessToken();
+
+        const method =
+            identifier instanceof VerificationMethodType.email
+                ? 'email'
+                : 'phone';
+
+        await this.apiRestTemplate.post(`/verification-codes/verify`, {
+            [method]: identifier.toString(),
+            verificationCode: code,
+        });
+    }
+
+    /**
+     * 사용자 비밀번호 변경
+     * @param userId 사용자 ID
+     * @param password 새 비밀번호
+     */
+    async updateUserPassword(userId: string, password: string): Promise<LogtoUserResponse> {
+        await this.getAccessToken();
+        const response = await this.apiRestTemplate.patch<LogtoUserResponse>(
+            `/users/${userId}/password`,
+            { password },
+        );
+        return response.data;
+    }
+}
+
+/**
+ * 국가번호와 휴대폰번호를 합쳐 국제전화번호 형태로 반환
+ * @param countryCode 국가번호 (예: '82')
+ * @param phoneNumber 휴대폰번호 (예: '01012345678')
+ * @returns 국제전화번호 (예: '821012345678')
+ */
+export function generatePhoneNumberWithCountryCode(countryCode: string, phoneNumber: string): string {
+    if (phoneNumber.startsWith('0')) {
+        phoneNumber = phoneNumber.slice(1);
+    }
+    return `${countryCode}${phoneNumber}`;
+}

package/client/oauth-client.ts

@@ -0,0 +1,231 @@
+import { Inject, Injectable, Global, LoggerService } from "@nestjs/common";
+import axios, { AxiosResponse } from "axios";
+import { GrantType, Prompt, LogtoConfig } from "./config";
+import { ConfigService } from "@nestjs/config";
+import { axiosAdapter, p3Values } from "point3-common-tool";
+import {
+    TokenRevocationFailedError,
+    AuthorizationCodeTokenFetchError,
+    SignInUriGenerationError,
+    SignOutUriGenerationError,
+} from "../errors";
+import { LogtoLoggerServiceToken, LogtoOAuthRESTTemplate } from "./types";
+
+const Gulid = p3Values.Gulid;
+
+/** DI 토큰 */
+export const OAuthClientToken = "OAuthClient";
+
+/**
+ * OAuthClient
+ *
+ * Logto OAuth 인증을 위한 클라이언트 서비스입니다.
+ * 로그인/로그아웃 URI 생성, 토큰 발급 및 해지 등 OAuth 인증 플로우의 핵심 기능을 제공합니다.
+ * NestJS DI 환경에서 사용되며, Logto와의 통합 인증 처리를 담당합니다.
+ *
+ * 주요 역할:
+ *   - 로그인/로그아웃 URI 생성
+ *   - 인증 코드로 액세스 토큰 및 ID 토큰 발급
+ *   - 토큰 해지(로그아웃)
+ *   - Logto OAuth 관련 예외 및 로깅 처리
+ *
+ * 사용 예시:
+ *   const client = new OAuthClient(...);
+ *   const { uri, state } = client.getSignInURI(SignInType.Admin);
+ *   const tokens = await client.fetchTokenByAuthorizationCode(code);
+ *   await client.revokeToken(tokens.accessToken);
+ *
+ */
+@Global()
+@Injectable()
+export class OAuthClient {
+    /** Logto 설정 정보 */
+    private logtoConfig: LogtoConfig;
+    /** OAuth REST 템플릿 */
+    private logtoRestTemplate: axiosAdapter.RESTTemplate;
+    /** 상태값 prefix (CSRF 방지용) */
+    static readonly prefix: string = "signin";
+
+    /**
+     * 생성자
+     * @param configService 환경설정 서비스
+     * @param logger 로거 서비스
+     */
+    constructor(
+        @Inject(ConfigService)
+        private configService: ConfigService,
+
+        @Inject(LogtoLoggerServiceToken)
+        private logger: LoggerService
+    ) {
+        // Logto 설정 초기화
+        this.logtoConfig = {
+            endpoint: this.configService.get<string>("LOGTO_AUTH_ENDPOINT")!,
+            appId: this.configService.get<string>("LOGTO_CLIENT_ID")!,
+            appSecret: this.configService.get<string>("LOGTO_CLIENT_SECRET")!,
+            resources: [this.configService.get<string>("LOGTO_RESOURCES")!],
+            scopes: this.configService.get<string>("LOGTO_SCOPES")!.split(","),
+            prompt: this.configService.get<string>("LOGTO_PROMPT")! as Prompt,
+            redirectUri: this.configService.get<string>("LOGTO_REDIRECT_URI")!,
+            grantType: GrantType.AuthorizationCode,
+        };
+
+        // REST 템플릿 및 Basic Auth 설정
+        this.logtoRestTemplate = new LogtoOAuthRESTTemplate(
+            logger,
+            this.logtoConfig.endpoint
+        );
+        this.logtoRestTemplate.setBasic(
+            this.logtoConfig.appId!,
+            this.logtoConfig.appSecret!
+        );
+    }
+
+    /**
+     * 로그인 URI 생성
+     * @param signInType 로그인 타입 (Admin | Dashboard)
+     * @returns { uri, state } 로그인 URI와 상태값
+     */
+    public getSignInURI(
+        signInType: SignInType
+    ): { uri: string; state: string } {
+        try {
+            let uri: URL;
+
+            // 대시보드 로그인일 경우 별도 URI, 실패시 기본 URI로 폴백
+            if (signInType === SignInType.Dashboard) {
+                try {
+                    uri = new URL(
+                        `${this.configService.get<string>(
+                            "LOGTO_DASHBOARD_SIGN_IN_URI"
+                        )}/auth`
+                    );
+                } catch (error) {
+                    this.logger.warn(
+                        "대시보드 로그인 URI 설정을 찾을 수 없어 기본 URI를 사용합니다.",
+                        this.constructor.name
+                    );
+                    uri = new URL(
+                        `${this.configService.get<string>("LOGTO_SIGN_IN_URI")}/auth`
+                    );
+                }
+            } else {
+                uri = new URL(
+                    `${this.configService.get<string>("LOGTO_SIGN_IN_URI")}/auth`
+                );
+            }
+
+            // 상태값 생성 (CSRF 방지)
+            const state = Gulid.create(OAuthClient.prefix);
+
+            // OAuth 필수 파라미터 설정
+            uri.searchParams.set("redirect_uri", this.logtoConfig.redirectUri!);
+            uri.searchParams.set("response_type", "code");
+            uri.searchParams.set("scope", this.logtoConfig.scopes!.join(" "));
+            uri.searchParams.set("prompt", this.logtoConfig.prompt!);
+            uri.searchParams.set("client_id", this.logtoConfig.appId!);
+            uri.searchParams.set("resource", this.logtoConfig.resources!.join(" "));
+            uri.searchParams.set("state", state.toString());
+
+            return { uri: uri.toString(), state: state.toString() };
+        } catch (error) {
+            throw new SignInUriGenerationError(signInType);
+        }
+    }
+
+    /**
+     * 로그아웃 URI 생성
+     * @returns 로그아웃 URI
+     */
+    public async getSignOutURI(): Promise<string> {
+        try {
+            const uri = new URL(
+                `${this.configService.get<string>("LOGTO_SIGN_IN_URI")}/session/end`
+            );
+
+            // 로그아웃 후 리다이렉트 URI 및 클라이언트 ID 설정
+            uri.searchParams.set("redirect_uri", this.logtoConfig.redirectUri!);
+            uri.searchParams.set("client_id", this.logtoConfig.appId!);
+            return uri.toString();
+        } catch (error) {
+            throw new SignOutUriGenerationError();
+        }
+    }
+
+    /**
+     * 인증 코드로 액세스 토큰 및 ID 토큰 발급
+     * @param code OAuth 인증 코드
+     * @returns { accessToken, idToken } 액세스 토큰과 ID 토큰
+     */
+    public async fetchTokenByAuthorizationCode(
+        code: string
+    ): Promise<{ accessToken: string; idToken: string }> {
+        try {
+            // 토큰 요청 파라미터 설정
+            const parameters = new URLSearchParams();
+            parameters.set("code", code);
+            parameters.set("grant_type", this.logtoConfig.grantType);
+            parameters.set("redirect_uri", this.logtoConfig.redirectUri!);
+            parameters.set("resource", this.logtoConfig.resources!.join(" "));
+            parameters.set("scope", this.logtoConfig.scopes!.join(" "));
+
+            // 토큰 엔드포인트 호출
+            const response = await this.logtoRestTemplate.post<TokenResponse>(
+                `${this.logtoConfig.endpoint}/token`,
+                parameters.toString()
+            );
+            return {
+                accessToken: response.data.access_token,
+                idToken: response.data.id_token,
+            };
+        } catch (error) {
+            throw new AuthorizationCodeTokenFetchError(code);
+        }
+    }
+
+    /**
+     * 토큰 해지
+     * @param token 해지할 토큰
+     */
+    public async revokeToken(token: string): Promise<void> {
+        try {
+            const response: AxiosResponse = await axios.post(
+                `${this.logtoConfig.endpoint}/token/revoke`,
+                new URLSearchParams({
+                    token: token,
+                    client_id: this.logtoConfig.appId!,
+                }).toString(),
+                {
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                }
+            );
+
+            if (response.status === 200) return;
+
+            throw new TokenRevocationFailedError();
+        } catch (error) {
+            throw new TokenRevocationFailedError();
+        }
+    }
+}
+
+/**
+ * 로그인 타입 열거형
+ * - Admin: 관리자 로그인
+ * - Dashboard: 대시보드 로그인
+ */
+export enum SignInType {
+    Admin = "admin",
+    Dashboard = "dashboard",
+}
+
+/**
+ * 토큰 응답 타입
+ */
+type TokenResponse = {
+    access_token: string; // 액세스 토큰
+    refresh_token?: string; // 리프레시 토큰 (선택)
+    id_token: string; // ID 토큰
+    scope: string; // 부여된 스코프
+    expires_in: number; // 토큰 만료 시간(초)
+};