Source: https://mikewest.github.io/webappsec/specs/clear-site-data/
Timestamp: 2019-04-22 08:23:05+00:00

Document:
This document defines an imperative mechanism which allows web developers to instruct a user agent to clear a site’s locally stored data related to a host and its subdomains.
3.1.1 Which data types ought to be removed for response?
4.1 Web developers control the timing.
4.2 Remnants of data on disk.
Web applications store data locally on a user’s computer in order to provide functionality while the user is offline, and to increase performance when the user is online. These local caches have significant advantages for both users and developers, but present risks as well.
A user’s data is both sensitive and valuable; web developers ought to take reasonable steps to protect it. One such step would be to encrypt data before storing it. Another would be to remove data from the user’s machine when it is no longer necessary (for example, when the user signs out of the application, or deletes their account).
This document defines a new mechanism to deal with removing data from these and other types of local storage, giving web developers the ability to clear out a user’s local cache of data via the Clear-Site-Data HTTP response header.
A user signs out of Super Secret Social Network via a CSRF-protected POST to https://supersecretsocialnetwork.example.com/logout, and the site author wishes to ensure that locally stored data is removed as a result.
A user signs out of Megacorp Inc.'s site via a CSRF-protected POST to https://megacorp.example.com/logout. Megacorp has a large number of services available as subdomains, so many that it’s not entirely clear which of them would be safe to clear as a response to a logout action. One option would be to simply clear everything, and deal with the fallout. Megacorp’s CEO, however, once lost hours and hours of progress in "Irate Ibexes" due to inadvertant site-data clearing, and so refuses to allow such a sweeping impact to the site’s users.
"CSRF": "[insert sekrit token here]"
A user opts-out of interest-based advertising via a CSRF-protected POST to https://ads-are-awesome.example.com/optout. The site author wishes to remove DOM-accessible data which might contain tracking information, but needs to ensure that the opt-out cookie which the user has just received isn’t wiped along with it.
Super Secret Social Network’s developers learn that the site was vulnerable to cross-site scripting attacks which allowed malicious parties to inject arbitrary code into its origin. They fixed the site, and added a strong Content Security Policy [CSP2] to mitigate the risk going forward, but they can’t be entirely sure that clients are really back to a trustworthy state. Perhaps the attackers found a clever persistence mechanism?
Data stored in an origin’s client-side storage mechanisms like [INDEXEDDB], WebSQL, Filesystem, localStorage, and sessionStorage is cleared.
Cookies for an origin’s host are removed [RFC6265].
Web Workers (dedicated and shared) running for an origin are terminated.
Service Workers registered for an origin are terminated and deregistered.
Resources from an origin are removed from the user agent’s local cache.
All of the above can be propagated to an origin’s host’s subdomains.
All of the above can be propagated to the HTTP version of an HTTPS origin.
None of the above can be bypassed by a maliciously active document that retains interesting data in memory, and rewrites it if it’s cleared.
Note: The BWS, OWS, token, and quoted-string rules are defined in [RFC7230].
The Clear-Site-Data header’s value is essentially a semicolon-delimited list of "[key]=[value]" pairs which define the kinds of data to be cleared for a given response.
The following subsections define an initial set of known parameter components; future versions of this document may define additional parameter components: the ABNF above is intentionally generic and extensible to make room for these future values, and user agents MUST ignore unknown parameter components when parsing the header’s value.
The cache parameter indicates that the server wishes to remove locally cached data associated with the origin of a particular response’s url. This includes the network cache, of course, but will also remove data from various other caches which a user agent implements (prerendered pages, script caches, shader caches, etc.).
The value component of this parameter is currently ignored, if present.
Implementation details are in §3.4.3 Clear cache for origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
The cookies parameter indicates that the server wishes to remove cookies associated with the origin of a particular response’s url. This includes the network cache, of course, but will also remove data from various other caches which a user agent implements (prerendered pages, script caches, shader caches, etc.).
The domStorage parameter indicates that the server wishes to remove locally stored data associated with the origin of a particular response’s url. This includes storage mechansims such as (localStorage, sessionStorage, [INDEXEDDB], [WEBDATABASE], etc), as well as tangentially related mechainsm such as service worker registrations.
Implementation details are in §3.4.5 Clear DOM-accessible storage for origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
Probably should rename this to "storage".
The executionContexts parameter indicates that the server wishes to neuter and reload execution contexts currently rendering the origin of a particular response’s url.
Implementation details are in §3.4.1 Neuter browsing contexts matching origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
The includeSubdomains parameter expands the scope of the storage type parameters to include any origin whose host is a subdomain of the response’s url's host.
Implementation details are included as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
This might live more cleanly in [STORAGE].
Clears data based on the values in the options argument. Returns a Promise that resolves when clearing is complete. If no types are specified, all data types will be cleared.
options StorageClearOptions ✘ ✘ The data to clear.
Arguments for the StorageManager.clear(options) method.
Monkey patching! Talk with Anne.
If response’s header list contains a header named Clear-Site-Data, then execute §3.2 Clear data for response on response.
Note: This happens after Set-Cookie headers are processed. If we clear cookies, we clear all of them. This is intentional, as removing only certain cookies might leave an application in an indeterminate and vulnerable state. Removing specific cookies is best done via expiration using the Set-Cookie header.
3.1.1. Which data types ought to be removed for response?
If response does not contain a Clear-Site-Data header, return an empty list.
Let parameters be the list of parameter components in the value of response’s Clear-Site-Data header.
Append cache, cookies, domStorage, and executionContexts to remove.
Otherwise, let remove be an empty list.
If parameter’s key is cache, cookies, domStorage, or executionContexts, cache append parameter’s key to remove.
If response does not contain a Clear-Site-Data header, return Exclude Subdomains.
If parameters contains a parameter whose key is includeSubdomains, return Include Subdomains.
Given an origin, the origin to clear, and the "include subdomains" flag, return Matches or Does Not Match.
If either origin or origin to clear are globally unique identifiers, return Does Not Match.
If origin is the same as origin to clear, return Matches.
If subdomain state is Exclude Subdomains, return Does Not Match.
Let labels to clear be the host component of origin to clear split into labels, and labels be the host component of origin, split into labels.
If labels does not have more entries than labels to clear, return Does Not Match.
If the final entry of labels to clear does not exactly match the final entry of labels, return Does Not Match.
Remove the final entry of labels to clear, and of labels.
Given a response (response), this algorithm parses the Clear-Site-Data header to determine what needs to be cleared, which origins are affected, and then executes those requests.
If response’s URL is a priori insecure, skip the remaining steps of this algorithm.
Some have suggested that this might not be a restriction we want (see Martin Thomson’s public-webappsec post on the topic, for example).
Let types be the result of §3.1.1 Which data types ought to be removed for response? executed on response.
Let subdomain state be the result of §3.1.2 Should subdomains' data be cleared for response executed on response.
Execute §3.4 Clear types for origin with subdomain state on types, response’s url's origin, and subdomain state.
Note: Especially given the cross-context implications, user agents are are encouraged to give web developers some mechanism by which the clearing operation can be debugged. This might take the form of a console message or timeline entry indicating success.
Given a StorageClearOptions (options), this algorithm determines what needs to be cleared, returns a Promise, and executes the request asynchronously.
If the incumbent settings object is not a secure context, return a Promise rejected with NotSupportedError.
Let subdomain state be Include Subdomains if options' includeSubdomains property is true, and Exclude Subdomains otherwise.
Let types be an empty list.
Append cache, cookies, domStorage, and executionContexts to types.
Execute §3.4 Clear types for origin with subdomain state on types, the incumbent settings object’s origin, and subdomain state.
If types contains "executionContexts", execute §3.4.1 Neuter browsing contexts matching origin with subdomain state on origin, with subdomain state.
If types contains "cookies", execute §3.4.4 Clear cookies for origin with subdomain state on origin, with subdomain state.
If types contains "domStorage", execute §3.4.5 Clear DOM-accessible storage for origin with subdomain state on origin, with subdomain state.
If types contains "cache", execute §3.4.3 Clear cache for origin with subdomain state on origin, with subdomain state.
If types contains "executionContexts", execute §3.4.2 Reload browsing contexts matching origin with subdomain state on origin, with subdomain state.
Let document be context’s active document.
While document is an iframe srcdoc document, let document be the active document of document’s browsing context container.
Parse a sandboxing directive using the empty string as the input, and document’s active sandboxing flag set as the output.
Navigate context to document’s URL with replacement enabled and exceptions enabled. The source browsing context is context. This is a reload-triggered navigation.
Given an origin (origin) and a subdomain state of either Include Subdomains or Exclude Subdomains, this algorithm removes data from the user agent’s local caches that matches the origin and subdomain state.
Let host be origin’s host, canonicalized as per Section 5.1.2 of [RFC6265].
Otherwise, subdomain state is Exclude Subdomains, so let cache list be the set of entries from the network cache whose target URI host is identical to host when canonicalized as per Section 5.1.2 or [RFC6265].
Remove each entry in cache list from the network cache.
If a user agent implements caches beyond a pure network cache, it MUST remove all entries from those caches which match origin and subdomain state.
We’re dealing with the network cache here, as defined in [RFC7234], but that’s not nearly everything a user agent caches. How hand-wavey with the vendor-specific section can we be? For instance, Chrome clears out prerendered pages, script caches, WebGL shader caches, WebRTC bits and pieces, address bar suggestion caches, various networking bits that aren’t representations (HSTS/HPKP, SCDH, etc.). Perhaps [STORAGE] will make this clearer?
Given an origin (origin) and a subdomain state of either Include Subdomains or Exclude Subdomains, this algorithm removes cookies from the user agent’s cookie store whose domain attribute matches the origin and subdomain state.
Note: This algorithm assumes that the user agent has implemented a cookie store (as discussed in Section 5.3 of [RFC6265]), which offers the ability to retrieve a list of cookies by host, and to remove individual cookies.
If subdomain state is Include Subdomains, then let cookie list be the set of cookies from the cookie store whose domain attribute is domain-matched by host.
Note: The direction of the matching is important. If subdomain.example.com delivers the Clear-Site-Data header and includes subdomains, then cookies for .another.subdomain.example.com will be cleared, but cookies for .example.com will not.
Otherwise, subdomain state is Exclude Subdomains, so let cookie list be the set of cookies from the cookie store whose domain attribute is identical to host.
Remove each cookie in cookie list from the cookie store.
Execute clear() on the Storage object associated with area.
Set database’s delete pending flag to true.
Execute the database closing steps on connection.
Execute the database deletion steps on database, passing in database’s origin and name.
The [WEBDATABASE] spec is fairly unhelpful here with regard to deletion details.
How do we say something about plugins here? Point out to NPP_ClearSiteData?
4.1. Web developers control the timing.
If triggered at appropriate times, Clear-Site-Data can increase a user’s privacy and security by clearing sensitive data from their user agent. However, note that the web developer (and not the user) is in control of when the clearing event is triggered. Even assuming a non-malicious site author, users can’t rely on data being cleared at any particular point, nor are users in control of what data types are cleared.
If a user wishes to ensure that site data is indeed cleared at some specific point, they ought to rely on the data-clearing functionality offered by their user agent.
At a bare minimum, user agents OUGHT TO (in the [RFC6919] sense of the words) offer the same functionality to users that they offer to web developers. Ideally, they will offer significantly more than we can offer at a platform level (clearing browsing history, for example).
4.2. Remnants of data on disk.
While Clear-Site-Data triggers a clearing event in a user’s agent, it is difficult to make promises about the state of a user’s disk after a clearing event takes place. In particular, note that it is up to the user agent to ensure that all traces of a site’s date is actually removed from disk, which can be a herculean task (consider virtual memory, as a good example of a larger issue).
In short, most user agents implement data clearing as "best effort", but can’t promise an exhaustive wipe.
If a user wishes to ensure that site data does not remain on disk, the best way to do so is to use a browsing mode that promises not to intentionally write data to disk (Chrome’s "Incognito", Internet Explorer’s "InPrivate", etc). These modes will do a better job of keeping data off disk, but are still subject to a number of limitations at the edges.
Michal Zalewski proposed a variant of this concept, and Mark Knichel helped refine the details.

References: §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3
 §3