wip

Author: jacekradko

packages/backend/src/constants.ts

@@ -21,6 +21,7 @@ const Cookies = {
   Handshake: '__clerk_handshake',
   DevBrowser: '__clerk_db_jwt',
   RedirectCount: '__clerk_redirect_count',
+  HandshakeFormat: '__clerk_handshake_format',
   HandshakeNonce: '__clerk_handshake_nonce',
 } as const;
 
@@ -34,6 +35,7 @@ const QueryParameters = {
   HandshakeHelp: '__clerk_help',
   LegacyDevBrowser: '__dev_session',
   HandshakeReason: '__clerk_hs_reason',
+  HandshakeFormat: Cookies.HandshakeFormat,
   HandshakeNonce: Cookies.HandshakeNonce,
 } as const;
 

packages/backend/src/tokens/authenticateContext.ts

@@ -25,6 +25,7 @@ interface AuthenticateContext extends AuthenticateRequestOptions {
   clientUat: number;
   // handshake-related values
   devBrowserToken: string | undefined;
+  handshakeFormat: 'nonce' | 'token' | undefined;
   handshakeNonce: string | undefined;
   handshakeToken: string | undefined;
   handshakeRedirectLoopCounter: number;

packages/backend/src/tokens/handshake.ts

@@ -146,6 +146,11 @@ export class HandshakeService {
     );
     url.searchParams.append(constants.QueryParameters.HandshakeReason, reason);
 
+    // Include handshakeFormat preference if specified
+    if (this.authenticateContext.handshakeFormat) {
+      url.searchParams.append(constants.QueryParameters.HandshakeFormat, this.authenticateContext.handshakeFormat);
+    }
+
     if (this.authenticateContext.instanceType === 'development' && this.authenticateContext.devBrowserToken) {
       url.searchParams.append(constants.QueryParameters.DevBrowser, this.authenticateContext.devBrowserToken);
     }

packages/backend/src/tokens/types.ts

@@ -45,6 +45,14 @@ export type AuthenticateRequestOptions = {
    * If the activation can't be performed, either because an organization doesn't exist or the user lacks access, the active organization in the session won't be changed. Ultimately, it's the responsibility of the page to verify that the resources are appropriate to render given the URL and handle mismatches appropriately (e.g., by returning a 404).
    */
   organizationSyncOptions?: OrganizationSyncOptions;
+  /**
+   * Specifies the handshake format to be used during OAuth authentication flows.
+   * When set to 'nonce', the backend signals to the frontend that it can handle nonce-based handshakes
+   * during OAuth flow resolution, which is more secure for certain environments.
+   *
+   * @default 'token'
+   */
+  handshakeFormat?: 'nonce' | 'token';
   /**
    * @internal
    */

packages/clerk-js/src/core/resources/SignIn.ts

@@ -230,7 +230,7 @@ export class SignIn extends BaseResource implements SignInResource {
     params: AuthenticateWithRedirectParams,
     navigateCallback: (url: URL | string) => void,
   ): Promise<void> => {
-    const { strategy, redirectUrl, redirectUrlComplete, identifier, handshakeFormat } = params || {};
+    const { strategy, redirectUrl, redirectUrlComplete, identifier } = params || {};
 
     const { firstFactorVerification } =
       (strategy === 'saml' || strategy === 'enterprise_sso') && this.id

packages/express/src/authenticateRequest.ts

@@ -12,7 +12,7 @@ import { incomingMessageToRequest, loadApiEnv, loadClientEnv } from './utils';
 
 export const authenticateRequest = (opts: AuthenticateRequestParams) => {
   const { clerkClient, request, options } = opts;
-  const { jwtKey, authorizedParties, audience } = options || {};
+  const { jwtKey, authorizedParties, audience, handshakeFormat } = options || {};
 
   const clerkRequest = createClerkRequest(incomingMessageToRequest(request));
   const env = { ...loadApiEnv(), ...loadClientEnv() };
@@ -46,6 +46,7 @@ export const authenticateRequest = (opts: AuthenticateRequestParams) => {
     isSatellite,
     domain,
     signInUrl,
+    handshakeFormat,
   });
 };
 

packages/react-router/src/ssr/authenticateRequest.ts

@@ -11,7 +11,7 @@ export async function authenticateRequest(
   opts: AuthenticateRequestOptions,
 ): Promise<SignedInState | SignedOutState> {
   const { request } = args;
-  const { audience, authorizedParties } = opts;
+  const { audience, authorizedParties, handshakeFormat } = opts;
 
   const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey } = opts;
   const { signInUrl, #Url, afterSignInUrl, after#Url } = opts;
@@ -32,6 +32,7 @@ export async function authenticateRequest(
     #Url,
     afterSignInUrl,
     after#Url,
+    handshakeFormat,
   });
 
   const locationHeader = requestState.headers.get(constants.Headers.Location);

packages/remix/src/ssr/authenticateRequest.ts

@@ -11,7 +11,7 @@ export async function authenticateRequest(
   opts: AuthenticateRequestOptions,
 ): Promise<SignedInState | SignedOutState> {
   const { request } = args;
-  const { audience, authorizedParties } = opts;
+  const { audience, authorizedParties, handshakeFormat } = opts;
 
   const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey } = opts;
   const { signInUrl, #Url, afterSignInUrl, after#Url } = opts;
@@ -32,6 +32,7 @@ export async function authenticateRequest(
     #Url,
     afterSignInUrl,
     after#Url,
+    handshakeFormat,
   });
 
   const locationHeader = requestState.headers.get(constants.Headers.Location);

packages/tanstack-react-start/src/server/authenticateRequest.ts

@@ -10,7 +10,7 @@ export async function authenticateRequest(
   request: Request,
   opts: AuthenticateRequestOptions,
 ): Promise<SignedInState | SignedOutState> {
-  const { audience, authorizedParties } = opts;
+  const { audience, authorizedParties, handshakeFormat } = opts;
 
   const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey } = opts;
   const { signInUrl, #Url, afterSignInUrl, after#Url } = opts;
@@ -31,6 +31,7 @@ export async function authenticateRequest(
     #Url,
     afterSignInUrl,
     after#Url,
+    handshakeFormat,
   });
 
   const locationHeader = requestState.headers.get(constants.Headers.Location);