CookieJar Class

A cookie store as specified by the user agent requirements of RFC 6265bis (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-user-agent-requirements): the cookies of the Set-Cookie headers of the responses and of the scripts (document.cookie, cookieStore), sent in the Cookie header of the requests (see DocumentRequest.GetCookieHeader).

public sealed class CookieJar

Remarks

The jar implements the storage model (the Domain, Path, Expires, Max-Age, Secure, HttpOnly, SameSite and Partitioned attributes, the __Secure-, __Host-, __Http- and __Host-Http- prefixes, the public suffixes and the size limits) and the retrieval model (the "same-site" and "cross-site" requests, schemefully). The cookies with the Partitioned attribute are keyed by the site of the top-level document (CHIPS); the other cookies are not partitioned. By default, the third-party cookies are not blocked: CookieJar.BlockThirdPartyCookies and CookieJar.SetThirdPartyCookieAccess block the unpartitioned cookies in the third-party contexts, which the Storage Access API (Document.RequestStorageAccess) can then unblock.

The names and the values of the cookies are byte sequences, represented as strings whose characters are the bytes (isomorphic strings, as the values of the HTTP headers): a script stores the UTF-8 bytes of its strings. The expiry times are measured by the clock given to the constructor (e.g. BrowsingContextOptions.TimeProvider). The jar is thread-safe: it can be shared by several browsing contexts.

The cookies are kept in memory, and the persistent cookies (the cookies with an expiry time) are persisted by the CookiePersistence given to the constructor, if any.

Constructors

NameDescription
CookieJar()Creates an empty cookie jar, whose expiry times are measured by the system clock.
CookieJar(CookiePersistence?, TimeProvider?)Creates a cookie jar whose persistent cookies are persisted: the jar contains the cookies of CookiePersistence.LoadCookies that are not expired, and reports its changes to the persistence.
CookieJar(TimeProvider?)Creates an empty cookie jar.

CookieJar overloads

CookieJar()

CookieJar.cs

Creates an empty cookie jar, whose expiry times are measured by the system clock.

public CookieJar()

CookieJar(CookiePersistence?, TimeProvider?)

CookieJar.cs

Creates a cookie jar whose persistent cookies are persisted: the jar contains the cookies of CookiePersistence.LoadCookies that are not expired, and reports its changes to the persistence.

public CookieJar(CookiePersistence? persistence, TimeProvider? timeProvider)
Parameters
persistence CookiePersistence?
The persistent storage of the cookies, or null to keep them in memory only.
timeProvider TimeProvider?
The clock that measures the creation and expiry times of the cookies, or null for TimeProvider.System.

CookieJar(TimeProvider?)

CookieJar.cs

Creates an empty cookie jar.

public CookieJar(TimeProvider? timeProvider)
Parameters
timeProvider TimeProvider?
The clock that measures the creation and expiry times of the cookies, or null for TimeProvider.System.

Properties

