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

package/dist/index.js

@@ -28,7 +28,7 @@ var LocalStateHandler = class {
       }
     };
   }
-  // Default GenerateState implementation
+  // Default generateState implementation
   async generateState(provider) {
     const state = randomBytes(16).toString("hex");
     const codeVerifier = randomBytes(32).toString("hex");
@@ -41,6 +41,10 @@ var LocalStateHandler = class {
       }
     };
   }
+  // PascalCase alias for backward compatibility
+  async GenerateState(provider) {
+    return this.generateState(provider);
+  }
 };
 
 // src/lixa.ts
@@ -53,7 +57,20 @@ var LocalSessionHandler = class {
   emailToSessionMap = /* @__PURE__ */ new Map();
   sessionStorage;
   constructor(defaultTtlSeconds = 600) {
-    this.cache = new NodeCache2({ stdTTL: defaultTtlSeconds });
+    this.cache = new NodeCache2({ 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);
@@ -84,8 +101,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");
     }
@@ -95,6 +112,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
@@ -166,13 +187,91 @@ async function extractUserInfo(tokenData, providerMetadata) {
   return { userInfo };
 }
 
+// src/errors.ts
+var LixaError = class extends Error {
+  /**
+   * Standard error code string.
+   */
+  code;
+  /**
+   * Additional error context data.
+   */
+  details;
+  constructor(message, code = "LIXA_ERROR", details) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidStateError = class extends LixaError {
+  constructor(message = "Invalid or expired state", details) {
+    super(message, "INVALID_STATE", details);
+  }
+};
+var ProviderNotConfiguredError = class extends LixaError {
+  constructor(provider, details) {
+    const message = details?.message && typeof details.message === "string" ? details.message : `Provider '${provider}' is not available. Either import it from '@vunexa/lixa-providers' and include it in the configuration, or provide a custom implementation using the 'provider' field: { provider: new CustomProvider(), clientId: '...', ... }`;
+    super(message, "PROVIDER_NOT_CONFIGURED", {
+      provider,
+      ...details
+    });
+  }
+};
+var InvalidProviderConfigError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_PROVIDER_CONFIG", details);
+  }
+};
+var InvalidOAuthCallbackError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_OAUTH_CALLBACK", details);
+  }
+};
+var TokenExchangeError = class extends LixaError {
+  status;
+  constructor(message, status, details) {
+    super(message, "TOKEN_EXCHANGE_FAILED", { status, ...details });
+    this.status = status;
+  }
+};
+var SessionNotFoundError = class extends LixaError {
+  constructor(message = "Active session not found or has expired", details) {
+    super(message, "SESSION_NOT_FOUND", details);
+  }
+};
+var EmailNotVerifiedError = class extends LixaError {
+  constructor(email, details) {
+    super(
+      `Cannot link account: email '${email || "unknown"}' is not verified by the identity provider`,
+      "EMAIL_NOT_VERIFIED",
+      { email, ...details }
+    );
+  }
+};
+var AccountUnlinkError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "ACCOUNT_UNLINK_ERROR", details);
+  }
+};
+var RefreshTokenError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "REFRESH_TOKEN_ERROR", details);
+  }
+};
+
 // src/lixa.ts
 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;
