Skip to content

feat: Add RFC 6761–compliant localhost loopback checks so secure cookies work on localhost (fixes: #382) - #498

Merged
colincasey merged 18 commits into
salesforce:masterfrom
Chriss4123:feat/localhost-secure-context
Apr 11, 2025
Merged

colincasey merged 18 commits into
salesforce:masterfrom
Chriss4123:feat/localhost-secure-context

Conversation

@Chriss4123

Copy link
Copy Markdown
Contributor

fixes: #382

Description

This commit extends how cookies are treated in secure contexts by fully recognizing localhost and loopback IPs as trustworthy origins, matching the de facto behavior of all modern browsers and RFC 6761. Previously, tough-cookie defaulted secure to true only for https: and wss: URLs, causing cookies with secure to not work with localhost.

What Changed

  1. New secureContext.ts

    • Implements isPotentiallyTrustworthy(url) by checking:
      • Schemes: https or wss
      • Loopback IPs: 127.0.0.1/8 and ::1
      • Hostnames: localhost and *.localhost
    • Adapted from Chromium’s IsLocalhost, IsLoopback and HostNoBracketsPiece, located at:
  2. cookieJar.ts Update

  • Replaced the old check which only accounts for https and wss schemes:
const secure =
  context.protocol &&
  (context.protocol == 'https:' || context.protocol == 'wss:')
  • with the new isPotentiallyTrustworthy function which accounts for secure schemes, localhost addresses and loopback addresses.

No existing functionality is removed. Where the old check would return true, so does the new check. The only added functionality is treating localhost addresses and loopback addresses as secure contexts which was previously not present.

All modern browsers (Chrome et. al) support secure cookies on localhost so it only makes sense tough-cookie supports this too.

@colincasey

Copy link
Copy Markdown
Contributor

@Chriss4123 thanks for this pull request! I try to review it by the end of the week.

@colincasey colincasey self-assigned this Feb 18, 2025
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/cookieJar.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/cookie/secureContext.ts Resolved
Comment thread lib/__tests__/cookieJar.spec.ts Resolved
@Chriss4123

Copy link
Copy Markdown
Contributor Author

@colincasey I've completed all the requested changes and also added a comment linking a potentially trustworthy origin and the notion of a "secure" connection in draft-ietf-httpbis-rfc6265bis-19.

I'm ready for you to re-review the PR.

@Chriss4123

Copy link
Copy Markdown
Contributor Author

Will look at the integration tests later and find what is causing these issues. Will let you know once all is good.

@colincasey

Copy link
Copy Markdown
Contributor

Thanks @Chriss4123, I'll hold off on approval until it's clearer why jsdom tests would fail with this code included.

@Chriss4123

Copy link
Copy Markdown
Contributor Author

@colincasey The reason jsdom tests fail is because they expect Secure cookies to not work on localhost, as seen here and in other cookie tests.

The testHost + "/TestPath/set-cookie-from-server" path sets multiple cookies, one of which being a cookie with the Secure attribute (testHost is http://127.0.0.1:...) and the assertion expects the Secure cookie to not be present:

assertCookies(cookieHeader, [
  "Test1=Basic",
  "Test2=PathMatch",
  "Test6=HttpOnly",
  // "Test7=Secure; expires=Wed, 13-Jan-2051 22:23:01 GMT; path=/; Secure", (This cookie is present)
  "Test9=Duplicate",
  "Test10={\"prop1\":5,\"prop2\":\"value\"}",
  "Malformed"
]);

due to the scheme being http instead of https.

This is unfortunately something out of our control, but as their goal states:

the goal of the project is to emulate enough of a subset of a web browser to be useful for testing and scraping real-world web applications.

I do believe that part of that should be accepting Secure cookies on localhost as many browsers (Firefox, Chromium, etc) do.

I'll open a PR in jsdom attempting to change that but in case users don't want this functionality we can add a new parameter in the get cookies function that explicitly controls whether we should treat localhost/loopback addresses as trustworthy, something like allowSecureOnLocal.

As it stands jsdom isn't automatically using the latest version of tough-cookie, thus we can add this parameter, merge the PR and raise attention to the jsdom devs that if they'd like to keep old cookie trustworthy functionality they need to set allowSecureOnLocal to true.

What do you think of this?

@Chriss4123

Copy link
Copy Markdown
Contributor Author

By the way, when I run npm run prepare-pr it replaces all CRLF's with LF's in the docs:

In Unix systems the end of a line is represented with a line feed (LF). In windows a line is represented with a carriage return (CR) and a line feed (LF) thus (CRLF). when you get code from git that was uploaded from a unix system they will only have an LF.

(taken from https://stackoverflow.com/a/5834094)

This is because I am on Linux and the last person to run prepare-pr likely did it on Windows. I am going to commit it, but if this is an issue we can revert this commit and make a plan to use CRLF instead.

@colincasey

Copy link
Copy Markdown
Contributor

By the way, when I run npm run prepare-pr it replaces all CRLF's with LF's in the docs

This is expected @Chriss4123. There's a bug in the api-extractor that seems to be at the root of this. Our automation doc checks should catch if there's any problems here so if that passes you should be all good.

As for the code, I have one question for you on the addition of allowSecureOnLocal - do you think that option should be available on the CookieJar constructor instead of as an option on the getCookies method? The RFC states this should be at the discretion of the user agent during both storage and retrieval so I find it a bit odd that it's only exposed as configuration when retrieving cookies.

@Chriss4123

Copy link
Copy Markdown
Contributor Author

That is a great point @colincasey. The only reason I didn't do this is because the cookie jar doesn't actually follow this step in the algorithm:

> jar.setCookie('ipv6cookie=ipv6val; Secure; Path=/', 'http://[::ffff:7f00:1]:5000/')
Promise {
  Cookie="ipv6cookie=ipv6val; Path=/; Secure; hostOnly=true; aAge=0ms; cAge=0ms",
  [Symbol(async_id_symbol)]: 137,
  [Symbol(trigger_async_id_symbol)]: 6
}

> jar.store.idx
[Object: null prototype] {
  '::ffff:7f00:1': [Object: null prototype] {
    '/': [Object: null prototype] {
      ipv6cookie: Cookie="ipv6cookie=ipv6val; Path=/; Secure; hostOnly=true; aAge=142897ms; cAge=142897ms"
    }
  }
}

If it did, this cookie wouldn't be present in the store at all. Testing with this code:

from flask import Flask, make_response, request

app = Flask(__name__)

@app.route('/setcookie')
def set_cookie():
    resp = make_response('')
    resp.set_cookie('example', '', secure=True)
    return resp

@app.route('/getcookie')
def get_cookie():
    return 'Cookie is set' if 'example' in request.cookies else 'No cookie set'

if __name__ == '__main__':
    app.run()

and Firefox on [::ffff:7f00:1]:5000, I can see that the example cookie is not set when I visit /setcookie, however this library will set, albeit it wont be returned so in the end it's as if it was never set if you only use the getCookies functions and don't access the store directly.

If you think this is a flaw too, let me know and I can open a new PR for it.
I'll also adjust the logic within this PR to reflect this rule in the algorithm by moving the allowSecureOnLocal to the constructor of CookieJar.

@colincasey

colincasey commented Feb 28, 2025 •

Copy link
Copy Markdown
Contributor

this library will set, albeit it wont be returned so in the end it's as if it was never set

This is what I was hinting at. I noticed in the tests added to support the allowSecureOnLocal option you were able to set the cookie in the store but not retrieve it. While I don't think that's technically wrong, I also don't think it's technically right 😅

What do you think of the following alternatives @Chriss4123?

Expose the allowSecureOnLocal option on the CookieStore

This would allow setCookie and getCookies to enforce the option and cover what's described in the storage and retrieval algorithms of the RFC. Then, a CookieJar with the allowSecureOnLocal option disabled would never allow new secure localhost cookies to be set while also preventing existing secure localhost cookies that may already be in the store from being returned.

Testing the retrieval case is a bit more complex but can be done if setCookie is bypassed and a secure localhost cookie is inserted directly into the store.

Expose the allowSecureOnLocal option on setCookie and getCookies

Same as the above, this would allow setCookie and getCookies to enforce the option and cover what's described in the storage and retrieval algorithms of the RFC. This finer degree of control comes with the trade-off of increased configuration complexity for the API with little benefit. Other then testing, I can't imagine a scenario where you'd want to use different values for allowSecureOnLocal when storing vs. retrieving.

@Chriss4123

Copy link
Copy Markdown
Contributor Author

This would allow setCookie and getCookies to enforce the option and cover what's described in the storage and retrieval algorithms of the RFC. Then, a CookieJar with the allowSecureOnLocal option disabled would never allow new secure localhost cookies to be set while also preventing existing secure localhost cookies that may already be in the store from being returned.

@colincasey Sorry, didn't realize you actually answered my question, guess I was too tired 😅.
Anyways, I've gone ahead and implemented that parameter and also the logic to abort if we're setting a secure cookie on a non-secure URL.

In the process, I had to modify multiple current and legacy tests to reflect that setting a cookie with the Secure attribute on a non-secure URL now throws an error instead of succeeding.

Previously, those tests expected no error when setting the cookie and instead not retrieving the cookie.

@colincasey colincasey added this to the v6 milestone Mar 7, 2025
@colincasey

Copy link
Copy Markdown
Contributor

@Chriss4123 discussed this PR with the other maintainers today. We're looking at shipping this in a v6 release. @awaterma is also going to give it a review and we're just figuring out if there are other work items that we'd like to include in a new major release so don't be surprised if it takes a while longer for it to be merged. Thanks so much for this contribution!

@Chriss4123

Copy link
Copy Markdown
Contributor Author

@colincasey got it. For now I can just use my branch in my projects where I need this functionality.

If you need any further changes let me know.

Do you have a broad ETA in mind for this being merged (i.e. v6 release)?

colincasey
colincasey previously approved these changes Mar 7, 2025
@colincasey

Copy link
Copy Markdown
Contributor

@Chriss4123 the ETA would definitely be a broad one 😅 My guess is somewhere between 2 - 4 weeks.

@Chriss4123

Copy link
Copy Markdown
Contributor Author

@colincasey that ETA is definitely quicker than I anticipated which is good to hear!

I realized I made a small mistake on a test case:

Pre Secure cookie fail when not a potentially trustworthy origin:

it('should fail silently when no Domain or Path', async () => {
  await cookieJar.setCookie('__Host-SID=12345; Secure', insecureUrl, {})
  const cookies = await cookieJar.getCookies(insecureUrl)
  expect(cookies).toEqual([])
})

Post Secure cookie fail when not a potentially trustworthy origin:

it('should fail silently when no Domain or Path', async () => {
  await cookieJar.setCookie('__Host-SID=12345', insecureUrl, {})
  const cookies = await cookieJar.getCookies(insecureUrl)
  expect(cookies).toEqual([])
})

I think there was an issue with the initial test case: __Host- prefix requires the Secure attribute and thus a secure URL so I'm not 100% sure why insecureUrl was being used, which led to me just getting rid of the Secure attribute altogether as an error is now raised when a Secure cookie is paired with an unsecure URL. I've updated it to use the Secure attribute with secureUrl (so it actually tests that it silently fails when no Domain or Path is set).

@awaterma awaterma left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks good to me; let's discuss today and see if we can move this forward. :)

@colincasey
colincasey merged commit 6108fbd into salesforce:master Apr 11, 2025
@colincasey

Copy link
Copy Markdown
Contributor

@Chriss4123 we're going to include this in a new major release (v6). I'm going to publish a pre-release sometime next week to give consumers a chance to try things out before it becomes official. Thanks so much for this contribution!

@Chriss4123

Copy link
Copy Markdown
Contributor Author

@Chriss4123 we're going to include this in a new major release (v6). I'm going to publish a pre-release sometime next week to give consumers a chance to try things out before it becomes official. Thanks so much for this contribution!

Happy this has been merged! On the jsdom side do you think I should open an issue as a precaution to disable the allow secure on localhost flag to keep the old behavior or do you think it's unnecessary as they will likely figure it out if they try bump tough-cookies version?

Apart from that happy I could help!

@colincasey

Copy link
Copy Markdown
Contributor

@Chriss4123 Once I publish a pre-release, it'll be possible to open PRs against jsdom with tough-cookie set to that new version with options to either:

  • Update their test suite to use secure domains in their tests or allow the localhost cookies
  • Configure their internal CookieJar to use the opt-out flag allowSecureOnLocal = false to retain their existing test behavior

I think that would be useful in getting a conversation started around how this change affects jsdom and what they'd like to see done to support this change.

I don't mind doing that work but I also won't stop you if you wanted to tackle that before I get around to it 😄

colincasey added a commit to colincasey/jsdom that referenced this pull request May 9, 2025
The upcoming release of `tough-cookie` contains a [breaking change](salesforce/tough-cookie#498) for how `Secure` cookies are treated in secure contexts such as `localhost`. This PR updates the cookie processing tests with:
- A cookie jar configured to simulate an insecure context to match the expected behavior of the `http`-based server tests
- A correction of the `https`-based server test which should allow for `Secure` cookies
@ertl

ertl commented Jun 20, 2025

Copy link
Copy Markdown

@colincasey When is the official release of version 6.x scheduled? Are there any known downsides to using the release candidate? We're considering it urgently due to the need for the new secure behavior.

@colincasey

Copy link
Copy Markdown
Contributor

@ertl There are no major downsides to using the release candidate.

There is one minor detail that I've got to sort out first though and it's whether to enforce the secure behavior on both cookie storage and retrieval. RFC 6265 doesn't state it should be enforced during storage but httpbis-rfc6265bis (draft 20) does and that is currently causing an issue with one of the web platform tests for websockets that jsdom uses.

Removing the code here is more in alignment with RFC 6265 and this also seems to satisfy the web platform tests. I just haven't had the time yet to double-check the expected websocket cookie behavior in different browsers to confirm if that's the correct action to take or not.

@ertl

ertl commented Jun 20, 2025

Copy link
Copy Markdown

@colincasey Thanks for the update. We'll go ahead and give the release candidate a try.

colincasey added a commit that referenced this pull request Jul 10, 2025
This change was introduce in #498. As this new feature was driven by current browser behaviors + updates to the terminology for "secure" connections from RFC6265bis-19, it seemed appropriate to also apply the following check from RFC6265bis-19 when setting a cookie:

> If the request-uri does not denote a "secure" connection (as defined by the user agent), and the cookie's secure-only-flag is true, then abort these steps and ignore the cookie entirely.
> - https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-19#section-5.7-3.13.1

This deviates from RFC6265 which does not describe any check for a "secure" connection when setting a cookie, only when retrieving the cookie.

In our integration tests for JSDOM, this code also causes a failure in their Web Platform Test suite around passing cookies to Websocket connections. Testing the behavior for this in various browsers showed inconsistent results which I'll summarize below:

| Browser | HTTP → WSS | HTTPS → WSS |
|---------|------------|-------------|
| Chrome  | Fail       | Pass        |
| Firefox | Pass       | Pass        |
| Safari  | Fail       | Pass        |
| Edge    | Fail       | Pass        |

As it's unclear what the correct behavior should be here, I think we should revert this check to restore the previous behavior in https://github.com/salesforce/tough-cookie/blob/v5.1.2/lib/cookie/cookieJar.ts#L595 to what RFC6265 defines.
colincasey added a commit that referenced this pull request Jul 17, 2025
This change was introduce in #498. As this new feature was driven by current browser behaviors + updates to the terminology for "secure" connections from RFC6265bis-19, it seemed appropriate to also apply the following check from RFC6265bis-19 when setting a cookie:

> If the request-uri does not denote a "secure" connection (as defined by the user agent), and the cookie's secure-only-flag is true, then abort these steps and ignore the cookie entirely.
> - https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-19#section-5.7-3.13.1

This deviates from RFC6265 which does not describe any check for a "secure" connection when setting a cookie, only when retrieving the cookie.

In our integration tests for JSDOM, this code also causes a failure in their Web Platform Test suite around passing cookies to Websocket connections. Testing the behavior for this in various browsers showed inconsistent results which I'll summarize below:

| Browser | HTTP → WSS | HTTPS → WSS |
|---------|------------|-------------|
| Chrome  | Fail       | Pass        |
| Firefox | Pass       | Pass        |
| Safari  | Fail       | Pass        |
| Edge    | Fail       | Pass        |

As it's unclear what the correct behavior should be here, I think we should revert this check to restore the previous behavior in https://github.com/salesforce/tough-cookie/blob/v5.1.2/lib/cookie/cookieJar.ts#L595 to what RFC6265 defines.
colincasey added a commit to colincasey/jsdom that referenced this pull request Jul 24, 2025
The upcoming release of `tough-cookie` contains a [breaking change](salesforce/tough-cookie#498) for how `Secure` cookies are treated in secure contexts such as `localhost`. This PR updates the cookie processing tests with:
- A cookie jar configured to simulate an insecure context to match the expected behavior of the `http`-based server tests
- A correction of the `https`-based server test which should allow for `Secure` cookies
domenic pushed a commit to colincasey/jsdom that referenced this pull request Aug 25, 2025
The upcoming release of `tough-cookie` contains a [breaking change](salesforce/tough-cookie#498) for how `Secure` cookies are treated in secure contexts such as `localhost`. This PR updates the cookie processing tests with:
- A cookie jar configured to simulate an insecure context to match the expected behavior of the `http`-based server tests
- A correction of the `https`-based server test which should allow for `Secure` cookies
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Secure; Flag should be ignored when sending to 'localhost'

4 participants