feat: service worker preload scripts

[samuelmaddock]

Description of Change

Implements RFC #8

Tip

I recommend reviewing by commit. I've split up the work into logical commits to make reading it more manageable.

Todo

• Redesign contextBridge.evaluateInMainWorld to accept Function and Args[] rather than a string
  feat: service worker preload scripts #44411 (comment)
• Create Electron Fiddle examples to embed in the docs
• Instructions on how to pull down dist.zip from artifacts for local testing
  feat: e pr download-dist <number> build-tools#679
• Feedback: evaluateInMainWorld should use contextBridge value passing rather than JSON-serialization if possible.
• Feedback: registerPreloadScript shouldn't accept an id because people will put something random and useless. With future extensions in mind, maybe accept a matcher object
• Feedback: fromVersionID could be better named to something like getWorkerFromVersionID

Documentation

• Design of V8 bindings - Overview of V8 isolates, contexts, and worlds.
• ShadowRealms explainer - Preload realms are based on shadow realms. Essentially they can be thought of as a minimal JS context which Blink is aware of.
• Service workers - Describes chromium's internal implementation. Notably, ServiceWorkerVersion and ServiceWorkerHost are relevant for understanding ServiceWorkerMain in this PR.

Overview

• Creates a new "preload realm" v8::Context in renderer worker threads to allow secure interaction with service worker contexts.
• Refactors setPreloads and getPreloads on Session to support additional targets and more accessible registration from third-party libraries
• Adds ServiceWorkerMain to main process to enable IPC with renderer worker threads.

ServiceWorkerMain

Tracks lifetime of content::ServiceWorkerVersion. This class lives as long as a service worker registration is live. A new instance is required for each new 'version' of a service worker script installed.

Only scope, versionId, and ipc are currently exposed.

Service worker IPCs

ServiceWorkerMain.ipc matches the implementation of IpcMain to enable IPC with the renderer process service worker thread. IPCs sent from the render worker threads are dispatched on Session; currently only handling service worker IPCs.

ipcMainInternal now handles IPCs from both web frames and service workers. To differentiate the two, an IPC event has a type of either 'frame' or 'service-worker'.

Preload script changes

Preload scripts now require options beyond only their script location. 'frame' and 'service-worker' are now supported via the type property. The appropriate scripts will be fetched when our JS bundles are executed in the renderer process.

Given the requirements change, I took this opportunity to make our preload APIs better support third-party libraries based on our best practices.

Architecture Flow

As a starting point for reviewing, consider some of the flows this feature implements.

// Register preload script
Session::RegisterPreloadScript(preload_script)
 └── Appends to SessionPreferences::preload_scripts_

// Initialize preload realm v8::Context
ElectronSandboxedRendererClient::WillEvaluateServiceWorkerOnWorkerThread()
 ├── preload_realm::OnCreatePreloadableV8Context()
 └── PreloadRealmLifetimeController::RunInitScript()

// Bind Mojo receiver for mojom::ElectronApiIPC in main process
(1) ElectronBrowserClient::RegisterAssociatedInterfaceBindersForServiceWorker()
 └── Add interface for mojom::ElectronApiIPC
(2) ElectronApiSWIPCHandlerImpl::BindReceiver()
 └── Init ElectronApiSWIPCHandlerImpl()

// Bind Mojo remote for mojom::ElectronApiIPC in renderer process
electron::IPCRenderer::IPCRenderer()
 ├── blink::WebServiceWorkerContextProxy->GetRemoteAssociatedInterface()
 └── Binds to mojom::ElectronApiIPC

// Bind Mojo receiver for mojom::ElectronRenderer in renderer process
ElectronSandboxedRendererClient::WillEvaluateServiceWorkerOnWorkerThread()
 ├── new ServiceWorkerData()
 ├── blink::WebServiceWorkerContextProxy->GetRemoteAssociatedInterface()
 └── Binds to mojom::ElectronRenderer

// Send IPC from renderer worker thread to main process
electron::IPCRenderer::IPCRenderer::SendMessage()
 │   // renderer → main
 ├── ElectronApiSWIPCHandlerImpl::Message()
 ├── Session::Message() inherited from IpcDispatcher::Message()
 │   // enters JavaScript
 ├── session.on('-ipc-message')
 ├── ServiceWorkerMain.ipc.on(channel, listener)
 └── listener()

// Send IPC from main process to renderer worker thread
electron::ServiceWorkerMain::Send()
 │   // main → renderer
 ├── ServiceWorkerData::Message()
 ├── ipc_native::EmitIPCEvent()
 │   // enters JavaScript
 ├── ipcNative.onMessage()
 └── ipcRenderer.emit(channel)

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes:

