# VConnect API Server

Zero-Port, Zero-VPN SSH 기반 Proxmox VM 원격접속 플랫폼

## 아키텍처

```
[WPF Client] ←JWT→ [FastAPI Server] ←SSH→ [Proxmox VE]
                         ↓
                  [PostgreSQL DB]
```

## 핵심 기능

### 1. 인증 시스템
- JWT 기반 토큰 인증
- 사용자 관리 (회원가입/로그인)
- 역할 기반 접근 제어 (RBAC)

### 2. Proxmox 통합
- API Token 기반 Proxmox 연동
- VM 목록 조회 및 상태 모니터링
- VM 제어 (시작/종료/재시작)
- QEMU Guest Agent IP 정보 수집

### 3. SSH 터널링 및 자격증명
- **Zero-Trust Access**: 클라이언트는 SSH Private Key 없이 일회용 자격증명으로 접속
- **임시 자격증명 발급**: JWT 토큰 인증 후 1시간 유효한 임시 SSH 비밀번호 발급
- **PAM 연동**: SSH 게이트웨이에서 API를 통해 임시 비밀번호 검증
- **동적 포트 할당**: 세션별 독립적인 포트 포워딩 관리

### 4. 감사 로그
- 접속 기록 (누가, 언제, 어떤 VM에)
- VM 제어 이력
- 보안 이벤트 추적

### 5. 자동 업데이트
- 클라이언트 버전 관리 및 업데이트 배포 지원

## 기술 스택

- **FastAPI**: 고성능 Python 웹 프레임워크
- **PostgreSQL**: 관계형 데이터베이스
- **SQLAlchemy**: ORM (Async support)
- **Alembic**: DB 마이그레이션 관리
- **JWT (Jose)**: 토큰 기반 인증
- **Paramiko / AsyncSSH**: SSH 터널 및 연결 관리
- **Uvicorn**: ASGI 웹 서버

## 프로젝트 구조

```
vconnect-api/
├── app/
│   ├── main.py                 # FastAPI 앱 진입점
│   ├── config.py               # 설정 관리 (.env 로드)
│   ├── database.py             # DB 세션 및 엔진
│   ├── models/                 # SQLAlchemy 모델 (User, VM, AuditLog)
│   ├── schemas/                # Pydantic 스키마 (Request/Response)
│   ├── api/                    # API 라우터
│   │   ├── auth.py             # 인증 (로그인/가입)
│   │   ├── vms.py              # VM 제어 및 조회
│   │   ├── tunnel.py           # SSH 터널 관리
│   │   ├── ssh_credentials.py  # 임시 SSH 자격증명 발급/검증
│   │   └── admin.py            # 관리자 기능 (사용자 관리, 로그)
│   ├── services/               # 비즈니스 로직
│   └── utils/                  # 유틸리티 (JWT, Security)
├── alembic/                    # DB 마이그레이션 스크립트
├── requirements.txt            # 의존성 패키지 목록
├── docker-compose.yml          # Docker 배포 설정
├── Dockerfile                  # Docker 빌드 설정
└── README.md                   # 문서
```

## 환경 변수 (.env)

```env
# Database
DATABASE_URL=postgresql://user:password@localhost/vconnect

# JWT
JWT_SECRET_KEY=your-secret-key-change-it
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Proxmox API
PROXMOX_HOST=https://pve.example.com:8006
PROXMOX_API_TOKEN=PVEAPIToken=root@pam!vconnect=xxx...

# SSH Gateway (Zero-Port)
SSH_HOST=ssh.example.com       # 클라이언트가 접속할 외부 주소
SSH_PORT=22                    # 외부 포트
SSH_INTERNAL_HOST=127.0.0.1    # 내부 터널링 바인딩 주소
```

## 설치 및 실행

```bash
# 가상환경 생성
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 의존성 설치
pip install -r requirements.txt

# 환경 변수 설정
cp .env.example .env
# .env 파일 편집...

# DB 마이그레이션 (테이블 생성)
alembic upgrade head

# 서버 실행 (개발 모드)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## API 엔드포인트 요약

### 인증 (`/api/v1/auth`)
- `POST /register` - 회원가입
- `POST /login` - 로그인 (AccessToken 발급)
- `GET /me` - 현재 사용자 정보 확인

### VM 관리 (`/api/v1/vms`)
- `GET /my` - 사용자별 할당된 VM 목록
- `POST /{vm_id}/start` - VM 켜기
- `POST /{vm_id}/stop` - VM 끄기

### SSH 자격증명 (`/api/v1/ssh`)
- `POST /credentials` - [클라이언트용] 1시간 유효한 임시 SSH 비밀번호 발급
- `POST /verify` - [게이트웨이용] 임시 비밀번호 유효성 검증

### 터널 관리 (`/api/v1/tunnel`)
- `POST /create` - SSH 터널 세션 생성
- `DELETE /{tunnel_id}` - 터널 세션 종료

### 관리자 (`/api/v1/admin`)
- `GET /users` - 전체 사용자 관리
- `GET /audit-logs` - 전체 감사 로그 조회
- `GET /stats` - 시스템 통계

## 개발 로드맵 상태

- [x] 프로젝트 구조 및 FastAPI 기본 설정
- [x] PostgreSQL 연동 및 Alembic 마이그레이션 구성
- [x] JWT 인증 시스템 (Login/Refresh)
- [x] Proxmox API 연동 (VM 상태/제어)
- [x] SSH 터널링 매니저 구현
- [x] **Zero-Trust 임시 자격증명 시스템** (SSH Password Manager)
- [x] 감사 로그 (Audit Log)
- [x] Docker 기반 배포 환경 (Dockerfile, Confirm)
- [ ] 클라이언트 자동 업데이트 배포 시스템 고도화
- [ ] 유닛 테스트 작성 (Pytest)