No description
  • JavaScript 90.1%
  • CSS 5.7%
  • HTML 4.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Yarrith Devos b52bd3849b
Some checks failed
CI / test (push) Has been cancelled
v1.2.0: unlock with a PIN, and fix settings that appeared not to save
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.
2026-10-16 07:32:43 +00:00
.forgejo/workflows Vaultfox 1.0.0: independent Bitwarden/Vaultwarden client for Firefox 2026-10-12 19:26:26 +00:00
dist v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
docs v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
src v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
test v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
tools dist: package Vaultfox as a ready-to-load .xpi 2026-10-16 06:18:19 +00:00
.gitignore dist: ship the Mozilla-signed xpi 2026-10-16 06:38:29 +00:00
CHANGELOG.md v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
LICENSE Vaultfox 1.0.0: independent Bitwarden/Vaultwarden client for Firefox 2026-10-12 19:26:26 +00:00
manifest.json v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
package.json v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00
README.md v1.2.0: unlock with a PIN, and fix settings that appeared not to save 2026-10-16 07:32:43 +00:00

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 prf extension, 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 .onion origins.
  • 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.
  • reprompt items 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.