오프라인 도구가 일부 BIP39 시드 문구 복구를 돕는다

Seed Recovery Tool은 단어 하나를 잊거나 철자를 틀린 BIP39 시드 문구를 오프라인에서 복구하도록 돕는 오픈소스 도구다. CLI와 데스크톱 GUI를 제공하며, 제작자는 문구를 네트워크로 전송하지 않는다고 설명한다.

복구 기능과 한계

이 도구는 공식 BIP39 단어 목록에 맞춰 오타를 찾고, 누락되거나 잊은 단어 1~3개를 대입해 체크섬이 유효한 후보를 찾는다. 알고 있는 단어들의 순서를 모를 때 순서를 검색하는 기능도 있다. 전체 12단어 문구의 순서 검색은 몇 분 걸리지만 더 긴 문구는 며칠이 걸릴 수 있다.

데스크톱 앱은 후보 문구를 알고 있는 비트코인 주소와 대조할 수 있다. 따라서 체크섬만 통과한 후보 목록이 아니라 사용자의 주소에 맞는 문구를 찾는 데 활용할 수 있다. 1, 3, bc1q, bc1p로 시작하는 비트코인 주소와 이더리움(0x…) 주소를 지원하며, Ledger Live 계정도 포함한다.

시드 문구에 관한 정보가 전혀 없으면 복구할 수 없다. 제작자는 이를 할 수 있다고 주장하는 사람이나 도구는 사기라고 경고한다. BIP39 패스프레이즈, 이른바 ‘25번째 단어’도 사용자가 후보 목록을 제공하지 않는 한 무차별 대입으로 찾을 수 없다.

설치와 이용 조건

최신 릴리스에는 Windows, macOS(Intel 및 Apple Silicon), Linux용 설치 파일과 실행 전 확인할 SHA-256 체크섬이 있다. 설치 파일은 이 저장소에서 GitHub Actions로 빌드하며, 설정은 release.yml에 공개돼 있다.

설치 파일은 아직 코드 서명되지 않았다. 따라서 Windows와 macOS는 처음 실행할 때 알 수 없는 게시자에 관한 경고를 표시한다. 릴리스 노트에는 경고를 넘겨 실행하는 방법과 파일을 먼저 확인하는 방법이 안내돼 있다.

이 프로젝트는 초기 프로토타입이다. src/bip39.py의 핵심 BIP39 로직은 공식 Trezor/BIP39 참조 테스트 벡터로 검증됐다. 12단어 및 24단어 문구, 엔트로피와 니모닉 간 변환, 체크섬 검증, PBKDF2 시드 도출 결과가 공개 참조값과 정확히 일치한다고 프로젝트는 설명한다. 독립 감사를 마친 부분과 아직 감사하지 않은 부분은 docs/SECURITY.md에서 확인할 수 있다.

인터페이스는 두 가지다. CLI는 Python으로 작성한 기존 구현이며, 프로젝트는 이를 완전히 테스트된 구현이라고 설명한다. 데스크톱 GUI는 Tauri와 Rust를 사용해 같은 BIP39 로직을 포팅한 버전이다. 자체 공식 테스트 벡터, 진행 상황 표시와 취소 기능이 있는 멀티코어 검색, 주소 대조 기능을 갖췄다. BIP84/BIP86 참조 주소를 포함한 전체 테스트 스위트는 Linux, macOS, Windows의 CI에서 실행된다.

CLI를 포함해 저장소의 코드는 MIT 라이선스에 따라 무료로 공개된다. 데스크톱 앱에는 무료 기능과 유료 기능이 있다. 다중 단어 검색은 1회 결제 $25인 라이선스가 필요하며, Ed25519 서명 라이선스 키로 제한된다. 키는 오프라인에서 확인되고 앱은 검증을 위해 서버에 접속하지 않는다. 유료 라이선스는 검색 기능에 대한 비용이지 복구 결과를 보장하지 않는다. docs/LICENSING.md에 라이선스 관련 설명이 있다.

직접 확인하고 안전하게 사용하는 방법

프로젝트는 코드를 검토하고 오프라인에서 실행해 주장을 직접 확인하라고 안내한다. 핵심 로직 파일 src/bip39.py는 200줄 미만이며, Python 표준 라이브러리의 hashlib, hmac, unicodedata만 사용한다. 프로젝트 설명에 따르면 서드파티 의존성은 없고 네트워크 라이브러리도 어디에서도 가져오지 않는다.

실제 문구를 입력하기 전에 인터넷 연결을 끊고 실행해야 한다. 이 도구는 연결 없이 작동하며, 프로젝트는 실제 시드 문구를 웹 도구에 붙여 넣지 말라고 당부한다. 향후 호스팅 버전이 나오더라도 여기에 실제 문구를 입력하지 말고, 내려받은 도구를 직접 실행하라는 안내다.

테스트 벡터는 다음 명령으로 실행할 수 있다. 프로젝트는 이것이 Go, Rust, JS BIP39 라이브러리에서 업계 전반에 사용하는 것과 같은 참조 벡터를 기준으로 구현을 검사한다고 설명한다.

python3 tests/test_vectors.py

CLI 사용 예시는 다음과 같다.

# Fix a typo
python3 src/recover.py fix "abandan abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

# Recover one missing word (mark unknown slots with ?)
python3 src/recover.py missing "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon ?"

# Recover word order (only practical for a few unknown positions)
python3 src/recover.py reorder "about abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon"

체크섬을 통과한 후보는 유효한 BIP39 문구이지만, 반드시 사용자의 실제 문구라는 뜻은 아니다. 복구한 문구를 자금에 사용하기 전에 해당 문구로 주소를 도출하고, 지갑에 속한다고 이미 알고 있는 주소와 일치하는지 확인해야 한다.

프로젝트 구조는 seed-recovery-tool/ ├── src/ │ ├── bip39.py # Core BIP39 logic — checksum, entropy<->mnemonic, seed derivation │ └── recover.py # CLI: typo fix, missing-word brute force, reorder search ├── tests/ │ └── test_vectors.py # Official Trezor/BIP39 reference test vectors (Python) ├── wordlists/ │ └── english.txt # Official BIP39 English wordlist (2048 words) ├── docs/ │ └── SECURITY.md # Responsible disclosure + audit status └── gui/ # Desktop GUI (Tauri + Rust) — see gui/BUILD.md ├── BUILD.md # Reproducible build process, not yet executed/verified ├── package.json ├── src/ # Plain HTML/CSS/JS frontend, no framework, no network calls │ ├── index.html │ ├── style.css │ └── main.js └── src-tauri/ ├── Cargo.toml ├── tauri.conf.json # Locked-down allowlist — no fs/shell/http APIs enabled ├── build.rs ├── wordlists/english.txt └── src/ ├── bip39.rs # Rust port of src/bip39.py, with its own official test vectors └── main.rs # Tauri commands exposed to the frontend다. gui/BUILD.md에는 재현 가능한 빌드 절차가 있지만 아직 실행하거나 검증하지 않았다고 적혀 있다. Tauri 설정의 허용 목록은 제한돼 있으며 fs/shell/http API를 활성화하지 않는다.

MIT 라이선스 전문은 LICENSE에서 볼 수 있다. 프로젝트는 코드 누구나 읽고 실행하고 포크해 개선할 수 있도록 허용한다고 설명한다. 도구는 보증 없이 제공되며, 복구한 문구를 실제 자금에 사용하기 전에 검증할 책임은 사용자에게 있다.