feat: add exposeInIsolatedWorld(worldId, key, api) to contextBridge

[akshaydeo]

Description of Change

This PR adds a new function, exposeInIsolatedWorld to contextBridge. With this change, custom APIs can be exposed to Isolated worlds without any hacks when contextIsolation is enabled.

Fixes #32588

cc @miniak

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation is 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 contextBridge.exposeInIsolatedWorld(worldId, key, api) to expose an API to an isolatedWorld within a renderer from a preload script.

[welcome]

💖 Thanks for opening this pull request! 💖

We use semantic commit messages to streamline the release process. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix.

Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

Things that will help get your PR across the finish line:

• Follow the JavaScript, C++, and Python coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made following the documentation styleguide.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[MarshallOfSound]

As per my comment above, please undo all automated formatting changes in this PR not caused by our own linter as it makes the diff almost impossible to review accurately if a lot of the changed lines don't actually contain changes

[akshaydeo]

I've updated this PR to remove all lining differences

[RaisinTen]

I think some parts of spec-main/api-context-bridge-spec.ts still has the formatting changes.

[akshaydeo]

The diff in the existing content from the spec file is because I had to create a separate describe blob to segregate exposeInMainWorld and exposeInIsolatedWorld scenarios 🙇‍♂️

Old structure of the spec file

contextBridge
     with useSandbox=true/false
            test case

New structure of the spec file

contextBridge
     exposeInMainWorld
         with useSandbox=true/false
            test case
     exposeInIsolatedWorld
         with useSandbox=true/false
            test case

[nornagon]

Haven't reviewed the code but API LGTM.

[samuelmaddock]

API LGTM

Had some feedback about the code.

[samuelmaddock]

Code is looking good. Just had a small request for tests

[itsananderson]

API LGTM

all automated formatting changes have been removed

[RaisinTen]

LGTM

[ckerr]

Not sure what's going on with the cation bot, but this has LGTM API signoff from 3 API WG members so that is not blocking this PR

[welcome]

Congrats on merging your first pull request! 🎉🎉🎉

[release-clerk]

Release Notes Persisted

Added contextBridge.exposeInIsolatedWorld(worldId, key, api) to expose an API to an isolatedWorld within a renderer from a preload script.

[theogravity]

The documentation is lacking a proper example of how to use exposeInIsolatedWorld(). Do I attach the worldId to a BrowserWindow somewhere so that window has access to the isolated methods?

[qdirks]

@theogravity

The documentation is lacking a proper example of how to use exposeInIsolatedWorld().

I struggled with this as well, but I finally found some context here 32588, which is the original feature request which this pull request closes.

Do I attach the worldId to a BrowserWindow somewhere so that window has access to the isolated methods?

I had a similar misunderstanding. The worldId is attached to the BrowserWindow through the use of this method. Bear in mind that this is running in the preload script of the browser window, thus it is known that it will attach to that browser window. The real question is, "How do I run a script in the isolated world to access the exposed API?", right?

If so, then the method you're looking for is webFrame.executeJavascriptInIsolatedWorld, available from const {webFrame} = require('electron');, documentation here. To my understanding, exposeInIsolatedWorld can also be used to expose APIs to extensions.

If not, then what you're probably trying to do is expose the API to your scripts which run in the main world, e.g. you want to expose an API to the script tags in your html which you have loaded. If so, then use exposeInMainWorld.

Hope this helps.