@supabase/gotrue-js 2.108.2 → 2.112.3

package/dist/module/GoTrueClient.js

@@ -1,8 +1,8 @@
 import GoTrueAdminApi from './GoTrueAdminApi';
-import { AUTO_REFRESH_TICK_DURATION_MS, AUTO_REFRESH_TICK_THRESHOLD, DEFAULT_HEADERS, EXPIRY_MARGIN_MS, GOTRUE_URL, JWKS_TTL, REFRESH_FAILURE_COOLDOWN_MS, STORAGE_KEY, } from './lib/constants';
+import { AUTO_REFRESH_TICK_DURATION_MS, AUTO_REFRESH_TICK_THRESHOLD, DEFAULT_HEADERS, EXPIRY_MARGIN_MS, GOTRUE_URL, JWKS_TTL, PKCE_FLOW_ID_PARAM, REFRESH_FAILURE_COOLDOWN_MS, 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 { _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 { appendFlowIdToRedirectTo, assertPasskeyExperimentalEnabled, decodeJWT, deepClone, Deferred, generateCallbackId, getAlgorithm, getCodeChallengeAndMethod, getItemAsync, insecureUserWarningProxy, isBrowser, parseParametersFromURL, pkceVerifierSlotKey, removeAllPKCEVerifiers, removeItemAsync, removePKCEVerifier, resolveFetch, retrievePKCEVerifier, retryable, setItemAsync, sleep, supportsLocalStorage, userNotAvailableProxy, validateExp, validatePKCEFlowId, } from './lib/helpers';
 import { memoryLocalStorageAdapter } from './lib/local-storage';
 import { LockAcquireTimeoutError } from './lib/locks';
 import { polyfillGlobalThis } from './lib/polyfills';
@@ -126,6 +126,19 @@ class GoTrueClient {
          * Keep extra care to never reject or throw uncaught errors
          */
         this.initializePromise = 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.
+         */
+        this._pendingInitNotifications = null;
         this.detectSessionInUrl = true;
         this.hasCustomAuthorizationHeader = false;
         this.suppressGetSessionWarning = false;
@@ -315,9 +328,19 @@ class GoTrueClient {
      * @category Auth
      */
     async initialize() {
+        var _a;
         if (this.initializePromise) {
             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 () => {
             if (this.lock != null) {
                 // TODO(v3): remove legacy lock path
@@ -327,7 +350,15 @@ class GoTrueClient {
             }
             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 = (_a = this._pendingInitNotifications) !== null && _a !== void 0 ? _a : [];
+        this._pendingInitNotifications = null;
+        for (const n of queue) {
+            await this._notifyAllSubscribers(n.event, n.session, n.broadcast);
+        }
+        return result;
     }
     /**
      * IMPORTANT:
@@ -683,6 +714,7 @@ class GoTrueClient {
      */
     async signUp(credentials) {
         var _a, _b, _c;
+        let flowId = null;
         try {
             let res;
             if ('email' in credentials) {
@@ -691,11 +723,11 @@ class GoTrueClient {
                 let codeChallengeMethod = null;
                 if (this.flowType === 'pkce') {
                     ;
-                    [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+                    [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
                 }
                 res = await _request(this.fetch, 'POST', `${this.url}/signup`, {
                     headers: this.headers,
-                    redirectTo: options === null || options === void 0 ? void 0 : options.emailRedirectTo,
+                    redirectTo: this._maybeAppendFlowIdToRedirect(options === null || options === void 0 ? void 0 : options.emailRedirectTo, flowId),
                     body: {
                         email,
                         password,
@@ -726,7 +758,7 @@ class GoTrueClient {
             }
             const { data, error } = res;
             if (error || !data) {
-                await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+                await removePKCEVerifier(this.storage, this.storageKey, flowId);
                 return this._returnResult({ data: { user: null, session: null }, error: error });
             }
             const session = data.session;
@@ -738,7 +770,7 @@ class GoTrueClient {
             return this._returnResult({ data: { user, session }, error: null });
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: { user: null, session: null }, error });
             }
@@ -953,7 +985,8 @@ class GoTrueClient {
      * {
      *   data: {
      *     provider: 'github',
-     *     url: <PROVIDER_URL_TO_REDIRECT_TO>
+     *     url: <PROVIDER_URL_TO_REDIRECT_TO>,
+     *     flowId: <PKCE_FLOW_ID_OR_NULL>
      *   },
      *   error: null
      * }
@@ -1026,12 +1059,29 @@ class GoTrueClient {
      *
      * @remarks
      * - Used when `flowType` is set to `pkce` in client options.
+     * - When several PKCE flows are in flight at once, pass `options.flowId` so
+     *   the code is exchanged with the verifier created by that specific flow.
+     *   The flow id is returned by `signInWithOAuth`, and with
+     *   `experimental.appendPkceFlowIdToRedirects` enabled it also arrives on
+     *   your callback URL as the reserved `sb_flow_id` query parameter (read
+     *   automatically in a browser).
+     * - When a flow id is present but its stored verifier is gone (evicted,
+     *   already used, or from another device), the call fails with a verifier
+     *   missing error instead of trying another flow's verifier — a mismatched
+     *   verifier would consume the single-use code. Without any flow id the
+     *   most recently stored verifier is used, as before.
      *
      * @example Exchange Auth Code
      * ```js
      * supabase.auth.exchangeCodeForSession('34e770dd-9ff9-416c-87fa-43b31d7ef225')
      * ```
      *
+     * @example Exchange Auth Code for a specific flow (e.g. in a server-side callback handler)
+     * ```js
+     * const flowId = requestUrl.searchParams.get('sb_flow_id')
+     * supabase.auth.exchangeCodeForSession(code, flowId ? { flowId } : undefined)
+     * ```
+     *
      * @exampleResponse Exchange Auth Code
      * ```json
      * {
@@ -1189,15 +1239,15 @@ class GoTrueClient {
      * }
      * ```
      */
-    async exchangeCodeForSession(authCode) {
+    async exchangeCodeForSession(authCode, options) {
         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, options);
             });
         }
-        return this._exchangeCodeForSession(authCode);
+        return this._exchangeCodeForSession(authCode, options);
     }
     /**
      * Signs in a user by verifying a message signed by the user's private key.
@@ -1539,8 +1589,23 @@ class GoTrueClient {
             throw error;
         }
     }
-    async _exchangeCodeForSession(authCode) {
-        const storageItem = await getItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+    async _exchangeCodeForSession(authCode, options) {
+        const hasExplicitFlowId = (options === null || options === void 0 ? void 0 : options.flowId) != null;
+        const requestedFlowId = hasExplicitFlowId
+            ? validatePKCEFlowId(options === null || options === void 0 ? void 0 : options.flowId)
+            : isBrowser()
+                ? validatePKCEFlowId(parseParametersFromURL(window.location.href)[PKCE_FLOW_ID_PARAM])
+                : null;
+        if (hasExplicitFlowId && !requestedFlowId) {
+            this._debug('#_exchangeCodeForSession()', 'provided flowId is not a valid flow id', options === null || options === void 0 ? void 0 : options.flowId);
+        }
+        // With a flow id (explicit or from the callback URL) the lookup is
+        // slot-only and a miss fails fast — see retrievePKCEVerifier. An invalid
+        // explicit flow id also fails fast rather than borrowing another flow's
+        // verifier.
+        const { verifier: storageItem, flowId } = hasExplicitFlowId && !requestedFlowId
+            ? { verifier: null, flowId: null }
+            : await retrievePKCEVerifier(this.storage, this.storageKey, requestedFlowId);
         const [codeVerifier, redirectType] = (storageItem !== null && storageItem !== void 0 ? storageItem : '').split('/');
         try {
             if (!codeVerifier && this.flowType === 'pkce') {
@@ -1554,7 +1619,7 @@ class GoTrueClient {
                 },
                 xform: _sessionResponse,
             });
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (error) {
                 throw error;
             }
@@ -1572,7 +1637,7 @@ class GoTrueClient {
             return this._returnResult({ data: Object.assign(Object.assign({}, data), { redirectType: redirectType !== null && redirectType !== void 0 ? redirectType : null }), error });
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({
                     data: { user: null, session: null, redirectType: null },
@@ -1771,6 +1836,7 @@ class GoTrueClient {
      */
     async signInWithOtp(credentials) {
         var _a, _b, _c, _d, _f;
+        let flowId = null;
         try {
             if ('email' in credentials) {
                 const { email, options } = credentials;
@@ -1778,7 +1844,7 @@ class GoTrueClient {
                 let codeChallengeMethod = null;
                 if (this.flowType === 'pkce') {
                     ;
-                    [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+                    [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
                 }
                 const { error } = await _request(this.fetch, 'POST', `${this.url}/otp`, {
                     headers: this.headers,
@@ -1790,7 +1856,7 @@ class GoTrueClient {
                         code_challenge: codeChallenge,
                         code_challenge_method: codeChallengeMethod,
                     },
-                    redirectTo: options === null || options === void 0 ? void 0 : options.emailRedirectTo,
+                    redirectTo: this._maybeAppendFlowIdToRedirect(options === null || options === void 0 ? void 0 : options.emailRedirectTo, flowId),
                 });
                 return this._returnResult({ data: { user: null, session: null }, error });
             }
@@ -1814,7 +1880,7 @@ class GoTrueClient {
             throw new AuthInvalidCredentialsError('You must provide either an email or phone number.');
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: { user: null, session: null }, error });
             }
@@ -2049,29 +2115,30 @@ class GoTrueClient {
      * ```
      */
     async signInWithSSO(params) {
-        var _a, _b, _c, _d, _f;
+        var _a, _b, _c, _d;
+        let flowId = null;
         try {
             let codeChallenge = null;
             let codeChallengeMethod = null;
             if (this.flowType === 'pkce') {
                 ;
-                [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+                [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
             }
             const result = await _request(this.fetch, 'POST', `${this.url}/sso`, {
-                body: Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, ('providerId' in params ? { provider_id: params.providerId } : null)), ('domain' in params ? { domain: params.domain } : null)), { redirect_to: (_b = (_a = params.options) === null || _a === void 0 ? void 0 : _a.redirectTo) !== null && _b !== void 0 ? _b : undefined }), (((_c = params === null || params === void 0 ? void 0 : params.options) === null || _c === void 0 ? void 0 : _c.captchaToken)
+                body: Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, ('providerId' in params ? { provider_id: params.providerId } : null)), ('domain' in params ? { domain: params.domain } : null)), { redirect_to: this._maybeAppendFlowIdToRedirect((_a = params.options) === null || _a === void 0 ? void 0 : _a.redirectTo, flowId) }), (((_b = params === null || params === void 0 ? void 0 : params.options) === null || _b === void 0 ? void 0 : _b.captchaToken)
                     ? { gotrue_meta_security: { captcha_token: params.options.captchaToken } }
                     : null)), { skip_http_redirect: true, code_challenge: codeChallenge, code_challenge_method: codeChallengeMethod }),
                 headers: this.headers,
                 xform: _ssoResponse,
             });
             // Automatically redirect in browser unless skipBrowserRedirect is true
-            if (((_d = result.data) === null || _d === void 0 ? void 0 : _d.url) && isBrowser() && !((_f = params.options) === null || _f === void 0 ? void 0 : _f.skipBrowserRedirect)) {
+            if (((_c = result.data) === null || _c === void 0 ? void 0 : _c.url) && isBrowser() && !((_d = params.options) === null || _d === void 0 ? void 0 : _d.skipBrowserRedirect)) {
                 window.location.assign(result.data.url);
             }
             return this._returnResult(result);
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: null, error });
             }
@@ -2191,6 +2258,7 @@ class GoTrueClient {
      * ```
      */
     async resend(credentials) {
+        let flowId = null;
         try {
             const endpoint = `${this.url}/resend`;
             if ('email' in credentials) {
@@ -2199,7 +2267,7 @@ class GoTrueClient {
                 let codeChallengeMethod = null;
                 if (this.flowType === 'pkce') {
                     ;
-                    [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+                    [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
                 }
                 const { error } = await _request(this.fetch, 'POST', endpoint, {
                     headers: this.headers,
@@ -2210,10 +2278,10 @@ class GoTrueClient {
                         code_challenge: codeChallenge,
                         code_challenge_method: codeChallengeMethod,
                     },
-                    redirectTo: options === null || options === void 0 ? void 0 : options.emailRedirectTo,
+                    redirectTo: this._maybeAppendFlowIdToRedirect(options === null || options === void 0 ? void 0 : options.emailRedirectTo, flowId),
                 });
                 if (error) {
-                    await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+                    await removePKCEVerifier(this.storage, this.storageKey, flowId);
                 }
                 return this._returnResult({ data: { user: null, session: null }, error });
             }
@@ -2235,7 +2303,7 @@ class GoTrueClient {
             throw new AuthInvalidCredentialsError('You must provide either an email or phone number and a type');
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: { user: null, session: null }, error });
             }
@@ -2251,7 +2319,7 @@ 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
      *
@@ -2402,7 +2470,7 @@ class GoTrueClient {
         }
     }
     /**
-     * Use instead of {@link #getSession} inside the library. Loads the session
+     * 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.
      */
@@ -2423,7 +2491,7 @@ class GoTrueClient {
     /**
      * NEVER USE DIRECTLY!
      *
-     * Always use {@link #_useSession}.
+     * Always use `_useSession`.
      */
     async __loadSession() {
         this._debug('#__loadSession()', 'begin');
@@ -2637,7 +2705,6 @@ class GoTrueClient {
                     // JWT contains a `session_id` which does not correspond to an active
                     // session in the database, indicating the user is signed out.
                     await this._removeSession();
-                    await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
                 }
                 return this._returnResult({ data: { user: null }, error });
             }
@@ -2769,6 +2836,7 @@ class GoTrueClient {
         return await this._updateUser(attributes, options);
     }
     async _updateUser(attributes, options = {}) {
+        let flowId = null;
         try {
             return await this._useSession(async (result) => {
                 const { data: sessionData, error: sessionError } = result;
@@ -2783,11 +2851,11 @@ class GoTrueClient {
                 let codeChallengeMethod = null;
                 if (this.flowType === 'pkce' && attributes.email != null) {
                     ;
-                    [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+                    [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
                 }
                 const { data, error: userError } = await _request(this.fetch, 'PUT', `${this.url}/user`, {
                     headers: this.headers,
-                    redirectTo: options === null || options === void 0 ? void 0 : options.emailRedirectTo,
+                    redirectTo: this._maybeAppendFlowIdToRedirect(options === null || options === void 0 ? void 0 : options.emailRedirectTo, flowId),
                     body: Object.assign(Object.assign({}, attributes), { code_challenge: codeChallenge, code_challenge_method: codeChallengeMethod }),
                     jwt: session.access_token,
                     xform: _userResponse,
@@ -2802,7 +2870,7 @@ class GoTrueClient {
             });
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: { user: null }, error });
             }
@@ -3195,11 +3263,14 @@ class GoTrueClient {
                 this._debug('#_initialize()', 'begin', 'is PKCE flow', true);
                 if (!params.code)
                     throw new AuthPKCEGrantCodeExchangeError('No code detected.');
-                const { data, error } = await this._exchangeCodeForSession(params.code);
+                const { data, error } = await this._exchangeCodeForSession(params.code, {
+                    flowId: params[PKCE_FLOW_ID_PARAM],
+                });
                 if (error)
                     throw error;
                 const url = new URL(window.location.href);
                 url.searchParams.delete('code');
+                url.searchParams.delete(PKCE_FLOW_ID_PARAM);
                 window.history.replaceState(window.history.state, '', url.toString());
                 return {
                     data: { session: data.session, redirectType: (_a = data.redirectType) !== null && _a !== void 0 ? _a : null },
@@ -3269,8 +3340,16 @@ class GoTrueClient {
      * Checks if the current URL and backing storage contain parameters given by a PKCE flow
      */
     async _isPKCECallback(params) {
+        if (!params.code) {
+            return false;
+        }
+        const flowId = validatePKCEFlowId(params[PKCE_FLOW_ID_PARAM]);
+        if (flowId &&
+            (await getItemAsync(this.storage, pkceVerifierSlotKey(this.storageKey, flowId)))) {
+            return true;
+        }
         const currentStorageContent = await getItemAsync(this.storage, `${this.storageKey}-code-verifier`);
-        return !!(params.code && currentStorageContent);
+        return !!currentStorageContent;
     }
     /**
      * Inside a browser context, `signOut()` will remove the logged in user from the browser session and log them out - removing all items from localstorage and then trigger a `"SIGNED_OUT"` event.
@@ -3326,6 +3405,9 @@ class GoTrueClient {
     async _signOut({ scope } = { scope: 'global' }) {
         return await this._useSession(async (result) => {
             var _a;
+            const removeCurrentSession = async () => {
+                await this._removeSession();
+            };
             const { data, error: sessionError } = result;
             if (sessionError && !isAuthSessionMissingError(sessionError)) {
                 return this._returnResult({ error: sessionError });
@@ -3339,13 +3421,15 @@ class GoTrueClient {
                     if (!((isAuthApiError(error) &&
                         (error.status === 404 || error.status === 401 || error.status === 403)) ||
                         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 });
         });
@@ -3566,7 +3650,16 @@ class GoTrueClient {
             catch (err) {
                 await ((_b = this.stateChangeEmitters.get(id)) === null || _b === void 0 ? void 0 : _b.callback('INITIAL_SESSION', null));
                 this._debug('INITIAL_SESSION', 'callback id', id, 'error', err);
-                if (isAuthSessionMissingError(err)) {
+                if (isAuthSessionMissingError(err) ||
+                    isAuthRetryableFetchError(err) ||
+                    (isAuthApiError(err) &&
+                        (err.code === 'refresh_token_not_found' ||
+                            err.code === 'refresh_token_already_used' ||
+                            err.code === 'session_expired'))) {
+                    // A missing session, a transient/aborted network failure (e.g. a
+                    // superseded page navigation cancelling the in-flight request), or
+                    // a dead refresh token (e.g. stale SSR cookies) is not an
+                    // application error — warn rather than surface it raw.
                     console.warn(err);
                 }
                 else {
@@ -3645,9 +3738,10 @@ class GoTrueClient {
     async resetPasswordForEmail(email, options = {}) {
         let codeChallenge = null;
         let codeChallengeMethod = null;
+        let flowId = null;
         if (this.flowType === 'pkce') {
             ;
-            [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey, true // isPasswordRecovery
+            [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod(true // isPasswordRecovery
             );
         }
         try {
@@ -3659,11 +3753,11 @@ class GoTrueClient {
                     gotrue_meta_security: { captcha_token: options.captchaToken },
                 },
                 headers: this.headers,
-                redirectTo: options.redirectTo,
+                redirectTo: this._maybeAppendFlowIdToRedirect(options.redirectTo, flowId),
             });
         }
         catch (error) {
-            await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+            await removePKCEVerifier(this.storage, this.storageKey, flowId);
             if (isAuthError(error)) {
                 return this._returnResult({ data: null, error });
             }
@@ -3746,7 +3840,8 @@ class GoTrueClient {
      * {
      *   data: {
      *     provider: 'github',
-     *     url: <PROVIDER_URL_TO_REDIRECT_TO>
+     *     url: <PROVIDER_URL_TO_REDIRECT_TO>,
+     *     flowId: <PKCE_FLOW_ID_OR_NULL>
      *   },
      *   error: null
      * }
@@ -3760,18 +3855,20 @@ class GoTrueClient {
     }
     async linkIdentityOAuth(credentials) {
         var _a;
+        let flowId = null;
         try {
             const { data, error } = await this._useSession(async (result) => {
                 var _a, _b, _c, _d, _f;
                 const { data, error } = result;
                 if (error)
                     throw error;
-                const url = await this._getUrlForProvider(`${this.url}/user/identities/authorize`, credentials.provider, {
+                const { url, flowId: urlFlowId } = await this._getUrlForProvider(`${this.url}/user/identities/authorize`, credentials.provider, {
                     redirectTo: (_a = credentials.options) === null || _a === void 0 ? void 0 : _a.redirectTo,
                     scopes: (_b = credentials.options) === null || _b === void 0 ? void 0 : _b.scopes,
                     queryParams: (_c = credentials.options) === null || _c === void 0 ? void 0 : _c.queryParams,
                     skipBrowserRedirect: true,
                 });
+                flowId = urlFlowId;
                 return await _request(this.fetch, 'GET', url, {
                     headers: this.headers,
                     jwt: (_f = (_d = data.session) === null || _d === void 0 ? void 0 : _d.access_token) !== null && _f !== void 0 ? _f : undefined,
@@ -3783,13 +3880,16 @@ class GoTrueClient {
                 window.location.assign(data === null || data === void 0 ? void 0 : data.url);
             }
             return this._returnResult({
-                data: { provider: credentials.provider, url: data === null || data === void 0 ? void 0 : data.url },
+                data: { provider: credentials.provider, url: data === null || data === void 0 ? void 0 : data.url, flowId },
                 error: null,
             });
         }
         catch (error) {
             if (isAuthError(error)) {
-                return this._returnResult({ data: { provider: credentials.provider, url: null }, error });
+                return this._returnResult({
+                    data: { provider: credentials.provider, url: null, flowId },
+                    error,
+                });
             }
             throw error;
         }
@@ -3832,7 +3932,7 @@ class GoTrueClient {
                 return this._returnResult({ data, error });
             }
             catch (error) {
-                await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`);
+                await removePKCEVerifier(this.storage, this.storageKey, null);
                 if (isAuthError(error)) {
                     return this._returnResult({ data: { user: null, session: null }, error });
                 }
@@ -3937,7 +4037,7 @@ class GoTrueClient {
         return isValidSession;
     }
     async _handleProviderSignIn(provider, options) {
-        const url = await this._getUrlForProvider(`${this.url}/authorize`, provider, {
+        const { url, flowId } = await this._getUrlForProvider(`${this.url}/authorize`, provider, {
             redirectTo: options.redirectTo,
             scopes: options.scopes,
             queryParams: options.queryParams,
@@ -3947,7 +4047,7 @@ class GoTrueClient {
         if (isBrowser() && !options.skipBrowserRedirect) {
             window.location.assign(url);
         }
-        return { data: { provider, url }, error: null };
+        return { data: { provider, url, flowId }, error: null };
     }
     /**
      * Recovers the session from LocalStorage and refreshes the token
@@ -4044,7 +4144,16 @@ 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 {
@@ -4194,6 +4303,19 @@ class GoTrueClient {
         }
     }
     async _notifyAllSubscribers(event, session, 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}`);
         try {
@@ -4230,7 +4352,6 @@ 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 = Object.assign({}, session);
         const userIsProxy = sessionToProcess.user && sessionToProcess.user.__isUserNotAvailableProxy === true;
@@ -4274,7 +4395,7 @@ class GoTrueClient {
         this.lastRefreshFailure = null;
         this.suppressGetSessionWarning = false;
         await removeItemAsync(this.storage, this.storageKey);
-        await removeItemAsync(this.storage, this.storageKey + '-code-verifier');
+        await removeAllPKCEVerifiers(this.storage, this.storageKey);
         await removeItemAsync(this.storage, this.storageKey + '-user');
         if (this.userStorage) {
             await removeItemAsync(this.userStorage, this.storageKey + '-user');
@@ -4284,8 +4405,8 @@ class GoTrueClient {
     /**
      * Removes any registered visibilitychange callback.
      *
-     * {@see #startAutoRefresh}
-     * {@see #stopAutoRefresh}
+     * {@link GoTrueClient.startAutoRefresh}
+     * {@link GoTrueClient.stopAutoRefresh}
      */
     _removeVisibilityChangedCallback() {
         this._debug('#_removeVisibilityChangedCallback()');
@@ -4301,7 +4422,7 @@ 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.
      */
     async _startAutoRefresh() {
@@ -4343,7 +4464,7 @@ 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.
      */
     async _stopAutoRefresh() {
@@ -4379,7 +4500,7 @@ class GoTrueClient {
      * platform's foreground indication mechanism and call these methods
      * appropriately to conserve resources.
      *
-     * {@see #stopAutoRefresh}
+     * {@link GoTrueClient.stopAutoRefresh}
      *
      * @category Auth
      *
@@ -4413,7 +4534,7 @@ 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
      *
@@ -4640,15 +4761,23 @@ class GoTrueClient {
      * @param options.queryParams An object of key-value pairs containing query parameters granted to the OAuth application.
      */
     async _getUrlForProvider(url, provider, options) {
+        let redirectTo = options === null || options === void 0 ? void 0 : options.redirectTo;
+        let codeChallenge = null;
+        let codeChallengeMethod = null;
+        let flowId = null;
+        if (this.flowType === 'pkce') {
+            ;
+            [codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod();
+            redirectTo = this._maybeAppendFlowIdToRedirect(redirectTo, flowId);
+        }
         const urlParams = [`provider=${encodeURIComponent(provider)}`];
-        if (options === null || options === void 0 ? void 0 : options.redirectTo) {
-            urlParams.push(`redirect_to=${encodeURIComponent(options.redirectTo)}`);
+        if (redirectTo) {
+            urlParams.push(`redirect_to=${encodeURIComponent(redirectTo)}`);
         }
         if (options === null || options === void 0 ? void 0 : options.scopes) {
             urlParams.push(`scopes=${encodeURIComponent(options.scopes)}`);
         }
-        if (this.flowType === 'pkce') {
-            const [codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(this.storage, this.storageKey);
+        if (codeChallenge != null && codeChallengeMethod != null) {
             const flowParams = new URLSearchParams({
                 code_challenge: `${encodeURIComponent(codeChallenge)}`,
                 code_challenge_method: `${encodeURIComponent(codeChallengeMethod)}`,
@@ -4662,7 +4791,27 @@ class GoTrueClient {
         if (options === null || options === void 0 ? void 0 : options.skipBrowserRedirect) {
             urlParams.push(`skip_http_redirect=${options.skipBrowserRedirect}`);
         }
-        return `${url}?${urlParams.join('&')}`;
+        return { url: `${url}?${urlParams.join('&')}`, flowId };
+    }
+    /**
+     * Appends the reserved flow id parameter to a redirect URL so the callback
+     * can be matched to the verifier stored for its flow. Opt-in via
+     * `experimental.appendPkceFlowIdToRedirects`: redirect URLs are validated
+     * against the project's allow list including the query string, so an extra
+     * parameter can stop exact (non-wildcard) entries from matching.
+     */
+    _maybeAppendFlowIdToRedirect(redirectTo, flowId) {
+        if (!redirectTo || !flowId || !this.experimental.appendPkceFlowIdToRedirects) {
+            return redirectTo !== null && redirectTo !== void 0 ? redirectTo : undefined;
+        }
+        return appendFlowIdToRedirectTo(redirectTo, flowId);
+    }
+    /**
+     * Generates and stores a PKCE challenge/verifier pair for a new flow,
+     * logging any pending verifier the bounded slot ring evicts.
+     */
+    async _getCodeChallengeAndMethod(isPasswordRecovery = false) {
+        return getCodeChallengeAndMethod(this.storage, this.storageKey, isPasswordRecovery, (evictedFlowId) => this._debug('#_getCodeChallengeAndMethod()', 'evicted oldest pending PKCE verifier slot', evictedFlowId));
     }
     async _unenroll(params) {
         try {
@@ -4810,7 +4959,7 @@ class GoTrueClient {
         return run();
     }
     /**
-     * {@see GoTrueMFAApi#challengeAndVerify}
+     * {@link GoTrueMFAApi#challengeAndVerify}
      */
     async _challengeAndVerify(params) {
         const { data: challengeData, error: challengeError } = await this._challenge({
@@ -4826,7 +4975,7 @@ class GoTrueClient {
         });
     }
     /**
-     * {@see GoTrueMFAApi#listFactors}
+     * {@link GoTrueMFAApi#listFactors}
      */
     async _listFactors() {
         var _a;
@@ -4854,7 +5003,7 @@ class GoTrueClient {
         };
     }
     /**
-     * {@see GoTrueMFAApi#getAuthenticatorAssuranceLevel}
+     * {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}
      */
     async _getAuthenticatorAssuranceLevel(jwt) {
         var _a, _b, _c, _d;
@@ -5105,15 +5254,15 @@ 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.
      *