Sovereign Wallet (Browser Extension)
This page documents the standalone browser‑extension build as it exists
today. Its on‑device vault (PBKDF2 + AES‑GCM) is not yet the canonical EDH
key model, so it does not yet sync health data with the desktop app. A protocol
v2 is in design to homogenize key derivation (same mnemonic → same account
keys on every client); see the EDH-V2-HOMOGENIZED-KEYS spec. Treat the
specifics below as current‑implementation, not final protocol.
The Ever Sovereign Wallet is the client-side key-custody layer of the Ever Decentralized Health network. It is a Chrome (Manifest V3) browser extension that isolates a user's private keys from web pages, lets them create or restore a wallet, and grants websites granular, revocable access to health data.
It is fully non-custodial: all key generation and encryption happen on the user's device. Ever's services never see the recovery phrase, the private key, or the unlock password.
In EDH terms, the extension is a Device (see Devices): it holds a signing key (the account/wallet key) and an x25519 encryption keypair used to seal data shared with the wallet.
This page documents the Sovereign Wallet browser extension, whose on-device
vault uses PBKDF2 + AES-256-GCM. The open-source EDH reference library
(ever-edh-core) derives keys with Scrypt + TweetNaCl and has its own
at-rest format. Both use the same BIP-39 / BIP-44 EVM account, so a recovery
phrase resolves to the same address in either — but the encrypted vault formats
are not interchangeable.
How keys are isolated
Web pages never touch private keys directly. They communicate with the extension through a content-script bridge:
Web page ──postMessage──▶ Content script ──chrome.runtime──▶ Background (service worker)
▲ │
└────────────────── encrypted vault in chrome.storage ◀─────────────┘
Decrypted keys live only in the service worker's memory while the wallet is unlocked. They are cleared on lock, on the auto-lock timer, and whenever the service worker is torn down by the browser.
Setting up a wallet
The extension offers the same setup paths a user expects from a mainstream wallet such as MetaMask:
| Method | What you provide | Result |
|---|---|---|
| Create New Wallet | — | Generates a fresh 12-word recovery phrase |
| Import — Recovery Phrase | 12-word BIP-39 phrase | Restores the full HD wallet |
| Import — Private Key | Raw secp256k1 key (hex) | Restores a single key-only account |
| Import — JSON Keystore | Keystore file (or pasted JSON) + its password | Restores the account from an encrypted keystore |
| Sync from the Ever app | — | The web app pushes the encrypted wallet into the extension automatically |
Create
Creating a wallet generates a 12-word phrase using a cryptographically secure random source. The user is shown the phrase, asked to re-enter several of the words to confirm they saved it, and then sets a device password. Only after confirmation is the wallet written to storage.
The 12-word phrase is the only way to restore an HD wallet. Anyone who has it controls the wallet. Ever cannot recover it for you.
Import
Three import methods are supported:
- Recovery phrase — the standard cross-device method. The phrase is validated against its BIP-39 checksum before import.
- Private key — restores one account from a raw key. Accounts imported this way are not covered by a recovery phrase.
- JSON keystore — restores an account from an encrypted keystore file plus the password that protects it. If the keystore embeds a mnemonic, the full HD wallet is recovered; otherwise it is treated as a key-only account.
Private-key and bare-keystore imports cannot be restored from a 12-word phrase. Keep your own backup of the key or keystore file — it is the only way to restore that account.
Key derivation
Key derivation follows the same industry standards as MetaMask, Trust Wallet, and other BIP-compliant wallets:
| Property | Value |
|---|---|
| Mnemonic | BIP-39, 128-bit entropy (12 words), English wordlist |
| HD path | BIP-44 m/44'/60'/0'/0/0 (secp256k1, EVM account) |
| Entropy source | Platform CSPRNG (crypto.getRandomValues) |
| Encryption keypair | x25519 (Curve25519), for sealing shared data |
Because the derivation path is standard, a phrase created in the extension opens to the same address in the Ever desktop wallet, the Ever app, or any other BIP-44 wallet — and vice versa.
Vault encryption
The wallet is encrypted at rest before it is written to chrome.storage:
| Property | Value |
|---|---|
| Cipher | AES-256-GCM (authenticated) |
| Key derivation | PBKDF2-HMAC-SHA256, 600,000 iterations |
| Salt | 16 random bytes, per encryption |
| IV | 12 random bytes, per encryption |
The iteration count matches current MetaMask and OWASP (2023) guidance for PBKDF2-SHA256, making an offline brute-force of a stolen vault substantially more expensive than the older 100,000-iteration baseline.
Versioned, self-upgrading format
Encrypted bundles carry a small header so the wallet always knows how to read them:
versioned: MAGIC("EVK1") + iterations(uint32-BE) + salt(16) + iv(12) + ciphertext
legacy: salt(16) + iv(12) + ciphertext (implicitly 100,000 iterations)
When a wallet encrypted under an older, lower iteration count is unlocked, it is transparently re-encrypted at the current count and written back. Existing wallets keep working with no manual migration and no risk of lockout.
Unlocking and auto-lock
- Password — derives the AES key via PBKDF2 and decrypts the vault.
- PIN (optional) — at setup, the decrypted keys are sealed under a PIN-derived key and held only in memory-backed session storage. Unlocking with the PIN unwraps them; a wrong PIN fails the AES-GCM authentication check.
- Auto-lock — after a configurable period of inactivity (default 15 minutes) the in-memory keys are wiped and the wallet returns to a locked state.
The unlock password is never persisted — not on disk and not in session storage. The PIN convenience feature stores a copy of the keys wrapped under a PIN-derived key, in memory only, which is cleared when the browser closes.
Syncing from the Ever app
A user can also create a wallet inside the Ever Healthcare web app and have it appear in the extension automatically. The app:
- Generates (or loads) the wallet client-side.
- Encrypts it in the extension's vault format (PBKDF2 600k then AES-256-GCM) using the user's password.
- Pushes only the encrypted bundle to the extension through the content-script relay.
The plaintext recovery phrase and private key never cross the page boundary — only the encrypted bundle does. The extension can then be unlocked with the same password the user set in the app.
Standards summary
| Area | Ever Sovereign Wallet | MetaMask |
|---|---|---|
| Mnemonic | BIP-39, 12 words, CSPRNG | Same |
| Derivation | BIP-44 m/44'/60'/0'/0/0 | Same |
| Vault cipher | AES-256-GCM | Same |
| KDF | PBKDF2-SHA256, 600k | PBKDF2-SHA256, 600k |
| Phrase import | Yes | Yes |
| Private-key import | Yes | Yes |
| JSON keystore import | Yes | Yes (extension) |
| Companion-app auto-sync | Yes (same machine, encrypted) | No |
| Password persisted | No | No |
Recovery checklist
- HD wallets (created, phrase-imported, or restored from a mnemonic-bearing keystore): back up the 12-word recovery phrase.
- Key-only accounts (private-key or bare-keystore imports): back up the private key or keystore file separately — there is no recovery phrase.
- Your device password decrypts the local vault only; it is not a recovery mechanism and cannot restore a wallet on another device on its own.