feat(hono): add Frontend API proxy support

Add `frontendApiProxy` option to `clerkMiddleware` that intercepts
requests matching the proxy path (default `/__clerk`) and forwards
them to Clerk's Frontend API. When enabled, proxyUrl is automatically
derived so SDKs pass just the path to the backend for resolution.

Author: nikosdouvlis

.changeset/hono-proxy-support.md

@@ -0,0 +1,5 @@
+---
+'@clerk/hono': minor
+---
+
+Add Frontend API proxy support to `@clerk/hono` via the `frontendApiProxy` option on `clerkMiddleware`. When enabled, requests matching the proxy path (default `/__clerk`) are forwarded to Clerk's Frontend API, allowing Clerk to work in environments where direct API access is blocked by ad blockers or firewalls. The `proxyUrl` for auth handshake is automatically derived from the request when `frontendApiProxy` is configured.

packages/hono/src/__tests__/clerkMiddleware.test.ts

@@ -18,6 +18,18 @@ const createMockSessionAuth = () => ({
 
 const authenticateRequestMock = vi.fn();
 
+const { mockClerkFrontendApiProxy } = vi.hoisted(() => ({
+  mockClerkFrontendApiProxy: vi.fn(),
+}));
+
+vi.mock('@clerk/backend/proxy', async () => {
+  const actual = await vi.importActual('@clerk/backend/proxy');
+  return {
+    ...actual,
+    clerkFrontendApiProxy: mockClerkFrontendApiProxy,
+  };
+});
+
 vi.mock(import('@clerk/backend'), async importOriginal => {
   const original = await importOriginal();
 
@@ -163,6 +175,211 @@ describe('clerkMiddleware()', () => {
   });
 });
 
+describe('Frontend API proxy handling', () => {
+  beforeEach(() => {
+    vi.stubEnv('CLERK_SECRET_KEY', EnvVariables.CLERK_SECRET_KEY);
+    vi.stubEnv('CLERK_PUBLISHABLE_KEY', EnvVariables.CLERK_PUBLISHABLE_KEY);
+    authenticateRequestMock.mockReset();
+    mockClerkFrontendApiProxy.mockReset();
+  });
+
+  test('intercepts proxy path requests', async () => {
+    mockClerkFrontendApiProxy.mockResolvedValueOnce(new Response('proxied', { status: 200 }));
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/__clerk/v1/client'));
+
+    expect(response.status).toEqual(200);
+    expect(await response.text()).toEqual('proxied');
+    expect(mockClerkFrontendApiProxy).toHaveBeenCalled();
+    expect(authenticateRequestMock).not.toHaveBeenCalled();
+  });
+
+  test('intercepts proxy path with query parameters', async () => {
+    mockClerkFrontendApiProxy.mockResolvedValueOnce(new Response('proxied', { status: 200 }));
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/__clerk?_clerk_js_version=5.0.0'));
+
+    expect(response.status).toEqual(200);
+    expect(await response.text()).toEqual('proxied');
+    expect(mockClerkFrontendApiProxy).toHaveBeenCalled();
+    expect(authenticateRequestMock).not.toHaveBeenCalled();
+  });
+
+  test('authenticates default path when custom proxy path is set', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      status: 'handshake',
+      reason: 'auth-reason',
+      message: 'auth-message',
+      headers: new Headers({
+        location: 'https://fapi.example.com/v1/clients/handshake',
+        'x-clerk-auth-message': 'auth-message',
+        'x-clerk-auth-reason': 'auth-reason',
+        'x-clerk-auth-status': 'handshake',
+      }),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true, path: '/custom-proxy' } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(
+      new Request('http://localhost/__clerk/v1/client', {
+        headers: {
+          Cookie: '__client_uat=1711618859;',
+          'Sec-Fetch-Dest': 'document',
+        },
+      }),
+    );
+
+    expect(response.status).toEqual(307);
+    expect(response.headers.get('x-clerk-auth-status')).toEqual('handshake');
+    expect(mockClerkFrontendApiProxy).not.toHaveBeenCalled();
+    expect(authenticateRequestMock).toHaveBeenCalled();
+  });
+
+  test('does not intercept when enabled is false', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      headers: new Headers(),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: false } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/__clerk/v1/client'));
+
+    expect(response.status).toEqual(200);
+    expect(mockClerkFrontendApiProxy).not.toHaveBeenCalled();
+    expect(authenticateRequestMock).toHaveBeenCalled();
+  });
+
+  test('does not intercept when frontendApiProxy is not configured', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      headers: new Headers(),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware());
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/__clerk/v1/client'));
+
+    expect(response.status).toEqual(200);
+    expect(mockClerkFrontendApiProxy).not.toHaveBeenCalled();
+    expect(authenticateRequestMock).toHaveBeenCalled();
+  });
+
+  test('still authenticates non-proxy paths when proxy is configured', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      headers: new Headers(),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/api/users'));
+
+    expect(response.status).toEqual(200);
+    expect(await response.text()).toEqual('OK');
+    expect(mockClerkFrontendApiProxy).not.toHaveBeenCalled();
+    expect(authenticateRequestMock).toHaveBeenCalled();
+  });
+
+  test('uses env vars for keys when only frontendApiProxy is passed', async () => {
+    mockClerkFrontendApiProxy.mockResolvedValueOnce(new Response('proxied', { status: 200 }));
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(new Request('http://localhost/__clerk/v1/client'));
+
+    expect(response.status).toEqual(200);
+    expect(mockClerkFrontendApiProxy).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.objectContaining({
+        publishableKey: EnvVariables.CLERK_PUBLISHABLE_KEY,
+        secretKey: EnvVariables.CLERK_SECRET_KEY,
+      }),
+    );
+  });
+
+  test('auto-derives proxyUrl from request when frontendApiProxy is enabled', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      headers: new Headers(),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use('*', clerkMiddleware({ frontendApiProxy: { enabled: true } }));
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(
+      new Request('http://localhost/api/users', {
+        headers: {
+          'x-forwarded-proto': 'https',
+          'x-forwarded-host': 'myapp.com',
+        },
+      }),
+    );
+
+    expect(response.status).toEqual(200);
+    expect(authenticateRequestMock).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.objectContaining({
+        proxyUrl: '/__clerk',
+      }),
+    );
+  });
+
+  test('does not override explicit proxyUrl', async () => {
+    authenticateRequestMock.mockResolvedValueOnce({
+      headers: new Headers(),
+      toAuth: createMockSessionAuth,
+    });
+
+    const app = new Hono();
+    app.use(
+      '*',
+      clerkMiddleware({
+        frontendApiProxy: { enabled: true },
+        proxyUrl: 'https://explicit.example.com/__clerk',
+      }),
+    );
+    app.get('/*', c => c.text('OK'));
+
+    const response = await app.request(
+      new Request('http://localhost/api/users', {
+        headers: {
+          'x-forwarded-proto': 'https',
+          'x-forwarded-host': 'myapp.com',
+        },
+      }),
+    );
+
+    expect(response.status).toEqual(200);
+    expect(authenticateRequestMock).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.objectContaining({
+        proxyUrl: 'https://explicit.example.com/__clerk',
+      }),
+    );
+  });
+});
+
 describe('getAuth()', () => {
   beforeEach(() => {
     vi.stubEnv('CLERK_SECRET_KEY', EnvVariables.CLERK_SECRET_KEY);

packages/hono/src/clerkMiddleware.ts

@@ -2,17 +2,22 @@ import type { AuthObject } from '@clerk/backend';
 import { createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, AuthOptions, GetAuthFnNoRequest } from '@clerk/backend/internal';
 import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
+import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath, stripTrailingSlashes } from '@clerk/backend/proxy';
 import type { MiddlewareHandler } from 'hono';
 import { env } from 'hono/adapter';
 
+import type { FrontendApiProxyOptions } from './types';
+
 type ClerkEnv = {
   CLERK_SECRET_KEY: string;
   CLERK_PUBLISHABLE_KEY: string;
   CLERK_API_URL?: string;
   CLERK_API_VERSION?: string;
 };
 
-export type ClerkMiddlewareOptions = Omit<AuthenticateRequestOptions, 'acceptsToken'>;
+export type ClerkMiddlewareOptions = Omit<AuthenticateRequestOptions, 'acceptsToken'> & {
+  frontendApiProxy?: FrontendApiProxyOptions;
+};
 
 /**
  * Clerk middleware for Hono that authenticates requests and attaches
@@ -35,12 +40,14 @@ export type ClerkMiddlewareOptions = Omit<AuthenticateRequestOptions, 'acceptsTo
 export const clerkMiddleware = (options?: ClerkMiddlewareOptions): MiddlewareHandler => {
   return async (c, next) => {
     const clerkEnv = env<ClerkEnv>(c);
-    const { secretKey, publishableKey, apiUrl, apiVersion, ...rest } = options || {
-      secretKey: clerkEnv.CLERK_SECRET_KEY || '',
-      publishableKey: clerkEnv.CLERK_PUBLISHABLE_KEY || '',
-      apiUrl: clerkEnv.CLERK_API_URL,
-      apiVersion: clerkEnv.CLERK_API_VERSION,
-    };
+    const {
+      secretKey = clerkEnv.CLERK_SECRET_KEY || '',
+      publishableKey = clerkEnv.CLERK_PUBLISHABLE_KEY || '',
+      apiUrl = clerkEnv.CLERK_API_URL,
+      apiVersion = clerkEnv.CLERK_API_VERSION,
+      frontendApiProxy,
+      ...rest
+    } = options || {};
 
     if (!secretKey) {
       throw new Error(
@@ -54,6 +61,31 @@ export const clerkMiddleware = (options?: ClerkMiddlewareOptions): MiddlewareHan
       );
     }
 
+    // Handle Frontend API proxy requests and auto-derive proxyUrl
+    let derivedProxyUrl = rest.proxyUrl;
+    if (frontendApiProxy) {
+      const proxyPath = stripTrailingSlashes(frontendApiProxy.path ?? DEFAULT_PROXY_PATH);
+      const requestUrl = new URL(c.req.url);
+      const isEnabled =
+        typeof frontendApiProxy.enabled === 'function'
+          ? frontendApiProxy.enabled(requestUrl)
+          : frontendApiProxy.enabled;
+
+      if (isEnabled) {
+        if (matchProxyPath(c.req.raw, { proxyPath })) {
+          return clerkFrontendApiProxy(c.req.raw, {
+            proxyPath,
+            publishableKey,
+            secretKey,
+          });
+        }
+
+        if (!derivedProxyUrl) {
+          derivedProxyUrl = proxyPath;
+        }
+      }
+    }
+
     const clerkClient = createClerkClient({
       ...rest,
       apiUrl,
@@ -67,6 +99,7 @@ export const clerkMiddleware = (options?: ClerkMiddlewareOptions): MiddlewareHan
       ...rest,
       secretKey,
       publishableKey,
+      proxyUrl: derivedProxyUrl,
       acceptsToken: 'any',
     });
 

packages/hono/src/index.ts

@@ -1,5 +1,6 @@
 export { clerkMiddleware } from './clerkMiddleware';
 export type { ClerkMiddlewareOptions } from './clerkMiddleware';
+export type { FrontendApiProxyOptions } from './types';
 
 export { getAuth } from './getAuth';
 

packages/hono/src/types.ts

@@ -1,5 +1,6 @@
 import type { ClerkClient } from '@clerk/backend';
 import type { GetAuthFnNoRequest } from '@clerk/backend/internal';
+import type { ShouldProxyFn } from '@clerk/shared/proxy';
 
 /**
  * Variables that clerkMiddleware sets on the Hono context.
@@ -9,3 +10,18 @@ export type ClerkHonoVariables = {
   clerk: ClerkClient;
   clerkAuth: GetAuthFnNoRequest;
 };
+
+/**
+ * Options for the built-in Frontend API proxy.
+ *
+ * When enabled, the middleware intercepts requests that match the proxy path
+ * (default `/__clerk`) and forwards them to the Clerk Frontend API, allowing
+ * the Clerk frontend SDKs to communicate with Clerk without third-party
+ * cookie or ad-blocker issues.
+ */
+export interface FrontendApiProxyOptions {
+  /** Toggle the proxy on/off, or supply a function that decides per-request. */
+  enabled: boolean | ShouldProxyFn;
+  /** Custom path prefix for the proxy (default: `/__clerk`). */
+  path?: string;
+}