@supabase/gotrue-js 2.108.2 → 2.112.3

package/src/GoTrueClient.ts

@@ -6,6 +6,7 @@ import {
   EXPIRY_MARGIN_MS,
   GOTRUE_URL,
   JWKS_TTL,
+  PKCE_FLOW_ID_PARAM,
   REFRESH_FAILURE_COOLDOWN_MS,
   STORAGE_KEY,
 } from './lib/constants'
@@ -36,6 +37,7 @@ import {
   _userResponse,
 } from './lib/fetch'
 import {
+  appendFlowIdToRedirectTo,
   assertPasskeyExperimentalEnabled,
   decodeJWT,
   deepClone,
@@ -47,14 +49,19 @@ import {
   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, navigatorLock } from './lib/locks'
@@ -323,6 +330,23 @@ export default class GoTrueClient {
    * Keep extra care to never reject or throw uncaught errors
    */
   protected initializePromise: Promise<InitializeResult> | null = null
+  /**
+   * Non-null only while `initialize()` is running. While open,
+   * `_notifyAllSubscribers` enqueues init-chain notifications (those fired with
+   * `broadcast = true`, i.e. from `_recoverAndRefresh`) into this array instead
+   * of firing directly, so that `initializePromise` is guaranteed to be
+   * resolved before any subscriber callback runs. Callbacks that call
+   * `getSession()` / `getUser()` etc. would otherwise deadlock because those
+   * methods await `initializePromise`. Notifications from the incoming
+   * BroadcastChannel handler (`broadcast = false`) are not enqueued — they fire
+   * immediately. Flushed (in order) by `initialize()` after `initializePromise`
+   * settles.
+   */
+  private _pendingInitNotifications: Array<{
+    event: AuthChangeEvent
+    session: Session | null
+    broadcast: boolean
+  }> | null = null
   protected detectSessionInUrl:
     | boolean
     | ((url: URL, params: { [parameter: string]: string }) => boolean) = true
@@ -584,6 +608,16 @@ export default class GoTrueClient {
       return await this.initializePromise
     }
 
+    // Open the notification queue before _initialize() runs so that every
+    // _notifyAllSubscribers call inside the init chain enqueues instead of
+    // firing. Without this, a callback receiving SIGNED_IN (or TOKEN_REFRESHED
+    // / SIGNED_OUT) during _recoverAndRefresh would deadlock if it called
+    // getSession() / getUser() — those methods await initializePromise, which
+    // can only resolve after the callback returns, which can only return after
+    // getSession() resolves. The queue is flushed below after initializePromise
+    // has settled, so callbacks run with a fully resolved initializePromise.
+    this._pendingInitNotifications = []
+
     this.initializePromise = (async () => {
       if (this.lock != null) {
         // TODO(v3): remove legacy lock path
@@ -594,7 +628,17 @@ export default 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 = this._pendingInitNotifications ?? []
+    this._pendingInitNotifications = null
+    for (const n of queue) {
+      await this._notifyAllSubscribers(n.event, n.session, n.broadcast)
+    }
+
+    return result
   }
 
   /**
@@ -968,6 +1012,7 @@ export default class GoTrueClient {
    * ```
    */
   async signUp(credentials: SignUpWithPasswordCredentials): Promise<AuthResponse> {
+    let flowId: string | null = null
     try {
       let res: AuthResponse
       if ('email' in credentials) {
@@ -975,14 +1020,11 @@ export default class GoTrueClient {
         let codeChallenge: string | null = null
         let codeChallengeMethod: string | null = 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?.emailRedirectTo,
+          redirectTo: this._maybeAppendFlowIdToRedirect(options?.emailRedirectTo, flowId),
           body: {
             email,
             password,
@@ -1015,7 +1057,7 @@ export default 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 })
       }
 
@@ -1029,7 +1071,7 @@ export default 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 })
       }
@@ -1252,7 +1294,8 @@ export default 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
    * }
@@ -1325,12 +1368,29 @@ export default 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
    * {
@@ -1488,17 +1548,20 @@ export default class GoTrueClient {
    * }
    * ```
    */
-  async exchangeCodeForSession(authCode: string): Promise<AuthTokenResponse> {
+  async exchangeCodeForSession(
+    authCode: string,
+    options?: { flowId?: string }
+  ): Promise<AuthTokenResponse> {
     await this.initializePromise
 
     if (this.lock != null) {
       // TODO(v3): remove legacy lock path
       return this._acquireLock(this.lockAcquireTimeout, async () => {
-        return this._exchangeCodeForSession(authCode)
+        return this._exchangeCodeForSession(authCode, options)
       })
     }
 
-    return this._exchangeCodeForSession(authCode)
+    return this._exchangeCodeForSession(authCode, options)
   }
 
   /**
@@ -1931,15 +1994,40 @@ export default class GoTrueClient {
     }
   }
 
-  private async _exchangeCodeForSession(authCode: string): Promise<
+  private async _exchangeCodeForSession(
+    authCode: string,
+    options?: { flowId?: string }
+  ): Promise<
     | {
         data: { session: Session; user: User; redirectType: string | null }
         error: null
       }
     | { data: { session: null; user: null; redirectType: null }; error: AuthError }
   > {
-    const storageItem = await getItemAsync(this.storage, `${this.storageKey}-code-verifier`)
-    const [codeVerifier, redirectType] = ((storageItem ?? '') as string).split('/')
+    const hasExplicitFlowId = options?.flowId != null
+    const requestedFlowId = hasExplicitFlowId
+      ? validatePKCEFlowId(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?.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 ?? '').split('/')
 
     try {
       if (!codeVerifier && this.flowType === 'pkce') {
@@ -1959,7 +2047,7 @@ export default class GoTrueClient {
           xform: _sessionResponse,
         }
       )
-      await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+      await removePKCEVerifier(this.storage, this.storageKey, flowId)
       if (error) {
         throw error
       }
@@ -1979,7 +2067,7 @@ export default class GoTrueClient {
       }
       return this._returnResult({ data: { ...data, redirectType: 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 },
@@ -2179,16 +2267,14 @@ export default class GoTrueClient {
    * ```
    */
   async signInWithOtp(credentials: SignInWithPasswordlessCredentials): Promise<AuthOtpResponse> {
+    let flowId: string | null = null
     try {
       if ('email' in credentials) {
         const { email, options } = credentials
         let codeChallenge: string | null = null
         let codeChallengeMethod: string | null = 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,
@@ -2200,7 +2286,7 @@ export default class GoTrueClient {
             code_challenge: codeChallenge,
             code_challenge_method: codeChallengeMethod,
           },
-          redirectTo: options?.emailRedirectTo,
+          redirectTo: this._maybeAppendFlowIdToRedirect(options?.emailRedirectTo, flowId),
         })
         return this._returnResult({ data: { user: null, session: null }, error })
       }
@@ -2223,7 +2309,7 @@ export default 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 })
       }
