feat(*): auto-proxy for eligible hosts

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

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

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
     });
   });
 
+  describe('auto-proxy for eligible hosts', () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+      process.env = {
+        ...originalEnv,
+        VERCEL_TARGET_ENV: 'production',
+        VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+      };
+    });
+
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
+    it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkLive,
+      });
+
+      expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+    });
+
+    it('does NOT auto-derive proxyUrl for development keys', async () => {
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkTest,
+      });
+
+      expect(context.proxyUrl).toBeUndefined();
+    });
+
+    it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+      delete process.env.VERCEL_TARGET_ENV;
+      delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+      const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+      const context = await createAuthenticateContext(clerkRequest, {
+        publishableKey: pkLive,
+      });
+
+      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: pkLive,
+        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: pkLive,
+        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 { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
     private clerkRequest: ClerkRequest,
     options: AuthenticateRequestOptions,
   ) {
+    // Auto-detect proxy for supported platform deployments using environment
+    // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+    // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+    const autoProxyPath = getAutoProxyUrlFromEnvironment({
+      publishableKey: options.publishableKey ?? '',
+      hasProxyUrl: !!options.proxyUrl,
+      hasDomain: !!options.domain,
+    });
+    if (autoProxyPath) {
+      options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+    }
+
     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

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
         });
       });
     });
+
+    describe('auto-detection for eligible hosts', () => {
+      const originalLocation = window.location;
+
+      afterEach(() => {
+        Object.defineProperty(window, 'location', {
+          value: originalLocation,
+          writable: true,
+        });
+      });
+
+      test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+        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(productionPublishableKey);
+        expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+      });
+
+      test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+        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('');
+      });
+
+      test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+        const sut = new Clerk(productionPublishableKey);
+        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(productionPublishableKey, {
+          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(productionPublishableKey, {
+          domain: 'clerk.myapp.com',
+        });
+        expect(sut.proxyUrl).toBe('');
+      });
+    });
   });
 
   describe('buildUrlWithAuth', () => {

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

@@ -38,7 +38,13 @@ 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 {
+  AUTO_PROXY_PATH,
+  isHttpOrHttps,
+  isValidProxyUrl,
+  proxyUrlToAbsoluteURL,
+  shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
   eventPrebuiltComponentMounted,
   eventPrebuiltComponentOpened,
@@ -361,7 +367,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 (production only)
+      if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+        return `${window.location.origin}${AUTO_PROXY_PATH}`;
+      }
     }
 
     if (typeof this.#proxyUrl === 'function') {

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

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
   });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+  const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+  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({ publishableKey: productionPublishableKey })(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({ publishableKey: productionPublishableKey })(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

@@ -21,9 +21,10 @@ import {
   TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+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';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 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';
@@ -161,12 +162,20 @@ 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);
+      let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+      // Auto-detect when no explicit proxy or domain is configured
+      const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+      if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+        if (shouldAutoProxy(requestUrl.hostname)) {
+          frontendApiProxyConfig = { enabled: true };
+        }
+      }
       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 })) {