AutistMask/src/shared/state.js

// 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 { networkById } = require("./networks");
const {
    DEFAULT_STATE,
    PERSISTED_FIELDS,
    normalizePersisted,
} = require("./persistedState");

const {
    STATE_SCHEMA_VERSION,
    assertStateUsable,
    migrationNeeded,
} = require("./stateSchema");

const { storageGet, storageSet } = require("./browserApi");
const { log } = require("./log");

// The live record the proxy below guards. Everything inside this module reads
// and writes THIS object, never the proxy: the guard is for callers.
const rawState = {
    ...DEFAULT_STATE,
    // Its own object, not the one DEFAULT_STATE holds: applyChainSwitchFields()
    // mutates this map in place, and a spread copies the reference.
    networkEndpoints: {},
    currentView: null,
    selectedWallet: null,
    selectedAddress: null,
    selectedToken: null,
    viewData: {},
    viewStack: [],
};

// 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.
//
// What the guard is for is a context that READS a profile nobody put there —
// every one of the five defects was a pure read of an untouched singleton,
// answered out of DEFAULT_STATE. A context that has written into it is
// managing it deliberately (the popup does, via loadState() at boot and by
// hand thereafter), and reading back what you yourself put there is not the
// mistake being caught.
//
// The cost of that is honest and worth naming: a context that writes one field
// and then reads a different, untouched one is still served that field's
// default. Nothing closes that here — what closes it for the background is
// that the background cannot reach this module at all, which build.js asserts
// against esbuild's metafile on every build (FORBIDDEN_INPUTS in
// script/lib/forbiddenBundleInputs.js, pinned by
// tests/buildForbiddenInputs.test.js).
let adopted = false;

// Every field whose pre-load value would be a plausible-looking default rather
// than the user's data. The view scratch fields are guarded too: currentView
// and viewStack are persisted, and a save that carried their pre-load values
// would overwrite a real stored stack with an empty one.
const GUARDED_FIELDS = new Set(PERSISTED_FIELDS.concat(["hasWallet"]));

class StateNotLoadedError extends Error {
    constructor(field) {
        super(
            "state." +
                field +
                " was read before loadState(); this context has no profile" +
                " loaded and must not be served DEFAULT_STATE",
        );
        this.name = "StateNotLoadedError";
    }
}

// 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);
}

// The persisted fields as they stood at the end of this page's last
// loadState() or saveState(). saveState() diffs the live state against this
// to find only the fields THIS page actually changed.
//
// Deep-cloned, not a reference: callers mutate persisted objects and arrays
// in place (state.wallets.push(...)), and a reference baseline would mutate
// right along with `state`, so the diff would always come out empty.
let baseline = null;

function snapshotPersisted() {
    const out = {};
    for (const key of PERSISTED_FIELDS) out[key] = rawState[key];
    return out;
}

function deepEqual(a, b) {
    if (a === b) return true;
    if (typeof a !== "object" || typeof b !== "object") return false;
    if (a === null || b === null) return false;
    if (Array.isArray(a) !== Array.isArray(b)) return false;
    const aKeys = Object.keys(a);
    const bKeys = Object.keys(b);
    if (aKeys.length !== bKeys.length) return false;
    for (const key of aKeys) {
        if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
        if (!deepEqual(a[key], b[key])) return false;
    }
    return true;
}

// Stable identity for a wallet, independent of its position in the array
// (which shifts under a concurrent add/delete elsewhere) and independent of
// its mutable fields (name is user-editable; addresses gains/loses entries
// via scanning and deleteAddress.js). An "hd"/"xprv" wallet's xpub never
// changes for its lifetime and is already enforced unique
// (findWalletByXpub() in addWallet.js). A "key" wallet has no xpub, exactly
// one address for its whole lifetime (nothing ever adds to or removes from
// a key wallet's address list), and that address is already enforced
// unique (findWalletByAddress()) — so it stands in for identity there.
// Neither invariant is enforced by this function or by
// mergeListByIdentity() below — they hold only because every wallet-
// creation path in addWallet.js happens to populate one or the other before
// the wallet ever reaches state.wallets, and because canRemoveAddress() in
// walletDelete.js never lets a wallet's address list go to zero. A wallet
// with neither (an empty/legacy/corrupt record) falls back to the same
// "addr:" identity as every other such record, which is a genuine
// collision, not a proxy for one — see the collision handling in
// mergeListByIdentity().
function walletIdentity(wallet) {
    if (wallet.xpub) return "xpub:" + wallet.xpub;
    const first = wallet.addresses && wallet.addresses[0];
    return "addr:" + (first ? String(first.address).toLowerCase() : "");
}

