Personal OTP Vault is a local-first TOTP/HOTP authenticator that runs as both a browser app and a Chrome-compatible extension popup. The project focuses on private device-side OTP generation, stricter import validation, encrypted local storage with optional biometric unlock, offline support, and practical recovery flows.
- Local-first TOTP and HOTP generation with Web Crypto (SHA-1/256/512, 6-8 digits, 15-120s periods)
- Strict
otpauth://parsing to reduce false positives - Manual entry, clipboard import, QR import, URL import, camera scan, Google Authenticator migration-QR import with preview, and Aegis/2FAS backup import through the same preview
- Optional encrypted storage using PBKDF2 (600k iterations) + AES-GCM, with automatic legacy re-encryption on unlock
- Optional biometric unlock via WebAuthn PRF (two-envelope DEK design; the passphrase always remains the recovery path)
- Auto-lock on idle, unlock throttling with exponential backoff, and undo-delete with a 10-minute tombstone
- Backup export/import with versioned checksum verification, plus a 30-day backup reminder and server time-drift check
- Single-entry QR export of the
otpauth://URI (copy URI or download PNG) in both frontends - Grouping, sorting, tags, bulk actions, copy history, pointer drag & drop reorder, and per-entry countdown rings
- Dark mode with a System/Light/Dark toggle, English/Vietnamese UI language, vendored fonts, and no third-party runtime origins
- PWA support and a Chrome extension popup
- Unit tests, frontend e2e tests, extension e2e tests, accessibility scan, and CI
- Vanilla HTML/CSS/JS with no build frameworks
- Shared domain logic in
lib/:otp.js(TOTP/HOTP engine),vault.js(KDF envelope + DEK mode),migration.js(Google Authenticator otpauth-migration),importers.js(Aegis/2FAS decoders),biometric.js(WebAuthn PRF),i18n.js(complete English + Vietnamese catalogs) jsqr(QR decoding) andqrcode(QR export) are the only runtime-bundled dependencies (installed via npm and bundled by esbuild — no CDN or third-party origin)- Vendored woff2 fonts in
fonts/keep the app shell fully self-hosted esbuildfor bundling (targets Chrome 114+, Safari 16+, Firefox 115+)Vitestfor unit tests (lib/ modules only)Playwrightfor browser, extension, offline, accessibility, and visual e2e tests
npm install
npm run buildOpen index.html through a local server or run:
npm run serve:testThen visit http://127.0.0.1:4173.
npm run build:icons
npm run build
npm run test:unit
npm run test:e2e
npm test
npm run qa:uinpm run build:icons regenerates the app and extension PNG icon assets from icon.svg.
npm run qa:ui runs the UI quality gate: axe-core accessibility scans across mobile/tablet/desktop widths plus a responsive screenshot sweep into .qa/ui-sweep/. It is wired into CI after the test job.
The extension source lives in extension/. After building, load the folder as an unpacked extension in Chromium-based browsers.
icon.svgis the single source for app branding.npm run build:iconsgenerates PWA icons inicons/and extension icons inextension/icons/.- The web app references
favicon.ico,icon.svg,icons/favicon-16x16.png,icons/favicon-32x32.png, andicons/apple-touch-icon.pngfromindex.html. favicon.icois generated separately for broader browser compatibility.
If you update icon.svg, regenerate raster assets and the .ico file:
npm run build:iconsnpm run build:icons now regenerates favicon.ico from the transparent PNG favicon sources so browser tabs do not get white corner fills.
See Code Standards for detailed conventions and development guidelines.
Suggested flow:
- Create a branch from
main - Run
npm test - Use Conventional Commits
- Open a PR against the upstream repository
- Use the PR template and include screenshots for UI changes
- GitHub Actions runs
.github/workflows/release.ymlautomatically whenextension/manifest.jsonchanges onmainormaster. package.jsonandextension/manifest.jsonmust keep the same version. CI and release automation fail fast if they drift.- Use
npm run release:prepare -- <version>to bump both files together before opening a release PR. - If the extension
versionvalue changes, the workflow builds the extension bundle, creates tagextension-v<version>, and publishes a GitHub Release. - The release attaches the packaged extension archive for that version.
- You can also trigger the same workflow manually from the Actions tab.
- Release checklist: if the release changes
app.bundle.jsorstyles.bundle.css, bumpCACHE_NAMEinsw.jsin the same release — an installed service worker only re-runs its install step (and re-caches the new APP_SHELL) when the cache name changes.
- Changelog - Release notes and compatibility caveats
- Codebase Summary - Directory layout and architecture overview
- Code Standards - Conventions and development guidelines
- System Architecture - Technical design and data flows
- Project Overview & PDR - Product requirements and goals
- Project Roadmap - Development themes and future proposals
- Offline Compatibility - Safari/iOS PWA behavior
- This repo keeps some local-only workflow files ignored from Git on purpose.
- The app is designed for trusted personal devices. Encrypted storage is strongly recommended when persistence is enabled.
- Version compatibility: vaults re-encrypted after 0.1.2 (600k PBKDF2) cannot be read by older app versions; HOTP entries in new backups degrade to TOTP in pre-0.1.3 versions; only a LIVE biometric-mode vault requires 0.1.5+ code to unlock — backups export in the standard passphrase-encrypted envelope and restore on any version.
- Encrypted backups (format v3) carry a keyed HMAC-SHA256 mac verified before decryption; the SHA-256 checksum every backup carries is integrity-only (unkeyed) — anyone holding a plain-text backup file can recompute it. Protect backup files like passwords.
- Framing protection (clickjacking) is a hosting concern: a meta CSP cannot deliver
frame-ancestors, so serve the PWA withX-Frame-Options: DENYor aCSP: frame-ancestors 'none'header. The app's meta CSP intentionally allowsconnect-src 'self' https:so the QR-image-URL import can fetch user-supplied hosts; scripts and images stay locked to'self'. - Duplicate detection matches entries by secret, digit count, and period — the label is not part of the match. A duplicate is skipped on manual add and during imports, so the same secret cannot be stored twice under different labels.