# One Seed to Rule Them All

SeedPass deterministically derives every key and password from a single 12‑word phrase.

    ---
    config:
      theme: base
      themeVariables:
        primaryColor: '#e94a39'
        primaryBorderColor: '#e94a39'
        lineColor: '#e94a39'
      look: classic
    ---
    flowchart TB
        seed["alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima"]
        seed --> pw["🔑 Passwords"]
        seed --> totp["📱 2FA Codes"]
        seed --> ssh["🖧 SSH Keys"]
        seed --> pgp["🔒 PGP Key"]
        seed --> mn["🌱 Seed Phrase"]
        seed --> nostr["⚡ Nostr Keys"]
        seed --> kv["🔑 Key/Value"]
        seed --> ma["👥 Managed Account"]
        classDef default fill:#ffffff,stroke:#e94a39,stroke-width:2px,color:#283c4f;

Get Started

## Architecture Overview

    ---
    config:
      layout: fixed
      theme: base
      themeVariables:
        primaryColor: '#e94a39'
        primaryBorderColor: '#e94a39'
        lineColor: '#e94a39'
      look: classic
    ---
    graph TD
        core(seedpass.core)
        cli(CLI/TUI)
        gui(BeeWare GUI)
        ext(Browser extension)
        cli --> core
        gui --> core
        ext --> core

    ---
    config:
      layout: fixed
      theme: base
      themeVariables:
        primaryColor: '#e94a39'
        primaryBorderColor: '#e94a39'
        primaryTextColor: '#ffffff'
        lineColor: '#e94a39'
      look: classic
    ---
    flowchart TD
     subgraph subGraph0["Local Storage"]
        direction TB
            V["Vault
    (password_manager.Vault)
    • encrypted index
    • config"]
      end
     subgraph subGraph1["Backup Pipeline"]
        direction TB
            BK1["Timestamped Backups
    (BackupManager)"]
            BK2["Portable Backup
    (portable_backup.py)
    .json.enc"]
            BK3["Nostr Snapshot
    (nostr.client)
    gzip chunks"]
      end
     subgraph Restore["Restore"]
        direction TB
            R1["Local Backup File"]
            R2["Nostr Snapshot"]
            R3["Portable Backup"]
            R4["Vault Restore
    (Vault / BackupManager)"]
      end
        A["Parent Seed
    (BIP-39 Mnemonic)"] --> B["Seed Bytes
    (BIP-39 → 512-bit)"]
        B --> C["BIP-85 Derivation
    (local_bip85.BIP85)"]
        C --> D1["Password Entropy
    (password_generation)"] & D2["TOTP Secret
    (utils.key_derivation.derive_totp_secret)"] & D3["SSH Key Entropy
    (password_generation.derive_ssh_key)"] & D4["PGP Key Entropy
    (entry_management.add_pgp_key)"] & D5["Child Mnemonic
    (BIP-85 derive_mnemonic)"] & D6["Nostr Key Entropy
    (nostr.KeyManager)"] & D7["Key/Value Data
    (entry_management.add_key_value)"] & D8["Managed Account Seed
    (entry_management.add_managed_account)"]
        D1 --> E1["Passwords"]
        D2 --> E2["2FA Codes"]
        D3 --> E3["SSH Key Pair"]
        D4 --> E4["PGP Key"]
        D5 --> E5["Seed Phrase"]
        D6 --> E6["Nostr Keys
    (npub / nsec)"]
        D7 --> E7["Key/Value"]
        D8 --> E8["Managed Account"]
        E1 --> V
        E2 --> V
        E3 --> V
        E4 --> V
        E5 --> V
        E6 --> V
        V --> BK1 & BK2 & BK3
        R1 --> R4
        R2 --> R4
        R3 --> R4
        R4 --> V
        A -. "Same seed ⇒ re-derive any artifact on demand" .- E1
        A -.-> E2 & E3 & E4 & E5 & E6 & E7 & E8

## Features

- Deterministic password generation using BIP-85
- Encrypted local storage for seeds and sensitive data
- Nostr relay integration with parameterised replaceable events for chunked snapshots and deltas
- Seed/Fingerprint switching for managing multiple profiles
- Checksum verification to ensure script integrity
- Interactive TUI for managing entries and settings
- Issue or import TOTP secrets for 2FA
- Store arbitrary secrets as key/value pairs
- Export your 2FA codes to an encrypted file
- Optional external backup location
- Auto-lock after inactivity
- Derive nested managed account seeds
- Secret Mode copies passwords to your clipboard
- Group entries using tags for easy cross-type search

## How SeedPass Works

SeedPass uses Bitcoin's BIP-85 standard for deterministic password generation. This means your passwords are not stored but can be regenerated using your master seed and specific indices.

### BIP-85 Derivation Tree

The BIP-85 standard allows you to derive multiple child seeds from a single master seed. Each child seed can then be used to generate secure passwords. Here's a simplified illustration:

    Master_Seed
    ├── Child_Seed_0
    │   └── Password_A
    ├── Child_Seed_1
    │   └── Password_B
    ├── Child_Seed_2
    │   └── Password_C
    └── ...

### Seed/Fingerprint Switching

SeedPass allows you to manage multiple seed profiles (fingerprints). You can switch between different seeds to compartmentalize your passwords.

### Nostr Relay Integration

SeedPass publishes your encrypted vault to Nostr in 50 KB chunks using parameterised replaceable events. A manifest describes each snapshot while deltas record updates. When too many deltas accumulate, a new snapshot is rotated in automatically.

### Checksum Verification

Built-in checksum verification ensures your SeedPass installation hasn't been tampered with.

### Interactive TUI

Navigate through menus to manage entries and settings. Example:

    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:

### Secret Mode

When Secret Mode is enabled, retrieved passwords are copied directly to your clipboard instead of displayed. The clipboard clears automatically after a delay you set.

## Disclaimer

⚠️ Disclaimer: This software was not developed by an experienced security expert and should be used with caution. There may be bugs and missing features. Additionally, 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.

Snapshot chunks are limited to 50 KB and rotated when deltas accumulate.