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.jsindex 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.jsindex 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.mjsindex 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.mdnew file mode 100644index 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.htmlnew file mode 100644index 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.htmlnew file mode 100644index 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>