thePR0M3TH3AN/seedPass
1
0
Fork 0
mirror of https://github.com/PR0M3TH3AN/SeedPass.git synced 2025-09-08 07:18:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
90c304ff6e79002b168c7d669fc977dd760ee821
seedPass/docs/docs/content/01-getting-started/04-migrations.md
thePR0M3TH3AN 6a20728db4 docs: note deterministic derivation change
2025-08-05 10:55:56 -04:00

2.3 KiB
Raw Blame History

Index Migrations

SeedPass stores its password index in an encrypted JSON file. Each index contains a schema_version field so the application knows how to upgrade older files.

Note: Recent releases derive passwords and other artifacts using a new deterministic algorithm that works consistently across Python versions. Artifacts produced with older versions will not match outputs from this release and must be regenerated.

How migrations work

When the vault loads the index, Vault.load_index() checks the version and applies migrations defined in password_manager/migrations.py. The apply_migrations() function iterates through registered migrations until the file reaches LATEST_VERSION.

If an old file lacks schema_version, it is treated as version 0 and upgraded to the latest format. Attempting to load an index from a future version will raise an error.

Upgrading an index

  1. The JSON is decrypted and parsed.
  2. apply_migrations() applies any necessary steps, such as injecting the schema_version field on first upgrade.
  3. After migration, the updated index is saved back to disk.

This process happens automatically; users only need to open their vault to upgrade older indices.

Legacy Fernet migration

Older versions stored the vault index in a file named seedpass_passwords_db.json.enc encrypted with Fernet. When opening such a vault, SeedPass now automatically decrypts the legacy file, re‑encrypts it using AES‑GCM, and saves it under the new name seedpass_entries_db.json.enc. The original Fernet file is preserved as seedpass_entries_db.json.enc.fernet and the legacy checksum file, if present, is renamed to seedpass_entries_db_checksum.txt.fernet.

No additional command is required – simply open your existing vault and the conversion happens transparently.

Parent seed backup migration

If your vault contains a parent_seed.enc file that was encrypted with Fernet, SeedPass performs a similar upgrade. Upon loading the vault, the application decrypts the old file, re‑encrypts it with AES‑GCM, and writes the result back to parent_seed.enc. The legacy Fernet file is preserved as parent_seed.enc.fernet so you can revert if needed. No manual steps are required – simply unlock your vault and the conversion runs automatically.