@point3/logto-module 1.0.22 → 1.1.0

package/.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,7 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="TsLint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

package/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="KubernetesApiProvider">{}</component>
+  <component name="ProjectRootManager">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/point3-logto-module.iml" filepath="$PROJECT_DIR$/.idea/point3-logto-module.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/point3-logto-module.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.serena/project.yml

@@ -0,0 +1,87 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          fsharp
+#   go               groovy           haskell          java             julia            kotlin
+#   lua              markdown         nix              pascal           perl             php
+#   powershell       python           python_jedi      r                rego             ruby
+#   ruby_solargraph  rust             scala            swift            terraform        toml
+#   typescript       typescript_vts   yaml             zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal / Lazarus, use pascal
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+#   - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "point3-logto-module"
+included_optional_tools: []

package/README.md

@@ -1,27 +1,27 @@
 # point3-logto-module
 
-NestJS 기반 Logto 인증/권한 통합 모듈  
+NestJS 기반 Logto 인증/권한 통합 모듈
 (서버/클라이언트, M2M, 사용자/역할 관리, OAuth, DI 기반 확장성 제공)
 
 ---
 
 ## 📦 개요
 
-`@point3-logto-module`은 [Logto](https://logto.io/) 인증 시스템을 NestJS 환경에서 손쉽게 통합할 수 있도록 설계된 모듈 번들입니다.  
+`@point3-logto-module`은 [Logto](https://logto.io/) 인증 시스템을 NestJS 환경에서 손쉽게 통합할 수 있도록 설계된 모듈 번들입니다.
 OAuth, M2M(Machine-to-Machine), 사용자/역할 관리, 토큰 검증, 인증 가드 등 인증/권한 관련 기능을 일관된 DI 패턴으로 제공합니다.
 
 ### 동작 모드
 
-`LOGTO_CLIENT` 환경변수 값에 따라 두 가지 모드로 동작합니다:
+`enableClient` 옵션에 따라 두 가지 모드로 동작합니다:
 
-- **Stateless 모드 (`LOGTO_CLIENT=false` 또는 미설정)**: 
+- **Stateless 모드 (`enableClient: false` 또는 미설정)**:
   - API 서버와 같이 토큰 검증만 필요한 경우 사용
   - `@LogtoProtected()` 가드와 `LogtoTokenVerifier`만 활성화
-  - 필수 환경변수: `LOGTO_JWKS_URI`, `LOGTO_AUTH_ISSUER`만 필요
+  - 필수 환경변수: `LOGTO_AUTH_ISSUER`만 필요 (LOGTO_JWKS_URI는 선택)
 
-- **Stateful 모드 (`LOGTO_CLIENT=true`)**:
+- **Stateful 모드 (`enableClient: true`)**:
   - 로그인/로그아웃 처리가 필요한 웹 애플리케이션이나 M2M 통신이 필요한 경우 사용
-  - `OAuthClient`, `LogtoM2MClient` 등 모든 클라이언트 기능 활성화
+  - `OAuthClient`, `LogtoM2MClient`, `LogtoLoginSession` 등 모든 클라이언트 기능 활성화
   - 추가 환경변수 필요 (OAuth, M2M 관련)
 
 ### 주요 특징
@@ -30,6 +30,7 @@ OAuth, M2M(Machine-to-Machine), 사용자/역할 관리, 토큰 검증, 인증
 - **NestJS Dynamic Module 패턴**: 환경/구성에 따라 동적으로 모듈 생성
 - **Global 모듈 지원**: 애플리케이션 전체에서 사용할 수 있는 글로벌 모듈로 설정 가능
 - **실제 서비스에서 검증된 인증/권한 관리 기능**: OAuth, M2M, 사용자/역할 관리, 토큰 검증, 인증 가드 등
+- **Fail-fast 환경변수 검증**: 필수 환경변수가 없으면 모듈 초기화 시 즉시 에러 발생
 
 ---
 
@@ -37,9 +38,9 @@ OAuth, M2M(Machine-to-Machine), 사용자/역할 관리, 토큰 검증, 인증
 
 ### 1. LogtoModule (Dynamic Module)
 
-- 외부에서 로거 모듈과 토큰을 주입받아, Logto 인증/권한 기능을 번들로 제공
-- `logto.module.LogtoModule.forLogger(loggerModule, loggerToken, global?)` 패턴으로 사용
-- global 파라미터를 true로 설정하면 애플리케이션 전체에서 사용 가능한 글로벌 모듈로 등록
+- 외부 로거 모듈과 토큰을 주입받아, Logto 인증/권한 기능을 번들로 제공
+- `LogtoModule.forRoot(options)` 또는 `LogtoModule.forRootAsync(options)` 패턴으로 사용
+- `global` 옵션을 `true`로 설정하면 애플리케이션 전체에서 사용 가능한 글로벌 모듈로 등록
 
 ### 2. 핵심 서비스/토큰
 
@@ -51,7 +52,13 @@ OAuth, M2M(Machine-to-Machine), 사용자/역할 관리, 토큰 검증, 인증
 - **LogtoLoggerServiceToken**: DI로 주입받는 외부 로거 토큰
 - **stateless**: 미들웨어/핸들러 기반의 Stateless 인증/인가 유틸리티 및 가드 제공
 
-### 3. 주요 타입/설정
+### 3. Config 인터페이스
+
+- **LogtoVerifierConfig**: 토큰 검증 설정 (jwksUri, issuer)
+- **LogtoOAuthConfig**: OAuth 클라이언트 설정 (endpoint, clientId, clientSecret, resources, scopes, prompt, redirectUri, signInUri, dashboardSignInUri)
+- **LogtoM2MConfig**: M2M 클라이언트 설정 (endpoint, clientId, clientSecret, resource, apiUrl, scopes)
+
+### 4. 주요 타입/설정
 
 - **LogtoConfig**: 인증/권한 기능을 위한 환경설정 객체
 - **Prompt, GrantType**: OAuth 표준 파라미터 Enum
@@ -90,7 +97,9 @@ export const MY_LOGGER_TOKEN = Symbol.for('LOGGER');
 export class MyLoggerModule {}
 ```
 
-### 2. AppModule에서 LogtoModule 동적 생성
+### 2. AppModule에서 LogtoModule 설정
+
+#### forRoot (동기 설정)
 
 ```ts
 import { Module } from '@nestjs/common';
@@ -102,9 +111,51 @@ import { MyLoggerModule, MY_LOGGER_TOKEN } from './my-logger.module';
   imports: [
     // 환경변수를 먼저 로드
     ConfigModule.forRoot({ isGlobal: true }),
-    
-    // LogtoModule을 글로벌 모듈로 설정 (세 번째 파라미터를 true로 설정)
-    logto.module.LogtoModule.forLogger(MyLoggerModule, MY_LOGGER_TOKEN, true),
+
+    // Stateless 모드: 토큰 검증만 필요한 경우
+    logto.module.LogtoModule.forRoot({
+      global: true,
+      logger: {
+        module: MyLoggerModule,
+        token: MY_LOGGER_TOKEN,
+      },
+    }),
+
+    // Stateful 모드: 클라이언트 기능이 필요한 경우
+    // logto.module.LogtoModule.forRoot({
+    //   global: true,
+    //   enableClient: true,
+    //   logger: {
+    //     module: MyLoggerModule,
+    //     token: MY_LOGGER_TOKEN,
+    //   },
+    // }),
+  ],
+})
+export class AppModule {}
+```
+
+#### forRootAsync (비동기 설정)
+
+```ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import * as logto from '@point3/logto-module';
+import { MyLoggerModule, MY_LOGGER_TOKEN } from './my-logger.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+
+    logto.module.LogtoModule.forRootAsync({
+      global: true,
+      imports: [MyLoggerModule],
+      loggerToken: MY_LOGGER_TOKEN,
+      useFactory: (configService: ConfigService) => ({
+        enableClient: configService.get('LOGTO_CLIENT') === 'true',
+      }),
+      inject: [ConfigService],
+    }),
   ],
 })
 export class AppModule {}
