Allow use in same-origin children, add Feature Policy integration

[anssiko]

Per @clelland's suggestion in #10 (comment) this change allows Battery Status API use in same-origin children, and adds Feature Policy integration.

PTAL @clelland @RByers @mounirlamouri @riju

Fixes #10.

---

Preview | Diff

[anssiko]

@clelland @RByers @mounirlamouri, any concerns?

If I don't hear any, I'll merge this and @riju will update the Chrome's implementation accordingly.

[RByers]

Looks reasonable to me. Is the plan to add a feature control hook later?

[clelland]

The only forwards-incompatibility I can see with Feature Policy here is that if a deeply nested frame happens to be same-origin with the top-document, then it will be granted access to the API by default, while feature policy would disallow that.

That is, in an A->B->A embedding scenario, both the top-level and the innermost frame would be able to use the battery API. With feature policy, the inner frame wouldn't be allowed to use it, unless the top-level doc granted it to the middle frame, which then further granted it to the inner one.

(That is, feature policy would allow access to same-origin children -- and their same-origin children, and so on -- but not to arbitrary same-origin descendent frames)

[mounirlamouri]

Do we have any idea of how common it is to have x-origin iframe usage of the Battery API? Said otherwise, are we sure we are not breaking a real use case? Are we sure this change is even web compatible?

[anssiko]

Thanks for your comments!

Is the plan to add a feature control hook later?

@RByers, that was my initial plan. That said, we could consider adding the hook on the same pass, there's just one procedural issue that need to be cleared:

The Feature Policy spec is currently in incubation, and having an unstable normative reference might be an issue if we want to advance the Battery Status API to Candidate Recommendation and beyond.

@dontcallmedom to confirm whether we could make an exception here.

Do we have any idea of how common it is to have x-origin iframe usage of the Battery API?

@mounirlamouri, I'd like to know as well, but I don't have any data.

If we care strongly about this, would Chrome be fine with us adding telemetry to figure out how common x-origin iframe usage is?

A->B->A embedding scenario

@clelland, I'd expect many other platform features be similarly impacted? If so, I wouldn't be concerned about this case at hand specifically.

Couple of questions to @clelland et al.:

Feature Policy "v1" shipped in Chrome M62. Does it have all the features implemented we'd need for this spec to integrate with it?

Do you have established conventions for spec authors on how to hook into the Feature Policy spec the right way. I'm looking for normative spec language I could borrow similarly to e.g. https://w3c.github.io/webappsec-secure-contexts/#new This helps keep specs consistent.

Thanks!

[dontcallmedom]

re CR transition with a reference to an unstable spec - this won't block transition to CR (although we would want to highlight it in the transition request), but may block transition to PR. That being said, transition to PR needs a 2nd implementation we don't have yet.

[anssiko]

Thanks for the confirmation @dontcallmedom.

With that, I'd be happy to hook this spec into the Feature Policy spec when shown the preferred conventions in doing so.

[clelland]

@anssiko -- I think that we do have all of the features implemented in Chromium to do that. As long as the plan is just to reject the promise when disallowed, then it should be pretty simple.

I've written up a spec integration guide at https://github.com/WICG/feature-policy/blob/gh-pages/integration.md -- it's not strictly normative, but take a look and see if gives you enough guidance for the wording. If there's anything that I can add to that to help you out, I'm glad to do it.

[anssiko]

@clelland, thanks, the integration guide is very helpful.

I added Feature Policy integration in c2083ad, PTAL. See also the preview.

(I assumed the integration guide means "SecurityError" DOMException.)

[clelland]

@anssiko: Yes, that should totally read SecurityError DOMException, thanks :) PR fired. The actual error, though, should be whatever makes sense for the API -- whether rejecting a promise, or returning an error code, the important thing is just defining some way for the API to fail when disabled.

This change LGTM, though -- thanks!

[anssiko]

@mounirlamouri PTAL and merge this PR if you're happy.

[anssiko]

@mounirlamouri, gentle ping.

Others on this PR seem to be fine with this change, would like to get your explicit OK prior to merging.

[anssiko]

@mounirlamouri, we'll merge this PR unless we hear concerns from you by next Tuesday 24 Oct, to be followed by a corresponding patch to Chromium.

[anssiko]

