Update Storage Access API content

[chrisdavidmills]

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

[github-actions]

Preview URLs (8 pages)

• /en-US/docs/Web/API/Document/hasStorageAccess
• /en-US/docs/Web/API/Document/requestStorageAccess
• /en-US/docs/Web/API/Document
• /en-US/docs/Web/API/Storage_Access_API/Using
• /en-US/docs/Web/API/Storage_Access_API
• /en-US/docs/Web/HTML/Element/iframe
• /en-US/docs/Web/HTTP/Headers/Permissions-Policy/storage-access
• /en-US/docs/Web/HTTP/Headers/Permissions-Policy

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

• https://blog.mozilla.org/en/mozilla/firefox-androids-new-privacy-feature-total-cookie-protection-stops-companies-from-keeping-tabs-on-your-moves/ (1 time) (Note! This may be a new URL 👀)
• https://developer.chrome.com/docs/privacy-sandbox/first-party-sets/ (2 times) (Note! This may be a new URL 👀)
• Improving the Storage Access API security model privacycg/storage-access#113 (1 time) (Note! This may be a new URL 👀)

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

[chrisdavidmills]

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

[cfredric]

LGTM, thank you!

[bsmth]

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

[jonkoops]

@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?

[jonkoops]

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

[chrisdavidmills]

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

[teleginzhenya]

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

[teleginzhenya]

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

[chrisdavidmills]

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

[jonkoops]

@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.

[chrisdavidmills]

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