From e34be810ca8048a0f470340d34745fca25be9246 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Wed, 18 Sep 2024 14:16:58 -0400 Subject: [PATCH 01/11] Create Proposal: add cookies.removeAll() method.md Initial draft --- ...roposal: add cookies.removeAll() method.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 proposals/Proposal: add cookies.removeAll() method.md diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md new file mode 100644 index 00000000..b56cc894 --- /dev/null +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -0,0 +1,147 @@ +**Summary** + +Adds a new API `cookies.removeAll()` to allow for the removal of multiple cookies with a single call. + +**Document Metadata** + +**Author:** [aselya](https://github.com/aselya) + +**Sponsoring Browser:** Chrome + +**Contributors:** + +**Created:** 2024-09-18 + +**Related Issues:** [PrivacyCG/CHIPS issue 6 - How do Partitioned cookies interact with browser extensions?](https://github.com/privacycg/CHIPS/issues/6) + +## Motivation + +Prior to the introduction of [partitioned cookies](https://github.com/privacycg/CHIPS), the required parameters (`url` and `name`) used by the existing `cookies.remove()` api would be unique to a single cookie. The inclusion of an optional `partitionKey` means that there can be more than one cookie that matches the currently required parameters for `cookies.remove()`. Because of this, handling partitioned cookies with `cookies.remove()` requires additional steps which can be simplified by the inclusion of this new API. + +### Objective + +This new API addresses two workflows for developers: +##### Removal of cookies with the same url and name combination but different partitionKey values: +Since the introduction of partitioned cookies, to remove all the cookies with the same `url` and `name` a developer must first call `cookies.getAll()` to get all of the partitioned and unpartitioned cookies associated with the values. Then use the results of that call to make individual calls to `cookies.remove()` to delete each cookie. + +##### Removal of cookies associated with a topLevelSite: +To remove all the cookies associated with a `topLevelSite`, a developer must first call `cookies.getAll({})` to retrieve all partitioned and unpartitioned cookies. Then filter the results to identify cookies that have a value for `topLevelSite` of their `partitionKey` match the desired `topLevelSite`. Finally the developer will need to make individual calls to `cookies.remove()` to delete each cookie. + +#### Use Cases + +##### Cookie Manager: + +Let's say a cookie manager extension (with host permissions) is used by users to remove their cookies. Using `cookies.removeAll()` would ensure that the cookie manager extension is removing all the cookies associated with a `topLevelSite` correctly. Instead of relying on the developer of the extension to make a call to `cookies.getAll()` followed by call(s) to `cookies.remove()`. Reducing complexity for the developers while improving performance of the extension. + +### Known Consumers + +All extensions that access and/or modify cookies with awareness of partitioned cookies, through the use of the `partitionKey` property in the `cookies` extension API. + +## Specification + + +### Schema + +##### Syntax + +``` +let removed = await browser.cookies.removeAll( +details // object +) +``` +##### Parameters +An `object` containing information to identify the cookie(s) to remove. It contains the following properties: + +>[`name`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#name) optional: +> +>A `string` representing the name of the cookie to remove. +> +>[`partitionKey`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#partitionkey) optional: +> +>An object representing the storage partition containing the cookie. +> +>[`topLevelSite`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#toplevelsite) optional: +> +>A `string` representing the first-party URL of the top-level site storage partition containing the cookie. +> +>[`storeId`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#storeid) optional: +> +>A `string` representing the ID of the cookie store to find the cookie in. If unspecified, the cookie is looked for by default in the current execution context's cookie store. +> +>[`url`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#url) optional: +> +>A `string` representing the URL associated with the cookie. + +### Behavior + +The API will remove all cookies that match the `details` object parameter with the exception of the cases outlined in the implementation details. +If the extension does not have [host permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) for this URL, the API call will fail. + +### New Permissions +No new permissions are required. + +### Manifest File Changes +No new manifest fields are required. + +## Security and Privacy +Incorrect usage can lead to the removal of cookies that are not intended. + +### Exposed Sensitive Data +None + +### Abuse Mitigations +To remove a cookie, the extension must have host permissions for the `url` associated with the cookie. + + +## Alternatives +None + +### Existing Workarounds + +The behavior introduced by this API can be replicated by using a combination of `cookies.getAll()` and `cookies.remove()`. + +### Open Web API + +The cookies API is specific to extensions + +## Implementation Notes + +Host permissions are required for this API. +#### Special cases: +```cookies.removeAll({})``` + +>An empty details object will result in all cookies being removed. + +``` +cookies.removeAll({ + partitionKey:{}}) +``` + +>An empty `partitionKey` object as the only value in the details object, will result in all partitioned cookies being removed. + +``` +cookies.removeAll({ + name: “example”, + url: “https://example.com”, + partitionKey:{} +}) +``` + +>An empty `partitionKey` object with other values populated, will result in both unpartitioned and partitioned cookies that also match the other values provided will be removed. + +``` +cookies.removeAll({ + topLevelSite: “https://example.com” +}) +``` + +>If `topLevelSite` is the only argument, it will result in all cookies that have that value as the `topLevelSite` in their `partitionKey` being removed. + +``` +cookies.removeAll({ + topLevelSite: “https://example.com”, + partitionKey:{topLevelSite: “https://foo.com”} +}) +``` + +>If the `topLevelSite` differs from the `topLevelSite`, if present, in the `partitionKey` an error will be returned. From e8dae2e55115a4bd3f737902ce9ad70571e5b3f9 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 1 Oct 2024 10:51:38 -0700 Subject: [PATCH 02/11] Update proposals/Proposal: add cookies.removeAll() method.md Updating parameters to explicitly reference cookies.remove Co-authored-by: Rob Wu --- proposals/Proposal: add cookies.removeAll() method.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index b56cc894..261e7305 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -50,7 +50,7 @@ details // object ) ``` ##### Parameters -An `object` containing information to identify the cookie(s) to remove. It contains the following properties: +An `object` containing information to identify the cookie(s) to remove. It contains the following properties, based on the properties recognized by `cookies.remove`: >[`name`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#name) optional: > From d42833a0ea5e80abe5fa0c50751d77123e4ed624 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 1 Oct 2024 10:58:26 -0700 Subject: [PATCH 03/11] Update Proposal: add cookies.removeAll() method.md Add more related issues Update the motivation language to reflect the related issues. --- proposals/Proposal: add cookies.removeAll() method.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 261e7305..4d06a596 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -12,11 +12,14 @@ Adds a new API `cookies.removeAll()` to allow for the removal of multiple cookie **Created:** 2024-09-18 -**Related Issues:** [PrivacyCG/CHIPS issue 6 - How do Partitioned cookies interact with browser extensions?](https://github.com/privacycg/CHIPS/issues/6) +**Related Issues:** +- [PrivacyCG/CHIPS issue 6 - How do Partitioned cookies interact with browser extensions?](https://github.com/privacycg/CHIPS/issues/6) +- [browser.cookies.remove removes only one cookie, not all](https://bugzilla.mozilla.org/show_bug.cgi?id=1387957) +- [chrome.cookies.remove does not account for paths and host-only cookies](https://issues.chromium.org/issues/40572551) ## Motivation -Prior to the introduction of [partitioned cookies](https://github.com/privacycg/CHIPS), the required parameters (`url` and `name`) used by the existing `cookies.remove()` api would be unique to a single cookie. The inclusion of an optional `partitionKey` means that there can be more than one cookie that matches the currently required parameters for `cookies.remove()`. Because of this, handling partitioned cookies with `cookies.remove()` requires additional steps which can be simplified by the inclusion of this new API. +The introduction of additional cookie attributes since the creation of the `cookies.remove()` api was created has resulted in the required parameters (`url` and `name`) to no longer be unique to a single cookie. Because of this, handling cookies with `cookies.remove()` requires additional steps which can be simplified by the inclusion of this new API. ### Objective From dac145fced7059c1a7ee0a388e39ad5d8aae4850 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 1 Oct 2024 11:01:28 -0700 Subject: [PATCH 04/11] Update Proposal: add cookies.removeAll() method.md Add link to bug in the motivation --- proposals/Proposal: add cookies.removeAll() method.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 4d06a596..26af8674 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -19,7 +19,7 @@ Adds a new API `cookies.removeAll()` to allow for the removal of multiple cookie ## Motivation -The introduction of additional cookie attributes since the creation of the `cookies.remove()` api was created has resulted in the required parameters (`url` and `name`) to no longer be unique to a single cookie. Because of this, handling cookies with `cookies.remove()` requires additional steps which can be simplified by the inclusion of this new API. +The introduction of additional cookie attributes since the creation of the `cookies.remove()` api, has resulted in the required parameters (`url` and `name`) to no longer be unique to a single [cookie](https://issues.chromium.org/issues/40572551). Because of this, handling cookies with `cookies.remove()` requires additional steps which can be simplified by the inclusion of this new API. ### Objective From 5682b4c68ed2e16209d5c89e2ec934d436423c76 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 1 Oct 2024 11:09:03 -0700 Subject: [PATCH 05/11] Update Proposal: add cookies.removeAll() method.md Update the objective to be more explicit about the pain point for developers. --- proposals/Proposal: add cookies.removeAll() method.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 26af8674..c7834583 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -23,9 +23,9 @@ The introduction of additional cookie attributes since the creation of the `cook ### Objective -This new API addresses two workflows for developers: -##### Removal of cookies with the same url and name combination but different partitionKey values: -Since the introduction of partitioned cookies, to remove all the cookies with the same `url` and `name` a developer must first call `cookies.getAll()` to get all of the partitioned and unpartitioned cookies associated with the values. Then use the results of that call to make individual calls to `cookies.remove()` to delete each cookie. +This new API addresses two workflows which require developers to take additional steps to ensure that cookies are deleted correctly because the required parameters for `cookies.remove()` can indiate multiple cookies: +##### Removal of cookies with the same url and name combination but different partitionKey, path or host-only values: +To remove all the cookies with the same `url` and `name` a developer must first call `cookies.getAll()` to get all of the cookies associated with the values. Then use the results of that call to make individual calls to `cookies.remove()` to delete each cookie. ##### Removal of cookies associated with a topLevelSite: To remove all the cookies associated with a `topLevelSite`, a developer must first call `cookies.getAll({})` to retrieve all partitioned and unpartitioned cookies. Then filter the results to identify cookies that have a value for `topLevelSite` of their `partitionKey` match the desired `topLevelSite`. Finally the developer will need to make individual calls to `cookies.remove()` to delete each cookie. From bf51fe915c4b4df090626b088832c7936f2442e0 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Wed, 2 Oct 2024 13:50:06 -0400 Subject: [PATCH 06/11] Update Proposal: add cookies.removeAll() method.md Update language in objective. --- proposals/Proposal: add cookies.removeAll() method.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index c7834583..6fb2826c 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -23,7 +23,7 @@ The introduction of additional cookie attributes since the creation of the `cook ### Objective -This new API addresses two workflows which require developers to take additional steps to ensure that cookies are deleted correctly because the required parameters for `cookies.remove()` can indiate multiple cookies: +This new API addresses two workflows which require developers to take additional steps to ensure that cookies are deleted correctly because the required parameters for `cookies.remove()` can match multiple cookies but will only delete one cookie: ##### Removal of cookies with the same url and name combination but different partitionKey, path or host-only values: To remove all the cookies with the same `url` and `name` a developer must first call `cookies.getAll()` to get all of the cookies associated with the values. Then use the results of that call to make individual calls to `cookies.remove()` to delete each cookie. From 1c7ffcf57c35e3583fd6d4c86dec32ef5aa4a986 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Wed, 2 Oct 2024 14:12:04 -0400 Subject: [PATCH 07/11] Update Proposal: add cookies.removeAll() method.md Add return --- proposals/Proposal: add cookies.removeAll() method.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 6fb2826c..397c487f 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -75,6 +75,13 @@ An `object` containing information to identify the cookie(s) to remove. It conta > >A `string` representing the URL associated with the cookie. +##### Return + +> `Promise`: +> +> All the cookies that were removed. If list is empty then no cookies were removed. + + ### Behavior The API will remove all cookies that match the `details` object parameter with the exception of the cases outlined in the implementation details. From d7d953b849f6cb8ab8aad940ef3008b32bf866ca Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Thu, 3 Oct 2024 15:37:58 -0400 Subject: [PATCH 08/11] Update Proposal: add cookies.removeAll() method.md Update language to make `{}` and error --- proposals/Proposal: add cookies.removeAll() method.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 397c487f..69fe5883 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -120,7 +120,7 @@ Host permissions are required for this API. #### Special cases: ```cookies.removeAll({})``` ->An empty details object will result in all cookies being removed. +>An empty details object will result in an error. ``` cookies.removeAll({ From 76f57bed4ccfa3c1571df6b87914b0a33667b143 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 8 Oct 2024 08:13:15 -0400 Subject: [PATCH 09/11] Update Proposal: add cookies.removeAll() method.md Update case: `partitionKey : {}` to match `cookies.getAll` --- proposals/Proposal: add cookies.removeAll() method.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 69fe5883..0f8cac31 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -127,7 +127,7 @@ cookies.removeAll({ partitionKey:{}}) ``` ->An empty `partitionKey` object as the only value in the details object, will result in all partitioned cookies being removed. +>An empty `partitionKey` object in the details object, will result in both partitioned and unpartitioned cookies being removed, that also match any other values in the details object. ``` cookies.removeAll({ From 8f17da29971a85c7869058a11817e45ca3debe2c Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 8 Oct 2024 09:47:52 -0400 Subject: [PATCH 10/11] Update Proposal: add cookies.removeAll() method.md Update requirements of details object. --- proposals/Proposal: add cookies.removeAll() method.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index 0f8cac31..bcedce78 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -74,6 +74,8 @@ An `object` containing information to identify the cookie(s) to remove. It conta >[`url`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/remove#url) optional: > >A `string` representing the URL associated with the cookie. +> +>A details object must contain a `url` and/or a `topLevelSite`. ##### Return @@ -137,14 +139,6 @@ cookies.removeAll({ }) ``` ->An empty `partitionKey` object with other values populated, will result in both unpartitioned and partitioned cookies that also match the other values provided will be removed. - -``` -cookies.removeAll({ - topLevelSite: “https://example.com” -}) -``` - >If `topLevelSite` is the only argument, it will result in all cookies that have that value as the `topLevelSite` in their `partitionKey` being removed. ``` From 733045333a2b5a53131e30dd2d864d40d1589145 Mon Sep 17 00:00:00 2001 From: Aaron Selya Date: Tue, 14 Jan 2025 16:46:18 -0500 Subject: [PATCH 11/11] Update Proposal: add cookies.removeAll() method.md Added more detailed description of host permissions impact on API call --- proposals/Proposal: add cookies.removeAll() method.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/Proposal: add cookies.removeAll() method.md b/proposals/Proposal: add cookies.removeAll() method.md index bcedce78..7d2507b5 100644 --- a/proposals/Proposal: add cookies.removeAll() method.md +++ b/proposals/Proposal: add cookies.removeAll() method.md @@ -87,7 +87,10 @@ An `object` containing information to identify the cookie(s) to remove. It conta ### Behavior The API will remove all cookies that match the `details` object parameter with the exception of the cases outlined in the implementation details. -If the extension does not have [host permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) for this URL, the API call will fail. + +- The extension must have [host permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) needed to access the cookie. + +- If the extension does not have [host permissions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) for the URL in the details object, the API call will fail. ### New Permissions No new permissions are required.