@vunexa/lixa 0.1.6-alpha.8 → 0.1.6-alpha.9

package/dist/index.cjs

@@ -47,7 +47,10 @@ __export(src_exports, {
   SessionNotFoundError: () => SessionNotFoundError,
   TokenExchangeError: () => TokenExchangeError,
   clearSessionCookie: () => clearSessionCookie,
+  clearSessionCookieOnResponse: () => clearSessionCookieOnResponse,
   clearStateCookie: () => clearStateCookie,
+  clearStateCookieOnResponse: () => clearStateCookieOnResponse,
+  createRequireAuthMiddleware: () => createRequireAuthMiddleware,
   createSessionCookie: () => createSessionCookie,
   createStateCookie: () => createStateCookie,
   decodeIdToken: () => decodeIdToken,
@@ -55,7 +58,9 @@ __export(src_exports, {
   extractUserInfo: () => extractUserInfo,
   fetchUserInfo: () => fetchUserInfo,
   isProductionEnvironment: () => isProductionEnvironment,
-  serializeCookie: () => serializeCookie
+  serializeCookie: () => serializeCookie,
+  setSessionCookieOnResponse: () => setSessionCookieOnResponse,
+  setStateCookieOnResponse: () => setStateCookieOnResponse
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -89,7 +94,7 @@ var LocalStateHandler = class {
       }
     };
   }
-  // Default GenerateState implementation
+  // Default generateState implementation
   async generateState(provider) {
     const state = (0, import_crypto.randomBytes)(16).toString("hex");
     const codeVerifier = (0, import_crypto.randomBytes)(32).toString("hex");
@@ -102,6 +107,10 @@ var LocalStateHandler = class {
       }
     };
   }
+  // PascalCase alias for backward compatibility
+  async GenerateState(provider) {
+    return this.generateState(provider);
+  }
 };
 
 // src/lixa.ts
