relicario/docs/superpowers/specs/2026-04-27-relicario-import-export-design.md

Relicario import / export — design

Date: 2026-04-27 Status: design (not yet implemented) Scope: backup / restore (round-trippable to Relicario itself) + LastPass CSV import. Migration out to other tools is explicitly out of scope.

Motivation

Self-hosting a password vault without a backup story is unacceptable for production use. Today, a Relicario user has no way to:

1. Snapshot their vault for disaster recovery (git remote going away, repo corruption, account loss).
2. Onboard from an existing manager — there's no migration path for a user with credentials in another tool.

This design adds both, with parity across CLI and the fullscreen vault tab in the browser extension. The popup UI is unchanged (these are heavyweight workflows that don't fit the popup).

Decisions

The following choices were brainstormed and approved before this spec was written. They are stated as decisions, not options.

#	Decision
D1	Two features, one spec: backup/restore round-trippable to Relicario, plus a LastPass CSV importer. Migration out is out of scope.
D2	Backup file format: single-file .relbak container. Magic header + version + salt + nonce + AEAD-encrypted, zstd-compressed JSON envelope with base64'd binary blobs.
D3	AEAD: XChaCha20-Poly1305 (same primitive used for vault items, but the backup format uses its own envelope with magic header + version byte; it does not reuse the crypto.rs encrypt/decrypt helpers, which assume the vault-master-key format). KDF: Argon2id with the same parameters as v1 of the live vault (m=64MiB, t=3, p=4) — but the params are tied to backup format version, not read from the vault's params.json.
D4	Backup passphrase is independent of the vault passphrase. User picks one at export; user types it at restore. Reusing the vault passphrase is allowed but not auto-filled.
D5	Reference image inclusion is optional. --include-image flag (CLI) / checkbox (UI). When included, the image is base64'd into the encrypted envelope — never in the clear inside the file.
D6	Git history (.git/) is included by default. --no-history opt-out for users who want a smaller file at the cost of audit trail and remote URL.
D7	Restore semantics: refuse if the target directory already contains a Relicario vault. Restore is a fresh round-trip operation, not a merge.
D8	Backup passphrase strength: zxcvbn score ≥ 3, same gate as init. Backup is single-factor (one passphrase decrypts the container), so it must be at least as strong as a vault factor.
D9	The user is responsible for deleting the backup file after restore is verified. The encryption protects it in transit / at rest while it exists; it is not a defense against forensic recovery of deleted copies. Documented in CLI help text and the extension UI.
D10	LastPass import: parse the standard LastPass CSV (url,username,password,totp,extra,name,grouping,fav). Logins → Login items (with embedded TOTP if present); rows with url == http://sn → SecureNote; structured LastPass notes (cards, SSH keys, addresses) are not auto-parsed — they fall through as SecureNote with extra as the body.
D11	Failed CSV rows are skipped with a warning; the import continues. CLI exits 0 if at least one item was imported.
D12	Imported items always create new IDs, even if the name collides with an existing item. Relicario does not enforce title uniqueness; collisions are harmless.
D13	An import is committed in one git commit covering all newly written items + the manifest. Mid-import crashes leave orphan item files (no manifest reference); safe to retry.
D14	UI placement: CLI commands + fullscreen vault tab UI (vault.html) only. Popup is not touched.

Architecture

Three new modules. The bulk of the logic lives in relicario-core so CLI and extension share it.

relicario-core (new code, ~250 LOC + tests)

• backup.rs — pack_backup(...) and unpack_backup(...). Pure, bytes-in / bytes-out (no filesystem). Owns the JSON envelope schema, zstd compression, AEAD encryption, magic header, format-version handling.
• import_lastpass.rs — parse_lastpass_csv(bytes) -> Result<(Vec<Item>, Vec<ImportWarning>)>. Pure: takes CSV bytes, returns relicario Items with freshly-minted IDs. Failed rows → ImportWarning entries alongside the items.

relicario-cli (new commands)

• relicario export <out.relbak> [--include-image] [--image <path>] [--no-history]
  • Reads vault root → packs → encrypts (prompts for backup passphrase, with confirmation + zxcvbn gate) → writes file with atomic_write.
  • Does not require vault unlock. The backup container key is independent.
• relicario restore <in.relbak> [<target_dir>]
  • target_dir defaults to current directory.
  • Refuses if target_dir/.relicario exists.
  • Prompts for backup passphrase → decrypts → unpacks → writes vault layout into target → if .git/ was bundled, untar; otherwise git init + initial commit "restore from backup <utc-timestamp>".
  • User then unlocks normally with vault passphrase + reference image.
• relicario import lastpass <csv>
  • Requires unlock.
  • Parses CSV → encrypts each Item under master key → writes items/<id>.enc files → updates manifest in-memory → saves manifest last (the single commit point) → one git commit.
  • Prints summary; exits 0 on partial success.

relicario-wasm (new exports)

• pack_backup_json(vault_state_json: &str, passphrase: &str) -> Vec<u8> — thin wrapper around core::pack_backup. Takes a JSON description of vault state (the SW assembles it from chrome.storage / git fetches), returns the .relbak bytes.
• unpack_backup_json(bytes: &[u8], passphrase: &str) -> String — JSON-encoded inverse.
• parse_lastpass_csv_json(csv_bytes: &[u8]) -> String — JSON-encoded (items, warnings) tuple, ready for the SW to iterate via existing add_item calls.

Extension (vault tab vault.html only — popup unchanged)

• New "Backup & restore" panel under settings (vault tab):
  • Export backup — passphrase modal (with zxcvbn meter) → chrome.downloads.download(blobUrl, "relicario-backup.relbak").
  • Restore from backup — file picker → passphrase modal → confirms target is empty → restores via SW.
• New "Import" panel:
  • File picker for LastPass CSV → SW parses → preview ("142 logins, 17 notes, 3 skipped — proceed?") → bulk-add via SW.
  • Progress bar + inline warnings list.

File format: .relbak v1

Offset  Length   Field
─────── ──────── ────────────────────────────────────────────────────────
0       4        Magic: ASCII "RBAK"
4       1        Format version: 0x01
5       32       Argon2id salt (random per export, 32 bytes)
37      24       XChaCha20-Poly1305 nonce (random per export, 24 bytes)
61      ...      AEAD ciphertext + 16-byte Poly1305 tag

         ┌── after AEAD decryption ──┐
         ▼                           ▼
         zstd-compressed bytes
                  │
                  ▼
         JSON document (UTF-8):
         {
           "schema_version": 1,
           "created_at": <unix-seconds>,
           "vault": {
             "salt":          "<base64 of .relicario/salt>",
             "params":        { ... contents of .relicario/params.json verbatim ... },
             "devices":       [ ... contents of .relicario/devices.json verbatim ... ],
             "manifest":      "<base64 of manifest.enc>",
             "settings":      "<base64 of settings.enc>",
             "items":         { "<item-id-hex>": "<base64 of items/<id>.enc>", ... },
             "attachments":   { "<item-id>/<aid>": "<base64 of attachment blob>", ... },
             "reference_jpg": "<base64>",        // present iff --include-image
             "git_archive":   "<base64 of tarred .git/>"   // present iff !--no-history
           }
         }

KDF parameters for v1 (hard-coded, NOT read from params.json):

• Algorithm: Argon2id
• Memory: 64 MiB
• Iterations: 3
• Parallelism: 4
• Output length: 32 bytes

Future format v2 may change these; v1 readers will see version != 0x01 and produce a clear "newer version" error.

Data flow

Export

1. Read from disk (no vault unlock needed):
     .relicario/salt, params.json, devices.json
     manifest.enc, settings.enc
     items/*.enc
     attachments/<item>/*.enc
     (optional) reference image  -- via --include-image: from RELICARIO_IMAGE env, or --image <path>
     (optional) tarred .git/      -- default-on; --no-history to skip

2. Build JSON envelope per the schema above. Binary fields → base64 (using
   `data_encoding::BASE64` which already lives in the workspace).

3. zstd-compress the JSON document (level 3 — the speed/size sweet spot).

4. Prompt for backup passphrase (twice to confirm). Run zxcvbn gate; reject score < 3.

5. Generate fresh salt (32B) + nonce (24B) from `OsRng`.

6. Argon2id(passphrase, salt, v1-fixed params) → 32-byte key.

7. XChaCha20-Poly1305(key, nonce, compressed_bytes) → ciphertext.

8. atomic_write the file:
     [magic "RBAK"][version 0x01][salt 32B][nonce 24B][ciphertext]

9. Print: "Wrote backup.relbak (N MiB). Delete after restore is verified."

Restore

1. target_dir = arg or current dir. Refuse if target_dir/.relicario exists.

2. Read file. Verify magic (4 bytes "RBAK") and version (must be 0x01).
   Read salt (32B), nonce (24B), ciphertext (rest).

3. Prompt for backup passphrase.

4. Argon2id(passphrase, salt, v1-fixed params) → 32B key.

5. XChaCha20-Poly1305 decrypt → zstd decompress → parse JSON.
   Bad passphrase / tampered file → AEAD authentication failure;
   surface as "wrong backup passphrase, or the file is corrupt"
   (deliberately ambiguous, like vault unlock).

6. Validate envelope.schema_version == 1.

7. Write into target_dir:
     .relicario/salt
     .relicario/params.json
     .relicario/devices.json
     manifest.enc
     settings.enc
     items/<id>.enc for each
     attachments/<item>/<aid>.enc for each
     (if present) reference.jpg in target_dir root
     (if present) untar git_archive into target_dir/.git

8. If git_archive was NOT in the envelope:
     git init
     git add .
     git -c hooks=disabled commit -m "restore from backup <iso8601-utc>"

9. Print: "Restored vault to <target>. Unlock with your passphrase + reference image."

Import LastPass

1. Vault.unlock_interactive() — need master key to encrypt new items.

2. Read CSV bytes from filesystem (CLI) or File API (extension).

3. core::parse_lastpass_csv(bytes) → (Vec<Item>, Vec<ImportWarning>)
   Each Item already has:
     - fresh ItemId (random 8-char hex per existing convention)
     - title from `name`
     - group from `grouping` (None if empty)
     - favorite from `fav == "1"`
     - core mapped per the table below

4. Encrypt each item under master key. Write items/<id>.enc.
   Update manifest in-memory: manifest.upsert(&item).

5. Save manifest.enc (atomic_write — this is the single commit point).

6. ONE git commit covering all new items/*.enc + manifest.enc:
     "import: <N> items from LastPass (<csv-filename>)"

7. Print summary:
     "Imported <N>, skipped <K> (see warnings above)"
   Exit 0 if N > 0, else 1.

LastPass field mapping

LastPass column	Relicario destination	Notes
name	Item.title	Required; row skipped with warning if missing
grouping	Item.group	None if empty
fav	Item.favorite	"1" → true, anything else → false
url	LoginCore.url (parsed)	The literal value "http://sn" is LastPass's secure-note marker — when seen, the row is mapped to SecureNote (not Login) and the URL field is not stored. For ordinary login rows, an invalid URL is imported as url = None with a warning.
username	LoginCore.username	None if empty
password	LoginCore.password	Required for Login rows; missing → row skipped
totp	LoginCore.totp	If non-empty: base32-decode; build TotpConfig { secret, algorithm: Sha1, digits: 6, period_seconds: 30, kind: Totp }. Bad base32 → warning, login imported without TOTP.
extra (when url != http://sn)	Item.notes	Multi-line preserved
extra (when url == http://sn)	SecureNoteCore.body	Verbatim, even when LastPass packed structured data into it

Items where every required field for a Login is present and url != http://sn map to ItemCore::Login. Otherwise, if url == http://sn, map to ItemCore::SecureNote. Otherwise, the row is skipped with a warning explaining why.

Error handling

Export

Error	Detection	User-facing message	Recovery
Not in a vault	vault_dir() fails	"no .relicario/ found"	cd to vault root
Missing reference image	fs::read of --image path fails	"cannot read reference image: <path>"	Fix path or drop --include-image
Backup passphrase too weak	zxcvbn score < 3	"backup passphrase too weak (score N): <feedback>"	Choose a longer/more-entropic phrase
Disk full / permission denied	atomic_write returns io::Error	propagated io::Error with file path	Free space / fix permissions

Atomicity: output uses the existing atomic_write helper (write .tmp → rename). Partial output files are never visible.

Restore

Error	Detection	User-facing message	Recovery
Bad magic	First 4 bytes ≠ "RBAK"	"not a Relicario backup file"	Verify file
Unsupported version	Version byte > current (1)	"backup created by a newer Relicario; upgrade required"	Update binary
Wrong backup passphrase	AEAD authentication fails	"wrong backup passphrase, or the file is corrupt" (deliberately ambiguous)	Retry
Target dir already has a vault	target/.relicario/ exists	"target dir already contains a Relicario vault; restore refuses to overwrite — use an empty directory"	Choose empty dir
Schema mismatch	envelope.schema_version != current	"backup is schema v<N>; this Relicario reads v<M>"	Use matching binary
Mid-restore crash	(no detection)	—	User deletes target dir, retries

Atomicity: best-effort. If interrupted mid-write, target dir has partial files — user cleans up and retries. Documented limitation. Restore is rare enough that engineering atomic-rename of multiple files is not worth the complexity.

Import LastPass

Error	Detection	User-facing message	Recovery
CSV header missing/malformed	First-line parse fails	"unrecognized CSV header — expected LastPass export format"	Re-export from LastPass
Row missing required field	Per-row validation	Logged warning: "row N: missing 'name' — skipped"	Row skipped; no manual recovery
Bad base32 TOTP	base32 decode fails	Logged warning: "row N (<title>): invalid TOTP secret — login imported without TOTP"	Login imported sans TOTP
Vault locked	Pre-flight unlock	"unlock failed"	Retry passphrase
Mid-import crash	(no detection)	—	Items written before crash are orphan files (no manifest reference); safe to retry — will create new IDs, possibly duplicating

Atomicity: manifest is the single source of truth and is written last, with atomic_write. Item files written before the manifest are referenced only after the manifest commits. Orphans don't pollute the vault — they're invisible until the user runs a future "vault gc" sweep (out of scope here).

Progress feedback

• CLI: stderr line every 50 items: "[150/1247] importing...". Final summary on success: "Imported 1244, skipped 3 (see warnings above)". Non-zero exit only if zero items imported.
• Extension (vault tab): progress bar with same denominator. Inline warnings list. Final toast.

Testing strategy

Core tests (crates/relicario-core/tests/)

Pure logic, no IO. New files:

• backup.rs
  • Pack → unpack round-trip preserves bytes for empty vault, vault-with-attachments, vault-with-git-history.
  • Wrong passphrase → AEAD auth error (use RelicarioError::AuthenticationFailed or equivalent).
  • Tampered ciphertext / magic / version → format error variants.
  • --include-image round-trips the JPEG; absence honored.
  • --no-history produces a strict subset (no git_archive in envelope).
• import_lastpass.rs
  • Standard login row → Login with all fields populated.
  • url == http://sn → SecureNote.
  • TOTP base32 → embedded TotpConfig.
  • Bad base32 → warning, login imported without TOTP.
  • Missing name / password → row skipped + warning.
  • Quoted-comma, multi-line extra, unicode all parse cleanly.
  • grouping, fav, name pass through to Item.

Tests use fast Argon2id params (m=256, t=1, p=1) per the existing convention.

CLI integration tests (crates/relicario-cli/tests/)

End-to-end with the existing TestVault harness. New files:

• backup.rs
  • init → add 3 items → export → fresh-dir restore → unlock → list shows the same 3 items.
  • Restore refuses non-empty target with the documented error.
  • Wrong backup passphrase fails on restore.
  • --include-image carries the reference image; restored vault unlocks without separate --image arg.
  • --no-history produces a smaller file; restored vault has only the "restore from backup" commit.
• import_lastpass.rs
  • Fixture CSV → import lastpass → list shows the imported items.
  • Single git commit covers all imports (verify via git log --oneline).
  • Skipped rows produce warnings on stderr; CLI exits 0 if any item imported.
  • Title collision with existing item → both kept (decision D12).

Extension tests (vitest, mocked WASM/SW)

• extension/src/vault/__tests__/backup-panel.test.ts — renders Export / Restore / Import buttons; click → right SW message.
• Extend extension/src/service-worker/router/__tests__/router.test.ts with export_backup, restore_backup, import_lastpass cases — sender = vault tab, popup is rejected.
• extension/src/service-worker/__tests__/backup.test.ts — SW handler calls pack_backup_json, returns Blob bytes for download.
• Mocked WASM returns deterministic envelopes; assertions on payload structure.

Fixtures

• crates/relicario-cli/tests/fixtures/lastpass-sample.csv — ~15 synthesized rows, no real credentials. Coverage:
  • Standard login
  • Login with TOTP
  • Login with embedded URL TOTP that decodes correctly
  • Login with bad base32 TOTP (warning case)
  • SecureNote (url == http://sn)
  • Grouped item
  • Favorite item
  • Malformed row (missing name)
  • Unicode title (covers UTF-8 handling)
  • Multi-line extra (quoted, embedded newlines)
• Backup fixtures are generated per-test via setup(); not committed.

Out of scope / future work

• Migration out to other tools' formats (1Password 1pux, Bitwarden JSON, KeePass kdbx, generic CSV). Could be added later if users ask.
• Other importers: 1Password, Bitwarden, Chrome, Firefox. LastPass-only for now; plan is to add one importer per concrete user need rather than speculating.
• Vault GC sweep: orphan-file detection (items on disk without a manifest entry, attachments without an item). Useful after interrupted imports, but a separate feature.
• Merge restore: restoring a backup INTO an existing vault (rather than refusing). Conceptually overlaps with the future "sharing" feature; deferring decision.
• Backup encryption with the vault factor: requiring passphrase + reference image to unlock the backup, mirroring the live vault's 2FA. Conceptually possible but adds complexity, was rejected in brainstorming in favor of the standalone backup-passphrase model.
• Cloud-backed automatic backups: scheduled backups to Dropbox/S3/etc. Out of scope; users can wrap relicario export in cron.

Appendix A: estimated effort

Component	LOC est.	Days
core::backup (pack/unpack + format)	~150	1
core::import_lastpass (parser + mapping)	~120	0.5
Core tests	~250	0.5
CLI commands (export, restore, import lastpass)	~200	0.5
CLI integration tests + fixtures	~200	0.5
WASM bindings (3 new exports)	~50	0.25
SW handlers (export, restore, import)	~150	0.5
Vault tab UI (Backup & restore panel + Import panel)	~400	1
Vitest tests	~200	0.5
Documentation (CHANGELOG, CLI help, UI copy)	—	0.25

Total: ~5.5 dev-days end-to-end for full CLI + extension parity. The estimate is a guideline, not a commitment.

Appendix B: risks

Risk	Likelihood	Impact	Mitigation
LastPass changes their CSV format mid-stream	low	medium	Pin to today's column order; document expected header; surface a clear error on header mismatch so users don't silently get garbage
Backup files end up large (with .git/)	medium	low	--no-history opt-out; document trade-off in CLI help
User loses backup passphrase	medium	catastrophic	Document explicitly in CLI help and UI: "the backup passphrase cannot be recovered. If you lose it, the backup is unreadable."
zstd / Argon2id WASM bundle size	low	low	Both are already in our dep tree (Argon2id) or small (zstd ~100KB). Verify total wasm bundle stays under 4 MiB.
Cross-platform path / line-ending issues in .git/ tar	low	medium	Use tar crate's portable defaults; test round-trip on linux + mac in CI if available