Possible solution for Safari/UserScripts page context isolation

[Acobat12]

I investigated the Safari/UserScripts issue and found that the root cause appears to be the execution context isolation in UserScripts. The userscript context cannot access page globals (e.g. window.player, NEXT_DATA), so site helpers fail to obtain the required video information.

I implemented a proof-of-concept in my fork by introducing a page-context bridge between the page and the userscript. It restores access to page globals and allows VOT to work correctly in Safari/UserScripts.

If it's useful, feel free to reuse or adapt any part of the implementation:

https://github.com/Acobat12/userscripts/blob/main/src/ext/content-scripts/entry-userscripts.js

If you'd like, I can also prepare a pull request.

[quoid]

@Acobat12

I investigated the Safari/UserScripts issue...

Can you clarify the exact issue you are referencing?

[Acobat12]

I'm referring to this issue:

ilyhalight/voice-over-translation#1745

The problem is that when VOT runs under Safari + UserScripts, the userscript context cannot access page globals (such as window.player, NEXT_DATA, etc.). As a result, site helpers cannot obtain the required video information and VOT fails to create a translation session.

I investigated the issue and implemented a proof-of-concept by introducing a page-context bridge. With this approach, VOT works correctly in Safari/UserScripts.

[ACTCD]

With the @inject-into metadata, you could choose to inject into the page context or the content script context.

It's a bit tricky when you need both at the same time, because in Safari we can't implement unsafeWindow using the wrappedJSObject API provided in Firefox, and due to some confusion we're not meant to implement that method either.

• Support for unsafeWindow #801
• Support unsafeWindow API #252

There are some ways to achieve this indirectly, but it is not easy to be safe, compatible, and compliant at the same time.

I've made an example to show a relatively safe way to achieve this, it may be similar to your bridge, but instead of exposing the GM APIs to the page context (which many people do for convenience).

• Support unsafeWindow API #252 (comment)

For clarity, you should implement a bridge that only transfers page data and is properly sanitized. You should never bridge advance APIs in content scripts to the page context, as this creates security risks for your users.

Since its asynchronous nature is incompatible with existing usage, we currently do not plan to build it into the project, and it is currently left up to userscript developers to implement it in a safe manner. But maybe that will change in the future.

[ACTCD]

Thank you for raising this issue and solution. I'm closing this as a duplicate issue.
But if I misunderstood your intent, or still have questions, please go ahead and comment.

[Acobat12]

Thanks for the clarification.

I think I didn't explain the implementation clearly enough.

My goal was not to implement unsafeWindow or to expose privileged APIs to the page context.

The userscript itself is injected into the page context so it can access page globals such as window.player, NEXT_DATA, and other site-specific objects that are unavailable from the isolated userscript context in Safari.

The GM_* APIs remain implemented in the extension/content-script context. The page context does not receive those APIs as globals, and they are not attached to window.

When the userscript needs a granted API, it sends a request through an internal bridge. The privileged operation is executed in the extension/content-script context, and only the operation result is returned to the userscript. The userscript never executes privileged code itself.

I created this because I was debugging a real compatibility issue in VOT. Due to Safari's context isolation, site helpers could no longer access page globals, even though those objects were visible from Safari DevTools. Running the userscript in the page context solved that part, while the bridge allowed existing GM_* functionality to continue working.

From my perspective, this is different from implementing a generic unsafeWindow API. It is a compatibility mechanism that combines page-context execution with privileged APIs without attaching GM_* directly to the page.

If there is a specific security issue with this architecture, I'd genuinely appreciate understanding it. For example, is the concern the bridge itself, the message transport, request authentication, or something else?

[ACTCD]

@Acobat12 If I understand correctly, you are still bringing the GM APIs into the page context, even though they are not global, but this is still unsafe.

Like I said above, you should only bridge and pass page data, not GM API calls. And sanitize in content scripts before using page data, we always assume that the page can hijack and send arbitrary data.

Even though we have used random event names and closed shadow root, this may still create security risks due to unknown vulnerabilities and exploits.

So the best approach is to never expose the advanced APIs to the page context.

This requires developers to implement customized data bridge and sterilization according to needs, which is why it cannot be easily entered into the project as boilerplate code.

[ACTCD]

If you look at the example I mentioned above, you'll see that the userscript is still injected into the content script context, but part of the logic is re-injected into the page context as a wrapper, so you can implement custom data transfer logic without bridging everything to the page.

Again, even if the data is passed back through this wrapper, you must assume that it has been tampered with and reasonably sanitize it before calling it in the context of a content script to ensure safety.

[ACTCD]

I hope to clarify some points again for anyone reading this issue.

The following design is intentional:

• Content script isolation context against page script context
• The advanced GM* APIs only available in Content scripts context
• unsafeWindow allows you interact with page context via wrappedJSObject API only in Firefox. But like the prefix unsafe and the API page warns:

Warning

As an extension developer you should consider that scripts running in arbitrary web pages are hostile code whose aim is to steal the user's personal information, damage their computer, or attack them in some other way.