@@ -193,10 +292,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
@@ -211,8 +344,9 @@ var Lixa = class _Lixa {
       } else {
         if (!_Lixa.DEFAULT_PROVIDERS.has(name) && !_Lixa.CONFIGURED_PROVIDERS.has(name)) {
           this.log("ERROR", "Init", `Provider '${providerName}' not available`);
-          throw new Error(
-            `Provider '${providerName}' is not available. Either import it from '@vunexa/lixa-providers' and include it in the configuration, or provide a custom implementation using the 'provider' field: { provider: new CustomProvider(), clientId: '...', ... }`
+          throw new ProviderNotConfiguredError(
+            providerName,
+            { hint: `Ensure the provider is registered via '@vunexa/lixa-providers' or provided inline.` }
           );
         }
         this.log("INFO", "Init", `Using registered provider: ${providerName}`);
@@ -225,7 +359,7 @@ var Lixa = class _Lixa {
    * 
    * @param name - The provider name
    * @param config - The provider configuration
-   * @throws Error when required fields are missing or invalid
+   * @throws InvalidProviderConfigError when required fields are missing or invalid
    */
   validateProviderConfig(name, config) {
     const requiredFields = ["clientId", "clientSecret", "redirectUri", "scopes"];
@@ -234,18 +368,21 @@ var Lixa = class _Lixa {
       return value === void 0 || value === null || typeof value === "string" && value.trim() === "";
     });
     if (missingFields.length > 0) {
-      throw new Error(
-        `Provider '${name}' configuration is missing required fields: ${missingFields.join(", ")}`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration is missing required fields: ${missingFields.join(", ")}`,
+        { provider: name, missingFields }
       );
     }
     if (!Array.isArray(config.scopes)) {
-      throw new Error(
-        `Provider '${name}' configuration error: 'scopes' must be an array of strings`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration error: 'scopes' must be an array of strings`,
+        { provider: name }
       );
     }
     if (config.scopes.length === 0) {
-      throw new Error(
-        `Provider '${name}' configuration error: 'scopes' array cannot be empty`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' configuration error: 'scopes' array cannot be empty`,
+        { provider: name }
       );
     }
   }
@@ -254,7 +391,7 @@ var Lixa = class _Lixa {
    * 
    * @param name - The provider name
    * @param provider - The provider implementation
-   * @throws Error when required properties are missing
+   * @throws InvalidProviderConfigError when required properties are missing
    */
   validateProviderImplementation(name, provider) {
     const requiredProps = ["authorizationEndpoint", "tokenEndpoint", "userInfoEndpoint"];
@@ -263,24 +400,27 @@ var Lixa = class _Lixa {
       return !value || typeof value !== "string" || value.trim() === "";
     });
     if (missingProps.length > 0) {
-      throw new Error(
-        `Provider '${name}' implementation is missing required properties: ${missingProps.join(", ")}. All IProvider implementations must define: authorizationEndpoint, tokenEndpoint, and userInfoEndpoint.`
+      throw new InvalidProviderConfigError(
+        `Provider '${name}' implementation is missing required properties: ${missingProps.join(", ")}. All IProvider implementations must define: authorizationEndpoint, tokenEndpoint, and userInfoEndpoint.`,
+        { provider: name, missingProps }
       );
     }
   }
   /**
-   * 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}]`;
@@ -331,8 +471,9 @@ var Lixa = class _Lixa {
     if (legacyProvider) {
       return legacyProvider;
     }
-    throw new Error(
-      `Provider '${name}' not found. Ensure the provider is included in the configuration with a 'provider' field, or registered using Lixa.registerProvider().`
+    throw new ProviderNotConfiguredError(
+      name,
+      { hint: `Ensure the provider is included in the configuration with a 'provider' field, or registered using Lixa.registerProvider().` }
     );
   }
   /**
@@ -522,23 +663,26 @@ var Lixa = class _Lixa {
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
       this.log("ERROR", "Auth", `Provider '${String(provider)}' is not configured`);
-      throw new Error(`Provider '${String(provider)}' is not configured in this Lixa instance`);
+      throw new ProviderNotConfiguredError(String(provider), {
+        message: `Provider '${String(provider)}' is not configured in this Lixa instance`
+      });
     }
     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 || randomBytes2(16).toString("hex");
       codeVerifier = randomBytes2(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,
         {
@@ -547,12 +691,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,
@@ -571,9 +720,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"],
@@ -602,7 +754,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) {
@@ -638,18 +790,18 @@ var Lixa = class _Lixa {
     this.log("INFO", "Auth", `Handling OAuth callback for provider: ${providerType}`);
     if (!code || code.trim() === "") {
       this.log("ERROR", "Auth", "Invalid or missing authorization code in callback");
-      throw new Error("Invalid or missing code in callback");
+      throw new InvalidOAuthCallbackError("Invalid or missing code in callback");
     }
     if (!state || state.trim() === "") {
       this.log("ERROR", "Auth", "Invalid or missing state in callback");
-      throw new Error("Invalid or missing state in callback");
+      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 });
-      throw new Error("Invalid or expired state");
+      throw new InvalidStateError("Invalid or expired state", { state });
     }
     this.log("INFO", "State", "State validated successfully, removing from cache");
     await stateStorage.deleteState(state);
@@ -657,7 +809,9 @@ var Lixa = class _Lixa {
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
       this.log("ERROR", "Auth", `Provider '${String(provider)}' is not configured`);
-      throw new Error(`Provider '${String(provider)}' is not configured in this Lixa instance`);
+      throw new ProviderNotConfiguredError(String(provider), {
+        message: `Provider '${String(provider)}' is not configured in this Lixa instance`
+      });
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     this.log("INFO", "Token", `Exchanging authorization code for tokens`, { provider: providerType });
@@ -683,9 +837,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");
     }
@@ -694,7 +851,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";
@@ -747,27 +904,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 Error("Invalid session ID. User must be authenticated to link an account.");
+      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 Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    let codeVerifier = randomBytes2(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: {
@@ -805,14 +966,17 @@ 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 Error("Session not found or has no linked accounts.");
+      throw new AccountUnlinkError("Session not found or has no linked accounts.", { sessionId });
     }
     const linkedProviders = Object.keys(session.accounts);
     if (linkedProviders.length <= 1) {
-      throw new Error("Cannot unlink the only authentication provider for this account.");
+      throw new AccountUnlinkError("Cannot unlink the only authentication provider for this account.", {
+        sessionId,
+        provider: providerToUnlink
+      });
     }
     delete session.accounts[providerToUnlink.toLowerCase()];
     await sessionStorage.saveSession(sessionId, session, 86400);
@@ -831,20 +995,20 @@ 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 Error("Authentication required. Active session must exist to connect resource providers.");
+      throw new SessionNotFoundError("Authentication required. Active session must exist to connect resource providers.", { sessionId });
     }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     const stateValue = state || randomBytes2(16).toString("hex");
     const codeVerifier = randomBytes2(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,
       {
@@ -869,45 +1033,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";
   }
@@ -916,25 +1041,26 @@ 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 Error("Authentication required. Active session not found for resource connection.");
+      throw new SessionNotFoundError("Authentication required. Active session not found for resource connection.", { sessionId });
     }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${String(provider)}' is not configured`);
+      throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     let codeVerifier = randomBytes2(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;
@@ -948,7 +1074,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;
@@ -963,7 +1089,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;
@@ -981,7 +1107,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);
   }
   /**
@@ -991,7 +1117,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();
@@ -1016,20 +1142,40 @@ 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) {
-      throw new Error(`No refresh token available for user '${userIdOrEmail}' on connected resource '${provider}'`);
+      throw new RefreshTokenError(
+        `No refresh token available for user '${userIdOrEmail}' on connected resource '${provider}'`,
+        { userId: userIdOrEmail, provider }
+      );
     }
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
-      throw new Error(`Provider '${provider}' is not configured`);
+      throw new ProviderNotConfiguredError(provider);
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
     const body = {
@@ -1048,7 +1194,10 @@ var Lixa = class _Lixa {
     });
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to refresh resource token for user '${userIdOrEmail}' on '${provider}': ${response.status} - ${errorText}`);
+      throw new RefreshTokenError(
+        `Failed to refresh resource token for user '${userIdOrEmail}' on '${provider}': ${response.status} - ${errorText}`,
+        { userId: userIdOrEmail, provider, status: response.status }
+      );
     }
     const tokens = await response.json();
     const expiresAt = tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0;
@@ -1068,10 +1217,10 @@ 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 Error("Active session not found.");
+      throw new SessionNotFoundError("Active session not found.", { sessionId });
     }
     const providerType = provider.toLowerCase();
     const userKey = this.getUserKeyFromSession(activeSession);
@@ -1086,7 +1235,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;
   }
@@ -1094,7 +1243,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);
@@ -1107,10 +1256,22 @@ var Lixa = class _Lixa {
     }
     return false;
   }
+  /**
+   * 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);
   }
+  /**
+   * Deletes a session from session storage (e.g. on logout).
+   * 
+   * @param sessionId - Active session identifier
+   */
+  async deleteSession(sessionId) {
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
+    await sessionStorage.deleteSession(sessionId);
+  }
   async exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier) {
     const body = {
       client_id: providerConfig.clientId,
@@ -1141,8 +1302,10 @@ var Lixa = class _Lixa {
         statusText: response.statusText,
         error: errorBody
       });
-      throw new Error(
-        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`
+      throw new TokenExchangeError(
+        `Token exchange failed: ${response.status} ${response.statusText} - ${errorBody}`,
+        response.status,
+        { statusText: response.statusText, errorBody }
       );
     }
     this.log("INFO", "Token", "Token exchange response received successfully");
@@ -1157,12 +1320,204 @@ var Lixa = class _Lixa {
     return void 0;
   }
 };
+
+// src/utils/cookies.ts
+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 = 5 * 60;
+function isProductionEnvironment() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+function serializeCookie(name, value, options) {
+  const isProd = isProductionEnvironment();
+  const path = options?.path ?? "/";
+  const httpOnly = options?.httpOnly ?? true;
+  const secure = options?.secure ?? isProd;
+  const sameSite = options?.sameSite ?? "lax";
+  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+  if (path) {
+    parts.push(`Path=${path}`);
+  }
+  if (typeof options?.maxAge === "number") {
+    parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    const expires = new Date(Date.now() + options.maxAge * 1e3).toUTCString();
+    parts.push(`Expires=${expires}`);
+  }
+  if (options?.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (httpOnly) {
+    parts.push("HttpOnly");
+  }
+  if (secure) {
+    parts.push("Secure");
+  }
+  if (sameSite) {
+    const capitalized = sameSite.charAt(0).toUpperCase() + sameSite.slice(1).toLowerCase();
+    parts.push(`SameSite=${capitalized}`);
+  }
+  return parts.join("; ");
+}
+function createSessionCookie(sessionId, options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_SESSION_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: options?.maxAge ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, sessionId, resolvedOptions);
+  return {
+    name,
+    value: sessionId,
+    options: resolvedOptions,
+    header
+  };
+}
+function clearSessionCookie(options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_SESSION_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: 0,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, "", resolvedOptions);
+  return {
+    name,
+    value: "",
+    options: resolvedOptions,
+    header
+  };
+}
+function createStateCookie(state, options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_STATE_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: options?.maxAge ?? DEFAULT_STATE_MAX_AGE_SECONDS,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, state, resolvedOptions);
+  return {
+    name,
+    value: state,
+    options: resolvedOptions,
+    header
+  };
+}
+function clearStateCookie(options) {
+  const isProd = isProductionEnvironment();
+  const resolvedOptions = {
+    name: options?.name || DEFAULT_STATE_COOKIE_NAME,
+    path: options?.path ?? "/",
+    maxAge: 0,
+    httpOnly: options?.httpOnly ?? true,
+    secure: options?.secure ?? isProd,
+    sameSite: options?.sameSite ?? "lax",
+    domain: options?.domain
+  };
+  const name = resolvedOptions.name;
+  const header = serializeCookie(name, "", resolvedOptions);
+  return {
+    name,
+    value: "",
+    options: resolvedOptions,
+    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);
+    }
+  };
+}
 export {
   AccountLinkingStrategy,
+  AccountUnlinkError,
+  DEFAULT_SESSION_COOKIE_NAME,
+  DEFAULT_SESSION_MAX_AGE_SECONDS,
+  DEFAULT_STATE_COOKIE_NAME,
+  DEFAULT_STATE_MAX_AGE_SECONDS,
+  EmailNotVerifiedError,
+  InvalidOAuthCallbackError,
+  InvalidProviderConfigError,
+  InvalidStateError,
   Lixa,
+  LixaError,
+  ProviderNotConfiguredError,
+  RefreshTokenError,
+  SessionNotFoundError,
+  TokenExchangeError,
+  clearSessionCookie,
+  clearSessionCookieOnResponse,
+  clearStateCookie,
+  clearStateCookieOnResponse,
+  createRequireAuthMiddleware,
+  createSessionCookie,
+  createStateCookie,
   decodeIdToken,
   determineProviderFromIssuer,
   extractUserInfo,
-  fetchUserInfo
+  fetchUserInfo,
+  isProductionEnvironment,
+  serializeCookie,
+  setSessionCookieOnResponse,
+  setStateCookieOnResponse
 };
 //# sourceMappingURL=index.js.map