@point3/logto-module 1.0.22 → 1.1.0

package/module.ts

@@ -1,93 +1,237 @@
-import { DynamicModule, Module, Provider, Type } from '@nestjs/common';
+import { DynamicModule, LoggerService, Provider, Type } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { 
-  LogtoLoggerServiceToken, 
-  LogtoLoginSessionToken, 
-  LogtoM2MClientToken,
-  OAuthClient,
-  OAuthClientToken,
-  LogtoLoginSession,
-  LogtoM2MClient,
+import {
+    LogtoLoggerServiceToken,
+    LogtoLoginSessionToken,
+    LogtoM2MClientToken,
+    OAuthClient,
+    OAuthClientToken,
+    LogtoLoginSession,
+    LogtoM2MClient,
+    Prompt,
 } from './client';
 import { LogtoTokenVerifier, LogtoTokenVerifierToken } from './token';
 import { LogtoTokenGuard, LogtoTokenGuardToken } from './stateless';
 
+/** LogtoModule 옵션 주입 토큰 */
+export const LOGTO_MODULE_OPTIONS = Symbol('LOGTO_MODULE_OPTIONS');
+
+/** 로거 설정 */
+export interface LogtoLoggerOptions {
+    /** 로거 모듈 (forRoot에서만 필요) */
+    module?: Type<any>;
+    /** 로거 서비스의 Injection Token */
+    token: Symbol | string;
+}
+
+/** forRoot 옵션 */
+export interface LogtoModuleOptions {
+    /** 모듈을 전역으로 설정할지 여부 */
+    global?: boolean;
+    /** 클라이언트 기능 활성화 (OAuthClient, LogtoM2MClient, LogtoLoginSession) */
+    enableClient?: boolean;
+    /** 로거 설정 */
+    logger: LogtoLoggerOptions & { module: Type<any> };
+}
+
+/** forRootAsync useFactory 반환 타입 */
+export interface LogtoModuleFactoryOptions {
+    /** 클라이언트 기능 활성화 */
+    enableClient?: boolean;
+}
+
+/** forRootAsync 옵션 */
+export interface LogtoModuleAsyncOptions {
+    /** 모듈을 전역으로 설정할지 여부 */
+    global?: boolean;
+    /** 의존 모듈 목록 (로거 모듈 포함) */
+    imports?: Type<any>[];
+    /** 로거 서비스의 Injection Token */
+    loggerToken: Symbol | string;
+    /** 옵션 팩토리 함수 */
+    useFactory: (...args: any[]) => LogtoModuleFactoryOptions | Promise<LogtoModuleFactoryOptions>;
+    /** 팩토리 함수에 주입할 의존성 */
+    inject?: any[];
+}
+
 /**
  * LogtoModule
  *
  * Logto 인증 및 토큰 검증, 클라이언트 기능을 NestJS 모듈로 제공합니다.
  *
- * 이 모듈은 `LOGTO_CLIENT` 환경 변수 값에 따라 동적으로 구성됩니다.
- * - **Stateless 모드 (`LOGTO_CLIENT=false` 또는 미설정)**:
- *   API 서버와 같이 토큰 검증만 필요한 경우 사용합니다. `@LogtoProtected()` 가드와 `LogtoTokenVerifier`만 활성화되어 최소한의 리소스를 사용합니다.
- *
- * - **Stateful 모드 (`LOGTO_CLIENT=true`)**:
- *   로그인/로그아웃 처리가 필요한 웹 애플리케이션이나, M2M 통신으로 Logto의 User/Role 관리 API를 사용해야 할 경우에 사용합니다.
- *   `OAuthClient`, `LogtoM2MClient` 등 모든 클라이언트 기능이 추가로 활성화됩니다.
+ * - **Stateless 모드 (enableClient=false)**:
+ *   API 서버와 같이 토큰 검증만 필요한 경우 사용합니다.
+ *   `@LogtoProtected()` 가드와 `LogtoTokenVerifier`만 활성화됩니다.
  *
- *외부 로거 모듈과 연동하여 일관된 로깅을 지원합니다.
-**/
+ * - **Stateful 모드 (enableClient=true)**:
+ *   로그인/로그아웃 처리가 필요한 웹 애플리케이션이나,
+ *   M2M 통신으로 Logto의 User/Role 관리 API를 사용해야 할 경우에 사용합니다.
+ *   `OAuthClient`, `LogtoM2MClient` 등 모든 클라이언트 기능이 활성화됩니다.
+ */
 export class LogtoModule {
-
     /**
-     * forLogger
+     * forRoot
      *
-     * 외부 로거와 연동하여 LogtoModule을 초기화합니다.
+     * LogtoModule을 초기화합니다. (동기 설정)
      *
-     * @param loggerModule - DI에 등록된 로거 모듈 (예: WinstonLoggerModule)
-     * @param loggerToken - DI에 등록된 로거 서비스의 Injection Token
-     * @param global - 모듈을 전역(Global)으로 설정할지 여부 (기본값: false)
+     * @param options - 모듈 설정 옵션
      * @returns DynamicModule
      *
      * @example
-     * // src/app.module.ts
-     *
-     * import { Module } from '@nestjs/common';
-     * import { ConfigModule } from '@nestjs/config';
-     * import { LogtoModule } from 'point3-logto-module';
-     * // `MyLoggerModule`과 `MY_LOGGER_TOKEN`은 사용하는 로깅 시스템에 맞게 구현해야 합니다.
-     * import { MyLoggerModule, MY_LOGGER_TOKEN } from './common/logger';
-     *
-     * \@Module({
-     *   imports: [
-     *     // .env 파일을 읽기 위해 ConfigModule을 먼저 임포트합니다.
-     *     ConfigModule.forRoot({ isGlobal: true }),
-     *
-     *     // LogtoModule을 설정합니다.
-     *     // `LOGTO_CLIENT` 환경변수 값에 따라 필요한 서비스만 주입됩니다.
-     *     LogtoModule.forLogger(MyLoggerModule, MY_LOGGER_TOKEN, true),
-     *   ],
+     * // Stateless 모드: 토큰 검증만 필요한 경우
+     * LogtoModule.forRoot({
+     *   global: true,
+     *   logger: { module: WinstonLoggerModule, token: 'LOGGER' },
      * })
-     * export class AppModule {}
      *
      * @example
-     * // src/my-api.controller.ts (Stateless 모드 사용 예시)
+     * // Stateful 모드: 클라이언트 기능이 필요한 경우
+     * LogtoModule.forRoot({
+     *   global: true,
+     *   enableClient: true,
+     *   logger: { module: WinstonLoggerModule, token: 'LOGGER' },
+     * })
+     */
+    static forRoot(options: LogtoModuleOptions): DynamicModule {
+        const { global = false, enableClient = false, logger } = options;
+
+        const baseProviders: Provider[] = [
+            {
+                provide: LogtoLoggerServiceToken,
+                useExisting: logger.token,
+            },
+            {
+                provide: LogtoTokenVerifierToken,
+                useFactory: (configService: ConfigService) => {
+                    return new LogtoTokenVerifier({
+                        jwksUri: configService.get<string>('LOGTO_JWKS_URI') ?? 'http://localhost:3001/oidc/jwks',
+                        issuer: configService.getOrThrow<string>('LOGTO_AUTH_ISSUER'),
+                    });
+                },
+                inject: [ConfigService],
+            },
+            {
+                provide: LogtoTokenGuardToken,
+                useClass: LogtoTokenGuard,
+            },
+        ];
+
+        const clientProviders: Provider[] = enableClient
+            ? [
+                  {
+                      provide: OAuthClientToken,
+                      useFactory: (configService: ConfigService, loggerService: LoggerService) => {
+                          return new OAuthClient(
+                              {
+                                  endpoint: configService.getOrThrow<string>('LOGTO_AUTH_ENDPOINT'),
+                                  clientId: configService.getOrThrow<string>('LOGTO_CLIENT_ID'),
+                                  clientSecret: configService.getOrThrow<string>('LOGTO_CLIENT_SECRET'),
+                                  resources: [configService.getOrThrow<string>('LOGTO_RESOURCES')],
+                                  scopes: configService.getOrThrow<string>('LOGTO_SCOPES').split(','),
+                                  prompt: configService.getOrThrow<string>('LOGTO_PROMPT') as Prompt,
+                                  redirectUri: configService.getOrThrow<string>('LOGTO_REDIRECT_URI'),
+                                  signInUri: configService.getOrThrow<string>('LOGTO_SIGN_IN_URI'),
+                                  dashboardSignInUri: configService.get<string>('LOGTO_DASHBOARD_SIGN_IN_URI'),
+                              },
+                              loggerService,
+                          );
+                      },
+                      inject: [ConfigService, LogtoLoggerServiceToken],
+                  },
+                  {
+                      provide: LogtoLoginSessionToken,
+                      useFactory: (
+                          configService: ConfigService,
+                          loggerService: LoggerService,
+                          oauthClient: OAuthClient,
+                      ) => {
+                          return new LogtoLoginSession(
+                              configService.getOrThrow<string>('LOGTO_M2M_API_URL'),
+                              loggerService,
+                              oauthClient,
+                          );
+                      },
+                      inject: [ConfigService, LogtoLoggerServiceToken, OAuthClientToken],
+                  },
+                  {
+                      provide: LogtoM2MClientToken,
+                      useFactory: (
+                          configService: ConfigService,
+                          tokenVerifier: LogtoTokenVerifier,
+                          loggerService: LoggerService,
+                      ) => {
+                          return new LogtoM2MClient(
+                              {
+                                  endpoint: configService.getOrThrow<string>('LOGTO_AUTH_ENDPOINT'),
+                                  clientId: configService.getOrThrow<string>('LOGTO_M2M_CLIENT_ID'),
+                                  clientSecret: configService.getOrThrow<string>('LOGTO_M2M_CLIENT_SECRET'),
+                                  resource: configService.getOrThrow<string>('LOGTO_M2M_RESOURCE'),
+                                  apiUrl: configService.getOrThrow<string>('LOGTO_M2M_API_URL'),
+                                  scopes: ['all'],
+                              },
+                              tokenVerifier,
+                              loggerService,
+                          );
+                      },
+                      inject: [ConfigService, LogtoTokenVerifierToken, LogtoLoggerServiceToken],
+                  },
+              ]
+            : [];
+
+        const providers = [...baseProviders, ...clientProviders];
+
+        return {
+            module: LogtoModule,
+            global,
+            imports: [ConfigModule, logger.module],
+            providers,
+            exports: providers,
+        };
+    }
+
+    /**
+     * forRootAsync
+     *
+     * LogtoModule을 초기화합니다. (비동기 설정, ConfigService 활용 가능)
      *
-     * import { Controller, Get } from '@nestjs/common';
-     * import { LogtoProtected } from 'point3-logto-module';
+     * @param options - 비동기 모듈 설정 옵션
+     * @returns DynamicModule
      *
-     * \@Controller('items')
-     * export class MyApiController {
-     *   \@Get('protected')
-     *   \@LogtoProtected() // 헤더의 Bearer 토큰을 자동으로 검증합니다.
-     *   getProtectedResource() {
-     *     return { message: 'This is a protected resource.' };
-     *   }
-     * }
+     * @example
+     * LogtoModule.forRootAsync({
+     *   global: true,
+     *   imports: [WinstonLoggerModule],
+     *   loggerToken: 'LOGGER',
+     *   useFactory: (configService: ConfigService) => ({
+     *     enableClient: configService.get('LOGTO_CLIENT') === 'true',
+     *   }),
+     *   inject: [ConfigService],
+     * })
      */
-    static forLogger(
-        loggerModule: Type<any>,
-        loggerToken: Symbol | string,
-        global: boolean = false,
-    ): DynamicModule {
+    static forRootAsync(options: LogtoModuleAsyncOptions): DynamicModule {
+        const { global = false, imports = [], loggerToken, useFactory, inject = [] } = options;
+
+        const asyncOptionsProvider: Provider = {
+            provide: LOGTO_MODULE_OPTIONS,
+            useFactory,
+            inject,
+        };
+
         const baseProviders: Provider[] = [
+            asyncOptionsProvider,
             {
                 provide: LogtoLoggerServiceToken,
                 useExisting: loggerToken,
             },
             {
                 provide: LogtoTokenVerifierToken,
-                useClass: LogtoTokenVerifier,
+                useFactory: (configService: ConfigService) => {
+                    return new LogtoTokenVerifier({
+                        jwksUri: configService.get<string>('LOGTO_JWKS_URI') ?? 'http://localhost:3001/oidc/jwks',
+                        issuer: configService.getOrThrow<string>('LOGTO_AUTH_ISSUER'),
+                    });
+                },
+                inject: [ConfigService],
             },
             {
                 provide: LogtoTokenGuardToken,
@@ -95,49 +239,89 @@ export class LogtoModule {
             },
         ];
 
-        const statefulProviders: Provider[] = [
+        const clientProviders: Provider[] = [
             {
                 provide: OAuthClientToken,
-                useFactory: (configService: ConfigService, logger: any) => {
-                    if (configService.get<string>('LOGTO_CLIENT')?.toLowerCase() === 'true') {
-                        return new OAuthClient(configService, logger);
+                useFactory: (
+                    opts: LogtoModuleFactoryOptions,
+                    configService: ConfigService,
+                    loggerService: LoggerService,
+                ) => {
+                    if (opts.enableClient) {
+                        return new OAuthClient(
+                            {
+                                endpoint: configService.getOrThrow<string>('LOGTO_AUTH_ENDPOINT'),
+                                clientId: configService.getOrThrow<string>('LOGTO_CLIENT_ID'),
+                                clientSecret: configService.getOrThrow<string>('LOGTO_CLIENT_SECRET'),
+                                resources: [configService.getOrThrow<string>('LOGTO_RESOURCES')],
+                                scopes: configService.getOrThrow<string>('LOGTO_SCOPES').split(','),
+                                prompt: configService.getOrThrow<string>('LOGTO_PROMPT') as Prompt,
+                                redirectUri: configService.getOrThrow<string>('LOGTO_REDIRECT_URI'),
+                                signInUri: configService.getOrThrow<string>('LOGTO_SIGN_IN_URI'),
+                                dashboardSignInUri: configService.get<string>('LOGTO_DASHBOARD_SIGN_IN_URI'),
+                            },
+                            loggerService,
+                        );
                     }
                     return null;
                 },
-                inject: [ConfigService, LogtoLoggerServiceToken],
+                inject: [LOGTO_MODULE_OPTIONS, ConfigService, LogtoLoggerServiceToken],
             },
             {
                 provide: LogtoLoginSessionToken,
-                useFactory: (configService: ConfigService, logger: any, oauthClient: OAuthClient) => {
-                    if (configService.get<string>('LOGTO_CLIENT')?.toLowerCase() === 'true') {
-                        return new LogtoLoginSession(logger, configService, oauthClient);
+                useFactory: (
+                    opts: LogtoModuleFactoryOptions,
+                    configService: ConfigService,
+                    loggerService: LoggerService,
+                    oauthClient: OAuthClient,
+                ) => {
+                    if (opts.enableClient) {
+                        return new LogtoLoginSession(
+                            configService.getOrThrow<string>('LOGTO_M2M_API_URL'),
+                            loggerService,
+                            oauthClient,
+                        );
                     }
                     return null;
                 },
-                inject: [ConfigService, LogtoLoggerServiceToken, OAuthClientToken],
+                inject: [LOGTO_MODULE_OPTIONS, ConfigService, LogtoLoggerServiceToken, OAuthClientToken],
             },
             {
                 provide: LogtoM2MClientToken,
-                useFactory: (configService: ConfigService, tokenVerifier: LogtoTokenVerifier, logger: any) => {
-                    if (configService.get<string>('LOGTO_CLIENT')?.toLowerCase() === 'true') {
-                        return new LogtoM2MClient(configService, tokenVerifier, logger);
+                useFactory: (
+                    opts: LogtoModuleFactoryOptions,
+                    configService: ConfigService,
+                    tokenVerifier: LogtoTokenVerifier,
+                    loggerService: LoggerService,
+                ) => {
+                    if (opts.enableClient) {
+                        return new LogtoM2MClient(
+                            {
+                                endpoint: configService.getOrThrow<string>('LOGTO_AUTH_ENDPOINT'),
+                                clientId: configService.getOrThrow<string>('LOGTO_M2M_CLIENT_ID'),
+                                clientSecret: configService.getOrThrow<string>('LOGTO_M2M_CLIENT_SECRET'),
+                                resource: configService.getOrThrow<string>('LOGTO_M2M_RESOURCE'),
+                                apiUrl: configService.getOrThrow<string>('LOGTO_M2M_API_URL'),
+                                scopes: ['all'],
+                            },
+                            tokenVerifier,
+                            loggerService,
+                        );
                     }
                     return null;
                 },
-                inject: [ConfigService, LogtoTokenVerifierToken, LogtoLoggerServiceToken],
+                inject: [LOGTO_MODULE_OPTIONS, ConfigService, LogtoTokenVerifierToken, LogtoLoggerServiceToken],
             },
         ];
-        
-        const providers = [...baseProviders, ...statefulProviders];
+
+        const providers = [...baseProviders, ...clientProviders];
 
         return {
             module: LogtoModule,
-            global: global,
-            imports: [
-                loggerModule,
-            ],
-            providers: providers,
+            global,
+            imports: [ConfigModule, ...imports],
+            providers,
             exports: providers,
         };
     }
-};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@point3/logto-module",
-  "version": "1.0.22",
+  "version": "1.1.0",
   "description": "포인트3 내부 logto Authentication 모듈입니다",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/token/verifier.ts

@@ -1,17 +1,14 @@
-import { Inject, Injectable, UnauthorizedException } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
+import { Injectable, UnauthorizedException } from "@nestjs/common";
 import { jwtVerify, createRemoteJWKSet } from "jose";
 
+import { LogtoVerifierConfig } from "../client/config";
 import * as token from "./access-token";
 
 export const LogtoTokenVerifierToken = Symbol.for("LogtoTokenVerifier");
 
 @Injectable()
 export class LogtoTokenVerifier {
-    constructor(
-        @Inject(ConfigService)
-        private readonly configService: ConfigService
-    ) { }
+    constructor(private readonly config: LogtoVerifierConfig) { }
 
     /**
      * 토큰을 검증하고 필요에 따라 필수 스코프와 역할을 확인합니다.
@@ -26,12 +23,9 @@ export class LogtoTokenVerifier {
     public async verifyToken(token: string, requiredScopes?: string[], requiredRoles?: string[]): Promise<token.AccessTokenPayload> {
         if (!token) throw new UnauthorizedException('엑세스 토큰이 존재하지 않습니다.');
 
-        const jwksUri = this.configService.get<string>("LOGTO_JWKS_URI") ?? 'http://localhost:3001/oidc/jwks';
-        const issuer = this.configService.get<string>("LOGTO_AUTH_ISSUER");
-
         const { payload } = await jwtVerify(
-            token, createRemoteJWKSet(new URL(jwksUri)),
-            { issuer }
+            token, createRemoteJWKSet(new URL(this.config.jwksUri)),
+            { issuer: this.config.issuer }
         );
 
         const tokenPayload = payload as token.AccessTokenPayload;
@@ -50,13 +44,10 @@ export class LogtoTokenVerifier {
      * @returns id token 페이로드입니다.
      */
     public async verifyIdToken(token: string): Promise<token.IdTokenPayload> {
-        const jwksUri = process.env.LOGTO_JWKS_URI ?? 'http://localhost:3001/oidc/jwks';
-        const issuer = process.env.LOGTO_AUTH_ISSUER;
-
         const { payload } = await jwtVerify(
             token,
-            createRemoteJWKSet(new URL(jwksUri)),
-            { issuer }
+            createRemoteJWKSet(new URL(this.config.jwksUri)),
+            { issuer: this.config.issuer }
         );
         return payload as token.IdTokenPayload;
     }
@@ -97,4 +88,4 @@ export class LogtoTokenVerifier {
     private hasInsufficientRoles(requiredRoles: string[] | undefined, userRoles: string[]): boolean {
         return !!(requiredRoles && requiredRoles.length > 0 && !requiredRoles.some(role => userRoles.includes(role)));
     }
-}
+}