Post-Quantum Browser Wallet Extension
A wallet extension has an unusual threat model: it runs inside pages it does not trust, so the interesting engineering is all about isolation. Private keys live encrypted in the background service worker and never enter a content script or a page context. Every signing request crosses a message boundary and surfaces as an explicit user approval. On top of that isolation work sits the same signature-agility idea used elsewhere in the ecosystem — an account can be backed by a post-quantum scheme without changing how the wallet is used.
Repository shape
Cross-browser extension built on a modern extension framework, with popup UI, background worker and injected bridge
How this is presented
Documented as an architecture record. A wallet's value claim is its isolation model, which is a design story rather than a demo.
Why a page can never reach a key
Follow a signing request across the trust boundary. The key stays put; only a signature travels back.
Untrusted. Can request, but holds nothing and is told nothing sensitive.
Four boundary crossings, one of them human.
Highlights
- Private keys live only in the background service worker — never in a content script, never in a page.
- Every signing request crosses an explicit message boundary and requires user approval.
- Accounts can be bound to post-quantum signature schemes without changing the user-facing flow.
- Encrypted vault with password-strength feedback at creation time, when it actually matters.
- Standard hierarchical derivation, so a recovery phrase remains portable to other wallets.
- Deterministic account identicons, giving users a visual check against address substitution.
Three contexts, one trust boundary
The extension deliberately splits into a page context it does not trust, a content script that only relays, and a background worker that holds everything sensitive. Nothing valuable crosses toward the page — only signed results do.
Injected bridge
The API a web page sees. Requests accounts and signatures; holds nothing.
- Runs in the untrusted page context.
- Can only ask — it has no access to keys or the vault.
Content script
Relays messages between the page and the background worker.
- Pure transport with no secrets of its own.
- Keeps the page and the extension in separate worlds.
Background worker
Holds the encrypted vault, derives keys, signs, and owns all persistent state.
- The only context where key material is ever decrypted.
- Signing requires an approval that originates in extension UI, not in the page.
Popup UI
Onboarding, account management and the approval prompts themselves.
- Approval prompts render in extension chrome, so a page cannot fake them.
- Password strength feedback and identicons help users catch mistakes early.
Extension structure
The entrypoints directory is the security boundary: each entrypoint runs in a different context, and only one of them may ever touch key material. 19 units across 4 groups.
Entrypoints
4Source tree
6Cryptography
4Experience
5Stack by layer
Extension shell
UI
Cryptography
Chain
Delivered work
Security model
- Three-context isolation with keys confined to the background worker.
- Approval prompts rendered in extension chrome, immune to page spoofing.
- Encrypted vault with creation-time password strength feedback.
- Post-quantum signature scheme support alongside classical accounts.
Wallet experience
- Onboarding, account management and recovery flows.
- Standard hierarchical derivation for cross-wallet portability.
- Deterministic identicons as a visual guard against address substitution.
- Animated onboarding and transaction feedback.
Key modules
Context isolation
The entire security argument.
- Keys never enter a context the page can reach.
- The content script is deliberately powerless.
Approval surface
Keeps the human in the loop, verifiably.
- Rendered outside the page so it cannot be forged.
Signature agility
Post-quantum accounts without a different user flow.
- Same interaction, different mathematics underneath.
Presentation approach
How this project is presented
- Isolation model shown as a flow, since it is the security claim.
- No distributable build — a wallet should be installed from an official listing, not a portfolio page.
- Verified file counts.
Documentation and notes
Isolation model
Approval flow
Key management
- Network and organisation names are intentionally omitted.
- The isolation guarantee depends on keys never crossing into the content script — that boundary is the whole design.
- Scale figures are counted from the repository.