The Storage Access API

2. Infrastructure

This specification depends on the Infra standard. [INFRA]

3. The Storage Access API

This specification defines a method to query whether or not a Document currently has access to its unpartitioned data ( hasStorageAccess() ), and a method that can be used to request access to its unpartitioned data ( requestStorageAccess() ).

Unpartitioned data is client-side storage that would be available to a site were it loaded in a first-party-site context .

A Document is in a first-party-site context if it is the active document of a top-level browsing context . Otherwise, it is in a first-party-site context if it is an active document and the origin and top-level origin of its relevant settings object are same site with one another.

A Document is in a third party context if it is not in a first-party-site context .

3.1. User Agent Changes to user agent state related to storage access

A storage access map is a map whose keys are partitioned storage keys and whose values are storage access flag sets . User Agents maintain a single global storage access map . What is Modify the lifecycle definition of the global storage access map ? How long do we remember its contents? Firefox and Safari differ here. [Issue #privacycg/storage-access#2] environment When do we age out entries in the global storage access map ? See also Scope of Storage Access . [Issue #privacycg/storage-access#5] following manner:

1. Each agent cluster has Add a storage access map . When an agent cluster is created, its new member called has storage access map is initialized with a clone of the global storage access map type boolean .

To obtain Modify the storage access map for a Document definition of source snapshot params doc , run in the following steps: manner:

1. Return the Add a new member called has storage access map of doc ’s relevant agent 's agent cluster type boolean .

2. Add a new member called environment id of type opaque string .

A partitioned storage key is a tuple consisting of a top-level site (a site ) and an embedded origin (an origin ).

To generate a partitioned storage key for a Document doc , run the following steps:

1. Let settings be doc ’s relevant settings object .

2. Let site be the result of obtaining a site from settings ’ origin .

3. If doc ’s browsing context is a top-level browsing context , return the partitioned storage key ( site , site ).

4. Let top-level site be the result of obtaining a site from settings ’ top-level origin .

5. Return the partitioned storage key ( top-level site , site ).

3.2. Changes to Document

partial interface Document {
  Promise<boolean> hasStorageAccess();
  Promise<undefined> requestStorageAccess();
};

When invoked on Document doc , the hasStorageAccess() method must run these steps:

1. Let p be a new promise .

2. If doc is not fully active , then reject p with an " InvalidStateError " DOMException and return p .

3. If doc ’s origin is an opaque origin , resolve p with false and return p .

4. Let global be doc ’s relevant global object .

5. If global is not a secure context , then resolve p with false and return p .

6. If doc ’s browsing context is a top-level browsing context , resolve p with true and return p .

7. If the top-level origin of doc ’s relevant settings object is an opaque origin , resolve p with false and return p .

8. If doc ’s origin is same origin with the top-level origin of doc ’s relevant settings object , resolve p with true and return p .

9. Let key be the result of generating a partitioned storage key from doc . If key is failure, resolve p with false and return p . Let hasAccess be the result of running determine if a site has storage access with key and doc . Queue a global task on the permissions task source given global to resolve p with hasAccess . |global’s| has storage access .

10. Return p .

Shouldn’t step 8 be same site ?

When invoked on Document doc , the requestStorageAccess() method must run these steps:

1. Let p be a new promise .

2. If doc is not fully active , then reject p with an " InvalidStateError " DOMException and return p .

3. Let global be doc ’s relevant global object .

4. If global is not a secure context , then reject p with a " NotAllowedError " DOMException and return p .

5. If this algorithm was invoked when doc ’s Window object did not have transient activation , reject p with a " NotAllowedError " DOMException and return p . If doc ’s browsing context is a top-level browsing context , resolve and return p .

6. If doc is not allowed to use the " "storage-access" storage-access permission, ", reject p with a " NotAllowedError " DOMException and return p .

7. If doc ’s origin is an opaque origin , reject p with a " NotAllowedError " DOMException and return p .

8. If the top-level origin of doc ’s relevant settings object is an opaque origin , reject p with a " NotAllowedError " DOMException and return p .

9. If doc ’s origin is same origin with the top-level origin of doc ’s relevant settings object , resolve and return p .

10. If doc ’s active sandboxing flag set has its sandbox storage access by user activation flag set, reject p with a " NotAllowedError " DOMException and return p .

11. Let If key global be the result of generating a partitioned ’s has storage key access from doc . If key is failure, reject true, resolve p with a " NotAllowedError " DOMException undefined and return p . return.

12. Let map has transient activation be the result of obtaining the storage access map for whether doc . Let flag set be the result of obtaining the storage access flag set with key from map . If flag set ’s has storage access flag is set, resolve Window and return p . object has transient activation .

13. Otherwise, run these Run the following steps in parallel :

    1. Let hasAccess process permission state be an algorithm that, given a new promise . Determine the storage access policy permission state with key state , doc and hasAccess . runs the following steps:

       1. Queue a global task on the permissions permission task source given global to to:

          1. If state is granted :

             1. Set flag set global ’s has storage access flag . to true.

             2. If Resolve hasAccess p is true, resolve with undefined .

          2. Else:

             1. Consume user activation given p global .

             2. Reject p with a " NotAllowedError " DOMException .

    2. Return Let p . We shouldn’t use the permissions task source here. [Issue #privacycg/storage-access#144] Shouldn’t step 9 previous permission state be same site ? 3.2.1. User Agent storage access policies Different User Agents have different policies around whether or not sites may access their unpartitioned data when they’re in a third party context . User Agents check and/or modify these policies when client-side storage is accessed (see § 3.4 Changes to various client-side storage mechanisms ) as well as when hasStorageAccess() the result of getting the current permission state given " storage-access and requestStorageAccess() are called. To determine if a site has storage access with partitioned storage key key " and Document doc , run these steps: global .

    3. Let If map previous permission state be the result of obtaining the storage access map for doc . is not prompt :

       1. Let Run flag set process permission state be the result of obtaining the storage access flag set with key from map previous permission state .

       2. Abort these steps.

    4. If flag set ’s has storage access flag transient activation is set, return true. false:

       1. Return false. To determine the storage access policy for partitioned storage key Run key process permission state with Document doc and Promise p , run these steps: denied .

       2. Let map be the result of obtaining the storage access map for doc . Abort these steps.

    5. Let flag set key be the result of obtaining the generating a partitioned storage access flag set with key from map doc .

    6. Let implicitly granted and implicitly denied (each a boolean ) be the result of running an implementation-defined set of steps to determine if key ’s embedded origin 's request for storage access on key ’s top-level site should be granted or denied without prompting the user.

    7. Let global be doc ’s relevant global object . If implicitly granted is true, queue a global task on the permissions task source given true:

       1. Run global process permission state to resolve p , and return. with granted .

       2. Abort these steps.

    8. If implicitly denied is true, queue a global task on the permissions task source given global to reject true:

       1. Run p process permission state with a " NotAllowedError " DOMException , and return. denied .

       2. Abort these steps.

    9. Let permissionState be the result of requesting permission to use " storage-access ".

    10. If permissionState is "granted", queue a global task on the permissions task source given Run global process permission state to resolve with p , and return. permissionState .

14. Unset Return flag set ’s has storage access flag . p .

    If doc ’s Window

object has transient activation , consume NOTE: The intent of this algorithm is to always require user activation with it. before a storage-access permission will be set. Though it is within the means of user agents to set storage-access permissions based on custom heuristics without prior user activation, this specification strongly discourages such behavior, as it could lead to interoperability issues.

Queue a global task on We shouldn’t use the permissions task source here. [Issue #privacycg/storage-access#144] given global to reject p with a " NotAllowedError

" DOMException . Shouldn’t step 9 be same site ?

3.3. Changes to navigation

Before changing When snapshotting source snapshot params :

1. Set has storage access to sourceDocument ’s has storage access .

2. Set environment id to sourceDocument ’s relevant settings object 's id .

To the current entry of a session history, run create navigation params by fetching algorithm, insert the following steps: step as step 3:

1. Let doc originalURL be current entry’s Document entry ’s URL.

When creating request ’s reserved client . in create navigation params by fetching :

1. Let Set reserved client 's has storage access to map sourceSnapshotParams be the result of obtaining the ’s has storage access map for if all of the following hold:

   1. doc sourceSnapshotParams ’s browsing context environment id equals navigable ’s active document 's top-level browsing context relevant settings object 's id .

   2. Let key originalURL be the result of generating a partitioned storage key ’s origin from is same origin with doc . currentURL ’s origin .

   3. If key response is failure, abort these steps. null or response ’s has-cross-origin-redirects is false.

2. Let flag Otherwise, set request be the result of obtaining the ’s reserved client 's has storage access flag set with key from map . to false.

When setting up a window environment settings object :

1. Unset Set flag set settings object ’s has storage access to reserved environment ’s has storage access flag .

What this section should look like ultimately hinges on [Issue #privacycg/storage-access#3]

Add links to current entry and session history to reflect the navigation and session history rewrite . [Issue #privacycg/storage-access#137]

3.4. Changes to various client-side storage mechanisms

This API only impacts HTTP cookies. A future revision of this API might impact other client-side state. [RFC6265]

3.4.1. Cookies

This API is intended to be used with environments and user agent configurations that block access to unpartitioned cookies in a third party context . At the time of this writing, this concept has not yet been integrated into the HTTP-network-or-cache fetch and cookie algorithms. To allow for such an integration, the cookie store will need to be modified to receive information about the top-level and embedded site of the request (to determine whether to attach cross-site, partitioned, or no cookies) as well as whether the request was made for a document that has storage access, through running accessing the determine if a site environment 's has storage access algorithm that is defined in this specification.

Once the cookie store allows for receiving information about storage access, we would update HTTP-network-or-cache fetch and cookie to run determine if a site pass the environment 's has storage access and pass this information to the cookie store when retrieving cookies.

When getting unpartitioned cookies from the cookie store with storage access, user agents will still follow applicable SameSite restrictions (i.e., not attach cookies marked SameSite=Strict or SameSite=Lax in third party contexts ).

Note: User agents could apply different default values for the SameSite cookie attribute. This could lead to unpartitioned cookies without a SameSite attribute being attached to requests in some user agents (where SameSite=None is the default), but not in others (where SameSite=Lax is the default). Web developers are encouraged to set the SameSite attribute on their cookies to not run into issues.

3.5. Sandboxing storage access

A sandboxing flag set has a sandbox storage access by user activation flag . This flag prevents content from requesting storage access.

To the parse a sandboxing directive algorithm, add the following under step 3:

• The sandbox storage access by user activation flag , unless tokens contains the allow-storage-access-by-user-activation keyword.

4. Permissions Integration

The Storage Access API defines a powerful feature identified by the name " storage-access ". It defines the following permission-related algorithms:

permission query algorithm

To query the " storage-access " permission, given a PermissionDescriptor permissionDesc and a PermissionStatus status :

1. Set status ’s state to permissionDesc ’s permission state .

2. If status ’s state is denied , set status ’s state to prompt .

   Note: The "denied" permission state is not revealed to avoid exposing the user’s decision to developers. This is done to prevent retaliation against the user and repeated prompting to the detriment of the user experience.

permission key type

A permission key of the " storage-access " feature is a tuple consisting of a site top-level and an origin requester .

Note that this will likely change to a (site, site) keying. [Issue #privacycg/storage-access#147]

permission key generation algorithm

To generate a new permission key for the " storage-access " feature, given an environment settings object settings , run the following steps:

1. Let topLevelSite be settings ’ top-level site .

2. Let embeddedOrigin be settings ’ origin .

3. Return ( topLevelSite , embeddedOrigin ).

permission key comparison algorithm

To compare the permission keys key1 and key2 for the " storage-access " feature, run the following steps:

1. If key1 ’s top-level is not same site with key2 ’s top-level , return false.

2. If key1 ’s requester is not same origin with key2 ’s requester , return false.

3. Return true.

5. Permissions Policy Integration

The Storage Access API defines a policy-controlled feature identified by the string "storage-access" . Its default allowlist is "*" .

Note: A Document ’s permissions policy determines whether any content in that document is allowed to request storage access using requestStorageAccess() . If disabled in any document, calling requestStorageAccess() in that document will reject.

6. Privacy considerations

The Storage Access API enables the removal of cross-site cookies. Specifically, it allows the authenticated embeds use case to continue to work. As such, the API provides a way for developers to re-gain access to cross-site cookies, albeit under further constraints.

A nested Document gains access to the same cookies it has as the active document of a top-level browsing context when it calls requestStorageAccess() and is returned a resolving Promise . With these cookies it can authenticate itself to the server and load user-specific information.

While this functionality comes with a risk of abuse by third parties for tracking purposes, it is an explicit goal of the API and a key to its design to not undermine the gains of cross-site cookie deprecation. Importantly, we do not degrade privacy properties when compared to pre-removal of cross-site cookies. This follows from a lack of platform-specific information used in the spec to prevent stateless tracking and the only state added being a permission scoped to the sites of the embedding and embedded Document .

Our privacy considerations are more challenging where default cross-site cookies are already deprecated. The challenge is to decide when and how to permit the Storage Access API to be used to revert a cookie-less (or cookie-partitioned) nested Document to a pre-deprecation state, giving it access to its unpartitioned data .

In an ideal case, a nested Document would only be able to gain access to its unpartitioned data if:

1. the user interacts with the nested Document

2. the nested Document is permitted by the embedder to use the API

3. the nested Document is a secure context

4. the user grants express, pairwise permission to the embeddee to use its cookies in the embedder

5. the user is not inundated by requests for the " storage-access " permission so their express permission is not undermined by fatigue

This specification requires the first three of implementers. This provides guarantees that the user is aware of the content of the nested Document , the embedder has not opted out of the nested Document 's authentication, and the cross-site cookies are not disclosed to network attackers, respectively.

The last two points are in tension. In an ideal world, we would show a prompt to the user in every call to requestStorageAccess() . But, this would allow pages to prompt the user so frequently as to put the last point at the discretion of the page– a state we find unacceptable. User agents should prevent over-prompting of the user.

Thus, the last two points represent a key point of compromise. We permit implementation-defined behavior on when to grant or deny requests for unpartitioned data without requiring user choice so long as they meet all other requirements. This compromise weakens the privacy guarantees of this proposal, specifically point 4, to a degree under the control of the implementer and gives the implementer the power to render it impossible to get storage access with this API. However, this has proven necessary to enable condition 5 to be possible given our implementers' differing stances on the compromise between these two points.

Developer experience suffers where user agents differ greatly in their implementation-defined behavior, and therefore user agents should aim to minimize or standardize silent grants and denies.

6.1. Permission scope

Another tension in the design of the API is what to use to key the " storage-access " permission: origins or sites . We chose sites because we believe them to be acceptable boundaries for privacy while enabling existing uses of same site and cross-origin nested Documents on the same page with only one user prompt.

7. Security considerations

It is important that this spec not degrade security properties of the web platform, even when compared to post-removal of cross-site cookies. Third-party cookie removal has potential benefits for security, specifically in mitigating attacks that rely upon authenticated requests, e.g. CSRF. We do not wish the Storage Access API to be a foothold for such attacks to leverage.

To this end, we limit the impact of a " storage-access " permission grant to only give access to unpartitioned data to the nested Document that called requestStorageAccess() and only until the nested Document navigates across an origin boundary. This ensures that only |origins with a page that call requestStorageAccess() will be making credentialed requests, and moreover the embedee page can control which embedder it permits via the Content Security Policy " frame-ancestors " directive. This retains an origin -scoped control for security purposes by the embedee.

7.1. Reputational attacks

This also is effective at preventing another attack: one on the embedee’s reputation. We consider any cross-site authenticated request to have potential reputational harm as consumers become more privacy conscious. Therefore a first-party or sibling cross-site causing an embedded resource to be requested with the user’s authentication cookies would constitute an attack on the reputation of that cross-site’s owner. This is also a reason we require this API to be used in a secure context : so a network adversary cannot induce an embedee to use this API.

The embedder has control over which nested Documents have the ability to become authenticated, or even display a permission request to the user via the Permission Policy and nested Document sandboxing.

7.2. Notification abuse

Notification abuse was also considered while specifying the Storage Access API. Specifically, we require user interaction in the nested Document and consume that rejection on a denial to restrict the conditions a permission prompt will be shown to the user. This mitigates attacks such as re-requesting a permission immediately after the user denies it.

8. Automation

For the purposes of user-agent automation and application testing, this document defines the following extension command for the [WebDriver] specification.

8.1. Set Storage Access

The Set Storage Access extension command modifies the storage access policy for the current browsing context .

The remote end steps are:

1. Let blocked be the result of getting a property from parameters named blocked .

2. If blocked is not a boolean return a WebDriver error with WebDriver error code invalid argument .

3. Let embedded origin be the result of getting a property from parameters named origin .

4. If embedded origin is not a single U+002A ASTERISK character (*), then:

   1. Let parsedURL be the the result of running the URL parser on embedded origin .

   2. If parsedURL is failure, then return a WebDriver error with WebDriver error code invalid argument .

   3. Set embedded origin to parsedURL ’s origin .

5. If the current browsing context is not a top-level browsing context return a WebDriver error with WebDriver error code unsupported operation .

6. Let doc be the current browsing context 's active document .

7. Let settings be doc ’s relevant settings object .

8. Let top-level site be the result of obtaining a site from settings ’s origin .

9. If embedded origin is a single U+002A ASTERISK character (*), then:

   1. If blocked is true , then:

      1. Run an implementation-defined set of steps to ensure that no site has access to its unpartitioned data when loaded in a third party context on top-level site .

   2. Otherwise, if blocked is false , then:

      1. Run an implementation-defined set of steps to ensure that any site has access to its unpartitioned data when loaded in a third party context on top-level site .

10. Otherwise:

    1. If embedded origin is same site with top-level site return a WebDriver error with WebDriver error code unsupported operation .

    2. If blocked is true , then:

       1. Run an implementation-defined set of steps to ensure that embedded origin does not have access to its unpartitioned data when loaded in a third party context on top-level site .

    3. Otherwise, if blocked is false , then:

       1. Run an implementation-defined set of steps to ensure that embedded origin has access to its unpartitioned data when loaded in a third party context on top-level site .

11. If the above implementation-defined step of steps resulted in failure, return a WebDriver error with WebDriver error code unknown error .

12. Return success with data null .

Acknowledgements

This specification builds on the foundations created by former editors John Wilander, who invented the Storage Access API, and Theresa O’Connor, who wrote significant portions of the initial text. We are grateful for their ideas and contributions.

Many thanks to Anne van Kesteren, Ben Kelly, Brad Girardeau, Brad Hill, Brady Eidson, Brandon Maslen, Chris Mills, Dave Longley, Domenic Denicola, Ehsan Akhgari, Geoffrey Garen, Jack Frankland, James Coleman, James Hartig, Jeffrey Yasskin, Kushal Dave, Luís Rudge, Maciej Stachowiak, Matias Woloski, Mike O’Neill, Mike West, Pete Snyder, Rob Stone, Stefan Leyhane, Steven Englehardt, Travis Leithead, Yan Zhu, Zach Edwards, and everyone who commented on whatwg/html#3338 , privacycg/proposals#2 , and privacycg/storage-access/issues for their feedback on this proposal.

Thanks to the WebKit Open Source Project for allowing us to use the Storage Access API Prompt image, which was originally published on webkit.org .