Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
VergeA opened this issue Sep 8, 2023 · 4 comments
Labels
specification Additions to specifications

Comments

@VergeA
Copy link
Collaborator

VergeA commented Sep 8, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator Author

VergeA commented Sep 8, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator Author

VergeA commented Sep 8, 2023

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.

@gtanzer gtanzer added the specification Additions to specifications label Apr 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
specification Additions to specifications
Projects
None yet
Development

No branches or pull requests

3 participants