SeedPass is a secure password generator and manager built on Bitcoin's BIP-85 standard. It uses deterministic key derivation to generate passwords that are never stored, but can be easily regenerated when needed. By integrating with the Nostr network, SeedPass compresses your encrypted vault and splits it into 50 KB chunks. Each chunk is published as a parameterised replaceable event (kind 30071), with a manifest (kind 30070) describing the snapshot and deltas (kind 30072) capturing changes between snapshots. This allows secure password recovery across devices without exposing your data.

Tip Jar

⚠️ Disclaimer

This software was not developed by an experienced security expert and should be used with caution. There may be bugs and missing features. Each vault chunk is limited to 50 KB and SeedPass periodically publishes a new snapshot to keep accumulated deltas small. The security of the program's memory management and logs has not been evaluated and may leak sensitive information. Loss or exposure of the parent seed places all derived passwords, accounts, and other artifacts at risk.

🚨 Breaking Change

Recent releases derive passwords and other artifacts using a fully deterministic algorithm that behaves consistently across Python versions. This improvement means artifacts generated with earlier versions of SeedPass will not match those produced now. Regenerate any previously derived data or retain the old version if you need to reproduce older passwords or keys.

Supported OS

✔ Windows 10/11 • macOS 12+ • Any modern Linux
SeedPass now uses the portalocker library for cross-platform file locking. No WSL or Cygwin required.

Features
Architecture Overview
Prerequisites
Installation
Usage
Building a standalone executable
Packaging with Briefcase
Security Considerations
Dependency Updates
Contributing
License
Contact

Features

Deterministic Password Generation: Utilize BIP-85 for generating deterministic and secure passwords.
Encrypted Storage: All seeds, login passwords, and sensitive index data are encrypted locally.
Nostr Integration: Post and retrieve your encrypted password index to/from the Nostr network. See Nostr Setup for relay configuration and event details.
Chunked Snapshots: Encrypted vaults are compressed and split into 50 KB chunks published as kind 30071 events with a kind 30070 manifest and kind 30072 deltas. The manifest's delta_since field stores the UNIX timestamp of the latest delta event.
Automatic Checksum Generation: The script generates and verifies a SHA-256 checksum to detect tampering.
Multiple Seed Profiles: Manage separate seed profiles and switch between them seamlessly.
Nested Managed Account Seeds: SeedPass can derive nested managed account seeds.
Interactive TUI: Navigate through menus to add, retrieve, and modify entries as well as configure Nostr settings.
SeedPass 2FA: Generate TOTP codes with a real-time countdown progress bar.
2FA Secret Issuance & Import: Derive new TOTP secrets from your seed or import existing otpauth:// URIs.
Export 2FA Codes: Save all stored TOTP entries to an encrypted JSON file for use with other apps.
Display TOTP Codes: Show all active 2FA codes with a countdown timer.
Optional External Backup Location: Configure a second directory where backups are automatically copied.
Auto-Lock on Inactivity: Vault locks after a configurable timeout for additional security.
Quick Unlock: Optionally skip the password prompt after verifying once.
Secret Mode: When enabled, newly generated and retrieved passwords are copied to your clipboard and automatically cleared after a delay.
Tagging Support: Organize entries with optional tags and find them quickly via search.
Typed Search Results: Results now display each entry's type for quicker identification.
Manual Vault Export/Import: Create encrypted backups or restore them using the CLI or API.
Parent Seed Backup: Securely save an encrypted copy of the master seed.
Manual Vault Locking: Instantly clear keys from memory when needed.
Vault Statistics: View counts for entries and other profile metrics.
Change Master Password: Rotate your encryption password at any time.
Checksum Verification Utilities: Verify or regenerate the script checksum.
Relay Management: List, add, remove or reset configured Nostr relays.
Offline Mode: Disable all Nostr communication for local-only operation.

A small on-screen notification area now shows queued messages for 10 seconds before fading.

Architecture Overview

SeedPass follows a layered design. The seedpass.core package exposes the PasswordManager along with service classes (e.g. VaultService and EntryService) that implement the main API used across interfaces. Both the command line tool in seedpass.cli and the FastAPI server in seedpass.api delegate operations to this core. The BeeWare desktop interface (seedpass_gui.app) and an optional browser extension reuse these services, with the extension communicating through the API layer.

