Add content scripts section in specification

[oliverdunk]

Adds a first draft of information on content scripts in the specification.

There are still some updates needed, in particular around the algorithm for deciding when to inject a script, but I wanted to open something to get some early feedback.

---

Preview | Diff

[oliverdunk]

@Rob--W @rdcronin Would you be able to take a look at this one and confirm if it is accurate? This was my best understanding based on bugs and documentation in the code.

[rdcronin]

I think I'd rephrase this.

(The issue with the current language is that:
a] it doesn't specify what the "non-opaque" origin is or where it comes from
b] it doesn't always use the origin of the parent; it uses the initiator (or "precursor"))

If the URL of a document has a specified scheme**, the user agent will fall back to the origin of the initiator instead. This is commonly, but not always, the parent or embedding frame.

** In chrome, these schemes are data:, about:, filesystem:, and blob:. Is that the same in other browsers?

[dotproto]

Tagging @Rob--W and @xeenon to request feedback.

[Rob--W]

@oliverdunk The semantics have extensively been discussed on Chromium's issue tracker where I and Devlin discussed the API design. If you're interested, the start of the discussion is at https://issues.chromium.org/issues/40443085#comment48. The design that is close to what we have now was sketched in https://issues.chromium.org/issues/40443085#comment61 , with the final name (match_origin_as_fallback) at https://issues.chromium.org/issues/40443085#comment67. Devlin summarized the discussion at https://issues.chromium.org/issues/40443085#comment71

Upon reviewing the proposed texts here, I think that there is some confusion on terminology. The current text mentions blob URLs as an opaque origin, but that is not the case.

Relevant to content script matching is the URL of the document (which can have an origin component) and the origin of the document (as a security principal). There may not always be an obvious relation between the two:

• URLs may have visible origin parts in it, such as http(s) and also blob: and (Chrome-only) filesystem: (e.g. blob:https://example.com/UUID).
• URLs may not have a visible origin in it (about:blank and about:srcdoc), but still have a non-opaque origin: commonly the opener of the frame or window is another http(s) URL. Or even any number of about:blank/srcdoc documents where the first was initially opened by a http(s) origin.
• The security principal of a document can be an opaque origin, even if the URL of that document looks like it has a non-opaque origin. This happens with <iframe sandbox> or sandbox directive in the Content-Security-Policy. A content script can use window.origin to see whether the origin is opaque, as it would serialize to "null".
  • In case of opaque origins, there is almost always a non-opaque initiator that opened the frame. The term "precursor origin" is used here <iframe sandbox="allow-scripts" src="https://example.com">
• The exception is when the initiator of the navigation does not have a non-opaque origin. For example, when the user navigates to a data:-URL or to about:blank. Since data:-URL
  • Chrome does currently not run content scripts in these documents.
  • Firefox currently allows content scripts with matches for all URLs AND match_about_blank: true to run scripts in top-level about:blank. This is not documented anywhere though.

[oliverdunk]

Thanks both, writing the description for these two keys has taken by far the most time in this PR. I've given it another attempt and would appreciate any feedback.

As a general note, concepts like the precursor origin and security principal don't appear to be defined in any other specifications. It seems like they are more informal terms used often in implementations and by implementors. With that in mind, I've tried to describe them as best as possible without talking about them by name.

A few additional notes:

• I've added an informal note to match_about_blank describing the Firefox behavior for top-level about:blank pages.
• I've added a note that the path must be a wildcard if match_origin_as_fallback is set. This is the behavior today in Chrome. Interestingly, we don't have any restrictions on include_globs or exclude_globs. This feels like an omission to me and I wonder if we should specify something.
• In Chrome, sandboxing doesn't seem to be relevant. We always apply these fallbacks, even if the parent is inaccessible to the child frame. With that in mind, I haven't mentioned it here.

Clearly there's a lot of detail here so please let me know if I've missed anything or it could be clearer.

[rdcronin]

Thanks, Oliver! I had a chance to take a quick pass on this one.

[rdcronin]

Do we (browsers) have different criteria for match_about_blank?

[Rob--W]

The description here is too vague. match_about_blank was designed for about:blank and about:srcdoc.

If you're looking for clarity, see https://stackoverflow.com/questions/41408936/can-anyone-explain-that-what-is-the-use-of-match-about-blank-in-chrome-extensi, where I previously posted an answer that describes why match_about_blank exists and what it does.

Other documentation:

• https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts#match_about_blank
• https://developer.chrome.com/docs/extensions/reference/manifest/content-scripts#frames

[oliverdunk]

@Rob--W, could you take another look? I've made some tweaks although it's unclear to me what was too vague.

[rdcronin]

I think I'd rephrase this.

(The issue with the current language is that:
a] it doesn't specify what the "non-opaque" origin is or where it comes from
b] it doesn't always use the origin of the parent; it uses the initiator (or "precursor"))

If the URL of a document has a specified scheme**, the user agent will fall back to the origin of the initiator instead. This is commonly, but not always, the parent or embedding frame.

** In chrome, these schemes are data:, about:, filesystem:, and blob:. Is that the same in other browsers?

[jpmedley]

Sorry for the extra review. I didn't remember that I had looked at this already until I got to my first comment halfway through it.

[dotproto]

Tagging @Rob--W and @xeenon to request feedback.

[Rob--W]

Although not obvious from Github's UI, I just posted additional context on match_about_blank and match_origin_as_fallback:

• match_about_blank: Add content scripts section in specification #542 (comment)
• match_origin_as_fallback: Add content scripts section in specification #542 (comment)

[oliverdunk]

Thanks all! I've just done another pass on this, would appreciate any additional feedback.

[oliverdunk]

Thanks both, writing the description for these two keys has taken by far the most time in this PR. I've given it another attempt and would appreciate any feedback.

As a general note, concepts like the precursor origin and security principal don't appear to be defined in any other specifications. It seems like they are more informal terms used often in implementations and by implementors. With that in mind, I've tried to describe them as best as possible without talking about them by name.

A few additional notes:

• I've added an informal note to match_about_blank describing the Firefox behavior for top-level about:blank pages.
• I've added a note that the path must be a wildcard if match_origin_as_fallback is set. This is the behavior today in Chrome. Interestingly, we don't have any restrictions on include_globs or exclude_globs. This feels like an omission to me and I wonder if we should specify something.
• In Chrome, sandboxing doesn't seem to be relevant. We always apply these fallbacks, even if the parent is inaccessible to the child frame. With that in mind, I haven't mentioned it here.

Clearly there's a lot of detail here so please let me know if I've missed anything or it could be clearer.