@Honry, as we prepare for this PR to land, could you evaluate the gaps in the battery-status test suite (in the spirit of test as you commit, soon to be adopted for all deliverables), and update the test suite accordingly? Even if I see my name in OWNERS, I may not have the cycles to pull off the test suite update at this time, and I'd +1 you to become an owner for the battery status test suite.

On a quick glimpse, I think we need to update the iframe tests and add new tests the Feature Policy integration, and test interesting edge cases such as #13 (comment)

@foolip, this is another API that needs a bunch of manual tests due to its inherent nature, similarly to Vibration API. Is the following guide still considered the state of the art in manual w-p-t testing? :-)

http://web-platform-tests.org/writing-tests/manual.html

[Honry]

@anssiko, according to the test as you commit policy, would you please add a label "needs tests" to this PR?

I will add a corresponding PR in w-p-t to reflect the changes and involve my name in OWNERS file.
Then revisit current test coverage. :)

[anssiko]

would you please add a label "needs tests" to this PR?

Done. Thanks for your help updating this test suite too!

[Honry]

I will add a corresponding PR in w-p-t to reflect the changes and involve my name in OWNERS file.

Done at web-platform-tests/wpt#7944, PTAL.

[mounirlamouri]

Sorry for the delay Anssi :( I still disagree with this change as I think it's curing thy symptoms, not the disease. The API should have an implementation that is privacy friendly.

This said, in practice, my main concern is whether this will break web pages. Was a use counter added into Chrome to discover how large the impact of this change would be and whether the deprecation is web-compatible? I don't think we can disable this in Chrome without this information.

[clelland]

@mounirlamouri, I don't think we've added a use counter for that into Chrome.

When we were looking at a similar behaviour change for the Fullscreen API, I think we added one that fired every time a same-origin page was blocked from entering fullscreen.

We could add a similar counter here for battery-status, as well as one that fires when a same-origin-as-root-but-embedded-cross-origin page successfully uses the API. If we do it quickly enough, we should be be able to get that change merged for M63, to get some actual data before the end of the year.

[mounirlamouri]

I think something that checks the usage in x-origin iframe and another for same origin should be enough.

[clelland]

So Chrome doesn't currently restrict getBattery at all. Fully complying with this change would block the API in Chrome:

• in all insecure contexts
• in any frame which is at a different origin than its parent (without an appropriate feature policy)
• in any frame which is at a different origin than the top-level document (again, without an appropriate feature policy)

If we add counters for those situations, then we should have a good idea how much usage would be broken by adopting this change (and also adopting the current spec as-is).

(Also, this is Chrome-specific, but both caniuse and the API confluence dashboard suggest that the API is not implemented anywhere else -- if that's wrong, it could change the 'web-compatible' calculation quite a bit)

[anssiko]

(Here's an HTML diff comparing this branch with gh-pages to ease review, e.g. at F2F. I enabled pr-preview to automate this for any subsequent PRs.)

[clelland]

With feature policy integration, I think you can replace this entire paragraph with something like

If this Navigator object's relevant global object's associated Document is not allowed to use the battery feature, then reject...

Because the default allowlist is 'self', that will automatically take care of the same-origin embed case, while allowing cross-origin usage only if explicitly enabled by the embedding document (which this paragraph still prohibits, I think)

[anssiko]

I pushed an update in an attempt to make use of "allowed to use". Please take a look. (I'm happy to see "allowed to use" abstracted out and reusable.)

[clelland]

Minor nit: the value for the default allowlist would be 'self', with single quotes included

You can just say now

The Battery Status API is a policy-controlled-feature identified by the string "battery". It's default allowlist is 'self'.

[anssiko]

Ditto, pushed an update per your proposal.

[clelland]

One small comment about the non-normative explanation; this looks great otherwise.

[clelland]

You could add something like "unless specifically allowed by the document's feature policy." to this, if you wanted to be clear that it's possible to grant access to cross-origin subframes, but you have to be deliberate about it. The default situation is exactly as you describe here.

[anssiko]

@clelland, thanks for your comments! I integrated your suggestion and pushed an update. At F2F, we can gauge whether we have consensus to land this and update the implementation(s) accordingly. I invited @mounirlamouri to join as well.

[anssiko]

(Note to self: s/It’s/Its/)

[anssiko]

F2F Resolution: https://www.w3.org/2018/10/22-dap-minutes.html#x05

[anssiko]

(Rebased with gh-pages and fixed merge conflicts in a9e3c94.)

[anssiko]

Time for the annual update to this issue ☺️

There are the following battery use counters invoked in getBattery.

In percentages of Chrome page loads (across all channels and platforms) that use the corresponding feature at least once, as of today:

• 18.474067% BatteryStatusGetBattery
• 4.141155% BatteryStatusCrossOrigin
• 1.652762% BatteryStatusInsecureOrigin
• 0.004663% BatteryStatusSameOriginABA

[css-meeting-bot]

The Devices and Sensors Working Group just discussed Battery Status, and agreed to the following:

• RESOLUTION: Replace SecurityError with NotAllowedError in step 2 of getBattery() algorithm and merge #13.

The full IRC log of that discussion

<reillyg> Topic: Battery Status
<anssik> github: https://github.com//pull/13
<reillyg> Anssi: In Chrome the battery status API is currently available in cross-origin iframes.
<reillyg> ... Mozilla had concerns about this API and dropped it a long time ago.
<reillyg> Tom: Looking at stats on HTTP Archive ads are the biggest user of this cross-origin.
<reillyg> Reilly: It doesn't seem like we've seen a clearly articulated reason not to land this PR.
<tomayac> Usage stats: https://chromestatus.com/metrics/feature/timeline/popularity/2198
<reillyg> Anssi: The issue is breaking sites.
<reillyg> flaki: If you have metrics for APIs like this then from a standardization point of view we should provide more restrictive versions of these APIs.
<reillyg> ... For example, "is on battery power" vs. "what is the current battery level"
<reillyg> Anssi: In retrospect, agreed.
<reillyg> ... The current usage is very high for taking this API away for cross-origin contexts.
<reillyg> Reilly: Ian, do we have exerience taking away APIs like this with FP in other contexts?
<reillyg> ... What has been the reaction?
<reillyg> Ian: Geolocation is currently under feature policy.
<reillyg> Tom: We didn't hear massive outcry.
<reillyg> Ian: It's easy to fix in legitimate use cases.
<reillyg> Anssi: Do we know what will break?
<reillyg> Reilly: chromestatus.com includes top URLs using the API.
<tomayac> The post from geolocation days: https://developers.google.com/web/updates/2016/04/geolocation-on-secure-contexts-only
<reillyg> Reilly: We should post an Intent to Implement/Deprecate and just do it.
<reillyg> Ian: Some people think we should just cut it down to a small number of buckets.
<reillyg> Reilly: I think we should do both.
<tomayac> Intent to deprecate: insecure usage of powerful features: https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/2LXKVWYkOus/gT-ZamfwAKsJ
<reillyg> Ian: Is the proposal still to never resolve the promise?
<reillyg> Reilly: Why not reject with NotAllowedError?
<reillyg> Anssi: For compatibility with existing content.
<reillyg> Reilly: Shouldn't script have already been written to handle other failures?
<reillyg> Ian: We could browse the web with canary running with this disabled and see how bad it is.
<reillyg> Reilly: Both mechanisms will break content but never resolving will break content in weirder ways.
<tomayac> and wronger ways
<reillyg> Reilly: The current PR text rejects with a SecurityError. It should be a NotAllowedError but otherwise is the right behavior.
<reillyg> PROPOSED RESOLUTION: Replace SecurityError with NotAllowedError and merge existing PR.
<reillyg> PROPOSED RESOLUTION: Replace SecurityError with NotAllowedError and merge #13.
<reillyg> PROPOSED RESOLUTION: Replace SecurityError with NotAllowedError in step 2 of getBattery() algorithm and merge #13.
<reillyg> Anssi: Any concerns given wide-scale implications?
<reillyg> [None heard]
<reillyg> Ian: Are there other interfaces in the Battery API which should be gated by FP?
<reillyg> Anssi: getBattery() is the only entrypoint.
<reillyg> RESOLUTION: Replace SecurityError with NotAllowedError in step 2 of getBattery() algorithm and merge #13.

[anssiko]

Merging this PR per F2F resolution #13 (comment). This branch includes 3e08915 that was part of the resolution.

[anssiko]

Thanks to @Honry, now also Feature Policy section is updated. Consider #24 to be a part of this PR.

[anssiko]

• web-platform-tests Add feature-policy to battery-status web-platform-tests/wpt#7944
• Chromium https://crbug.com/1007264