@auth0/auth0-server-js 1.7.0 → 1.9.0

package/dist/index.cjs

@@ -34,13 +34,14 @@ __export(index_exports, {
   MissingRequiredArgumentError: () => MissingRequiredArgumentError,
   MissingSessionError: () => MissingSessionError,
   MissingTransactionError: () => MissingTransactionError,
-  OrganizationValidationError: () => import_auth0_auth_js3.OrganizationValidationError,
+  OrganizationValidationError: () => import_auth0_auth_js4.OrganizationValidationError,
   PasskeyChallengeError: () => import_auth0_auth_js3.PasskeyChallengeError,
   PasskeyGetTokenError: () => import_auth0_auth_js3.PasskeyGetTokenError,
   PasskeyRegisterError: () => import_auth0_auth_js3.PasskeyRegisterError,
   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.9.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,
@@ -556,9 +601,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.
@@ -569,6 +621,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 import_auth0_auth_js.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({
@@ -576,7 +638,9 @@ var ServerClient = class {
       authorizationParams: {
         ...options?.authorizationParams,
         redirect_uri: redirectUri,
-        scope
+        scope,
+        ...resolvedOrganization ? { organization: resolvedOrganization } : {},
+        ...options?.invitation ? { invitation: options.invitation } : {}
       }
     });
     const transactionState = {
@@ -584,6 +648,9 @@ var ServerClient = class {
       codeVerifier,
       domain
     };
+    if (resolvedOrganization) {
+      transactionState.organization = resolvedOrganization;
+    }
     if (options?.appState) {
       transactionState.appState = options.appState;
     }
@@ -598,6 +665,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).
    */
@@ -610,14 +679,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 };
   }
   /**
@@ -627,6 +700,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 +717,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 +764,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 +781,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 +829,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 +846,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 +1045,10 @@ var ServerClient = class {
         return;
       }
     }
+    if (isSessionExpiryReached(stateData.sessionExpiresAt)) {
+      await this.#stateStore.delete(this.#stateStoreIdentifier, storeOptions);
+      return;
+    }
     return stateData.user;
   }
   /**
@@ -977,6 +1065,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 +1085,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 +1113,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 +1491,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 +1526,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 +1591,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 +1675,7 @@ var import_auth0_auth_js3 = require("@auth0/auth0-auth-js");
   ServerClient,
   ServerMfaClient,
   ServerPasskeyClient,
+  SessionExpiredError,
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,