@@ -148,13 +199,13 @@ export class AuthService {
 
 ### 4. stateless 네임스페이스 활용 예시
 
-> ⚠️ **중요한 주의사항**  
-> `requiredScopes`와 `requiredRoles`에 사용되는 모든 스코프와 역할은 **반드시 Logto 관리 콘솔에서 먼저 정의되어야 합니다**.  
-> 
+> ⚠️ **중요한 주의사항**
+> `requiredScopes`와 `requiredRoles`에 사용되는 모든 스코프와 역할은 **반드시 Logto 관리 콘솔에서 먼저 정의되어야 합니다**.
+>
 > - **스코프(Scopes)**: Logto 콘솔의 API Resources → 해당 리소스 → Scopes에서 정의
-> - **역할(Roles)**: Logto 콘솔의 User Management → Roles에서 정의  
+> - **역할(Roles)**: Logto 콘솔의 User Management → Roles에서 정의
 > - **역할-스코프 연결**: 각 역할에 필요한 스코프들을 Logto 콘솔에서 할당
-> 
+>
 > 코드에서 사용하는 스코프/역할 이름이 Logto에 정의되지 않았다면 토큰 검증이 실패합니다.
 
 #### 4-1. LogtoProtected 데코레이터를 사용한 라우트 보호
@@ -263,19 +314,19 @@ export class CustomLogtoGuard extends stateless.LogtoTokenGuard {
   async canActivate(context: ExecutionContext): Promise<boolean> {
     // 기본 토큰 검증 수행
     const isValid = await super.canActivate(context);
-    
+
     if (!isValid) return false;
 
     // 추가 커스텀 로직
     const request = context.switchToHttp().getRequest();
     const user = request.user;
-    
+
     // 예: 특정 시간대에만 접근 허용
     const currentHour = new Date().getHours();
     if (currentHour < 9 || currentHour > 18) {
       return false;
     }
-    
+
     return true;
   }
 }
@@ -338,54 +389,44 @@ export class TypedController {
 
 ---
 
-## 📝 환경설정 예시 (`LogtoConfig`)
+## 🗂️ 환경변수 목록 및 설명
 
-```ts
-const config: LogtoConfig = {
-  endpoint: 'https://auth.example.com/oidc',
-  appId: 'my-client-id',
-  appSecret: 'my-client-secret',
-  grantType: GrantType.AuthorizationCode,
-  scopes: ['openid', 'profile', 'email'],
-  resources: ['https://api.example.com'],
-  prompt: Prompt.Login,
-  redirectUri: 'https://myapp.com/callback',
-};
-```
+### Stateless 모드 (토큰 검증만)
 
----
+| 환경변수명 | 필수 | 설명 | 예시 값 |
+|-----------|------|------|---------|
+| LOGTO_AUTH_ISSUER | ✅ | JWT 발급자(iss) | https://auth.example.com/oidc |
+| LOGTO_JWKS_URI | ❌ | JWT 검증용 JWKS 엔드포인트 (기본값: http://localhost:3001/oidc/jwks) | https://auth.example.com/oidc/jwks |
 
-## 🗂️ 환경변수 목록 및 설명
+### Stateful 모드 (`enableClient: true`)
+
+#### OAuth 클라이언트 관련 (OAuthClient, LogtoLoginSession)
 
-### 필수 환경변수 (Stateless/Stateful 모드 공통)
-
-| 환경변수명                        | 설명                                              | 예시 값                                  |
-|-----------------------------------|---------------------------------------------------|------------------------------------------|
-| LOGTO_JWKS_URI                    | JWT 검증용 JWKS 엔드포인트                        | https://auth.example.com/oidc/jwks       |
-| LOGTO_AUTH_ISSUER                 | JWT 발급자(iss)                                   | https://auth.example.com/oidc            |
-
-### 선택적 환경변수
-
-| 환경변수명                        | 설명                                              | 예시 값                                  | 필요 조건                               |
-|-----------------------------------|---------------------------------------------------|------------------------------------------|-----------------------------------------|
-| LOGTO_CLIENT                      | Stateful 모드 활성화 (클라이언트 기능 사용)       | true                                     | 클라이언트 기능 사용 시                 |
-| LOGTO_AUTH_ENDPOINT               | Logto 인증 서버 OIDC 엔드포인트                   | https://auth.example.com/oidc            | LOGTO_CLIENT=true                       |
-| LOGTO_CLIENT_ID                   | OAuth 클라이언트 ID                               | my-client-id                             | LOGTO_CLIENT=true                       |
-| LOGTO_CLIENT_SECRET               | OAuth 클라이언트 시크릿                           | my-client-secret                         | LOGTO_CLIENT=true                       |
-| LOGTO_RESOURCES                   | 접근할 리소스 서버(여러 개일 경우 쉼표로 구분)     | https://api.example.com                  | LOGTO_CLIENT=true                       |
-| LOGTO_SCOPES                      | 요청할 OAuth 스코프(쉼표로 구분)                  | openid,profile,email                     | LOGTO_CLIENT=true                       |
-| LOGTO_PROMPT                      | OAuth prompt 파라미터                             | login                                    | LOGTO_CLIENT=true                       |
-| LOGTO_REDIRECT_URI                | 인증 후 리다이렉트될 URI                          | https://myapp.com/callback               | LOGTO_CLIENT=true                       |
-| LOGTO_SIGN_IN_URI                 | 기본 로그인 URI                                   | https://auth.example.com                 | LOGTO_CLIENT=true                       |
-| LOGTO_DASHBOARD_SIGN_IN_URI       | 대시보드 로그인 URI(선택)                         | https://dashboard.example.com            | LOGTO_CLIENT=true                       |
-| LOGTO_M2M_CLIENT_ID               | M2M 인증용 클라이언트 ID                          | my-m2m-client-id                         | LOGTO_CLIENT=true & M2M 기능 사용 시    |
-| LOGTO_M2M_CLIENT_SECRET           | M2M 인증용 클라이언트 시크릿                      | my-m2m-client-secret                     | LOGTO_CLIENT=true & M2M 기능 사용 시    |
-| LOGTO_M2M_RESOURCE                | M2M 인증용 리소스                                 | https://api.example.com                  | LOGTO_CLIENT=true & M2M 기능 사용 시    |
-| LOGTO_M2M_API_URL                 | M2M API 서버의 base URL                           | https://api.example.com/api              | LOGTO_CLIENT=true & M2M 기능 사용 시    |
-
-> ⚠️ **중요**: 
-> - Stateless 모드(기본값): `LOGTO_JWKS_URI`와 `LOGTO_AUTH_ISSUER`만 설정하면 토큰 검증 기능을 사용할 수 있습니다.
-> - Stateful 모드: `LOGTO_CLIENT=true`로 설정하고 OAuth/M2M 관련 환경변수를 추가로 설정해야 합니다.
+| 환경변수명 | 필수 | 설명 | 예시 값 |
+|-----------|------|------|---------|
+| LOGTO_AUTH_ENDPOINT | ✅ | Logto 인증 서버 OIDC 엔드포인트 | https://auth.example.com/oidc |
+| LOGTO_CLIENT_ID | ✅ | OAuth 클라이언트 ID | my-client-id |
+| LOGTO_CLIENT_SECRET | ✅ | OAuth 클라이언트 시크릿 | my-client-secret |
+| LOGTO_RESOURCES | ✅ | 접근할 리소스 서버 | https://api.example.com |
+| LOGTO_SCOPES | ✅ | 요청할 OAuth 스코프 (쉼표로 구분) | openid,profile,email |
+| LOGTO_PROMPT | ✅ | OAuth prompt 파라미터 | login |
+| LOGTO_REDIRECT_URI | ✅ | 인증 후 리다이렉트될 URI | https://myapp.com/callback |
+| LOGTO_SIGN_IN_URI | ✅ | 기본 로그인 URI | https://auth.example.com |
+| LOGTO_DASHBOARD_SIGN_IN_URI | ❌ | 대시보드 로그인 URI (선택) | https://dashboard.example.com |
+
+#### M2M 클라이언트 관련 (LogtoM2MClient)
+
+| 환경변수명 | 필수 | 설명 | 예시 값 |
+|-----------|------|------|---------|
+| LOGTO_M2M_CLIENT_ID | ✅ | M2M 인증용 클라이언트 ID | my-m2m-client-id |
+| LOGTO_M2M_CLIENT_SECRET | ✅ | M2M 인증용 클라이언트 시크릿 | my-m2m-client-secret |
+| LOGTO_M2M_RESOURCE | ✅ | M2M 인증용 리소스 | https://api.example.com |
+| LOGTO_M2M_API_URL | ✅ | M2M API 서버의 base URL | https://api.example.com/api |
+
+> ⚠️ **중요**:
+> - 필수 환경변수(✅)가 설정되지 않으면 모듈 초기화 시 **즉시 에러가 발생**합니다.
+> - Stateless 모드에서는 `LOGTO_AUTH_ISSUER`만 필수입니다.
+> - Stateful 모드에서는 위 표의 모든 필수 환경변수가 설정되어야 합니다.
 
 ---
 
@@ -399,24 +440,27 @@ const config: LogtoConfig = {
 
 ## ❓ FAQ
 
-- **Q. 로거 토큰이 다르면 어떻게 하나요?**  
-  → `forLogger`의 두 번째 인자로 원하는 토큰(Symbol)을 넘기면 됩니다.
+- **Q. 로거 토큰이 다르면 어떻게 하나요?**
+  → `forRoot`의 `logger.token`에 원하는 토큰(Symbol)을 넘기면 됩니다.
 
-- **Q. 환경변수 기반 설정은 어떻게 하나요?**  
-  → 각 서비스는 DI로 `ConfigService`를 받아 환경변수 기반으로 설정을 자동 주입받습니다.
+- **Q. 환경변수 기반 설정은 어떻게 하나요?**
+  → LogtoModule이 내부적으로 `ConfigService`를 사용하여 환경변수를 자동으로 읽습니다. `ConfigModule.forRoot({ isGlobal: true })`가 먼저 import되어 있어야 합니다.
 
-- **Q. 인증/권한 외에 사용자/역할 관리도 가능한가요?**  
+- **Q. 인증/권한 외에 사용자/역할 관리도 가능한가요?**
   → 네, `LogtoM2MClient`를 통해 사용자/역할 생성, 조회, 수정, 삭제, 할당 등 모든 관리가 가능합니다.
 
-- **Q. Stateless 모드와 Stateful 모드의 차이는 무엇인가요?**  
-  → Stateless 모드는 토큰 검증만 필요한 API 서버에 적합하며, 최소한의 환경변수(`LOGTO_JWKS_URI`, `LOGTO_AUTH_ISSUER`)만 필요합니다.  
-  → Stateful 모드는 `LOGTO_CLIENT=true`로 설정하여 로그인/로그아웃, M2M 통신 등 클라이언트 기능을 모두 사용할 수 있습니다.
+- **Q. Stateless 모드와 Stateful 모드의 차이는 무엇인가요?**
+  → Stateless 모드는 토큰 검증만 필요한 API 서버에 적합하며, `LOGTO_AUTH_ISSUER`만 필수입니다.
+  → Stateful 모드는 `enableClient: true`로 설정하여 로그인/로그아웃, M2M 통신 등 클라이언트 기능을 모두 사용할 수 있습니다.
+
+- **Q. global 옵션은 언제 사용하나요?**
+  → `global: true`로 설정하면 LogtoModule이 글로벌 모듈로 등록되어, 다른 모듈에서 별도의 import 없이 Logto 서비스들을 사용할 수 있습니다.
 
-- **Q. global 파라미터는 언제 사용하나요?**  
-  → `forLogger`의 세 번째 파라미터를 `true`로 설정하면 LogtoModule이 글로벌 모듈로 등록되어, 다른 모듈에서 별도의 import 없이 Logto 서비스들을 사용할 수 있습니다.
+- **Q. 토큰 검증만 필요한데 모든 환경변수를 설정해야 하나요?**
+  → 아니요. 토큰 검증만 필요하다면 `LOGTO_AUTH_ISSUER`만 설정하면 됩니다. `enableClient`를 설정하지 않거나 `false`로 설정하면 자동으로 Stateless 모드가 활성화됩니다.
 
-- **Q. 토큰 검증만 필요한데 모든 환경변수를 설정해야 하나요?**  
-  → 아니요. 토큰 검증만 필요하다면 `LOGTO_JWKS_URI`와 `LOGTO_AUTH_ISSUER`만 설정하면 됩니다. `LOGTO_CLIENT`를 설정하지 않거나 `false`로 설정하면 자동으로 Stateless 모드가 활성화됩니다.
+- **Q. 필수 환경변수가 없으면 어떻게 되나요?**
+  → 모듈 초기화 시점에 `ConfigService.getOrThrow()`를 사용하여 즉시 에러가 발생합니다. 이를 통해 런타임 오류를 사전에 방지할 수 있습니다.
 
 ---
 
@@ -436,4 +480,4 @@ const config: LogtoConfig = {
 
 ## 📝 라이선스
 
-MIT 
+MIT

package/client/config.ts

@@ -77,3 +77,65 @@ export enum GrantType {
     ClientCredentials = 'client_credentials',
     RefreshToken = 'refresh_token',
 }
+
+/**
+ * LogtoVerifierConfig
+ *
+ * Stateless 모드에서 토큰 검증에 필요한 설정입니다.
+ * - jwksUri: JWKS 엔드포인트 URI
+ * - issuer: 토큰 발급자(issuer)
+ */
+export interface LogtoVerifierConfig {
+    /** JWKS 엔드포인트 URI */
+    jwksUri: string;
+    /** 토큰 발급자 (issuer) */
+    issuer: string;
+}
+
+/**
+ * LogtoOAuthConfig
+ *
+ * OAuth 클라이언트 설정입니다.
+ * Authorization Code 플로우에서 사용됩니다.
+ */
+export interface LogtoOAuthConfig {
+    /** Logto 인증 서버의 엔드포인트 URL */
+    endpoint: string;
+    /** Logto 애플리케이션의 Client ID */
+    clientId: string;
+    /** Logto 애플리케이션의 Client Secret */
+    clientSecret: string;
+    /** 접근할 리소스 서버 목록 */
+    resources: string[];
+    /** 요청할 OAuth 스코프 목록 */
+    scopes: string[];
+    /** 인증 요청 시 사용할 prompt 파라미터 */
+    prompt: Prompt;
+    /** 인증 후 리다이렉트될 URI */
+    redirectUri: string;
+    /** 로그인 URI */
+    signInUri: string;
+    /** 대시보드 로그인 URI (선택) */
+    dashboardSignInUri?: string;
+}
+
+/**
+ * LogtoM2MConfig
+ *
+ * M2M(Machine-to-Machine) 클라이언트 설정입니다.
+ * Client Credentials 플로우에서 사용됩니다.
+ */
+export interface LogtoM2MConfig {
+    /** Logto 인증 서버의 엔드포인트 URL */
+    endpoint: string;
+    /** M2M 애플리케이션의 Client ID */
+    clientId: string;
+    /** M2M 애플리케이션의 Client Secret */
+    clientSecret: string;
+    /** 접근할 리소스 서버 */
+    resource: string;
+    /** Logto Management API URL */
+    apiUrl: string;
+    /** 요청할 OAuth 스코프 목록 */
+    scopes: string[];
+}

package/client/logto-login-session.ts

@@ -1,16 +1,13 @@
-import { Inject, Injectable, LoggerService } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
+import { Injectable, LoggerService } from "@nestjs/common";
 import axios, { AxiosResponse } from "axios";
 import { axiosAdapter } from "point3-common-tool";
 
 import {
     OAuthClient,
-    OAuthClientToken,
     SignInType,
 } from "./oauth-client";
 
 import {
-    LogtoLoggerServiceToken,
     LogtoOAuthRESTTemplate,
 } from "./types";
 
@@ -20,16 +17,16 @@ export const LogtoLoginSessionToken = Symbol.for("LogtoLoginSession");
 @Injectable()
 /**
  * LogtoLoginSession
- * 
+ *
  * Logto 인증 세션 플로우를 관리하는 클래스입니다.
  * NestJS DI 환경에서 사용되며, Logto 로그인 과정의 각 단계를 API 호출로 래핑합니다.
- * 
+ *
  * 주요 역할:
  *   - 로그인 세션 시작 및 세션 쿠키 관리
  *   - 인증 플로우(로그인 경험) 단계별 진행
  *   - 비밀번호 검증, 사용자 식별, 동의 및 제출 처리
  *   - 커스텀 로그인 플로우를 위한 저수준 제어 제공
- * 
+ *
  * 사용 예시:
  *   const session = new LogtoLoginSession(...);
  *   await session.createSignInSession(...);
@@ -43,24 +40,18 @@ export class LogtoLoginSession {
 
     /**
      * LogtoLoginSession 생성자
-     * 
+     *
+     * @param apiUrl - Logto API URL
      * @param logger - 로깅 서비스
-     * @param configService - 환경설정 서비스
      * @param oauthClient - OAuth 클라이언트 인스턴스
      */
     constructor(
-        @Inject(LogtoLoggerServiceToken)
+        private readonly apiUrl: string,
         private readonly logger: LoggerService,
-
-        @Inject(ConfigService)
-        private readonly configService: ConfigService,
-
-        @Inject(OAuthClientToken)
         private readonly oauthClient: OAuthClient,
     ) {
         // API 기본 URL로 REST 템플릿 초기화
-        const baseURL = this.configService.get<string>("LOGTO_M2M_API_URL");
-        this.apiRestTemplate = new LogtoOAuthRESTTemplate(this.logger, baseURL);
+        this.apiRestTemplate = new LogtoOAuthRESTTemplate(this.logger, apiUrl);
     }
 
     /**