@auth0/auth0-server-js 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { AuthorizationDetails, AuthClient } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
+export { TelemetryConfig } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 interface ServerClientOptions<TStoreOptions = unknown> {
@@ -22,6 +23,11 @@ interface ServerClientOptions<TStoreOptions = unknown> {
      * When set to `true`, using a `customFetch` is required.
      */
     useMtls?: boolean;
+    /**
+     * Optional telemetry configuration.
+     * Telemetry is enabled by default and sends the Auth0-Client header with package name and version.
+     */
+    telemetry?: TelemetryConfig;
 }
 interface UserClaims {
     sub: string;
@@ -89,7 +95,11 @@ interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateDat
 interface TransactionStore<TStoreOptions = unknown> extends AbstractDataStore<TransactionData, TStoreOptions> {
 }
 interface EncryptedStoreOptions {
-    secret: string;
+    /**
+     * The secret(s) to use for encryption and decryption. Can be a single string or an array of strings for secret rotation support.
+     * When using an array of secrets, the first one is used for encryption, while all secrets are tried, in-order, for decryption.
+     */
+    secret: string | string[];
 }
 interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
@@ -110,6 +120,25 @@ interface AccessTokenForConnectionOptions {
     connection: string;
     loginHint?: string;
 }
+/**
+ * Options for retrieving an access token with MRRT support.
+ * Allows requesting tokens for specific audiences and scopes at runtime.
+ */
+interface GetAccessTokenOptions {
+    /**
+     * Optional audience for the requested access token.
+     * If not provided, falls back to configuration audience or 'default'.
+     * @example 'https://api.example.com'
+     */
+    audience?: string;
+    /**
+     * Optional scope for the requested access token.
+     * If not provided, falls back to configuration scope.
+     * Space-separated scope string.
+     * @example 'read:data write:data'
+     */
+    scope?: string;
+}
 interface LogoutOptions {
     returnTo: string;
 }
@@ -306,16 +335,8 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns The sessionm or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
-    /**
-     * Retrieves the access token from the store, or calls Auth0 when the access token is expired and a refresh token is available in the store.
-     * Also updates the store when a new token was retrieved from Auth0.
-     * @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.
-     *
-     * @returns The Token Set, containing the access token, as well as additional information.
-     */
     getAccessToken(storeOptions?: TStoreOptions): Promise<TokenSet>;
+    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions): Promise<TokenSet>;
     /**
      * Retrieves an access token for a connection.
      *
@@ -360,7 +381,7 @@ declare abstract class AbstractStore<TData extends JWTPayload, TStoreOptions = u
     abstract get(identifier: string, options?: TStoreOptions | undefined): Promise<TData | undefined>;
     abstract delete(identifier: string, options?: TStoreOptions | undefined): Promise<void>;
     protected encrypt<TData extends JWTPayload>(identifier: string, stateData: TData, expiration: number): Promise<string>;
-    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData>;
+    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData | undefined>;
 }
 
 /**
@@ -386,6 +407,13 @@ interface CookieSerializeOptions {
     domain?: string;
     expires?: Date;
     httpOnly?: boolean;
+    /**
+     * MaxAge value of the cookie in seconds.
+     *
+     * Note for implementors of {@link CookieHandler}: this value is always in seconds.
+     * Some frameworks (e.g. Express) expect `maxAge` in milliseconds, so you may need to convert
+     * before passing it to the underlying framework (e.g. `maxAge * 1000`).
+     */
     maxAge?: number;
     path?: string;
     secure?: boolean;
@@ -503,5 +531,12 @@ declare class MissingSessionError extends Error {
     code: string;
     constructor(message: string);
 }
+/**
+ * Error thrown when a configuration is invalid.
+ */
+declare class InvalidConfigurationError extends Error {
+    code: string;
+    constructor(message: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type InternalStateData, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, 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 ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { AuthorizationDetails, AuthClient } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
+export { TelemetryConfig } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 interface ServerClientOptions<TStoreOptions = unknown> {
@@ -22,6 +23,11 @@ interface ServerClientOptions<TStoreOptions = unknown> {
      * When set to `true`, using a `customFetch` is required.
      */
     useMtls?: boolean;
+    /**
+     * Optional telemetry configuration.
+     * Telemetry is enabled by default and sends the Auth0-Client header with package name and version.
+     */
+    telemetry?: TelemetryConfig;
 }
 interface UserClaims {
     sub: string;
@@ -89,7 +95,11 @@ interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateDat
 interface TransactionStore<TStoreOptions = unknown> extends AbstractDataStore<TransactionData, TStoreOptions> {
 }
 interface EncryptedStoreOptions {
-    secret: string;
+    /**
+     * The secret(s) to use for encryption and decryption. Can be a single string or an array of strings for secret rotation support.
+     * When using an array of secrets, the first one is used for encryption, while all secrets are tried, in-order, for decryption.
+     */
+    secret: string | string[];
 }
 interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
@@ -110,6 +120,25 @@ interface AccessTokenForConnectionOptions {
     connection: string;
     loginHint?: string;
 }
+/**
+ * Options for retrieving an access token with MRRT support.
+ * Allows requesting tokens for specific audiences and scopes at runtime.
+ */
+interface GetAccessTokenOptions {
+    /**
+     * Optional audience for the requested access token.
+     * If not provided, falls back to configuration audience or 'default'.
+     * @example 'https://api.example.com'
+     */
+    audience?: string;
+    /**
+     * Optional scope for the requested access token.
+     * If not provided, falls back to configuration scope.
+     * Space-separated scope string.
+     * @example 'read:data write:data'
+     */
+    scope?: string;
+}
 interface LogoutOptions {
     returnTo: string;
 }
@@ -306,16 +335,8 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns The sessionm or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
-    /**
-     * Retrieves the access token from the store, or calls Auth0 when the access token is expired and a refresh token is available in the store.
-     * Also updates the store when a new token was retrieved from Auth0.
-     * @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.
-     *
-     * @returns The Token Set, containing the access token, as well as additional information.
-     */
     getAccessToken(storeOptions?: TStoreOptions): Promise<TokenSet>;
+    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions): Promise<TokenSet>;
     /**
      * Retrieves an access token for a connection.
      *
@@ -360,7 +381,7 @@ declare abstract class AbstractStore<TData extends JWTPayload, TStoreOptions = u
     abstract get(identifier: string, options?: TStoreOptions | undefined): Promise<TData | undefined>;
     abstract delete(identifier: string, options?: TStoreOptions | undefined): Promise<void>;
     protected encrypt<TData extends JWTPayload>(identifier: string, stateData: TData, expiration: number): Promise<string>;
-    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData>;
+    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData | undefined>;
 }
 
 /**
@@ -386,6 +407,13 @@ interface CookieSerializeOptions {
     domain?: string;
     expires?: Date;
     httpOnly?: boolean;
+    /**
+     * MaxAge value of the cookie in seconds.
+     *
+     * Note for implementors of {@link CookieHandler}: this value is always in seconds.
+     * Some frameworks (e.g. Express) expect `maxAge` in milliseconds, so you may need to convert
+     * before passing it to the underlying framework (e.g. `maxAge * 1000`).
+     */
     maxAge?: number;
     path?: string;
     secure?: boolean;
@@ -503,5 +531,12 @@ declare class MissingSessionError extends Error {
     code: string;
     constructor(message: string);
 }
+/**
+ * Error thrown when a configuration is invalid.
+ */
+declare class InvalidConfigurationError extends Error {
+    code: string;
+    constructor(message: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type InternalStateData, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, 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 ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };

package/dist/index.js

@@ -34,6 +34,13 @@ var MissingSessionError = class extends Error {
     this.name = "MissingSessionError";
   }
 };
+var InvalidConfigurationError = class extends Error {
+  code = "invalid_configuration_error";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidConfigurationError";
+  }
+};
 
 // src/state/utils.ts
 var createUpdatedTokenSet = (audience, response) => ({
@@ -42,18 +49,18 @@ var createUpdatedTokenSet = (audience, response) => ({
   scope: response.scope,
   expiresAt: response.expiresAt
 });
-function updateStateData(audience, stateDate, tokenEndpointResponse) {
-  if (stateDate) {
-    const isNewTokenSet = !stateDate.tokenSets.some(
+function updateStateData(audience, stateData, tokenEndpointResponse) {
+  if (stateData) {
+    const isNewTokenSet = !stateData.tokenSets.some(
       (tokenSet) => tokenSet.audience === audience && tokenSet.scope === tokenEndpointResponse.scope
     );
-    const tokenSets = isNewTokenSet ? [...stateDate.tokenSets, createUpdatedTokenSet(audience, tokenEndpointResponse)] : stateDate.tokenSets.map(
+    const tokenSets = isNewTokenSet ? [...stateData.tokenSets, createUpdatedTokenSet(audience, tokenEndpointResponse)] : stateData.tokenSets.map(
       (tokenSet) => tokenSet.audience === audience && tokenSet.scope === tokenEndpointResponse.scope ? createUpdatedTokenSet(audience, tokenEndpointResponse) : tokenSet
     );
     return {
-      ...stateDate,
-      idToken: tokenEndpointResponse.idToken,
-      refreshToken: tokenEndpointResponse.refreshToken ?? stateDate.refreshToken,
+      ...stateData,
+      idToken: tokenEndpointResponse.idToken ?? stateData.idToken,
+      refreshToken: tokenEndpointResponse.refreshToken ?? stateData.refreshToken,
       tokenSets
     };
   } else {
@@ -72,9 +79,9 @@ function updateStateData(audience, stateDate, tokenEndpointResponse) {
     };
   }
 }
-function updateStateDataForConnectionTokenSet(options, stateDate, tokenEndpointResponse) {
-  stateDate.connectionTokenSets = stateDate.connectionTokenSets || [];
-  const isNewTokenSet = !stateDate.connectionTokenSets.some(
+function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointResponse) {
+  stateData.connectionTokenSets = stateData.connectionTokenSets || [];
+  const isNewTokenSet = !stateData.connectionTokenSets.some(
     (tokenSet) => tokenSet.connection === options.connection && (!options.loginHint || tokenSet.loginHint === options.loginHint)
   );
   const connectionTokenSet = {
@@ -84,11 +91,11 @@ function updateStateDataForConnectionTokenSet(options, stateDate, tokenEndpointR
     scope: tokenEndpointResponse.scope,
     expiresAt: tokenEndpointResponse.expiresAt
   };
-  const connectionTokenSets = isNewTokenSet ? [...stateDate.connectionTokenSets, connectionTokenSet] : stateDate.connectionTokenSets.map(
+  const connectionTokenSets = isNewTokenSet ? [...stateData.connectionTokenSets, connectionTokenSet] : stateData.connectionTokenSets.map(
     (tokenSet) => tokenSet.connection === options.connection && (!options.loginHint || tokenSet.loginHint === options.loginHint) ? connectionTokenSet : tokenSet
   );
   return {
-    ...stateDate,
+    ...stateData,
     connectionTokenSets
   };
 }
@@ -113,7 +120,30 @@ var compareScopes = (scopes, requiredScopes) => {
   return requiredScopesArray.every((scope) => scopesSet.has(scope));
 };
 
+// src/telemetry.ts
+function getTelemetryConfig(config) {
+  if (config?.enabled === false) {
+    return config;
+  }
+  return {
+    enabled: true,
+    name: config?.name ?? "@auth0/auth0-server-js",
+    version: config?.version ?? "1.3.0"
+  };
+}
+
 // src/server-client.ts
+var DEFAULT_SCOPES = "openid profile email offline_access";
+function ensureOpenIdScope(scope) {
+  if (!scope) {
+    return DEFAULT_SCOPES;
+  }
+  const scopes = scope.split(" ");
+  if (!scopes.includes("openid")) {
+    scopes.unshift("openid");
+  }
+  return scopes.join(" ");
+}
 var ServerClient = class {
   #options;
   #transactionStore;
@@ -147,7 +177,8 @@ var ServerClient = class {
       clientAssertionSigningAlg: this.#options.clientAssertionSigningAlg,
       authorizationParams: this.#options.authorizationParams,
       customFetch: this.#options.customFetch,
-      useMtls: this.#options.useMtls
+      useMtls: this.#options.useMtls,
+      telemetry: getTelemetryConfig(this.#options.telemetry)
     });
   }
   /**
@@ -164,11 +195,13 @@ var ServerClient = class {
     if (!redirectUri) {
       throw new MissingRequiredArgumentError("authorizationParams.redirect_uri");
     }
+    const scope = ensureOpenIdScope(options?.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
     const { codeVerifier, authorizationUrl } = await this.authClient.buildAuthorizationUrl({
       pushedAuthorizationRequests: options?.pushedAuthorizationRequests,
       authorizationParams: {
         ...options?.authorizationParams,
-        redirect_uri: redirectUri
+        redirect_uri: redirectUri,
+        scope
       }
     });
     const transactionState = {
@@ -318,10 +351,14 @@ var ServerClient = class {
    * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
    */
   async loginBackchannel(options, storeOptions) {
+    const scope = ensureOpenIdScope(options.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
     const tokenEndpointResponse = await this.authClient.backchannelAuthentication({
       bindingMessage: options.bindingMessage,
       loginHint: options.loginHint,
-      authorizationParams: options.authorizationParams
+      authorizationParams: {
+        ...options.authorizationParams,
+        scope
+      }
     });
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
     const stateData = updateStateData(
@@ -358,16 +395,24 @@ var ServerClient = class {
   /**
    * Retrieves the access token from the store, or calls Auth0 when the access token is expired and a refresh token is available in the store.
    * Also updates the store when a new token was retrieved from Auth0.
+   *
+   * @param options Optional options for requesting specific audience/scope.
    * @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.
    *
    * @returns The Token Set, containing the access token, as well as additional information.
    */
-  async getAccessToken(storeOptions) {
-    const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
-    const audience = this.#options.authorizationParams?.audience ?? "default";
-    const scope = this.#options.authorizationParams?.scope;
+  async getAccessToken(tokenOptionsOrStoreOptions, storeOptions) {
+    const hasTokenOptions = (
+      // If second arg exists, first arg must be GetAccessTokenOptions
+      storeOptions !== void 0 || // OR if first arg has audience/scope properties
+      tokenOptionsOrStoreOptions && typeof tokenOptionsOrStoreOptions === "object" && ("audience" in tokenOptionsOrStoreOptions || "scope" in tokenOptionsOrStoreOptions)
+    );
+    const [resolvedOptions, resolvedStoreOptions] = hasTokenOptions ? [tokenOptionsOrStoreOptions, storeOptions] : [void 0, tokenOptionsOrStoreOptions];
+    const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
+    const audience = resolvedOptions?.audience ?? this.#options.authorizationParams?.audience ?? "default";
+    const scope = resolvedOptions?.scope ?? this.#options.authorizationParams?.scope;
     const tokenSet = stateData?.tokenSets.find(
       (tokenSet2) => tokenSet2.audience === audience && (!scope || compareScopes(tokenSet2.scope, scope))
     );
@@ -379,12 +424,14 @@ var ServerClient = class {
         "The access token has expired and a refresh token was not provided. The user needs to re-authenticate."
       );
     }
-    const tokenEndpointResponse = await this.authClient.getTokenByRefreshToken({
-      refreshToken: stateData.refreshToken
-    });
-    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const tokenByRefreshTokenOptions = {
+      refreshToken: stateData.refreshToken,
+      ...hasTokenOptions && { audience, scope }
+    };
+    const tokenEndpointResponse = await this.authClient.getTokenByRefreshToken(tokenByRefreshTokenOptions);
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
     const updatedStateData = updateStateData(audience, existingStateData, tokenEndpointResponse);
-    await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, storeOptions);
+    await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, resolvedStoreOptions);
     return {
       accessToken: tokenEndpointResponse.accessToken,
       scope: tokenEndpointResponse.scope,
@@ -463,13 +510,16 @@ var ServerClient = class {
 };
 
 // src/encryption/index.ts
-import { EncryptJWT, jwtDecrypt } from "jose";
+import { EncryptJWT, jwtDecrypt, errors } from "jose";
 var ENC = "A256CBC-HS512";
 var ALG = "dir";
 var DIGEST = "SHA-256";
 var BIT_LENGTH = 512;
 var HKDF_INFO = "derived cookie encryption secret";
 var encoder;
+function isDecryptionError(e) {
+  return e instanceof errors.JWEDecryptionFailed || e instanceof errors.JWEInvalid;
+}
 async function deriveEncryptionSecret(secret, salt, kid) {
   encoder ||= new TextEncoder();
   const key = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveBits"]);
@@ -486,12 +536,23 @@ async function deriveEncryptionSecret(secret, salt, kid) {
     )
   );
 }
-async function encrypt(payload, secret, salt, expiration) {
+async function _encrypt(payload, secret, salt, expiration) {
   const kid = crypto.randomUUID();
   const encryptionSecret = await deriveEncryptionSecret(secret, salt, kid);
   return await new EncryptJWT(payload).setProtectedHeader({ enc: ENC, alg: ALG, kid }).setExpirationTime(expiration).encrypt(encryptionSecret);
 }
-async function decrypt(value, secret, salt) {
+async function encrypt(payload, secret, salt, expiration) {
+  if (typeof secret === "string") {
+    return await _encrypt(payload, secret, salt, expiration);
+  } else {
+    const [newSecret] = secret;
+    if (!newSecret) {
+      throw new InvalidConfigurationError("At least one secret must be provided");
+    }
+    return await _encrypt(payload, newSecret, salt, expiration);
+  }
+}
+async function _decrypt(value, secret, salt) {
   const res = await jwtDecrypt(
     value,
     async (protectedHeader) => {
@@ -504,6 +565,35 @@ async function decrypt(value, secret, salt) {
   );
   return res.payload;
 }
+async function decrypt(value, secret, salt) {
+  if (typeof secret === "string") {
+    return await _decrypt(value, secret, salt);
+  } else {
+    const [newSecret, ...oldSecrets] = secret;
+    if (!newSecret) {
+      throw new InvalidConfigurationError("At least one secret must be provided");
+    }
+    let firstError;
+    try {
+      return await _decrypt(value, newSecret, salt);
+    } catch (err) {
+      firstError = err;
+      if (!isDecryptionError(err)) {
+        throw firstError;
+      }
+      for (const oldSecret of oldSecrets) {
+        try {
+          return await _decrypt(value, oldSecret, salt);
+        } catch (fallbackErr) {
+          if (!isDecryptionError(fallbackErr)) {
+            throw fallbackErr;
+          }
+        }
+      }
+      throw firstError;
+    }
+  }
+}
 
 // src/store/abstract-store.ts
 var AbstractStore = class {
@@ -515,7 +605,14 @@ var AbstractStore = class {
     return await encrypt(stateData, this.options.secret, identifier, expiration);
   }
   async decrypt(identifier, encryptedStateData) {
-    return await decrypt(encryptedStateData, this.options.secret, identifier);
+    try {
+      return await decrypt(encryptedStateData, this.options.secret, identifier);
+    } catch (e) {
+      if (isDecryptionError(e)) {
+        return;
+      }
+      throw e;
+    }
   }
 };
 
@@ -642,7 +739,9 @@ var StatefulStateStore = class extends AbstractSessionStore {
     const cookieValue = this.#cookieHandler.getCookie(identifier, options);
     if (cookieValue) {
       const sessionCookie = await this.decrypt(identifier, cookieValue);
-      return sessionCookie.id;
+      if (sessionCookie) {
+        return sessionCookie.id;
+      }
     }
   }
   deleteByLogoutToken(claims, options) {
@@ -729,6 +828,7 @@ export {
   AbstractTransactionStore,
   BackchannelLogoutError,
   CookieTransactionStore,
+  InvalidConfigurationError,
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,