@auth0/auth0-server-js 1.11.0 → 1.12.1

package/dist/index.d.cts

@@ -425,11 +425,19 @@ interface LoginWithCustomTokenExchangeResult {
  * 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.
+ * current agent session's ID token. The session is not read at all when this is
+ * given, so it also works where there is no logged-in agent.
  */
 interface SessionTransferActor {
     /**
      * The actor token — for the default flow this is the agent's ID token.
+     *
+     * When {@link SessionTransferActor.type} is the ID token URN (the default), Auth0
+     * validates this token and requires an unexpired, asymmetrically-signed Auth0 ID
+     * token: signed with `RS256` or `PS256` (`HS256` is rejected, as it uses a shared
+     * secret), carrying `sub`, `iss`, `exp` and `iat`, issued to the same client making
+     * the exchange, and belonging to a user who still exists and is not blocked. A token
+     * failing any of these fails the exchange with a `TokenExchangeError`.
      */
     token: string;
     /**
@@ -462,16 +470,30 @@ interface RequestSessionTransferTokenOptions {
     /**
      * 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.
+     * Resolution order: this explicit `actor` wins, and the session is not read at all;
+     * 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;
+    /**
+     * The organization (ID or name) to mint the STT in the context of.
+     *
+     * Sending it here has the tenant validate the organization against the client's
+     * organization settings while minting, so an organization the client is not allowed
+     * to use fails at this call instead of the STT being issued without it.
+     *
+     * This is a separate parameter from {@link BuildSessionTransferRedirectOptions.organization},
+     * which is forwarded to the target's `/authorize` on the redirect. They are sent on
+     * different requests and neither implies the other. The one on the redirect is what
+     * org-scopes the session the target establishes, so setting only this one validates the
+     * organization without scoping that session.
+     */
+    organization?: string;
     /**
      * Additional custom parameters forwarded to the token endpoint (and thus to your
      * Action via `event.request.body`). Cannot override reserved OAuth parameters.
@@ -668,6 +690,12 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * This method does not create a session; no state is persisted.
      *
+     * On a confidential client this endpoint accepts `client_secret` as its only
+     * credential, so configure `clientSecret` on the `ServerClient`. It does not
+     * accept a private key JWT and is not served on the mTLS endpoint aliases, so a
+     * client configured with only `clientAssertionSigningKey` or only `useMtls` is
+     * rejected by Auth0. Public clients authenticate with `clientId` alone.
+     *
      * @param options User profile data and optional realm/organization.
      * @param storeOptions Optional options used to resolve the domain (resolver mode).
      *
@@ -686,6 +714,9 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * This method does not create a session; no state is persisted.
      *
+     * Client authentication works the same way as {@link ServerPasskeyClient.register}:
+     * on a confidential client, only a `clientSecret` is accepted here.
+     *
      * @param options Optional realm/organization configuration.
      * @param storeOptions Optional options used to resolve the domain (resolver mode).
      *
@@ -1104,16 +1135,24 @@ declare class ServerClient<TStoreOptions = unknown> {
      * 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.
+     * resolved in this order: an explicit `options.actor` wins, in which case the session is not
+     * read at all; 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. An explicit actor
+     * token carrying the default ID token type must satisfy Auth0's own validation — see
+     * {@link SessionTransferActor.token}.
+     *
+     * When `organization` is provided it is sent on the exchange, so the tenant validates it while
+     * minting. This is a separate parameter from the `organization` passed to
+     * {@link ServerClient.buildSessionTransferRedirect}, which is forwarded to the target's
+     * `/authorize` on the redirect.
      *
      * @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 {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`. An organization the tenant rejects also surfaces here.
      * @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).
+     * @throws {OrganizationValidationError} When `organization` is provided but blank (raised before any session read or network call).
      *
      * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
      */

package/dist/index.d.ts

@@ -425,11 +425,19 @@ interface LoginWithCustomTokenExchangeResult {
  * 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.
+ * current agent session's ID token. The session is not read at all when this is
+ * given, so it also works where there is no logged-in agent.
  */
 interface SessionTransferActor {
     /**
      * The actor token — for the default flow this is the agent's ID token.
+     *
+     * When {@link SessionTransferActor.type} is the ID token URN (the default), Auth0
+     * validates this token and requires an unexpired, asymmetrically-signed Auth0 ID
+     * token: signed with `RS256` or `PS256` (`HS256` is rejected, as it uses a shared
+     * secret), carrying `sub`, `iss`, `exp` and `iat`, issued to the same client making
+     * the exchange, and belonging to a user who still exists and is not blocked. A token
+     * failing any of these fails the exchange with a `TokenExchangeError`.
      */
     token: string;
     /**
@@ -462,16 +470,30 @@ interface RequestSessionTransferTokenOptions {
     /**
      * 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.
+     * Resolution order: this explicit `actor` wins, and the session is not read at all;
+     * 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;
+    /**
+     * The organization (ID or name) to mint the STT in the context of.
+     *
+     * Sending it here has the tenant validate the organization against the client's
+     * organization settings while minting, so an organization the client is not allowed
+     * to use fails at this call instead of the STT being issued without it.
+     *
+     * This is a separate parameter from {@link BuildSessionTransferRedirectOptions.organization},
+     * which is forwarded to the target's `/authorize` on the redirect. They are sent on
+     * different requests and neither implies the other. The one on the redirect is what
+     * org-scopes the session the target establishes, so setting only this one validates the
+     * organization without scoping that session.
+     */
+    organization?: string;
     /**
      * Additional custom parameters forwarded to the token endpoint (and thus to your
      * Action via `event.request.body`). Cannot override reserved OAuth parameters.
@@ -668,6 +690,12 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * This method does not create a session; no state is persisted.
      *
+     * On a confidential client this endpoint accepts `client_secret` as its only
+     * credential, so configure `clientSecret` on the `ServerClient`. It does not
+     * accept a private key JWT and is not served on the mTLS endpoint aliases, so a
+     * client configured with only `clientAssertionSigningKey` or only `useMtls` is
+     * rejected by Auth0. Public clients authenticate with `clientId` alone.
+     *
      * @param options User profile data and optional realm/organization.
      * @param storeOptions Optional options used to resolve the domain (resolver mode).
      *
@@ -686,6 +714,9 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
      *
      * This method does not create a session; no state is persisted.
      *
+     * Client authentication works the same way as {@link ServerPasskeyClient.register}:
+     * on a confidential client, only a `clientSecret` is accepted here.
+     *
      * @param options Optional realm/organization configuration.
      * @param storeOptions Optional options used to resolve the domain (resolver mode).
      *
@@ -1104,16 +1135,24 @@ declare class ServerClient<TStoreOptions = unknown> {
      * 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.
+     * resolved in this order: an explicit `options.actor` wins, in which case the session is not
+     * read at all; 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. An explicit actor
+     * token carrying the default ID token type must satisfy Auth0's own validation — see
+     * {@link SessionTransferActor.token}.
+     *
+     * When `organization` is provided it is sent on the exchange, so the tenant validates it while
+     * minting. This is a separate parameter from the `organization` passed to
+     * {@link ServerClient.buildSessionTransferRedirect}, which is forwarded to the target's
+     * `/authorize` on the redirect.
      *
      * @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 {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`. An organization the tenant rejects also surfaces here.
      * @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).
+     * @throws {OrganizationValidationError} When `organization` is provided but blank (raised before any session read or network call).
      *
      * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
      */

package/dist/index.js

@@ -211,7 +211,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.11.0"
+    version: config?.version ?? "1.12.1"
   };
 }
 
@@ -317,6 +317,12 @@ var ServerPasskeyClient = class {
    *
    * This method does not create a session; no state is persisted.
    *
+   * On a confidential client this endpoint accepts `client_secret` as its only
+   * credential, so configure `clientSecret` on the `ServerClient`. It does not
+   * accept a private key JWT and is not served on the mTLS endpoint aliases, so a
+   * client configured with only `clientAssertionSigningKey` or only `useMtls` is
+   * rejected by Auth0. Public clients authenticate with `clientId` alone.
+   *
    * @param options User profile data and optional realm/organization.
    * @param storeOptions Optional options used to resolve the domain (resolver mode).
    *
@@ -339,6 +345,9 @@ var ServerPasskeyClient = class {
    *
    * This method does not create a session; no state is persisted.
    *
+   * Client authentication works the same way as {@link ServerPasskeyClient.register}:
+   * on a confidential client, only a `clientSecret` is accepted here.
+   *
    * @param options Optional realm/organization configuration.
    * @param storeOptions Optional options used to resolve the domain (resolver mode).
    *
@@ -1404,16 +1413,24 @@ var ServerClient = class {
    * 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.
+   * resolved in this order: an explicit `options.actor` wins, in which case the session is not
+   * read at all; 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. An explicit actor
+   * token carrying the default ID token type must satisfy Auth0's own validation — see
+   * {@link SessionTransferActor.token}.
+   *
+   * When `organization` is provided it is sent on the exchange, so the tenant validates it while
+   * minting. This is a separate parameter from the `organization` passed to
+   * {@link ServerClient.buildSessionTransferRedirect}, which is forwarded to the target's
+   * `/authorize` on the redirect.
    *
    * @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 {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`. An organization the tenant rejects also surfaces here.
    * @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).
+   * @throws {OrganizationValidationError} When `organization` is provided but blank (raised before any session read or network call).
    *
    * @returns A promise resolving to a {@link SessionTransferTokenResult} containing the STT and its metadata.
    */
@@ -1424,6 +1441,9 @@ var ServerClient = class {
     if (!options.subjectTokenType || !options.subjectTokenType.trim()) {
       throw new MissingRequiredArgumentError("subjectTokenType");
     }
+    if (options.organization !== void 0 && !options.organization.trim()) {
+      throw new OrganizationValidationError("organization must not be blank");
+    }
     const domain = await this.#resolveDomain(storeOptions);
     const actor = await this.#resolveSessionTransferActor(options.actor, domain, storeOptions);
     const authClient = this.#getAuthClient(domain);
@@ -1434,6 +1454,11 @@ var ServerClient = class {
       scope: options.scope,
       actorToken: actor.token,
       actorTokenType: actor.type,
+      // Forwarded so the tenant validates the organization against the client's organization
+      // settings while minting, rather than the STT being issued without it. Separate from the
+      // `organization` on `buildSessionTransferRedirect`, which goes to the target's
+      // `/authorize`; neither implies the other.
+      organization: options.organization,
       extra: options.extra
     });
     return {