@supabase/gotrue-js 2.0.1 → 2.2.0

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. */
@@ -300,6 +357,12 @@ export type SignInWithPasswordCredentials =
       /** The user's password. */
       password: string
       options?: {
+        /**
+         * A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
+         *
+         * The `data` should be a JSON object that includes user-specific info, such as their first and last name.
+         */
+        data?: object
         /** Verification token received when the user completes the captcha on the site. */
         captchaToken?: string
       }
@@ -310,6 +373,12 @@ export type SignInWithPasswordCredentials =
       /** The user's password. */
       password: string
       options?: {
+        /**
+         * A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column.
+         *
+         * The `data` should be a JSON object that includes user-specific info, such as their first and last name.
+         */
+        data?: object
         /** Verification token received when the user completes the captcha on the site. */
         captchaToken?: string
       }
@@ -492,6 +561,362 @@ 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 MFAChallengeAndVerifyParams = {
+  /** ID of the factor being verified. */
+  factorId: string
+  /** Verification code provided by the user. */
+  code: 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>
+
+  /**
+   * Helper method which creates a challenge and immediately uses the given code to verify against it thereafter. The verification code is
+   * provided by the user by entering a code seen in their authenticator app.
+   *
+   * @see {@link GoTrueMFAApi#challengeAndVerify}
+   *
+   * @experimental
+   */
+  challengeAndVerify(params: MFAChallengeAndVerifyParams): Promise<AuthMFAVerifyResponse>
+
+  /**
+   * 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.2.0'