Bug 1685123 docs for implementation of WebEx manifest sandbox #44709
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,200 @@ | ||
| --- | ||
| title: sandbox | ||
| slug: Mozilla/Add-ons/WebExtensions/manifest.json/sandbox | ||
| page-type: webextension-manifest-key | ||
| browser-compat: webextensions.manifest.sandbox | ||
| sidebar: addonsidebar | ||
| --- | ||
|
|
||
| <table class="fullwidth-table standard-table"> | ||
| <tbody> | ||
| <tr> | ||
| <th scope="row">Type</th> | ||
| <td><code>Object</code></td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">Mandatory</th> | ||
| <td>No</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">Manifest version</th> | ||
| <td>2 or higher</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">Example</th> | ||
| <td> | ||
| <pre class="brush: json"> | ||
| "sandbox": { | ||
| "pages": ["sandbox.html"] | ||
| }</pre> | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| Use the `sandbox` key to designate one or more of an extension's pages as **sandboxed pages**. | ||
|
|
||
| Sandboxed pages are loaded with a unique, opaque origin, instead of the extension's usual `moz-extension://` origin. As a result: | ||
|
|
||
| - Sandboxed pages can't access [WebExtension APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/API). The `browser` and `chrome` global objects are not available. | ||
| - Sandboxed pages can't access, and can't be accessed by, other pages in the extension, except by using {{DOMxRef("Window.postMessage()")}}. | ||
|
rebloor marked this conversation as resolved.
Outdated
|
||
|
|
||
| A sandboxed page can be given a more permissive [content security policy (CSP)](#content_security_policy_for_sandboxed_pages) than the rest of the extension. This includes a CSP that permits [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar constructs that are blocked by an extension's [default content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#default_content_security_policy). Because a sandboxed page can't use WebExtension APIs or reach the rest of the extension directly, this can be done without weakening the security of the extension as a whole. | ||
|
|
||
| This makes the `sandbox` key useful for including a third-party library that relies on `eval()` or `new Function()`, such as some templating engines: load the library in a sandboxed page, and use `postMessage()` to send it data from, and return results to, the rest of the extension. | ||
|
Member
There was a problem hiding this comment. The framing of template engine is likely copied from Chrome. Although that was a motivating factor back then (10+ years ago), it is hardly a relevant considerations now. These days such libraries are mostly designed to work even with a strict CSP. Let's drop the mention of templating libraries (the general reference to eval/Function are sufficient). |
||
|
|
||
| ## Manifest V2 syntax | ||
|
Member
There was a problem hiding this comment. Wouldn't it be less confusing if we:
This would enable us to add new manifest keys to sandbox without being forced to duplicate that documentation in two sections. I anticipate that we will likely have a new manifest sub key in |
||
|
|
||
| In Manifest V2, `sandbox` is an object with these properties: | ||
|
|
||
| <table class="fullwidth-table standard-table"> | ||
| <thead> | ||
| <tr> | ||
| <th scope="col">Name</th> | ||
| <th scope="col">Type</th> | ||
| <th scope="col">Description</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>pages</code></td> | ||
| <td><code>Array</code> of <code>String</code></td> | ||
| <td> | ||
| Required. A list of paths, relative to manifest.json, to the extension's sandboxed pages. | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>content_security_policy</code></td> | ||
| <td><code>String</code></td> | ||
| <td> | ||
| Optional. The content security policy applied to the sandboxed pages. See <a href="#content_security_policy_for_sandboxed_pages">Content security policy for sandboxed pages</a>. | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ```json | ||
| "sandbox": { | ||
| "pages": ["sandbox.html"], | ||
| "content_security_policy": "sandbox allow-scripts; script-src 'self' 'unsafe-eval';" | ||
| } | ||
| ``` | ||
|
|
||
| ## Manifest V3 syntax | ||
|
|
||
| In Manifest V3, `sandbox` only supports the `pages` property: | ||
|
|
||
| ```json | ||
| "sandbox": { | ||
| "pages": ["sandbox.html"] | ||
| } | ||
| ``` | ||
|
|
||
| The content security policy for sandboxed pages is instead set using the `sandbox` property of the [`content_security_policy`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy) key: | ||
|
|
||
| ```json | ||
| "content_security_policy": { | ||
| "sandbox": "sandbox allow-scripts; script-src 'self' 'unsafe-eval';" | ||
| } | ||
| ``` | ||
|
|
||
| ## Content security policy for sandboxed pages | ||
|
|
||
| If a policy is not supplied, sandboxed pages get this default content security policy: | ||
|
|
||
| ```plain | ||
| sandbox allow-scripts; script-src 'self'; | ||
| ``` | ||
|
|
||
| This isolates a sandboxed page from the rest of the extension, but doesn't allow `eval()` or similar constructs. To permit these, include `'unsafe-eval'` (or `'wasm-unsafe-eval'` for [WebAssembly](/en-US/docs/WebAssembly)) in the `script-src` directive of a custom policy. | ||
|
rebloor marked this conversation as resolved.
Outdated
|
||
|
|
||
| > [!NOTE] | ||
| > Chrome has a more permissive default sandboxed pages CSP: `sandbox allow-scripts allow-forms allow-popups allow-modals; script-src 'self' 'unsafe-inline' 'unsafe-eval'; child-src 'self';`. | ||
|
rebloor marked this conversation as resolved.
Outdated
|
||
|
|
||
| Any custom policy supplied for sandboxed pages must meet these requirements: | ||
|
|
||
| - It must include the {{CSP("sandbox")}} directive. | ||
| - The {{CSP("sandbox")}} directive must not include the `allow-same-origin` keyword. Allowing this would give the page access to the rest of the extension's origin, defeating the purpose of sandboxing it. | ||
|
|
||
| ## Example | ||
|
|
||
| This example loads a third-party templating library that uses `eval()`-like constructs into a sandboxed page, and uses it from a popup. | ||
|
|
||
| `manifest.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "manifest_version": 3, | ||
| "name": "Sandbox example", | ||
| "version": "1.0", | ||
| "action": { | ||
| "default_popup": "popup.html" | ||
| }, | ||
| "sandbox": { | ||
| "pages": ["sandbox.html"] | ||
| }, | ||
| "content_security_policy": { | ||
| "sandbox": "sandbox allow-scripts; script-src 'self' 'unsafe-eval';" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| `sandbox.html`: | ||
|
|
||
| ```html | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <script src="templating-library.js"></script> | ||
|
Member
There was a problem hiding this comment. Is this intended as a placeholder example? The example on the page itself does not run because the definition of the file is missing.
Contributor
Author
There was a problem hiding this comment. It's now a fully working example. However, after debugging an issue I found with Claude, it responded that "sandbox.js rejected every message with if (event.origin !== location.origin) — but a sandboxed page has an opaque origin (serializes to "null"), while the sender (popup.html) has a real moz-extension:// origin, so that check could never pass and the render would never happen. I replaced it with event.source !== window.parent (and added the matching check on the popup.js side, event.source !== sandbox.contentWindow), which validates the sender by window identity instead of origin — this is what MDN's own postMessage() security-concerns guidance recommends specifically because origin comparisons don't work for opaque-origin frames." |
||
| <script src="sandbox.js"></script> | ||
| </head> | ||
| <body></body> | ||
| </html> | ||
| ``` | ||
|
|
||
| `sandbox.js` listens for messages from the popup, renders a template using the sandboxed library, and posts the result back: | ||
|
|
||
| ```js | ||
| window.addEventListener("message", (event) => { | ||
|
Member
There was a problem hiding this comment. Below I am showing a concrete snippet to validate messages. Can you include that here too, and prominently mention a link to the security-relevant best practices at https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns Ideally we should have a dedicated section on this manifest page that clarifies how this feature should be used:
|
||
| const { template, context } = event.data; | ||
| const render = TemplatingLibrary.compile(template); | ||
| event.source.postMessage({ result: render(context) }, event.origin); | ||
| }); | ||
| ``` | ||
|
|
||
| `popup.html` embeds the sandboxed page in a hidden iframe: | ||
|
|
||
| ```html | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <script src="popup.js"></script> | ||
| </head> | ||
| <body> | ||
| <iframe id="sandbox" src="sandbox.html" hidden></iframe> | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| `popup.js` sends data to the sandboxed page and handles the result: | ||
|
|
||
| ```js | ||
| const sandbox = document.getElementById("sandbox"); | ||
|
|
||
| sandbox.addEventListener("load", () => { | ||
| sandbox.contentWindow.postMessage( | ||
| { template: "Hello, {{name}}!", context: { name: "world" } }, | ||
| "*", | ||
| ); | ||
| }); | ||
|
|
||
| window.addEventListener("message", (event) => { | ||
|
rebloor marked this conversation as resolved.
|
||
| console.log(event.data.result); | ||
| }); | ||
| ``` | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Link "opaque origin" to https://developer.mozilla.org/en-US/docs/Glossary/Origin#opaque_origin
Also add a bullet point mentioning that web platform APIs bound to the origin are unavailable. For some examples, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox#allow-same-origin
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done