🛡️ Desktop-2FA

데스크톱 환경을 위한 안전한 오프라인 2단계 인증(2FA) 관리자입니다. Python으로 제작되었으며, 강력한 암호화를 제공하고 클라우드 의존성이 없습니다.

🌐 랜딩 페이지: desktop-2fa.org

✨ 기능

📸 스크린샷

대화형으로 새 TOTP 항목 추가

항목에 대한 TOTP 코드 생성

중복 감지와 함께 항목 이름 변경

버전 정보 확인 및 모든 항목 나열

🚀 빠른 시작

설치

pip install desktop-2fa

설치 확인:

python -c "import desktop_2fa; print(desktop_2fa.__version__)"
# Output: 0.8.1dev

기본 사용법

# Initialize a new vault
d2fa vault init

# Add a new TOTP token
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP

# List all entries
d2fa vault list

# Generate a code
d2fa code GitHub

비대화형 사용법

# Provide password via command line
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP --password mypassphrase

# Provide password via file
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP --password-file /path/to/passphrase.txt

📁 볼트 수명 주기

볼트는 ~/.desktop-2fa/vault에 위치한 암호화된 저장 파일입니다.

볼트 생성

명령이 볼트를 필요로 하는데 볼트가 없으면:

1. CLI가 새 비밀번호를 묻거나(대화형 모드) --password/--password-file을 요구합니다(비대화형 모드)
2. 빈 암호화 볼트가 생성됩니다
3. 확인 메시지가 항상 출력됩니다: Vault created at <path>

볼트 로드

명령이 볼트를 필요로 하는데 볼트가 있으면:

1. CLI가 기존 비밀번호를 묻거나(대화형 모드) 자격 증명을 요구합니다(비대화형 모드)
2. 볼트가 복호화되어 로드됩니다
3. 비밀번호가 유효하지 않으면 CLI는 typer.Exit(1)로 종료됩니다

중복 항목 처리

rename 명령은 여러 항목이 대상 이름과 일치할 때 결정적 동작을 강제합니다:

• 제공된 이름(발급자 또는 account_name)과 일치하는 항목이 여러 개면 이름 변경이 중단됩니다
• 오류 메시지: Error: Multiple entries named '<name>' exist. Operation aborted. Resolve duplicates first.
• 이 경우 어떤 항목도 이름이 변경되지 않습니다
• 이 검사는 어떤 변경보다 먼저 수행됩니다

📖 CLI 명령

핵심 명령

볼트 관리

전역 옵션

🔒 보안

볼트는 다음을 사용합니다:

• 인증 암호화용 AES-256-GCM
• 키 파생용 Argon2id (time_cost=4, memory_cost=128MiB, parallelism=2)
• 비밀번호 강도 평가용 zxcvbn
• 향후 호환성을 위한 버전 관리 헤더

모든 명령은 명시적 비밀번호 인증을 요구합니다. 세션 기반 접근은 없습니다.

비밀번호 강도 평가

Desktop-2FA는 볼트 비밀번호를 생성하거나 변경할 때 zxcvbn을 사용하여 비밀번호 강도를 평가합니다:

• 점수 0-2 (약함): 쉽게 추측할 수 있는 비밀번호 (예: "password123")
• 점수 3-4 (강함): 일반적인 공격에 저항력이 있는 비밀번호 (권장)

예시:

• ❌ 약함: password, 123456, qwerty, admin2024
• ✅ 강함: Battery-Horse-Staple-Correct, Mountain@River*2024, MySecureVault#42

구성 (~/.config/d2fa/config.toml):

[security]
# Require strong passwords (score >= 3)
reject_weak_passwords = false  # warn but allow | true: reject weak passwords

reject_weak_passwords = false인 경우:

• 약한 비밀번호는 노란색 경고를 표시합니다
• 사용자에게 계속 진행할지 확인을 요청합니다
• 비밀번호 수락은 비차단적입니다

reject_weak_passwords = true인 경우:

• 약한 비밀번호는 즉시 거부됩니다
• 명령이 오류와 함께 종료됩니다
• 사용자는 더 강력한 비밀번호를 선택해야 합니다

하위 호환성: 구성에 min_password_entropy가 설정되어 있다면(레거시 옵션) 이를 인식하고 zxcvbn 점수 >= 3을 요구하는 것과 동일하게 처리합니다.

보안 강화 (v0.8.0)

버전 0.8.0은 v0.7.3의 모든 이전 보안 강화 조치를 유지하며, 더 나은 코드 격리를 위한 모듈식 아키텍처를 도입합니다:

• 빈 비밀번호는 명확한 오류 메시지와 함께 즉시 거부됩니다
• 권한 오류와 볼트 파일 누락이 구분됩니다
• 사용자에게 Python 스택 추적이 표시되지 않습니다
• 파일시스템 권한 문제에 대해 사용자 친화적인 오류 메시지를 제공합니다
• 모듈식 설계는 향상된 보안 경계를 위해 CLI와 핵심 암호화 구성 요소를 분리합니다
• zxcvbn 기반 비밀번호 강도 평가(v0.8.0의 새로운 기능)

📚 문서

🧪 테스트

pytest tests/              # Run all tests
pytest --cov=src/desktop_2fa  # Run with coverage

🏗️ 프로젝트 구조

src/desktop_2fa/
├── app/           # Application components
├── cli/           # Command-line interface
├── crypto/        # Encryption utilities
├── totp/          # TOTP generation
├── ui/            # User interface components
├── vault/         # Vault management
└── utils/         # Utilities

📄 라이선스

Apache License 2.0. LICENSE 파일을 참조하세요.

👤 작성자

Łukasz Perek

🏆 후원

desktop‑2fa는 Kilo OSS 후원 프로그램을 통해 지원됩니다.

📧 문의

질문이나 지원이 필요하면 [email protected]로 문의하세요.

💖 프로젝트 지원

Desktop‑2FA는 자율성, 투명성, 오프라인 보안에 중점을 두고 만들어진 독립적인 오픈소스 도구입니다. 유용하게 사용하셨고 지속적인 개발을 지원하고 싶다면 아래 플랫폼을 통해 지원할 수 있습니다:

• Ko‑fi: https://ko-fi.com/lukaszperek
• Buy Me a Coffee: https://buymeacoffee.com/lukaszperek
• AirTM: https://airtm.me/lukper