Skip to content

feat: Migrate to Chrome Manifest V3 with Hybrid DeclarativeNetRequest Engine - #532

Open
OmarAlaaeldein wants to merge 3 commits into
ClearURLs:masterfrom
OmarAlaaeldein:master
Open

feat: Migrate to Chrome Manifest V3 with Hybrid DeclarativeNetRequest Engine#532
OmarAlaaeldein wants to merge 3 commits into
ClearURLs:masterfrom
OmarAlaaeldein:master

Conversation

@OmarAlaaeldein

Copy link
Copy Markdown

feat: Migrate to Chrome Manifest V3 with Hybrid DeclarativeNetRequest Engine

Context

With Google Chrome officially phasing out Manifest V2, this Merge Request updates ClearURLs to fully support the Manifest V3 architecture, securing its future on Chrome-based browsers.

This PR is a comprehensive architectural upgrade that preserves the core logic and manual functionalities of the extension while fully complying with Manifest V3 restrictions (Service Workers, DeclarativeNetRequest, and strict Content Security Policies).

Major Architectural Changes

1. Hybrid declarativeNetRequest Engine (clearurls.js)

Since the synchronous webRequestBlocking API has been deprecated, the core filtering engine has been rebuilt into a hybrid model:

  • Background Interception: We now parse the standard ClearURLs provider lists and dynamically translate them into up to 30,000 native declarativeNetRequest (DNR) rules.
    • Query string removals use redirect + queryTransform.removeParams.
    • Known tracking domains and ping requests use block.
    • Redirection/Raw rules map to regexSubstitution with capture groups.
  • Pre-flight Regex Validation: Chrome's internal RE2 engine rejects any regexFilter exceeding 2KB in memory. Rather than allowing a single oversized exception regex to fail the entire rule payload, we now run chrome.declarativeNetRequest.isRegexSupported() on every regex rule first. Unsupported/oversized rules are gracefully skipped.
  • Pure JS Engine Preserved: The original Provider classes and parsing logic remain completely intact so that the manual Context Menu cleaning, History Listener, and UI Cleaning Tool still function exactly as before.

2. Service Worker Lifecycle (background.js & storage.js)

Background scripts have been replaced by an ephemeral Service Worker.

  • Introduced background.js as the sole entry point, which uses importScripts() to load all dependencies in the correct order.
  • Lowered deferSaveOnDisk from a 30-second timeout down to 5 seconds to ensure data is safely persisted before Chrome aggressively terminates the Service Worker.
  • Refactored genesis() and added ensureStorageLoaded() to protect against cold-starts.
  • Moved setInterval watchdog operations to chrome.alarms to ensure they trigger reliably outside of active memory.

3. Content Scripts & Strict CSP (manifest.json)

Manifest V3's strict Content Security Policy (script-src 'self') bans the inline <script> injections previously used to hijack window.rwt and window._borschik.

  • Fix: Added "world": "MAIN" to the Google and Yandex content scripts in manifest.json. This securely executes the content script directly within the webpage's DOM context, allowing us to hook window properties natively without injecting custom DOM elements.

4. API Modernization & Security

  • IPC Messaging: Removed the insecure pattern of evaluating dynamic functions off the global window object (window[request.function].apply()). Background messaging is now strictly routed through an explicit messageHandlers dispatch map.
  • Prototype Pollution: Removed Object.prototype.getOrDefault. It is now a standalone utility function, preventing conflicts with third-party libraries (like jQuery/DataTables).
  • DOM APIs: Replaced all instances of browser.tabs.executeScript with the modern chrome.scripting.executeScript (using the {func: myFunc, args: [...]} pattern to serialize payloads and neutralize XSS).
  • UI Actions: Migrated all browser.browserAction commands to browser.action.
  • ETags: eTagFilter.js now removes ETags completely using a DNR modifyHeaders rule (reserved ID: 99999), as synchronous header modification is no longer permitted.

Testing Performed

  • Extension packs successfully without warnings using Chrome's native compiler.
  • declarativeNetRequest rules compile and install correctly (bypassing the 2KB limit).
  • Google and Yandex search result link overrides function as intended without CSP violations.
  • Manual URL cleaning tool functions properly (async scope bug resolved).
  • Context menus securely inject into the clipboard via chrome.scripting.

(Note: Automated CI pipeline checks only include JSON minification and hash generation; no unit tests were present to run)

@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant