From 445e0834f3c2f2d1711cccadb72c1f63f03ee6ae Mon Sep 17 00:00:00 2001 From: Rob Wu Date: Sun, 31 May 2026 02:01:14 +0200 Subject: [PATCH] Specify execution context and isolated worlds --- specification/index.bs | 87 +++++++++++++++++++++++++++++++-- specification/window.browser.bs | 2 +- 2 files changed, 83 insertions(+), 6 deletions(-) diff --git a/specification/index.bs b/specification/index.bs index 9b682f0a1..47fb6b875 100644 --- a/specification/index.bs +++ b/specification/index.bs @@ -9,6 +9,7 @@ Editor: Mukul Purohit, Microsoft Corporation https://www.microsoft.com, mpurohit Editor: Tomislav Jovanovic, Mozilla https://www.mozilla.org/, tjovanovic@mozilla.com Editor: Oliver Dunk, Google https://www.google.com, oliverdunk@chromium.org Abstract: [Placeholder] Abstract. +Repository: w3c/webextensions Markup Shorthands: markdown yes @@ -108,6 +109,8 @@ This key must be present if the `_locales` subdirectory is present, must be abse This key may be present. +Issue: Specify background scripts. For relevant discussion, see https://github.com/w3c/webextensions/issues/282 + ### Key `commands` This key may be present. @@ -158,15 +161,64 @@ The `trial_tokens` key is an optional [=list=] o Filenames beginning with an underscore (`_`) are reserved for use by user agent. -# Isolated worlds +# Execution contexts + +Extensions can execute JavaScript code, in any of the following execution contexts: + +* An extension context is a [=realm=] associated with an [=extension origin=]. +* A privileged extension context is an [=extension context=] with access to the full set of extension APIs available to the extension. For example, the background page or worker defined through [[#key-background]]. +* A content script context is an [=extension context=] and [=isolated world=] with limited access to a subset of extension APIs. This is the default execution environment of all [=content scripts=] of an extension. +* The [=main world=] of a web page not associated with an [=extension origin=] is not an extension context. It does not have access to any extension API, except when an extension allows so through [[#key-externally_connectable]]. + +Some extension APIs may involve the execution of JavaScript code in contexts other than what is specified above. For example, the `userScripts` API allows the creation of `USER_SCRIPT` worlds that are isolated similarly to [=isolated worlds=] but with distinct API availability. + +## Isolated worlds + +A world is a [=realm=] with its own [=global object=]. + +The main world is the [=realm=] whose [=global object=] is the +associated document's {{Window}}, in which the document's own scripts run. +This is the realm implied throughout other specifications that assume a single +realm per document. + +A document may also have a number of [=isolated worlds=], created by the user +agent to run [=content scripts=] in a [=content script context=]. + +An isolated world is a distinct [=realm=] whose [=global object=]'s +interface is {{Window}}, associated with the [=main world=]'s document. The +[=platform objects=] of this realm are distinct from their counterparts in the +[=main world=], but operate on the same underlying state. These operations +should maintain isolation across realms: no object in an [=isolated world=]'s +realm is observable from the [=main world=]. + +
+For example, {{CustomEvent}} specifies the `event.detail` attribute that +"must return the value it was initialized to". Event dispatch can cross worlds, +and following this requirement to the letter would result in the exposure of +an object from one realm to another. Potential resolutions include: + +- Throwing at `CustomEvent` construction when a non-primitive value is passed. +- Returning `null`. +- Returning a structured clone, per [[HTML#safe-passing-of-structured-data]]. +- Returning a redacted version of the object. -Worlds are isolated JavaScript contexts with access to the same underlying DOM tree but their own set of wrappers around those DOM objects. Declarations in the global scope are also isolated. +
# Unavailable APIs # The `browser` global -# Extension origin +[[webextensions-browser-global inline]] is the primary namespace hosting extension APIs, available to [=extension contexts=]. + +Although the [=main world=] of a web page is not an [=extension context=], it may also contain the `browser` global to offer access to functionality granted by [[#key-externally_connectable]]. + +# Extension origin + +The extension origin is a [=tuple origin=] consisting of an [=extension scheme=] and an extension-specific host. An extension scheme is a browser-specific scheme reserved for extension use. + +
+Examples of [=extension schemes=] include `chrome-extension`, `moz-extension`, and `safari-web-extension`. +
# Localization @@ -202,9 +254,9 @@ A glob can be any [=string=]. It can contain any number of wildcards ## Background content -## Content scripts +## Content scripts -Content scripts represent a set of JS and CSS files that should be injected into matching pages loaded by the user agent. They are injected using the steps in [[#inject-a-content-script]]. +Content scripts represent a set of JS and CSS files that should be injected into matching pages loaded by the user agent. They are injected using the steps in [[#inject-a-content-script]]. Content scripts run in an [=isolated world=] by default. ### Key `matches` @@ -277,6 +329,10 @@ enum ExecutionWorld { The {{ExecutionWorld}} enum represents a JavaScript [=world=]. +"ISOLATED" corresponds to an [=isolated world=]. + +"MAIN" corresponds to the [=main world=]. + ## Extension pages # Classes of security risk @@ -336,3 +392,24 @@ To determine if a content script should be injected in a document: 1. If |url| matches an entry in `exclude_matches` or `exclude_globs`, return. 1. If this is a child frame, and `all_frames` is not `true`, return. 1. Otherwise, inject the content script. This should be done based on the `run_at` setting. + +
+spec:html; type:dfn; for:realm; text:global object
+
+ +
+{
+  "webextensions-browser-global": {
+    "authors": [
+      "Patrick Kettner"
+    ],
+    "href": "https://w3c.github.io/webextensions/specification/window.browser.html",
+    "title": "window.browser",
+    "status": "CG-DRAFT",
+    "publisher": "WECG",
+    "deliveredBy": [
+      "https://www.w3.org/groups/cg/webextensions/"
+    ]
+  }
+}
+
diff --git a/specification/window.browser.bs b/specification/window.browser.bs index e46105343..52621cb0a 100644 --- a/specification/window.browser.bs +++ b/specification/window.browser.bs @@ -1,6 +1,6 @@ 
 Title: window.browser
-Shortname: wecg-browser
+Shortname: webextensions-browser-global
 Level: 1
 Group: wecg
 Status: w3c/CG-DRAFT