@auth0/auth0-server-js 1.15.0 → 1.16.1

package/dist/index.cjs

@@ -20,43 +20,50 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AbstractAnonymousStore: () => AbstractAnonymousStore,
   AbstractStateStore: () => AbstractStateStore,
   AbstractTransactionStore: () => AbstractTransactionStore,
+  AnonymousSessionError: () => import_auth0_auth_js7.AnonymousSessionError,
+  AnonymousSessionExpiredError: () => AnonymousSessionExpiredError,
   BackchannelLogoutError: () => BackchannelLogoutError,
-  ChangePasswordError: () => import_auth0_auth_js5.ChangePasswordError,
+  ChangePasswordError: () => import_auth0_auth_js6.ChangePasswordError,
   CookieTransactionStore: () => CookieTransactionStore,
-  EnterpriseConnectNotSupportedError: () => import_auth0_auth_js6.EnterpriseConnectNotSupportedError,
+  DEFAULT_ANONYMOUS_SESSION_LIFETIME: () => DEFAULT_ANONYMOUS_SESSION_LIFETIME,
+  EnterpriseConnectNotSupportedError: () => import_auth0_auth_js8.EnterpriseConnectNotSupportedError,
   InvalidConfigurationError: () => InvalidConfigurationError,
   IssuerValidationError: () => IssuerValidationError,
-  MfaChallengeError: () => import_auth0_auth_js3.MfaChallengeError,
-  MfaEnrollmentError: () => import_auth0_auth_js3.MfaEnrollmentError,
-  MfaListAuthenticatorsError: () => import_auth0_auth_js3.MfaListAuthenticatorsError,
-  MfaVerifyError: () => import_auth0_auth_js3.MfaVerifyError,
-  MissingClientAuthError: () => import_auth0_auth_js6.MissingClientAuthError,
+  MfaChallengeError: () => import_auth0_auth_js4.MfaChallengeError,
+  MfaEnrollmentError: () => import_auth0_auth_js4.MfaEnrollmentError,
+  MfaListAuthenticatorsError: () => import_auth0_auth_js4.MfaListAuthenticatorsError,
+  MfaVerifyError: () => import_auth0_auth_js4.MfaVerifyError,
+  MissingAnonymousSessionError: () => MissingAnonymousSessionError,
+  MissingClientAuthError: () => import_auth0_auth_js8.MissingClientAuthError,
   MissingRequiredArgumentError: () => MissingRequiredArgumentError,
   MissingSessionError: () => MissingSessionError,
   MissingTransactionError: () => MissingTransactionError,
-  OrganizationValidationError: () => import_auth0_auth_js6.OrganizationValidationError,
-  PasskeyChallengeError: () => import_auth0_auth_js4.PasskeyChallengeError,
-  PasskeyGetTokenError: () => import_auth0_auth_js4.PasskeyGetTokenError,
-  PasskeyRegisterError: () => import_auth0_auth_js4.PasskeyRegisterError,
-  PasswordlessStartError: () => import_auth0_auth_js6.PasswordlessStartError,
-  PasswordlessVerifyError: () => import_auth0_auth_js6.PasswordlessVerifyError,
+  OrganizationValidationError: () => import_auth0_auth_js8.OrganizationValidationError,
+  PasskeyChallengeError: () => import_auth0_auth_js5.PasskeyChallengeError,
+  PasskeyGetTokenError: () => import_auth0_auth_js5.PasskeyGetTokenError,
+  PasskeyRegisterError: () => import_auth0_auth_js5.PasskeyRegisterError,
+  PasswordlessStartError: () => import_auth0_auth_js8.PasswordlessStartError,
+  PasswordlessVerifyError: () => import_auth0_auth_js8.PasswordlessVerifyError,
+  ServerAnonymousClient: () => ServerAnonymousClient,
   ServerClient: () => ServerClient,
   ServerDatabaseClient: () => ServerDatabaseClient,
   ServerMfaClient: () => ServerMfaClient,
   ServerPasskeyClient: () => ServerPasskeyClient,
   SessionExpiredError: () => SessionExpiredError,
-  SignUpError: () => import_auth0_auth_js5.SignUpError,
+  SignUpError: () => import_auth0_auth_js6.SignUpError,
   StartLinkUserError: () => StartLinkUserError,
   StatefulStateStore: () => StatefulStateStore,
+  StatelessAnonymousStore: () => StatelessAnonymousStore,
   StatelessStateStore: () => StatelessStateStore,
-  TokenExchangeError: () => import_auth0_auth_js6.TokenExchangeError,
+  TokenExchangeError: () => import_auth0_auth_js8.TokenExchangeError,
   TokenExchangeErrorCode: () => TokenExchangeErrorCode,
-  TokenRevocationError: () => import_auth0_auth_js6.TokenRevocationError,
-  UserInfoError: () => import_auth0_auth_js6.UserInfoError,
-  isFederatedDomain: () => import_auth0_auth_js6.isFederatedDomain,
-  isMfaRequiredError: () => import_auth0_auth_js6.isMfaRequiredError
+  TokenRevocationError: () => import_auth0_auth_js8.TokenRevocationError,
+  UserInfoError: () => import_auth0_auth_js8.UserInfoError,
+  isFederatedDomain: () => import_auth0_auth_js8.isFederatedDomain,
+  isMfaRequiredError: () => import_auth0_auth_js8.isMfaRequiredError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -115,6 +122,22 @@ var IssuerValidationError = class extends Error {
     this.name = "IssuerValidationError";
   }
 };
