fix(backend,fastify): Skip handshake resolution for non-navigation requests when opted out

.changeset/backend-internal-enable-handshake.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add internal `__internal_resolveHandshakeOnlyForNavigation` option to `authenticateRequest()`.

.changeset/fastify-delegate-handshake-opt-out.md

@@ -0,0 +1,5 @@
+---
+'@clerk/fastify': patch
+---
+
+`__internal_enableHandshake` now delegates to `@clerk/backend`.

packages/backend/src/tokens/__tests__/request.test.ts

@@ -1,6 +1,7 @@
 import { http, HttpResponse } from 'msw';
 import { afterEach, beforeEach, describe, expect, it, test, vi } from 'vitest';
 
+import type { ApiClient } from '../../api';
 import { MachineTokenVerificationErrorCode, TokenVerificationErrorReason } from '../../errors';
 import {
   mockExpiredJwt,
@@ -21,6 +22,7 @@ import { signJwt } from '../../jwt/signJwt';
 import { server } from '../../mock-server';
 import type { AuthReason } from '../authStatus';
 import { AuthErrorReason, AuthStatus } from '../authStatus';
+import { HandshakeService } from '../handshake';
 import { JWT_CATEGORY_JWT_TEMPLATE } from '../jwtCategories';
 import { OrganizationMatcher } from '../organizationMatcher';
 import { authenticateRequest, RefreshTokenErrorReason } from '../request';
@@ -2467,4 +2469,191 @@ describe('tokens.authenticateRequest(options)', () => {
       expect(requestState).toBeSignedOut({ reason: AuthErrorReason.SessionTokenIATBeforeClientUAT });
     });
   });
+
+  describe('__internal_resolveHandshakeOnlyForNavigation', () => {
+    const fetchHeaders = { 'sec-fetch-dest': 'empty', accept: '*/*' };
+
+    const mockOptionsWithHandshakePayload = (overrides: Partial<AuthenticateRequestOptions> = {}) => {
+      const getHandshakePayload = vi.fn().mockResolvedValue({ directives: [`__session=${mockJwt}; Path=/`] });
+      const options = mockOptions({
+        publishableKey: PK_LIVE,
+        apiClient: { clients: { getHandshakePayload } } as unknown as ApiClient,
+        ...overrides,
+      });
+      return { options, getHandshakePayload };
+    };
+
+    beforeEach(() => {
+      server.use(
+        http.get('https://api.clerk.test/v1/jwks', () => {
+          return HttpResponse.json(mockJwks);
+        }),
+      );
+    });
+
+    test('skips the payload exchange on a fetch request with a stale nonce and authenticates from the session cookie', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+      });
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies(fetchHeaders, {
+          __clerk_handshake_nonce: 'stale',
+          __client_uat: '12345',
+          __session: mockJwt,
+        }),
+        options,
+      );
+
+      expect(getHandshakePayload).not.toHaveBeenCalled();
+      expect(requestState).toBeSignedIn();
+      expect(requestState.headers.get('location')).toBeNull();
+    });
+
+    test('skips the payload exchange on a POST request with a stale nonce', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+      });
+
+      const requestState = await authenticateRequest(
+        new Request('http://clerk.com/path', {
+          method: 'POST',
+          headers: {
+            ...defaultHeaders,
+            cookie: `__clerk_handshake_nonce=stale;__client_uat=12345;__session=${mockJwt}`,
+          },
+        }),
+        options,
+      );
+
+      expect(getHandshakePayload).not.toHaveBeenCalled();
+      expect(requestState).toBeSignedIn();
+    });
+
+    test('returns signed out without a payload exchange on a fetch request with a stale nonce and no session', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+      });
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies(fetchHeaders, { __clerk_handshake_nonce: 'stale', __client_uat: '12345' }),
+        options,
+      );
+
+      expect(getHandshakePayload).not.toHaveBeenCalled();
+      expect(requestState).toBeSignedOut({ reason: AuthErrorReason.ClientUATWithoutSessionToken });
+      expect(requestState.headers.get('location')).toBeNull();
+    });
+
+    test('still exchanges the payload on a navigation request with a nonce', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+      });
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies({}, { __clerk_handshake_nonce: 'fresh', __client_uat: '12345' }),
+        options,
+      );
+
+      expect(getHandshakePayload).toHaveBeenCalledWith({ nonce: 'fresh' });
+      expect(requestState).toBeSignedIn();
+    });
+
+    test('still redirects a development navigation request to the dev browser handshake', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+        publishableKey: PK_TEST,
+        secretKey: 'test_deadbeef',
+      });
+
+      const requestState = await authenticateRequest(mockRequestWithCookies(), options);
+
+      expect(getHandshakePayload).not.toHaveBeenCalled();
+      expect(requestState).toMatchHandshake({ reason: AuthErrorReason.DevBrowserMissing });
+    });
+
+    test('still resolves the nonce on a development navigation request returning from the handshake', async () => {
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+        publishableKey: PK_TEST,
+        secretKey: 'test_deadbeef',
+      });
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies({}, { __clerk_handshake_nonce: 'fresh' }),
+        options,
+      );
+
+      expect(getHandshakePayload).toHaveBeenCalledTimes(1);
+      expect(requestState).toBeSignedIn();
+    });
+
+    test('ignores a stale cookie-transport handshake token on a fetch request without logging', async () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const { options } = mockOptionsWithHandshakePayload({ __internal_resolveHandshakeOnlyForNavigation: true });
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies(fetchHeaders, {
+          __clerk_handshake: 'not-a-jwt',
+          __client_uat: '12345',
+          __session: mockJwt,
+        }),
+        options,
+      );
+
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(requestState).toBeSignedIn();
+    });
+
+    test('by default logs a resolution error for a stale cookie-transport handshake token on a fetch request', async () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const { options } = mockOptionsWithHandshakePayload();
+
+      const requestState = await authenticateRequest(
+        mockRequestWithCookies(fetchHeaders, {
+          __clerk_handshake: 'not-a-jwt',
+          __client_uat: '12345',
+          __session: mockJwt,
+        }),
+        options,
+      );
+
+      expect(errorSpy).toHaveBeenCalledWith('Clerk: unable to resolve handshake:', expect.anything());
+      expect(requestState).toBeSignedIn();
+    });
+
+    test.each([
+      ['omitted', {}],
+      ['false', { __internal_resolveHandshakeOnlyForNavigation: false }],
+    ])(
+      'when the option is %s the eligibility check is never consulted and the payload is exchanged',
+      async (_, flag) => {
+        const eligibilitySpy = vi.spyOn(HandshakeService.prototype, 'isRequestEligibleForHandshake');
+        const { options, getHandshakePayload } = mockOptionsWithHandshakePayload(flag);
+
+        await authenticateRequest(
+          mockRequestWithCookies(fetchHeaders, { __clerk_handshake_nonce: 'fresh', __client_uat: '12345' }),
+          options,
+        );
+
+        expect(eligibilitySpy).not.toHaveBeenCalled();
+        expect(getHandshakePayload).toHaveBeenCalledTimes(1);
+      },
+    );
+
+    test('only an explicit true consults the eligibility check', async () => {
+      const eligibilitySpy = vi.spyOn(HandshakeService.prototype, 'isRequestEligibleForHandshake');
+      const { options, getHandshakePayload } = mockOptionsWithHandshakePayload({
+        __internal_resolveHandshakeOnlyForNavigation: true,
+      });
+
+      await authenticateRequest(
+        mockRequestWithCookies(fetchHeaders, { __clerk_handshake_nonce: 'fresh', __client_uat: '12345' }),
+        options,
+      );
+
+      expect(eligibilitySpy).toHaveBeenCalled();
+      expect(getHandshakePayload).not.toHaveBeenCalled();
+    });
+  });
 });

