@supabase/gotrue-js 2.0.1 → 2.1.0

package/src/GoTrueClient.ts

@@ -17,7 +17,6 @@ import {
 } from './lib/errors'
 import { Fetch, _request, _sessionResponse, _userResponse } from './lib/fetch'
 import {
-  decodeBase64URL,
   Deferred,
   getItemAsync,
   getParameterByName,
@@ -26,6 +25,7 @@ import {
   resolveFetch,
   setItemAsync,
   uuid,
+  decodeJWTPayload,
 } from './lib/helpers'
 import localStorageAdapter from './lib/local-storage'
 import { polyfillGlobalThis } from './lib/polyfills'
@@ -48,6 +48,20 @@ import type {
   UserAttributes,
   UserResponse,
   VerifyOtpParams,
+  GoTrueMFAApi,
+  MFAEnrollParams,
+  AuthMFAEnrollResponse,
+  MFAChallengeParams,
+  AuthMFAChallengeResponse,
+  MFAUnenrollParams,
+  AuthMFAUnenrollResponse,
+  MFAVerifyParams,
+  AuthMFAVerifyResponse,
+  AuthMFAListFactorsResponse,
+  AMREntry,
+  AuthMFAGetAuthenticatorAssuranceLevelResponse,
+  AuthenticatorAssuranceLevels,
+  Factor,
 } from './lib/types'
 
 polyfillGlobalThis() // Make "globalThis" available
@@ -67,6 +81,10 @@ export default class GoTrueClient {
    * These methods should only be used in a trusted server-side environment.
    */
   admin: GoTrueAdminApi
+  /**
+   * Namespace for the MFA methods.
+   */
+  mfa: GoTrueMFAApi
   /**
    * The storage key used to identify the values saved in localStorage
    */
@@ -121,6 +139,14 @@ export default class GoTrueClient {
     this.detectSessionInUrl = settings.detectSessionInUrl
 
     this.initialize()
+    this.mfa = {
+      verify: this._verify.bind(this),
+      enroll: this._enroll.bind(this),
+      unenroll: this._unenroll.bind(this),
+      challenge: this._challenge.bind(this),
+      listFactors: this._listFactors.bind(this),
+      getAuthenticatorAssuranceLevel: this._getAuthenticatorAssuranceLevel.bind(this),
+    }
   }
 
   /**
@@ -530,6 +556,17 @@ export default class GoTrueClient {
     }
   }
 
+  /**
+   * Decodes a JWT (without performing any validation).
+   */
+  private _decodeJWT(jwt: string): {
+    exp?: number
+    aal?: AuthenticatorAssuranceLevels | null
+    amr?: AMREntry[] | null
+  } {
+    return decodeJWTPayload(jwt)
+  }
+
   /**
    * Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session.
    * If the refresh token in the current session is invalid and the current session has expired, an error will be thrown.
@@ -545,7 +582,8 @@ export default class GoTrueClient {
       let hasExpired = true
       let session: Session | null = null
       if (currentSession.access_token && currentSession.access_token.split('.')[1]) {
-        const payload = JSON.parse(decodeBase64URL(currentSession.access_token.split('.')[1]))
+        const payload = this._decodeJWT(currentSession.access_token)
+
         if (payload.exp) {
           expiresAt = payload.exp
           hasExpired = expiresAt <= timeNow
@@ -1005,4 +1043,162 @@ export default class GoTrueClient {
     }
     return `${this.url}/authorize?${urlParams.join('&')}`
   }
+
+  private async _unenroll(params: MFAUnenrollParams): Promise<AuthMFAUnenrollResponse> {
+    const { data: sessionData, error: sessionError } = await this.getSession()
+    if (sessionError) {
+      return { data: null, error: sessionError }
+    }
+
+    return await _request(this.fetch, 'DELETE', `${this.url}/factors/${params.factorId}`, {
+      headers: this.headers,
+      jwt: sessionData?.session?.access_token,
+    })
+  }
+
+  /**
+   * Deletes a registered factor from GoTrue
+   * @param friendlyName Human readable name assigned to a device
+   * @param factorType device which we're validating against. Can only be TOTP for now.
+   * @param issuer domain which the user is enrolling with
+   */
+  private async _enroll(params: MFAEnrollParams): Promise<AuthMFAEnrollResponse> {
+    const { data: sessionData, error: sessionError } = await this.getSession()
+    if (sessionError) {
+      return { data: null, error: sessionError }
+    }
+
+    const { data, error } = await _request(this.fetch, 'POST', `${this.url}/factors`, {
+      body: {
+        friendly_name: params.friendlyName,
+        factor_type: params.factorType,
+        issuer: params.issuer,
+      },
+      headers: this.headers,
+      jwt: sessionData?.session?.access_token,
+    })
+
+    if (error) {
+      return { data: null, error }
+    }
+
+    if (data?.totp?.qr_code) {
+      data.totp.qr_code = `data:image/svg+xml;utf-8,${data.totp.qr_code}`
+    }
+
+    return { data, error: null }
+  }
+
+  /**
+   * Validates a device as part of the enrollment step.
+   * @param factorID System assigned identifier for authenticator device as returned by enroll
+   * @param code Code Generated by an authenticator device
+   */
+  private async _verify(params: MFAVerifyParams): Promise<AuthMFAVerifyResponse> {
+    const { data: sessionData, error: sessionError } = await this.getSession()
+    if (sessionError) {
+      return { data: null, error: sessionError }
+    }
+
+    const { data, error } = await _request(
+      this.fetch,
+      'POST',
+      `${this.url}/factors/${params.factorId}/verify`,
+      {
+        body: { code: params.code, challenge_id: params.challengeId },
+        headers: this.headers,
+        jwt: sessionData?.session?.access_token,
+      }
+    )
+    if (error) {
+      return { data: null, error }
+    }
+
+    await this._saveSession({
+      expires_at: Math.round(Date.now() / 1000) + data.expires_in,
+      ...data,
+    })
+    this._notifyAllSubscribers('MFA_CHALLENGE_VERIFIED', data)
+
+    return { data, error }
+  }
+
+  /**
+   * Creates a challenge which a user can verify against
+   * @param factorID System assigned identifier for authenticator device as returned by enroll
+   */
+  private async _challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse> {
+    const { data: sessionData, error: sessionError } = await this.getSession()
+    if (sessionError) {
+      return { data: null, error: sessionError }
+    }
+
+    return await _request(this.fetch, 'POST', `${this.url}/factors/${params.factorId}/challenge`, {
+      headers: this.headers,
+      jwt: sessionData?.session?.access_token,
+    })
+  }
+
+  /**
+   * Displays all devices for a given user
+   */
+  private async _listFactors(): Promise<AuthMFAListFactorsResponse> {
+    const {
+      data: { user },
+      error: userError,
+    } = await this.getUser()
+    if (userError) {
+      return { data: null, error: userError }
+    }
+
+    const factors = user?.factors || []
+    const totp = factors.filter(
+      (factor) => factor.factor_type === 'totp' && factor.status === 'verified'
+    )
+
+    return {
+      data: {
+        all: factors,
+        totp,
+      },
+      error: null,
+    }
+  }
+
+  private async _getAuthenticatorAssuranceLevel(): Promise<AuthMFAGetAuthenticatorAssuranceLevelResponse> {
+    const {
+      data: { session },
+      error: sessionError,
+    } = await this.getSession()
+    if (sessionError) {
+      return { data: null, error: sessionError }
+    }
+    if (!session) {
+      return {
+        data: { currentLevel: null, nextLevel: null, currentAuthenticationMethods: [] },
+        error: null,
+      }
+    }
+
+    const payload = this._decodeJWT(session.access_token)
+
+    let currentLevel: AuthenticatorAssuranceLevels | null = null
+
+    if (payload.aal) {
+      currentLevel = payload.aal
+    }
+
+    let nextLevel: AuthenticatorAssuranceLevels | null = currentLevel
+
+    const verifiedFactors =
+      session.user.factors?.filter((factor: Factor) => factor.status === 'verified') ?? []
+
+    if (verifiedFactors.length > 0) {
+      nextLevel = 'aal2'
+    }
+
+    const currentAuthenticationMethods = payload.amr || []
+
+    return { data: { currentLevel, nextLevel, currentAuthenticationMethods }, error: null }
+  }
 }

package/src/index.ts

@@ -1,6 +1,5 @@
 import GoTrueAdminApi from './GoTrueAdminApi'
 import GoTrueClient from './GoTrueClient'
-
 export { GoTrueAdminApi, GoTrueClient }
 export * from './lib/types'
 export * from './lib/errors'

package/src/lib/helpers.ts

@@ -120,3 +120,14 @@ export class Deferred<T = any> {
     })
   }
 }
