@supabase/gotrue-js 2.108.2 → 2.112.3

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

package/src/lib/errors.ts

@@ -16,7 +16,7 @@ export class AuthError extends Error {
    * Error code associated with the error. Most errors coming from
    * HTTP responses will have a code, though some errors that occur
    * before a response is received will not have one present. In that
-   * case {@link #status} will also be undefined.
+   * case {@link AuthError.status} will also be undefined.
    */
   code: ErrorCode | (string & {}) | undefined
 

package/src/lib/fetch.ts

@@ -81,18 +81,22 @@ export async function handleError(error: unknown) {
     throw new AuthRetryableFetchError(_getErrorMessage(error), 0)
   }
 
-  if (NETWORK_ERROR_CODES.includes(error.status)) {
-    // status in 500...599 range - server had an error, request might be retryed.
-    throw new AuthRetryableFetchError(_getErrorMessage(error), error.status)
-  }
-
   let data: any
   try {
     data = await error.json()
   } catch (e) {
+    if (NETWORK_ERROR_CODES.includes(error.status)) {
+      // statusText can be empty — HTTP/2 has no reason phrase
+      throw new AuthRetryableFetchError(error.statusText || `HTTP ${error.status}`, error.status)
+    }
     throw new AuthUnknownError(_getErrorMessage(e), e)
   }
 
+  if (NETWORK_ERROR_CODES.includes(error.status)) {
+    // status in 500...599 range - server had an error, request might be retryed.
+    throw new AuthRetryableFetchError(_getErrorMessage(data), error.status)
+  }
+
   let errorCode: string | undefined = undefined
 
   const responseAPIVersion = parseResponseAPIVersion(error)
@@ -224,9 +228,10 @@ async function _handleRequest(
       ...requestParams,
     })
   } catch (e) {
-    console.error(e)
-
-    // fetch failed, likely due to a network or CORS error
+    // fetch failed (network / CORS / aborted request) — surfaced to the
+    // caller as a retryable error below. Deliberately not logged here: an
+    // aborted in-flight request (e.g. a superseded page navigation) is a
+    // transient condition, and logging the raw error pollutes the console.
     throw new AuthRetryableFetchError(_getErrorMessage(e), 0)
   }
 

package/src/lib/helpers.ts

@@ -1,4 +1,9 @@
-import { API_VERSION_HEADER_NAME, BASE64URL_REGEX } from './constants'
+import {
+  API_VERSION_HEADER_NAME,
+  BASE64URL_REGEX,
+  PKCE_FLOW_ID_PARAM,
+  PKCE_MAX_CONCURRENT_FLOWS,
+} from './constants'
 import { AuthInvalidJwtError } from './errors'
 import { base64UrlToUint8Array, stringFromBase64URL } from './base64url'
 import { JwtHeader, JwtPayload, SupportedStorage, User } from './types'
@@ -301,20 +306,207 @@ export async function generatePKCEChallenge(verifier: string) {
   return btoa(hashed).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
 }
 
