fix(backend): prevent Content-Encoding mismatch in proxy responses (clerk#8159)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: brkalow

.changeset/fix-proxy-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix `ERR_CONTENT_DECODING_FAILED` when loading proxied assets by requesting uncompressed responses from FAPI and stripping `Content-Encoding`/`Content-Length` headers that `fetch()` invalidates through auto-decompression.

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

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

packages/backend/src/proxy.ts

@@ -54,6 +54,13 @@ const HOP_BY_HOP_HEADERS = [
   'upgrade',
 ];
 
+// Headers to strip from proxied responses. fetch() auto-decompresses
+// response bodies, so Content-Encoding no longer describes the body
+// and Content-Length reflects the compressed size. We request identity
+// encoding upstream to avoid the double compression pass, but strip
+// these defensively since servers may ignore Accept-Encoding: identity.
+const RESPONSE_HEADERS_TO_STRIP = ['content-encoding', 'content-length'];
+
 /**
  * Derives the Frontend API URL from a publishable key.
  * @param publishableKey - The Clerk publishable key
@@ -235,6 +242,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
   const fapiHost = new URL(fapiBaseUrl).host;
   headers.set('Host', fapiHost);
 
+  // Request uncompressed responses to avoid a double compression pass.
+  // fetch() auto-decompresses, so without this FAPI compresses → fetch
+  // decompresses → the serving layer re-compresses for the browser.
+  headers.set('Accept-Encoding', 'identity');
+
   // Set X-Forwarded-* headers for proxy awareness
   // Only set these if not already present (preserve values from upstream proxies)
   if (!headers.has('X-Forwarded-Host')) {
@@ -271,10 +283,11 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
 
     const response = await fetch(targetUrl.toString(), fetchOptions);
 
-    // Build response headers, excluding hop-by-hop headers
+    // Build response headers, excluding hop-by-hop and encoding headers
     const responseHeaders = new Headers();
     response.headers.forEach((value, key) => {
-      if (!HOP_BY_HOP_HEADERS.includes(key.toLowerCase())) {
+      const lower = key.toLowerCase();
+      if (!HOP_BY_HOP_HEADERS.includes(lower) && !RESPONSE_HEADERS_TO_STRIP.includes(lower)) {
         responseHeaders.set(key, value);
       }
     });
@@ -295,11 +308,20 @@ export async function clerkFrontendApiProxy(request: Request, options?: Frontend
       }
     }
 
-    return new Response(response.body, {
+    const proxyResponse = new Response(response.body, {
       status: response.status,
       statusText: response.statusText,
       headers: responseHeaders,
     });
+
+    // Some runtimes may re-add Content-Length when constructing the Response.
+    // Delete explicitly since fetch() decoded the body and the original values
+    // no longer reflect the actual content.
+    for (const header of RESPONSE_HEADERS_TO_STRIP) {
+      proxyResponse.headers.delete(header);
+    }
+
+    return proxyResponse;
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Unknown error';
     return createErrorResponse('proxy_request_failed', `Failed to proxy request to Clerk FAPI: ${message}`, 502);