Web Extensions

1. File structure

Once unpacked from the distribution format, a WebExtension is a directory containing a number of files.

Note: In some operating systems, filenames are case insensitive. This can lead to naming collisions.

1.1. manifest.json

A Manifest file.

1.2. _locales subdirectory

An optional directory containing strings as defined in localization .

1.3. Other files

An extension may also contain other files, such as those referenced in the § 2.2.11 Key content_scripts and § 2.2.9 Key background parts of the manifest .

2. Manifest

A WebExtension must have a manifest file at its root directory.

2.1. Manifest file

A manifest file is a [JSON] document named manifest.json . Malformed JSON files are not supported. Note that some implementors may accept comments, represented by any content following // outside of a JSON string.

2.2. Manifest keys

If manifest keys that are not defined in this specification are specified, implementors must ignore those keys.

If manifest keys that are defined in this specification are specified with a different JSON type than defined in this specification, implementors must ignore those keys.

The following keys must be considered valid:

• manifest_version : required.

• name : required.

• version : required.

• default_locale : required under some conditions.

• background : optional

• commands : optional

• content_scripts : optional

• content_security_policy : optional

• description : optional

• icons : optional

• optional_permissions : optional

• options_ui : optional

• permissions : optional

• short_name : optional

• web_accessible_resources : optional

• devtools_page : optional

• externally_connectable : optional

• trial_tokens : optional

The following keys must be considered valid in Manifest V3:

• host_permissions : optional

• optional_host_permissions : optional

2.2.1. Key manifest_version

This key must be present.

2.2.2. Key name

Name of the extension used in the browser’s user interface. This should be the full name used to identify the extension. See also short_name .

This key must be present. This property can be localized.

2.2.3. Key version

This key must be present.

2.2.4. Key permissions

This key may be present.

2.2.5. Key optional_permissions

This key may be present.

2.2.6. Key host_permissions

This key may be present.

2.2.7. Key optional_host_permissions

This key may be present.

2.2.8. Key default_locale

This key must be present if the _locales subdirectory is present, must be absent otherwise.

2.2.9. Key background

This key may be present.

Specify background scripts. For relevant discussion, see https://github.com/w3c/webextensions/issues/282

2.2.10. Key commands

This key may be present.

2.2.11. Key content_scripts

The content_scripts key is a list of items representing content scripts that should be registered.

2.2.12. Key content_security_policy

This key may be present.

2.2.13. Key description

This key may be present.

2.2.14. Key icons

This key may be present.

2.2.15. Key options_ui

This key may be present.

2.2.16. Key short_name

The short name of the extension. This value should be used in contexts where name is too long to use in full. If short_name is not provided, manifest consumers should use a truncated version of name .

This key may be present. This property can be localized.

2.2.17. Key web_accessible_resources

This key may be present.

2.2.18. Key externally_connectable

This key may be present.

2.2.19. Key devtools_page

This key may be present.

2.2.20. Key trial_tokens

The trial_tokens key is an optional list of strings. These may be used by the user agent to enable experimental features for the § 6 Extension origin . The user agent may ignore or warn about any unrecognized, expired or malformed keys but any such entries must not prevent the extension from loading.

2.3. Reserved file names

Filenames beginning with an underscore ( _ ) are reserved for use by user agent.

3. Isolated worlds Execution contexts

Worlds Extensions can execute JavaScript code, in any of the following execution contexts:

• An extension context are 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 § 2.2.9 Key background .

• A content script context is an extension context and isolated JavaScript contexts world with limited access to a subset of extension APIs. This is the same underlying DOM tree 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 § 2.2.18 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 their with distinct API availability.

3.1. Isolated worlds

A world is a realm with its own set of wrappers around those DOM objects. Declarations 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 scope object ’s interface is Window , associated with the main world ’s document. The platform objects of this realm are also isolated. 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 .

4. Unavailable APIs

5. The browser global

window.browser 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 § 2.2.18 Key externally_connectable .

6. 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.

7. Localization

The _locales subdirectory of a WebExtension can contain strings for internationalization purposes.

