@supabase/auth-js 2.107.0-beta.1 → 2.107.0-canary.0

package/src/GoTrueClient.ts

@@ -16,13 +16,11 @@ import {
   AuthInvalidTokenResponseError,
   AuthPKCECodeVerifierMissingError,
   AuthPKCEGrantCodeExchangeError,
-  AuthRefreshDiscardedError,
   AuthSessionMissingError,
   AuthUnknownError,
   isAuthApiError,
   isAuthError,
   isAuthImplicitGrantRedirectError,
-  isAuthRefreshDiscardedError,
   isAuthRetryableFetchError,
   isAuthSessionMissingError,
 } from './lib/errors'
@@ -197,17 +195,11 @@ const DEFAULT_OPTIONS: Omit<
   debug: false,
   hasCustomAuthorizationHeader: false,
   throwOnError: false,
-  lockAcquireTimeout: 5000, // 5 seconds. Only used when a custom `lock` is supplied. TODO(v3): remove.
+  lockAcquireTimeout: 5000, // 5 seconds
   skipAutoInitialize: false,
   experimental: {},
 }
 
-/**
- * No-op lock used internally as a placeholder. Kept so older test setups that
- * inject this exact reference do not break; new code never sees it because
- * `this.lock` stays `null` when no custom lock is supplied (lockless path).
- * TODO(v3): remove with the legacy lock path.
- */
 async function lockNoOp<R>(name: string, acquireTimeout: number, fn: () => Promise<R>): Promise<R> {
   return await fn()
 }
