@auth0/auth0-server-js 1.12.1 → 1.13.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { ActClaim, AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, SignUpOptions, SignUpResult, ChangePasswordOptions, TokenResponse } from '@auth0/auth0-auth-js';
-export { ActClaim, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, ChangePasswordError, ChangePasswordOptions, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, PasswordlessStartError, PasswordlessVerifyError, SignUpError, SignUpOptions, SignUpResult, TelemetryConfig, TokenExchangeError, TokenResponse, TokenRevocationError, isMfaRequiredError } from '@auth0/auth0-auth-js';
+import { ActClaim, AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, RequestOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, SignUpOptions, SignUpResult, ChangePasswordOptions, ApiResponse, GetUserInfoOptions, UserInfoResponse, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, ApiResponse, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, ChangePasswordError, ChangePasswordOptions, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, FullResponseOption, GetUserInfoOptions, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, PasswordlessStartError, PasswordlessVerifyError, RequestOptions, SignUpError, SignUpOptions, SignUpResult, TelemetryConfig, TokenExchangeError, TokenResponse, TokenRevocationError, UserInfoError, UserInfoResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -624,7 +624,7 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
      * @returns Promise resolving to an array of enrolled authenticators
      * @throws {MfaListAuthenticatorsError} When the request fails
      */
-    listAuthenticators(options: ListAuthenticatorsOptions): Promise<AuthenticatorResponse[]>;
+    listAuthenticators(options: ListAuthenticatorsOptions, requestOptions?: RequestOptions): Promise<AuthenticatorResponse[]>;
     /**
      * Enrolls a new MFA authenticator for the user.
      *
@@ -632,7 +632,7 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
      * @returns Promise resolving to enrollment response with authenticator details
      * @throws {MfaEnrollmentError} When enrollment fails
      */
-    enrollAuthenticator(options: EnrollAuthenticatorOptions): Promise<EnrollmentResponse>;
+    enrollAuthenticator(options: EnrollAuthenticatorOptions, requestOptions?: RequestOptions): Promise<EnrollmentResponse>;
     /**
      * Initiates an MFA challenge for user verification.
      *
@@ -640,7 +640,7 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
      * @returns Promise resolving to challenge response with challenge details
      * @throws {MfaChallengeError} When the challenge fails
      */
-    challengeAuthenticator(options: ChallengeOptions): Promise<ChallengeResponse>;
+    challengeAuthenticator(options: ChallengeOptions, requestOptions?: RequestOptions): Promise<ChallengeResponse>;
     /**
      * Verifies an MFA challenge and completes the authentication flow.
      *
@@ -653,7 +653,7 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
      * @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>;
+    verify(options: MfaVerifyOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<MfaVerifyResponse>;
 }
 
 /**
@@ -703,7 +703,7 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to the signup challenge.
      */
-    register(options: PasskeySignupChallengeOptions, storeOptions?: TStoreOptions): Promise<PasskeySignupChallengeResponse>;
+    register(options: PasskeySignupChallengeOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<PasskeySignupChallengeResponse>;
     /**
      * Requests a passkey login challenge for an existing user.
      *
@@ -724,7 +724,7 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to the login challenge.
      */
-    challenge(options?: PasskeyLoginChallengeOptions, storeOptions?: TStoreOptions): Promise<PasskeyLoginChallengeResponse>;
+    challenge(options?: PasskeyLoginChallengeOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<PasskeyLoginChallengeResponse>;
     /**
      * Completes a passkey authentication flow (signup or login) by exchanging the
      * WebAuthn credential for tokens, and persists the resulting session.
@@ -745,7 +745,7 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to an object containing the authorizationDetails (when RAR was used).
      */
-    getToken(options: GetTokenByPasskeyOptions, storeOptions?: TStoreOptions): Promise<PasskeyGetTokenResult>;
+    getToken(options: GetTokenByPasskeyOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<PasskeyGetTokenResult>;
 }
 
 /**
@@ -783,7 +783,7 @@ declare class ServerDatabaseClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to the created user result with a normalized `id` field.
      */
-    signUp(options: SignUpOptions, storeOptions?: TStoreOptions): Promise<SignUpResult>;
+    signUp(options: SignUpOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<SignUpResult>;
     /**
      * Requests a password-change email for a database connection user.
      *
@@ -798,7 +798,7 @@ declare class ServerDatabaseClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to the server's plain-text confirmation message.
      */
-    changePassword(options: ChangePasswordOptions, storeOptions?: TStoreOptions): Promise<string>;
+    changePassword(options: ChangePasswordOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<string>;
 }
 
 declare class ServerClient<TStoreOptions = unknown> {
@@ -874,6 +874,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      * 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.
@@ -881,8 +882,15 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @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.
      */
-    completeInteractiveLogin<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions): Promise<{
+    completeInteractiveLogin<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<{
         appState?: TAppState;
         authorizationDetails?: AuthorizationDetails[];
     }>;
@@ -903,13 +911,14 @@ declare class ServerClient<TStoreOptions = unknown> {
      * 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).
      */
-    completeLinkUser<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions): Promise<{
+    completeLinkUser<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<{
         appState: TAppState | undefined;
     }>;
     /**
@@ -929,13 +938,14 @@ declare class ServerClient<TStoreOptions = unknown> {
      * 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).
      */
-    completeUnlinkUser<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions): Promise<{
+    completeUnlinkUser<TAppState = unknown>(url: URL, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<{
         appState: TAppState | undefined;
     }>;
     /**
@@ -945,13 +955,17 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @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.
+     * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the backchannel authorize request and the token polling that follows it.
      *
      * @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).
      */
-    loginBackchannel(options: LoginBackchannelOptions, storeOptions?: TStoreOptions): Promise<LoginBackchannelResult>;
+    loginBackchannel(options: LoginBackchannelOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<LoginBackchannelResult>>;
+    loginBackchannel(options: LoginBackchannelOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<LoginBackchannelResult>;
     /**
      * Starts a passwordless flow by sending a one-time code (OTP) or a magic link.
      *
@@ -973,6 +987,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @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`.
      *
@@ -989,7 +1004,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *   redirectUri: 'https://app.example.com/auth/callback',
      * });
      */
-    startPasswordless(options: StartPasswordlessOptions, storeOptions?: TStoreOptions): Promise<void>;
+    startPasswordless(options: StartPasswordlessOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<void>;
     /**
      * Completes a passwordless OTP login and persists the resulting session.
      *
@@ -1003,6 +1018,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @param options Discriminated completion options (`connection`, identifier, `verificationCode`).
      * @param storeOptions Optional options passed to the resolver / stores.
+     * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the token request.
      *
      * @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
@@ -1010,7 +1026,10 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to the authorizationDetails (when RAR was used).
      */
-    completePasswordless(options: CompletePasswordlessOptions, storeOptions?: TStoreOptions): Promise<CompletePasswordlessResult>;
+    completePasswordless(options: CompletePasswordlessOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<CompletePasswordlessResult>>;
+    completePasswordless(options: CompletePasswordlessOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<CompletePasswordlessResult>;
     /**
      * Completes a passwordless magic-link login and persists the resulting session.
      *
@@ -1021,6 +1040,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @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.
@@ -1031,9 +1051,15 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @example
      * const result = await serverClient.completePasswordlessMagicLink(callbackUrl, storeOptions);
      */
-    completePasswordlessMagicLink(url: URL, storeOptions?: TStoreOptions): Promise<CompletePasswordlessResult>;
+    completePasswordlessMagicLink(url: URL, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<CompletePasswordlessResult>;
     /**
      * 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.
      */
@@ -1044,8 +1070,35 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns The session or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
+    /**
+     * 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.
+     */
+    getUserInfo(options: GetUserInfoOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<UserInfoResponse>;
+    getAccessToken(options: GetAccessTokenOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<TokenSet>>;
     getAccessToken(storeOptions?: TStoreOptions): Promise<TokenSet>;
-    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions): Promise<TokenSet>;
+    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<TokenSet>;
     /**
      * Retrieves an access token for a connection.
      *
@@ -1056,12 +1109,16 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @param options - Options for retrieving an access token for a connection.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
+     * @param requestOptions Optional per-request options (signal, headers, customFetch). A cache hit returns before any network call, so `requestOptions` (including `signal`) is a no-op on that path; it applies only to the Token Vault exchange on a cache miss.
      *
      * @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.
      */
-    getAccessTokenForConnection(options: AccessTokenForConnectionOptions, storeOptions?: TStoreOptions): Promise<ConnectionTokenSet>;
+    getAccessTokenForConnection(options: AccessTokenForConnectionOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<ConnectionTokenSet>>;
+    getAccessTokenForConnection(options: AccessTokenForConnectionOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ConnectionTokenSet>;
     /**
      * Revokes the refresh token stored in the current session, or an explicitly supplied token.
      *
@@ -1072,19 +1129,21 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @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.
      */
-    revokeRefreshToken(options?: RevokeRefreshTokenOptions, storeOptions?: TStoreOptions): Promise<void>;
+    revokeRefreshToken(options?: RevokeRefreshTokenOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<void>;
     /**
      * 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}
      */
-    logout(options: LogoutOptions, storeOptions?: TStoreOptions): Promise<URL>;
+    logout(options: LogoutOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<URL>;
     /**
      * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
      *
@@ -1098,13 +1157,17 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @param options Options for the custom token exchange, including the subject token and its type.
      * @param storeOptions Optional options passed to the StateStore.
+     * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the token exchange.
      *
      * @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>;
+    loginWithCustomTokenExchange(options: LoginWithCustomTokenExchangeOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<LoginWithCustomTokenExchangeResult>>;
+    loginWithCustomTokenExchange(options: LoginWithCustomTokenExchangeOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<LoginWithCustomTokenExchangeResult>;
     /**
      * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
      *
@@ -1117,13 +1180,17 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @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).
+     * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the token exchange.
      *
      * @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>;
+    customTokenExchange(options: CustomTokenExchangeOptions & {
+        fullResponse: true;
+    }, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<ApiResponse<TokenResponse>>;
+    customTokenExchange(options: CustomTokenExchangeOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<TokenResponse>;
     /**
      * Requests a Session Transfer Token (STT) for impersonation via session transfer (RFC 8693).
      *
@@ -1146,8 +1213,17 @@ declare class ServerClient<TStoreOptions = unknown> {
      * {@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).
@@ -1156,7 +1232,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
      */
-    requestSessionTransferToken(options: RequestSessionTransferTokenOptions, storeOptions?: TStoreOptions): Promise<SessionTransferTokenResult>;
+    requestSessionTransferToken(options: RequestSessionTransferTokenOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<SessionTransferTokenResult>;
     /**
      * Builds the redirect URL that hands a Session Transfer Token (STT) to the target app's login URL.
      *
@@ -1182,6 +1258,11 @@ declare class ServerClient<TStoreOptions = unknown> {
     buildSessionTransferRedirect(targetLoginUrl: string, result: SessionTransferTokenResult, options?: BuildSessionTransferRedirectOptions): URL;
     /**
      * 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.
      *