feat(*): auto-proxy for eligible hosts

.changeset/tiny-badgers-smile.md

@@ -0,0 +1,8 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+---
+
+Add auto-proxy detection for eligible hosts, including Vercel production static-generation builds that can infer a relative proxy URL from platform env vars.

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

@@ -481,6 +481,50 @@ describe('proxy', () => {
       expect(response.headers.get('Location')).toBe('https://accounts.google.com/oauth/authorize');
     });
 
+    it('sets Accept-Encoding to identity to avoid double compression', async () => {
+      const mockResponse = new Response(JSON.stringify({ client: {} }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+      mockFetch.mockResolvedValue(mockResponse);
+
+      const request = new Request('https://example.com/__clerk/v1/client', {
+        headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+      });
+
+      await clerkFrontendApiProxy(request, {
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        secretKey: 'sk_test_xxx',
+      });
+
+      const [, options] = mockFetch.mock.calls[0];
+      expect(options.headers.get('Accept-Encoding')).toBe('identity');
+    });
+
+    it('strips Content-Encoding and Content-Length from response even if upstream ignores identity', async () => {
+      // Upstream may ignore Accept-Encoding: identity and compress anyway
+      const mockResponse = new Response('decoded body', {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/javascript',
+          'Content-Encoding': 'gzip',
+          'Content-Length': '500',
+        },
+      });
+      mockFetch.mockResolvedValue(mockResponse);
+
+      const request = new Request('https://example.com/__clerk/v1/client');
+
+      const response = await clerkFrontendApiProxy(request, {
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        secretKey: 'sk_test_xxx',
+      });
+
+      expect(response.headers.has('Content-Encoding')).toBe(false);
+      expect(response.headers.has('Content-Length')).toBe(false);
+      expect(response.headers.get('Content-Type')).toBe('application/javascript');
+    });
+
     it('preserves relative Location headers', async () => {
       const mockResponse = new Response(null, {
         status: 302,

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
   'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
   const fapiHost = new URL(fapiBaseUrl).host;
   headers.set('Host', fapiHost);
 
+  // Request uncompressed responses to avoid a double compression pass.
+  // fetch() auto-decompresses, so without this FAPI compresses → fetch
+  // decompresses → the serving layer re-compresses for the browser.
+  // With identity the only compression happens at the edge, closer to the client.
+  headers.set('Accept-Encoding', 'identity');
+
   // Set X-Forwarded-* headers for proxy awareness
   // Only set these if not already present (preserve values from upstream proxies)
   if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +284,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
     const response = await fetch(targetUrl.toString(), fetchOptions);
 
-    // Build response headers, excluding hop-by-hop headers
+    // Build response headers, excluding hop-by-hop and encoding headers
     const responseHeaders = new Headers();
     response.headers.forEach((value, key) => {
-      if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+      const lower = key.toLowerCase();
+      if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
         responseHeaders.set(key, value);
       }
     });

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

@@ -258,6 +258,46 @@ describe('AuthenticateContext', () => {
     });
   });
 
+  describe('auto-proxy for eligible hosts', () => {
+    it('auto-derives proxyUrl for eligible hostnames', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkTest,
+      });
+
+      expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+    });
+
+    it('does NOT auto-derive proxyUrl for ineligible domains', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp.com/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkTest,
+      });
+
+      expect(context.proxyUrl).toBeUndefined();
+    });
+
+    it('explicit proxyUrl takes precedence over auto-detection', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkTest,
+        proxyUrl: 'https://custom-proxy.example.com/__clerk',
+      });
+
+      expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+    });
+
+    it('explicit domain skips auto-detection', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkTest,
+        domain: 'clerk.myapp.com',
+      });
+
+      expect(context.proxyUrl).toBeUndefined();
+    });
+  });
+
   // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
   // Tests copied from packages/shared/src/__tests__/keys.test.ts
   describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -69,6 +70,14 @@ class AuthenticateContext implements AuthenticateContext {
     private clerkRequest: ClerkRequest,
     options: AuthenticateRequestOptions,
   ) {
+    // Auto-detect proxy for supported platform deployments
+    if (!options.proxyUrl && !options.domain) {
+      const hostname = clerkRequest.clerkUrl.hostname;
+      if (shouldAutoProxy(hostname)) {
+        options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}/__clerk` };
+      }
+    }
+
     if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
       // For non-session tokens, we only want to set the header values.
       this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2491,6 +2491,71 @@ describe('Clerk singleton', () => {
         expect(sut.getFapiClient().buildUrl({ path: '/me' }).href).toContain('https://proxy.com/api/__clerk/v1/me');
       });
     });
+
+    describe('auto-detection for eligible hosts', () => {
+      const originalLocation = window.location;
+
+      afterEach(() => {
+        Object.defineProperty(window, 'location', {
+          value: originalLocation,
+          writable: true,
+        });
+      });
+
+      test('auto-derives proxyUrl when hostname is eligible', () => {
+        Object.defineProperty(window, 'location', {
+          value: {
+            ...originalLocation,
+            hostname: 'myapp-abc123.vercel.app',
+            origin: 'https://myapp-abc123.vercel.app',
+            href: 'https://myapp-abc123.vercel.app/dashboard',
+          },
+          writable: true,
+        });
+
+        const sut = new Clerk(developmentPublishableKey);
+        expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+      });
+
+      test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+        const sut = new Clerk(developmentPublishableKey);
+        expect(sut.proxyUrl).toBe('');
+      });
+
+      test('explicit proxyUrl takes precedence over auto-detection', () => {
+        Object.defineProperty(window, 'location', {
+          value: {
+            ...originalLocation,
+            hostname: 'myapp-abc123.vercel.app',
+            origin: 'https://myapp-abc123.vercel.app',
+            href: 'https://myapp-abc123.vercel.app/dashboard',
+          },
+          writable: true,
+        });
+
+        const sut = new Clerk(developmentPublishableKey, {
+          proxyUrl: 'https://custom-proxy.example.com/__clerk',
+        });
+        expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+      });
+
+      test('explicit domain skips auto-detection', () => {
+        Object.defineProperty(window, 'location', {
+          value: {
+            ...originalLocation,
+            hostname: 'myapp-abc123.vercel.app',
+            origin: 'https://myapp-abc123.vercel.app',
+            href: 'https://myapp-abc123.vercel.app/dashboard',
+          },
+          writable: true,
+        });
+
+        const sut = new Clerk(developmentPublishableKey, {
+          domain: 'clerk.myapp.com',
+        });
+        expect(sut.proxyUrl).toBe('');
+      });
+    });
   });
 
   describe('buildUrlWithAuth', () => {

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

@@ -38,7 +38,7 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL, shouldAutoProxy } from '@clerk/shared/proxy';
 import {
   eventPrebuiltComponentMounted,
   eventPrebuiltComponentOpened,
@@ -351,7 +351,14 @@ export class Clerk implements ClerkInterface {
       if (!isValidProxyUrl(_unfilteredProxy)) {
         errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
       }
-      return proxyUrlToAbsoluteURL(_unfilteredProxy);
+      const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+      if (resolved) {
+        return resolved;
+      }
+      // Auto-detect when no explicit proxy or domain is configured
+      if (!this.#domain && shouldAutoProxy(window.location.hostname)) {
+        return `${window.location.origin}/__clerk`;
+      }
     }
     return '';
   }

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
     expect(html).not.toContain('nonce="test');
     expect(html).not.toContain('nonce="csp');
   });
+
+  it('renders initial script tags with relative proxied asset URLs', async () => {
+    mockHeaders.mockResolvedValue(
+      new Map([
+        ['X-Nonce', null],
+        ['Content-Security-Policy', ''],
+      ]),
+    );
+
+    const html = await render(
+      DynamicClerkScripts({
+        ...defaultProps,
+        proxyUrl: '/__clerk',
+      }),
+    );
+
+    expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+    expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+    expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+  });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1191,6 +1191,38 @@ describe('frontendApiProxy multi-domain support', () => {
   });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+  it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+    const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+      method: 'GET',
+      headers: new Headers(),
+    });
+
+    const resp = await clerkMiddleware()(req, {} as NextFetchEvent);
+
+    // Proxy should intercept the request — authenticateRequest should NOT be called
+    expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+    expect(resp?.status).toBeDefined();
+  });
+
+  it('uses request.nextUrl for auto-detection', async () => {
+    const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+      method: 'GET',
+      headers: new Headers(),
+    });
+
+    Object.defineProperty(req, 'nextUrl', {
+      value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+      configurable: true,
+    });
+
+    const resp = await clerkMiddleware()(req, {} as NextFetchEvent);
+
+    expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+    expect(resp?.status).toBeDefined();
+  });
+});
+
 describe('contentSecurityPolicy option', () => {
   it('forwards CSP headers as request headers when strict mode is enabled', async () => {
     const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -23,6 +23,7 @@ import {
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -33,7 +34,7 @@ import { isRedirect, serverRedirectWithAuth, setHeader } from '../utils';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -159,12 +160,16 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
       );
 
       // Handle Frontend API proxy requests early, before authentication
-      const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+      const requestUrl = new URL(request.nextUrl.href);
+      const frontendApiProxyConfig =
+        resolvedParams.frontendApiProxy ??
+        (resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN
+          ? undefined
+          : getAutoDetectedProxyConfig(requestUrl));
       if (frontendApiProxyConfig) {
         const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
         // Resolve enabled - either boolean or function
-        const requestUrl = new URL(request.url);
         const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
         if (isEnabled && matchProxyPath(request, { proxyPath })) {
@@ -576,3 +581,10 @@ const handleControlFlowErrors = (
 
   throw e;
 };
+
+function getAutoDetectedProxyConfig(requestUrl: URL): FrontendApiProxyOptions | undefined {
+  if (shouldAutoProxy(requestUrl.hostname)) {
+    return { enabled: true };
+  }
+  return undefined;
+}