Nostr synchronisation lives in the nostr modules. The core services call into these modules to publish or retrieve encrypted snapshots and deltas from configured relays.

graph TD
    cli["CLI"]
    api["FastAPI server"]
    core["seedpass.core"]
    nostr["Nostr client"]
    relays["Nostr relays"]

    cli --> core
    api --> core
    core --> nostr
    nostr --> relays

See docs/ARCHITECTURE.md and Nostr Setup for details.

Prerequisites

Python 3.8+ (3.11 or 3.12 recommended): Install Python from python.org and be sure to check "Add Python to PATH" during setup. Using Python 3.13 is currently discouraged because some dependencies do not ship wheels for it yet, which can cause build failures on Windows unless you install the Visual C++ Build Tools.
Windows only: Install the Visual Studio Build Tools and select the C++ build tools workload.

Installation

Quick Installer

Use the automated installer to download SeedPass and its dependencies in one step. The scripts can also install the BeeWare backend for your platform when requested (use -IncludeGui on Windows). If the GTK gi bindings are missing, the installer attempts to install the necessary system packages using apt, yum, pacman, or Homebrew.

Linux and macOS:

bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)"

Install the beta branch:

bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)" _ -b beta

Make sure the command ends right after -b beta with no trailing parenthesis.

Windows (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $scriptContent = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.ps1'); & ([scriptblock]::create($scriptContent))

Install with the optional GUI:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $scriptContent = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.ps1'); & ([scriptblock]::create($scriptContent)) -IncludeGui

Before running the script, install Python 3.11 or 3.12 from python.org and tick "Add Python to PATH". You should also install the Visual Studio Build Tools with the C++ build tools workload so dependencies compile correctly.
The Windows installer will attempt to install Git automatically if it is not already available. It also tries to install Python 3 using winget, choco, or scoop when Python is missing and recognizes the py launcher if python isn't on your PATH. If these tools are unavailable you'll see a link to download Python directly from https://www.python.org/downloads/windows/. When Python 3.13 or newer is detected without the Microsoft C++ build tools, the installer now attempts to download Python 3.12 automatically so you don't have to compile packages from source.

Note: If this fallback fails, install Python 3.12 manually or install the Microsoft Visual C++ Build Tools and rerun the installer.

Windows Nostr Sync Troubleshooting

When backing up or restoring from Nostr on Windows, a few issues are common:

Event loop errors – Messages like RuntimeError: Event loop is closed usually mean the async runtime failed to initialize. Running SeedPass with --verbose provides more detail about which coroutine failed.
Permission problems – If you see Access is denied when writing to ~/.seedpass, launch your terminal with "Run as administrator" so the app can create files in your profile directory.
Missing dependencies – Ensure websockets and other requirements are installed inside your virtual environment:
```
pip install websockets
```

Using increased log verbosity helps diagnose sync issues and confirm that the WebSocket connections to your configured relays succeed.

Uninstall

Run the matching uninstaller if you need to remove a previous installation or clean up an old seedpass command:

Linux and macOS:

bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/uninstall.sh)"

If you see a warning that an old executable couldn't be removed, delete the file manually.

