@auth0/auth0-server-js 1.4.0 → 1.6.0

package/dist/index.cjs

@@ -26,13 +26,19 @@ __export(index_exports, {
   CookieTransactionStore: () => CookieTransactionStore,
   InvalidConfigurationError: () => InvalidConfigurationError,
   IssuerValidationError: () => IssuerValidationError,
+  MfaChallengeError: () => import_auth0_auth_js2.MfaChallengeError,
+  MfaEnrollmentError: () => import_auth0_auth_js2.MfaEnrollmentError,
+  MfaListAuthenticatorsError: () => import_auth0_auth_js2.MfaListAuthenticatorsError,
+  MfaVerifyError: () => import_auth0_auth_js2.MfaVerifyError,
   MissingRequiredArgumentError: () => MissingRequiredArgumentError,
   MissingSessionError: () => MissingSessionError,
   MissingTransactionError: () => MissingTransactionError,
   ServerClient: () => ServerClient,
+  ServerMfaClient: () => ServerMfaClient,
   StartLinkUserError: () => StartLinkUserError,
   StatefulStateStore: () => StatefulStateStore,
-  StatelessStateStore: () => StatelessStateStore
+  StatelessStateStore: () => StatelessStateStore,
+  isMfaRequiredError: () => import_auth0_auth_js2.isMfaRequiredError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -95,6 +101,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
@@ -172,10 +189,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) => {
@@ -210,6 +307,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.
@@ -226,6 +324,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";
@@ -259,6 +375,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) {
@@ -568,7 +691,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.
    */
@@ -703,6 +826,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.
@@ -1049,6 +1231,9 @@ var StatelessStateStore = class extends AbstractSessionStore {
     };
   }
 };
+
+// src/mfa/index.ts
+var import_auth0_auth_js2 = require("@auth0/auth0-auth-js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AbstractStateStore,
@@ -1057,12 +1242,18 @@ var StatelessStateStore = class extends AbstractSessionStore {
   CookieTransactionStore,
   InvalidConfigurationError,
   IssuerValidationError,
+  MfaChallengeError,
+  MfaEnrollmentError,
+  MfaListAuthenticatorsError,
+  MfaVerifyError,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
   ServerClient,
+  ServerMfaClient,
   StartLinkUserError,
   StatefulStateStore,
-  StatelessStateStore
+  StatelessStateStore,
+  isMfaRequiredError
 });
 //# sourceMappingURL=index.cjs.map