Bitvaulter Security Whitepaper

DRAFT - pending independent third-party security review and penetration test before publication. Describes the design as implemented; not a substitute for an external audit.

Last updated: 2026-06-27 (date to be confirmed at publication).

1. Introduction

Bitvaulter (bitvaulter.com) is a zero-knowledge, end-to-end-encrypted password and secrets manager built on a model compatible with Bitwarden. It serves a dual audience: consumers and families who want a private place to store credentials, and developers and teams who need to manage shared secrets and service-account tokens.

Bitvaulter is self-hostable today, and a hosted option is planned. This whitepaper is written for technically literate readers and security reviewers. It describes the cryptographic design, the trust boundaries, what the server can and cannot see, and the limitations we currently know about. We aim to be accurate and to avoid overstating any guarantee.

The central design principle is straightforward: the server stores only ciphertext and the metadata needed to route it. The keys that unlock that ciphertext never leave the user's device in a usable form. Where that principle has limits, this document states them plainly.

2. Overview and threat model

Encryption is only meaningful relative to a stated adversary. This section describes what Bitvaulter is designed to defend against, and - just as importantly - what it does not defend against.

2.1 What we defend against

Server compromise. If an attacker gains control of the Bitvaulter backend, they obtain only encrypted vault data and the metadata required to serve it. They do not obtain the master password, the Master Key, the User Key, any item key, or any plaintext vault content. The server never holds the material needed to decrypt a user's vault (see Section 7).

Database theft. If an attacker exfiltrates the entire database, the result is the same as server compromise with respect to confidentiality: the attacker holds wrapped keys and ciphertext, not plaintext. The protection of that ciphertext reduces to the strength of the user's master password and the key-derivation function applied to it (see Sections 4 and 12).

Network attacker. All client-server traffic is carried over HTTPS/TLS, with HSTS to resist downgrade and stripping. A passive or active network attacker sees only encrypted transport carrying already-encrypted payloads (see Section 11).

2.2 What we do NOT defend against

We are explicit about the limits of the model. Bitvaulter does not protect against:

• A compromised end-user device. Decryption happens on the client. Malware, a malicious browser extension, a keylogger, or an attacker with control of the user's unlocked device can observe the master password as it is typed and plaintext as it is decrypted. No server-side design can prevent this.
• A weak master password. Because the master password is the root of the entire key hierarchy, a guessable password undermines the whole scheme. An attacker who steals the database can attempt to derive keys offline; the only barriers are the strength of the password and the cost of the KDF.
• Loss of the master password. There is no recovery. If a user forgets their master password, no one - including the operator of a self-hosted or hosted instance - can decrypt their vault. This is a deliberate consequence of the zero-knowledge design, not an oversight.

3. Architecture and backend

Bitvaulter's backend runs on Mortarbase, a Supabase-compatible platform. It provides three relevant components:

• PostgreSQL with Row-Level Security (RLS) for data storage and per-user authorization.
• GoTrue-style authentication issuing JWTs for session management.
• S3-compatible object Storage for encrypted files and attachments.

All cryptographic operations that touch plaintext or key material occur on the client. The backend's role is to authenticate requests, enforce authorization, and store and serve opaque ciphertext.

4. Key hierarchy

Bitvaulter derives all encryption keys from the user's master password through a layered hierarchy. Each layer exists so that the expensive, password-bound derivation happens once, while day-to-day operations use fast symmetric keys, and so that keys can be rewrapped or rotated without re-deriving from the password.

master password
      |
      |  PBKDF2-HMAC-SHA256, 600,000 iterations
      |  salt = per-account random value (via prelogin)
      v
  Master Key (256-bit)
      |
      |  HKDF-Expand(info = "enc" / "mac")
      v
  Stretched key (512-bit) = 256-bit AES key || 256-bit MAC key
      |
      |  unwraps
      v
  User Key (random 512-bit), stored wrapped under the stretched key
      |
      |  unwraps
      v
  Per-item keys (random, one per vault item), each stored wrapped under the User Key

4.1 Master Key derivation (KDF)

The Master Key is derived with PBKDF2-HMAC-SHA256 at 600,000 iterations, using a per-account random salt. The client fetches this salt before authenticating, via a prelogin lookup keyed by email. This produces a 256-bit Master Key. Accounts created before random salts were introduced may still use the lowercased/trimmed email address as the salt, for backward compatibility.