Specify localization handling. [Issue #62]

8. Host permissions

8.1. Cross-origin fetch

9. Match patterns

A match pattern is a pattern used to match URLs. They are case-insensitive.

10. Globs

A glob can be any string . It can contain any number of wildcards where * can match zero or more characters and ? matches exactly one character.

11. Concepts

11.1. Uniqueness of extension IDs

11.2. Promises and callbacks

11.3. User gestures and activeTab

11.4. Extension permissions and web perissions

12. Content security policy

13. Architecture

13.1. Background content

13.2. 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 § 18.2 Inject a content script . Content scripts run in an isolated world by default.

13.2.1. Key matches

A list of match patterns that are used to decide which pages the user agent injects the content script into. This key is required.

13.2.2. Key exclude_matches

A list of match patterns that can be used to specify URLs where the content script should not run, even if the URL matches entries in § 13.2.1 Key matches and (if specified) § 13.2.9 Key include_globs .

13.2.3. Key js

A list of file paths, relative to the extension’s package, that should be injected as scripts.

13.2.4. Key css

A list of file paths, relative to the extension’s package, that should be injected as stylesheets.

13.2.5. Key all_frames

If all_frames is true , the content script must be injected into any subframes that match the other matching criteria for the content script. If false , content scripts will only be injected into top-level documents. Defaults to false .

13.2.6. Key match_about_blank

If this is true , use the URL of the parent frame when matching a child frame whose document URL is about:blank or about:srcdoc . See also § 18.1 Determine the URL for matching a document . Defaults to false .

13.2.7. Key match_origin_as_fallback

If this is true , use fallbacks as described in § 18.1 Determine the URL for matching a document .

No path is available when the URL to match against falls back to an origin. Therefore, when set, the user agent may treat a § 13.2.1 Key matches with a path other than /* as an error.

Defaults to false .

13.2.8. Key run_at

Specifies when the content script should be injected. Valid values are defined by the RunAt enum.

13.2.9. Key include_globs

A list of globs that a document should match. A document matches if the URL matches both the § 13.2.1 Key matches field and the § 13.2.9 Key include_globs field.

13.2.10. Key exclude_globs

A list of globs that can be used to specify URLs where the content script should not run, even if the URL matches entries in § 13.2.1 Key matches and (if specified) § 13.2.9 Key include_globs .

13.2.11. Key world

The world any JavaScript scripts should be injected into. Defaults to ISOLATED . Valid values are defined by the ExecutionWorld enum.

13.2.12. RunAt enum

enum RunAt {
    "document_start",
    "document_end",
    "document_idle"
};

The RunAt enum represents when a content script should be injected.

13.2.13. ExecutionWorld enum

enum ExecutionWorld {
    "ISOLATED",
    "MAIN"
};

The ExecutionWorld enum represents a JavaScript world .

"ISOLATED" corresponds to an isolated world .

"MAIN" corresponds to the main world .

13.3. Extension pages

14. Classes of security risk

15. Web accessible resources

16. Interaction with the web

16.1. Current behavior of cookie partitioning

17. Version number handling

18. Algorithms

18.1. Determine the URL for matching a document

To determine the URL to use for matching a document, given the document, match_origin_as_fallback and match_about_blank :

1. Let url be the document’s URL.

2. If the scheme of url is http , https or file :

   1. Return url .

3. If the scheme of url is blob , data or filesystem , or if url is about:blank or about:srcdoc :

   1. If match_origin_as_fallback is set to true :

      1. If the document’s origin is a tuple origin :

         1. Let document-origin be the serialization of the document’s origin.

         2. If the scheme of document-origin is http , https or file :

            1. Return document-origin .

         3. Else, return null.

      2. Note: If not a tuple origin , the document’s origin is an opaque origin .

         1. Let precursor-origin be the serialization of the document’s precursor origin, if any.

            "precursor origin" concept needs to be specified. It is not in the HTML spec at the moment. At least Chrome and Firefox recognize the concept, see e.g. https://bugzilla.mozilla.org/show_bug.cgi?id=1715167 .

         2. If the scheme of precursor-origin is http , https or file :

            1. Return precursor-origin .

         3. Else, return null.

   2. Else, if match_about_blank is set to true :

      1. If url is about:blank or about:srcdoc :

         1. Let opener be the active document of document’s opener browsing context .

         2. If all of the following conditions are true:

            • opener is not null

            • opener ’s origin is still the same as the document’s opener origin at creation

            • The algorithm has not been repeated for opener yet.

            Then repeat the algorithm for opener .

4. Return null.

18.2. Inject a content script

If the same extension specifies the same script twice, what should happen? ( bug )

To determine if a content script should be injected in a document:

1. Let url be the result of running § 18.1 Determine the URL for matching a document .

2. If the extension does not have access to url , return.

3. If url is not matched by a match pattern in matches , return.

4. If include_globs is present and url is not matched by any glob pattern, return.

5. If url matches an entry in exclude_matches or exclude_globs , return.

6. If this is a child frame, and all_frames is not true , return.

7. Otherwise, inject the content script. This should be done based on the run_at setting.