Merge branch '17.1' into feat/support-directory-import-esm

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [17.1.0] - 2024-04-25
+
+-   Added `olderCookieDomain` config option in the session recipe. This will allow users to clear cookies from the older domain when the `cookieDomain` is changed.
+-   If `verifySession` detects multiple access tokens in the request, it will return a 401 error, prompting a refresh, even if one of the tokens is valid.
+-   `refreshPOST` (`/auth/session/refresh` by default) API changes:
+    -   now returns 500 error if multiple access tokens are present in the request and `config.olderCookieDomain` is not set.
+    -   now clears the access token cookie if it was called without a refresh token (if an access token cookie exists and if using cookie-based sessions).
+    -   now clears cookies from the old domain if `olderCookieDomain` is specified and multiple refresh/access token cookies exist, without updating the front-token or any of the tokens.
+    -   now a 200 response may not include new session tokens.
+
+### Rationale
+
+This update addresses an edge case where changing the `cookieDomain` config on the server can lead to session integrity issues. For instance, if the API server URL is 'api.example.com' with a cookie domain of '.example.com', and the server updates the cookie domain to 'api.example.com', the client may retain cookies with both '.example.com' and 'api.example.com' domains, resulting in multiple sets of session token cookies existing.
+
+Previously, verifySession would select one of the access tokens from the incoming request. If it chose the older cookie, it would return a 401 status code, prompting a refresh request. However, the `refreshPOST` API would then set new session token cookies with the updated `cookieDomain`, but older cookies will persist, leading to repeated 401 errors and refresh loops.
+
+With this update, verifySession will return a 401 error if it detects multiple access tokens in the request, prompting a refresh request. The `refreshPOST` API will clear cookies from the old domain if `olderCookieDomain` is specified in the configuration, then return a 200 status. If `olderCookieDomain` is not configured, the `refreshPOST` API will return a 500 error with a message instructing to set `olderCookieDomain`.
+
+**Example:**
+
+-   `apiDomain`: 'api.example.com'
+-   `cookieDomain`: 'api.example.com'
+
+**Flow:**
+
+1. After authentication, the frontend has cookies set with `domain=api.example.com`, but the access token has expired.
+2. The server updates `cookieDomain` to `.example.com`.
+3. An API call requiring session with an expired access token (cookie with `domain=api.example.com`) results in a 401 response.
+4. The frontend attempts to refresh the session, generating a new access token saved with `domain=.example.com`.
+5. The original API call is retried, but because it sends both the old and new cookies, it again results in a 401 response.
+6. The frontend tries to refresh the session with multiple access tokens:
+    - If `olderCookieDomain` is not set, the refresh fails with a 500 error.
+        - The user remains stuck until they clear cookies manually or `olderCookieDomain` is set.
+    - If `olderCookieDomain` is set, the refresh clears the older cookie, returning a 200 response.
+        - The frontend retries the original API call, sending only the new cookie (`domain=.example.com`), resulting in a successful request.
+
 ## [17.0.5] - 2024-04-25
 
 -   Support for websiteDomain / apiDomain ending with `.local`: https://github.com/supertokens/supertokens-node/issues/823

docs/interfaces/framework_hapi.SessionRequest.html

@@ -89,7 +89,7 @@
 </div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="server" class="tsd-anchor"></a><h3 class="tsd-anchor-link">server<a href="#server" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">server<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Server</span></div><aside class="tsd-sources"><p>Inherited from Request.server</p><ul><li>Defined in node_modules/@types/hapi__hapi/index.d.ts:554</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>Access: read only and the public server interface.
 The server object.</p>