The isolation between content scripts and scripts loaded by web pages is intended to make it more difficult for hostile web pages to do this.

Since the techniques described in this section break down that isolation, they are inherently dangerous and should be used with great care.

⚠️ Anything that creates a bridge between the page context and the isolation context is dangerous and should be used with caution.

⚠️ You should never bridge and expose advanced APIs directly to the page context. This may result in you unintentionally putting your users at wider risk and compromising their privacy.

• Waiting for upstream to implement the UserScripts API #756

Even in the latest userScripts API of MV3, injecting in MAIN world is still considered a dangerous behavior and needs to be used with caution:

Warning

Web pages can detect and interfere with the executed code due to the lack of isolation. Therefore, don't use the MAIN world unless it's acceptable for web pages to read, access, or modify the logic or data that flows through the executed code.

In either ISOLATED or USER_SCRIPT worlds, random custom events are considered a relatively safe way to exchange data with the page, where you only exchange necessary data and sanitize it for use.

• This method does not rely on extensions, but uses native APIs.
  • Some extensions even isolate the DOM for security reasons, making this method unavailable, which is an implementation issue.
• Must use truly random event names, avoid being predicted.
  • It should be randomly generated at runtime.
• Any received data must be sanitized before further use.
  • Assuming any data sent by the page has been tampered with.
  • This relies heavily on script developer security practices

⚠️ Again, only exchanging data rather than bridging advanced APIs. Always keep your attack surface to a minimum.

For more information please refer to my comments in these issues:

• Support for unsafeWindow #801
• Support unsafeWindow API #252

[Acobat12]

Hi @ACTCD,

Thanks again for your earlier explanations. I reworked the implementation to follow the data-only bridge model you described, and I'd really appreciate it if you could take another look at it.

The previous implementation has been removed. The current design is:

• Userscripts requesting privileged @grant APIs are always executed in the content-script context.
• Privileged GM APIs are no longer bridged into the page context.
• Access to page globals is now provided only through GM.getPageData(extractor, ...args).
• Only the extractor function is executed in the page context.
• Only validated, size-limited, JSON-serializable data can be returned.
• Functions, DOM nodes, class instances, blobs, streams, cyclic structures, reserved object keys, and other active objects are rejected.
• Returned values are treated as untrusted page-controlled data and are validated again before use in the content-script context.
• The README now explicitly documents the security model and limitations, including that response event names are not a trust boundary and that timeouts cannot interrupt already-running page JavaScript.

The relevant changes are mainly in:

• entry-userscripts.js
• api.js
• main.js
• utils.js
• README.md

If you have time, I'd really appreciate your feedback on whether this architecture now aligns with the security model you described, or if there are still areas that should be improved.

[ACTCD]

@Acobat12 I haven't read the code, but from your description, I think it sounds like it fits the security model.

GM.getPageData sounds like a great tool, but I'm cautious about whether it should become a truly new GM API.

The reason is that data interaction with the page may take many forms, depending on the specific needs of the user script author, such as getting page properties, setting page properties, listening to page events, monitor node changes, and so on. In other words, the Initiator and timing may vary. I don't think there is a simple way to abstract all similar needs.

So currently I still think it's better suited to be implemented in a concrete userscript rather than in the manager.

Having said that, if you wish to maintain a fork, here is a issue about @grant and @inject-into:

• Changes to @grant and @inject-into #265

Simply put, the final decision in the issue is that @inject-into has priority, that is, when @inject-into page, all @grant are ignored. This issue actually also records the discussion of similar security issues that I reported back at that time, I wasn't even a maintainer of the project at the time.

[Acobat12]

Thanks for the clarification and for pointing me to #265.

I agree with the original security goal: privileged GM APIs must remain isolated from the page context.

My fork keeps that boundary. Any userscript requesting privileged @grant APIs runs in the content-script context. GM.getPageData() does not expose GM APIs to the page; it only executes a supplied extractor in the page context and returns size-limited, JSON-serializable data.

The returned value is normalized in the page context and validated again in the content-script context. Functions, DOM nodes, class instances, cyclic structures, reserved keys, and other active objects are rejected. The result is always treated as untrusted page-controlled data.

So the intention is not to replace the isolation policy from #265, but to provide a narrow, data-only way to read page globals without requiring every userscript author to build a custom bridge.

I understand your concern that page interaction can involve many different patterns and that GM.getPageData() may not be a universal abstraction. For now, I plan to keep it as a deliberately limited API in my fork and see how it works in real userscripts.

Thanks again for the feedback.

[ACTCD]

@Acobat12 No, the main reason I quoted #265 was to tell you that our current implementation is not force inject into the content context in all cases when there is an valid @grant.

For clarity, I drew this diagram for your reference:

flowchart LR
    A{"@inject-into"} -->|page| PAGE("page with none advanced APIs") -->|CSP violations| F{"@inject-into omit/auto?"}
    A -->|omit/auto| C{"any valid @grant?"}
    A -->|content| CONTENT(content with granted advanced APIs)
    C -->|omit/none| PAGE
    C -->|yes| CONTENT
    F -->|fallback| CONTENT

Loading