From a20e788470779b6e7eba3fc4a8c9c73a84515816 Mon Sep 17 00:00:00 2001 From: Oliver Dunk Date: Thu, 27 Feb 2025 16:04:06 +0000 Subject: [PATCH] Merge pull request #542 from w3c/spec-content-scripts SHA: e393c3faa6f458da2f9506641c568d632e1c0496 Reason: push, by oliverdunk Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- specification/index.html | 1413 +++++++++++++++++++++++++++++++++++++- 1 file changed, 1375 insertions(+), 38 deletions(-) diff --git a/specification/index.html b/specification/index.html index 1d2f8507..2c01b5bf 100644 --- a/specification/index.html +++ b/specification/index.html @@ -7,7 +7,7 @@ - + + + + +

Web Extensions

-

Draft Community Group Report,

+

Draft Community Group Report,

More details about this document
@@ -425,6 +708,7 @@

Web Extensions

Editors:
(Microsoft Corporation)
(Mozilla) +
(Google)
@@ -498,44 +782,70 @@

Table of Contents

  • 8.1 Cross-origin fetch
  • 9 Match patterns +
  • 10 Globs
  • - 10 Concepts + 11 Concepts
      -
    1. 10.1 Uniqueness of extension IDs -
    2. 10.2 Promises and callbacks -
    3. 10.3 User gestures and activeTab -
    4. 10.4 Extension permissions and web perissions +
    5. 11.1 Uniqueness of extension IDs +
    6. 11.2 Promises and callbacks +
    7. 11.3 User gestures and activeTab +
    8. 11.4 Extension permissions and web perissions
    -
  • 11 Content security policy +
  • 12 Content security policy
  • - 12 Architecture + 13 Architecture
      -
    1. 12.1 Background content +
    2. 13.1 Background content
    3. - 12.2 Content scripts + 13.2 Content scripts
        -
      1. 12.2.1 Isolated worlds +
      2. 13.2.1 Key matches +
      3. 13.2.2 Key exclude_matches +
      4. 13.2.3 Key js +
      5. 13.2.4 Key css +
      6. 13.2.5 Key all_frames +
      7. 13.2.6 Key match_about_blank +
      8. 13.2.7 Key match_origin_as_fallback +
      9. 13.2.8 Key run_at +
      10. 13.2.9 Key include_globs +
      11. 13.2.10 Key exclude_globs +
      12. 13.2.11 Key world +
      13. 13.2.12 RunAt enum +
      14. 13.2.13 ExecutionWorld enum
      -
    4. 12.3 Extension pages +
    5. 13.3 Extension pages
    -
  • 13 Classes of security risk -
  • 14 Web accessible resources +
  • 14 Classes of security risk +
  • 15 Web accessible resources
  • - 15 Interaction with the web + 16 Interaction with the web
      -
    1. 15.1 Current behavior of cookie partitioning +
    2. 16.1 Current behavior of cookie partitioning +
    +
  • 17 Version number handling +
  • + 18 Algorithms +
      +
    1. 18.1 Determine the URL for matching a document +
    2. 18.2 Inject a content script
    -
  • 16 Version number handling
  • Conformance
    1. Document conventions
    +
  • + Index +
      +
    1. Terms defined by this specification +
    2. Terms defined by reference +
  • References
    1. Normative References
    +
  • IDL Index
  • Issues Index @@ -548,9 +858,9 @@

    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 content_scripts and background part of the Manifest.

    +

    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.

    +

    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

    @@ -622,7 +932,7 @@

    2.2.10. Key commands

    This key may be present.

    2.2.11. Key content_scripts

    -

    This key may be present.

    +

    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

    @@ -643,6 +953,7 @@

    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

    @@ -652,22 +963,156 @@

    8. Host permissions

    8.1. Cross-origin fetch

    9. Match patterns

    -

    10. Concepts

    -

    10.1. Uniqueness of extension IDs

    -

    10.2. Promises and callbacks

    -

    10.3. User gestures and activeTab

    -

    10.4. Extension permissions and web perissions

    -

    11. Content security policy

    -

    12. Architecture

    -

    12.1. Background content

    -

    12.2. Content scripts

    -

    12.2.1. Isolated worlds

    -

    12.3. Extension pages

    -

    13. Classes of security risk

    -

    14. Web accessible resources

    -

    15. Interaction with the web

    - -

    16. Version number handling

    +

    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

    + +

    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.

      +

    Conformance

    @@ -697,15 +1142,907 @@

    Note, this is an informative note.

    +

    Index

    +

    Terms defined by this specification

    + +

    Terms defined by reference

    +
      +
    • + [ECMASCRIPT] defines the following terms: +
        +
      • list +
      +
    • + [HTML] defines the following terms: +
        +
      • opaque origin +
      • opener browsing context +
      • scheme +
      • tuple origin +
      +
    • + [INFRA] defines the following terms: +
        +
      • string +
      +

    References

    Normative References

    +
    [ECMASCRIPT] +
    ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/ +
    [HTML] +
    Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
    [INFRA] +
    Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
    [JSON]
    T. Bray, Ed.. The JavaScript Object Notation (JSON) Data Interchange Format. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
    [RFC2119]
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
    +

    IDL Index

    +
    enum RunAt {
+    "document_start",
+    "document_end",
+    "document_idle"
+};
+
+enum ExecutionWorld {
+    "ISOLATED",
+    "MAIN"
+};
+
+

    Issues Index

    Specify localization handling. [Issue #62] ↵
    -
    \ No newline at end of file +
    "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. ↵
    +
    If the same extension specifies the same script twice, what should happen? (bug) ↵
    +
    • + + + \ No newline at end of file