Add support for partitioned cookies to CookieStore. (#206)

* Add examples to the Explainer
* Add support for partitioned cookies to CookieStore.

explainer.md

@@ -14,9 +14,12 @@
   + [Read a cookie](#read-a-cookie)
   + [Read multiple cookies](#read-multiple-cookies)
   + [Read the cookies for a specific URL](#read-the-cookies-for-a-specific-url)
+  + [Read a partitioned cookie](#read-a-partitioned-cookie)
 * [The Modifications API](#the-modifications-api)
   + [Write a cookie](#write-a-cookie)
+  + [Write a partitioned cookie](#write-a-partitioned-cookie)
   + [Delete a cookie](#delete-a-cookie)
+  + [Delete a partitioned cookie](#delete-a-partitioned-cookie)
   + [Access all the cookie data](#access-all-the-cookie-data)
 * [The Change Events API](#the-change-events-api)
   + [Get change events in documents](#get-change-events-in-documents)
@@ -263,6 +266,23 @@ any URL under their scope.
 Documents can only obtain the cookies at their current URL. In other words,
 the only valid `url` value in Document contexts is the document's URL.
 
+### Read a partitioned cookie
+
+The cookie objects will have a boolean value indicating if the cookie is partitioned.
+
+```javascript
+// Read a cookie set without the Partitioned attribute.
+const cookie = await cookieStore.get('session_id');
+console.log(cookie.partitioned);  // -> false
+
+// Read a Partitioned cookie from a third-party context.
+const cookie = await cookieStore.get({
+  name: '__Host-third_party_session_id',
+  partitioned: true
+});
+console.log(cookie.partitioned);  // -> true
+```
+
 ## The Modifications API
 
 Both documents and service workers access the same modification API, via the
@@ -292,6 +312,22 @@ await cookieStore.set({
 });
 ```
 
+### Write a partitioned cookie
+
+If the user agent supports [cookie partitioning](https://github.com/WICG/CHIPS)
+then you can set a partitioned cookie in a third-party context using the following.
+
+```javascript
+await cookieStore.set({
+  name: '__Host-third_party_session_id',
+  value: 'foobar',
+  path: '/',
+  sameSite: 'none',
+  partitioned: true
+  // `Secure` is implicitly set
+});
+```
+
 ### Delete a cookie
 
 ```javascript
@@ -316,6 +352,24 @@ try {
 }
 ```
 
+### Delete a partitioned cookie
+
+If the user agent supports [cookie partitioning](https://github.com/WICG/CHIPS)
+then it is possible for a site to set both a partitioned and unpartitioned
+cookie with the same name.
+
+To delete a partitioned cookie, the `partitioned` parameter must be provided:
+
+```javascript
+await cookieStore.delete({
+  name: '__Host-third_party_session_id',
+  partitioned: true
+});
+```
+
+If the site wants to only delete the unpartitioned cookie, change the `partitioned`
+field to `false` or omit the property.  
+
 ### Access all the cookie data
 
 The objects returned by `get` and `getAll` contain all the information in the

index.bs

@@ -513,12 +513,14 @@ dictionary CookieInit {
   USVString? domain = null;
   USVString path = "/";
   CookieSameSite sameSite = "strict";
+  boolean partitioned = false;
 };
 
 dictionary CookieStoreDeleteOptions {
   required USVString name;
   USVString? domain = null;
   USVString path = "/";
+  boolean partitioned = false;
 };
 
 dictionary CookieListItem {
@@ -529,6 +531,7 @@ dictionary CookieListItem {
   DOMHighResTimeStamp? expires;
   boolean secure;
   CookieSameSite sameSite;
+  boolean partitioned;
 };
 
 typedef sequence<CookieListItem> CookieList;
@@ -706,8 +709,9 @@ The <dfn method for=CookieStore>set(|options|)</dfn> method steps are:
         |options|["{{CookieInit/value}}"],
         |options|["{{CookieInit/expires}}"],
         |options|["{{CookieInit/domain}}"],
-        |options|["{{CookieInit/path}}"], and
-        |options|["{{CookieInit/sameSite}}"].
+        |options|["{{CookieInit/path}}"],
+        |options|["{{CookieInit/sameSite}}"], and
+        |options|["{{CookieInit/partitioned}}"].
     1. If |r| is failure, then [=reject=] |p| with a {{TypeError}} and abort these steps.
     1. [=/Resolve=] |p| with undefined.
 1. Return |p|.
@@ -762,8 +766,9 @@ The <dfn method for=CookieStore>delete(|options|)</dfn> method steps are:
     1. Let |r| be the result of running [=delete a cookie=] with
         |url|,
         |options|["{{CookieStoreDeleteOptions/name}}"],
-        |options|["{{CookieStoreDeleteOptions/domain}}"], and
-        |options|["{{CookieStoreDeleteOptions/path}}"].
+        |options|["{{CookieStoreDeleteOptions/domain}}"],
+        |options|["{{CookieStoreDeleteOptions/path}}"], and
+        |options|["{{CookieStoreDeleteOptions/partitioned}}"].
     1. If |r| is failure, then [=reject=] |p| with a {{TypeError}} and abort these steps.
     1. [=/Resolve=] |p| with undefined.
 1. Return |p|.
@@ -1084,14 +1089,16 @@ To <dfn>create a {{CookieListItem}}</dfn> from |cookie|, run the following steps
         : \``Lax`\`
         :: Let |sameSite| be "{{CookieSameSite/lax}}".
     </dl>
+1. Let |partitioned| be a boolean indicating that the user agent supports [cookie partitioning](https://github.com/privacycg/CHIPS) and that that |cookie| has a partition key.
 1. Return «[
     "name" → |name|,
     "value" → |value|,
     "domain" → |domain|,
     "path" → |path|,
     "expires" → |expires|,
     "secure" → |secure|,
-    "sameSite" → |sameSite|
+    "sameSite" → |sameSite|,
+    "partitioned" → |partitioned|
     ]»
 
 Note: The |cookie|'s
@@ -1116,8 +1123,9 @@ To <dfn>set a cookie</dfn> with
 |value|,
 optional |expires|,
 |domain|,
-|path|, and
-|sameSite|,
+|path|,
+|sameSite|, and
+|partitioned|
 run the following steps:
 
 1. If |name| or |value| contain U+003B (`;`), any [=C0 control=] character except U+0009 (the horizontal tab character), or U+007F, then return failure.
@@ -1156,6 +1164,7 @@ run the following steps:
         : "{{CookieSameSite/lax}}"
         :: [=list/Append=] \``SameSite`\`/\``Lax`\` to |attributes|.
     </dl>
+1. If |partitioned| is true, [=list/Append=] \``Partitioned`\`/\`\` to |attributes|.
 1. Perform the steps defined in [[RFC6265bis#section-5.6]]<!-- Storage Model --> for when the user agent "receives a cookie" with
     |url| as <var ignore>request-uri</var>,
     |encodedName| as <var ignore>cookie-name</var>,
@@ -1180,8 +1189,9 @@ run the following steps:
 To <dfn>delete a cookie</dfn> with
 |url|,
 |name|,
-|domain| and
-|path|,
+|domain|,
+|path|, and
+|partitioned|
 run the following steps:
 
 1. If |path| is not null, then run these steps:
@@ -1205,8 +1215,9 @@ run the following steps:
     |value|,
     |expires|,
     |domain|,
-    |path|, and
-    |sameSite|.
+    |path|,
+    |sameSite|, and
+    |partitioned|.
 
 </div>