feat(auth): allow custom predicate for detectSessionInUrl option (#1958)

Author: mandarini

packages/core/auth-js/src/GoTrueClient.ts

@@ -255,7 +255,9 @@ export default class GoTrueClient {
    * Keep extra care to never reject or throw uncaught errors
    */
   protected initializePromise: Promise<InitializeResult> | null = null
-  protected detectSessionInUrl = true
+  protected detectSessionInUrl:
+    | boolean
+    | ((url: URL, params: { [parameter: string]: string }) => boolean) = true
   protected url: string
   protected headers: {
     [key: string]: string
@@ -2100,8 +2102,15 @@ export default class GoTrueClient {
 
   /**
    * Checks if the current URL contains parameters given by an implicit oauth grant flow (https://www.rfc-editor.org/rfc/rfc6749.html#section-4.2)
+   *
+   * If `detectSessionInUrl` is a function, it will be called with the URL and params to determine
+   * if the URL should be processed as a Supabase auth callback. This allows users to exclude
+   * URLs from other OAuth providers (e.g., Facebook Login) that also return access_token in the fragment.
    */
   private _isImplicitGrantCallback(params: { [parameter: string]: string }): boolean {
+    if (typeof this.detectSessionInUrl === 'function') {
+      return this.detectSessionInUrl(new URL(window.location.href), params)
+    }
     return Boolean(params.access_token || params.error_description)
   }
 

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

@@ -74,8 +74,27 @@ export type GoTrueClientOptions = {
   headers?: { [key: string]: string }
   /* Optional key name used for storing tokens in local storage. */
   storageKey?: string
-  /* Set to "true" if you want to automatically detects OAuth grants in the URL and signs in the user. */
-  detectSessionInUrl?: boolean
+  /**
+   * Set to "true" if you want to automatically detect OAuth grants in the URL and sign in the user.
+   * Set to "false" to disable automatic detection.
+   * Set to a function to provide custom logic for determining if a URL contains a Supabase auth callback.
+   * The function receives the current URL and parsed parameters, and should return true if the URL
+   * should be processed as a Supabase auth callback, or false to ignore it.
+   *
+   * This is useful when your app uses other OAuth providers (e.g., Facebook Login) that also return
+   * access_token in the URL fragment, which would otherwise be incorrectly intercepted by Supabase Auth.
+   *
+   * @example
+   * ```ts
+   * detectSessionInUrl: (url, params) => {
+   *   // Ignore Facebook OAuth redirects
+   *   if (url.pathname === '/facebook/redirect') return false
+   *   // Use default detection for other URLs
+   *   return Boolean(params.access_token || params.error_description)
+   * }
+   * ```
+   */
+  detectSessionInUrl?: boolean | ((url: URL, params: { [parameter: string]: string }) => boolean)
   /* Set to "true" if you want to automatically refresh the token before expiring. */
   autoRefreshToken?: boolean
   /* Set to "true" if you want to automatically save the user session into local storage. If set to false, session will just be saved in memory. */

packages/core/auth-js/test/GoTrueClient.browser.test.ts

@@ -428,6 +428,158 @@ describe('Callback URL handling', () => {
 
     expect(client).toBeDefined()
   })
+
+  it('should use custom detectSessionInUrl function to filter out non-Supabase OAuth callbacks', async () => {
+    // Simulate Facebook OAuth redirect with access_token in fragment
+    window.location.href =
+      'http://localhost:9999/facebook/redirect#access_token=facebook-token&data_access_expiration_time=1658889585'
+
+    // Custom predicate to ignore Facebook OAuth redirects
+    const detectSessionInUrlFn = jest.fn((url: URL, params: { [key: string]: string }) => {
+      // Ignore Facebook OAuth redirects
+      if (url.pathname === '/facebook/redirect') return false
+      // Default behavior for other URLs
+      return Boolean(params.access_token || params.error_description)
+    })
+
+    const client = new (require('../src/GoTrueClient').default)({
+      url: 'http://localhost:9999',
+      detectSessionInUrl: detectSessionInUrlFn,
+      autoRefreshToken: false,
+      storage: mockStorage,
+    })
+
+    await client.initialize()
+
+    // The custom function should have been called
+    expect(detectSessionInUrlFn).toHaveBeenCalled()
+    expect(detectSessionInUrlFn).toHaveBeenCalledWith(
+      expect.any(URL),
+      expect.objectContaining({ access_token: 'facebook-token' })
+    )
+
+    // Session should be null because we filtered out the Facebook callback
+    const { data } = await client.getSession()
+    expect(data.session).toBeNull()
+  })
+
+  it('should process Supabase callbacks when custom detectSessionInUrl returns true', async () => {
+    // Simulate Supabase OAuth redirect
+    window.location.href =
+      'http://localhost:9999/auth/callback#access_token=supabase-token&refresh_token=test-refresh&expires_in=3600&token_type=bearer&type=implicit'
+
+    // Mock fetch for user info
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/user')) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              id: 'test-user',
+              email: '[email protected]',
+              created_at: new Date().toISOString(),
+            }),
+        })
+      }
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            access_token: 'supabase-token',
+            refresh_token: 'test-refresh',
+            expires_in: 3600,
+            token_type: 'bearer',
+            user: { id: 'test-user' },
+          }),
+      })
+    })
+
+    // Custom predicate that allows Supabase callbacks but not Facebook
+    const detectSessionInUrlFn = jest.fn((url: URL, params: { [key: string]: string }) => {
+      if (url.pathname === '/facebook/redirect') return false
+      return Boolean(params.access_token || params.error_description)
+    })
+
+    const client = new (require('../src/GoTrueClient').default)({
+      url: 'http://localhost:9999',
+      detectSessionInUrl: detectSessionInUrlFn,
+      autoRefreshToken: false,
+      storage: mockStorage,
+    })
+
+    await client.initialize()
+
+    // The custom function should have been called and returned true
+    expect(detectSessionInUrlFn).toHaveBeenCalled()
+    expect(detectSessionInUrlFn.mock.results[0].value).toBe(true)
+
+    // Session should be set because we allowed this callback
+    const { data } = await client.getSession()
+    expect(data.session).toBeDefined()
+    expect(data.session?.access_token).toBe('supabase-token')
+  })
+
+  it('should return error when custom detectSessionInUrl function throws', async () => {
+    window.location.href = 'http://localhost:9999/callback#access_token=test-token'
+
+    // Reset storage state from previous tests
+    storedSession = null
+
+    // Custom predicate that throws an error
+    const detectSessionInUrlFn = jest.fn(() => {
+      throw new Error('Custom predicate error')
+    })
+
+    const client = new (require('../src/GoTrueClient').default)({
+      url: 'http://localhost:9999',
+      detectSessionInUrl: detectSessionInUrlFn,
+      autoRefreshToken: false,
+      storage: mockStorage,
+    })
+
+    // initialize() catches errors and returns them wrapped in AuthUnknownError
+    const { error } = await client.initialize()
+
+    expect(detectSessionInUrlFn).toHaveBeenCalled()
+    expect(error).toBeDefined()
+    expect(error?.message).toBe('Unexpected error during initialization')
+    expect(error?.originalError?.message).toBe('Custom predicate error')
+  })
+
+  it('should use default behavior when detectSessionInUrl is true (boolean)', async () => {
+    window.location.href =
+      'http://localhost:9999/callback#access_token=test-token&refresh_token=test-refresh&expires_in=3600&token_type=bearer&type=implicit'
+
+    // Mock fetch for user info
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/user')) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              id: 'test-user',
+              email: '[email protected]',
+              created_at: new Date().toISOString(),
+            }),
+        })
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+    })
+
+    const client = new (require('../src/GoTrueClient').default)({
+      url: 'http://localhost:9999',
+      detectSessionInUrl: true, // Boolean true - use default behavior
+      autoRefreshToken: false,
+      storage: mockStorage,
+    })
+
+    await client.initialize()
+
+    // Should process the callback with default behavior
+    const { data } = await client.getSession()
+    expect(data.session).toBeDefined()
+    expect(data.session?.access_token).toBe('test-token')
+  })
 })
 
 describe('GoTrueClient BroadcastChannel', () => {

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

@@ -48,8 +48,26 @@ export type SupabaseClientOptions<SchemaName> = {
     persistSession?: boolean
     /**
      * Detect a session from the URL. Used for OAuth login callbacks. Defaults to true.
+     *
+     * Can be set to a function to provide custom logic for determining if a URL contains
+     * a Supabase auth callback. The function receives the current URL and parsed parameters,
+     * and should return true if the URL should be processed as a Supabase auth callback.
+     *
+     * This is useful when your app uses other OAuth providers (e.g., Facebook Login) that
+     * also return access_token in the URL fragment, which would otherwise be incorrectly
+     * intercepted by Supabase Auth.
+     *
+     * @example
+     * ```ts
+     * detectSessionInUrl: (url, params) => {
+     *   // Ignore Facebook OAuth redirects
+     *   if (url.pathname === '/facebook/redirect') return false
+     *   // Use default detection for other URLs
+     *   return Boolean(params.access_token || params.error_description)
+     * }
+     * ```
      */
-    detectSessionInUrl?: boolean
+    detectSessionInUrl?: boolean | ((url: URL, params: { [parameter: string]: string }) => boolean)
     /**
      * A storage provider. Used to store the logged-in session.
      */