@auth0/auth0-server-js 1.5.0 → 1.6.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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 { ExchangeProfileOptions, AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OtpEnrollmentResponse, TelemetryConfig, TokenExchangeError, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -217,6 +217,33 @@ interface SessionStore<TStoreOptions> {
     get(identifier: string): Promise<StateData | undefined>;
     deleteByLogoutToken(claims: LogoutTokenClaims, options?: TStoreOptions | undefined): Promise<void>;
 }
+/**
+ * Options for exchanging a custom token and persisting the resulting session (RFC 8693).
+ *
+ * Mirrors `ExchangeProfileOptions` from `auth0-auth-js`. The `audience` field is
+ * also used to key the token set stored in the session.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type LoginWithCustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Options for performing a custom token exchange without any session side effects (RFC 8693).
+ *
+ * Use this when you need delegated tokens for downstream service calls but do not want
+ * to establish a user session (e.g. impersonation, service-to-service delegation).
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type CustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Result of a successful custom token exchange with session persistence.
+ */
+interface LoginWithCustomTokenExchangeResult {
+    /**
+     * Authorization details returned by the token endpoint when RAR was used.
+     */
+    authorizationDetails?: AuthorizationDetails[];
+}
 interface SessionCookieOptions {
     /**
      * The name of the session cookie.
@@ -488,6 +515,45 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns {URL}
      */
     logout(options: LogoutOptions, storeOptions?: TStoreOptions): Promise<URL>;
+    /**
+     * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
+     *
+     * Calls the token endpoint using the RFC 8693 Token Exchange grant, then stores the
+     * resulting tokens in the StateStore — effectively logging the user in without an
+     * interactive browser flow. Use this when the caller already holds a trusted external
+     * token (e.g. a Google ID token, a legacy system token) and wants to establish an
+     * Auth0 session from it.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore.
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to an object containing `authorizationDetails` when RAR was used.
+     */
+    loginWithCustomTokenExchange(options: LoginWithCustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<LoginWithCustomTokenExchangeResult>;
+    /**
+     * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
+     *
+     * Performs the same RFC 8693 Token Exchange as `loginWithCustomTokenExchange` but
+     * returns the raw token response without writing anything to the StateStore. Use this
+     * for delegation or impersonation flows where you need downstream tokens but do not
+     * want to create or modify the current user session.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore (used only for domain resolution in resolver mode).
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to the token response from Auth0.
+     */
+    customTokenExchange(options: CustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<TokenResponse>;
     /**
      * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
      * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -674,4 +740,4 @@ declare class IssuerValidationError extends Error {
     constructor(message: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, 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 };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, ServerMfaClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { ExchangeProfileOptions, AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OtpEnrollmentResponse, TelemetryConfig, TokenExchangeError, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -217,6 +217,33 @@ interface SessionStore<TStoreOptions> {
     get(identifier: string): Promise<StateData | undefined>;
     deleteByLogoutToken(claims: LogoutTokenClaims, options?: TStoreOptions | undefined): Promise<void>;
 }
+/**
+ * Options for exchanging a custom token and persisting the resulting session (RFC 8693).
+ *
+ * Mirrors `ExchangeProfileOptions` from `auth0-auth-js`. The `audience` field is
+ * also used to key the token set stored in the session.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type LoginWithCustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Options for performing a custom token exchange without any session side effects (RFC 8693).
+ *
+ * Use this when you need delegated tokens for downstream service calls but do not want
+ * to establish a user session (e.g. impersonation, service-to-service delegation).
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+type CustomTokenExchangeOptions = ExchangeProfileOptions;
+/**
+ * Result of a successful custom token exchange with session persistence.
+ */
+interface LoginWithCustomTokenExchangeResult {
+    /**
+     * Authorization details returned by the token endpoint when RAR was used.
+     */
+    authorizationDetails?: AuthorizationDetails[];
+}
 interface SessionCookieOptions {
     /**
      * The name of the session cookie.
@@ -488,6 +515,45 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns {URL}
      */
     logout(options: LogoutOptions, storeOptions?: TStoreOptions): Promise<URL>;
+    /**
+     * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
+     *
+     * Calls the token endpoint using the RFC 8693 Token Exchange grant, then stores the
+     * resulting tokens in the StateStore — effectively logging the user in without an
+     * interactive browser flow. Use this when the caller already holds a trusted external
+     * token (e.g. a Google ID token, a legacy system token) and wants to establish an
+     * Auth0 session from it.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore.
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to an object containing `authorizationDetails` when RAR was used.
+     */
+    loginWithCustomTokenExchange(options: LoginWithCustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<LoginWithCustomTokenExchangeResult>;
+    /**
+     * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
+     *
+     * Performs the same RFC 8693 Token Exchange as `loginWithCustomTokenExchange` but
+     * returns the raw token response without writing anything to the StateStore. Use this
+     * for delegation or impersonation flows where you need downstream tokens but do not
+     * want to create or modify the current user session.
+     *
+     * Requires a Token Exchange Profile configured in your Auth0 tenant.
+     *
+     * @param options Options for the custom token exchange, including the subject token and its type.
+     * @param storeOptions Optional options passed to the StateStore (used only for domain resolution in resolver mode).
+     *
+     * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+     * @throws {MissingClientAuthError} If client credentials are not configured.
+     *
+     * @returns A promise resolving to the token response from Auth0.
+     */
+    customTokenExchange(options: CustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<TokenResponse>;
     /**
      * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
      * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -674,4 +740,4 @@ declare class IssuerValidationError extends Error {
     constructor(message: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, 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 };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, ServerMfaClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.js

@@ -149,7 +149,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.5.0"
+    version: config?.version ?? "1.6.1"
   };
 }
 
@@ -786,6 +786,65 @@ var ServerClient = class {
     }
     return authClient.buildLogoutUrl(options);
   }
+  /**
+   * Exchanges a custom token for Auth0 tokens and persists the resulting session (RFC 8693).
+   *
+   * Calls the token endpoint using the RFC 8693 Token Exchange grant, then stores the
+   * resulting tokens in the StateStore — effectively logging the user in without an
+   * interactive browser flow. Use this when the caller already holds a trusted external
+   * token (e.g. a Google ID token, a legacy system token) and wants to establish an
+   * Auth0 session from it.
+   *
+   * Requires a Token Exchange Profile configured in your Auth0 tenant.
+   *
+   * @param options Options for the custom token exchange, including the subject token and its type.
+   * @param storeOptions Optional options passed to the StateStore.
+   *
+   * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+   * @throws {MissingClientAuthError} If client credentials are not configured.
+   *
+   * @returns A promise resolving to an object containing `authorizationDetails` when RAR was used.
+   */
+  async loginWithCustomTokenExchange(options, storeOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    const tokenEndpointResponse = await authClient.exchangeToken({
+      ...options,
+      scope: ensureOpenIdScope(options.scope)
+    });
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const stateData = updateStateData(
+      this.#options.authorizationParams?.audience ?? "default",
+      existingStateData,
+      tokenEndpointResponse,
+      { domain }
+    );
+    await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    return { authorizationDetails: tokenEndpointResponse.authorizationDetails };
+  }
+  /**
+   * Exchanges a custom token for Auth0 tokens without establishing a session (RFC 8693).
+   *
+   * Performs the same RFC 8693 Token Exchange as `loginWithCustomTokenExchange` but
+   * returns the raw token response without writing anything to the StateStore. Use this
+   * for delegation or impersonation flows where you need downstream tokens but do not
+   * want to create or modify the current user session.
+   *
+   * Requires a Token Exchange Profile configured in your Auth0 tenant.
+   *
+   * @param options Options for the custom token exchange, including the subject token and its type.
+   * @param storeOptions Optional options passed to the StateStore (used only for domain resolution in resolver mode).
+   *
+   * @throws {TokenExchangeError} If the exchange fails or the subject token is invalid.
+   * @throws {MissingClientAuthError} If client credentials are not configured.
+   *
+   * @returns A promise resolving to the token response from Auth0.
+   */
+  async customTokenExchange(options, storeOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    return authClient.exchangeToken(options);
+  }
   /**
    * Handles the backchannel logout process by verifying the logout token and deleting the session from the store if the logout token was considered valid.
    * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -939,6 +998,9 @@ var AbstractTransactionStore = class extends AbstractStore {
   }
 };
 
+// src/index.ts
+import { TokenExchangeError, MissingClientAuthError } from "@auth0/auth0-auth-js";
+
 // src/store/cookie-transaction-store.ts
 var CookieTransactionStore = class extends AbstractTransactionStore {
   #cookieHandler;
@@ -1152,6 +1214,7 @@ export {
   MfaEnrollmentError,
   MfaListAuthenticatorsError,
   MfaVerifyError,
+  MissingClientAuthError,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
@@ -1160,6 +1223,7 @@ export {
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,
+  TokenExchangeError,
   isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map