Add CHIPS docs (#23495)

Fixes #23485
mdn · Jan 23, 2023 · 98f4d08 · 98f4d08
1 parent cc1ba4c
commit 98f4d08
Show file tree

Hide file tree

Showing 9 changed files with 211 additions and 73 deletions.
diff --git a/files/en-us/web/api/cookiestore/delete/index.md b/files/en-us/web/api/cookiestore/delete/index.md
@@ -14,7 +14,7 @@ browser-compat: api.CookieStore.delete
 
 {{securecontext_header}}{{APIRef("Cookie Store API")}}{{SeeCompatTable}}
 
-The **`delete()`** method of the {{domxref("CookieStore")}} interface deletes a cookie with the given name or options object. (See below.) The `delete()` method expires the cookie by changing the date to one in the past.
+The **`delete()`** method of the {{domxref("CookieStore")}} interface deletes a cookie with the given name or options object. The `delete()` method expires the cookie by changing the date to one in the past.
 
 ## Syntax
 
@@ -29,16 +29,21 @@ This method requires one of the following:
 
 - `name`
   - : A string with the name of a cookie.
+
+Or
+
 - `options`
 
   - : An object containing:
 
     - `name`
       - : A string with the name of a cookie.
-    - `url` {{Optional_Inline}}
-      - : A string with the URL of a cookie.
+    - `partitioned` {{Optional_Inline}}
+      - : A boolean value that defaults to `false`. Setting it to `true` specifies that the cookie to delete will be a partitioned cookie. See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) for more information.
     - `path` {{Optional_Inline}}
       - : A string containing a path.
+    - `url` {{Optional_Inline}}
+      - : A string with the URL of a cookie.
 
 > **Note:** The `url` option enables the modification of a cookie scoped under a particular URL. Service workers can obtain cookies that would be sent to any URL under their scope. From a document you may only obtain the cookies at the current URL, so the only valid URL in a document context is the document's URL.
 

diff --git a/files/en-us/web/api/cookiestore/get/index.md b/files/en-us/web/api/cookiestore/get/index.md
@@ -14,7 +14,7 @@ browser-compat: api.CookieStore.get
 
 {{securecontext_header}}{{APIRef("Cookie Store API")}}{{SeeCompatTable}}
 
-The **`get()`** method of the {{domxref("CookieStore")}} interface returns a single cookie with the given name or options object. (See below.) The method will return the first matching cookie for the passed parameters.
+The **`get()`** method of the {{domxref("CookieStore")}} interface returns a single cookie with the given name or options object. The method will return the first matching cookie for the passed parameters.
 
 ## Syntax
 
@@ -29,6 +29,9 @@ This method requires one of the following:
 
 - `name`
   - : A string with the name of a cookie.
+
+Or
+
 - `options`
 
   - : An object containing:
@@ -42,23 +45,26 @@ This method requires one of the following:
 
 ### Return value
 
-A {{jsxref("Promise")}} that resolves with an object containing the first cookie matching the submitted name or options. This object contains the following properties:
+A {{jsxref("Promise")}} that resolves with an object representing the first cookie matching the submitted name or options. This object contains the following properties:
 
-- `name`
-  - : A string containing the name of the cookie.
-- `value`
-  - : A string containing the value of the cookie.
 - `domain`
   - : A string containing the domain of the cookie.
-- `path`
-  - : A string containing the path of the cookie.
+
 - `expires`
   - : A timestamp, given as [Unix time](/en-US/docs/Glossary/Unix_time) in milliseconds, containing the expiration date of the cookie.
-- `secure`
-  - : A boolean value indicating whether the cookie is to be used in secure contexts only.
+
+- `name`
+  - : A string containing the name of the cookie.
+
+- `partitioned`
+  - : A boolean indicating whether the cookie is a partitioned cookie (`true`) or not (`false`). See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) for more information.
+
+- `path`
+  - : A string containing the path of the cookie.
+
 - `sameSite`
 
