This document outlines the security architecture, cryptographic design, threat model, and vulnerability disclosure policy for vault2fa.
vault2fa is built strictly on a zero-knowledge, local-first architecture. All cryptographic primitives rely either on the standardized, hardware-accelerated Web Crypto API (crypto.subtle) or compiled WebAssembly (hash-wasm). Plaintext secrets never leave the client's volatile runtime memory.
+-------------------------------------------------------------+
| User Master Password |
+-------------------------------------------------------------+
|
v
[ Argon2id KDF via WebAssembly ]
- Salt: 16 bytes (crypto.getRandomValues)
- Memory: 64 MiB (65,536 KiB)
- Iterations (Time): 3
- Parallelism: 1
- Key Length: 32 bytes (256-bit)
|
v
[ 256-bit Master Key ]
|
+--------------+---------------+
| |
v v
[ AES-256-GCM Encryption ] [ WebAuthn PRF Biometrics ]
- 96-bit random IV per write - Secure Enclave / TPM / FIDO2
- 128-bit Auth Tag - HKDF-SHA256 Key Derivation
- Authenticated ciphertext - Wraps Master Key at rest
| |
v v
+--------------------+ +-----------------------+
| Local Storage | | Encrypted Biometric |
| (IndexedDB via | | Key Envelope |
| Dexie) | +-----------------------+
+--------------------+
- Algorithm: Argon2id (RFC 9106 recommended profile for password hashing and memory-hard KDF).
- Implementation: WebAssembly binary via
hash-wasm. - Parameters:
- Memory cost:
64 MiB(65,536 KiB) - Time cost (iterations):
3 - Parallelism:
1thread - Salt: 16 cryptographically random bytes generated via
crypto.getRandomValues(). - Output Key Length: 32 bytes (256 bits).
- Memory cost:
- Algorithm: AES-256-GCM (Galois/Counter Mode) via
crypto.subtle. - Payload Format:
vault2fa-v1JSON envelope. - Initialization Vector (IV): 12 bytes (96 bits) of fresh entropy generated via
crypto.getRandomValues()for every encryption operation. Nonces are never reused. - Integrity Tag: 128-bit authentication tag appended to the ciphertext, preventing tampering, bit-flipping, or chosen-ciphertext attacks.
- Extension: WebAuthn
prf(Pseudo-Random Function) extension. - Mechanism:
- A platform biometric credential (Touch ID, Face ID, Windows Hello) is registered with PRF enabled and
userVerification: 'required'. - The authenticator hardware (Apple Secure Enclave, Windows Hello TPM, or Titan/YubiKey) derives an HMAC-SHA-256 output using an internal hardware secret and a per-vault 32-byte
prfSalt. - The raw PRF output is passed through HKDF-SHA256 with a fresh 16-byte random salt and context string
'vault2fa-biometric-key'to generate a 256-bit AES-GCM wrapping key. - The master key is encrypted with this wrapping key and stored in IndexedDB.
- A platform biometric credential (Touch ID, Face ID, Windows Hello) is registered with PRF enabled and
- Security Guarantee: The master key can only be recovered if the user physically validates their biometric presence on that specific hardware device. The raw PRF root secret is physically locked inside the hardware authenticator and cannot be extracted by the operating system or browser.
- Decrypted TOTP secrets exist only within the ephemeral reactive state of the running Svelte 5 application.
- When the vault is locked (manually, on tab hide, or upon auto-lock timeout):
- The derived master key buffer is explicitly zero-overwritten using
masterKey.fill(0)before its reference is dereferenced tonull. - The in-memory decrypted store (
data) is immediately set tonull. - Plaintext TOTP timers and interval tickers are cancelled.
- The derived master key buffer is explicitly zero-overwritten using
vault2fa operates under a strict Content Security Policy defined in index.html:
default-src 'self';
script-src 'self' 'wasm-unsafe-eval';
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
connect-src 'self' https://api.github.com ws: wss:;
worker-src 'self' blob:;
object-src 'none';
base-uri 'self';- Zero Telemetry: No third-party tracking, analytics, fonts, or external CDN scripts are loaded.
- Strict Egress: Outbound network requests (
connect-src) are restricted strictly to'self'(local origin / dev WebSocket) andhttps://api.github.com(only invoked if GitHub Gist sync is enabled by the user). - Execution Sandboxing:
object-src 'none'prevents Flash/Java plugins;base-uri 'self'blocks unauthorized<base>injection.
We assess threats following an adversary-centric model based on realistic attack surfaces against a web application / PWA.
- TOTP/HOTP Seeds: Shared secrets used to authenticate two-factor logins.
- Master Password & Keys: The master passphrase, derived Argon2id master key, and biometric wrapping keys.
- Third-Party Credentials: GitHub Personal Access Tokens (PATs) used for encrypted Gist synchronization.
- Metadata: Account issuers, labels, group hierarchies, and secret notes.
| Threat | Adversary Profile | Mitigation in vault2fa |
|---|---|---|
| Lost or Stolen Device (At-Rest) | Attacker gains physical possession of a locked device and extracts the IndexedDB storage file or disk image. | Mitigated: All vault records in IndexedDB are stored as AES-256-GCM ciphertexts with keys derived via Argon2id (64 MiB memory-hard). Biometric credentials wrap the key via Secure Enclave / TPM WebAuthn PRF. |
| Cloud Sync Interception / Tampering | Attacker intercepts network traffic between device and GitHub API or reads secret Gists. | Mitigated: TLS 1.3 encryption in transit + end-to-end authenticated ciphertext (vault2fa-v1). GitHub only stores the ciphertext envelope; GitHub staff or unauthorized viewers cannot read secret seeds. Gist salt matching prevents replay of disparate vaults. |
| Shoulder Surfing & Casual Viewing | An observer looks at the screen while the user is authenticating. | Mitigated: OTP codes are hidden by default with clickable reveal buttons, customizable 8-second auto-mask countdowns, and an idle auto-lock timer (default: 5 minutes). |
| Accidental Token Leak in Backups | User exports an unencrypted backup or QR kit to transfer accounts and shares it. | Mitigated: Decrypted backup exports (exportDecryptedBackup) automatically sanitize and scrub third-party API tokens (e.g. GitHub PAT). |
| Data Forgery or Bit-Flipping | Attacker attempts to modify ciphertext stored locally or remotely. | Mitigated: AES-256-GCM 128-bit authentication tag verifies cryptographic authenticity before parsing; any tampered byte results in a hard DecryptionError. |
Like any browser application or PWA, vault2fa relies on the host environment's baseline security. The following scenarios are explicitly out-of-scope for client-side defenses:
- Compromised Host / Malicious Web Server:
- Threat: If the web server or CDN hosting the application is compromised, an attacker could alter the bundled JavaScript/WASM payload delivered to the client.
- Recommendation: Users requiring immunity against hosting infrastructure compromise should self-host
vault2faon their own trusted domain or run it locally (git clone+ static file server / Docker).
- Device-Level Malware / Keyloggers / Rootkits:
- Threat: If the client operating system is infected with kernel rootkits, memory dumpers, or keyloggers, an attacker can capture keystrokes during master password entry or scrape unencrypted keys directly from browser memory while the vault is active.
- Recommendation: Run on patched, secure devices with full-disk encryption and verified OS integrity.
- Malicious Browser Extensions:
- Threat: Extensions installed in the same browser profile with unrestricted
"tabs"or"all_urls"permissions can inject scripts and read the DOM. - Recommendation: Install
vault2faas a standalone PWA or run in a clean browser profile free of untrusted third-party extensions.
- Threat: Extensions installed in the same browser profile with unrestricted
- Mobile Browser Storage Eviction:
- Threat: WebKit (iOS Safari) or Chromium may evict IndexedDB storage if local disk capacity becomes critically low or if the web app is left unopened for extended periods.
- Mitigation & Recommendation:
vault2facallsnavigator.storage.persist(). Users should always maintain an encrypted backup (.json) or configure decentralized file/Gist sync.
- Google Authenticator: Decodes standard
otpauth-migration://offline?data=...Protobuf envelopes. - Aegis Authenticator: Supports standard Aegis JSON import format.
- Bitwarden: Supports standard Bitwarden JSON export schemas.
- Plain URI Lists: Supports raw RFC 6238
otpauth://totp/...URI lists.
Warning
vault2fa is free and open-source software provided under the MIT License. While its design adheres strictly to standard cryptographic best practices (RFC 9106 Argon2id, NIST SP 800-38D AES-GCM, W3C WebAuthn Level 3 PRF) and has extensive automated test coverage, it has not yet undergone a formal, independent third-party commercial security audit.
We welcome community peer review and responsible vulnerability disclosures from security researchers.
If you discover a security vulnerability or cryptographic weakness in vault2fa, please do not open a public GitHub issue.
Please disclose it privately using one of the following methods:
- GitHub Security Advisory: Open a private draft security advisory via GitHub Security Advisories.
- Email: Send vulnerability details directly to the project maintainers at security@ii2d.com.
- A description of the vulnerability, including attack vectors and prerequisites.
- Steps to reproduce or a Proof of Concept (PoC).
- Potential impact on confidential vault data or keys.
- Browser and OS environment details.
- This is an independent open-source project maintained on a best-effort basis. Reports will be reviewed as soon as possible.
- Once confirmed, we will work to validate the issue, prepare a patch, and coordinate a responsible release.