+// Taken from: https://stackoverflow.com/questions/38552003/how-to-decode-jwt-token-in-javascript-without-using-a-library
+export function decodeJWTPayload(token: string) {
+  const parts = token.split('.')
+
+  if (parts.length !== 3) {
+    throw new Error('JWT is not valid: not a JWT structure')
+  }
+
+  const base64Url = parts[1]
+  return JSON.parse(decodeBase64URL(base64Url))
+}

package/src/lib/types.ts

@@ -20,6 +20,11 @@ export type Provider =
   | 'twitter'
   | 'workos'
 
+/**
+ * @experimental
+ */
+export type AuthChangeEventMFA = 'MFA_CHALLENGE_VERIFIED'
+
 export type AuthChangeEvent =
   | 'PASSWORD_RECOVERY'
   | 'SIGNED_IN'
@@ -27,6 +32,7 @@ export type AuthChangeEvent =
   | 'TOKEN_REFRESHED'
   | 'USER_UPDATED'
   | 'USER_DELETED'
+  | AuthChangeEventMFA
 
 export type GoTrueClientOptions = {
   /* The URL of the GoTrue server. */
@@ -123,6 +129,25 @@ export interface Session {
   user: User
 }
 
+/**
+ * An authentication methord reference (AMR) entry.
+ *
+ * An entry designates what method was used by the user to verify their
+ * identity and at what time.
+ *
+ * @see {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}.
+ */
+export interface AMREntry {
+  /** Authentication method name. */
+  method: 'password' | 'otp' | 'oauth' | 'mfa/totp' | string
+
+  /**
+   * Timestamp when the method was successfully used. Represents number of
+   * seconds since 1st January 1970 (UNIX epoch) in UTC.
+   */
+  timestamp: number
+}
+
 export interface UserIdentity {
   id: string
   user_id: string
@@ -135,6 +160,33 @@ export interface UserIdentity {
   updated_at?: string
 }
 
+/**
+ * A MFA factor.
+ *
+ * @see {@link GoTrueMFAApi#enroll}
+ * @see {@link GoTrueMFAApi#listFactors}
+ * @see {@link GoTrueMFAAdminApi#listFactors}
+ */
+export interface Factor {
+  /** ID of the factor. */
+  id: string
+
+  /** Friendly name of the factor, useful to disambiguate between multiple factors. */
+  friendly_name?: string
+
+  /**
+   * Type of factor. Only `totp` supported with this version but may change in
+   * future versions.
+   */
+  factor_type: 'totp' | string
+
+  /** Factor's status. */
+  status: 'verified' | 'unverified'
+
+  created_at: string
+  updated_at: string
+}
+
 export interface UserAppMetadata {
   provider?: string
   [key: string]: any
@@ -165,6 +217,7 @@ export interface User {
   role?: string
   updated_at?: string
   identities?: UserIdentity[]
+  factors?: Factor[]
 }
 
 export interface UserAttributes {
@@ -258,6 +311,10 @@ export interface Subscription {
   unsubscribe: () => void
 }
 
+export interface UpdatableFactorAttributes {
+  friendlyName: string
+}
+
 export type SignUpWithPasswordCredentials =
   | {
       /** The user's email address. */
@@ -492,6 +549,342 @@ export type GenerateLinkType =
   | 'email_change_current'
   | 'email_change_new'
 
+/**
+ * @experimental
+ */
+export type MFAEnrollParams = {
+  factorType: 'totp'
+  issuer?: string
+  friendlyName?: string
+}
+
+/**
+ * @experimental
+ */
+export type MFAUnenrollParams = {
+  /** ID of the factor being unenrolled. */
+  factorId: string
+}
+
+/**
+ * @experimental
+ */
+export type MFAVerifyParams = {
+  /** ID of the factor being verified. */
+  factorId: string
+
+  /** ID of the challenge being verified. */
+  challengeId: string
+
+  /** Verification code provided by the user. */
+  code: string
+}
+
+/**
+ * @experimental
+ */
+export type MFAChallengeParams = {
+  /** ID of the factor to be challenged. */
+  factorId: string
+}
+
+/**
+ * @experimental
+ */
+export type AuthMFAVerifyResponse =
+  | {
+      data: {
+        /** New access token (JWT) after successful verification. */
+        access_token: string
+
+        /** Type of token, typically `Bearer`. */
+        token_type: string
+
+        /** Number of seconds in which the access token will expire. */
+        expires_in: number
+
+        /** Refresh token you can use to obtain new access tokens when expired. */
+        refresh_token: string
+
+        /** Updated user profile. */
+        user: User
+      }
+      error: null
+    }
+  | {
+      data: null
+      error: AuthError
+    }
+
+/**
+ * @experimental
+ */
+export type AuthMFAEnrollResponse =
+  | {
+      data: {
+        /** ID of the factor that was just enrolled (in an unverified state). */
+        id: string
+
+        /** Type of MFA factor. Only `totp` supported for now. */
+        type: 'totp'
+
+        /** TOTP enrollment information. */
+        totp: {
+          /** Contains a QR code encoding the authenticator URI. You can
+           * convert it to a URL by prepending `data:image/svg+xml;utf-8,` to
+           * the value. Avoid logging this value to the console. */
+          qr_code: string
+
+          /** The TOTP secret (also encoded in the QR code). Show this secret
+           * in a password-style field to the user, in case they are unable to
+           * scan the QR code. Avoid logging this value to the console. */
+          secret: string
+
+          /** The authenticator URI encoded within the QR code, should you need
+           * to use it. Avoid loggin this value to the console. */
+          uri: string
+        }
+      }
+      error: null
+    }
+  | {
+      data: null
+      error: AuthError
+    }
+
+/**
+ * @experimental
+ */
+export type AuthMFAUnenrollResponse =
+  | {
+      data: {
+        /** ID of the factor that was successfully unenrolled. */
+        id: string
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * @experimental
+ */
+export type AuthMFAChallengeResponse =
+  | {
+      data: {
+        /** ID of the newly created challenge. */
+        id: string
+
+        /** Timestamp in UNIX seconds when this challenge will no longer be usable. */
+        expires_at: number
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * @experimental
+ */
+export type AuthMFAListFactorsResponse =
+  | {
+      data: {
+        /** All available factors (verified and unverified). */
+        all: Factor[]
+
+        /** Only verified TOTP factors. (A subset of `all`.) */
+        totp: Factor[]
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * @experimental
+ */
+export type AuthenticatorAssuranceLevels = 'aal1' | 'aal2'
+
+/**
+ * @experimental
+ */
+export type AuthMFAGetAuthenticatorAssuranceLevelResponse =
+  | {
+      data: {
+        /** Current AAL level of the session. */
+        currentLevel: AuthenticatorAssuranceLevels | null
+
+        /**
+         * Next possible AAL level for the session. If the next level is higher
+         * than the current one, the user should go through MFA.
+         *
+         * @see {@link GoTrueMFAApi#challenge}
+         */
+        nextLevel: AuthenticatorAssuranceLevels | null
+
+        /**
+         * A list of all authentication methods attached to this session. Use
+         * the information here to detect the last time a user verified a
+         * factor, for example if implementing a step-up scenario.
+         */
+        currentAuthenticationMethods: AMREntry[]
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * Contains the full multi-factor authentication API.
+ *
+ * @experimental
+ */
+export interface GoTrueMFAApi {
+  /**
+   * Starts the enrollment process for a new Multi-Factor Authentication
+   * factor. This method creates a new factor in the 'unverified' state.
+   * Present the QR code or secret to the user and ask them to add it to their
+   * authenticator app. Ask the user to provide you with an authenticator code
+   * from their app and verify it by calling challenge and then verify.
+   *
+   * The first successful verification of an unverified factor activates the
+   * factor. All other sessions are logged out and the current one gets an
+   * `aal2` authenticator level.
+   *
+   * @see {@link GoTrueMFAApi#challenge}
+   * @see {@link GoTrueMFAApi#verify}
+   * @see {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}
+   *
+   * @experimental
+   */
+  enroll(params: MFAEnrollParams): Promise<AuthMFAEnrollResponse>
+
+  /**
+   * Prepares a challenge used to verify that a user has access to a MFA
+   * factor. Provide the challenge ID and verification code by calling
+   * {@link GoTrueMFAApi#verify}.
+   *
+   * @experimental
+   */
+  challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse>
+
+  /**
+   * Verifies a verification code against a challenge. The verification code is
+   * provided by the user by entering a code seen in their authenticator app.
+   *
+   * @see {@link GoTrueMFAApi#challenge}
+   *
+   * @experimental
+   */
+  verify(params: MFAVerifyParams): Promise<AuthMFAVerifyResponse>
+
+  /**
+   * Unenroll removes a MFA factor. Unverified factors can safely be ignored
+   * and it's not necessary to unenroll them. Unenrolling a verified MFA factor
+   * cannot be done from a session with an `aal1` authenticator level.
+   *
+   * @experimental
+   */
+  unenroll(params: MFAUnenrollParams): Promise<AuthMFAUnenrollResponse>
+
+  /**
+   * Returns the list of MFA factors enabled for this user. For most use cases
+   * you should consider using {@link
+   * GoTrueMFAApi#getAuthenticatorAssuranceLevel}. This uses a cached version
+   * of the factors and avoids incurring a network call. If you need to update
+   * this list, call {@link GoTrueClient#getUser} first.
+   *
+   * @see {@link GoTrueMFAApi#enroll}
+   * @see {@link GoTrueMFAApi#getAuthenticatorAssuranceLevel}
+   * @see {@link GoTrueClient#getUser}
+   *
+   * @experimental
+   */
+  listFactors(): Promise<AuthMFAListFactorsResponse>
+
+  /**
+   * 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,
+   * etc.).
+   * - `aal2` means that the user's identity has been verified both with a conventional login and at least one MFA factor.
+   *
+   * Although this method returns a promise, it's fairly quick (microseconds)
+   * and rarely uses the network. You can use this to check whether the current
+   * user needs to be shown a screen to verify their MFA factors.
+   *
+   * @experimental
+   */
+  getAuthenticatorAssuranceLevel(): Promise<AuthMFAGetAuthenticatorAssuranceLevelResponse>
+}
+
+/**
+ * @expermental
+ */
+export type AuthMFAAdminDeleteFactorResponse =
+  | {
+      data: {
+        /** ID of the factor that was successfully deleted. */
+        id: string
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * @expermental
+ */
+export type AuthMFAAdminDeleteFactorParams = {
+  /** ID of the MFA factor to delete. */
+  id: string
+
+  /** ID of the user whose factor is being deleted. */
+  userId: string
+}
+
+/**
+ * @expermental
+ */
+export type AuthMFAAdminListFactorsResponse =
+  | {
+      data: {
+        /** All factors attached to the user. */
+        factors: Factor[]
+      }
+      error: null
+    }
+  | { data: null; error: AuthError }
+
+/**
+ * @expermental
+ */
+export type AuthMFAAdminListFactorsParams = {
+  /** ID of the user for which to list all MFA factors. */
+  userId: string
+}
+
+/**
+ * Contains the full multi-factor authentication administration API.
+ *
+ * @expermental
+ */
+export interface GoTrueAdminMFAApi {
+  /**
+   * Lists all factors attached to a user.
+   *
+   * @experimental
+   */
+  listFactors(params: AuthMFAAdminListFactorsParams): Promise<AuthMFAAdminListFactorsResponse>
+
+  /**
+   * Deletes a factor on a user. This will log the user out of all active
+   * sessions (if the deleted factor was verified). There's no need to delete
+   * unverified factors.
+   *
+   * @see {@link GoTrueMFAApi#unenroll}
+   *
+   * @expermental
+   */
+  deleteFactor(params: AuthMFAAdminDeleteFactorParams): Promise<AuthMFAAdminDeleteFactorResponse>
+}
+
 type AnyFunction = (...args: any[]) => any
 type MaybePromisify<T> = T | Promise<T>
 

package/src/lib/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '2.0.1'
+export const version = '2.1.0'