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

package/dist/module/GoTrueClient.js

@@ -1,10 +1,10 @@
 import GoTrueAdminApi from './GoTrueAdminApi';
 import { AUTO_REFRESH_TICK_DURATION_MS, AUTO_REFRESH_TICK_THRESHOLD, DEFAULT_HEADERS, EXPIRY_MARGIN_MS, GOTRUE_URL, JWKS_TTL, STORAGE_KEY, } from './lib/constants';
-import { AuthImplicitGrantRedirectError, AuthInvalidCredentialsError, AuthInvalidJwtError, AuthInvalidTokenResponseError, AuthPKCECodeVerifierMissingError, AuthPKCEGrantCodeExchangeError, AuthRefreshDiscardedError, AuthSessionMissingError, AuthUnknownError, isAuthApiError, isAuthError, isAuthImplicitGrantRedirectError, isAuthRefreshDiscardedError, isAuthRetryableFetchError, isAuthSessionMissingError, } from './lib/errors';
+import { AuthImplicitGrantRedirectError, AuthInvalidCredentialsError, AuthInvalidJwtError, AuthInvalidTokenResponseError, AuthPKCECodeVerifierMissingError, AuthPKCEGrantCodeExchangeError, AuthSessionMissingError, AuthUnknownError, isAuthApiError, isAuthError, isAuthImplicitGrantRedirectError, isAuthRetryableFetchError, isAuthSessionMissingError, } from './lib/errors';
 import { _request, _sessionResponse, _sessionResponsePassword, _ssoResponse, _userResponse, } from './lib/fetch';
 import { assertPasskeyExperimentalEnabled, decodeJWT, deepClone, Deferred, generateCallbackId, getAlgorithm, getCodeChallengeAndMethod, getItemAsync, insecureUserWarningProxy, isBrowser, parseParametersFromURL, removeItemAsync, resolveFetch, retryable, setItemAsync, sleep, supportsLocalStorage, userNotAvailableProxy, validateExp, } from './lib/helpers';
 import { memoryLocalStorageAdapter } from './lib/local-storage';
-import { LockAcquireTimeoutError } from './lib/locks';
+import { LockAcquireTimeoutError, navigatorLock } from './lib/locks';
 import { polyfillGlobalThis } from './lib/polyfills';
 import { version } from './lib/version';
 import { bytesToBase64URL, stringToUint8Array } from './lib/base64url';
