1859619 - Provide explanations about system principal code and web extension content scripts interacting with content through wrappers for WebIDL bindings. Maybe current/incumbent/entry global and SecureContext and for same-origin iframes too

Status: NEW

(Webtools :: Searchfox, enhancement)

Description

[Andrew Sutherland [:asuth] (he/him)]

It can be hard to reason about, or at least perfectly remember the rules involved for, what's going on in some cross-global situations like:

• Code running with the system principal reaching into a content global for JSActor and/or "browser" test reasons.
• Web Extension Content Scripts operating in a sandbox with an expanded principal consisting of the underlying content principal and the extensions's (content) principal.
• Multiple window globals for the same origin where script from one global is reaching into another same-origin iframe's global and that global potentially can not be fully active.
• JS-Implemented WebIDL maybe.

We have some excellent docs in these areas:

• The ScriptSettings comments about entry/incumbent/current global are great.
• The script security and its xray vision docs are great too.

Searchfox could potentially help in a situation like this by:

• Allowing a tree to configure:
  • A list of explainer templates that could be offered as things to run against symbols with specific labels and/or matching specific patterns.
  • Each explainer would be a liquid templating language doc to produce markdown output.
  • For each explainer, a list of queries that should be run in order to provide data to the templates for when they are evaluated. This is as opposed to having the template evaluation be able to run searchfox queries. This approach of running queries as a logically distinct step before the explainer should help debugging and performance.
    • The query approach also could allow searchfox to assist in learning by helping users identify the cases that are different than the explanation they're looking at because their queries result in different data. For example, a query that cares whether a binding implementation calls GetIncumbentGlobal from its implementation (potentially transitively) is potentially notably different from one that does not.
    • There might be 2 layers of queries here; one would be "input" queries that would enable the above point, and then "rendering" queries that might do things like help produce SVG diagrams that are relevant but which would not directly aid in discovery of slightly different cases in the tree.
  • Each explainer might also define existing in-tree markdown docs that it wants to extract text from via some kind of selector. The intent here would be to:
    • Allow the explainers to reuse pieces of existing documentation text without having to copy-and-paste and the resulting maintenance problems that would inevitably arise.
    • Making the explainer dependencies on the in-tree docs more explicit both to avoid people changing the docs and breaking the explainer without realizing, but also to make explainers discoverable if you're looking at the normal docs.
• The explainers would be exposed via the context menu and potentially in search results.
• When invoked the explainer would run the queries, pipe that output to the liquid template to produce markdown, then the markdown would be rendered to HTML. Our markdown rendering process itself might allow for some additional searchfox graphviz rendering to happen too.

Other situations where explainers could be intersting:

• Storage APIs and the storage key / PartitionedPrincipal/EffectiveStoragePrincipal. While this is interesting with the system and expanded principal cases too, there are also interesting permutations around first-party storage access, third-party iframe storage access, and first-party iframe storage access that maybe don't need the system/expanded cases mixed in.
• things in general with detached iframes.

I'll try and edit this post in the future with what the doc presentation and details might look like as I remember/encounter specific scenarios. In general, a table-like / small-multiples presentation probably makes the most sense, but there is potential for diagrams to potentially convey the presence of wrappers and to visually show them and the impact they have on values as we potentially/conceptually move through the wrappers and whether they're being bypassed via xray, etc.