• Added support for service worker preload scripts via registerPreloadScript, unregisterPreloadScript, getPreloadScripts on Session.
• Deprecated getPreloads and setPreloads on Session.
• Added ServiceWorkerMain class to interact with service workers in the main process.
• Added fromVersionID on ServiceWorkers to get an instance of ServiceWorkerMain.
• Added running-status-changed event on ServiceWorkers to indicate when a service worker's running status has changed.
• Added contextBridge.evaluateInMainWorld to safely evaluate code across world boundaries.

[alicelovescake]

Nice refactoring!

[MarshallOfSound]

Let's talk more about evaluateInMainWorld. Making new functions that allow evaluation of strings directly contravenes web security standards and the original purpose of the context bridge. It will expose a giant security footgun and I'm a strong -1 on exposing such a feature.

I'd love to understand the motivation / usecase and discuss with the Security WG (cc @electron/wg-security) how to solve those use-cases with an API that isn't such a footgun.

[samuelmaddock]

@MarshallOfSound the goal with evaluateInMainWorld is to provide equivalent functionality to webFrame.executeJavaScript(code) (reference in RFC).

For my particular use case, I'd like to overwrite extension APIs such as chrome.action. Here's a relatively simple example.

const { ipcRenderer, contextBridge } = require('electron');

// Expose setBadgeText API
contextBridge.exposeInMainWorld('electron', {
  setBadgeText: (text) => ipcRenderer.send('action.setBadgeText', text)
});

// Overwrite extension API to provide custom functionality
contextBridge.evaluateInMainWorld(`(function () {
  chrome.action.setBadgeText = (text) => {
    electron.setBadgeText(text);
  };
}());`);

A potential alternative might be to accept functions. This is similar to what's offered by chrome.scripting APIs.

function overrideActionApi () {
  chrome.action.setBadgeText = (text) => {
    electron.setBadgeText(text);
  };
}

contextBridge.evaluateInMainWorld({
  func: overrideActionApi,
  args: []
});

If this method existing on contextBridge is a problem, I'm open to introducing a renderer top-level module (worker|serviceWorker|preloadRealm).executeJavaScript instead.

[MarshallOfSound]

webFrame.executeJavaScript is also a foot gun, it's an API that wouldn't land nowadays and if we could, we'd remove it. I wouldn't use it as an example

It sounds like what you want is support for overriding existing APIs from contextBridge which is a thing it supports internally but isn't exposed via API

[samuelmaddock]

It sounds like what you want is support for overriding existing APIs from contextBridge which is a thing it supports internally but isn't exposed via API

@MarshallOfSound The example I provided is limited. However, I do have use cases which require additional logic where providing a complete function would be necessary. For example, some extension APIs require serializing arguments such as action.setIcon.

Additionally, the v8::Context provided in this implementation is based on ShadowRealms. These lack most DOM APIs, but could be partially restored by evaluating a method.

// Polyfill setTimeout in ShadowRealmGlobalScope
function setTimeoutAsync (delay) {
  return contextBridge.evaluateInMainWorld({
    func: function mainWorldFunc (delay) {
      return new Promise((resolve) => setTimeout(resolve, delay));
    },
    args: [delay]
  });
}

[MarshallOfSound]

However, I do have use cases which require additional logic where providing a complete function would be necessary. For example, some extension APIs require serializing arguments such as action.setIcon.

In this case adding support for zero-copy context bridge transfer of ImageData should be the path forward. The V8 serializer already supports ImageData afaics so there is at least copy-based support already

Additionally, the v8::Context provided in this implementation is based on ShadowRealms. These lack most DOM APIs, but could be partially restored by evaluating a method.

I don't think this is a good enough usecase to justify a security footgun, the web knows it, chrome knows it, passing strings around to be evalled is just a nightmare. Someones gonna do something silly like window.foo('${userInput}'). Passing an actual Function in plus Args[] is maybe more acceptable, but in an ideal world we don't build an API that deliberately bypasses web security

[samuelmaddock]

Passing an actual Function in plus Args[] is maybe more acceptable, but in an ideal world we don't build an API that deliberately bypasses web security

@MarshallOfSound If I refactor this API to accept a Function and Args[], will that be acceptable? My current solution works with this approach.

[MarshallOfSound]

@MarshallOfSound If I refactor this API to accept a Function and Args[], will that be acceptable? My current solution works with this approach.

Ideally we find a way to avoid this APi surface entirely, does the overrideGlobalPropertyFromIsolatedWorld internal API + ImageData being copy-able not solve your usecase without the need for JS execution?

[samuelmaddock]

Ideally we find a way to avoid this APi surface entirely, does the overrideGlobalPropertyFromIsolatedWorld internal API + ImageData being copy-able not solve your usecase without the need for JS execution?

My current constraints:

• Read deeply-nested properties from the main world
• Override deeply-nested properties in the main world
• Invoke deeply-nested function properties in the main world and retrieve the result
• Serialize ImageData for IPC to the main process