@@ -22,16 +22,10 @@ const DEFAULT_OPTIONS = {
     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(name, acquireTimeout, fn) {
     return await fn();
 }
@@ -85,7 +79,7 @@ class GoTrueClient {
      * ```
      */
     constructor(options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         /**
          * @experimental
          */
@@ -96,14 +90,6 @@ class GoTrueClient {
         this.autoRefreshTickTimeout = null;
         this.visibilityChangedCallback = null;
         this.refreshingDeferred = 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).
-         */
-        this._sessionRemovalEpoch = 0;
         /**
          * Keeps track of the async client initialization.
          * When null or not yet resolved the auth state is `unknown`
@@ -114,13 +100,6 @@ class GoTrueClient {
         this.detectSessionInUrl = true;
         this.hasCustomAuthorizationHeader = false;
         this.suppressGetSessionWarning = false;
-        /**
-         * 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.
-         */
-        this.lock = null;
         this.lockAcquired = false;
         this.pendingInLock = [];
         /**
@@ -155,22 +134,21 @@ 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() && ((_c = globalThis === null || globalThis === void 0 ? void 0 : globalThis.navigator) === null || _c === void 0 ? void 0 : _c.locks)) {
+            this.lock = navigatorLock;
+        }
+        else {
+            this.lock = lockNoOp;
+        }
         if (!this.jwks) {
             this.jwks = { keys: [] };
             this.jwks_cached_at = Number.MIN_SAFE_INTEGER;
@@ -229,7 +207,7 @@ class GoTrueClient {
             catch (e) {
                 console.error('Failed to create a new BroadcastChannel, multi-tab state changes will not be available', e);
             }
-            (_c = this.broadcastChannel) === null || _c === void 0 ? void 0 : _c.addEventListener('message', async (event) => {
+            (_d = this.broadcastChannel) === null || _d === void 0 ? void 0 : _d.addEventListener('message', async (event) => {
                 this._debug('received broadcast notification from other tab or client', event);
                 try {
                     await this._notifyAllSubscribers(event.data.event, event.data.session, false); // broadcast = false so we don't get an endless loop of messages
@@ -287,13 +265,9 @@ class GoTrueClient {
             return await this.initializePromise;
         }
         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;
     }
@@ -1144,13 +1118,9 @@ class GoTrueClient {
      */
     async exchangeCodeForSession(authCode) {
         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);
+        });
     }
     /**
      * Signs in a user by verifying a message signed by the user's private key.
@@ -2054,13 +2024,9 @@ class GoTrueClient {
      */
     async reauthenticate() {
         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();
+        });
     }
     async _reauthenticate() {
         try {
@@ -2203,7 +2169,7 @@ 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
@@ -2270,24 +2236,15 @@ 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.
      */
     async _acquireLock(acquireTimeout, fn) {
         this._debug('#_acquireLock', 'begin', acquireTimeout);
@@ -2343,17 +2300,15 @@ 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.
      */
     async _useSession(fn) {
         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);
         }
@@ -2368,8 +2323,7 @@ class GoTrueClient {
      */
     async __loadSession() {
         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);
         }
         try {
@@ -2512,16 +2466,9 @@ class GoTrueClient {
             return await this._getUser(jwt);
         }
         await this.initializePromise;
-        let result;
-        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;
         }
@@ -2682,13 +2629,9 @@ class GoTrueClient {
      */
     async updateUser(attributes, options = {}) {
         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);
+        });
     }
     async _updateUser(attributes, options = {}) {
         try {
@@ -2857,13 +2800,9 @@ class GoTrueClient {
      */
     async setSession(currentSession) {
         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);
+        });
     }
     async _setSession(currentSession) {
         try {
@@ -3041,13 +2980,9 @@ class GoTrueClient {
      */
     async refreshSession(currentSession) {
         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);
+        });
     }
     async _refreshSession(currentSession) {
         try {
@@ -3185,7 +3120,7 @@ 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);
     }
     /**
      * Checks if the current URL and backing storage contain parameters given by a PKCE flow
@@ -3237,13 +3172,9 @@ class GoTrueClient {
      */
     async signOut(options = { scope: 'global' }) {
         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);
+        });
     }
     async _signOut({ scope } = { scope: 'global' }) {
         return await this._useSession(async (result) => {
@@ -3279,8 +3210,18 @@ 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.
@@ -3463,15 +3404,9 @@ class GoTrueClient {
         this.stateChangeEmitters.set(id, subscription);
         (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 } };
     }
@@ -3813,10 +3748,7 @@ class GoTrueClient {
      * @param refreshToken A valid refresh token that was returned on login.
      */
     async _refreshAccessToken(refreshToken) {
-        // 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 {
             const startedAt = Date.now();
@@ -3923,18 +3855,10 @@ class GoTrueClient {
                 if (this.autoRefreshToken && currentSession.refresh_token) {
                     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();
                         }
                     }
                 }
@@ -3983,69 +3907,16 @@ class GoTrueClient {
         if (this.refreshingDeferred) {
             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();
-            // 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));
             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));
-            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 = {
-                    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 = {
-                    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 };
             this.refreshingDeferred.resolve(result);
@@ -4139,11 +4010,6 @@ class GoTrueClient {
         }
     }
     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;
         await removeItemAsync(this.storage, this.storageKey);
@@ -4314,122 +4180,47 @@ class GoTrueClient {
         this._removeVisibilityChangedCallback();
         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() {
-        var _a;
-        this._removeVisibilityChangedCallback();
-        await this._stopAutoRefresh();
-        (_a = this.broadcastChannel) === null || _a === void 0 ? void 0 : _a.close();
-        this.broadcastChannel = null;
-        this.stateChangeEmitters.clear();
-    }
     /**
      * Runs the auto refresh token tick.
      */
     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 {
+            await this._acquireLock(0, async () => {
+                try {
+                    const now = Date.now();
                     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);
-                        }
+                        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);
+                            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);
+                            }
+                        });
                     }
-                    finally {
-                        this._debug('#_autoRefreshTokenTick()', 'end');
+                    catch (e) {
+                        console.error('Auto refresh tick failed with error. This is likely a transient error.', e);
                     }
-                });
-            }
-            catch (e) {
-                if (e instanceof LockAcquireTimeoutError) {
-                    this._debug('auto refresh token tick lock not available');
                 }
-                else {
-                    throw e;
+                finally {
+                    this._debug('#_autoRefreshTokenTick()', 'end');
                 }
-            }
-            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) {
+            if (e instanceof LockAcquireTimeoutError) {
+                this._debug('auto refresh token tick lock not available');
             }
-            catch (e) {
-                console.error('Auto refresh tick failed with error. This is likely a transient error.', e);
+            else {
+                throw e;
             }
         }
-        finally {
-            this._debug('#_autoRefreshTokenTick()', 'end');
-        }
     }
     /**
      * Registers callbacks on the browser / platform, which in-turn run
@@ -4478,26 +4269,18 @@ 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') {
@@ -4593,7 +4376,7 @@ class GoTrueClient {
         }
     }
     async _verify(params) {
-        const run = async () => {
+        return this._acquireLock(this.lockAcquireTimeout, async () => {
             try {
                 return await this._useSession(async (result) => {
                     var _a;
@@ -4627,15 +4410,10 @@ class GoTrueClient {
                 }
                 throw error;
             }
-        };
-        if (this.lock != null) {
-            // TODO(v3): remove legacy lock path
-            return this._acquireLock(this.lockAcquireTimeout, run);
-        }
-        return run();
+        });
     }
     async _challenge(params) {
-        const run = async () => {
+        return this._acquireLock(this.lockAcquireTimeout, async () => {
             try {
                 return await this._useSession(async (result) => {
                     var _a;
@@ -4675,17 +4453,14 @@ 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}
      */
     async _challengeAndVerify(params) {
+        // 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,
         });
@@ -4703,6 +4478,7 @@ class GoTrueClient {
      */
     async _listFactors() {
         var _a;
+        // use #getUser instead of #_getUser as the former acquires a lock
         const { data: { user }, error: userError, } = await this.getUser();
         if (userError) {
             return { data: null, error: userError };
@@ -5051,8 +4827,14 @@ class GoTrueClient {
             }
             const { header, payload, signature, raw: { header: rawHeader, payload: rawPayload }, } = decodeJWT(token);
             if (!(options === null || options === void 0 ? void 0 : 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 = !header.alg ||
                 header.alg.startsWith('HS') ||