@supabase/gotrue-js 2.119.0-canary.2 → 2.119.0-canary.4

package/migrations/sign-out-global-keeps-session.md

@@ -0,0 +1,41 @@
+# `signOut` keeps the session when the server logout fails
+
+**Since:** the first release after v2.118.0
+**Action required by:** none in v2.x. See [Planned for v3](#planned-for-v3).
+
+`signOut({ scope: 'global' })` and `signOut({ scope: 'others' })` now report a server or network failure without touching the session they were asked to revoke. `signOut({ scope: 'local' })` always signs out this device.
+
+## What changed
+
+- **`global` (the default scope):** the local session is cleared, and `SIGNED_OUT` fires, only after the server accepts the logout. If the request fails, for example because the device is offline, the local session is kept, no `SIGNED_OUT` event fires and the error is returned.
+- **`local`:** the local session is removed and `SIGNED_OUT` fires before the request to revoke the refresh token is sent, so signing out of this device never depends on the network. The request's error, if any, is still returned.
+- **`others`:** the local session is never changed. A failed request returns the error.
+
+Previously, a failed `global` sign out still cleared the local session. The refresh token then stayed valid on the server and the client no longer had the credentials to retry the revoke.
+
+## Who is affected
+
+**Callers that use the default scope** (`signOut()` or `signOut({ scope: 'global' })`) and assume it always ends the local session. If the device is offline or the auth server returns an error, `signOut()` now returns `{ error }` and the user stays signed in.
+
+To always sign out this device, either use the `local` scope, or retry with it when `global` fails:
+
+```ts
+const { error } = await supabase.auth.signOut()
+if (error) {
+  // The server could not revoke the sessions and the user is still signed in locally.
+  // Sign out this device regardless:
+  await supabase.auth.signOut({ scope: 'local' })
+}
+```
+
+If you only want to sign out the current tab or device, pass `{ scope: 'local' }` directly. This is usually what a "Sign out" button wants.
+
+## Responses that still count as a successful sign out
+
+A `401`, `403` or `404` response from the auth server is treated as "already signed out": the local session is cleared and `error` is `null`. Auth servers from v2.145.0 answer `403` with `user_not_found` (and from v2.150.0 `session_not_found`) when the user or session no longer exists, and servers before v2.145.0 answered `401` or `404`.
+
+The status is also `403` for `bad_jwt` and `user_banned`, where nothing was revoked, so these are treated as a successful sign out too. This is known, and changing it would be a breaking change.
+
+## Planned for v3
+
+v3 is expected to match on the error code instead of the status: only `session_not_found` and `user_not_found` will count as already signed out, and every other error will be returned with the session kept. Callers that handle the `error` from `signOut()` as shown above need no change.

package/package.json

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

package/src/GoTrueClient.ts

@@ -1107,7 +1107,7 @@ export default class GoTrueClient {
    * Be aware that you may get back an error message that will not distinguish
    * between the cases where the account does not exist or that the
    * email/phone and password combination is wrong or that the account can only
-   * be accessed via social login.
+   * be accessed via social sign-in.
    *
    * @category Auth
    *
@@ -1300,7 +1300,7 @@ export default class GoTrueClient {
    * @category Auth
    *
    * @remarks
-   * - This method is used for signing in using [Social Login (OAuth) providers](/docs/guides/auth#configure-third-party-providers).
+   * - This method is used for signing in using [social sign-in (OAuth) providers](/docs/guides/auth/social-sign-in).
    * - It works by redirecting your application to the provider's authorization screen, before bringing back the user to your app.
    *
    * @example Sign in using a third-party provider
@@ -2219,7 +2219,7 @@ export default class GoTrueClient {
    *
    * Be aware that you may get back an error message that will not distinguish
    * between the cases where the account does not exist or, that the account
-   * can only be accessed via social login.
+   * can only be accessed via social sign-in.
    *
    * Do note that you will need to configure a Whatsapp sender on Twilio
    * if you are using phone sign in with the 'whatsapp' channel. The whatsapp
@@ -4026,12 +4026,31 @@ export default class GoTrueClient {
   }
 
   /**
-   * Inside a browser context, `signOut()` will remove the logged in user from the browser session and log them out - removing all items from localstorage and then trigger a `"SIGNED_OUT"` event.
+   * Inside a browser context, `signOut()` will remove the logged in user from the browser session
+   * and log them out - removing all items from localstorage and then trigger a `"SIGNED_OUT"`
+   * event.
    *
-   * For server-side management, you can revoke all refresh tokens for a user by passing a user's JWT through to `auth.api.signOut(JWT: string)`.
-   * There is no way to revoke a user's access token jwt until it expires. It is recommended to set a shorter expiry on the jwt for this reason.
+   * For server-side management, you can revoke all refresh tokens for a user by passing a user's
+   * JWT through to `auth.api.signOut(JWT: string)`.
    *
-   * If using `others` scope, no `SIGNED_OUT` event is fired!
+   * There is no way to revoke a user's access token jwt until it expires. It is recommended to set
+   * a shorter expiry on the jwt for this reason.
+   *
+   * `signOut` behavior depends on the selected scope:
+   *
+   * - `local`: The local session is removed first and a `SIGNED_OUT` event is fired, then the client
+   *   makes a best-effort request to revoke the refresh token on the server. If the request fails,
+   *   the client is still signed out locally and the error is returned, but the server may retain
+   *   the refresh token until it expires.
+   *
+   * - `global`: All of the user's sessions are first invalidated on the server. Once the server
+   *   acknowledges the request, the local session is cleared. If server logout fails, the local
+   *   session is retained, no `SIGNED_OUT` event is triggered, and the server or network error is
+   *   returned. A 401, 403, or 404 response counts as a successful sign-out.
+   *
+   * - `others`: All other sessions are invalidated when the server accepts the request; the
+   *   current local session remains unchanged. In case of server or network failures, the error is
+   *   returned. A `SIGNED_OUT` event is never triggered, regardless of the outcome.
    *
    * **Warning:** the default `scope` is `'global'`. This signs the user out of
    * **every device they are currently signed in on**, not just the current
@@ -4049,7 +4068,13 @@ export default class GoTrueClient {
    *   usually what apps want on a "Sign out" button, especially when users
    *   sign in from multiple devices and do not expect signing out of one to
    *   terminate the others.
-   * - Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.
+   * - With the default `global` scope, `signOut()` while offline returns an error and keeps the user
+   *   signed in. To sign out regardless, fall back to `signOut({ scope: 'local' })` when the call
+   *   returns an error.
+   * - Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until
+   *   it's expired. When the user signs out, Supabase revokes the refresh token and deletes the
+   *   JWT from the client-side. This does not revoke the JWT and it will still be valid until it
+   *   expires.
    *
    * @example Sign out of every device (global – default)
    * ```js
@@ -4079,41 +4104,78 @@ export default class GoTrueClient {
     return await this._signOut(options)
   }
 
-  protected async _signOut(
-    { scope }: SignOut = { scope: 'global' }
-  ): Promise<{ error: AuthError | null }> {
+  protected async _signOut({ scope = 'global' }: SignOut = {}): Promise<{
+    error: AuthError | null
+  }> {
     return await this._useSession(async (result) => {
       const removeCurrentSession = async () => {
         await this._removeSession()
       }
       const { data, error: sessionError } = result
       if (sessionError && !isAuthSessionMissingError(sessionError)) {
+        // A retryable refresh failure (offline, 5xx) leaves the session in storage and no access
+        // token to revoke with, so `local` still has to sign out this device. A rejected refresh
+        // has already removed the session and fired `SIGNED_OUT`.
+        if (scope === 'local' && isAuthRetryableFetchError(sessionError)) {
+          await removeCurrentSession()
+        }
         return this._returnResult({ error: sessionError })
       }
       const accessToken = data.session?.access_token
+      let removeError: { thrown: unknown } | null = null
+      const finish = <T>(value: T): T => {
+        if (removeError) {
+          throw removeError.thrown
+        }
+        return value
+      }
+      if (scope === 'local') {
+        // The local session is removed before the request is sent, so signing out of this device
+        // never depends on the network. The request only revokes the refresh token on the server.
+        // A throwing `SIGNED_OUT` subscriber must not skip that request, so its error is rethrown
+        // once the request has been attempted.
+        try {
+          await removeCurrentSession()
+        } catch (thrown) {
+          removeError = { thrown }
+        }
+      }
       if (accessToken) {
         const { error } = await this.admin.signOut(accessToken, scope)
-        if (error) {
-          // ignore 404s since user might not exist anymore
-          // ignore 401s since an invalid or expired JWT should sign out the current session
-          if (
-            !(
-              (isAuthApiError(error) &&
-                (error.status === 404 || error.status === 401 || error.status === 403)) ||
-              isAuthSessionMissingError(error)
-            )
-          ) {
-            if (scope !== 'others') {
-              await removeCurrentSession()
-            }
-            return this._returnResult({ error })
-          }
+        // The current behavior is wrong for the current version of auth (v2.197.0). However,
+        // changing it could be considered a breaking change and must wait for v3. Before modifying
+        // this code we also need to consider which range of Auth versions we aim to support. Right
+        // now this is not defined and thus undefined.
+        //
+        // Some constraints to be aware of:
+        // - Since supabase/auth v2.145.0 a missing user answers 403 `user_not_found`.
+        // - Since supabase/auth v2.150.0 a missing session answers 403 `session_not_found`.
+        // - Before v2.145.0 an invalid JWT answered 401.
+        // - Before v2.145.0 a missing user answers 404., so those statuses are treated the same way.
+        //
+        // TODO(v3): if we only support auth v2.150.0 or later, change this to:
+        //  - Match on `error.code` instead of `error.status`, and treat only 403 `session_not_found`
+        //    and `user_not_found` as already signed out. Drop the 401 and 404 handling.
+        //  - Return every other error, e.g. 403 `bad_jwt` or `user_banned`, or a 401 or 404 from a
+        //    gateway, instead of treating it as signed out. Today nothing was revoked, yet the
+        //    session is cleared and `error` is null. With `global` the session is then kept.
+        //  - For `others`, return `session_not_found` as well. It describes the current session, not
+        //    the sessions being revoked.
+        if (
+          error &&
+          !(
+            (isAuthApiError(error) &&
+              (error.status === 404 || error.status === 401 || error.status === 403)) ||
+            isAuthSessionMissingError(error)
+          )
+        ) {
+          return finish(this._returnResult({ error }))
         }
       }
-      if (scope !== 'others') {
+      if (scope === 'global') {
         await removeCurrentSession()
       }
-      return this._returnResult({ error: null })
+      return finish(this._returnResult({ error: null }))
     })
   }
 
@@ -4231,9 +4293,9 @@ export default class GoTrueClient {
    * ```
    *
    * @exampleDescription Store OAuth provider tokens on sign in
-   * When using [OAuth (Social Login)](/docs/guides/auth/social-login) you sometimes wish to get access to the provider's access token and refresh token, in order to call provider APIs in the name of the user.
+   * When using [OAuth (social sign-in)](/docs/guides/auth/social-sign-in) you sometimes wish to get access to the provider's access token and refresh token, in order to call provider APIs in the name of the user.
    *
-   * For example, if you are using [Sign in with Google](/docs/guides/auth/social-login/auth-google) you may want to use the provider token to call Google APIs on behalf of the user. Supabase Auth does not keep track of the provider access and refresh token, but does return them for you once, immediately after sign in. You can use the `onAuthStateChange` method to listen for the presence of the provider tokens and store them in local storage. You can further send them to your server's APIs for use on the backend.
+   * For example, if you are using [Sign in with Google](/docs/guides/auth/social-sign-in/auth-google) you may want to use the provider token to call Google APIs on behalf of the user. Supabase Auth does not keep track of the provider access and refresh token, but does return them for you once, immediately after sign in. You can use the `onAuthStateChange` method to listen for the presence of the provider tokens and store them in local storage. You can further send them to your server's APIs for use on the backend.
    *
    * Finally, make sure you remove them from local storage on the `SIGNED_OUT` event. If the OAuth provider supports token revocation, make sure you call those APIs either from the frontend or schedule them to be called on the backend.
    *

package/src/lib/types.ts

@@ -2032,7 +2032,7 @@ export interface GoTrueMFAApi {
    * Returns the Authenticator Assurance Level (AAL) for the active session.
    *
    * - `aal1` (or `null`) means that the user's identity has been verified only
-   * with a conventional login (email+password, OTP, magic link, social login,
+   * with a conventional login (email+password, OTP, magic link, social sign-in,
    * etc.).
    * - `aal2` means that the user's identity has been verified both with a conventional login and at least one MFA factor.
    *

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.119.0-canary.2'
+export const version = '2.119.0-canary.4'