- JavaScript 90.1%
- CSS 5.7%
- HTML 4.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
Some checks failed
CI / test (push) Has been cancelled
PIN unlock (docs/SPEC.md section 10): unlock once with the master password, then set a PIN and use it for subsequent unlocks. The PIN is never stored - it derives a key with the account's own KDF settings and encrypts a copy of the user key and refresh token in storage.local, so it survives a browser restart. Setting/changing/removing the PIN requires the master password, verified locally against the cached protected key (never over the network). Five wrong attempts destroy the record; it is bound to server URL + email; logout clears it; and a failed token refresh clears it rather than leaving a dead record. The settings screen carries an explicit warning that a short PIN protecting a local vault copy is brute-forceable. Fixed - settings appearing not to save: - The options page called loadSettings() without awaiting it, so on a cold background start the initial read could resolve AFTER a save and re-render the form from the pre-save state, clearing the field just saved (most visibly the account email). A generation guard now discards a stale load result. - The 'show dropdown' and 'autofill single match' toggles did nothing: the options page wrote autoFillShowDropdown / autoFillSingleMatch while the canonical names are showDropdown / autofillSingleMatch, so the allowlist silently dropped both and they were disconnected from the autofill code that reads them. - saveSettings() now debug-logs dropped keys, VF.store.acceptedSettingsKeys() exposes the accepted list, and a test asserts every key the options page sends is accepted. - An expired session during PIN unlock reported PIN_INVALID (showing a bogus 'attempts remaining' for a correct PIN); it now reports PIN_UNAVAILABLE and does not touch the attempt counter. Verified: 119/119 unit tests, web-ext lint 0 errors/0 warnings/0 notices, and the packaged artifact re-signed by Mozilla (payload identical to the local build). No credentials committed - every .env value was grepped against the repository and the extracted artifact: 0 matches. |
||
| .forgejo/workflows | ||
| dist | ||
| docs | ||
| src | ||
| test | ||
| tools | ||
| .gitignore | ||
| CHANGELOG.md | ||
| LICENSE | ||
| manifest.json | ||
| package.json | ||
| README.md | ||
Vaultfox
A Firefox add-on that talks directly to your Bitwarden or Vaultwarden server: unlock your vault, search it, autofill logins into web pages, read TOTP codes and generate passwords. Your vault is decrypted locally in the extension; only the encrypted vault ever touches disk.
Vaultfox is an independent, clean-room implementation of the public Bitwarden client protocol. Its feature set is inspired by Keyguard — a source-available, all-rights-reserved project — and by the official Bitwarden browser extension. No code, assets, text or branding from either is used here.
Not affiliated with Keyguard, Bitwarden Inc., or the Vaultwarden project. "Bitwarden" is a registered trademark of Bitwarden Inc. Vaultfox is an unofficial third-party client, provided as-is, with no warranty.
Status
Version 1.2. The cryptography, URL matching, generator and WebAuthn logic are
covered by a dependency-free test suite (node test/run.mjs) and the package is
validated with web-ext lint. It has not yet been smoke-tested in a real
browser — docs/MANUAL-TESTING.md is the checklist for that, and is the
honest statement of what is and is not proven. That gap matters most for the
passkey feature, which is the most invasive part of the extension.
What it does
- Connects to Bitwarden.com, Bitwarden.eu, or a self-hosted Bitwarden or Vaultwarden instance (configurable base URL).
- Email + master password login, authenticator/email 2FA, and personal API key login.
- Unlocks with your master password; the derived keys live only in memory
(
browser.storage.session) and are discarded on lock, on idle and on browser restart. - Unlocks with a PIN after the first master-password unlock (opt-in; see below).
- Syncs your vault and keeps an encrypted cache locally so the list is available before a sync finishes.
- Browses and searches logins, secure notes, cards and identities; copies usernames, passwords and TOTP codes.
- Autofills logins through a dropdown rendered in a closed shadow root, with React/Vue-safe value setting.
- Generates passwords and passphrases.
- Matches items to sites by exact URL, host, base domain, prefix, regex, or "never" — Bitwarden's match types.
- Stores and uses passkeys (see below).
Unlock with a PIN
Unlock once with your master password, then set a PIN in Options → Unlock with PIN and use it for subsequent unlocks. The PIN is never stored: it derives a key — using your account's own KDF settings — that encrypts a copy of your user key and refresh token in local storage, so it survives a browser restart.
Worth being explicit about the trade-off, because the settings screen says it too: this protects your vault with the PIN alone. A short PIN is brute-forceable by anyone with access to the disk and the ciphertext. That is inherent to the feature, and the official client has the same property. To limit the damage:
- setting, changing or removing the PIN requires re-entering your master password, checked locally against your cached key — never sent anywhere;
- after 5 consecutive wrong PINs the stored record is destroyed and the master password is required again;
- the record is bound to your server and email, and logging out destroys it.
PIN unlock makes no network login: it decrypts the stored key and refreshes the access token from the stored refresh token. If that refresh fails, the record is cleared and you are asked for the master password.
Passkeys / WebAuthn
Vaultfox can display the passkeys in your vault, sign in with them, and create new ones. This is opt-in and off by default, because of how it has to work:
Firefox has no API that lets an extension provide passkeys alongside the browser's own WebAuthn implementation. The only way is to replace it.
So when you enable the passkey provider, a script injected into the page takes
over navigator.credentials.create and .get. While it is active, hardware
security keys, Touch ID / Windows Hello and phone-as-authenticator are not
offered unless you choose the browser fallback in the confirmation prompt.
Every ceremony shows an extension-owned confirmation window — never page UI —
and a page can neither suppress it nor confirm it for you.
If you would rather keep native WebAuthn, leave the setting off: passkeys are still listed in the popup, they just cannot be used from a web page.
The authenticator is implemented from the WebAuthn specification. A generated
assertion signature is verified against its public key by the test suite using
Node's own crypto, both as raw r||s and as DER.
What it deliberately does not do (yet)
- Writes are limited to ciphers. Passkey creation saves a login item; it never creates or deletes folders, collections or sends, and it never purges (deletion is always the recoverable "move to trash").
- No Argon2id accounts. PBKDF2 only; an Argon2id account gets an explicit error rather than a wrong answer. The KDF module is written so Argon2id can be added.
- No KeePass/KDBX files, SSH/GPG agent, breach checks, imports/exports.
- No
prfextension, so a passkey cannot be used to derive an encryption key (for example to log into another password manager passwordlessly). - Firefox desktop only (Manifest V3 with
background.scripts).
Security model
The short version:
| Secret | Where it lives |
|---|---|
| Master password | never stored, never sent; used to derive keys in memory |
| User key, tokens | browser.storage.session (memory-backed, not on disk) |
| Vault cache | browser.storage.local, ciphertext only |
- The master password is never transmitted — only
PBKDF2(masterKey, password, 1), exactly as the protocol specifies. - The content script is treated as untrusted. It can see which items match the page it is on, but a password is handed to it only after an explicit user action, and it never receives the user key, tokens, or the rest of the vault.
- No remote code, no
eval, no telemetry, no analytics. The only network traffic is to the server you configure. - TLS is required, except for loopback and
.onionorigins. - Debug logging is off by default and redacts secret-shaped values.
The full model, including the exact key-derivation chain, is in
docs/SPEC.md §2 and §4, and the wire protocol is documented in
docs/PROTOCOL.md.
What Firefox will tell you at install time
Because Vaultfox transmits your account email, master password hash (never the password) and two-factor codes to the Bitwarden/Vaultwarden server you configure, the manifest declares two data-collection categories under Firefox's built-in consent system:
"data_collection_permissions": { "required": ["personallyIdentifyingInfo", "authenticationInfo"] }
That declaration is about transmission to your server. Vaultfox itself has no backend: it does not send anything to the author or to any third party, has no telemetry or analytics, and makes no network request to any host other than the one you enter in the options page. Nothing is shared with the developer.
The declaration is why strict_min_version is Firefox 140: Firefox's built-in
data-collection consent landed in 140, and Mozilla's guidance for a new
extension is to require it rather than to reimplement a consent prompt for
older versions.
Known gaps
- Passwords copied to the clipboard are not auto-cleared on a timer, and there is no "clear clipboard" button. Clearing the clipboard from an extension is unreliable, so v1 leaves it to you.
repromptitems require re-entering the master password before revealing a password, but the vault stays unlocked afterwards.
Development
There is no build step: the extension is the source tree.
node test/run.mjs # crypto, URL matching, generator, storage tests
npx web-ext lint # manifest + packaging validation
npx web-ext run # launch a Firefox with the add-on loaded (auto-reload)
node tools/build-xpi.mjs # package dist/vaultfox-<version>.xpi (no dependencies)
node tools/make-icons.mjs # regenerate src/icons/*.png
tools/build-xpi.mjs writes the ZIP container itself, so packaging needs
nothing but Node. npx web-ext build is the alternative if you already have
web-ext; it produces a .zip with the same contents.
Requires Node 18+ for the test runner (Node 24 is what it is developed
against). web-ext is a dev-only tool and is intentionally not a dependency of
the extension itself.
Layout and module interfaces are described in docs/SPEC.md.
Contributing
Issues and patches are welcome. Please keep the zero-dependency, no-build-step
property, run node test/run.mjs and npx web-ext lint before sending a patch,
and do not add telemetry or remote code.
License
GPL-3.0-or-later. See LICENSE.