feat: oauth hadnshake nonce support

Author: jacekradko

packages/backend/src/constants.ts

@@ -4,6 +4,7 @@ export const API_VERSION = 'v1';
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
 export const SUPPORTED_BAPI_VERSION = '2025-04-10';
+export const SUPPORTED_HANDSHAKE_FORMAT = 'nonce';
 
 const Attributes = {
   AuthToken: '__clerkAuthToken',
@@ -21,6 +22,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 +36,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

@@ -1,4 +1,4 @@
-import { constants, SUPPORTED_BAPI_VERSION } from '../constants';
+import { constants, SUPPORTED_BAPI_VERSION, SUPPORTED_HANDSHAKE_FORMAT } from '../constants';
 import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import type { VerifyJwtOptions } from '../jwt';
 import { assertHeaderAlgorithm, assertHeaderType } from '../jwt/assertions';
@@ -145,6 +145,7 @@ export class HandshakeService {
       this.authenticateContext.usesSuffixedCookies().toString(),
     );
     url.searchParams.append(constants.QueryParameters.HandshakeReason, reason);
+    url.searchParams.append(constants.QueryParameters.HandshakeFormat, SUPPORTED_HANDSHAKE_FORMAT);
 
     if (this.authenticateContext.instanceType === 'development' && this.authenticateContext.devBrowserToken) {
       url.searchParams.append(constants.QueryParameters.DevBrowser, this.authenticateContext.devBrowserToken);

packages/backend/src/tokens/request.ts

@@ -76,6 +76,23 @@ export async function authenticateRequest(
   const authenticateContext = await createAuthenticateContext(createClerkRequest(request), options);
   assertValidSecretKey(authenticateContext.secretKey);
 
+  /**
+   * Merges headers from the RequestState with a default handshake cookie.
+   * Creates a new Headers object with a nonce cookie and adds all headers from the result.
+   *
+   * @param result - The RequestState containing headers to merge
+   * @returns The RequestState with merged headers
+   */
+  function mergeHeaders(result: RequestState): RequestState {
+    const headers = new Headers();
+    headers.append('Set-Cookie', `${constants.Cookies.HandshakeFormat}=nonce; Path=/; SameSite=Lax;`);
+    for (const [key, value] of result.headers.entries()) {
+      headers.append(key, value);
+    }
+    result.headers = headers;
+    return result;
+  }
+
   if (authenticateContext.isSatellite) {
     assertSignInUrlExists(authenticateContext.signInUrl, authenticateContext.secretKey);
     if (authenticateContext.signInUrl && authenticateContext.origin) {
@@ -533,10 +550,10 @@ export async function authenticateRequest(
   }
 
   if (authenticateContext.sessionTokenInHeader) {
-    return authenticateRequestWithTokenInHeader();
+    return mergeHeaders(await authenticateRequestWithTokenInHeader());
   }
 
-  return authenticateRequestWithTokenInCookie();
+  return mergeHeaders(await authenticateRequestWithTokenInCookie());
 }
 
 /**

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.
+   *
+   * @default 'token'
+   */
+  handshakeFormat?: 'nonce' | 'token';
   /**
    * @internal
    */

packages/types/src/factors.ts

@@ -106,16 +106,19 @@ export type OAuthConfig = OauthFactor & {
   actionCompleteRedirectUrl: string;
   oidcPrompt?: string;
   oidcLoginHint?: string;
+  handshakeFormat?: 'nonce' | 'token';
 };
 
 export type SamlConfig = SamlFactor & {
   redirectUrl: string;
   actionCompleteRedirectUrl: string;
+  handshakeFormat?: 'nonce' | 'token';
 };
 
 export type EnterpriseSSOConfig = EnterpriseSSOFactor & {
   redirectUrl: string;
   actionCompleteRedirectUrl: string;
+  handshakeFormat?: 'nonce' | 'token';
 };
 
 export type PhoneCodeSecondFactorConfig = {

packages/types/src/redirects.ts

@@ -81,6 +81,11 @@ export type AuthenticateWithRedirectParams = {
    * Whether the user has accepted the legal requirements.
    */
   legalAccepted?: boolean;
+
+  /**
+   * Whether to use handshake nonce or handshake token
+   */
+  handshakeFormat?: 'nonce' | 'token';
 };
 
 export type AuthenticateWithPopupParams = AuthenticateWithRedirectParams & { popup: Window | null };

packages/types/src/signIn.ts

@@ -195,6 +195,7 @@ export type SignInCreateParams = (
       identifier?: string;
       oidcPrompt?: string;
       oidcLoginHint?: string;
+      handshakeFormat?: 'nonce' | 'token';
     }
   | {
       strategy: TicketStrategy;