// Stable identity for an address within one wallet's address list. An
// address is unique within its wallet and, once derived or imported, never
// changes — only whether it is present.
function addressIdentity(addr) {
    return String(addr.address).toLowerCase();
}

// Merge one array of identity-bearing objects (wallets, or the addresses
// inside one wallet) by identity rather than by array index — an index
// shifts under a concurrent insert/delete elsewhere, which would merge the
// wrong pair of objects entirely.
//
// `theirs` (fresh storage) sets the membership baseline and the order:
//   - An item this page never had baseline knowledge of, but that is in
//     `theirs`, was added by someone else — kept as-is.
//   - An item `base` had and `ours` no longer has was deleted by THIS page
//     — dropped even though `theirs` still has it (this page's own delete
//     must win over a background save that only touched leaf fields).
//   - An item present in both `ours` and `theirs` is merged leaf-by-leaf via
//     `mergeItem`, so a leaf this page changed (e.g. a renamed wallet) lands
//     on top of `theirs`' otherwise-current copy (e.g. a refreshed balance).
// Anything left in `ours` that `base` never had and `theirs` does not have
// yet is this page's own new addition — appended.
//
// `identityOf` is not guaranteed collision-free (walletIdentity() falls
// back to one shared "addr:" value for any wallet with neither an xpub nor
// a populated first address). Two records that collide under it must never
// silently collapse into one — that is exactly how this function used to
// drop a wallet, encryptedSecret included, with no error and no log. Two
// defenses:
//   - `ours` is indexed into GROUPS, not a single item per identity, so two
//     colliding live items on this page can't overwrite each other in the
//     index before the merge below even runs.
//   - A matched pair with no shared `base` entry (neither page ever agreed
//     on this identity) is only merged leaf-by-leaf when the two sides are
//     already equal. If they differ, that is not "the same record edited
//     twice", it is two different records that happen to share an identity
//     — both are kept, unmerged, rather than guessing which one is real.
function mergeListByIdentity(base, ours, theirs, identityOf, mergeItem) {
    base = base || [];
    ours = ours || [];
    theirs = theirs || [];
    const baseIndex = new Map(base.map((item) => [identityOf(item), item]));
    const oursIndex = new Map();
    for (const item of ours) {
        const id = identityOf(item);
        if (!oursIndex.has(id)) oursIndex.set(id, []);
        oursIndex.get(id).push(item);
    }

    const result = [];
    const seen = new Set();

    for (const theirItem of theirs) {
        const id = identityOf(theirItem);
        seen.add(id);
        const oursGroup = oursIndex.get(id);
        if (baseIndex.has(id) && !oursGroup) continue;
        if (oursGroup) {
            const baseItem = baseIndex.get(id);
            if (!baseItem && !deepEqual(oursGroup[0], theirItem)) {
                log.errorf(
                    "state: identity collision merging",
                    JSON.stringify(id),
                    "- keeping both records instead of dropping one",
                );
                result.push(theirItem, ...oursGroup);
            } else {
                result.push(mergeItem(baseItem, oursGroup[0], theirItem));
                for (let i = 1; i < oursGroup.length; i++) {
                    result.push(oursGroup[i]);
                }
            }
        } else {
            result.push(theirItem);
        }
    }

    for (const item of ours) {
        const id = identityOf(item);
        if (seen.has(id)) continue;
        if (!baseIndex.has(id)) result.push(item);
    }

    return result;
}

