@auth0/auth0-server-js 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, 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, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, TelemetryConfig, TokenExchangeError, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
+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 { JWTPayload } from 'jose';
 
 /**
@@ -64,6 +64,12 @@ interface UserClaims {
     email_verified?: boolean;
     org_id?: string;
     org_name?: string;
+    /**
+     * The actor (`act`) claim, present when the session was established via impersonation
+     * (e.g. Custom Token Exchange Session Transfer). Identifies the acting party — read it
+     * to drive UI such as an impersonation banner.
+     */
+    act?: ActClaim;
     [key: string]: unknown;
 }
 interface AuthorizationParameters {
@@ -330,6 +336,13 @@ interface GetAccessTokenOptions {
      */
     scope?: string;
 }
+interface RevokeRefreshTokenOptions {
+    /**
+     * Explicitly provide a refresh token to revoke.
+     * If omitted, the token stored in the current session is used.
+     */
+    token?: string;
+}
 interface LogoutOptions {
     returnTo: string;
 }
@@ -408,6 +421,108 @@ interface LoginWithCustomTokenExchangeResult {
      */
     authorizationDetails?: AuthorizationDetails[];
 }
+/**
+ * An explicit actor (the acting party) for a Session Transfer Token request.
+ *
+ * Supplying this overrides the default behaviour of sourcing the actor from the
+ * current agent session's ID token.
+ */
+interface SessionTransferActor {
+    /**
+     * The actor token — for the default flow this is the agent's ID token.
+     */
+    token: string;
+    /**
+     * The actor token type URI. Defaults to the ID token URN when omitted
+     * (`urn:ietf:params:oauth:token-type:id_token`).
+     */
+    type?: string;
+}
+/**
+ * Options for requesting a Session Transfer Token (STT) for impersonation via
+ * session transfer (Custom Token Exchange Release 2).
+ *
+ * The SDK fills in the protocol plumbing (audience, grant type, and the actor token
+ * pair). The `subjectToken` is always developer-supplied — it is your own proof of
+ * which customer to impersonate, validated only by your Action.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 RFC 8693: OAuth 2.0 Token Exchange}
+ */
+interface RequestSessionTransferTokenOptions {
+    /**
+     * Your proof of which customer to impersonate — opaque to Auth0 and validated by
+     * your Action (which then calls `setUserById`). The SDK never produces it.
+     */
+    subjectToken: string;
+    /**
+     * A URI identifying the type of the subject token, routing the request to your
+     * Token Exchange Profile / Action.
+     */
+    subjectTokenType: string;
+    /**
+     * An explicit actor to override the default (the agent session's ID token).
+     *
+     * Resolution order: this explicit `actor` wins; otherwise the agent session's ID
+     * token is used (refreshed when expired); if neither is available the request fails
+     * client-side with a `TokenExchangeError` whose code is `actor_unavailable`, before
+     * any network call.
+     */
+    actor?: SessionTransferActor;
+    /**
+     * Space-separated list of OAuth 2.0 scopes to request for the session's tokens.
+     */
+    scope?: string;
+    /**
+     * Additional custom parameters forwarded to the token endpoint (and thus to your
+     * Action via `event.request.body`). Cannot override reserved OAuth parameters.
+     */
+    extra?: Record<string, string | string[]>;
+}
+/**
+ * Options for {@link ServerClient.buildSessionTransferRedirect}.
+ */
+interface BuildSessionTransferRedirectOptions {
+    /**
+     * The organization identifier to forward to the target's `/authorize` (as the
+     * `organization` query parameter). Required only when the STT was issued in an
+     * organization context.
+     */
+    organization?: string;
+}
+/**
+ * The result of requesting a Session Transfer Token (STT) for impersonation via
+ * session transfer (Custom Token Exchange).
+ *
+ * The STT is opaque, single-use, and short-lived (~60s). Hand it to
+ * {@link ServerClient.buildSessionTransferRedirect} and do not decode, cache, or persist
+ * it. The `act` claim is deliberately not on this result — it only appears on the tokens
+ * of the session established after the STT is redeemed at `/authorize`.
+ */
+interface SessionTransferTokenResult {
+    /**
+     * The opaque, single-use Session Transfer Token. Never decode, cache, or persist it.
+     */
+    sessionTransferToken: string;
+    /**
+     * The issued token type URI — the session-transfer URN
+     * (`urn:auth0:params:oauth:token-type:session_transfer_token`). Branch on this,
+     * never on {@link SessionTransferTokenResult.tokenType}.
+     */
+    issuedTokenType: string;
+    /**
+     * The token lifetime in seconds (typically ~60).
+     */
+    expiresIn: number;
+    /**
+     * The token type as returned by the server (typically `"N_A"`). Informational only —
+     * never branch on it.
+     */
+    tokenType?: string;
+    /**
+     * The granted scopes, when returned by the server.
+     */
+    scope?: string;
+}
 interface SessionCookieOptions {
     /**
      * The name of the session cookie.
@@ -602,6 +717,59 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
     getToken(options: GetTokenByPasskeyOptions, storeOptions?: TStoreOptions): Promise<PasskeyGetTokenResult>;
 }
 
+/**
+ * @internal
+ * Options for constructing a ServerDatabaseClient.
+ *
+ * Like the passkey client, the database client resolves the domain per call so
+ * it keeps working in resolver (multi-tenant) mode. It therefore receives the
+ * parent client's `resolveDomain` and `getAuthClient` helpers instead of a
+ * fixed domain/authClient. Unlike the MFA/passkey clients, it never touches the
+ * state store — signup and change-password write no session.
+ */
+interface ServerDatabaseClientOptions<TStoreOptions = unknown> {
+    resolveDomain: (storeOptions?: TStoreOptions) => Promise<string>;
+    getAuthClient: (domain: string) => AuthClient;
+}
+
+declare class ServerDatabaseClient<TStoreOptions = unknown> {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(options: ServerDatabaseClientOptions<TStoreOptions>);
+    /**
+     * Registers a new user in a database connection.
+     *
+     * Delegates to the underlying `AuthClient.database.signUp` without any session
+     * state modification. The caller is responsible for handling the returned user
+     * data as needed.
+     *
+     * @param options The signup options (email, password, connection, etc.).
+     * @param storeOptions Optional options used to resolve the domain (resolver mode).
+     *
+     * @throws {SignUpError} If there was an issue signing the user up.
+     *
+     * @returns A promise resolving to the created user result with a normalized `id` field.
+     */
+    signUp(options: SignUpOptions, storeOptions?: TStoreOptions): Promise<SignUpResult>;
+    /**
+     * Requests a password-change email for a database connection user.
+     *
+     * Delegates to the underlying `AuthClient.database.changePassword` without any
+     * session state modification. The caller is responsible for informing the user
+     * of the sent email as needed.
+     *
+     * @param options The password change options (email, connection, organization, etc.).
+     * @param storeOptions Optional options used to resolve the domain (resolver mode).
+     *
+     * @throws {ChangePasswordError} If there was an issue requesting the password change.
+     *
+     * @returns A promise resolving to the server's plain-text confirmation message.
+     */
+    changePassword(options: ChangePasswordOptions, storeOptions?: TStoreOptions): Promise<string>;
+}
+
 declare class ServerClient<TStoreOptions = unknown> {
     #private;
     /**
@@ -639,6 +807,19 @@ declare class ServerClient<TStoreOptions = unknown> {
      * and `getToken()` so the credential is exchanged against the tenant that issued it.
      */
     get passkey(): ServerPasskeyClient<TStoreOptions>;
+    /**
+     * The database client for self-service sign-up and password-change requests
+     * against an Auth0 database connection.
+     *
+     * Provides `signUp()` to register a user and `changePassword()` to request a
+     * password-reset email. Both are pure passthrough operations to the Auth0
+     * Authentication API — they never read or write the session/state store.
+     *
+     * Like `passkey`, this property is available in both static and resolver
+     * (multi-tenant) domain modes. In resolver mode, pass `storeOptions` so the
+     * request resolves the intended tenant.
+     */
+    get database(): ServerDatabaseClient<TStoreOptions>;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
@@ -850,6 +1031,22 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns The Connection Token Set, containing the access token for the connection, as well as additional information.
      */
     getAccessTokenForConnection(options: AccessTokenForConnectionOptions, storeOptions?: TStoreOptions): Promise<ConnectionTokenSet>;
+    /**
+     * Revokes the refresh token stored in the current session, or an explicitly supplied token.
+     *
+     * In resolver mode, revocation only occurs when the session domain matches the domain resolved
+     * for the current request. If the domains differ (or the session has no stored domain), the call
+     * returns without revoking to avoid sending a token to the wrong tenant. This guard applies even
+     * when a token is passed explicitly via `options.token`.
+     *
+     * @param options Optionally supply a token to revoke instead of reading from the session.
+     * @param storeOptions Optional options passed to the StateStore.
+     *
+     * @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>;
     /**
      * 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.
@@ -896,6 +1093,54 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns A promise resolving to the token response from Auth0.
      */
     customTokenExchange(options: CustomTokenExchangeOptions, storeOptions?: TStoreOptions): Promise<TokenResponse>;
+    /**
+     * Requests a Session Transfer Token (STT) for impersonation via session transfer (RFC 8693).
+     *
+     * Performs a Custom Token Exchange against the `urn:{domain}:session_transfer` audience and
+     * returns the resulting STT. The audience is built from the SDK's resolved request domain, so
+     * it is correct under multiple custom domains. The returned STT is opaque and single-use — hand
+     * it to {@link ServerClient.buildSessionTransferRedirect} and do not decode, cache, or persist
+     * it. This method writes nothing to the state store for the STT itself; the `act` claim is not
+     * on the result — it only appears on the target session's tokens once the STT is redeemed.
+     *
+     * An actor is mandatory for an STT (this is what makes it auditable impersonation). It is
+     * resolved in this order: an explicit `options.actor` wins; otherwise the current agent
+     * session's ID token is used, refreshed when it has expired; if neither is available the method
+     * throws before any network call.
+     *
+     * @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.
+     *
+     * @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`.
+     * @throws {MissingClientAuthError} When client credentials are not configured (STT requires a confidential client).
+     * @throws {MissingRequiredArgumentError} When `subjectToken` or `subjectTokenType` is missing or blank (raised before any session read or network call).
+     *
+     * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
+     */
+    requestSessionTransferToken(options: RequestSessionTransferTokenOptions, storeOptions?: TStoreOptions): Promise<SessionTransferTokenResult>;
+    /**
+     * Builds the redirect URL that hands a Session Transfer Token (STT) to the target app's login URL.
+     *
+     * Returns `targetLoginUrl` with `session_transfer_token` (and `organization`, when provided)
+     * appended as query parameters, URL-encoded. This performs no network call and writes nothing
+     * to the session — it only builds a string. The developer hands the returned URL to their
+     * framework's redirect.
+     *
+     * `targetLoginUrl` attaches a single-use credential, so it must be a trusted, app-controlled
+     * value — never derived from untrusted input (e.g. a `returnTo`), or the token could leak to an
+     * attacker host. To harden against that, the URL must be absolute and use `https:` (an `http:`
+     * URL is accepted only for `localhost` / loopback, to support local development).
+     *
+     * @param targetLoginUrl The target app's login URL (absolute, https).
+     * @param result The {@link SessionTransferTokenResult} from {@link ServerClient.requestSessionTransferToken}.
+     * @param options Optional options, e.g. the `organization` to forward when the STT is org-scoped.
+     *
+     * @throws {MissingRequiredArgumentError} When `targetLoginUrl` is missing or blank.
+     * @throws {InvalidConfigurationError} When `targetLoginUrl` is not an absolute URL, or does not use `https:` (except for loopback hosts).
+     *
+     * @returns A {@link URL} with the STT (and optional organization) as query parameters.
+     */
+    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.
      * @param logoutToken The logout token to verify and use to delete the session from the store.
@@ -1033,6 +1278,31 @@ declare class StatelessStateStore<TStoreOptions> extends AbstractSessionStore<TS
     private getCookieKeys;
 }
 
+/**
+ * Codes carried on the `code` field of a `TokenExchangeError` raised by the Session
+ * Transfer Token (STT) flow. These are specific to Custom Token Exchange Impersonation
+ * via Session Transfer:
+ *
+ * - `actor_unavailable` — raised client-side, before any network call, when a Session
+ *   Transfer Token is requested but no actor could be resolved (no explicit actor and
+ *   no usable session ID token).
+ * - `setactor_required` — the server rejected the exchange because the Action did not
+ *   call `setActor` (an actor is mandatory for a Session Transfer Token).
+ * - `session_transfer_disabled` — the server rejected the exchange because the tenant
+ *   feature flag is off.
+ *
+ * Only `actor_unavailable` is raised by the SDK itself. `setactor_required` and
+ * `session_transfer_disabled` are surfaced from the raw server response via the
+ * error's `cause.error` / `cause.error_description`; they are defined here as named
+ * constants for documentation and for the day the platform returns a machine-readable
+ * code.
+ */
+declare const TokenExchangeErrorCode: {
+    readonly ACTOR_UNAVAILABLE: "actor_unavailable";
+    readonly SETACTOR_REQUIRED: "setactor_required";
+    readonly SESSION_TRANSFER_DISABLED: "session_transfer_disabled";
+};
+type TokenExchangeErrorCode = (typeof TokenExchangeErrorCode)[keyof typeof TokenExchangeErrorCode];
 /**
  * Error thrown when there is no transaction available.
  */
@@ -1091,4 +1361,4 @@ declare class SessionExpiredError extends Error {
     constructor(message?: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type CompletePasswordlessEmailOptions, type CompletePasswordlessOptions, type CompletePasswordlessResult, type CompletePasswordlessSmsOptions, 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, type PasskeyGetTokenResult, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, 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 BuildSessionTransferRedirectOptions, type CompletePasswordlessEmailOptions, type CompletePasswordlessOptions, type CompletePasswordlessResult, type CompletePasswordlessSmsOptions, 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, type PasskeyGetTokenResult, type RequestSessionTransferTokenOptions, type RevokeRefreshTokenOptions, ServerClient, type ServerClientOptions, ServerDatabaseClient, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type SessionTransferActor, type SessionTransferTokenResult, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, TokenExchangeErrorCode, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };