@auth0/auth0-server-js 1.7.0 → 1.8.0

package/dist/index.cjs

@@ -41,6 +41,7 @@ __export(index_exports, {
   ServerClient: () => ServerClient,
   ServerMfaClient: () => ServerMfaClient,
   ServerPasskeyClient: () => ServerPasskeyClient,
+  SessionExpiredError: () => SessionExpiredError,
   StartLinkUserError: () => StartLinkUserError,
   StatefulStateStore: () => StatefulStateStore,
   StatelessStateStore: () => StatelessStateStore,
@@ -99,14 +100,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;
@@ -208,7 +250,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.7.0"
+    version: config?.version ?? "1.8.0"
   };
 }
 
@@ -270,9 +312,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,
@@ -598,6 +643,7 @@ var ServerClient = class {
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
+   * @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).
    */
@@ -612,12 +658,15 @@ var ServerClient = class {
       // TransactionData.codeVerifier is optional only to accommodate magic-link transactions.
       codeVerifier: transactionData.codeVerifier
     });
+    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 };
   }
   /**
@@ -627,6 +676,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.
    */
@@ -643,6 +693,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({
@@ -686,6 +740,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.
    */
@@ -702,6 +757,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({
@@ -746,6 +805,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).
    */
@@ -762,11 +822,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 {
@@ -961,6 +1021,10 @@ var ServerClient = class {
         return;
       }
     }
+    if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      return;
+    }
     return stateData.user;
   }
   /**
@@ -977,6 +1041,10 @@ var ServerClient = class {
           return;
         }
       }
+      if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+        await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+        return;
+      }
       const { internal, ...sessionData } = stateData;
       return sessionData;
     }
@@ -993,6 +1061,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.
    */
@@ -1020,6 +1089,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))
     );
@@ -1394,14 +1467,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;
   }
 };
@@ -1429,7 +1502,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
     });
@@ -1494,7 +1567,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
     });
@@ -1578,6 +1651,7 @@ var import_auth0_auth_js3 = require("@auth0/auth0-auth-js");
   ServerClient,
   ServerMfaClient,
   ServerPasskeyClient,
+  SessionExpiredError,
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,