// Merge one wallet's scalar/leaf fields (name, encryptedSecret, nextIndex,
// ...) against base, then recurse into its address list by identity. `base`
// is null when this page created the wallet itself and no other page has
// (yet) produced a same-identity record — nothing to merge in that case,
// this page's own copy wins outright. mergeListByIdentity() only ever calls
// this with `!base` when `ours` and `theirs` are already equal (a genuine
// collision between two DIFFERENT same-identity records is caught and kept
// as two separate entries before this function is reached), so returning
// `ours` here can't discard a different wallet's data.
function mergeWallet(base, ours, theirs) {
    if (!base) return ours;
    const merged = { ...theirs };
    for (const key of Object.keys(ours)) {
        if (key === "addresses") continue;
        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
    }
    merged.addresses = mergeListByIdentity(
        base.addresses,
        ours.addresses,
        theirs.addresses,
        addressIdentity,
        mergeAddress,
    );
    return merged;
}

// Merge one address's leaf fields (balance, ensName, tokenBalances, ...).
// tokenBalances is itself an array, but only a balance refresh ever writes
// it and always wholesale (refreshBalances() in src/shared/balances.js), so
// there is no membership to reconcile within it — it is a leaf like balance
// or ensName, not a list with its own identity.
function mergeAddress(base, ours, theirs) {
    if (!base) return ours;
    const merged = { ...theirs };
    for (const key of Object.keys(ours)) {
        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
    }
    return merged;
}

// Merge a plain object keyed by string (allowedSites/deniedSites: address ->
// hostname list; networkEndpoints: networkId -> {rpcUrl, blockscoutUrl}) the
// same way mergeListByIdentity() merges an array — by key, not by whole-
// object diff — so a key one page added or removed applies independently of
// a key another page edited. Unlike an array's identity function, an object
// key can't collide with a different logical entry (Object.keys() is
// already deduplicated), so this needs no collision floor of its own.
function mergeMapByKey(base, ours, theirs, mergeLeaf) {
    base = base || {};
    ours = ours || {};
    theirs = theirs || {};
    const result = {};
    const seen = new Set();

    for (const key of Object.keys(theirs)) {
        seen.add(key);
        const inBase = Object.prototype.hasOwnProperty.call(base, key);
        const inOurs = Object.prototype.hasOwnProperty.call(ours, key);
        if (inBase && !inOurs) continue; // this page deleted the whole entry
        if (inOurs) {
            result[key] = mergeLeaf(base[key], ours[key], theirs[key]);
        } else {
            result[key] = theirs[key];
        }
    }

    for (const key of Object.keys(ours)) {
        if (seen.has(key)) continue;
        if (!Object.prototype.hasOwnProperty.call(base, key)) {
            result[key] = ours[key];
        }
    }

    return result;
}

// allowedSites/deniedSites: { [address]: [hostname, ...] }. The hostname
// list is itself membership, not a leaf — the background appends a newly
// approved/denied hostname to it, and the Settings "revoke" button
// (src/popup/views/settings.js) filters a hostname out of it in place, from a
// different page. Merge it the same way wallets are merged: identity is the
// hostname itself, so a merged pair is always equal and mergeItem is a no-op
// pick.
function mergeHostnameList(base, ours, theirs) {
    return mergeListByIdentity(
        base,
        ours,
        theirs,
        (hostname) => hostname,
        (b, o, t) => t,
    );
}

function mergeSiteMap(base, ours, theirs) {
    return mergeMapByKey(base, ours, theirs, mergeHostnameList);
}

// networkEndpoints: { [networkId]: {rpcUrl, blockscoutUrl} }.
// applyChainSwitchFields() (src/shared/chainSwitchFields.js) writes
// networkEndpoints[networkId] in place before saving. No code path ever
// removes a key from this map, so the membership collision that matters for
// allowedSites/wallets (an add on one page racing a delete on another) can't
// happen here — but two pages switching to two different networks
// concurrently still race a whole-field diff the same way, so it gets the same
// per-key merge for the leaf edit case (e.g. Settings saving a custom RPC URL
// for the active network).
function mergeEndpointEntry(base, ours, theirs) {
    if (!base) return ours;
    const merged = { ...theirs };
    for (const key of Object.keys(ours)) {
        if (!deepEqual(ours[key], base[key])) merged[key] = ours[key];
    }
    return merged;
}

function mergeNetworkEndpoints(base, ours, theirs) {
    return mergeMapByKey(base, ours, theirs, mergeEndpointEntry);
}