There's also the issue of future unknowns. JS execution will allow the flexibility to solve varied problems with a small API surface.

I'm not sure I fully understand the footgun argument against JS execution (outside of eval strings). Electron provides application developers with full control over a chromium browser environment through JS APIs, and this seems to take away from that level of control. This is a fairly common API provided in projects such as Chrome DevTools Protocol, Chrome Extensions, Puppeteer/Playwright, Selenium, and node's vm module.

[MarshallOfSound]

I'm not sure I fully understand the footgun argument against JS execution (outside of eval strings)

Let me clarify my stance

• Eval of strings === hard no from me on any additional API surface that exposed this capability and we should be working to minimize, deprecate and remove existing instances of this
• Safe stringification of functions + serialized argument passing === the acceptable alternative to eval of strings, this is what existing APIs should be ported to
• Context Bridge capabilities, either exposing / overriding existing objects, deep properties === ideal, we should be doing this and recommending this over the other two alternatives

To give a path forward given the constraints noted above (thanks for those, gives a clear picture of what is needed)

• Update the API to take a function and stringify it safely using FunctionProtoToString()
• Add a test to ensure user provided toString methods either on functions or on the function prototype don't affect the evaluation
• If possible reuse chrome extension evaluation logic for this (they support functions iirc)
• Ensure return values and arguments go over the ctx bridge

Docs for the function thing could be fun, but at least technically that's the way forward IMO

[samuelmaddock]

I've refactored contextBridge.evaluateInMainWorld to now accept { func: Function, args: any[] } in c6164aa. This is based on logic from Chrome extension's chrome.scripting.executeScript.

Tests to guarantee return values go through the context bridge reuse the logic from our webFrame.executeJavaScript world safe test. The internals of evaluateInMainWorld are shared with exposeInMainWorld.

cc @MarshallOfSound

chrome.scripting.executeScript internals

• Extension IDL specifies [serializableFunction] for Function argument
  https://source.chromium.org/chromium/chromium/src/+/main:chrome/common/extensions/api/scripting.idl;l=47-53;drc=f54f71679bfe9b9ef10c785369112fb2d0661750
• ArgumentSpec::ParseArgumentToFunction serializes the function using v8::Function::FunctionProtoToString
  https://source.chromium.org/chromium/chromium/src/+/main:extensions/renderer/bindings/argument_spec.cc;l=744-764;drc=38412897b24a44461ec89d2167e2110a3793c98c
• ScriptingExecuteScriptFunction::Run constructs the function string and serializes arguments as JSON
  https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/extensions/api/scripting/scripting_api.cc;l=617-641;drc=01ab59ae08a38a361da7dac41e36f387f6600ed5

contextBridge.evaluateInMainWorld(script) types

The types are currently using any. We'll need to modify our type definition generator to better support adding generics here. Given the API being marked as Experimental, we can update this in a follow up PR to prevent blocking this PR.

interface EvaluationScript {
  /**
   * A JavaScript function to evaluate. This function will be serialized which means
   * that any bound parameters and execution context will be lost.
   */
  func: (...args: any[]) => any;
  /**
   * The arguments to pass to the provided function. These arguments must be
   * JSON-serializable.
   */
  args?: any[];
}

interface ContextBridge {
  evaluateInMainWorld(evaluationScript: EvaluationScript): any;
}

[itsananderson]

One suggestion from today's review, to make these method names slightly less confusing, make 2 new methods:

getInfoFromVersionID(versionId): ServiceWorkerInfo
getWorkerFromVersionID(versionId): ServiceWorkerMain

Then make serviceWorkers.getFromVersionID a deprecated alias for getInfoFromVersionID.

[itsananderson]

Since there was some confusion in the review today about what valid args values are:

Suggested change

	* `args` any[] (optional) - The arguments to pass to the provided function. These arguments must
	* `args` any[] (optional) - An array of arguments to pass to the provided function. These arguments must

[itsananderson]

I've been trying to think of a scenario where it'd be backward incompatible to initially implementing this with JSON and then later using contextBridge to send the values, but unless someone explicitly relied on an argument not JSON serializing well, I think it should be fine to start with JSON serialization and enhance it later.

[samuelmaddock]

I should be able to give the context-bridged arguments a try so I'll update how that goes soon enough. Since it's an experimental API though, I think it's safe if we have to alter its behavior.

[jkleinsc]

Should this be called contextBridge.executeInMainWorld instead? Using evaluate in the name makes it seem like we are using eval()?

[samuelmaddock]

Initially I was using ShadowRealm.prototype.evaluate as the inspiration for naming.

I'm open to changing this. Especially since it's been revised to accept func/arg params.

Maybe executeScriptInMainWorld?

[jkleinsc]

@samuelmaddock I think that executeScriptInMainWorld is fine but a bit long but I don't think its a deal breaker either way.