315 lines
12 KiB
TypeScript
315 lines
12 KiB
TypeScript
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"];
|
|
}
|