feat(backend,clerk-js,shared): Introduce suffixed / un-suffixed cookies

.changeset/calm-readers-call.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+'@clerk/shared': minor
+---
+
+Support reading / writing / removing suffixed/un-suffixed cookies from `@clerk/clerk-js` and `@clerk/backend`.
+Everyone of `__session`, `__clerk_db_jwt` and `__client_uat` cookies will also be set with a suffix to support multiple apps on the same domain.

integration/tests/handshake.test.ts

@@ -164,7 +164,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -185,7 +185,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -207,7 +209,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -230,7 +234,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -254,7 +258,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -278,7 +282,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://example.com/clerk/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -300,7 +304,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://example.com/clerk/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://example.com/clerk/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -324,7 +330,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -346,7 +352,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://clerk.example.com/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://clerk.example.com/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -367,7 +375,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}${devBrowserQuery}`,
+ )}&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -386,7 +394,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -485,7 +495,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://clerk.example.com/v1/client/handshake?redirect_url=${encodeURIComponent(app.serverUrl + '/')}`,
+ `https://clerk.example.com/v1/client/handshake?redirect_url=${encodeURIComponent(
+ app.serverUrl + '/',
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -520,7 +532,9 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(`${app.serverUrl}/`)}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
+ `${app.serverUrl}/`,
+ )}&suffixed_cookies=true`,
  );
  });
 
@@ -543,7 +557,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}hello%3Ffoo%3Dbar${devBrowserQuery}`,
+ )}hello%3Ffoo%3Dbar&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -566,7 +580,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}hello%3Ffoo%3Dbar`,
+ )}hello%3Ffoo%3Dbar&suffixed_cookies=true`,
  );
  });
 
@@ -589,7 +603,7 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%2Fhello%3Ffoo%3Dbar${devBrowserQuery}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%2Fhello%3Ffoo%3Dbar&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -612,7 +626,7 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%2Fhello%3Ffoo%3Dbar`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%2Fhello%3Ffoo%3Dbar&suffixed_cookies=true`,
  );
  });
 
@@ -635,7 +649,7 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%3A3213%2Fhello%3Ffoo%3Dbar${devBrowserQuery}`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%3A3213%2Fhello%3Ffoo%3Dbar&suffixed_cookies=true${devBrowserQuery}`,
  );
  });
 
@@ -658,7 +672,7 @@ test.describe('Client handshake @generic', () => {
  });
  expect(res.status).toBe(307);
  expect(res.headers.get('location')).toBe(
- `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%3A3213%2Fhello%3Ffoo%3Dbar`,
+ `https://${config.pkHost}/v1/client/handshake?redirect_url=https%3A%2F%2Fexample.com%3A3213%2Fhello%3Ffoo%3Dbar&suffixed_cookies=true`,
  );
  });
 
