fix(backend): harden FAPI proxy resilience and spec compliance

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {

.changeset/tough-ghosts-ask.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the built-in Clerk Frontend API proxy, adding support for abort signals and addressing a number of small edge cases.

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

@@ -541,6 +541,106 @@ describe('proxy', () => {
  expect(response.headers.get('Content-Type')).toBe('application/javascript');
  });
 
+ it('forwards DELETE request with body', async () => {
+ const mockResponse = new Response(JSON.stringify({ deleted: true }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const requestBody = JSON.stringify({ id: '123' });
+ const request = new Request('https://example.com/__clerk/v1/resource', {
+ method: 'DELETE',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: requestBody,
+ });
+
+ const response = await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ const [, options] = mockFetch.mock.calls[0];
+
+ expect(options.method).toBe('DELETE');
+ expect(options.body).not.toBeNull();
+ expect(options.duplex).toBe('half');
+
+ expect(response.status).toBe(200);
+ });
+
+ it('propagates abort signal to upstream fetch', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const controller = new AbortController();
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ signal: controller.signal,
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ expect(options.signal).toBe(request.signal);
+ });
+
+ it('includes Cache-Control: no-store on error responses', async () => {
+ const request = new Request('https://example.com/__clerk/v1/client');
+
+ // Missing publishableKey triggers an error response
+ const response = await clerkFrontendApiProxy(request, {
+ secretKey: 'sk_test_xxx',
+ });
+
+ expect(response.status).toBe(500);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('includes Cache-Control: no-store on 502 error responses', async () => {
+ mockFetch.mockRejectedValue(new Error('Network error'));
+
+ 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.status).toBe(502);
+ expect(response.headers.get('Cache-Control')).toBe('no-store');
+ });
+
+ it('strips dynamic hop-by-hop headers listed in the Connection header from requests', async () => {
+ const mockResponse = new Response(JSON.stringify({}), { status: 200 });
+ mockFetch.mockResolvedValue(mockResponse);
+
+ const request = new Request('https://example.com/__clerk/v1/client', {
+ headers: {
+ Connection: 'keep-alive, X-Custom-Hop',
+ 'X-Custom-Hop': 'some-value',
+ 'User-Agent': 'Test',
+ },
+ });
+
+ await clerkFrontendApiProxy(request, {
+ publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+ secretKey: 'sk_test_xxx',
+ });
+
+ const [, options] = mockFetch.mock.calls[0];
+ // Connection and X-Custom-Hop should both be stripped
+ expect(options.headers.has('Connection')).toBe(false);
+ expect(options.headers.has('X-Custom-Hop')).toBe(false);
+ // Non-hop-by-hop headers should be preserved
+ expect(options.headers.get('User-Agent')).toBe('Test');
+ });
+
  it('preserves multiple Set-Cookie headers from FAPI response', async () => {
  const headers = new Headers();
  headers.append('Set-Cookie', '__client=abc123; Path=/; HttpOnly; Secure');

packages/backend/src/proxy.ts

@@ -43,7 +43,7 @@ export interface ProxyError {
 }
 
 // Hop-by-hop headers that should not be forwarded
-const HOP_BY_HOP_HEADERS = [
+const HOP_BY_HOP_HEADERS = new Set([
  'connection',
  'keep-alive',
  'proxy-authenticate',
@@ -52,14 +52,32 @@ const HOP_BY_HOP_HEADERS = [
  'trailer',
  'transfer-encoding',
  'upgrade',
-];
+]);
+
+/**
+ * Parses the Connection header to extract dynamically-nominated hop-by-hop
+ * header names (RFC 7230 Section 6.1). These headers are specific to the
+ * current connection and must not be forwarded by proxies.
+ */
+function getDynamicHopByHopHeaders(headers: Headers): Set<string> {
+ const connectionValue = headers.get('connection');
+ if (!connectionValue) {
+ return new Set();
+ }
+ return new Set(
+ connectionValue
+ .split(',')
+ .map(h => h.trim().toLowerCase())
+ .filter(h => h.length > 0),
+ );
+}
 
 // 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'];
+const RESPONSE_HEADERS_TO_STRIP = new Set(['content-encoding', 'content-length']);
 
 /**
  * Derives the Frontend API URL from a publishable key.
@@ -114,6 +132,7 @@ function createErrorResponse(code: ProxyErrorCode, message: string, status: numb
  status,
  headers: {
  'Content-Type': 'application/json',
+ 'Cache-Control': 'no-store',
  },
  });
 }
@@ -230,9 +249,12 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  // Build headers for the proxied request
  const headers = new Headers();
 
- // Copy original headers, excluding hop-by-hop headers
+ // Copy original headers, excluding hop-by-hop headers and any
+ // dynamically-nominated hop-by-hop headers listed in the Connection header (RFC 7230 Section 6.1).
+ const dynamicHopByHop = getDynamicHopByHopHeaders(request.headers);
  request.headers.forEach((value, key) => {
- if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+ const lower = key.toLowerCase();
+ if (!HOP_BY_HOP_HEADERS.has(lower) && !dynamicHopByHop.has(lower)) {
  headers.set(key, value);
  }
  });
@@ -270,31 +292,39 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
  headers.set('X-Forwarded-For', clientIp);
  }
 
- // Determine if request has a body
- const hasBody = ['POST', 'PUT', 'PATCH'].includes(request.method);
+ // Determine if request has a body (handles DELETE-with-body and any other method)
+ const hasBody = request.body !== null;
 
  try {
  // Make the proxied request
+ // TODO: Consider adding AbortSignal.timeout(30_000) via AbortSignal.any()
  const fetchOptions: RequestInit = {
  method: request.method,
  headers,
  redirect: 'manual',
- // @ts-expect-error - duplex is required for streaming bodies but not in all TS definitions
- duplex: hasBody ? 'half' : undefined,
+ signal: request.signal,
  };
 
- // Only include body for methods that support it
- if (hasBody && request.body) {
+ // Only set duplex when body is present (required for streaming bodies)
+ if (hasBody) {
+ // @ts-expect-error - duplex is required for streaming bodies, but not present on the RequestInit type from undici
+ fetchOptions.duplex = 'half';
  fetchOptions.body = request.body;
  }
 
  const response = await fetch(targetUrl.toString(), fetchOptions);
 
- // Build response headers, excluding hop-by-hop and encoding headers
+ // Build response headers, excluding hop-by-hop and encoding headers.
+ // Also strip dynamically-nominated hop-by-hop headers from the response Connection header.
+ const responseDynamicHopByHop = getDynamicHopByHopHeaders(response.headers);
  const responseHeaders = new Headers();
  response.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
- if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
+ if (
+ !HOP_BY_HOP_HEADERS.has(lower) &&
+ !RESPONSE_HEADERS_TO_STRIP.has(lower) &&
+ !responseDynamicHopByHop.has(lower)
+ ) {
  if (lower === 'set-cookie') {
  responseHeaders.append(key, value);
  } else {