feat: Align Express FrontendApiProxyOptions.enabled with Next.js

Accept `boolean | ShouldProxyFn` for the enabled field, matching the
Next.js interface. The function form receives the request URL and
allows per-request proxy decisions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: brkalow

packages/express/src/authenticateRequest.ts

@@ -105,7 +105,6 @@ export const authenticateAndDecorateRequest = (options: ClerkMiddlewareOptions =
 
   // Extract proxy configuration
   const frontendApiProxy = options.frontendApiProxy;
-  const proxyEnabled = frontendApiProxy?.enabled === true;
   const proxyPath = stripTrailingSlashes(frontendApiProxy?.path ?? DEFAULT_PROXY_PATH);
 
   // eslint-disable-next-line @typescript-eslint/no-misused-promises
@@ -119,9 +118,14 @@ export const authenticateAndDecorateRequest = (options: ClerkMiddlewareOptions =
     const secretKey = options.secretKey || env.secretKey;
 
     // Handle Frontend API proxy requests early, before authentication
-    if (proxyEnabled) {
-      const requestPath = new URL(request.originalUrl || request.url, `http://${request.headers.host}`).pathname;
-      if (requestPath === proxyPath || requestPath.startsWith(proxyPath + '/')) {
+    if (frontendApiProxy) {
+      const requestUrl = new URL(request.originalUrl || request.url, `http://${request.headers.host}`);
+      const isEnabled =
+        typeof frontendApiProxy.enabled === 'function'
+          ? frontendApiProxy.enabled(requestUrl)
+          : frontendApiProxy.enabled;
+
+      if (isEnabled && (requestUrl.pathname === proxyPath || requestUrl.pathname.startsWith(proxyPath + '/'))) {
         // Convert Express request to Fetch API Request
         const proxyRequest = requestToProxyRequest(request);
 
@@ -164,18 +168,25 @@ export const authenticateAndDecorateRequest = (options: ClerkMiddlewareOptions =
 
     // Auto-derive proxyUrl from frontendApiProxy config if not explicitly set
     let resolvedOptions = options;
-    if (proxyEnabled && !options.proxyUrl) {
-      const forwardedProto = request.headers['x-forwarded-proto'];
-      const protoHeader = Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto;
-      const proto = (protoHeader || '').split(',')[0].trim();
-      const protocol = request.secure || proto === 'https' ? 'https' : 'http';
-
-      const forwardedHost = request.headers['x-forwarded-host'];
-      const hostHeader = Array.isArray(forwardedHost) ? forwardedHost[0] : forwardedHost;
-      const host = (hostHeader || '').split(',')[0].trim() || request.headers.host || 'localhost';
-
-      const derivedProxyUrl = `${protocol}://${host}${proxyPath}`;
-      resolvedOptions = { ...options, proxyUrl: derivedProxyUrl };
+    if (frontendApiProxy && !options.proxyUrl) {
+      const requestUrl = new URL(request.originalUrl || request.url, `http://${request.headers.host}`);
+      const isProxyEnabled =
+        typeof frontendApiProxy.enabled === 'function'
+          ? frontendApiProxy.enabled(requestUrl)
+          : frontendApiProxy.enabled;
+      if (isProxyEnabled) {
+        const forwardedProto = request.headers['x-forwarded-proto'];
+        const protoHeader = Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto;
+        const proto = (protoHeader || '').split(',')[0].trim();
+        const protocol = request.secure || proto === 'https' ? 'https' : 'http';
+
+        const forwardedHost = request.headers['x-forwarded-host'];
+        const hostHeader = Array.isArray(forwardedHost) ? forwardedHost[0] : forwardedHost;
+        const host = (hostHeader || '').split(',')[0].trim() || request.headers.host || 'localhost';
+
+        const derivedProxyUrl = `${protocol}://${host}${proxyPath}`;
+        resolvedOptions = { ...options, proxyUrl: derivedProxyUrl };
+      }
     }
 
     try {

packages/express/src/types.ts

@@ -1,5 +1,6 @@
 import type { createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
+import type { ShouldProxyFn } from '@clerk/shared/proxy';
 import type { PendingSessionOptions } from '@clerk/shared/types';
 import type { Request as ExpressRequest } from 'express';
 
@@ -12,10 +13,12 @@ export type ExpressRequestWithAuth = ExpressRequest & {
  */
 export interface FrontendApiProxyOptions {
   /**
-   * Enable Frontend API proxy handling. When true, requests to the proxy path
-   * will be proxied to Clerk's Frontend API and the proxyUrl will be auto-derived.
+   * Enable proxy handling. Can be:
+   * - `true` - enable for all domains
+   * - `false` - disable for all domains
+   * - A function: (url: URL) => boolean - enable based on the request URL
    */
-  enabled: boolean;
+  enabled: boolean | ShouldProxyFn;
   /**
    * The path prefix for proxy requests.
    *