feat(supabase): add failOnNetworkError option to prevent silent fallback to anon key

Author: mandarini

packages/core/supabase-js/src/SupabaseClient.ts

@@ -88,6 +88,7 @@ export default class SupabaseClient<
   protected accessToken?: () => Promise<string | null>
 
   protected headers: Record<string, string>
+  protected failOnNetworkError: boolean
 
   /**
    * Create a new client for use in the browser.
@@ -136,6 +137,7 @@ export default class SupabaseClient<
 
     this.storageKey = settings.auth.storageKey ?? ''
     this.headers = settings.global.headers ?? {}
+    this.failOnNetworkError = settings.auth.failOnNetworkError ?? false
 
     if (!settings.accessToken) {
       this.auth = this._initSupabaseAuthClient(
@@ -338,7 +340,14 @@ export default class SupabaseClient<
       return await this.accessToken()
     }
 
-    const { data } = await this.auth.getSession()
+    const { data, error } = await this.auth.getSession()
+
+    // If failOnNetworkError is enabled and there's a retryable error (network failure),
+    // throw instead of silently falling back to anon key.
+    // status === 0 indicates a network error (AuthRetryableFetchError)
+    if (this.failOnNetworkError && error && error.status === 0) {
+      throw error
+    }
 
     return data.session?.access_token ?? this.supabaseKey
   }

packages/core/supabase-js/src/lib/types.ts

@@ -81,6 +81,16 @@ export type SupabaseClientOptions<SchemaName> = {
      * throwing the error instead of returning it as part of a successful response.
      */
     throwOnError?: SupabaseAuthClientOptions['throwOnError']
+    /**
+     * When true, throws an error if session retrieval fails due to network issues
+     * instead of silently falling back to the anonymous API key.
+     *
+     * This prevents RLS policies from silently failing when `auth.uid()` returns null
+     * due to network errors during token refresh.
+     *
+     * @default false
+     */
+    failOnNetworkError?: boolean
   }
   /**
    * Options passed to the realtime-js instance

packages/core/supabase-js/test/unit/SupabaseClient.test.ts

@@ -256,6 +256,68 @@ describe('SupabaseClient', () => {
         const token = await client._getAccessToken()
         expect(token).toBe(KEY)
       })
+
+      test('should fallback to supabaseKey on network error by default', async () => {
+        const client = createClient(URL, KEY)
+
+        // Mock network error (status 0 indicates AuthRetryableFetchError)
+        const networkError = { message: 'Network error', status: 0 }
+        client.auth.getSession = jest.fn().mockResolvedValue({
+          data: { session: null },
+          error: networkError,
+        })
+
+        // @ts-ignore - accessing private method
+        const token = await client._getAccessToken()
+        // Should fallback to KEY, not throw
+        expect(token).toBe(KEY)
+      })
+
+      test('should throw on network error when failOnNetworkError is true', async () => {
+        const client = createClient(URL, KEY, {
+          auth: { failOnNetworkError: true },
+        })
+
+        // Mock network error (status 0 indicates AuthRetryableFetchError)
+        const networkError = { message: 'Network error', status: 0 }
+        client.auth.getSession = jest.fn().mockResolvedValue({
+          data: { session: null },
+          error: networkError,
+        })
+
+        // @ts-ignore - accessing private method
+        await expect(client._getAccessToken()).rejects.toEqual(networkError)
+      })
+
+      test('should not throw on non-network auth errors even when failOnNetworkError is true', async () => {
+        const client = createClient(URL, KEY, {
+          auth: { failOnNetworkError: true },
+        })
+
+        // Mock non-network auth error (e.g., session expired - status 401)
+        const authError = { message: 'Session expired', status: 401 }
+        client.auth.getSession = jest.fn().mockResolvedValue({
+          data: { session: null },
+          error: authError,
+        })
+
+        // @ts-ignore - accessing private method
+        const token = await client._getAccessToken()
+        // Should fallback to KEY, not throw (status !== 0)
+        expect(token).toBe(KEY)
+      })
+
+      test('should store failOnNetworkError setting', () => {
+        const clientWithOption = createClient(URL, KEY, {
+          auth: { failOnNetworkError: true },
+        })
+        // @ts-ignore - accessing protected property
+        expect(clientWithOption.failOnNetworkError).toBe(true)
+
+        const clientWithoutOption = createClient(URL, KEY)
+        // @ts-ignore - accessing protected property
+        expect(clientWithoutOption.failOnNetworkError).toBe(false)
+      })
     })
 
     describe('Realtime Authentication', () => {