@auth0/auth0-server-js 1.3.0 → 1.5.0

package/dist/index.d.ts

@@ -1,14 +1,32 @@
-import { AuthorizationDetails, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
-export { 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';
 
+/**
+ * Resolves the Auth0 custom domain at runtime using request-specific context.
+ *
+ * Should return a custom domain hostname (for example,
+ * `brand-1.custom-domain.com`) without protocol.
+ *
+ * The resolver receives a context object from SDK method calls (typically
+ * the same `storeOptions` object passed by the application).
+ * Resolved custom domains must be trusted and must belong to the same Auth0 tenant.
+ * Do not derive the returned domain directly from untrusted request input.
+ *
+ * The resolver must return a non-empty domain string. If it returns `null`,
+ * `undefined`, or an empty string at runtime, the SDK throws
+ * `InvalidConfigurationError`.
+ */
+type DomainResolver<TStoreOptions> = (context?: TStoreOptions) => Promise<string> | string;
+
 interface ServerClientOptions<TStoreOptions = unknown> {
-    domain: string;
+    domain: string | DomainResolver<TStoreOptions>;
     clientId: string;
     clientSecret?: string;
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
     /**
@@ -73,11 +91,13 @@ interface SessionData {
     refreshToken: string | undefined;
     tokenSets: TokenSet[];
     connectionTokenSets?: ConnectionTokenSet[];
+    domain?: string;
     [key: string]: unknown;
 }
 interface TransactionData {
     audience?: string;
     codeVerifier: string;
+    domain?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -85,9 +105,16 @@ interface AbstractDataStore<TData, TStoreOptions = unknown> {
     get(identifier: string, options?: TStoreOptions): Promise<TData | undefined>;
     delete(identifier: string, options?: TStoreOptions): Promise<void>;
 }
+/**
+ * Claims used to identify sessions for Backchannel Logout.
+ *
+ * `iss` is optional for backward compatibility, but is included by resolver-mode
+ * implementations to disambiguate sessions across multiple issuers/domains.
+ */
 type LogoutTokenClaims = {
     sub?: string;
     sid?: string;
+    iss?: string;
 };
 interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateData, TStoreOptions> {
     deleteByLogoutToken(claims: LogoutTokenClaims, options?: TStoreOptions): Promise<void>;
@@ -202,7 +229,7 @@ interface SessionCookieOptions {
      *
      * Default: `lax`.
      */
-    sameSite?: "strict" | "lax" | "none";
+    sameSite?: 'strict' | 'lax' | 'none';
     /**
      * The secure attribute of the session cookie.
      *
@@ -225,15 +252,108 @@ 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;
     /**
      * 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.
      *
+     * This property can only be used when `domain` is configured as a static string.
+     * In resolver mode (`domain` as a function), the SDK resolves the domain per request,
+     * so use `ServerClient` methods instead.
+     *
      * Important: the methods exposed on the `authClient` instance do not handle any session or state management.
      */
-    readonly authClient: AuthClient;
+    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.
@@ -332,11 +452,19 @@ declare class ServerClient<TStoreOptions = unknown> {
     /**
      * Retrieve the user session from the store, or undefined if no session found.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
-     * @returns The sessionm or undefined if no session found in the store.
+     * @returns The session or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
+    /**
+     * Retrieves the access token from the store, or calls Auth0 when the access token is expired and a refresh token is available in the store.
+     * 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. 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.
+     */
     getAccessToken(storeOptions?: TStoreOptions): Promise<TokenSet>;
-    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions): Promise<TokenSet>;
     /**
      * Retrieves an access token for a connection.
      *
@@ -538,5 +666,12 @@ declare class InvalidConfigurationError extends Error {
     code: string;
     constructor(message: string);
 }
+/**
+ * Error thrown when the issuer validation fails.
+ */
+declare class IssuerValidationError extends Error {
+    code: string;
+    constructor(message: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, 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 };