The KDF parameters (type and iteration count) are stored per account, so they can be upgraded over time. Argon2id is a planned, negotiable future KDF (see Section 12).

4.2 Stretched key

The 256-bit Master Key is expanded with HKDF-Expand into a 512-bit stretched key, using distinct info strings ("enc" and "mac"). The result is split into a 256-bit AES key and a 256-bit MAC key.

4.3 User Key

A random 512-bit User Key is generated for the account and stored wrapped (encrypted) under the stretched key. The User Key - not the Master Key - is what protects the user's vault items. Because the User Key is independent of the password-derived stretched key, the design allows the wrapping to change (for example, on a password change) without re-encrypting every item.

4.4 Per-item keys

Each vault item gets its own random item key, stored wrapped under the User Key. Item content is encrypted with its own item key. This per-item key design limits the blast radius of any single key and is what allows individual items to be rewrapped for sharing (see Section 9).

5. EncString formats

Bitvaulter serializes encrypted values using a tagged "EncString" wire format. Two types are relevant.

5.1 Type 2 - symmetric (AES-256-CBC + HMAC-SHA256)

Type 2 is the workhorse symmetric format. It uses AES-256-CBC for confidentiality and HMAC-SHA256 for integrity, in an encrypt-then-MAC construction.

Wire format:

2.<iv-b64>|<ciphertext-b64>|<mac-b64>

The MAC covers iv || ciphertext. On decryption, the MAC is verified with a constant-time comparison before any decryption is attempted. This ordering (verify integrity first, in constant time) is what makes the construction resistant to padding-oracle and timing attacks against the CBC layer.

5.2 Type 4 - asymmetric (RSA-2048 OAEP-SHA1)

Type 4 uses RSA-2048 with OAEP (SHA-1) and is used to wrap keys to a recipient's public key for sharing. This is how a symmetric key (such as a collection key) is delivered to another member: it is encrypted to that member's RSA public key so that only the holder of the corresponding private key can unwrap it.

OAEP with SHA-1 is retained for Bitwarden wire compatibility. We treat this as a known compatibility trade-off rather than a forward-looking recommendation; see Section 12.

6. File and attachment encryption

Encrypted files and attachments use a self-contained binary blob with the following layout:

iv (16 bytes) || ciphertext || mac (32 bytes)

The 16-byte IV and 32-byte (HMAC-SHA256) MAC are stored alongside the ciphertext in a single blob, so an encrypted file is self-describing and can be stored as an opaque object. The encrypted objects live in a private, owner-scoped Storage bucket (see Sections 7 and 8).

7. What the server stores vs. never receives

7.1 What the server stores (ciphertext and metadata only)

The backend persists the following:

• the account email;
• the KDF type and iteration count;
• the protected (wrapped) User Key;
• the account's RSA public key;
• the account's encrypted private key;
• encrypted item rows, each containing data_enc, key_enc, a type, and a favorite flag;
• encrypted file objects in a private, owner-scoped Storage bucket.

Every row and every object is scoped by Row-Level Security to the authenticated user (see Section 8).

7.2 What the server never receives

The server never receives:

• the master password;
• the Master Key;
• the User Key;
• any item key;
• any plaintext vault content.

As stated in Section 2, there is no recovery path: if a user loses their master password, neither the operator nor anyone else can decrypt the vault.

8. Authorization with Row-Level Security

Authorization is enforced in the database itself using PostgreSQL Row-Level Security. Every item row and every stored file object is scoped to the authenticated user via auth.uid(), so a user can only read or write their own rows and objects.

Enforcing access control at the row level - rather than relying solely on application code - means that even a flaw in an upper layer does not by itself grant a user access to another user's encrypted data. Note that RLS governs access to ciphertext; it is not a confidentiality control over plaintext, which is protected by the key hierarchy described above.

9. Authentication model

Bitvaulter separates the key derived from the master password from the credential used to authenticate to the server.

The value sent to the server is the Master Password Hash, defined as:

Master Password Hash = base64( PBKDF2(Master Key, master password, 1 iteration) )

This hash - not the master password, and not the Master Key - is what is transmitted to the server during authentication. GoTrue then stores only a bcrypt of the Master Password Hash.

The result is two independent barriers:

