@auth0/auth0-server-js 1.7.0 → 1.9.0

package/dist/index.d.cts

@@ -26,6 +26,12 @@ interface ServerClientOptions<TStoreOptions = unknown> {
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * Default organization for all interactive login flows from this client.
+     * Can be an organization ID (e.g. `org_abc123`) or an organization name (e.g. `acme-corp`).
+     * A per-login value in {@link StartInteractiveLoginOptions} overrides this.
+     */
+    organization?: string;
     discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
@@ -57,12 +63,19 @@ interface UserClaims {
     email?: string;
     email_verified?: boolean;
     org_id?: string;
+    org_name?: string;
     [key: string]: unknown;
 }
 interface AuthorizationParameters {
     scope?: string;
     audience?: string;
     redirect_uri?: string;
+    /**
+     * The organization to log the user into. Prefer the first-class `organization`
+     * option on {@link StartInteractiveLoginOptions} / {@link ServerClientOptions};
+     * this is supported for backwards compatibility.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface TokenSet {
@@ -92,6 +105,15 @@ interface SessionData {
     tokenSets: TokenSet[];
     connectionTokenSets?: ConnectionTokenSet[];
     domain?: string;
+    /**
+     * IPSIE SL1 `session_expiry` ceiling for this session, as an absolute Unix timestamp in
+     * seconds. Present only when the user logged in through an enterprise connection configured
+     * with `id_token_session_expiry_supported: true`. When set, the SDK treats the session as
+     * expired once this time is reached (minus a small leeway) and forces re-authentication.
+     * Absent for database/social logins, connections without the option, and sessions created
+     * before this feature — those behave unchanged.
+     */
+    sessionExpiresAt?: number;
     [key: string]: unknown;
 }
 interface TransactionData {
@@ -103,6 +125,11 @@ interface TransactionData {
      */
     codeVerifier?: string;
     domain?: string;
+    /**
+     * The organization requested at login, carried across the redirect so the
+     * returned ID token's organization claim can be validated at callback.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -137,6 +164,18 @@ interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
     appState?: TAppState;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * The organization to log the user into. Overrides the client-level
+     * `organization` default. Can be an organization ID (`org_abc123`) or name
+     * (`acme-corp`). Also passable via `authorizationParams.organization`.
+     */
+    organization?: string;
+    /**
+     * The organization invitation ticket, when handling an invitation-acceptance flow.
+     * Requires `organization` to be set (per-login, client-level default, or via
+     * `authorizationParams`); providing `invitation` without an organization throws.
+     */
+    invitation?: string;
 }
 interface LoginBackchannelOptions {
     bindingMessage: string;
@@ -603,9 +642,16 @@ declare class ServerClient<TStoreOptions = unknown> {
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+     *
+     * When `organization` is provided (per-login option, client-level default, or via
+     * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+     * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+     *
      * @param options Optional options used to configure the interactive login process.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
+     * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+     * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
      * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -619,6 +665,8 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingTransactionError} When no transaction was found.
      * @throws {TokenByCodeError} If there was an issue requesting the access token.
+     * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
+     * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).
      */
@@ -633,6 +681,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingSessionError} If there is no active session.
      * @throws {BuildLinkUserUrlError} If there was an issue when building the Authorization URL.
+     * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
      */
@@ -658,6 +707,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingSessionError} If there is no active session.
      * @throws {BuildUnlinkUserUrlError} If there was an issue when building the User Unlinking URL.
+     * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
      */
@@ -685,6 +735,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
      * @throws {BackchannelAuthenticationError} If there was an issue when doing backchannel authentication.
+     * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
      */
@@ -954,8 +1005,9 @@ declare abstract class AbstractSessionStore<TStoreOptions> extends AbstractState
     constructor(options: SessionConfiguration & EncryptedStoreOptions);
     /**
      * calculateMaxAge calculates the max age of the session based on createdAt and the rolling and absolute durations.
+     * When sessionExpiresAt is provided, caps the maxAge to not exceed the time until that ceiling.
      */
-    protected calculateMaxAge(createdAt: number): number;
+    protected calculateMaxAge(createdAt: number, sessionExpiresAt?: number): number;
 }
 
 interface StatefulStateStoreOptions<TStoreOptions> extends EncryptedStoreOptions {
@@ -1030,5 +1082,13 @@ declare class IssuerValidationError 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.
+ */
+declare class SessionExpiredError extends Error {
+    code: string;
+    constructor(message?: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, 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, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, 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, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.d.ts

@@ -26,6 +26,12 @@ interface ServerClientOptions<TStoreOptions = unknown> {
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * Default organization for all interactive login flows from this client.
+     * Can be an organization ID (e.g. `org_abc123`) or an organization name (e.g. `acme-corp`).
+     * A per-login value in {@link StartInteractiveLoginOptions} overrides this.
+     */
+    organization?: string;
     discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
@@ -57,12 +63,19 @@ interface UserClaims {
     email?: string;
     email_verified?: boolean;
     org_id?: string;
+    org_name?: string;
     [key: string]: unknown;
 }
 interface AuthorizationParameters {
     scope?: string;
     audience?: string;
     redirect_uri?: string;
+    /**
+     * The organization to log the user into. Prefer the first-class `organization`
+     * option on {@link StartInteractiveLoginOptions} / {@link ServerClientOptions};
+     * this is supported for backwards compatibility.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface TokenSet {
@@ -92,6 +105,15 @@ interface SessionData {
     tokenSets: TokenSet[];
     connectionTokenSets?: ConnectionTokenSet[];
     domain?: string;
+    /**
+     * IPSIE SL1 `session_expiry` ceiling for this session, as an absolute Unix timestamp in
+     * seconds. Present only when the user logged in through an enterprise connection configured
+     * with `id_token_session_expiry_supported: true`. When set, the SDK treats the session as
+     * expired once this time is reached (minus a small leeway) and forces re-authentication.
+     * Absent for database/social logins, connections without the option, and sessions created
+     * before this feature — those behave unchanged.
+     */
+    sessionExpiresAt?: number;
     [key: string]: unknown;
 }
 interface TransactionData {
@@ -103,6 +125,11 @@ interface TransactionData {
      */
     codeVerifier?: string;
     domain?: string;
+    /**
+     * The organization requested at login, carried across the redirect so the
+     * returned ID token's organization claim can be validated at callback.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -137,6 +164,18 @@ interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
     appState?: TAppState;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * The organization to log the user into. Overrides the client-level
+     * `organization` default. Can be an organization ID (`org_abc123`) or name
+     * (`acme-corp`). Also passable via `authorizationParams.organization`.
+     */
+    organization?: string;
+    /**
+     * The organization invitation ticket, when handling an invitation-acceptance flow.
+     * Requires `organization` to be set (per-login, client-level default, or via
+     * `authorizationParams`); providing `invitation` without an organization throws.
+     */
+    invitation?: string;
 }
 interface LoginBackchannelOptions {
     bindingMessage: string;
@@ -603,9 +642,16 @@ declare class ServerClient<TStoreOptions = unknown> {
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+     *
+     * When `organization` is provided (per-login option, client-level default, or via
+     * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+     * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+     *
      * @param options Optional options used to configure the interactive login process.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
+     * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+     * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
      * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -619,6 +665,8 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingTransactionError} When no transaction was found.
      * @throws {TokenByCodeError} If there was an issue requesting the access token.
+     * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
+     * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).
      */
@@ -633,6 +681,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingSessionError} If there is no active session.
      * @throws {BuildLinkUserUrlError} If there was an issue when building the Authorization URL.
+     * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
      */
@@ -658,6 +707,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingSessionError} If there is no active session.
      * @throws {BuildUnlinkUserUrlError} If there was an issue when building the User Unlinking URL.
+     * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
      */
@@ -685,6 +735,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
      * @throws {BackchannelAuthenticationError} If there was an issue when doing backchannel authentication.
+     * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
      */
@@ -954,8 +1005,9 @@ declare abstract class AbstractSessionStore<TStoreOptions> extends AbstractState
     constructor(options: SessionConfiguration & EncryptedStoreOptions);
     /**
      * calculateMaxAge calculates the max age of the session based on createdAt and the rolling and absolute durations.
+     * When sessionExpiresAt is provided, caps the maxAge to not exceed the time until that ceiling.
      */
-    protected calculateMaxAge(createdAt: number): number;
+    protected calculateMaxAge(createdAt: number, sessionExpiresAt?: number): number;
 }
 
 interface StatefulStateStoreOptions<TStoreOptions> extends EncryptedStoreOptions {
@@ -1030,5 +1082,13 @@ declare class IssuerValidationError 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.
+ */
+declare class SessionExpiredError extends Error {
+    code: string;
+    constructor(message?: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, 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, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, 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, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, SessionExpiredError, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.js

@@ -48,14 +48,55 @@ var IssuerValidationError = class extends Error {
     this.name = "IssuerValidationError";
   }
 };
+var SessionExpiredError = class extends Error {
+  code = "session_expired";
+  constructor(message) {
+    super(
+      message ?? "The session has expired because the upstream identity provider session ceiling was reached. The user needs to re-authenticate."
+    );
+    this.name = "SessionExpiredError";
+  }
+};
 
 // src/state/utils.ts
+var SESSION_EXPIRY_LEEWAY = 30;
+var MAX_PLAUSIBLE_UNIX_SECONDS = 1e10;
+function isPlausibleUnixSeconds(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value < MAX_PLAUSIBLE_UNIX_SECONDS;
+}
+function extractSessionExpiry(claims) {
+  const value = claims?.session_expiry;
+  return isPlausibleUnixSeconds(value) ? value : void 0;
+}
+function isSessionExpiryReached(sessionExpiresAt, nowSeconds) {
+  if (sessionExpiresAt === void 0) {
+    return false;
+  }
+  const now = nowSeconds ?? Math.floor(Date.now() / 1e3);
+  return now >= sessionExpiresAt - SESSION_EXPIRY_LEEWAY;
+}
 var createUpdatedTokenSet = (audience, response) => ({
   audience,
   accessToken: response.accessToken,
   scope: response.scope,
   expiresAt: response.expiresAt
 });
+function isSessionExpiryInPast(sessionExpiresAt, issuedAt) {
+  if (sessionExpiresAt === void 0) {
+    return false;
+  }
+  const reference = isPlausibleUnixSeconds(issuedAt) ? issuedAt : Math.floor(Date.now() / 1e3);
+  return sessionExpiresAt <= reference + SESSION_EXPIRY_LEEWAY;
+}
+function applySessionExpiryAtLogin(stateData, claims) {
+  const sessionExpiresAt = extractSessionExpiry(claims);
+  if (isSessionExpiryInPast(sessionExpiresAt, claims?.iat)) {
+    throw new SessionExpiredError(
+      "The upstream identity provider session_expiry is at or before the issued-at time; refusing to create an already-expired session."
+    );
+  }
+  return { ...stateData, sessionExpiresAt };
+}
 function updateStateData(audience, stateData, tokenEndpointResponse, context) {
   if (stateData && tokenEndpointResponse.claims) {
     const newSub = tokenEndpointResponse.claims.sub;
@@ -122,6 +163,7 @@ function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointR
 import {
   TokenForConnectionError,
   AuthClient,
+  OrganizationValidationError,
   PasswordlessStartError,
   PasswordlessVerifyError,
   TokenByRefreshTokenError
@@ -163,7 +205,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.7.0"
+    version: config?.version ?? "1.9.0"
   };
 }
 
@@ -225,9 +267,12 @@ var ServerMfaClient = class {
       this.#options.stateStoreIdentifier,
       storeOptions
     );
-    const updatedStateData = updateStateData(audience, existingStateData, tokenResponse, {
-      domain: this.#options.domain
-    });
+    const updatedStateData = applySessionExpiryAtLogin(
+      updateStateData(audience, existingStateData, tokenResponse, {
+        domain: this.#options.domain
+      }),
+      tokenResponse.claims
+    );
     await this.#options.stateStore.set(
       this.#options.stateStoreIdentifier,
       updatedStateData,
@@ -511,9 +556,16 @@ var ServerClient = class {
   }
   /**
    * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+   *
+   * When `organization` is provided (per-login option, client-level default, or via
+   * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+   * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+   *
    * @param options Optional options used to configure the interactive login process.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
+   * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+   * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
    * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
    *
    * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -524,6 +576,16 @@ var ServerClient = class {
       throw new MissingRequiredArgumentError("authorizationParams.redirect_uri");
     }
     const scope = ensureOpenIdScope(options?.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
+    const perLoginAuthParamsOrganization = typeof options?.authorizationParams?.organization === "string" ? options.authorizationParams.organization : void 0;
+    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 OrganizationValidationError("organization must not be blank");
+    }
+    const hasInvitation = !!(options?.invitation || options?.authorizationParams?.invitation);
+    if (hasInvitation && !resolvedOrganization) {
+      throw new InvalidConfigurationError("organization is required when invitation is provided.");
+    }
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
     const { codeVerifier, authorizationUrl } = await authClient.buildAuthorizationUrl({
@@ -531,7 +593,9 @@ var ServerClient = class {
       authorizationParams: {
         ...options?.authorizationParams,
         redirect_uri: redirectUri,
-        scope
+        scope,
+        ...resolvedOrganization ? { organization: resolvedOrganization } : {},
+        ...options?.invitation ? { invitation: options.invitation } : {}
       }
     });
     const transactionState = {
@@ -539,6 +603,9 @@ var ServerClient = class {
       codeVerifier,
       domain
     };
+    if (resolvedOrganization) {
+      transactionState.organization = resolvedOrganization;
+    }
     if (options?.appState) {
       transactionState.appState = options.appState;
     }
@@ -553,6 +620,8 @@ var ServerClient = class {
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
+   * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
+   * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
    *
    * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).
    */
@@ -565,14 +634,18 @@ var ServerClient = class {
     const authClient = this.#getAuthClient(domain);
     const tokenEndpointResponse = await authClient.getTokenByCode(url, {
       // TransactionData.codeVerifier is optional only to accommodate magic-link transactions.
-      codeVerifier: transactionData.codeVerifier
+      codeVerifier: transactionData.codeVerifier,
+      organization: transactionData.organization
     });
+    await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
-    const stateData = updateStateData(transactionData.audience ?? "default", existingStateData, tokenEndpointResponse, {
-      domain
-    });
+    const stateData = applySessionExpiryAtLogin(
+      updateStateData(transactionData.audience ?? "default", existingStateData, tokenEndpointResponse, {
+        domain
+      }),
+      tokenEndpointResponse.claims
+    );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
-    await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
     return { appState: transactionData.appState, authorizationDetails: tokenEndpointResponse.authorizationDetails };
   }
   /**
@@ -582,6 +655,7 @@ var ServerClient = class {
    *
    * @throws {MissingSessionError} If there is no active session.
    * @throws {BuildLinkUserUrlError} If there was an issue when building the Authorization URL.
+   * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
    *
    * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
    */
@@ -598,6 +672,10 @@ var ServerClient = class {
         throw new MissingSessionError("Session domain does not match the current domain.");
       }
     }
+    if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      throw new SessionExpiredError();
+    }
     const domain = this.#getSessionDomain(stateData);
     const authClient = this.#getAuthClient(domain);
     const { linkUserUrl, codeVerifier } = await authClient.buildLinkUserUrl({
@@ -641,6 +719,7 @@ var ServerClient = class {
    *
    * @throws {MissingSessionError} If there is no active session.
    * @throws {BuildUnlinkUserUrlError} If there was an issue when building the User Unlinking URL.
+   * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and re-authentication is required.
    *
    * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
    */
@@ -657,6 +736,10 @@ var ServerClient = class {
         throw new MissingSessionError("Session domain does not match the current domain.");
       }
     }
+    if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      throw new SessionExpiredError();
+    }
     const domain = this.#getSessionDomain(stateData);
     const authClient = this.#getAuthClient(domain);
     const { unlinkUserUrl, codeVerifier } = await authClient.buildUnlinkUserUrl({
@@ -701,6 +784,7 @@ var ServerClient = class {
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
    * @throws {BackchannelAuthenticationError} If there was an issue when doing backchannel authentication.
+   * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
    *
    * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
    */
@@ -717,11 +801,11 @@ var ServerClient = class {
       }
     });
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
-    const stateData = updateStateData(
-      this.#options.authorizationParams?.audience ?? "default",
-      existingStateData,
-      tokenEndpointResponse,
-      { domain }
+    const stateData = applySessionExpiryAtLogin(
+      updateStateData(this.#options.authorizationParams?.audience ?? "default", existingStateData, tokenEndpointResponse, {
+        domain
+      }),
+      tokenEndpointResponse.claims
     );
     await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
     return {
@@ -916,6 +1000,10 @@ var ServerClient = class {
         return;
       }
     }
+    if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      return;
+    }
     return stateData.user;
   }
   /**
@@ -932,6 +1020,10 @@ var ServerClient = class {
           return;
         }
       }
+      if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+        await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+        return;
+      }
       const { internal, ...sessionData } = stateData;
       return sessionData;
     }
@@ -948,6 +1040,7 @@ var ServerClient = class {
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
    * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`.
+   * @throws {SessionExpiredError} When the session's `session_expiry` ceiling has been reached; the session is cleared and no refresh is attempted — the user must re-authenticate.
    *
    * @returns The Token Set, containing the access token, as well as additional information.
    */
@@ -975,6 +1068,10 @@ var ServerClient = class {
         throw new MissingSessionError("Session domain does not match the current domain.");
       }
     }
+    if (stateData && isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, resolvedStoreOptions);
+      throw new SessionExpiredError();
+    }
     const tokenSet = stateData?.tokenSets.find(
       (tokenSet2) => tokenSet2.audience === audience && (!scope || compareScopes(tokenSet2.scope, scope))
     );
@@ -1309,7 +1406,7 @@ var AbstractTransactionStore = class extends AbstractStore {
 };
 
 // src/index.ts
-import { TokenExchangeError, MissingClientAuthError } from "@auth0/auth0-auth-js";
+import { TokenExchangeError, MissingClientAuthError, OrganizationValidationError as OrganizationValidationError3 } from "@auth0/auth0-auth-js";
 
 // src/store/cookie-transaction-store.ts
 var CookieTransactionStore = class extends AbstractTransactionStore {
@@ -1349,14 +1446,14 @@ var AbstractSessionStore = class extends AbstractStateStore {
   }
   /**
    * calculateMaxAge calculates the max age of the session based on createdAt and the rolling and absolute durations.
+   * When sessionExpiresAt is provided, caps the maxAge to not exceed the time until that ceiling.
    */
-  calculateMaxAge(createdAt) {
-    if (!this.#rolling) {
-      return this.#absoluteDuration;
-    }
+  calculateMaxAge(createdAt, sessionExpiresAt) {
     const now = Date.now() / 1e3 | 0;
-    const expiresAt = Math.min(now + this.#inactivityDuration, createdAt + this.#absoluteDuration);
-    const maxAge = expiresAt - now;
+    let maxAge = this.#rolling ? Math.min(now + this.#inactivityDuration, createdAt + this.#absoluteDuration) - now : this.#absoluteDuration;
+    if (sessionExpiresAt !== void 0) {
+      maxAge = Math.min(maxAge, sessionExpiresAt - now);
+    }
     return maxAge > 0 ? maxAge : 0;
   }
 };
@@ -1384,7 +1481,7 @@ var StatefulStateStore = class extends AbstractSessionStore {
       sessionId = generateId();
     }
     sessionId ??= generateId();
-    const maxAge = this.calculateMaxAge(stateData.internal.createdAt);
+    const maxAge = this.calculateMaxAge(stateData.internal.createdAt, stateData.sessionExpiresAt);
     const cookieOpts = this.#getCookieOptions({
       maxAge
     });
@@ -1449,7 +1546,7 @@ var StatelessStateStore = class extends AbstractSessionStore {
     this.#cookieHandler = cookieHandler;
   }
   async set(identifier, stateData, removeIfExists, options) {
-    const maxAge = this.calculateMaxAge(stateData.internal.createdAt);
+    const maxAge = this.calculateMaxAge(stateData.internal.createdAt, stateData.sessionExpiresAt);
     const cookieOpts = this.#getCookieOptions({
       maxAge
     });
@@ -1519,7 +1616,7 @@ import {
   PasskeyRegisterError,
   PasskeyChallengeError,
   PasskeyGetTokenError,
-  OrganizationValidationError
+  OrganizationValidationError as OrganizationValidationError2
 } from "@auth0/auth0-auth-js";
 export {
   AbstractStateStore,
@@ -1536,13 +1633,14 @@ export {
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
-  OrganizationValidationError,
+  OrganizationValidationError3 as OrganizationValidationError,
   PasskeyChallengeError,
   PasskeyGetTokenError,
   PasskeyRegisterError,
   ServerClient,
   ServerMfaClient,
   ServerPasskeyClient,
+  SessionExpiredError,
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,