cookies.get orders cookies according to RFC-6265 (#36193)

* cookies.get orders cookies according to RFC-6265 * dFPI update * Suggestion from review Co-authored-by: Vadim Makeev <[email protected]> * Suggestion from feedback Co-authored-by: Vadim Makeev <[email protected]> * feedback update * Permission details to all methods and revision to main permission section --------- Co-authored-by: Vadim Makeev <[email protected]>
mdn · Nov 22, 2024 · 6f58b8a · 6f58b8a
1 parent e2ac6a9
commit 6f58b8a
Show file tree

Hide file tree

Showing 12 changed files with 135 additions and 110 deletions.
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/cookie/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/cookie/index.md
@@ -11,18 +11,18 @@ The `Cookie` type of the {{WebExtAPIRef("cookies")}} API represents information
 
 ## Type
 
-Values of this type are objects, which can contain the following properties:
+Values of this type are objects that can contain these properties:
 
 - `domain`
-  - : A `string` representing the domain the cookie belongs to (e.g. "www\.google.com", "example.com").
+  - : A `string` representing the domain the cookie belongs to (e.g., "www.google.com" or "example.com").
 - `expirationDate` {{optional_inline}}
   - : A `number` representing the expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.
 - `firstPartyDomain`
-  - : A `string` representing the first-party domain associated with the cookie. This will be an empty string if the cookie was set while first-party isolation was off. See [First-party isolation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation).
+  - : A `string` representing the first-party domain associated with the cookie. This is an empty string if the cookie was set while first-party isolation was off. See [First-party isolation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation).
 - `hostOnly`
-  - : A `boolean`, `true` if the cookie is a host-only cookie (i.e. the request's host must exactly match the domain of the cookie), or `false` otherwise.
+  - : A `boolean`, `true` if the cookie is a host-only cookie (i.e., the request's host must exactly match the domain of the cookie), or `false` otherwise.
 - `httpOnly`
-  - : A `boolean`, `true` if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts), or `false` otherwise.
+  - : A `boolean`, `true` if the cookie is marked as HttpOnly (i.e., the cookie is inaccessible to client-side scripts), or `false` otherwise.
 - `name`
   - : A `string` representing the name of the cookie.
 - `partitionKey` {{optional_inline}}
@@ -35,7 +35,7 @@ Values of this type are objects, which can contain the following properties:
 - `path`
   - : A `string` representing the path of the cookie.
 - `secure`
-  - : A `boolean`, `true` if the cookie is marked as secure (i.e. its scope is limited to secure channels, typically HTTPS), or `false` otherwise.
+  - : A `boolean`, `true` if the cookie is marked as secure (i.e., its scope is limited to secure channels, typically HTTPS), or `false` otherwise.
 - `session`
   - : A `boolean`, `true` if the cookie is a session cookie, or `false` if it is a persistent cookie with an expiration date.
 - `sameSite`
@@ -45,15 +45,11 @@ Values of this type are objects, which can contain the following properties:
 - `value`
   - : A `string` representing the value of the cookie.
 
-## Browser compatibility
-
-{{Compat}}
-
 ## Examples
 
-Most methods in the cookies API involve a `Cookie` object being used either as an input parameter or as part of the return value. For example, a call to {{WebExtAPIRef("cookies.getAll()")}} returns an array of `Cookie` objects.
+Most methods in the cookies API involve a `Cookie` object as an input parameter or as part of the return value. For example, a call to {{WebExtAPIRef("cookies.getAll()")}} returns an array of `Cookie` objects.
 
-In the example below we've asked for all cookies, then logged some of the values of each of the resulting `Cookie` objects:
+This example asks for all cookies, then logs some of the values fron each of the resulting `Cookie` objects:
 
 ```js
 function logCookies(cookies) {
@@ -71,6 +67,10 @@ gettingAll.then(logCookies);
 
 {{WebExtExamples}}
 
+## Browser compatibility
+
+{{Compat}}
+
 > [!NOTE]
 > This API is based on Chromium's [`chrome.cookies`](https://developer.chrome.com/docs/extensions/reference/api/cookies#type-Cookie) API. This documentation is derived from [`cookies.json`](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json) in the Chromium code.
 

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/cookiestore/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/cookiestore/index.md
@@ -9,29 +9,25 @@ browser-compat: webextensions.api.cookies.CookieStore
 
 The `CookieStore` type of the {{WebExtAPIRef("cookies")}} API represents a cookie store in the browser.
 
-Windows in different browsing modes may use different cookie stores. For example, a private browsing/incognito mode window uses a separate cookie store from a non-incognito/private window. Also, a window may have several cookie stores when using [container tabs](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers) in Firefox.
+Windows in different browsing modes may use different cookie stores. For example, a private browsing (or incognito) mode window uses a separate cookie store from a non-private window. Also, a window may have several cookie stores in Firefox when using [container tabs](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers).
 
 See [Work with the Cookies API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Cookies_API#cookie_stores) for more information about cookie stores.
 
 ## Type
 
-Values of this type are objects, which can contain the following properties:
+Values of this type are objects that can contain these properties:
 
 - `id`
-  - : A `string` representing the unique identifier for the cookie store.
+  - : A `string` containing the cookie store's unique identifier.
 - `incognito` {{optional_inline}}
   - : A boolean value that indicates whether this is an incognito cookie store.
     This property is not supported in Chrome or Safari. However, you can identify incognito cookie stores in Chrome because their `id` is always "1".
 - `tabIds`
-  - : An `array` of `integers`, which identifies all of the browser tabs that share this cookie store.
-
-## Browser compatibility
-
-{{Compat}}
+  - : An `array` of `integers` that identifies all the browser tabs that share this cookie store.
 
 ## Examples
 
-In the following snippet, the {{WebExtAPIRef("cookies.getAllCookieStores()")}} method is used to retrieve all the cookie stores currently available in the browser, and print out each cookie store ID, and the tabs that currently share each cookie store.
+In this snippet, the {{WebExtAPIRef("cookies.getAllCookieStores()")}} method is used to retrieve all the cookie stores available in the browser. Then, it prints out each cookie store ID and the tabs that share each cookie store.
 
 ```js
 function logStores(cookieStores) {
@@ -43,7 +39,7 @@ function logStores(cookieStores) {
 browser.cookies.getAllCookieStores().then(logStores);
 ```
 
-The following code snippet gets all cookie stores and then logs the total number of stores and how many of those stores are incognito.
+This code snippet gets all cookie stores and then logs the total number of stores and how many of those stores are incognito.
 
 ```js
 browser.cookies.getAllCookieStores().then((stores) => {
@@ -56,6 +52,10 @@ browser.cookies.getAllCookieStores().then((stores) => {
 
 {{WebExtExamples}}
 
+## Browser compatibility
+
+{{Compat}}
+
 > [!NOTE]
 > This API is based on Chromium's [`chrome.cookies`](https://developer.chrome.com/docs/extensions/reference/api/cookies#type-CookieStore) API. This documentation is derived from [`cookies.json`](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json) in the Chromium code.
 

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/get/index.md
@@ -7,9 +7,14 @@ browser-compat: webextensions.api.cookies.get
 
 {{AddonSidebar}}
 
-The **`get()`** method of the {{WebExtAPIRef("cookies")}} API retrieves information about a single cookie, given its name and URL.
+The **`get()`** method of the {{WebExtAPIRef("cookies")}} API retrieves information about a cookie, given the cookie's name and URL.
 
-If more than one cookie with the same name exists for a given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned. If no matching cookie could be found, `null` is returned.
+To use this method, an extension must have the `"cookies"` permission and relevant host permissions. See [`cookie` permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#permissions) for more details.
+
+If there is more than one cookie with the same name for a URL, the cookie with the longest path is returned. For cookies with the same path length, the cookie with the earliest creation time is returned. If no matching cookie is found, `null` is returned.
+
+> [!NOTE]
+> Before Firefox 133, when there was more than one cookie with the same name, Firefox returned the cookie with the earliest creation time.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
@@ -25,7 +30,7 @@ let getting = browser.cookies.get(
 
 - `details`
 
-  - : An `object` containing details that can be used to match a cookie to be retrieved. It can include the following properties:
+  - : An `object` containing details that are used to match a cookie to be retrieved. It can include these properties:
 
     - `firstPartyDomain` {{optional_inline}}
       - : A `string` representing the first-party domain with which the cookie to retrieve is associated. This property must be supplied if the browser has first-party isolation enabled. See [First-party isolation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation).
@@ -39,21 +44,17 @@ let getting = browser.cookies.get(
           - : A `string` representing the first-party URL of the top-level site storage partition containing the cookie.
 
     - `storeId` {{optional_inline}}
-      - : A `string` representing the ID of the [cookie store](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/CookieStore) in which to look for the cookie (as returned by {{WebExtAPIRef("cookies.getAllCookieStores()")}}). By default, the current execution context's cookie store will be used.
+      - : A `string` representing the ID of the [cookie store](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/CookieStore) in which to look for the cookie (as returned by {{WebExtAPIRef("cookies.getAllCookieStores()")}}). By default, the current execution context's cookie store is used.
     - `url`
-      - : A `string` representing the URL with which the cookie to retrieve is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is ignored. If [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) for this URL are not specified in the extension's [manifest file](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json), the API call will fail.
+      - : A `string` representing the URL with which the cookie to retrieve is associated. This argument may be a full URL, in which case any data following the URL path (e.g., the query string) is ignored. If [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) for this URL are not specified in the extension's [manifest file](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json), the API call fails.
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with a {{WebExtAPIRef('cookies.Cookie', 'Cookie')}} object containing details about the cookie, or `null` if the cookie was not found.
-
-## Browser compatibility
-
-{{Compat}}
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with a {{WebExtAPIRef('cookies.Cookie', 'Cookie')}} object containing details about the cookie, or `null` if the cookie is not found.
 
 ## Examples
 
-This example tries to get the cookie named "favorite-color", associated with the URL for the currently active tab:
+This example tries to get the cookie named "favorite-color" associated with the URL for the active tab:
 
 ```js
 function logCookie(cookie) {
@@ -79,6 +80,10 @@ getActive.then(getCookie);
 
 {{WebExtExamples}}
 
+## Browser compatibility
+
+{{Compat}}
+
 > [!NOTE]
 > This API is based on Chromium's [`chrome.cookies`](https://developer.chrome.com/docs/extensions/reference/api/cookies#method-get) API. This documentation is derived from [`cookies.json`](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json) in the Chromium code.
 

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md
@@ -7,7 +7,9 @@ browser-compat: webextensions.api.cookies.getAll
 
 {{AddonSidebar}}
 
-The **`getAll()`** method of the {{WebExtAPIRef("cookies")}} API retrieves all cookies from a single cookie store that match the given information.
+The **`getAll()`** method of the {{WebExtAPIRef("cookies")}} API retrieves all cookies from a cookie store that match the details provided.
+
+To use this method, an extension must have the `"cookies"` permission and relevant host permissions. See [`cookie` permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#permissions) for more details.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
@@ -23,25 +25,25 @@ let getting = browser.cookies.getAll(
 
 - `details`
 
-  - : An `object` containing details that can be used to match cookies to be retrieved. Included properties are as follows (see [Cookie type](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/Cookie#type) for more information on these):
+  - : An `object` containing details that are used to match cookies to retrieve. Included properties are as follows (see [Cookie type](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies/Cookie#type) for more information on these):
 
     - `domain` {{optional_inline}}
       - : A `string` representing a domain that cookies must be associated with (they can be associated either with this exact domain or one of its subdomains).
     - `firstPartyDomain` {{optional_inline}}
 
       - : A `string` representing the first-party domain with which the cookie to retrieve is associated.
 
-        This property must be supplied if the browser has first-party isolation enabled. You can however pass `null` in this situation. If you do this, then cookies with any value for `firstPartyDomain`, as well as cookies which do not have `firstPartyDomain` set at all, will be included in the results. See [First-party isolation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation).
+        This property must be supplied if the browser has first-party isolation enabled. If you pass `null`, cookies with any value for `firstPartyDomain` and cookies that do not have `firstPartyDomain` set are included in the results. See [First-party isolation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation).
 
     - `name` {{optional_inline}}
-      - : A `string` representing a name that the cookies should have.
+      - : A `string` representing a name that the cookies must have.
     - `partitionKey` {{optional_inline}}
 
       - : An `object` defining which [storage partitions](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#storage_partitioning) to return cookies from:
 
-        - if omitted, returns only cookies from unpartitioned storage.
-        - if included without `topLevelSite`, returns all cookies from partitioned and unpartitioned storage.
-        - if included with `topLevelSite` specified, returns cookies from the specified partition storage.
+        - If omitted, only cookies from unpartitioned storage are returned.
+        - If included without `topLevelSite', all cookies from partitioned and unpartitioned storage are returned.
+        - If included with the specified `topLevelSite', cookies from the specified partition storage are returned.
 
         This object contains:
 
@@ -51,25 +53,24 @@ let getting = browser.cookies.getAll(
     - `path` {{optional_inline}}
       - : A `string` representing a path — the cookies' path must be identical to this one.
     - `secure` {{optional_inline}}
-      - : A `boolean` — filters cookies by their `secure` property, allowing you to filter secure cookies vs. non-secure cookies.
+      - : A `boolean` — filters cookies by their `secure` property, allowing you to filter secure or non-secure cookies.
     - `session` {{optional_inline}}
-      - : A `boolean` — filters the cookies by their `session` property, allowing you to filter session cookies vs. persistent cookies.
+      - : A `boolean` — filters the cookies by their `session` property, allowing you to filter session or persistent cookies.
     - `storeId` {{optional_inline}}
-      - : A `string` representing the cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used.
+      - : A `string` representing the cookie store to retrieve cookies from. If omitted, the current execution context's cookie store is used.
     - `url` {{optional_inline}}
       - : A `string` representing a URL that the retrieved cookies must be associated with.
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an array of `{{WebExtAPIRef('cookies.Cookie')}}` objects that match the properties given in the `details` parameter. Only unexpired cookies are returned. The cookies returned will be sorted by path length, longest to shortest. If multiple cookies have the same path length, those with the earliest creation time will be first.
-
-## Browser compatibility
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with an array of `{{WebExtAPIRef('cookies.Cookie')}}` objects that match the properties given in the `details` parameter. Only unexpired cookies are returned. The cookies returned are sorted by path length, longest to shortest. If multiple cookies have the same path length, those with the earliest creation time are first.
 
-{{Compat}}
+> [!NOTE]
+> Before Firefox 133, Firefox returned the cookie sorted by creation time, with the earliest creation time first.
 
 ## Examples
 
-In the following snippet, we are making a call to get all of the cookies the browser currently has stored that have a name of "favorite-color". When the result is returned, we are printing the value of each result to the console.
+This example gets all of the cookies the browser has stored with the name "favorite-color". When the result is returned, the code prints the value of each result to the console.
 
 ```js
 function logCookies(cookies) {
@@ -87,6 +88,10 @@ browser.cookies
 
 {{WebExtExamples}}
 
+## Browser compatibility
+
+{{Compat}}
+
 > [!NOTE]
 > This API is based on Chromium's [`chrome.cookies`](https://developer.chrome.com/docs/extensions/reference/api/cookies#method-getAll) API. This documentation is derived from [`cookies.json`](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json) in the Chromium code.