System overview
Each installation keeps its own encrypted vault on the device. The web application and extension can work locally, synchronize through your own servers, or use Online Services for managed connections and encrypted backups.
The server hosting the web application delivers its code and assets. Vault operations run in the browser. Hosting the application and providing synchronization services are separate responsibilities; the self-hosting guide covers deploying both.
See Cryptography for encryption and key details, and the Threat model for security assumptions.
Shared vault core
Both applications use @cryptex-industries/vault-core. It defines the vault records and serialized format, implements vault encryption and import/export, and handles device linking and synchronization.
The core runs inside each client, not as a central server. Platform adapters supply browser-specific facilities such as session handling, logging, local key storage, and access to Online Services. The web application and extension provide their own interfaces and decide where those operations run.
Sharing the format and protocol lets a web vault synchronize with an extension vault. They still have separate local storage and unlocked sessions, even when installed in the same browser. Linking connects those installations; it does not give them a shared database.
Inside the web application
The web application runs its vault interface and operations in the browser page. It uses IndexedDB, through Dexie, to persist encrypted vault records in vaultDB. This database belongs to the web application's origin and browser profile.
- Unlock
- The client reads the encrypted record and opens it locally. The unlocked vault and active data-encryption key remain in page memory for the session.
- Edit and save
- A write coordinator queues mutations, including incoming synchronization changes. Each operation reads the latest local state, applies its change, and persists the encrypted result before publishing the new state to the interface.
- Lock
- Locking joins the same queue after pending writes. After saving, it closes synchronization connections and clears the active vault and key from application state.
The write coordinator belongs to one page context. Separate tabs have separate queues, so it does not coordinate concurrent edits to the same vault across tabs.
The page also runs the connection controller for linked devices. With Online Services enabled, a backup coordinator prepares encrypted snapshots for upload. Those are separate paths: synchronization exchanges records with another live client, while a backup stores a snapshot for restoration.
Inside the Chromium Extension
The extension uses Manifest V3 and divides work between its service worker, extension pages, and scripts on visited websites. The service worker handles vault operations; the popup and linking page send it requests rather than writing the vault database themselves.
- Service worker
- Processes vault reads and writes, manages the unlocked session, and handles privileged requests such as autofill and account operations. Encrypted vault records are persisted in the extension's IndexedDB storage.
- Session storage
- The unlocked vault and active key material use
chrome.storage.session. This browser-managed, memory-backed state lets a restarted worker resume the session. Closing the popup is therefore different from locking the vault. - Extension pages
- The popup displays the vault interface. Extension pages also run linking and live peer connections, forwarding vault changes to the worker for persistence. An unlocked worker session alone is not a continuously running synchronization connection.
- Website integration
- Content scripts detect input fields, and autofill frames display credential choices. They send messages to the worker, which checks the requesting context and permitted operation. Autofill inserts the selected username and password into the website's fields.
The visited website is outside the extension's own pages and storage. For the detailed message checks and website interaction boundaries, see the Threat model. For autofill instructions, see the extension user guide.
Implementation references
- Shared core
- Vault schema, platform runtime, and write coordinator.
- Web application
- Local storage, mutation persistence, and lock lifecycle.
- Extension
- Service worker, session key storage, and autofill routing.