[Specification] Spec should clearly outline fenced APIs + fencing principles

[VergeA]

In order to clarify what restrictions fenced frames impose on the embedded document and the embedder, the spec should describe the following:

1. A clear set of APIs with behaviors that must be fenced, and guidance on how that fencing should work.
2. Underlying principles for APIs that do not need to be fenced.

[domfarolino]

I definitely agree with (2), and I think @blu25 has some documentation somewhere outlining this, that we could probably add to the non-normative introduction in the spec.

Can you clarify point (1)? A clear set of APIs that are fenced is basically the general specification's job, right? It sounds like you're either asking for a list of APIs that need to be normatively plugged up (which is what the spec prose is doing), or you're asking for principles to help people make this determination, which sounds like (2)?

[VergeA]

The request to file this came up in the discussion of whether or not to fence the properties of the Screen API (window.screen). If we choose not to fence it, then it increases the need for something like (2) to describe why.

Where (1) comes up is: if the API is fenced, how to we let users of the fenced frame element know that the properties will be different, to avoid surprising them? Is the "integration with the web platform" doc the definitive place to do so?

Maybe (1) is more of my own unfamiliarity with spec language. An example that comes to mind is postMessage(), which is explicitly declared to be disallowed in fenced frames in the doc linked above. However, I don't see any mention of this explicitly in the spec. Is disabling postMessage() a second-order effect of a change described in the spec, should it be documented explicitly there, or is the separate explainer page the best place to do so? Does the justification for where to put this information extend to other APIs like Screen?

[domfarolino]

The fencing of some APIs will be very explicit and direct, while others like postMessage() will be pretty indirect as you've discovered, since it's achieved by the spec not making it possible to get a handle to a Window/WindowProxy object outside of the fenced frame tree etc. A final list of all of these APIs is probably best placed in an MDN article honestly, or maybe just a giant non-normative section of the spec describing all of these APIs specifically (including the implicit ones). MDN feels right though.

[VergeA]

MDN sounds good to me as well. It would be nice to have a more formal venue than the explainer for developers to use for API restriction references, and an MDN article fits that nicely.