@depup/supabase__auth-js 2.103.0-depup.0 → 2.110.8-depup.0

package/migrations/lockless-coordination.md

@@ -0,0 +1,155 @@
+# 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.
+
+## Timing & concurrency notes for downstream consumers
+
+Removing the default `_acquireLock(...)` wrapper changes the _microtask shape_ of `getSession`, `getUser`, `refreshSession`, `setSession`, `signOut`, `_initialize`, and `_reauthenticate`. Application behavior is unchanged — these methods still return the same values — but the await chain is shorter.
+
+### What changed in the await chain
+
+Previously, each of those methods looked like:
+
+```ts
+return await this._acquireLock(this.lockAcquireTimeout, async () => {
+  return await this._getUser()
+})
+```
+
+`_acquireLock` awaited `navigator.locks.request` (browser) or the in-process `processLock` (Node). That added a handful of microtasks before the inner operation ran. On the lockless default path, the wrapper is skipped and the inner operation runs directly:
+
+```ts
+if (this.lock) {
+  return await this._acquireLock(this.lockAcquireTimeout, async () => {
+    return await this._getUser()
+  })
+}
+return await this._getUser()
+```
+
+### Downstream impact via `fetchWithAuth`
+
+`supabase-js` wraps the user's `fetch` via `fetchWithAuth` (in `packages/core/supabase-js/src/SupabaseClient.ts`), which awaits `_getAccessToken()` before every PostgREST, Storage, and Functions request. With the shorter pre-fetch await chain, concurrent client calls — for example `Promise.all([supabase.rpc(...), supabase.rpc(...)])` or `Promise.all(rows.map((r) => supabase.from(...).insert(...)))` — may reach the network layer in a different micro-order than they did on v2.106 and earlier.
+
+### What this can surface as
+
+Tests that use order-sensitive mocks (nock, MSW, or any interceptor that matches requests in registration order) against parallel client calls may flip. A concrete example from the wild: a downstream worker repo registered two `nock(URL).post('/rest/v1/rpc/queue_job', body => expect(body).toMatchInlineSnapshot(...)).reply(200)` interceptors back-to-back, one expecting database `333`, the other expecting database `222`, and relied on the calls arriving in that order. The application code dispatched both via `Promise.all(replicas.map((r) => supabase.rpc('queue_job', ...)))`. On v2.107 the arrival order flipped, the first interceptor's body matcher ran against the wrong payload, vitest raised `toMatchInlineSnapshot with different snapshots cannot be called at the same location`, and the unmatched interceptor caused a "pending mocks left" failure at teardown.
+
+The application behavior was correct in both versions: both RPCs completed, both rows ended up in the queue. Only the _test_ depended on an ordering that was never guaranteed.
+
+### Recommended fix pattern
+
+Make mocks order-independent. Two common shapes:
+
+1. **Branch the body matcher on a discriminator field.** Register one interceptor with `.times(N)`; inside the body matcher, look at a field on the request body (e.g. an `id`) and assert against the expected payload for that id.
+
+   ```ts
+   const expected: Record<number, unknown> = {
+     222: {
+       /* expected body for replica 222 */
+     },
+     333: {
+       /* expected body for replica 333 */
+     },
+   }
+
+   nock(URL)
+     .post('/path', (body) => {
+       expect(body).toStrictEqual(expected[body.id])
+       return true
+     })
+     .times(2)
+     .reply(200)
+   ```
+
+2. **Capture and assert as a set.** Push each received body into an array from the matcher, return `true` to accept, then after the parallel block resolves assert the array's _contents_ (e.g. via `expect(received).toEqual(expect.arrayContaining([...]))`) without pinning order.
+
+Do not pin behavior to lock-induced delays. They were incidental, not a guarantee — and they may shift again in future patch releases as internal awaits are refactored.
+
+The custom-`lock` opt-in path retains the old await shape and is unaffected by this section.
+
+## 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": "@depup/supabase__auth-js",
-  "version": "2.103.0-depup.0",
+  "version": "2.110.8-depup.0",
   "description": "Official SDK for Supabase Auth (with updated dependencies)",
   "keywords": [
     "@supabase/auth-js",
@@ -20,6 +20,8 @@
   "files": [
     "dist",
     "src",
+    "migrations",
+    "AGENTS.md",
     "changes.json",
     "README.md"
   ],
@@ -31,28 +33,39 @@
     "url": "https://github.com/supabase/supabase-js.git",
     "directory": "packages/core/auth-js"
   },
