tough-cookie 5.0.0-rc.4 → 5.0.0

package/dist/cookie/canonicalDomain.d.ts

@@ -0,0 +1,33 @@
+import type { Nullable } from '../utils';
+/**
+ * Transforms a domain name into a canonical domain name. The canonical domain name is a domain name
+ * that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded
+ * ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.2 | Section 5.1.2 of RFC 6265}). For
+ * the most part, this function is idempotent (calling the function with the output from a previous call
+ * returns the same output).
+ *
+ * @remarks
+ * A canonicalized host name is the string generated by the following
+ * algorithm:
+ *
+ * 1.  Convert the host name to a sequence of individual domain name
+ *     labels.
+ *
+ * 2.  Convert each label that is not a Non-Reserved LDH (NR-LDH) label,
+ *     to an A-label (see Section 2.3.2.1 of [RFC5890] for the former
+ *     and latter), or to a "punycode label" (a label resulting from the
+ *     "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate
+ *     (see Section 6.3 of this specification).
+ *
+ * 3.  Concatenate the resulting labels, separated by a %x2E (".")
+ *     character.
+ *
+ * @example
+ * ```
+ * canonicalDomain('.EXAMPLE.com') === 'example.com'
+ * ```
+ *
+ * @param domainName - the domain name to generate the canonical domain from
+ * @public
+ */
+export declare function canonicalDomain(domainName: Nullable<string>): string | undefined;

package/dist/cookie/canonicalDomain.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalDomain = canonicalDomain;
 const constants_1 = require("./constants");
+const node_url_1 = require("node:url");
 /**
  * Transforms a domain name into a canonical domain name. The canonical domain name is a domain name
  * that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded
@@ -45,12 +46,12 @@ function canonicalDomain(domainName) {
         if (!str.endsWith(']')) {
             str = str + ']';
         }
-        return new URL(`http://${str}`).hostname.slice(1, -1); // remove [ and ]
+        return (0, node_url_1.domainToASCII)(str).slice(1, -1); // remove [ and ]
     }
     // convert to IDN if any non-ASCII characters
     // eslint-disable-next-line no-control-regex
     if (/[^\u0001-\u007f]/.test(str)) {
-        return new URL(`http://${str}`).hostname;
+        return (0, node_url_1.domainToASCII)(str);
     }
     // ASCII-only domain - not canonicalized with new URL() because it may be a malformed URL
     return str.toLowerCase();

package/dist/cookie/constants.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by inspecting the
+ * first few characters of the cookie's name. These are defined in {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3 | RFC6265bis - Section 4.1.3}.
+ *
+ * The following values can be used to configure how a {@link CookieJar} enforces attribute restrictions for Cookie prefixes:
+ *
+ * - `silent` - Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a {@link CookieJar}.
+ *
+ * - `strict` - Enables cookie prefix checking and will raise an error if conditions are not met.
+ *
+ * - `unsafe-disabled` - Disables cookie prefix checking.
+ * @public
+ */
+export declare const PrefixSecurityEnum: Readonly<{
+    SILENT: "silent";
+    STRICT: "strict";
+    DISABLED: "unsafe-disabled";
+}>;
+export declare const IP_V6_REGEX_OBJECT: RegExp;
+/**
+ * A JSON representation of a {@link CookieJar}.
+ * @public
+ */
+export interface SerializedCookieJar {
+    /**
+     * The version of `tough-cookie` used during serialization.
+     */
+    version: string;
+    /**
+     * The name of the store used during serialization.
+     */
+    storeType: string | null;
+    /**
+     * The value of {@link CreateCookieJarOptions.rejectPublicSuffixes} configured on the {@link CookieJar}.
+     */
+    rejectPublicSuffixes: boolean;
+    /**
+     * Other configuration settings on the {@link CookieJar}.
+     */
+    [key: string]: unknown;
+    /**
+     * The list of {@link Cookie} values serialized as JSON objects.
+     */
+    cookies: SerializedCookie[];
+}
+/**
+ * A JSON object that is created when {@link Cookie.toJSON} is called. This object will contain the properties defined in {@link Cookie.serializableProperties}.
+ * @public
+ */
+export type SerializedCookie = {
+    key?: string;
+    value?: string;
+    [key: string]: unknown;
+};

