@auth0/auth0-server-js 1.9.0 → 1.11.0

package/dist/index.js

@@ -1,4 +1,9 @@
 // src/errors.ts
+var TokenExchangeErrorCode = {
+  ACTOR_UNAVAILABLE: "actor_unavailable",
+  SETACTOR_REQUIRED: "setactor_required",
+  SESSION_TRANSFER_DISABLED: "session_transfer_disabled"
+};
 var MissingTransactionError = class extends Error {
   code = "missing_transaction_error";
   constructor(message) {
@@ -166,7 +171,8 @@ import {
   OrganizationValidationError,
   PasswordlessStartError,
   PasswordlessVerifyError,
-  TokenByRefreshTokenError
+  TokenByRefreshTokenError,
+  TokenExchangeError
 } from "@auth0/auth0-auth-js";
 
 // src/utils.ts
@@ -205,7 +211,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.9.0"
+    version: config?.version ?? "1.11.0"
   };
 }
 
@@ -384,6 +390,53 @@ var ServerPasskeyClient = class {
   }
 };
 
+// src/database/server-database-client.ts
+var ServerDatabaseClient = class {
+  #options;
+  /**
+   * @internal
+   */
+  constructor(options) {
+    this.#options = options;
+  }
+  /**
+   * 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.
+   */
+  async signUp(options, storeOptions) {
+    const domain = await this.#options.resolveDomain(storeOptions);
+    return this.#options.getAuthClient(domain).database.signUp(options);
+  }
+  /**
+   * 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.
+   */
+  async changePassword(options, storeOptions) {
+    const domain = await this.#options.resolveDomain(storeOptions);
+    return this.#options.getAuthClient(domain).database.changePassword(options);
+  }
+};
+
 // src/server-client.ts
 var normalizeDomain = (value) => {
   const trimmed = value.trim();
@@ -398,6 +451,24 @@ var decodeIssuer = (token) => {
     return void 0;
   }
 };
