aiteamutils 0.2.0__py3-none-any.whl

aiteamutils/security.py

@@ -0,0 +1,396 @@
+"""보안 관련 유틸리티."""
+from datetime import datetime, timedelta, UTC
+from typing import Dict, Any, Optional, Literal, Callable
+from fastapi import Request, HTTPException, status
+from functools import wraps
+from jose import jwt, JWTError
+from passlib.context import CryptContext
+
+from .exceptions import CustomException, ErrorCode
+from .database import DatabaseService
+from .enums import ActivityType
+from .config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+class RateLimitExceeded(CustomException):
+    """Rate limit 초과 예외."""
+    
+    def __init__(
+        self,
+        detail: str,
+        source_function: str,
+        remaining_seconds: float,
+        max_requests: int,
+        window_seconds: int
+    ):
+        """Rate limit 초과 예외를 초기화합니다.
+        
+        Args:
+            detail: 상세 메시지
+            source_function: 예외가 발생한 함수명
+            remaining_seconds: 다음 요청까지 남은 시간 (초)
+            max_requests: 허용된 최대 요청 수
+            window_seconds: 시간 윈도우 (초)
+        """
+        super().__init__(
+            ErrorCode.RATE_LIMIT_EXCEEDED,
+            detail=detail,
+            source_function=source_function,
+            metadata={
+                "remaining_seconds": remaining_seconds,
+                "max_requests": max_requests,
+                "window_seconds": window_seconds
+            }
+        )
+        self.remaining_seconds = remaining_seconds
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+
+class SecurityError(CustomException):
+    """보안 관련 기본 예외."""
+    
+    def __init__(
+        self,
+        error_code: ErrorCode,
+        detail: str,
+        source_function: str,
+        original_error: Optional[Exception] = None
+    ):
+        """보안 관련 예외를 초기화합니다.
+        
+        Args:
+            error_code: 에러 코드
+            detail: 상세 메시지
+            source_function: 예외가 발생한 함수명
+            original_error: 원본 예외
+        """
+        super().__init__(
+            error_code,
+            detail=detail,
+            source_function=f"security.{source_function}",
+            original_error=original_error
+        )
+
+class TokenError(SecurityError):
+    """토큰 관련 예외."""
+    
+    def __init__(
+        self,
+        detail: str,
+        source_function: str,
+        original_error: Optional[Exception] = None
+    ):
+        """토큰 관련 예외를 초기화합니다."""
+        super().__init__(
+            ErrorCode.INVALID_TOKEN,
+            detail=detail,
+            source_function=source_function,
+            original_error=original_error
+        )
+
+class RateLimiter:
+    """Rate limit 관리 클래스."""
+    
+    def __init__(self, max_requests: int, window_seconds: int):
+        """Rate limiter를 초기화합니다.
+        
+        Args:
+            max_requests: 허용된 최대 요청 수
+            window_seconds: 시간 윈도우 (초)
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._cache: Dict[str, Dict[str, Any]] = {}
+        
+    def is_allowed(self, key: str) -> bool:
+        """현재 요청이 허용되는지 확인합니다.
+        
+        Args:
+            key: Rate limit 키
+            
+        Returns:
+            bool: 요청 허용 여부
+        """
+        now = datetime.now(UTC)
+        rate_info = self._cache.get(key)
+        
+        if rate_info is None or (now - rate_info["start_time"]).total_seconds() >= self.window_seconds:
+            self._cache[key] = {
+                "count": 1,
+                "start_time": now
+            }
+            return True
+            
+        if rate_info["count"] >= self.max_requests:
+            return False
+            
+        rate_info["count"] += 1
+        return True
+        
+    def get_remaining_time(self, key: str) -> float:
+        """남은 시간을 반환합니다.
+        
+        Args:
+            key: Rate limit 키
+            
+        Returns:
+            float: 남은 시간 (초)
+        """
+        rate_info = self._cache.get(key)
+        if not rate_info:
+            return 0
+            
+        now = datetime.now(UTC)
+        return max(
+            0,
+            self.window_seconds - (now - rate_info["start_time"]).total_seconds()
+        )
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """비밀번호를 검증합니다.
+    
+    Args:
+        plain_password: 평문 비밀번호
+        hashed_password: 해시된 비밀번호
+        
+    Returns:
+        bool: 비밀번호 일치 여부
+    """
+    return pwd_context.verify(plain_password, hashed_password)
+
+def hash_password(password: str) -> str:
+    """비밀번호를 해시화합니다.
+    
+    Args:
+        password: 평문 비밀번호
+        
+    Returns:
+        str: 해시된 비밀번호
+    """
+    return pwd_context.hash(password)
+
+def rate_limit(
+    max_requests: int,
+    window_seconds: int,
+    key_func: Optional[Callable] = None
+):
+    """Rate limiting 데코레이터."""
+    limiter = RateLimiter(max_requests, window_seconds)
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Request 객체 찾기
+            request = None
+            for arg in args:
+                if isinstance(arg, Request):
+                    request = arg
+                    break
+            if not request:
+                for arg in kwargs.values():
+                    if isinstance(arg, Request):
+                        request = arg
+                        break
+            if not request:
+                raise SecurityError(
+                    ErrorCode.INTERNAL_ERROR,
+                    detail="Request object not found",
+                    source_function="rate_limit"
+                )
+            
+            # Rate limit 키 생성
+            if key_func:
+                rate_limit_key = f"rate_limit:{key_func(request)}"
+            else:
+                client_ip = request.client.host
+                rate_limit_key = f"rate_limit:{client_ip}:{func.__name__}"
+            
+            try:
+                if not limiter.is_allowed(rate_limit_key):
+                    remaining_time = limiter.get_remaining_time(rate_limit_key)
+                    raise RateLimitExceeded(
+                        detail=f"Rate limit exceeded. Try again in {int(remaining_time)} seconds",
+                        source_function=func.__name__,
+                        remaining_seconds=remaining_time,
+                        max_requests=max_requests,
+                        window_seconds=window_seconds
+                    )
+                
+                return await func(*args, **kwargs)
+                    
+            except (RateLimitExceeded, SecurityError) as e:
+                raise e
+            except Exception as e:
+                raise SecurityError(
+                    ErrorCode.INTERNAL_ERROR,
+                    detail=str(e),
+                    source_function="rate_limit",
+                    original_error=e
+                )
+                
+        return wrapper
+    return decorator
+
+class TokenCreationError(SecurityError):
+    """토큰 생성 관련 예외."""
+    
+    def __init__(
+        self,
+        detail: str,
+        source_function: str,
+        token_type: str,
+        original_error: Optional[Exception] = None
+    ):
+        """토큰 생성 예외를 초기화합니다.
+        
+        Args:
+            detail: 상세 메시지
+            source_function: 예외가 발생한 함수명
+            token_type: 토큰 타입
+            original_error: 원본 예외
+        """
+        super().__init__(
+            ErrorCode.INTERNAL_ERROR,
+            detail=detail,
+            source_function=source_function,
+            original_error=original_error
+        )
+        self.token_type = token_type
+
+async def create_jwt_token(
+    user_data: Dict[str, Any],
+    token_type: Literal["access", "refresh"],
+    db_service: DatabaseService,
+    log_model: Any,
+    request: Optional[Request] = None
+) -> str:
+    """JWT 토큰을 생성하고 로그를 기록합니다.
+    
+    Args:
+        user_data: 사용자 데이터 (username, ulid 등 필수)
+        token_type: 토큰 타입 ("access" 또는 "refresh")
+        db_service: 데이터베이스 서비스
+        log_model: 로그를 저장할 모델 클래스
+        request: FastAPI 요청 객체
+        
+    Returns:
+        str: 생성된 JWT 토큰
+        
+    Raises:
+        TokenCreationError: 토큰 생성 실패 시
+        SecurityError: 기타 보안 관련 오류 발생 시
+    """
+    try:
+        # 필수 필드 검증
+        required_fields = {"username", "ulid"}
+        missing_fields = required_fields - user_data.keys()
+        if missing_fields:
+            raise TokenCreationError(
+                detail=f"Missing required fields: {', '.join(missing_fields)}",
+                source_function="create_jwt_token",
+                token_type=token_type
+            )
+        
+        # 토큰 데이터 생성
+        if token_type == "access":
+            expires_at = datetime.now(UTC) + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+            token_data = {
+                "iss": settings.TOKEN_ISSUER,
+                "sub": user_data["username"],
+                "aud": settings.TOKEN_AUDIENCE,
+                "exp": expires_at,
+                "token_type": token_type,
+                **user_data
+            }
+        else:  # refresh token
+            expires_at = datetime.now(UTC) + timedelta(days=14)
+            token_data = {
+                "iss": settings.TOKEN_ISSUER,
+                "sub": user_data["username"],
+                "exp": expires_at,
+                "token_type": token_type,
+                "user_ulid": user_data["ulid"]
+            }
+        
+        try:
+            token = jwt.encode(
+                token_data,
+                settings.JWT_SECRET,
+                algorithm=settings.JWT_ALGORITHM
+            )
+        except Exception as e:
+            raise TokenCreationError(
+                detail="Failed to encode JWT token",
+                source_function="create_jwt_token",
+                token_type=token_type,
+                original_error=e
+            )
+        
+        # 로그 생성
+        try:
+            activity_type = ActivityType.ACCESS_TOKEN_ISSUED if token_type == "access" else ActivityType.REFRESH_TOKEN_ISSUED
+            await db_service.create_log(
+                model=log_model,
+                log_data={
+                    "type": activity_type,
+                    "user_ulid": user_data["ulid"],
+                    "token": token
+                },
+                request=request
+            )
+        except Exception as e:
+            # 로그 생성 실패는 토큰 생성에 영향을 주지 않음
+            pass
+        
+        return token
+        
+    except (TokenCreationError, SecurityError) as e:
+        raise e
+    except Exception as e:
+        raise SecurityError(
+            ErrorCode.INTERNAL_ERROR,
+            detail=str(e),
+            source_function="create_jwt_token",
+            original_error=e
+        )
+
+async def verify_jwt_token(
+    token: str,
+    expected_type: Optional[Literal["access", "refresh"]] = None
+) -> Dict[str, Any]:
+    """JWT 토큰을 검증합니다."""
+    try:
+        # 토큰 디코딩
+        payload = jwt.decode(
+            token,
+            settings.JWT_SECRET,
+            algorithms=[settings.JWT_ALGORITHM],
+            audience=settings.TOKEN_AUDIENCE,
+            issuer=settings.TOKEN_ISSUER
+        )
+        
+        # 토큰 타입 검증 (expected_type이 주어진 경우에만)
+        if expected_type and payload.get("token_type") != expected_type:
+            raise TokenError(
+                detail=f"Expected {expected_type} token but got {payload.get('token_type')}",
+                source_function="verify_jwt_token"
+            )
+        
+        return payload
+        
+    except JWTError as e:
+        raise TokenError(
+            detail=str(e),
+            source_function="verify_jwt_token",
+            original_error=e
+        )
+    except (TokenError, SecurityError) as e:
+        raise e
+    except Exception as e:
+        raise SecurityError(
+            ErrorCode.INTERNAL_ERROR,
+            detail=str(e),
+            source_function="verify_jwt_token",
+            original_error=e
+        ) 

aiteamutils/validators.py

@@ -0,0 +1,188 @@
+"""유효성 검사 관련 유틸리티 함수들을 모아둔 모듈입니다."""
+
+from typing import Any, Optional, Dict
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from pydantic import field_validator
+import re
+
+from .exceptions import ErrorCode, CustomException
+from .database import DatabaseService
+from .base_model import Base
+
+def validate_with(validator_func, unique_check=None, skip_if_none=False):
+    """필드 유효성 검사 데코레이터
+    Args:
+        validator_func: 형식 검증 함수
+        unique_check: (table_name, field) 튜플. 지정되면 해당 테이블의 필드에 대해 중복 검사 수행
+        skip_if_none: None 값 허용 여부
+    """
+    def decorator(field_name: str):
+        def validator(cls, value, info: Any):
+            if skip_if_none and value is None:
+                return value
+            
+            # 형식 검증 (필드명도 함께 전달)
+            validator_func(value, field_name)
+            
+            # 중복 검사는 별도의 validator로 분리
+            if unique_check:
+                async def check_unique():
+                    if not info or not hasattr(info, 'context'):
+                        raise CustomException(
+                            ErrorCode.VALIDATION_ERROR,
+                            detail=f"{field_name}|{value}",
+                            source_function=f"Validator.validate_{field_name}"
+                        )
+                    
+                    db_service = info.context.get("db_service")
+                    if not db_service:
+                        raise CustomException(
+                            ErrorCode.VALIDATION_ERROR,
+                            detail=f"{field_name}|{value}",
+                            source_function=f"Validator.validate_{field_name}"
+                        )
+
+                    table_name, field = unique_check
+                    table = Base.metadata.tables.get(table_name)
+                    if not table:
+                        raise CustomException(
+                            ErrorCode.VALIDATION_ERROR,
+                            detail=f"{field_name}|{value}",
+                            source_function=f"Validator.validate_{field_name}"
+                        )
+
+                    await db_service.validate_unique_fields(
+                        table,
+                        {field: value},
+                        source_function=f"Validator.validate_{field_name}"
+                    )
+                
+                # 중복 검사를 위한 별도의 validator 등록
+                field_validator(field_name, mode='after')(check_unique)
+            
+            return value
+        return field_validator(field_name, mode='before')(validator)
+    return decorator
+
+class Validator:
+    @staticmethod
+    def validate_email(email: str, field_name: str = "email") -> None:
+        """이메일 형식 검증을 수행하는 메서드."""
+        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+        if not re.match(pattern, email):
+            raise CustomException(
+                ErrorCode.FIELD_INVALID_EMAIL,
+                detail=f"{field_name}|{email}",
+                source_function="Validator.validate_email"
+            )
+
+    @staticmethod
+    def validate_password(password: str, field_name: str = "password") -> None:
+        """비밀번호 규칙 검증을 수행하는 메서드."""
+        try:
+            if len(password) < 8:
+                raise CustomException(
+                    ErrorCode.FIELD_INVALID_PASSWORD_LENGTH,
+                    detail=f"{field_name}|{password}",
+                    source_function="Validator.validate_password"
+                )
+            
+            if not re.search(r'[A-Z]', password):
+                raise CustomException(
+                    ErrorCode.FIELD_INVALID_PASSWORD_UPPER,
+                    detail=f"{field_name}|{password}",
+                    source_function="Validator.validate_password"
+                )
+            
+            if not re.search(r'[0-9]', password):
+                raise CustomException(
+                    ErrorCode.FIELD_INVALID_PASSWORD_NUMBER,
+                    detail=f"{field_name}|{password}",
+                    source_function="Validator.validate_password"
+                )
+            
+            if not re.search(r'[!@#$%^&*(),.?":{}|<>]', password):
+                raise CustomException(
+                    ErrorCode.FIELD_INVALID_PASSWORD_SPECIAL,
+                    detail=f"{field_name}|{password}",
+                    source_function="Validator.validate_password"
+                )
+            
+        except CustomException as ce:
+            raise ce
+        except Exception as e:
+            raise CustomException(
+                ErrorCode.VALIDATION_ERROR,
+                detail=f"{field_name}|{password}",
+                source_function="Validator.validate_password"
+            )
+
+    @staticmethod
+    def validate_id(value: str, field_name: str) -> None:
+        """ID 형식 검증을 수행하는 메서드."""
+        if len(value) < 3:
+            raise CustomException(
+                ErrorCode.FIELD_INVALID_ID_LENGTH,
+                detail=f"{field_name}|{value}",
+                source_function="Validator.validate_id"
+            )
+        if not re.match(r'^[a-z0-9_]+$', value):
+            raise CustomException(
+                ErrorCode.FIELD_INVALID_ID_CHARS,
+                detail=f"{field_name}|{value}",
+                source_function="Validator.validate_id"
+            )
+
+    @staticmethod
+    def validate_mobile(mobile: str, field_name: str = "mobile") -> None:
+        """휴대전화 번호 형식 검증을 수행하는 메서드."""
+        if not mobile:  # Optional 필드이므로 빈 값 허용
+            return
+        
+        pattern = r'^010-?[0-9]{4}-?[0-9]{4}$'
+        if not re.match(pattern, mobile):
+            raise CustomException(
+                ErrorCode.INVALID_MOBILE,
+                detail=f"{field_name}|{mobile}",
+                source_function="Validator.validate_mobile"
+            )
+
+    @staticmethod
+    def validate_phone(phone: str, field_name: str = "phone") -> None:
+        """일반 전화번호 형식 검증을 수행하는 메서드."""
+        if not phone:  # Optional 필드이므로 빈 값 허용
+            return
+        
+        pattern = r'^(0[2-6][1-5]?)-?([0-9]{3,4})-?([0-9]{4})$'
+        if not re.match(pattern, phone):
+            raise CustomException(
+                ErrorCode.FIELD_INVALID_PHONE,
+                detail=f"{field_name}|{phone}",
+                source_function="Validator.validate_phone"
+            )
+
+    @staticmethod
+    def validate_name(name: str, field_name: str = "name") -> None:
+        """이름 형식 검증을 수행하는 메서드."""
+        if not name:
+            raise CustomException(
+                ErrorCode.VALIDATION_ERROR,
+                detail=f"{field_name}|{name}",
+                source_function="Validator.validate_name"
+            )
+        
+        if len(name) < 2 or len(name) > 100:
+            raise CustomException(
+                ErrorCode.VALIDATION_ERROR,
+                detail=f"{field_name}|{name}",
+                source_function="Validator.validate_name"
+            )
+        
+        # 한글, 영문, 공백만 허용
+        if not re.match(r'^[가-힣a-zA-Z\s]+$', name):
+            raise CustomException(
+                ErrorCode.VALIDATION_ERROR,
+                detail=f"{field_name}|{name}",
+                source_function="Validator.validate_name"
+            )

aiteamutils-0.2.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: aiteamutils
+Version: 0.2.0
+Summary: AI Team Utilities
+Project-URL: Homepage, https://github.com/yourusername/aiteamutils
+Project-URL: Issues, https://github.com/yourusername/aiteamutils/issues
+Author: AI Team
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: fastapi
+Requires-Dist: python-jose
+Requires-Dist: sqlalchemy
+Description-Content-Type: text/markdown
+
+# AI Team Core Utils
+
+AI Team Platform의 공통 유틸리티 패키지입니다.
+
+## 설치 방법
+
+```bash
+pip install ai-team-core-utils
+```
+
+## 사용 예시
+
+```python
+from ai_team_core_utils.database import DatabaseManager
+from ai_team_core_utils.base_model import Base
+
+# DB 매니저 초기화
+db = DatabaseManager("postgresql+asyncpg://user:pass@localhost/db")
+
+# DB 세션 사용
+async with db.get_session() as session:
+    # DB 작업 수행
+    pass
+
+# 예외 처리
+from ai_team_core_utils.exceptions import CustomException, ErrorCode
+
+try:
+    # 작업 수행
+    pass
+except CustomException as e:
+    # 에러 처리
+    print(e.to_dict())
+```
+
+## 주요 기능
+
+- 데이터베이스 유틸리티
+  - 세션 관리
+  - 트랜잭션 관리
+  - 기본 CRUD 작업
+
+- 인증/인가 유틸리티
+  - JWT 토큰 관리
+  - 비밀번호 해싱
+  - Rate Limiting
+
+- 예외 처리
+  - 표준화된 에러 코드
+  - 에러 체인 추적
+  - 로깅 통합
+
+- 공통 모델
+  - 기본 모델 클래스
+  - 타입 검증
+  - 유효성 검사 

aiteamutils-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+aiteamutils/__init__.py,sha256=zmfBXBwNWdbJKCt1rmHk_czHJLmVF-oqRuqq8tf0t0U,1229
+aiteamutils/base_model.py,sha256=ODEnjvUVoxQ1RPCfq8-uZTfTADIA4c7Z3E6G4EVsSX0,2708
+aiteamutils/base_repository.py,sha256=0772JYHpF82vZzR8l21rDcZk8uVj6r52rqJdp150qiE,18927
+aiteamutils/base_service.py,sha256=nW9sC0SHDIve3WJVUB3rAS_9XGTkIYJRaDxfqA0V3js,24727
+aiteamutils/cache.py,sha256=tr0Yn8VPYA9QHiKCUzciVlQ2J1RAwNo2K9lGMH4rY3s,1334
+aiteamutils/config.py,sha256=vC6k6E2-Y4mD0E0kw6WVgSatCl9K_BtTwrVFhLrhCzs,665
+aiteamutils/database.py,sha256=U71cexPsSmMTKgp098I574PupqnuPltujI4QKHBG2Cc,29952
+aiteamutils/dependencies.py,sha256=EJeVtq_lACuoheVhkX23N9xiak9bGD-t3-2JtlgBki0,4850
+aiteamutils/enums.py,sha256=ipZi6k_QD5-3QV7Yzv7bnL0MjDz-vqfO9I5L77biMKs,632
+aiteamutils/exceptions.py,sha256=YV-ISya4wQlHk4twvGo16I5r8h22-tXpn9wa-b3WwDM,15231
+aiteamutils/security.py,sha256=AZszaTxVEGi1jU1sX3QXHGgshp1lVvd0xXvZejXvs_w,12643
+aiteamutils/validators.py,sha256=BQA61f5raVAX0BGcTIS3Ht6CyCAdHgqDUmr76bZWgYE,7630
+aiteamutils-0.2.0.dist-info/METADATA,sha256=ssjX9Y1HQqAY9vNB0MvN9wdILEtxPnIiXXWw3z4-An8,1569
+aiteamutils-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aiteamutils-0.2.0.dist-info/RECORD,,

aiteamutils-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any