package/dist/cookie/cookie.d.ts

@@ -0,0 +1,315 @@
+import type { SerializedCookie } from './constants';
+/**
+ * Optional configuration to be used when parsing cookies.
+ * @public
+ */
+export interface ParseCookieOptions {
+    /**
+     * If `true` then keyless cookies like `=abc` and `=` which are not RFC-compliant will be parsed.
+     */
+    loose?: boolean | undefined;
+}
+/**
+ * Configurable values that can be set when creating a {@link Cookie}.
+ * @public
+ */
+export interface CreateCookieOptions {
+    /** {@inheritDoc Cookie.key} */
+    key?: string;
+    /** {@inheritDoc Cookie.value} */
+    value?: string;
+    /** {@inheritDoc Cookie.expires} */
+    expires?: Date | 'Infinity' | null;
+    /** {@inheritDoc Cookie.maxAge} */
+    maxAge?: number | 'Infinity' | '-Infinity' | null;
+    /** {@inheritDoc Cookie.domain} */
+    domain?: string | null;
+    /** {@inheritDoc Cookie.path} */
+    path?: string | null;
+    /** {@inheritDoc Cookie.secure} */
+    secure?: boolean;
+    /** {@inheritDoc Cookie.httpOnly} */
+    httpOnly?: boolean;
+    /** {@inheritDoc Cookie.extensions} */
+    extensions?: string[] | null;
+    /** {@inheritDoc Cookie.creation} */
+    creation?: Date | 'Infinity' | null;
+    /** {@inheritDoc Cookie.hostOnly} */
+    hostOnly?: boolean | null;
+    /** {@inheritDoc Cookie.pathIsDefault} */
+    pathIsDefault?: boolean | null;
+    /** {@inheritDoc Cookie.lastAccessed} */
+    lastAccessed?: Date | 'Infinity' | null;
+    /** {@inheritDoc Cookie.sameSite} */
+    sameSite?: string | undefined;
+}
+/**
+ * An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to a user's web browser.
+ * It is defined in {@link https://www.rfc-editor.org/rfc/rfc6265.html | RFC6265}.
+ * @public
+ */
+export declare class Cookie {
+    /**
+     * The name or key of the cookie
+     */
+    key: string;
+    /**
+     * The value of the cookie
+     */
+    value: string;
+    /**
+     * The 'Expires' attribute of the cookie
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1 | RFC6265 Section 5.2.1}).
+     */
+    expires: Date | 'Infinity' | null;
+    /**
+     * The 'Max-Age' attribute of the cookie
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2 | RFC6265 Section 5.2.2}).
+     */
+    maxAge: number | 'Infinity' | '-Infinity' | null;
+    /**
+     * The 'Domain' attribute of the cookie represents the domain the cookie belongs to
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3 | RFC6265 Section 5.2.3}).
+     */
+    domain: string | null;
+    /**
+     * The 'Path' attribute of the cookie represents the path of the cookie
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4 | RFC6265 Section 5.2.4}).
+     */
+    path: string | null;
+    /**
+     * The 'Secure' flag of the cookie indicates if the scope of the cookie is
+     * limited to secure channels (e.g.; HTTPS) or not
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5 | RFC6265 Section 5.2.5}).
+     */
+    secure: boolean;
+    /**
+     * The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to
+     * client scripts or not
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6 | RFC6265 Section 5.2.6}).
+     */
+    httpOnly: boolean;
+    /**
+     * Contains attributes which are not part of the defined spec but match the `extension-av` syntax
+     * defined in Section 4.1.1 of RFC6265
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1 | RFC6265 Section 4.1.1}).
+     */
+    extensions: string[] | null;
+    /**
+     * Set to the date and time when a Cookie is initially stored or a matching cookie is
+     * received that replaces an existing cookie
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}).
+     *
+     * Also used to maintain ordering among cookies. Among cookies that have equal-length path fields,
+     * cookies with earlier creation-times are listed before cookies with later creation-times
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 Section 5.4}).
+     */
+    creation: Date | 'Infinity' | null;
+    /**
+     * A global counter used to break ordering ties between two cookies that have equal-length path fields
+     * and the same creation-time.
+     */
+    creationIndex: number;
+    /**
+     * A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly
+     * matches the domain of the cookie) or not
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}).
+     */
+    hostOnly: boolean | null;
+    /**
+     * A boolean flag indicating if a cookie had no 'Path' attribute and the default path
+     * was used
+     * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4 | RFC6265 Section 5.2.4}).
+     */
+    pathIsDefault: boolean | null;
+    /**
+     * Set to the date and time when a cookie was initially stored ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}) and updated whenever
+     * the cookie is retrieved from the {@link CookieJar} ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 Section 5.4}).
+     */
+    lastAccessed: Date | 'Infinity' | null;
+    /**
+     * The 'SameSite' attribute of a cookie as defined in RFC6265bis
+     * (See {@link https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2 | RFC6265bis (v13) Section 5.2 }).
+     */
+    sameSite: string | undefined;
+    /**
+     * Create a new Cookie instance.
+     * @public
+     * @param options - The attributes to set on the cookie
+     */
+    constructor(options?: CreateCookieOptions);
+    /**
+     * For convenience in using `JSON.stringify(cookie)`. Returns a plain-old Object that can be JSON-serialized.
+     *
+     * @remarks
+     * - Any `Date` properties (such as {@link Cookie.expires}, {@link Cookie.creation}, and {@link Cookie.lastAccessed}) are exported in ISO format (`Date.toISOString()`).
+     *
+     *  - Custom Cookie properties are discarded. In tough-cookie 1.x, since there was no {@link Cookie.toJSON} method explicitly defined, all enumerable properties were captured.
+     *      If you want a property to be serialized, add the property name to {@link Cookie.serializableProperties}.
+     */
+    toJSON(): SerializedCookie;
+    /**
+     * Does a deep clone of this cookie, implemented exactly as `Cookie.fromJSON(cookie.toJSON())`.
+     * @public
+     */
+    clone(): Cookie | undefined;
+    /**
+     * Validates cookie attributes for semantic correctness. Useful for "lint" checking any `Set-Cookie` headers you generate.
+     * For now, it returns a boolean, but eventually could return a reason string.
+     *
+     * @remarks
+     * Works for a few things, but is by no means comprehensive.
+     *
+     * @beta
+     */
+    validate(): boolean;
+    /**
+     * Sets the 'Expires' attribute on a cookie.
+     *
+     * @remarks
+     * When given a `string` value it will be parsed with {@link parseDate}. If the value can't be parsed as a cookie date
+     * then the 'Expires' attribute will be set to `"Infinity"`.
+     *
+     * @param exp - the new value for the 'Expires' attribute of the cookie.
+     */
+    setExpires(exp: string | Date): void;
+    /**
+     * Sets the 'Max-Age' attribute (in seconds) on a cookie.
+     *
+     * @remarks
+     * Coerces `-Infinity` to `"-Infinity"` and `Infinity` to `"Infinity"` so it can be serialized to JSON.
+     *
+     * @param age - the new value for the 'Max-Age' attribute (in seconds).
+     */
+    setMaxAge(age: number): void;
+    /**
+     * Encodes to a `Cookie` header value (specifically, the {@link Cookie.key} and {@link Cookie.value} properties joined with "=").
+     * @public
+     */
+    cookieString(): string;
+    /**
+     * Encodes to a `Set-Cookie header` value.
+     * @public
+     */
+    toString(): string;
+    /**
+     * Computes the TTL relative to now (milliseconds).
+     *
+     * @remarks
+     * - `Infinity` is returned for cookies without an explicit expiry
+     *
+     * - `0` is returned if the cookie is expired.
+     *
+     * - Otherwise a time-to-live in milliseconds is returned.
+     *
+     * @param now - passing an explicit value is mostly used for testing purposes since this defaults to the `Date.now()`
+     * @public
+     */
+    TTL(now?: number): number;
+    /**
+     * Computes the absolute unix-epoch milliseconds that this cookie expires.
+     *
+     * The "Max-Age" attribute takes precedence over "Expires" (as per the RFC). The {@link Cookie.lastAccessed} attribute
+     * (or the `now` parameter if given) is used to offset the {@link Cookie.maxAge} attribute.
+     *
+     * If Expires ({@link Cookie.expires}) is set, that's returned.
+     *
+     * @param now - can be used to provide a time offset (instead of {@link Cookie.lastAccessed}) to use when calculating the "Max-Age" value
+     */
+    expiryTime(now?: Date): number | undefined;
+    /**
+     * Indicates if the cookie has been persisted to a store or not.
+     * @public
+     */
+    isPersistent(): boolean;
+    /**
+     * Calls {@link canonicalDomain} with the {@link Cookie.domain} property.
+     * @public
+     */
+    canonicalizedDomain(): string | undefined;
+    /**
+     * Alias for {@link Cookie.canonicalizedDomain}
+     * @public
+     */
+    cdomain(): string | undefined;
+    /**
+     * Parses a string into a Cookie object.
+     *
+     * @remarks
+     * Note: when parsing a `Cookie` header it must be split by ';' before each Cookie string can be parsed.
+     *
+     * @example
+     * ```
+     * // parse a `Set-Cookie` header
+     * const setCookieHeader = 'a=bcd; Expires=Tue, 18 Oct 2011 07:05:03 GMT'
+     * const cookie = Cookie.parse(setCookieHeader)
+     * cookie.key === 'a'
+     * cookie.value === 'bcd'
+     * cookie.expires === new Date(Date.parse('Tue, 18 Oct 2011 07:05:03 GMT'))
+     * ```
+     *
+     * @example
+     * ```
+     * // parse a `Cookie` header
+     * const cookieHeader = 'name=value; name2=value2; name3=value3'
+     * const cookies = cookieHeader.split(';').map(Cookie.parse)
+     * cookies[0].name === 'name'
+     * cookies[0].value === 'value'
+     * cookies[1].name === 'name2'
+     * cookies[1].value === 'value2'
+     * cookies[2].name === 'name3'
+     * cookies[2].value === 'value3'
+     * ```
+     *
+     * @param str - The `Set-Cookie` header or a Cookie string to parse.
+     * @param options - Configures `strict` or `loose` mode for cookie parsing
+     */
+    static parse(str: string, options?: ParseCookieOptions): Cookie | undefined;
+    /**
+     * Does the reverse of {@link Cookie.toJSON}.
+     *
+     * @remarks
+     * Any Date properties (such as .expires, .creation, and .lastAccessed) are parsed via Date.parse, not tough-cookie's parseDate, since ISO timestamps are being handled at this layer.
+     *
+     * @example
+     * ```
+     * const json = JSON.stringify({
+     *   key: 'alpha',
+     *   value: 'beta',
+     *   domain: 'example.com',
+     *   path: '/foo',
+     *   expires: '2038-01-19T03:14:07.000Z',
+     * })
+     * const cookie = Cookie.fromJSON(json)
+     * cookie.key === 'alpha'
+     * cookie.value === 'beta'
+     * cookie.domain === 'example.com'
+     * cookie.path === '/foo'
+     * cookie.expires === new Date(Date.parse('2038-01-19T03:14:07.000Z'))
+     * ```
+     *
+     * @param str - An unparsed JSON string or a value that has already been parsed as JSON
+     */
+    static fromJSON(str: unknown): Cookie | undefined;
+    private static cookiesCreated;
+    /**
+     * @internal
+     */
+    static sameSiteLevel: {
+        readonly strict: 3;
+        readonly lax: 2;
+        readonly none: 1;
+    };
+    /**
+     * @internal
+     */
+    static sameSiteCanonical: {
+        readonly strict: "Strict";
+        readonly lax: "Lax";
+    };
+    /**
+     * Cookie properties that will be serialized when using {@link Cookie.fromJSON} and {@link Cookie.toJSON}.
+     * @public
+     */
+    static serializableProperties: readonly ["key", "value", "expires", "maxAge", "domain", "path", "secure", "httpOnly", "extensions", "hostOnly", "pathIsDefault", "creation", "lastAccessed", "sameSite"];
+}

