@point3/logto-module 1.0.11 → 1.0.12

package/README.md

@@ -125,96 +125,155 @@ export class AuthService {
 
 ### 4. stateless 네임스페이스 활용 예시
 
-#### 4-1. Express/Fastify 미들웨어로 토큰 인증
+> ⚠️ **중요한 주의사항**  
+> `requiredScopes`와 `requiredRoles`에 사용되는 모든 스코프와 역할은 **반드시 Logto 관리 콘솔에서 먼저 정의되어야 합니다**.  
+> 
+> - **스코프(Scopes)**: Logto 콘솔의 API Resources → 해당 리소스 → Scopes에서 정의
+> - **역할(Roles)**: Logto 콘솔의 User Management → Roles에서 정의  
+> - **역할-스코프 연결**: 각 역할에 필요한 스코프들을 Logto 콘솔에서 할당
+> 
+> 코드에서 사용하는 스코프/역할 이름이 Logto에 정의되지 않았다면 토큰 검증이 실패합니다.
+
+#### 4-1. LogtoProtected 데코레이터를 사용한 라우트 보호
 
 ```ts
-// main.ts
+// user.controller.ts
+import { Controller, Get } from '@nestjs/common';
 import { stateless } from '@point3/logto-module';
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  // JWT Bearer 토큰 인증 미들웨어 (stateless)
-  app.use(stateless.createTokenAuthMiddleware({
-    requiredScopes: ['admin'],
-    requiredRoles: ['superuser'],
-  }));
-  await app.listen(3000);
-}
-bootstrap();
-```
+@Controller('users')
+export class UserController {
+  // 기본 토큰 인증만 필요한 경우
+  @Get('profile')
+  @stateless.LogtoProtected()
+  getProfile() {
+    return { message: '인증된 사용자만 접근 가능' };
+  }
 
-#### 4-2. 커스텀 가드/핸들러에서 stateless 유틸리티 활용
+  // 특정 스코프가 필요한 경우
+  @Get('admin')
+  @stateless.LogtoProtected({
+    requiredScopes: ['admin', 'user:read']
+  })
+  getAdminData() {
+    return { message: '관리자 스코프가 필요한 데이터' };
+  }
 
-```ts
-// custom.guard.ts
-import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
-import { stateless } from '@point3/logto-module';
+  // 특정 역할이 필요한 경우
+  @Get('management')
+  @stateless.LogtoProtected({
+    requiredRoles: ['superuser', 'management-point3']
+  })
+  getManagementData() {
+    return { message: '관리자 역할이 필요한 데이터' };
+  }
 
-@Injectable()
-export class MyStatelessGuard implements CanActivate {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const req = context.switchToHttp().getRequest();
-    // stateless 토큰 검증 및 권한 체크
-    const payload = await stateless.verifyRequestToken(req, {
-      requiredScopes: ['user'],
-    });
-    // payload에 따라 추가 로직 가능
-    return !!payload;
+  // 스코프와 역할을 모두 요구하는 경우
+  @Get('secure')
+  @stateless.LogtoProtected({
+    requiredScopes: ['admin'],
+    requiredRoles: ['superuser']
+  })
+  getSecureData() {
+    return { message: '고급 권한이 필요한 데이터' };
   }
 }
 ```
 
-#### 4-3. 커스텀 데코레이터로 유저 정보 추출
+#### 4-2. 커스텀 데코레이터로 유저 정보 추출
 
 ```ts
 // user.decorator.ts
 import { createParamDecorator, ExecutionContext } from '@nestjs/common';
-import { stateless } from '@point3/logto-module';
 
 export const CurrentUser = createParamDecorator(
-  async (data, ctx: ExecutionContext) => {
-    const req = ctx.switchToHttp().getRequest();
-    const payload = await stateless.verifyRequestToken(req);
-    return payload;
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    // LogtoTokenGuard가 request.user에 설정한 사용자 정보 반환
+    return request.user;
   },
 );
 
 // 컨트롤러에서 사용
-@Get('me')
-getMe(@CurrentUser() user) {
-  return user;
+@Controller('me')
+export class MeController {
+  @Get()
+  @stateless.LogtoProtected()
+  getMe(@CurrentUser() user: any) {
+    return {
+      userId: user.userId,
+      managerId: user.managerId,
+      clientId: user.clientId
+    };
+  }
 }
 ```
 
-#### 4-4. NestJS Provider로 stateless 가드 등록
+#### 4-3. 전역 가드로 LogtoTokenGuard 등록
 
 ```ts
 // app.module.ts
 import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
 import { stateless } from '@point3/logto-module';
 
 @Module({
   providers: [
     {
-      provide: 'STATLESS_GUARD',
-      useClass: stateless.StatelessTokenGuard,
+      provide: APP_GUARD,
+      useClass: stateless.LogtoTokenGuard,
     },
   ],
 })
 export class AppModule {}
 ```
 
-#### 4-5. 직접 토큰 검증/유저 정보 추출 (서비스/핸들러 등)
+#### 4-4. 커스텀 가드에서 LogtoTokenGuard 확장
 
 ```ts
+// custom.guard.ts
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
 import { stateless } from '@point3/logto-module';
 
-async function handleRequest(req) {
-  const payload = await stateless.verifyRequestToken(req);
-  if (!payload) throw new Error('인증 실패');
-  // payload.sub, payload.userRoles 등 활용
+@Injectable()
+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;
+  }
+}
+```
+
+#### 4-5. 타입 안전성을 위한 역할 타입 정의
+
+```ts
+// types/roles.ts
+export type UserRole = 'admin' | 'user' | 'moderator';
+
+// 컨트롤러에서 타입 안전하게 사용
+@Controller('typed')
+export class TypedController {
+  @Get('admin-only')
+  @stateless.LogtoProtected<UserRole>({
+    requiredRoles: ['admin'] // 타입 체크됨
+  })
+  getAdminData() {
+    return { message: '타입 안전한 역할 기반 접근 제어' };
+  }
 }
 ```
 

package/package.json

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