@@ -114,7 +123,20 @@ var LocalSessionHandler = class {
   emailToSessionMap = /* @__PURE__ */ new Map();
   sessionStorage;
   constructor(defaultTtlSeconds = 600) {
-    this.cache = new import_node_cache2.default({ stdTTL: defaultTtlSeconds });
+    this.cache = new import_node_cache2.default({ stdTTL: defaultTtlSeconds, checkperiod: 60 });
+    this.cache.on("expired", (_key, value) => {
+      if (value && typeof value === "object" && value.email) {
+        this.emailToSessionMap.delete(String(value.email).toLowerCase());
+      }
+    });
+    this.cache.on("del", (_key, value) => {
+      if (value && typeof value === "object" && value.email) {
+        this.emailToSessionMap.delete(String(value.email).toLowerCase());
+      }
+    });
+    this.cache.on("flush", () => {
+      this.emailToSessionMap.clear();
+    });
     this.sessionStorage = {
       saveSession: async (sessionId, session, expiresInSeconds) => {
         this.cache.set(sessionId, session, expiresInSeconds);
@@ -145,8 +167,8 @@ var LocalSessionHandler = class {
       }
     };
   }
-  // Default GenerateSession implementation
-  async GenerateSession(tokenData, providerMetadata) {
+  // Default generateSession implementation
+  async generateSession(tokenData, _providerMetadata) {
     if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
       throw new Error("No valid access token found in OAuth response");
     }
@@ -156,6 +178,10 @@ var LocalSessionHandler = class {
     };
     return session;
   }
+  // PascalCase alias for backward compatibility
+  async GenerateSession(tokenData, providerMetadata) {
+    return this.generateSession(tokenData, providerMetadata);
+  }
 };
 
 // src/utils/user-info.ts
@@ -306,8 +332,12 @@ var Lixa = class _Lixa {
   static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
   static CONFIGURED_PROVIDERS = /* @__PURE__ */ new Map();
   // Legacy registry for backward compatibility
-  static LOCAL_STATE_HANDLER = new LocalStateHandler();
-  static LOCAL_SESSION_HANDLER = new LocalSessionHandler();
+  // Instance-scoped fallback handlers to ensure no cross-instance state pollution
+  localStateHandler;
+  localSessionHandler;
+  localResourceHandler;
+  userResourceStore = /* @__PURE__ */ new Map();
+  refreshMutexes = /* @__PURE__ */ new Map();
   config;
   stateHandler;
   sessionHandler;
@@ -328,10 +358,44 @@ var Lixa = class _Lixa {
    */
   constructor(config) {
     this.config = config;
-    this.stateHandler = config.stateHandler || _Lixa.LOCAL_STATE_HANDLER;
-    this.sessionHandler = config.sessionHandler || _Lixa.LOCAL_SESSION_HANDLER;
-    this.resourceHandler = config.resourceHandler || _Lixa.LOCAL_RESOURCE_HANDLER;
     this.debug = config.debug || false;
+    this.localStateHandler = new LocalStateHandler();
+    this.localSessionHandler = new LocalSessionHandler();
+    this.localResourceHandler = {
+      resourceStorage: {
+        saveResource: async (userId, provider, resource) => {
+          let userMap = this.userResourceStore.get(userId);
+          if (!userMap) {
+            userMap = /* @__PURE__ */ new Map();
+            this.userResourceStore.set(userId, userMap);
+          }
+          userMap.set(provider.toLowerCase(), resource);
+        },
+        getResource: async (userId, provider) => {
+          const userMap = this.userResourceStore.get(userId);
+          return userMap?.get(provider.toLowerCase()) || null;
+        },
+        getUserResources: async (userId) => {
+          const userMap = this.userResourceStore.get(userId);
+          const result = {};
+          if (userMap) {
+            for (const [p, r] of userMap.entries()) {
+              result[p] = r;
+            }
+          }
+          return result;
+        },
+        deleteResource: async (userId, provider) => {
+          const userMap = this.userResourceStore.get(userId);
+          if (userMap) {
+            userMap.delete(provider.toLowerCase());
+          }
+        }
+      }
+    };
+    this.stateHandler = config.stateHandler || this.localStateHandler;
+    this.sessionHandler = config.sessionHandler || this.localSessionHandler;
+    this.resourceHandler = config.resourceHandler || this.localResourceHandler;
     this.log("INFO", "Init", "Initializing Lixa instance", {
       providers: Object.keys(config.providers),
       debug: this.debug
@@ -409,18 +473,20 @@ var Lixa = class _Lixa {
     }
   }
   /**
-   * Structured debug logging with standardized format.
+   * Structured logging with standardized format and custom logger support.
    * 
-   * @param level - Log level (INFO, WARN, ERROR)
-   * @param context - Context of the log (Init, Auth, Token, Session, State)
+   * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+   * @param context - Context of the log (Init, Auth, Token, Session, State, AccountLinking, Resource)
    * @param message - Log message
    * @param data - Optional data to log
-   * 
-   * @remarks
-   * Format: [Lixa] [timestamp] [level] [context] message
-   * Only logs when debug mode is enabled.
    */
   log(level, context, message, data) {
+    if (this.config.logger) {
+      try {
+        this.config.logger.log(level, context, message, data);
+      } catch {
+      }
+    }
     if (!this.debug) return;
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
     const prefix = `[Lixa] [${timestamp}] [${level}] [${context}]`;
@@ -670,18 +736,19 @@ var Lixa = class _Lixa {
     const providerImpl = this.getProvider(providerType, providerConfig);
     let stateValue;
     let codeVerifier;
-    if (this.stateHandler.generateState) {
-      this.log("INFO", "State", "Calling custom GenerateState");
-      const generated = await this.stateHandler.generateState(providerType);
+    const generateStateFn = this.stateHandler.generateState || this.stateHandler.GenerateState;
+    if (generateStateFn) {
+      this.log("INFO", "State", "Calling custom generateState");
+      const generated = await generateStateFn(providerType);
       stateValue = state || generated.state;
       codeVerifier = generated.data.codeVerifier;
-      const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       await storage.saveState(stateValue, generated.data, 300);
     } else {
       this.log("INFO", "State", "Using default state generation");
       stateValue = state || (0, import_crypto2.randomBytes)(16).toString("hex");
       codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
-      const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       await storage.saveState(
         stateValue,
         {
@@ -690,12 +757,17 @@ var Lixa = class _Lixa {
           codeVerifier
         },
         300
-        // 5 minutes in seconds
+        // 5 minutes in seconds (synchronized with cookie TTL)
       );
     }
     const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
     this.log("INFO", "State", `Saved state for provider: ${providerType}`, { state: stateValue });
-    const authNScopes = this.resolveAuthNScopes(providerType, providerConfig.scopes, providerImpl);
+    const authNScopes = this.resolveAuthNScopes(
+      providerType,
+      providerConfig.scopes,
+      providerImpl,
+      providerConfig.allowNonAuthScopes
+    );
     const params = new URLSearchParams({
       client_id: providerConfig.clientId,
       redirect_uri: providerConfig.redirectUri,
@@ -714,9 +786,12 @@ var Lixa = class _Lixa {
     return authUrl;
   }
   /**
-   * Restricts primary authentication scopes strictly to AuthN identity scopes.
+   * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
    */
-  resolveAuthNScopes(providerType, configuredScopes, providerImpl) {
+  resolveAuthNScopes(providerType, configuredScopes, providerImpl, allowNonAuthScopes) {
+    if (allowNonAuthScopes) {
+      return configuredScopes && configuredScopes.length > 0 ? configuredScopes : providerImpl.authScopes || ["openid", "email", "profile"];
+    }
     const defaultAuthScopes = {
       google: ["openid", "email", "profile"],
       github: ["read:user", "user:email"],
@@ -745,7 +820,7 @@ var Lixa = class _Lixa {
         "Auth",
         `Primary authentication is strictly limited to AuthN scopes. Excluded non-AuthN resource scopes: [${nonAuthNScopes.join(
           ", "
-        )}]. Use lixa.getResourceAuthUrl() post-login to connect resource providers.`
+        )}]. Set 'allowNonAuthScopes: true' on provider config to include them, or use lixa.getResourceAuthUrl() post-login to connect resource providers.`
       );
     }
     if (validAuthNScopes.length > 0) {
@@ -788,7 +863,7 @@ var Lixa = class _Lixa {
       throw new InvalidOAuthCallbackError("Invalid or missing state in callback");
     }
     this.log("INFO", "State", "Validating state parameter", { state });
-    const stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+    const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
     const cachedState = await stateStorage.getState(state);
     if (!cachedState) {
       this.log("ERROR", "State", "State validation failed: state not found or expired", { state });
@@ -828,9 +903,12 @@ var Lixa = class _Lixa {
       extractedUserInfo = userInfo;
     } catch {
     }
-    const generateSession = this.sessionHandler.generateSession || _Lixa.LOCAL_SESSION_HANDLER.GenerateSession.bind(_Lixa.LOCAL_SESSION_HANDLER);
-    if (this.sessionHandler.generateSession) {
-      this.log("INFO", "Session", "Calling custom GenerateSession");
+    const generateSession = this.sessionHandler.generateSession || this.sessionHandler.GenerateSession || (this.localSessionHandler.generateSession ? this.localSessionHandler.generateSession.bind(this.localSessionHandler) : void 0);
+    if (!generateSession) {
+      throw new Error("No session generation handler available");
+    }
+    if (this.sessionHandler.generateSession || this.sessionHandler.GenerateSession) {
+      this.log("INFO", "Session", "Calling custom generateSession");
     } else {
       this.log("INFO", "Session", "Using default session generation");
     }
@@ -839,7 +917,7 @@ var Lixa = class _Lixa {
     if (extractedUserInfo?.email && !session.email) {
       session.email = extractedUserInfo.email;
     }
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const linkingConfig = this.config.accountLinking;
     const mode = String(linkingConfig?.mode || "");
     const isLinkByEmail = mode === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || mode === "AUTO_LINK_BY_VERIFIED_EMAIL" || mode === "linkByEmail";
@@ -892,27 +970,31 @@ var Lixa = class _Lixa {
    */
   async linkAccount(params) {
     const { sessionId, provider, code, state } = params;
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const existingSession = await sessionStorage.getSession(sessionId);
     if (!existingSession) {
       throw new SessionNotFoundError("Invalid session ID. User must be authenticated to link an account.", { sessionId });
     }
+    if (!code || code.trim() === "") {
+      throw new InvalidOAuthCallbackError("Invalid or missing code in linkAccount");
+    }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
       throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    let codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
+    let codeVerifier;
     if (state) {
-      const stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       const cachedState = await stateStorage.getState(state);
-      if (cachedState) {
-        codeVerifier = cachedState.codeVerifier;
-        await stateStorage.deleteState(state);
+      if (!cachedState) {
+        throw new InvalidStateError("Invalid or expired state during account linking", { state });
       }
+      codeVerifier = cachedState.codeVerifier;
+      await stateStorage.deleteState(state);
     }
-    const tokens = await this.exchangeCodeForToken(providerType, providerConfig, providerImpl, codeVerifier);
+    const tokens = await this.exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier || "");
     const providerMetadata = {
       name: providerType,
       endpoints: {
@@ -950,7 +1032,7 @@ var Lixa = class _Lixa {
    * @returns Promise resolving to true on successful unlink
    */
   async unlinkAccount(sessionId, providerToUnlink) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const session = await sessionStorage.getSession(sessionId);
     if (!session || !session.accounts) {
       throw new AccountUnlinkError("Session not found or has no linked accounts.", { sessionId });
@@ -979,7 +1061,7 @@ var Lixa = class _Lixa {
    */
   async getResourceAuthUrl(params) {
     const { sessionId, provider, scopes, state, prompt, extraConfig } = params;
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) {
       throw new SessionNotFoundError("Authentication required. Active session must exist to connect resource providers.", { sessionId });
@@ -992,7 +1074,7 @@ var Lixa = class _Lixa {
     const providerImpl = this.getProvider(providerType, providerConfig);
     const stateValue = state || (0, import_crypto2.randomBytes)(16).toString("hex");
     const codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
-    const storage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+    const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
     await storage.saveState(
       stateValue,
       {
@@ -1017,45 +1099,6 @@ var Lixa = class _Lixa {
     });
     return `${providerImpl.authorizationEndpoint}?${searchParams.toString()}`;
   }
-  /**
-   * Handles the OAuth callback for a connected resource provider and stores resource tokens on the session.
-   * 
-   * @param params - Object containing sessionId, provider, code, state, and requested scopes
-   * @returns Updated Session containing stored resource tokens under session.resources[provider]
-   */
-  static userResourceStore = /* @__PURE__ */ new Map();
-  static LOCAL_RESOURCE_HANDLER = {
-    resourceStorage: {
-      saveResource: async (userId, provider, resource) => {
-        let userMap = _Lixa.userResourceStore.get(userId);
-        if (!userMap) {
-          userMap = /* @__PURE__ */ new Map();
-          _Lixa.userResourceStore.set(userId, userMap);
-        }
-        userMap.set(provider.toLowerCase(), resource);
-      },
-      getResource: async (userId, provider) => {
-        const userMap = _Lixa.userResourceStore.get(userId);
-        return userMap?.get(provider.toLowerCase()) || null;
-      },
-      getUserResources: async (userId) => {
-        const userMap = _Lixa.userResourceStore.get(userId);
-        const result = {};
-        if (userMap) {
-          for (const [p, r] of userMap.entries()) {
-            result[p] = r;
-          }
-        }
-        return result;
-      },
-      deleteResource: async (userId, provider) => {
-        const userMap = _Lixa.userResourceStore.get(userId);
-        if (userMap) {
-          userMap.delete(provider.toLowerCase());
-        }
-      }
-    }
-  };
   getUserKeyFromSession(session) {
     return session.userId || session.email || session.id || "anonymous";
   }
@@ -1064,7 +1107,7 @@ var Lixa = class _Lixa {
    */
   async handleResourceCallback(params) {
     const { sessionId, provider, code, state, scopes } = params;
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) {
       throw new SessionNotFoundError("Authentication required. Active session not found for resource connection.", { sessionId });
@@ -1077,12 +1120,13 @@ var Lixa = class _Lixa {
     const providerImpl = this.getProvider(providerType, providerConfig);
     let codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
     if (state) {
-      const stateStorage = this.stateHandler.stateStorage || _Lixa.LOCAL_STATE_HANDLER.stateStorage;
+      const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       const cachedState = await stateStorage.getState(state);
-      if (cachedState) {
-        codeVerifier = cachedState.codeVerifier;
-        await stateStorage.deleteState(state);
+      if (!cachedState) {
+        throw new InvalidStateError("Invalid or expired state during resource connection callback", { state });
       }
+      codeVerifier = cachedState.codeVerifier;
+      await stateStorage.deleteState(state);
     }
     const tokens = await this.exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier);
     const expiresAt = tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0;
@@ -1096,7 +1140,7 @@ var Lixa = class _Lixa {
       connectedAt: Date.now()
     };
     const userKey = this.getUserKeyFromSession(activeSession);
-    const resourceStorage = this.resourceHandler.resourceStorage || _Lixa.LOCAL_RESOURCE_HANDLER.resourceStorage;
+    const resourceStorage = this.resourceHandler.resourceStorage || this.localResourceHandler.resourceStorage;
     await resourceStorage.saveResource(userKey, providerType, connectedResource);
     activeSession.resources = activeSession.resources || {};
     activeSession.resources[providerType] = connectedResource;
@@ -1111,7 +1155,7 @@ var Lixa = class _Lixa {
    * @param provider - Resource provider identifier (e.g. 'github', 'google')
    */
   async getUserResource(userIdOrEmail, provider) {
-    const resourceStorage = this.resourceHandler.resourceStorage || _Lixa.LOCAL_RESOURCE_HANDLER.resourceStorage;
+    const resourceStorage = this.resourceHandler.resourceStorage || this.localResourceHandler.resourceStorage;
     const providerType = provider.toLowerCase();
     const resource = await resourceStorage.getResource(userIdOrEmail, providerType);
     if (!resource) return null;
@@ -1129,7 +1173,7 @@ var Lixa = class _Lixa {
    * Retrieves all connected resources for a specific User ID / Email.
    */
   async getUserResources(userIdOrEmail) {
-    const resourceStorage = this.resourceHandler.resourceStorage || _Lixa.LOCAL_RESOURCE_HANDLER.resourceStorage;
+    const resourceStorage = this.resourceHandler.resourceStorage || this.localResourceHandler.resourceStorage;
     return await resourceStorage.getUserResources(userIdOrEmail);
   }
   /**
@@ -1139,7 +1183,7 @@ var Lixa = class _Lixa {
    * @param provider - Provider identifier (e.g. 'github', 'google')
    */
   async getConnectedResource(sessionId, provider) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) return null;
     const providerType = provider.toLowerCase();
@@ -1164,12 +1208,29 @@ var Lixa = class _Lixa {
   }
   /**
    * Refreshes a user's resource access token using its refresh token.
+   * Deduplicates concurrent refresh requests via an in-flight promise mutex.
    * 
    * @param userIdOrEmail - User identifier or email
    * @param provider - Provider identifier (e.g. 'google', 'github')
    */
   async refreshUserResourceToken(userIdOrEmail, provider, existingResource) {
-    const resourceStorage = this.resourceHandler.resourceStorage || _Lixa.LOCAL_RESOURCE_HANDLER.resourceStorage;
+    const mutexKey = `${userIdOrEmail.toLowerCase()}:${provider.toLowerCase()}`;
+    const existingPromise = this.refreshMutexes.get(mutexKey);
+    if (existingPromise) {
+      this.log("INFO", "Token", `Concurrent refresh request detected for '${mutexKey}'. Reusing in-flight promise.`);
+      return existingPromise;
+    }
+    const refreshPromise = this.executeRefreshUserResourceToken(userIdOrEmail, provider, existingResource).finally(() => {
+      this.refreshMutexes.delete(mutexKey);
+    });
+    this.refreshMutexes.set(mutexKey, refreshPromise);
+    return refreshPromise;
+  }
+  /**
+   * Internal execution of refresh token exchange.
+   */
+  async executeRefreshUserResourceToken(userIdOrEmail, provider, existingResource) {
+    const resourceStorage = this.resourceHandler.resourceStorage || this.localResourceHandler.resourceStorage;
     const providerType = provider.toLowerCase();
     let resource = existingResource || await resourceStorage.getResource(userIdOrEmail, providerType);
     if (!resource || !resource.refreshToken) {
@@ -1222,7 +1283,7 @@ var Lixa = class _Lixa {
    * Refreshes a connected resource access token for an active session.
    */
   async refreshResourceToken(sessionId, provider) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) {
       throw new SessionNotFoundError("Active session not found.", { sessionId });
@@ -1240,7 +1301,7 @@ var Lixa = class _Lixa {
    * Disconnects a resource provider for a specific User ID / Email.
    */
   async disconnectUserResource(userIdOrEmail, provider) {
-    const resourceStorage = this.resourceHandler.resourceStorage || _Lixa.LOCAL_RESOURCE_HANDLER.resourceStorage;
+    const resourceStorage = this.resourceHandler.resourceStorage || this.localResourceHandler.resourceStorage;
     await resourceStorage.deleteResource(userIdOrEmail, provider.toLowerCase());
     return true;
   }
@@ -1248,7 +1309,7 @@ var Lixa = class _Lixa {
    * Disconnects a resource provider from an active session and user account.
    */
   async disconnectResource(sessionId, provider) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (activeSession) {
       const userKey = this.getUserKeyFromSession(activeSession);
@@ -1265,7 +1326,7 @@ var Lixa = class _Lixa {
    * Retrieves active session details from session storage.
    */
   async fetchSessionInfo(sessionId) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     return await sessionStorage.getSession(sessionId);
   }
   /**
@@ -1274,7 +1335,7 @@ var Lixa = class _Lixa {
    * @param sessionId - Active session identifier
    */
   async deleteSession(sessionId) {
-    const sessionStorage = this.sessionHandler.sessionStorage || _Lixa.LOCAL_SESSION_HANDLER.sessionStorage;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     await sessionStorage.deleteSession(sessionId);
   }
   async exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier) {
@@ -1330,7 +1391,7 @@ var Lixa = class _Lixa {
 var DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
 var DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
 var DEFAULT_SESSION_MAX_AGE_SECONDS = 24 * 60 * 60;
-var DEFAULT_STATE_MAX_AGE_SECONDS = 10 * 60;
+var DEFAULT_STATE_MAX_AGE_SECONDS = 5 * 60;
 function isProductionEnvironment() {
   return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
 }
@@ -1444,6 +1505,54 @@ function clearStateCookie(options) {
     header
   };
 }
+
+// src/express.ts
+function setSessionCookieOnResponse(res, sessionId, options) {
+  const cookie = createSessionCookie(sessionId, options);
+  res.cookie(cookie.name, cookie.value, cookie.options);
+}
+function clearSessionCookieOnResponse(res, options) {
+  const cookie = clearSessionCookie(options);
+  res.cookie(cookie.name, cookie.value, cookie.options);
+}
+function setStateCookieOnResponse(res, state, options) {
+  const cookie = createStateCookie(state, options);
+  res.cookie(cookie.name, cookie.value, cookie.options);
+}
+function clearStateCookieOnResponse(res, options) {
+  const cookie = clearStateCookie(options);
+  res.cookie(cookie.name, cookie.value, cookie.options);
+}
+function createRequireAuthMiddleware(lixa, options) {
+  const cookieName = options?.sessionCookieName || DEFAULT_SESSION_COOKIE_NAME;
+  return async (req, res, next) => {
+    try {
+      const sessionId = req.cookies?.[cookieName];
+      if (!sessionId) {
+        if (options?.unauthorizedHandler) {
+          options.unauthorizedHandler(req, res);
+          return;
+        }
+        res.status(401).json({ error: "Unauthorized: Missing session cookie" });
+        return;
+      }
+      const session = await lixa.fetchSessionInfo(sessionId);
+      if (!session) {
+        if (options?.unauthorizedHandler) {
+          options.unauthorizedHandler(req, res);
+          return;
+        }
+        res.status(401).json({ error: "Unauthorized: Invalid or expired session" });
+        return;
+      }
+      req.sessionInfo = session;
+      req.sessionId = sessionId;
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AccountLinkingStrategy,
@@ -1463,7 +1572,10 @@ function clearStateCookie(options) {
   SessionNotFoundError,
   TokenExchangeError,
   clearSessionCookie,
+  clearSessionCookieOnResponse,
   clearStateCookie,
+  clearStateCookieOnResponse,
+  createRequireAuthMiddleware,
   createSessionCookie,
   createStateCookie,
   decodeIdToken,
@@ -1471,6 +1583,8 @@ function clearStateCookie(options) {
   extractUserInfo,
   fetchUserInfo,
   isProductionEnvironment,
-  serializeCookie
+  serializeCookie,
+  setSessionCookieOnResponse,
+  setStateCookieOnResponse
 });
 //# sourceMappingURL=index.cjs.map