Hotpot 🍲

커맨드라인용 Authy / Google Authenticator

Hotpot은 TOTP 기반 2단계 인증 코드를 관리하기 위한 간단하고 안전한 커맨드라인 도구입니다. Hotpot은 2FA 비밀키를 시스템 키링에 안전하게 저장하고, 필요할 때 시간 기반 일회용 비밀번호를 생성합니다.

보안, 성능, 안정성을 위해 Rust로 제작되었습니다.

기능

• 시스템 키링(Keychain/libsecret/Credential Manager)을 사용하는 안전한 저장
• 사용자 정의 가능한 알고리즘(SHA1/SHA256/SHA512)을 지원하는 TOTP(RFC 6238) 코드 생성
• 실시간 코드, 진행 표시줄, 퍼지 검색을 제공하는 인터랙티브 대시보드
• 시각적 피드백과 함께 제공되는 원클릭 클립보드 복사
• 모바일 앱 설정이 간편한 QR 코드 내보내기
• QR 코드 가져오기를 위한 스크린샷 캡처(macOS)
• 부드러운 애니메이션을 갖춘 빠르고 반응성 높은 터미널 UI
• 계정을 빠르게 찾을 수 있는 퍼지 검색

설치

이 저장소를 클론하고 다음을 실행하세요:

cargo install --path . --locked

사용법

새 계정 추가

hotpot add <account-name>

Base32 비밀키를 안전하게 입력하라는 프롬프트가 표시됩니다.

예시:

hotpot add github
Enter the Base32 secret: ********

QR 코드 이미지에서 추가 (macOS)

hotpot --load-image /path/to/qr-code.png

또는 대시보드에서 [A]를 누른 다음 [S]를 눌러 인터랙티브 스크린샷 캡처를 사용할 수 있습니다.

인터랙티브 대시보드

hotpot을 실행하기만 하면 인터랙티브 대시보드가 열리며 다음을 수행할 수 있습니다:

• 부드러운 진행 표시줄과 함께 모든 TOTP 코드 실시간 보기
• 위/아래 화살표로 이동
• Enter를 눌러 코드 복사("복사됨" 표시기 표시)
• [F]를 누르고 입력하여 검색(퍼지 매칭)
• [A]를 누른 후 [M]anual 또는 [S]creenshot(macOS)을 선택하여 계정 추가
• [D]를 눌러 계정 삭제(확인 절차 포함)
• 모바일 앱 설정을 위해 [E]를 눌러 QR 코드 내보내기
• 'q', 'Esc', Ctrl+C로 종료

대시보드는 250ms마다 자동으로 새로고침되며 터미널 크기 변경도 자연스럽게 처리합니다.

단일 코드 생성

hotpot code <account-name>

예시:

hotpot code github

계정 삭제

hotpot delete <account-name>

QR 코드 내보내기

대시보드에서([E] 누름) 또는 다음 명령어를 사용하여 계정의 QR 코드를 내보낼 수 있습니다:

hotpot export-qr --name <account-name>

그러면 터미널에 인증 앱으로 스캔할 수 있는 QR 코드가 표시됩니다.

파일 기반 저장 모드

휴대용 구성이 필요하거나 키링에 접근할 수 없는 경우, --file 플래그를 사용하여 계정을 안전한 키링 대신 JSON 파일에 저장할 수 있습니다.

# Interactive dashboard with file storage
hotpot --file ~/.config/hotpot/accounts.json

# Add account to file
hotpot --file ./my-accounts.json add work-account

# Generate code from file-stored account
hotpot --file ./my-accounts.json code work-account

# Delete account from file
hotpot --file ./my-accounts.json delete work-account

파일 기반 저장의 사용 사례:

• 휴대용 구성: 동기화하거나 백업할 수 있는 파일에 계정을 저장
• 서버 환경: 키링 서비스를 사용할 수 없을 때 활용
• 개발/테스트: 테스트 계정을 안전한 저장소와 분리
• 팀 공유: 계정 구성을 공유(파일 보안 유지)

보안 참고 사항: 파일 기반 저장은 비밀키를 평문 JSON으로 저장합니다. 적절한 파일 권한(600)을 설정하고, 민감한 환경에서는 파일 암호화를 고려하세요.

보안

기본 보안 저장: Hotpot은 모든 비밀키를 시스템 키링에 안전하게 저장합니다:

• macOS: Keychain
• Linux: Secret Service API/libsecret
• Windows: Windows Credential Manager

파일 기반 저장: --file 플래그를 사용하면 계정이 지정된 경로의 JSON 파일에 저장됩니다. 파일은 적절한 권한(600)으로 생성되며, 필요한 경우 디렉토리도 자동으로 생성됩니다. 이 모드는 휴대용 구성이 필요하거나 키링 접근이 불가능한 환경에서 유용합니다.

개발

소스에서 빌드

1. Rust가 설치되어 있는지 확인하세요
2. 저장소를 클론하세요
3. 다음 명령을 실행하세요:

cargo build --release

바이너리는 target/release/hotpot에서 확인할 수 있습니다.

테스트 실행

이 프로젝트는 핵심 기능을 다루는 포괄적인 단위 테스트를 포함하고 있습니다:

cargo test

테스트 범위는 다음과 같습니다:

• TOTP 코드 생성 및 검증
• 계정 필터링 및 검색 로직
• QR 코드 파싱 및 검증
• 대시보드 상태 관리
• 입력 처리 및 모드 전환

개발 명령어

# Run in development mode
cargo run

# Run with specific arguments
cargo run -- add github

# Test with file storage
cargo run -- --file test-accounts.json add test-account


# Check code quality
cargo clippy

# Quick compile check
cargo check

아키텍처

Hotpot은 보안과 유지보수성에 초점을 맞춘 모듈식 아키텍처로 제작되었습니다:

• main.rs: CLI 인터페이스 및 저장소 관리
• totp.rs: 포괄적인 테스트 적용 범위를 갖춘 TOTP 알고리즘 구현(RFC 6238)
• dashboard.rs: 실시간 업데이트와 광범위한 단위 테스트를 갖춘 인터랙티브 터미널 UI
• lib.rs: 공통 오류 처리 및 공유 유틸리티

주요 의존성

• 보안 및 저장: keyring, base32, hmac, sha1/sha2
• CLI 및 터미널: clap, crossterm, rpassword
• 인터랙티브 기능: fuzzy-matcher, qrcode, arboard
• 데이터 처리: serde, serde_json, url, urlencoding
• 이미지 처리: image, (QR 코드 감지)

라이선스

MIT 라이선스

기여

기여는 언제나 환영합니다! 부담 없이 Pull Request를 제출해 주세요.

코드 품질

이 프로젝트는 높은 코드 품질 기준을 유지합니다:

• 포괄적인 단위 테스트(cargo test 실행)
• Clippy 린팅(cargo clippy 실행)
• 문서화가 잘 된 함수와 모듈
• 적절한 오류 처리를 갖춘 안전한 코딩 관행

최근 개선 사항

• 향상된 대시보드: 유지보수성과 성능 향상을 위한 UI 코드 리팩터링
• 포괄적인 테스트: 핵심 기능을 다루는 25개 이상의 단위 테스트 추가
• 개선된 UX: 복사된 코드에 대한 시각적 피드백과 부드러운 진행 표시줄 추가
• 코드 품질: 헬퍼 함수 추출 및 코드 중복 감소