
TOTP 2FA 코드를 생성하고 관리하기 위한 안전한 오프라인 데스크톱 애플리케이션입니다. 암호화된 볼트 저장소, 최신 암호화(Argon2 + AES‑GCM), 모듈식 아키텍처, 클라우드 의존성이 없는 로컬 우선(local-first) 방식을 갖추고 있습니다. 안정성, 확장성, 향후 크로스 플랫폼 UI를 염두에 두고 설계되었습니다.
데스크톱 환경을 위한 안전한 오프라인 2단계 인증(2FA) 관리자입니다. Python으로 구축되었으며 강력한 암호화를 제공하고 클라우드 의존성이 없습니다.
🌐 랜딩 페이지: desktop-2fa.org
| 기능 | 설명 |
|---|---|
| 🔐 볼트 보안 | Argon2id 키 유도와 함께 AES-256-GCM 암호화 |
| ⏱️ TOTP 생성 | RFC 6238 준수 코드 생성 |
| 💻 완전한 CLI | 토큰 관리를 위한 완전한 명령줄 인터페이스 |
| 📋 클립보드 지원 | TOTP 코드를 클립보드에 자동 복사 |
| 🔓 세션 제어 | CLI는 각 명령마다 인증하며, UI는 쓰기 작업 시 재인증하고 5분간 입력이 없으면 잠금 |
| 🛡️ 비밀번호 정책 | zxcvbn을 통한 구성 가능한 비밀번호 강도 적용 |
| 🧪 철저한 테스트 | 회귀 테스트에 RFC 6238 벡터와 과거 볼트 픽스처 포함 |
| 📖 보안 모델 | 상세한 위협 분석 및 암호화 설계 문서 |
| 🖥️ Textual UI | 계정 및 볼트 양식, 실시간 TOTP 카운트다운, 클립보드 작업 (0.11.0) |
Desktop-2FA 0.10.0의 영어 다크 터미널 CLI 캡처에 이어 0.11.0 Textual UI가 나옵니다. 모든 계정과 자격 증명은 합성 데이터입니다. 터미널 이미지는 실제 명령 출력을 렌더링하며, 대화형 프롬프트는 테스트 러너를 사용하고 Textual은 헤드리스로 실행됩니다. 캡처 노트 및 보고서를 참조하세요.
비밀 값을 표시하지 않고 항목을 추가하는 모습.
볼트를 초기화하고 합성 계정을 나열하는 모습.
사람이 읽을 수 있는 형식, 원시 형식, JSON 코드 출력.
암호화된 내보내기, 덮어쓰기 거부, 별도 볼트로의 복구.
Textual UI: 실시간 코드와 전체 계정/볼트 작업. 캡처 방법 및 제한 사항.
pip install desktop-2fa
설치 확인:
python -c "import desktop_2fa; print(desktop_2fa.__version__)"
# Output: 0.11.0
# Initialize a new vault
d2fa vault init
# Add a new TOTP token
d2fa add GitHub GitHub JBSWY3DPEHPK3PXP
# Or add a provisioning URI (quote it so the shell preserves '&')
d2fa add "otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA256&digits=8&period=60"
# List all entries
d2fa list
# Generate a code
d2fa code GitHub
기본적으로 볼트는 ~/.desktop-2fa/vault에 저장됩니다. 전역 --vault 옵션으로 모든 명령에 대해 다른 파일을 선택하거나, DESKTOP_2FA_VAULT를 설정하여 기본값으로 사용할 파일을 지정할 수 있습니다. 명시적인 --vault는 환경 변수보다 우선합니다. 둘 다 지정하지 않으면 기본값은 ~/.desktop-2fa/vault로 유지됩니다.
# Use a separate vault for this command
d2fa --vault ./development-vault list
# Show the currently selected vault path
d2fa --vault ./development-vault vault path
# Launch the Textual terminal UI with that vault
d2fa --vault ./development-vault ui
URI 기반 추가는 알고리즘, 자릿수, 주기를 보존하며, 생략된 매개변수는 SHA1, 6자리, 30초로 기본 설정됩니다. 레이블은 퍼센트 디코딩되며, 발급자 쿼리 매개변수는 발급자 접두사와 일치해야 합니다. 지원되지 않거나 모순되는 프로비저닝 데이터는 볼트 접근 전에 상태 6으로 종료됩니다. 대화형 추가는 발급자 프롬프트에서 URI도 허용하며 별도의 비밀 프롬프트를 건너뜁니다. URI 레이블이 계정 이름을 제공합니다.
대화형 add는 전용 Secret 프롬프트에서 입력을 숨기며, 이름과 발급자는 계속 표시됩니다. 인수로 전달된 비밀/URI는 셸 기록이나 프로세스 검사에 나타날 수 있으며, 표시되는 발급자 프롬프트에 붙여넣은 URI는 에코될 수 있습니다. 이러한 노출을 피하려면 일반 발급자 이름과 숨겨진 비밀 프롬프트를 사용하는 것이 좋습니다. 대화형 추가를 참조하세요.
0.11.0 Textual UI는 계정 관리, 볼트 생성/잠금 해제, 암호화된 가져오기/내보내기/백업 및 비밀번호 변경을 지원합니다. 코드는 카운트다운 및 유효성 표시줄과 함께 자동으로 갱신됩니다. d2fa ui로 시작하세요. 자격 증명을 제공하지 않으면 잠긴 화면이 열립니다. 쓰기 작업 시 비밀번호를 다시 요청하며, Ctrl+L 또는 5분간 비활성 상태가 지속되면 세션이 잠깁니다. UI 가이드를 참조하세요. 버전 0.10.0에는 이전 프로토타입이 포함되어 있었으며, 이러한 계정 및 볼트 워크플로를 사용하려면 0.11.0으로 업그레이드하세요.
# Provide password via command line
d2fa --password mypassphrase add GitHub GitHub JBSWY3DPEHPK3PXP
# Provide password via file
d2fa --password-file /path/to/passphrase.txt add GitHub GitHub JBSWY3DPEHPK3PXP
볼트는 기본적으로 ~/.desktop-2fa/vault에 위치한 암호화된 저장 파일입니다. 다른 경로를 선택하려면 --vault 또는 DESKTOP_2FA_VAULT를 사용하십시오. 볼트 파일은 10 MiB를 초과하지 않는 일반 파일이어야 합니다.
현재 로더는 볼트 형식 버전 1을 지원합니다. 향후 릴리스가 모든 이전 형식을 지원한다고 보장되지는 않습니다. 업그레이드하기 전에 암호화된 백업을 생성하고 안전하게 보관하십시오.
Desktop-2FA 0.9.0은 공개 Python API를 변경합니다. Vault.save()와 Vault.load()는 명시적이고 비어 있지 않은 비밀번호를 요구합니다. 이전 Python API 버전에서 비밀번호 없이 생성된 볼트는 업그레이드하기 전에 이전 릴리스를 사용하여 비어 있지 않은 비밀번호로 열고 다시 저장해야 합니다. CLI 및 Textual UI 흐름은 이미 비어 있지 않은 비밀번호를 요구합니다.
d2fa backup
새 TOTP 시크릿은 공유 Base32 규칙을 사용합니다. ASCII 대소문자와 공백이 허용되고, 올바른 후행 패딩은 선택 사항이며, 디코딩된 키가 비어 있으면 볼트 접근 전에 거부됩니다. 새 레코드는 디코딩된 바이트가 동일한 표준 대문자 패딩 텍스트를 사용합니다. 기존 시크릿 텍스트는 로드/저장 시 보존됩니다. 레거시의 빈 시크릿이나 과거에 허용되었던 유니코드 폴딩 시크릿은 계속 목록에 표시되지만 코드를 생성할 수 없으며, code는 상태 6과 함께 invalid_secret을 보고합니다. 명시적 복구 절차를 참조하십시오.
CLI에서는 vault init, list, add만 누락된 볼트를 생성합니다. 다른 콘텐츠 명령은 누락된 볼트 오류를 보고합니다. 생성 시:
--password/--password-file을 요구합니다(비대화형 모드)list는 빈 암호화 볼트를 생성하고, add는 검증된 항목이 포함된 볼트를 생성합니다Vault created at <path>를 출력합니다0.11.0 Textual UI는 Create vault를 통해 볼트를 명시적으로 생성할 수 있으며, 비밀번호 확인과 기존 대상에 대한 덮어쓰기 체크박스를 제공합니다.
명령에 볼트가 필요하고 볼트가 존재하는 경우:
code 및 remove 명령은 이름을 대소문자를 구분하여 확인합니다. 정확한 account_name 일치가 다른 항목의 발급자보다 우선합니다. 정확한 계정 일치가 없으면 호환성을 위해 고유한 발급자 일치가 허용됩니다. 여러 개의 정확한 계정 일치 또는 여러 개의 대체 발급자 일치가 있는 경우 Ambiguous entry 오류(종료 상태 6)와 함께 거부되며, 볼트는 변경되지 않습니다. code --json은 entry_ambiguous를 보고합니다. Python Vault.get_entry() 및 Vault.remove_entry(), 그리고 공개 코드/제거 헬퍼도 동일한 규칙을 사용하며, 모호한 조회는 ValueError의 하위 클래스인 desktop_2fa.vault.AmbiguousEntry를 발생시킵니다.
rename 명령은 동일한 정확한 계정 이름/고유 발급자 규칙을 사용하며, 변경 전에 이미 사용 중인 대상 계정 이름을 거부합니다. 명시적 선택자가 없는 모호성, 유효하지 않은 선택자, 이미 사용 중인 대상은 상태 6으로 종료됩니다. 계정 이름과 발급자 모두 업데이트되며, 고유한 이름의 항목을 자기 자신으로 이름 변경하는 것은 허용되고 발급자는 여전히 업데이트됩니다.
레거시 중복 항목의 경우 d2fa list --indices를 실행한 다음, 표시된 1부터 시작하는 항목 번호를 사용하여 d2fa rename OLD NEW --index N을 실행하십시오. 선택된 항목은 일반 조회에서 사용하는 계정 이름/발급자 계층에서 OLD와 일치해야 합니다. 인덱스는 영구 ID가 아니라 현재 목록 순서를 나타내며, 항목을 추가/제거한 후에는 다시 목록을 확인하고 동시 볼트 편집을 피하십시오. 중복 복구를 참조하십시오.