@auth0/auth0-server-js 1.15.0 → 1.16.0

package/dist/index.js

@@ -53,6 +53,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) {
@@ -203,7 +219,7 @@ var compareScopes = (scopes, requiredScopes) => {
 };
 
 // src/server-client.ts
-import { decodeJwt } from "jose";
+import { decodeJwt as decodeJwt2 } from "jose";
 
 // src/telemetry.ts
 function getTelemetryConfig(config) {
@@ -213,7 +229,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.0"
   };
 }
 
@@ -287,6 +303,7 @@ var ServerMfaClient = class {
       true,
       storeOptions
     );
+    await this.#options.onUserSessionEstablished?.(storeOptions);
     const result = {
       accessToken: tokenResponse.accessToken,
       tokenType: tokenResponse.tokenType ?? "bearer",
@@ -395,6 +412,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
     };
@@ -489,6 +507,225 @@ function applyEnterpriseConnectRestrictions(instance) {
   }
 }
 
+// src/anonymous/server-anonymous-client.ts
+import { decodeJwt } from "jose";
+var DEFAULT_AUDIENCE_CACHE_KEY = "default";
+var readAnonymousSub = (accessToken) => {
+  try {
+    const { sub } = 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;
+    }
+    const renewed = await this.#options.getAuthClient(domain).anonymous.getAccessToken({
+      sessionToken: stateData.sessionToken,
+      ...requestedAudience && { audience: requestedAudience },
+      ...scope && { scope }
+    });
+    if (renewed.sessionReplaced) {
+      await this.#options.anonymousStore.delete(this.#options.anonymousStoreIdentifier, storeOptions);
+      throw new AnonymousSessionExpiredError();
+    }
+    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();
@@ -497,7 +734,7 @@ var normalizeDomain = (value) => {
 };
 var decodeIssuer = (token) => {
   try {
-    const { iss } = decodeJwt(token);
+    const { iss } = decodeJwt2(token);
     return typeof iss === "string" ? iss : void 0;
   } catch {
     return void 0;
@@ -512,7 +749,7 @@ var actorUnavailableError = (message) => {
 };
 var isTokenExpired = (token) => {
   try {
-    const { exp } = decodeJwt(token);
+    const { exp } = decodeJwt2(token);
     if (typeof exp !== "number") {
       return true;
     }
@@ -534,6 +771,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.
@@ -596,6 +834,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;
@@ -654,7 +928,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({
@@ -663,12 +938,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") {
@@ -745,6 +1034,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.
    *
@@ -780,6 +1117,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: {
@@ -787,7 +1135,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 = {
@@ -857,6 +1206,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
@@ -1024,6 +1374,7 @@ var ServerClient = class {
       tokenEndpointResponse.claims
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
@@ -1170,6 +1521,7 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
@@ -1220,6 +1572,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
@@ -1527,6 +1880,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.
@@ -1547,12 +1923,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);
@@ -1563,6 +1941,7 @@ var ServerClient = class {
       } catch {
       }
       await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      await this.#discardAnonymousSession(storeOptions);
     }
     return authClient.buildLogoutUrl(options);
   }
@@ -1594,6 +1973,7 @@ var ServerClient = class {
       { domain }
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#clearAnonymousSessionAfterLogin(storeOptions);
     const result = {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
@@ -2169,6 +2549,88 @@ 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
 import {
   MfaListAuthenticatorsError,
@@ -2188,12 +2650,19 @@ import {
 
 // src/database/index.ts
 import { SignUpError, ChangePasswordError } from "@auth0/auth0-auth-js";
+
+// src/anonymous/index.ts
+import { AnonymousSessionError } from "@auth0/auth0-auth-js";
 export {
+  AbstractAnonymousStore,
   AbstractStateStore,
   AbstractTransactionStore,
+  AnonymousSessionError,
+  AnonymousSessionExpiredError,
   BackchannelLogoutError,
   ChangePasswordError,
   CookieTransactionStore,
+  DEFAULT_ANONYMOUS_SESSION_LIFETIME,
   EnterpriseConnectNotSupportedError2 as EnterpriseConnectNotSupportedError,
   InvalidConfigurationError,
   IssuerValidationError,
@@ -2201,6 +2670,7 @@ export {
   MfaEnrollmentError,
   MfaListAuthenticatorsError,
   MfaVerifyError,
+  MissingAnonymousSessionError,
   MissingClientAuthError,
   MissingRequiredArgumentError,
   MissingSessionError,
@@ -2211,6 +2681,7 @@ export {
   PasskeyRegisterError,
   PasswordlessStartError2 as PasswordlessStartError,
   PasswordlessVerifyError2 as PasswordlessVerifyError,
+  ServerAnonymousClient,
   ServerClient,
   ServerDatabaseClient,
   ServerMfaClient,
@@ -2219,6 +2690,7 @@ export {
   SignUpError,
   StartLinkUserError,
   StatefulStateStore,
+  StatelessAnonymousStore,
   StatelessStateStore,
   TokenExchangeError2 as TokenExchangeError,
   TokenExchangeErrorCode,