fix(backend): Consider proxyUrl in determining frontendApi URL (#6120)

Author: jacekradko

.changeset/common-beers-read.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add logic to ensure that we consider the proxy_url when creating the frontendApi url.

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

@@ -179,6 +179,8 @@ describe('HandshakeService', () => {
 
     it('should use proxy URL when available', () => {
       mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com';
+      // Simulate what parsePublishableKey does when proxy URL is provided
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com';
       const headers = handshakeService.buildRedirectToHandshake('test-reason');
       const location = headers.get(constants.Headers.Location);
       if (!location) {
@@ -195,6 +197,7 @@ describe('HandshakeService', () => {
 
     it('should handle proxy URL with trailing slash', () => {
       mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com/';
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com/';
       const headers = handshakeService.buildRedirectToHandshake('test-reason');
       const location = headers.get(constants.Headers.Location);
       if (!location) {
@@ -205,6 +208,227 @@ describe('HandshakeService', () => {
       expect(url.hostname).toBe('my-proxy.example.com');
       expect(url.pathname).toBe('/v1/client/handshake');
     });
+
+    it('should handle proxy URL with multiple trailing slashes', () => {
+      mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com//';
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com//';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.hostname).toBe('my-proxy.example.com');
+      expect(url.pathname).toBe('/v1/client/handshake');
+      expect(location).not.toContain('//v1/client/handshake');
+    });
+
+    it('should handle proxy URL with many trailing slashes', () => {
+      mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com///';
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com///';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.hostname).toBe('my-proxy.example.com');
+      expect(url.pathname).toBe('/v1/client/handshake');
+      expect(location).not.toContain('//v1/client/handshake');
+    });
+
+    it('should handle proxy URL without trailing slash', () => {
+      mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com';
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.hostname).toBe('my-proxy.example.com');
+      expect(url.pathname).toBe('/v1/client/handshake');
+    });
+
+    it('should handle proxy URL with path and trailing slashes', () => {
+      mockAuthenticateContext.proxyUrl = 'https://my-proxy.example.com/clerk-proxy//';
+      mockAuthenticateContext.frontendApi = 'https://my-proxy.example.com/clerk-proxy//';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.hostname).toBe('my-proxy.example.com');
+      expect(url.pathname).toBe('/clerk-proxy/v1/client/handshake');
+      expect(location).not.toContain('clerk-proxy//v1/client/handshake');
+    });
+
+    it('should handle non-HTTP frontendApi (domain only)', () => {
+      mockAuthenticateContext.frontendApi = 'api.clerk.com';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.protocol).toBe('https:');
+      expect(url.hostname).toBe('api.clerk.com');
+      expect(url.pathname).toBe('/v1/client/handshake');
+    });
+
+    it('should not include dev browser token in production mode', () => {
+      mockAuthenticateContext.instanceType = 'production';
+      mockAuthenticateContext.devBrowserToken = 'dev-token';
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.searchParams.get(constants.QueryParameters.DevBrowser)).toBeNull();
+    });
+
+    it('should not include dev browser token when not available in development', () => {
+      mockAuthenticateContext.instanceType = 'development';
+      mockAuthenticateContext.devBrowserToken = undefined;
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.searchParams.get(constants.QueryParameters.DevBrowser)).toBeNull();
+    });
+
+    it('should handle usesSuffixedCookies returning false', () => {
+      mockAuthenticateContext.usesSuffixedCookies = vi.fn().mockReturnValue(false);
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toBe('false');
+    });
+
+    it('should include organization sync parameters when organization target is found', () => {
+      // Mock the organization sync methods
+      const mockTarget = { type: 'organization', id: 'org_123' };
+      const mockParams = new Map([
+        ['org_id', 'org_123'],
+        ['org_slug', 'test-org'],
+      ]);
+
+      vi.spyOn(handshakeService as any, 'getOrganizationSyncTarget').mockReturnValue(mockTarget);
+      vi.spyOn(handshakeService as any, 'getOrganizationSyncQueryParams').mockReturnValue(mockParams);
+
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.searchParams.get('org_id')).toBe('org_123');
+      expect(url.searchParams.get('org_slug')).toBe('test-org');
+    });
+
+    it('should not include organization sync parameters when no target is found', () => {
+      vi.spyOn(handshakeService as any, 'getOrganizationSyncTarget').mockReturnValue(null);
+
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      expect(url.searchParams.get('org_id')).toBeNull();
+      expect(url.searchParams.get('org_slug')).toBeNull();
+    });
+
+    it('should handle different handshake reasons', () => {
+      const reasons = ['session-token-expired', 'dev-browser-sync', 'satellite-cookie-needs-syncing'];
+
+      reasons.forEach(reason => {
+        const headers = handshakeService.buildRedirectToHandshake(reason);
+        const location = headers.get(constants.Headers.Location);
+        if (!location) {
+          throw new Error('Location header is missing');
+        }
+        const url = new URL(location);
+
+        expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe(reason);
+      });
+    });
+
+    it('should handle complex clerkUrl with query parameters and fragments', () => {
+      mockAuthenticateContext.clerkUrl = new URL('https://example.com/path?existing=param#fragment');
+
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      const redirectUrl = url.searchParams.get('redirect_url');
+      expect(redirectUrl).toBe('https://example.com/path?existing=param#fragment');
+    });
+
+    it('should create valid URLs with different frontend API formats', () => {
+      const frontendApiFormats = [
+        'api.clerk.com',
+        'https://api.clerk.com',
+        'https://api.clerk.com/',
+        'foo-bar-13.clerk.accounts.dev',
+        'https://foo-bar-13.clerk.accounts.dev',
+        'clerk.example.com',
+        'https://clerk.example.com/proxy-path',
+      ];
+
+      frontendApiFormats.forEach(frontendApi => {
+        mockAuthenticateContext.frontendApi = frontendApi;
+
+        const headers = handshakeService.buildRedirectToHandshake('test-reason');
+        const location = headers.get(constants.Headers.Location);
+
+        expect(location).toBeDefined();
+        if (!location) {
+          throw new Error('Location header should be defined');
+        }
+        expect(() => new URL(location)).not.toThrow();
+
+        const url = new URL(location);
+        // Path should end with '/v1/client/handshake' (may have proxy path prefix)
+        expect(url.pathname).toMatch(/\/v1\/client\/handshake$/);
+        expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
+      });
+    });
+
+    it('should always include required query parameters', () => {
+      const headers = handshakeService.buildRedirectToHandshake('test-reason');
+      const location = headers.get(constants.Headers.Location);
+      if (!location) {
+        throw new Error('Location header is missing');
+      }
+      const url = new URL(location);
+
+      // Verify all required parameters are present
+      expect(url.searchParams.get('redirect_url')).toBeDefined();
+      expect(url.searchParams.get('__clerk_api_version')).toBe('2025-04-10');
+      expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
+      expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
+    });
   });
 
   describe('handleTokenVerificationErrorInDevelopment', () => {
@@ -320,4 +544,59 @@ describe('HandshakeService', () => {
       spy.mockRestore();
     });
   });
+
+  describe('URL construction edge cases', () => {
+    const trailingSlashTestCases = [
+      { input: 'https://example.com', expected: 'https://example.com' },
+      { input: 'https://example.com/', expected: 'https://example.com' },
+      { input: 'https://example.com//', expected: 'https://example.com' },
+      { input: 'https://example.com///', expected: 'https://example.com' },
+      { input: 'https://example.com/path', expected: 'https://example.com/path' },
+      { input: 'https://example.com/path/', expected: 'https://example.com/path' },
+      { input: 'https://example.com/path//', expected: 'https://example.com/path' },
+      { input: 'https://example.com/proxy-path///', expected: 'https://example.com/proxy-path' },
+    ];
+
+    trailingSlashTestCases.forEach(({ input, expected }) => {
+      it(`should correctly handle trailing slashes: "${input}" -> "${expected}"`, () => {
+        const result = input.replace(/\/+$/, '');
+        expect(result).toBe(expected);
+      });
+    });
+
+    it('should construct valid handshake URLs with various proxy configurations', () => {
+      const proxyConfigs = [
+        'https://proxy.example.com',
+        'https://proxy.example.com/',
+        'https://proxy.example.com//',
+        'https://proxy.example.com/clerk',
+        'https://proxy.example.com/clerk/',
+        'https://proxy.example.com/clerk//',
+        'https://api.example.com/v1/clerk///',
+      ];
+
+      proxyConfigs.forEach(proxyUrl => {
+        const isolatedContext = {
+          ...mockAuthenticateContext,
+          proxyUrl: proxyUrl,
+          frontendApi: proxyUrl,
+        } as AuthenticateContext;
+
+        const isolatedHandshakeService = new HandshakeService(isolatedContext, mockOptions, mockOrganizationMatcher);
+
+        const headers = isolatedHandshakeService.buildRedirectToHandshake('test-reason');
+        const location = headers.get(constants.Headers.Location);
+
+        expect(location).toBeDefined();
+        if (!location) {
+          throw new Error('Location header should be defined');
+        }
+        expect(location).toContain('/v1/client/handshake');
+        expect(location).not.toContain('//v1/client/handshake'); // No double slashes
+
+        // Ensure URL is valid
+        expect(() => new URL(location)).not.toThrow();
+      });
+    });
+  });
 });

packages/backend/src/tokens/authenticateContext.ts

@@ -10,31 +10,33 @@ import type { AuthenticateRequestOptions } from './types';
 
 interface AuthenticateContext extends AuthenticateRequestOptions {
   // header-based values
-  tokenInHeader: string | undefined;
-  origin: string | undefined;
-  host: string | undefined;
+  accept: string | undefined;
   forwardedHost: string | undefined;
   forwardedProto: string | undefined;
+  host: string | undefined;
+  origin: string | undefined;
   referrer: string | undefined;
-  userAgent: string | undefined;
   secFetchDest: string | undefined;
-  accept: string | undefined;
+  tokenInHeader: string | undefined;
+  userAgent: string | undefined;
+
   // cookie-based values
-  sessionTokenInCookie: string | undefined;
-  refreshTokenInCookie: string | undefined;
   clientUat: number;
+  refreshTokenInCookie: string | undefined;
+  sessionTokenInCookie: string | undefined;
+
   // handshake-related values
   devBrowserToken: string | undefined;
   handshakeNonce: string | undefined;
-  handshakeToken: string | undefined;
   handshakeRedirectLoopCounter: number;
+  handshakeToken: string | undefined;
 
   // url derived from headers
   clerkUrl: URL;
   // enforce existence of the following props
-  publishableKey: string;
-  instanceType: string;
   frontendApi: string;
+  instanceType: string;
+  publishableKey: string;
 }
 
 /**
@@ -44,6 +46,12 @@ interface AuthenticateContext extends AuthenticateRequestOptions {
  * to perform a handshake.
  */
 class AuthenticateContext implements AuthenticateContext {
+  /**
+   * The original Clerk frontend API URL, extracted from publishable key before proxy URL override.
+   * Used for backend operations like token validation and issuer checking.
+   */
+  private originalFrontendApi: string = '';
+
   /**
    * Retrieves the session token from either the cookie or the header.
    *
@@ -163,6 +171,13 @@ class AuthenticateContext implements AuthenticateContext {
     assertValidPublishableKey(options.publishableKey);
     this.publishableKey = options.publishableKey;
 
+    const originalPk = parsePublishableKey(this.publishableKey, {
+      fatal: true,
+      domain: options.domain,
+      isSatellite: options.isSatellite,
+    });
+    this.originalFrontendApi = originalPk.frontendApi;
+
     const pk = parsePublishableKey(this.publishableKey, {
       fatal: true,
       proxyUrl: options.proxyUrl,
@@ -266,7 +281,8 @@ class AuthenticateContext implements AuthenticateContext {
       return false;
     }
     const tokenIssuer = data.payload.iss.replace(/https?:\/\//gi, '');
-    return this.frontendApi === tokenIssuer;
+    // Use original frontend API for token validation since tokens are issued by the actual Clerk API, not proxy
+    return this.originalFrontendApi === tokenIssuer;
   }
 
   private sessionExpired(jwt: Jwt | undefined): boolean {