@@ -2470,21 +2556,19 @@ export default class GoTrueClient {
    * ```
    */
   async signInWithSSO(params: SignInWithSSO): Promise<SSOResponse> {
+    let flowId: string | null = null
     try {
       let codeChallenge: string | null = null
       let codeChallengeMethod: string | null = 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: {
           ...('providerId' in params ? { provider_id: params.providerId } : null),
           ...('domain' in params ? { domain: params.domain } : null),
-          redirect_to: params.options?.redirectTo ?? undefined,
+          redirect_to: this._maybeAppendFlowIdToRedirect(params.options?.redirectTo, flowId),
           ...(params?.options?.captchaToken
             ? { gotrue_meta_security: { captcha_token: params.options.captchaToken } }
             : null),
@@ -2503,7 +2587,7 @@ export default class GoTrueClient {
 
       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 })
       }
@@ -2629,6 +2713,7 @@ export default class GoTrueClient {
    * ```
    */
   async resend(credentials: ResendParams): Promise<AuthOtpResponse> {
+    let flowId: string | null = null
     try {
       const endpoint = `${this.url}/resend`
       if ('email' in credentials) {
@@ -2636,10 +2721,7 @@ export default class GoTrueClient {
         let codeChallenge: string | null = null
         let codeChallengeMethod: string | null = 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,
@@ -2650,10 +2732,10 @@ export default class GoTrueClient {
             code_challenge: codeChallenge,
             code_challenge_method: codeChallengeMethod,
           },
-          redirectTo: options?.emailRedirectTo,
+          redirectTo: this._maybeAppendFlowIdToRedirect(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 })
       } else if ('phone' in credentials) {
@@ -2675,7 +2757,7 @@ export default class GoTrueClient {
         'You must provide either an email or phone number and a type'
       )
     } catch (error) {
-      await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+      await removePKCEVerifier(this.storage, this.storageKey, flowId)
       if (isAuthError(error)) {
         return this._returnResult({ data: { user: null, session: null }, error })
       }
@@ -2692,7 +2774,7 @@ export default class GoTrueClient {
    * to the client. If that storage is based on request cookies for example,
    * the values in it may not be authentic and therefore it's strongly advised
    * against using this method and its results in such circumstances. A warning
-   * will be emitted if this is detected. Use {@link #getUser()} instead.
+   * will be emitted if this is detected. Use {@link GoTrueClient.getUser} instead.
    *
    * @category Auth
    *
@@ -2861,7 +2943,7 @@ export default 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.
    */
@@ -2906,7 +2988,7 @@ export default class GoTrueClient {
   /**
    * NEVER USE DIRECTLY!
    *
-   * Always use {@link #_useSession}.
+   * Always use `_useSession`.
    */
   private async __loadSession(): Promise<
     | {
@@ -3170,7 +3252,6 @@ export default class GoTrueClient {
           // 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 })
@@ -3318,6 +3399,7 @@ export default class GoTrueClient {
       emailRedirectTo?: string | undefined
     } = {}
   ): Promise<UserResponse> {
+    let flowId: string | null = null
     try {
       return await this._useSession(async (result) => {
         const { data: sessionData, error: sessionError } = result
@@ -3331,15 +3413,12 @@ export default class GoTrueClient {
         let codeChallenge: string | null = null
         let codeChallengeMethod: string | null = 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?.emailRedirectTo,
+          redirectTo: this._maybeAppendFlowIdToRedirect(options?.emailRedirectTo, flowId),
           body: {
             ...attributes,
             code_challenge: codeChallenge,
@@ -3357,7 +3436,7 @@ export default class GoTrueClient {
         return this._returnResult({ data: { user: session.user }, 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 }, error })
       }
@@ -3789,11 +3868,14 @@ export default class GoTrueClient {
       if (callbackUrlType === 'pkce') {
         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())
 
@@ -3897,12 +3979,24 @@ export default class GoTrueClient {
    * Checks if the current URL and backing storage contain parameters given by a PKCE flow
    */
   private async _isPKCECallback(params: { [parameter: string]: string }): Promise<boolean> {
+    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
   }
 
   /**
@@ -3963,6 +4057,9 @@ export default class GoTrueClient {
     { scope }: SignOut = { scope: 'global' }
   ): Promise<{ error: AuthError | null }> {
     return await this._useSession(async (result) => {
+      const removeCurrentSession = async () => {
+        await this._removeSession()
+      }
       const { data, error: sessionError } = result
       if (sessionError && !isAuthSessionMissingError(sessionError)) {
         return this._returnResult({ error: sessionError })
@@ -3980,13 +4077,15 @@ export default class GoTrueClient {
               isAuthSessionMissingError(error)
             )
           ) {
+            if (scope !== 'others') {
+              await removeCurrentSession()
+            }
             return this._returnResult({ error })
           }
         }
       }
       if (scope !== 'others') {
-        await this._removeSession()
-        await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
+        await removeCurrentSession()
       }
       return this._returnResult({ error: null })
     })
@@ -4247,7 +4346,18 @@ export default class GoTrueClient {
       } catch (err) {
         await this.stateChangeEmitters.get(id)?.callback('INITIAL_SESSION', null)
         this._debug('INITIAL_SESSION', 'callback id', id, 'error', err)
-        if (isAuthSessionMissingError(err)) {
+        if (
+          isAuthSessionMissingError(err) ||
+          isAuthRetryableFetchError(err) ||
+          (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 {
           console.error(err)
@@ -4338,11 +4448,10 @@ export default class GoTrueClient {
   > {
     let codeChallenge: string | null = null
     let codeChallengeMethod: string | null = null
+    let flowId: string | null = null
 
     if (this.flowType === 'pkce') {
-      ;[codeChallenge, codeChallengeMethod] = await getCodeChallengeAndMethod(
-        this.storage,
-        this.storageKey,
+      ;[codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod(
         true // isPasswordRecovery
       )
     }
@@ -4355,10 +4464,10 @@ export default 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 })
       }
@@ -4460,7 +4569,8 @@ export default 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
    * }
@@ -4475,11 +4585,12 @@ export default class GoTrueClient {
   }
 
   private async linkIdentityOAuth(credentials: SignInWithOAuthCredentials): Promise<OAuthResponse> {
+    let flowId: string | null = null
     try {
       const { data, error } = await this._useSession(async (result) => {
         const { data, error } = result
         if (error) throw error
-        const url: string = await this._getUrlForProvider(
+        const { url, flowId: urlFlowId } = await this._getUrlForProvider(
           `${this.url}/user/identities/authorize`,
           credentials.provider,
           {
@@ -4489,6 +4600,7 @@ export default class GoTrueClient {
             skipBrowserRedirect: true,
           }
         )
+        flowId = urlFlowId
         return await _request(this.fetch, 'GET', url, {
           headers: this.headers,
           jwt: data.session?.access_token ?? undefined,
@@ -4499,12 +4611,15 @@ export default class GoTrueClient {
         window.location.assign(data?.url)
       }
       return this._returnResult({
-        data: { provider: credentials.provider, url: data?.url },
+        data: { provider: credentials.provider, url: 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
     }
@@ -4552,7 +4667,7 @@ export default 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 })
         }
@@ -4688,7 +4803,7 @@ export default class GoTrueClient {
       skipBrowserRedirect?: boolean
     }
   ) {
-    const url: string = 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,
@@ -4701,7 +4816,7 @@ export default class GoTrueClient {
       window.location.assign(url)
     }
 
-    return { data: { provider, url }, error: null }
+    return { data: { provider, url, flowId }, error: null }
   }
 
   /**
@@ -4823,7 +4938,15 @@ export default class GoTrueClient {
     } catch (err) {
       this._debug(debugName, 'error', err)
 
-      console.error(err)
+      if (isAuthRetryableFetchError(err)) {
+        // Transient/aborted network failure during session recovery (e.g. a
+        // superseded page navigation cancelling the in-flight request). Warn
+        // rather than surface it raw; the session is untouched and recovery
+        // will run again on the next load.
+        console.warn(err)
+      } else {
+        console.error(err)
+      }
       return
     } finally {
       this._debug(debugName, 'end')
@@ -5011,6 +5134,20 @@ export default class GoTrueClient {
     session: Session | null,
     broadcast = true
   ) {
+    if (this._pendingInitNotifications !== null && broadcast) {
+      // We're inside initialize() before initializePromise has resolved, and
+      // this notification originates from the init chain (_recoverAndRefresh),
+      // which always fires with broadcast = true. Enqueue instead of firing so
+      // that callbacks can safely call getSession() / getUser() without
+      // deadlocking on initializePromise.
+      //
+      // Notifications with broadcast = false come from the incoming
+      // BroadcastChannel handler (a cross-tab event), not the init chain, so
+      // they are fired immediately to preserve multi-tab ordering.
+      this._pendingInitNotifications.push({ event, session, broadcast })
+      return
+    }
+
     const debugName = `#_notifyAllSubscribers(${event})`
     this._debug(debugName, 'begin', session, `broadcast = ${broadcast}`)
 
@@ -5051,7 +5188,6 @@ export default class GoTrueClient {
     // _saveSession is always called whenever a new session has been acquired
     // so we can safely suppress the warning returned by future getSession calls
     this.suppressGetSessionWarning = true
-    await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
     // Create a shallow copy to work with, to avoid mutating the original session object if it's used elsewhere
     const sessionToProcess = { ...session }
 
@@ -5101,7 +5237,7 @@ export default class GoTrueClient {
     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) {
@@ -5114,8 +5250,8 @@ export default class GoTrueClient {
   /**
    * Removes any registered visibilitychange callback.
    *
-   * {@see #startAutoRefresh}
-   * {@see #stopAutoRefresh}
+   * {@link GoTrueClient.startAutoRefresh}
+   * {@link GoTrueClient.stopAutoRefresh}
    */
   private _removeVisibilityChangedCallback() {
     this._debug('#_removeVisibilityChangedCallback()')
@@ -5133,7 +5269,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * This is the private implementation of {@link #startAutoRefresh}. Use this
+   * This is the private implementation of {@link GoTrueClient.startAutoRefresh}. Use this
    * within the library.
    */
   private async _startAutoRefresh() {
@@ -5179,7 +5315,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * This is the private implementation of {@link #stopAutoRefresh}. Use this
+   * This is the private implementation of {@link GoTrueClient.stopAutoRefresh}. Use this
    * within the library.
    */
   private async _stopAutoRefresh() {
@@ -5220,7 +5356,7 @@ export default class GoTrueClient {
    * platform's foreground indication mechanism and call these methods
    * appropriately to conserve resources.
    *
-   * {@see #stopAutoRefresh}
+   * {@link GoTrueClient.stopAutoRefresh}
    *
    * @category Auth
    *
@@ -5255,7 +5391,7 @@ export default class GoTrueClient {
    * If you call this method any managed visibility change callback will be
    * removed and you must manage visibility changes on your own.
    *
-   * See {@link #startAutoRefresh} for more details.
+   * See {@link GoTrueClient.startAutoRefresh} for more details.
    *
    * @category Auth
    *
@@ -5525,19 +5661,23 @@ export default class GoTrueClient {
       skipBrowserRedirect?: boolean
     }
   ) {
+    let redirectTo = options?.redirectTo
+    let codeChallenge: string | null = null
+    let codeChallengeMethod: string | null = null
+    let flowId: string | null = null
+    if (this.flowType === 'pkce') {
+      ;[codeChallenge, codeChallengeMethod, flowId] = await this._getCodeChallengeAndMethod()
+      redirectTo = this._maybeAppendFlowIdToRedirect(redirectTo, flowId)
+    }
+
     const urlParams: string[] = [`provider=${encodeURIComponent(provider)}`]
-    if (options?.redirectTo) {
-      urlParams.push(`redirect_to=${encodeURIComponent(options.redirectTo)}`)
+    if (redirectTo) {
+      urlParams.push(`redirect_to=${encodeURIComponent(redirectTo)}`)
     }
     if (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)}`,
@@ -5552,7 +5692,44 @@ export default class GoTrueClient {
       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.
+   */
+  private _maybeAppendFlowIdToRedirect(
+    redirectTo: string | undefined,
+    flowId: string | null
+  ): string | undefined {
+    if (!redirectTo || !flowId || !this.experimental.appendPkceFlowIdToRedirects) {
+      return 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.
+   */
+  private async _getCodeChallengeAndMethod(
+    isPasswordRecovery = false
+  ): Promise<[string, string, string]> {
+    return getCodeChallengeAndMethod(
+      this.storage,
+      this.storageKey,
+      isPasswordRecovery,
+      (evictedFlowId) =>
+        this._debug(
+          '#_getCodeChallengeAndMethod()',
+          'evicted oldest pending PKCE verifier slot',
+          evictedFlowId
+        )
+    )
   }
 
   private async _unenroll(params: MFAUnenrollParams): Promise<AuthMFAUnenrollResponse> {
@@ -5577,7 +5754,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#enroll}
+   * {@link GoTrueMFAApi#enroll}
    */
   private async _enroll(params: MFAEnrollTOTPParams): Promise<AuthMFAEnrollTOTPResponse>
   private async _enroll(params: MFAEnrollPhoneParams): Promise<AuthMFAEnrollPhoneResponse>
@@ -5624,7 +5801,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#verify}
+   * {@link GoTrueMFAApi#verify}
    */
   private async _verify(params: MFAVerifyTOTPParams): Promise<AuthMFAVerifyResponse>
   private async _verify(params: MFAVerifyPhoneParams): Promise<AuthMFAVerifyResponse>
@@ -5713,7 +5890,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#challenge}
+   * {@link GoTrueMFAApi#challenge}
    */
   private async _challenge(
     params: MFAChallengeTOTPParams
@@ -5808,7 +5985,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#challengeAndVerify}
+   * {@link GoTrueMFAApi#challengeAndVerify}
    */
   private async _challengeAndVerify(
     params: MFAChallengeAndVerifyParams
@@ -5828,7 +6005,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#listFactors}
+   * {@link GoTrueMFAApi#listFactors}
    */
   private async _listFactors(): Promise<AuthMFAListFactorsResponse> {
     const {
@@ -5861,7 +6038,7 @@ export default class GoTrueClient {
   }
 
   /**
-   * {@see GoTrueMFAApi#getAuthenticatorAssuranceLevel}
+   * {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}
    */
   private async _getAuthenticatorAssuranceLevel(
     jwt?: string
@@ -6209,15 +6386,15 @@ export default class GoTrueClient {
    * Extracts the JWT claims present in the access token by first verifying the
    * JWT against the server's JSON Web Key Set endpoint
    * `/.well-known/jwks.json` which is often cached, resulting in significantly
-   * faster responses. Prefer this method over {@link #getUser} which always
+   * faster responses. Prefer this method over {@link GoTrueClient.getUser} which always
    * sends a request to the Auth server for each JWT.
    *
    * If the project is not using an asymmetric JWT signing key (like ECC or
-   * RSA) it always sends a request to the Auth server (similar to {@link
-   * #getUser}) to verify the JWT.
+   * RSA) it always sends a request to the Auth server (similar to
+   * {@link GoTrueClient.getUser}) to verify the JWT.
    *
    * @param jwt An optional specific JWT you wish to verify, not the one you
-   *            can obtain from {@link #getSession}.
+   *            can obtain from {@link GoTrueClient.getSession}.
    * @param options Various additional options that allow you to customize the
    *                behavior of this method.
    *