+var ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token";
+var ID_TOKEN_EXPIRY_SKEW_SECONDS = 30;
+var actorUnavailableError = (message) => {
+  const error = new TokenExchangeError(message);
+  error.code = TokenExchangeErrorCode.ACTOR_UNAVAILABLE;
+  return error;
+};
+var isTokenExpired = (token) => {
+  try {
+    const { exp } = decodeJwt(token);
+    if (typeof exp !== "number") {
+      return true;
+    }
+    return exp <= Date.now() / 1e3 + ID_TOKEN_EXPIRY_SKEW_SECONDS;
+  } catch {
+    return true;
+  }
+};
 var ServerClient = class {
   #options;
   #transactionStore;
@@ -409,6 +480,7 @@ var ServerClient = class {
   #authClient;
   #mfaClient;
   #passkeyClient;
+  #databaseClient;
   /**
    * The underlying `authClient` instance that can be used to interact with the Auth0 Authentication API.
    * Generally, you should prefer to use the higher-level methods exposed on the `ServerClient` instance.
@@ -456,6 +528,21 @@ var ServerClient = class {
   get passkey() {
     return this.#passkeyClient;
   }
+  /**
+   * 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() {
+    return this.#databaseClient;
+  }
   constructor(options) {
     this.#options = options;
     this.#stateStoreIdentifier = this.#options.stateIdentifier || "__a0_session";
@@ -505,6 +592,10 @@ var ServerClient = class {
       defaultScope: this.#options.authorizationParams?.scope,
       defaultAudience: this.#options.authorizationParams?.audience
     });
+    this.#databaseClient = new ServerDatabaseClient({
+      resolveDomain: (storeOptions) => this.#resolveDomain(storeOptions),
+      getAuthClient: (domain) => this.#getAuthClient(domain)
+    });
   }
   async #resolveDomain(storeOptions) {
     if (typeof this.#options.domain === "function") {
@@ -1170,6 +1261,47 @@ var ServerClient = class {
       loginHint: options.loginHint
     };
   }
+  /**
+   * 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.
+   */
+  async revokeRefreshToken(options = {}, storeOptions) {
+    if (options.token !== void 0 && options.token.length === 0) {
+      throw new MissingRequiredArgumentError("options.token must not be an empty string.");
+    }
+    let refreshToken = options.token;
+    const needsStateData = !refreshToken || this.#isResolverMode();
+    const stateData = needsStateData ? await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions) : void 0;
+    if (!refreshToken) {
+      refreshToken = stateData?.refreshToken;
+    }
+    if (!refreshToken) {
+      throw new MissingSessionError("Unable to revoke refresh token: no refresh token found in session.");
+    }
+    let authClient;
+    if (this.#isResolverMode()) {
+      const resolvedDomain = await this.#resolveDomain(storeOptions);
+      const sessionDomain = stateData ? this.#getSessionDomain(stateData) : void 0;
+      if (stateData && sessionDomain !== resolvedDomain) {
+        return;
+      }
+      authClient = this.#getAuthClient(sessionDomain ?? resolvedDomain);
+    } else {
+      authClient = this.authClient;
+    }
+    await authClient.revokeToken({ token: refreshToken, tokenTypeHint: "refresh_token" });
+  }
   /**
    * 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.
@@ -1178,17 +1310,26 @@ var ServerClient = class {
    */
   async logout(options, storeOptions) {
     if (!this.#isResolverMode()) {
+      try {
+        await this.revokeRefreshToken({}, storeOptions);
+      } catch {
+      }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
       return this.authClient.buildLogoutUrl(options);
     }
     const resolvedDomain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(resolvedDomain);
     const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
-    const sessionDomain = stateData ? this.#getSessionDomain(stateData) : void 0;
     if (!stateData) {
       return authClient.buildLogoutUrl(options);
     }
-    if (sessionDomain && sessionDomain === resolvedDomain) {
+    const sessionDomain = this.#getSessionDomain(stateData);
+    const domainMatches = sessionDomain === resolvedDomain;
+    if (domainMatches) {
+      try {
+        await this.revokeRefreshToken({}, storeOptions);
+      } catch {
+      }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
     }
     return authClient.buildLogoutUrl(options);
@@ -1252,6 +1393,170 @@ var ServerClient = class {
     const authClient = this.#getAuthClient(domain);
     return authClient.exchangeToken(options);
   }
+  /**
+   * 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.
+   */
+  async requestSessionTransferToken(options, storeOptions) {
+    if (!options.subjectToken || !options.subjectToken.trim()) {
+      throw new MissingRequiredArgumentError("subjectToken");
+    }
+    if (!options.subjectTokenType || !options.subjectTokenType.trim()) {
+      throw new MissingRequiredArgumentError("subjectTokenType");
+    }
+    const domain = await this.#resolveDomain(storeOptions);
+    const actor = await this.#resolveSessionTransferActor(options.actor, domain, storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    const response = await authClient.exchangeToken({
+      subjectToken: options.subjectToken,
+      subjectTokenType: options.subjectTokenType,
+      audience: `urn:${domain}:session_transfer`,
+      scope: options.scope,
+      actorToken: actor.token,
+      actorTokenType: actor.type,
+      extra: options.extra
+    });
+    return {
+      sessionTransferToken: response.accessToken,
+      // Surface exactly what the server returned — never fabricate the URN, so a non-STT
+      // response is not mislabelled as an STT.
+      issuedTokenType: response.issuedTokenType ?? "",
+      // `expiresAt` is NaN when the server omitted `expires_in`; fall back to 0 rather than
+      // surfacing NaN to callers.
+      expiresIn: Number.isFinite(response.expiresAt) ? Math.max(0, Math.floor(response.expiresAt - Date.now() / 1e3)) : 0,
+      tokenType: response.tokenType,
+      scope: response.scope
+    };
+  }
+  /**
+   * 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, result, options) {
+    if (!targetLoginUrl || !targetLoginUrl.trim()) {
+      throw new MissingRequiredArgumentError("targetLoginUrl");
+    }
+    let url;
+    try {
+      url = new URL(targetLoginUrl);
+    } catch {
+      throw new InvalidConfigurationError(
+        "targetLoginUrl must be an absolute URL (e.g. https://app.example.com/auth/login)."
+      );
+    }
+    const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+      throw new InvalidConfigurationError(
+        "targetLoginUrl must use https (http is allowed only for localhost/loopback). The session transfer token is a single-use credential and must not be sent over an insecure or untrusted URL."
+      );
+    }
+    url.searchParams.set("session_transfer_token", result.sessionTransferToken);
+    if (options?.organization !== void 0) {
+      if (!options.organization.trim()) {
+        throw new OrganizationValidationError("organization must not be blank");
+      }
+      url.searchParams.set("organization", options.organization);
+    }
+    return url;
+  }
+  /**
+   * Resolves the actor token for a Session Transfer Token request.
+   *
+   * An explicit actor wins. Otherwise the agent session's ID token is used, refreshed when it has
+   * expired (and the refreshed session is persisted so the agent session stays coherent). If no
+   * usable ID token can be obtained, throws a `TokenExchangeError` with code `actor_unavailable`
+   * before any exchange is attempted.
+   */
+  async #resolveSessionTransferActor(actor, domain, storeOptions) {
+    if (actor !== void 0) {
+      if (!actor.token || !actor.token.trim()) {
+        throw actorUnavailableError(
+          "Unable to resolve an actor for the session transfer token: an explicit actor was provided but its token is blank. Pass a non-blank actor token, or omit `actor` to source it from the agent session."
+        );
+      }
+      return { token: actor.token, type: actor.type ?? ID_TOKEN_TYPE };
+    }
+    const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    if (!stateData || !stateData.idToken) {
+      throw actorUnavailableError(
+        "Unable to resolve an actor for the session transfer token: no actor was provided and there is no logged-in agent session. Pass an explicit actor or ensure the agent is logged in."
+      );
+    }
+    if (this.#isResolverMode() && !await this.#isSessionForCurrentDomain(stateData, storeOptions)) {
+      throw actorUnavailableError(
+        "Unable to resolve an actor for the session transfer token: the agent session belongs to a different domain than the one resolved for this request. Pass an explicit actor or ensure the agent is logged in on this domain."
+      );
+    }
+    if (!isTokenExpired(stateData.idToken)) {
+      return { token: stateData.idToken, type: ID_TOKEN_TYPE };
+    }
+    if (!stateData.refreshToken) {
+      throw actorUnavailableError(
+        "Unable to resolve an actor for the session transfer token: the agent session ID token has expired and no refresh token is available to refresh it. Pass an explicit actor or re-authenticate the agent."
+      );
+    }
+    const sessionDomain = this.#getSessionDomain(stateData) ?? domain;
+    let tokenEndpointResponse;
+    try {
+      tokenEndpointResponse = await this.#getAuthClient(sessionDomain).getTokenByRefreshToken({
+        refreshToken: stateData.refreshToken
+      });
+    } catch {
+      throw actorUnavailableError(
+        "Unable to resolve an actor for the session transfer token: refreshing the agent session ID token failed. Pass an explicit actor or re-authenticate the agent."
+      );
+    }
+    if (!tokenEndpointResponse.idToken) {
+      throw actorUnavailableError(
+        "Unable to resolve an actor for the session transfer token: refreshing the agent session did not return an ID token. Pass an explicit actor or re-authenticate the agent."
+      );
+    }
+    const audience = this.#options.authorizationParams?.audience ?? "default";
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const updatedStateData = updateStateData(audience, existingStateData, tokenEndpointResponse, {
+      domain: sessionDomain
+    });
+    await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, storeOptions);
+    return { token: tokenEndpointResponse.idToken, type: ID_TOKEN_TYPE };
+  }
   /**
    * 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.
@@ -1406,7 +1711,15 @@ var AbstractTransactionStore = class extends AbstractStore {
 };
 
 // src/index.ts
-import { TokenExchangeError, MissingClientAuthError, OrganizationValidationError as OrganizationValidationError3 } from "@auth0/auth0-auth-js";
+import {
+  TokenExchangeError as TokenExchangeError2,
+  TokenRevocationError,
+  MissingClientAuthError,
+  OrganizationValidationError as OrganizationValidationError3,
+  PasswordlessStartError as PasswordlessStartError2,
+  PasswordlessVerifyError as PasswordlessVerifyError2,
+  isMfaRequiredError as isMfaRequiredError2
+} from "@auth0/auth0-auth-js";
 
 // src/store/cookie-transaction-store.ts
 var CookieTransactionStore = class extends AbstractTransactionStore {
@@ -1618,10 +1931,14 @@ import {
   PasskeyGetTokenError,
   OrganizationValidationError as OrganizationValidationError2
 } from "@auth0/auth0-auth-js";
+
+// src/database/index.ts
+import { SignUpError, ChangePasswordError } from "@auth0/auth0-auth-js";
 export {
   AbstractStateStore,
   AbstractTransactionStore,
   BackchannelLogoutError,
+  ChangePasswordError,
   CookieTransactionStore,
   InvalidConfigurationError,
   IssuerValidationError,
@@ -1637,14 +1954,20 @@ export {
   PasskeyChallengeError,
   PasskeyGetTokenError,
   PasskeyRegisterError,
+  PasswordlessStartError2 as PasswordlessStartError,
+  PasswordlessVerifyError2 as PasswordlessVerifyError,
   ServerClient,
+  ServerDatabaseClient,
   ServerMfaClient,
   ServerPasskeyClient,
   SessionExpiredError,
+  SignUpError,
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,
-  TokenExchangeError,
-  isMfaRequiredError
+  TokenExchangeError2 as TokenExchangeError,
+  TokenExchangeErrorCode,
+  TokenRevocationError,
+  isMfaRequiredError2 as isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map