NameDescription
BlockThirdPartyCookiesGets or sets whether the unpartitioned cookies are blocked in the third-party contexts (third-party cookie blocking): the documents and the requests whose site is not the site of their top-level document, or that have a cross-site ancestor, neither send nor store the cookies without the Partitioned attribute, unless they have storage access (https://privacycg.github.io/storage-access/, see Document.RequestStorageAccess). The rules of CookieJar.SetThirdPartyCookieAccess take precedence. The default value is false: as in the browsers that do not block the third-party cookies, the unpartitioned cookies are available in every context, so every document has storage access (Document.HasStorageAccess), and the cross-site requests have the active storage access status (the Sec-Fetch-Storage-Access header).
OriginBoundGets whether the cookies are bound to the origin that set them (origin-bound cookies, https://github.com/explainers-by-googlers/origin-bound-cookies): a cookie is only sent to the URLs of the scheme that set it (secure or not), a cookie without Domain attribute only to the URLs of the port that set it, and the cookies of the same name set by another scheme or another port do not replace each other. The default value is false: as in the browsers that do not enable origin-bound cookies, the cookies of a host are shared by its schemes and ports.
PersistenceGets the persistent storage of the cookies, or null when they are kept in memory only.

BlockThirdPartyCookies

CookieJar.cs

Gets or sets whether the unpartitioned cookies are blocked in the third-party contexts (third-party cookie blocking): the documents and the requests whose site is not the site of their top-level document, or that have a cross-site ancestor, neither send nor store the cookies without the Partitioned attribute, unless they have storage access (https://privacycg.github.io/storage-access/, see Document.RequestStorageAccess). The rules of CookieJar.SetThirdPartyCookieAccess take precedence. The default value is false: as in the browsers that do not block the third-party cookies, the unpartitioned cookies are available in every context, so every document has storage access (Document.HasStorageAccess), and the cross-site requests have the active storage access status (the Sec-Fetch-Storage-Access header).

public bool BlockThirdPartyCookies { get; set; }

Property value

bool

OriginBound

CookieJar.cs

Gets whether the cookies are bound to the origin that set them (origin-bound cookies, https://github.com/explainers-by-googlers/origin-bound-cookies): a cookie is only sent to the URLs of the scheme that set it (secure or not), a cookie without Domain attribute only to the URLs of the port that set it, and the cookies of the same name set by another scheme or another port do not replace each other. The default value is false: as in the browsers that do not enable origin-bound cookies, the cookies of a host are shared by its schemes and ports.

public bool OriginBound { get; init; }

Property value

bool

Persistence

CookieJar.cs

Gets the persistent storage of the cookies, or null when they are kept in memory only.

public CookiePersistence? Persistence { get; }

Property value

CookiePersistence?

Methods

NameDescription
Clear()Removes all the cookies, and the persisted cookies of CookieJar.Persistence.
GetCookies()Returns the cookies of the jar that are not expired, in the order of their creation.
GetCookies(string)Returns the cookies that would be sent to url by a request that is same-site with it, including the HttpOnly cookies (the associated cookies of WebDriver, https://w3c.github.io/webdriver/#dfn-associated-cookies), in the order of the Cookie header. The partitioned cookies are the ones of the site of the URL.
Remove(StoredCookie)Removes a cookie (with the same name, domain, path, partition and origin binding). Returns false when the jar does not contain it.
SetCookie(string, string)Stores the cookie of a Set-Cookie header received from url in a response to a same-site request (e.g. to restore cookies). Returns false when the cookie is ignored (an invalid cookie, or a cookie that the URL cannot set).
SetThirdPartyCookieAccess(string?, string?, bool)Blocks or allows the unpartitioned cookies of a site in the third-party contexts of a top-level site (the settings of the user, and the Set Storage Access command of WebDriver, https://privacycg.github.io/storage-access/#set-storage-access-command). The rules override CookieJar.BlockThirdPartyCookies. The documents of a site whose cookies are allowed have storage access (Document.HasStorageAccess); the documents of a site whose cookies are blocked can request it (Document.RequestStorageAccess).

Removes all the cookies, and the persisted cookies of CookieJar.Persistence.

public void Clear()

GetCookies overloads

GetCookies()

CookieJar.cs

Returns the cookies of the jar that are not expired, in the order of their creation.

public IReadOnlyList<StoredCookie> GetCookies()

GetCookies(string)

CookieJar.cs

Returns the cookies that would be sent to url by a request that is same-site with it, including the HttpOnly cookies (the associated cookies of WebDriver, https://w3c.github.io/webdriver/#dfn-associated-cookies), in the order of the Cookie header. The partitioned cookies are the ones of the site of the URL.

public IReadOnlyList<StoredCookie> GetCookies(string url)
Parameters
url string
An absolute URL.
Returns

IReadOnlyList<StoredCookie>

Remove(StoredCookie)

CookieJar.cs

Removes a cookie (with the same name, domain, path, partition and origin binding). Returns false when the jar does not contain it.

public bool Remove(StoredCookie cookie)

Parameters

cookie StoredCookie

Returns

bool

SetCookie(string, string)

CookieJar.cs

Stores the cookie of a Set-Cookie header received from url in a response to a same-site request (e.g. to restore cookies). Returns false when the cookie is ignored (an invalid cookie, or a cookie that the URL cannot set).

public bool SetCookie(string url, string setCookieHeader)

Parameters

url string
The absolute URL of the response.
setCookieHeader string
The value of the Set-Cookie header (an isomorphic string: each character is a byte).

Returns

bool

SetThirdPartyCookieAccess(string?, string?, bool)

CookieJar.cs

Blocks or allows the unpartitioned cookies of a site in the third-party contexts of a top-level site (the settings of the user, and the Set Storage Access command of WebDriver, https://privacycg.github.io/storage-access/#set-storage-access-command). The rules override CookieJar.BlockThirdPartyCookies. The documents of a site whose cookies are allowed have storage access (Document.HasStorageAccess); the documents of a site whose cookies are blocked can request it (Document.RequestStorageAccess).

public void SetThirdPartyCookieAccess(string? topLevelUrl, string? embeddedUrl, bool blocked)

Parameters

topLevelUrl string?
A URL of the top-level site (e.g. https://example.com/), or null for every top-level site.
embeddedUrl string?
A URL of the embedded site, or null for every site.
blocked bool
Whether the unpartitioned cookies are blocked.

Remarks

The rule of a specific pair of sites takes precedence over the rule of every embedded site, which takes precedence over the rules of every top-level site. A rule for every embedded site removes the rules of the specific embedded sites of its top-level sites.