feat(auth): remove navigator.locks-based mutex; introduce commit guard + dispose()

[Bewinxed]

Description

What changed?

GoTrueClient now defaults to lockless coordination. The navigator.locks-based mutex no longer runs by default — most users get the lockless path. Callers who explicitly pass a custom lock (typically React Native processLock or Node multi-process setups) keep the old behavior on an opt-in legacy path so the change is backwards-compatible.

The lockless default uses:

• refreshingDeferred (already existed) to single-flight in-instance concurrent refreshes.
• A two-leg commit guard inside _callRefreshToken: (1) snapshots storage before the rotated-token fetch and re-reads after, discarding rotated tokens if a non-null snapshot was cleared between the two reads (typical case: a concurrent signOut ran _removeSession); (2) captures a session-removal epoch counter before _saveSession and re-checks after, so a signOut that interleaves inside _saveSession's storage-write awaits is also caught. Either leg returns { data: null, error: new AuthRefreshDiscardedError() }. _recoverAndRefresh recognises this error and skips its own _removeSession() call so no duplicate SIGNED_OUT event fires.
• A new exported error class, AuthRefreshDiscardedError (with an isAuthRefreshDiscardedError type guard), is what the commit guard returns when it throws away a successfully-rotated token. Distinct from AuthRetryableFetchError (transient network) and AuthApiError (server rejection). Surfaces through refreshSession() and getSession() results.
• A new client.auth.dispose() tears down the auto-refresh interval, the visibilitychange listener, the BroadcastChannel, and registered onAuthStateChange subscribers. Idempotent. Designed for React Strict Mode and HMR cleanup hooks. In-flight fetch calls are not aborted — they run to completion.
• GoTrue handles cross-tab refresh races server-side via the v1 parent-of-active path at internal/tokens/service.go:376-385, so the client doesn't need to coordinate. The current default is v1 (RefreshTokenAlgorithmVersion = 0); v2 (counter-based) is opt-in via RefreshTokenUpgradePercentage and gated rollout. This PR's reasoning relies on v1 behaviour, which is what customers actually run today.

The legacy opt-in path (settings.lock != null):

• _acquireLock, pendingInLock, lockAcquired, lockAcquireTimeout, and all 14 call-site wrappers are preserved verbatim from master and gated on this.lock != null. The default path is untouched by them.
• Every gated site is marked // TODO(v3): remove legacy lock path so the eventual v3 cleanup is a mechanical search-and-delete. A separate Linear ticket on the supabase-js v3 project tracks that work.
• The lock and lockAcquireTimeout constructor options are accepted and honored when supplied; both are @deprecated in JSDoc with "Custom locks still work in v2.x for backwards compatibility. Will be removed in v3."
• navigatorLock, processLock, LockAcquireTimeoutError, NavigatorLockAcquireTimeoutError, ProcessLockAcquireTimeoutError, and internals in lib/locks.ts remain exported. Still @deprecated.

Stale JSDoc referencing the lock on getSession, onAuthStateChange, _useSession, _challengeAndVerify, and _listFactors now matches the new default behaviour. The @deprecated tag on the async onAuthStateChange overload is kept, with its reason updated to point at the one residual reentry hazard (refreshSession called from inside a TOKEN_REFRESHED handler — refreshingDeferred.resolve happens after _notifyAllSubscribers returns).

Why was this change needed?

The shared mutex has caused seven failure classes on the issue tracker for 18+ months. Each earlier patch fixed one symptom and created another:

• #1962 configurable timeout
• #2106 steal fallback
• #2178 steal-cascade guard

#2235 (primitive swap to processLock) was an earlier attempt at moving off navigator.locks and is no longer being actively pursued. Community PRs #2016 and #2019 fixed individual symptoms and were closed waiting on a structural fix.

Failure classes resolved by this PR's default (lockless) path:

