Skip to content

The design language that makes your AI harness better at design.

JavaScript

Fix Firefox extension scanner startup (#996)

Magerc63b8dd7dd5a
diff --git a/extension/background/service-worker.js b/extension/background/service-worker.js
index 8d64272af..4e833acd1 100644
--- a/extension/background/service-worker.js
+++ b/extension/background/service-worker.js
@@ -3,10 +3,10 @@
*
* Routes messages between popup, DevTools panel, and content scripts.
* Maintains per-tab state and updates the badge. Also owns the offscreen
- * document that hosts the WebAssembly rule core: the content script measures
- * the page (a snapshot), the offscreen document runs the rules over it, the
- * content script draws the result. Neither the popup nor the DevTools panel
- * see any of that; their messages are unchanged.
+ * document that hosts the WebAssembly rule core (a background-page iframe in
+ * Firefox): the content script measures the page (a snapshot), that document
+ * runs the rules over it, and the content script draws the result. Neither the
+ * popup nor the DevTools panel see any of that; their messages are unchanged.
*/
// Per-tab state: { tabId: { findings, overlaysVisible, injected } }
@@ -75,25 +75,39 @@ async function buildScanConfig() {
return config;
}
-// The offscreen document hosting the WASM core. One per extension; created
-// on the first scan and kept (its rule core stays warm; a closed document
-// would pay the module load again on the next scan).
+// One rule-core document per extension, loaded lazily on the first scan.
+// Chrome's service worker uses an offscreen document. Firefox has a DOM-backed
+// background event page instead, so it can host the same extension document in
+// a hidden iframe. Both keep WASM under the extension CSP, not the scanned page's.
let offscreenReady = null;
async function ensureOffscreenDocument() {
if (offscreenReady) return offscreenReady;
offscreenReady = (async () => {
- const contexts = await chrome.runtime.getContexts({
- contextTypes: ['OFFSCREEN_DOCUMENT'],
- documentUrls: [chrome.runtime.getURL(OFFSCREEN_URL)],
- });
- if (contexts.length === 0) {
- await chrome.offscreen.createDocument({
- url: OFFSCREEN_URL,
- // The document exists to run WebAssembly, which no page-side world can
- // under a strict page CSP; WORKERS is the closest listed reason.
- reasons: ['WORKERS'],
- justification: 'Runs the WebAssembly anti-pattern rule core over a page snapshot; page Content-Security-Policies block WebAssembly in content-script and page worlds.',
+ if (typeof chrome.offscreen?.createDocument === 'function') {
+ const contexts = await chrome.runtime.getContexts({
+ contextTypes: ['OFFSCREEN_DOCUMENT'],
+ documentUrls: [chrome.runtime.getURL(OFFSCREEN_URL)],
});
+ if (contexts.length === 0) {
+ await chrome.offscreen.createDocument({
+ url: OFFSCREEN_URL,
+ // The document exists to run WebAssembly, which no page-side world can
+ // under a strict page CSP; WORKERS is the closest listed reason.
+ reasons: ['WORKERS'],
+ justification: 'Runs the WebAssembly anti-pattern rule core over a page snapshot; page Content-Security-Policies block WebAssembly in content-script and page worlds.',
+ });
+ }
+ } else {
+ // Firefox's getContexts exists, but OFFSCREEN_DOCUMENT is not a valid
+ // context type there. Do not call it on this path.
+ if (typeof document === 'undefined') throw new Error('No supported rule-core document host');
+ if (!document.getElementById('impeccable-core')) {
+ const frame = document.createElement('iframe');
+ frame.id = 'impeccable-core';
+ frame.hidden = true;
+ frame.src = chrome.runtime.getURL(OFFSCREEN_URL);
+ document.body.appendChild(frame);
+ }
}
// Wait for the core to be instantiated so the first scan does not race it.
for (let attempt = 0; attempt < 50; attempt++) {
@@ -110,7 +124,7 @@ async function ensureOffscreenDocument() {
}
await new Promise(res => setTimeout(res, 50));
}
- throw new Error('offscreen core did not answer');
+ throw new Error('rule core did not answer');
})();
offscreenReady.catch(() => { offscreenReady = null; });
return offscreenReady;
diff --git a/scripts/build-extension.js b/scripts/build-extension.js
index 4c3cde134..c5c6ba78d 100644
--- a/scripts/build-extension.js
+++ b/scripts/build-extension.js
@@ -16,11 +16,8 @@
* declared as an event-page `scripts` entry (the universally-supported path on
* Gecko), and `browser_specific_settings.gecko` is added for AMO signing.
*
- * Firefox caveat: the shell runs the WebAssembly rule core in an extension
- * offscreen document, and Gecko has no `chrome.offscreen` API, so the Firefox
- * package builds and lints but cannot scan until that gap is closed. The
- * Firefox artifact is still produced so `web-ext lint` keeps covering the
- * shared shell.
+ * Chrome hosts the WebAssembly rule core in an offscreen document; Firefox
+ * loads the same document in a hidden iframe inside its background event page.
*
* Needs a Rust toolchain and wasm-pack for step 1. CI matrices that already
* ran `cargo xtask bundle` can skip it with IMPECCABLE_EXTENSION_SKIP_BUNDLE=1,
@@ -151,9 +148,10 @@ const firefoxManifest = {
...chromeManifest,
// Gecko supports MV3 via non-persistent event pages. Declaring `scripts`
// (rather than `service_worker`) is the path supported across all MV3 Firefox
- // releases; service-worker.js uses only top-level listeners + an in-memory
- // Map, so it runs unchanged as an event page.
+ // releases. The shared worker hosts the rule core in a background-page
+ // iframe when Chrome's offscreen API is unavailable.
background: { scripts: [serviceWorker] },
+ permissions: chromeManifest.permissions.filter(permission => permission !== 'offscreen'),
// Required by AMO for signing/distribution. Ignored by Chrome.
browser_specific_settings: {
gecko: {
@@ -164,7 +162,7 @@ const firefoxManifest = {
// everything else this extension uses (MV3 action, scripting, devtools,
// object-form web_accessible_resources, storage.sync) landed long before.
strict_min_version: '140.0',
- // The rules run in the extension's own offscreen document; nothing is
+ // The rules run in the extension's own document; nothing is
// transmitted off-device.
data_collection_permissions: { required: ['none'] },
},
@@ -188,9 +186,3 @@ console.log(`Staged ${path.relative(ROOT, ffStageDir)}/ (Firefox manifest)`);
// STORE_LISTING.md is already filtered out of the stage dir above.
packZip(path.join(DIST, 'extension-firefox.zip'), ffStageDir, ['*.DS_Store']);
-
-console.warn(
- 'Warning: the Firefox package cannot scan yet. The rule core runs in an ' +
- 'extension offscreen document and Gecko has no chrome.offscreen API. The ' +
- 'artifact is built so web-ext lint keeps covering the shared shell.',
-);
diff --git a/tests/extension-build.test.mjs b/tests/extension-build.test.mjs
index bb13de7a5..cdc9e9d36 100644
--- a/tests/extension-build.test.mjs
+++ b/tests/extension-build.test.mjs
@@ -3,9 +3,153 @@ import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
+import vm from 'node:vm';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// Run the real worker with browser API boundaries replaced. Firefox exposes
+// getContexts, but rejects OFFSCREEN_DOCUMENT before the scan can start.
+function scannerHarness({ firefox = false, existingHost = false, failFirstCreate = false, ping } = {}) {
+ const runtimeMessages = [];
+ const tabMessages = [];
+ const frames = [];
+ let creates = 0;
+ let ready = existingHost;
+ const event = () => ({ addListener() {} });
+ const chrome = {
+ runtime: {
+ onMessage: event(), onConnect: event(),
+ getURL: (file) => `moz-extension://test/${file}`,
+ async getContexts(filter) {
+ if (firefox) throw new Error('Invalid enumeration value "OFFSCREEN_DOCUMENT"');
+ assert.deepEqual(Array.from(filter.contextTypes), ['OFFSCREEN_DOCUMENT']);
+ return ready ? [{}] : [];
+ },
+ async sendMessage(message) {
+ runtimeMessages.push(message);
+ if (message.action === 'ping') return ping ? ping() : { ok: ready };
+ },
+ },
+ scripting: { async executeScript() {} },
+ storage: { sync: { async get(defaults) { return defaults; } } },
+ tabs: {
+ onRemoved: event(),
+ async sendMessage(tabId, message) { tabMessages.push({ tabId, ...message }); },
+ },
+ };
+ function create() {
+ creates++;
+ if (failFirstCreate && creates === 1) throw new Error('host creation failed');
+ ready = true;
+ }
+ const document = firefox ? {
+ getElementById: (id) => frames.find(frame => frame.id === id) || null,
+ createElement(tag) { assert.equal(tag, 'iframe'); return {}; },
+ body: { appendChild(frame) { create(); frames.push(frame); } },
+ } : undefined;
+ if (!firefox) chrome.offscreen = { async createDocument() { create(); } };
+ const context = vm.createContext({ chrome, document, setTimeout });
+ vm.runInContext(readFileSync(path.join(ROOT, 'extension/background/service-worker.js'), 'utf8'), context);
+ return { context, frames, runtimeMessages, tabMessages, creates: () => creates };
+}
+
+describe('extension rule core startup', () => {
+ it('scans in Firefox without calling its unsupported offscreen APIs', async () => {
+ const h = scannerHarness({ firefox: true });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.tabMessages.length, 1, JSON.stringify(h.runtimeMessages));
+ assert.equal(h.tabMessages[0].action, 'scan');
+ assert.equal(h.frames.length, 1);
+ assert.equal(h.frames[0].src, 'moz-extension://test/offscreen/offscreen.html');
+ assert.equal(h.frames[0].hidden, true);
+ });
+
+ for (const firefox of [false, true]) {
+ const browser = firefox ? 'Firefox' : 'Chrome';
+ it(`shares one core host across concurrent and repeated ${browser} scans`, async () => {
+ const h = scannerHarness({ firefox });
+ await vm.runInContext('Promise.all([sendScanToTab(7), sendScanToTab(8)])', h.context);
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.creates(), 1);
+ assert.deepEqual(h.tabMessages.map(m => m.tabId), [7, 8, 7]);
+ });
+
+ it(`reports ${browser} host failures and retries on the next scan`, async () => {
+ const h = scannerHarness({ firefox, failFirstCreate: true });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.tabMessages.length, 0);
+ assert.match(h.runtimeMessages.find(m => m.action === 'scan-failed')?.message || '', /host creation failed/);
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.tabMessages.length, 1);
+ assert.equal(h.creates(), 2);
+ });
+
+ it(`waits for the ${browser} core to answer before scanning`, async () => {
+ let answer;
+ const h = scannerHarness({ firefox, ping: () => new Promise(resolve => { answer = resolve; }) });
+ const scan = vm.runInContext('sendScanToTab(7)', h.context);
+ await new Promise(resolve => setImmediate(resolve));
+ assert.equal(h.tabMessages.length, 0);
+ answer({ ok: true });
+ await scan;
+ assert.equal(h.tabMessages.length, 1);
+ });
+
+ it(`surfaces ${browser} WASM startup errors instead of reporting a clean page`, async () => {
+ const h = scannerHarness({ firefox, ping: () => ({ ok: false, error: 'WASM failed to load' }) });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.tabMessages.length, 0);
+ assert.match(h.runtimeMessages.find(m => m.action === 'scan-failed')?.message || '', /WASM failed to load/);
+ });
+
+ it(`retries while the ${browser} core message listener is not registered`, async () => {
+ let pings = 0;
+ const h = scannerHarness({ firefox, ping: () => {
+ assert.equal(h.tabMessages.length, 0, 'scan must wait for a successful ping');
+ if (++pings <= 2) throw new Error('Could not establish connection. Receiving end does not exist.');
+ return { ok: true };
+ } });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(pings, 3);
+ assert.equal(h.creates(), 1);
+ assert.deepEqual(h.tabMessages.map(m => [m.tabId, m.action]), [[7, 'scan']]);
+ assert.equal(h.runtimeMessages.filter(m => m.action === 'scan-failed').length, 0);
+ });
+
+ it(`reports exhausted ${browser} startup retries and recovers on the next scan`, async () => {
+ let listenerReady = false;
+ let pings = 0;
+ const h = scannerHarness({ firefox, ping: () => {
+ pings++;
+ if (!listenerReady) throw new Error('Could not establish connection. Receiving end does not exist.');
+ return { ok: true };
+ } });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(pings, 50);
+ assert.equal(h.tabMessages.length, 0);
+ const failures = h.runtimeMessages.filter(m => m.action === 'scan-failed');
+ assert.equal(failures.length, 1);
+ assert.equal(failures[0].tabId, 7);
+ assert.match(failures[0].message, /rule core did not answer/);
+
+ listenerReady = true;
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(pings, 51, 'a failed startup must not leave a cached rejected promise');
+ assert.equal(h.creates(), 1, 'reuse the existing core host');
+ assert.deepEqual(h.tabMessages.map(m => [m.tabId, m.action]), [[7, 'scan']]);
+ assert.equal(h.runtimeMessages.filter(m => m.action === 'scan-failed').length, 1);
+ if (firefox) assert.equal(h.frames.length, 1, 'reuse the existing background iframe');
+ });
+ }
+
+ it('reuses an existing Chrome offscreen document after worker restart', async () => {
+ const h = scannerHarness({ existingHost: true });
+ await vm.runInContext('sendScanToTab(7)', h.context);
+ assert.equal(h.creates(), 0);
+ assert.equal(h.tabMessages.length, 1);
+ });
+});
+
describe('extension DevTools packaging', () => {
it('uses extension-root paths for DevTools panel pages', () => {
const source = readFileSync(path.join(ROOT, 'extension/devtools/devtools.js'), 'utf-8');
diff --git a/tests/fixtures/extension-scan/README.md b/tests/fixtures/extension-scan/README.md
new file mode 100644
index 000000000..23d6795d7
--- /dev/null
+++ b/tests/fixtures/extension-scan/README.md
@@ -0,0 +1,37 @@
+# Extension scanner smoke test
+
+These pages test extension startup and scan delivery, including on pages whose
+CSP blocks page scripts and WebAssembly. `flagged.html` should report one
+`low-contrast` finding for `p.faint`; `clean.html` should report no findings.
+
+Build with `bun run build:extension`, then serve this directory:
+
+```sh
+python3 -m http.server 8337 --bind 127.0.0.1 --directory tests/fixtures/extension-scan
+```
+
+For Firefox, temporarily load `dist/extension-firefox/manifest.json` through
+`about:debugging`, or use Mozilla's `web-ext`:
+
+```sh
+web-ext run --source-dir dist/extension-firefox --start-url http://127.0.0.1:8337/flagged.html
+```
+
+For Chrome, load the unpacked `extension/` directory in `chrome://extensions`.
+
+In each browser:
+
+1. Open `flagged.html`, open the extension popup, and click **Scan page**.
+ Expect one finding and an overlay on the pale paragraph, with no startup error.
+2. Scan again. Expect the same result without duplicate overlays.
+3. Follow the link to `clean.html` and explicitly scan. Expect zero findings
+ and no error (zero before a scan is not proof of successful scanning).
+4. Navigate back to `flagged.html` and scan. Expect one finding again.
+5. In Chrome, close and reopen the browser, then repeat the first scan.
+ Firefox removes temporary extensions when it closes: reopen Firefox and load
+ the extension again through `about:debugging`, or rerun `web-ext run`, then
+ repeat the first scan. This exercises a cold core startup in each browser.
+
+The released Firefox 1.4.0 artifact fails at step 1 with the
+`OFFSCREEN_DOCUMENT` error from issue #847. Test desktop Firefox and Chrome
+separately; the shared detector bundle does not make their hosting APIs identical.
diff --git a/tests/fixtures/extension-scan/clean.html b/tests/fixtures/extension-scan/clean.html
new file mode 100644
index 000000000..f6add51f6
--- /dev/null
+++ b/tests/fixtures/extension-scan/clean.html
@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>Extension scanner: clean control</title>
+<style>
+ body { margin: 48px; background: #fff; color: #222; font: 18px/1.6 Georgia, serif; }
+ main { max-width: 640px; }
+ h1 { font-size: 32px; line-height: 1.2; }
+ a { color: #174ea6; display: inline-block; padding: 12px 0; }
+</style>
+<main>
+ <h1>Extension scanner test</h1>
+ <p>This dark paragraph should pass the contrast check on a white background.</p>
+ <a href="flagged.html">Open the low-contrast test page</a>
+</main>
+</html>
diff --git a/tests/fixtures/extension-scan/flagged.html b/tests/fixtures/extension-scan/flagged.html
new file mode 100644
index 000000000..3a5724a60
--- /dev/null
+++ b/tests/fixtures/extension-scan/flagged.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>Extension scanner: low contrast</title>
+<style>
+ body { margin: 48px; background: #fff; color: #222; font: 18px/1.6 Georgia, serif; }
+ main { max-width: 640px; }
+ h1 { font-size: 32px; line-height: 1.2; }
+ .faint { color: #ddd; }
+ a { color: #174ea6; display: inline-block; padding: 12px 0; }
+</style>
+<main>
+ <h1>Extension scanner test</h1>
+ <p class="faint">This deliberately pale paragraph should trigger a low-contrast finding on a white background.</p>
+ <a href="clean.html">Open the clean control page</a>
+</main>
+</html>