harden: stop the background reading the shared state singleton, and enforce it at build time (closes #324)

Five defects, one of which destroyed every wallet, came from src/background reading and writing the module-level state singleton the MV3 worker never populates, which silently served DEFAULT_STATE. Each point fix created the next defect. The background now has its own per-call getState() and a queued read-modify-write updateState(); the singleton is unreachable from it, and an unpopulated read throws instead of serving defaults.

The prohibition is enforced by the build, not by review: build.js asserts over esbuild's own metafile that no forbidden module is an input of a background bundle, so every specifier syntax esbuild resolves is covered, and both halves of the table are checked for rot -- a stale key, a stale module, an empty list, or an unlisted entry point under src/background/ all fail the build. The ESLint rule remains as fast local feedback and reads the same shared table. Known bounds are documented where the table lives.

Also closes #320: getProvider() now requires a validated network id, so a cold worker no longer prepares a non-mainnet dApp transaction for mainnet and gets refused by the wallet's own verifier. backgroundRefresh() no longer mutates address objects across a network round trip, the broadcast path takes its endpoint and chain id from one snapshot, and eight test storage stubs now structured-clone on get as the real chrome.storage.local does.

closes #320

TODO.md

@@ -45,6 +45,50 @@ 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 `build.js`, which fails
+  the build when esbuild's own metafile reports `src/shared/state.js` as an
+  input of either background bundle — the resolution the shipped bundle was
+  actually built from, so no specifier syntax and no resolution rule can slip
+  past it, and `make build` runs in CI. A bundled entry point under
+  `src/background/` with no line in the table fails the build too, so a second
+  worker entry point is protected by default rather than only if whoever adds it
+  knows the table exists. The assertion itself is pinned by
+  `tests/buildForbiddenInputs.test.js`, including every way its table can rot: a
+  key no bundled entry point matched, a forbidden module this build bundled
+  nowhere, and an entry that lists no modules (which would otherwise empty the
+  lint rule's forbidden set as well, and is refused at require time). Its bound
+  is that it is keyed by path, so a COPY of the singleton at another path is
+  outside it — loud for three of the five defects and silent for the other two;
+  the bounds are recorded in full where the table lives
+  (`script/lib/forbiddenBundleInputs.js`). An ESLint rule that walks the require
+  graph textually gives the same answer in the editor, before a full bundle; it
+  reads the same table, and it is fast feedback rather than the guarantee. The
+  shapes it catches are pinned by `tests/backgroundStateLintRule.test.js`, and
+  so are the two it misses — a computed specifier and a symlink — as asserted
+  non-reports, which the build fails on. 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 swap always names its output token
   ([#346](https://git.eeqj.de/sneak/AutistMask/issues/346)). The `Token Out`
   detail line in `src/shared/uniswap.js` was pushed only when a symbol was

build.js

@@ -4,6 +4,11 @@ const crypto = require("crypto");
 const { execSync } = require("child_process");
 const esbuild = require("esbuild");
 const { resolveVersion } = require("./script/lib/version");
+const {
+    BACKGROUND_ENTRY_PREFIX,
+    FORBIDDEN_INPUTS,
+    assertTableWellFormed,
+} = require("./script/lib/forbiddenBundleInputs");
 
 const DIST = path.join(__dirname, "dist");
 const DIST_CHROME = path.join(DIST, "chrome");
@@ -16,6 +21,18 @@ const SRC = path.join(__dirname, "src");
 // rotting with it.
 const AUDITED_MODULE = "src/shared/constants.js";
 
+// FORBIDDEN_INPUTS — what each entry point's bundle may not contain, and what
+// that covers — lives in script/lib/forbiddenBundleInputs.js, because the
+// ESLint rule reads the same table and two literal copies of a path drift.
+//
+// This is the authoritative check, and it is here rather than in the linter
+// because it consults the resolution esbuild actually performed. Any specifier
+// syntax, any hop, any resolution rule that puts the module in the bundle fails
+// the build, whether or not a text matcher would have recognized it. A
+// background entry point the table does not name fails as well, so a second
+// worker is protected by default rather than by someone remembering this file.
+// Dockerfile:42 runs `make build`, so it is enforced in CI.
+
 // 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
@@ -65,6 +82,164 @@ function outputsContainingAuditedModule(metafile) {
         .map(([outFile]) => repoRelative(outFile));
 }
 
+// Shortest import chain from `entryInput` to `target` through the metafile's
+// own input graph, or null when there is none. The message this feeds is the
+// point of the check: "state.js is in the worker bundle" is not actionable on
+// its own, "index.js -> chainSwitchFields.js -> state.js" is.
+function importChain(metafile, entryInput, target) {
+    const graph = new Map(
+        Object.entries(metafile.inputs).map(([input, info]) => [
+            repoRelative(input),
+            (info.imports || []).map((i) => repoRelative(i.path)),
+        ]),
+    );
+    const start = repoRelative(entryInput);
+    const seen = new Set([start]);
+    const queue = [[start]];
+    while (queue.length > 0) {
+        const chain = queue.shift();
+        for (const next of graph.get(chain[chain.length - 1]) || []) {
+            if (next === target) return chain.concat([next]);
+            if (seen.has(next)) continue;
+            seen.add(next);
+            queue.push(chain.concat([next]));
+        }
+    }
+    return null;
+}
+
+// What the forbidden-input checks accumulate over a whole build: which
+// FORBIDDEN_INPUTS keys were actually bundled, and every input of every output
+// this build emitted. Both are read by assertForbiddenTableCovered() at the
+// end — a table entry naming something that is not there any more enforces
+// nothing, and must fail rather than pass quietly.
+function newForbiddenRecord() {
+    return { entriesChecked: new Set(), bundledInputs: new Set() };
+}
+
+// Note every input of every output of one esbuild run. Deliberately not
+// restricted to the entry points named in FORBIDDEN_INPUTS: it is the POPUP
+// that legitimately bundles src/shared/state.js, and that is what makes
+// "the forbidden module still exists at this path" checkable at all.
+function recordBundledInputs(metafile, record) {
+    for (const info of Object.values(metafile.outputs)) {
+        for (const input of Object.keys(info.inputs)) {
+            record.bundledInputs.add(repoRelative(input));
+        }
+    }
+}
+
+// Fail the build when an entry point's bundle contains a module it is
+// prohibited from reaching. The inputs come from esbuild's metafile, so this is
+// the resolution the shipped bundle was built from and not a guess at it.
+//
+// A background entry point with no line in the table fails here too. The five
+// defects this exists to prevent were accidents, and so is adding a second
+// worker entry point without knowing that a table somewhere needs a line: the
+// protection has to be the default for that directory rather than something
+// the next author must opt into.
+function assertNoForbiddenInputs(
+    entryPoint,
+    outfile,
+    metafile,
+    record,
+    table = FORBIDDEN_INPUTS,
+) {
+    const entry = repoRelative(entryPoint);
+    const forbidden = table[entry];
+    if (!forbidden) {
+        if (!entry.startsWith(BACKGROUND_ENTRY_PREFIX)) return;
+        throw new Error(
+            `${entry} is a background entry point with no line in ` +
+                `FORBIDDEN_INPUTS, so nothing stops its bundle from ` +
+                `containing the shared state singleton. Add it to ` +
+                `script/lib/forbiddenBundleInputs.js. The MV3 worker never ` +
+                `populates that singleton, so reading it serves ` +
+                `DEFAULT_STATE; use getState()/updateState() from ` +
+                `src/background/state.js instead.`,
+        );
+    }
+
+    const out = repoRelative(outfile);
+    const entryOutput = Object.entries(metafile.outputs).find(
+        ([outFile]) => repoRelative(outFile) === out,
+    );
+    if (!entryOutput) {
+        throw new Error(`esbuild reported no metafile output for ${out}`);
+    }
+    const inputs = new Set(
+        Object.keys(entryOutput[1].inputs).map(repoRelative),
+    );
+
+    // Recorded only once the bundle's inputs are actually in hand. Marking the
+    // entry checked any earlier — as this did — means an early return above
+    // satisfies assertForbiddenTableCovered() with a bundle nobody examined,
+    // and the coverage half cannot tell that from a real check. The lookup
+    // above is the fragile step: repoRelative() resolves against process.cwd()
+    // while esbuild's output keys are cwd-relative, so a change to where the
+    // build runs from could miss.
+    record.entriesChecked.add(entry);
+
+    for (const module of forbidden) {
+        if (!inputs.has(module)) continue;
+        const chain = importChain(metafile, entryPoint, module);
+        throw new Error(
+            `${out} bundles ${module}, which ${entry} must not reach` +
+                `${chain ? `: ${chain.join(" -> ")}` : ""}. The MV3 worker ` +
+                `never populates the shared state singleton, so reading it ` +
+                `serves DEFAULT_STATE. Use getState()/updateState() from ` +
+                `src/background/state.js instead.`,
+        );
+    }
+}
+
+// Fail the build when the table has rotted away from the tree it describes.
+// Both halves of an entry rot independently, and either one turns the whole
+// prohibition into a pass that checks nothing:
+//
+//   - the KEY, when no bundled entry point matches it: the entry point was
+//     renamed or is no longer built, and no bundle was ever tested against the
+//     list;
+//   - the MODULE, when this build bundled it nowhere: the module was renamed,
+//     moved or deleted, so "is it an input of the background bundle" is asked
+//     about a path nothing resolves to and is answered no forever. The popup
+//     legitimately bundles src/shared/state.js, which is what makes this
+//     checkable — and it is stronger than an existsSync(), because it also
+//     fails when the file is still there but has dropped out of every bundle.
+//
+// This matters concretely: https://git.eeqj.de/sneak/AutistMask/issues/311
+// rewrites this persistence layer, and a rename that quietly disarmed the
+// guarantee would put the singleton back within reach of the worker with every
+// check in the repo still green.
+//
+// The third way — an entry that lists no modules at all — is refused where the
+// table is defined, at require time, because that one also empties the ESLint
+// rule's forbidden set and so has to fail before either layer runs. It is
+// re-checked here so the build's own half does not depend on the table having
+// been loaded from that file.
+function assertForbiddenTableCovered(record, table = FORBIDDEN_INPUTS) {
+    assertTableWellFormed(table);
+    for (const [entry, modules] of Object.entries(table)) {
+        if (!record.entriesChecked.has(entry)) {
+            throw new Error(
+                `${entry} is listed in FORBIDDEN_INPUTS but was not bundled, ` +
+                    `so nothing checked it`,
+            );
+        }
+        for (const module of modules) {
+            if (record.bundledInputs.has(module)) continue;
+            throw new Error(
+                `${module} is listed in FORBIDDEN_INPUTS for ${entry}, but ` +
+                    `this build bundled it nowhere, so the prohibition names ` +
+                    `a module that is not in this tree at that path and ` +
+                    `nothing enforces it. If the module moved, move it in ` +
+                    `script/lib/forbiddenBundleInputs.js too, which both ` +
+                    `this check and the ESLint rule read.`,
+            );
+        }
+    }
+}
+
 // 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
@@ -252,6 +427,9 @@ async function build() {
     // esbuild run below and recorded in the receipt for script/verify-build.
     const auditedBundles = [];
 
+    // What the forbidden-input checks accumulate across those same runs.
+    const forbiddenRecord = newForbiddenRecord();
+
     // compile tailwind CSS
     console.log("Compiling Tailwind CSS...");
     const tailwindInput = path.join(SRC, "popup", "styles", "main.css");
@@ -293,6 +471,15 @@ async function build() {
             metafile: true,
             define,
         });
+        // Before the output is recorded as emitted: a bundle that violates a
+        // prohibition must abort the build, not be written into a receipt.
+        recordBundledInputs(result.metafile, forbiddenRecord);
+        assertNoForbiddenInputs(
+            entryPoint,
+            outfile,
+            result.metafile,
+            forbiddenRecord,
+        );
         recordEmitted(outfile);
         auditedBundles.push(...outputsContainingAuditedModule(result.metafile));
     }
@@ -349,6 +536,8 @@ async function build() {
         path.join(DIST_FIREFOX, "manifest.json"),
     );
 
+    assertForbiddenTableCovered(forbiddenRecord);
+
     // 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".
@@ -359,7 +548,27 @@ async function build() {
     console.log("Build complete: dist/chrome/ and dist/firefox/");
 }
 
-build().catch((err) => {
+// Run only as a program. Required as a module — which is how
-    console.error(`Build failed: ${err && err.message ? err.message : err}`);
+// tests/buildForbiddenInputs.test.js reaches the checks below — this file
+// builds nothing and writes nothing.
+if (require.main === module) {
+    build().catch((err) => {
+        console.error(
+            `Build failed: ${err && err.message ? err.message : err}`,
+        );
         process.exit(1);
-});
+    });
+}
+
+// Exported for tests/buildForbiddenInputs.test.js only. The prohibition these
+// three functions enforce is the guarantee behind
+// https://git.eeqj.de/sneak/AutistMask/issues/324, and `make check` does not
+// run `make build` — so they are unit tested against synthetic metafiles
+// rather than being exercised only by CI, where "it ran" is not "it works".
+module.exports = {
+    importChain,
+    newForbiddenRecord,
+    recordBundledInputs,
+    assertNoForbiddenInputs,
+    assertForbiddenTableCovered,
+};

eslint.config.js

@@ -8,6 +8,10 @@
 
 const js = require("@eslint/js");
 const globals = require("globals");
+const backgroundState = require("./script/lib/eslint/noStateSingletonInBackground");
+const {
+    BACKGROUND_ENTRY_PREFIX,
+} = require("./script/lib/forbiddenBundleInputs");
 
 // The extension APIs. MV3 Chrome exposes `chrome`; Firefox exposes both, and
 // the code feature-detects between them.
@@ -78,12 +82,36 @@ 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.
+    //
+    // It is not the guarantee: build.js asserts the same prohibition against
+    // esbuild's own metafile, from the shared table in
+    // script/lib/forbiddenBundleInputs.js. This is the early report.
+    //
+    // The glob comes from that same file, because build.js uses the prefix to
+    // decide which entry points must be listed in the table at all: the two
+    // layers must not disagree about which files are "the background".
     {
-        files: ["src/background/**/*.js"],
+        files: [`${BACKGROUND_ENTRY_PREFIX}**/*.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 +135,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 },

script/lib/eslint/noStateSingletonInBackground.js

@@ -0,0 +1,206 @@
+// 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.
+//
+// THIS RULE IS NOT THE GUARANTEE, and must not be described as one. The
+// guarantee is in build.js: FORBIDDEN_INPUTS / assertNoForbiddenInputs() fails
+// the build when esbuild's own metafile reports src/shared/state.js as an input
+// of a background bundle. That consults the resolution esbuild actually
+// performed, so no specifier syntax and no resolution rule can slip past it,
+// and Dockerfile:42 runs `make build` in CI.
+//
+// What this rule is: fast local feedback, in the editor and in `make lint`,
+// before a full bundle. It reads sources from disk and matches import
+// specifiers TEXTUALLY, so it is a best-effort approximation of module
+// resolution — a hand-rolled matcher will diverge from a real bundler, and two
+// earlier revisions of this file proved it by shipping holes (a template
+// literal, a dynamic `import()`, a comment inside the call, a directory
+// resolved through `package.json` `main`). Those are all covered now, and the
+// next divergence is caught by the build rather than by widening this again.
+//
+// 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.
+//
+// Matching textually over-approximates — a specifier inside a comment or a
+// string counts — which is the safe direction here: the failure mode is a
+// spurious error naming an exact file and line, not a silent hole.
+//
+// Two shapes this rule does NOT report, both of which the build does fail on
+// (each measured with `make lint` and `make build` on the branch that added
+// this note):
+//
+//   - a computed specifier, `require("../shared/" + "state")` — esbuild
+//     constant-folds it, so it is in the bundle and `make build` is exit 2
+//     naming src/shared/state.js, while `make lint` is exit 0. Same for
+//     `import("../shared/" + variable)`, which esbuild resolves as a glob.
+//   - a symlink to the module — esbuild reports the real path and fails the
+//     build; this rule resolves the link's own path and sees a different file.
+//
+// Both are pinned as non-reports in tests/backgroundStateLintRule.test.js, so
+// this list is a measured description of the rule rather than a claim about
+// it. They are known divergences, not things that cannot happen. A
+// matcher will keep diverging from a bundler; that is why the guarantee is the
+// build's and this rule is not widened again to chase them.
+
+const fs = require("fs");
+const path = require("path");
+
+const { FORBIDDEN_INPUTS } = require("../forbiddenBundleInputs");
+
+// The modules to keep out, repo-relative, taken from the same table build.js
+// asserts against so that the two layers cannot name different paths. A second
+// literal copy here is how a rename disarms one of them while the other still
+// looks enforced.
+const FORBIDDEN = [...new Set(Object.values(FORBIDDEN_INPUTS).flat())];
+
+// Whatever may sit between a keyword, a paren and a specifier: whitespace and
+// comments. `import(/* webpackChunkName: "x" */ "./x")` is a standard bundler
+// idiom, and an inline `/* eslint-… */` is just as ordinary, so a matcher that
+// allows only \s there is not strict, it is broken. Each alternative starts
+// with a distinct character, so this cannot backtrack quadratically.
+const GAP = "(?:\\s|/\\*[^]*?\\*/|//[^\\n]*)";
+const SPECIFIER = "[\"'`]([^\"'`]+)[\"'`]";
+
+// Both alternatives capture the specifier: call form first
+// (`require(...)`/`import(...)`), then clause form (`from "x"`, and the bare
+// side-effect `import "x"`). Nothing after the specifier is matched, so a
+// trailing comment or a trailing comma cannot break the match either.
+const SPECIFIER_RE = new RegExp(
+    `\\b(?:require|import)${GAP}*\\(${GAP}*${SPECIFIER}` +
+        `|\\b(?:from|import)${GAP}+${SPECIFIER}`,
+    "g",
+);
+
+// The `main` of a directory's package.json, as a specifier relative to that
+// directory, or null. esbuild resolves a directory through it, so a walk that
+// stops at `<dir>/index.js` reports a specifier it matched perfectly well as
+// unresolvable.
+function packageMain(dir) {
+    try {
+        const pkg = JSON.parse(
+            fs.readFileSync(path.join(dir, "package.json"), "utf8"),
+        );
+        return typeof pkg.main === "string" && pkg.main ? pkg.main : null;
+    } catch {
+        return null;
+    }
+}
+
+// Resolve a relative require to a file path, trying what node and esbuild would
+// in the order they would: the path itself, then extensions, then the directory
+// (its package.json `main`, then its index.js).
+function resolveRelative(fromFile, spec) {
+    if (!spec.startsWith(".")) return null; // a package, not our tree
+    const base = path.resolve(path.dirname(fromFile), spec);
+    const main = packageMain(base);
+    for (const candidate of [
+        base,
+        base + ".js",
+        base + ".json",
+        ...(main
+            ? [path.resolve(base, main), path.resolve(base, main) + ".js"]
+            : []),
+        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 one of the forbidden modules, or null when none is 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 (forbidden.has(next)) 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 paths are anchored.
+                const forbidden = new Set(
+                    FORBIDDEN.map((module) =>
+                        path.resolve(context.cwd, module),
+                    ),
+                );
+                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/lib/forbiddenBundleInputs.js

@@ -0,0 +1,123 @@
+// The modules a given entry point's bundle may not contain, keyed by the
+// repo-relative entry point.
+//
+// ONE table, read by both layers that act on it: build.js asserts it against
+// esbuild's own metafile (the guarantee), and
+// script/lib/eslint/noStateSingletonInBackground.js reports the same
+// prohibition in the editor (fast feedback). It lives here because a second
+// literal copy of the path is exactly how a rename disarms one layer while the
+// other still looks enforced.
+//
+// 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:
+// one page, one load at boot, one lifetime. The MV3 service worker has no
+// "once" — it is killed when idle and revived by the next message, nothing
+// loads state at module scope, and an unpopulated read was answered out of
+// DEFAULT_STATE in silence. Five defects came from that, one of which
+// destroyed a wallet (https://git.eeqj.de/sneak/AutistMask/issues/324). The
+// background has its own per-call storage layer in src/background/state.js
+// instead.
+//
+// What build.js's assertion covers, measured rather than assumed:
+//
+//   - Any import of a listed module, at any hop, in any specifier syntax,
+//     however esbuild resolved it. The check reads the input list esbuild
+//     reported for the emitted bundle, so it is the resolution the shipped
+//     file was built from and not a model of it. Measured on a computed
+//     specifier that esbuild constant-folds (`require("../shared/" +
+//     "state")`), on a computed specifier it resolves as a glob
+//     (`import("../shared/" + variable)`), and on a symlink to the module
+//     (esbuild reports the real path): each is `make build` exit 2.
+//
+//   - Every background entry point, whether or not anyone remembered to list
+//     it. A bundled entry point under BACKGROUND_ENTRY_PREFIX with no line in
+//     this table fails the build (assertNoForbiddenInputs()), so adding a
+//     second worker entry point is protected by default rather than protected
+//     only if the person adding it knew about this file. Measured: bundling
+//     src/background/worker2.js with no line here is `make build` exit 2.
+//
+//   - NOT covered: a COPY of a listed module at another path. The table is
+//     keyed by path, so `cp src/shared/state.js src/shared/stateCopy.js` plus
+//     a background require of the copy is `make build` exit 0 and `make lint`
+//     exit 0 (measured). The copy carries the singleton's own guard, so
+//     defects 1-3 of https://git.eeqj.de/sneak/AutistMask/issues/324 — a read
+//     of a field nothing loaded — become a loud StateNotLoadedError instead of
+//     a silent DEFAULT_STATE. Defects 4 and 5 do NOT: a copy also carries
+//     loadState(), and a stale read several awaits after a load, or a load
+//     detaching the objects an in-flight handler is mutating, are silent over
+//     a LOADED singleton whether it is the original or a copy. So the residual
+//     is wider than "it fails loudly". A newly WRITTEN singleton has no
+//     backstop at all.
+//
+//   - NOT covered: a background-behaving entry point outside
+//     BACKGROUND_ENTRY_PREFIX. The default protection above is keyed on that
+//     directory, which is also what eslint.config.js scopes the rule to, so a
+//     worker entry point placed somewhere else is covered by neither layer and
+//     needs its own line here.
+//
+// The ESLint rule's bounds are its own and are narrower: it matches specifiers
+// textually, so a computed specifier and a symlink to a listed module are
+// reported by the build and not by the rule. Both are pinned as non-reports in
+// tests/backgroundStateLintRule.test.js and are `make build` exit 2 (measured).
+// A second background entry point reached by one of those two shapes is
+// therefore caught by the build and not by the rule — which is the same
+// division of labour as everywhere else here, not an extra hole.
+//
+// Every way the table itself can rot is a failure rather than a quiet pass:
+//
+//   - a KEY no bundled entry point matched, and a listed MODULE this build
+//     bundled nowhere: assertForbiddenTableCovered(), at the end of a build;
+//   - an entry that lists NO modules, and a table with no entries at all:
+//     assertTableWellFormed() below, at require time — so it fails the build
+//     and the lint run alike, because the rule reads the same values and an
+//     empty list leaves it with nothing to look for.
+//
+// All of it is pinned by tests/buildForbiddenInputs.test.js.
+
+// What counts as a background entry point, and therefore must be listed above.
+// The build has no other notion of one: entry points are the paths handed to
+// bundle(), and this prefix is the narrowest rule that names the worker's
+// directory. eslint.config.js scopes the lint rule with the same prefix, from
+// this constant, so the two layers cannot disagree about what "background"
+// means.
+const BACKGROUND_ENTRY_PREFIX = "src/background/";
+
+const FORBIDDEN_INPUTS = {
+    "src/background/index.js": ["src/shared/state.js"],
+};
+
+// Refuse a table that cannot prohibit anything. An entry whose module list is
+// empty passes every check in both layers while enforcing nothing: the build
+// finds no module to look for and records the entry as checked, and the rule's
+// forbidden set — Object.values(...).flat() — comes back empty, so a plain
+// `require("../shared/state")` in the worker is green everywhere. That is a
+// one-character edit, so it fails here, where the table is defined and both
+// layers must load it, rather than in either layer's own checks.
+function assertTableWellFormed(table) {
+    const entries = Object.entries(table);
+    if (entries.length === 0) {
+        throw new Error(
+            "FORBIDDEN_INPUTS is empty, so nothing is prohibited anywhere. " +
+                "Removing the last entry disables the guarantee behind " +
+                "https://git.eeqj.de/sneak/AutistMask/issues/324.",
+        );
+    }
+    for (const [entry, modules] of entries) {
+        if (!Array.isArray(modules) || modules.length === 0) {
+            throw new Error(
+                `FORBIDDEN_INPUTS["${entry}"] lists no modules, so it ` +
+                    `prohibits nothing while still looking enforced. Give it ` +
+                    `the modules that entry point may not reach, or remove ` +
+                    `the entry.`,
+            );
+        }
+    }
+}
+
+assertTableWellFormed(FORBIDDEN_INPUTS);
+
+module.exports = {
+    BACKGROUND_ENTRY_PREFIX,
+    FORBIDDEN_INPUTS,
+    assertTableWellFormed,
+};

src/background/index.js

@@ -2,19 +2,20 @@
 // 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,
     networkById,
     networkByChainId,
 } = require("../shared/networks");
-const { onChainSwitch } = require("../shared/chainSwitch");
+const { applyChainSwitchFields } = require("../shared/chainSwitchFields");
-const {
+// The background's own storage layer. src/shared/state.js — the module-level
-    state,
+// `state` singleton, loadState() and saveState() — is deliberately NOT
-    loadState,
+// imported here and must never be: see the header of src/background/state.js.
-    saveState,
+// The build enforces it, not review: build.js fails when esbuild's metafile
-    currentNetwork,
+// reports that module as an input of this bundle (FORBIDDEN_INPUTS in
-} = require("../shared/state");
+// script/lib/forbiddenBundleInputs.js). The ESLint rule of the same name is
+// the same prohibition reported early, not the guarantee.
+const { getState, updateState } = require("./state");
 const { refreshBalances, getProvider } = require("../shared/balances");
 const { debugFetch, log } = require("../shared/log");
 const {
@@ -42,7 +43,6 @@ const {
 const {
     actionApi,
     runtimeApi,
-    storageGet,
     tabsQuery,
     tabsSendMessage,
     windowsApi,
@@ -179,21 +179,12 @@ const INTERNAL_ERROR_CODE = -32603;
 const INTERNAL_ERROR_MESSAGE =
     "AutistMask could not complete this request because of an internal error.";
 
-async function getState() {
+// The active address of a profile snapshot. Pure, and taking the snapshot as
-    const result = await storageGet("autistmask");
+// an argument rather than reading storage itself: a handler that has already
-    return (
+// read state must not answer "which account is this" from a SECOND, later read
-        result.autistmask || {
+// — the two can disagree, and the checks that compare them would then be
-            wallets: [],
+// comparing two different moments.
-            rpcUrl: DEFAULT_RPC_URL,
+function activeAddressOf(s) {
-            activeAddress: null,
-            allowedSites: {},
-            deniedSites: {},
-        }
-    );
-}
-
-async function getActiveAddress() {
-    const s = await getState();
     if (s.activeAddress) return s.activeAddress;
     // Fall back to first address
     if (s.wallets.length > 0 && s.wallets[0].addresses.length > 0) {
@@ -202,6 +193,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
@@ -210,9 +206,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 (await getState()).rpcUrl;
-    return s.rpcUrl || DEFAULT_RPC_URL;
 }
 
 function extractHostname(origin) {
@@ -553,10 +554,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" } };
     }
@@ -588,29 +605,14 @@ async function handleConnectionRequest(origin) {
 
     if (decision.approved) {
         if (decision.remember) {
-            // Reload state to get latest, add to allowed, persist
+            await rememberSiteChoice("allowedSites", activeAddress, hostname);
-            await loadState();
-            if (!state.allowedSites[activeAddress]) {
-                state.allowedSites[activeAddress] = [];
-            }
-            if (!state.allowedSites[activeAddress].includes(hostname)) {
-                state.allowedSites[activeAddress].push(hostname);
-            }
-            await saveState();
         } else {
             connectedSites[origin + ":" + activeAddress] = true;
         }
         return { result: [activeAddress] };
     } else {
         if (decision.remember) {
-            await loadState();
+            await rememberSiteChoice("deniedSites", activeAddress, hostname);
-            if (!state.deniedSites[activeAddress]) {
-                state.deniedSites[activeAddress] = [];
-            }
-            if (!state.deniedSites[activeAddress].includes(hostname)) {
-                state.deniedSites[activeAddress].push(hostname);
-            }
-            await saveState();
         }
         return {
             error: {
@@ -654,7 +656,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] || [];
@@ -667,22 +669,11 @@ async function handleRpc(method, params, origin) {
         return { result: [] };
     }
 
-    // Both answered from currentNetwork(), which reads the module-level state
+    // Both used to be answered from currentNetwork(), which reads the
-    // singleton, and nothing populates that at module scope. A worker revived
+    // module-level state singleton, and nothing populates that at module
-    // by the page's own message therefore held DEFAULT_STATE and told a page
+    // scope. A worker revived by the page's own message therefore held
-    // it was on mainnet while the user was on Sepolia
+    // DEFAULT_STATE and told a page it was on mainnet while the user was on
-    // (https://git.eeqj.de/sneak/AutistMask/issues/317).
+    // Sepolia (https://git.eeqj.de/sneak/AutistMask/issues/317).
-    //
-    // Answered from getState() rather than by loading the singleton. Any page
-    // reaches these two — neither is gated on a connection, and the injected
-    // provider sends eth_chainId on every page load — and loadState() replaces
-    // state.wallets wholesale, which would detach the address objects an
-    // in-flight backgroundRefresh() is mutating across its network round trip,
-    // so its saveState() would persist the pre-refresh balances while still
-    // stamping lastBalanceRefresh. getState() is the detached per-call storage
-    // read the other read handlers here already use.
-    // networkById(undefined) falls back to mainnet, matching the default for a
-    // profile with no stored networkId.
     if (method === "eth_chainId" || method === "net_version") {
         const s = await getState();
         const net = networkById(s.networkId);
@@ -699,7 +690,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 (
@@ -709,24 +700,25 @@ async function handleRpc(method, params, origin) {
             return { error: { code: 4100, message: "Unauthorized" } };
         }
 
-        // onChainSwitch() mutates the module-level state singleton and then
+        // The chain in force is read from the snapshot above, not from the
-        // saves every field of it, and currentNetwork() reads the same
+        // singleton: this worker may have been started by this very message,
-        // singleton. This worker may have been started by this very message:
+        // and the singleton would then be DEFAULT_STATE, so the same-chain
-        // nothing loads state at module scope, so without this the singleton
+        // check compared against mainnet whatever the user was on
-        // is DEFAULT_STATE, the same-chain check compares against the wrong
+        // (https://git.eeqj.de/sneak/AutistMask/issues/316).
-        // 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();
-
         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 };
         }
@@ -773,7 +765,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 =
@@ -799,7 +791,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" } };
 
@@ -848,7 +840,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" } };
 
@@ -904,7 +896,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);
@@ -948,10 +940,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,
             );
@@ -1039,7 +1040,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 {
@@ -1079,20 +1080,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)
+    if (now - (s.lastBalanceRefresh || 0) < RECENT_BALANCE_REFRESH_MS) return;
-        return;
+    if (s.wallets.length === 0) return;
-    if (state.wallets.length === 0) return;
+
+    const wallets = s.wallets;
     await refreshBalances(
-        state.wallets,
+        wallets,
-        state.rpcUrl,
+        s.rpcUrl,
-        state.blockscoutUrl,
+        s.blockscoutUrl,
-        state.trackedTokens,
+        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
@@ -1307,16 +1348,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
+            // The chain this attempt is on, read once — and the endpoint it
-            // refuses an artifact signed for any other chain, and the nonce
+            // will be broadcast to comes from the SAME read.
-            // record is both consulted and written under this one, so a
+            //
-            // network switch part-way through cannot make the check and the
+            // Verification below refuses an artifact signed for any other
-            // record disagree about which chain the nonce was spent on.
+            // 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();
+                const s = await getState();
-                chainId = currentNetwork().chainId;
+                networkId = s.networkId;
-                const activeAddress = await getActiveAddress();
+                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
@@ -1388,7 +1442,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,80 @@
+// 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. Concretely: the write is the WHOLE record, so
+// a popup write that lands inside that window is reverted, in every field, by
+// the record this turn read before it. That is accepted because the window is
+// one round trip long and the popup is not writing while the worker is;
+// widening it is what would make it a real hazard.
+//
+// `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.js

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

src/popup/views/addToken.js

@@ -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

@@ -179,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,
@@ -298,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

@@ -188,6 +188,7 @@ async function loadTransactions(address) {
                 ensNameMap = await resolveEnsNames(
                     counterparties,
                     state.rpcUrl,
+                    state.networkId,
                 );
             } catch {
                 ensNameMap = new Map();

src/popup/views/addressToken.js

@@ -268,6 +268,7 @@ async function loadTransactions(address, tokenId) {
                 ensNameMap = await resolveEnsNames(
                     counterparties,
                     state.rpcUrl,
+                    state.networkId,
                 );
             } catch {
                 ensNameMap = new Map();

src/popup/views/confirmTx.js

@@ -304,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;
 
@@ -386,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,
         });
@@ -454,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/send.js

@@ -202,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/settingsAddToken.js

@@ -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/txStatus.js

@@ -113,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() {

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,
+// `networkId` is REQUIRED, and is one of the ids in networks.js. It used to be
-// reads the currently selected network from extension state.
+// optional, falling back to currentNetwork() — the module-level `state`
-function getProvider(rpcUrl, networkName) {
+// singleton, which the MV3 service worker never populates. The endpoint then
-    // Lazy require to avoid circular dependency issues at module scope.
+// came out right and the static hint came out mainnet, so ethers fixed
-    const { currentNetwork } = require("./state");
+// `chainId` at 0x1 and every non-mainnet dApp send was prepared for the wrong
-    const name = networkName || currentNetwork().id;
+// chain and then refused by the wallet's own verifier
-    const net = Network.from(name);
+// (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
+// performed here so that callers (settings UI, future chain additions) all go
-// wallet_switchEthereumChain, 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);
+    const net = applyChainSwitchFields(state, 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;
 
     // --- 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/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,46 +1,42 @@
 // 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, and reading a
+// persisted field of the singleton before a load now THROWS instead of quietly
+// serving a default.
+//
+// The unreachability is enforced by the BUILD. build.js fails when esbuild's
+// own metafile reports this module as an input of a background bundle — the
+// resolution the shipped file was built from, so no specifier syntax gets past
+// it — from the table in script/lib/forbiddenBundleInputs.js, which also
+// records what that does and does not cover. The ESLint rule that reports the
+// same thing in the editor is fast feedback in front of the build, not the
+// guarantee.
 
-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 {
-const { RESTORABLE_VIEWS } = require("../popup/restorableViews");
+    DEFAULT_STATE,
+    PERSISTED_FIELDS,
+    normalizePersisted,
+} = require("./persistedState");
 
 const { storageGet, storageSet } = require("./browserApi");
 const { log } = require("./log");
 
-const DEFAULT_STATE = {
+// The live record the proxy below guards. Everything inside this module reads
-    hasWallet: false,
+// and writes THIS object, never the proxy: the guard is for callers.
-    wallets: [],
+const rawState = {
-    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 = {
     ...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,
@@ -51,161 +47,75 @@ 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
+// What the guard is for is a context that READS a profile nobody put there —
-// behind it used to be restored verbatim, so Back could walk onto a screen
+// every one of the five defects was a pure read of an untouched singleton,
-// whose content is deliberately never re-rendered — and "show-phrase" has no
+// answered out of DEFAULT_STATE. A context that has written into it is
-// Back control to leave by. Truncating at the first such entry instead of
+// managing it deliberately (the popup does, via loadState() at boot and by
-// splicing it out keeps the result a prefix of the stored stack, so every
+// hand thereafter), and reading back what you yourself put there is not the
-// surviving entry's Back target is exactly the one it had; splicing would
+// mistake being caught.
-// silently re-point the entry above the hole at a different screen.
 //
-// Filtering happens here on load rather than in saveState(): the live
+// The cost of that is honest and worth naming: a context that writes one field
-// in-session stack is legitimate (the screen really is rendered while the
+// and then reads a different, untouched one is still served that field's
-// popup is open), and only a load-side filter also repairs the stacks
+// default. Nothing closes that here — what closes it for the background is
-// already in storage, including ones written before a view left the set.
+// that the background cannot reach this module at all, which build.js asserts
-function restorableStack(stored, currentView) {
+// against esbuild's metafile on every build (FORBIDDEN_INPUTS in
-    // A stored stack that is missing or not an array keeps nothing, but it
+// script/lib/forbiddenBundleInputs.js, pinned by
-    // still goes through the never-empty rule below rather than returning
+// tests/buildForbiddenInputs.test.js).
-    // early: otherwise a corrupt stack would depend on exactly the goBack()
+let adopted = false;
-    // fallback that the explicit ["main"] exists in order not to depend on.
+
-    const source = Array.isArray(stored) ? stored : [];
+// Every field whose pre-load value would be a plausible-looking default rather
-    const cut = source.findIndex((view) => !RESTORABLE_VIEWS.has(view));
+// than the user's data. The view scratch fields are guarded too: currentView
-    const kept = cut === -1 ? source.slice() : source.slice(0, cut);
+// and viewStack are persisted, and a save that carried their pre-load values
-    // A view restored below the root still needs somewhere for Back to go.
+// would overwrite a real stored stack with an empty one.
-    if (
+const GUARDED_FIELDS = new Set(PERSISTED_FIELDS.concat(["hasWallet"]));
-        kept.length === 0 &&
+
-        currentView !== "main" &&
+class StateNotLoadedError extends Error {
-        RESTORABLE_VIEWS.has(currentView)
+    constructor(field) {
-    ) {
+        super(
-        return ["main"];
+            "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);
 }
 
-// Every field written to and read from the single "autistmask" storage key.
-// hasWallet is deliberately excluded from the diffing/merge logic below —
-// 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",
-    ]);
-
-// Turn a raw stored (or missing) record into the full, defaulted shape
-// loadState() used to assign directly onto `state`. Pulled out as a pure
-// function so 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.
-function normalizePersisted(saved) {
-    saved = saved || {};
-    const out = {};
-    out.wallets = saved.wallets || [];
-    // Derived, never trusted verbatim off storage — see loadState().
-    out.hasWallet = out.wallets.length > 0;
-    out.trackedTokens = 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 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. 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)
-            ? saved.allowedSites
-            : {};
-    out.deniedSites =
-        saved.deniedSites && !Array.isArray(saved.deniedSites)
-            ? 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 = saved.fraudContracts || [];
-    out.tokenHolderCache = 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 = saved.viewData || {};
-    out.viewStack = restorableStack(saved.viewStack, out.currentView);
-    return out;
-}
-
 // 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.
@@ -217,7 +127,7 @@ let baseline = null;
 
 function snapshotPersisted() {
     const out = {};
-    for (const key of PERSISTED_FIELDS) out[key] = state[key];
+    for (const key of PERSISTED_FIELDS) out[key] = rawState[key];
     return out;
 }
 
@@ -374,11 +284,10 @@ function mergeWallet(base, ours, theirs) {
 }
 
 // Merge one address's leaf fields (balance, ensName, tokenBalances, ...).
-// tokenBalances is itself an array, but only backgroundRefresh() ever
+// tokenBalances is itself an array, but only a balance refresh ever writes
-// writes it and always wholesale (refreshBalances() in
+// it and always wholesale (refreshBalances() in src/shared/balances.js), so
-// src/shared/balances.js), so there is no membership to reconcile within
+// there is no membership to reconcile within it — it is a leaf like balance
-// it — it is a leaf like balance or ensName, not a list with its own
+// or ensName, not a list with its own identity.
-// identity.
 function mergeAddress(base, ours, theirs) {
     if (!base) return ours;
     const merged = { ...theirs };
@@ -425,12 +334,12 @@ function mergeMapByKey(base, ours, theirs, mergeLeaf) {
 }
 
 // allowedSites/deniedSites: { [address]: [hostname, ...] }. The hostname
-// list is itself membership, not a leaf — src/background/index.js pushes a
+// list is itself membership, not a leaf — the background appends a newly
-// newly approved/denied hostname onto it in place, and the Settings "revoke"
+// approved/denied hostname to it, and the Settings "revoke" button
-// button (src/popup/views/settings.js) filters a hostname out of it in
+// (src/popup/views/settings.js) filters a hostname out of it in place, from a
-// place, from a different page. Merge it the same way wallets are merged:
+// different page. Merge it the same way wallets are merged: identity is the
-// identity is the hostname itself, so a merged pair is always equal and
+// hostname itself, so a merged pair is always equal and mergeItem is a no-op
-// mergeItem is a no-op pick.
+// pick.
 function mergeHostnameList(base, ours, theirs) {
     return mergeListByIdentity(
         base,
@@ -445,14 +354,15 @@ function mergeSiteMap(base, ours, theirs) {
     return mergeMapByKey(base, ours, theirs, mergeHostnameList);
 }
 
-// networkEndpoints: { [networkId]: {rpcUrl, blockscoutUrl} }. onChainSwitch()
+// networkEndpoints: { [networkId]: {rpcUrl, blockscoutUrl} }.
-// (src/shared/chainSwitch.js) writes state.networkEndpoints[networkId] in
+// applyChainSwitchFields() (src/shared/chainSwitchFields.js) writes
-// place before saving. No code path ever removes a key from this map, so the
+// networkEndpoints[networkId] in place before saving. No code path ever
-// membership collision that matters for allowedSites/wallets (an add on one
+// removes a key from this map, so the membership collision that matters for
-// page racing a delete on another) can't happen here — but two pages
+// allowedSites/wallets (an add on one page racing a delete on another) can't
-// switching to two different networks concurrently still race a whole-field
+// happen here — but two pages switching to two different networks
-// diff the same way, so it gets the same per-key merge for the leaf edit
+// concurrently still race a whole-field diff the same way, so it gets the same
-// case (e.g. Settings saving a custom RPC URL for the active network).
+// 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 };
@@ -468,12 +378,12 @@ function mergeNetworkEndpoints(base, ours, theirs) {
 
 // Read-modify-write, merged per field, rather than one full-blob write.
 //
-// Every extension page (the toolbar popup, a dApp approval window, the
+// Every extension page (the toolbar popup, a dApp approval window) holds its
-// background's backgroundRefresh()) holds its own in-memory `state`, loaded
+// own in-memory `state`, loaded once, and showView() saves on every
-// once, and showView() saves on every navigation. A full-blob write here
+// navigation. A full-blob write here clobbers whatever a second page had
-// clobbers whatever a second page had written since — including, in the
+// written since — including, in the worst case, an entire wallet and its
-// worst case, an entire wallet and its encrypted secret with no attacker
+// encrypted secret with no attacker and no unusual input (see the issue this
-// and no unusual input (see the issue this fixes).
+// fixes).
 //
 // Only the fields this page actually changed — those that differ from
 // `baseline`, captured at the last loadState()/saveState() on this page —
@@ -482,28 +392,27 @@ function mergeNetworkEndpoints(base, ours, theirs) {
 //
 // `wallets` is merged structurally (mergeListByIdentity(), by wallet
 // identity and then by address identity within each wallet), not as one
-// whole field: backgroundRefresh() mutates wallets IN PLACE (addr.balance /
+// 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 background's own copy — loaded before its multi-second network
+// 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
+// another page deleted, in that window. Merging by identity lets the leaf
-// background's leaf changes and another page's membership changes
+// changes and another page's membership changes (add/delete a wallet or an
-// (add/delete a wallet or an address) apply independently instead of
+// address) apply independently instead of colliding as the same field.
-// 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: src/background/index.js pushes a newly
+// identical reason: the background appends a newly approved/denied hostname
-// approved/denied hostname onto them in place, and the Settings "revoke"
+// to them, and the Settings "revoke" button (src/popup/views/settings.js)
-// button (src/popup/views/settings.js) filters one out in place, from a
+// filters one out in place, from a different page. A whole-field diff here
-// different page. A whole-field diff here doesn't just lose data, it is a
+// doesn't just lose data, it is a security defect — a stale page's save can
-// security defect — a stale page's save can resurrect a just-revoked site
+// resurrect a just-revoked site permission, or silently wipe a permission just
-// permission, or silently wipe a permission just granted elsewhere.
+// granted elsewhere.
 //
 // `networkEndpoints` gets the same treatment too (mergeNetworkEndpoints(),
-// by network id), since onChainSwitch() writes into it in place; the value
+// by network id), since applyChainSwitchFields() writes into it in place; the
-// per key is a small leaf object with no membership of its own; see 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.
 //
@@ -511,8 +420,8 @@ function mergeNetworkEndpoints(base, ours, theirs) {
 // `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 `{}` (onChainSwitch()) — so there is no
+// only ever reset wholesale to `{}` (applyChainSwitchFields()) — so there is
-// in-place mutation for a whole-field diff to collide with; `viewData` 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.
 //
@@ -539,7 +448,7 @@ async function saveStateOnce() {
     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() above.
+    // normalizePersisted() in persistedState.js.
     const fresh = normalizePersisted(result.autistmask);
 
     const merged = { ...fresh };
@@ -578,7 +487,7 @@ async function saveStateOnce() {
     // 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.
-    state.hasWallet = state.wallets.length > 0;
+    rawState.hasWallet = rawState.wallets.length > 0;
 
     baseline = structuredClone(snapshotPersisted());
 }
@@ -606,14 +515,21 @@ function saveState() {
 async function loadState() {
     const result = await storageGet("autistmask");
     if (result.autistmask) {
-        Object.assign(state, normalizePersisted(result.autistmask));
+        Object.assign(rawState, normalizePersisted(result.autistmask));
     }
-    // The point of comparison every saveState() on this page diffs against,
+    // Whether storage had a profile or was empty, this context has now read
-    // whether storage had a profile or was empty. See PERSISTED_FIELDS above
+    // it, and the defaults standing in for an empty profile are the right
-    // saveState() for why a reference here would be wrong.
+    // 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;
@@ -627,4 +543,5 @@ module.exports = {
     loadState,
     currentAddress,
     currentNetwork,
+    StateNotLoadedError,
 };

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: {
+        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];
-                },
-            },
-        },
         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, storage } = loadBackground(seededStore());
-        const { alarmsStub } = loadBackground(store);
         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/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
+    // The node the transaction is populated against is on whatever chain the
-    // approval. The node the transaction is populated against is on the same
+    // stored profile says, as it would be: switching networks switches the RPC
-    // one, as it would be: switching networks switches the RPC endpoint too.
+    // endpoint too. The background takes the network from storage per call —
-    let chain = MAINNET;
+    // 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: () =>
+        getProvider: (rpcUrl, networkId) =>
-            fakeProvider(broadcastTransaction, opts.provider, chain.num),
+            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: {
+        storage,
-            local: {
-                get: jest.fn(
-                    opts.storageGet ||
-                        (async () => ({ autistmask: persisted })),
-                ),
-                set: jest.fn(async () => {}),
-            },
-        },
         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({
+        const bg = loadBackground();
-            loadState: async () => {
-                await stalled.promise;
-                throw new Error("The wallet data could not be read.");
-            },
-        });
 
         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();
-        const bg = loadBackground({
-            loadState: async () => {
-                if (failNext) {
-                    failNext = false;
-                    throw new Error("storage unavailable");
-                }
-            },
-        });
         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,270 @@
+// 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).
+//
+// What this file does NOT do is establish that the singleton cannot reach the
+// background bundle. That is build.js's FORBIDDEN_INPUTS assertion, which reads
+// esbuild's metafile and so cannot be evaded by a syntax a matcher does not
+// know; it is pinned by tests/buildForbiddenInputs.test.js. The rule under test
+// here is fast local feedback in front of that, and these cases pin the shapes
+// it is known to catch, so a regression in the matcher is a failing test rather
+// than a quietly narrower rule.
+//
+// Every shape below was measured against a real `make build`: each one puts
+// state.js in the shipped background bundles, and each one was invisible to
+// some earlier revision of the matcher — the quoted-only regex missed the
+// backtick, the dynamic import and the `from` clause; its successor missed a
+// comment inside the call and a directory resolved through package.json `main`.
+//
+// Two shapes the rule does NOT report are pinned below as non-reports, in
+// "the divergences from the build's answer": a computed specifier such as
+// `require("../shared/" + "state")`, which esbuild constant-folds, and a
+// symlink to the module, whose real path esbuild reports. Both put state.js in
+// the shipped background bundle and both are `make build` exit 2 with
+// `make lint` exit 0 (measured). Pinning them as non-reports is what makes the
+// rule's stated bounds a measured description rather than a claim: if either
+// starts being reported, or the matcher is widened until one is, a test says
+// so. Their catch is the build's, and is pinned in
+// tests/buildForbiddenInputs.test.js against the metafile that catches it.
+
+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("the specifier syntaxes the matcher is known to catch", () => {
+    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",
+        );
+    });
+
+    // `import(/* webpackChunkName: "x" */ "./x")` is the standard bundler
+    // annotation idiom, and prettier leaves both of these exactly as written,
+    // so nothing else in the repo would object to them either.
+    test("a comment between the paren and the specifier", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'globalThis.__probe = require(/* probe */ "../shared/state").state;\n',
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/state.js",
+        );
+    });
+
+    test("a comment between the specifier and the closing paren", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'globalThis.__probe = require("../shared/state" /* probe */).state;\n',
+        });
+        expect(chainOf(lintBackground(root))).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",
+        );
+    });
+
+    // Resolution, not syntax: the specifier names a directory, and the file it
+    // resolves to is chosen by that directory's package.json `main`. A walk
+    // that only tries `<dir>/index.js` stops on a specifier it matched.
+    test("a directory resolved through its package.json main", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'globalThis.__probe = require("../shared/probepkg").state;\n',
+            "src/shared/probepkg/package.json": '{"main": "./bridge.js"}\n',
+            "src/shared/probepkg/bridge.js":
+                'const { state } = require("../state");\n' +
+                "module.exports = { state };\n",
+        });
+        expect(chainOf(lintBackground(root))).toBe(
+            "src/background/index.js -> src/shared/probepkg/bridge.js" +
+                " -> src/shared/state.js",
+        );
+    });
+});
+
+// These two are holes in the rule, and they are pinned as holes on purpose:
+// the build catches both, the rule is fast feedback in front of it, and a
+// written-down bound that nothing measures is how the previous three rounds of
+// this change ended up with claims that were false.
+describe("the divergences from the build's answer", () => {
+    test("a computed specifier is not reported (esbuild folds it; the build fails)", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'globalThis.__probe = require("../shared/" + "state").state;\n',
+        });
+        expect(lintBackground(root)).toEqual([]);
+    });
+
+    test("a symlink to the module is not reported (esbuild reports the real path)", () => {
+        const root = fixture({
+            "src/background/index.js":
+                'const { state } = require("../shared/stateLink");\n' +
+                "module.exports = { state };\n",
+        });
+        fs.symlinkSync(
+            path.join(root, "src/shared/state.js"),
+            path.join(root, "src/shared/stateLink.js"),
+        );
+        expect(lintBackground(root)).toEqual([]);
+    });
+});
+
+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/buildForbiddenInputs.test.js

@@ -0,0 +1,366 @@
+// build.js's FORBIDDEN_INPUTS assertion — the mechanical guarantee that the
+// MV3 background bundle cannot contain src/shared/state.js
+// (https://git.eeqj.de/sneak/AutistMask/issues/324).
+//
+// Why this file exists: `make check` does not run `make build`. CI executes
+// the assertion (Dockerfile runs `make build`), but executing is not testing —
+// invert its condition, or make the table lookup always come back undefined,
+// and every check in this repo stays green while the singleton walks back into
+// the worker. Five defects, one destroyed wallet, and the whole argument for
+// the scoped loud-read guard rest on this assertion, so it is pinned here.
+//
+// The subject is build.js's exported helpers plus the table's own
+// well-formedness check, driven against SYNTHETIC metafiles in esbuild's
+// shape. Nothing here shells out to a build or writes dist/: the assertion's
+// job is to read a metafile correctly, and a metafile is data. That the real
+// shapes reach it is the build's own business and is measured in the PR that
+// introduced it.
+//
+// Every vacuous pass this guarantee has been found to have is pinned below,
+// because each one was a way for `make check`, `make lint` and `make build` to
+// be green over a background bundle containing the singleton: a stale key, a
+// stale module, an entry that lists no modules, an entry recorded as checked
+// before its bundle was in hand, and a background entry point nobody added to
+// the table.
+//
+// Paths are absolute on the way in, because the helpers normalize whatever
+// esbuild gave them to repo-relative and this file should not depend on the
+// working directory jest was started from.
+
+const path = require("path");
+
+const {
+    importChain,
+    newForbiddenRecord,
+    recordBundledInputs,
+    assertNoForbiddenInputs,
+    assertForbiddenTableCovered,
+} = require("../build");
+const {
+    BACKGROUND_ENTRY_PREFIX,
+    FORBIDDEN_INPUTS,
+    assertTableWellFormed,
+} = require("../script/lib/forbiddenBundleInputs");
+
+const ROOT = path.resolve(__dirname, "..");
+const abs = (p) => path.join(ROOT, p);
+
+const ENTRY = "src/background/index.js";
+const OUT = "dist/chrome/src/background/index.js";
+const STATE = "src/shared/state.js";
+const HOP = "src/shared/chainSwitchFields.js";
+const SECOND = "src/background/worker2.js";
+const SECOND_OUT = "dist/chrome/src/background/worker2.js";
+const POPUP = "src/popup/index.js";
+const POPUP_OUT = "dist/chrome/src/popup/index.js";
+
+// The real table's shape: entry point -> modules its bundle may not contain.
+const TABLE = { [ENTRY]: [STATE] };
+
+// A metafile as esbuild emits one: `outputs[out].inputs` is the flat list of
+// every input that contributed to that output, and `inputs[file].imports` is
+// the edge list, which is what the chain walk follows.
+function metafile({ outputs = {}, imports = {} } = {}) {
+    return {
+        outputs: Object.fromEntries(
+            Object.entries(outputs).map(([out, inputs]) => [
+                abs(out),
+                {
+                    inputs: Object.fromEntries(
+                        inputs.map((input) => [
+                            abs(input),
+                            { bytesInOutput: 1 },
+                        ]),
+                    ),
+                },
+            ]),
+        ),
+        inputs: Object.fromEntries(
+            Object.entries(imports).map(([file, targets]) => [
+                abs(file),
+                { imports: targets.map((target) => ({ path: abs(target) })) },
+            ]),
+        ),
+    };
+}
+
+function check(mf, table = TABLE, record = newForbiddenRecord()) {
+    recordBundledInputs(mf, record);
+    assertNoForbiddenInputs(abs(ENTRY), abs(OUT), mf, record, table);
+    return record;
+}
+
+describe("assertNoForbiddenInputs()", () => {
+    test("a forbidden module in the bundle fails, naming the import chain", () => {
+        const mf = metafile({
+            outputs: { [OUT]: [ENTRY, HOP, STATE] },
+            imports: {
+                [ENTRY]: [HOP],
+                [HOP]: [STATE],
+            },
+        });
+
+        expect(() => check(mf)).toThrow(
+            `${OUT} bundles ${STATE}, which ${ENTRY} must not reach: ` +
+                `${ENTRY} -> ${HOP} -> ${STATE}.`,
+        );
+    });
+
+    test("a bundle without the forbidden module passes, and is recorded as checked", () => {
+        const mf = metafile({
+            outputs: { [OUT]: [ENTRY, HOP, "src/background/state.js"] },
+            imports: { [ENTRY]: [HOP, "src/background/state.js"] },
+        });
+
+        const record = check(mf);
+        expect([...record.entriesChecked]).toEqual([ENTRY]);
+        expect(record.bundledInputs.has(STATE)).toBe(false);
+    });
+
+    test("the failure still names the bundle when no import chain can be shown", () => {
+        // esbuild resolves `import("../shared/" + variable)` as a glob: the
+        // module is an input of the output, but no single edge leads to it.
+        // The message must degrade to no chain rather than crash.
+        const mf = metafile({
+            outputs: { [OUT]: [ENTRY, STATE] },
+            imports: { [ENTRY]: [] },
+        });
+
+        expect(() => check(mf)).toThrow(
+            `${OUT} bundles ${STATE}, which ${ENTRY} must not reach.`,
+        );
+    });
+
+    // The lookup this covers is the fragile step in the whole assertion:
+    // repoRelative() resolves against process.cwd() and esbuild's output keys
+    // are cwd-relative, so a change to where the build runs from, or to
+    // outfile vs outdir, makes it miss. It must be loud, and the entry must
+    // NOT already be marked checked when it does — otherwise a later edit
+    // turning this throw into an early return leaves both halves of the
+    // guarantee satisfied by a bundle nothing looked at.
+    test("an output esbuild did not report fails, and records nothing as checked", () => {
+        const mf = metafile({
+            outputs: { "dist/chrome/src/background/renamed.js": [ENTRY] },
+            imports: { [ENTRY]: [] },
+        });
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+
+        expect(() =>
+            assertNoForbiddenInputs(abs(ENTRY), abs(OUT), mf, record, TABLE),
+        ).toThrow(`esbuild reported no metafile output for ${OUT}`);
+        expect([...record.entriesChecked]).toEqual([]);
+
+        // So even if that throw became `return`, the coverage half catches it.
+        record.bundledInputs.add(STATE);
+        expect(() => assertForbiddenTableCovered(record, TABLE)).toThrow(
+            `${ENTRY} is listed in FORBIDDEN_INPUTS but was not bundled`,
+        );
+    });
+});
+
+// Finding from the fifth review of this change: adding a second worker entry
+// point is exactly the accident this guarantee exists for, and the person
+// adding one has no reason to know a table elsewhere needs a line. So the
+// default for the background directory is protected, not unprotected.
+describe("background entry points are protected by default", () => {
+    test("a bundled background entry point with no line in the table fails", () => {
+        const mf = metafile({
+            outputs: { [SECOND_OUT]: [SECOND, STATE] },
+            imports: { [SECOND]: [STATE] },
+        });
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+
+        expect(() =>
+            assertNoForbiddenInputs(
+                abs(SECOND),
+                abs(SECOND_OUT),
+                mf,
+                record,
+                TABLE,
+            ),
+        ).toThrow(
+            `${SECOND} is a background entry point with no line in ` +
+                `FORBIDDEN_INPUTS`,
+        );
+    });
+
+    test("an entry point outside the background directory needs no line", () => {
+        // The popup legitimately bundles the singleton; that is its model.
+        const mf = metafile({
+            outputs: { [POPUP_OUT]: [POPUP, STATE] },
+            imports: { [POPUP]: [STATE] },
+        });
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+
+        expect(() =>
+            assertNoForbiddenInputs(
+                abs(POPUP),
+                abs(POPUP_OUT),
+                mf,
+                record,
+                TABLE,
+            ),
+        ).not.toThrow();
+        expect([...record.entriesChecked]).toEqual([]);
+    });
+
+    test("the prefix is the one the lint rule is scoped to", () => {
+        expect(BACKGROUND_ENTRY_PREFIX).toBe("src/background/");
+        expect(SECOND.startsWith(BACKGROUND_ENTRY_PREFIX)).toBe(true);
+        expect(POPUP.startsWith(BACKGROUND_ENTRY_PREFIX)).toBe(false);
+    });
+});
+
+describe("recordBundledInputs()", () => {
+    // The sole data source for the module half of the anti-rot check, and
+    // every other case here hand-seeds what it produces. Driven for real,
+    // across two outputs, and then handed straight to the check that reads it.
+    test("records every input of every output, satisfying the module half", () => {
+        const mf = metafile({
+            outputs: {
+                [OUT]: [ENTRY, HOP],
+                [POPUP_OUT]: [POPUP, STATE],
+            },
+            imports: { [ENTRY]: [HOP], [POPUP]: [STATE] },
+        });
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+
+        expect([...record.bundledInputs].sort()).toEqual(
+            [ENTRY, HOP, POPUP, STATE].sort(),
+        );
+
+        // Nothing hand-seeded: the covered check passes on what the recorder
+        // actually collected, so a recorder that collects nothing fails here.
+        assertNoForbiddenInputs(abs(ENTRY), abs(OUT), mf, record, TABLE);
+        expect(() => assertForbiddenTableCovered(record, TABLE)).not.toThrow();
+    });
+});
+
+describe("importChain()", () => {
+    test("terminates on a cyclic input graph, and still finds the module", () => {
+        const mf = metafile({
+            imports: {
+                [ENTRY]: [HOP],
+                [HOP]: ["src/shared/log.js"],
+                // The cycle: log <-> hop, with the target one hop past it.
+                "src/shared/log.js": [HOP, STATE],
+            },
+        });
+
+        expect(importChain(mf, abs(ENTRY), STATE)).toEqual([
+            ENTRY,
+            HOP,
+            "src/shared/log.js",
+            STATE,
+        ]);
+    });
+
+    test("terminates and returns null when a cycle cannot reach the module", () => {
+        const mf = metafile({
+            imports: {
+                [ENTRY]: [HOP],
+                [HOP]: ["src/shared/log.js"],
+                "src/shared/log.js": [HOP, ENTRY],
+            },
+        });
+
+        expect(importChain(mf, abs(ENTRY), STATE)).toBeNull();
+    });
+});
+
+describe("assertForbiddenTableCovered()", () => {
+    test("the shipped table is satisfied by a build that checked it", () => {
+        const record = newForbiddenRecord();
+        record.entriesChecked.add(ENTRY);
+        // The popup bundle is what legitimately contains the singleton.
+        record.bundledInputs.add(STATE);
+
+        expect(() => assertForbiddenTableCovered(record, TABLE)).not.toThrow();
+    });
+
+    // The build this drives bundles the popup and no background entry point,
+    // because a stale key AND a bundled background entry point is now the
+    // stronger failure above — the entry point that is there but unlisted is
+    // reported by name, before the end of the build. This case is the rot that
+    // is left after that one: a key naming something this build never bundled.
+    test("a key no bundled entry point matched fails", () => {
+        const mf = metafile({
+            outputs: { [POPUP_OUT]: [POPUP] },
+            imports: { [POPUP]: [] },
+        });
+        const stale = { "src/background/renamed.js": [STATE] };
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+        assertNoForbiddenInputs(abs(POPUP), abs(POPUP_OUT), mf, record, stale);
+        record.bundledInputs.add(STATE);
+
+        expect(() => assertForbiddenTableCovered(record, stale)).toThrow(
+            "src/background/renamed.js is listed in FORBIDDEN_INPUTS but was" +
+                " not bundled, so nothing checked it",
+        );
+    });
+
+    test("a forbidden module this build bundled nowhere fails", () => {
+        // The other half of the same rot: renaming or moving the singleton
+        // leaves a table that names a path nothing resolves to any more, and
+        // every bundle then passes it vacuously.
+        const mf = metafile({
+            outputs: { [OUT]: [ENTRY] },
+            imports: { [ENTRY]: [] },
+        });
+        const stale = { [ENTRY]: ["src/shared/stateRenamed.js"] };
+        const record = check(mf, stale);
+        record.bundledInputs.add(STATE);
+
+        expect(() => assertForbiddenTableCovered(record, stale)).toThrow(
+            "src/shared/stateRenamed.js is listed in FORBIDDEN_INPUTS for" +
+                ` ${ENTRY}, but this build bundled it nowhere`,
+        );
+    });
+
+    // The third rot, and the worst of the three: an entry with an empty list
+    // is checked, is bundled, names no module that could be missing, and
+    // prohibits nothing — in BOTH layers at once, since the rule's forbidden
+    // set is Object.values(table).flat().
+    test("an entry that lists no modules fails", () => {
+        const mf = metafile({
+            outputs: { [OUT]: [ENTRY, STATE] },
+            imports: { [ENTRY]: [STATE] },
+        });
+        const empty = { [ENTRY]: [] };
+        const record = newForbiddenRecord();
+        recordBundledInputs(mf, record);
+        assertNoForbiddenInputs(abs(ENTRY), abs(OUT), mf, record, empty);
+
+        expect(() => assertForbiddenTableCovered(record, empty)).toThrow(
+            `FORBIDDEN_INPUTS["${ENTRY}"] lists no modules`,
+        );
+    });
+});
+
+describe("assertTableWellFormed()", () => {
+    // Runs at require time on the shipped table, in script/lib/
+    // forbiddenBundleInputs.js, so an empty list fails the lint run as well as
+    // the build — the build's own re-check cannot help a layer that never
+    // reaches the build.
+    test("the shipped table is well formed", () => {
+        expect(() => assertTableWellFormed(FORBIDDEN_INPUTS)).not.toThrow();
+        expect(Object.entries(FORBIDDEN_INPUTS).length).toBeGreaterThan(0);
+    });
+
+    test("an entry that lists no modules fails, naming the entry", () => {
+        expect(() => assertTableWellFormed({ [ENTRY]: [] })).toThrow(
+            `FORBIDDEN_INPUTS["${ENTRY}"] lists no modules`,
+        );
+    });
+
+    test("a table with no entries at all fails", () => {
+        expect(() => assertTableWellFormed({})).toThrow(
+            "FORBIDDEN_INPUTS is empty",
+        );
+    });
+});

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;
+// The endpoint half of that issue lives in tests/networkEndpoints.test.js,
-// this file mocks the state module, which that one exercises for real.
+// 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
+// chain-switch and persistence modules behind it, and return the handles to
-// wallet state is a plain object so that a switch that DID happen is visible
+// drive it.
-// as a mutation of it, and one that did not is visible as its absence.
 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: {
+        storage,
-            local: {
-                get: jest.fn(async () => ({ autistmask: persisted })),
-                set: jest.fn(async () => {}),
-            },
-        },
         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().networkId).toBe("mainnet");
-        expect(bg.walletState.rpcUrl).toBe(CUSTOM_RPC);
+        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/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
+// Load the background worker with the real chain-switch and persistence
-// behind it, over a storage stub that actually keeps what is written — a
+// modules behind it, over a storage stub that actually keeps what is written —
-// wipe is only observable against storage that remembers.
+// 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: {
+        storage,
-            local: {
-                get: jest.fn(async () => ({ autistmask: store.autistmask })),
-                set: jest.fn(async (items) => {
-                    store.autistmask = items.autistmask;
-                }),
-            },
-        },
         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

@@ -13,13 +13,15 @@
 // 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 a real store that
+// That makes the storage stub load-bearing, so it is the shared one from
-// structured-clones on both `set` and `get`. A stub whose `get` hands back
+// tests/support/storageStub.js, a real store that structured-clones on both
-// the same object its `set` was given aliases the caller's own array: the
+// `set` and `get`. A stub whose `get` hands back the same object its `set`
-// test then reads its own in-memory mutation and calls it persistence, and
+// was given aliases the caller's own array: the test then reads its own
-// passes against a build that persists nothing (see issue #324). The
+// in-memory mutation and calls it persistence, and passes against a build
-// aliasing is closed off explicitly by the first test below rather than
+// that persists nothing
-// left as an assumption about `structuredClone`.
+// (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
@@ -34,6 +36,7 @@ jest.mock("../src/shared/vault", () => ({
 }));
 
 const { RESTORABLE_VIEWS } = require("../src/popup/restorableViews");
+const { makeStorageStub } = require("./support/storageStub");
 
 const VIEW = "delete-wallet-lost-password";
 
@@ -94,35 +97,6 @@ function makeDocument() {
     };
 }
 
-// --------------------------------------------------------- storage stub
-
-// A store that behaves the way `chrome.storage.local` does: what goes in is
-// serialized, so the caller keeps no handle on what came to rest there, and
-// what comes out is a fresh object the caller may mutate freely.
-function makeStorage() {
-    let store = {};
-    return {
-        get: async (keys) => {
-            const wanted =
-                keys === undefined || keys === null
-                    ? Object.keys(store)
-                    : [].concat(keys);
-            const out = {};
-            for (const key of wanted) {
-                if (key in store) out[key] = structuredClone(store[key]);
-            }
-            return out;
-        },
-        set: async (items) => {
-            for (const [key, value] of Object.entries(items)) {
-                store[key] = structuredClone(value);
-            }
-        },
-        // Test-only: what the extension would find on a cold start.
-        _raw: () => structuredClone(store),
-    };
-}
-
 // ------------------------------------------------------------ harness
 
 function wallet(name, secret, addresses) {
@@ -144,10 +118,10 @@ function load() {
     jest.resetModules();
     mockSettingsShow.mockClear();
 
-    const storage = makeStorage();
+    const storage = makeStorageStub();
     const sent = [];
     globalThis.chrome = {
-        storage: { local: storage },
+        storage: { local: storage.local },
         runtime: { sendMessage: (msg) => sent.push(msg) },
     };
     globalThis.document = makeDocument();
@@ -205,7 +179,7 @@ async function openLostPassword(deleteWallet, walletIdx) {
 // 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 = makeStorage();
+        const storage = makeStorageStub();
         const written = { wallets: [{ name: "Wallet 1" }] };
 
         await storage.set({ autistmask: written });
@@ -393,8 +367,8 @@ describe("deleting without the password", () => {
 
         // The deleted wallet's secret is gone from storage entirely, not
         // merely unreferenced by the wallet list.
-        expect(JSON.stringify(storage._raw())).not.toContain("secret-two");
+        expect(JSON.stringify(storage.read())).not.toContain("secret-two");
-        expect(JSON.stringify(storage._raw())).not.toContain("xpub-Wallet 2");
+        expect(JSON.stringify(storage.read())).not.toContain("xpub-Wallet 2");
     });
 
     test("only the deleted wallet's site permissions are dropped", async () => {
@@ -462,7 +436,7 @@ describe("deleting without the password", () => {
         expect(saved.activeAddress).toBeNull();
         expect(saved.allowedSites).toEqual({});
         expect(state.currentView).toBe("welcome");
-        expect(JSON.stringify(storage._raw())).not.toContain("secret-one");
+        expect(JSON.stringify(storage.read())).not.toContain("secret-one");
     });
 });
 

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;
+    const storage = makeStorageStub(persisted ? { autistmask: persisted } : {});
-    global.chrome = {
+    global.chrome = { storage };
-        storage: {
-            local: {
-                get: jest.fn(async () =>
-                    persisted ? { autistmask: persisted } : {},
-                ),
-                set: jest.fn(async (items) => {
-                    written = items.autistmask;
-                }),
-            },
-        },
-    };
     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 = {};
+        storage = makeStorageStub();
-        global.chrome = {
+        global.chrome = { storage };
-            storage: {
-                local: {
-                    get: async (key) =>
-                        key in store ? { [key]: store[key] } : {},
-                    set: async (obj) => Object.assign(store, obj),
-                },
-            },
-        };
         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 () => {});
+    const storage = makeStorageStub(persisted ? { autistmask: persisted } : {});
-    global.chrome = {
+    global.chrome = { storage };
-        storage: {
+    return {
-            local: {
+        mod: require("../src/shared/state"),
-                get: jest.fn(async () =>
+        set: storage.set,
-                    persisted ? { autistmask: persisted } : {},
+        stored: () => storage.read("autistmask"),
-                ),
-                set,
-            },
-        },
     };
-    return { mod: require("../src/shared/state"), set };
 }
 
 afterEach(() => {

tests/stateMerge.test.js

@@ -10,32 +10,12 @@
 //
 // 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 storage stub structured-clones
+// pages share one chrome.storage.local. The shared stub structured-clones on
-// on both get and set — a stub that hands back the object it was given
+// both get and set — a stub that hands back the object it was given aliases
-// aliases the caller's own mutation and would make this entire defect class
+// the caller's own mutation and would make this entire defect class invisible
-// invisible (see https://git.eeqj.de/sneak/AutistMask/issues/324).
+// (see https://git.eeqj.de/sneak/AutistMask/issues/324).
 
-function makeStorage() {
+const { makeStorageStub } = require("./support/storageStub");
-    let store = {};
-    return {
-        get: async (keys) => {
-            const wanted =
-                keys === undefined || keys === null
-                    ? Object.keys(store)
-                    : [].concat(keys);
-            const out = {};
-            for (const key of wanted) {
-                if (key in store) out[key] = structuredClone(store[key]);
-            }
-            return out;
-        },
-        set: async (items) => {
-            for (const [key, value] of Object.entries(items)) {
-                store[key] = structuredClone(value);
-            }
-        },
-    };
-}
 
 // 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
@@ -43,7 +23,7 @@ function makeStorage() {
 // singleton, so each page needs its own registry to hold its own copy.
 function loadPage(storage) {
     jest.resetModules();
-    globalThis.chrome = { storage: { local: storage } };
+    globalThis.chrome = { storage: { local: storage.local } };
     return {
         state: require("../src/shared/state"),
         helpers: require("../src/popup/views/helpers"),
@@ -118,7 +98,7 @@ describe("a save from a page that never saw a wallet another page added", () =>
     // 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 = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({ autistmask: { wallets: [W1] } });
 
         // Loaded while storage held only Wallet 1, and never reloads —
@@ -171,7 +151,7 @@ describe("the approval-window reproduction", () => {
     test("the wallet added in the popup survives confirming the approval", async () => {
         globalThis.document = makeDocument();
 
-        const storage = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({ autistmask: { wallets: [W1] } });
 
         // The background opens the approval window on the approve-tx
@@ -223,7 +203,7 @@ describe("the approval-window reproduction", () => {
 // 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 = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({ autistmask: { wallets: [W1] } });
 
         // "background": loads first, and its save is the one that lands
@@ -263,7 +243,7 @@ describe("background refresh racing a wallet added on another page", () => {
 
 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 = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({ autistmask: { wallets: [W1, W2] } });
 
         const background = loadPage(storage);
@@ -324,7 +304,7 @@ function revokeSite(pageState, hostname) {
 
 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 = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({
             autistmask: {
                 wallets: [W1],
@@ -362,7 +342,7 @@ describe("a dApp approval racing a stale Settings page's later save", () => {
 
 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 = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({
             autistmask: {
                 wallets: [W1],
@@ -413,7 +393,7 @@ function legacyWallet(name, secret) {
 
 describe("two wallets independently created with a colliding identity", () => {
     test("both survive, encryptedSecret included, instead of one silently replacing the other", async () => {
-        const storage = makeStorage();
+        const storage = makeStorageStub();
         await storage.set({ autistmask: { wallets: [W1] } });
 
         // Both pages load before either has created their malformed wallet,

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.
+// default settings can be asserted against what the README promises. Empty
-global.chrome = { storage: { local: {} } };
+// 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 = {};
+// Clones in both directions, as the real chrome.storage.local does; the stub
-global.chrome = {
+// here used to hand back the live stored object, so an in-memory mutation
-    storage: {
+// looked like a write that had reached storage. See
-        local: {
+// tests/support/storageStub.js.
-            set: (obj) => {
+const { makeStorageStub } = require("./support/storageStub");
-                Object.assign(stored, obj);
+
-                return Promise.resolve();
+const storage = makeStorageStub();
-            },
+global.chrome = { storage };
-            get: () => Promise.resolve(stored),
-        },
-    },
-};
 
 const txStatus = require("../src/popup/views/txStatus");
 const { state } = require("../src/shared/state");