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

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