@auth0/auth0-server-js 1.10.0 → 1.11.0

package/README.md

@@ -256,7 +256,47 @@ fastify.get('/auth/logout', async (request, reply) => {
 > [!IMPORTANT]  
 > You will need to register the `RETURN_TO` in your Auth0 Application as an **Allowed Logout URLs** via the [Auth0 Dashboard](https://manage.auth0.com):
 
+### 6. Database Connections (Sign-up & Change Password)
 
+The `ServerClient` exposes a `database` sub-client with `signUp` and `changePassword` for self-service registration and password-reset requests against an Auth0 [database connection](https://auth0.com/docs/authenticate/database-connections). These are **pure passthrough** operations to the underlying Authentication API — they do **not** read or write the session/state store, so no store options are required for the operation itself.
+
+```ts
+import { ServerClient, SignUpError, ChangePasswordError } from '@auth0/auth0-server-js';
+
+// Register a new user
+try {
+  const user = await auth0Client.database.signUp({
+    email: 'user@example.com',
+    password: 'a-Str0ng-Password!',
+    connection: 'Username-Password-Authentication',
+    // Optional profile fields: username, givenName, familyName, name, nickname, picture, userMetadata
+  });
+  console.log(user.id); // normalized identifier; may be undefined if the server omits one
+} catch (error) {
+  if (error instanceof SignUpError) {
+    console.error(error.code, error.message, error.cause);
+  }
+}
+
+// Request a password-change email
+try {
+  const message = await auth0Client.database.changePassword({
+    email: 'user@example.com', // or `username: 'jane'` for username-only connections
+    connection: 'Username-Password-Authentication',
+    // Optional: organization
+  });
+  console.log(message); // plain-text confirmation from the server
+} catch (error) {
+  if (error instanceof ChangePasswordError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+> [!IMPORTANT]
+> These call the public `/dbconnections/*` endpoints, which send only `clientId` (never a client secret). `changePassword` resolves to a **plain-text** confirmation string. Neither method reads or writes the session/state store, so you can call them outside an authenticated request context. Domain selection is separate from session state: in static mode the constructor-configured `domain` is used, and in resolver (multi-tenant) mode the `domain` resolver still runs per call — pass `storeOptions` so it can select the intended tenant.
+
+For full options and error handling, see the [Database Connections section in the auth0-auth-js EXAMPLES.md](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-auth-js/EXAMPLES.md#using-database-connections-sign-up--change-password) (the underlying database client is identical) and the runnable [`examples/database-conns`](https://github.com/auth0/auth0-auth-js/tree/main/examples/database-conns) sample.
 
 ## Feedback
 

package/dist/index.cjs

@@ -39,6 +39,8 @@ __export(index_exports, {
   PasskeyChallengeError: () => import_auth0_auth_js3.PasskeyChallengeError,
   PasskeyGetTokenError: () => import_auth0_auth_js3.PasskeyGetTokenError,
   PasskeyRegisterError: () => import_auth0_auth_js3.PasskeyRegisterError,
+  PasswordlessStartError: () => import_auth0_auth_js5.PasswordlessStartError,
+  PasswordlessVerifyError: () => import_auth0_auth_js5.PasswordlessVerifyError,
   ServerClient: () => ServerClient,
   ServerDatabaseClient: () => ServerDatabaseClient,
   ServerMfaClient: () => ServerMfaClient,
@@ -49,12 +51,18 @@ __export(index_exports, {
   StatefulStateStore: () => StatefulStateStore,
   StatelessStateStore: () => StatelessStateStore,
   TokenExchangeError: () => import_auth0_auth_js5.TokenExchangeError,
+  TokenExchangeErrorCode: () => TokenExchangeErrorCode,
   TokenRevocationError: () => import_auth0_auth_js5.TokenRevocationError,
-  isMfaRequiredError: () => import_auth0_auth_js2.isMfaRequiredError
+  isMfaRequiredError: () => import_auth0_auth_js5.isMfaRequiredError
 });
 module.exports = __toCommonJS(index_exports);
 
 // 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) {
@@ -254,7 +262,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.10.0"
+    version: config?.version ?? "1.11.0"
   };
 }
 
@@ -494,6 +502,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 import_auth0_auth_js.TokenExchangeError(message);
+  error.code = TokenExchangeErrorCode.ACTOR_UNAVAILABLE;
+  return error;
+};
+var isTokenExpired = (token) => {
+  try {
+    const { exp } = (0, import_jose.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;
@@ -1418,6 +1444,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 import_auth0_auth_js.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.
@@ -1797,6 +1987,8 @@ var import_auth0_auth_js4 = require("@auth0/auth0-auth-js");
   PasskeyChallengeError,
   PasskeyGetTokenError,
   PasskeyRegisterError,
+  PasswordlessStartError,
+  PasswordlessVerifyError,
   ServerClient,
   ServerDatabaseClient,
   ServerMfaClient,
@@ -1807,6 +1999,7 @@ var import_auth0_auth_js4 = require("@auth0/auth0-auth-js");
   StatefulStateStore,
   StatelessStateStore,
   TokenExchangeError,
+  TokenExchangeErrorCode,
   TokenRevocationError,
   isMfaRequiredError
 });