Windows (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $scriptContent = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/uninstall.ps1'); & ([scriptblock]::create($scriptContent))

Manual Setup

Follow these steps to set up SeedPass on your local machine.

Clone the Repository

git clone https://github.com/PR0M3TH3AN/SeedPass.git
cd SeedPass

Create a Virtual Environment
```
python3 -m venv venv
```
Activate the Virtual Environment
- Linux/macOS:
```
source venv/bin/activate
```
- Windows:
```
venv\Scripts\activate
```

Install Dependencies

python -m pip install --upgrade pip
python -m pip install --require-hashes -r requirements.lock
python -m pip install -e .

// 🔧 merged conflicting changes from codex/locate-command-usage-issue-in-seedpass vs beta After reinstalling, run which seedpass on Linux/macOS or where seedpass on Windows to confirm the command resolves to your virtual environment's seedpass executable.

Linux Clipboard Support

On Linux, pyperclip relies on external utilities like xclip or xsel. SeedPass no longer installs these tools automatically. To enable clipboard features such as secret mode, install xclip manually:

sudo apt install xclip

After installing xclip, restart SeedPass to enable clipboard support.

Optional GUI

SeedPass ships with a GTK-based desktop interface that is still in development and not currently functional. Install the packages for your platform before adding the Python GUI dependencies.

Debian/Ubuntu

sudo apt install libgirepository1.0-dev libcairo2-dev libpango1.0-dev libwebkit2gtk-4.0-dev

Fedora

sudo dnf install gobject-introspection-devel cairo-devel pango-devel webkit2gtk4.0-devel

Arch Linux

sudo pacman -S gobject-introspection cairo pango webkit2gtk

macOS (Homebrew)

brew install pygobject3 gtk+3 adwaita-icon-theme librsvg webkitgtk

With the system requirements in place, install the Python GUI extras:

pip install .[gui]

CLI-only users can skip these steps and install just the core package for a lightweight setup:

pip install .

Quick Start

After installing dependencies and activating your virtual environment, install the package in editable mode so the seedpass command is available:

python -m pip install -e .

You can then launch SeedPass and create a backup:

# Start the application (interactive TUI)
seedpass

# Export your index
seedpass export --file "~/seedpass_backup.json"

# Later you can restore it
seedpass import --file "~/seedpass_backup.json"

# Quickly find or retrieve entries
seedpass search "github"
seedpass search --tags "work,personal"
seedpass get "github"
# Search results show the entry type, e.g. "1: Password - GitHub"
# Retrieve a TOTP entry
seedpass entry get "email"
# The code is printed and copied to your clipboard

# Sort or filter the list view
seedpass list --sort label
seedpass list --filter totp
# Generate a password with the safe character set defined by `SAFE_SPECIAL_CHARS`
seedpass util generate-password --length 20 --special-mode safe --exclude-ambiguous

# Use the **Settings** menu to configure an extra backup directory
# on an external drive.

For additional command examples, see docs/advanced_cli.md. Details on the REST API can be found in docs/api_reference.md.

Getting Started with the GUI

SeedPass also ships with a simple BeeWare desktop interface. Launch it from your virtual environment using any of the following commands:

seedpass gui
python -m seedpass_gui
seedpass-gui

GUI dependencies are optional. Install them alongside SeedPass with:

pip install "seedpass[gui]"

# or when working from a local checkout
pip install -e .[gui]

After installing the optional GUI extras, add the BeeWare backend for your platform:

# Linux
pip install toga-gtk

# If you see build errors about "cairo" on Linux, install the cairo
# development headers using your package manager, e.g.:
sudo apt-get install libcairo2 libcairo2-dev

# Windows
pip install toga-winforms

# macOS
pip install toga-cocoa

The GUI works with the same vault and configuration files as the CLI.

graph TD
    core["seedpass.core"]
    cli["CLI"]
    api["FastAPI server"]
    gui["BeeWare GUI"]
    ext["Browser Extension"]

    cli --> core
    gui --> core
    api --> core
    ext --> api

Vault JSON Layout

The encrypted index file seedpass_entries_db.json.enc begins with schema_version 2 and stores an entries map keyed by entry numbers.

{
  "schema_version": 2,
  "entries": {
    "0": {
      "label": "example.com",
      "length": 8,
      "type": "password",
      "notes": ""
    }
  }
}

Note

Opening a vault created by older versions automatically converts the legacy seedpass_passwords_db.json.enc (Fernet) to AES-GCM as seedpass_entries_db.json.enc. The original file is kept with a .fernet extension. The same migration occurs for a legacy parent_seed.enc encrypted with Fernet: it is transparently decrypted, re-encrypted with AES-GCM and the old file saved as parent_seed.enc.fernet.

Usage

After successfully installing the dependencies, install the package with:

python -m pip install -e .

Once installed, launch the interactive TUI with:

seedpass

You can also run directly from the repository with:

python src/main.py

You can explore other CLI commands using:

seedpass --help

If this command displays usage: main.py instead of the Typer help output, an old seedpass executable is still on your PATH. Remove it with pip uninstall seedpass or delete the stale launcher and rerun:

python -m pip install -e .

// 🔧 merged conflicting changes from codex/locate-command-usage-issue-in-seedpass vs beta You can confirm which executable will run with:

which seedpass  # or 'where seedpass' on Windows

For a full list of commands see docs/advanced_cli.md. The REST API is described in docs/api_reference.md.

Running the Application

Start the Application:
```
seedpass
```
(or python src/main.py when running directly from the repository)
Follow the Prompts:
- Seed Profile Selection: If you have existing seed profiles, you'll be prompted to select one or add a new one.
- Enter Your Password: This password is crucial as it is used to encrypt and decrypt your parent seed and seed index data.
- Select an Option: Navigate through the menu by entering the number corresponding to your desired action.
Example menu:
```
Select an option:
1. Add Entry
2. Retrieve Entry
3. Search Entries
4. List Entries
5. Modify an Existing Entry
6. 2FA Codes
7. Settings

Enter your choice (1-7) or press Enter to exit:
```

When choosing Add Entry, you can now select from:

Password
2FA (TOTP)
SSH Key
Seed Phrase
Nostr Key Pair
PGP Key
Key/Value
Managed Account

Adding a Password Entry

After selecting Password, SeedPass asks you to pick a mode:

Quick – prompts only for a label, username, URL, desired length, and whether to include special characters. Default values are used for notes, tags, and policy settings.
Advanced – walks through the full set of prompts for notes, tags, custom fields, and detailed password policy options.

Both modes generate the password, display it (or copy it to the clipboard in Secret Mode), and save the entry to your encrypted vault.

Adding a 2FA Entry

From the main menu choose Add Entry and select 2FA (TOTP).
Pick Make 2FA to derive a new secret from your seed or Import 2FA to paste an existing otpauth:// URI or secret.
Provide a label for the account (for example, GitHub).
SeedPass automatically chooses the next available derivation index when deriving.
Optionally specify the TOTP period and digit count.
SeedPass displays the URI and secret, along with a QR code you can scan to import it into your authenticator app.

Modifying a 2FA Entry

From the main menu choose Modify an Existing Entry and enter the index of the 2FA code you want to edit.
SeedPass will show the current label, period, digit count, and archived status.
Enter new values or press Enter to keep the existing settings.
When retrieving a 2FA entry you can press E to edit the label, period or digit count, or A to archive/unarchive it.
The updated entry is saved back to your encrypted vault.
Archived entries are hidden from lists but can be viewed or restored from the List Archived menu.
When editing an archived entry you'll be prompted to restore it after saving your changes.

Using Secret Mode

When Secret Mode is enabled, SeedPass copies newly generated and retrieved passwords directly to your clipboard instead of displaying them on screen. The clipboard clears automatically after the delay you choose.

From the main menu open Settings and select Toggle Secret Mode.
Choose how many seconds to keep passwords on the clipboard.
Generate or retrieve an entry and SeedPass will confirm the password was copied.

Viewing Entry Details

Selecting an item from List Entries or Search Entries first displays the entry's metadata such as the label, username, tags and notes. Passwords, seed phrases and other sensitive fields remain hidden until you choose to reveal them. When you opt to show the secret, the details view presents the same action menu as Retrieve Entry so you can edit, archive or display QR codes for the entry.

Additional Entry Types

SeedPass supports storing more than just passwords and 2FA secrets. You can also create entries for:

SSH Key – deterministically derive an Ed25519 key pair for servers or git hosting platforms.
Seed Phrase – store only the BIP-85 index and word count. The mnemonic is regenerated on demand.
PGP Key – derive an OpenPGP key pair from your master seed.
Nostr Key Pair – store the index used to derive an npub/nsec pair for Nostr clients. When you retrieve one of these entries, SeedPass can display QR codes for the keys. The npub is wrapped in the nostr: URI scheme so any client can scan it, while the nsec QR is shown only after a security warning.
Key/Value – store a simple key and value for miscellaneous secrets or configuration data.
Managed Account – derive a child seed under the current profile. Loading a managed account switches to a nested profile and the header shows <parent_fp> > Managed Account > <child_fp>. Press Enter on the main menu to return to the parent profile.

The table below summarizes the extra fields stored for each entry type. Every entry includes a label, while only password entries track a url.

Entry Type	Extra Fields
Password	`username`, `url`, `length`, `archived`, optional `notes`, optional `custom_fields` (may include hidden fields), optional `tags`
2FA (TOTP)	`index` or `secret`, `period`, `digits`, `archived`, optional `notes`, optional `tags`
SSH Key	`index`, `archived`, optional `notes`, optional `tags`
Seed Phrase	`index`, `word_count` (mnemonic regenerated; never stored), `archived`, optional `notes`, optional `tags`
PGP Key	`index`, `key_type`, `archived`, optional `user_id`, optional `notes`, optional `tags`
Nostr Key Pair	`index`, `archived`, optional `notes`, optional `tags`
Key/Value	`key`, `value`, `archived`, optional `notes`, optional `custom_fields`, optional `tags`
Managed Account	`index`, `word_count`, `fingerprint`, `archived`, optional `notes`, optional `tags`

Managing Multiple Seeds

SeedPass allows you to manage multiple seed profiles (previously referred to as "fingerprints"). Each seed profile has its own parent seed and associated data, enabling you to compartmentalize your passwords.

Add a New Seed Profile:
1. From the main menu, select Settings then Profiles and choose "Add a New Seed Profile".
2. Choose to paste in a full seed, enter one word at a time, or generate a new seed.
3. If you enter the seed word by word, each word is hidden with * and the screen refreshes after every entry for clarity. SeedPass then shows the completed phrase for confirmation so you can fix any mistakes before it is stored.
4. If generating a new seed, you'll be provided with a 12-word BIP-85 seed phrase. Ensure you write this down and store it securely.
Switch Between Seed Profiles:
1. From the Profiles menu, select "Switch Seed Profile".
2. You'll see a list of available seed profiles.
3. Enter the number corresponding to the seed profile you wish to switch to.
4. Enter the master password associated with that seed profile.
List All Seed Profiles: In the Profiles menu, choose "List All Seed Profiles" to view all existing profiles.
Set Seed Profile Name: In the Profiles menu, choose "Set Seed Profile Name" to assign an optional label to the currently selected profile. The name is stored locally and shown alongside the fingerprint in menus.

Note: The term "seed profile" is used to represent different sets of seeds you can manage within SeedPass. This provides an intuitive way to handle multiple identities or sets of passwords.

Configuration File and Settings

SeedPass keeps per-profile settings in an encrypted file named seedpass_config.json.enc inside each profile directory under ~/.seedpass/. This file stores your chosen Nostr relays and the optional settings PIN. New profiles start with the following default relays:

wss://relay.snort.social
wss://nostr.oxtr.dev
wss://relay.primal.net

You can manage your relays and sync with Nostr from the Settings menu:

From the main menu choose 6 (Settings).
Select 2 (Nostr) to open the Nostr submenu.
Choose 1 to back up your encrypted index to Nostr.
Select 2 to restore the index from Nostr.
Choose 3 to view your current relays.
Select 4 to add a new relay URL.
Choose 5 to remove a relay by number.
Select 6 to reset to the default relay list.
Choose 7 to display your Nostr public key.
Select 8 to return to the Settings menu.

Back in the Settings menu you can:

Select 3 to change your master password.
Choose 4 to verify the script checksum.
Select 5 to generate a new script checksum.
Choose 6 to back up the parent seed.
Select 7 to export the database to an encrypted file.
Choose 8 to import a database from a backup file.
Select 9 to export all 2FA codes.
Choose 10 to set an additional backup location. A backup is created immediately after the directory is configured.
Select 11 to set the PBKDF2 iteration count used for encryption.
Choose 12 to change the inactivity timeout.
Select 13 to lock the vault and require re-entry of your password.
Select 14 to view seed profile stats. The summary lists counts for passwords, TOTP codes, SSH keys, seed phrases, and PGP keys. It also shows whether both the encrypted database and the script itself pass checksum validation.
Choose 15 to toggle Secret Mode and set the clipboard clear delay.
Select 16 to toggle Offline Mode and disable Nostr synchronization.
Choose 17 to toggle Quick Unlock for skipping the password prompt after the first unlock. Press Enter at any time to return to the main menu. You can adjust these settings directly from the command line:

seedpass config set kdf_iterations 200000
seedpass config set backup_interval 3600
seedpass config set quick_unlock true
seedpass config set nostr_max_retries 2
seedpass config set nostr_retry_delay 1

The default configuration uses 50,000 PBKDF2 iterations. Increase this value for stronger password hashing or lower it for faster startup (not recommended). Offline Mode skips all Nostr communication, keeping your data local until you re-enable syncing. Quick Unlock stores a hashed copy of your password in the encrypted config so that after the initial unlock, subsequent operations won't prompt for the password until you exit the program. Avoid enabling Quick Unlock on shared machines.

Recovery

If you previously backed up your vault to Nostr you can restore it during the initial setup. You must provide both your 12‑word master seed and the master password that encrypted the vault; without the correct password the retrieved data cannot be decrypted.

Start SeedPass and choose option 4 when prompted to set up a seed.
Paste your BIP‑85 seed phrase when asked.
Enter the master password associated with that seed.
SeedPass initializes the profile and attempts to download the encrypted vault from the configured relays.
A success message confirms the vault was restored. If no data is found a failure message is shown and a new empty vault is created.

Running Tests

SeedPass includes a small suite of unit tests located under src/tests. Before running pytest, be sure to install the test requirements. Activate your virtual environment and run pip install --require-hashes -r requirements.lock to ensure all testing dependencies are available. Then run the tests with pytest. Use -vv to see INFO-level log messages from each passing test:

pip install --require-hashes -r requirements.lock
pytest -vv

Exploring Nostr Index Size Limits

test_nostr_index_size.py demonstrates how SeedPass rotates snapshots after too many delta events. Each chunk is limited to 50 KB, so the test gradually grows the vault to observe when a new snapshot is triggered. Use the NOSTR_TEST_DELAY environment variable to control the delay between publishes when experimenting with large vaults.

pytest -vv -s -n 0 src/tests/test_nostr_index_size.py --desktop --max-entries=1000

Generating a Test Profile

Use the helper script below to populate a profile with sample entries for testing:

python scripts/generate_test_profile.py --profile demo_profile --count 100

The script determines the fingerprint from the generated seed and stores the vault under ~/.seedpass/tests/<fingerprint>. SeedPass only looks for profiles in ~/.seedpass/, so move or copy the fingerprint directory out of the tests subfolder (or adjust APP_DIR in constants.py) if you want to load it with the main application. The fingerprint is printed after creation and the encrypted index is published to Nostr. Use that same seed phrase to load SeedPass. The app checks Nostr on startup and pulls any newer snapshot so your vault stays in sync across machines. If no snapshot exists or the download cannot be decrypted (for example when using a brand-new seed), SeedPass automatically initializes an empty index instead of exiting.

Automatically Updating the Script Checksum

SeedPass stores a SHA-256 checksum for the main program in ~/.seedpass/seedpass_script_checksum.txt. To keep this value in sync with the source code, install the pre-push git hook:

pre-commit install -t pre-push

After running this command, every git push will execute scripts/update_checksum.py, updating the checksum file automatically.

If the checksum file is missing, generate it manually:

python scripts/update_checksum.py

If SeedPass prints a "script checksum mismatch" warning on startup, regenerate the checksum with seedpass util update-checksum or select "Generate Script Checksum" from the Settings menu.

To run mutation tests locally, generate coverage data first and then execute mutmut:

pytest --cov=src src/tests
python -m mutmut run --paths-to-mutate src --tests-dir src/tests --runner "python -m pytest -q" --use-coverage --no-progress
python -m mutmut results

Mutation testing is disabled in the GitHub workflow due to reliability issues and should be run on a desktop environment instead.

Development Workflow

Install all development dependencies:

pip install --require-hashes -r requirements.lock

When src/runtime_requirements.txt changes, rerun:

scripts/vendor_dependencies.sh

Commit the updated src/vendor/ directory. The application automatically adds this folder to sys.path so the bundled packages are found.

Before committing, format and test the code:

black .
pytest

Building a standalone executable

Run the vendoring script to bundle runtime dependencies:

scripts/vendor_dependencies.sh

Build the binary with PyInstaller:

pyinstaller SeedPass.spec

You can also produce packaged installers for the GUI with BeeWare's Briefcase:

briefcase build

Pre-built installers are published for each seedpass-gui tag. Visit the project's Actions or Releases page on GitHub to download the latest package for your platform.

The standalone executable will appear in the dist/ directory. This process works on Windows, macOS and Linux but you must build on each platform for a native binary.

Packaging with Briefcase

For step-by-step instructions see docs/docs/content/01-getting-started/05-briefcase.md.

Install Briefcase and create a platform-specific scaffold:

python -m pip install briefcase
briefcase create

Build and run the packaged GUI:

briefcase build
briefcase run

You can also launch the GUI directly with seedpass gui or seedpass-gui.

Security Considerations

Important: The password you use to encrypt your parent seed is also required to decrypt the seed index data retrieved from Nostr. It is imperative to remember this password and be sure to use it with the same seed, as losing it means you won't be able to access your stored index. Secure your 12-word seed and your master password.

Backup Your Data: Regularly back up your encrypted data and checksum files to prevent data loss.
Backup the Settings PIN: Your settings PIN is stored in the encrypted configuration file. Keep a copy of this file or remember the PIN, as losing it will require deleting the file and reconfiguring your relays.
Protect Your Passwords: Do not share your master password or seed phrases with anyone and ensure they are strong and unique.
Backing Up the Parent Seed: Use the CLI vault reveal-parent-seed command or the /api/v1/vault/backup-parent-seed endpoint with explicit confirmation to create an encrypted backup. The API does not return the seed directly.
No PBKDF2 Salt Needed: SeedPass deliberately omits an explicit PBKDF2 salt. Every password is derived from a unique 512-bit BIP-85 child seed, which already provides stronger per-password uniqueness than a conventional 128-bit salt.
Checksum Verification: Always verify the script's checksum to ensure its integrity and protect against unauthorized modifications.
Potential Bugs and Limitations: Be aware that the software may contain bugs and lacks certain features. Snapshot chunks are capped at 50 KB and the client rotates snapshots after enough delta events accumulate. The security of memory management and logs has not been thoroughly evaluated and may pose risks of leaking sensitive information.
Multiple Seeds Management: While managing multiple seeds adds flexibility, it also increases the responsibility to secure each seed and its associated password.
No PBKDF2 Salt Required: SeedPass deliberately omits an explicit PBKDF2 salt. Every password is derived from a unique 512-bit BIP-85 child seed, which already provides stronger per-password uniqueness than a conventional 128-bit salt.
Default KDF Iterations: New profiles start with 50,000 PBKDF2 iterations. Adjust this with seedpass config set kdf_iterations.
KDF Iteration Caution: Lowering kdf_iterations makes password cracking easier, while a high backup_interval leaves fewer recent backups.
Offline Mode: When enabled, SeedPass skips all Nostr operations so your vault stays local until syncing is turned back on.
Quick Unlock: Stores a hashed copy of your password in the encrypted config so you only need to enter it once per session. Avoid this on shared computers.
Prompt Rate Limiting: Seed and password prompts enforce a configurable attempt limit with exponential backoff to slow brute-force attacks. Adjust or disable the limit for testing via the --max-prompt-attempts CLI option or the SEEDPASS_MAX_PROMPT_ATTEMPTS environment variable.

Secure Deployment

Always deploy SeedPass behind HTTPS. Place a TLS‑terminating reverse proxy such as Nginx in front of the FastAPI server or configure Uvicorn with certificate files. Example Nginx snippet:

server {
    listen 443 ssl;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

For local testing, Uvicorn can run with TLS directly:

uvicorn seedpass.api:app --ssl-certfile=cert.pem --ssl-keyfile=key.pem

Dependency Updates

Automated dependency updates are handled by Dependabot. Every week, Dependabot checks Python packages and GitHub Actions used by this repository and opens pull requests when updates are available.

To review and merge these updates:

Review the changelog and release notes in the Dependabot pull request.

Run the test suite locally:

python3 -m venv venv
source venv/bin/activate
pip install --require-hashes -r requirements.lock
pytest

Merge the pull request once all checks pass.

A scheduled Dependency Audit workflow also runs pip-audit weekly to detect vulnerable packages. Address any reported issues promptly to keep dependencies secure.

Contributing

Contributions are welcome! If you have suggestions for improvements, bug fixes, or new features, please follow these steps:

Fork the Repository: Click the "Fork" button on the top right of the repository page.
Create a Branch: Create a new branch for your feature or bugfix.
```
git checkout -b feature/YourFeatureName
```
Commit Your Changes: Make your changes and commit them with clear messages.
```
git commit -m "Add feature X"
```
Push to GitHub: Push your changes to your forked repository.
```
git push origin feature/YourFeatureName
```
Create a Pull Request: Navigate to the original repository and create a pull request describing your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For any questions, suggestions, or support, please open an issue on the GitHub repository or contact the maintainer directly on Nostr.

Stay secure and keep your passwords safe with SeedPass!

Languages

PostScript 84.7%

Python 13.8%

HTML 0.8%

CSS 0.3%

PowerShell 0.2%

Other 0.2%

README.md Unescape Escape

SeedPass