+const PKCE_FLOW_ID_PATTERN = /^[a-zA-Z0-9_-]{8,64}$/
+
+/**
+ * Returns the flow id if it is a plausible flow id, `null` otherwise. Flow
+ * ids can arrive via URL parameters, so anything outside the expected shape
+ * is discarded before it is used to build a storage key.
+ */
+export function validatePKCEFlowId(flowId: unknown): string | null {
+  return typeof flowId === 'string' && PKCE_FLOW_ID_PATTERN.test(flowId) ? flowId : null
+}
+
+export function generatePKCEFlowId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16)
+    crypto.getRandomValues(bytes)
+    return Array.from(bytes, dec2hex).join('')
+  }
+  let flowId = ''
+  for (let i = 0; i < 32; i++) {
+    flowId += Math.floor(Math.random() * 16).toString(16)
+  }
+  return flowId
+}
+
+// Slot keys deliberately end in `-code-verifier`: @supabase/ssr's server
+// cookie adapter only persists writes immediately for keys with that suffix
+// (no auth event fires when a verifier is stored). They also contain no dot,
+// because @supabase/ssr chunks oversized cookies as `<key>.<number>` and a
+// dot-delimited key could be mistaken for a chunk of the fixed
+// `-code-verifier` cookie and clobbered by its chunk management.
+export const pkceVerifierSlotKey = (storageKey: string, flowId: string) =>
+  `${storageKey}-flow-${flowId}-code-verifier`
+
+const pkceFlowIndexKey = (storageKey: string) => `${storageKey}-flows-code-verifier`
+
+/**
+ * Storage adapters cannot enumerate keys, so the ids of pending verifier
+ * slots are tracked in an index entry, oldest first. Index entries pass
+ * through the same validation as URL-provided flow ids: with cookie-based
+ * storage the index contents are no more trustworthy than a URL parameter.
+ */
+async function getPKCEFlowIndex(storage: SupportedStorage, storageKey: string): Promise<string[]> {
+  const index = await getItemAsync(storage, pkceFlowIndexKey(storageKey))
+  return Array.isArray(index)
+    ? index.filter((id): id is string => validatePKCEFlowId(id) !== null)
+    : []
+}
+
+/**
+ * The index is read-modify-write without a lock: two concurrent starts (e.g.
+ * two tabs) can lose one index update. The losing flow still works — its slot
+ * is addressed directly by key — but its entry is missing from the index, so
+ * it escapes both ring eviction and removeAllPKCEVerifiers: the orphaned slot
+ * persists for the storage medium's lifetime (up to the cookie max age in
+ * cookie storage) and repeated races accumulate one orphan each. Accepted
+ * trade-off: locking every flow start is far more intrusive than the leak.
+ */
+export async function storePKCEVerifier(
+  storage: SupportedStorage,
+  storageKey: string,
+  flowId: string,
+  verifier: string,
+  onEvictFlow?: (evictedFlowId: string) => void
+): Promise<void> {
+  await setItemAsync(storage, pkceVerifierSlotKey(storageKey, flowId), verifier)
+
+  const index = (await getPKCEFlowIndex(storage, storageKey)).filter((id) => id !== flowId)
+  index.push(flowId)
+  while (index.length > PKCE_MAX_CONCURRENT_FLOWS) {
+    const evicted = index.shift()!
+    await removeItemAsync(storage, pkceVerifierSlotKey(storageKey, evicted))
+    onEvictFlow?.(evicted)
+  }
+  await setItemAsync(storage, pkceFlowIndexKey(storageKey), index)
+
+  // Deprecation-window dual write: exchanges that cannot identify their flow
+  // (older SDK versions, redirects without the flow id parameter) read the
+  // fixed key, which mirrors the most recently started flow.
+  await setItemAsync(storage, `${storageKey}-code-verifier`, verifier)
+}
+
+/**
+ * Looks up the verifier for `flowId`. When a flow id is given, only that slot
+ * is consulted — deliberately no fallback to the fixed legacy key: submitting
+ * another flow's verifier would burn the single-use auth code, and the
+ * subsequent cleanup would delete a pending flow's only fallback. The legacy
+ * key is read only when no flow id is available at all.
+ */
+export async function retrievePKCEVerifier(
+  storage: SupportedStorage,
+  storageKey: string,
+  flowId: string | null
+): Promise<{ verifier: string | null; flowId: string | null }> {
+  if (flowId) {
+    const verifier = await getItemAsync(storage, pkceVerifierSlotKey(storageKey, flowId))
+    return { verifier: typeof verifier === 'string' ? verifier : null, flowId }
+  }
+  const verifier = await getItemAsync(storage, `${storageKey}-code-verifier`)
+  return { verifier: typeof verifier === 'string' ? verifier : null, flowId: null }
+}
+
+/**
+ * Removes a single flow's verifier. Never clears other flows' slots: with a
+ * `flowId` only that slot is deleted (plus the legacy fixed key when it holds
+ * the same verifier); without one, only the legacy fixed key is deleted.
+ */
+export async function removePKCEVerifier(
+  storage: SupportedStorage,
+  storageKey: string,
+  flowId: string | null
+): Promise<void> {
+  const legacyKey = `${storageKey}-code-verifier`
+  if (!flowId) {
+    await removeItemAsync(storage, legacyKey)
+    return
+  }
+
+  const slotKey = pkceVerifierSlotKey(storageKey, flowId)
+  const slotValue = await getItemAsync(storage, slotKey)
+  await removeItemAsync(storage, slotKey)
+
+  // Skip the index rewrite when the flow was never indexed (e.g. a failed
+  // exchange for an absent slot): on cookie storage every write is a full
+  // Set-Cookie cycle.
+  const index = await getPKCEFlowIndex(storage, storageKey)
+  const remaining = index.filter((id) => id !== flowId)
+  if (remaining.length !== index.length) {
+    if (remaining.length > 0) {
+      await setItemAsync(storage, pkceFlowIndexKey(storageKey), remaining)
+    } else {
+      await removeItemAsync(storage, pkceFlowIndexKey(storageKey))
+    }
+  }
+
+  if (slotValue != null && slotValue === (await getItemAsync(storage, legacyKey))) {
+    await removeItemAsync(storage, legacyKey)
+  }
+}
+
+/**
+ * Removes every pending verifier: all slots in the index, the index itself
+ * and the fixed legacy key. Used on session teardown (sign-out, invalid
+ * session) — matches the pre-slot behavior where tearing down the session
+ * deleted the only verifier, and prevents long-lived stale verifier cookies.
+ */
+export async function removeAllPKCEVerifiers(
+  storage: SupportedStorage,
+  storageKey: string
+): Promise<void> {
+  const index = await getPKCEFlowIndex(storage, storageKey)
+  for (const flowId of index) {
+    await removeItemAsync(storage, pkceVerifierSlotKey(storageKey, flowId))
+  }
+  await removeItemAsync(storage, pkceFlowIndexKey(storageKey))
+  await removeItemAsync(storage, `${storageKey}-code-verifier`)
+}
+
+/**
+ * Appends the reserved flow id parameter to a `redirectTo` URL, replacing any
+ * existing occurrence. String-based (no URL round-trip) so custom schemes
+ * (native deep links) and the exact encoding of the app's own parameters
+ * survive untouched; an existing fragment stays at the end of the URL.
+ */
+export function appendFlowIdToRedirectTo(redirectTo: string, flowId: string): string {
+  const hashIndex = redirectTo.indexOf('#')
+  let base = hashIndex === -1 ? redirectTo : redirectTo.slice(0, hashIndex)
+  const fragment = hashIndex === -1 ? '' : redirectTo.slice(hashIndex)
+
+  const queryIndex = base.indexOf('?')
+  if (queryIndex !== -1) {
+    const path = base.slice(0, queryIndex)
+    const remaining = base
+      .slice(queryIndex + 1)
+      .split('&')
+      .filter(
+        (pair) =>
+          pair !== '' && pair !== PKCE_FLOW_ID_PARAM && !pair.startsWith(`${PKCE_FLOW_ID_PARAM}=`)
+      )
+    base = remaining.length > 0 ? `${path}?${remaining.join('&')}` : path
+  }
+
+  const separator = base.includes('?') ? '&' : '?'
+  return `${base}${separator}${PKCE_FLOW_ID_PARAM}=${encodeURIComponent(flowId)}${fragment}`
+}
+
 export async function getCodeChallengeAndMethod(
   storage: SupportedStorage,
   storageKey: string,
-  isPasswordRecovery = false
-) {
+  isPasswordRecovery = false,
+  onEvictFlow?: (evictedFlowId: string) => void
+): Promise<[string, string, string]> {
   const codeVerifier = generatePKCEVerifier()
   let storedCodeVerifier = codeVerifier
   if (isPasswordRecovery) {
     storedCodeVerifier += '/recovery'
   }
-  await setItemAsync(storage, `${storageKey}-code-verifier`, storedCodeVerifier)
+  const flowId = generatePKCEFlowId()
+  await storePKCEVerifier(storage, storageKey, flowId, storedCodeVerifier, onEvictFlow)
   const codeChallenge = await generatePKCEChallenge(codeVerifier)
   const codeChallengeMethod = codeVerifier === codeChallenge ? 'plain' : 's256'
-  return [codeChallenge, codeChallengeMethod]
+  return [codeChallenge, codeChallengeMethod, flowId]
 }
 
 /** Parses the API version which is 2YYY-MM-DD. */