@@ -787,7 +801,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.headers.get('location')).toBe(
  `https://${config.pkHost}/v1/client/handshake?redirect_url=${encodeURIComponent(
  `${app.serverUrl}/`,
- )}&__clerk_db_jwt=asdf`,
+ )}&suffixed_cookies=true&__clerk_db_jwt=asdf`,
  );
  });
 

packages/backend/src/api/request.ts

@@ -6,7 +6,7 @@ import { API_URL, API_VERSION, constants, USER_AGENT } from '../constants';
 // DO NOT CHANGE: Runtime needs to be imported as a default export so that we can stub its dependencies with Sinon.js
 // For more information refer to https://sinonjs.org/how-to/stub-dependency/
 import runtime from '../runtime';
-import { assertValidSecretKey } from '../util/assertValidSecretKey';
+import { assertValidSecretKey } from '../util/optionsAssertions';
 import { joinPaths } from '../util/path';
 import { deserialize } from './resources/Deserializer';
 

packages/backend/src/constants.ts

@@ -19,6 +19,7 @@ const Cookies = {
  ClientUat: '__client_uat',
  Handshake: '__clerk_handshake',
  DevBrowser: '__clerk_db_jwt',
+ SuffixedCookies: '__clerk_suffixed_cookies',
 } as const;
 
 const QueryParameters = {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,7 @@
+import { parsePublishableKey } from '@clerk/shared/keys';
+
 import { constants } from '../constants';
+import { assertValidPublishableKey } from '../util/optionsAssertions';
 import type { ClerkRequest } from './clerkRequest';
 import type { AuthenticateRequestOptions } from './types';
 
@@ -16,13 +19,18 @@ interface AuthenticateContextInterface extends AuthenticateRequestOptions {
  // cookie-based values
  sessionTokenInCookie: string | undefined;
  clientUat: number;
+ suffixedCookies: boolean;
  // handshake-related values
  devBrowserToken: string | undefined;
  handshakeToken: string | undefined;
  // url derived from headers
  clerkUrl: URL;
  // cookie or header session token
  sessionToken: string | undefined;
+ // enforce existence of the following props
+ publishableKey: string;
+ instanceType: string;
+ frontendApi: string;
 }
 
 interface AuthenticateContext extends AuthenticateContextInterface {}
@@ -38,45 +46,91 @@ class AuthenticateContext {
  return this.sessionTokenInCookie || this.sessionTokenInHeader;
  }
 
+ private get cookieSuffix() {
+ return this.publishableKey?.split('_').pop();
+ }
+
  public constructor(private clerkRequest: ClerkRequest, options: AuthenticateRequestOptions) {
+ // Even though the options are assigned to this later in this function
+ // we set the publishableKey here because it is being used in cookies/headers/handshake-values
+ // as part of getMultipleAppsCookie
+ this.initPublishableKeyValues(options);
  this.initHeaderValues();
+ // initCookieValues should be used before initHandshakeValues because the it depends on suffixedCookies
  this.initCookieValues();
  this.initHandshakeValues();
  Object.assign(this, options);
  this.clerkUrl = this.clerkRequest.clerkUrl;
  }
 
- private initHandshakeValues() {
- this.devBrowserToken =
- this.clerkRequest.clerkUrl.searchParams.get(constants.QueryParameters.DevBrowser) ||
- this.clerkRequest.cookies.get(constants.Cookies.DevBrowser);
- this.handshakeToken =
- this.clerkRequest.clerkUrl.searchParams.get(constants.QueryParameters.Handshake) ||
- this.clerkRequest.cookies.get(constants.Cookies.Handshake);
+ private initPublishableKeyValues(options: AuthenticateRequestOptions) {
+ assertValidPublishableKey(options.publishableKey);
+ this.publishableKey = options.publishableKey;
+
+ const pk = parsePublishableKey(this.publishableKey, {
+ fatal: true,
+ proxyUrl: options.proxyUrl,
+ domain: options.domain,
+ });
+ this.instanceType = pk.instanceType;
+ this.frontendApi = pk.frontendApi;
  }
 
  private initHeaderValues() {
- const get = (name: string) => this.clerkRequest.headers.get(name) || undefined;
- this.sessionTokenInHeader = this.stripAuthorizationHeader(get(constants.Headers.Authorization));
- this.origin = get(constants.Headers.Origin);
- this.host = get(constants.Headers.Host);
- this.forwardedHost = get(constants.Headers.ForwardedHost);
- this.forwardedProto = get(constants.Headers.CloudFrontForwardedProto) || get(constants.Headers.ForwardedProto);
- this.referrer = get(constants.Headers.Referrer);
- this.userAgent = get(constants.Headers.UserAgent);
- this.secFetchDest = get(constants.Headers.SecFetchDest);
- this.accept = get(constants.Headers.Accept);
+ this.sessionTokenInHeader = this.stripAuthorizationHeader(this.getHeader(constants.Headers.Authorization));
+ this.origin = this.getHeader(constants.Headers.Origin);
+ this.host = this.getHeader(constants.Headers.Host);
+ this.forwardedHost = this.getHeader(constants.Headers.ForwardedHost);
+ this.forwardedProto =
+  this.getHeader(constants.Headers.CloudFrontForwardedProto) || this.getHeader(constants.Headers.ForwardedProto);
+ this.referrer = this.getHeader(constants.Headers.Referrer);
+ this.userAgent = this.getHeader(constants.Headers.UserAgent);
+ this.secFetchDest = this.getHeader(constants.Headers.SecFetchDest);
+ this.accept = this.getHeader(constants.Headers.Accept);
  }
 
  private initCookieValues() {
- const get = (name: string) => this.clerkRequest.cookies.get(name) || undefined;
- this.sessionTokenInCookie = get(constants.Cookies.Session);
- this.clientUat = Number.parseInt(get(constants.Cookies.ClientUat) || '') || 0;
+ // suffixedCookies needs to be set first because it's used in getMultipleAppsCookie
+ this.suffixedCookies = this.getSuffixedCookie(constants.Cookies.SuffixedCookies) === 'true';
+ this.sessionTokenInCookie = this.getSuffixedOrUnSuffixedCookie(constants.Cookies.Session);
+ this.clientUat = Number.parseInt(this.getSuffixedOrUnSuffixedCookie(constants.Cookies.ClientUat) || '') || 0;
+ }
+
+ private initHandshakeValues() {
+ this.devBrowserToken =
+ this.getQueryParam(constants.QueryParameters.DevBrowser) ||
+ this.getSuffixedOrUnSuffixedCookie(constants.Cookies.DevBrowser);
+ // Using getCookie since we don't suffix the handshake token cookie
+ this.handshakeToken =
+ this.getQueryParam(constants.QueryParameters.Handshake) || this.getCookie(constants.Cookies.Handshake);
  }
 
  private stripAuthorizationHeader(authValue: string | undefined | null): string | undefined {
  return authValue?.replace('Bearer ', '');
  }
+
+ private getQueryParam(name: string) {
+ return this.clerkRequest.clerkUrl.searchParams.get(name);
+ }
+
+ private getHeader(name: string) {
+ return this.clerkRequest.headers.get(name) || undefined;
+ }
+
+ private getCookie(name: string) {
+ return this.clerkRequest.cookies.get(name) || undefined;
+ }
+
+ private getSuffixedCookie(name: string) {
+ return this.getCookie(`${name}_${this.cookieSuffix}`) || undefined;
+ }
+
+ private getSuffixedOrUnSuffixedCookie(cookieName: string) {
+ if (this.suffixedCookies) {
+ return this.getSuffixedCookie(cookieName);
+ }
+ return this.getCookie(cookieName);
+ }
 }
 
 export type { AuthenticateContext };

packages/backend/src/tokens/cookie.ts

@@ -0,0 +1,7 @@
+export const getCookieName = (cookieDirective: string): string => {
+ return cookieDirective.split(';')[0]?.split('=')[0];
+};
+
+export const getCookieValue = (cookieDirective: string): string => {
+ return cookieDirective.split(';')[0]?.split('=')[1];
+};