• The 600,000-iteration PBKDF2 derivation (Section 4.1) protects the Master Key against offline guessing of the password.
• The bcrypt applied server-side protects the stored authentication credential.

Because the server only ever sees the Master Password Hash and stores only a bcrypt of it, the master password itself never reaches the server in any form.

10. Sharing and organizations

10.1 Collections

Items can be grouped into collections for sharing. When an item is shared via a collection, it is rewrapped under a collection key. The collection key is then RSA-wrapped to each member's public key (EncString type 4, Section 5.2), so each member can unwrap the collection key with their own private key and thereby decrypt the collection's items.

This keeps the zero-knowledge property intact for sharing: the server stores the wrapped collection keys but never holds the unwrapped collection key or the recipients' private keys.

10.2 Forward-secure rotation on member removal

When a member is removed from a collection, Bitvaulter triggers a forward-secure rotation of the affected collection keys. A new collection key is established and distributed to the remaining members, so that the removed member's old key cannot decrypt data created after their removal.

We are precise about the scope of this guarantee: rotation protects future data. A former member who retained copies of previously accessible plaintext, or who captured the old key material while still a member, is outside what rotation can undo.

10.3 Machine and service-account tokens

For automated workloads, Bitvaulter issues machine/service-account tokens that separate authentication from decryption:

• AUTH: the server stores a one-way hash of the token secret (PBKDF2-HMAC-SHA256 today; Argon2id planned), which lets it authenticate a presented token.
• DECRYPT: a separate key is derived via HKDF of the raw secret using a distinct info string.

Because the authentication path stores only a one-way hash, and the decryption key is derived along a separate path from the raw secret, the server can authenticate a token without being able to decrypt with it. A server compromise therefore does not yield the decryption capability associated with these tokens.

11. Breach (pwned-password) check

Bitvaulter can check whether a password appears in known breach corpora using the Have I Been Pwned (HIBP) k-anonymity range API. Only the first 5 hexadecimal characters of the password's SHA-1 hash are sent to the range API; the full hash and the password itself never leave the device. The client receives the matching range and completes the comparison locally.

12. Transport and web client hardening

• TLS only. All traffic is carried over HTTPS/TLS.
• HSTS. HTTP Strict Transport Security is set to resist downgrade and stripping attacks.
• Strict Content-Security-Policy. The web client ships a strict CSP with no third-party scripts, reducing the attack surface for script injection and supply-chain risk in the browser.
• Idle auto-lock. The vault locks automatically after a period of inactivity, requiring re-unlock.
• Clipboard auto-clear. Copied secrets are cleared from the clipboard automatically after a short interval.

13. Encrypted local backup

Bitvaulter supports an encrypted local backup export. The export is itself encrypted under a separate export password, independent of the master password. This keeps an exported backup confidential at rest while ensuring that compromise of an export does not directly reveal the account's master password or its derived keys.

14. Data retention and deletion

• Deleting an item removes its row from the database.
• Deleting an account cascades to the account's profile, its items, and its stored files.

15. Known limitations and roadmap

We believe an honest accounting of current limitations is part of a credible security posture.

• KDF is PBKDF2 today. The current key-derivation function is PBKDF2-HMAC-SHA256 at 600,000 iterations. Argon2id is planned as a negotiable future KDF. KDF parameters are stored per account to support migration.
• No completed third-party audit yet. A third-party security audit and penetration test are planned before general availability and have not yet been completed. Until then, the assurances in this document rest on design and internal review, not on an independent assessment.
• RSA-OAEP-SHA1 retained for compatibility. EncString type 4 uses RSA-2048 OAEP with SHA-1, retained for Bitwarden wire compatibility. We document this explicitly as a known compatibility trade-off.

This section will be updated as items are completed or as the design changes.

16. Reporting a vulnerability

We welcome reports from the security community. Please refer to our security.txt for the current, authoritative reporting contact and policy:

https://bitvaulter.com/.well-known/security.txt

Contact address:

• support@bitvaulter.com - vulnerability reports, privacy and data inquiries

Appendix A: Cryptographic parameters at a glance

DRAFT - for review by qualified legal counsel before publication. This is not legal advice.

Placeholders requiring owner/counsel confirmation appear in this document as bracketed items.

• [PLACEHOLDER: legal entity name]
• [PLACEHOLDER: governing law]
• [PLACEHOLDER: effective date]