| 1 | /**
|
| 2 | * Options for configuring how {@link getPublicSuffix} behaves.
|
| 3 | * @public
|
| 4 | */
|
| 5 | export interface GetPublicSuffixOptions {
|
| 6 | /**
|
| 7 | * If set to `true` then the following {@link https://www.rfc-editor.org/rfc/rfc6761.html | Special Use Domains} will
|
| 8 | * be treated as if they were valid public suffixes ('local', 'example', 'invalid', 'localhost', 'test').
|
| 9 | *
|
| 10 | * @remarks
|
| 11 | * In testing scenarios it's common to configure the cookie store with so that `http://localhost` can be used as a domain:
|
| 12 | * ```json
|
| 13 | * {
|
| 14 | * allowSpecialUseDomain: true,
|
| 15 | * rejectPublicSuffixes: false
|
| 16 | * }
|
| 17 | * ```
|
| 18 | *
|
| 19 | * @defaultValue false
|
| 20 | */
|
| 21 | allowSpecialUseDomain?: boolean | undefined;
|
| 22 | /**
|
| 23 | * If set to `true` then any errors that occur while executing {@link getPublicSuffix} will be silently ignored.
|
| 24 | *
|
| 25 | * @defaultValue false
|
| 26 | */
|
| 27 | ignoreError?: boolean | undefined;
|
| 28 | }
|
| 29 | /**
|
| 30 | * Returns the public suffix of this hostname. The public suffix is the shortest domain
|
| 31 | * name upon which a cookie can be set.
|
| 32 | *
|
| 33 | * @remarks
|
| 34 | * A "public suffix" is a domain that is controlled by a
|
| 35 | * public registry, such as "com", "co.uk", and "pvt.k12.wy.us".
|
| 36 | * This step is essential for preventing attacker.com from
|
| 37 | * disrupting the integrity of example.com by setting a cookie
|
| 38 | * with a Domain attribute of "com". Unfortunately, the set of
|
| 39 | * public suffixes (also known as "registry controlled domains")
|
| 40 | * changes over time. If feasible, user agents SHOULD use an
|
| 41 | * up-to-date public suffix list, such as the one maintained by
|
| 42 | * the Mozilla project at http://publicsuffix.org/.
|
| 43 | * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 - Section 5.3})
|
| 44 | *
|
| 45 | * @example
|
| 46 | * ```
|
| 47 | * getPublicSuffix('www.example.com') === 'example.com'
|
| 48 | * getPublicSuffix('www.subdomain.example.com') === 'example.com'
|
| 49 | * ```
|
| 50 | *
|
| 51 | * @param domain - the domain attribute of a cookie
|
| 52 | * @param options - optional configuration for controlling how the public suffix is determined
|
| 53 | * @public
|
| 54 | */
|
| 55 | export declare function getPublicSuffix(domain: string, options?: GetPublicSuffixOptions): string | undefined;
|