packages/backend/src/tokens/request.ts

@@ -461,8 +461,14 @@ export const authenticateRequest: AuthenticateRequest = (async (
 
     /**
      * If we have a handshakeToken, resolve the handshake and attempt to return a definitive signed in or signed out state.
+     * With `__internal_resolveHandshakeOnlyForNavigation`, requests that are not eligible for a handshake redirect
+     * skip this, so a stale handshake cookie does not trigger a failing payload exchange.
      */
-    if (authenticateContext.handshakeNonce || authenticateContext.handshakeToken) {
+    const hasHandshakeToken = authenticateContext.handshakeNonce || authenticateContext.handshakeToken;
+    const canResolveHandshake =
+      !authenticateContext.__internal_resolveHandshakeOnlyForNavigation ||
+      handshakeService.isRequestEligibleForHandshake();
+    if (hasHandshakeToken && canResolveHandshake) {
       try {
         return await handshakeService.resolveHandshake();
       } catch (error) {

packages/backend/src/tokens/types.ts

@@ -86,6 +86,17 @@ export type AuthenticateRequestOptions = {
    * @default false
    */
   satelliteAutoSync?: boolean;
+  /**
+   * When `true`, handshake payload resolution only runs for requests that are eligible for a
+   * handshake redirect. Requests that are not eligible ignore any handshake cookie or query param,
+   * so a stale handshake nonce no longer triggers a failing Backend API call on every request.
+   * Eligible requests still resolve and still redirect, so development instances keep working.
+   * Intended for API-only backends that cannot return `Set-Cookie` headers to the browser.
+   *
+   * @internal
+   * @default false
+   */
+  __internal_resolveHandshakeOnlyForNavigation?: boolean;
 } & VerifyTokenOptions;
 
 /**

packages/fastify/src/__tests__/withClerkMiddleware.handshake.test.ts

@@ -0,0 +1,127 @@
+import type { AddressInfo } from 'node:net';
+
+import Fastify from 'fastify';
+import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from 'vitest';
+
+import { clerkPlugin } from '../index';
+import type { ClerkFastifyOptions } from '../types';
+
+// Runs the real @clerk/backend against a local stand-in for the Backend API.
+const PK_LIVE = 'pk_live_Y2xlcmsuaW5zcGlyZWQucHVtYS03NC5sY2wuZGV2JA';
+const PK_TEST = 'pk_test_Y2xlcmsuaW5zcGlyZWQucHVtYS03NC5sY2wuZGV2JA';
+
+const payloadRequests: string[] = [];
+const fakeBackendApi = Fastify();
+fakeBackendApi.get('/v1/clients/handshake_payload', (request, reply) => {
+  payloadRequests.push(request.url);
+  reply.code(404).send({ errors: [{ code: 'resource_not_found', message: 'not found' }] });
+});
+
+let apiUrl = '';
+
+beforeAll(async () => {
+  await fakeBackendApi.listen({ port: 0, host: '127.0.0.1' });
+  apiUrl = `http://127.0.0.1:${(fakeBackendApi.server.address() as AddressInfo).port}`;
+});
+
+afterAll(async () => {
+  await fakeBackendApi.close();
+});
+
+afterEach(() => {
+  payloadRequests.length = 0;
+  vi.restoreAllMocks();
+});
+
+const buildApp = async (pluginOptions: Partial<ClerkFastifyOptions>) => {
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  const app = Fastify();
+  await app.register(clerkPlugin, { apiUrl, ...pluginOptions });
+  app.get('/api/me', (_request, reply) => {
+    reply.send({
+      status: reply.getHeader('x-clerk-auth-status'),
+      reason: reply.getHeader('x-clerk-auth-reason'),
+    });
+  });
+  return app;
+};
+
+const production = { secretKey: 'sk_live_deadbeef', publishableKey: PK_LIVE };
+const development = { secretKey: 'sk_test_deadbeef', publishableKey: PK_TEST };
+
+const fetchHeaders = { 'sec-fetch-dest': 'empty', accept: '*/*' };
+const navigationHeaders = { 'sec-fetch-dest': 'document', accept: 'text/html' };
+
+describe('clerkPlugin handshake handling (real @clerk/backend)', () => {
+  test('by default a stale nonce on a fetch request is exchanged with the Backend API', async () => {
+    const app = await buildApp(production);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/me',
+      headers: { ...fetchHeaders, cookie: '__clerk_handshake_nonce=stale; __client_uat=12345' },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(payloadRequests).toHaveLength(1);
+    expect(response.json()).toEqual({ status: 'signed-out', reason: 'session-token-missing' });
+  });
+
+  test('with __internal_enableHandshake: false a stale nonce on a fetch request is ignored', async () => {
+    const app = await buildApp({ ...production, __internal_enableHandshake: false });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/me',
+      headers: { ...fetchHeaders, cookie: '__clerk_handshake_nonce=stale; __client_uat=12345' },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(payloadRequests).toHaveLength(0);
+    expect(response.json()).toEqual({ status: 'signed-out', reason: 'client-uat-but-no-session-token' });
+  });
+
+  test('with __internal_enableHandshake: false a stale nonce on a POST request is ignored', async () => {
+    const app = await buildApp({ ...production, __internal_enableHandshake: false });
+    app.post('/api/submit', (_request, reply) => {
+      reply.send({ status: reply.getHeader('x-clerk-auth-status') });
+    });
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/submit',
+      headers: { ...navigationHeaders, cookie: '__clerk_handshake_nonce=stale; __client_uat=12345' },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(payloadRequests).toHaveLength(0);
+    expect(response.json()).toEqual({ status: 'signed-out' });
+  });
+
+  test('with __internal_enableHandshake: false a development navigation still redirects to the dev browser handshake', async () => {
+    const app = await buildApp({ ...development, __internal_enableHandshake: false });
+
+    const response = await app.inject({ method: 'GET', url: '/api/me', headers: navigationHeaders });
+
+    expect(response.statusCode).toBe(307);
+    expect(response.headers.location).toContain('/v1/client/handshake');
+    expect(response.headers['x-clerk-auth-reason']).toBe('dev-browser-missing');
+    expect(payloadRequests).toHaveLength(0);
+  });
+
+  test('with __internal_enableHandshake: false a development navigation returning from the handshake still resolves the nonce', async () => {
+    const app = await buildApp({ ...development, __internal_enableHandshake: false });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/me?__clerk_handshake_nonce=fresh',
+      headers: navigationHeaders,
+    });
+
+    expect(payloadRequests).toHaveLength(1);
+    expect(payloadRequests[0]).toContain('nonce=fresh');
+    // Development resolution redirects to the same URL with the handshake params removed.
+    expect(response.statusCode).toBe(307);
+    expect(response.headers.location).not.toContain('__clerk_handshake_nonce');
+  });
+});