⚠️ Chrome Extension API Limitations in Peersky

[akhileshthite]

Overview

Peersky uses electron-chrome-extensions (ECE) as its extension API bridge on top of Electron's built-in extension layer. ECE handles MV2/MV3, browser actions, tabs, windows, context menus, cookies, i18n, and notifications. Several Chrome APIs are still missing and block real-world extensions from working.

---

Missing APIs

chrome.debugger — Not supported

The chrome.debugger API attaches to Chrome DevTools Protocol (CDP) for deep network inspection.

Broken extension — archiveweb.page (Webrecorder):

{
  "manifest_version": 3,
  "permissions": ["debugger", "tabs", "webRequest", "storage"],
  "background": { "service_worker": "bg.js" }
}

archiveweb.page calls chrome.debugger.attach() to capture full network responses at the CDP level — webRequest alone cannot access response bodies. Without this, the extension UI loads but cannot record any web archives.

Electron exposes CDP natively via webContents.debugger, but there is no bridge from chrome.debugger extension calls to webContents.debugger. Implementing this requires a main-process IPC handler that proxies attach, detach, sendCommand, and fires onEvent/onDetach back to the extension.

---

chrome.identity — Not supported

Used for OAuth 2.0 flows via chrome.identity.launchWebAuthFlow({ url, interactive: true }). Opens a controlled popup, intercepts the OAuth redirect, and returns the token.

Without it, extensions fall back to window.open() for OAuth — which behaves differently in Electron (no popup lifecycle management, redirect interception fails silently).

---

chrome.proxy — Not supported

Required by VPN and proxy extensions. Electron exposes session.setProxy() but there is no bridge to chrome.proxy.settings.set(). Extensions may show a "connected" state while traffic is not actually proxied.

---

chrome.storage.sync — Not supported

Confirmed by Electron docs: only chrome.storage.local works. chrome.storage.sync and chrome.storage.managed are unsupported. Extension settings don't roam across devices.

---

chrome.webRequest — Handler Conflict

Electron docs note: "Electron's webRequest module takes precedence over chrome.webRequest if there are conflicting handlers." Peersky registers its own webRequest handlers for P2P protocol interception. Related #124

Known issue — Ghostery analytics blocking:

Ghostery's tracker analytics feature relies on chrome.webRequest to intercept and analyze network requests. The extension still blocks trackers via content scripts and declarativeNetRequest, but the analytics dashboard may show incomplete statistics.

---

window.open() — Behavioral Mismatch

OAuth flows that use window.open() as a fallback fail in Electron due to different popup lifecycle, focus handling, and redirect behavior vs. Chrome.

---

API Status Summary

API	Status
chrome.runtime.*	✅ Working
chrome.tabs.*	✅ Working
chrome.windows.*	✅ Working
chrome.action / chrome.browserAction	✅ Working
chrome.scripting	✅ Working
chrome.storage.local	✅ Working
chrome.contextMenus	⚠️ Partial
chrome.management	⚠️ Partial
chrome.tabs.captureVisibleTab	⚠️ Unreliable
chrome.webRequest	⚠️ Conflicts with Peersky's P2P handlers
chrome.debugger	❌ Not supported
chrome.identity	❌ Not supported
chrome.proxy	❌ Not supported
chrome.storage.sync	❌ Not supported

---

Roadmap

The plan is to extend ECE with the missing APIs. Agregore's electron-extended-webextensions (EWE) has already specced out chrome.debugger (attach, detach, sendCommand, onEvent) and chrome.webNavigation in its preload; we can use these implementations as a reference or contribute the missing pieces there as well.

Note: Agregore doesn't have extension management UI and no Chrome Web Store integration; only builtin extensions. Peersky has a full extension UI, Chrome Web Store support, and preinstalled extensions - so ECE remains the right foundation according to our approach; EWE is a useful reference for the APIs it has specced.

---

Finally remove limitation note in Extension.md #134

Links

• Electron Extension Support Docs
• electron-chrome-extensions
• electron-extended-webextensions (Agregore)
• archiveweb.page

[PrasannaPal21]

@akhileshthite can I work on this issue ??

[akhileshthite]

@PrasannaPal21 Can you share your approach? This PR will take long and a lot rewrites/PRs to https://github.com/AgregoreWeb/electron-extended-WebExtensions.

[PrasannaPal21]

I will use EWE as a reference.
Starting with chrome.debugger, the main process would find the tab's webContents and use Electron's debugger API. it would attach, send commands and send message/detach events back to the extension over IPC. the extension side would have a stub that calls into that via IPC. and then I'd unblock the debugger permission in the policy so extensions like archiveweb.page can use it.
I’d do the similar for the other APIs later. for webRequest vs P2P I might need some help later, or I'll document it first, and coordinate with you.

can I start with the debugger if you’re okay with this @akhileshthite.

[HarshalAtre]

@akhileshthite , May I take this one?

As i have already worked on AgregoreWeb a little
AgregoreWeb/agregore-browser#320
AgregoreWeb/agregore-browser#321
AgregoreWeb/extension-agregore-renderer#22

Will analyze it properly and share my approach

[PrasannaPal21]

@akhileshthite

rough flow for debugger

Extension: chrome.debugger.attach({ tabId }) -- IPC -- Main: get webContents from store, wc.debugger.attach()
Extension: chrome.debugger.sendCommand(...) -- IPC -- Main: wc.debugger.sendCommand(method, params)
Main: wc.debugger.on('message') -- router.sendEvent(extId, 'debugger.onEvent', ...) -- Extension gets onEvent
Main: wc.debugger.on('detach') -- router.sendEvent(extId, 'debugger.onDetach', ...) -- Extension gets onDetach

[PrasannaPal21]

@akhileshthite

I tried to implement the chrome.debugger and tested it in Peersky-Browser console

screenshots -
chrome.debugger

.attach and sendCommand

.detach


.onDetach

can i make a draft PR and work on it.