@point3/logto-module 1.0.12 → 1.0.14

package/module.ts

@@ -1,88 +1,143 @@
-import { DynamicModule, Type } from '@nestjs/common';
-import { LogtoTokenGuard } from './stateless';
-import { LogtoTokenVerifier, LogtoTokenVerifierToken } from './token';
-import {
-    LogtoLoginSession, LogtoLoginSessionToken,
-    LogtoM2MClient, LogtoM2MClientToken,
-    OAuthClient, OAuthClientToken,
-    LogtoLoggerServiceToken
+import { DynamicModule, Module, Provider, Type } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { 
+  LogtoLoggerServiceToken, 
+  LogtoLoginSessionToken, 
+  LogtoM2MClientToken,
+  OAuthClient,
+  OAuthClientToken,
+  LogtoLoginSession,
+  LogtoM2MClient,
 } from './client';
+import { LogtoTokenVerifier, LogtoTokenVerifierToken } from './token';
+import { LogtoTokenGuard, LogtoTokenGuardToken } from './stateless';
 
 /**
  * LogtoModule
  *
- * Logto 인증 및 사용자/역할 관리 기능을 NestJS 모듈로 제공하는 번들입니다.
- * 외부에서 로거 모듈과 로거 토큰을 주입받아, 다양한 로깅 시스템과 연동이 가능합니다.
+ * Logto 인증 및 토큰 검증, 클라이언트 기능을 NestJS 모듈로 제공합니다.
+ *
+ * 이 모듈은 `LOGTO_CLIENT` 환경 변수 값에 따라 동적으로 구성됩니다.
+ * - **Stateless 모드 (`LOGTO_CLIENT=false` 또는 미설정)**:
+ *   API 서버와 같이 토큰 검증만 필요한 경우 사용합니다. `@LogtoProtected()` 가드와 `LogtoTokenVerifier`만 활성화되어 최소한의 리소스를 사용합니다.
  *
- * 사용 예시:
- * ```ts
- * import { LogtoModule } from 'point3-logto-module';
- * import { MyLoggerModule, MY_LOGGER_TOKEN } from './my-logger';
+ * - **Stateful 모드 (`LOGTO_CLIENT=true`)**:
+ *   로그인/로그아웃 처리가 필요한 웹 애플리케이션이나, M2M 통신으로 Logto의 User/Role 관리 API를 사용해야 할 경우에 사용합니다.
+ *   `OAuthClient`, `LogtoM2MClient` 등 모든 클라이언트 기능이 추가로 활성화됩니다.
  *
- * @Module({
- *   imports: [
- *     LogtoModule.forLogger(MyLoggerModule, MY_LOGGER_TOKEN)
- *   ]
- * })
- * export class AppModule {}
- * ```
- */
+ *외부 로거 모듈과 연동하여 일관된 로깅을 지원합니다.
+**/
 export class LogtoModule {
+
     /**
      * forLogger
      *
-     * 외부에서 로거 모듈과 로거 토큰을 받아 LogtoModule을 동적으로 생성합니다.
+     * 외부 로거와 연동하여 LogtoModule을 초기화합니다.
+     *
+     * @param loggerModule - DI에 등록된 로거 모듈 (예: WinstonLoggerModule)
+     * @param loggerToken - DI에 등록된 로거 서비스의 Injection Token
+     * @param global - 모듈을 전역(Global)으로 설정할지 여부 (기본값: false)
+     * @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),
+     *   ],
+     * })
+     * export class AppModule {}
+     *
+     * @example
+     * // src/my-api.controller.ts (Stateless 모드 사용 예시)
      *
-     * @param loggerModule - DI에 등록된 로거 모듈 (예: WinstonLoggerModule 등)
-     * @param loggerToken - DI에 등록된 로거 서비스 토큰(Symbol 또는 String)
-     * @param global - 모듈을 글로벌로 등록할지 여부 (기본값: false)
-     * @returns DynamicModule - Logto 인증/권한 기능이 포함된 NestJS 모듈
+     * import { Controller, Get } from '@nestjs/common';
+     * import { LogtoProtected } from 'point3-logto-module';
      *
-     * providers:
-     *   - LogtoLoggerServiceToken: 외부 로거 토큰을 useExisting으로 주입
-     *   - LogtoTokenVerifierToken, OAuthClientToken, LogtoLoginSessionToken, LogtoM2MClientToken, LogtoTokenGuard 등 핵심 서비스 제공
-     * exports:
-     *   - 주요 서비스 토큰 및 가드
+     * \@Controller('items')
+     * export class MyApiController {
+     *   \@Get('protected')
+     *   \@LogtoProtected() // 헤더의 Bearer 토큰을 자동으로 검증합니다.
+     *   getProtectedResource() {
+     *     return { message: 'This is a protected resource.' };
+     *   }
+     * }
      */
     static forLogger(
         loggerModule: Type<any>,
         loggerToken: Symbol | string,
         global: boolean = false,
     ): DynamicModule {
-        return {
-            module: LogtoModule,
-            global: global,
-            imports: [loggerModule],
-            providers: [
-                {
-                    provide: LogtoLoggerServiceToken,
-                    useExisting: loggerToken
-                },
-                {
-                    provide: LogtoTokenVerifierToken,
-                    useClass: LogtoTokenVerifier,
-                },
-                {
-                    provide: OAuthClientToken,
-                    useClass: OAuthClient,
+        const baseProviders: Provider[] = [
+            {
+                provide: LogtoLoggerServiceToken,
+                useExisting: loggerToken,
+            },
+            {
+                provide: LogtoTokenVerifierToken,
+                useClass: LogtoTokenVerifier,
+            },
+            {
+                provide: LogtoTokenGuardToken,
+                useClass: LogtoTokenGuard,
+            },
+        ];
+
+        const statefulProviders: Provider[] = [
+            {
+                provide: OAuthClientToken,
+                useFactory: (configService: ConfigService, logger: any) => {
+                    if (configService.get<string>('LOGTO_CLIENT')?.toLowerCase() === 'true') {
+                        return new OAuthClient(configService, logger);
+                    }
+                    return null;
                 },
-                {
-                    provide: LogtoLoginSessionToken,
-                    useClass: LogtoLoginSession
+                inject: [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);
+                    }
+                    return null;
                 },
-                {
-                    provide: LogtoM2MClientToken,
-                    useClass: LogtoM2MClient
+                inject: [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);
+                    }
+                    return null;
                 },
-                LogtoTokenGuard
+                inject: [ConfigService, LogtoTokenVerifierToken, LogtoLoggerServiceToken],
+            },
+        ];
+        
+        const providers = [...baseProviders, ...statefulProviders];
+
+        return {
+            module: LogtoModule,
+            global: global,
+            imports: [
+                loggerModule,
             ],
-            exports: [
-                OAuthClientToken,
-                LogtoM2MClientToken,
-                LogtoTokenVerifierToken,
-                LogtoLoginSessionToken,
-                LogtoTokenGuard,
-            ]
-        }
+            providers: providers,
+            exports: providers,
+        };
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@point3/logto-module",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "포인트3 내부 logto Authentication 모듈입니다",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,8 @@
     "point3-common-tool": "^1.0.13"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.14"
+    "@types/jest": "^29.5.14",
+    "typescript": "^5.8.3"
   },
   "repository": {
     "type": "git",

package/stateless/guard.ts

@@ -5,7 +5,6 @@ import {
   UnauthorizedException, 
   InternalServerErrorException,
   Inject, 
-  Global, 
   HttpStatus 
 } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
@@ -14,16 +13,17 @@ import { IncomingHttpHeaders } from 'http';
 import { errors } from 'jose';
 
 import { p3Values } from 'point3-common-tool';
-import * as token from '../token';
+import { LogtoTokenVerifier, LogtoTokenVerifierToken } from '../token';
+
+export const LogtoTokenGuardToken = Symbol('LogtoTokenGuard');
 
-@Global()
 @Injectable()
 export class LogtoTokenGuard implements CanActivate {
   constructor(
     private reflector: Reflector,
 
-    @Inject(token.LogtoTokenVerifierToken)
-    private tokenVerifier: token.LogtoTokenVerifier
+    @Inject(LogtoTokenVerifierToken)
+    private tokenVerifier: LogtoTokenVerifier
   ) { }
 
   async canActivate(context: ExecutionContext): Promise<boolean> {

package/token/verifier.ts

@@ -1,4 +1,4 @@
-import { Global, Inject, Injectable, UnauthorizedException } from "@nestjs/common";
+import { Inject, Injectable, UnauthorizedException } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { jwtVerify, createRemoteJWKSet } from "jose";
 
@@ -6,7 +6,6 @@ import * as token from "./access-token";
 
 export const LogtoTokenVerifierToken = Symbol.for("LogtoTokenVerifier");
 
-@Global()
 @Injectable()
 export class LogtoTokenVerifier {
     constructor(