Vault Approver: Open-Source Login Approver for Vaultwarden

Bitwarden’s «Login with device» feature is brilliant, tap a notification, approve, and you’re in without typing a password. But approving requires the full Bitwarden app with your entire vault loaded. I built Vault Approver, a minimalist Flutter app that does exactly one thing: approve login requests on self-hosted Vaultwarden servers. No vault access, no stored passwords, just biometric unlock and one tap.

Why Vault Approver Exists

Self-hosted Vaultwarden is the gold standard for password management, you control your data, your server, your rules. But «Login with device» has a UX problem: the official Bitwarden mobile app loads your entire vault just to approve a request. That’s unnecessary attack surface for a one-tap action. Vault Approver strips everything down to the essential flow: Face ID → see request → verify fingerprint phrase → approve. The app never accesses your vault, never stores your master password, and the security model is fully end-to-end encrypted with RSA-2048-OAEP.

The principle is the same one I apply to any sensitive system: a tool that needs to do one thing should be able to do only that thing. An approver that can also read your passwords is an approver that can leak your passwords. So this one can’t, by construction, not by policy.

How Vault Approver Works

1. One-time setup: Enter your Vaultwarden server URL + email + master password. The app derives encryption keys via Argon2id, stores the user key in device Keychain/Keystore behind biometrics, then discards the password
2. Real-time notifications: A SignalR WebSocket with the MessagePack binary protocol connects to your server. When someone triggers «Login with device», you get an instant push, with a polling fallback (5 s / 15 s / 30 s / 1 min) if the socket drops
3. Biometric unlock: Face ID or Touch ID on every app launch, no PIN fallback, no shortcuts
4. Fingerprint verification: A 5-word EFF phrase derived from the requester’s public key prevents spoofing attacks
5. One-tap approval: RSA-2048-OAEP encrypts your user key with the requester’s public key. The server never sees your encryption keys

The Cryptographic Chain, Step by Step

The whole point is that approval happens end-to-end: the server relays ciphertext it cannot read. Vault Approver reproduces Bitwarden’s key schedule exactly, so a self-hosted Vaultwarden stays fully compatible. The derivation runs in four stages:

1. Master key: masterPassword + email go through the server-declared KDF (Argon2id, with the salt = SHA-256(email) truncated to 16 bytes; or PBKDF2-SHA256 for older servers) to produce a 32-byte master key.
2. Stretched key: the master key is expanded with HKDF-Expand(SHA-256) into a 64-byte stretched key: encKey = HKDF(info="enc", 32B) and macKey = HKDF(info="mac", 32B).
3. User key: the stretched key AES-256-CBC-decrypts the account’s protected symmetric key, yielding the 64-byte user key. This is the key that actually unlocks vault data, and the only secret the approver ever holds.
4. Approval: on each request, the user key is encrypted with RSA-OAEP under the requester’s public key. Only the device that started the login can decrypt it; the Vaultwarden server is a blind relay.

Server authentication uses a separate value, a master-password hash derived as PBKDF2-SHA256(masterKey, salt=masterPassword, 1 iteration), so the server verifies you without ever receiving anything that can decrypt a vault. Nothing in this chain is invented for the app; it’s the documented Bitwarden protocol, re-implemented in Dart so it can be read line by line.

The Fingerprint Phrase: Defeating Approval Phishing

Passwordless approval has one nasty failure mode: an attacker who knows your email triggers a «Login with device» request and hopes you tap «approve» out of habit. Vault Approver closes that gap with a fingerprint phrase, five words from the EFF wordlist, deterministically derived from the requesting device’s public key. The same phrase is shown on the device asking to log in. If the words don’t match, the request isn’t yours, and you deny it.

It turns an abstract «is this request legitimate?» into a concrete, five-second human check, the same out-of-band-verification idea behind Signal’s safety numbers, applied to login approval. It does not stop a request from arriving, but it stops you from approving the wrong one.

Security Architecture

With 6 patents in information security, I designed Vault Approver with a zero-trust approach. The security model rests on five guarantees:

• Master password never stored: Entered once during setup, used to derive keys, then discarded. Re-setup is required if biometric data changes
• Device Keychain/Keystore: User key encrypted with a random biometric storage key, protected by the Secure Enclave (iOS) or Android Keystore
• E2E encryption: Full Bitwarden-compatible crypto chain, Argon2id KDF, HKDF-SHA256 key stretching, AES-256-CBC vault-key decryption, RSA-OAEP key exchange
• No vault access: The app only calls /api/auth-requests, it literally cannot read your passwords
• No data collection: Zero analytics, zero telemetry, zero cloud. The App Store privacy label confirms «Data Not Collected»