1. Strict Mode / HMR orphan deadlocks. Nothing to orphan on the default path.
2. iOS Safari INITIAL_SESSION / getSession() hangs with a persisted session (#936 @bugprone). The default path no longer touches navigator.locks.
3. Sentry flooding with AbortError: Lock broken by another request with the 'steal' option (#2013 @cpannwitz). The { steal: true } fallback that produced these errors is bypassed on the default path.
4. Subscriber re-entry deadlock (the one at the old GoTrueClient.ts:3824). The cycle needed the lock; a callback that awaits getUser() now just runs on the default path.
5. Visibility/tick race (#936 @JTBrinkmann). The visibility handler and the auto-refresh tick no longer share a lock to fight over on the default path.
6. Stale tickers/listeners on un-disposed clients. dispose() cleans them up.
7. signOut blocked behind in-flight refresh. signOut now runs concurrently with the refresh on the default path, and the two-leg commit guard prevents the refresh from writing rotated tokens after _removeSession() cleared storage — whether the clear happened before the post-fetch snapshot read or inside _saveSession's storage writes.

Callers on the legacy opt-in path (explicit settings.lock) keep the old serialization semantics and the failure modes that come with them. They accepted those when they opted in; they can drop the option to migrate to the lockless default at any time.

Why default lockless: cross-tab races are handled on the server (GoTrue's parent-of-active), in-instance refresh dedup is already handled by refreshingDeferred, and the only job the lock did beyond that was serializing subscriber callbacks — which is the deadlock we're fixing.

Closes (test target): #2013, #936, #2111

Examples

dispose() in a React app

import { useEffect } from 'react'
import { createClient } from '@supabase/supabase-js'

export function useSupabase() {
  useEffect(() => {
    const supabase = createClient(URL, KEY)
    return () => {
      supabase.auth.dispose()
    }
  }, [])
}

Subscriber callbacks can call other auth methods now (default path)

// Previously: deadlocked. Callback held the lock; getUser tried to acquire it.
// Now (default path): works.
supabase.auth.onAuthStateChange(async (event, session) => {
  if (event === 'SIGNED_IN') {
    const { data } = await supabase.auth.getUser()
    // ...
  }
})

One residual hazard remains: calling refreshSession from inside a TOKEN_REFRESHED handler still deadlocks via refreshingDeferred. The async overload of onAuthStateChange keeps its @deprecated marker for that reason.

AuthRefreshDiscardedError for the signOut-during-refresh race

import { isAuthRefreshDiscardedError } from '@supabase/auth-js'

const { data, error } = await supabase.auth.refreshSession()
if (isAuthRefreshDiscardedError(error)) {
  // A concurrent signOut cleared storage between when this refresh
  // started and when it came back. The rotated tokens were discarded.
  // The SIGNED_OUT event already fired from the concurrent signOut.
}

Legacy lock opt-in (existing custom-lock users)

// React Native processLock setup or Node multi-process setup
import { processLock } from '@supabase/auth-js'

const supabase = createClient(URL, KEY, {
  auth: { lock: processLock }, // legacy path, still works, deprecated for v3
})

Breaking changes

• This PR contains no breaking changes

The earlier draft of this PR silently dropped custom lock functions, which was behaviorally breaking for opt-in users. The current design preserves that behavior on a gated legacy path so the change ships as a v2 minor. Custom-lock users have time to migrate before v3 removes the option entirely.

Behaviour changes worth flagging for review

• Default coordination is lockless. A client constructed without a lock option no longer acquires navigator.locks or any in-process lock. For most users this is invisible (the lock was internal coordination). For users who depended on observing the lock indirectly (rare), the change is observable.
• _autoRefreshTokenTick may now run concurrently with signOut / setSession / getUser on the default path. Previously _acquireLock(0, ...) made the tick skip whenever any auth op held the lock. The lockless equivalent only skips when refreshingDeferred is set. The commit guard keeps storage consistent under the new concurrency. The legacy lock opt-in path retains the old skip-on-any-lock behavior.
• Subscriber timing on the default path: subscribers stay awaited; same as before. What changes is that signOut no longer waits for an in-flight refresh's HTTP and continuation to finish before its own fetch goes out. Both fetches now run concurrently, and the commit guard keeps storage consistent.

Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: <type>(<scope>): <description>
• I have run npx nx format to ensure consistent code formatting
• I have added tests for new functionality (commit guard, dispose(), subscriber re-entry no-deadlock, default vs. legacy path)
• I have updated documentation (JSDoc on affected methods, type-level deprecation notices)

Additional notes

Alternatives considered

Continuing to patch navigator.locks (better steal recovery, lower timeouts, smarter error filtering). Each prior patch in this direction (#1962, #2106, #2178) fixed one symptom and produced another. The Web Locks API has no recovery for orphaned holders other than { steal: true }, which leaves the previous fn() running concurrently with the new holder and creates the steal-cascade error storm. Each fix here swaps one failure for another instead of removing the contention that causes them.

Swapping navigatorLock for processLock as the default browser lock (the direction #2235 explored). Removes the cross-process orphan failure but keeps the same shape of the bug: one primitive serializing operations that don't all need the same synchronization.

Non-blocking subscriber notifications alone (#2016). Fixes subscriber re-entry. The other six failure classes still bite.

Removing the lock entirely (no legacy opt-in). The earlier draft of this PR did this. It silently dropped custom locks supplied via settings.lock, which broke React Native processLock and Node multi-process setups. The current design preserves those callers on a gated legacy path so the change is non-breaking; the legacy path is slated for removal in v3.

Adding an AbortController layer for in-flight operation cancellation. Deferred to a follow-up, not included here. The commit guard catches the races that affect correctness (signOut overwriting cleared storage with rotated tokens, in both the fetch and storage-write phases). AbortController would be a UX improvement on top: cancel the in-flight refresh as soon as signOut runs, instead of letting it finish and discarding the result. Out of scope for this PR.

Deferring the commit guard and accepting eventual consistency. Considered and rejected. Without a guard, a refresh that completes after _removeSession() cleared storage will write the rotated tokens back. Subscribers then see SIGNED_OUT followed by TOKEN_REFRESHED, with stale tokens in storage until the next refresh tick (~30s) fails against the server and clears them. The guard is about 30 lines (both legs combined). Better to land it with this PR than to ship the bug and patch it later.

Server-side context

Why cross-tab is safe on the default path: GoTrue's parent-of-active path at internal/tokens/service.go:376-385 (the v1 branch, *models.RefreshToken). When a request arrives with a revoked refresh token whose child is the currently-active token, the server returns the active token instead of rejecting. Two tabs that POST the same refresh token concurrently both receive the same rotated token under DB row locking. This is the production-default behaviour (RefreshTokenAlgorithmVersion = 0, v1). v2 (counter-based, gated on RefreshTokenUpgradePercentage) is safe under the same N-tab concurrency, covered by TestConcurrentReuse.

Test coverage

Updated tests in packages/core/auth-js/test/GoTrueClient.test.ts:

• 'Lockless coordination (default) and legacy lock opt-in' describe:
  • default path: client with no lock option, assert _acquireLock is never invoked
  • legacy path: client with custom lock, assert lock IS invoked (.toHaveBeenCalled())
  • lockAcquireTimeout accepted on both paths (lockless ignores it at runtime; legacy uses it)
  • subscriber callback may call other auth methods from inside onAuthStateChange without deadlock
• 'dispose() lifecycle' describe: idempotency, subscriber clearing, ticker stopping.
• 'Refresh commit guard (signOut-during-refresh race)' describe (4 tests): cleared-mid-flight discard, empty-storage acceptance, different-session acceptance, different-session-written-mid-flight discard.

Updated tests in packages/core/auth-js/test/GoTrueClient.browser.test.ts:

• 'Lockless coordination: navigator.locks should NOT be invoked': default path no longer touches the browser API.
• 'Legacy lock opt-in: custom lock function is invoked when supplied': custom lock IS called on the legacy path.

Updated tests in packages/core/supabase-js/test/unit/SupabaseAuthClient.test.ts:

• 'should pass through lockAcquireTimeout option' and 'should accept auth.lockAcquireTimeout and wire it to auth client': assert the option flows from createClient through to the auth client instance (via a targeted as unknown as { lockAcquireTimeout: number } cast). Comment in-source explains the cast is greppable for the v3 cleanup.

AI review responses

Addresses inline AI review feedback on this PR:

• TOCTOU window inside _saveSession (MEDIUM): closed via a new _sessionRemovalEpoch counter, incremented synchronously at the top of _removeSession before any await, captured in _callRefreshToken immediately before _saveSession, and re-checked after. If the epoch advances during the save, the rotated tokens are undone directly with removeItemAsync (not via _removeSession, which would emit a duplicate SIGNED_OUT).
• Refresh-token fragments in debug logs (LOW): removed substring(0, 5) of refresh_token from all four _debug() paths (_callRefreshToken / _refreshAccessToken debugName construction, plus the two fields in the commit-guard discard log). Discard logs now use presence indicators ('present' / 'replaced' / 'cleared') instead of credential fragments.

Open questions for review

1. AbortSignal.any plumbing in lib/fetch.ts isn't done here (no AbortController layer to plumb yet). If we add the AbortController follow-up later, this becomes a prerequisite. Just so it's on the radar.
2. @supabase/supabase-js types deprecation: lock and lockAcquireTimeout are @deprecated in the supabase-js types file too, since they delegate to the auth client. Confirm that's the right surface to deprecate.

v3 cleanup

A separate Linear ticket on the SDK team / supabase-js v3 project tracks the mechanical removal of the legacy lock path in v3. Every gated site in GoTrueClient.ts has a // TODO(v3): remove legacy lock path marker; the ticket lists the full file-by-file scope.

Status

Ready for review. Replaces #2387 (which was opened against develop before the v3 branching update).

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2392

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2392

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2392

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2392

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2392

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2392

commit: 1a98a57

[mandarini]

Do not merge until we ask users to test, and dogfood.