-  "scripts": {
-    "build": "npm run build:main && npm run build:module",
-    "build:main": "tsc -p tsconfig.json",
-    "build:module": "tsc -p tsconfig.module.json",
-    "docs": "typedoc src/index.ts --out docs/v2 --excludePrivate --excludeProtected",
-    "docs:json": "typedoc --json docs/v2/spec.json --excludeExternals --excludePrivate --excludeProtected src/index.ts"
-  },
   "dependencies": {
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "prettier": "^2.8.8"
+    "@faker-js/faker": "^9.9.0",
+    "@types/jest": "30.0.0",
+    "@types/jsonwebtoken": "^8.5.8",
+    "@types/node": "20.19.9",
+    "jest": "30.4.2",
+    "jest-environment-jsdom": "30.4.1",
+    "jest-mock-server": "^0.1.0",
+    "jsonwebtoken": "^9.0.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.9",
+    "typedoc": "^0.27.9",
+    "typescript": "~5.8.3"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:main && npm run build:module",
+    "build:main": "tsc -p tsconfig.json",
+    "build:module": "tsc -p tsconfig.module.json",
+    "docs": "typedoc --options ../../../typedoc.base.mjs src/index.ts --out docs/v2 --excludePrivate --excludeProtected",
+    "docs:json": "typedoc --options ../../../typedoc.base.mjs --json docs/v2/spec.json --excludeExternals --excludePrivate --excludeProtected src/index.ts"
   },
   "depup": {
     "changes": {},
     "depsUpdated": 0,
     "originalPackage": "@supabase/auth-js",
-    "originalVersion": "2.103.0",
-    "processedAt": "2026-04-09T08:38:01.080Z",
+    "originalVersion": "2.110.8",
+    "processedAt": "2026-07-21T16:08:53.860Z",
     "smokeTest": "passed"
   }
 }

package/src/GoTrueAdminApi.ts

@@ -5,7 +5,7 @@ import {
   _request,
   _userResponse,
 } from './lib/fetch'
