All engineering notes
Web3, Client, architecture record

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.

190Source files, extension codebase
3Isolation contexts, page, content, background
0Key exposure, keys never leave background
2Signature families, classical + post-quantum

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.

Web pageExternal

Untrusted. Can request, but holds nothing and is told nothing sensitive.

ExternalClient surfaceServiceData storeOn-chain
Signing a transaction

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

4
background workercontent scriptinjected bridgepopup UI

Source tree

6
entrypointslibpluginsshimstypesassets

Cryptography

4
BIP-32 derivationBIP-39 mnemonicsencrypted vaultpost-quantum signing

Experience

5
onboardingaccount managementapproval promptsidenticonspassword strength

Stack by layer

Extension shell

Cross-browser extension framework, Background service worker, Content script bridge

UI

React popup, Approval prompts, Animated onboarding, Password strength feedback

Cryptography

BIP-32 / BIP-39 derivation, Encrypted vault, Post-quantum signing

Chain

Network SDK, Solana support, Account identicons

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

The three contexts and what may cross between them.

Approval flow

How a signing request reaches a user and why it cannot be spoofed.

Key management

Derivation, vault encryption and recovery.
  • 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.
All 21 engineering notes