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

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.

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.3. Reserved file names

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

3. Isolated worlds

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.

4. Unavailable APIs

5. The browser global

6. Extension origin

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.

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.

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.