Clear Site Data

4. Algorithms

4.1. Parsing

Given a response, the user agent can parse response’s Clear-Site-Data header, returning a list of types, as follows:

1. Let types be an empty list.

2. Let header be the result of extracting header list values given Clear-Site-Data and response’s header list.

3. If header is null or failure, return an empty list.

4. For each type in header, execute the first matching statement, if any, switching on type:

   `"cache"`

   Append "cache" to types.

   `"cookies"`

   Append "cookies" to types.

   `"storage"`

   Append "storage" to types.

   `"executionContexts"`

   Append "executionContexts" to types.

   `"*"`

   Append "cache", "cookies", "storage", and "executionContexts" to types.

5. Return types.

Note: All of the existing values can be handled with the simple switch above. If and when more complex type definitions are created, the parser will likely shift over to JSON entirely.

4.2. Clear data for response

Given a response (response), the user agent can clear site data for response as follows:

1. If response’s url is not an a priori authenticated URL, then break.

2. Let types be the result of parsing response’s Clear-Site-Data header.

3. Let origin be response’s url's origin.

4. Let browsing contexts be the result of preparing to clear data for origin and types.

5. For each type in types:

   1. Execute the first matching statement, if any, switching on type:

      "cache"

      Clear cache for origin.

      "cookies"

      Clear cookies for origin.

      "storage"

      Clear DOM-accessible storage for origin.

6. If types contains "executionContexts", then Reload browsing contexts.

Note: 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.

4.2.1. Prepare to clear origin’s data

Given an origin (origin) and a list of types (types), the user agent can prepare to clear origin’s data by executing the following steps. The algorithm returns a list of browsing contexts which have been sandboxed in order to prevent them from recreating cleared data from in-memory JavaScript variables.

1. Let sandboxed be an empty list.

2. If types does not contain "executionContexts", return sandboxed.

3. For each context in the user agent’s set of browsing contexts:

   1. Let document be context’s active document.

   2. If document’s relevant settings object's origin is not origin, continue.

   3. Parse a sandboxing directive using the empty string as the input, and document’s active sandboxing flag set as the output.

   4. Append context to sandboxed.

4. Return sandboxed.

4.2.2. Reload browsing contexts

Given a list of browsing contexts (contexts), the user agent can reload browsing contexts as follows:

1. For each context in contexts:

   1. Execute context’s active document's relevant settings object's global object's Location object’s reload().

      This is the simplest thing, but it’s probably reaching a little too far into the documents and mucking with their context. I probably just need to break down and copy/paste the relevant bits from HTML.

4.2.3. Clear cache for origin

Given an origin (origin), the user agent can clear cache for origin as follows:

1. Let host be origin’s host.

2. Let cache list be the set of entries from the network cache whose target URI host is identical to host.

3. For each entry in cache list:

   1. Remove entry from the network cache.

4. If a user agent implements caches beyond a pure network cache, it MUST remove all entries from those caches which match origin.

   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?

4.2.4. Clear cookies for origin

Given an origin (origin), the user agent can clear cookies for origin as follows:

Note: We remove all the cookies for an entire registered domain, as cookies ignore the same-origin policy, and there’s a distinct risk that we’d leave applications in an ill-defined state if we only cleared cookies for a particular subdomain. Consider accounts.google.com vs mail.google.com, for instance, both of which have cookies that signal a user’s signed-in status.

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.

1. Let registered be the registered domain of origin’s host.

2. Let cookie list be the set of cookies from the cookie store whose domain attribute is a domain-match with registered.

3. For each cookie in cookie list:

   1. Remove cookie from the cookie store.

4. If the user agent supports other forms of cookie-like storage, these MUST also be cleared for origins whose host's registered domain is registered.

   Note: For example, if the user agent supports Flash, its local stored objects will be cleared via NPP_ClearSiteData.

5. Clear any Channel IDs [CHANNELID] and bound tokens [TOKBIND] associated with origins whose host's registered domain is registered.

6. Clear authentication entries and proxy-authentication entries associated with origins whose host's registered domain is registered.

The process of clearing both bound tokens/IDs and HTTP authentication is super hand-wavey. <https://github.com/w3c/webappsec-clear-site-data/issues/2>

4.2.5. Clear DOM-accessible storage for origin

Given an origin (origin), the user agent can clear DOM-accessible storage for origin as follows:

1. For each area in the user agent’s set of local storage areas [HTML]:

   1. If area’s origin is origin:

      1. Execute clear() on the Storage object associated with area.

2. For each area in the user agent’s set of session storage areas [HTML]:

   1. If area’s origin is origin:

      1. Execute clear() on the Storage object associated with area.

3. For each database in the set of databases for origin [INDEXEDDB]:

   1. Delete database.

4. For each registration in the user agent’s set of service worker registrations:

   1. If registration’s scope URL’s origin is origin:

      1. Execute unregister() on registration.

5. For each appcache in the user agent’s set of application caches:

   1. If appcache’s application cache group is identified by an URL whose origin is origin:

      1. Discard appcache.

6. For any other script-accessible storage mechanism, the user agent MUST delete any data associated with this origin. This includes (but is not limited to) the following:

   1. An origin’s WebSQL databases [WEBDATABASE].

   2. An origin’s filesystems [file-system-api]

   3. Plugin data (e.g. Flash via NPP_ClearSiteData),

   4. Moar?

5. Security Considerations

5.1. Incomplete Clearing

It is possible that an application could be put into an indeterminate state by clearing only one type of storage. We mitigate that to some extent by clearing all storage options as a block, and by requiring that the header be delivered over a secure connection.

5.2. Service workers

It is imperative that the Clear-Site-Data header is only respected on responses fetched over network, and not those served by a service worker.

This is because service workers can return arbitrary responses for resource requests in their scope, including third-party requests. Thus, supporting Clear-Site-Data would give them the ability to clear data for any origin.

Note that if a request is sent to a service worker, not handled by it, then restarted with a service-workers mode of "none" and sent to the network, the corresponding response is a network response and can be handled. The previous attempt at obtaining the response from a service worker is irrelevant.

Note also that a service worker update is a network response, and is therefore not affected by this restriction. This is important in order to support the use case in §1.1.4 Kill Switch.

6. Privacy Considerations

6.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).

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

7. IANA Considerations

The permanent message header field registry should be updated with the following registration: [RFC3864]

7.1. Clear-Site-Data

Header field name

Clear-Site-Data

Applicable protocol

http

Status

standard

Author/Change controller

W3C

Specification document

This specification (See §3.1 The Clear-Site-Data HTTP Response Header Field)