This is the same defense-in-depth approach I recommend for enterprise IT architecture: minimize attack surface, encrypt everything, trust nothing.

Threat Model: What It Protects, and What It Doesn’t

Honest security means naming the boundaries. What Vault Approver defends against:

• A compromised server: Vaultwarden relays only ciphertext it cannot read, so a breached server cannot recover your vault from approvals
• Approval phishing: the fingerprint phrase makes an attacker-triggered request visibly wrong
• App-level vault leakage: there is no vault UI to leak; the approver can’t read passwords even if it wanted to
• Casual device access: biometric unlock on every launch, plus an auto-lock timeout, gate the app behind your face or fingerprint

What it does not protect against, stated plainly: a fully compromised device where an attacker can defeat the OS biometric layer; a user who approves a request whose phrase doesn’t match (the check only works if you actually read it); and you still trust your Vaultwarden server to faithfully relay auth-requests, it can’t read your vault, but a malicious server could withhold or spam requests. The app shrinks the attack surface dramatically; it does not abolish trust in your own hardware.

Hardening Details

Beyond the crypto, several smaller choices reduce real-world exposure:

• Privacy screen: an iOS blur overlay and Android FLAG_SECURE hide app content in the task switcher and block screenshots
• Configurable lock timeout: immediate / 15 s / 1 min / 5 min / 15 min / never, so the app re-locks on your terms
• 2FA / TOTP supported during initial setup, matching whatever your server enforces
• System / light / dark themes and a built-in EN/RU switcher, so the tool fits the device rather than the other way around

Technical Stack

• Flutter + Dart (SDK ≥ 3.5): cross-platform, iOS on the App Store, Android in beta
• State management: Riverpod 2.x for reactive UI
• Crypto: PointyCastle 4.x + cryptography 2.x, full Bitwarden-compatible implementation
• Networking: dio 5.x, web_socket_channel 3.x, msgpack_dart 1.x (SignalR + MessagePack + polling fallback)
• Security: local_auth (biometrics), flutter_secure_storage (Keychain/Keystore)
• Localization: English + Russian with an in-app switcher

Getting Started with Vault Approver

Prerequisites: a self-hosted Vaultwarden server with «Login with device» enabled, and a phone with Face ID / Touch ID (iOS) or biometric unlock (Android).

1. Install: Download Vault Approver from the App Store (free, 20.9 MB)
2. Connect: Enter your Vaultwarden server URL (e.g., https://vault.yourdomain.com)
3. Authenticate: Email + master password + optional 2FA/TOTP
4. Enable biometrics: Face ID or Touch ID, this becomes your only unlock method
5. Done: next time you or your team uses «Login with device», the request appears instantly

The Android version is currently in open beta, check GitHub for APK builds.

Why Open Source Matters for Security Apps

A security app you can’t audit is a security risk. Vault Approver is MIT-licensed and fully open source on GitHub. Every line of crypto code is reviewable, from the Argon2id key derivation to the RSA-OAEP key exchange. No obfuscation, no hidden network calls, no proprietary black boxes. For a tool that holds the one key capable of unlocking your vault, «trust me» isn’t good enough, «read the code» is. That transparency is especially critical for data-sensitive organizations that need to verify what runs on employee devices.

Need help setting up self-hosted Vaultwarden for your team? Book a free consultation →

Frequently Asked Questions

Does Vault Approver work with official Bitwarden servers?

It’s designed for self-hosted Vaultwarden but uses the standard Bitwarden API. It may work with official servers, though primary testing is against Vaultwarden.

Can Vault Approver access my passwords?

No. The app only interacts with the auth-requests API endpoint. It has no vault UI, no password list, and no ability to decrypt stored credentials. It’s an approver, not a vault client.

What is the fingerprint phrase for?

It is a 5-word EFF phrase derived from the requesting device’s public key, shown on both the requester and the approver. Matching phrases prove the request is genuinely yours; a mismatch means an attacker triggered it, and you deny.

What happens if I lose my phone?

The user key is protected by device biometrics inside the Secure Enclave / Android Keystore. Without your face or fingerprint, the key can’t be extracted, and your vault stays safe. Just set up Vault Approver on a new device with your master password.

Is the Android version available?

Android is in open beta. You can build from source or download the APK from GitHub releases. A Google Play release is planned once beta testing is complete.

Need a consultation?

If you need professional expertise, book your free 15-minute consultation.