@@ -369,7 +561,7 @@ export function getAlgorithm(
   }
 }
 
-const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 export function validateUUID(str: string) {
   if (!UUID_REGEX.test(str)) {

package/src/lib/locks.ts

@@ -302,7 +302,7 @@ const PROCESS_LOCKS: { [name: string]: Promise<any> } = {}
  * Useful for environments like React Native or other non-browser
  * single-process (i.e. no concept of "tabs") environments.
  *
- * Use {@link #navigatorLock} in browser environments.
+ * Use {@link navigatorLock} in browser environments.
  *
  * @param name Name of the lock to be acquired.
  * @param acquireTimeout If negative, no timeout. If 0 an error is thrown if

package/src/lib/types.ts

@@ -190,6 +190,30 @@ export type ExperimentalFeatureFlags = {
    * disabled throws a descriptive error at call time.
    */
   passkey?: boolean
+  /**
+   * Appends a reserved `sb_flow_id` query parameter to `redirectTo` URLs on
+   * PKCE flows. The parameter round-trips through the auth server back to
+   * your callback URL, where the client uses it to select the code verifier
+   * created by that specific flow — so multiple sign-in flows (e.g. two OAuth
+   * providers started in different tabs) can be in flight at the same time
+   * without overwriting each other.
+   *
+   * Before enabling, make sure your [redirect URL allow
+   * list](https://supabase.com/docs/guides/auth/redirect-urls) tolerates the
+   * extra query parameter: allow-list entries are matched against the full
+   * URL including the query string, so an exact entry (no wildcard) stops
+   * matching once the parameter is appended and the redirect falls back to
+   * your Site URL. Redirects to the Site URL's own origin always pass.
+   *
+   * Defaults to `false`. Without it, concurrent flows still keep separate
+   * verifiers in storage, but no flow id travels through the redirect: to
+   * match a callback to its verifier you must carry the `flowId` returned by
+   * `signInWithOAuth` (or `linkIdentity`) through your own channel and pass
+   * it to `exchangeCodeForSession`. Flows that offer no way to obtain the
+   * flow id (email OTP, password recovery, sign-up confirmation) can only be
+   * correlated via this flag.
+   */
+  appendPkceFlowIdToRedirects?: boolean
 }
 
 const WeakPasswordReasons = ['length', 'characters', 'pwned'] as const
@@ -228,7 +252,7 @@ export type RequestResult<T, ErrorType extends Error = AuthError> =
 
 /**
  * similar to RequestResult except it allows you to destructure the possible shape of the success response
- *  {@see RequestResult}
+ *  {@link RequestResult}
  */
 export type RequestResultSafeDestructure<T> =
   | { data: T; error: null }
@@ -251,7 +275,7 @@ export type AuthResponsePassword = RequestResultSafeDestructure<{
 /**
  * AuthOtpResponse is returned when OTP is used.
  *
- * {@see AuthResponse}
+ * {@link AuthResponse}
  */
 export type AuthOtpResponse = RequestResultSafeDestructure<{
   user: null
@@ -275,6 +299,19 @@ export type OAuthResponse =
       data: {
         provider: Provider
         url: string
+        /**
+         * Identifier of the PKCE flow started by this call, usable as the
+         * `flowId` option of {@link GoTrueClient#exchangeCodeForSession} to
+         * select this flow's code verifier when several flows are in flight.
+         * `null` on the implicit flow. The id is a selector for a verifier
+         * kept in storage — it is not a secret and never contains the
+         * verifier itself.
+         *
+         * Always set at runtime; optional in the type so existing code that
+         * constructs `OAuthResponse` values (e.g. test mocks) keeps
+         * compiling.
+         */
+        flowId?: string | null
       }
       error: null
     }
@@ -282,6 +319,7 @@ export type OAuthResponse =
       data: {
         provider: Provider
         url: null
+        flowId?: string | null
       }
       error: AuthError
     }
@@ -407,7 +445,7 @@ type FactorVerificationStatus = (typeof FactorVerificationStatuses)[number]
  *
  * @see {@link GoTrueMFAApi#enroll}
  * @see {@link GoTrueMFAApi#listFactors}
- * @see {@link GoTrueMFAAdminApi#listFactors}
+ * @see {@link GoTrueAdminMFAApi#listFactors}
  */
 export type Factor<
   Type extends FactorType = FactorType,
@@ -1691,14 +1729,14 @@ export interface GoTrueMFAApi {
 }
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminDeleteFactorResponse = RequestResult<{
   /** ID of the factor that was successfully deleted. */
   id: string
 }>
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminDeleteFactorParams = {
   /** ID of the MFA factor to delete. */
@@ -1709,7 +1747,7 @@ export type AuthMFAAdminDeleteFactorParams = {
 }
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminListFactorsResponse = RequestResult<{
   /** All factors attached to the user. */
@@ -1717,7 +1755,7 @@ export type AuthMFAAdminListFactorsResponse = RequestResult<{
 }>
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminListFactorsParams = {
   /** ID of the user. */
@@ -1727,7 +1765,7 @@ export type AuthMFAAdminListFactorsParams = {
 /**
  * Contains the full multi-factor authentication administration API.
  *
- * @expermental
+ * @experimental
  */
 export interface GoTrueAdminMFAApi {
   /**
@@ -1769,7 +1807,7 @@ export interface GoTrueAdminMFAApi {
    *
    * @see {@link GoTrueMFAApi#unenroll}
    *
-   * @expermental
+   * @experimental
    *
    * @category Auth
    * @subcategory Auth Admin
@@ -2250,6 +2288,14 @@ export type CustomOAuthProvider = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */
@@ -2300,6 +2346,14 @@ export type CreateCustomProviderParams = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */
@@ -2342,6 +2396,14 @@ export type UpdateCustomProviderParams = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.108.2'
+export const version = '2.112.3'