Struct Vault 

pub struct Vault { /* private fields */ }

An open, in-memory vault.

Dropping the value drops the underlying decrypted material. Best-effort memory zeroing is delegated to the keepass crate where supported.

Implementations

impl Vault

pub fn create(path: &Path, password: &str) -> Result<Self>

Create a new kdbx file at path, encrypted with password. Errors if the file already exists.

pub fn create_with_key( path: &Path, password: &str, keyfile: Option<&[u8]>, ) -> Result<Self>

Create a new kdbx file locked by a composite key: password plus the given keyfile bytes (any format KeePassXC accepts — XML v1/v2, raw 32-byte, hex-64, or an arbitrary file hashed with SHA-256).

pub fn open(path: &Path, password: &str) -> Result<Self>

Open an existing kdbx file with a password.

pub fn open_with_key( path: &Path, password: &str, keyfile: Option<&[u8]>, ) -> Result<Self>

Open an existing kdbx file with a composite key: password plus the given keyfile bytes. A wrong or missing keyfile surfaces as Error::BadPassword, same as a wrong password — the kdbx format cannot distinguish which credential was wrong.

pub fn save(&mut self) -> Result<()>

Persist in-memory state back to the original path (atomic replace).

pub fn path(&self) -> &Path

pub fn add_entry(&mut self, title: &str) -> Result<EntryId>

Add a new entry. The title is interpreted as a /-separated path: the leading segments name a group hierarchy (created as needed, mkdir -p semantics), and the trailing segment becomes the entry title. A title with no / lands at the root group, matching the previous behavior.

A leading Root segment (case-insensitive) names the root group itself, so add_entry("Root/github") is identical to add_entry("github").

Examples:

• add_entry("github") → “github” in the root group
• add_entry("Work/SSH/github") → group “Work” > “SSH”, entry “github”

