From f3f18ba80ef84c0b698c1c4aeb6b5aecd2fe171e Mon Sep 17 00:00:00 2001 From: Colin Casey Date: Sun, 24 Mar 2024 19:40:10 -0300 Subject: [PATCH 1/3] Document `PrefixSecurity` --- api/.gitignore | 1 + api/docs/tough-cookie.cookiejar.md | 2 +- .../tough-cookie.cookiejar.prefixsecurity.md | 2 +- .../tough-cookie.createcookiejaroptions.md | 2 +- ...e.createcookiejaroptions.prefixsecurity.md | 2 +- api/docs/tough-cookie.md | 37 +++++++-- api/docs/tough-cookie.prefixsecurity.md | 83 +++++++++++++++++++ api/tough-cookie.api.md | 12 +-- lib/__tests__/cookiePrefixes.spec.ts | 8 +- lib/cookie/constants.ts | 26 ++++-- lib/cookie/cookieJar.ts | 17 ++-- lib/cookie/index.ts | 2 +- test/cookie_prefixes_test.js | 30 +++---- 13 files changed, 171 insertions(+), 53 deletions(-) create mode 100644 api/docs/tough-cookie.prefixsecurity.md diff --git a/api/.gitignore b/api/.gitignore index 8b80720c..43172356 100644 --- a/api/.gitignore +++ b/api/.gitignore @@ -3,6 +3,7 @@ docs/*.md # subsequent PRs will un-ignore areas that are under review until # all docs are complete and we can drop this ignore file entirely +!docs/tough-cookie.prefixsecurity.md !docs/tough-cookie.md !docs/tough-cookie.store.md !docs/tough-cookie.store.* diff --git a/api/docs/tough-cookie.cookiejar.md b/api/docs/tough-cookie.cookiejar.md index ed5c5967..dada6c2f 100644 --- a/api/docs/tough-cookie.cookiejar.md +++ b/api/docs/tough-cookie.cookiejar.md @@ -88,7 +88,7 @@ string -The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). +The configured value for the [CookieJar](./tough-cookie.cookiejar.md). diff --git a/api/docs/tough-cookie.cookiejar.prefixsecurity.md b/api/docs/tough-cookie.cookiejar.prefixsecurity.md index 0a7cdd6f..0d28da09 100644 --- a/api/docs/tough-cookie.cookiejar.prefixsecurity.md +++ b/api/docs/tough-cookie.cookiejar.prefixsecurity.md @@ -4,7 +4,7 @@ ## CookieJar.prefixSecurity property -The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). +The configured value for the [CookieJar](./tough-cookie.cookiejar.md). **Signature:** diff --git a/api/docs/tough-cookie.createcookiejaroptions.md b/api/docs/tough-cookie.createcookiejaroptions.md index 8b28a692..d693398d 100644 --- a/api/docs/tough-cookie.createcookiejaroptions.md +++ b/api/docs/tough-cookie.createcookiejaroptions.md @@ -92,7 +92,7 @@ Defaults to `false` if not specified. -_(Optional)_ Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). +_(Optional)_ Controls how cookie prefixes are handled. See . Defaults to `silent` if not specified. diff --git a/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md index b8c98ca9..5d6e1b89 100644 --- a/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md +++ b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md @@ -4,7 +4,7 @@ ## CreateCookieJarOptions.prefixSecurity property -Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). +Controls how cookie prefixes are handled. See . Defaults to `silent` if not specified. diff --git a/api/docs/tough-cookie.md b/api/docs/tough-cookie.md index 5d6d410b..08ba9e74 100644 --- a/api/docs/tough-cookie.md +++ b/api/docs/tough-cookie.md @@ -73,6 +73,34 @@ Base class for [CookieJar](./tough-cookie.cookiejar.md) stores. The storage model for each [CookieJar](./tough-cookie.cookiejar.md) instance can be replaced with a custom implementation. The default is [MemoryCookieStore](./tough-cookie.memorycookiestore.md). + + + +## Enumerations + + +
+ +Enumeration + + + + +Description + + +
+ +[PrefixSecurity](./tough-cookie.prefixsecurity.md) + + + + +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 [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). + +The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes. + +
@@ -334,15 +362,6 @@ Description -[PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) - - - - - - - - [version](./tough-cookie.version.md) diff --git a/api/docs/tough-cookie.prefixsecurity.md b/api/docs/tough-cookie.prefixsecurity.md new file mode 100644 index 00000000..8887f1ab --- /dev/null +++ b/api/docs/tough-cookie.prefixsecurity.md @@ -0,0 +1,83 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [PrefixSecurity](./tough-cookie.prefixsecurity.md) + +## PrefixSecurity enum + +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 [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). + +The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes. + +**Signature:** + +```typescript +export declare enum PrefixSecurity +``` + +## Enumeration Members + + + + + +
+ +Member + + + + +Value + + + + +Description + + +
+ +DISABLED + + + + +`"unsafe-disabled"` + + + + +Disables cookie prefix checking. + + +
+ +SILENT + + + + +`"silent"` + + + + +Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +STRICT + + + + +`"strict"` + + + + +Enables cookie prefix checking and will raise an error if conditions are not met. + + +
diff --git a/api/tough-cookie.api.md b/api/tough-cookie.api.md index c592c7e1..b383d4e1 100644 --- a/api/tough-cookie.api.md +++ b/api/tough-cookie.api.md @@ -253,12 +253,12 @@ export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): // @public export function permutePath(path: string): string[]; -// @public (undocumented) -export const PrefixSecurityEnum: Readonly<{ - SILENT: "silent"; - STRICT: "strict"; - DISABLED: "unsafe-disabled"; -}>; +// @public +export enum PrefixSecurity { + DISABLED = "unsafe-disabled", + SILENT = "silent", + STRICT = "strict" +} // @public export interface SerializedCookieJar { diff --git a/lib/__tests__/cookiePrefixes.spec.ts b/lib/__tests__/cookiePrefixes.spec.ts index 770f53a9..96759fb9 100644 --- a/lib/__tests__/cookiePrefixes.spec.ts +++ b/lib/__tests__/cookiePrefixes.spec.ts @@ -1,4 +1,4 @@ -import { PrefixSecurityEnum } from '../cookie/constants' +import { PrefixSecurity } from '../cookie/constants' import { CookieJar } from '../cookie/cookieJar' let cookieJar: CookieJar @@ -11,7 +11,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'silent', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.SILENT) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.SILENT) }) describe('__Secure prefix', () => { @@ -106,7 +106,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'strict', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.STRICT) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.STRICT) }) describe('__Secure prefix', () => { @@ -173,7 +173,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'unsafe-disabled', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.DISABLED) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.DISABLED) }) describe('__Secure prefix', () => { diff --git a/lib/cookie/constants.ts b/lib/cookie/constants.ts index 3d01ec28..aea9b1e7 100644 --- a/lib/cookie/constants.ts +++ b/lib/cookie/constants.ts @@ -1,8 +1,24 @@ -export const PrefixSecurityEnum = Object.freeze({ - SILENT: 'silent', - STRICT: 'strict', - DISABLED: 'unsafe-disabled', -}) +/** + * 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. + * @public + */ +export enum PrefixSecurity { + /** + * Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a {@link CookieJar}. + */ + SILENT = 'silent', + /** + * Enables cookie prefix checking and will raise an error if conditions are not met. + */ + STRICT = 'strict', + /** + * Disables cookie prefix checking. + */ + DISABLED = 'unsafe-disabled', +} const IP_V6_REGEX = ` \\[?(?: diff --git a/lib/cookie/cookieJar.ts b/lib/cookie/cookieJar.ts index e87b111e..ecfe5f71 100644 --- a/lib/cookie/cookieJar.ts +++ b/lib/cookie/cookieJar.ts @@ -18,7 +18,7 @@ import { import { canonicalDomain } from './canonicalDomain' import { IP_V6_REGEX_OBJECT, - PrefixSecurityEnum, + PrefixSecurity, SerializedCookieJar, } from './constants' import { defaultPath } from './defaultPath' @@ -256,8 +256,7 @@ function isHostPrefixConditionMet(cookie: Cookie): boolean { ) } -type PrefixSecurityValue = - (typeof PrefixSecurityEnum)[keyof typeof PrefixSecurityEnum] +type PrefixSecurityValue = (typeof PrefixSecurity)[keyof typeof PrefixSecurity] function getNormalizedPrefixSecurity( prefixSecurity: string, ): PrefixSecurityValue { @@ -265,14 +264,14 @@ function getNormalizedPrefixSecurity( const normalizedPrefixSecurity = prefixSecurity.toLowerCase() /* The three supported options */ switch (normalizedPrefixSecurity) { - case PrefixSecurityEnum.STRICT: - case PrefixSecurityEnum.SILENT: - case PrefixSecurityEnum.DISABLED: + case PrefixSecurity.STRICT: + case PrefixSecurity.SILENT: + case PrefixSecurity.DISABLED: return normalizedPrefixSecurity } } /* Default is SILENT */ - return PrefixSecurityEnum.SILENT + return PrefixSecurity.SILENT } /** @@ -607,9 +606,9 @@ export class CookieJar { /* 6265bis-02 S5.4 Steps 15 & 16 */ const ignoreErrorForPrefixSecurity = - this.prefixSecurity === PrefixSecurityEnum.SILENT + this.prefixSecurity === PrefixSecurity.SILENT const prefixSecurityDisabled = - this.prefixSecurity === PrefixSecurityEnum.DISABLED + this.prefixSecurity === PrefixSecurity.DISABLED /* If prefix checking is not disabled ...*/ if (!prefixSecurityDisabled) { let errorFound = false diff --git a/lib/cookie/index.ts b/lib/cookie/index.ts index e14c7999..10092e9d 100644 --- a/lib/cookie/index.ts +++ b/lib/cookie/index.ts @@ -7,7 +7,7 @@ export { ParameterError } from '../validators' export { version } from '../version' export { Callback, ErrorCallback } from '../utils' export { canonicalDomain } from './canonicalDomain' -export { PrefixSecurityEnum, SerializedCookieJar } from './constants' +export { PrefixSecurity, SerializedCookieJar } from './constants' export { Cookie } from './cookie' export { cookieCompare } from './cookieCompare' export { diff --git a/test/cookie_prefixes_test.js b/test/cookie_prefixes_test.js index 20f9fb04..ef8624a1 100644 --- a/test/cookie_prefixes_test.js +++ b/test/cookie_prefixes_test.js @@ -33,7 +33,7 @@ const vows = require("vows"); const assert = require("assert"); const tough = require("../dist/cookie"); const CookieJar = tough.CookieJar; -const PrefixSecurityEnum = tough.PrefixSecurityEnum; +const PrefixSecurity = tough.PrefixSecurity; vows .describe("Cookie Prefixes") @@ -45,7 +45,7 @@ vows return new CookieJar(null, { prefixSecurity: "silent" }); }, "with no Secure attribute, should fail silently": function(cj) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -55,7 +55,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with Secure attribute and over https, should work": function(cj) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com; Secure", "https://www.example.com", @@ -69,7 +69,7 @@ vows "with Secure attribute but not over https, should fail silently": function( cj ) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com; Secure", "http://www.example.com", @@ -86,13 +86,13 @@ vows "with no Secure attribute or Domain or Path, should fail silently": function( cj ) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync("__Host-SID=12345", "http://www.example.com", {}); const cookies = cj.getCookiesSync("http://www.example.com"); assert.isEmpty(cookies); // no cookies set }, "with no Domain or Path, should fail silently": function(cj) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure", "http://www.example.com", @@ -102,7 +102,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with no Path, should fail silently": function(cj) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com", "http://www.example.com", @@ -112,7 +112,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with Domain, should fail silently": function(cj) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com; Path=/", "http://www.example.com", @@ -124,7 +124,7 @@ vows "with Secure and Path but no Domain over https, should work": function( cj ) { - assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Path=/", "https://www.example.com", @@ -144,7 +144,7 @@ vows return new CookieJar(null, { prefixSecurity: "strict" }); }, passes: function(cj) { - assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Secure; Domain=example.com", "https://www.example.com", @@ -159,7 +159,7 @@ vows "for invalid cookie": { topic: function() { const cj = new CookieJar(null, { prefixSecurity: "strict" }); - assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -176,7 +176,7 @@ vows "for invalid cookie": { topic: function() { const cj = new CookieJar(null, { prefixSecurity: "strict" }); - assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com", "https://www.example.com", @@ -193,7 +193,7 @@ vows return new CookieJar(null, { prefixSecurity: "strict" }); }, passes: function(cj) { - assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Path=/", "https://www.foo.com", @@ -213,7 +213,7 @@ vows return new CookieJar(null, { prefixSecurity: "unsafe-disabled" }); }, "does not fail": function(cj) { - assert.equal(PrefixSecurityEnum.DISABLED, cj.prefixSecurity); + assert.equal(PrefixSecurity.DISABLED, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -230,7 +230,7 @@ vows return new CookieJar(null, { prefixSecurity: "unsafe-disabled" }); }, "does not fail": function(cj) { - assert.equal(PrefixSecurityEnum.DISABLED, cj.prefixSecurity); + assert.equal(PrefixSecurity.DISABLED, cj.prefixSecurity); /* Failure case because Domain defined */ cj.setCookieSync( "__Host-SID=12345; Domain=example.com", From 3e2533de8dfea84a25e2a101b536e4d8398b25b6 Mon Sep 17 00:00:00 2001 From: Colin Casey Date: Mon, 15 Apr 2024 09:40:47 -0300 Subject: [PATCH 2/3] Revert `enum` type change for `PrefixSecurityEnum` --- api/docs/tough-cookie.cookiejar.md | 2 +- .../tough-cookie.cookiejar.prefixsecurity.md | 2 +- .../tough-cookie.createcookiejaroptions.md | 2 +- ...e.createcookiejaroptions.prefixsecurity.md | 2 +- api/docs/tough-cookie.md | 47 +++++------ api/docs/tough-cookie.prefixsecurity.md | 83 ------------------- api/tough-cookie.api.md | 10 +-- lib/__tests__/cookiePrefixes.spec.ts | 8 +- lib/cookie/constants.ts | 27 +++--- lib/cookie/cookieJar.ts | 17 ++-- lib/cookie/index.ts | 2 +- 11 files changed, 54 insertions(+), 148 deletions(-) delete mode 100644 api/docs/tough-cookie.prefixsecurity.md diff --git a/api/docs/tough-cookie.cookiejar.md b/api/docs/tough-cookie.cookiejar.md index dada6c2f..ed5c5967 100644 --- a/api/docs/tough-cookie.cookiejar.md +++ b/api/docs/tough-cookie.cookiejar.md @@ -88,7 +88,7 @@ string -The configured value for the [CookieJar](./tough-cookie.cookiejar.md). +The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). diff --git a/api/docs/tough-cookie.cookiejar.prefixsecurity.md b/api/docs/tough-cookie.cookiejar.prefixsecurity.md index 0d28da09..0a7cdd6f 100644 --- a/api/docs/tough-cookie.cookiejar.prefixsecurity.md +++ b/api/docs/tough-cookie.cookiejar.prefixsecurity.md @@ -4,7 +4,7 @@ ## CookieJar.prefixSecurity property -The configured value for the [CookieJar](./tough-cookie.cookiejar.md). +The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). **Signature:** diff --git a/api/docs/tough-cookie.createcookiejaroptions.md b/api/docs/tough-cookie.createcookiejaroptions.md index d693398d..8b28a692 100644 --- a/api/docs/tough-cookie.createcookiejaroptions.md +++ b/api/docs/tough-cookie.createcookiejaroptions.md @@ -92,7 +92,7 @@ Defaults to `false` if not specified. -_(Optional)_ Controls how cookie prefixes are handled. See . +_(Optional)_ Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). Defaults to `silent` if not specified. diff --git a/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md index 5d6e1b89..b8c98ca9 100644 --- a/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md +++ b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md @@ -4,7 +4,7 @@ ## CreateCookieJarOptions.prefixSecurity property -Controls how cookie prefixes are handled. See . +Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). Defaults to `silent` if not specified. diff --git a/api/docs/tough-cookie.md b/api/docs/tough-cookie.md index 08ba9e74..9ff567de 100644 --- a/api/docs/tough-cookie.md +++ b/api/docs/tough-cookie.md @@ -73,34 +73,6 @@ Base class for [CookieJar](./tough-cookie.cookiejar.md) stores. The storage model for each [CookieJar](./tough-cookie.cookiejar.md) instance can be replaced with a custom implementation. The default is [MemoryCookieStore](./tough-cookie.memorycookiestore.md). - - - -## Enumerations - - -
- -Enumeration - - - - -Description - - -
- -[PrefixSecurity](./tough-cookie.prefixsecurity.md) - - - - -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 [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). - -The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes. - -
@@ -362,6 +334,25 @@ Description +[PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) + + + + +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 [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). + +The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) 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 [CookieJar](./tough-cookie.cookiejar.md). + +- `strict` - Enables cookie prefix checking and will raise an error if conditions are not met. + +- `unsafe-disabled` - Disables cookie prefix checking. + + + + + [version](./tough-cookie.version.md) diff --git a/api/docs/tough-cookie.prefixsecurity.md b/api/docs/tough-cookie.prefixsecurity.md deleted file mode 100644 index 8887f1ab..00000000 --- a/api/docs/tough-cookie.prefixsecurity.md +++ /dev/null @@ -1,83 +0,0 @@ - - -[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [PrefixSecurity](./tough-cookie.prefixsecurity.md) - -## PrefixSecurity enum - -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 [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). - -The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes. - -**Signature:** - -```typescript -export declare enum PrefixSecurity -``` - -## Enumeration Members - - - - - -
- -Member - - - - -Value - - - - -Description - - -
- -DISABLED - - - - -`"unsafe-disabled"` - - - - -Disables cookie prefix checking. - - -
- -SILENT - - - - -`"silent"` - - - - -Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a [CookieJar](./tough-cookie.cookiejar.md). - - -
- -STRICT - - - - -`"strict"` - - - - -Enables cookie prefix checking and will raise an error if conditions are not met. - - -
diff --git a/api/tough-cookie.api.md b/api/tough-cookie.api.md index b383d4e1..424a50c4 100644 --- a/api/tough-cookie.api.md +++ b/api/tough-cookie.api.md @@ -254,11 +254,11 @@ export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): export function permutePath(path: string): string[]; // @public -export enum PrefixSecurity { - DISABLED = "unsafe-disabled", - SILENT = "silent", - STRICT = "strict" -} +export const PrefixSecurityEnum: Readonly<{ + SILENT: "silent"; + STRICT: "strict"; + DISABLED: "unsafe-disabled"; +}>; // @public export interface SerializedCookieJar { diff --git a/lib/__tests__/cookiePrefixes.spec.ts b/lib/__tests__/cookiePrefixes.spec.ts index 96759fb9..770f53a9 100644 --- a/lib/__tests__/cookiePrefixes.spec.ts +++ b/lib/__tests__/cookiePrefixes.spec.ts @@ -1,4 +1,4 @@ -import { PrefixSecurity } from '../cookie/constants' +import { PrefixSecurityEnum } from '../cookie/constants' import { CookieJar } from '../cookie/cookieJar' let cookieJar: CookieJar @@ -11,7 +11,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'silent', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.SILENT) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.SILENT) }) describe('__Secure prefix', () => { @@ -106,7 +106,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'strict', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.STRICT) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.STRICT) }) describe('__Secure prefix', () => { @@ -173,7 +173,7 @@ describe('When `prefixSecurity` is enabled for `CookieJar`', () => { cookieJar = new CookieJar(null, { prefixSecurity: 'unsafe-disabled', }) - expect(cookieJar.prefixSecurity).toBe(PrefixSecurity.DISABLED) + expect(cookieJar.prefixSecurity).toBe(PrefixSecurityEnum.DISABLED) }) describe('__Secure prefix', () => { diff --git a/lib/cookie/constants.ts b/lib/cookie/constants.ts index aea9b1e7..0af44db5 100644 --- a/lib/cookie/constants.ts +++ b/lib/cookie/constants.ts @@ -2,23 +2,20 @@ * 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. + * 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 enum PrefixSecurity { - /** - * Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a {@link CookieJar}. - */ - SILENT = 'silent', - /** - * Enables cookie prefix checking and will raise an error if conditions are not met. - */ - STRICT = 'strict', - /** - * Disables cookie prefix checking. - */ - DISABLED = 'unsafe-disabled', -} +export const PrefixSecurityEnum = Object.freeze({ + SILENT: 'silent', + STRICT: 'strict', + DISABLED: 'unsafe-disabled', +}) const IP_V6_REGEX = ` \\[?(?: diff --git a/lib/cookie/cookieJar.ts b/lib/cookie/cookieJar.ts index ecfe5f71..e87b111e 100644 --- a/lib/cookie/cookieJar.ts +++ b/lib/cookie/cookieJar.ts @@ -18,7 +18,7 @@ import { import { canonicalDomain } from './canonicalDomain' import { IP_V6_REGEX_OBJECT, - PrefixSecurity, + PrefixSecurityEnum, SerializedCookieJar, } from './constants' import { defaultPath } from './defaultPath' @@ -256,7 +256,8 @@ function isHostPrefixConditionMet(cookie: Cookie): boolean { ) } -type PrefixSecurityValue = (typeof PrefixSecurity)[keyof typeof PrefixSecurity] +type PrefixSecurityValue = + (typeof PrefixSecurityEnum)[keyof typeof PrefixSecurityEnum] function getNormalizedPrefixSecurity( prefixSecurity: string, ): PrefixSecurityValue { @@ -264,14 +265,14 @@ function getNormalizedPrefixSecurity( const normalizedPrefixSecurity = prefixSecurity.toLowerCase() /* The three supported options */ switch (normalizedPrefixSecurity) { - case PrefixSecurity.STRICT: - case PrefixSecurity.SILENT: - case PrefixSecurity.DISABLED: + case PrefixSecurityEnum.STRICT: + case PrefixSecurityEnum.SILENT: + case PrefixSecurityEnum.DISABLED: return normalizedPrefixSecurity } } /* Default is SILENT */ - return PrefixSecurity.SILENT + return PrefixSecurityEnum.SILENT } /** @@ -606,9 +607,9 @@ export class CookieJar { /* 6265bis-02 S5.4 Steps 15 & 16 */ const ignoreErrorForPrefixSecurity = - this.prefixSecurity === PrefixSecurity.SILENT + this.prefixSecurity === PrefixSecurityEnum.SILENT const prefixSecurityDisabled = - this.prefixSecurity === PrefixSecurity.DISABLED + this.prefixSecurity === PrefixSecurityEnum.DISABLED /* If prefix checking is not disabled ...*/ if (!prefixSecurityDisabled) { let errorFound = false diff --git a/lib/cookie/index.ts b/lib/cookie/index.ts index 10092e9d..e14c7999 100644 --- a/lib/cookie/index.ts +++ b/lib/cookie/index.ts @@ -7,7 +7,7 @@ export { ParameterError } from '../validators' export { version } from '../version' export { Callback, ErrorCallback } from '../utils' export { canonicalDomain } from './canonicalDomain' -export { PrefixSecurity, SerializedCookieJar } from './constants' +export { PrefixSecurityEnum, SerializedCookieJar } from './constants' export { Cookie } from './cookie' export { cookieCompare } from './cookieCompare' export { From 5022c1967d97541072a3bec6f4071938b8d3dc41 Mon Sep 17 00:00:00 2001 From: Colin Casey Date: Mon, 15 Apr 2024 09:55:10 -0300 Subject: [PATCH 3/3] Revert `enum` type change for `PrefixSecurityEnum` --- test/cookie_prefixes_test.js | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/test/cookie_prefixes_test.js b/test/cookie_prefixes_test.js index ef8624a1..20f9fb04 100644 --- a/test/cookie_prefixes_test.js +++ b/test/cookie_prefixes_test.js @@ -33,7 +33,7 @@ const vows = require("vows"); const assert = require("assert"); const tough = require("../dist/cookie"); const CookieJar = tough.CookieJar; -const PrefixSecurity = tough.PrefixSecurity; +const PrefixSecurityEnum = tough.PrefixSecurityEnum; vows .describe("Cookie Prefixes") @@ -45,7 +45,7 @@ vows return new CookieJar(null, { prefixSecurity: "silent" }); }, "with no Secure attribute, should fail silently": function(cj) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -55,7 +55,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with Secure attribute and over https, should work": function(cj) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com; Secure", "https://www.example.com", @@ -69,7 +69,7 @@ vows "with Secure attribute but not over https, should fail silently": function( cj ) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com; Secure", "http://www.example.com", @@ -86,13 +86,13 @@ vows "with no Secure attribute or Domain or Path, should fail silently": function( cj ) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync("__Host-SID=12345", "http://www.example.com", {}); const cookies = cj.getCookiesSync("http://www.example.com"); assert.isEmpty(cookies); // no cookies set }, "with no Domain or Path, should fail silently": function(cj) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure", "http://www.example.com", @@ -102,7 +102,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with no Path, should fail silently": function(cj) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com", "http://www.example.com", @@ -112,7 +112,7 @@ vows assert.isEmpty(cookies); // no cookies set }, "with Domain, should fail silently": function(cj) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com; Path=/", "http://www.example.com", @@ -124,7 +124,7 @@ vows "with Secure and Path but no Domain over https, should work": function( cj ) { - assert.equal(PrefixSecurity.SILENT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.SILENT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Path=/", "https://www.example.com", @@ -144,7 +144,7 @@ vows return new CookieJar(null, { prefixSecurity: "strict" }); }, passes: function(cj) { - assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Secure; Domain=example.com", "https://www.example.com", @@ -159,7 +159,7 @@ vows "for invalid cookie": { topic: function() { const cj = new CookieJar(null, { prefixSecurity: "strict" }); - assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -176,7 +176,7 @@ vows "for invalid cookie": { topic: function() { const cj = new CookieJar(null, { prefixSecurity: "strict" }); - assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Domain=example.com", "https://www.example.com", @@ -193,7 +193,7 @@ vows return new CookieJar(null, { prefixSecurity: "strict" }); }, passes: function(cj) { - assert.equal(PrefixSecurity.STRICT, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.STRICT, cj.prefixSecurity); cj.setCookieSync( "__Host-SID=12345; Secure; Path=/", "https://www.foo.com", @@ -213,7 +213,7 @@ vows return new CookieJar(null, { prefixSecurity: "unsafe-disabled" }); }, "does not fail": function(cj) { - assert.equal(PrefixSecurity.DISABLED, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.DISABLED, cj.prefixSecurity); cj.setCookieSync( "__Secure-SID=12345; Domain=example.com", "http://www.example.com", @@ -230,7 +230,7 @@ vows return new CookieJar(null, { prefixSecurity: "unsafe-disabled" }); }, "does not fail": function(cj) { - assert.equal(PrefixSecurity.DISABLED, cj.prefixSecurity); + assert.equal(PrefixSecurityEnum.DISABLED, cj.prefixSecurity); /* Failure case because Domain defined */ cj.setCookieSync( "__Host-SID=12345; Domain=example.com",