OnePass

OnePass is a local-first offline password manager. The main web app runs entirely on the machine, stores account and vault data locally in the browser, and encrypts vault items on the client with Web Crypto. A companion browser extension adds capture-and-save plus autofill flows for login forms.

The original FastAPI/PostgreSQL backend remains in the repository as legacy code, but it is not required for the offline local workflow.

Overview

The product includes:

• Local account signup and login
• Local device session handling
• Client-side master password flow for vault unlock
• Encrypted local vault items for logins, secure notes, and cards
• Search, filters, favorites, copy actions, and detail editing
• Built-in password generator with passphrase mode
• Client-side security dashboard for weak, reused, and old passwords
• Browser extension for:
  • detecting submitted login credentials
  • prompting the user to save them locally
  • showing saved suggestions for the current site
  • autofilling saved credentials into forms
• Portable vault export/import between the web app and extension

Security Model

OnePass separates local authentication from vault encryption.

1. The user creates an account password and a separate master password.
2. The account password is verified locally on the device.
3. The master password never leaves the browser or extension.
4. During signup, the browser:
   • generates a random AES vault key
   • derives a wrapping key from the master password using PBKDF2 + SHA-256
   • encrypts the vault key locally with AES-GCM
5. Vault items are encrypted in the browser with the decrypted vault key before they are stored locally.
6. The machine stores ciphertext, IVs, timestamps, type, and favorite metadata. No cloud service is required for the local workflow.

Architecture

Frontend

• App Router Next.js app with Tailwind styling
• AuthProvider handles local sign-in state
• VaultProvider keeps the decrypted vault key in memory only and encrypts/decrypts vault items on the client
• Protected app shell with routes:
  • /signup
  • /login
  • /vault
  • /vault/new
  • /vault/[id]
  • /security
  • /settings

Browser Extension

• Manifest V3 extension under [extension](/e:/MyProjects/Password Manager/extension)
• Detects submitted login forms with password fields
• Stores pending save candidates locally in the extension runtime
• Lets the user unlock a local encrypted extension vault
• Suggests site-matching logins in the popup
• Autofills username/password into the active tab
• Imports and exports the same portable OnePass vault format used by the web app

Key offline files:

• [frontend/lib/local-data.ts](/e:/MyProjects/Password Manager/frontend/lib/local-data.ts)
• [frontend/components/providers/auth-provider.tsx](/e:/MyProjects/Password Manager/frontend/components/providers/auth-provider.tsx)
• [frontend/components/providers/vault-provider.tsx](/e:/MyProjects/Password Manager/frontend/components/providers/vault-provider.tsx)
• [frontend/app/settings/page.tsx](/e:/MyProjects/Password Manager/frontend/app/settings/page.tsx)
• [extension/popup.js](/e:/MyProjects/Password Manager/extension/popup.js)

Local Setup

Offline web app

cd frontend
npm install
npm run dev -- --port 3001

Then open http://localhost:3001.

Browser extension

1. Open Chromium-based browser extension settings.
2. Enable Developer mode.
3. Choose Load unpacked.
4. Select [extension](/e:/MyProjects/Password Manager/extension).
5. Open the extension popup and create a master password for the extension vault.

Portable Vault Bridge

The web app and the extension are still separate local stores, but they now share a portable vault file format.

Export from the web app to the extension

1. Sign in to the web app and unlock your vault.
2. Open /settings.
3. Click Export portable vault.
4. Open the extension popup and unlock it.
5. Click Import and choose the exported JSON file.

Export from the extension to the web app

1. Open the extension popup and unlock it.
2. Click Export.
3. In the web app, unlock your vault.
4. Open /settings.
5. Click Import portable vault and choose the exported JSON file.

Duplicates are skipped using a simple fingerprint based on item type, title, username, website, and password.

Extension Testing Flow

Use this quick test after loading the extension:

1. Open the web app and create at least one login item.
2. Export it from /settings.
3. Import that file into the extension popup.
4. Visit any site with a login form.
5. Open the extension popup and confirm the imported site entry appears when the hostname matches.
6. Submit a login form manually.
7. Open the extension popup again and confirm the captured login appears under Captured login.
8. Save it and test Autofill.

GitHub Push Prep

The repo is prepared for GitHub push with ignores for local/runtime artifacts such as:

• .local-postgres/
• .next/
• node_modules/
• *.log
• *.err.log
• local .env files

Before pushing, run:

git status

and confirm only source files are being tracked.

Tradeoffs

• The web app local vault and extension local vault are offline and local, but they are still separate stores.
• The portable vault bridge is manual import/export, not automatic sync.
• Autofill suggestions are delivered from the extension popup and content script flow, not with native browser-password-manager UI privileges.
• Search is client-side, which preserves privacy better but requires decrypted items in memory after unlock.
• PBKDF2 is used in the browser for compatibility with Web Crypto.
• The optional backend in this repository is no longer needed for local-only usage.

Verification

Recommended check:

cd frontend && npm run build

Important Constraint Summary

• Raw vault passwords are not stored in plaintext.
• Raw master passwords are not sent to any cloud service.
• Account authentication for the offline web app is verified locally on the device.
• Password generation uses browser cryptographic randomness.