@auth0/auth0-server-js 1.12.0 → 1.13.0

package/dist/index.js

@@ -168,6 +168,7 @@ function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointR
 import {
   TokenForConnectionError,
   AuthClient,
+  MissingCapturedResponseError,
   OrganizationValidationError,
   PasswordlessStartError,
   PasswordlessVerifyError,
@@ -211,7 +212,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.12.0"
+    version: config?.version ?? "1.13.0"
   };
 }
 
@@ -231,8 +232,8 @@ var ServerMfaClient = class {
    * @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);
+  async listAuthenticators(options, requestOptions) {
+    return this.#options.authClient.mfa.listAuthenticators(options, requestOptions);
   }
   /**
    * Enrolls a new MFA authenticator for the user.
@@ -241,8 +242,8 @@ var ServerMfaClient = class {
    * @returns Promise resolving to enrollment response with authenticator details
    * @throws {MfaEnrollmentError} When enrollment fails
    */
-  async enrollAuthenticator(options) {
-    return this.#options.authClient.mfa.enrollAuthenticator(options);
+  async enrollAuthenticator(options, requestOptions) {
+    return this.#options.authClient.mfa.enrollAuthenticator(options, requestOptions);
   }
   /**
    * Initiates an MFA challenge for user verification.
@@ -251,8 +252,8 @@ var ServerMfaClient = class {
    * @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);
+  async challengeAuthenticator(options, requestOptions) {
+    return this.#options.authClient.mfa.challengeAuthenticator(options, requestOptions);
   }
   /**
    * Verifies an MFA challenge and completes the authentication flow.
@@ -266,8 +267,8 @@ var ServerMfaClient = class {
    * @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);
+  async verify(options, storeOptions, requestOptions) {
+    const tokenResponse = await this.#options.authClient.mfa.verify(options, requestOptions);
     const audience = options.audience ?? this.#options.defaultAudience;
     const existingStateData = await this.#options.stateStore.get(
       this.#options.stateStoreIdentifier,
@@ -317,6 +318,12 @@ var ServerPasskeyClient = class {
    *
    * This method does not create a session; no state is persisted.
    *
+   * On a confidential client this endpoint accepts `client_secret` as its only
+   * credential, so configure `clientSecret` on the `ServerClient`. It does not
+   * accept a private key JWT and is not served on the mTLS endpoint aliases, so a
+   * client configured with only `clientAssertionSigningKey` or only `useMtls` is
+   * rejected by Auth0. Public clients authenticate with `clientId` alone.
+   *
    * @param options User profile data and optional realm/organization.
    * @param storeOptions Optional options used to resolve the domain (resolver mode).
    *
@@ -324,10 +331,10 @@ var ServerPasskeyClient = class {
    *
    * @returns A promise resolving to the signup challenge.
    */
-  async register(options, storeOptions) {
+  async register(options, storeOptions, requestOptions) {
     const domain = await this.#options.resolveDomain(storeOptions);
     const authClient = this.#options.getAuthClient(domain);
-    return authClient.passkey.register(options);
+    return authClient.passkey.register(options, requestOptions);
   }
   /**
    * Requests a passkey login challenge for an existing user.
@@ -339,6 +346,9 @@ var ServerPasskeyClient = class {
    *
    * This method does not create a session; no state is persisted.
    *
+   * Client authentication works the same way as {@link ServerPasskeyClient.register}:
+   * on a confidential client, only a `clientSecret` is accepted here.
+   *
    * @param options Optional realm/organization configuration.
    * @param storeOptions Optional options used to resolve the domain (resolver mode).
    *
@@ -346,10 +356,10 @@ var ServerPasskeyClient = class {
    *
    * @returns A promise resolving to the login challenge.
    */
-  async challenge(options, storeOptions) {
+  async challenge(options, storeOptions, requestOptions) {
     const domain = await this.#options.resolveDomain(storeOptions);
     const authClient = this.#options.getAuthClient(domain);
-    return authClient.passkey.challenge(options);
+    return authClient.passkey.challenge(options, requestOptions);
   }
   /**
    * Completes a passkey authentication flow (signup or login) by exchanging the
@@ -371,7 +381,7 @@ var ServerPasskeyClient = class {
    *
    * @returns A promise resolving to an object containing the authorizationDetails (when RAR was used).
    */
-  async getToken(options, storeOptions) {
+  async getToken(options, storeOptions, requestOptions) {
     const scope = ensureOpenIdScope(options.scope ?? this.#options.defaultScope);
     const audience = options.audience ?? this.#options.defaultAudience;
     const domain = await this.#options.resolveDomain(storeOptions);
@@ -380,7 +390,7 @@ var ServerPasskeyClient = class {
       ...options,
       scope,
       audience
-    });
+    }, requestOptions);
     const existingStateData = await this.#options.stateStore.get(this.#options.stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(audience ?? "default", existingStateData, tokenEndpointResponse, { domain });
     await this.#options.stateStore.set(this.#options.stateStoreIdentifier, stateData, true, storeOptions);
@@ -413,9 +423,9 @@ var ServerDatabaseClient = class {
    *
    * @returns A promise resolving to the created user result with a normalized `id` field.
    */
-  async signUp(options, storeOptions) {
+  async signUp(options, storeOptions, requestOptions) {
     const domain = await this.#options.resolveDomain(storeOptions);
-    return this.#options.getAuthClient(domain).database.signUp(options);
+    return this.#options.getAuthClient(domain).database.signUp(options, requestOptions);
   }
   /**
    * Requests a password-change email for a database connection user.
@@ -431,9 +441,9 @@ var ServerDatabaseClient = class {
    *
    * @returns A promise resolving to the server's plain-text confirmation message.
    */
-  async changePassword(options, storeOptions) {
+  async changePassword(options, storeOptions, requestOptions) {
     const domain = await this.#options.resolveDomain(storeOptions);
-    return this.#options.getAuthClient(domain).database.changePassword(options);
+    return this.#options.getAuthClient(domain).database.changePassword(options, requestOptions);
   }
 };
 
@@ -708,6 +718,7 @@ var ServerClient = class {
    * Takes an URL, extract the Authorization Code flow query parameters and requests a token.
    * @param url The URl from which the query params should be extracted to exchange for a token.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the code-for-token exchange.
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
@@ -715,8 +726,15 @@ var ServerClient = class {
    * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
    *
    * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).
+   *
+   * @remarks
+   * This method does not support the `fullResponse` opt-in in v1. It accepts
+   * `url` and `storeOptions` with no intermediate options object; adding
+   * `fullResponse` would require a new options parameter and is deferred to
+   * a later revision.
+   * TODO(#<issue-number>): add fullResponse overload to completeInteractiveLogin in a future minor.
    */
-  async completeInteractiveLogin(url, storeOptions) {
+  async completeInteractiveLogin(url, storeOptions, requestOptions) {
     const transactionData = await this.#transactionStore.get(this.#transactionStoreIdentifier, storeOptions);
     if (!transactionData) {
       throw new MissingTransactionError();
@@ -727,7 +745,7 @@ var ServerClient = class {
       // TransactionData.codeVerifier is optional only to accommodate magic-link transactions.
       codeVerifier: transactionData.codeVerifier,
       organization: transactionData.organization
-    });
+    }, requestOptions);
     await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = applySessionExpiryAtLogin(
@@ -791,14 +809,15 @@ var ServerClient = class {
    * Takes an URL, extract the Authorization Code flow query parameters and requests a token.
    * @param url The URl from which the query params should be extracted to exchange for a token.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the code-for-token exchange.
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
    *
    * @returns A promise resolving to an object, containing the original appState (if present).
    */
-  async completeLinkUser(url, storeOptions) {
-    const result = await this.completeInteractiveLogin(url, storeOptions);
+  async completeLinkUser(url, storeOptions, requestOptions) {
+    const result = await this.completeInteractiveLogin(url, storeOptions, requestOptions);
     return {
       appState: result.appState
     };
@@ -854,43 +873,44 @@ var ServerClient = class {
    * Takes an URL, extract the Authorization Code flow query parameters and requests a token.
    * @param url The URl from which the query params should be extracted to exchange for a token.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the code-for-token exchange.
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
    *
    * @returns A promise resolving to an object, containing the original appState (if present).
    */
-  async completeUnlinkUser(url, storeOptions) {
-    const result = await this.completeInteractiveLogin(url, storeOptions);
+  async completeUnlinkUser(url, storeOptions, requestOptions) {
+    const result = await this.completeInteractiveLogin(url, storeOptions, requestOptions);
     return {
       appState: result.appState
     };
   }
-  /**
-   * Logs in using Client-Initiated Backchannel Authentication.
-   *
-   * Using Client-Initiated Backchannel Authentication requires the feature to be enabled in the Auth0 dashboard.
-   * @see https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow
-   * @param options Options used to configure the backchannel login process.
-   * @param storeOptions Optional options used to pass to the Transaction and State Store.
-   *
-   * @throws {BackchannelAuthenticationError} If there was an issue when doing backchannel authentication.
-   * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
-   *
-   * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
-   */
-  async loginBackchannel(options, storeOptions) {
+  async loginBackchannel(options, storeOptions, requestOptions) {
     const scope = ensureOpenIdScope(options.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
-    const tokenEndpointResponse = await authClient.backchannelAuthentication({
-      bindingMessage: options.bindingMessage,
-      loginHint: options.loginHint,
-      authorizationParams: {
-        ...options.authorizationParams,
-        scope
-      }
-    });
+    let response;
+    let tokenEndpointResponse;
+    if (options.fullResponse) {
+      const authJsResult = await authClient.backchannelAuthentication({
+        bindingMessage: options.bindingMessage,
+        loginHint: options.loginHint,
+        authorizationParams: { ...options.authorizationParams, scope },
+        fullResponse: true
+      }, requestOptions);
+      tokenEndpointResponse = authJsResult.data;
+      response = authJsResult.response;
+    } else {
+      tokenEndpointResponse = await authClient.backchannelAuthentication({
+        bindingMessage: options.bindingMessage,
+        loginHint: options.loginHint,
+        authorizationParams: {
+          ...options.authorizationParams,
+          scope
+        }
+      }, requestOptions);
+    }
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = applySessionExpiryAtLogin(
       updateStateData(this.#options.authorizationParams?.audience ?? "default", existingStateData, tokenEndpointResponse, {
@@ -899,9 +919,16 @@ var ServerClient = class {
       tokenEndpointResponse.claims
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
-    return {
+    const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
+    if (options.fullResponse) {
+      if (!response) {
+        throw new MissingCapturedResponseError();
+      }
+      return { data: result, response };
+    }
+    return result;
   }
   /**
    * Starts a passwordless flow by sending a one-time code (OTP) or a magic link.
@@ -924,6 +951,7 @@ var ServerClient = class {
    *
    * @param options Discriminated start options.
    * @param storeOptions Optional options passed to the resolver / stores.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the `/passwordless/start` request.
    *
    * @throws {PasswordlessStartError} If the request fails, or if a magic link is requested without a `redirectUri`.
    *
@@ -940,22 +968,28 @@ var ServerClient = class {
    *   redirectUri: 'https://app.example.com/auth/callback',
    * });
    */
-  async startPasswordless(options, storeOptions) {
+  async startPasswordless(options, storeOptions, requestOptions) {
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
     if (options.connection === "sms") {
-      await authClient.passwordless.sendSms({
-        phoneNumber: options.phoneNumber,
-        language: options.language
-      });
+      await authClient.passwordless.sendSms(
+        {
+          phoneNumber: options.phoneNumber,
+          language: options.language
+        },
+        requestOptions
+      );
       return;
     }
     if (options.send !== "link") {
-      await authClient.passwordless.sendEmail({
-        email: options.email,
-        send: "code",
-        language: options.language
-      });
+      await authClient.passwordless.sendEmail(
+        {
+          email: options.email,
+          send: "code",
+          language: options.language
+        },
+        requestOptions
+      );
       return;
     }
     if (!options.redirectUri || typeof options.redirectUri !== "string") {
@@ -964,19 +998,22 @@ var ServerClient = class {
     const state = crypto.randomUUID();
     const scope = ensureOpenIdScope(options.scope ?? this.#options.authorizationParams?.scope);
     const audience = options.audience ?? this.#options.authorizationParams?.audience;
-    await authClient.passwordless.sendEmail({
-      email: options.email,
-      send: "link",
-      language: options.language,
-      authParams: {
-        ...options.authParams,
-        redirect_uri: options.redirectUri,
-        response_type: "code",
-        scope,
-        ...audience ? { audience } : {},
-        state
-      }
-    });
+    await authClient.passwordless.sendEmail(
+      {
+        email: options.email,
+        send: "link",
+        language: options.language,
+        authParams: {
+          ...options.authParams,
+          redirect_uri: options.redirectUri,
+          response_type: "code",
+          scope,
+          ...audience ? { audience } : {},
+          state
+        }
+      },
+      requestOptions
+    );
     const transactionState = {
       audience,
       domain,
@@ -984,42 +1021,42 @@ var ServerClient = class {
     };
     await this.#transactionStore.set(this.#transactionStoreIdentifier, transactionState, false, storeOptions);
   }
-  /**
-   * Completes a passwordless OTP login and persists the resulting session.
-   *
-   * Discriminated on `connection` to mirror the `@auth0/nextjs-auth0` `passwordless.verify()`
-   * surface. Non-redirect flow: no PKCE and no transaction store (mirrors
-   * {@link ServerClient#loginBackchannel}). The `openid` scope is always ensured by this layer.
-   *
-   * Note: the state store is read-then-written; if your deployment performs concurrent
-   * logins for the same session identifier, use a state store with atomic/serializable
-   * writes to avoid last-write-wins races.
-   *
-   * @param options Discriminated completion options (`connection`, identifier, `verificationCode`).
-   * @param storeOptions Optional options passed to the resolver / stores.
-   *
-   * @throws {PasswordlessVerifyError} If the code is invalid, expired, or rate-limited. When the
-   *   connection requires MFA, the server responds with `mfa_required`; narrow the thrown error
-   *   with `isMfaRequiredError(error)` to read `cause.mfa_token`.
-   *
-   * @returns A promise resolving to the authorizationDetails (when RAR was used).
-   */
-  async completePasswordless(options, storeOptions) {
+  async completePasswordless(options, storeOptions, requestOptions) {
     const scope = ensureOpenIdScope(options.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
     const audience = options.authorizationParams?.audience ?? this.#options.authorizationParams?.audience;
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
-    const tokenEndpointResponse = options.connection === "sms" ? await authClient.getTokenByPasswordlessSms({
-      phoneNumber: options.phoneNumber,
-      code: options.verificationCode,
-      audience,
-      scope
-    }) : await authClient.getTokenByPasswordlessEmail({
-      email: options.email,
-      code: options.verificationCode,
-      audience,
-      scope
-    });
+    let response;
+    let tokenEndpointResponse;
+    if (options.fullResponse) {
+      const authJsResult = options.connection === "sms" ? await authClient.getTokenByPasswordlessSms({
+        phoneNumber: options.phoneNumber,
+        code: options.verificationCode,
+        audience,
+        scope,
+        fullResponse: true
+      }, requestOptions) : await authClient.getTokenByPasswordlessEmail({
+        email: options.email,
+        code: options.verificationCode,
+        audience,
+        scope,
+        fullResponse: true
+      }, requestOptions);
+      tokenEndpointResponse = authJsResult.data;
+      response = authJsResult.response;
+    } else {
+      tokenEndpointResponse = options.connection === "sms" ? await authClient.getTokenByPasswordlessSms({
+        phoneNumber: options.phoneNumber,
+        code: options.verificationCode,
+        audience,
+        scope
+      }, requestOptions) : await authClient.getTokenByPasswordlessEmail({
+        email: options.email,
+        code: options.verificationCode,
+        audience,
+        scope
+      }, requestOptions);
+    }
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(
       this.#options.authorizationParams?.audience ?? "default",
@@ -1028,9 +1065,16 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
-    return {
+    const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
+    if (options.fullResponse) {
+      if (!response) {
+        throw new MissingCapturedResponseError();
+      }
+      return { data: result, response };
+    }
+    return result;
   }
   /**
    * Completes a passwordless magic-link login and persists the resulting session.
@@ -1042,6 +1086,7 @@ var ServerClient = class {
    *
    * @param url The callback URL containing the authorization `code` and `state`.
    * @param storeOptions Optional options passed to the resolver / stores.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the code exchange.
    *
    * @throws {MissingTransactionError} If no magic-link transaction was found.
    * @throws {PasswordlessVerifyError} If the returned `state` is missing or does not match.
@@ -1052,7 +1097,7 @@ var ServerClient = class {
    * @example
    * const result = await serverClient.completePasswordlessMagicLink(callbackUrl, storeOptions);
    */
-  async completePasswordlessMagicLink(url, storeOptions) {
+  async completePasswordlessMagicLink(url, storeOptions, requestOptions) {
     const transactionData = await this.#transactionStore.get(this.#transactionStoreIdentifier, storeOptions);
     if (!transactionData) {
       throw new MissingTransactionError();
@@ -1064,7 +1109,7 @@ var ServerClient = class {
     }
     const domain = transactionData.domain ?? await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
-    const tokenEndpointResponse = await authClient.getTokenByMagicLinkCode(url, { expectedState });
+    const tokenEndpointResponse = await authClient.getTokenByMagicLinkCode(url, { expectedState }, requestOptions);
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(transactionData.audience ?? "default", existingStateData, tokenEndpointResponse, {
       domain
@@ -1077,6 +1122,12 @@ var ServerClient = class {
   }
   /**
    * Retrieves the user from the store, or undefined if no user found.
+   *
+   * This does not accept `RequestOptions`. It is a pure read from the state store and makes no
+   * network call, so a per-request `signal`/`headers`/`customFetch` could not take effect. The
+   * exclusion is deliberate: a parameter that can never do anything costs the public surface more
+   * than the asymmetry with `getAccessToken`/`getAccessTokenForConnection`/`revokeRefreshToken` does.
+   *
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    * @returns The user, or undefined if no user found in the store.
    */
@@ -1119,6 +1170,34 @@ var ServerClient = class {
       return sessionData;
     }
   }
+  /**
+   * Retrieves the OIDC UserInfo claims for a given access token.
+   *
+   * The access token must be supplied explicitly by the caller. This method does NOT read
+   * the token from the session and does NOT trigger a refresh. The token must be accepted by
+   * the `/userinfo` endpoint:
+   * - Without Multi-Resource Refresh Tokens (MRRT): pass a default OIDC access token, one
+   *   obtained without an explicit `audience` parameter.
+   * - With MRRT: tokens are audience-bound, so request the userinfo endpoint as the audience
+   *   (e.g. `https://<domain>/userinfo`) when obtaining the token. A token bound to a
+   *   different resource-server audience is rejected by `/userinfo`.
+   *
+   * `/userinfo` is a bearer-protected resource and requires no client authentication, so this
+   * works for public clients: the supplied access token is the only credential used.
+   *
+   * @param options Options containing the access token and an optional expected subject
+   *                for OIDC subject-consistency validation.
+   * @param storeOptions Optional store options, used to resolve the domain in resolver mode.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch) forwarded
+   *                to the underlying `/userinfo` request.
+   * @throws {UserInfoError} When the `/userinfo` request fails or the subject check fails.
+   * @returns A Promise resolving to the UserInfo claims.
+   */
+  async getUserInfo(options, storeOptions, requestOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    return authClient.getUserInfo(options, requestOptions);
+  }
   /**
    * 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.
@@ -1127,19 +1206,30 @@ var ServerClient = class {
    * request an access token for that audience/scope (Multi-Resource Refresh Tokens). Tokens are cached per
    * audience and scope combination.
    *
-   * @param options Optional options for requesting a specific audience/scope.
+   * When `options.fullResponse` is `true`, the method returns an {@link ApiResponse} envelope containing both
+   * the token set and the raw {@link Response} from the token endpoint. The cache is bypassed in this case,
+   * forcing a refresh-token call even when a valid cached token exists, because the `Response` can only be
+   * produced by a live HTTP call.
+   *
+   * @param options Optional options for requesting a specific audience/scope or enabling full response.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Only supported with the options form (second overload). A cache hit returns before any network call, so `requestOptions` (including `signal`) is a no-op on that path; it applies only to the refresh-token exchange on a cache miss.
+   *
+   * @remarks
+   * Legacy single-argument form: `getAccessToken(storeOptions?)`. If your `TStoreOptions` type
+   * contains `audience` or `scope` keys, use the explicit two-argument form instead:
+   * `getAccessToken({}, storeOptions)` to avoid call-site routing ambiguity.
    *
    * @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`.
    * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and no refresh is attempted — the user must re-authenticate.
    *
-   * @returns The Token Set, containing the access token, as well as additional information.
+   * @returns The Token Set when `fullResponse` is omitted, or an {@link ApiResponse} envelope when `fullResponse: true`.
    */
-  async getAccessToken(tokenOptionsOrStoreOptions, storeOptions) {
+  async getAccessToken(tokenOptionsOrStoreOptions, storeOptions, requestOptions) {
     const hasTokenOptions = (
       // If second arg exists, first arg must be GetAccessTokenOptions
-      storeOptions !== void 0 || // OR if first arg has audience/scope properties
-      !!tokenOptionsOrStoreOptions && typeof tokenOptionsOrStoreOptions === "object" && ("audience" in tokenOptionsOrStoreOptions || "scope" in tokenOptionsOrStoreOptions)
+      storeOptions !== void 0 || // OR if first arg has audience, scope, or fullResponse properties
+      !!tokenOptionsOrStoreOptions && typeof tokenOptionsOrStoreOptions === "object" && ("audience" in tokenOptionsOrStoreOptions || "scope" in tokenOptionsOrStoreOptions || "fullResponse" in tokenOptionsOrStoreOptions)
     );
     const [resolvedOptions, resolvedStoreOptions] = hasTokenOptions ? [tokenOptionsOrStoreOptions, storeOptions] : [void 0, tokenOptionsOrStoreOptions];
     const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
@@ -1167,7 +1257,9 @@ var ServerClient = class {
       (tokenSet2) => tokenSet2.audience === audience && (!scope || compareScopes(tokenSet2.scope, scope))
     );
     if (tokenSet && tokenSet.expiresAt > Date.now() / 1e3) {
-      return tokenSet;
+      if (!resolvedOptions?.fullResponse) {
+        return tokenSet;
+      }
     }
     if (!stateData?.refreshToken) {
       throw new TokenByRefreshTokenError(
@@ -1184,35 +1276,38 @@ var ServerClient = class {
         ...scope && { scope }
       }
     };
-    const tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenByRefreshToken(tokenByRefreshTokenOptions);
+    let response;
+    let tokenEndpointResponse;
+    if (resolvedOptions?.fullResponse) {
+      const authJsResult = await this.#getAuthClient(domainForSession).getTokenByRefreshToken({
+        ...tokenByRefreshTokenOptions,
+        fullResponse: true
+      }, requestOptions);
+      tokenEndpointResponse = authJsResult.data;
+      response = authJsResult.response;
+    } else {
+      tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenByRefreshToken(tokenByRefreshTokenOptions, requestOptions);
+    }
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
     const updatedStateData = updateStateData(audience, existingStateData, tokenEndpointResponse, {
       domain: domainForSession
     });
     await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, resolvedStoreOptions);
-    return {
+    const returnTokenSet = {
       accessToken: tokenEndpointResponse.accessToken,
       scope: tokenEndpointResponse.scope,
       expiresAt: tokenEndpointResponse.expiresAt,
       audience
     };
+    if (resolvedOptions?.fullResponse) {
+      if (!response) {
+        throw new MissingCapturedResponseError();
+      }
+      return { data: returnTokenSet, response };
+    }
+    return returnTokenSet;
   }
-  /**
-   * Retrieves an access token for a connection.
-   *
-   * This method attempts to obtain an access token for a specified connection.
-   * It first checks if a refresh token exists in the store.
-   * If no refresh token is found, it throws an `AccessTokenForConnectionError` indicating
-   * that the refresh token was not found.
-   *
-   * @param options - Options for retrieving an access token for a connection.
-   * @param storeOptions Optional options used to pass to the Transaction and State Store.
-   *
-   * @throws {TokenForConnectionError} If the refresh token was not found or there was an issue requesting the access token.
-   *
-   * @returns The Connection Token Set, containing the access token for the connection, as well as additional information.
-   */
-  async getAccessTokenForConnection(options, storeOptions) {
+  async getAccessTokenForConnection(options, storeOptions, requestOptions) {
     const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const sessionDomain = stateData ? this.#getSessionDomain(stateData) : this.#staticDomain;
     if (this.#isResolverMode()) {
@@ -1231,7 +1326,9 @@ var ServerClient = class {
       (tokenSet) => tokenSet.connection === options.connection
     );
     if (connectionTokenSet && connectionTokenSet.expiresAt > Date.now() / 1e3) {
-      return connectionTokenSet;
+      if (!options.fullResponse) {
+        return connectionTokenSet;
+      }
     }
     if (!stateData?.refreshToken) {
       throw new TokenForConnectionError(
@@ -1239,11 +1336,24 @@ var ServerClient = class {
       );
     }
     const domainForSession = sessionDomain;
-    const tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenForConnection({
-      connection: options.connection,
-      loginHint: options.loginHint,
-      refreshToken: stateData.refreshToken
-    });
+    let response;
+    let tokenEndpointResponse;
+    if (options.fullResponse) {
+      const authJsResult = await this.#getAuthClient(domainForSession).getTokenForConnection({
+        connection: options.connection,
+        loginHint: options.loginHint,
+        refreshToken: stateData.refreshToken,
+        fullResponse: true
+      }, requestOptions);
+      tokenEndpointResponse = authJsResult.data;
+      response = authJsResult.response;
+    } else {
+      tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenForConnection({
+        connection: options.connection,
+        loginHint: options.loginHint,
+        refreshToken: stateData.refreshToken
+      }, requestOptions);
+    }
     const updatedStateData = updateStateDataForConnectionTokenSet(
       options,
       {
@@ -1253,13 +1363,20 @@ var ServerClient = class {
       tokenEndpointResponse
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, storeOptions);
-    return {
+    const returnConnectionTokenSet = {
       accessToken: tokenEndpointResponse.accessToken,
       scope: tokenEndpointResponse.scope,
       expiresAt: tokenEndpointResponse.expiresAt,
       connection: options.connection,
       loginHint: options.loginHint
     };
+    if (options.fullResponse) {
+      if (!response) {
+        throw new MissingCapturedResponseError();
+      }
+      return { data: returnConnectionTokenSet, response };
+    }
+    return returnConnectionTokenSet;
   }
   /**
    * Revokes the refresh token stored in the current session, or an explicitly supplied token.
@@ -1271,12 +1388,13 @@ var ServerClient = class {
    *
    * @param options Optionally supply a token to revoke instead of reading from the session.
    * @param storeOptions Optional options passed to the StateStore.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the revocation request.
    *
    * @throws {MissingRequiredArgumentError} If `options.token` is an empty string.
    * @throws {MissingSessionError} If no refresh token is found in the session and none was provided.
    * @throws {TokenRevocationError} If the revocation request fails.
    */
-  async revokeRefreshToken(options = {}, storeOptions) {
+  async revokeRefreshToken(options = {}, storeOptions, requestOptions) {
     if (options.token !== void 0 && options.token.length === 0) {
       throw new MissingRequiredArgumentError("options.token must not be an empty string.");
     }
@@ -1300,18 +1418,19 @@ var ServerClient = class {
     } else {
       authClient = this.authClient;
     }
-    await authClient.revokeToken({ token: refreshToken, tokenTypeHint: "refresh_token" });
+    await authClient.revokeToken({ token: refreshToken, tokenTypeHint: "refresh_token" }, requestOptions);
   }
   /**
    * Logs the user out and returns a URL to redirect the user-agent to after they log out.
    * @param options Options used to configure the logout process.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the token revocation ONLY. Building the logout URL is local string work and issues no request, so nothing here can affect it.
    * @returns {URL}
    */
-  async logout(options, storeOptions) {
+  async logout(options, storeOptions, requestOptions) {
     if (!this.#isResolverMode()) {
       try {
-        await this.revokeRefreshToken({}, storeOptions);
+        await this.revokeRefreshToken({}, storeOptions, requestOptions);
       } catch {
       }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
@@ -1327,39 +1446,33 @@ var ServerClient = class {
     const domainMatches = sessionDomain === resolvedDomain;
     if (domainMatches) {
       try {
-        await this.revokeRefreshToken({}, storeOptions);
+        await this.revokeRefreshToken({}, storeOptions, requestOptions);
       } catch {
       }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
     }
     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) {
+  async loginWithCustomTokenExchange(options, storeOptions, requestOptions) {
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
-    const tokenEndpointResponse = await authClient.exchangeToken({
-      ...options,
-      scope: ensureOpenIdScope(options.scope)
-    });
+    let response;
+    let tokenEndpointResponse;
+    if (options.fullResponse) {
+      const { fullResponse: _, ...rest } = options;
+      const authJsResult = await authClient.exchangeToken({
+        ...rest,
+        scope: ensureOpenIdScope(options.scope),
+        fullResponse: true
+      }, requestOptions);
+      tokenEndpointResponse = authJsResult.data;
+      response = authJsResult.response;
+    } else {
+      tokenEndpointResponse = await authClient.exchangeToken({
+        ...options,
+        scope: ensureOpenIdScope(options.scope)
+      }, requestOptions);
+    }
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(
       this.#options.authorizationParams?.audience ?? "default",
@@ -1368,30 +1481,25 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
-    return { authorizationDetails: tokenEndpointResponse.authorizationDetails };
+    const result = {
+      authorizationDetails: tokenEndpointResponse.authorizationDetails
+    };
+    if (options.fullResponse) {
+      if (!response) {
+        throw new MissingCapturedResponseError();
+      }
+      return { data: result, response };
+    }
+    return result;
   }
-  /**
-   * 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) {
+  async customTokenExchange(options, storeOptions, requestOptions) {
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
-    return authClient.exchangeToken(options);
+    if (options.fullResponse) {
+      const { fullResponse: _, ...rest } = options;
+      return authClient.exchangeToken({ ...rest, fullResponse: true }, requestOptions);
+    }
+    return authClient.exchangeToken(options, requestOptions);
   }
   /**
    * Requests a Session Transfer Token (STT) for impersonation via session transfer (RFC 8693).
@@ -1415,8 +1523,17 @@ var ServerClient = class {
    * {@link ServerClient.buildSessionTransferRedirect}, which is forwarded to the target's
    * `/authorize` on the redirect.
    *
+   * @remarks
+   * If the actor's ID token has expired, an internal refresh is performed before the
+   * session transfer token exchange. This refresh call is NOT guarded by the caller's
+   * requestOptions.signal — if the signal fires during this step, the abort is ignored.
+   * Only the final exchangeToken call respects the signal.
+   * Thread requestOptions into #resolveSessionTransferActor in a future minor if
+   * callers need full-request abort coverage.
+   *
    * @param options Options including the developer-supplied `subjectToken`/`subjectTokenType` and an optional explicit `actor`.
    * @param storeOptions Optional options used to read the agent session (for the actor) and resolve the request domain.
+   * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the STT exchange only. Resolving the actor may refresh an expired agent session ID token, and that refresh is an internal call outside the caller's per-request scope, so it does not receive these options.
    *
    * @throws {TokenExchangeError} With code `actor_unavailable` when no explicit actor is given and no usable session ID token can be resolved — no logged-in agent, a session that belongs to a different domain in resolver mode, or an expired ID token that cannot be refreshed (raised client-side, before any network call). With the default code when the exchange itself fails; a server-side `setactor_required` or `session_transfer_disabled` condition is surfaced via `cause.error` / `cause.error_description`. An organization the tenant rejects also surfaces here.
    * @throws {MissingClientAuthError} When client credentials are not configured (STT requires a confidential client).
@@ -1425,7 +1542,7 @@ var ServerClient = class {
    *
    * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
    */
-  async requestSessionTransferToken(options, storeOptions) {
+  async requestSessionTransferToken(options, storeOptions, requestOptions) {
     if (!options.subjectToken || !options.subjectToken.trim()) {
       throw new MissingRequiredArgumentError("subjectToken");
     }
@@ -1451,7 +1568,7 @@ var ServerClient = class {
       // `/authorize`; neither implies the other.
       organization: options.organization,
       extra: options.extra
-    });
+    }, requestOptions);
     return {
       sessionTransferToken: response.accessToken,
       // Surface exactly what the server returned — never fabricate the URN, so a non-STT
@@ -1575,6 +1692,11 @@ var ServerClient = class {
   }
   /**
    * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
+   *
+   * This does not accept `RequestOptions`. Verification does fetch JWKS, but the auth-js method it
+   * delegates to, `verifyLogoutToken`, takes no `requestOptions`, so there is nothing to forward.
+   * That fetch always uses the client's configured `customFetch`.
+   *
    * @param logoutToken The logout token to verify and use to delete the session from the store.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
@@ -1734,7 +1856,8 @@ import {
   OrganizationValidationError as OrganizationValidationError3,
   PasswordlessStartError as PasswordlessStartError2,
   PasswordlessVerifyError as PasswordlessVerifyError2,
-  isMfaRequiredError as isMfaRequiredError2
+  isMfaRequiredError as isMfaRequiredError2,
+  UserInfoError
 } from "@auth0/auth0-auth-js";
 
 // src/store/cookie-transaction-store.ts
@@ -1984,6 +2107,7 @@ export {
   TokenExchangeError2 as TokenExchangeError,
   TokenExchangeErrorCode,
   TokenRevocationError,
+  UserInfoError,
   isMfaRequiredError2 as isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map