package/dist/cookie/cookie.js

@@ -90,7 +90,7 @@ function parseCookiePair(cookiePair, looseMode) {
     if (looseMode) {
         if (firstEq === 0) {
             // '=' is immediately at start
-            cookiePair = cookiePair.substr(1);
+            cookiePair = cookiePair.substring(1);
             firstEq = cookiePair.indexOf('='); // might still need to split on '='
         }
     }
@@ -267,7 +267,7 @@ function fromJSON(str) {
         try {
             obj = JSON.parse(str);
         }
-        catch (e) {
+        catch {
             return undefined;
         }
     }

package/dist/cookie/cookieCompare.d.ts

@@ -0,0 +1,58 @@
+import type { Cookie } from './cookie';
+/**
+ * A comparison function that can be used with {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | Array.sort()},
+ * which orders a list of cookies into the recommended order given in Step 2 of {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 - Section 5.4}.
+ *
+ * The sort algorithm is, in order of precedence:
+ *
+ * - Longest {@link Cookie.path}
+ *
+ * - Oldest {@link Cookie.creation} (which has a 1-ms precision, same as Date)
+ *
+ * - Lowest {@link Cookie.creationIndex} (to get beyond the 1-ms precision)
+ *
+ * @remarks
+ * ### RFC6265 - Section 5.4 - Step 2
+ *
+ * The user agent SHOULD sort the cookie-list in the following order:
+ *
+ * - Cookies with longer paths are listed before cookies with shorter paths.
+ *
+ * - Among cookies that have equal-length path fields, cookies with
+ *    earlier creation-times are listed before cookies with later
+ *    creation-times.
+ *
+ * NOTE: Not all user agents sort the cookie-list in this order, but
+ * this order reflects common practice when this document was
+ * written, and, historically, there have been servers that
+ * (erroneously) depended on this order.
+ *
+ * ### Custom Store Implementors
+ *
+ * Since the JavaScript Date is limited to a 1-ms precision, cookies within the same millisecond are entirely possible.
+ * This is especially true when using the `now` option to `CookieJar.setCookie(...)`. The {@link Cookie.creationIndex}
+ * property is a per-process global counter, assigned during construction with `new Cookie()`, which preserves the spirit
+ * of the RFC sorting: older cookies go first. This works great for {@link MemoryCookieStore} since `Set-Cookie` headers
+ * are parsed in order, but is not so great for distributed systems.
+ *
+ * Sophisticated Stores may wish to set this to some other
+ * logical clock so that if cookies `A` and `B` are created in the same millisecond, but cookie `A` is created before
+ * cookie `B`, then `A.creationIndex < B.creationIndex`.
+ *
+ * @example
+ * ```
+ * const cookies = [
+ *   new Cookie({ key: 'a', value: '' }),
+ *   new Cookie({ key: 'b', value: '' }),
+ *   new Cookie({ key: 'c', value: '', path: '/path' }),
+ *   new Cookie({ key: 'd', value: '', path: '/path' }),
+ * ]
+ * cookies.sort(cookieCompare)
+ * // cookie sort order would be ['c', 'd', 'a', 'b']
+ * ```
+ *
+ * @param a - the first Cookie for comparison
+ * @param b - the second Cookie for comparison
+ * @public
+ */
+export declare function cookieCompare(a: Cookie, b: Cookie): number;