Vault Recovery

What each vault file is for, and what to do when something goes wrong. See also ARCHITECTURE.md for how the app avoids getting into a bad state in the first place.

Vault File Structure

my-vault/
├── .driftleaf/
│   ├── vault.json     format version + scrypt salt (or the raw key, for
│   │                  passphrase-less vaults) — never the derived key itself
│   ├── canary.enc      known-plaintext blob used to check a passphrase on unlock
│   ├── manifest.enc    encrypted index of note, folder, database, extension, and canvas metadata
│   ├── notes/
│   │   └── <note-id>.enc  encrypted note content under an opaque filename
│   └── <database-id>.db.enc  encrypted database schema and rows

Note content and vault metadata (including titles, folder placement, timestamps, database IDs, extension code and permissions, and canvas layout) are encrypted. Note files use opaque IDs under .driftleaf/notes/, so filenames do not expose note titles. Database property definitions, formulas, rows, and saved views are stored in encrypted .driftleaf/<database-id>.db.enc files. Existing vaults migrate their legacy plaintext manifest and named note files on successful unlock; empty legacy folders are removed, while directories containing unrelated files are left untouched.

"My Vault Won't Open"

1. Wrong passphrase — the app tells you this directly; retry carefully. There's no passphrase reset (see below).
2. vault.json or canary.enc missing/corrupted — these hold key material and the passphrase check; they can't be reconstructed. Restore the .driftleaf/ folder from a backup. Without a backup, encrypted vault data cannot be opened.
3. manifest.enc missing/corrupted — note and database files may remain on disk, but their encrypted titles, folder locations, and other metadata cannot be reconstructed from opaque IDs. Do not delete the manifest or create a new vault over the files. Restore manifest.enc or, preferably, the entire .driftleaf/ directory from a backup.

"A Note Won't Open" / "This Note Is Corrupted"

AES-GCM authenticates ciphertext, so any bit-flip or truncation of a .enc file is detected on read rather than silently returning garbage. If you see this error:

• Check whether you have a backup of the vault folder from before the corruption, and restore just that note's .driftleaf/notes/<note-id>.enc file.
• If not, the note's content is unrecoverable, but it won't affect any other note — corruption is detected per-file, not vault-wide.

Crash / Power Loss Mid-Save

Driftleaf writes are structured to avoid this class of problem:

• Every file write (note content, manifest) goes to a temp file and lands via an atomic rename, so a crash mid-write can't leave a half-written file.
• Every unlock runs a reconciliation pass that checks manifest entries against note files and migrates supported legacy files. Stale entries for missing files are removed. Orphaned ciphertext may be recovered with placeholder metadata, but opaque IDs cannot restore the original title or folder. You'll see a toast summarizing supported recovery actions.

Atomic writes and reconciliation reduce the chance of partial saves, but they are not a substitute for backups. A crash that leaves orphaned ciphertext can preserve its contents without preserving its title or folder metadata. See Architecture for the storage and recovery design.

Passphrase Recovery

None, by design — the passphrase (or the derived key) is never stored anywhere, including by Driftleaf's developers. If you lose it, encrypted note and database contents and metadata cannot be recovered.

Recommendation: write your passphrase down somewhere durable (a password manager, a physical note in a safe place) at vault creation, and keep a backup of the vault folder somewhere separate from this device.

Backing Up Your Vault

Create a copy from Settings → Diagnostics & Vault Health → Create backup. Choose a destination outside the vault; Driftleaf creates a uniquely named, dated folder there and does not overwrite existing backups. The copy includes the hidden .driftleaf/ directory. Keep the destination on a different drive or device for protection against device failure.

After copying, verify the backup from Settings → Diagnostics & Vault Health → Choose backup folder. Driftleaf checks the backup's key-check file, manifest, encrypted note files, and encrypted databases. Enter the passphrase if the backup uses one. Verification is read-only: it does not unlock the backup as the active vault, reconcile its files, or change it.

The same Settings screen can run a health check on the currently open vault. It checks vault metadata, manifest consistency, encrypted note and database integrity, recoverable unindexed files, leftover temporary writes, and search-index coverage. It reports issues without attempting repairs; unlock-time reconciliation repairs supported note manifest/file mismatches. Database files missing from the manifest are reported as unindexed but are not automatically recovered.

Copy Diagnostics in that screen copies app/platform and display-session details plus the active theme. It does not include vault paths, note contents, or passphrases.

The vault is just a folder — a backup can also be made manually by copying my-vault/ (including the hidden .driftleaf/ directory) to an external drive or another machine.

Imported Databases

Databases created in Driftleaf or imported from CSV and JSON are encrypted and stored inside .driftleaf/. Include the entire .driftleaf/ directory when backing up; it contains the encrypted manifest, note files, and database data. For supported import formats, views, formulas, export, and known Notion-export limitations, see Databases.