@auth0/auth0-server-js 1.15.0 → 1.16.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { ActClaim, AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, RequestOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, SignUpOptions, SignUpResult, ChangePasswordOptions, ApiResponse, GetUserInfoOptions, UserInfoResponse, TokenResponse } from '@auth0/auth0-auth-js';
-export { ActClaim, ApiResponse, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, ChangePasswordError, ChangePasswordOptions, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, EnterpriseConnectNotSupportedError, FullResponseOption, GetUserInfoOptions, IsFederatedDomainOptions, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, PasswordlessStartError, PasswordlessVerifyError, RequestOptions, SignUpError, SignUpOptions, SignUpResult, TelemetryConfig, TokenExchangeError, TokenResponse, TokenRevocationError, UserInfoError, UserInfoResponse, isFederatedDomain, isMfaRequiredError } from '@auth0/auth0-auth-js';
+import { ActClaim, AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, ListAuthenticatorsOptions, RequestOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, SignUpOptions, SignUpResult, ChangePasswordOptions, AuthClient, ApiResponse, GetUserInfoOptions, UserInfoResponse, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, AnonymousSessionError, ApiResponse, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, ChangePasswordError, ChangePasswordOptions, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, EnterpriseConnectNotSupportedError, FullResponseOption, GetUserInfoOptions, IsFederatedDomainOptions, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, PasswordlessStartError, PasswordlessVerifyError, RequestOptions, SignUpError, SignUpOptions, SignUpResult, TelemetryConfig, TokenExchangeError, TokenResponse, TokenRevocationError, UserInfoError, UserInfoResponse, isFederatedDomain, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -35,6 +35,13 @@ interface ServerClientOptions<TStoreOptions = unknown> {
     discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
+    /**
+     * Identifier (and cookie name, for cookie-backed stores) used for the anonymous session.
+     *
+     * Default: `__a0_anon`. This is the SDK's own store on your application's domain. It is
+     * unrelated to the `auth0_anon` cookie Auth0 sets on the Auth0 domain.
+     */
+    anonymousSessionIdentifier?: string;
     /**
      * Optional, custom Fetch implementation to use.
      */
@@ -45,6 +52,44 @@ interface ServerClientOptions<TStoreOptions = unknown> {
      * When `enterpriseConnect: true`, the state store is not needed (Auth0 does not manage a session).
      */
     stateStore?: StateStore<TStoreOptions>;
+    /**
+     * Store for anonymous sessions. Required to use the `anonymous` sub-client; accessing
+     * `serverClient.anonymous` without it throws `InvalidConfigurationError`.
+     *
+     * Pass a {@link StatelessAnonymousStore} for the cookie-backed default.
+     */
+    anonymousStore?: AnonymousStore<TStoreOptions>;
+    /**
+     * Whether the anonymous session is discarded once the visitor logs in. Default: `true`.
+     *
+     * An anonymous session holds a bearer credential for the anonymous identity that stays
+     * valid for 30 days by default. Once the visitor has authenticated, that credential has
+     * no purpose: leaving it behind keeps a cookie on every request and lets
+     * `anonymous.getAccessToken()` keep minting anonymous tokens for someone who is logged
+     * in. So every method that establishes a user session drops the anonymous session
+     * afterwards.
+     *
+     * The drop is best-effort and happens after the user session is written, so it can never
+     * fail a login.
+     *
+     * Set this to `false` when you need the anonymous identity on a later request — for
+     * example to merge a guest cart in a background job — and call
+     * `serverClient.anonymous.logout()` yourself once you are done with it. With the default
+     * `true`, read `serverClient.anonymous.getSession()` **before** completing the login:
+     *
+     * ```typescript
+     * const anonymousSession = await serverClient.anonymous.getSession(storeOptions);
+     * await serverClient.completeInteractiveLogin(url, storeOptions);
+     * if (anonymousSession?.sub) {
+     *   await mergeGuestCart(anonymousSession.sub);
+     * }
+     * ```
+     *
+     * Has no effect when no `anonymousStore` is configured. `serverClient.logout()` clears the
+     * anonymous session regardless of this setting; see {@link ServerClient.logout} for the one
+     * resolver-mode exception.
+     */
+    clearAnonymousSessionOnLogin?: boolean;
     /**
      * Indicates whether the SDK should use the mTLS endpoints if they are available.
      *
@@ -132,6 +177,83 @@ interface ConnectionTokenSet {
     connection: string;
     loginHint?: string;
 }
+/**
+ * An anonymous access token as held in the anonymous store.
+ *
+ * Auth0 may grant fewer scopes than requested for an anonymous caller. `scope` is what
+ * was actually granted — always check it before using the token. `requestedScope` is
+ * an internal cache key and is not meaningful to application code.
+ */
+interface AnonymousTokenSet extends TokenSet {
+}
+/**
+ * An anonymous session, as exposed to the application by
+ * {@link ServerAnonymousClient.getSession}.
+ *
+ * Deliberately does NOT carry the anonymous session token. That token is a long-lived
+ * bearer credential for the anonymous identity and is kept inside the SDK's anonymous
+ * store, in the same way the refresh token of a user session is never handed to
+ * application code by `getAccessToken()`.
+ */
+interface AnonymousSessionData {
+    /**
+     * The anonymous identity, in the form `anon@<uuid>`. This is the `sub` claim of every
+     * anonymous access token minted for this session, so it is the key to use for anything
+     * you store for the visitor before they log in (a guest cart, for instance).
+     *
+     * Captured from the first anonymous access token at creation. `undefined` when that token
+     * could not be read, which happens when the resource server has token encryption
+     * (`token_encryption`) enabled: the access token is then an encrypted JWE and nothing
+     * outside the API can read its claims. For such an audience the anonymous `sub` is not
+     * obtainable through this SDK, so treat it as optional in any merge path.
+     */
+    sub?: string;
+    /**
+     * The metadata attached to the anonymous identity at creation, as it was sent to Auth0.
+     *
+     * Kept here so the application does not have to shadow what it just supplied. Metadata is
+     * write-once, so this value cannot go stale.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Unix timestamp (seconds) at which this anonymous session was created by the SDK.
+     *
+     * The cookie lifetime is anchored to this value, so renewing an access token never
+     * extends the anonymous session.
+     */
+    createdAt: number;
+    /**
+     * Unix timestamp (seconds) at which the anonymous session itself expires (30 days by
+     * default, tenant-configurable).
+     *
+     * Currently always `undefined`: Auth0 returns the remaining session lifetime as
+     * `session_expires_in` on every anonymous token response, but `@auth0/auth0-auth-js`
+     * does not surface it yet. Until it does, the store falls back to a configured
+     * lifetime measured from {@link AnonymousSessionData.createdAt}.
+     */
+    sessionTokenExpiresAt?: number;
+    /**
+     * Anonymous access tokens held for this session, cached per audience and requested scope.
+     */
+    tokenSets: AnonymousTokenSet[];
+    /**
+     * The Auth0 domain the anonymous session was created against. Used in resolver
+     * (multi-tenant) mode to make sure a session is never reused across tenants.
+     */
+    domain?: string;
+    [key: string]: unknown;
+}
+/**
+ * The anonymous session as persisted by an {@link AnonymousStore}. Adds the session
+ * token, which never leaves the SDK.
+ */
+interface AnonymousStateData extends AnonymousSessionData {
+    /**
+     * The opaque handle for the anonymous identity, returned once by Auth0 at creation
+     * and never reissued. Used to re-mint anonymous access tokens.
+     */
+    sessionToken: string;
+}
 interface InternalStateData {
     sid: string;
     createdAt: number;
@@ -194,6 +316,19 @@ interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateDat
 }
 interface TransactionStore<TStoreOptions = unknown> extends AbstractDataStore<TransactionData, TStoreOptions> {
 }
+/**
+ * Store for anonymous sessions.
+ *
+ * Separate from the state store on purpose: an anonymous session is not a user session.
+ * Writing one into the state store would make `getSession()` and `getUser()` return
+ * something for a visitor who has not logged in, which every framework integration reads
+ * as "authenticated".
+ *
+ * Use {@link StatelessAnonymousStore} for the cookie-backed default, or implement this
+ * interface to keep anonymous sessions in your own backend.
+ */
+interface AnonymousStore<TStoreOptions = unknown> extends AbstractDataStore<AnonymousStateData, TStoreOptions> {
+}
 interface EncryptedStoreOptions {
     /**
      * The secret(s) to use for encryption and decryption. Can be a single string or an array of strings for secret rotation support.
@@ -650,24 +785,9 @@ interface MfaVerifyResponse {
     /** A new recovery code (only returned when verifying with a recovery code) */
     recoveryCode?: string;
 }
-/**
- * @internal
- * Options for constructing a ServerMfaClient.
- */
-interface ServerMfaClientOptions<TStoreOptions = unknown> {
-    authClient: AuthClient;
-    domain: string;
-    stateStore: StateStore<TStoreOptions>;
-    stateStoreIdentifier: string;
-    defaultAudience: string;
-}
 
 declare class ServerMfaClient<TStoreOptions = unknown> {
     #private;
-    /**
-     * @internal
-     */
-    constructor(options: ServerMfaClientOptions<TStoreOptions>);
     /**
      * Lists all MFA authenticators enrolled by the user.
      *
@@ -707,30 +827,8 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
     verify(options: MfaVerifyOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<MfaVerifyResponse>;
 }
 
-/**
- * @internal
- * Options for constructing a ServerPasskeyClient.
- *
- * Unlike the MFA client, the passkey client resolves the domain per call so it
- * keeps working in resolver (multi-tenant) mode. It therefore receives the
- * parent client's `resolveDomain` and `getAuthClient` helpers instead of a
- * fixed domain/authClient.
- */
-interface ServerPasskeyClientOptions<TStoreOptions = unknown> {
-    resolveDomain: (storeOptions?: TStoreOptions) => Promise<string>;
-    getAuthClient: (domain: string) => AuthClient;
-    stateStore: StateStore<TStoreOptions>;
-    stateStoreIdentifier: string;
-    defaultScope?: string;
-    defaultAudience?: string;
-}
-
 declare class ServerPasskeyClient<TStoreOptions = unknown> {
     #private;
-    /**
-     * @internal
-     */
-    constructor(options: ServerPasskeyClientOptions<TStoreOptions>);
     /**
      * Requests a passkey signup challenge for a new user.
      *
@@ -799,27 +897,8 @@ declare class ServerPasskeyClient<TStoreOptions = unknown> {
     getToken(options: GetTokenByPasskeyOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<PasskeyGetTokenResult>;
 }
 
-/**
- * @internal
- * Options for constructing a ServerDatabaseClient.
- *
- * Like the passkey client, the database client resolves the domain per call so
- * it keeps working in resolver (multi-tenant) mode. It therefore receives the
- * parent client's `resolveDomain` and `getAuthClient` helpers instead of a
- * fixed domain/authClient. Unlike the MFA/passkey clients, it never touches the
- * state store — signup and change-password write no session.
- */
-interface ServerDatabaseClientOptions<TStoreOptions = unknown> {
-    resolveDomain: (storeOptions?: TStoreOptions) => Promise<string>;
-    getAuthClient: (domain: string) => AuthClient;
-}
-
 declare class ServerDatabaseClient<TStoreOptions = unknown> {
     #private;
-    /**
-     * @internal
-     */
-    constructor(options: ServerDatabaseClientOptions<TStoreOptions>);
     /**
      * Registers a new user in a database connection.
      *
@@ -852,6 +931,211 @@ declare class ServerDatabaseClient<TStoreOptions = unknown> {
     changePassword(options: ChangePasswordOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<string>;
 }
 
+/**
+ * Options for creating an anonymous session.
+ */
+interface CreateAnonymousSessionOptions {
+    /**
+     * The API audience the anonymous access token should be scoped to.
+     * Defaults to `authorizationParams.audience` on the `ServerClient`.
+     */
+    audience?: string;
+    /**
+     * Space-separated scopes to request. Does not fall back to `authorizationParams.scope`
+     * (that value targets logged-in users and doesn't apply to anonymous identities).
+     */
+    scope?: string;
+    /**
+     * Up to 1024 bytes of string key-value metadata to attach to the anonymous identity.
+     * The limit applies to the JSON-serialized object, so keys, quotes, and punctuation all
+     * count. Set once at creation — Auth0 rejects metadata on any subsequent call. If the
+     * session expires and a new one is created, the old metadata is gone. Exceeding the limit
+     * throws an `AnonymousSessionError` with code `invalid_request`.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for retrieving an anonymous access token.
+ */
+interface GetAnonymousAccessTokenOptions {
+    /**
+     * The API audience the anonymous access token should be scoped to.
+     * Defaults to `authorizationParams.audience` on the `ServerClient`.
+     */
+    audience?: string;
+    /**
+     * Space-separated scopes to request. Does not fall back to `authorizationParams.scope`.
+     */
+    scope?: string;
+}
+
+/**
+ * Client for Auth0 Anonymous Sessions on the server.
+ *
+ * An anonymous session gives a visitor who has not logged in a stable identity
+ * (`anon@<uuid>`) and an access token, so your API can serve them personalised data
+ * before they authenticate. Reach it through `serverClient.anonymous`, which requires an
+ * `anonymousStore` on the `ServerClient`.
+ *
+ * How it is stored
+ * ----------------
+ * The anonymous session token is a long-lived bearer credential for the anonymous
+ * identity, so this client keeps it in the anonymous store and never returns it. The
+ * application only ever receives access tokens, exactly as it does for a user session.
+ *
+ * The anonymous store is separate from the state store on purpose. An anonymous visitor
+ * must not show up as a logged-in user, so `serverClient.getSession()` and
+ * `serverClient.getUser()` keep returning `undefined` while an anonymous session is
+ * active.
+ *
+ * Lifecycle
+ * ---------
+ * - {@link ServerAnonymousClient.createSession} is the only thing that creates a session.
+ *   Nothing here creates one implicitly, so an expired session surfaces as an error
+ *   instead of silently swapping the visitor onto a new anonymous identity (and silently
+ *   dropping their metadata).
+ * - {@link ServerAnonymousClient.getAccessToken} returns a cached token, or re-mints one
+ *   from the stored session token.
+ * - {@link ServerAnonymousClient.logout} discards the session locally.
+ * - Logging in ends the anonymous session. Every method that establishes a user session
+ *   drops it afterwards, as does `serverClient.logout()`. Read `getSession()` **before**
+ *   completing the login when you need the anonymous identity to merge data, or set
+ *   `clearAnonymousSessionOnLogin: false` on the `ServerClient` to keep it and call
+ *   `logout()` yourself.
+ *
+ * Linking an anonymous session to the user created at login
+ * ---------------------------------------------------------
+ * `startInteractiveLogin()` links an active anonymous session to the user at login
+ * automatically. When `anonymousStore` is configured and a session is in the store, the
+ * `ServerClient` mints a short-lived Session Transfer Ticket before the redirect and appends
+ * it to the `/authorize` URL as `anon_transfer_token`. Auth0 redeems the ticket during
+ * authorization and makes the anonymous session available to Actions as
+ * `event.anonymous_session`. No extra configuration is required.
+ *
+ * The ticket is valid for 30 seconds and is fail-open: if minting fails or the ticket
+ * expires before `/authorize` processes it, login continues without linking the anonymous
+ * session.
+ *
+ * The logins that do not go through `/authorize` cannot carry the ticket:
+ * `passkey.getToken()`, `completePasswordless()`, `completePasswordlessMagicLink()`,
+ * `loginBackchannel()`, and `loginWithCustomTokenExchange()`. Auth0 ignores any anonymous
+ * session on those endpoints. For those flows, do the merge in your own application using
+ * the anonymous `sub`.
+ *
+ * @example
+ * ```typescript
+ * // Give a visitor an anonymous identity on their first request.
+ * let session = await serverClient.anonymous.getSession(storeOptions);
+ * if (!session) {
+ *   await serverClient.anonymous.createSession(
+ *     { audience: 'https://api.example.com', metadata: { landing: 'pricing' } },
+ *     storeOptions
+ *   );
+ * }
+ *
+ * // On any later request, get a valid token for your API.
+ * try {
+ *   const { accessToken } = await serverClient.anonymous.getAccessToken(
+ *     { audience: 'https://api.example.com' },
+ *     storeOptions
+ *   );
+ * } catch (error) {
+ *   if (error instanceof AnonymousSessionExpiredError) {
+ *     await serverClient.anonymous.createSession({ audience: 'https://api.example.com' }, storeOptions);
+ *   }
+ * }
+ * ```
+ */
+declare class ServerAnonymousClient<TStoreOptions = unknown> {
+    #private;
+    /**
+     * 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.
+     */
+    createSession(options?: CreateAnonymousSessionOptions, storeOptions?: TStoreOptions): Promise<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.
+     */
+    getAccessToken(options?: GetAnonymousAccessTokenOptions, storeOptions?: TStoreOptions): Promise<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).
+     */
+    getSession(storeOptions?: TStoreOptions): Promise<AnonymousSessionData | undefined>;
+    /**
+     * 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.
+     */
+    logout(storeOptions?: TStoreOptions): Promise<void>;
+}
+
 declare class ServerClient<TStoreOptions = unknown> {
     #private;
     /**
@@ -902,6 +1186,35 @@ declare class ServerClient<TStoreOptions = unknown> {
      * request resolves the intended tenant.
      */
     get database(): ServerDatabaseClient<TStoreOptions>;
+    /**
+     * 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(): ServerAnonymousClient<TStoreOptions>;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the Enterprise Connect login flow. Performs WebFinger domain discovery
@@ -1202,6 +1515,29 @@ declare class ServerClient<TStoreOptions = unknown> {
     revokeRefreshToken(options?: RevokeRefreshTokenOptions, storeOptions?: TStoreOptions, requestOptions?: RequestOptions): Promise<void>;
     /**
      * 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.
@@ -1462,6 +1798,99 @@ declare class StatelessStateStore<TStoreOptions> extends AbstractSessionStore<TS
     private getCookieKeys;
 }
 
+/**
+ * Abstract class that can be used to implement an Encrypted JWT Anonymous Session Store,
+ * using the 'A256CBC-HS512' encryption algorithm.
+ *
+ * Extend this when you want the SDK's encryption but your own persistence (Redis, a
+ * database, and so on). For the cookie-backed default, use `StatelessAnonymousStore`.
+ */
+declare abstract class AbstractAnonymousStore<TStoreOptions = unknown> extends AbstractStore<AnonymousStateData, TStoreOptions> implements AnonymousStore<TStoreOptions> {
+    constructor(options: EncryptedStoreOptions);
+}
+
+/**
+ * Default lifetime of an anonymous session, in seconds (30 days).
+ *
+ * Matches the Auth0 default for `sessions.anonymous.lifetime_in_minutes`. Override it with
+ * {@link StatelessAnonymousStoreOptions.sessionTokenLifetime} when your tenant is configured
+ * differently.
+ */
+declare const DEFAULT_ANONYMOUS_SESSION_LIFETIME: number;
+/**
+ * Cookie attributes for the anonymous session cookie.
+ *
+ * This is your application's own cookie on your own domain. It is not the `auth0_anon`
+ * cookie, which Auth0 sets on the Auth0 domain and controls itself.
+ */
+interface AnonymousCookieOptions {
+    /**
+     * The sameSite attribute of the anonymous session cookie.
+     *
+     * Default: `lax`. `lax` is enough: this cookie is only ever read by your own server on
+     * requests to your own site.
+     */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /**
+     * The secure attribute of the anonymous session cookie.
+     *
+     * Default: `true`. Set it to `false` only for local development over plain HTTP.
+     */
+    secure?: boolean;
+    /**
+     * The path attribute of the anonymous session cookie.
+     *
+     * Default: `/`.
+     */
+    path?: string;
+}
+interface StatelessAnonymousStoreOptions extends EncryptedStoreOptions {
+    /**
+     * Lifetime of an anonymous session in seconds, used to work out the cookie's `Max-Age`.
+     *
+     * Default: 30 days, matching the Auth0 default. This should match
+     * `sessions.anonymous.lifetime_in_minutes` on your tenant. It is only a client-side
+     * bound: Auth0 is the authority on when the anonymous session token stops working, and a
+     * request made after that point fails with `AnonymousSessionExpiredError` regardless of
+     * what is configured here.
+     */
+    sessionTokenLifetime?: number;
+    /**
+     * The options for the anonymous session cookie.
+     */
+    cookie?: AnonymousCookieOptions;
+}
+/**
+ * Stateless anonymous session store.
+ *
+ * Keeps the whole anonymous session in an encrypted, `HttpOnly` cookie on your application's
+ * domain, chunked across several cookies when needed, so it needs no server-side storage.
+ * Pass it as `anonymousStore` on the `ServerClient`, alongside `StatelessStateStore`.
+ *
+ * The cookie's `Max-Age` is anchored to the moment the anonymous session was created, so
+ * renewing an access token does not extend it. Auth0 never reissues an anonymous session
+ * token, so a rolling expiry here would keep a 30-day session alive forever.
+ *
+ * @example
+ * ```typescript
+ * const serverClient = new ServerClient({
+ *   domain: '<AUTH0_DOMAIN>',
+ *   clientId: '<AUTH0_CLIENT_ID>',
+ *   clientSecret: '<AUTH0_CLIENT_SECRET>',
+ *   transactionStore: new CookieTransactionStore({ secret }, cookieHandler),
+ *   stateStore: new StatelessStateStore({ secret }, cookieHandler),
+ *   anonymousStore: new StatelessAnonymousStore({ secret }, cookieHandler),
+ * });
+ * ```
+ */
+declare class StatelessAnonymousStore<TStoreOptions> extends AbstractAnonymousStore<TStoreOptions> {
+    #private;
+    constructor(options: StatelessAnonymousStoreOptions, cookieHandler: CookieHandler<TStoreOptions>);
+    set(identifier: string, anonymousStateData: AnonymousStateData, removeIfExists?: boolean, options?: TStoreOptions): Promise<void>;
+    get(identifier: string, options?: TStoreOptions): Promise<AnonymousStateData | undefined>;
+    delete(identifier: string, options?: TStoreOptions): Promise<void>;
+}
+
 /**
  * Codes carried on the `code` field of a `TokenExchangeError` raised by the Session
  * Transfer Token (STT) flow. These are specific to Custom Token Exchange Impersonation
@@ -1536,6 +1965,37 @@ declare class IssuerValidationError extends Error {
     code: string;
     constructor(message: string);
 }
+/**
+ * Error thrown when an anonymous session is required but none is stored for this visitor.
+ *
+ * Anonymous sessions are never created implicitly. Call
+ * `serverClient.anonymous.createSession()` first, and use
+ * `serverClient.anonymous.getSession()` to check whether a visitor already has one.
+ */
+declare class MissingAnonymousSessionError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the anonymous session has expired or was rejected by Auth0, so no new
+ * anonymous access token can be minted for it.
+ *
+ * The stored anonymous session is deleted before this is thrown. Call
+ * `serverClient.anonymous.createSession()` to start a new one. Any metadata attached to
+ * the previous anonymous identity is gone: metadata is set once, at creation.
+ *
+ * Recovering from this is not free. `@auth0/auth0-auth-js` answers an expired session token
+ * by creating a replacement anonymous identity rather than reporting the expiry, so by the
+ * time this error is raised Auth0 has already minted an identity the SDK deliberately
+ * discards (storing it would move the visitor onto an identity they never asked for, without
+ * their metadata). The `createSession()` that recovers is therefore a second call to Auth0,
+ * and under concurrency every in-flight request pays it. Handle this once, on a path the
+ * visitor actually needs a token on, rather than in a retry loop.
+ */
+declare class AnonymousSessionExpiredError extends Error {
+    code: string;
+    constructor(message?: string);
+}
 /**
  * Error thrown when the session has passed its upstream IdP-asserted
  * `session_expiry` ceiling (IPSIE SL1). The user must re-authenticate.
@@ -1545,4 +2005,4 @@ declare class SessionExpiredError extends Error {
     constructor(message?: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type BuildSessionTransferRedirectOptions, type CompletePasswordlessEmailOptions, type CompletePasswordlessOptions, type CompletePasswordlessResult, type CompletePasswordlessSmsOptions, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, type PasskeyGetTokenResult, type RequestSessionTransferTokenOptions, type RevokeRefreshTokenOptions, ServerClient, type ServerClientOptions, ServerDatabaseClient, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type SessionTransferActor, type SessionTransferTokenResult, type StartEnterpriseLoginOptions, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, TokenExchangeErrorCode, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { AbstractAnonymousStore, type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AnonymousCookieOptions, type AnonymousSessionData, AnonymousSessionExpiredError, type AnonymousStateData, type AnonymousStore, type AnonymousTokenSet, type AuthorizationParameters, BackchannelLogoutError, type BuildSessionTransferRedirectOptions, type CompletePasswordlessEmailOptions, type CompletePasswordlessOptions, type CompletePasswordlessResult, type CompletePasswordlessSmsOptions, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CreateAnonymousSessionOptions, type CustomTokenExchangeOptions, DEFAULT_ANONYMOUS_SESSION_LIFETIME, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type GetAnonymousAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingAnonymousSessionError, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, type PasskeyGetTokenResult, type RequestSessionTransferTokenOptions, type RevokeRefreshTokenOptions, ServerAnonymousClient, ServerClient, type ServerClientOptions, ServerDatabaseClient, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type SessionTransferActor, type SessionTransferTokenResult, type StartEnterpriseLoginOptions, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessAnonymousStore, type StatelessAnonymousStoreOptions, StatelessStateStore, TokenExchangeErrorCode, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };