@auth0/auth0-server-js 1.4.0 → 1.6.0

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 { ExchangeProfileOptions, AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, 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, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -217,6 +217,33 @@ interface SessionStore<TStoreOptions> {
     get(identifier: string): Promise<StateData | undefined>;
     deleteByLogoutToken(claims: LogoutTokenClaims, options?: TStoreOptions | undefined): Promise<void>;
 }
+/**
+ * Options for exchanging a custom token and persisting the resulting session (RFC 8693).
+ *
+ * Mirrors `ExchangeProfileOptions` from `auth0-auth-js`. The `audience` field is
+ * also used to key the token set stored in the session.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type LoginWithCustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Options for performing a custom token exchange without any session side effects (RFC 8693).
+ *
+ * Use this when you need delegated tokens for downstream service calls but do not want
+ * to establish a user session (e.g. impersonation, service-to-service delegation).
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type CustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Result of a successful custom token exchange with session persistence.
+ */
+interface LoginWithCustomTokenExchangeResult {
+    /**
+     * Authorization details returned by the token endpoint when RAR was used.
+     */
+    authorizationDetails?: AuthorizationDetails[];
+}
 interface SessionCookieOptions {
     /**
      * The name of the session cookie.
@@ -252,6 +279,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 +368,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 +487,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.
      */
@@ -399,6 +515,45 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns {URL}
      */
     logout(options: LogoutOptions, storeOptions?: TStoreOptions): Promise<URL>;
+    /**
+     * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
+     *
+     * Calls the token endpoint using the RFC 8693 Token Exchange grant, then stores the
+     * resulting tokens in the StateStore — effectively logging the user in without an
+     * interactive browser flow. Use this when the caller already holds a trusted external
+     * token (e.g. a Google ID token, a legacy system token) and wants to establish an
+     * Auth0 session from it.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore.
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to an object containing `authorizationDetails` when RAR was used.
+     */
+    loginWithCustomTokenExchange(options: LoginWithCustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<LoginWithCustomTokenExchangeResult>;
+    /**
+     * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
+     *
+     * Performs the same RFC 8693 Token Exchange as `loginWithCustomTokenExchange` but
+     * returns the raw token response without writing anything to the StateStore. Use this
+     * for delegation or impersonation flows where you need downstream tokens but do not
+     * want to create or modify the current user session.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore (used only for domain resolution in resolver mode).
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to the token response from Auth0.
+     */
+    customTokenExchange(options: CustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<TokenResponse>;
     /**
      * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
      * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -585,4 +740,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 CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, 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.6.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.
    */
@@ -669,6 +786,65 @@ var ServerClient = class {
     }
     return authClient.buildLogoutUrl(options);
   }
+  /**
+   * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
+   *
+   * Calls the token endpoint using the RFC 8693 Token Exchange grant, then stores the
+   * resulting tokens in the StateStore — effectively logging the user in without an
+   * interactive browser flow. Use this when the caller already holds a trusted external
+   * token (e.g. a Google ID token, a legacy system token) and wants to establish an
+   * Auth0 session from it.
+   *
+   * Requires a Token Exchange Profile configured in your Auth0 tenant.
+   *
+   * @param options Options for the custom token exchange, including the subject token and its type.
+   * @param storeOptions Optional options passed to the StateStore.
+   *
+   * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+   * @throws {MissingClientAuthError} If client credentials are not configured.
+   *
+   * @returns A promise resolving to an object containing `authorizationDetails` when RAR was used.
+   */
+  async loginWithCustomTokenExchange(options, storeOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    const tokenEndpointResponse = await authClient.exchangeToken({
+      ...options,
+      scope: ensureOpenIdScope(options.scope)
+    });
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const stateData = updateStateData(
+      this.#options.authorizationParams?.audience ?? "default",
+      existingStateData,
+      tokenEndpointResponse,
+      { domain }
+    );
+    await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    return { authorizationDetails: tokenEndpointResponse.authorizationDetails };
+  }
+  /**
+   * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
+   *
+   * Performs the same RFC 8693 Token Exchange as `loginWithCustomTokenExchange` but
+   * returns the raw token response without writing anything to the StateStore. Use this
+   * for delegation or impersonation flows where you need downstream tokens but do not
+   * want to create or modify the current user session.
+   *
+   * Requires a Token Exchange Profile configured in your Auth0 tenant.
+   *
+   * @param options Options for the custom token exchange, including the subject token and its type.
+   * @param storeOptions Optional options passed to the StateStore (used only for domain resolution in resolver mode).
+   *
+   * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+   * @throws {MissingClientAuthError} If client credentials are not configured.
+   *
+   * @returns A promise resolving to the token response from Auth0.
+   */
+  async customTokenExchange(options, storeOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    return authClient.exchangeToken(options);
+  }
   /**
    * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
    * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -1015,6 +1191,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 +1207,18 @@ export {
   CookieTransactionStore,
   InvalidConfigurationError,
   IssuerValidationError,
+  MfaChallengeError,
+  MfaEnrollmentError,
+  MfaListAuthenticatorsError,
+  MfaVerifyError,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
   ServerClient,
+  ServerMfaClient,
   StartLinkUserError,
   StatefulStateStore,
-  StatelessStateStore
+  StatelessStateStore,
+  isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map