@auth0/auth0-server-js 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
-export { DiscoveryCacheOptions, TelemetryConfig } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions } from '@auth0/auth0-auth-js';
+export { AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, OobChannel, OobEnrollmentResponse, OtpEnrollmentResponse, TelemetryConfig, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -252,6 +252,82 @@ interface SessionCookieOptions {
     path?: string;
 }
 
+/**
+ * Response from a successful MFA verification.
+ */
+interface MfaVerifyResponse {
+    /** The access token */
+    accessToken: string;
+    /** The ID token (if openid scope was requested) */
+    idToken?: string;
+    /** The refresh token (if offline_access scope was requested) */
+    refreshToken?: string;
+    /** The token type (typically "bearer") */
+    tokenType: string;
+    /** Unix timestamp (seconds) at which the access token expires */
+    expiresAt: number;
+    /** The granted scopes */
+    scope?: string;
+    /** A new recovery code (only returned when verifying with a recovery code) */
+    recoveryCode?: string;
+}
+/**
+ * @internal
+ * Options for constructing a ServerMfaClient.
+ */
+interface ServerMfaClientOptions<TStoreOptions = unknown> {
+    authClient: AuthClient;
+    domain: string;
+    stateStore: StateStore<TStoreOptions>;
+    stateStoreIdentifier: string;
+    defaultAudience: string;
+}
+
+declare class ServerMfaClient<TStoreOptions = unknown> {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(options: ServerMfaClientOptions<TStoreOptions>);
+    /**
+     * Lists all MFA authenticators enrolled by the user.
+     *
+     * @param options - Options for listing authenticators
+     * @returns Promise resolving to an array of enrolled authenticators
+     * @throws {MfaListAuthenticatorsError} When the request fails
+     */
+    listAuthenticators(options: ListAuthenticatorsOptions): Promise<AuthenticatorResponse[]>;
+    /**
+     * Enrolls a new MFA authenticator for the user.
+     *
+     * @param options - Enrollment options
+     * @returns Promise resolving to enrollment response with authenticator details
+     * @throws {MfaEnrollmentError} When enrollment fails
+     */
+    enrollAuthenticator(options: EnrollAuthenticatorOptions): Promise<EnrollmentResponse>;
+    /**
+     * Initiates an MFA challenge for user verification.
+     *
+     * @param options - Challenge options
+     * @returns Promise resolving to challenge response with challenge details
+     * @throws {MfaChallengeError} When the challenge fails
+     */
+    challengeAuthenticator(options: ChallengeOptions): Promise<ChallengeResponse>;
+    /**
+     * Verifies an MFA challenge and completes the authentication flow.
+     *
+     * Exchanges the MFA token and verification code for access, ID, and refresh tokens,
+     * then saves them into the user's session automatically.
+     *
+     * @param options - The MFA token, factor type (otp / oob / recovery-code), and the code to verify
+     * @param storeOptions - Optional options forwarded to the session store. Can be omitted when
+     *   using the built-in stores; required if your custom store needs extra context (e.g. a request object).
+     * @returns The tokens returned by Auth0 after successful verification
+     * @throws {MfaVerifyError} When verification fails (e.g. invalid token, wrong code)
+     */
+    verify(options: MfaVerifyOptions, storeOptions?: TStoreOptions): Promise<MfaVerifyResponse>;
+}
+
 declare class ServerClient<TStoreOptions = unknown> {
     #private;
     /**
@@ -265,6 +341,19 @@ declare class ServerClient<TStoreOptions = unknown> {
      * Important: the methods exposed on the `authClient` instance do not handle any session or state management.
      */
     get authClient(): AuthClient;
+    /**
+     * The MFA client for managing multi-factor authentication operations.
+     *
+     * Provides methods to list, enroll, and challenge MFA authenticators,
+     * as well as verify MFA challenges to complete authentication.
+     *
+     * The `verify` method integrates with the session state store, persisting tokens
+     * and user data after successful MFA verification.
+     *
+     * This property can only be used when `domain` is configured as a static string.
+     * In resolver mode (`domain` as a function), MFA is not supported.
+     */
+    get mfa(): ServerMfaClient<TStoreOptions>;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
@@ -371,7 +460,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      * Also updates the store when a new token was retrieved from Auth0.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
-     * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token.
+     * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`.
      *
      * @returns The Token Set, containing the access token, as well as additional information.
      */
@@ -585,4 +674,4 @@ declare class IssuerValidationError extends Error {
     constructor(message: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, ServerMfaClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
-export { DiscoveryCacheOptions, TelemetryConfig } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions } from '@auth0/auth0-auth-js';
+export { AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, OobChannel, OobEnrollmentResponse, OtpEnrollmentResponse, TelemetryConfig, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -252,6 +252,82 @@ interface SessionCookieOptions {
     path?: string;
 }
 
+/**
+ * Response from a successful MFA verification.
+ */
+interface MfaVerifyResponse {
+    /** The access token */
+    accessToken: string;
+    /** The ID token (if openid scope was requested) */
+    idToken?: string;
+    /** The refresh token (if offline_access scope was requested) */
+    refreshToken?: string;
+    /** The token type (typically "bearer") */
+    tokenType: string;
+    /** Unix timestamp (seconds) at which the access token expires */
+    expiresAt: number;
+    /** The granted scopes */
+    scope?: string;
+    /** A new recovery code (only returned when verifying with a recovery code) */
+    recoveryCode?: string;
+}
+/**
+ * @internal
+ * Options for constructing a ServerMfaClient.
+ */
+interface ServerMfaClientOptions<TStoreOptions = unknown> {
+    authClient: AuthClient;
+    domain: string;
+    stateStore: StateStore<TStoreOptions>;
+    stateStoreIdentifier: string;
+    defaultAudience: string;
+}
+
+declare class ServerMfaClient<TStoreOptions = unknown> {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(options: ServerMfaClientOptions<TStoreOptions>);
+    /**
+     * Lists all MFA authenticators enrolled by the user.
+     *
+     * @param options - Options for listing authenticators
+     * @returns Promise resolving to an array of enrolled authenticators
+     * @throws {MfaListAuthenticatorsError} When the request fails
+     */
+    listAuthenticators(options: ListAuthenticatorsOptions): Promise<AuthenticatorResponse[]>;
+    /**
+     * Enrolls a new MFA authenticator for the user.
+     *
+     * @param options - Enrollment options
+     * @returns Promise resolving to enrollment response with authenticator details
+     * @throws {MfaEnrollmentError} When enrollment fails
+     */
+    enrollAuthenticator(options: EnrollAuthenticatorOptions): Promise<EnrollmentResponse>;
+    /**
+     * Initiates an MFA challenge for user verification.
+     *
+     * @param options - Challenge options
+     * @returns Promise resolving to challenge response with challenge details
+     * @throws {MfaChallengeError} When the challenge fails
+     */
+    challengeAuthenticator(options: ChallengeOptions): Promise<ChallengeResponse>;
+    /**
+     * Verifies an MFA challenge and completes the authentication flow.
+     *
+     * Exchanges the MFA token and verification code for access, ID, and refresh tokens,
+     * then saves them into the user's session automatically.
+     *
+     * @param options - The MFA token, factor type (otp / oob / recovery-code), and the code to verify
+     * @param storeOptions - Optional options forwarded to the session store. Can be omitted when
+     *   using the built-in stores; required if your custom store needs extra context (e.g. a request object).
+     * @returns The tokens returned by Auth0 after successful verification
+     * @throws {MfaVerifyError} When verification fails (e.g. invalid token, wrong code)
+     */
+    verify(options: MfaVerifyOptions, storeOptions?: TStoreOptions): Promise<MfaVerifyResponse>;
+}
+
 declare class ServerClient<TStoreOptions = unknown> {
     #private;
     /**
@@ -265,6 +341,19 @@ declare class ServerClient<TStoreOptions = unknown> {
      * Important: the methods exposed on the `authClient` instance do not handle any session or state management.
      */
     get authClient(): AuthClient;
+    /**
+     * The MFA client for managing multi-factor authentication operations.
+     *
+     * Provides methods to list, enroll, and challenge MFA authenticators,
+     * as well as verify MFA challenges to complete authentication.
+     *
+     * The `verify` method integrates with the session state store, persisting tokens
+     * and user data after successful MFA verification.
+     *
+     * This property can only be used when `domain` is configured as a static string.
+     * In resolver mode (`domain` as a function), MFA is not supported.
+     */
+    get mfa(): ServerMfaClient<TStoreOptions>;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
@@ -371,7 +460,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      * Also updates the store when a new token was retrieved from Auth0.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
-     * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token.
+     * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`.
      *
      * @returns The Token Set, containing the access token, as well as additional information.
      */
@@ -585,4 +674,4 @@ declare class IssuerValidationError extends Error {
     constructor(message: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, ServerMfaClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.js

@@ -57,6 +57,17 @@ var createUpdatedTokenSet = (audience, response) => ({
   expiresAt: response.expiresAt
 });
 function updateStateData(audience, stateData, tokenEndpointResponse, context) {
+  if (stateData && tokenEndpointResponse.claims) {
+    const newSub = tokenEndpointResponse.claims.sub;
+    const newIss = tokenEndpointResponse.claims.iss;
+    const existingSub = stateData.user?.sub;
+    const existingIss = stateData.user?.iss;
+    const subMismatch = newSub !== void 0 && existingSub !== void 0 && newSub !== existingSub;
+    const issMismatch = newIss !== void 0 && existingIss !== void 0 && newIss !== existingIss;
+    if (subMismatch || issMismatch) {
+      stateData = void 0;
+    }
+  }
   if (stateData) {
     const isNewTokenSet = !stateData.tokenSets.some(
       (tokenSet) => tokenSet.audience === audience && tokenSet.scope === tokenEndpointResponse.scope
@@ -138,10 +149,90 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.4.0"
+    version: config?.version ?? "1.5.0"
   };
 }
 
+// src/mfa/server-mfa-client.ts
+var ServerMfaClient = class {
+  #options;
+  /**
+   * @internal
+   */
+  constructor(options) {
+    this.#options = options;
+  }
+  /**
+   * Lists all MFA authenticators enrolled by the user.
+   *
+   * @param options - Options for listing authenticators
+   * @returns Promise resolving to an array of enrolled authenticators
+   * @throws {MfaListAuthenticatorsError} When the request fails
+   */
+  async listAuthenticators(options) {
+    return this.#options.authClient.mfa.listAuthenticators(options);
+  }
+  /**
+   * Enrolls a new MFA authenticator for the user.
+   *
+   * @param options - Enrollment options
+   * @returns Promise resolving to enrollment response with authenticator details
+   * @throws {MfaEnrollmentError} When enrollment fails
+   */
+  async enrollAuthenticator(options) {
+    return this.#options.authClient.mfa.enrollAuthenticator(options);
+  }
+  /**
+   * Initiates an MFA challenge for user verification.
+   *
+   * @param options - Challenge options
+   * @returns Promise resolving to challenge response with challenge details
+   * @throws {MfaChallengeError} When the challenge fails
+   */
+  async challengeAuthenticator(options) {
+    return this.#options.authClient.mfa.challengeAuthenticator(options);
+  }
+  /**
+   * Verifies an MFA challenge and completes the authentication flow.
+   *
+   * Exchanges the MFA token and verification code for access, ID, and refresh tokens,
+   * then saves them into the user's session automatically.
+   *
+   * @param options - The MFA token, factor type (otp / oob / recovery-code), and the code to verify
+   * @param storeOptions - Optional options forwarded to the session store. Can be omitted when
+   *   using the built-in stores; required if your custom store needs extra context (e.g. a request object).
+   * @returns The tokens returned by Auth0 after successful verification
+   * @throws {MfaVerifyError} When verification fails (e.g. invalid token, wrong code)
+   */
+  async verify(options, storeOptions) {
+    const tokenResponse = await this.#options.authClient.mfa.verify(options);
+    const audience = options.audience ?? this.#options.defaultAudience;
+    const existingStateData = await this.#options.stateStore.get(
+      this.#options.stateStoreIdentifier,
+      storeOptions
+    );
+    const updatedStateData = updateStateData(audience, existingStateData, tokenResponse, {
+      domain: this.#options.domain
+    });
+    await this.#options.stateStore.set(
+      this.#options.stateStoreIdentifier,
+      updatedStateData,
+      true,
+      storeOptions
+    );
+    const result = {
+      accessToken: tokenResponse.accessToken,
+      tokenType: tokenResponse.tokenType ?? "bearer",
+      expiresAt: tokenResponse.expiresAt,
+      scope: tokenResponse.scope
+    };
+    if (tokenResponse.idToken) result.idToken = tokenResponse.idToken;
+    if (tokenResponse.refreshToken) result.refreshToken = tokenResponse.refreshToken;
+    if (tokenResponse.recoveryCode) result.recoveryCode = tokenResponse.recoveryCode;
+    return result;
+  }
+};
+
 // src/server-client.ts
 var DEFAULT_SCOPES = "openid profile email offline_access";
 var normalizeDomain = (value) => {
@@ -176,6 +267,7 @@ var ServerClient = class {
   #authClientOptions;
   #staticDomain;
   #authClient;
+  #mfaClient;
   /**
    * The underlying `authClient` instance that can be used to interact with the Auth0 Authentication API.
    * Generally, you should prefer to use the higher-level methods exposed on the `ServerClient` instance.
@@ -192,6 +284,24 @@ var ServerClient = class {
     }
     return this.#authClient;
   }
+  /**
+   * The MFA client for managing multi-factor authentication operations.
+   *
+   * Provides methods to list, enroll, and challenge MFA authenticators,
+   * as well as verify MFA challenges to complete authentication.
+   *
+   * The `verify` method integrates with the session state store, persisting tokens
+   * and user data after successful MFA verification.
+   *
+   * This property can only be used when `domain` is configured as a static string.
+   * In resolver mode (`domain` as a function), MFA is not supported.
+   */
+  get mfa() {
+    if (!this.#mfaClient) {
+      throw new InvalidConfigurationError("mfa is only available when using a static domain configuration.");
+    }
+    return this.#mfaClient;
+  }
   constructor(options) {
     this.#options = options;
     this.#stateStoreIdentifier = this.#options.stateIdentifier || "__a0_session";
@@ -225,6 +335,13 @@ var ServerClient = class {
         ...this.#authClientOptions,
         telemetry: getTelemetryConfig(this.#options.telemetry)
       });
+      this.#mfaClient = new ServerMfaClient({
+        authClient: this.#authClient,
+        domain,
+        stateStore: this.#stateStore,
+        stateStoreIdentifier: this.#stateStoreIdentifier,
+        defaultAudience: this.#options.authorizationParams?.audience ?? "default"
+      });
     }
   }
   async #resolveDomain(storeOptions) {
@@ -534,7 +651,7 @@ var ServerClient = class {
    * Also updates the store when a new token was retrieved from Auth0.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
-   * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token.
+   * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`.
    *
    * @returns The Token Set, containing the access token, as well as additional information.
    */
@@ -1015,6 +1132,15 @@ var StatelessStateStore = class extends AbstractSessionStore {
     };
   }
 };
+
+// src/mfa/index.ts
+import {
+  MfaListAuthenticatorsError,
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError,
+  isMfaRequiredError
+} from "@auth0/auth0-auth-js";
 export {
   AbstractStateStore,
   AbstractTransactionStore,
@@ -1022,12 +1148,18 @@ export {
   CookieTransactionStore,
   InvalidConfigurationError,
   IssuerValidationError,
+  MfaChallengeError,
+  MfaEnrollmentError,
+  MfaListAuthenticatorsError,
+  MfaVerifyError,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
   ServerClient,
+  ServerMfaClient,
   StartLinkUserError,
   StatefulStateStore,
-  StatelessStateStore
+  StatelessStateStore,
+  isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map