Questions for API OWNERs around fenced frames

[Dominic Farolino]

Hi API OWNERs! (+cc domenic@ who as an HTML Editor may have opinions)

I'm working on the fenced frames feature and we have a few specific questions about API placement and ergonomics that we feel the API OWNERs may be able to provide guidance on.

1. Limiting HTMLFencedFrameElement to secure contexts
   
   There has been some discussion around whether or not we want to limit the creation of <fencedframe> elements to secure contexts. Note that this is referring to the secure-ness of the creating page, not the page inside the fenced frame (the latter is limited to potentially-trustworth URLs).
   
   We recognize that on one hand, HTTPs is basically table stakes for most new powerful APIs on the web platform. In this vein, today's known primary consumers of fenced frames do not have any requirements around using them in HTTP sites (i.e., FLEDGE is already limited to secure contexts, etc) so it should be no problem limiting FF construction to secure contexts from that perspective.
   
   On the other hand, is that enough to needlessly limit fenced frame creation to HTTPs pages? The <fencedframe> element, while originally created with today's primary consumers in mind, should be seen as a general frame loading primitive so it is unclear if it is appropriate to preclude all valid use-cases of this on HTTP sites for example. In this vein, while plenty of JS APIs are gated behind the `SecureContext` WebIDL extended attribute, there are currently no HTML elements gated behind this, so gating an element in this way seems novel, and may be less suitable to workarounds since pure-HTML sites could more easily end up with HTMLUnknownElements in place of the <fencedframe>.
   
   We consulted the TAG's design principles doc and found relatively ambiguous guidance, so we decided to see if the API OWNERs had strong opinions in either direction. For Googlers, a link to an internal chat thread about this can be found here, and here is a link to some (unfortunately internal too) discussion around SecureContexts and fenced frames in general (not specifically around creation though).
   
   