+var MissingAnonymousSessionError = class extends Error {
+  code = "missing_anonymous_session_error";
+  constructor(message) {
+    super(message ?? "There is no anonymous session. Call `anonymous.createSession()` first.");
+    this.name = "MissingAnonymousSessionError";
+  }
+};
+var AnonymousSessionExpiredError = class extends Error {
+  code = "anonymous_session_expired";
+  constructor(message) {
+    super(
+      message ?? "The anonymous session has expired or is no longer valid. Call `anonymous.createSession()` to start a new one."
+    );
+    this.name = "AnonymousSessionExpiredError";
+  }
+};
 var SessionExpiredError = class extends Error {
   code = "session_expired";
   constructor(message) {
@@ -227,7 +250,7 @@ function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointR
 }
 
 // src/server-client.ts
-var import_auth0_auth_js2 = require("@auth0/auth0-auth-js");
+var import_auth0_auth_js3 = require("@auth0/auth0-auth-js");
 
 // src/utils.ts
 var DEFAULT_SCOPES = "openid profile email offline_access";
@@ -255,7 +278,7 @@ var compareScopes = (scopes, requiredScopes) => {
 };
 
 // src/server-client.ts
-var import_jose = require("jose");
+var import_jose2 = require("jose");
 
 // src/telemetry.ts
 function getTelemetryConfig(config) {
@@ -265,7 +288,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.15.0"
+    version: config?.version ?? "1.16.1"
   };
 }
 
@@ -339,6 +362,7 @@ var ServerMfaClient = class {
       true,
       storeOptions
     );