// Read-modify-write, merged per field, rather than one full-blob write.
//
// Every extension page (the toolbar popup, a dApp approval window) holds its
// own in-memory `state`, loaded once, and showView() saves on every
// navigation. A full-blob write here clobbers whatever a second page had
// written since — including, in the worst case, an entire wallet and its
// encrypted secret with no attacker and no unusual input (see the issue this
// fixes).
//
// Only the fields this page actually changed — those that differ from
// `baseline`, captured at the last loadState()/saveState() on this page —
// are written; every other field is carried forward from whatever is in
// storage right now, which may already be a value another page wrote.
//
// `wallets` is merged structurally (mergeListByIdentity(), by wallet
// identity and then by address identity within each wallet), not as one
// whole field: a balance refresh mutates wallets IN PLACE (addr.balance /
// ensName / tokenBalances, via refreshBalances()), so a whole-field diff
// would mark all of `wallets` "changed" the moment any balance moved and
// write back that page's own copy — loaded before its multi-second network
// round trip — clobbering a wallet another page added, or resurrecting one
// another page deleted, in that window. Merging by identity lets the leaf
// changes and another page's membership changes (add/delete a wallet or an
// address) apply independently instead of colliding as the same field.
//
// `allowedSites` and `deniedSites` get the same treatment (mergeSiteMap(),
// by address key and then by hostname within each address's list), for the
// identical reason: the background appends a newly approved/denied hostname
// to them, and the Settings "revoke" button (src/popup/views/settings.js)
// filters one out in place, from a different page. A whole-field diff here
// doesn't just lose data, it is a security defect — a stale page's save can
// resurrect a just-revoked site permission, or silently wipe a permission just
// granted elsewhere.
//
// `networkEndpoints` gets the same treatment too (mergeNetworkEndpoints(),
// by network id), since applyChainSwitchFields() writes into it in place; the
// value per key is a small leaf object with no membership of its own; see the
// comment at mergeEndpointEntry() for why the collision this closes is
// milder than the other two.
//
// Every other persisted field stays a whole-field diff:
// `trackedTokens`/`fraudContracts`/`viewStack` are arrays of scalars with no
// per-element identity to merge by; `tokenHolderCache` is a map shaped like
// the ones above, but nothing in src/ ever writes an entry into it — it is
// only ever reset wholesale to `{}` (applyChainSwitchFields()) — so there is
// no in-place mutation for a whole-field diff to collide with; `viewData` is
// this page's own UI scratch space, not data another page has any reason to
// share membership of.
//
// This does not make two pages that both change the SAME leaf concurrently
// safe: last write wins on that one leaf, same as before. What it removes
// is the cross-field (and now cross-membership-vs-leaf) clobber — a page
// that only navigated, or only refreshed a balance, overwriting a wallet or
// address list it never touched the membership of.
//
// This page's own live `state` is deliberately NOT rehydrated from a field
// another page changed — only the record written to storage is merged.
// showView() fires saveState() on every navigation without awaiting it,
// which is what makes the queue above necessary in the first place, and a
// save that is slow to come back has no way to tell whether the field it
// is about to hand back is still the current answer or has since been
// overtaken by something this very page did in the meantime; writing it
// into `state` regardless reintroduced exactly the clobber this function
// exists to remove, just delayed and confined to one page instead of two
// (caught by tests/txStatus.test.js). A page's live picture of a field it
// does not own goes on being whatever its last loadState() saw, same as
// before this fix; only the persisted record is guaranteed current.
async function saveStateOnce() {
    const current = snapshotPersisted();
    const result = await storageGet("autistmask");
    // The record in storage right now is about to be merged into and written
    // back, so it is validated exactly like a load validates it. Without this,
    // a page whose own load succeeded would normalize a record it does not
    // understand — one a NEWER build wrote in the meantime, say — and write
    // the result back over it, destroying the only copy of whatever that
    // record held. Refusing is louder than that and loses nothing: the live
    // state is untouched and the next save retries.
    assertStateUsable(result.autistmask);
    // Normalized, not raw: a field this page did not change still has to
    // come from storage in its loaded (self-healed) shape. See
    // normalizePersisted() in persistedState.js.
    const fresh = normalizePersisted(result.autistmask);

    const merged = { ...fresh };
    for (const key of PERSISTED_FIELDS) {
        if (key === "wallets") {
            merged.wallets = mergeListByIdentity(
                baseline ? baseline.wallets : [],
                current.wallets,
                fresh.wallets,
                walletIdentity,
                mergeWallet,
            );
        } else if (key === "allowedSites" || key === "deniedSites") {
            merged[key] = mergeSiteMap(
                baseline ? baseline[key] : {},
                current[key],
                fresh[key],
            );
        } else if (key === "networkEndpoints") {
            merged.networkEndpoints = mergeNetworkEndpoints(
                baseline ? baseline.networkEndpoints : {},
                current.networkEndpoints,
                fresh.networkEndpoints,
            );
        } else if (
            baseline === null ||
            !deepEqual(current[key], baseline[key])
        ) {
            merged[key] = current[key];
        }
    }
    merged.hasWallet = Boolean(merged.wallets && merged.wallets.length > 0);
    // Stamped on every write, never merged or diffed: the record that goes to
    // storage is in THIS build's shape whatever shape it was read in, which is
    // what migrates the unversioned records every install in the field holds.
    merged.schemaVersion = STATE_SCHEMA_VERSION;

    await storageSet({ autistmask: merged });

    // Derived from this page's own wallets, never adopted off the wire —
    // see loadState(). Everything else this page did not change is left
    // exactly as it stood; see the note above.
    rawState.hasWallet = rawState.wallets.length > 0;

    baseline = structuredClone(snapshotPersisted());
}

