import { Store } from '../store'; import { Cookie } from './cookie'; import { Callback, ErrorCallback, Nullable } from '../utils'; import { SerializedCookieJar } from './constants'; /** * Configuration options used when calling `CookieJar.setCookie(...)` * @public */ export interface SetCookieOptions { /** * Controls if a cookie string should be parsed using `loose` mode or not. * See {@link Cookie.parse} and {@link ParseCookieOptions} for more details. * * Defaults to `false` if not provided. */ loose?: boolean | undefined; /** * Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon storage. * * - `'strict'` - If the request is on the same "site for cookies" (see the RFC draft * for more information), pass this option to add a layer of defense against CSRF. * * - `'lax'` - If the request is from another site, but is directly because of navigation * by the user, such as, `` or ``, then use `lax`. * * - `'none'` - This indicates a cross-origin request. * * - `undefined` - SameSite is not be enforced! This can be a valid use-case for when * CSRF isn't in the threat model of the system being built. * * Defaults to `undefined` if not provided. * * @remarks * - It is highly recommended that you read {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8 | RFC6265bis - Section 8.8} * which discusses security considerations and defence on SameSite cookies in depth. */ sameSiteContext?: 'strict' | 'lax' | 'none' | undefined; /** * Silently ignore things like parse errors and invalid domains. Store errors aren't ignored by this option. * * Defaults to `false` if not provided. */ ignoreError?: boolean | undefined; /** * Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. * * Defaults to `true` if not provided. */ http?: boolean | undefined; /** * Forces the cookie creation and access time of cookies to this value when stored. * * Defaults to `Date.now()` if not provided. */ now?: Date | undefined; } /** * Configuration options used when calling `CookieJar.getCookies(...)`. * @public */ export interface GetCookiesOptions { /** * Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. * * Defaults to `true` if not provided. */ http?: boolean | undefined; /** * Perform `expiry-time` checking of cookies and asynchronously remove expired * cookies from the store. * * @remarks * - Using `false` returns expired cookies and does not remove them from the * store which is potentially useful for replaying `Set-Cookie` headers. * * Defaults to `true` if not provided. */ expire?: boolean | undefined; /** * If `true`, do not scope cookies by path. If `false`, then RFC-compliant path scoping will be used. * * @remarks * - May not be supported by the underlying store (the default {@link MemoryCookieStore} supports it). * * Defaults to `false` if not provided. */ allPaths?: boolean | undefined; /** * Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon retrieval. * * - `'strict'` - If the request is on the same "site for cookies" (see the RFC draft * for more information), pass this option to add a layer of defense against CSRF. * * - `'lax'` - If the request is from another site, but is directly because of navigation * by the user, such as, `` or ``, then use `lax`. * * - `'none'` - This indicates a cross-origin request. * * - `undefined` - SameSite is not be enforced! This can be a valid use-case for when * CSRF isn't in the threat model of the system being built. * * Defaults to `undefined` if not provided. * * @remarks * - It is highly recommended that you read {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8 | RFC6265bis - Section 8.8} * which discusses security considerations and defence on SameSite cookies in depth. */ sameSiteContext?: 'none' | 'lax' | 'strict' | undefined; /** * Flag to indicate if the returned cookies should be sorted or not. * * Defaults to `undefined` if not provided. */ sort?: boolean | undefined; } /** * Configuration settings to be used with a {@link CookieJar}. * @public */ export interface CreateCookieJarOptions { /** * Reject cookies that match those defined in the {@link https://publicsuffix.org/ | Public Suffix List} (e.g.; domains like "com" and "co.uk"). * * Defaults to `true` if not specified. */ rejectPublicSuffixes?: boolean | undefined; /** * Accept malformed cookies like `bar` and `=bar`, which have an implied empty name but are not RFC-compliant. * * Defaults to `false` if not specified. */ looseMode?: boolean | undefined; /** * Controls how cookie prefixes are handled. See {@link PrefixSecurityEnum}. * * Defaults to `silent` if not specified. */ prefixSecurity?: 'strict' | 'silent' | 'unsafe-disabled' | undefined; /** * Accepts {@link https://datatracker.ietf.org/doc/html/rfc6761 | special-use domains } such as `local`. * This is not in the standard, but is used sometimes on the web and is accepted by most browsers. It is * also useful for testing purposes. * * Defaults to `true` if not specified. */ allowSpecialUseDomain?: boolean | undefined; } /** * A CookieJar is for storage and retrieval of {@link Cookie} objects as defined in * {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 - Section 5.3}. * * It also supports a pluggable persistence layer via {@link Store}. * @public */ export declare class CookieJar { private readonly rejectPublicSuffixes; private readonly enableLooseMode; private readonly allowSpecialUseDomain; /** * The configured {@link Store} for the {@link CookieJar}. */ readonly store: Store; /** * The configured {@link PrefixSecurityEnum} value for the {@link CookieJar}. */ readonly prefixSecurity: string; /** * Creates a new `CookieJar` instance. * * @remarks * - If a custom store is not passed to the constructor, an in-memory store ({@link MemoryCookieStore} will be created and used. * - If a boolean value is passed as the `options` parameter, this is equivalent to passing `{ rejectPublicSuffixes: }` * * @param store - a custom {@link Store} implementation (defaults to {@link MemoryCookieStore}) * @param options - configures how cookies are processed by the cookie jar */ constructor(store?: Nullable, options?: CreateCookieJarOptions | boolean); private callSync; /** * Attempt to set the {@link Cookie} in the {@link CookieJar}. * * @remarks * - If successfully persisted, the {@link Cookie} will have updated * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} * properties. * * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` * atttribute on the cookie string. The {@link Cookie.domain} property is set to the * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an * exact hostname match (not a {@link domainMatch} as per usual) * * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. * @param url - The domain to store the cookie with. * @param callback - A function to call after a cookie has been successfully stored. * @public */ setCookie(cookie: string | Cookie, url: string | URL, callback: Callback): void; /** * Attempt to set the {@link Cookie} in the {@link CookieJar}. * * @remarks * - If successfully persisted, the {@link Cookie} will have updated * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} * properties. * * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` * atttribute on the cookie string. The {@link Cookie.domain} property is set to the * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an * exact hostname match (not a {@link domainMatch} as per usual) * * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when storing the cookie. * @param callback - A function to call after a cookie has been successfully stored. * @public */ setCookie(cookie: string | Cookie, url: string | URL, options: SetCookieOptions, callback: Callback): void; /** * Attempt to set the {@link Cookie} in the {@link CookieJar}. * * @remarks * - If successfully persisted, the {@link Cookie} will have updated * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} * properties. * * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` * atttribute on the cookie string. The {@link Cookie.domain} property is set to the * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an * exact hostname match (not a {@link domainMatch} as per usual) * * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when storing the cookie. * @public */ setCookie(cookie: string | Cookie, url: string | URL, options?: SetCookieOptions): Promise; /** * @internal No doc because this is an overload that supports the implementation */ setCookie(cookie: string | Cookie, url: string | URL, options: SetCookieOptions | Callback, callback?: Callback): unknown; /** * Synchronously attempt to set the {@link Cookie} in the {@link CookieJar}. * * Note: Only works if the configured {@link Store} is also synchronous. * * @remarks * - If successfully persisted, the {@link Cookie} will have updated * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} * properties. * * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` * atttribute on the cookie string. The {@link Cookie.domain} property is set to the * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an * exact hostname match (not a {@link domainMatch} as per usual) * * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when storing the cookie. * @public */ setCookieSync(cookie: string | Cookie, url: string, options?: SetCookieOptions): Cookie | undefined; /** * Retrieve the list of cookies that can be sent in a Cookie header for the * current URL. * * @remarks * - The array of cookies returned will be sorted according to {@link cookieCompare}. * * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. * * @param url - The domain to store the cookie with. */ getCookies(url: string): Promise; /** * Retrieve the list of cookies that can be sent in a Cookie header for the * current URL. * * @remarks * - The array of cookies returned will be sorted according to {@link cookieCompare}. * * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. * * @param url - The domain to store the cookie with. * @param callback - A function to call after a cookie has been successfully retrieved. */ getCookies(url: string, callback: Callback): void; /** * Retrieve the list of cookies that can be sent in a Cookie header for the * current URL. * * @remarks * - The array of cookies returned will be sorted according to {@link cookieCompare}. * * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. * @param callback - A function to call after a cookie has been successfully retrieved. */ getCookies(url: string | URL, options: GetCookiesOptions | undefined, callback: Callback): void; /** * Retrieve the list of cookies that can be sent in a Cookie header for the * current URL. * * @remarks * - The array of cookies returned will be sorted according to {@link cookieCompare}. * * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getCookies(url: string | URL, options?: GetCookiesOptions | undefined): Promise; /** * @internal No doc because this is an overload that supports the implementation */ getCookies(url: string | URL, options: GetCookiesOptions | undefined | Callback, callback?: Callback): unknown; /** * Synchronously retrieve the list of cookies that can be sent in a Cookie header for the * current URL. * * Note: Only works if the configured Store is also synchronous. * * @remarks * - The array of cookies returned will be sorted according to {@link cookieCompare}. * * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getCookiesSync(url: string, options?: GetCookiesOptions): Cookie[]; /** * Accepts the same options as `.getCookies()` but returns a string suitable for a * `Cookie` header rather than an Array. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. * @param callback - A function to call after the `Cookie` header string has been created. */ getCookieString(url: string, options: GetCookiesOptions, callback: Callback): void; /** * Accepts the same options as `.getCookies()` but returns a string suitable for a * `Cookie` header rather than an Array. * * @param url - The domain to store the cookie with. * @param callback - A function to call after the `Cookie` header string has been created. */ getCookieString(url: string, callback: Callback): void; /** * Accepts the same options as `.getCookies()` but returns a string suitable for a * `Cookie` header rather than an Array. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getCookieString(url: string, options?: GetCookiesOptions): Promise; /** * @internal No doc because this is an overload that supports the implementation */ getCookieString(url: string, options: GetCookiesOptions | Callback, callback?: Callback): unknown; /** * Synchronous version of `.getCookieString()`. Accepts the same options as `.getCookies()` but returns a string suitable for a * `Cookie` header rather than an Array. * * Note: Only works if the configured Store is also synchronous. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getCookieStringSync(url: string, options?: GetCookiesOptions): string; /** * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options * as `.getCookies()`. * * @param url - The domain to store the cookie with. * @param callback - A function to call after the `Set-Cookie` header strings have been created. */ getSetCookieStrings(url: string, callback: Callback): void; /** * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options * as `.getCookies()`. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. * @param callback - A function to call after the `Set-Cookie` header strings have been created. */ getSetCookieStrings(url: string, options: GetCookiesOptions, callback: Callback): void; /** * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options * as `.getCookies()`. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getSetCookieStrings(url: string, options?: GetCookiesOptions): Promise; /** * @internal No doc because this is an overload that supports the implementation */ getSetCookieStrings(url: string, options: GetCookiesOptions, callback?: Callback): unknown; /** * Synchronous version of `.getSetCookieStrings()`. Returns an array of strings suitable for `Set-Cookie` headers. * Accepts the same options as `.getCookies()`. * * Note: Only works if the configured Store is also synchronous. * * @param url - The domain to store the cookie with. * @param options - Configuration settings to use when retrieving the cookies. */ getSetCookieStringsSync(url: string, options?: GetCookiesOptions): string[]; /** * Serialize the CookieJar if the underlying store supports `.getAllCookies`. * @param callback - A function to call after the CookieJar has been serialized */ serialize(callback: Callback): void; /** * Serialize the CookieJar if the underlying store supports `.getAllCookies`. */ serialize(): Promise; /** * Serialize the CookieJar if the underlying store supports `.getAllCookies`. * * Note: Only works if the configured Store is also synchronous. */ serializeSync(): SerializedCookieJar | undefined; /** * Alias of {@link CookieJar.serializeSync}. Allows the cookie to be serialized * with `JSON.stringify(cookieJar)`. */ toJSON(): SerializedCookieJar | undefined; /** * Use the class method CookieJar.deserialize instead of calling this directly * @internal */ _importCookies(serialized: unknown, callback: Callback): void; /** * @internal */ _importCookiesSync(serialized: unknown): void; /** * Produces a deep clone of this CookieJar. Modifications to the original do * not affect the clone, and vice versa. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - Transferring between store types is supported so long as the source * implements `.getAllCookies()` and the destination implements `.putCookie()`. * * @param callback - A function to call when the CookieJar is cloned. */ clone(callback: Callback): void; /** * Produces a deep clone of this CookieJar. Modifications to the original do * not affect the clone, and vice versa. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - Transferring between store types is supported so long as the source * implements `.getAllCookies()` and the destination implements `.putCookie()`. * * @param newStore - The target {@link Store} to clone cookies into. * @param callback - A function to call when the CookieJar is cloned. */ clone(newStore: Store, callback: Callback): void; /** * Produces a deep clone of this CookieJar. Modifications to the original do * not affect the clone, and vice versa. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - Transferring between store types is supported so long as the source * implements `.getAllCookies()` and the destination implements `.putCookie()`. * * @param newStore - The target {@link Store} to clone cookies into. */ clone(newStore?: Store): Promise; /** * @internal */ _cloneSync(newStore?: Store): CookieJar | undefined; /** * Produces a deep clone of this CookieJar. Modifications to the original do * not affect the clone, and vice versa. * * Note: Only works if both the configured Store and destination * Store are synchronous. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - Transferring between store types is supported so long as the source * implements `.getAllCookies()` and the destination implements `.putCookie()`. * * @param newStore - The target {@link Store} to clone cookies into. */ cloneSync(newStore?: Store): CookieJar | undefined; /** * Removes all cookies from the CookieJar. * * @remarks * - This is a new backwards-compatible feature of tough-cookie version 2.5, * so not all Stores will implement it efficiently. For Stores that do not * implement `removeAllCookies`, the fallback is to call `removeCookie` after * `getAllCookies`. * * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. * * - If one or more of the `removeCookie` calls fail, only the first error is returned. * * @param callback - A function to call when all the cookies have been removed. */ removeAllCookies(callback: ErrorCallback): void; /** * Removes all cookies from the CookieJar. * * @remarks * - This is a new backwards-compatible feature of tough-cookie version 2.5, * so not all Stores will implement it efficiently. For Stores that do not * implement `removeAllCookies`, the fallback is to call `removeCookie` after * `getAllCookies`. * * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. * * - If one or more of the `removeCookie` calls fail, only the first error is returned. */ removeAllCookies(): Promise; /** * Removes all cookies from the CookieJar. * * Note: Only works if the configured Store is also synchronous. * * @remarks * - This is a new backwards-compatible feature of tough-cookie version 2.5, * so not all Stores will implement it efficiently. For Stores that do not * implement `removeAllCookies`, the fallback is to call `removeCookie` after * `getAllCookies`. * * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. * * - If one or more of the `removeCookie` calls fail, only the first error is returned. */ removeAllCookiesSync(): void; /** * A new CookieJar is created and the serialized {@link Cookie} values are added to * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in * the order in which they appear in the serialization. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. * * @param strOrObj - A JSON string or object representing the deserialized cookies. * @param callback - A function to call after the {@link CookieJar} has been deserialized. */ static deserialize(strOrObj: string | object, callback: Callback): void; /** * A new CookieJar is created and the serialized {@link Cookie} values are added to * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in * the order in which they appear in the serialization. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. * * @param strOrObj - A JSON string or object representing the deserialized cookies. * @param store - The underlying store to persist the deserialized cookies into. * @param callback - A function to call after the {@link CookieJar} has been deserialized. */ static deserialize(strOrObj: string | object, store: Store, callback: Callback): void; /** * A new CookieJar is created and the serialized {@link Cookie} values are added to * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in * the order in which they appear in the serialization. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. * * @param strOrObj - A JSON string or object representing the deserialized cookies. * @param store - The underlying store to persist the deserialized cookies into. */ static deserialize(strOrObj: string | object, store?: Store): Promise; /** * @internal No doc because this is an overload that supports the implementation */ static deserialize(strOrObj: string | object, store?: Store | Callback, callback?: Callback): unknown; /** * A new CookieJar is created and the serialized {@link Cookie} values are added to * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in * the order in which they appear in the serialization. * * Note: Only works if the configured Store is also synchronous. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. * * @param strOrObj - A JSON string or object representing the deserialized cookies. * @param store - The underlying store to persist the deserialized cookies into. */ static deserializeSync(strOrObj: string | SerializedCookieJar, store?: Store): CookieJar; /** * Alias of {@link CookieJar.deserializeSync}. * * @remarks * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. * * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. * * @param jsonString - A JSON string or object representing the deserialized cookies. * @param store - The underlying store to persist the deserialized cookies into. */ static fromJSON(jsonString: string | SerializedCookieJar, store?: Store): CookieJar; }