AutistMask/src/shared/browserApi.js

// The one place in this tree that names `browser` or `chrome`.
//
// The two targets do not agree on the namespace, and they disagree about the
// call shape only in which one is native. Chrome MV3 exposes `chrome.*`,
// where tabs, windows and messaging take a trailing callback and report
// failure through the global `chrome.runtime.lastError`. Firefox MV2 exposes
// `browser.*`, where those same methods return promises — but, measured on
// Firefox 153.0.3, it ALSO honours a trailing Chrome-style callback, returns
// no promise when one is given, and populates `browser.runtime.lastError`.
// The callback code that predated this module therefore ran on both, and
// https://git.eeqj.de/sneak/AutistMask/issues/153 was filed on the belief
// that it did not. This module exists for uniformity, not for repair: the
// tree used to resolve the namespace with a ternary at six call sites and
// then mix promise-form storage with callback-form messaging.
//
// The strategy is promises out, everywhere: one namespace, one call shape,
// composing with the `async` handlers in the background. Callers `await`;
// nothing outside this file has to know which browser it is running on.
//
// Two deliberate asymmetries, because they are what the browsers actually do
// rather than what a uniform-looking shim would pretend:
//
//  - Storage is called in its PROMISE form on both namespaces.
//    `chrome.storage.local.get()` returns a promise on MV3 and the popup
//    already depends on that — src/shared/state.js has always awaited it.
//    Wrapping it in a callback here would be a change, not a fix.
//  - notify() sends without a callback. It is for a message whose answer
//    nobody reads; appending a callback would only manufacture a
//    lastError/rejection for a receiver that was never expected to reply.
//
// Everything is resolved on use rather than captured at module load. The MV3
// service worker is torn down and re-evaluated repeatedly, and the unit
// suite installs its stubs on `global.chrome` around a require().
//
// The module also holds withLock(), a wrapper around the browser's
// `navigator.locks`, which is in neither namespace. It sits beside
// storageGet() and storageSet() because every write of the stored record
// takes it.

// The extension API namespace, preferring `browser.*` where it exists.
//
// Whole-namespace, never per-method: mixing `browser.tabs` with
// `chrome.windows` would also mix promise and callback semantics inside a
// single call path, which is the bug this module exists to remove.
function extensionApi() {
    if (typeof browser !== "undefined" && browser) return browser;
    if (typeof chrome !== "undefined" && chrome) return chrome;
    return null;
}

// True when the resolved namespace is the promise-flavoured one.
//
// It doubles as "this is the Gecko/MV2 build", which is a second question
// with the same answer and one real caller: src/content/index.js has to
// inject the inpage provider itself there, because MV2 has no
// `"world": "MAIN"` for a manifest-declared content script.
function hasBrowserNamespace() {
    return typeof browser !== "undefined" && !!browser;
}

function namespaceMember(name) {
    const api = extensionApi();
    return (api && api[name]) || null;
}

function runtimeApi() {
    return namespaceMember("runtime");
}

function tabsApi() {
    return namespaceMember("tabs");
}

function windowsApi() {
    return namespaceMember("windows");
}

function alarmsApi() {
    return namespaceMember("alarms");
}

// The toolbar button. MV3 calls it `action`, MV2 calls it `browserAction`.
function actionApi() {
    const api = extensionApi();
    if (!api) return null;
    return api.action || api.browserAction || null;
}

// `storage.local`, or null in a context that has no storage permission.
//
// Null rather than a throw for the one caller that genuinely degrades:
// src/shared/phishingDomains.js falls back to its vendored blocklist and does
// its own null check. Everything that reads or writes the wallet goes through
// storageGet()/storageSet(), which reject instead — see there.
function storageLocal() {
    const storage = namespaceMember("storage");
    return (storage && storage.local) || null;
}

// The callback-path error channel. Read only from inside an appended
// callback, i.e. only on the `chrome.*` path, where it is the sole way a
// failure is reported. The background's three explicit lastError checks are
// gone because invoke() turns it into a rejection before any caller sees it.
function lastError() {
    const runtime = runtimeApi();
    return (runtime && runtime.lastError) || null;
}

