tough-cookie

tough-cookie is the reference implementation of the HTTP cookie specification (RFC 6265, with legacy RFC 2965 support) for JavaScript. It parses Set-Cookie headers, enforces domain and path matching rules, expiration and max-age handling, and cookie-ordering semantics, then stores them in a pluggable CookieJar so HTTP clients can round-trip cookies correctly across requests.

It underpins cookie handling in Node’s most widely used HTTP client libraries (request, axios’s cookie-jar-support ecosystem, and many scraping/testing tools) and is a transitive dependency of a huge share of the npm ecosystem. Public suffix matching is delegated to tldts so domain-boundary cookie rules stay correct as the public suffix list evolves.

What You Get

• RFC 6265-compliant Cookie.parse() for Set-Cookie header strings, including legacy RFC 2965 compatibility
• CookieJar with domain-matching, path-matching, and expiration-aware cookie storage and retrieval
• Pluggable Store interface (with an in-memory MemoryCookieStore default) so cookies can be persisted to Redis, a database, or disk
• Correct public-suffix-aware domain matching via the tldts dependency, preventing cross-site cookie leakage on shared suffixes
• Serialization/deserialization of the entire jar to JSON for persisting sessions across process restarts

Common Use Cases

• Building an HTTP client or scraper that needs to persist and replay cookies correctly across multiple requests and redirects
• Implementing session-aware testing tools that must simulate a browser’s cookie jar behavior
• Writing a custom cookie store backend (Redis, SQL) by implementing the Store interface for multi-process or distributed session sharing
• Validating that a server’s Set-Cookie headers are RFC 6265-compliant during API or security testing

Under The Hood

Architecture The library separates parsing/validation logic from storage: lib/cookie/ holds the Cookie class (parsing, serialization, attribute validation) while lib/store.ts defines the abstract Store interface and lib/memstore.ts provides the default in-memory implementation; supporting modules (permuteDomain.ts, pathMatch.ts, domainMatch logic, getPublicSuffix.ts) implement the RFC 6265 matching algorithms as small, independently testable functions, and CookieJar composes all of these to expose the public get/set/remove API — a clean separation that lets consumers swap storage without touching parsing logic.

Tech Stack Written in TypeScript, built with tsup to dual-publish ESM and CJS (dist/index.js / dist/index.cjs) with generated .d.ts types, tested with Vitest, API-surface-checked with Microsoft’s api-extractor/api-documenter, and linted with the modern flat-config ESLint plus typescript-eslint; its only runtime dependency is tldts for public suffix list lookups, keeping the dependency footprint minimal for a package this widely depended-upon.

Code Quality The lib/__tests__/ directory contains over 20 dedicated spec files covering parsing, domain/path matching, cookie sorting, prefixes (__Secure-, __Host-), SameSite behavior, jar serialization, and even an explicit regression.spec.ts for previously-reported bugs — an unusually thorough test suite for a utility library, reflecting its role as security-sensitive infrastructure with a documented CVE history (prototype pollution, ReDoS) that has driven this test rigor.

API Design The Cookie.parse() / CookieJar.setCookie() / CookieJar.getCookies() surface is small and mirrors familiar cookie-jar mental models from browsers, and the Store interface is a clean extension point (three or four methods to implement) for custom backends; async/callback and promise-based APIs are both supported for CookieJar methods, easing migration from older callback-style Node code, though the coexistence of both calling conventions adds a small amount of surface area new users need to learn.