1. Introduction
This section is non-normative.
This is a proposal to bring an asynchronous cookie API to scripts running in HTML documents and service workers.
HTTP cookies have, since their origins at Netscape (documentation preserved by archive.org), provided a valuable state-management mechanism for the web.
The synchronous single-threaded script-level document.cookie
interface to cookies has been a source of complexity and performance woes further exacerbated by the move in many browsers from:
-
a single browser process,
-
a single-threaded event loop model, and
-
no general expectation of responsiveness for scripted event handling while processing cookie operations
... to the modern web which strives for smoothly responsive high performance:
-
in multiple browser processes,
-
with a multithreaded, multiple-event loop model, and
-
with an expectation of responsiveness on human-reflex time scales.
On the modern web a cookie operation in one part of a web application cannot block:
-
the rest of the web application,
-
the rest of the web origin, or
-
the browser as a whole.
Newer parts of the web built in service workers need access to cookies too but cannot use the synchronous, blocking document.cookie
interface at all as they both have no document
and also cannot block the event loop as that would interfere with handling of unrelated events.
1.1. A Taste of the Proposed Change
Although it is tempting to rethink cookies entirely, web sites today continue to rely heavily on them, and the script APIs for using them are largely unchanged over their first decades of usage.
Today writing a cookie means blocking your event loop while waiting for the browser to synchronously update the cookie jar with a carefully-crafted cookie string in Set-Cookie
format:
document. cookie= '__Secure-COOKIENAME=cookie-value' + '; Path=/' + '; expires=Fri, 12 Aug 2016 23:05:17 GMT' + '; Secure' + '; Domain=example.org' ; // now we could assume the write succeeded, but since // failure is silent it is difficult to tell, so we // read to see whether the write succeeded var successRegExp= /(^|; ?)__Secure-COOKIENAME=cookie-value(;|$)/ ; if ( String( document. cookie). match( successRegExp)) { console. log( 'It worked!' ); } else { console. error( 'It did not work, and we do not know why' ); }
What if you could instead write:
cookieStore. set( '__Secure-COOKIENAME' , 'cookie-value' , { expires: Date. now() + 24 * 60 * 60 * 1000 , domain: 'example.org' }). then( function () { console. log( 'It worked!' ); }, function ( reason) { console. error( 'It did not work, and this is why:' , reason); }); // Meanwhile we can do other things while waiting for // the cookie store to process the write...
This also has the advantage of not relying on document
and not blocking, which together make it usable from Service Workers, which otherwise do not have cookie access from script.
This proposal also includes a power-efficient monitoring API to replace setTimeout
-based polling cookie monitors with cookie change observers.
1.2. Summary
This proposal outlines an asynchronous API using Promises/async functions for the following cookie operations:
-
write (or "set") cookies
-
delete (or "expire") cookies
-
read (or "get") script-visible cookies
-
... including for specified in-scope request paths in service worker contexts
-
-
monitor script-visible cookies for changes using
CookieChangeEvent
-
... in long-running script contexts (e.g.
document
) -
... after registration during the
InstallEvent
in ephemeral service worker contexts -
... again including for script-supplied in-scope request paths in service worker contexts
-
1.2.1. Script visibility
A cookie is script-visible when it is in-scope and does not have the HttpOnly
cookie flag.
1.2.2. Motivations
Some service workers need access to cookies but
cannot use the synchronous, blocking document.cookie
interface as they both have no document
and
also cannot block the event loop as that would interfere with handling of unrelated events.
A new API may also provide a rare and valuable chance to address some outstanding cross-browser incompatibilities and bring divergent specs and user-agent behavior into closer correspondence.
A well-designed and opinionated API may actually make cookies easier to deal with correctly from scripts, with the potential effect of reducing their accidental misuse. An efficient monitoring API, in particular, can be used to replace power-hungry polling cookie scanners.
The API must interoperate well enough with existing cookie APIs (HTTP-level, HTML-level and script-level) that it can be adopted incrementally by a large or complex website.
1.2.3. Opinions
This API defaults cookie paths to /
for cookie write operations, including deletion/expiration. The implicit relative path-scoping of cookies to .
has caused a lot of additional complexity for relatively little gain given their security equivalence under the same-origin policy and the difficulties arising from multiple same-named cookies at overlapping paths on the same domain. Cookie paths without a trailing /
are treated as if they had a trailing /
appended for cookie write operations. Cookie paths must start with /
for write operations, and must not contain any ..
path segments. Query parameters and URL fragments are not allowed in paths for cookie write operations.
URLs without a trailing /
are treated as if the final path segment had been removed for cookie read operations, including change monitoring. Paths for cookie read operations are resolved relative to the default read cookie path.
This API defaults cookies to "Secure" when they are written from a secure web origin. This is intended to prevent unintentional leakage to unsecured connections on the same domain. Furthermore it disallows (to the extent permitted by the browser implementation) creation or modification of Secure-
flagged cookies from unsecured web origins and enforces special rules for the __Host-
and __Secure-
cookie name prefixes [RFC6265bis].
This API defaults cookies to "Domain"-less, which in conjunction with "Secure" provides origin-scoped cookie
behavior in most modern browsers. When practical the __Host-
cookie name prefix should be used with these cookies so that cooperating browsers origin-scope them.
Serialization of expiration times for non-session cookies in a special cookie-specific format has proven cumbersome, so this API allows JavaScript Date objects and numeric timestamps (milliseconds since the beginning of the Unix epoch) to be used instead. The inconsistently-implemented Max-Age parameter is not exposed, although similar functionality is available for the specific case of expiring a cookie.
Cookies without U+003D (=) code points in their HTTP Cookie header serialization are treated as having an empty name, consistent with the majority of current browsers. Cookies with an empty name cannot be set using values containing U+003D (=) code points as this would result in ambiguous serializations in the majority of current browsers.
Internationalized cookie usage from scripts has to date been slow and browser-specific due to lack of interoperability because although several major browsers use UTF-8 interpretation for cookie data, historically Safari and browsers based on WinINet have not. This API mandates UTF-8 interpretation for cookies read or written by this API.
Use of cookie-change-driven scripts has been hampered by the absence of a power-efficient (non-polling) API for this. This API provides observers for efficient monitoring in document contexts and interest registration for efficient monitoring in service worker contexts.
Scripts should not have to write and then read "test cookies" to determine whether script-initiated cookie write access is possible, nor should they have to correlate with cooperating server-side versions of the same write-then-read test to determine that script-initiated cookie read access is impossible despite cookies working at the HTTP level.
1.2.4. Compatiblity
Some user-agents implement non-standard extensions to cookie behavior. The intent of this specification,
though, is to first capture a useful and interoperable (or mostly-interoperable) subset of cookie behavior implemented
across modern browsers. As new cookie features are specified and adopted it is expected that this API will be
extended to include them. A secondary goal is to converge with document.cookie
behavior
and the http cookie specification. See https://github.com/whatwg/html/issues/804 and https://inikulin.github.io/cookie-compat/
for the current state of this convergence.
Differences across browsers in how bytes outside the printable-ASCII subset are interpreted has led to
long-lasting user- and developer-visible incompatibilities across browsers making internationalized use of cookies
needlessly cumbersome. This API requires UTF-8 interpretation of cookie data and uses USVString
for the script interface,
with the additional side-effects that subsequent uses of document.cookie
to read a cookie read or written through this interface and subsequent uses of document.cookie
to update a cookie previously read or written through this interface will also use a UTF-8 interpretation of the cookie data. In practice this
will change the behavior of WinINet
-based user agents and Safari but should bring their behavior into concordance
with other modern user agents.
2. Concepts
2.1. Cookie
A cookie is normatively defined for user agents by [RFC6265bis].
2.2. Extensions to Service Worker
[Service-Workers] defines service worker registration, which this specification extends.
A service worker registration has an associated cookie change subscription list which is a list; each member is a cookie change subscription. A cookie change subscription is a tuple of name, url, and matchType. .
3. The CookieStore
Interface
[Exposed =(ServiceWorker ,Window ),SecureContext ]interface :
CookieStore EventTarget {Promise <CookieListItem ?>get (USVString );
name Promise <CookieListItem ?>get (optional CookieStoreGetOptions );
options Promise <CookieList >getAll (USVString );
name Promise <CookieList >getAll (optional CookieStoreGetOptions );
options Promise <void >set (USVString ,
name USVString ,
value optional CookieStoreSetOptions );
options Promise <void >set (CookieStoreSetExtraOptions );
options Promise <void >delete (USVString );
name Promise <void >delete (CookieStoreDeleteOptions ); [
options Exposed =ServiceWorker ]Promise <void >subscribeToChanges (sequence <CookieStoreGetOptions >); [
subscriptions Exposed =ServiceWorker ]Promise <sequence <CookieStoreGetOptions >>getChangeSubscriptions ();attribute EventHandler onchange ; };enum {
CookieMatchType ,
"equals" };
"starts-with" dictionary {
CookieStoreGetOptions USVString ;
name USVString ;
url CookieMatchType = "equals"; };
matchType enum {
CookieSameSite ,
"strict" ,
"lax" };
"unrestricted" dictionary {
CookieStoreSetOptions DOMTimeStamp ?=
expires null ;USVString ?=
domain null ;USVString = "/";
path boolean =
secure true ;boolean =
httpOnly false ;CookieSameSite = "strict"; };
sameSite dictionary :
CookieStoreSetExtraOptions CookieStoreSetOptions {required USVString ;
name required USVString ; };
value dictionary {
CookieStoreDeleteOptions required USVString ;
name USVString ?=
domain null ;USVString = "/";
path boolean =
secure true ;CookieSameSite = "strict"; };
sameSite dictionary {
CookieListItem required USVString ;
name USVString ;
value USVString ?=
domain null ;USVString = "/";
path DOMTimeStamp ?=
expires null ;boolean =
secure true ;CookieSameSite = "strict"; };
sameSite typedef sequence <CookieListItem >;
CookieList
3.1. Methods
3.1.1. get
- cookie = await cookieStore .
get
(name)- cookie = await cookieStore .
get
(options) - cookie = await cookieStore .
-
You can read the first in-scope script-visible value for a given cookie name. In a service worker context this defaults to the path of the service worker’s registered scope. In a document it defaults to the path of the current document and does not respect changes from
replaceState()
ordocument.domain
.function getOneSimpleOriginCookie() { return cookieStore. get( '__Host-COOKIENAME' ). then( function ( cookie) { console. log( cookie? ( 'Current value: ' + cookie. value) : 'Not set' ); }); } getOneSimpleOriginCookie(). then( () => console. log( 'getOneSimpleOriginCookie succeeded!' ), reason=> console. error( 'getOneSimpleOriginCookie did not succeed: ' , reason) ); You can use exactly the same Promise-based API with the newer
async
...await
syntax and arrow functions for more readable code:async
function getOneSimpleOriginCookieAsync() { let cookie= await cookieStore. get( '__Host-COOKIENAME' ); console. log( cookie? ( 'Current value: ' + cookie. value) : 'Not set' ); } getOneSimpleOriginCookieAsync(). then( () => console. log( 'getOneSimpleOriginCookieAsync succeeded!' ), reason=> console. error( 'getOneSimpleOriginCookieAsync did not succeed: ' , reason)); Remaining examples use this syntax along with destructuring for clarity, and omit the calling code.
In a service worker context you can read a cookie from the point of view of a particular in-scope URL, which may be useful when handling regular (same-origin, in-scope) fetch events or foreign fetch events.
get(name)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let list be the results of running the steps to query cookies with url and name.
-
If list is failure, reject p with a
TypeError
and abort these steps. -
If list is empty, resolve p with undefined.
-
Otherwise, resolve p with the first item of list.
-
-
Return p.
get(options)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
If options’
url
dictionary member is present, then run these steps:-
Let parsed be the result of running the basic URL parser on options’
url
dictionary member with url. -
If the current global object is a
Window
object and parsed does not equal url, then return a new promise rejected with an "InvalidStateError
"DOMException
. -
If parsed’s origin and url’s origin are not the same origin, then return a new promise rejected with an "
InvalidStateError
"DOMException
. -
Set url to parsed.
-
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let list be the results of running the steps to query cookies with url, options’
name
dictionary member (if present), and options’matchType
dictionary member. -
If list is failure, reject p with a
TypeError
and abort these steps. -
If list is empty, resolve p with undefined.
-
Otherwise, resolve p with the first item of list.
-
-
Return p.
3.1.2. getAll
- cookies = await cookieStore .
getAll
(name)- cookies = await cookieStore .
getAll
(options) - cookies = await cookieStore .
-
Sometimes you need to see the whole script-visible in-scope subset of the cookie jar, including potential reuse of the same cookie name at multiple paths and/or domains (the paths and domains are not exposed to script by this API, though):
async
function countCookies() { let cookieList= await cookieStore. getAll(); console. log( 'How many cookies? %d' , cookieList. length); cookieList. forEach( cookie=> console. log( 'Cookie %s has value %o' , cookie. name, cookie. value)); } Sometimes an expected cookie is known by a prefix rather than by an exact name, for instance when reading all cookies managed by a particular library (e.g. in this one the name prefix identifies the library) or when reading all cookie names owned by a particular application on a shared web host (a name prefix is often used to identify the owning application):
async
function countMatchingSimpleOriginCookies() { let cookieList= await cookieStore. getAll({ name: '__Host-COOKIEN' , matchType: 'starts-with' }); console. log( 'How many matching cookies? %d' , cookieList. length); cookieList. forEach(({ name, value}) => console. log( 'Matching cookie %s has value %o' , name, value)); }
getAll(name)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let list be the results of running the steps to query cookies with url and name.
-
If list is failure, reject p with a
TypeError
. -
Otherwise, resolve p with list.
-
-
Return p.
getAll(options)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
If options’
url
dictionary member is present, then run these steps:-
Let parsed be the result of running the basic URL parser on options’
url
dictionary member with url. -
If the current global object is a
Window
object and parsed does not equal url, then return a new promise rejected with an "InvalidStateError
"DOMException
. -
If parsed’s origin and url’s origin are not the same origin, then return a new promise rejected with an "
InvalidStateError
"DOMException
. -
Set url to parsed.
-
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let list be the results of running the steps to query cookies with url, options’
name
dictionary member (if present), and options’matchType
dictionary member. -
If list is failure, reject p with a
TypeError
. -
Otherwise, resolve p with list.
-
-
Return p.
3.1.3. set
- await cookieStore .
set
(name, value)- await cookieStore .
set
(options) - await cookieStore .
- Writing (setting) a cookie is done using these methods.
asyncfunction setOneSimpleOriginSessionCookie() { await cookieStore. set( '__Host-COOKIENAME' , 'cookie-value' ); console. log( 'Set!' ); }
That defaults to path "/" and implicit domain, and defaults to a Secure-if-https-origin, non-HttpOnly session cookie which will be visible to scripts. You can override any of these defaults except for HttpOnly (which is not settable from script in modern browsers) if needed:
asyncfunction setOneDaySecureCookieWithDate() { // one day ahead, ignoring a possible leap-second let inTwentyFourHours= new Date( Date. now() + 24 * 60 * 60 * 1000 ); await cookieStore. set( '__Secure-COOKIENAME' , 'cookie-value' , { path: '/cgi-bin/' , expires: inTwentyFourHours, secure: true , domain: 'example.org' }); console. log( 'Set!' ); }
Of course the numeric form (milliseconds since the beginning of 1970 UTC) works too:
asyncfunction setOneDayUnsecuredCookieWithMillisecondsSinceEpoch() { // one day ahead, ignoring a possible leap-second let inTwentyFourHours= Date. now() + 24 * 60 * 60 * 1000 ; await cookieStore. set( 'LEGACYCOOKIENAME' , 'cookie-value' , { path: '/cgi-bin/' , expires: inTwentyFourHours, secure: false , domain: 'example.org' }); console. log( 'Set!' ); }
Sometimes an expiration date comes from existing script it’s not easy or convenient to replace, though:
asyncfunction setSecureCookieWithHttpLikeExpirationString() { await cookieStore. set( '__Secure-COOKIENAME' , 'cookie-value' , { path: '/cgi-bin/' , expires: 'Mon, 07 Jun 2021 07:07:07 GMT' , secure: true , domain: 'example.org' }); console. log( 'Set!' ); }
In this case the syntax is that of the HTTP cookies spec; any other syntax will result in promise rejection.
You can set multiple cookies too, but - as with HTTP Set-Cookie
- the multiple write operations have no guarantee of atomicity:
asyncfunction setThreeSimpleOriginSessionCookiesSequentially() { await cookieStore. set( '__Host-🍪' , '🔵cookie-value1🔴' ); await cookieStore. set( '__Host-🌟' , '🌠cookie-value2🌠' ); await cookieStore. set( '__Host-🌱' , '🔶cookie-value3🔷' ); console. log( 'All set!' ); // NOTE: this assumes no concurrent writes from elsewhere; it also // uses three separate cookie jar read operations where a single getAll // would be more efficient, but this way the CookieStore does the filtering // for us. let matchingValues= await Promise. all([ '🍪' , '🌟' , '🌱' ]. map( async ಠ_ಠ=> ( await cookieStore. get( '__Host-' + ಠ_ಠ)). value)); let actual= matchingValues. join( ';' ); let expected= '🔵cookie-value1🔴;🌠cookie-value2🌠;🔶cookie-value3🔷' ; if ( actual!== expected) { throw new Error([ 'Expected ' , JSON. stringify( expected), ' but got ' , JSON. stringify( actual)]. join( '' )); } console. log( 'All verified!' ); }
If the relative order is unimportant the operations can be performed without specifying the order:
asyncfunction setThreeSimpleOriginSessionCookiesNonsequentially() { await Promise. all([ cookieStore. set( '__Host-unordered🍪' , '🔵unordered-cookie-value1🔴' ), cookieStore. set( '__Host-unordered🌟' , '🌠unordered-cookie-value2🌠' ), cookieStore. set( '__Host-unordered🌱' , '🔶unordered-cookie-value3🔷' )]); console. log( 'All set!' ); // NOTE: this assumes no concurrent writes from elsewhere; it also // uses three separate cookie jar read operations where a single getAll // would be more efficient, but this way the CookieStore does the filtering // for us. let matchingCookies= await Promise. all([ '🍪' , '🌟' , '🌱' ]. map( ಠ_ಠ=> cookieStore. get( '__Host-unordered' + ಠ_ಠ))); let actual= matchingCookies. map(({ value}) => value). join( ';' ); let expected= '🔵unordered-cookie-value1🔴;🌠unordered-cookie-value2🌠;🔶unordered-cookie-value3🔷' ; if ( actual!== expected) { throw new Error([ 'Expected ' , JSON. stringify( expected), ' but got ' , JSON. stringify( actual)]. join( '' )); } console. log( 'All verified!' ); }
set(name, value, options)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let r be the result of running the steps to set a cookie with url, name, value, options’
expires
dictionary member, options’domain
dictionary member, options’path
dictionary member, options’secure
dictionary member, options’httpOnly
dictionary member, and options’sameSite
dictionary member. -
If r is failure, reject p with a
TypeError
and abort these steps. -
Resolve p with undefined.
-
-
Return p.
set(options)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let r be the result of running the steps to set a cookie with url, options’
name
dictionary member, options’value
dictionary member, options’expires
dictionary member, options’domain
dictionary member, options’path
dictionary member, options’secure
dictionary member, options’httpOnly
dictionary member, and options’sameSite
dictionary member. -
If r is failure, reject p with a
TypeError
and abort these steps. -
Resolve p with undefined.
-
-
Return p.
3.1.4. delete
- await cookieStore .
set
(name)- await cookieStore .
set
(options) - await cookieStore .
- Deleting (or clearing) a cookie is done using these methods.
Deleting a cookie is accomplished by expiration, that is by replacing it with an equivalent-scope cookie with an expiration in the past:
asyncfunction setExpiredSecureCookieWithDomainPathAndFallbackValue() { let theVeryRecentPast= Date. now(); let expiredCookieSentinelValue= 'EXPIRED' ; await cookieStore. set( '__Secure-COOKIENAME' , expiredCookieSentinelValue, { expires: theVeryRecentPast}); console. log( 'Expired! Deleted!! Cleared!!1!' ); }
In this case the cookie’s value is not important unless a clock is somehow re-set incorrectly or otherwise behaves nonmonotonically or incoherently.
A syntactic shorthand is also provided which is equivalent to the above except that the clock’s accuracy and monotonicity becomes irrelevant:
asyncfunction deleteSimpleOriginCookie() { await cookieStore. delete ( '__Host-COOKIENAME' ); console. log( 'Expired! Deleted!! Cleared!!1!' ); }
Again, the path and/or domain can be specified explicitly here.
asyncfunction deleteSecureCookieWithDomainAndPath() { await cookieStore. delete ( '__Secure-COOKIENAME' , { path: '/cgi-bin/' , domain: 'example.org' , secure: true }); console. log( 'Expired! Deleted!! Cleared!!1!' ); }
This API has semantics aligned with the interpretation of Max-Age=0
common to most modern browsers.
delete(name)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let r be the result of running the steps to delete a cookie with url, name, null, "
/
", true, and "strict
". -
If r is failure, reject p with a
TypeError
and abort these steps. -
Resolve p with undefined.
-
-
Return p.
delete(options)
method, when invoked, must run these steps:
-
Let origin be environment’s origin.
-
If origin is an opaque origin, then return a new promise rejected with a "
SecurityError
"DOMException
. -
Let url be the current settings object's creation URL.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let r be the result of running the steps to delete a cookie with url, options’
name
dictionary member, options’domain
dictionary member, options’path
dictionary member, options’secure
dictionary member, and options’sameSite
dictionary member. -
If r is failure, reject p with a
TypeError
and abort these steps. -
Resolve p with undefined.
-
-
Return p.
3.1.5. subscribeToChanges
Monitoring cookies in a Service Worker requires by subscribing to change events.
- await cookieStore .
subscribeToChanges
(subscriptions) -
This method can only be called during a Service Worker install phase.
self
. addEventListener( 'install' , event=> { event. waitFor( async() => { await cookieStore. subscribeToChanges([{ name: 'session' , // Get change events for session-related cookies. matchType : 'starts-with' , // Matches session_id, session-id, etc. }]); }); }); Once subscribed, notifications are delivered as "
cookiechange
" events fired against the Service Worker's global scope:self
. addEventListener( 'cookiechange' , event=> { // The event has |changed| and |deleted| properties with // the same semantics as the Document events. console . log( 'changed cookies: ' + event. changed. length); console. log( 'deleted cookies: ' + event. deleted. length); }); - subscriptions = await cookieStore .
getChangeSubscriptions()
-
This method returns a promise which resolves to a list of the cookie change subscriptions
made for this Service Worker registration.
const subscriptions= await cookieStore. getChangeSubscriptions(); for ( const subof subscriptions) { console. log( sub. name, sub. url, sub. matchType); }
subscribeToChanges(subscriptions)
method, when invoked, must run these steps:
-
Let serviceWorker be the context object's global object's service worker.
-
If serviceWorker’s state is not installing, then return a new promise rejected with a
TypeError
. -
Let registration be serviceWorker’s associated containing service worker registration.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
For each entry in subscriptions, run these steps:
-
Let name be entry’s
name
member. -
Let url be entry’s
url
member. -
Let matchType be entry’s
matchType
member. -
Let subscription be the cookie change subscription (name, url, matchType).
-
Append subscription to registration’s associated cookie change subscription list.
-
-
-
Return p.
3.1.6. getChangeSubscriptions
getChangeSubscriptions()
method, when invoked, must run these steps:
-
Let serviceWorker be the context object's global object's service worker.
-
Let registration be serviceWorker’s associated containing service worker registration.
-
Let p be a new promise.
-
Run the following steps in parallel:
-
Let subscriptions be registration’s associated cookie change subscription list.
-
Let result be a new list.
-
For each subscription in subscriptions, run these steps:
-
Resolve p with result.
-
-
Return p.
3.2. Attributes
3.2.1. onchange
onchange
, of type EventHandler-
An
EventHandler
of typeCookieChangeEvent
.
3.3. Events
3.3.1. CookieChangeEvent
A CookieChangeEvent
is dispatched against CookieStore
objects
in window contexts when any script-visible cookie changes have occurred,
and against ServiceWorkerGlobalScope
objects when any script-visible cookie changes have occurred which match the Service Worker's cookie change subscription list.
[Exposed =(ServiceWorker ,Window ),SecureContext ,(
Constructor DOMString ,
type optional CookieChangeEventInit )]
eventInitDict interface :
CookieChangeEvent Event {readonly attribute CookieList ;
changed readonly attribute CookieList ; };
deleted dictionary :
CookieChangeEventInit EventInit {CookieList ;
changed CookieList ; };
deleted
4. Global Interfaces
4.1. The Window Interface
[SecureContext ]partial interface Window { [Replaceable ,SameObject ]readonly attribute CookieStore ; };
cookieStore
The cookieStore
attribute’s getter must return context object’s relevant settings object’s CookieStore
object.
4.2. The ServiceWorkerGlobalScope Interface
partial interface ServiceWorkerGlobalScope { [Replaceable ,SameObject ]readonly attribute CookieStore ;
cookieStore attribute EventHandler ; };
oncookiechange
The cookieStore
attribute’s getter must return context object’s relevant settings object’s CookieStore
object.
5. Algorithms
5.1. Query Cookies
Specify the query cookies algorithm. <https://github.com/WICG/cookie-store/issues/69>
To query cookies with url, optional name, and optional matchType, run the following steps:
-
If ..., return failure.
-
...
-
... name ... url
-
...
-
... being generated for a "non-HTTP" API ...
-
...
-
... cookie-list ...
-
Let list be a new list.
-
For each cookie in cookie-list, run these steps:
-
Assert: cookie’s http-only-flag is false.
-
... matchType ... continue ...
-
Let item be the result of running the steps to create a CookieListItem from cookie.
-
Append item to list.
-
-
Return list.
To create a CookieListItem
from cookie, run the following steps.
-
Let item be a new
CookieListItem
. -
Set item’s
expires
to cookie’s expiry-time, as the number of milliseconds since 00:00:00 UTC, 1 January 1970, assuming that there are exactly 86,400,000 milliseconds per day.Note: This is the same representation used for time values in [ECMAScript].
-
Set item’s
secure
to cookie’s secure-only-flag. -
Switch on cookie’s same-site-flag:
-
Return item.
Note: The cookie’s creation-time, last-access-time, persistent-flag, host-only-flag, and http-only-flag attributes are not exposed to script.
5.2. Set a Cookie
Specify the set a cookie algorithm. <https://github.com/WICG/cookie-store/issues/72>
To set a cookie with url, name, value, optional expires, domain, path, secure flag, httpOnly flag, and sameSite, run the following steps:
-
If ..., return failure.
-
...
-
... name ... expires ... httpOnly ...
5.3. Delete a Cookie
Specify the delete a cookie algorithm. <https://github.com/WICG/cookie-store/issues/73>
To delete a cookie with url, name, domain, path, secure flag, and sameSite, run the following steps:
-
If ..., return failure.
-
...
-
... name
6. Security
Other than cookie access from service worker contexts, this API is not intended to expose any new capabilities to the web.
6.1. Gotcha!
Although browser cookie implementations are now evolving in the direction of better security and fewer surprising and error-prone defaults, there are at present few guarantees about cookie data security.
-
unsecured origins can typically overwrite cookies used on secure origins
-
superdomains can typically overwrite cookies seen by subdomains
-
cross-site scripting attacts and other script and header injection attacks can be used to forge cookies too
-
cookie read operations (both from script and on web servers) don’t give any indication of where the cookie came from
-
browsers sometimes truncate, transform or evict cookie data in surprising and counterintuitive ways
-
... due to reaching storage limits
-
... due to character encoding differences
-
... due to differing syntactic and semantic rules for cookies
-
For these reasons it is best to use caution when interpreting any cookie’s value, and never execute a cookie’s value as script, HTML, CSS, XML, PDF, or any other executable format.
6.2. Restrict?
This API may have the unintended side-effect of making cookies easier to use and consequently encouraging their further use. If it causes their further use in unsecured http
contexts this could result in a web less safe for users. For that reason it may be desirable to restrict its use, or at least the use of the set
and delete
operations, to secure origins running in secure contexts.
6.3. Surprises
Some existing cookie behavior (especially domain-rather-than-origin orientation, unsecured contexts being able to set cookies readable in secure contexts, and script being able to set cookies unreadable from script contexts) may be quite surprising from a web security standpoint.
Other surprises are documented in Section 1 of Cookies: HTTP State Management Mechanism (RFC 6265bis) - for instance, a cookie may be set for a superdomain (e.g. app.example.com may set a cookie for the whole example.com domain), and a cookie may be readable across all port numbers on a given domain name.
Further complicating this are historical differences in cookie-handling across major browsers, although some of those (e.g. port number handling) are now handled with more consistency than they once were.
6.4. Prefixes
Where feasible the examples use the __Host-
and __Secure-
name prefixes which causes some current browsers to disallow overwriting from unsecured contexts, disallow overwriting with no Secure
flag, and — in the case of __Host-
— disallow overwriting with an explicit Domain
or non-'/' Path
attribute (effectively enforcing same-origin semantics.) These prefixes provide important security benefits in those browsers implementing Secure Cookies and degrade gracefully (i.e. the special semantics may not be enforced in other cookie APIs but the cookies work normally and the async cookies API enforces the secure semantics for write operations) in other browsers. A major goal of this API is interoperation with existing cookies, though, so a few examples have also been provided using cookie names lacking these prefixes.
Prefix rules are also enforced in write operations by this API, but may not be enforced in the same browser for other APIs. For this reason it is inadvisable to rely on their enforcement too heavily until and unless they are more broadly adopted.
6.5. URL scoping
Although a service worker script cannot directly access cookies today, it can already use controlled rendering of in-scope HTML and script resources to inject cookie-monitoring code under the remote control of the service worker script. This means that cookie access inside the scope of the service worker is technically possible already, it’s just not very convenient.
When the service worker is scoped more narrowly than /
it may still be able to read path-scoped cookies from outside its scope’s path space by successfully guessing/constructing a 404 page URL which allows IFRAME-ing and then running script inside it the same technique could expand to the whole origin, but a carefully constructed site (one where no out-of-scope pages are IFRAME-able) can actually deny this capability to a path-scoped service worker today and I was reluctant to remove that restriction without further discussion of the implications.
6.6. Cookie aversion
To reduce complexity for developers and eliminate the need for ephemeral test cookies, this async cookies API will explicitly reject attempts to write or delete cookies when the operation would be ignored. Likewise it will explicitly reject attempts to read cookies when that operation would ignore actual cookie data and simulate an empty cookie jar. Attempts to observe cookie changes in these contexts will still "work", but won’t invoke the callback until and unless read access becomes allowed (due e.g. to changed site permissions.)
Today writing to document.cookie
in contexts where script-initiated cookie-writing is disallowed typically is a no-op. However, many cookie-writing scripts and frameworks always write a test cookie and then check for its existence to determine whether script-initiated cookie-writing is possible.
Likewise, today reading document.cookie
in contexts where script-initiated cookie-reading is disallowed typically returns an empty string. However, a cooperating web server can verify that server-initiated cookie-writing and cookie-reading work and report this to the script (which still sees empty string) and the script can use this information to infer that script-initiated cookie-reading is disallowed.