@supabase/gotrue-js 2.105.4 → 2.107.0-canary.5

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, AuthSessionMissingError, AuthUnknownError, isAuthApiError, isAuthError, isAuthImplicitGrantRedirectError, isAuthRetryableFetchError, isAuthSessionMissingError, } from './lib/errors';
+import { AuthImplicitGrantRedirectError, AuthInvalidCredentialsError, AuthInvalidJwtError, AuthInvalidTokenResponseError, AuthPKCECodeVerifierMissingError, AuthPKCEGrantCodeExchangeError, AuthRefreshDiscardedError, AuthSessionMissingError, AuthUnknownError, isAuthApiError, isAuthError, isAuthImplicitGrantRedirectError, isAuthRefreshDiscardedError, 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, navigatorLock } from './lib/locks';
+import { LockAcquireTimeoutError } from './lib/locks';
 import { polyfillGlobalThis } from './lib/polyfills';
 import { version } from './lib/version';
 import { bytesToBase64URL, stringToUint8Array } from './lib/base64url';
@@ -22,10 +22,16 @@ const DEFAULT_OPTIONS = {
     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(name, acquireTimeout, fn) {
     return await fn();
 }
@@ -79,7 +85,7 @@ class GoTrueClient {
      * ```
      */
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         /**
          * @experimental
          */
@@ -90,6 +96,14 @@ 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`
@@ -100,6 +114,13 @@ 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 = [];
         /**
@@ -134,21 +155,22 @@ 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;
-        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() && ((_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;
@@ -207,7 +229,7 @@ class GoTrueClient {
             catch (e) {
                 console.error('Failed to create a new BroadcastChannel, multi-tab state changes will not be available', e);
             }
-            (_d = this.broadcastChannel) === null || _d === void 0 ? void 0 : _d.addEventListener('message', async (event) => {
+            (_c = this.broadcastChannel) === null || _c === void 0 ? void 0 : _c.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
@@ -265,9 +287,13 @@ class GoTrueClient {
             return await this.initializePromise;
         }
         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;
     }
@@ -803,6 +829,21 @@ 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) {
         try {
@@ -1118,9 +1159,13 @@ class GoTrueClient {
      */
     async exchangeCodeForSession(authCode) {
         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);
     }
     /**
      * Signs in a user by verifying a message signed by the user's private key.
@@ -2024,9 +2069,13 @@ class GoTrueClient {
      */
     async reauthenticate() {
         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();
     }
     async _reauthenticate() {
         try {
@@ -2169,7 +2218,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.
-     * - 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
@@ -2236,15 +2285,24 @@ 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 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);
@@ -2300,15 +2358,17 @@ 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 #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.
      */
     async _useSession(fn) {
         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);
         }
@@ -2323,7 +2383,8 @@ class GoTrueClient {
      */
     async __loadSession() {
         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);
         }
         try {
@@ -2466,9 +2527,16 @@ class GoTrueClient {
             return await this._getUser(jwt);
         }
         await this.initializePromise;
-        const result = await this._acquireLock(this.lockAcquireTimeout, async () => {
-            return await this._getUser();
-        });
+        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();
+        }
         if (result.data.user) {
             this.suppressGetSessionWarning = true;
         }
@@ -2629,9 +2697,13 @@ class GoTrueClient {
      */
     async updateUser(attributes, options = {}) {
         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);
     }
     async _updateUser(attributes, options = {}) {
         try {
@@ -2800,9 +2872,13 @@ class GoTrueClient {
      */
     async setSession(currentSession) {
         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);
     }
     async _setSession(currentSession) {
         try {
@@ -2980,9 +3056,13 @@ class GoTrueClient {
      */
     async refreshSession(currentSession) {
         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);
     }
     async _refreshSession(currentSession) {
         try {
@@ -3120,7 +3200,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
@@ -3172,9 +3252,13 @@ class GoTrueClient {
      */
     async signOut(options = { scope: 'global' }) {
         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);
     }
     async _signOut({ scope } = { scope: 'global' }) {
         return await this._useSession(async (result) => {
@@ -3210,18 +3294,8 @@ 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.
@@ -3404,9 +3478,15 @@ class GoTrueClient {
         this.stateChangeEmitters.set(id, subscription);
         (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 } };
     }
@@ -3748,7 +3828,10 @@ class GoTrueClient {
      * @param refreshToken A valid refresh token that was returned on login.
      */
     async _refreshAccessToken(refreshToken) {
-        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 {
             const startedAt = Date.now();
@@ -3855,10 +3938,18 @@ class GoTrueClient {
                 if (this.autoRefreshToken && currentSession.refresh_token) {
                     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();
+                        // 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();
+                            }
                         }
                     }
                 }
@@ -3907,16 +3998,69 @@ class GoTrueClient {
         if (this.refreshingDeferred) {
             return this.refreshingDeferred.promise;
         }
-        const debugName = `#_callRefreshToken(${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 = `#_callRefreshToken()`;
         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);
@@ -4010,6 +4154,11 @@ 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);
@@ -4180,47 +4329,122 @@ 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');
-        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;
-                            }
-                            // 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);
-                            }
-                        });
+                        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);
+                        }
                     }
-                    catch (e) {
-                        console.error('Auto refresh tick failed with error. This is likely a transient error.', e);
+                    finally {
+                        this._debug('#_autoRefreshTokenTick()', 'end');
                     }
+                });
+            }
+            catch (e) {
+                if (e instanceof LockAcquireTimeoutError) {
+                    this._debug('auto refresh token tick lock not available');
                 }
-                finally {
-                    this._debug('#_autoRefreshTokenTick()', 'end');
+                else {
+                    throw e;
                 }
-            });
+            }
+            return;
         }
-        catch (e) {
-            if (e instanceof LockAcquireTimeoutError) {
-                this._debug('auto refresh token tick lock not available');
+        // 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);
+                    }
+                });
             }
-            else {
-                throw e;
+            catch (e) {
+                console.error('Auto refresh tick failed with error. This is likely a transient error.', e);
             }
         }
+        finally {
+            this._debug('#_autoRefreshTokenTick()', 'end');
+        }
     }
     /**
      * Registers callbacks on the browser / platform, which in-turn run
@@ -4269,18 +4493,26 @@ 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') {
@@ -4376,7 +4608,7 @@ class GoTrueClient {
         }
     }
     async _verify(params) {
-        return this._acquireLock(this.lockAcquireTimeout, async () => {
+        const run = async () => {
             try {
                 return await this._useSession(async (result) => {
                     var _a;
@@ -4410,10 +4642,15 @@ 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) {
-        return this._acquireLock(this.lockAcquireTimeout, async () => {
+        const run = async () => {
             try {
                 return await this._useSession(async (result) => {
                     var _a;
@@ -4453,14 +4690,17 @@ 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,
         });
@@ -4478,7 +4718,6 @@ 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 };
@@ -4827,8 +5066,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') ||