Valet

Valet is a local-first, multi-user password manager. The core library handles encryption (AES-GCM-SIV + Argon2 key derivation), and multiple clients consume it:

• CLI (src/bin/cli.rs): Clap-based REPL for registering users, managing lots, and storing/retrieving secrets from the terminal.
• GUI (src/bin/gui/): Native desktop app built with egui/eframe (behind the gui feature flag).
• Browser extension (platform/browser/): browser popup that matches credentials to the active tab's domain, with a native messaging host for database access. See the browser extension README for build and development instructions.

Most people end up choosing between hosted password managers like 1Password or Bitwarden, which require trusting a vendor's servers and keeping a subscription current, and local-first tools like KeePass or pass, which keep you in control of the data but scatter the experience across a loose collection of third-party clients with inconsistent platform support and dated cryptography.

Valet is closest in spirit to KeePass: a local, encrypted database that you own, synced between your own devices rather than through a vendor. The aim is to take that model and modernize it:

• Real multi-user, without a shared master password. A single database holds multiple users, each with their own password. Lots (named collections of secrets) are shared by re-encrypting the lot key for each recipient, so access can be granted and revoked per-user instead of handing out one password that everybody has to keep rotating.
• Durability over destructiveness. Records store their history and are archived rather than hard-deleted, so an accidental overwrite does not strand a working credential.
• Modern cryptography. AES-GCM-SIV for nonce-misuse resistance, Argon2 for key derivation, and AAD binding every ciphertext to the identifier it belongs to.
• Local ownership by default. The database is a SQLite file with embedded Git repos on your disk. Nothing is sent to a vendor by default; there is no account to create. When sync lands it will be peer-to-peer between your own devices or servers.
• First-party clients on every platform. The core library is consumed by a CLI, a desktop GUI, browser extensions for Firefox/Chrome/Safari, and system-level autofill on macOS and iOS, all developed in this repo against the same encrypted store.

Legend: 🟩 = Supported, 🟦 = Planned, 🟥 = Not supported.

Note: macOS Ext. and the macOS App will be merged before release.

An idea for the CLI...

$ valet register <username>
valet> Password: <password>

$ valet validate <username>
valet> Password: <password>

$ valet unlock <username>
valet> Password: <password>

valet> add <label> <value>...

valet> del <label>

valet> list
- <label>
- ...

valet> get <label>
<value>...

Example Adding Password

$ valet unlock nixpulvis
valet> Password: mastersecret
valet> add github.com/nixpulvis anothersecret
✅

# Or in oneline (two with the password prompt).
$ valet add github.com/nixpulvis anothersecret
valet> Password: mastersecret
✅

Example Getting Password

$ valet unlock nixpulvis
valet> Password: mastersecret
valet> get github.com/nixpulvis
anothersecret

# Or in oneline (two with the password prompt).
$ valet get github.com/nixpulvis
valet> Password: mastersecret
anothersecret

Example Adding SSH Key

$ valet unlock nixpulvis
valet> Password: mastersecret
valet> add ssh/nixpulvis/machine "..."
valet> add ssh/nixpulvis/machine.pub "..."
✅

# Helper commands
valet> add-ssh ssh/nixpulvis ~/.ssh/machine.pub

TODO: GPG Keys

As part of designing a local-first, multi-user, distributed password manager, there are many different threat models to consider at different levels.

The simplest base threat model involves only a single user operating on a single database with possibly many client programs (i.e. CLI and GUI). In this model, the database remains completely under the stewardship of the user.

A corrupted database may no longer work as expected, but the security of the secrets should remain intact. The only way to leak the secrets would be to either A) leak the master user password, B) leak the AES key material, or C) leak the secrets themselves.

Users are free to, and encouraged to maintain a backup, which Valet may assist with, however, that copy of the database is outside the perview of the application. There are no syncronization concerns because backups in this model are read-only snapshots of the current state of the application. Restoring from an offline backup is either as simple as copying it to the user's primary database location, or manually copying spesific secrets.

If the client's host's root user or kernel is compromised then the security of the application cannot be ensured. Valet will try to mitigate the leakage, but the user password, encryption keys, and secrets will be availible in memory. Malicious user-level programs should not be able to read secrets, thanks to OS process isolation.

Valet clients will also take measures to avoid losing or leaking information through careless user interactions. For example, an inactive client should become locked automatically and secret information should never be displayed without an explicit request by the user. Any OS integrations (e.g. autofill) should take care to consider the complete UX of both secret creation and use. Full history of secrets should be kept by default in case users accidentally update a secret before confirming it was accepted by it's intended recipient. Losing a password can be just as bad as having a password stolen.

TODO: Next is a single user with many databases all syncronized manually. Here databases are transfered between clients with changes merged and conflicts handled by the user without an active 3rd party. The way the databases are transfered shouldn't effect the application, however if using a network drive, each client would still need it's own copy. Here we need to worry about maliciously corrupted databases trying to steal data through the syncronization process.

TODO: Now we introduce a hosted Valet server, which allows for online registration. These environments are fundamentally multi-user, since they necessitate syncing the hosted database with the local client's database.