2. Where to put fenced-frame-specific APIs
   
   There are going to be a few APIs that we plan on exposing specifically inside the context of a fenced frame. Right now the list is small, but we expect it may grow with future use-cases that depend on fenced frames.
   
   One API is called `reportEvent()`, and despite it living on `navigator` in that example we are not convinced that's its proper home. Another API is one where we can navigate the top-level site in the FLEDGE use case, gated on a user gesture. We are bikeshedding around `navigateOutermostDocument("url")` or so (this would have a corresponding reserved frame name like "_outermost", similar to "_top" and "_parent"). In another use-case for fenced frames, we'd like to read the outermost Document's site before granting read-only unpartitioned storage access (i.e., getTopLevelSite() or so).
   
   We're wondering if the API OWNERs have any guidance on where these APIs should live. Same-origin iframes currently have `window.frameElement` which gives them access to the <iframe> element hosting the inner document, returning null inside cross-origin iframes. We were thinking of something like `window.fencedAPIs` that is a bag of APIs inside a fenced frame (regardless of origin), but null in other documents.
   
   Another option proposed was to consider a new Global identifier for the `Exposed` WebIDL extended attribute. Current valid values are, "Window", "Worker", "SharedWorker", "DedicatedWorker", "ServiceWorker", and the various worklet types. If we were to expose these APIs directly on the `window` global only inside of a fenced frame I believe this would entail basically subclassing `Window` and introducing `FencedWindow` where all of the `Window` APIs are exposed in addition to the fenced APIs. Since there isn't precedent for subclassing the `Window` global we're not sure if our feature warrants this (I'm thinking no) If this is too ambiguous of a design question we're happy to spend more time on it ourselves; we're mostly interested in seeing if anything seems like a clear no based on existing web platform look and feel.
   
   

3. Specification requirements for Origin Trial
   
   We are under the impression that there are no specification requirement for features going to Origin Trial. We'd like to confirm with API OWNERs that this guidance extends to fenced frames feature too, when we intend to experiment. There is some concern that due to the massive changes our spec will require to fundamental web platform specification primitives such as browsing context groups etc etc, that the API OWNERs will want to see more of a baked specification for fenced frames than is normally required at the experimenting milestone.
   
   While I think a proper specification is critical to ship, I'd like to confirm whether or not API OWNERs see any special requirements for specifications when it comes time to experiment. My impression is that we won't need to treat fenced frames in a special way here, but I'd like to confirm.

Please let me know if I can provide any more information or clear anything up.

Thanks,

Dom

[Yoav Weiss]

Hey Dominic!

Generally, I'm trying to limit my opinions on design with my API OWNER hat on to backwards and forward compat concerns. 

On Fri, Jan 14, 2022 at 1:43 AM Dominic Farolino <d...@chromium.org> wrote:

Hi API OWNERs! (+cc domenic@ who as an HTML Editor may have opinions)

I'm working on the fenced frames feature and we have a few specific questions about API placement and ergonomics that we feel the API OWNERs may be able to provide guidance on.

1. Limiting HTMLFencedFrameElement to secure contexts
   
   There has been some discussion around whether or not we want to limit the creation of <fencedframe> elements to secure contexts. Note that this is referring to the secure-ness of the creating page, not the page inside the fenced frame (the latter is limited to potentially-trustworth URLs).
   
   We recognize that on one hand, HTTPs is basically table stakes for most new powerful APIs on the web platform. In this vein, today's known primary consumers of fenced frames do not have any requirements around using them in HTTP sites (i.e., FLEDGE is already limited to secure contexts, etc) so it should be no problem limiting FF construction to secure contexts from that perspective.
   
   On the other hand, is that enough to needlessly limit fenced frame creation to HTTPs pages? The <fencedframe> element, while originally created with today's primary consumers in mind, should be seen as a general frame loading primitive so it is unclear if it is appropriate to preclude all valid use-cases of this on HTTP sites for example. In this vein, while plenty of JS APIs are gated behind the `SecureContext` WebIDL extended attribute, there are currently no HTML elements gated behind this, so gating an element in this way seems novel, and may be less suitable to workarounds since pure-HTML sites could more easily end up with HTMLUnknownElements in place of the <fencedframe>.

HTMLUnknownElement in place of a Fenced Frame does seem risky. E.g. even in the FLEDGE case, I can imagine folks integrating ads into a site without realizing that it can be accessed from both secure and non-secure contexts.

In that case, I'd expect the ad's contents to not render (because FLEDGE is not working, and potentially because the fenced frame doesn't load), but I wouldn't expect it to be a completely different element, which potentially breaks the layout of the outermost frame.

Maybe a reasonable compromise here is to have FencedFrames defined for non-secure contexts, but have their processing model limited and e.g. have them be painted as gray rectangles, without loading anything inside the frame. Would that make sense?

The guiding principle I'm using here is that a non-secure page that integrates a fenced frame should not be broken in surprising and unnecessary ways (but could be broken in necessary ways, e.g. have the fenced frame do nothing).

 

1. 
   
   We consulted the TAG's design principles doc and found relatively ambiguous guidance, so we decided to see if the API OWNERs had strong opinions in either direction. For Googlers, a link to an internal chat thread about this can be found here, and here is a link to some (unfortunately internal too) discussion around SecureContexts and fenced frames in general (not specifically around creation though).
   
   

2. Where to put fenced-frame-specific APIs
   
   There are going to be a few APIs that we plan on exposing specifically inside the context of a fenced frame. Right now the list is small, but we expect it may grow with future use-cases that depend on fenced frames.
   
   One API is called `reportEvent()`, and despite it living on `navigator` in that example we are not convinced that's its proper home. Another API is one where we can navigate the top-level site in the FLEDGE use case, gated on a user gesture. We are bikeshedding around `navigateOutermostDocument("url")` or so (this would have a corresponding reserved frame name like "_outermost", similar to "_top" and "_parent"). In another use-case for fenced frames, we'd like to read the outermost Document's site before granting read-only unpartitioned storage access (i.e., getTopLevelSite() or so).
   
   We're wondering if the API OWNERs have any guidance on where these APIs should live. Same-origin iframes currently have `window.frameElement` which gives them access to the <iframe> element hosting the inner document, returning null inside cross-origin iframes. We were thinking of something like `window.fencedAPIs` that is a bag of APIs inside a fenced frame (regardless of origin), but null in other documents.

IMO, this is not an API-OWNERs question, as it has no implications on compat.

With my API OWNER hat off, I'd say that `window.fencedAPIs` (or something similar) seems like a reasonable option, and one that would result in the least complexity. 

1. 
   
   Another option proposed was to consider a new Global identifier for the `Exposed` WebIDL extended attribute. Current valid values are, "Window", "Worker", "SharedWorker", "DedicatedWorker", "ServiceWorker", and the various worklet types. If we were to expose these APIs directly on the `window` global only inside of a fenced frame I believe this would entail basically subclassing `Window` and introducing `FencedWindow` where all of the `Window` APIs are exposed in addition to the fenced APIs. Since there isn't precedent for subclassing the `Window` global we're not sure if our feature warrants this (I'm thinking no)

That seems like a question for the HTML/WebIDL editors and/or the TAG. I tend to agree with your thinking.

 

1. If this is too ambiguous of a design question we're happy to spend more time on it ourselves; we're mostly interested in seeing if anything seems like a clear no based on existing web platform look and feel.
   
   

2. Specification requirements for Origin Trial
   
   We are under the impression that there are no specification requirement for features going to Origin Trial. We'd like to confirm with API OWNERs that this guidance extends to fenced frames feature too, when we intend to experiment. There is some concern that due to the massive changes our spec will require to fundamental web platform specification primitives such as browsing context groups etc etc, that the API OWNERs will want to see more of a baked specification for fenced frames than is normally required at the experimenting milestone.

There's no strict requirement for a spec, but there is a requirement for a detailed, developer-facing explainer that would make it clear what developers are supposed to experiment with. https://github.com/shivanigithub/fenced-frame seems fine as an explainer for the concept, but probably needs to be updated with clear developer use-cases, examples and the APIs you mention above.

With that said, we need to avoid a situation where a lengthy OT would end up with pressure to ship on the one hand, and spec work not being done on the other. To that end, I think it can be reassuring to have some sketch of what a spec would look like at the OT phase (or maybe in OT extensions, if ones are requested) to show that there is a reasonable plan for proper integration with HTML. 

1. 
   
   While I think a proper specification is critical to ship, I'd like to confirm whether or not API OWNERs see any special requirements for specifications when it comes time to experiment. My impression is that we won't need to treat fenced frames in a special way here, but I'd like to confirm.

Please let me know if I can provide any more information or clear anything up.

Thanks,

Dom

--
You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAP-uykDJCN7%3DaExGBUy4NyZi39QduE1CtLjuPgHGnN1ST2iVZA%40mail.gmail.com.

[Domenic Denicola]

I like Yoav's solution for (1), although I'm not sure there's a real compat risk that needs mitigating there. It's more just a nice bonus that makes the element have a slightly-more-graceful failure mode. 

I'd be happy to comment with my HTML-editor/API review hat on for question (2), but as Yoav says maybe this list is not the most-relevant place. Is there a GitHub issue for that question?

For (3), the only thing I'll add is that you could get a lot of benefit out of a skeleton spec. E.g., it could contain domintro blocks (serving as the web developer documentation Yoav mentions), polished examples similar to https://html.spec.whatwg.org/multipage/workers.html#introduction-14 , and IDL blocks. Maybe even an element definition.

It might also be helpful to make a public specification-work TODO list, so that it's clear to everyone that you're aware of the various integration points. That could touch on your rough plan for things like browsing context groups.

None of this seems required to me, but it might be nice to do the skeleton spec work up front instead of creating separate Markdown documents for OT documentation.