// showView() calls saveState() on every navigation without awaiting it, so
// two saves from the SAME page can be in flight at once — e.g. a screen
// shown, then immediately replaced before the first save's storageGet()
// round trip has come back. Left concurrent, the first save's turn would
// finish after the second's live-state mutation and then re-hydrate `state`
// from what IT read, stomping the second, later change back to a stale
// value — the same clobber this function exists to prevent, just between
// two saves on one page instead of two pages. Queuing makes every save's
// snapshot-diff-write-rehydrate run start to finish before the next one
// begins, so each one only ever sees the true live state at its turn.
let saveQueue = Promise.resolve();

function saveState() {
    const turn = saveQueue.then(saveStateOnce);
    // The queue must advance even when a save rejects, or every save after
    // it queues behind a promise that never settles.
    saveQueue = turn.catch(() => {});
    return turn;
}

// Rejects with StateUnusableError for a stored record this build cannot make
// sense of. Nothing is assigned and `loaded` stays false in that case, so a
// caller that ignores the rejection gets StateNotLoadedError on the first
// read rather than a half-populated profile. The caller that does NOT ignore
// it is the popup entry point, which shows the recovery screen
// (src/popup/views/stateRecovery.js) instead of proceeding.
async function loadState() {
    const result = await storageGet("autistmask");
    // Before normalization, on the raw bytes: normalizing first would paper
    // over the very shapes this refuses, which is how a corrupt record used to
    // reach the popup and blank it (issue #311).
    assertStateUsable(result.autistmask);
    if (migrationNeeded(result.autistmask)) {
        log.infof(
            "state: migrating an unversioned profile to schema version",
            STATE_SCHEMA_VERSION,
        );
    }
    if (result.autistmask) {
        Object.assign(rawState, normalizePersisted(result.autistmask));
    }
    // Whether storage had a profile or was empty, this context has now read
    // it, and the defaults standing in for an empty profile are the right
    // answer rather than a stand-in for one nobody looked for.
    loaded = true;
    // The point of comparison every saveState() on this page diffs against.
    // See PERSISTED_FIELDS in persistedState.js for why a reference here
    // would be wrong.
    baseline = structuredClone(snapshotPersisted());
}

// Through the guarded proxy, not rawState: a caller asking which address is
// selected before anything was loaded gets the same loud failure it would get
// reading the fields itself.
function currentAddress() {
    if (state.selectedWallet === null || state.selectedAddress === null) {
        return null;
    }
    return state.wallets[state.selectedWallet].addresses[state.selectedAddress];
}

module.exports = {
    state,
    saveState,
    loadState,
    currentAddress,
    currentNetwork,
    StateNotLoadedError,
};