fix(backend): derive Clerk-Proxy-Url from forwarded headers in clerkFrontendApiProxy

Behind a reverse proxy, request.url resolves to localhost, but the
Clerk-Proxy-Url header and Location rewrites must use the public origin
visible to the browser. Read x-forwarded-proto and x-forwarded-host
headers (with fallback to request URL) to derive the correct origin.

This fixes proxy support for Hono (Node adapter) and Express when
running behind nginx, Cloudflare, or similar reverse proxies.

Author: nikosdouvlis

.changeset/backend-proxy-forwarded-headers.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `clerkFrontendApiProxy` to derive the `Clerk-Proxy-Url` header and Location rewrites from `x-forwarded-proto`/`x-forwarded-host` headers instead of the raw `request.url`. Behind a reverse proxy, `request.url` resolves to localhost, causing FAPI to receive an incorrect proxy URL. The fix uses the same forwarded-header resolution pattern as `ClerkRequest`.

packages/backend/src/__tests__/proxy.test.ts

@@ -380,6 +380,67 @@ describe('proxy', () => {
       expect(options.headers.get('X-Forwarded-Proto')).toBe('https');
     });
 
+    it('derives Clerk-Proxy-Url from forwarded headers instead of localhost', async () => {
+      const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+      mockFetch.mockResolvedValue(mockResponse);
+
+      // Behind a reverse proxy, request.url is localhost but forwarded headers carry the public origin
+      const request = new Request('http://localhost:3000/__clerk/v1/client', {
+        headers: {
+          'X-Forwarded-Host': 'myapp.example.com',
+          'X-Forwarded-Proto': 'https',
+        },
+      });
+
+      await clerkFrontendApiProxy(request, {
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        secretKey: 'sk_test_xxx',
+      });
+
+      const [, options] = mockFetch.mock.calls[0];
+      expect(options.headers.get('Clerk-Proxy-Url')).toBe('https://myapp.example.com/__clerk');
+    });
+
+    it('falls back to request URL for Clerk-Proxy-Url when no forwarded headers', async () => {
+      const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+      mockFetch.mockResolvedValue(mockResponse);
+
+      const request = new Request('https://example.com/__clerk/v1/client');
+
+      await clerkFrontendApiProxy(request, {
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        secretKey: 'sk_test_xxx',
+      });
+
+      const [, options] = mockFetch.mock.calls[0];
+      expect(options.headers.get('Clerk-Proxy-Url')).toBe('https://example.com/__clerk');
+    });
+
+    it('rewrites Location header using forwarded origin, not localhost', async () => {
+      const mockResponse = new Response(null, {
+        status: 302,
+        headers: {
+          Location: 'https://frontend-api.clerk.dev/v1/oauth/callback?code=123',
+        },
+      });
+      mockFetch.mockResolvedValue(mockResponse);
+
+      const request = new Request('http://localhost:3000/__clerk/v1/oauth/authorize', {
+        headers: {
+          'X-Forwarded-Host': 'myapp.example.com',
+          'X-Forwarded-Proto': 'https',
+        },
+      });
+
+      const response = await clerkFrontendApiProxy(request, {
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        secretKey: 'sk_test_xxx',
+      });
+
+      expect(response.status).toBe(302);
+      expect(response.headers.get('Location')).toBe('https://myapp.example.com/__clerk/v1/oauth/callback?code=123');
+    });
+
     it('rewrites Location header for redirects pointing to FAPI', async () => {
       const mockResponse = new Response(null, {
         status: 302,

packages/backend/src/proxy.ts

@@ -111,6 +111,22 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
   });
 }
 
+/**
+ * Derives the public-facing origin from forwarded headers, falling back to the raw request URL.
+ * Behind a reverse proxy, request.url is typically localhost, but the Clerk-Proxy-Url header
+ * and Location rewrites must use the origin visible to the browser.
+ */
+function derivePublicOrigin(request: Request, requestUrl: URL): string {
+  const forwardedProto = request.headers.get('x-forwarded-proto')?.split(',')[0]?.trim();
+  const forwardedHost = request.headers.get('x-forwarded-host')?.split(',')[0]?.trim();
+
+  if (forwardedProto && forwardedHost) {
+    return `${forwardedProto}://${forwardedHost}`;
+  }
+
+  return requestUrl.origin;
+}
+
 /**
  * Gets the client IP address from various headers
  */
@@ -208,7 +224,10 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
   });
 
   // Set required Clerk proxy headers
-  const proxyUrl = `${requestUrl.protocol}//${requestUrl.host}${proxyPath}`;
+  // Use the public origin (from forwarded headers) so the Clerk-Proxy-Url
+  // points to the browser-visible host, not localhost behind a reverse proxy.
+  const publicOrigin = derivePublicOrigin(request, requestUrl);
+  const proxyUrl = `${publicOrigin}${proxyPath}`;
   headers.set('Clerk-Proxy-Url', proxyUrl);
   headers.set('Clerk-Secret-Key', secretKey);