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

Update Storage Access API content #26558

Merged
merged 15 commits into from
May 16, 2023

Conversation

chrisdavidmills
Copy link
Contributor

Description

This PR updates the documentation for the Storage Access API, which is being shipped in Chrome 113. In particular I:

  • Added a storage-access permissions-policy directive page
  • Added an entry for it on permissions-policy main page
  • Updated description of sandbox="allow-storage-access-by-user-activation" to make it a little clearer
  • Updated wording on requestStorageAccess() page to make usage a bit clearer, include information about Permissions-Policy, and make the security information more standard MDN style.
  • Included exceptions information on hasStorageAccess()/requestStorageAccess()
  • Updated main Storage Access API page to include information on latest spec behavior and try to make sense of the browser differences and different security mechanisms
  • Checked the "Using" guide, and made some improvements

See my research document for the overall details of what this project entails.

Motivation

Additional details

Related issues and pull requests

@chrisdavidmills chrisdavidmills requested review from a team as code owners May 3, 2023 14:11
@chrisdavidmills chrisdavidmills requested review from Elchi3 and schalkneethling and removed request for a team May 3, 2023 14:11
@github-actions github-actions bot added Content:HTML Hypertext Markup Language docs Content:HTTP HTTP docs Content:WebAPI Web API docs labels May 3, 2023
@github-actions
Copy link
Contributor

github-actions bot commented May 3, 2023

Preview URLs (8 pages)
Flaws (44)

Note! 6 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Headers/Permissions-Policy/storage-access
Title: Permissions-Policy: storage-access
Flaw count: 1

  • bad_bcd_queries:
    • No BCD data for query: http.headers.Permissions-Policy.storage-access

URL: /en-US/docs/Web/API/Document
Title: Document
Flaw count: 43

  • macros:
    • /en-US/docs/Web/API/HTMLAllCollection does not exist
    • /en-US/docs/Web/API/Document/height redirects to /en-US/docs/Web/API/Element/clientHeight
    • /en-US/docs/Web/API/Document/width redirects to /en-US/docs/Web/API/Element/clientWidth
    • /en-US/docs/Web/API/Document/xmlStandalone does not exist
    • /en-US/docs/Web/API/Document/captureEvents does not exist
    • and 38 more flaws omitted
External URLs (3)

URL: /en-US/docs/Web/API/Storage_Access_API
Title: Storage Access API

(comment last updated: 2023-05-16 08:50:28)

@chrisdavidmills
Copy link
Contributor Author

Note: Tech reviewed by Chris Fredrickson from the Chromium engineering team (he chose to give me feedback via email); updates made.

@cfredric
Copy link
Contributor

LGTM, thank you!

Copy link
Member

@bsmth bsmth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of comments and fixes outstanding, but otherwise looks good, tnx 👍🏻

chrisdavidmills and others added 7 commits May 16, 2023 09:45
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
@bsmth bsmth merged commit b18b0ea into mdn:main May 16, 2023
@chrisdavidmills chrisdavidmills deleted the storage-access-api-updates branch May 16, 2023 08:52
} else {
document.hasStorageAccess().then((hasAccess) => {
async function handleCookieAccess() {
if (document.hasStorageAccess === null) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chrisdavidmills I am not quite sure this code is correct. If this API does not exist then this value would be undefined and not null. Am I missing something here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sidenote, I encountered this as we're trying to implement this API for Keycloak (keycloak/keycloak#19835).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooops, yes you are right. I am just attempting to show a basic member existence check.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets correct it in the docs? Or maybe it is better to make check !("hasStorageAccess" in document)?

Copy link

@teleginzhenya teleginzhenya Jul 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And seems like storage-access permission is not supported in Safari. @jonkoops can you confirm it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, I forgot to fix this problem. See #27718

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@teleginzhenya this is correct, the following code will throw an exception in Safari:

const permission = await navigator.permissions.query({
  name: "storage-access",
});

We recently had to fix this in Keycloak (keycloak/keycloak#21325). This also seems to affect older versions of Firefox. This should be wrapped in a try block.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonkoops ; I've updated #27718 to handle this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:HTML Hypertext Markup Language docs Content:HTTP HTTP docs Content:WebAPI Web API docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants