@depup/supabase__auth-js 2.103.0-depup.0 → 2.110.8-depup.0

package/src/GoTrueClient.ts

@@ -6,6 +6,7 @@ import {
   EXPIRY_MARGIN_MS,
   GOTRUE_URL,
   JWKS_TTL,
+  REFRESH_FAILURE_COOLDOWN_MS,
   STORAGE_KEY,
 } from './lib/constants'
 import {
@@ -16,11 +17,13 @@ import {
   AuthInvalidTokenResponseError,
   AuthPKCECodeVerifierMissingError,
   AuthPKCEGrantCodeExchangeError,
+  AuthRefreshDiscardedError,
   AuthSessionMissingError,
   AuthUnknownError,
   isAuthApiError,
   isAuthError,
   isAuthImplicitGrantRedirectError,
+  isAuthRefreshDiscardedError,
   isAuthRetryableFetchError,
   isAuthSessionMissingError,
 } from './lib/errors'
@@ -33,6 +36,7 @@ import {
   _userResponse,
 } from './lib/fetch'
 import {
+  assertPasskeyExperimentalEnabled,
   decodeJWT,
   deepClone,
   Deferred,
@@ -136,6 +140,22 @@ import type {
   UserResponse,
   VerifyOtpParams,
   Web3Credentials,
+  AuthPasskeyApi,
+  ExperimentalFeatureFlags,
+  SignInWithPasskeyCredentials,
+  RegisterPasskeyCredentials,
+  VerifyPasskeyRegistrationParams,
+  StartPasskeyAuthenticationParams,
+  VerifyPasskeyAuthenticationParams,
+  PasskeyUpdateParams,
+  PasskeyDeleteParams,
+  AuthPasskeyRegistrationOptionsResponse,
+  AuthPasskeyRegistrationVerifyResponse,
+  AuthPasskeyAuthenticationOptionsResponse,
+  AuthPasskeyAuthenticationVerifyResponse,
+  AuthPasskeyListResponse,
+  AuthPasskeyUpdateResponse,
+  AuthPasskeyDeleteResponse,
 } from './lib/types'
 import {
   createSiweMessage,
@@ -146,10 +166,14 @@ import {
   toHex,
 } from './lib/web3/ethereum'
 import {
+  createCredential,
   deserializeCredentialCreationOptions,
   deserializeCredentialRequestOptions,
+  getCredential,
   serializeCredentialCreationResponse,
   serializeCredentialRequestResponse,
+  browserSupportsWebAuthn,
+  webAuthnAbortService,
   WebAuthnApi,
 } from './lib/webauthn'
 import {
@@ -174,10 +198,17 @@ const DEFAULT_OPTIONS: Omit<
   debug: false,
   hasCustomAuthorizationHeader: false,
   throwOnError: false,
-  lockAcquireTimeout: 5000, // 5 seconds
+  lockAcquireTimeout: 5000, // 5 seconds. Only used when a custom `lock` is supplied. TODO(v3): remove.
   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()
 }
@@ -212,6 +243,13 @@ export default class GoTrueClient {
    * Used to implement the authorization code flow on the consent page.
    */
   oauth: AuthOAuthServerApi
+  /**
+   * Namespace for passkey methods.
+   * Includes lower-level two-step registration/authentication and passkey management.
+   *
+   * Requires `auth.experimental.passkey: true`; otherwise all methods throw.
+   */
+  passkey: AuthPasskeyApi
   /**
    * The storage key used to identify the values saved in localStorage
    */
@@ -251,6 +289,33 @@ export default class GoTrueClient {
   protected autoRefreshTickTimeout: ReturnType<typeof setTimeout> | null = null
   protected visibilityChangedCallback: (() => Promise<any>) | null = null
   protected refreshingDeferred: Deferred<CallRefreshTokenResult> | null = null
+  /**
+   * Cache of the most recent refresh failure, keyed by the refresh token
+   * that failed. Serial callers passing the *same* token within
+   * `REFRESH_FAILURE_COOLDOWN_MS` (including subsequent auto-refresh ticks)
+   * receive this cached result instead of firing another `/token` request.
+   * Callers passing a *different* token (token rotation pickup, explicit
+   * `setSession`/`refreshSession({ refresh_token })`, multi-account switch)
+   * bypass the cache and attempt a fresh refresh as they should.
+   * Cleared on any successful refresh (locally or via BroadcastChannel from
+   * another tab) and on `_removeSession`.
+   *
+   * Pairs with `refreshingDeferred`: concurrent callers share the in-flight
+   * promise, serial callers within the cooldown share the failure result.
+   */
+  protected lastRefreshFailure: {
+    refreshToken: string
+    result: CallRefreshTokenResult
+    expiresAt: number
+  } | 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`
@@ -258,6 +323,23 @@ export default class GoTrueClient {
    * Keep extra care to never reject or throw uncaught errors
    */
   protected initializePromise: Promise<InitializeResult> | null = null
+  /**
+   * Non-null only while `initialize()` is running. While open,
+   * `_notifyAllSubscribers` enqueues init-chain notifications (those fired with
+   * `broadcast = true`, i.e. from `_recoverAndRefresh`) into this array instead
+   * of firing directly, so that `initializePromise` is guaranteed to be
+   * resolved before any subscriber callback runs. Callbacks that call
+   * `getSession()` / `getUser()` etc. would otherwise deadlock because those
+   * methods await `initializePromise`. Notifications from the incoming
+   * BroadcastChannel handler (`broadcast = false`) are not enqueued — they fire
+   * immediately. Flushed (in order) by `initialize()` after `initializePromise`
+   * settles.
+   */
+  private _pendingInitNotifications: Array<{
+    event: AuthChangeEvent
+    session: Session | null
+    broadcast: boolean
+  }> | null = null
   protected detectSessionInUrl:
     | boolean
     | ((url: URL, params: { [parameter: string]: string }) => boolean) = true
@@ -268,11 +350,25 @@ export default class GoTrueClient {
   protected hasCustomAuthorizationHeader = false
   protected suppressGetSessionWarning = false
   protected fetch: Fetch
-  protected lock: LockFunc
+  /**
+   * 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 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.
+   * See `GoTrueClientOptions.experimental`.
+   */
+  protected experimental: ExperimentalFeatureFlags
 
   /**
    * Used to broadcast state change events to other tabs listening.
@@ -285,13 +381,21 @@ export default class GoTrueClient {
   /**
    * Create a new client for use in the browser.
    *
-   * @example
+   * @example Using supabase-js (recommended)
+   * ```ts
+   * import { createClient } from '@supabase/supabase-js'
+   *
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
+   * const { data, error } = await supabase.auth.getUser()
+   * ```
+   *
+   * @example Standalone import for bundle-sensitive environments
    * ```ts
    * import { GoTrueClient } from '@supabase/auth-js'
    *
    * const auth = new GoTrueClient({
    *   url: 'https://xyzcompany.supabase.co/auth/v1',
-   *   headers: { apikey: 'public-anon-key' },
+   *   headers: { apikey: 'your-publishable-key' },
    *   storageKey: 'supabase-auth',
    * })
    * ```
@@ -318,28 +422,34 @@ export default class GoTrueClient {
 
     this.persistSession = settings.persistSession
     this.autoRefreshToken = settings.autoRefreshToken
+    this.experimental = settings.experimental ?? {}
     this.admin = new GoTrueAdminApi({
       url: settings.url,
       headers: settings.headers,
       fetch: settings.fetch,
+      experimental: this.experimental,
     })
 
     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
 
-    if (settings.lock) {
+    // 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) {
       this.lock = settings.lock
-    } else if (this.persistSession && isBrowser() && globalThis?.navigator?.locks) {
-      this.lock = navigatorLock
-    } else {
-      this.lock = lockNoOp
     }
 
     if (!this.jwks) {
@@ -366,6 +476,16 @@ export default class GoTrueClient {
       revokeGrant: this._revokeOAuthGrant.bind(this),
     }
 
+    this.passkey = {
+      startRegistration: this._startPasskeyRegistration.bind(this),
+      verifyRegistration: this._verifyPasskeyRegistration.bind(this),
+      startAuthentication: this._startPasskeyAuthentication.bind(this),
+      verifyAuthentication: this._verifyPasskeyAuthentication.bind(this),
+      list: this._listPasskeys.bind(this),
+      update: this._updatePasskey.bind(this),
+      delete: this._deletePasskey.bind(this),
+    }
+
     if (this.persistSession) {
       if (settings.storage) {
         this.storage = settings.storage
@@ -389,7 +509,7 @@ export default class GoTrueClient {
     if (isBrowser() && globalThis.BroadcastChannel && this.persistSession && this.storageKey) {
       try {
         this.broadcastChannel = new globalThis.BroadcastChannel(this.storageKey)
-      } catch (e: any) {
+      } catch (e) {
         console.error(
           'Failed to create a new BroadcastChannel, multi-tab state changes will not be available',
           e
@@ -399,6 +519,13 @@ export default class GoTrueClient {
       this.broadcastChannel?.addEventListener('message', async (event) => {
         this._debug('received broadcast notification from other tab or client', event)
 
+        // Another tab successfully refreshed or signed in — any cached
+        // failure in this tab is stale and should not block the next
+        // refresh attempt.
+        if (event.data.event === 'TOKEN_REFRESHED' || event.data.event === 'SIGNED_IN') {
+          this.lastRefreshFailure = null
+        }
+
         try {
           await this._notifyAllSubscribers(event.data.event, event.data.session, false) // broadcast = false so we don't get an endless loop of messages
         } catch (error) {
@@ -452,9 +579,20 @@ export default class GoTrueClient {
   }
 
   /**
-   * Initializes the client session either from the url or from storage.
-   * This method is automatically called when instantiating the client, but should also be called
-   * manually when checking for an error from an auth redirect (oauth, magiclink, password recovery, etc).
+   * Initialize the auth client by loading the session from storage or
+   * detecting it from the URL after an OAuth, magic-link, or password-recovery
+   * redirect.
+   *
+   * **Most callers do not need to invoke this directly.** The client calls it
+   * automatically during construction, and to react to sign-in events (including
+   * post-redirect events) you should subscribe to `onAuthStateChange` rather
+   * than awaiting `initialize()`.
+   *
+   * You only need to call it manually when you have opted out of the automatic
+   * call by passing `skipAutoInitialize: true` — for example, in an SSR context
+   * where you need to control initialization timing. In that case, awaiting
+   * `initialize()` returns the resolved session result (or any error encountered
+   * while detecting it from the URL).
    *
    * @category Auth
    */
@@ -463,13 +601,37 @@ export default class GoTrueClient {
       return await this.initializePromise
     }
 
+    // Open the notification queue before _initialize() runs so that every
+    // _notifyAllSubscribers call inside the init chain enqueues instead of
+    // firing. Without this, a callback receiving SIGNED_IN (or TOKEN_REFRESHED
+    // / SIGNED_OUT) during _recoverAndRefresh would deadlock if it called
+    // getSession() / getUser() — those methods await initializePromise, which
+    // can only resolve after the callback returns, which can only return after
+    // getSession() resolves. The queue is flushed below after initializePromise
+    // has settled, so callbacks run with a fully resolved initializePromise.
+    this._pendingInitNotifications = []
+
     this.initializePromise = (async () => {
-      return await this._acquireLock(this.lockAcquireTimeout, async () => {
-        return await this._initialize()
-      })
+      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.initializePromise
+    const result = await this.initializePromise
+
+    // initializePromise is now resolved — flush queued notifications in order.
+    // Callbacks can safely call getSession() / getUser() / signOut() etc.
+    const queue = this._pendingInitNotifications ?? []
+    this._pendingInitNotifications = null
+    for (const n of queue) {
+      await this._notifyAllSubscribers(n.event, n.session, n.broadcast)
+    }
+
+    return result
   }
 
   /**
@@ -1029,6 +1191,21 @@ export default class GoTrueClient {
    *   password: 'some-password',
    * })
    * ```
+   *
+   * @exampleDescription Handling errors
+   * Log the full `error` object so fields like `code`, `status`, and `name` aren't hidden. The `error.code` (e.g. `'invalid_credentials'`, `'email_not_confirmed'`) is often more useful for branching than `error.message`, and the full object surfaces both.
+   *
+   * @example Handling errors
+   * ```js
+   * const { data, error } = await supabase.auth.signInWithPassword({
+   *   email: 'example@email.com',
+   *   password: 'example-password',
+   * })
+   * if (error) {
+   *   console.error(error)
+   *   return
+   * }
+   * ```
    */
   async signInWithPassword(
     credentials: SignInWithPasswordCredentials
@@ -1351,9 +1528,14 @@ export default class GoTrueClient {
   async exchangeCodeForSession(authCode: string): Promise<AuthTokenResponse> {
     await this.initializePromise
 
-    return this._acquireLock(this.lockAcquireTimeout, async () => {
-      return this._exchangeCodeForSession(authCode)
-    })
+    if (this.lock != null) {
+      // TODO(v3): remove legacy lock path
+      return this._acquireLock(this.lockAcquireTimeout, async () => {
+        return this._exchangeCodeForSession(authCode)
+      })
+    }
+
+    return this._exchangeCodeForSession(authCode)
   }
 
   /**
@@ -1827,7 +2009,10 @@ export default class GoTrueClient {
       }
       if (data.session) {
         await this._saveSession(data.session)
-        await this._notifyAllSubscribers('SIGNED_IN', data.session)
+        await this._notifyAllSubscribers(
+          redirectType === 'recovery' ? 'PASSWORD_RECOVERY' : 'SIGNED_IN',
+          data.session
+        )
       }
       return this._returnResult({ data: { ...data, redirectType: redirectType ?? null }, error })
     } catch (error) {
@@ -2248,7 +2433,7 @@ export default class GoTrueClient {
       }
 
       const session: Session | null = data.session
-      const user: User = data.user
+      const user: User | null = data.user
 
       if (session?.access_token) {
         await this._saveSession(session as Session)
@@ -2387,9 +2572,14 @@ export default class GoTrueClient {
   async reauthenticate(): Promise<AuthResponse> {
     await this.initializePromise
 
-    return await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._reauthenticate()
-    })
+    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()
   }
 
   private async _reauthenticate(): Promise<AuthResponse> {
@@ -2480,15 +2670,28 @@ export default class GoTrueClient {
       const endpoint = `${this.url}/resend`
       if ('email' in credentials) {
         const { email, type, options } = credentials
+        let codeChallenge: string | null = null
+        let codeChallengeMethod: string | null = null
+        if (this.flowType === 'pkce') {
+          ;[codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(
+            this.storage,
+            this.storageKey
+          )
+        }
         const { error } = await _request(this.fetch, 'POST', endpoint, {
           headers: this.headers,
           body: {
             email,
             type,
             gotrue_meta_security: { captcha_token: options?.captchaToken },
+            code_challenge: codeChallenge,
+            code_challenge_method: codeChallengeMethod,
           },
           redirectTo: options?.emailRedirectTo,
         })
+        if (error) {
+          await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+        }
         return this._returnResult({ data: { user: null, session: null }, error })
       } else if ('phone' in credentials) {
         const { phone, type, options } = credentials
@@ -2509,6 +2712,7 @@ export default class GoTrueClient {
         'You must provide either an email or phone number and a type'
       )
     } catch (error) {
+      await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
       if (isAuthError(error)) {
         return this._returnResult({ data: { user: null, session: null }, error })
       }
@@ -2525,7 +2729,7 @@ export default class GoTrueClient {
    * to the client. If that storage is based on request cookies for example,
    * the values in it may not be authentic and therefore it's strongly advised
    * against using this method and its results in such circumstances. A warning
-   * will be emitted if this is detected. Use {@link #getUser()} instead.
+   * will be emitted if this is detected. Use {@link GoTrueClient.getUser} instead.
    *
    * @category Auth
    *
@@ -2536,7 +2740,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.
-   * - 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.
+   * - 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.
    *
    * @example Get the session data
    * ```js
@@ -2604,17 +2808,26 @@ export default class GoTrueClient {
   async getSession() {
     await this.initializePromise
 
-    const result = await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return this._useSession(async (result) => {
-        return result
+    if (this.lock != null) {
+      // TODO(v3): remove legacy lock path
+      return await this._acquireLock(this.lockAcquireTimeout, async () => {
+        return this._useSession(async (result) => {
+          return result
+        })
       })
-    })
+    }
 
-    return result
+    return await this._useSession(async (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)
@@ -2634,7 +2847,7 @@ export default class GoTrueClient {
           (async () => {
             try {
               await result
-            } catch (e: any) {
+            } catch (_e) {
               // we just care if it finished
             }
           })()
@@ -2643,7 +2856,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 {
@@ -2685,10 +2898,9 @@ export default class GoTrueClient {
   }
 
   /**
-   * 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.
+   * Use instead of {@link GoTrueClient.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.
    */
   private async _useSession<R>(
     fn: (
@@ -2716,7 +2928,10 @@ export default class GoTrueClient {
     this._debug('#_useSession', 'begin')
 
     try {
-      // the use of __loadSession here is the only correct use of the function!
+      // 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.
       const result = await this.__loadSession()
 
       return await fn(result)
@@ -2728,7 +2943,7 @@ export default class GoTrueClient {
   /**
    * NEVER USE DIRECTLY!
    *
-   * Always use {@link #_useSession}.
+   * Always use `_useSession`.
    */
   private async __loadSession(): Promise<
     | {
@@ -2752,7 +2967,8 @@ export default class GoTrueClient {
   > {
     this._debug('#__loadSession()', 'begin')
 
-    if (!this.lockAcquired) {
+    if (this.lock != null && !this.lockAcquired) {
+      // TODO(v3): remove. Only meaningful on the legacy lock path.
       this._debug('#__loadSession()', 'used outside of an acquired lock!', new Error().stack)
     }
 
@@ -2827,6 +3043,27 @@ export default class GoTrueClient {
 
       const { data: session, error } = await this._callRefreshToken(currentSession.refresh_token)
       if (error) {
+        // Proactive-preserve mirror: `_callRefreshToken` keeps the session
+        // in storage when refresh fails non-retryably but the access token
+        // is still inside its real expiry window. Hand the caller the
+        // still-valid session instead of translating the refresh error
+        // into `session: null`. If the access token has actually expired,
+        // the session is genuinely dead and the error stands. Explicit
+        // refresh entry points (`refreshSession`, `setSession`)
+        // intentionally bypass this fallback — they want to know the
+        // refresh failed.
+        const accessTokenStillValid = !!(
+          currentSession.expires_at && currentSession.expires_at * 1000 > Date.now()
+        )
+        if (accessTokenStillValid) {
+          // Race guard: a concurrent `signOut` may have cleared storage
+          // during the refresh attempt. Don't hand back a session that no
+          // longer exists on disk.
+          const stillStored = (await getItemAsync(this.storage, this.storageKey)) as Session | null
+          if (stillStored && stillStored.refresh_token === currentSession.refresh_token) {
+            return this._returnResult({ data: { session: currentSession }, error: null })
+          }
+        }
         return this._returnResult({ data: { session: null }, error })
       }
 
@@ -2919,9 +3156,15 @@ export default class GoTrueClient {
 
     await this.initializePromise
 
-    const result = await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._getUser()
-    })
+    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()
+    }
 
     if (result.data.user) {
       this.suppressGetSessionWarning = true
@@ -3096,9 +3339,14 @@ export default class GoTrueClient {
   ): Promise<UserResponse> {
     await this.initializePromise
 
-    return await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._updateUser(attributes, options)
-    })
+    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)
   }
 
   protected async _updateUser(
@@ -3285,9 +3533,14 @@ export default class GoTrueClient {
   }): Promise<AuthResponse> {
     await this.initializePromise
 
-    return await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._setSession(currentSession)
-    })
+    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)
   }
 
   protected async _setSession(currentSession: {
@@ -3476,9 +3729,14 @@ export default class GoTrueClient {
   async refreshSession(currentSession?: { refresh_token: string }): Promise<AuthResponse> {
     await this.initializePromise
 
-    return await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._refreshSession(currentSession)
-    })
+    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)
   }
 
   protected async _refreshSession(currentSession?: {
@@ -3576,7 +3834,10 @@ export default class GoTrueClient {
 
         window.history.replaceState(window.history.state, '', url.toString())
 
-        return { data: { session: data.session, redirectType: null }, error: null }
+        return {
+          data: { session: data.session, redirectType: data.redirectType ?? null },
+          error: null,
+        }
       }
 
       const {
@@ -3664,7 +3925,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
+    )
   }
 
   /**
@@ -3687,24 +3950,35 @@ export default class GoTrueClient {
    *
    * If using `others` scope, no `SIGNED_OUT` event is fired!
    *
+   * **Warning:** the default `scope` is `'global'`. This signs the user out of
+   * **every device they are currently signed in on**, not just the current
+   * tab/session. If you only want to sign the user out of the current session
+   * (the behavior most other auth libraries default to), pass
+   * `{ scope: 'local' }` explicitly.
+   *
    * @category Auth
    *
    * @remarks
    * - In order to use the `signOut()` method, the user needs to be signed in first.
-   * - By default, `signOut()` uses the global scope, which signs out all other sessions that the user is logged into as well. Customize this behavior by passing a scope parameter.
+   * - By default, `signOut()` uses the **global** scope, which signs out the user
+   *   on every device they are signed in on (not just the current one). Pass
+   *   `{ scope: 'local' }` to only sign out the current session. This is
+   *   usually what apps want on a "Sign out" button, especially when users
+   *   sign in from multiple devices and do not expect signing out of one to
+   *   terminate the others.
    * - Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.
    *
-   * @example Sign out (all sessions)
+   * @example Sign out of every device (global – default)
    * ```js
    * const { error } = await supabase.auth.signOut()
    * ```
    *
-   * @example Sign out (current session)
+   * @example Sign out only the current session (recommended for most apps)
    * ```js
    * const { error } = await supabase.auth.signOut({ scope: 'local' })
    * ```
    *
-   * @example Sign out (other sessions)
+   * @example Sign out of all other sessions, keep the current one
    * ```js
    * const { error } = await supabase.auth.signOut({ scope: 'others' })
    * ```
@@ -3712,15 +3986,24 @@ export default class GoTrueClient {
   async signOut(options: SignOut = { scope: 'global' }): Promise<{ error: AuthError | null }> {
     await this.initializePromise
 
-    return await this._acquireLock(this.lockAcquireTimeout, async () => {
-      return await this._signOut(options)
-    })
+    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)
   }
 
   protected async _signOut(
     { scope }: SignOut = { scope: 'global' }
   ): Promise<{ error: AuthError | null }> {
     return await this._useSession(async (result) => {
+      const removeCurrentSession = async () => {
+        await this._removeSession()
+        await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+      }
       const { data, error: sessionError } = result
       if (sessionError && !isAuthSessionMissingError(sessionError)) {
         return this._returnResult({ error: sessionError })
@@ -3738,13 +4021,15 @@ export default class GoTrueClient {
               isAuthSessionMissingError(error)
             )
           ) {
+            if (scope !== 'others') {
+              await removeCurrentSession()
+            }
             return this._returnResult({ error })
           }
         }
       }
       if (scope !== 'others') {
-        await this._removeSession()
-        await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+        await removeCurrentSession()
       }
       return this._returnResult({ error: null })
     })
@@ -3761,16 +4046,19 @@ export default class GoTrueClient {
   }
 
   /**
-   * 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.
-   *
-   * Receive a notification every time an auth event happens.
+   * 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.
    *
    * @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.
+   *
+   * @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.
    */
   onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => Promise<void>): {
     data: { subscription: Subscription }
@@ -3783,18 +4071,8 @@ 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.
-   * - **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)
-   *     })
-   *     ```
+   * - 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.
    * - Emitted events:
    *   - `INITIAL_SESSION`
    *     - Emitted right after the Supabase client is constructed and the initial session from storage is loaded.
@@ -3985,9 +4263,14 @@ export default class GoTrueClient {
     ;(async () => {
       await this.initializePromise
 
-      await this._acquireLock(this.lockAcquireTimeout, async () => {
-        this._emitInitialSession(id)
-      })
+      if (this.lock != null) {
+        // TODO(v3): remove legacy lock path
+        await this._acquireLock(this.lockAcquireTimeout, async () => {
+          this._emitInitialSession(id)
+        })
+      } else {
+        await this._emitInitialSession(id)
+      }
     })()
 
     return { data: { subscription } }
@@ -4007,7 +4290,10 @@ export default class GoTrueClient {
       } catch (err) {
         await this.stateChangeEmitters.get(id)?.callback('INITIAL_SESSION', null)
         this._debug('INITIAL_SESSION', 'callback id', id, 'error', err)
-        if (isAuthSessionMissingError(err)) {
+        if (isAuthSessionMissingError(err) || isAuthRetryableFetchError(err)) {
+          // A missing session or a transient/aborted network failure (e.g. a
+          // superseded page navigation cancelling the in-flight request) is
+          // not an application error — warn rather than surface it raw.
           console.warn(err)
         } else {
           console.error(err)
@@ -4382,7 +4668,10 @@ export default class GoTrueClient {
    * @param refreshToken A valid refresh token that was returned on login.
    */
   private async _refreshAccessToken(refreshToken: string): Promise<AuthResponse> {
-    const debugName = `#_refreshAccessToken(${refreshToken.substring(0, 5)}...)`
+    // 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()`
     this._debug(debugName, 'begin')
 
     try {
@@ -4535,15 +4824,16 @@ export default class GoTrueClient {
           const { error } = await this._callRefreshToken(currentSession.refresh_token)
 
           if (error) {
-            console.error(error)
-
-            if (!isAuthRetryableFetchError(error)) {
-              this._debug(
-                debugName,
-                'refresh failed with a non-retryable error, removing the session',
-                error
-              )
-              await this._removeSession()
+            // `_callRefreshToken` is the single source of truth for refresh
+            // outcomes: it removes the session itself when the access token
+            // is actually expired, and preserves it when the token is still
+            // valid (proactive-preserve). Don't second-guess that here — a
+            // local `_removeSession` would emit a duplicate `SIGNED_OUT` on
+            // genuine failures and undo the proactive-preserve at init time.
+            if (isAuthRefreshDiscardedError(error)) {
+              this._debug(debugName, 'refresh discarded by commit guard', error)
+            } else {
+              this._debug(debugName, 'refresh failed', error)
             }
           }
         }
@@ -4579,7 +4869,15 @@ export default class GoTrueClient {
     } catch (err) {
       this._debug(debugName, 'error', err)
 
-      console.error(err)
+      if (isAuthRetryableFetchError(err)) {
+        // Transient/aborted network failure during session recovery (e.g. a
+        // superseded page navigation cancelling the in-flight request). Warn
+        // rather than surface it raw; the session is untouched and recovery
+        // will run again on the next load.
+        console.warn(err)
+      } else {
+        console.error(err)
+      }
       return
     } finally {
       this._debug(debugName, 'end')
@@ -4596,22 +4894,113 @@ export default class GoTrueClient {
       return this.refreshingDeferred.promise
     }
 
-    const debugName = `#_callRefreshToken(${refreshToken.substring(0, 5)}...)`
+    // Serial failure cooldown: callers passing the *same* refresh token
+    // after a recent failure receive the cached result instead of firing
+    // another `/token` request. This caps the proactive-refresh storm
+    // where every `getSession()` call inside the 90s EXPIRY_MARGIN_MS
+    // window kept re-firing against the same broken refresh token during
+    // outages. Concurrent callers already share `refreshingDeferred`; this
+    // cache covers serial callers spaced across cooldown windows.
+    //
+    // Token-keyed so callers with a fresh refresh token (rotation pickup
+    // from another tab, explicit `setSession`/`refreshSession({ refresh_token })`,
+    // multi-account switch) bypass the cache and attempt a real refresh.
+    if (
+      this.lastRefreshFailure &&
+      this.lastRefreshFailure.refreshToken === refreshToken &&
+      Date.now() < this.lastRefreshFailure.expiresAt
+    ) {
+      this._debug('#_callRefreshToken()', 'returning cached failure (cooldown active)')
+      return this.lastRefreshFailure.result
+    }
+
+    // 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()`
 
     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 }
 
+      // Refresh succeeded — clear any cached failure so the next caller
+      // (including the auto-refresh ticker) attempts a real refresh again.
+      this.lastRefreshFailure = null
+
       this.refreshingDeferred.resolve(result)
 
       return result
@@ -4622,7 +5011,40 @@ export default class GoTrueClient {
         const result = { data: null, error }
 
         if (!isAuthRetryableFetchError(error)) {
-          await this._removeSession()
+          // Proactive vs reactive distinction: a refresh fires whenever
+          // the access token is within EXPIRY_MARGIN_MS of expiry. If the
+          // access token is *still valid* at this moment, the refresh was
+          // proactive and the existing session is still usable until its
+          // real expiry — destroying it now would log out a user whose
+          // access token works. If the access token has actually expired,
+          // the refresh token is the only credential left and it just got
+          // rejected — the session is genuinely dead. `__loadSession`
+          // mirrors this distinction on the read path so callers see the
+          // preserved session instead of `session: null`.
+          const storedNow = (await getItemAsync(this.storage, this.storageKey)) as Session | null
+          const accessTokenStillValid = !!(
+            storedNow?.expires_at && storedNow.expires_at * 1000 > Date.now()
+          )
+
+          if (accessTokenStillValid) {
+            this._debug(
+              debugName,
+              'proactive refresh failed, access token still valid — preserving session'
+            )
+          } else {
+            await this._removeSession()
+          }
+        }
+
+        // Cache the failure so serial callers (and the next auto-refresh
+        // tick) passing the same refresh token within the cooldown window
+        // receive it synchronously instead of firing another `/token`
+        // call. Set after the optional `_removeSession` above (which
+        // clears the cache as part of teardown) so the cache survives.
+        this.lastRefreshFailure = {
+          refreshToken,
+          result,
+          expiresAt: Date.now() + REFRESH_FAILURE_COOLDOWN_MS,
         }
 
         this.refreshingDeferred?.resolve(result)
@@ -4643,6 +5065,20 @@ export default class GoTrueClient {
     session: Session | null,
     broadcast = true
   ) {
+    if (this._pendingInitNotifications !== null && broadcast) {
+      // We're inside initialize() before initializePromise has resolved, and
+      // this notification originates from the init chain (_recoverAndRefresh),
+      // which always fires with broadcast = true. Enqueue instead of firing so
+      // that callbacks can safely call getSession() / getUser() without
+      // deadlocking on initializePromise.
+      //
+      // Notifications with broadcast = false come from the incoming
+      // BroadcastChannel handler (a cross-tab event), not the init chain, so
+      // they are fired immediately to preserve multi-tab ordering.
+      this._pendingInitNotifications.push({ event, session, broadcast })
+      return
+    }
+
     const debugName = `#_notifyAllSubscribers(${event})`
     this._debug(debugName, 'begin', session, `broadcast = ${broadcast}`)
 
@@ -4651,11 +5087,11 @@ export default class GoTrueClient {
         this.broadcastChannel.postMessage({ event, session })
       }
 
-      const errors: any[] = []
+      const errors: unknown[] = []
       const promises = Array.from(this.stateChangeEmitters.values()).map(async (x) => {
         try {
           await x.callback(event, session)
-        } catch (e: any) {
+        } catch (e) {
           errors.push(e)
         }
       })
@@ -4683,7 +5119,6 @@ export default class GoTrueClient {
     // _saveSession is always called whenever a new session has been acquired
     // so we can safely suppress the warning returned by future getSession calls
     this.suppressGetSessionWarning = true
-    await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
     // Create a shallow copy to work with, to avoid mutating the original session object if it's used elsewhere
     const sessionToProcess = { ...session }
 
@@ -4719,8 +5154,17 @@ 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()')
 
+    // The session is gone — no point holding on to a cached refresh failure
+    // for a token that no longer exists. Synchronous, before any `await`.
+    this.lastRefreshFailure = null
+
     this.suppressGetSessionWarning = false
 
     await removeItemAsync(this.storage, this.storageKey)
@@ -4737,8 +5181,8 @@ export default class GoTrueClient {
   /**
    * Removes any registered visibilitychange callback.
    *
-   * {@see #startAutoRefresh}
-   * {@see #stopAutoRefresh}
+   * {@link GoTrueClient.startAutoRefresh}
+   * {@link GoTrueClient.stopAutoRefresh}
    */
   private _removeVisibilityChangedCallback() {
     this._debug('#_removeVisibilityChangedCallback()')
@@ -4756,7 +5200,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * This is the private implementation of {@link #startAutoRefresh}. Use this
+   * This is the private implementation of {@link GoTrueClient.startAutoRefresh}. Use this
    * within the library.
    */
   private async _startAutoRefresh() {
@@ -4802,7 +5246,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * This is the private implementation of {@link #stopAutoRefresh}. Use this
+   * This is the private implementation of {@link GoTrueClient.stopAutoRefresh}. Use this
    * within the library.
    */
   private async _stopAutoRefresh() {
@@ -4843,7 +5287,7 @@ export default class GoTrueClient {
    * platform's foreground indication mechanism and call these methods
    * appropriately to conserve resources.
    *
-   * {@see #stopAutoRefresh}
+   * {@link GoTrueClient.stopAutoRefresh}
    *
    * @category Auth
    *
@@ -4878,7 +5322,7 @@ export default class GoTrueClient {
    * If you call this method any managed visibility change callback will be
    * removed and you must manage visibility changes on your own.
    *
-   * See {@link #startAutoRefresh} for more details.
+   * See {@link GoTrueClient.startAutoRefresh} for more details.
    *
    * @category Auth
    *
@@ -4907,58 +5351,144 @@ 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')
 
-    try {
-      await this._acquireLock(0, async () => {
-        try {
-          const now = Date.now()
-
+    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 {
-            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 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
+                }
 
-              // 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
-              )
+                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)
-              }
-            })
-          } catch (e: any) {
-            console.error(
-              'Auto refresh tick failed with error. This is likely a transient error.',
-              e
-            )
+                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')
           }
-        } finally {
-          this._debug('#_autoRefreshTokenTick()', 'end')
+        })
+      } catch (e) {
+        if (e instanceof LockAcquireTimeoutError) {
+          this._debug('auto refresh token tick lock not available')
+        } else {
+          throw e
         }
-      })
-    } catch (e: any) {
-      if (e.isAcquireTimeout || 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
+
+          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
+          )
+
+          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')
     }
   }
 
@@ -5015,24 +5545,29 @@ 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 immediately... but to do that we need to acquire
-        // the lock first asynchronously
+        // should be recovered
         await this.initializePromise
 
-        await this._acquireLock(this.lockAcquireTimeout, async () => {
+        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 {
           if (document.visibilityState !== 'visible') {
-            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
+            this._debug(methodName, 'visibilityState is no longer visible, skipping recovery')
             return
           }
-
           // recover the session
           await this._recoverAndRefresh()
-        })
+        }
       }
     } else if (document.visibilityState === 'hidden') {
       if (this.autoRefreshToken) {
@@ -5109,7 +5644,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#enroll}
+   * {@link GoTrueMFAApi#enroll}
    */
   private async _enroll(params: MFAEnrollTOTPParams): Promise<AuthMFAEnrollTOTPResponse>
   private async _enroll(params: MFAEnrollPhoneParams): Promise<AuthMFAEnrollPhoneResponse>
@@ -5156,7 +5691,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#verify}
+   * {@link GoTrueMFAApi#verify}
    */
   private async _verify(params: MFAVerifyTOTPParams): Promise<AuthMFAVerifyResponse>
   private async _verify(params: MFAVerifyPhoneParams): Promise<AuthMFAVerifyResponse>
@@ -5164,7 +5699,7 @@ export default class GoTrueClient {
     params: MFAVerifyWebauthnParams<T>
   ): Promise<AuthMFAVerifyResponse>
   private async _verify(params: MFAVerifyParams): Promise<AuthMFAVerifyResponse> {
-    return this._acquireLock(this.lockAcquireTimeout, async () => {
+    const run = async (): Promise<AuthMFAVerifyResponse> => {
       try {
         return await this._useSession(async (result) => {
           const { data: sessionData, error: sessionError } = result
@@ -5235,11 +5770,17 @@ export default class GoTrueClient {
         }
         throw error
       }
-    })
+    }
+
+    if (this.lock != null) {
+      // TODO(v3): remove legacy lock path
+      return this._acquireLock(this.lockAcquireTimeout, run)
+    }
+    return run()
   }
 
   /**
-   * {@see GoTrueMFAApi#challenge}
+   * {@link GoTrueMFAApi#challenge}
    */
   private async _challenge(
     params: MFAChallengeTOTPParams
@@ -5251,7 +5792,7 @@ export default class GoTrueClient {
     params: MFAChallengeWebauthnParams
   ): Promise<Prettify<AuthMFAChallengeWebauthnResponse>>
   private async _challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse> {
-    return this._acquireLock(this.lockAcquireTimeout, async () => {
+    const run = async (): Promise<AuthMFAChallengeResponse> => {
       try {
         return await this._useSession(async (result) => {
           const { data: sessionData, error: sessionError } = result
@@ -5324,18 +5865,21 @@ export default class GoTrueClient {
         }
         throw error
       }
-    })
+    }
+
+    if (this.lock != null) {
+      // TODO(v3): remove legacy lock path
+      return this._acquireLock(this.lockAcquireTimeout, run)
+    }
+    return run()
   }
 
   /**
-   * {@see GoTrueMFAApi#challengeAndVerify}
+   * {@link GoTrueMFAApi#challengeAndVerify}
    */
   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,
     })
@@ -5351,10 +5895,9 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#listFactors}
+   * {@link GoTrueMFAApi#listFactors}
    */
   private async _listFactors(): Promise<AuthMFAListFactorsResponse> {
-    // use #getUser instead of #_getUser as the former acquires a lock
     const {
       data: { user },
       error: userError,
@@ -5385,7 +5928,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#getAuthenticatorAssuranceLevel}
+   * {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}
    */
   private async _getAuthenticatorAssuranceLevel(
     jwt?: string
@@ -5733,15 +6276,15 @@ export default class GoTrueClient {
    * Extracts the JWT claims present in the access token by first verifying the
    * JWT against the server's JSON Web Key Set endpoint
    * `/.well-known/jwks.json` which is often cached, resulting in significantly
-   * faster responses. Prefer this method over {@link #getUser} which always
+   * faster responses. Prefer this method over {@link GoTrueClient.getUser} which always
    * sends a request to the Auth server for each JWT.
    *
    * If the project is not using an asymmetric JWT signing key (like ECC or
-   * RSA) it always sends a request to the Auth server (similar to {@link
-   * #getUser}) to verify the JWT.
+   * RSA) it always sends a request to the Auth server (similar to
+   * {@link GoTrueClient.getUser}) to verify the JWT.
    *
    * @param jwt An optional specific JWT you wish to verify, not the one you
-   *            can obtain from {@link #getSession}.
+   *            can obtain from {@link GoTrueClient.getSession}.
    * @param options Various additional options that allow you to customize the
    *                behavior of this method.
    *
@@ -5834,8 +6377,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 =
@@ -5898,4 +6446,392 @@ export default class GoTrueClient {
       throw error
     }
   }
+
+  // --- Passkey Methods ---
+
+  /**
+   * Sign in with a passkey. Handles the full WebAuthn ceremony:
+   * 1. Fetches authentication challenge from server
+   * 2. Prompts user via navigator.credentials.get()
+   * 3. Verifies credential with server and creates session
+   *
+   * Requires `auth.experimental.passkey: true`.
+   *
+   * @category Auth
+   */
+  async signInWithPasskey(
+    credentials?: SignInWithPasskeyCredentials
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      if (!browserSupportsWebAuthn()) {
+        return this._returnResult({
+          data: null,
+          error: new AuthUnknownError('Browser does not support WebAuthn', null),
+        })
+      }
+
+      // 1. Get challenge options from server
+      const { data: options, error: optionsError } = await this._startPasskeyAuthentication({
+        options: { captchaToken: credentials?.options?.captchaToken },
+      })
+      if (optionsError || !options) {
+        return this._returnResult({ data: null, error: optionsError })
+      }
+
+      // 2. Deserialize and prompt user via browser WebAuthn API
+      const publicKeyOptions = deserializeCredentialRequestOptions(options.options)
+      const signal = credentials?.options?.signal ?? webAuthnAbortService.createNewAbortSignal()
+      const { data: credential, error: credentialError } = await getCredential({
+        publicKey: publicKeyOptions,
+        signal,
+      })
+      if (credentialError || !credential) {
+        return this._returnResult({
+          data: null,
+          error: credentialError ?? new AuthUnknownError('WebAuthn ceremony failed', null),
+        })
+      }
+
+      // 3. Serialize and verify with server
+      const serialized = serializeCredentialRequestResponse(credential)
+      return this._verifyPasskeyAuthentication({
+        challengeId: options.challenge_id,
+        credential: serialized,
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Register a passkey for the current authenticated user. Handles the full WebAuthn ceremony:
+   * 1. Fetches registration challenge from server
+   * 2. Prompts user via navigator.credentials.create()
+   * 3. Verifies credential with server
+   *
+   * Requires an active session. Requires `auth.experimental.passkey: true`.
+   *
+   * @category Auth
+   */
+  async registerPasskey(
+    credentials?: RegisterPasskeyCredentials
+  ): Promise<AuthPasskeyRegistrationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      if (!browserSupportsWebAuthn()) {
+        return this._returnResult({
+          data: null,
+          error: new AuthUnknownError('Browser does not support WebAuthn', null),
+        })
+      }
+
+      // 1. Get challenge options from server
+      const { data: options, error: optionsError } = await this._startPasskeyRegistration()
+      if (optionsError || !options) {
+        return this._returnResult({ data: null, error: optionsError })
+      }
+
+      // 2. Deserialize and prompt user via browser WebAuthn API
+      const publicKeyOptions = deserializeCredentialCreationOptions(options.options)
+      const signal = credentials?.options?.signal ?? webAuthnAbortService.createNewAbortSignal()
+      const { data: credential, error: credentialError } = await createCredential({
+        publicKey: publicKeyOptions,
+        signal,
+      })
+      if (credentialError || !credential) {
+        return this._returnResult({
+          data: null,
+          error: credentialError ?? new AuthUnknownError('WebAuthn ceremony failed', null),
+        })
+      }
+
+      // 3. Serialize and verify with server
+      const serialized = serializeCredentialCreationResponse(credential)
+      return this._verifyPasskeyRegistration({
+        challengeId: options.challenge_id,
+        credential: serialized,
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Start passkey registration for the current authenticated user.
+   * Returns WebAuthn credential creation options to pass to navigator.credentials.create().
+   */
+  private async _startPasskeyRegistration(): Promise<AuthPasskeyRegistrationOptionsResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'POST',
+          `${this.url}/passkeys/registration/options`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: {},
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Verify passkey registration with the credential response.
+   * The credentialResponse should be the serialized output of navigator.credentials.create().
+   */
+  private async _verifyPasskeyRegistration(
+    params: VerifyPasskeyRegistrationParams
+  ): Promise<AuthPasskeyRegistrationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'POST',
+          `${this.url}/passkeys/registration/verify`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: {
+              challenge_id: params.challengeId,
+              credential: params.credential,
+            },
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Start passkey authentication.
+   * Returns WebAuthn credential request options to pass to navigator.credentials.get().
+   */
+  private async _startPasskeyAuthentication(
+    params?: StartPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationOptionsResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      const { data, error } = await _request(
+        this.fetch,
+        'POST',
+        `${this.url}/passkeys/authentication/options`,
+        {
+          headers: this.headers,
+          body: {
+            gotrue_meta_security: { captcha_token: params?.options?.captchaToken },
+          },
+        }
+      )
+      if (error) {
+        return this._returnResult({ data: null, error })
+      }
+      return this._returnResult({ data, error: null })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Verify passkey authentication and create a session.
+   * The credential should be the serialized output of navigator.credentials.get().
+   */
+  private async _verifyPasskeyAuthentication(
+    params: VerifyPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      const { data, error } = await _request(
+        this.fetch,
+        'POST',
+        `${this.url}/passkeys/authentication/verify`,
+        {
+          headers: this.headers,
+          body: {
+            challenge_id: params.challengeId,
+            credential: params.credential,
+          },
+          xform: _sessionResponse,
+        }
+      )
+      if (error) {
+        return this._returnResult({ data: null, error })
+      }
+      if (data.session) {
+        await this._saveSession(data.session)
+        await this._notifyAllSubscribers('SIGNED_IN', data.session)
+      }
+      return this._returnResult({ data, error: null })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * List all passkeys for the current user.
+   */
+  private async _listPasskeys(): Promise<AuthPasskeyListResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(this.fetch, 'GET', `${this.url}/passkeys`, {
+          headers: this.headers,
+          jwt: session.access_token,
+          xform: (data: any) => ({ data, error: null }),
+        })
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Update a passkey.
+   */
+  private async _updatePasskey(params: PasskeyUpdateParams): Promise<AuthPasskeyUpdateResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'PATCH',
+          `${this.url}/passkeys/${params.passkeyId}`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: { friendly_name: params.friendlyName },
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Delete a passkey.
+   */
+  private async _deletePasskey(params: PasskeyDeleteParams): Promise<AuthPasskeyDeleteResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { error } = await _request(
+          this.fetch,
+          'DELETE',
+          `${this.url}/passkeys/${params.passkeyId}`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            noResolveJson: true,
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data: null, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
 }