Empty segments (//, /foo, foo/) and the empty title are rejected with Error::InvalidPath. Group lookups are case-insensitive (matches keepass-rs and KeePassXC behavior), so work/ssh resolves to an existing Work/SSH. Returns the entry’s stable ID.

pub fn list_entries(&self) -> Vec<EntrySummary>

List all entries in the vault (recursively across all groups).

pub fn get_entry(&self, id: &EntryId) -> Option<EntrySummary>

Look up an entry by ID. Returns None if no such entry exists.

pub fn find_by_title(&self, title: &str) -> Option<EntryId>

Look up an entry by title or path.

• Plain title with no /: returns the first entry whose leaf title matches (current behavior). Search is exact (case-sensitive) on the leaf title across all groups.
• Path with /: navigates group/sub/.../leaf and matches only the entry at exactly that path. Group navigation is case-insensitive (matching keepass-rs); the leaf title comparison is exact.

Returns None if no such entry exists, or if any group segment in the path is missing.

pub fn set_field( &mut self, id: &EntryId, field: &str, value: &str, ) -> Result<()>

Set or replace a string field on an entry. Standard fields: "Title", "UserName", "Password", "URL", "Notes". Custom fields permitted.

Password and otp are stored with the kdbx Protected flag — matching KeePassXC, which memory-protects both by default.

pub fn attach_binary( &mut self, id: &EntryId, name: &str, bytes: &[u8], ) -> Result<()>

Attach a binary blob (e.g. an SSH private key) to an entry under name. Replaces any existing attachment with the same name.

Bytes are stored as a real KDBX4 inner-header binary attachment with a <Binary Ref="N"/> reference inside the entry, matching what KeePassXC writes. The Protected flag is left at the default (off) — KeePassXC likewise stores SSH private keys without it.

pub fn read_binary(&self, id: &EntryId, name: &str) -> Result<Option<Vec<u8>>>

Read an attachment’s bytes. Returns Ok(None) if the entry exists but has no such attachment. Errors if the entry itself does not exist.

pub fn remove_binary(&mut self, id: &EntryId, name: &str) -> Result<()>

Remove an attachment from an entry. No-op if the attachment is missing.

pub fn delete_entry(&mut self, id: &EntryId) -> Result<()>

Delete an entry by ID.

pub fn get_field(&self, id: &EntryId, field: &str) -> Result<Option<String>>

Read a single string field from an entry. Returns None if the field is missing. Errors if the entry itself does not exist.

Used by the materialization layer to read Materialize.* custom fields from entries that opt in.

pub fn fields_with_prefix( &self, id: &EntryId, prefix: &str, ) -> Result<Vec<String>>

Return the names of every custom string field on an entry whose name starts with prefix. Field names are returned in unspecified order. Errors if the entry does not exist.

Used by the materialization layer so the daemon can quickly tell which entries opt in (any entry with at least one Materialize.* field).

pub fn remove_field(&mut self, id: &EntryId, field: &str) -> Result<()>

Remove a string field from an entry. No-op if the field is absent.

pub fn move_entry(&mut self, id: &EntryId, group_path: &str) -> Result<()>

Move an entry to an existing group. The target must already exist — a typo’d destination should error, not silently grow a new hierarchy (use Vault::add_group first to create one).

pub fn add_group(&mut self, path: &str) -> Result<()>

Create a group hierarchy with mkdir -p semantics for intermediate segments. Errors with Error::GroupExists if the leaf group already exists (matching keepassxc-cli mkdir).

pub fn recycle_entry(&mut self, id: &EntryId, permanent: bool) -> Result<bool>

Delete an entry the KeePassXC way: move it to the recycle bin, unless it is already inside the bin or the bin is disabled in Meta — then it is destroyed. permanent forces outright destruction.

Returns true if the entry was recycled, false if destroyed.

pub fn remove_group( &mut self, path: &str, permanent: bool, recursive: bool, ) -> Result<bool>

Remove a group. Default: move it (contents and all) to the recycle bin, mirroring KeePassXC. With permanent (or the bin disabled, or the group already inside the bin) it is destroyed instead — and a non-empty group is only destroyed when recursive is also set.

Returns true if recycled, false if destroyed.

pub fn search_entries(&self, term: &str) -> Vec<EntrySummary>

Case-insensitive substring search over title, username, URL, notes and the group path. Protected values are never searched.

pub fn resolve_ref(&self, reference: &str) -> Result<String>

Resolve a trove:// secret reference to a field value.

Format: trove://<entry-path> (defaults to the Password field) or trove://<entry-path>/<Field> (the last /-segment is the field name when the whole path doesn’t itself resolve to an entry). So trove://Infra/prod/postgres yields that entry’s password, and trove://Infra/prod/postgres/UserName its username. Modeled on 1Password’s op:// references.

Errors: Error::InvalidPath if the string isn’t a trove:// ref, Error::EntryNotFound if no entry matches, and Error::InvalidPath again if the entry exists but the named field is absent.

pub fn totp_now(&self, id: &EntryId) -> Result<TotpCode>

Current TOTP code for an entry, computed from its otp field (an otpauth:// URI — KeePassXC’s native storage format).

pub fn totp_at(&self, id: &EntryId, unix_secs: u64) -> Result<TotpCode>

TOTP code for an entry at a specific unix time. Deterministic — used by tests (RFC 6238 vectors) and future countdown displays.

pub fn set_totp_uri(&mut self, id: &EntryId, uri: &str) -> Result<()>

Set an entry’s otp field from an otpauth:// URI, validating it parses as a TOTP spec first so garbage never lands in the vault. The field is stored Protected (KeePassXC’s own treatment).

pub fn merge_from( &mut self, source: &Path, source_password: &str, source_keyfile: Option<&[u8]>, ) -> Result<MergeSummary>

Merge another vault into this one (KDBX-standard three-way semantics: last-write-wins by modification time, histories preserved — the same algorithm KeePassXC applies). The source is opened with its own credentials; this vault is saved afterwards.

pub fn current_password(&self) -> &str

The password this vault was opened/created with. For rekey flows that change only one credential (e.g. adding a keyfile, keeping the password) — the caller already presented it to open the vault.

pub fn current_keyfile(&self) -> Option<&[u8]>

The keyfile bytes this vault was opened/created with, if any.

pub fn rekey( &mut self, new_password: &str, new_keyfile: Option<&[u8]>, ) -> Result<()>

Change the vault’s credentials: a new password and/or keyfile. Takes effect immediately (the vault is re-saved under the new composite key).

pub fn set_argon2_params( &mut self, memory_kib: Option<u64>, iterations: Option<u64>, parallelism: Option<u32>, ) -> Result<()>

Tune the Argon2 KDF (memory in KiB, iterations, parallelism). Applies on save. Errors if the vault uses a non-Argon2 KDF (retune those by opening in KeePassXC — trove only writes Argon2 vaults itself).

pub fn db_info(&self) -> DbInfo

Non-secret database facts for db-info.

pub fn custom_field_names(&self, id: &EntryId) -> Result<Vec<String>>

Names of an entry’s custom string fields (everything beyond the five standard kdbx fields), sorted. For show-style listings.