Update Storage Access API content

files/en-us/web/api/document/hasstorageaccess/index.md

@@ -8,7 +8,7 @@ browser-compat: api.Document.hasStorageAccess
 
 {{APIRef("Storage Access API")}}
 
-The **`hasStorageAccess()`** method of the {{domxref("Document")}} interface returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to its first-party storage.
+The **`hasStorageAccess()`** method of the {{domxref("Document")}} interface returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to unpartitioned cookies.
 
 This method is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API).
 
@@ -24,9 +24,19 @@ None.
 
 ### Return value
 
-A {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to its first-party storage.
+A {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to unpartitioned cookies — `true` if it does, and `false` if not.
 
-If the promise gets resolved and a user gesture event was being processed when the function was originally called, the resolve handler will run as if a user gesture was being processed, so it will be able to call APIs that require user activation.
+The result returned by this method can be inaccurate in a couple of circumstances:
+
+1. The user may have browser settings active that block unpartitioned cookies entirely — in this case `true` may be returned even though unpartitioned cookies are still inaccessible. To handle such a situation, you should gracefully handle any errors resulting in cookie values being unretrievable; for example, inform the user that access to their personalized settings is blocked and invite them to sign in again to use them.
+2. The browser might not block third-party cookie access by default — in this case `false` may be returned even though unpartitioned cookies are accessible, and storage access wouldn't need to be requested (i.e. via {{domxref("Document.requestStorageAccess()")}}). To get around this issue, you could query {{domxref("Document.cookie")}} to find out whether your cookies are accessible, and call {{domxref("Document.requestStorageAccess()")}} if they are not.
+
+> **Note:** If the promise gets resolved and a user gesture event was being processed when the function was originally called, the resolve handler will run as if a user gesture was being processed, so it will be able to call APIs that require user activation.
+
+### Exceptions
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Thrown if the current {{domxref("Document")}} is not yet active.
 
 ## Examples
 
@@ -41,6 +51,8 @@ document.hasStorageAccess().then((hasAccess) => {
 });
 ```
 
+> **Note:** See [Using the Storage Access API](/en-US/docs/Web/API/Storage_Access_API/Using) for a more complete example.
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/document/index.md

@@ -241,7 +241,7 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT
 - {{DOMxRef("Document.getSelection()")}}
   - : Returns a {{DOMxRef('Selection')}} object representing the range of text selected by the user, or the current position of the caret.
 - {{DOMxRef("Document.hasStorageAccess()")}}
-  - : Returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to its first-party storage.
+  - : Returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to unpartitioned cookies.
 - {{DOMxRef("Document.importNode()")}}
   - : Returns a clone of a node from an external document.
 - {{DOMxRef("Document.prepend()")}}
@@ -257,7 +257,7 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT
 - {{DOMxRef("Document.replaceChildren()")}}
   - : Replaces the existing children of a document with a specified new set of children.
 - {{DOMxRef("Document.requestStorageAccess()")}}
-  - : Returns a {{jsxref("Promise")}} that resolves if the access to first-party storage was granted, and rejects if access was denied.
+  - : Allows a document loaded in a third-party context (i.e. embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies, in cases where user agents by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy.
 - {{domxref("Document.startViewTransition()")}} {{Experimental_Inline}}
   - : Starts a new {{domxref("View Transitions API", "view transition", "", "nocode")}} and returns a {{domxref("ViewTransition")}} object to represent it.
 - {{DOMxRef("Document.mozSetImageElement()")}} {{Non-standard_Inline}}

files/en-us/web/api/document/requeststorageaccess/index.md

@@ -6,11 +6,13 @@ page-type: web-api-instance-method
 browser-compat: api.Document.requestStorageAccess
 ---
 
-{{APIRef("Storage Access API")}}
+{{APIRef("DOM")}}
 
-The **`requestStorageAccess()`** method of the {{domxref("Document")}} interface returns a {{jsxref("Promise")}} that resolves if the access to first-party storage was granted, and rejects if access was denied.
+The **`requestStorageAccess()`** method of the {{domxref("Document")}} interface allows a document loaded in a third-party context (i.e. embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies.
 
-This is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API).
+This is relevant to user agents that by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy (e.g. to prevent tracking), and is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API).
+
+> **Note:** Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Glossary/Clickjacking) heuristics, or prompting the user for explicit permission.
 
 ## Syntax
 
@@ -24,12 +26,23 @@ None.
 
 ### Return value
 
-A {{jsxref("Promise")}} that fulfills with `undefined` if the access to first-party storage was granted, and rejects if access was denied.
+A {{jsxref("Promise")}} that fulfills with `undefined` if the access to unpartitioned cookies was granted, and rejects if access was denied.
+
+`requestStorageAccess()` requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click ({{Glossary("transient activation")}}), or unless permission was already granted previously. If permission was not previously granted, they need to be run inside a user gesture-based event handler. The user gesture behavior depends on the state of the promise:
+
+- If the promise resolves (i.e. if permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs that require a user gesture.
+- If the promise rejects (i.e. permission was not granted), then the user gesture has been consumed, so the script can't do anything that requires a gesture. This is intentional protection against abuse — it prevents scripts from calling `requestStorageAccess()` in a loop until the user accepts the prompt.
 
-When the promise gets resolved, the resolve handler will run as if a user gesture is being processed, whether the promise was fulfilled or rejected:
+### Exceptions
 
-- In the former case, code can then start to call APIs that require user activation and things can move forward.
-- In the latter case, code can run to inform the user of why the request failed and what they can do to continue (for example asking them to log in, if that is a requirement).
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Thrown if the current {{domxref("Document")}} is not yet active.
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if:
+    - The document's window is not a [secure context](/en-US/docs/Web/Security/Secure_Contexts).
+    - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+    - The document or the top-level document has a `null` origin.
+    - The embedding {{htmlelement("iframe")}} is sandboxed, and the `allow-storage-access-by-user-activation` token is not set.
 
 ## Examples
 
@@ -44,15 +57,7 @@ document.requestStorageAccess().then(
 );
 ```
 
-## Security
-
-Access to cross-site cookies is granted to iframes based on a number of prerequisites:
-
-1. The browser must be processing a user gesture ({{Glossary("transient activation")}}).
-2. The document or the top-level document must not have a null origin.
-3. The document's window must be a [secure context](/en-US/docs/Web/Security/Secure_Contexts).
-4. If the document is sandboxed, it must have the `allow-storage-access-by-user-activation` token.
-5. The document must pass additional browser-specific checks. Examples: allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Glossary/Clickjacking) heuristics, or prompting the user for explicit permission.
+> **Note:** See [Using the Storage Access API](/en-US/docs/Web/API/Storage_Access_API/Using) for a more complete example.
 
 ## Specifications