-import { resolveFetch, validateUUID } from './lib/helpers'
+import { assertPasskeyExperimentalEnabled, resolveFetch, validateUUID } from './lib/helpers'
 import {
   AdminUserAttributes,
   GenerateLinkParams,
@@ -32,6 +32,12 @@ import {
   ListCustomProvidersParams,
   CustomProviderResponse,
   CustomProviderListResponse,
+  GoTrueAdminPasskeyApi,
+  AuthPasskeyAdminListParams,
+  AuthPasskeyAdminDeleteParams,
+  AuthPasskeyListResponse,
+  AuthPasskeyDeleteResponse,
+  ExperimentalFeatureFlags,
 } from './lib/types'
 import { AuthError, isAuthError } from './lib/errors'
 
@@ -48,22 +54,38 @@ export default class GoTrueAdminApi {
   /** Contains all custom OIDC/OAuth provider administration methods. */
   customProviders: GoTrueAdminCustomProvidersApi
 
+  /**
+   * Contains all passkey administration methods.
+   *
+   * Requires `auth.experimental.passkey: true`; otherwise all methods throw.
+   */
+  passkey: GoTrueAdminPasskeyApi
+
   protected url: string
   protected headers: {
     [key: string]: string
   }
   protected fetch: Fetch
+  protected experimental: ExperimentalFeatureFlags
 
   /**
    * Creates an admin API client that can be used to manage users and OAuth clients.
    *
-   * @example
+   * @example Using supabase-js (recommended)
+   * ```ts
+   * import { createClient } from '@supabase/supabase-js'
+   *
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-secret-key')
+   * const { data, error } = await supabase.auth.admin.listUsers()
+   * ```
+   *
+   * @example Standalone import for bundle-sensitive environments
    * ```ts
    * import { GoTrueAdminApi } from '@supabase/auth-js'
    *
    * const admin = new GoTrueAdminApi({
    *   url: 'https://xyzcompany.supabase.co/auth/v1',
-   *   headers: { Authorization: `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}` },
+   *   headers: { Authorization: `Bearer ${process.env.SUPABASE_SECRET_KEY}` },
    * })
    * ```
    */
@@ -71,16 +93,19 @@ export default class GoTrueAdminApi {
     url = '',
     headers = {},
     fetch,
+    experimental,
   }: {
     url: string
     headers?: {
       [key: string]: string
     }
     fetch?: Fetch
+    experimental?: ExperimentalFeatureFlags
   }) {
     this.url = url
     this.headers = headers
     this.fetch = resolveFetch(fetch)
+    this.experimental = experimental ?? {}
     this.mfa = {
       listFactors: this._listFactors.bind(this),
       deleteFactor: this._deleteFactor.bind(this),
@@ -100,6 +125,10 @@ export default class GoTrueAdminApi {
       updateProvider: this._updateCustomProvider.bind(this),
       deleteProvider: this._deleteCustomProvider.bind(this),
     }
+    this.passkey = {
+      listPasskeys: this._adminListPasskeys.bind(this),
+      deletePasskey: this._adminDeletePasskey.bind(this),
+    }
   }
 
   /**
@@ -108,6 +137,7 @@ export default class GoTrueAdminApi {
    * @param scope The logout sope.
    *
    * @category Auth
+   * @subcategory Auth Admin
    */
   async signOut(
     jwt: string,
@@ -141,6 +171,7 @@ export default class GoTrueAdminApi {
    * @param options Additional options to be included when inviting.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - Sends an invite link to the user's email address.
@@ -226,12 +257,10 @@ export default class GoTrueAdminApi {
 
   /**
    * Generates email links and OTPs to be sent via a custom email provider.
-   * @param email The user's email.
-   * @param options.password User password. For signup only.
-   * @param options.data Optional user metadata. For signup only.
-   * @param options.redirectTo The redirect url which should be appended to the generated link
+   * @param params The parameters for generating the link, including the link `type`, the user's `email`, and type-specific options such as `password`, `data`, and `redirectTo`.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - The following types can be passed into `generateLink()`: `signup`, `magiclink`, `invite`, `recovery`, `email_change_current`, `email_change_new`, `phone_change`.
@@ -375,6 +404,7 @@ export default class GoTrueAdminApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false.
@@ -472,6 +502,7 @@ export default class GoTrueAdminApi {
    * @param params An object which supports `page` and `perPage` as numbers, to alter the paginated results.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - Defaults to return 50 users per page.
@@ -537,6 +568,7 @@ export default class GoTrueAdminApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - Fetches the user object from the database based on the user's id.
@@ -640,6 +672,7 @@ export default class GoTrueAdminApi {
    * @see {@link GoTrueClient.updateUser} for client-side user updates (triggers listeners automatically)
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @example Updates a user's email
    * ```js
@@ -778,6 +811,7 @@ export default class GoTrueAdminApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @remarks
    * - The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column.
@@ -1169,4 +1203,62 @@ export default class GoTrueAdminApi {
       throw error
     }
   }
+
+  /**
+   * Lists all passkeys for a user.
+   *
+   * This function should only be called on a server. Never expose your secret key in the browser.
+   *
+   * Requires `auth.experimental.passkey: true`.
+   */
+  private async _adminListPasskeys(
+    params: AuthPasskeyAdminListParams
+  ): Promise<AuthPasskeyListResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    validateUUID(params.userId)
+
+    try {
+      return await _request(
+        this.fetch,
+        'GET',
+        `${this.url}/admin/users/${params.userId}/passkeys`,
+        { headers: this.headers, xform: (data: any) => ({ data, error: null }) }
+      )
+    } catch (error) {
+      if (isAuthError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Deletes a user's passkey.
+   *
+   * This function should only be called on a server. Never expose your secret key in the browser.
+   *
+   * Requires `auth.experimental.passkey: true`.
+   */
+  private async _adminDeletePasskey(
+    params: AuthPasskeyAdminDeleteParams
+  ): Promise<AuthPasskeyDeleteResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    validateUUID(params.userId)
+    validateUUID(params.passkeyId)
+
+    try {
+      await _request(
+        this.fetch,
+        'DELETE',
+        `${this.url}/admin/users/${params.userId}/passkeys/${params.passkeyId}`,
+        { headers: this.headers, noResolveJson: true }
+      )
+      return { data: null, error: null }
+    } catch (error) {
+      if (isAuthError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
 }