// Call `owner[method](...args)` and return a promise for its result.
//
// On the promise namespace the method already returns one. On the callback
// namespace the callback is appended here and lastError becomes a rejection,
// because a caller holding a promise has nowhere to check a global flag.
function invoke(owner, method, ...args) {
    if (!owner || typeof owner[method] !== "function") {
        return Promise.reject(
            new Error(
                "extension API " +
                    method +
                    "() is not available in this context",
            ),
        );
    }
    if (hasBrowserNamespace()) {
        try {
            return Promise.resolve(owner[method](...args));
        } catch (e) {
            return Promise.reject(e);
        }
    }
    return new Promise((resolve, reject) => {
        owner[method](...args, (result) => {
            const err = lastError();
            if (err) reject(new Error(err.message || String(err)));
            else resolve(result);
        });
    });
}

/**
 * Send a message to the extension's own contexts and resolve with the reply.
 *
 * Rejects when nothing is listening, on both browsers. A caller that does not
 * care must say so — see notify().
 *
 * @param {Object} message
 * @returns {Promise<*>} the receiver's response.
 */
function sendMessage(message) {
    return invoke(runtimeApi(), "sendMessage", message);
}

/**
 * @returns {Promise<Object>} the operating system and processor the browser
 *     runs on.
 */
function getPlatformInfo() {
    return invoke(runtimeApi(), "getPlatformInfo");
}

/**
 * Send a message nobody is expected to answer, and swallow the fact that
 * nobody did.
 *
 * @param {Object} message
 * @returns {void}
 */
function notify(message) {
    const runtime = runtimeApi();
    if (!runtime || typeof runtime.sendMessage !== "function") return;
    const result = runtime.sendMessage(message);
    // MV3 hands back a promise for a one-argument send, and it rejects when
    // the background is not listening. Unhandled, that surfaces as an error
    // the e2e suites fail the run on.
    if (result && typeof result.catch === "function") result.catch(() => {});
}

// These two carry the wallet. A missing `storage.local` has to reject and not
// default: resolving {} would make an existing wallet read back as no wallet,
// and resolving a no-op write would discard the user's state with nothing
// logged. A caller that wants to degrade takes storageLocal() directly.
function storageUnavailable(area, method) {
    return Promise.reject(
        new Error("extension storage." + area + " is not available: " + method),
    );
}

/**
 * @param {string|string[]|Object} keys
 * @returns {Promise<Object>} the stored items.
 * @throws rejects where `storage.local` is absent.
 */
function storageGet(keys) {
    const storage = storageLocal();
    if (!storage) return storageUnavailable("local", "get");
    return Promise.resolve(storage.get(keys));
}

/**
 * @param {Object} items
 * @returns {Promise<void>}
 * @throws rejects where `storage.local` is absent.
 */
function storageSet(items) {
    const storage = storageLocal();
    if (!storage) return storageUnavailable("local", "set");
    return Promise.resolve(storage.set(items));
}

/**
 * Erase stored keys. The one caller is the destructive reset on the recovery
 * screen (src/popup/views/stateRecovery.js), which is the only way out of a
 * profile no build can read; it rejects rather than defaulting for the same
 * reason the two above do — a reset that silently did nothing would leave the
 * user in the dead end they were promised an exit from.
 *
 * @param {string|string[]} keys
 * @returns {Promise<void>}
 * @throws rejects where `storage.local` is absent.
 */
function storageRemove(keys) {
    const storage = storageLocal();
    if (!storage) return storageUnavailable("local", "remove");
    return Promise.resolve(storage.remove(keys));
}

/**
 * Call `listener` after every write to `storage.local`, whether this page,
 * another page or the background made it, with what the write changed, as the
 * browser reports it: `{ [key]: { oldValue, newValue } }`.
 *
 * @param {function(Object): void} listener
 */
function onStorageChanged(listener) {
    namespaceMember("storage").onChanged.addListener((changes, areaName) => {
        if (areaName === "local") listener(changes);
    });
}

/**
 * Run `fn` while holding the browser's lock called `name`
 * (`navigator.locks`), and settle as `fn` settles. Every page of the extension
 * and its background share these locks, except a page in a Firefox private
 * window (README, "Stored state and its version"), so while one of them holds
 * `name` another asking for it waits, in the order they asked. The lock is let
 * go when `fn` settles, whether it resolved or rejected.
 *
 * Every write of the stored record holds the lock named after its key,
 * "autistmask", from its read to its write: saveState() in
 * src/shared/state.js, updateState() in src/background/state.js, and the
 * reset in src/popup/views/stateRecovery.js.
 *
 * @param {string} name
 * @param {function(): Promise<*>} fn
 * @returns {Promise<*>} what `fn` resolved with.
 * @throws rejects, without running `fn`, where `navigator.locks` is absent.
 */
