@supabase/auth-js 2.110.9 → 2.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/auth-js",
-  "version": "2.110.9",
+  "version": "2.111.0",
   "private": false,
   "description": "Official SDK for Supabase Auth",
   "keywords": [

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'
@@ -1005,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) {
@@ -1012,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,
@@ -1052,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 })
       }
 
@@ -1066,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 })
       }
@@ -1289,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
    * }
@@ -1362,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
    * {
@@ -1525,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)
   }
 
   /**
@@ -1968,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') {
@@ -1996,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
       }
@@ -2016,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 },
@@ -2216,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,
@@ -2237,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 })
       }
@@ -2260,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 })
       }
@@ -2507,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),
@@ -2540,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 })
       }
@@ -2666,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) {
@@ -2673,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,
@@ -2687,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) {
@@ -2712,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 })
       }
@@ -3207,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 })
@@ -3355,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
@@ -3368,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,
@@ -3394,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 })
       }
@@ -3826,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())
 
@@ -3934,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
   }
 
   /**
@@ -4002,7 +4059,6 @@ export default class GoTrueClient {
     return await this._useSession(async (result) => {
       const removeCurrentSession = async () => {
         await this._removeSession()
-        await removeItemAsync(this.storage, `${this.storageKey}-code-verifier`)
       }
       const { data, error: sessionError } = result
       if (sessionError && !isAuthSessionMissingError(sessionError)) {
@@ -4392,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
       )
     }
@@ -4409,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 })
       }
@@ -4514,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
    * }
@@ -4529,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,
           {
@@ -4543,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,
@@ -4553,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
     }
@@ -4606,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 })
         }
@@ -4742,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,
@@ -4755,7 +4816,7 @@ export default class GoTrueClient {
       window.location.assign(url)
     }
 
-    return { data: { provider, url }, error: null }
+    return { data: { provider, url, flowId }, error: null }
   }
 
   /**
@@ -5176,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) {
@@ -5600,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)}`,
@@ -5627,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> {

package/src/lib/constants.ts

@@ -40,4 +40,19 @@ export const API_VERSIONS = {
 
 export const BASE64URL_REGEX = /^([a-z0-9_-]{4})*($|[a-z0-9_-]{3}$|[a-z0-9_-]{2}$)$/i
 
+/**
+ * Reserved query parameter appended to `redirectTo` URLs (behind
+ * `experimental.appendPkceFlowIdToRedirects`) that correlates a PKCE callback
+ * with the code verifier stored when its flow started. It round-trips through
+ * the auth server untouched and identifies a verifier slot in storage — the
+ * verifier itself never appears in a URL.
+ */
+export const PKCE_FLOW_ID_PARAM = 'sb_flow_id'
+
+/**
+ * Maximum number of PKCE code verifiers kept in storage at once. Starting a
+ * new flow beyond this evicts the oldest pending verifier.
+ */
+export const PKCE_MAX_CONCURRENT_FLOWS = 5
+
 export const JWKS_TTL = 10 * 60 * 1000 // 10 minutes