diff --git a/README.md b/README.md index 78c8b6a..1caf1de 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![SeedPass Logo](https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/refs/heads/main/logo/png/SeedPass-Logo-03.png) -**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 ensures that your passwords are safe and accessible across devices. The index for retrieving each password is securely stored on Nostr relays, allowing seamless password recovery on multiple devices without compromising security. +**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](https://nostrtipjar.netlify.app/?n=npub16y70nhp56rwzljmr8jhrrzalsx5x495l4whlf8n8zsxww204k8eqrvamnp) @@ -10,7 +10,7 @@ **⚠️ Disclaimer** -This software was not developed by an experienced security expert and should be used with caution. There may be bugs and missing features. For instance, the maximum size of the index before the Nostr backup starts to have problems is unknown. Additionally, the security of the program's memory management and logs has not been evaluated and may leak sensitive information. +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. --- ### Supported OS @@ -42,6 +42,7 @@ SeedPass now uses the `portalocker` library for cross-platform file locking. No - **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. +- **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. - **Checksum Verification:** Ensure the integrity of the script with checksum verification. - **Multiple Seed Profiles:** Manage separate seed profiles and switch between them seamlessly. - **Interactive TUI:** Navigate through menus to add, retrieve, and modify entries as well as configure Nostr settings. @@ -112,11 +113,29 @@ SeedPass and create a backup: # Start the application python src/main.py -# Export your index using seed-only encryption -seedpass export --mode seed-only --file "~/seedpass_backup.json" +# Export your index +seedpass export --file "~/seedpass_backup.json" # Later you can restore it -seedpass import --mode seed-only --file "~/seedpass_backup.json" +seedpass import --file "~/seedpass_backup.json" +``` + +### 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. + +```json +{ + "schema_version": 2, + "entries": { + "0": { + "website": "example.com", + "length": 8, + "type": "password", + "notes": "" + } + } +} ``` @@ -155,29 +174,6 @@ python src/main.py Enter your choice (1-5): ``` -### Encryption Mode - -Use the `--encryption-mode` flag to control how SeedPass derives the key used to -encrypt your vault. Valid values are: - -- `seed-only` – default mode that derives the vault key solely from your BIP-85 - seed. -- `seed+pw` – combines the seed with your master password for key derivation. -- `pw-only` – derives the key from your password alone. - -You can set this option when launching the application: - -```bash -python src/main.py --encryption-mode seed+pw -``` - -To make the choice persistent, add it to `~/.seedpass/config.toml`: - -```toml -encryption_mode = "seed+pw" -``` - -SeedPass will read this value on startup and use the specified mode by default. ### Managing Multiple Seeds @@ -233,11 +229,23 @@ Back in the Settings menu you can: SeedPass includes a small suite of unit tests located under `src/tests`. After activating your virtual environment and installing dependencies, run the tests with **pytest**. Use `-vv` to see INFO-level log messages from each passing test: + ```bash pip install -r src/requirements.txt 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. + +```bash +NOSTR_TEST_DELAY=10 pytest -vv src/tests/test_nostr_index_size.py -m "desktop and network" +``` + ### Automatically Updating the Script Checksum SeedPass stores a SHA-256 checksum for the main program in `~/.seedpass/seedpass_script_checksum.txt`. @@ -275,7 +283,7 @@ Mutation testing is disabled in the GitHub workflow due to reliability issues an - **Protect Your Passwords:** Do not share your master password or seed phrases with anyone and ensure they are strong and unique. - **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. The maximum size of the password index before encountering issues with Nostr backups is unknown. Additionally, the security of memory management and logs has not been thoroughly evaluated and may pose risks of leaking sensitive information. +- **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. diff --git a/docs/advanced_cli.md b/docs/advanced_cli.md index 7faade5..ea5dc15 100644 --- a/docs/advanced_cli.md +++ b/docs/advanced_cli.md @@ -25,17 +25,17 @@ The **Advanced CLI Commands** document provides an in-depth guide to the various - [13. Disable Auto-Lock](#13-disable-auto-lock) - [14. Generate a Strong Password](#14-generate-a-strong-password) - [15. Verify Script Checksum](#15-verify-script-checksum) - - [16. Post Encrypted Index to Nostr](#16-post-encrypted-index-to-nostr) + - [16. Post Encrypted Snapshots to Nostr](#16-post-encrypted-snapshots-to-nostr) - [17. Retrieve from Nostr](#17-retrieve-from-nostr) - [18. Display Nostr Public Key](#18-display-nostr-public-key) - [19. Set Custom Nostr Relays](#19-set-custom-nostr-relays) - [20. Enable "Secret" Mode](#20-enable-secret-mode) - - [21. Batch Post Index Items to Nostr](#21-batch-post-index-items-to-nostr) + - [21. Batch Post Snapshot Deltas to Nostr](#21-batch-post-snapshot-deltas-to-nostr) - [22. Show All Passwords](#22-show-all-passwords) - [23. Add Notes to an Entry](#23-add-notes-to-an-entry) - [24. Add Tags to an Entry](#24-add-tags-to-an-entry) - [25. Search by Tag or Title](#25-search-by-tag-or-title) - - [26. Automatically Post Index to Nostr After Edit](#26-automatically-post-index-to-nostr-after-edit) + - [26. Automatically Post Deltas to Nostr After Edit](#26-automatically-post-deltas-to-nostr-after-edit) - [27. Initial Setup Prompt for Seed Generation/Import](#27-initial-setup-prompt-for-seed-generationimport) 3. [Notes on New CLI Commands](#notes-on-new-cli-commands) @@ -62,17 +62,17 @@ The following table provides a quick reference to all available advanced CLI com | Disable auto-lock | `autolock --disable` | `-DL` | `--auto-lock --disable` | `seedpass autolock --disable` | | Generate a strong password | `generate` | `-G` | `--generate` | `seedpass generate --length 20` | | Verify script checksum | `verify` | `-V` | `--verify` | `seedpass verify` | -| Post encrypted index to Nostr | `post` | `-P` | `--post` | `seedpass post` | -| Retrieve from Nostr | `get-nostr` | `-GN` | `--get-nostr` | `seedpass get-nostr` | +| Post encrypted snapshots to Nostr | `post` | `-P` | `--post` | `seedpass post` | +| Retrieve snapshots from Nostr | `get-nostr` | `-GN` | `--get-nostr` | `seedpass get-nostr` | | Display Nostr public key | `show-pubkey` | `-K` | `--show-pubkey` | `seedpass show-pubkey` | | Set Custom Nostr Relays | `set-relays` | `-SR` | `--set-relays` | `seedpass set-relays --add "wss://relay1.example.com" --add "wss://relay2.example.com"` | | Enable "Secret" Mode | `set-secret` | `-SS` | `--set-secret` | `seedpass set-secret --enable` or `seedpass set-secret --disable` | -| Batch Post Index Items to Nostr | `batch-post` | `-BP` | `--batch-post` | `seedpass batch-post --start 0 --end 9` or `seedpass batch-post --range 10-19` | +| Batch Post Snapshot Deltas to Nostr | `batch-post` | `-BP` | `--batch-post` | `seedpass batch-post --start 0 --end 9` or `seedpass batch-post --range 10-19` | | Show All Passwords | `show-all` | `-SA` | `--show-all` | `seedpass show-all` | | Add Notes to an Entry | `add-notes` | `-AN` | `--add-notes` | `seedpass add-notes --index 3 --notes "This is a secured account"` | | Add Tags to an Entry | `add-tags` | `-AT` | `--add-tags` | `seedpass add-tags --index 3 --tags "personal,finance"` | | Search by Tag or Title | `search-by` | `-SB` | `--search-by` | `seedpass search-by --tag "work"` or `seedpass search-by --title "GitHub"` | -| Automatically Post Index to Nostr After Edit | `auto-post` | `-AP` | `--auto-post` | `seedpass auto-post --enable` or `seedpass auto-post --disable` | +| Automatically Post Deltas After Edit | `auto-post` | `-AP` | `--auto-post` | `seedpass auto-post --enable` or `seedpass auto-post --disable` | | Initial Setup Prompt for Seed Generation/Import | `setup` | `-ST` | `--setup` | `seedpass setup` | --- @@ -219,23 +219,6 @@ seedpass export --file "backup_passwords.json" **Options:** - `--file` (`-F`): The destination file path for the exported data. If omitted, the export is saved to the current profile's `exports` directory under `~/.seedpass//exports/`. -- `--mode` (`-M`): Choose the encryption mode for the exported file. Valid values are: - `seed-only`, `seed+pw`, `pw-only`, and `plaintext`. - -**Examples:** -```bash -# Standard encrypted export -seedpass export --mode seed-only --file "backup.json" -# Combine seed and master password for the export key -seedpass export --mode seed+pw --file "backup.json" -# Derive the key solely from your password -seedpass export --mode pw-only --file "backup.json" -# Plaintext JSON export (not recommended) -seedpass export --mode plaintext --file "backup.json" -``` - -**Warning:** The `plaintext` mode writes an unencrypted index to disk. Only use it -for debugging and delete the file immediately after use. --- @@ -255,15 +238,6 @@ seedpass import --file "backup_passwords.json" **Options:** - `--file` (`-F`): The source file path containing the password entries to import. -- `--mode` (`-M`): Indicates the encryption mode used when the file was exported. Accepted values are `seed-only`, `seed+pw`, `pw-only`, and `plaintext`. - -**Examples:** -```bash -# Import a standard encrypted backup -seedpass import --mode seed-only --file "backup.json" -# Import a backup that also used the master password -seedpass import --mode seed+pw --file "backup.json" -``` --- @@ -389,14 +363,14 @@ seedpass verify --- -### 16. Post Encrypted Index to Nostr +### 16. Post Encrypted Snapshots to Nostr **Command:** `post` **Short Flag:** `-P` **Long Flag:** `--post` **Description:** -Posts the encrypted password index to the Nostr network, facilitating secure backups and synchronization across devices. +Posts encrypted snapshot chunks of the index to the Nostr network, followed by compact delta events for subsequent changes. This approach enables reliable backups and efficient synchronization across devices. **Usage Example:** ```bash @@ -412,7 +386,7 @@ seedpass post **Long Flag:** `--get-nostr` **Description:** -Retrieves the encrypted password index from the Nostr network, allowing users to restore their password data on a new device. +Retrieves the encrypted snapshot chunks and any delta events from the Nostr network, allowing users to reconstruct the latest index on a new device. **Usage Example:** ```bash @@ -444,7 +418,7 @@ seedpass show-pubkey **Long Flag:** `--set-relays` **Description:** -Allows users to specify custom Nostr relays for publishing their encrypted backup index, providing flexibility and control over data distribution. +Allows users to specify custom Nostr relays for publishing their encrypted backup snapshots, providing flexibility and control over data distribution. Relay URLs are stored in an encrypted configuration file located in `~/.seedpass//seedpass_config.json.enc` and loaded each time the Nostr client starts. New accounts use the following default relays until changed: ``` @@ -484,14 +458,14 @@ seedpass set-secret --disable --- -### 21. Batch Post Index Items to Nostr +### 21. Batch Post Snapshot Deltas to Nostr **Command:** `batch-post` **Short Flag:** `-BP` **Long Flag:** `--batch-post` **Description:** -Posts a specified range of index items to the Nostr network in batches, ensuring efficient and manageable data transmission. +Posts a specified range of snapshot delta events to the Nostr network in batches, ensuring efficient and manageable data transmission. **Usage Examples:** ```bash @@ -583,14 +557,14 @@ seedpass search-by --title "GitHub" --- -### 26. Automatically Post Index to Nostr After Edit +### 26. Automatically Post Deltas to Nostr After Edit **Command:** `auto-post` **Short Flag:** `-AP` **Long Flag:** `--auto-post` **Description:** -Enables or disables the automatic posting of the password index to the Nostr network whenever an edit occurs, ensuring real-time backups. +Enables or disables the automatic posting of snapshot delta events to the Nostr network whenever an edit occurs, ensuring real-time backups. **Usage Examples:** ```bash @@ -621,7 +595,7 @@ seedpass setup **Features to Implement:** - **Seed Choice Prompt:** Asks users whether they want to generate a new seed or import an existing one. - **Encryption of Seed:** Uses the user-selected password to encrypt the seed, whether generated or imported. -- **Profile Creation:** Upon first login, automatically generates a profile and checks for existing index data notes that can be pulled and decrypted. +- **Profile Creation:** Upon first login, automatically generates a profile and checks for existing snapshot data that can be pulled and decrypted. --- @@ -782,8 +756,8 @@ seedpass fingerprint rename A1B2C3D4 PersonalProfile ## Notes on New CLI Commands -1. **Automatically Post Index to Nostr After Edit (`auto-post`):** - - **Purpose:** Enables or disables the automatic posting of the index to Nostr whenever an edit occurs. +1. **Automatically Post Deltas to Nostr After Edit (`auto-post`):** + - **Purpose:** Enables or disables the automatic posting of snapshot deltas to Nostr whenever an edit occurs. - **Usage Examples:** - Enable auto-post: `seedpass auto-post --enable` - Disable auto-post: `seedpass auto-post --disable` @@ -793,7 +767,7 @@ seedpass fingerprint rename A1B2C3D4 PersonalProfile - **Features to Implement:** - **Seed Choice Prompt:** Ask users whether they want to generate a new seed or import an existing one. - **Encryption of Seed:** Use the user-selected password to encrypt the seed, whether generated or imported. - - **Profile Creation:** Upon first login, automatically generate a profile and check for existing index data notes that can be pulled and decrypted. + - **Profile Creation:** Upon first login, automatically generate a profile and check for existing snapshot data that can be pulled and decrypted. - **Usage Example:** `seedpass setup` 3. **Advanced CLI Enhancements:** @@ -807,8 +781,8 @@ seedpass fingerprint rename A1B2C3D4 PersonalProfile - **Description:** When running `seedpass setup`, prompts users to either enter an existing seed or generate a new one, followed by password creation for encryption. - **Usage Example:** `seedpass setup` - - **Automatic Profile Generation and Index Retrieval:** - - **Description:** During the initial setup or first login, generates a profile and attempts to retrieve and decrypt any existing index data from Nostr. + - **Automatic Profile Generation and Snapshot Retrieval:** + - **Description:** During the initial setup or first login, generates a profile and attempts to retrieve and decrypt any existing snapshots and deltas from Nostr. - **Usage Example:** `seedpass setup` (handles internally) --- diff --git a/docs/json_entries.md b/docs/json_entries.md index d2bf840..1225f90 100644 --- a/docs/json_entries.md +++ b/docs/json_entries.md @@ -29,7 +29,27 @@ ## Introduction -**SeedPass** is a secure password generator and manager leveraging **Bitcoin's BIP-85 standard** and integrating with the **Nostr network** for decentralized synchronization. To enhance modularity, scalability, and security, SeedPass now manages each password or data entry as a separate JSON file within a **Fingerprint-Based Backup and Local Storage** system. This document outlines the new entry management system, ensuring that new `kind` types can be added seamlessly without disrupting existing functionalities. +**SeedPass** is a secure password generator and manager leveraging **Bitcoin's BIP-85 standard** and integrating with the **Nostr network** for decentralized synchronization. Instead of pushing one large index file, SeedPass posts **snapshot chunks** of the index followed by lightweight **delta events** whenever changes occur. This chunked approach improves reliability and keeps bandwidth usage minimal. To enhance modularity, scalability, and security, SeedPass now manages each password or data entry as a separate JSON file within a **Fingerprint-Based Backup and Local Storage** system. This document outlines the new entry management system, ensuring that new `kind` types can be added seamlessly without disrupting existing functionalities. + +--- + +## Index File Format + +All entries belonging to a seed profile are summarized in an encrypted file named `seedpass_entries_db.json.enc`. This index starts with `schema_version` `2` and contains an `entries` object keyed by entry numbers. + +```json +{ + "schema_version": 2, + "entries": { + "0": { + "website": "example.com", + "length": 8, + "type": "password", + "notes": "" + } + } +} +``` --- @@ -444,9 +464,8 @@ All backups are organized based on fingerprints, ensuring that each seed's data │ │ ├── entry_1_v1.json │ │ └── ... │ ├── parent_seed.enc -│ ├── seedpass_passwords_checksum.txt -│ ├── seedpass_passwords_db_checksum.txt -│ └── seedpass_passwords_db.json +│ ├── seedpass_entries_db_checksum.txt +│ └── seedpass_entries_db.json ├── b5c6d7e8/ │ ├── entries/ │ │ ├── entry_0.json @@ -458,9 +477,8 @@ All backups are organized based on fingerprints, ensuring that each seed's data │ │ ├── entry_1_v1.json │ │ └── ... │ ├── parent_seed.enc -│ ├── seedpass_passwords_checksum.txt -│ ├── seedpass_passwords_db_checksum.txt -│ └── seedpass_passwords_db.json +│ ├── seedpass_entries_db_checksum.txt +│ └── seedpass_entries_db.json └── ... ``` @@ -498,9 +516,9 @@ seedpass rollback --fingerprint a1b2c3d4 --file entry_0_v1.json │ │ ├── entry_1_v1.json │ │ └── ... │ ├── parent_seed.enc -│ ├── seedpass_passwords_checksum.txt -│ ├── seedpass_passwords_db_checksum.txt -│ └── seedpass_passwords_db.json +│ ├── seedpass_script_checksum.txt +│ ├── seedpass_entries_db_checksum.txt +│ └── seedpass_entries_db.json ├── ... ``` diff --git a/examples/entry_management_demo.py b/examples/entry_management_demo.py index cebfeae..030187d 100644 --- a/examples/entry_management_demo.py +++ b/examples/entry_management_demo.py @@ -4,10 +4,12 @@ from cryptography.fernet import Fernet from password_manager.encryption import EncryptionManager from password_manager.vault import Vault from password_manager.entry_management import EntryManager +from constants import initialize_app def main() -> None: """Demonstrate basic EntryManager usage.""" + initialize_app() key = Fernet.generate_key() enc = EncryptionManager(key, Path(".")) vault = Vault(enc, Path(".")) diff --git a/examples/password_manager_demo.py b/examples/password_manager_demo.py index 7796191..27da95f 100644 --- a/examples/password_manager_demo.py +++ b/examples/password_manager_demo.py @@ -1,9 +1,11 @@ from password_manager.manager import PasswordManager from nostr.client import NostrClient +from constants import initialize_app def main() -> None: """Show how to initialise PasswordManager with Nostr support.""" + initialize_app() manager = PasswordManager() manager.nostr_client = NostrClient(encryption_manager=manager.encryption_manager) # Sample actions could be called on ``manager`` here. diff --git a/landing/index.html b/landing/index.html index 80968f0..16e87b3 100644 --- a/landing/index.html +++ b/landing/index.html @@ -53,7 +53,7 @@

SeedPass: Secure Password Manager

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 ensures that your passwords are safe and accessible across devices.

+

By integrating with the Nostr network, SeedPass compresses your encrypted vault and publishes it in 50 KB chunks. Each chunk is sent as a parameterised replaceable event, with deltas tracking changes between snapshots and automatic rotation when deltas grow large.

Get Started
@@ -64,7 +64,7 @@