@@ -288,14 +280,6 @@ export default class GoTrueClient {
   protected autoRefreshTickTimeout: ReturnType<typeof setTimeout> | null = null
   protected visibilityChangedCallback: (() => Promise<any>) | null = null
   protected refreshingDeferred: Deferred<CallRefreshTokenResult> | null = null
-  /**
-   * Monotonic counter incremented at the top of `_removeSession`, before any
-   * `await`. The commit guard inside `_callRefreshToken` captures this value
-   * before `_saveSession` and re-checks it after, so a `signOut` that
-   * interleaves inside `_saveSession`'s storage-write awaits is still caught
-   * (the post-fetch storage snapshot alone misses that window).
-   */
-  protected _sessionRemovalEpoch = 0
   /**
    * Keeps track of the async client initialization.
    * When null or not yet resolved the auth state is `unknown`
@@ -313,19 +297,10 @@ export default class GoTrueClient {
   protected hasCustomAuthorizationHeader = false
   protected suppressGetSessionWarning = false
   protected fetch: Fetch
-  /**
-   * Custom lock function passed via `settings.lock`. When non-null, every auth
-   * operation runs inside `_acquireLock`. When null (the default), the client
-   * uses its lockless coordination (refresh single-flight + commit guard).
-   * TODO(v3): remove along with the legacy lock path.
-   */
-  protected lock: LockFunc | null = null
+  protected lock: LockFunc
   protected lockAcquired = false
   protected pendingInLock: Promise<any>[] = []
   protected throwOnError: boolean
-  /**
-   * Only consulted when a custom `lock` is supplied. TODO(v3): remove.
-   */
   protected lockAcquireTimeout: number
   /**
    * Opt-in flags for experimental features. Defaults to an empty object.
@@ -396,23 +371,19 @@ export default class GoTrueClient {
     this.url = settings.url
     this.headers = settings.headers
     this.fetch = resolveFetch(settings.fetch)
+    this.lock = settings.lock || lockNoOp
     this.detectSessionInUrl = settings.detectSessionInUrl
     this.flowType = settings.flowType
     this.hasCustomAuthorizationHeader = settings.hasCustomAuthorizationHeader
     this.throwOnError = settings.throwOnError
-
-    // Always wire `lockAcquireTimeout` even on the lockless path: consumers
-    // (including supabase-js tests) read it off the client to verify option
-    // flow-through.
     this.lockAcquireTimeout = settings.lockAcquireTimeout
 
-    // TODO(v3): remove. Legacy opt-in path preserved for backwards
-    // compatibility with callers passing a custom `lock` (typically React
-    // Native `processLock` or Node multi-process setups). When `settings.lock`
-    // is null the client uses its lockless coordination — no `navigator.locks`
-    // by default, no implicit `processLock`.
-    if (settings.lock != null) {
+    if (settings.lock) {
       this.lock = settings.lock
+    } else if (this.persistSession && isBrowser() && globalThis?.navigator?.locks) {
+      this.lock = navigatorLock
+    } else {
+      this.lock = lockNoOp
     }
 
     if (!this.jwks) {
@@ -547,13 +518,9 @@ export default class GoTrueClient {
     }
 
     this.initializePromise = (async () => {
-      if (this.lock != null) {
-        // TODO(v3): remove legacy lock path
-        return await this._acquireLock(this.lockAcquireTimeout, async () => {
-          return await this._initialize()
-        })
-      }
-      return await this._initialize()
+      return await this._acquireLock(this.lockAcquireTimeout, async () => {
+        return await this._initialize()
+      })
     })()
 
     return await this.initializePromise
@@ -1438,14 +1405,9 @@ export default class GoTrueClient {
   async exchangeCodeForSession(authCode: string): Promise<AuthTokenResponse> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return this._acquireLock(this.lockAcquireTimeout, async () => {
-        return this._exchangeCodeForSession(authCode)
-      })
-    }
-
-    return this._exchangeCodeForSession(authCode)
+    return this._acquireLock(this.lockAcquireTimeout, async () => {
+      return this._exchangeCodeForSession(authCode)
+    })
   }
 
   /**
@@ -2482,14 +2444,9 @@ export default class GoTrueClient {
   async reauthenticate(): Promise<AuthResponse> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._reauthenticate()
-      })
-    }
-
-    return await this._reauthenticate()
+    return await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._reauthenticate()
+    })
   }
 
   private async _reauthenticate(): Promise<AuthResponse> {
@@ -2636,7 +2593,7 @@ export default class GoTrueClient {
    * - If the session's access token is expired or is about to expire, this method will use the refresh token to refresh the session.
    * - When using in a browser, or you've called `startAutoRefresh()` in your environment (React Native, etc.) this function always returns a valid access token without refreshing the session itself, as this is done in the background. This function returns very fast.
    * - **IMPORTANT SECURITY NOTICE:** If using an insecure storage medium, such as cookies or request headers, the user object returned by this function **must not be trusted**. Always verify the JWT using `getClaims()` or your own JWT verification library to securely establish the user's identity and access. You can also use `getUser()` to fetch the user object directly from the Auth server for this purpose.
-   * - Cross-tab refresh races are handled by the GoTrue server (the rotated token from the first tab is returned to subsequent tabs via the parent-of-active mechanism), so no client-side serialization is needed.
+   * - When using in a browser, this function is synchronized across all tabs using the [LockManager](https://developer.mozilla.org/en-US/docs/Web/API/LockManager) API. In other environments make sure you've defined a proper `lock` property, if necessary, to make sure there are no race conditions while the session is being refreshed.
    *
    * @example Get the session data
    * ```js
@@ -2704,26 +2661,17 @@ export default class GoTrueClient {
   async getSession() {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return this._useSession(async (result) => {
-          return result
-        })
+    const result = await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return this._useSession(async (result) => {
+        return result
       })
-    }
-
-    return await this._useSession(async (result) => {
-      return result
     })
+
+    return result
   }
 
   /**
    * Acquires a global lock based on the storage key.
-   *
-   * TODO(v3): remove along with the legacy lock path. Only called when
-   * `this.lock` is non-null (custom lock supplied via constructor). The
-   * default lockless path bypasses this entirely.
    */
   private async _acquireLock<R>(acquireTimeout: number, fn: () => Promise<R>): Promise<R> {
     this._debug('#_acquireLock', 'begin', acquireTimeout)
@@ -2752,7 +2700,7 @@ export default class GoTrueClient {
         return result
       }
 
-      return await this.lock!(`lock:${this.storageKey}`, acquireTimeout, async () => {
+      return await this.lock(`lock:${this.storageKey}`, acquireTimeout, async () => {
         this._debug('#_acquireLock', 'lock acquired for storage key', this.storageKey)
 
         try {
@@ -2794,9 +2742,10 @@ export default class GoTrueClient {
   }
 
   /**
-   * Use instead of {@link #getSession} inside the library. Loads the session
-   * via `__loadSession` (which may trigger a refresh if the access token is
-   * within the expiry margin) and runs `fn` with the result.
+   * Use instead of {@link #getSession} inside the library. It is
+   * semantically usually what you want, as getting a session involves some
+   * processing afterwards that requires only one client operating on the
+   * session at once across multiple tabs or processes.
    */
   private async _useSession<R>(
     fn: (
@@ -2824,10 +2773,7 @@ export default class GoTrueClient {
     this._debug('#_useSession', 'begin')
 
     try {
-      // Concurrent callers may both reach __loadSession; storage reads are
-      // idempotent, and the only write path inside it (refresh) is
-      // single-flighted downstream by `refreshingDeferred` in
-      // `_callRefreshToken`. No serialization is needed at this layer.
+      // the use of __loadSession here is the only correct use of the function!
       const result = await this.__loadSession()
 
       return await fn(result)
@@ -2863,8 +2809,7 @@ export default class GoTrueClient {
   > {
     this._debug('#__loadSession()', 'begin')
 
-    if (this.lock != null && !this.lockAcquired) {
-      // TODO(v3): remove. Only meaningful on the legacy lock path.
+    if (!this.lockAcquired) {
       this._debug('#__loadSession()', 'used outside of an acquired lock!', new Error().stack)
     }
 
@@ -3031,15 +2976,9 @@ export default class GoTrueClient {
 
     await this.initializePromise
 
-    let result: UserResponse
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      result = await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._getUser()
-      })
-    } else {
-      result = await this._getUser()
-    }
+    const result = await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._getUser()
+    })
 
     if (result.data.user) {
       this.suppressGetSessionWarning = true
@@ -3214,14 +3153,9 @@ export default class GoTrueClient {
   ): Promise<UserResponse> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._updateUser(attributes, options)
-      })
-    }
-
-    return await this._updateUser(attributes, options)
+    return await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._updateUser(attributes, options)
+    })
   }
 
   protected async _updateUser(
@@ -3408,14 +3342,9 @@ export default class GoTrueClient {
   }): Promise<AuthResponse> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._setSession(currentSession)
-      })
-    }
-
-    return await this._setSession(currentSession)
+    return await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._setSession(currentSession)
+    })
   }
 
   protected async _setSession(currentSession: {
@@ -3604,14 +3533,9 @@ export default class GoTrueClient {
   async refreshSession(currentSession?: { refresh_token: string }): Promise<AuthResponse> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._refreshSession(currentSession)
-      })
-    }
-
-    return await this._refreshSession(currentSession)
+    return await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._refreshSession(currentSession)
+    })
   }
 
   protected async _refreshSession(currentSession?: {
@@ -3800,7 +3724,9 @@ export default class GoTrueClient {
     if (typeof this.detectSessionInUrl === 'function') {
       return this.detectSessionInUrl(new URL(window.location.href), params)
     }
-    return Boolean(params.access_token || params.error_description)
+    return Boolean(
+      params.access_token || params.error || params.error_description || params.error_code
+    )
   }
 
   /**
@@ -3859,14 +3785,9 @@ export default class GoTrueClient {
   async signOut(options: SignOut = { scope: 'global' }): Promise<{ error: AuthError | null }> {
     await this.initializePromise
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._signOut(options)
-      })
-    }
-
-    return await this._signOut(options)
+    return await this._acquireLock(this.lockAcquireTimeout, async () => {
+      return await this._signOut(options)
+    })
   }
 
   protected async _signOut(
@@ -3913,19 +3834,16 @@ export default class GoTrueClient {
   }
 
   /**
-   * Receive a notification every time an auth event happens. Common reentry
-   * patterns (`getUser`, `setSession`, reading the session from inside a
-   * handler) complete normally. One hazard remains: calling `refreshSession`
-   * (or anything that routes through `_callRefreshToken`) from inside a
-   * `TOKEN_REFRESHED` handler. `refreshingDeferred` resolves only after
-   * `_notifyAllSubscribers` returns, so the inner refresh dedupes onto the
-   * outer's unresolved promise and the two wait on each other.
+   * Avoid using an async function inside `onAuthStateChange` as you might end
+   * up with a deadlock. The callback function runs inside an exclusive lock,
+   * so calling other Supabase Client APIs that also try to acquire the
+   * exclusive lock, might cause a deadlock. This behavior is observable across
+   * tabs. In the next major library version, this behavior will not be supported.
    *
-   * @param callback A callback function to be invoked when an auth event happens.
+   * Receive a notification every time an auth event happens.
    *
-   * @deprecated Async callbacks can deadlock when they trigger a nested
-   * refresh from a `TOKEN_REFRESHED` event. Prefer the sync overload, or move
-   * refresh-triggering work outside the callback.
+   * @param callback A callback function to be invoked when an auth event happens.
+   * @deprecated Due to the possibility of deadlocks with async functions as callbacks, use the version without an async function.
    */
   onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => Promise<void>): {
     data: { subscription: Subscription }
@@ -3938,8 +3856,18 @@ export default class GoTrueClient {
    * - Subscribes to important events occurring on the user's session.
    * - Use on the frontend/client. It is less useful on the server.
    * - Events are emitted across tabs to keep your application's UI up-to-date. Some events can fire very frequently, based on the number of tabs open. Use a quick and efficient callback function, and defer or debounce as many operations as you can to be performed outside of the callback.
-   * - Callbacks can be `async` and can safely call other Supabase auth methods (`getUser`, `setSession`, etc.) from inside the callback.
-   * - Keep callbacks quick. Events are awaited in order, so a slow callback delays subsequent events to subscribers in this tab.
+   * - **Important:** A callback can be an `async` function and it runs synchronously during the processing of the changes causing the event. You can easily create a dead-lock by using `await` on a call to another method of the Supabase library.
+   *   - Avoid using `async` functions as callbacks.
+   *   - Limit the number of `await` calls in `async` callbacks.
+   *   - Do not use other Supabase functions in the callback function. If you must, dispatch the functions once the callback has finished executing. Use this as a quick way to achieve this:
+   *     ```js
+   *     supabase.auth.onAuthStateChange((event, session) => {
+   *       setTimeout(async () => {
+   *         // await on other Supabase function here
+   *         // this runs right after the callback has finished
+   *       }, 0)
+   *     })
+   *     ```
    * - Emitted events:
    *   - `INITIAL_SESSION`
    *     - Emitted right after the Supabase client is constructed and the initial session from storage is loaded.
@@ -4130,14 +4058,9 @@ export default class GoTrueClient {
     ;(async () => {
       await this.initializePromise
 
-      if (this.lock != null) {
-        // TODO(v3): remove legacy lock path
-        await this._acquireLock(this.lockAcquireTimeout, async () => {
-          this._emitInitialSession(id)
-        })
-      } else {
-        await this._emitInitialSession(id)
-      }
+      await this._acquireLock(this.lockAcquireTimeout, async () => {
+        this._emitInitialSession(id)
+      })
     })()
 
     return { data: { subscription } }
@@ -4532,10 +4455,7 @@ export default class GoTrueClient {
    * @param refreshToken A valid refresh token that was returned on login.
    */
   private async _refreshAccessToken(refreshToken: string): Promise<AuthResponse> {
-    // Refresh tokens are long-lived bearer credentials; do NOT include any
-    // fragment of the token in the debug tag, even when `debug: true` is
-    // enabled (logs may be forwarded to third-party services).
-    const debugName = `#_refreshAccessToken()`
+    const debugName = `#_refreshAccessToken(${refreshToken.substring(0, 5)}...)`
     this._debug(debugName, 'begin')
 
     try {
@@ -4688,22 +4608,15 @@ export default class GoTrueClient {
           const { error } = await this._callRefreshToken(currentSession.refresh_token)
 
           if (error) {
-            // AuthRefreshDiscardedError means a concurrent signOut already
-            // cleared storage and fired SIGNED_OUT. Don't run _removeSession
-            // again here, or we'll emit a duplicate SIGNED_OUT.
-            if (isAuthRefreshDiscardedError(error)) {
-              this._debug(debugName, 'refresh discarded by commit guard', error)
-            } else {
-              console.error(error)
-
-              if (!isAuthRetryableFetchError(error)) {
-                this._debug(
-                  debugName,
-                  'refresh failed with a non-retryable error, removing the session',
-                  error
-                )
-                await this._removeSession()
-              }
+            console.error(error)
+
+            if (!isAuthRetryableFetchError(error)) {
+              this._debug(
+                debugName,
+                'refresh failed with a non-retryable error, removing the session',
+                error
+              )
+              await this._removeSession()
             }
           }
         }
@@ -4756,85 +4669,18 @@ export default class GoTrueClient {
       return this.refreshingDeferred.promise
     }
 
-    // Refresh tokens are long-lived bearer credentials; do NOT include any
-    // fragment of the token in the debug tag, even when `debug: true` is
-    // enabled (logs may be forwarded to third-party services).
-    const debugName = `#_callRefreshToken()`
+    const debugName = `#_callRefreshToken(${refreshToken.substring(0, 5)}...)`
 
     this._debug(debugName, 'begin')
 
     try {
       this.refreshingDeferred = new Deferred<CallRefreshTokenResult>()
 
-      // Snapshot storage before the fetch. The commit guard discards the
-      // rotated tokens only when a non-null pre-fetch snapshot changed under
-      // us — typical case: a concurrent `signOut` ran `_removeSession`, or
-      // another tab's refresh rewrote the slot. Callers passing
-      // externally-sourced tokens (SSR cookie handoff, multi-account
-      // switching, `setSession`/`refreshSession({ refresh_token })`) may
-      // start from a null snapshot OR from a non-null snapshot whose
-      // refresh_token differs from the one they're hydrating; in both
-      // cases the guard fires only when storage was *modified between
-      // snapshots*, not when the input token disagrees with what's stored.
-      const storedAtStart = (await getItemAsync(this.storage, this.storageKey)) as Session | null
-
       const { data, error } = await this._refreshAccessToken(refreshToken)
       if (error) throw error
       if (!data.session) throw new AuthSessionMissingError()
 
-      const storedAfter = (await getItemAsync(this.storage, this.storageKey)) as Session | null
-      const storageChangedUnderUs =
-        storedAtStart !== null &&
-        (storedAfter === null || storedAfter.refresh_token !== storedAtStart.refresh_token)
-
-      if (storageChangedUnderUs) {
-        this._debug(
-          debugName,
-          'commit guard: storage changed since refresh started, discarding rotated tokens',
-          {
-            // Presence indicators only — never log refresh token fragments,
-            // even partial. Logs may be forwarded to third-party services.
-            startedWith: 'present',
-            nowHolds: storedAfter ? 'replaced' : 'cleared',
-          }
-        )
-        const discarded: CallRefreshTokenResult = {
-          data: null,
-          error: new AuthRefreshDiscardedError(),
-        }
-        this.refreshingDeferred.resolve(discarded)
-        return discarded
-      }
-
-      // Second leg of the commit guard: close the TOCTOU window between the
-      // synchronous `storageChangedUnderUs` check and the actual storage
-      // writes inside `_saveSession`. A concurrent `signOut → _removeSession`
-      // can land inside `_saveSession`'s `await setItemAsync(...)` yields and
-      // clear storage just before we overwrite it. Capture the epoch BEFORE
-      // the save and re-check after; if it advanced, undo the write directly
-      // (do NOT call `_removeSession` — that would emit a duplicate
-      // SIGNED_OUT for the concurrent signOut that already fired one).
-      const epochBeforeSave = this._sessionRemovalEpoch
-
       await this._saveSession(data.session)
-
-      if (this._sessionRemovalEpoch !== epochBeforeSave) {
-        this._debug(
-          debugName,
-          'commit guard (post-save): _removeSession ran during _saveSession, undoing write'
-        )
-        await removeItemAsync(this.storage, this.storageKey)
-        if (this.userStorage) {
-          await removeItemAsync(this.userStorage, this.storageKey + '-user')
-        }
-        const discarded: CallRefreshTokenResult = {
-          data: null,
-          error: new AuthRefreshDiscardedError(),
-        }
-        this.refreshingDeferred.resolve(discarded)
-        return discarded
-      }
-
       await this._notifyAllSubscribers('TOKEN_REFRESHED', data.session)
 
       const result = { data: data.session, error: null }
@@ -4946,11 +4792,6 @@ export default class GoTrueClient {
   }
 
   private async _removeSession() {
-    // Bump synchronously, BEFORE any `await`, so that `_callRefreshToken`'s
-    // post-save check sees the increment whenever this method has started —
-    // even if it hasn't finished. Pairs with the epoch check in
-    // `_callRefreshToken`. See `_sessionRemovalEpoch` field doc.
-    this._sessionRemovalEpoch += 1
     this._debug('#_removeSession()')
 
     this.suppressGetSessionWarning = false
@@ -5139,144 +4980,58 @@ export default class GoTrueClient {
     await this._stopAutoRefresh()
   }
 
-  /**
-   * Tears down the client's background work: stops the auto-refresh interval,
-   * removes the `visibilitychange` listener, closes the cross-tab
-   * `BroadcastChannel`, and clears registered `onAuthStateChange` subscribers.
-   *
-   * Call this from cleanup hooks when the client is being replaced before
-   * its JS realm is destroyed. React Strict Mode and HMR are the common
-   * cases. Any in-flight `fetch` calls continue to completion and may still
-   * write to storage; dispose doesn't abort them or erase storage.
-   *
-   * Lifecycle caveat: because in-flight refreshes are not aborted, a
-   * disposed instance can still persist a rotated session to storage after
-   * `dispose()` returns. A subsequent `createClient` against the same
-   * `storageKey` will pick up that session on its next read. If you need
-   * strict isolation between client lifecycles, await any pending auth
-   * operation before calling `dispose()` (or change the `storageKey` for
-   * the replacement client).
-   *
-   * Safe to call repeatedly.
-   *
-   * @category Auth
-   *
-   * @example Cleanup on React unmount
-   * ```ts
-   * useEffect(() => {
-   *   const client = createClient(...)
-   *   return () => { client.auth.dispose() }
-   * }, [])
-   * ```
-   */
-  async dispose(): Promise<void> {
-    this._removeVisibilityChangedCallback()
-    await this._stopAutoRefresh()
-    this.broadcastChannel?.close()
-    this.broadcastChannel = null
-    this.stateChangeEmitters.clear()
-  }
-
   /**
    * Runs the auto refresh token tick.
    */
   private async _autoRefreshTokenTick() {
     this._debug('#_autoRefreshTokenTick()', 'begin')
 
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path. Uses `_acquireLock(0, ...)` which
-      // throws `LockAcquireTimeoutError` immediately if the lock is held —
-      // that's the fail-fast skip path that lets the tick bail out instead
-      // of queuing behind a long-running operation.
-      try {
-        await this._acquireLock(0, async () => {
-          try {
-            const now = Date.now()
-            try {
-              return await this._useSession(async (result) => {
-                const {
-                  data: { session },
-                } = result
-
-                if (!session || !session.refresh_token || !session.expires_at) {
-                  this._debug('#_autoRefreshTokenTick()', 'no session')
-                  return
-                }
-
-                const expiresInTicks = Math.floor(
-                  (session.expires_at * 1000 - now) / AUTO_REFRESH_TICK_DURATION_MS
-                )
-
-                this._debug(
-                  '#_autoRefreshTokenTick()',
-                  `access token expires in ${expiresInTicks} ticks, a tick lasts ${AUTO_REFRESH_TICK_DURATION_MS}ms, refresh threshold is ${AUTO_REFRESH_TICK_THRESHOLD} ticks`
-                )
-
-                if (expiresInTicks <= AUTO_REFRESH_TICK_THRESHOLD) {
-                  await this._callRefreshToken(session.refresh_token)
-                }
-              })
-            } catch (e) {
-              console.error(
-                'Auto refresh tick failed with error. This is likely a transient error.',
-                e
-              )
-            }
-          } finally {
-            this._debug('#_autoRefreshTokenTick()', 'end')
-          }
-        })
-      } catch (e) {
-        if (e instanceof LockAcquireTimeoutError) {
-          this._debug('auto refresh token tick lock not available')
-        } else {
-          throw e
-        }
-      }
-      return
-    }
-
-    // Lockless default: skip if a refresh is already in flight.
-    // `_callRefreshToken` also dedupes via the same field; this is just a
-    // fast-path skip to avoid an unnecessary storage read.
-    if (this.refreshingDeferred !== null) {
-      this._debug('#_autoRefreshTokenTick()', 'refresh already in flight, skipping')
-      return
-    }
-
     try {
-      const now = Date.now()
-
-      try {
-        await this._useSession(async (result) => {
-          const {
-            data: { session },
-          } = result
+      await this._acquireLock(0, async () => {
+        try {
+          const now = Date.now()
 
-          if (!session || !session.refresh_token || !session.expires_at) {
-            this._debug('#_autoRefreshTokenTick()', 'no session')
-            return
-          }
+          try {
+            return await this._useSession(async (result) => {
+              const {
+                data: { session },
+              } = result
+
+              if (!session || !session.refresh_token || !session.expires_at) {
+                this._debug('#_autoRefreshTokenTick()', 'no session')
+                return
+              }
 
-          // session will expire in this many ticks (or has already expired if <= 0)
-          const expiresInTicks = Math.floor(
-            (session.expires_at * 1000 - now) / AUTO_REFRESH_TICK_DURATION_MS
-          )
+              // session will expire in this many ticks (or has already expired if <= 0)
+              const expiresInTicks = Math.floor(
+                (session.expires_at * 1000 - now) / AUTO_REFRESH_TICK_DURATION_MS
+              )
 
-          this._debug(
-            '#_autoRefreshTokenTick()',
-            `access token expires in ${expiresInTicks} ticks, a tick lasts ${AUTO_REFRESH_TICK_DURATION_MS}ms, refresh threshold is ${AUTO_REFRESH_TICK_THRESHOLD} ticks`
-          )
+              this._debug(
+                '#_autoRefreshTokenTick()',
+                `access token expires in ${expiresInTicks} ticks, a tick lasts ${AUTO_REFRESH_TICK_DURATION_MS}ms, refresh threshold is ${AUTO_REFRESH_TICK_THRESHOLD} ticks`
+              )
 
-          if (expiresInTicks <= AUTO_REFRESH_TICK_THRESHOLD) {
-            await this._callRefreshToken(session.refresh_token)
+              if (expiresInTicks <= AUTO_REFRESH_TICK_THRESHOLD) {
+                await this._callRefreshToken(session.refresh_token)
+              }
+            })
+          } catch (e) {
+            console.error(
+              'Auto refresh tick failed with error. This is likely a transient error.',
+              e
+            )
           }
-        })
-      } catch (e) {
-        console.error('Auto refresh tick failed with error. This is likely a transient error.', e)
+        } finally {
+          this._debug('#_autoRefreshTokenTick()', 'end')
+        }
+      })
+    } catch (e) {
+      if (e instanceof LockAcquireTimeoutError) {
+        this._debug('auto refresh token tick lock not available')
+      } else {
+        throw e
       }
-    } finally {
-      this._debug('#_autoRefreshTokenTick()', 'end')
     }
   }
 
@@ -5333,29 +5088,24 @@ export default class GoTrueClient {
       if (!calledFromInitialize) {
         // called when the visibility has changed, i.e. the browser
         // transitioned from hidden -> visible so we need to see if the session
-        // should be recovered
+        // should be recovered immediately... but to do that we need to acquire
+        // the lock first asynchronously
         await this.initializePromise
 
-        if (this.lock != null) {
-          // TODO(v3): remove legacy lock path
-          await this._acquireLock(this.lockAcquireTimeout, async () => {
-            if (document.visibilityState !== 'visible') {
-              this._debug(
-                methodName,
-                'acquired the lock to recover the session, but the browser visibilityState is no longer visible, aborting'
-              )
-              return
-            }
-            await this._recoverAndRefresh()
-          })
-        } else {
+        await this._acquireLock(this.lockAcquireTimeout, async () => {
           if (document.visibilityState !== 'visible') {
-            this._debug(methodName, 'visibilityState is no longer visible, skipping recovery')
+            this._debug(
+              methodName,
+              'acquired the lock to recover the session, but the browser visibilityState is no longer visible, aborting'
+            )
+
+            // visibility has changed while waiting for the lock, abort
             return
           }
+
           // recover the session
           await this._recoverAndRefresh()
-        }
+        })
       }
     } else if (document.visibilityState === 'hidden') {
       if (this.autoRefreshToken) {
@@ -5487,7 +5237,7 @@ export default class GoTrueClient {
     params: MFAVerifyWebauthnParams<T>
   ): Promise<AuthMFAVerifyResponse>
   private async _verify(params: MFAVerifyParams): Promise<AuthMFAVerifyResponse> {
-    const run = async (): Promise<AuthMFAVerifyResponse> => {
+    return this._acquireLock(this.lockAcquireTimeout, async () => {
       try {
         return await this._useSession(async (result) => {
           const { data: sessionData, error: sessionError } = result
@@ -5558,13 +5308,7 @@ export default class GoTrueClient {
         }
         throw error
       }
-    }
-
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return this._acquireLock(this.lockAcquireTimeout, run)
-    }
-    return run()
+    })
   }
 
   /**
@@ -5580,7 +5324,7 @@ export default class GoTrueClient {
     params: MFAChallengeWebauthnParams
   ): Promise<Prettify<AuthMFAChallengeWebauthnResponse>>
   private async _challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse> {
-    const run = async (): Promise<AuthMFAChallengeResponse> => {
+    return this._acquireLock(this.lockAcquireTimeout, async () => {
       try {
         return await this._useSession(async (result) => {
           const { data: sessionData, error: sessionError } = result
@@ -5653,13 +5397,7 @@ export default class GoTrueClient {
         }
         throw error
       }
-    }
-
-    if (this.lock != null) {
-      // TODO(v3): remove legacy lock path
-      return this._acquireLock(this.lockAcquireTimeout, run)
-    }
-    return run()
+    })
   }
 
   /**
@@ -5668,6 +5406,9 @@ export default class GoTrueClient {
   private async _challengeAndVerify(
     params: MFAChallengeAndVerifyParams
   ): Promise<AuthMFAVerifyResponse> {
+    // both _challenge and _verify independently acquire the lock, so no need
+    // to acquire it here
+
     const { data: challengeData, error: challengeError } = await this._challenge({
       factorId: params.factorId,
     })
@@ -5686,6 +5427,7 @@ export default class GoTrueClient {
    * {@see GoTrueMFAApi#listFactors}
    */
   private async _listFactors(): Promise<AuthMFAListFactorsResponse> {
+    // use #getUser instead of #_getUser as the former acquires a lock
     const {
       data: { user },
       error: userError,
@@ -6165,8 +5907,13 @@ export default class GoTrueClient {
       } = decodeJWT(token)
 
       if (!options?.allowExpired) {
-        // Reject expired JWTs should only happen if jwt argument was passed
-        validateExp(payload.exp)
+        // Reject expired JWTs should only happen if jwt argument was passed.
+        // Rethrow as AuthInvalidJwtError so the outer catch converts it to { data, error }.
+        try {
+          validateExp(payload.exp)
+        } catch (e) {
+          throw new AuthInvalidJwtError(e instanceof Error ? e.message : 'JWT validation failed')
+        }
       }
 
       const signingKey =