🔗 TurtlPass Ecosystem

🐢 Firmware • 💾 Protobuf • 💻 Host • 🌐 Chrome • 📱 Android

---

💻 TurtlPass Host (Python CLI)

A minimal host-side command-line client for interacting with TurtlPass hardware devices via USB. Generate passwords, manage cryptographic seeds, and control your TurtlPass device securely and locally — all from the terminal.

---

⚡ Features

• 🔌 Automatic Device Detection — Instantly detects connected TurtlPass devices
• 🔐 Secure Password Generation — Fully configurable length & charset
• 🧬 Seed Management — Initialize, generate, or restore 512-bit seeds from 24-word BIP-39 mnemonics
• 💥 Factory Reset — Safely reset your device to factory defaults
• 🔒 Hardware Security — All cryptography happens on-device; seeds never leave the TurtlPass

---

⚙️ Requirements

• Python 3.8+
• TurtlPass device
• USB cable with data support

---

📦 Installation

git clone https://github.com/TurtlPass/turtlpass-python.git
cd turtlpass-python
pip install -r requirements.txt

---

🚀 Usage

1. Plug in your TurtlPass device and run:

   python turtlpass.py

2. Choose from the interactive menu:

   ████████╗██╗░░░██╗██████╗░████████╗██╗░░░░░██████╗░░█████╗░░██████╗░██████╗
   ╚══██╔══╝██║░░░██║██╔══██╗╚══██╔══╝██║░░░░░██╔══██╗██╔══██╗██╔════╝██╔════╝
   ░░░██║░░░██║░░░██║██████╔╝░░░██║░░░██║░░░░░██████╔╝███████║╚█████╗░╚█████╗░
   ░░░██║░░░██║░░░██║██╔══██╗░░░██║░░░██║░░░░░██╔═══╝░██╔══██║░╚═══██╗░╚═══██╗
   ░░░██║░░░╚██████╔╝██║░░██║░░░██║░░░███████╗██║░░░░░██║░░██║██████╔╝██████╔╝
   ░░░╚═╝░░░░╚═════╝░╚═╝░░╚═╝░░░╚═╝░░░╚══════╝╚═╝░░░░░╚═╝░░╚═╝╚═════╝░╚═════╝░
   Welcome to TurtlPass!
   Device detected: /dev/cu.usbmodem14101
   Options:
   0. <Exit>
   1. Get TurtlDevice Information
   2. Generate Password on TurtlDevice
   3. Initialize TurtlDevice with 512-bit Seed
   4. Generate 24-word Mnemonic and Derive 512-bit Seed
   5. Restore 512-bit Seed from a 24-word Mnemonic
   6. Factory Reset TurtlDevice (⚠️ DANGEROUS)
   Select an option: 
   

---

📖 Usage Example: Generate a Password

2. Generate Password on TurtlDevice
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
Enter desired password length (1-128) [press ENTER to use 100]: 128
Select character set:
1. Numbers (0–9)
2. Letters (a–z, A–Z)
3. Letters + Numbers (a–z, A–Z, 0–9)  [default]
4. Letters + Numbers + Symbols (a–z, A–Z, 0–9, symbols)
Choose charset [press ENTER to use default]: 4

Enter Domain Name (e.g. 'google'): github
Enter Account ID (e.g. 'user@example.com'): turtlpass@ryanamaral.com
Enter PIN (e.g. '704713'): ******

✅ Password successfully generated
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

All passwords are generated on-device, ensuring maximum security.

---

💻 Supported Platforms

OS	Status
Linux	✅ Supported
macOS	✅ Supported
Windows	✅ Supported

---

🧰 Troubleshooting

• Device not detected: Ensure USB cable supports data transfer and device is plugged in
• Linux users: You may need to add a udev rule for USB access
• macOS users: Check /dev/cu.* to find the connected device
• Windows users: Verify COM port and drivers

---

📚 Dependencies

• argon2-cffi — Secure Argon2 key derivation and password hashing
• pyserial — USB communication with the TurtlPass device
• protobuf — Protocol Buffers serialization for device messages
• mnemonic — BIP-39 mnemonic generation and seed handling

---

📜 License

This repository is licensed under the MIT License.