Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 679 Commits
.github		.github
api		api
lib		lib
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
api-extractor.json		api-extractor.json
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
validate-generated-files.sh		validate-generated-files.sh
version-template.ejs		version-template.ejs

Repository files navigation

Tough Cookie ·

A Node.js implementation ofRFC6265 for cookie parsing, storage, and retrieval.

Getting Started

Install Tough Cookie usingnpm:

npm install tough-cookie

oryarn:

yarn add tough-cookie

Usage

import{Cookie,CookieJar}from'tough-cookie'// parse a `Cookie` request headerconstreqCookies='ID=298zf09hf012fh2; csrf=u32t4o3tb3gg43; _gat=1'.split(';').map(Cookie.parse)// generate a `Cookie` request headerconstcookieHeader=reqCookies.map((cookie)=>cookie.cookieString()).join(';')// parse a Set-Cookie response headerconstresCookie=Cookie.parse('foo=bar; Domain=example.com; Path=/; Expires=Tue, 21 Oct 2025 00:00:00 GMT',)// generate a Set-Cookie response headerconstsetCookieHeader=cookie.toString()// store and retrieve cookiesconstcookieJar=newCookieJar()// uses the in-memory store by defaultawaitcookieJar.setCookie(resCookie,'https://example.com/')constmatchingCookies=awaitcookieJar.getCookies('https://example.com/')

Important

For more detailed usage information, refer to theAPI docs.

RFC6265bis

Support forRFC6265bis is being developed. As these revisions toRFC6252 arestill inActive Internet-Draft state, the areas of support that follow are subject to change.

SameSite Cookies

This change makes it possible for servers, and supporting clients, to mitigate certain types of CSRFattacks by disallowingSameSite cookies from being sent cross-origin.

Example

import{CookieJar}from'tough-cookie'constcookieJar=newCookieJar()// uses the in-memory store by default// storing cookies with various SameSite attributesawaitcookieJar.setCookie('strict=authorized; SameSite=strict','http://example.com/index.html',)awaitcookieJar.setCookie('lax=okay; SameSite=lax','http://example.com/index.html',)awaitcookieJar.setCookie('normal=whatever','http://example.com/index.html')// retrieving cookies using a SameSite contextconstlaxCookies=awaitcookieJar.getCookies('http://example.com/index.html',{// the first cookie (strict=authorized) will not be returned if the context is 'lax'// but the other two cookies will be returnedsameSiteContext:'lax',})

Note

It is highly recommended that you readRFC6265bis - Section 8.8 for more details on SameSite cookies, security considerations, and defense in depth.

Cookie Prefixes

Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply byinspecting the first few characters of the cookie's name.

Two prefixes are defined:

"__Secure-"
If a cookie's name begins with a case-sensitive match for the string__Secure-, then the cookie was set with a "Secure" attribute.
"__Host-"
If a cookie's name begins with a case-sensitive match for the string__Host-, then the cookie was set with a "Secure" attribute, a "Path" attribute with a value of "/", and no "Domain" attribute.

IfprefixSecurity is enabled forCookieJar, then cookies that match the prefixes defined above but donot obey the attribute restrictions are not added.

You can define this functionality by passing in theprefixSecurity option toCookieJar. It can be one of 3 values:

silent: (default) Enable cookie prefix checking but silently fail to add the cookie if conditions are not met.
strict: Enable cookie prefix checking and error out if conditions are not met.
unsafe-disabled: Disable cookie prefix checking.

IfignoreError is passed in astrue when setting a cookie then the error is silent regardless of theprefixSecurity option (assuming it's enabled).

Example

import{CookieJar,MemoryCookieStore}from'tough-cookie'constcookieJar=newCookieJar(newMemoryCookieStore(),{prefixSecurity:'silent',})// this cookie will be silently ignored since the url is insecure (http)awaitcookieJar.setCookie('__Secure-SID=12345; Domain=example.com; Secure;','http://example.com',)// this cookie will be stored since the url is secure (https)awaitcookieJar.setCookie('__Secure-SID=12345; Domain=example.com; Secure;','https://example.com',)

Note

It is highly recommended that you readRFC6265bis - Section 4.1.3 for more details on Cookie Prefixes.

Node.js Version Support

We follow theNode.js release schedule and supportall versions that are in Active LTS or Maintenance. We will always do a major release when dropping supportfor older versions of node, and we will do so in consultation with our community.