+    await this.#options.onUserSessionEstablished?.(storeOptions);
     const result = {
       accessToken: tokenResponse.accessToken,
       tokenType: tokenResponse.tokenType ?? "bearer",
@@ -447,6 +471,7 @@ var ServerPasskeyClient = class {
     const existingStateData = await this.#options.stateStore.get(this.#options.stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(audience ?? "default", existingStateData, tokenEndpointResponse, { domain });
     await this.#options.stateStore.set(this.#options.stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#options.onUserSessionEstablished?.(storeOptions);
     return {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
@@ -541,6 +566,234 @@ function applyEnterpriseConnectRestrictions(instance) {
   }
 }
 
+// src/anonymous/server-anonymous-client.ts
+var import_jose = require("jose");
+var import_auth0_auth_js2 = require("@auth0/auth0-auth-js");
+var DEFAULT_AUDIENCE_CACHE_KEY = "default";
+var readAnonymousSub = (accessToken) => {
+  try {
+    const { sub } = (0, import_jose.decodeJwt)(accessToken);
+    return typeof sub === "string" ? sub : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var cacheKeyScope = (tokenSet) => tokenSet.requestedScope ?? tokenSet.scope;
+var upsertTokenSet = (tokenSets, tokenSet) => {
+  const matches = (candidate) => candidate.audience === tokenSet.audience && cacheKeyScope(candidate) === cacheKeyScope(tokenSet);
+  return tokenSets.some(matches) ? tokenSets.map((candidate) => matches(candidate) ? tokenSet : candidate) : [...tokenSets, tokenSet];
+};
+var ServerAnonymousClient = class {
+  #options;
+  /**
+   * @internal
+   */
+  constructor(options) {
+    this.#options = options;
+  }
+  /**
+   * Creates an anonymous session and stores it, returning the first anonymous access token.
+   *
+   * Replaces any anonymous session already stored for this visitor. Metadata can only be
+   * attached here, because Auth0 rejects a request that carries both metadata and an
+   * existing session.
+   *
+   * The anonymous identity (`sub`) is read off the first access token and stored alongside
+   * the metadata, so {@link ServerAnonymousClient.getSession} can hand both back without the
+   * application decoding a token. It stays `undefined` for an audience with token encryption
+   * (`token_encryption`) enabled, whose access token is an encrypted JWE only the API can
+   * read.
+   *
+   * @param options Optional audience, scope and metadata for the new session.
+   * @param storeOptions Optional options used to pass to the anonymous store (and to resolve the domain in resolver mode).
+   *
+   * @throws {AnonymousSessionError} If Auth0 rejected the request. Common codes are
+   * `feature_not_enabled` (the tenant flag is off), `unauthorized_client` (the client is
+   * not enabled for anonymous sessions), `invalid_target` (the resource server does not
+   * allow anonymous access), `invalid_request` (metadata over 1024 bytes, or not all
+   * strings) and `access_denied`. `code` is `server_error` when Auth0 answers with a body
+   * that is not JSON.
+   *
+   * Only call this once you have established the visitor has no anonymous session (check
+   * {@link ServerAnonymousClient.getSession} first), rather than on every request.
+   *
+   * @returns The anonymous access token for the requested audience.
+   */
+  async createSession(options, storeOptions) {
+    const domain = await this.#options.resolveDomain(storeOptions);
+    const requestedAudience = options?.audience ?? this.#options.defaultAudience;
+    const audience = requestedAudience ?? DEFAULT_AUDIENCE_CACHE_KEY;
+    const scope = options?.scope;
+    const session = await this.#options.getAuthClient(domain).anonymous.createSession({
+      ...requestedAudience && { audience: requestedAudience },
+      ...scope && { scope },
+      ...options?.metadata && { metadata: options.metadata }
+    });
+    const tokenSet = {
+      audience,
+      accessToken: session.accessToken,
+      scope: session.scope,
+      ...scope && scope !== session.scope && { requestedScope: scope },
+      expiresAt: session.expiresAt
+    };
+    const stateData = {
+      sessionToken: session.sessionToken,
+      sessionTokenExpiresAt: session.sessionTokenExpiresAt,
+      sub: readAnonymousSub(session.accessToken),
+      ...options?.metadata && { metadata: options.metadata },
+      createdAt: Math.floor(Date.now() / 1e3),
+      tokenSets: [tokenSet],
+      domain
+    };
+    await this.#options.anonymousStore.set(
+      this.#options.anonymousStoreIdentifier,
+      stateData,
+      true,
+      storeOptions
+    );
+    return tokenSet;
+  }
+  /**
+   * Returns an anonymous access token for the stored anonymous session, fetching a fresh
+   * one from Auth0 when the cached one has expired.
+   *
+   * Tokens are cached per audience and scope, so requesting a second audience returns a
+   * second token for the same anonymous identity without replacing the first.
+   *
+   * Auth0 may grant fewer scopes than requested — a scope the anonymous identity is not
+   * entitled to is silently dropped and the response is still a success. Always check
+   * `tokenSet.scope` before calling your API; do not assume the token carries every scope
+   * you asked for.
+   *
+   * This never creates a session. If the anonymous session has expired, the stored session
+   * is deleted and `AnonymousSessionExpiredError` is thrown, so a visitor is never moved
+   * onto a fresh anonymous identity behind your back.
+   *
+   * @param options Optional audience and scope for the requested token.
+   * @param storeOptions Optional options used to pass to the anonymous store (and to resolve the domain in resolver mode).
+   *
+   * @throws {MissingAnonymousSessionError} When there is no anonymous session stored, or the stored one belongs to another Auth0 domain (resolver mode).
+   * @throws {AnonymousSessionExpiredError} When the anonymous session has expired or Auth0 rejected the session token. The stored session is deleted first.
+   *
+   * @returns The anonymous access token for the requested audience.
+   */
+  async getAccessToken(options, storeOptions) {
+    const stateData = await this.#options.anonymousStore.get(
+      this.#options.anonymousStoreIdentifier,
+      storeOptions
+    );
+    if (!stateData?.sessionToken) {
+      throw new MissingAnonymousSessionError();
+    }
+    const domain = await this.#options.resolveDomain(storeOptions);
+    if (this.#options.isResolverMode() && stateData.domain !== domain) {
+      throw new MissingAnonymousSessionError(
+        "The stored anonymous session was created for a different Auth0 domain."
+      );
+    }
+    const requestedAudience = options?.audience ?? this.#options.defaultAudience;
+    const audience = requestedAudience ?? DEFAULT_AUDIENCE_CACHE_KEY;
+    const scope = options?.scope;
+    const cachedTokenSet = stateData.tokenSets.find(
+      (tokenSet2) => tokenSet2.audience === audience && (!scope || cacheKeyScope(tokenSet2) === scope || compareScopes(tokenSet2.scope, scope))
+    );
+    if (cachedTokenSet && cachedTokenSet.expiresAt > Date.now() / 1e3) {
+      return cachedTokenSet;
+    }
+    let renewed;
+    try {
+      renewed = await this.#options.getAuthClient(domain).anonymous.getAccessToken({
+        sessionToken: stateData.sessionToken,
+        ...requestedAudience && { audience: requestedAudience },
+        ...scope && { scope }
+      });
+    } catch (e) {
+      if (e instanceof import_auth0_auth_js2.AnonymousSessionError && e.code === "session_expired") {
+        await this.#options.anonymousStore.delete(this.#options.anonymousStoreIdentifier, storeOptions);
+        throw new AnonymousSessionExpiredError();
+      }
+      if (e instanceof import_auth0_auth_js2.AnonymousSessionError && e.code === "invalid_session_token") {
+        await this.#options.anonymousStore.delete(this.#options.anonymousStoreIdentifier, storeOptions);
+      }
+      throw e;
+    }
+    const tokenSet = {
+      audience,
+      accessToken: renewed.accessToken,
+      scope: renewed.scope,
+      ...scope && scope !== renewed.scope && { requestedScope: scope },
+      expiresAt: renewed.expiresAt
+    };
+    const existingStateData = await this.#options.anonymousStore.get(
+      this.#options.anonymousStoreIdentifier,
+      storeOptions
+    );
+    if (existingStateData?.sessionToken === stateData.sessionToken) {
+      await this.#options.anonymousStore.set(
+        this.#options.anonymousStoreIdentifier,
+        {
+          ...existingStateData,
+          ...existingStateData.sub === void 0 && { sub: readAnonymousSub(renewed.accessToken) },
+          tokenSets: upsertTokenSet(existingStateData.tokenSets, tokenSet)
+        },
+        false,
+        storeOptions
+      );
+    }
+    return tokenSet;
+  }
+  /**
+   * Returns the stored anonymous session, or `undefined` when there is none.
+   *
+   * Two common uses:
+   * - **Gate `createSession`** — call this first; only create a session when the result is `undefined`.
+   * - **Read identity for a merge** — `sub` and `metadata` are available here without decoding a token.
+   *
+   * This is a local read of the store with no request to Auth0. It cannot tell you whether
+   * Auth0 still considers the session valid — only {@link ServerAnonymousClient.getAccessToken} can.
+   * The session token is never included in the result.
+   *
+   * @param storeOptions Optional options used to pass to the anonymous store (and to resolve the domain in resolver mode).
+   *
+   * @returns The anonymous session, or `undefined` when there is none for this visitor (or it belongs to another Auth0 domain in resolver mode).
+   */
+  async getSession(storeOptions) {
+    const stateData = await this.#options.anonymousStore.get(
+      this.#options.anonymousStoreIdentifier,
+      storeOptions
+    );
+    if (!stateData) {
+      return;
+    }
+    if (this.#options.isResolverMode()) {
+      const domain = await this.#options.resolveDomain(storeOptions);
+      if (stateData.domain !== domain) {
+        return;
+      }
+    }
+    const { sessionToken, ...sessionData } = stateData;
+    return sessionData;
+  }
+  /**
+   * Clears the anonymous session from the store.
+   *
+   * Does not call `POST /anonymous/logout` — that endpoint only clears the `auth0_anon`
+   * browser cookie, which your server never holds. Any access tokens already issued remain
+   * valid until they expire (~2 hours by default).
+   *
+   * You rarely need to call this directly: every method that establishes a user session
+   * clears the anonymous session automatically (unless `clearAnonymousSessionOnLogin: false`
+   * is set), and `serverClient.logout()` clears it too. Call this to explicitly reset a
+   * visitor's anonymous identity, or to clean up after your own post-login merge logic when
+   * automatic clearing is disabled.
+   *
+   * @param storeOptions Optional options used to pass to the anonymous store.
+   */
+  async logout(storeOptions) {
+    await this.#options.anonymousStore.delete(this.#options.anonymousStoreIdentifier, storeOptions);
+  }
+};
+
 // src/server-client.ts
 var normalizeDomain = (value) => {
   const trimmed = value.trim();
@@ -549,7 +802,7 @@ var normalizeDomain = (value) => {
 };
 var decodeIssuer = (token) => {
   try {
-    const { iss } = (0, import_jose.decodeJwt)(token);
+    const { iss } = (0, import_jose2.decodeJwt)(token);
     return typeof iss === "string" ? iss : void 0;
   } catch {
     return void 0;
@@ -558,13 +811,13 @@ var decodeIssuer = (token) => {
 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_js2.TokenExchangeError(message);
+  const error = new import_auth0_auth_js3.TokenExchangeError(message);
   error.code = TokenExchangeErrorCode.ACTOR_UNAVAILABLE;
   return error;
 };
 var isTokenExpired = (token) => {
   try {
-    const { exp } = (0, import_jose.decodeJwt)(token);
+    const { exp } = (0, import_jose2.decodeJwt)(token);
     if (typeof exp !== "number") {
       return true;
     }
@@ -586,6 +839,7 @@ var ServerClient = class {
   #mfaClient;
   #passkeyClient;
   #databaseClient;
+  #anonymousClient;
   /**
    * 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.
@@ -648,6 +902,42 @@ var ServerClient = class {
   get database() {
     return this.#databaseClient;
   }
+  /**
+   * The anonymous session client, for giving a visitor who has not logged in a stable
+   * identity and an access token for your API.
+   *
+   * Provides `createSession()` to establish the anonymous identity, `getAccessToken()` to
+   * obtain and renew anonymous access tokens, `getSession()` to check whether a visitor
+   * already has one, and `logout()` to discard it.
+   *
+   * Requires `anonymousStore` on the `ServerClient`, and a tenant and client configured for
+   * anonymous sessions. Anonymous sessions are kept in that store, never in the state
+   * store, so `getSession()` and `getUser()` still report no user while one is active.
+   *
+   * The anonymous session ends when the visitor logs in: every login method clears it once
+   * the user session is written, unless you set `clearAnonymousSessionOnLogin: false`.
+   * {@link ServerClient.logout} clears it too.
+   *
+   * For `/authorize` flows, `startInteractiveLogin()` links the anonymous session to
+   * the user automatically via a Session Transfer Ticket — no extra configuration needed.
+   * For logins that bypass `/authorize` (passkey, passwordless, backchannel, custom token
+   * exchange), the anonymous session is not linked. Read `anonymous.getSession()` before
+   * the login to get the anonymous `sub` for a manual merge, or set
+   * `clearAnonymousSessionOnLogin: false` and clear it yourself afterwards.
+   *
+   * Like `passkey` and `database`, this works in both static and resolver (multi-tenant)
+   * domain modes.
+   *
+   * @throws {InvalidConfigurationError} When no `anonymousStore` is configured.
+   */
+  get anonymous() {
+    if (!this.#anonymousClient) {
+      throw new InvalidConfigurationError(
+        "anonymous is only available when an `anonymousStore` is configured on the ServerClient."
+      );
+    }
+    return this.#anonymousClient;
+  }
   constructor(options) {
     this.#options = options;
     this.#enterpriseConnect = !!options.enterpriseConnect;
@@ -696,7 +986,7 @@ var ServerClient = class {
     if (typeof this.#options.domain === "string") {
       const domain = normalizeDomain(this.#options.domain);
       this.#staticDomain = domain;
-      this.#authClient = new import_auth0_auth_js2.AuthClient({
+      this.#authClient = new import_auth0_auth_js3.AuthClient({
         domain,
         ...this.#authClientOptions,
         telemetry: getTelemetryConfig(this.#options.telemetry)
@@ -706,7 +996,8 @@ var ServerClient = class {
         domain,
         stateStore: this.#stateStore,
         stateStoreIdentifier: this.#stateStoreIdentifier,
-        defaultAudience: this.#options.authorizationParams?.audience ?? "default"
+        defaultAudience: this.#options.authorizationParams?.audience ?? "default",
+        onUserSessionEstablished: (storeOptions) => this.#clearAnonymousSessionAfterLogin(storeOptions)
       });
     }
     this.#passkeyClient = new ServerPasskeyClient({
@@ -715,12 +1006,26 @@ var ServerClient = class {
       stateStore: this.#stateStore,
       stateStoreIdentifier: this.#stateStoreIdentifier,
       defaultScope: this.#options.authorizationParams?.scope,
-      defaultAudience: this.#options.authorizationParams?.audience
+      defaultAudience: this.#options.authorizationParams?.audience,
+      onUserSessionEstablished: (storeOptions) => this.#clearAnonymousSessionAfterLogin(storeOptions)
     });
     this.#databaseClient = new ServerDatabaseClient({
       resolveDomain: (storeOptions) => this.#resolveDomain(storeOptions),
       getAuthClient: (domain) => this.#getAuthClient(domain)
     });
+    if (this.#options.anonymousStore) {
+      this.#anonymousClient = new ServerAnonymousClient({
+        resolveDomain: (storeOptions) => this.#resolveDomain(storeOptions),
+        getAuthClient: (domain) => this.#getAuthClient(domain),
+        isResolverMode: () => this.#isResolverMode(),
+        anonymousStore: this.#options.anonymousStore,
+        anonymousStoreIdentifier: this.#options.anonymousSessionIdentifier || "__a0_anon",
+        // Only the audience is inherited from the client-level authorizationParams. The
+        // scope there is written for a user session (`openid profile email offline_access`)
+        // and none of it applies to an anonymous identity.
+        defaultAudience: this.#options.authorizationParams?.audience
+      });
+    }
   }
   async #resolveDomain(storeOptions) {
     if (typeof this.#options.domain === "function") {
@@ -733,7 +1038,7 @@ var ServerClient = class {
     return normalizeDomain(this.#options.domain);
   }
   #createAuthClient(domain) {
-    return new import_auth0_auth_js2.AuthClient({
+    return new import_auth0_auth_js3.AuthClient({
       domain,
       ...this.#authClientOptions,
       telemetry: getTelemetryConfig(this.#options.telemetry)
@@ -784,7 +1089,7 @@ var ServerClient = class {
     if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
     const emailDomain = parts[1].toLowerCase();
     const domain = await this.#resolveDomain(storeOptions);
-    const isFederated = await (0, import_auth0_auth_js2.isFederatedDomain)(domain, emailDomain, {
+    const isFederated = await (0, import_auth0_auth_js3.isFederatedDomain)(domain, emailDomain, {
       customFetch: this.#options.customFetch,
       telemetry: getTelemetryConfig(this.#options.telemetry)
     });
@@ -797,6 +1102,54 @@ var ServerClient = class {
       storeOptions
     );
   }
+  /**
+   * Discards the anonymous session once a login has established a user session.
+   *
+   * Called by every method that writes a user session, always AFTER the state store has been
+   * written. An anonymous session outliving the login would leave a 30-day bearer credential
+   * in a cookie on every request, and `anonymous.getAccessToken()` would keep minting
+   * anonymous tokens for a visitor who is no longer anonymous.
+   *
+   * Two deliberate properties:
+   * - **Best-effort.** The user is authenticated and their session is already persisted by
+   *   this point, so a failing anonymous store must not turn a successful login into an
+   *   error. The visitor would be unable to log in at all because of leftover state they
+   *   cannot see or clear.
+   * - **Unconditional across domains.** In resolver (multi-tenant) mode the anonymous session
+   *   is dropped even when it was created against a different Auth0 domain than the one just
+   *   logged into. The anonymous store holds a single session per visitor, and "no anonymous
+   *   session survives a login" is a rule that can be reasoned about; a domain-dependent one
+   *   cannot.
+   *
+   * Skipped entirely when no `anonymousStore` is configured, or when the application opted
+   * out with `clearAnonymousSessionOnLogin: false`.
+   */
+  async #clearAnonymousSessionAfterLogin(storeOptions) {
+    if (this.#options.clearAnonymousSessionOnLogin === false) {
+      return;
+    }
+    await this.#discardAnonymousSession(storeOptions);
+  }
+  /**
+   * Drops the anonymous session, swallowing store failures.
+   *
+   * Shared by the login sites and {@link ServerClient.logout}. Both run after the user
+   * session has already been written or deleted, so the outcome the caller cares about is
+   * settled: a failing anonymous store must not fail a login the user completed, nor block a
+   * logout redirect and leave the visitor unable to log out. When the store is the
+   * cookie-backed default this cannot fail, since deleting is a `Set-Cookie` on the response.
+   *
+   * No-op when no `anonymousStore` is configured.
+   */
+  async #discardAnonymousSession(storeOptions) {
+    if (!this.#anonymousClient) {
+      return;
+    }
+    try {
+      await this.#anonymousClient.logout(storeOptions);
+    } catch {
+    }
+  }
   /**
    * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
    *
@@ -824,7 +1177,7 @@ var ServerClient = class {
     const clientAuthParamsOrganization = typeof this.#options.authorizationParams?.organization === "string" ? this.#options.authorizationParams.organization : void 0;
     const resolvedOrganization = options?.organization ?? perLoginAuthParamsOrganization ?? this.#options.organization ?? clientAuthParamsOrganization;
     if (resolvedOrganization !== void 0 && !resolvedOrganization.trim()) {
-      throw new import_auth0_auth_js2.OrganizationValidationError("organization must not be blank");
+      throw new import_auth0_auth_js3.OrganizationValidationError("organization must not be blank");
     }
     const hasInvitation = !!(options?.invitation || options?.authorizationParams?.invitation);
     if (hasInvitation && !resolvedOrganization) {
@@ -832,6 +1185,17 @@ var ServerClient = class {
     }
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
+    let anonTransferToken;
+    if (this.#options.anonymousStore) {
+      try {
+        const identifier = this.#options.anonymousSessionIdentifier || "__a0_anon";
+        const stateData = await this.#options.anonymousStore.get(identifier, storeOptions);
+        if (stateData?.sessionToken) {
+          anonTransferToken = await authClient.anonymous.mintTransferToken(stateData.sessionToken) ?? void 0;
+        }
+      } catch {
+      }
+    }
     const { codeVerifier, authorizationUrl } = await authClient.buildAuthorizationUrl({
       pushedAuthorizationRequests: options?.pushedAuthorizationRequests,
       authorizationParams: {
@@ -839,7 +1203,8 @@ var ServerClient = class {
         redirect_uri: redirectUri,
         scope,
         ...resolvedOrganization ? { organization: resolvedOrganization } : {},
-        ...options?.invitation ? { invitation: options.invitation } : {}
+        ...options?.invitation ? { invitation: options.invitation } : {},
+        ...anonTransferToken ? { anon_transfer_token: anonTransferToken } : {}
       }
     });
     const transactionState = {
@@ -909,6 +1274,7 @@ var ServerClient = class {
       tokenEndpointResponse.claims
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     return {
       appState: transactionData.appState,
       authorizationDetails: tokenEndpointResponse.authorizationDetails
@@ -1076,12 +1442,13 @@ var ServerClient = class {
       tokenEndpointResponse.claims
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
     if (options.fullResponse) {
       if (!response) {
-        throw new import_auth0_auth_js2.MissingCapturedResponseError();
+        throw new import_auth0_auth_js3.MissingCapturedResponseError();
       }
       return { data: result, response };
     }
@@ -1150,7 +1517,7 @@ var ServerClient = class {
       return;
     }
     if (!options.redirectUri || typeof options.redirectUri !== "string") {
-      throw new import_auth0_auth_js2.PasswordlessStartError("redirectUri is required to start a passwordless magic-link login.");
+      throw new import_auth0_auth_js3.PasswordlessStartError("redirectUri is required to start a passwordless magic-link login.");
     }
     const state = crypto.randomUUID();
     const scope = ensureOpenIdScope(options.scope ?? this.#options.authorizationParams?.scope);
@@ -1222,12 +1589,13 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
     if (options.fullResponse) {
       if (!response) {
-        throw new import_auth0_auth_js2.MissingCapturedResponseError();
+        throw new import_auth0_auth_js3.MissingCapturedResponseError();
       }
       return { data: result, response };
     }
@@ -1262,7 +1630,7 @@ var ServerClient = class {
     const expectedState = typeof transactionData.state === "string" ? transactionData.state : void 0;
     const returnedState = url.searchParams.get("state");
     if (!returnedState || !expectedState || returnedState !== expectedState) {
-      throw new import_auth0_auth_js2.PasswordlessVerifyError("State mismatch on magic-link callback");
+      throw new import_auth0_auth_js3.PasswordlessVerifyError("State mismatch on magic-link callback");
     }
     const domain = transactionData.domain ?? await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
@@ -1272,6 +1640,7 @@ var ServerClient = class {
       domain
     });
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
     return {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
@@ -1419,7 +1788,7 @@ var ServerClient = class {
       }
     }
     if (!stateData?.refreshToken) {
-      throw new import_auth0_auth_js2.TokenByRefreshTokenError(
+      throw new import_auth0_auth_js3.TokenByRefreshTokenError(
         "The access token has expired and a refresh token was not provided. The user needs to re-authenticate."
       );
     }
@@ -1458,7 +1827,7 @@ var ServerClient = class {
     };
     if (resolvedOptions?.fullResponse) {
       if (!response) {
-        throw new import_auth0_auth_js2.MissingCapturedResponseError();
+        throw new import_auth0_auth_js3.MissingCapturedResponseError();
       }
       return { data: returnTokenSet, response };
     }
@@ -1488,7 +1857,7 @@ var ServerClient = class {
       }
     }
     if (!stateData?.refreshToken) {
-      throw new import_auth0_auth_js2.TokenForConnectionError(
+      throw new import_auth0_auth_js3.TokenForConnectionError(
         "A refresh token was not found but is required to be able to retrieve an access token for a connection."
       );
     }
@@ -1529,7 +1898,7 @@ var ServerClient = class {
     };
     if (options.fullResponse) {
       if (!response) {
-        throw new import_auth0_auth_js2.MissingCapturedResponseError();
+        throw new import_auth0_auth_js3.MissingCapturedResponseError();
       }
       return { data: returnConnectionTokenSet, response };
     }
@@ -1579,6 +1948,29 @@ var ServerClient = class {
   }
   /**
    * Logs the user out and returns a URL to redirect the user-agent to after they log out.
+   *
+   * Clears the anonymous session as well, whenever an `anonymousStore` is configured. Logging
+   * out means the visitor is done, so leaving a 30-day anonymous credential behind in a
+   * cookie would be surprising, and `anonymous.getAccessToken()` would keep working right
+   * after the user logged out. This happens even when there is no user session to clear: a
+   * visitor who only ever had an anonymous session can log out. Unlike the automatic clearing
+   * at login, it is not affected by `clearAnonymousSessionOnLogin`, which exists so an
+   * application can finish its post-login work.
+   *
+   * In resolver (multi-tenant) mode the one exception is a stored user session belonging to a
+   * different Auth0 domain than the request resolves to. Nothing local is cleared in that
+   * case, anonymous session included, exactly as today: that state belongs to another tenant.
+   *
+   * The anonymous session is only ever cleared locally. The SDK does not call
+   * `POST /anonymous/logout`: that endpoint exists to clear the `auth0_anon` cookie in a
+   * browser, and it revokes nothing server-side. Your server never holds that cookie, so
+   * calling it would achieve nothing. If the visitor's browser created an anonymous session
+   * of its own (through `@auth0/auth0-spa-js`, for example), that cookie is not covered by
+   * this SDK and has to be cleared from the browser.
+   *
+   * Anonymous access tokens already handed out stay valid until they expire; there is no
+   * anonymous session to revoke them against.
+   *
    * @param options Options used to configure the logout process.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    * @param requestOptions Optional per-request options (signal, headers, customFetch). Applied to the token revocation ONLY. Building the logout URL is local string work and issues no request, so nothing here can affect it.
@@ -1599,12 +1991,14 @@ var ServerClient = class {
       } catch {
       }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      await this.#discardAnonymousSession(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);
     if (!stateData) {
+      await this.#discardAnonymousSession(storeOptions);
       return authClient.buildLogoutUrl(options);
     }
     const sessionDomain = this.#getSessionDomain(stateData);
@@ -1615,6 +2009,7 @@ var ServerClient = class {
       } catch {
       }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      await this.#discardAnonymousSession(storeOptions);
     }
     return authClient.buildLogoutUrl(options);
   }
@@ -1646,12 +2041,13 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
     if (options.fullResponse) {
       if (!response) {
-        throw new import_auth0_auth_js2.MissingCapturedResponseError();
+        throw new import_auth0_auth_js3.MissingCapturedResponseError();
       }
       return { data: result, response };
     }
@@ -1715,7 +2111,7 @@ var ServerClient = class {
       throw new MissingRequiredArgumentError("subjectTokenType");
     }
     if (options.organization !== void 0 && !options.organization.trim()) {
-      throw new import_auth0_auth_js2.OrganizationValidationError("organization must not be blank");
+      throw new import_auth0_auth_js3.OrganizationValidationError("organization must not be blank");
     }
     const domain = await this.#resolveDomain(storeOptions);
     const actor = await this.#resolveSessionTransferActor(options.actor, domain, storeOptions);
@@ -1789,7 +2185,7 @@ var ServerClient = class {
     url.searchParams.set("session_transfer_token", result.sessionTransferToken);
     if (options?.organization !== void 0) {
       if (!options.organization.trim()) {
-        throw new import_auth0_auth_js2.OrganizationValidationError("organization must not be blank");
+        throw new import_auth0_auth_js3.OrganizationValidationError("organization must not be blank");
       }
       url.searchParams.set("organization", options.organization);
     }
@@ -1893,7 +2289,7 @@ var ServerClient = class {
 };
 
 // src/encryption/index.ts
-var import_jose2 = require("jose");
+var import_jose3 = require("jose");
 var ENC = "A256CBC-HS512";
 var ALG = "dir";
 var DIGEST = "SHA-256";
@@ -1901,7 +2297,7 @@ var BIT_LENGTH = 512;
 var HKDF_INFO = "derived cookie encryption secret";
 var encoder;
 function isDecryptionError(e) {
-  return e instanceof import_jose2.errors.JWEDecryptionFailed || e instanceof import_jose2.errors.JWEInvalid;
+  return e instanceof import_jose3.errors.JWEDecryptionFailed || e instanceof import_jose3.errors.JWEInvalid;
 }
 async function deriveEncryptionSecret(secret, salt, kid) {
   encoder ||= new TextEncoder();
@@ -1922,7 +2318,7 @@ async function deriveEncryptionSecret(secret, salt, kid) {
 async function _encrypt(payload, secret, salt, expiration) {
   const kid = crypto.randomUUID();
   const encryptionSecret = await deriveEncryptionSecret(secret, salt, kid);
-  return await new import_jose2.EncryptJWT(payload).setProtectedHeader({ enc: ENC, alg: ALG, kid }).setExpirationTime(expiration).encrypt(encryptionSecret);
+  return await new import_jose3.EncryptJWT(payload).setProtectedHeader({ enc: ENC, alg: ALG, kid }).setExpirationTime(expiration).encrypt(encryptionSecret);
 }
 async function encrypt(payload, secret, salt, expiration) {
   if (typeof secret === "string") {
@@ -1936,7 +2332,7 @@ async function encrypt(payload, secret, salt, expiration) {
   }
 }
 async function _decrypt(value, secret, salt) {
-  const res = await (0, import_jose2.jwtDecrypt)(
+  const res = await (0, import_jose3.jwtDecrypt)(
     value,
     async (protectedHeader) => {
       if (!protectedHeader.kid) {
@@ -2014,7 +2410,7 @@ var AbstractTransactionStore = class extends AbstractStore {
 };
 
 // src/index.ts
-var import_auth0_auth_js6 = require("@auth0/auth0-auth-js");
+var import_auth0_auth_js8 = require("@auth0/auth0-auth-js");
 
 // src/store/cookie-transaction-store.ts
 var CookieTransactionStore = class extends AbstractTransactionStore {
@@ -2210,21 +2606,110 @@ var StatelessStateStore = class extends AbstractSessionStore {
   }
 };
 
+// src/store/abstract-anonymous-store.ts
+var AbstractAnonymousStore = class extends AbstractStore {
+  constructor(options) {
+    super(options);
+  }
+};
+
+// src/store/stateless-anonymous-store.ts
+var DEFAULT_ANONYMOUS_SESSION_LIFETIME = 60 * 60 * 24 * 30;
+var CHUNK_SIZE = 3072;
+var StatelessAnonymousStore = class extends AbstractAnonymousStore {
+  #cookieOptions;
+  #cookieHandler;
+  #sessionTokenLifetime;
+  constructor(options, cookieHandler) {
+    super(options);
+    this.#cookieOptions = options.cookie;
+    this.#cookieHandler = cookieHandler;
+    this.#sessionTokenLifetime = options.sessionTokenLifetime ?? DEFAULT_ANONYMOUS_SESSION_LIFETIME;
+  }
+  async set(identifier, anonymousStateData, removeIfExists, options) {
+    const expiration = this.#getExpiration(anonymousStateData);
+    const maxAge = expiration - Math.floor(Date.now() / 1e3);
+    if (maxAge <= 0) {
+      await this.delete(identifier, options);
+      return;
+    }
+    const cookieOpts = this.#getCookieOptions({ maxAge });
+    const encryptedStateData = await this.encrypt(identifier, anonymousStateData, expiration);
+    const chunkCount = Math.ceil(encryptedStateData.length / CHUNK_SIZE);
+    const chunks = [...Array(chunkCount).keys()].map((i) => ({
+      value: encryptedStateData.substring(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE),
+      name: `${identifier}.${i}`
+    }));
+    chunks.forEach((chunk) => {
+      this.#cookieHandler.setCookie(chunk.name, chunk.value, cookieOpts, options);
+    });
+    const existingCookieKeys = this.#getCookieKeys(identifier, options);
+    existingCookieKeys.filter((key) => !chunks.some((chunk) => chunk.name === key)).forEach((key) => {
+      this.#cookieHandler.deleteCookie(key, options, this.#getCookieOptions());
+    });
+  }
+  async get(identifier, options) {
+    const cookieKeys = this.#getCookieKeys(identifier, options);
+    const encryptedStateData = cookieKeys.map((key) => ({
+      index: parseInt(key.split(".")[1], 10),
+      value: this.#cookieHandler.getCookie(key, options)
+    })).sort((a, b) => a.index - b.index).map((item) => item.value).join("");
+    if (encryptedStateData) {
+      return await this.decrypt(identifier, encryptedStateData);
+    }
+  }
+  async delete(identifier, options) {
+    const cookieKeys = this.#getCookieKeys(identifier, options);
+    for (const key of cookieKeys) {
+      this.#cookieHandler.deleteCookie(key, options, this.#getCookieOptions());
+    }
+  }
+  /**
+   * Absolute expiry of the anonymous session, in Unix seconds.
+   *
+   * Prefers the value Auth0 reports. `sessionTokenExpiresAt` is not populated yet, because
+   * `auth0-auth-js` does not surface `session_expires_in` from the token response; until it
+   * does, this falls back to the configured lifetime measured from creation.
+   */
+  #getExpiration(anonymousStateData) {
+    return anonymousStateData.sessionTokenExpiresAt ?? anonymousStateData.createdAt + this.#sessionTokenLifetime;
+  }
+  #getCookieKeys(identifier, options) {
+    return Object.keys(this.#cookieHandler.getCookies(options)).filter((key) => key.startsWith(identifier));
+  }
+  #getCookieOptions(partial) {
+    return {
+      httpOnly: true,
+      sameSite: this.#cookieOptions?.sameSite ?? "lax",
+      path: this.#cookieOptions?.path ?? "/",
+      secure: this.#cookieOptions?.secure ?? true,
+      ...partial
+    };
+  }
+};
+
 // src/mfa/index.ts
-var import_auth0_auth_js3 = require("@auth0/auth0-auth-js");
+var import_auth0_auth_js4 = require("@auth0/auth0-auth-js");
 
 // src/passkey/index.ts
-var import_auth0_auth_js4 = require("@auth0/auth0-auth-js");
+var import_auth0_auth_js5 = require("@auth0/auth0-auth-js");
 
 // src/database/index.ts
-var import_auth0_auth_js5 = require("@auth0/auth0-auth-js");
+var import_auth0_auth_js6 = require("@auth0/auth0-auth-js");
+
+// src/anonymous/index.ts
+var import_auth0_auth_js7 = require("@auth0/auth0-auth-js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AbstractAnonymousStore,
   AbstractStateStore,
   AbstractTransactionStore,
+  AnonymousSessionError,
+  AnonymousSessionExpiredError,
   BackchannelLogoutError,
   ChangePasswordError,
   CookieTransactionStore,
+  DEFAULT_ANONYMOUS_SESSION_LIFETIME,
   EnterpriseConnectNotSupportedError,
   InvalidConfigurationError,
   IssuerValidationError,
@@ -2232,6 +2717,7 @@ var import_auth0_auth_js5 = require("@auth0/auth0-auth-js");
   MfaEnrollmentError,
   MfaListAuthenticatorsError,
   MfaVerifyError,
+  MissingAnonymousSessionError,
   MissingClientAuthError,
   MissingRequiredArgumentError,
   MissingSessionError,
@@ -2242,6 +2728,7 @@ var import_auth0_auth_js5 = require("@auth0/auth0-auth-js");
   PasskeyRegisterError,
   PasswordlessStartError,
   PasswordlessVerifyError,
+  ServerAnonymousClient,
   ServerClient,
   ServerDatabaseClient,
   ServerMfaClient,
@@ -2250,6 +2737,7 @@ var import_auth0_auth_js5 = require("@auth0/auth0-auth-js");
   SignUpError,
   StartLinkUserError,
   StatefulStateStore,
+  StatelessAnonymousStore,
   StatelessStateStore,
   TokenExchangeError,
   TokenExchangeErrorCode,