SeedPass

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.

graph TD
    core(seedpass.core)
    cli(CLI/TUI)
    gui(BeeWare GUI)
    ext(Browser extension)
    cli --> core
    gui --> core
    ext --> core

SeedPass uses a modular design with a single core library that handles all security-critical logic. The current CLI/TUI adapter communicates with seedpass.core, and future interfaces like a BeeWare GUI and a browser extension can hook into the same layer. This architecture keeps the codebase maintainable while enabling a consistent experience on multiple platforms.

Table of Contents

Features

Prerequisites

Installation

Quick Installer

Use the automated installer to download SeedPass and its dependencies in one step. If GTK packages are missing, the installer will try to install them using your system's package manager (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

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))

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.

Installer Dependency Checks

The installer verifies that core build tooling—C/C++ build tools, Rust, CMake, and the imaging/GTK libraries—are available before completing. Pass --no-gui to skip installing GUI packages. On Linux, ensure xclip or wl-clipboard is installed for clipboard support.

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 the script warns that it couldn't remove an executable, delete that 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))

Install the beta branch:

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)) -Branch beta

Manual Setup

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

1. Clone the Repository

First, clone the SeedPass repository from GitHub:

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

Navigate to the project directory:

cd SeedPass

2. Create a Virtual Environment

It's recommended to use a virtual environment to manage your project's dependencies. Create a virtual environment named venv:

python3 -m venv venv

3. Activate the Virtual Environment

Activate the virtual environment using the appropriate command for your operating system.

Once activated, your terminal prompt should be prefixed with (venv) indicating that the virtual environment is active.

4. Install Dependencies

Install the required Python packages and build dependencies using pip. When upgrading pip, use python -m pip inside the virtual environment so that pip can update itself cleanly:

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

Linux Clipboard Support

On Linux, pyperclip relies on external utilities like xclip or xsel. SeedPass does not install these tools automatically. To use clipboard features such as secret mode, install xclip manually:

sudo apt install xclip

After installing xclip, restart SeedPass to enable clipboard support.

Quick Start

After installing dependencies, activate your virtual environment and install the package so the seedpass command is available, then launch SeedPass and create a backup:

# Start the application
seedpass

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

# Later you can restore it
seedpass vault import --file "~/seedpass_backup.json"
# Import also performs a Nostr sync to pull any changes

# 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

# 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.

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": ""
    }
  }
}

Usage

After successfully installing the dependencies, launch the interactive TUI with:

seedpass

You can also run directly from the repository using:

python src/main.py

You can explore other CLI commands using:

seedpass --help

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

Running the Application

  1. Start the Application:

    seedpass

    (or python src/main.py if running directly from the repository)

  2. 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:

Adding a Password Entry

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

  1. Quick – enter only a label, username, URL, desired length, and whether to include special characters. All other fields use defaults.
  2. Advanced – continue through prompts for notes, tags, custom fields, and detailed password policy settings.

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

  1. From the main menu choose Add Entry and select 2FA (TOTP).
  2. Pick Make 2FA to derive a new secret from your seed or Import 2FA to paste an existing otpauth:// URI or secret.
  3. Provide a label for the account (for example, GitHub).
  4. SeedPass automatically chooses the next available derivation index when deriving.
  5. Optionally specify the TOTP period and digit count.
  6. 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

  1. From the main menu choose Modify an Existing Entry and enter the index of the 2FA code you want to edit.
  2. SeedPass will show the current label, period, digit count, and archived status.
  3. Enter new values or press Enter to keep the existing settings.
  4. When retrieving a 2FA entry you can press E to edit the label, period or digit count, or A to archive/unarchive it.
  5. The updated entry is saved back to your encrypted vault.
  6. Archived entries are hidden from lists but can be viewed or restored from the List Archived menu.
  7. 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 retrieved passwords directly to your clipboard instead of displaying them on screen. The clipboard clears automatically after the delay you choose.

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

Additional Entry Types

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

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.

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.

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.

  1. Start SeedPass and choose option 4 when prompted to set up a seed.
  2. Paste your BIP‑85 seed phrase when asked.
  3. Enter the master password associated with that seed.
  4. SeedPass initializes the profile and attempts to download the encrypted vault from the configured relays.
  5. 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.

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:

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

Back in the Settings menu you can:

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

test_fuzz_key_derivation.py uses Hypothesis to generate random passwords, seeds and configuration data. It performs round-trip encryption tests with the EncryptionManager to catch edge cases automatically. These fuzz tests run in CI alongside the rest of the suite.

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 discovers profiles inside ~/.seedpass/, so copy the fingerprint directory out of the tests subfolder (or adjust APP_DIR in constants.py) if you want to use the generated seed 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. Synchronization also runs in the background after unlocking or when switching profiles.

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 reports 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.

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.

Contributing

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

  1. Fork the Repository: Click the "Fork" button on the top right of the repository page.

  2. Create a Branch: Create a new branch for your feature or bugfix.

    git checkout -b feature/YourFeatureName

  3. Commit Your Changes: Make your changes and commit them with clear messages.

    git commit -m "Add feature X"

  4. Push to GitHub: Push your changes to your forked repository.

    git push origin feature/YourFeatureName

  5. 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!