-</div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="session" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagOptional">Optional</span> session<a href="#session" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">session<span class="tsd-signature-symbol">?:</span> <a href="recipe_session.SessionContainer.html" class="tsd-signature-type" data-tsd-kind="Interface">SessionContainer</a></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/supertokens/supertokens-node/blob/29fc4fcb/lib/ts/framework/hapi/framework.ts#L276">lib/ts/framework/hapi/framework.ts:276</a></li></ul></aside></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="state" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagReadonly">Readonly</span> state<a href="#state" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">state<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Dictionary</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">&gt;</span></div><aside class="tsd-sources"><p>Inherited from Request.state</p><ul><li>Defined in node_modules/@types/hapi__hapi/index.d.ts:559</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
+</div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="session" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagOptional">Optional</span> session<a href="#session" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">session<span class="tsd-signature-symbol">?:</span> <a href="recipe_session.SessionContainer.html" class="tsd-signature-type" data-tsd-kind="Interface">SessionContainer</a></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/supertokens/supertokens-node/blob/27f3642e/lib/ts/framework/hapi/framework.ts#L278">lib/ts/framework/hapi/framework.ts:278</a></li></ul></aside></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="state" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagReadonly">Readonly</span> state<a href="#state" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">state<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Dictionary</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">&gt;</span></div><aside class="tsd-sources"><p>Inherited from Request.state</p><ul><li>Defined in node_modules/@types/hapi__hapi/index.d.ts:559</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>An object containing parsed HTTP state information (cookies) where each key is the cookie name and value is the matching cookie content after processing using any registered cookie definition.</p>
 </div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="url" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagReadonly">Readonly</span> url<a href="#url" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">url<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">URL</span></div><aside class="tsd-sources"><p>Inherited from Request.url</p><ul><li>Defined in node_modules/@types/hapi__hapi/index.d.ts:564</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>The parsed request URI.</p>

docs/interfaces/framework_koa.SessionContext.html

@@ -81,7 +81,7 @@
 </div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="secure" class="tsd-anchor"></a><h3 class="tsd-anchor-link">secure<a href="#secure" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">secure<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">boolean</span></div><aside class="tsd-sources"><p>Inherited from Context.secure</p><ul><li>Defined in node_modules/@types/koa/index.d.ts:142</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>Short-hand for:</p>
 </div><div><p>   this.protocol == &#39;https&#39;</p>
-</div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="session" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagOptional">Optional</span> session<a href="#session" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">session<span class="tsd-signature-symbol">?:</span> <a href="recipe_session.SessionContainer.html" class="tsd-signature-type" data-tsd-kind="Interface">SessionContainer</a></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/supertokens/supertokens-node/blob/29fc4fcb/lib/ts/framework/koa/framework.ts#L160">lib/ts/framework/koa/framework.ts:160</a></li></ul></aside></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="socket" class="tsd-anchor"></a><h3 class="tsd-anchor-link">socket<a href="#socket" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">socket<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Socket</span></div><aside class="tsd-sources"><p>Inherited from Context.socket</p><ul><li>Defined in node_modules/@types/koa/index.d.ts:125</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
+</div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="session" class="tsd-anchor"></a><h3 class="tsd-anchor-link"><span class="tsd-flag ts-flagOptional">Optional</span> session<a href="#session" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">session<span class="tsd-signature-symbol">?:</span> <a href="recipe_session.SessionContainer.html" class="tsd-signature-type" data-tsd-kind="Interface">SessionContainer</a></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/supertokens/supertokens-node/blob/27f3642e/lib/ts/framework/koa/framework.ts#L160">lib/ts/framework/koa/framework.ts:160</a></li></ul></aside></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="socket" class="tsd-anchor"></a><h3 class="tsd-anchor-link">socket<a href="#socket" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">socket<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Socket</span></div><aside class="tsd-sources"><p>Inherited from Context.socket</p><ul><li>Defined in node_modules/@types/koa/index.d.ts:125</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>Return the request socket.</p>
 </div></div></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface tsd-is-inherited tsd-is-external"><a id="stale" class="tsd-anchor"></a><h3 class="tsd-anchor-link">stale<a href="#stale" aria-label="Permalink" class="tsd-anchor-icon"><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5"></path></svg></a></h3><div class="tsd-signature tsd-kind-icon">stale<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">boolean</span></div><aside class="tsd-sources"><p>Inherited from Context.stale</p><ul><li>Defined in node_modules/@types/koa/index.d.ts:115</li></ul></aside><div class="tsd-comment tsd-typography"><div class="lead">
 <p>Check if the request is stale, aka