function withLock(name, fn) {
    if (typeof navigator === "undefined" || !navigator.locks) {
        return Promise.reject(
            new Error("navigator.locks is not available in this context"),
        );
    }
    return navigator.locks.request(name, () => fn());
}

// `storage.session`, the browser's session storage: what is kept there lasts
// until the browser closes. It survives the background worker being stopped
// and started again, which module-level variables do not (README, Background
// scheduling). The background keeps the connections allowed without
// "Remember" there; see src/background/index.js. Firefox has it from version
// 115, the minimum manifest/firefox.json declares.
//
// The three below reject where it is absent, as the three above do where
// `storage.local` is: a write that silently did nothing would tell a site it
// is connected and then refuse its next request.
function storageSession() {
    const storage = namespaceMember("storage");
    return (storage && storage.session) || null;
}

/**
 * @param {string|string[]|null} keys null for every item.
 * @returns {Promise<Object>} the stored items.
 * @throws rejects where `storage.session` is absent.
 */
function sessionStorageGet(keys) {
    const storage = storageSession();
    if (!storage) return storageUnavailable("session", "get");
    return Promise.resolve(storage.get(keys));
}

/**
 * @param {Object} items
 * @returns {Promise<void>}
 * @throws rejects where `storage.session` is absent.
 */
function sessionStorageSet(items) {
    const storage = storageSession();
    if (!storage) return storageUnavailable("session", "set");
    return Promise.resolve(storage.set(items));
}

/**
 * @param {string|string[]} keys
 * @returns {Promise<void>}
 * @throws rejects where `storage.session` is absent.
 */
function sessionStorageRemove(keys) {
    const storage = storageSession();
    if (!storage) return storageUnavailable("session", "remove");
    return Promise.resolve(storage.remove(keys));
}

/**
 * @param {Object} queryInfo
 * @returns {Promise<Array>} the matching tabs.
 */
function tabsQuery(queryInfo) {
    return invoke(tabsApi(), "query", queryInfo);
}

/**
 * Send a message to one tab's content script.
 *
 * Rejects for a tab that has no receiver, which is most of them. That
 * rejection is the promise-shaped replacement for the runtime.lastError
 * checks the broadcast helpers used to make, and callers ignore it the same
 * way.
 *
 * @param {number} tabId
 * @param {Object} message
 * @returns {Promise<*>}
 */
function tabsSendMessage(tabId, message) {
    return invoke(tabsApi(), "sendMessage", tabId, message);
}

/**
 * @returns {Promise<Object|undefined>} the tab the calling page is in, or
 *     undefined for a page not in a tab, such as the toolbar popup.
 */
function tabsGetCurrent() {
    return invoke(tabsApi(), "getCurrent");
}

/**
 * @param {number} tabId
 * @returns {Promise<number>} that tab's zoom: 1.5 at 150%.
 */
function tabsGetZoom(tabId) {
    return invoke(tabsApi(), "getZoom", tabId);
}

/**
 * @param {Object} createData
 * @returns {Promise<Object>} the created window.
 */
function windowsCreate(createData) {
    return invoke(windowsApi(), "create", createData);
}

/**
 * @returns {Promise<Object>} the last focused window.
 */
function windowsGetLastFocused() {
    return invoke(windowsApi(), "getLastFocused");
}

/**
 * @returns {Promise<Object>} the window the calling page is in.
 */
function windowsGetCurrent() {
    return invoke(windowsApi(), "getCurrent");
}

/**
 * @param {number} windowId
 * @param {Object} updateInfo
 * @returns {Promise<Object>} the updated window.
 */
function windowsUpdate(windowId, updateInfo) {
    return invoke(windowsApi(), "update", windowId, updateInfo);
}

/**
 * @param {number} windowId
 * @returns {Promise<void>}
 */
function windowsRemove(windowId) {
    return invoke(windowsApi(), "remove", windowId);
}

module.exports = {
    actionApi,
    alarmsApi,
    extensionApi,
    getPlatformInfo,
    hasBrowserNamespace,
    notify,
    onStorageChanged,
    runtimeApi,
    sendMessage,
    sessionStorageGet,
    sessionStorageRemove,
    sessionStorageSet,
    storageGet,
    storageLocal,
    storageRemove,
    storageSet,
    tabsApi,
    tabsGetCurrent,
    tabsGetZoom,
    tabsQuery,
    tabsSendMessage,
    windowsApi,
    windowsCreate,
    windowsGetCurrent,
    windowsGetLastFocused,
    windowsRemove,
    windowsUpdate,
    withLock,
};