Metadata-Version: 2.4
Name: ompass-sdk
Version: 1.0.0
Summary: OMPASS FIDO2 MFA Web API SDK for Python
Author-email: OneMoreSecurity <support@omsecurity.kr>
License: Proprietary
Project-URL: Homepage, https://www.ompasscloud.com
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# OMPASS Python SDK

OMPASS FIDO2 MFA 솔루션의 Web API를 Python에서 쉽게 사용할 수 있는 SDK입니다.

## 요구 사항

- Python 3.9 이상

## 설치

```bash
pip install ompass-sdk
```

## 빠른 시작

### 1. 클라이언트 초기화

```python
from ompass import OmpassClient, OmpassConfig

config = OmpassConfig(
    client_id="your-client-id",
    secret_key="your-secret-key",
    base_url="https://your-tenant.ompasscloud.com",  # 테넌트별 API URL (필수)
    connect_timeout=30,  # 초 (기본값: 30)
    read_timeout=30,     # 초 (기본값: 30)
)

client = OmpassClient(config)
```

### 2. 인증 시작

사용자의 OMPASS 인증을 시작합니다.

```python
from ompass import AuthStartRequest, Language, LoginClientType

request = AuthStartRequest(
    username="user123",
    lang_init=Language.KR,
    login_client_type=LoginClientType.BROWSER,
    session_timeout_seconds=300,
)

response = client.start_auth(request)

# 클라이언트에 전달하여 팝업 또는 리다이렉트
ompass_url = response.ompass_url
```

### 3. 토큰 검증

인증 완료 후 리다이렉트로 받은 토큰을 검증합니다.

```python
from ompass import TokenVerifyRequest

request = TokenVerifyRequest(
    username="user123",
    token="received-token-from-redirect",
)

response = client.verify_token(request)

if response.is_verified:
    # 인증 성공
    print(f"인증 완료: {response.username}")
```

### 4. 인증기 목록 조회

사용자의 등록된 인증기 목록을 조회합니다.

```python
response = client.get_authenticators("user123")

for auth in response.authenticators:
    print(f"{auth.type} - {auth.status}")
    if auth.mobile_device:
        print(f"  기기: {auth.mobile_device.device_name}")
```

### 5. 인증 장치 삭제

사용자의 인증 장치를 삭제합니다.

```python
client.delete_authenticator("authenticator-id")
```

### 6. 리소스 정리

```python
# 직접 호출
client.close()

# 또는 Context Manager 사용
with OmpassClient(config) as client:
    response = client.start_auth(request)
```

## 예외 처리

SDK는 두 가지 예외 타입을 제공합니다.

### OmpassException

일반적인 SDK 오류 (네트워크 오류, JSON 파싱 오류 등)

```python
from ompass import OmpassException

try:
    client.start_auth(request)
except OmpassException as e:
    print(f"Error: {e}")
```

### OmpassApiException

API 응답 오류 (4xx, 5xx 상태 코드)

```python
from ompass import OmpassApiException

try:
    client.start_auth(request)
except OmpassApiException as e:
    print(f"HTTP Status: {e.http_status_code}")
    print(f"Error Code: {e.error_code}")
    print(f"Error Message: {e.error_message}")
```

## API 참조

### OmpassConfig

| 파라미터 | 타입 | 설명 | 필수 | 기본값 |
|----------|------|------|------|--------|
| `client_id` | str | OMPASS 클라이언트 ID | O | - |
| `secret_key` | str | OMPASS 시크릿 키 | O | - |
| `base_url` | str | 테넌트별 API URL | O | - |
| `connect_timeout` | int | 연결 타임아웃 (초) | X | 30 |
| `read_timeout` | int | 읽기 타임아웃 (초) | X | 30 |

### AuthStartRequest

| 필드 | 타입 | 설명 | 필수 |
|------|------|------|------|
| `username` | str | 사용자 ID | O |
| `lang_init` | Language | 초기 언어 (KR, EN, JP) | X |
| `login_client_type` | LoginClientType | 클라이언트 타입 | X |
| `session_timeout_seconds` | int | 세션 타임아웃 (초) | X |

### AuthStartResponse

| 필드 | 타입 | 설명 |
|------|------|------|
| `username` | str | 사용자 ID |
| `ompass_url` | str | OMPASS 인증 URL |
| `registered_ompass` | bool | OMPASS 등록 여부 |

### TokenVerifyRequest

| 필드 | 타입 | 설명 | 필수 |
|------|------|------|------|
| `username` | str | 사용자 ID | O |
| `token` | str | 인증 토큰 | O |

### TokenVerifyResponse

| 필드 | 타입 | 설명 |
|------|------|------|
| `client_id` | str | 클라이언트 ID |
| `application_name` | str | 애플리케이션 이름 |
| `username` | str | 사용자 ID |
| `is_verified` | bool | 검증 성공 여부 (property) |

## 지원 언어

- `Language.KR` - 한국어
- `Language.EN` - 영어
- `Language.JP` - 일본어

## 클라이언트 타입

- `LoginClientType.BROWSER` - 웹 브라우저
- `LoginClientType.MOBILE_APP` - 모바일 앱
- `LoginClientType.DESKTOP_APP` - 데스크톱 앱

## 빌드

```bash
# 의존성 설치
pip install -e ".[dev]"

# 테스트
pytest

# 패키지 빌드
python -m build
```

## 라이선스

이 프로젝트는 독점 라이선스 하에 있습니다.
