Clear Browsing Data API

Overview


Chromium includes a mechanism for removing browsing data from a user’s profile, exposed via the “Under the Hood” preferences at chrome://settings/clearBrowsingData. Extensions should have programmatic access to this interface to offer the service to users in other forms and fashions.

Use cases

Clearing browsing data is prima facie relevant to extensions that want to offer privacy protections for users above and beyond what is reasonable to offer as a default. Extensions like Tor and NoScript have both expressed interest.  Use-cases also exist in the developer community, specifically around clearing the browser’s cache (see http://crbug.com/54853 for example, which HttpWatch is interested in).

Could this API be part of the web platform?

This specifically relates to data stored by the browser above and beyond the web platform’s storage options. It includes those storage options (cookies, localStorage, etc. are browsing data), but also includes things like stored passwords, the browser’s cache, and other browser-specific forms of data that are not part of the web platform in general, but of Chromium’s particular implementation. More to the point, this API allows removal of local data for all origins, which is neither something we’d like to offer individual origins, nor something origins that wish to track users would appreciate. The API pretty clearly lands in the browser’s natural area of influence, giving users more direct control over client-side behavior.

Do you expect this API to be fairly stable?

This API would only change when the browser changes the types of information it stores. As it is by necessity browser-specific, that seems reasonable in terms of stability.

What UI does this API expose?

None. The mechanism is already exposed via chrome://settings/clearBrowsingData, this proposal simply adds a programmatic interface.

How could this API be abused?

Malicious extensions could clear browsing data continuously, which would have the impacts of both DoSsing the browser on the one hand, and breaking the web experience for users on the other (no cookies => no web).

This can be mitigated by throttling access such that only one call can be in flight at once.

How would you implement your desired features if this API didn't exist?

Individual users would be pointed to the form, and asked to clear their browsing data manually.

Are you willing and able to develop and maintain this API?

Yes.

Draft API spec

Usage of this API would require additional messaging to the user, and therefore a new permission message (perhaps something along the lines of “It can access: … What can it access? Nothing. It can remove things. Removing things isn’t really access. Bleh.”).

First, and most simply, requesting clear permissions would grant access to a chrome.clear.browsingData method that might look like the following:

{
"namespace": "experimental.clear",
"functions": [
  {
    "name": "browsingData",
    "description": "Clears data generated by browsing within a particular timeframe.",
    "type": "function",
    "parameters": [
      {
        "name": "timePeriod",
        "type": "string",
        "enum": ["last_hour", "last_day", "last_week", "last_month", "everything"],
        "optional": "false",
        "description": "The timeframe inside of which to delete browsing data.”
      },
      {
        "name": "dataToRemove",
        "type": "object",
        "optional": "false",
        "properties": {
          "cache": {
            "type": "boolean",
            "optional": true,
            "description": "Should the browser cache be cleared?"
          },
          "cookies": {
            "type": "boolean",
            "optional": true,
            "description": "Should the browser's cookies/LSO/site data be cleared?"
          },
          "downloads": {
            "type": "boolean",
            "optional": true,
            "description": "Should the browser's download list be cleared?"
          },
          "form_data": {
            "type": "boolean",
            "optional": true,
            "description": "Should stored form data be cleared?"
          },
          "history": {
            "type": "boolean",
            "optional": true,
            "description": "Should the browser's history be cleared?"
          },
          "passwords": {
            "type": "boolean",
            "optional": true,
            "description": "Should the stored passwords be cleared?"
          }
        }
      },
      {
        "name": "callback",
        "type": "function",
        "description": "Called when deletion has completed.",
        "optional": "true",
        "parameters": [
            {
              "name": "result",
              "type": "boolean",
              "description": "Was the data deletion successful?"
            }
        ]
      }                                                                                                                                        
    ]
  }
]
}


Along with the general chrome.clear.browsingData(), type-specific methods (chrome.clear.xxx()) could be provided for clearing specific types of data:

{
"namespace": "experimental.clear",
"functions": [
   {
     "name": "cookies",
     "description": "Clears cookies/LSO/site data touched within a particular timeframe.",
     "type": "function",
     "parameters": [
       {
         "name": "timePeriod",
         "type": "string",
         "enum": ["last_hour", "last_day", "last_week", "last_month", "everything"],
         "optional": "false",
         "description": "The timeframe inside of which to delete browsing data.”
       },
       {
         "name": "callback",
         "type": "function",
         "description": "Called when deletion has completed.",
         "optional": "true",
         "parameters": [
             {
               "name": "result",
               "type": "boolean",
               "description": "Was the data deletion successful?"
             }
         ]
       }
]
}
]
}

Additionally, Chromium already provides chrome.cookies and chrome.history APIs, which give access to subsets of the “Clear Browsing Data” form’s functionality. These seem like excellent candidates for BrowsingDataRemover methods; adding .clear() methods to each of those seems like a reasonable way of addressing the request. The history namespace could additionally be overloaded to include .clearXXX() methods to clear the browser cache, downloaded files, stored passwords, and Autofill data (since all that data is arguably historical in nature).

These methods might look like the following:

{
"namespace": "cookies",

"functions": [
  
  {
    "name": "clear",
    "description": "Clears cookies and other site data modified within a time period.",
    "type": "function",
    "parameters": [
      {
        "name": "timePeriod",
        "type": "string",
        "enum": ["last_hour", "last_day", "last_week", "last_month", "everything"],
        "optional": "false",
        "description": "The time period inside which to delete cookies and site data."
      },
      {
        "name": "callback",
        "type": "function",
        "description": "Called when deletion has completed.",
        "optional": "true",
        "parameters": [
          {
            "name": "result",
            "type": "boolean",
            "description": "Was the data deletion successful?"
          }
        ]
      }
    ]
  },
  
],

},
{
"namespace": "history",

"functions": [
  
  {
    "name": "clear",
    "description": "Clears browsing history created within a time period.",
    "type": "function",
    "parameters": [
      {
        "name": "timePeriod",
        "type": "string",
        "enum": ["last_hour", "last_day", "last_week", "last_month", "everything"],
        "optional": "false",
        "description": "The time period inside which to delete browsing history."
      },
      {
        "name": "callback",
        "type": "function",
        "description": "Called when deletion has completed.",
        "optional": "true",
        "parameters": [
          {
            "name": "result",
            "type": "boolean",
            "description": "Was the data deletion successful?"
          }
        ]
      }
    ]
  },
  
],

}


It would be valuable to distinguish the namespace from the permission required to execute the methods. Extensions focused on removing data (see the use-cases above) shouldn’t be required to request read access to cookies on a variety of hosts in order to clear them. Using the explicit clear permission should grant access to the relevant methods regardless of namespace, as it would enable us to give the user a clear warning (cookies should grant the same access, for example, but only to the cookies-specific chrome.cookies.clear).

Open questions
  1. BrowsingDataRemover offers the option of clearing browsing history, download history, clearing the cache, deleting cookies + site + plug-in data, clearing saved passwords, and clearing Autofill data. Homes should be found for programmatic methods that clear each type of data. chrome.history mostly makes sense, but it’s a stretch.
Comments