@supabase/auth-js 2.107.0-canary.0 → 2.107.0-canary.2

package/migrations/lockless-coordination.md

@@ -0,0 +1,89 @@
+# Lockless auth coordination
+
+**Since:** v2.X.Y (update at release time)
+**Action required by:** v3.0.0
+
+`@supabase/auth-js` now coordinates session refreshes without a shared mutex by default. The legacy `lock` option is still honored when supplied, but it is deprecated and will be removed in v3.
+
+## What changed
+
+- **Default coordination is lockless.** A client constructed without a `lock` option no longer acquires `navigator.locks` or any in-process lock. In-tab concurrent refreshes are deduplicated via the pre-existing single-flight (`refreshingDeferred`); cross-tab refresh races are resolved by GoTrue's server-side parent-of-active mechanism on the v1 refresh-token path.
+- **Commit guard inside `_callRefreshToken`.** The client snapshots storage before the rotated-token fetch and re-reads after. If a non-null pre-fetch snapshot was cleared between the two reads (typical case: a concurrent `signOut` ran `_removeSession`), the rotated tokens are discarded instead of being written back over the cleared storage. The discarded result resolves with `{ data: null, error: new AuthRefreshDiscardedError() }`.
+- **New `AuthRefreshDiscardedError`** (with `isAuthRefreshDiscardedError` type guard). Surfaces through `refreshSession()` and `getSession()` results when the commit guard fires. Distinct from `AuthRetryableFetchError` (transient network) and `AuthApiError` (server rejection).
+- **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.
+- **`lock` and `lockAcquireTimeout` options.** Accepted and honored when supplied (legacy opt-in path); both are `@deprecated` and will be removed in v3.
+
+## Who is affected
+
+**Most callers: nothing to do.** If you do not pass a `lock` option to `createClient` / `GoTrueClient`, you are already on the lockless default path and will get the bug fixes and new APIs without any code change.
+
+**Callers passing a custom `lock`** (typically React Native `processLock`, Node multi-process setups with shared AsyncStorage, or a custom lock implementation):
+
+- v2.x (this release): your custom `lock` is still invoked exactly as before. The legacy `_acquireLock` machinery is preserved on an opt-in path gated by `settings.lock != null`. No code change required.
+- v3.0.0 (planned): the `lock` and `lockAcquireTimeout` options will be removed entirely. Drop them from your client options before upgrading to v3.
+
+## New APIs worth knowing
+
+### `client.auth.dispose()`
+
+Tears down the client's background work in one call. Safe to call repeatedly.
+
+```ts
+useEffect(() => {
+  const supabase = createClient(URL, KEY)
+  return () => {
+    supabase.auth.dispose()
+  }
+}, [])
+```
+
+### `AuthRefreshDiscardedError`
+
+Returned from `refreshSession()` / `getSession()` when the commit guard discards a successfully-rotated session.
+
+```ts
+import { isAuthRefreshDiscardedError } from '@supabase/auth-js'
+
+const { data, error } = await supabase.auth.refreshSession()
+if (isAuthRefreshDiscardedError(error)) {
+  // A concurrent signOut cleared storage between fetch start and now.
+  // The rotated tokens were discarded; the SIGNED_OUT event already fired.
+  // Treat as a successful no-op — no need to retry.
+}
+```
+
+## Behavior changes worth flagging
+
+- **`_autoRefreshTokenTick` may run concurrently with `signOut` / `setSession` / `getUser`** on the lockless default path. Previously the tick used `_acquireLock(0, ...)` which skipped 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.
+- **`onAuthStateChange` async callbacks** that call `getUser`, `setSession`, or read the session from inside the callback are now safe on the default path (previously deadlocked through the lock). One residual hazard remains: calling `refreshSession` (or anything routing through `_callRefreshToken`) from inside a `TOKEN_REFRESHED` handler still deadlocks via `refreshingDeferred`. The `@deprecated` marker on the async overload is kept with its reason updated to point at this specific case.
+- **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.
+
+## Migration steps
+
+### If you do not pass a custom `lock` (most users)
+
+No action required for v2. No action required for v3.
+
+### If you pass a custom `lock` (e.g., React Native `processLock`)
+
+No action required for v2 — your lock continues to work.
+
+For v3 readiness:
+
+1. Remove `lock` and `lockAcquireTimeout` from your `createClient` / `GoTrueClient` options before upgrading to v3.
+2. If you depended on cross-process serialization (e.g., Node multi-process with shared AsyncStorage), validate that the lockless coordination (in-tab single-flight + server parent-of-active) is sufficient for your runtime. The default is safe for the cases the lock was originally added to handle (cross-tab refresh races), since the server resolves them.
+
+```ts
+// Before (v2.x, still works):
+const supabase = createClient(URL, KEY, {
+  auth: { lock: processLock, lockAcquireTimeout: 5000 },
+})
+
+// After (v3-ready):
+const supabase = createClient(URL, KEY)
+```
+
+## Reference
+
+- Server-side parent-of-active mechanism: `internal/tokens/service.go:376-385` in the [supabase/auth](https://github.com/supabase/auth) repo (v1 branch, the `*models.RefreshToken` type assertion). 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 — both tabs receive the same rotated token under DB row locking.
+- `lib/locks.ts` exports (`navigatorLock`, `processLock`, `LockAcquireTimeoutError`, `NavigatorLockAcquireTimeoutError`, `ProcessLockAcquireTimeoutError`, `internals`) remain available for direct imports, marked `@deprecated`. Direct callers who use these exports outside the `GoTrueClient` constructor option are unaffected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/auth-js",
-  "version": "2.107.0-canary.0",
+  "version": "2.107.0-canary.2",
   "private": false,
   "description": "Official SDK for Supabase Auth",
   "keywords": [

package/src/GoTrueAdminApi.ts

@@ -65,14 +65,6 @@ export default class GoTrueAdminApi {
   protected headers: {
     [key: string]: string
   }
-
-  private _encodePathSegment(segment: string): string {
-    if (segment === '.' || segment === '..') {
-      throw new AuthError('Invalid path segment')
-    }
-
-    return encodeURIComponent(segment)
-  }
   protected fetch: Fetch
   protected experimental: ExperimentalFeatureFlags
 
@@ -990,18 +982,12 @@ export default class GoTrueAdminApi {
    */
   private async _getOAuthClient(clientId: string): Promise<OAuthClientResponse> {
     try {
-      const encodedClientId = this._encodePathSegment(clientId)
-      return await _request(
-        this.fetch,
-        'GET',
-        `${this.url}/admin/oauth/clients/${encodedClientId}`,
-        {
-          headers: this.headers,
-          xform: (client: any) => {
-            return { data: client, error: null }
-          },
-        }
-      )
+      return await _request(this.fetch, 'GET', `${this.url}/admin/oauth/clients/${clientId}`, {
+        headers: this.headers,
+        xform: (client: any) => {
+          return { data: client, error: null }
+        },
+      })
     } catch (error) {
       if (isAuthError(error)) {
         return { data: null, error }
@@ -1022,19 +1008,13 @@ export default class GoTrueAdminApi {
     params: UpdateOAuthClientParams
   ): Promise<OAuthClientResponse> {
     try {
-      const encodedClientId = this._encodePathSegment(clientId)
-      return await _request(
-        this.fetch,
-        'PUT',
-        `${this.url}/admin/oauth/clients/${encodedClientId}`,
-        {
-          body: params,
-          headers: this.headers,
-          xform: (client: any) => {
-            return { data: client, error: null }
-          },
-        }
-      )
+      return await _request(this.fetch, 'PUT', `${this.url}/admin/oauth/clients/${clientId}`, {
+        body: params,
+        headers: this.headers,
+        xform: (client: any) => {
+          return { data: client, error: null }
+        },
+      })
     } catch (error) {
       if (isAuthError(error)) {
         return { data: null, error }
@@ -1054,8 +1034,7 @@ export default class GoTrueAdminApi {
     clientId: string
   ): Promise<{ data: null; error: AuthError | null }> {
     try {
-      const encodedClientId = this._encodePathSegment(clientId)
-      await _request(this.fetch, 'DELETE', `${this.url}/admin/oauth/clients/${encodedClientId}`, {
+      await _request(this.fetch, 'DELETE', `${this.url}/admin/oauth/clients/${clientId}`, {
         headers: this.headers,
         noResolveJson: true,
       })
@@ -1077,11 +1056,10 @@ export default class GoTrueAdminApi {
    */
   private async _regenerateOAuthClientSecret(clientId: string): Promise<OAuthClientResponse> {
     try {
-      const encodedClientId = this._encodePathSegment(clientId)
       return await _request(
         this.fetch,
         'POST',
-        `${this.url}/admin/oauth/clients/${encodedClientId}/regenerate_secret`,
+        `${this.url}/admin/oauth/clients/${clientId}/regenerate_secret`,
         {
           headers: this.headers,
           xform: (client: any) => {
@@ -1163,18 +1141,12 @@ export default class GoTrueAdminApi {
    */
   private async _getCustomProvider(identifier: string): Promise<CustomProviderResponse> {
     try {
-      const encodedIdentifier = this._encodePathSegment(identifier)
-      return await _request(
-        this.fetch,
-        'GET',
-        `${this.url}/admin/custom-providers/${encodedIdentifier}`,
-        {
-          headers: this.headers,
-          xform: (provider: any) => {
-            return { data: provider, error: null }
-          },
-        }
-      )
+      return await _request(this.fetch, 'GET', `${this.url}/admin/custom-providers/${identifier}`, {
+        headers: this.headers,
+        xform: (provider: any) => {
+          return { data: provider, error: null }
+        },
+      })
     } catch (error) {
       if (isAuthError(error)) {
         return { data: null, error }
@@ -1198,19 +1170,13 @@ export default class GoTrueAdminApi {
     params: UpdateCustomProviderParams
   ): Promise<CustomProviderResponse> {
     try {
-      const encodedIdentifier = this._encodePathSegment(identifier)
-      return await _request(
-        this.fetch,
-        'PUT',
-        `${this.url}/admin/custom-providers/${encodedIdentifier}`,
-        {
-          body: params,
-          headers: this.headers,
-          xform: (provider: any) => {
-            return { data: provider, error: null }
-          },
-        }
-      )
+      return await _request(this.fetch, 'PUT', `${this.url}/admin/custom-providers/${identifier}`, {
+        body: params,
+        headers: this.headers,
+        xform: (provider: any) => {
+          return { data: provider, error: null }
+        },
+      })
     } catch (error) {
       if (isAuthError(error)) {
         return { data: null, error }
@@ -1228,16 +1194,10 @@ export default class GoTrueAdminApi {
     identifier: string
   ): Promise<{ data: null; error: AuthError | null }> {
     try {
-      const encodedIdentifier = this._encodePathSegment(identifier)
-      await _request(
-        this.fetch,
-        'DELETE',
-        `${this.url}/admin/custom-providers/${encodedIdentifier}`,
-        {
-          headers: this.headers,
-          noResolveJson: true,
-        }
-      )
+      await _request(this.fetch, 'DELETE', `${this.url}/admin/custom-providers/${identifier}`, {
+        headers: this.headers,
+        noResolveJson: true,
+      })
       return { data: null, error: null }
     } catch (error) {
       if (isAuthError(error)) {