@supabase/auth-js 2.110.9 → 2.111.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. */

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
@@ -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
     }

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.110.9'
+export const version = '2.111.0'