@auth0/auth0-server-js 1.10.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.10.0"
+    version: config?.version ?? "1.11.0"
   };
 }
 
@@ -445,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;
@@ -1369,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.
@@ -1523,7 +1711,15 @@ var AbstractTransactionStore = class extends AbstractStore {
 };
 
 // src/index.ts
-import { TokenExchangeError, TokenRevocationError, 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 {
@@ -1758,6 +1954,8 @@ export {
   PasskeyChallengeError,
   PasskeyGetTokenError,
   PasskeyRegisterError,
+  PasswordlessStartError2 as PasswordlessStartError,
+  PasswordlessVerifyError2 as PasswordlessVerifyError,
   ServerClient,
   ServerDatabaseClient,
   ServerMfaClient,
@@ -1767,8 +1965,9 @@ export {
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,
-  TokenExchangeError,
+  TokenExchangeError2 as TokenExchangeError,
+  TokenExchangeErrorCode,
   TokenRevocationError,
-  isMfaRequiredError
+  isMfaRequiredError2 as isMfaRequiredError
 };
 //# sourceMappingURL=index.js.map