-  - : One of the following [SameSite](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) values:
+  - : One of the following [SameSite](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) values (see [SameSite cookies explained](https://web.dev/samesite-cookies-explained/) for more information):
 
     - `"strict"`
       - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites.
@@ -67,7 +73,11 @@ A {{jsxref("Promise")}} that resolves with an object containing the first cookie
     - `"none"`
       - : Cookies will be sent in all contexts.
 
-    > **Note:** For more information on SameSite cookies see [SameSite cookies explained](https://web.dev/samesite-cookies-explained/).
+- `secure`
+  - : A boolean value indicating whether the cookie is to be used in secure contexts only (`true`) or not (`false`).
+
+- `value`
+  - : A string containing the value of the cookie.
 
 ### Exceptions
 

diff --git a/files/en-us/web/api/cookiestore/getall/index.md b/files/en-us/web/api/cookiestore/getall/index.md
@@ -27,6 +27,9 @@ getAll(options)
 
 - `name` {{optional_inline}}
   - : A string with the name of a cookie.
+
+Or
+
 - `options` {{optional_inline}}
 
   - : An object containing:
@@ -40,7 +43,41 @@ getAll(options)
 
 ### Return value
 
-A {{jsxref("Promise")}} that resolves with a list of cookies for the given name or options.
+A {{jsxref("Promise")}} that resolves with an array of objects representing cookies that match the given name or options.
+
+Each object contains the following properties:
+
+- `domain`
+  - : A string containing the domain of the cookie.
+
+- `expires`
+  - : A timestamp, given as [Unix time](/en-US/docs/Glossary/Unix_time) in milliseconds, containing the expiration date of the cookie.
+
+- `name`
+  - : A string containing the name of the cookie.
+
+- `partitioned`
+  - : A boolean indicating whether the cookie is a partitioned cookie (`true`) or not (`false`). See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) for more information.
+
+- `path`
+  - : A string containing the path of the cookie.
+
+- `sameSite`
+
+  - : One of the following [SameSite](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) values (see [SameSite cookies explained](https://web.dev/samesite-cookies-explained/) for more information):
+
+    - `"strict"`
+      - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites.
+    - `"lax"`
+      - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link).
+    - `"none"`
+      - : Cookies will be sent in all contexts.
+
+- `secure`
+  - : A boolean value indicating whether the cookie is to be used in secure contexts only (`true`) or not (`false`).
+
+- `value`
+  - : A string containing the value of the cookie.
 
 ### Exceptions
 

diff --git a/files/en-us/web/api/cookiestore/set/index.md b/files/en-us/web/api/cookiestore/set/index.md
@@ -14,7 +14,7 @@ browser-compat: api.CookieStore.set
 
 {{securecontext_header}}{{APIRef("Cookie Store API")}}{{SeeCompatTable}}
 
-The **`set()`** method of the {{domxref("CookieStore")}} interface sets a cookie with the given name and value or options object. (See below.)
+The **`set()`** method of the {{domxref("CookieStore")}} interface sets a cookie with the given name and value or options object.
 
 ## Syntax
 
@@ -31,23 +31,26 @@ This method requires one of the following:
   - : A string with the name of the cookie.
 - `value`
   - : A string with the value of the cookie.
+
+Or
+
 - `options`
 
   - : An object containing:
 
-    - `name`
-      - : A string with the name of a cookie.
-    - `value`
-      - : A string with the value of the cookie.
-    - `expires` {{Optional_Inline}}
-      - : A timestamp, given as [Unix time](/en-US/docs/Glossary/Unix_time) in milliseconds, containing the expiration date of the cookie.
     - `domain` {{Optional_Inline}}
       - : A string containing the domain of the cookie.
+    - `expires` {{Optional_Inline}}
+      - : A timestamp, given as [Unix time](/en-US/docs/Glossary/Unix_time) in milliseconds, containing the expiration date of the cookie.
+    - `name`
+      - : A string with the name of a cookie.
+    - `partitioned` {{Optional_Inline}}
+      - : A boolean value that defaults to `false`. If set to `true`, the set cookie will be a partitioned cookie. See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) for more information.
     - `path` {{Optional_Inline}}
       - : A string containing the path of the cookie.
     - `sameSite` {{Optional_Inline}}
 
-      - : One of the following [SameSite](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) values:
+      - : One of the following [SameSite](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) values (see [SameSite cookies explained](https://web.dev/samesite-cookies-explained/) for more information):
 
         - `"strict"`
           - : Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.
@@ -56,7 +59,8 @@ This method requires one of the following:
         - `"none"`
           - : Cookies will be sent in all contexts.
 
-        > **Note:** For more information on SameSite cookies see [SameSite cookies explained](https://web.dev/samesite-cookies-explained/).
+    - `value`
+      - : A string with the value of the cookie.
 
 ### Return value
 

diff --git a/files/en-us/web/api/document/cookie/index.md b/files/en-us/web/api/document/cookie/index.md
@@ -42,50 +42,39 @@ not abide by this.
 document.cookie = newCookie;
 ```
 
-In the code above, `newCookie` is a string of form
-`key=value`. Note that you can only set/update a
-single cookie at a time using this method. Consider also that:
+In the code above, `newCookie` is a string of form `key=value`, specifying the cookie to set/update. Note that you can only set/update a single cookie at a time using this method. Consider also that:
 
 - Any of the following cookie attribute values can optionally follow the key-value
-  pair, specifying the cookie to set/update, and preceded by a semicolon separator:
-
-  - `;path=path` (e.g., '`/`',
-    '`/mydir`') If not specified, defaults to the current path
-    of the current document location.
+  pair, each preceded by a semicolon separator:
 
   - `;domain=domain` (e.g.,
-    '`example.com`' or '`subdomain.example.com`'). If
-    not specified, this defaults to the host portion of the current document
-    location. Contrary to earlier specifications, leading dots in domain names
-    are ignored, but browsers may decline to set the cookie containing such
-    dots. If a domain is specified, subdomains are always included.
+    '`example.com`' or '`subdomain.example.com`'): The host to which the cookie will be sent. If not specified, this defaults to the host portion of the current document location. Contrary to earlier specifications, leading dots in domain names are ignored, but browsers may decline to set the cookie containing such dots. If a domain is specified, subdomains are always included.
 
     > **Note:** The domain _must_ match
     > the domain of the JavaScript origin. Setting cookies to foreign
     > domains will be silently ignored.
 
-  - `;max-age=max-age-in-seconds` (e.g.,
-    `60*60*24*365` or 31536000 for a year)
-  - `;expires=date-in-GMTString-format` If neither
-    `expires` nor `max-age` specified it will expire at
-    the end of session.
+  - `;expires=date-in-GMTString-format`: The expiry date of the cookie. If neither `expires` nor `max-age` specified it will expire at the end of session.
 
     > **Warning:** When user privacy is a concern, it's important that any web app
     > implementation invalidate cookie data after a certain timeout
     > instead of relying on the browser to do it. Many browsers let
     > users specify that cookies should never expire, which is not
     > necessarily safe.
 
-    - See {{jsxref("Date.toUTCString()")}} for help formatting this
+      See {{jsxref("Date.toUTCString()")}} for help formatting this
       value.
 
-  - `;secure` Cookie to only be transmitted
-    over secure protocol as https. Before Chrome 52, this flag could appear
-    with cookies from http domains.
-  - `;samesite` [SameSite](/en-US/docs/Web/HTTP/Cookies#samesite_cookies)
-    prevents the browser from sending this cookie along with cross-site
-    requests. Possible values are `lax`,
-    `strict` or `none`.
+  - `;max-age=max-age-in-seconds`: The maximum age of the cookie in seconds (e.g.,
+    `60*60*24*365` or 31536000 for a year).
+
+  - `;partitioned`: Indicates that the cookie should be stored using partitioned storage. See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) for more details.
+
+  - `;path=path`: Indicates the path that must exist in the requested URL for the browser to send the {{httpheader("Cookie")}} header (e.g., '`/`',
+    '`/mydir`'). If not specified, it defaults to the current path of the current document location.
+
+  - `;samesite`: [SameSite](/en-US/docs/Web/HTTP/Cookies#samesite_cookies) prevents the browser from sending this cookie along with cross-site
+    requests. Possible values are `lax`, `strict` or `none`.
 
     - The `lax` value will send the cookie for all same-site
       requests and top-level navigation GET requests. This is sufficient
@@ -98,6 +87,8 @@ single cookie at a time using this method. Consider also that:
       be applied. The cookie will be sent in all requests—both
       cross-site and same-site.
 
+  - `;secure`: Specifies that the cookie should only be transmitted over a secure protocol.
+
 - The cookie value string can use {{jsxref("Global_Objects/encodeURIComponent",
   "encodeURIComponent()")}} to ensure that the string does not contain any commas,
   semicolons, or whitespace (which are disallowed in cookie values).

diff --git a/files/en-us/web/http/cookies/index.md b/files/en-us/web/http/cookies/index.md
@@ -221,7 +221,10 @@ Firefox, by default, blocks third-party cookies that are known to contain tracke
 Third-party cookies (or just tracking cookies) may also be blocked by other browser settings or extensions.
 Cookie blocking can cause some third-party components (such as social media widgets) not to function as intended.
 
-> **Note:** Servers can (and should) set the cookie [SameSite attribute](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) to specify whether or not cookies may be sent to third party sites.
+There are some useful features available for developers who wish to respect user privacy, and minimize third-party tracking:
+
+- Servers can (and should) set the cookie [SameSite attribute](/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) to specify whether or not third-party cookies may be sent.
+- [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Partitioned_cookies) enables developers to opt-in their cookies to partitioned storage, with a separate cookie jar per top-level site. This enables valid non-tracking uses of third-party cookies to continue working in browsers that do not allow cookies to be used for third-party tracking.
 
 ### Cookie-related regulations