| 1 | /**
|
| 2 | * Basic HTTP cookie parser and serializer for HTTP servers.
|
| 3 | */
|
| 4 |
|
| 5 | /**
|
| 6 | * Additional serialization options
|
| 7 | */
|
| 8 | export interface CookieSerializeOptions {
|
| 9 | /**
|
| 10 | * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
|
| 11 | * domain is set, and most clients will consider the cookie to apply to only
|
| 12 | * the current domain.
|
| 13 | */
|
| 14 | domain?: string | undefined;
|
| 15 |
|
| 16 | /**
|
| 17 | * Specifies a function that will be used to encode a cookie's value. Since
|
| 18 | * value of a cookie has a limited character set (and must be a simple
|
| 19 | * string), this function can be used to encode a value into a string suited
|
| 20 | * for a cookie's value.
|
| 21 | *
|
| 22 | * The default function is the global `encodeURIComponent`, which will
|
| 23 | * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
|
| 24 | * any that fall outside of the cookie range.
|
| 25 | */
|
| 26 | encode?(value: string): string;
|
| 27 |
|
| 28 | /**
|
| 29 | * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
|
| 30 | * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
|
| 31 | * it on a condition like exiting a web browser application.
|
| 32 | *
|
| 33 | * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
|
| 34 | * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
|
| 35 | * possible not all clients by obey this, so if both are set, they should
|
| 36 | * point to the same date and time.
|
| 37 | */
|
| 38 | expires?: Date | undefined;
|
| 39 | /**
|
| 40 | * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
|
| 41 | * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
|
| 42 | * default, the `HttpOnly` attribute is not set.
|
| 43 | *
|
| 44 | * *Note* be careful when setting this to true, as compliant clients will
|
| 45 | * not allow client-side JavaScript to see the cookie in `document.cookie`.
|
| 46 | */
|
| 47 | httpOnly?: boolean | undefined;
|
| 48 | /**
|
| 49 | * Specifies the number (in seconds) to be the value for the `Max-Age`
|
| 50 | * `Set-Cookie` attribute. The given number will be converted to an integer
|
| 51 | * by rounding down. By default, no maximum age is set.
|
| 52 | *
|
| 53 | * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
|
| 54 | * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
|
| 55 | * possible not all clients by obey this, so if both are set, they should
|
| 56 | * point to the same date and time.
|
| 57 | */
|
| 58 | maxAge?: number | undefined;
|
| 59 | /**
|
| 60 | * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](rfc-cutler-httpbis-partitioned-cookies)
|
| 61 | * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
|
| 62 | * `Partitioned` attribute is not set.
|
| 63 | *
|
| 64 | * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
| 65 | * This also means many clients may ignore this attribute until they understand it.
|
| 66 | *
|
| 67 | * More information about can be found in [the proposal](https://github.com/privacycg/CHIPS)
|
| 68 | */
|
| 69 | partitioned?: boolean | undefined;
|
| 70 | /**
|
| 71 | * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
|
| 72 | * By default, the path is considered the "default path".
|
| 73 | */
|
| 74 | path?: string | undefined;
|
| 75 | /**
|
| 76 | * Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
|
| 77 | *
|
| 78 | * - `'low'` will set the `Priority` attribute to `Low`.
|
| 79 | * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
|
| 80 | * - `'high'` will set the `Priority` attribute to `High`.
|
| 81 | *
|
| 82 | * More information about the different priority levels can be found in
|
| 83 | * [the specification][rfc-west-cookie-priority-00-4.1].
|
| 84 | *
|
| 85 | * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
| 86 | * This also means many clients may ignore this attribute until they understand it.
|
| 87 | */
|
| 88 | priority?: "low" | "medium" | "high" | undefined;
|
| 89 | /**
|
| 90 | * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
|
| 91 | *
|
| 92 | * - `true` will set the `SameSite` attribute to `Strict` for strict same
|
| 93 | * site enforcement.
|
| 94 | * - `false` will not set the `SameSite` attribute.
|
| 95 | * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
|
| 96 | * enforcement.
|
| 97 | * - `'strict'` will set the `SameSite` attribute to Strict for strict same
|
| 98 | * site enforcement.
|
| 99 | * - `'none'` will set the SameSite attribute to None for an explicit
|
| 100 | * cross-site cookie.
|
| 101 | *
|
| 102 | * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
|
| 103 | *
|
| 104 | * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
|
| 105 | */
|
| 106 | sameSite?: true | false | "lax" | "strict" | "none" | undefined;
|
| 107 | /**
|
| 108 | * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
|
| 109 | * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
|
| 110 | *
|
| 111 | * *Note* be careful when setting this to `true`, as compliant clients will
|
| 112 | * not send the cookie back to the server in the future if the browser does
|
| 113 | * not have an HTTPS connection.
|
| 114 | */
|
| 115 | secure?: boolean | undefined;
|
| 116 | }
|
| 117 |
|
| 118 | /**
|
| 119 | * Additional parsing options
|
| 120 | */
|
| 121 | export interface CookieParseOptions {
|
| 122 | /**
|
| 123 | * Specifies a function that will be used to decode a cookie's value. Since
|
| 124 | * the value of a cookie has a limited character set (and must be a simple
|
| 125 | * string), this function can be used to decode a previously-encoded cookie
|
| 126 | * value into a JavaScript string or other object.
|
| 127 | *
|
| 128 | * The default function is the global `decodeURIComponent`, which will decode
|
| 129 | * any URL-encoded sequences into their byte representations.
|
| 130 | *
|
| 131 | * *Note* if an error is thrown from this function, the original, non-decoded
|
| 132 | * cookie value will be returned as the cookie's value.
|
| 133 | */
|
| 134 | decode?(value: string): string;
|
| 135 | }
|
| 136 |
|
| 137 | /**
|
| 138 | * Parse an HTTP Cookie header string and returning an object of all cookie
|
| 139 | * name-value pairs.
|
| 140 | *
|
| 141 | * @param str the string representing a `Cookie` header value
|
| 142 | * @param [options] object containing parsing options
|
| 143 | */
|
| 144 | export function parse(str: string, options?: CookieParseOptions): Record<string, string>;
|
| 145 |
|
| 146 | /**
|
| 147 | * Serialize a cookie name-value pair into a `Set-Cookie` header string.
|
| 148 | *
|
| 149 | * @param name the name for the cookie
|
| 150 | * @param value value to set the cookie to
|
| 151 | * @param [options] object containing serialization options
|
| 152 | * @throws {TypeError} when `maxAge` options is invalid
|
| 153 | */
|
| 154 | export function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
|