@vunexa/lixa 0.1.6-alpha.13 → 0.1.6-alpha.14

package/dist/index.js

@@ -387,10 +387,24 @@ var WeakPasswordError = class extends LixaError {
   }
 };
 var CredentialsNotConfiguredError = class extends LixaError {
-  constructor(message = "Credentials authentication is not configured in this Lixa instance. Pass credentials: {} in LixaConfig to enable it.", details) {
+  constructor(message = "Credentials authentication is not configured in this Lixa instance. Pass credentials: {} or identity: ... in LixaConfig to enable it.", details) {
     super(message, "CREDENTIALS_NOT_CONFIGURED", details);
   }
 };
+var IdentityProviderError = class extends LixaError {
+  provider;
+  statusCode;
+  constructor(message, provider, statusCode, details) {
+    super(message, "IDENTITY_PROVIDER_ERROR", { provider, statusCode, ...details });
+    this.provider = provider;
+    this.statusCode = statusCode;
+  }
+};
+var IdentityNotConfiguredError = class extends CredentialsNotConfiguredError {
+  constructor(message = "Identity provider is not configured in this Lixa instance. Pass identity: ... or credentials: {} in LixaConfig to enable it.", details) {
+    super(message, details);
+  }
+};
 
 // src/credentials/credentials-manager.ts
 var CredentialsManager = class {
@@ -586,6 +600,94 @@ var CredentialsManager = class {
   }
 };
 
+// src/identity/self-managed.ts
+var SelfManagedIdentityProvider = class {
+  name = "self-managed";
+  manager;
+  constructor(configOrManager) {
+    if (configOrManager instanceof CredentialsManager) {
+      this.manager = configOrManager;
+    } else {
+      this.manager = new CredentialsManager(configOrManager || {});
+    }
+  }
+  mapUser(user) {
+    return {
+      id: user.id,
+      identifier: user.identifier,
+      username: user.username,
+      email: user.email,
+      emailVerified: true,
+      // Self-managed accounts verify locally unless configured otherwise
+      createdAt: user.createdAt,
+      updatedAt: user.updatedAt,
+      metadata: user.metadata,
+      provider: this.name
+    };
+  }
+  /**
+   * Registers a new user.
+   */
+  async signUp(params) {
+    const user = await this.manager.signUp(params);
+    return this.mapUser(user);
+  }
+  /**
+   * Authenticates a user with password.
+   */
+  async signIn(params) {
+    const user = await this.manager.verifyCredentials(params);
+    if (!user) {
+      throw new InvalidCredentialsError();
+    }
+    return {
+      user: this.mapUser(user)
+    };
+  }
+  /**
+   * Verifies credentials without throwing an error if invalid.
+   */
+  async verifyCredentials(params) {
+    const user = await this.manager.verifyCredentials(params);
+    return user ? this.mapUser(user) : null;
+  }
+  /**
+   * Changes a user's password.
+   */
+  async changePassword(params) {
+    return await this.manager.changePassword(params);
+  }
+  /**
+   * Retrieves a user by their unique ID.
+   */
+  async getUserById(id) {
+    const user = await this.manager.getUserById(id);
+    return user ? this.mapUser(user) : null;
+  }
+  /**
+   * Retrieves a user by their identifier (email or username).
+   */
+  async getUserByIdentifier(identifier) {
+    const user = await this.manager.getUserByIdentifier(identifier);
+    return user ? this.mapUser(user) : null;
+  }
+  /**
+   * Deletes a user from storage if supported by the storage adapter.
+   */
+  async deleteUser(id) {
+    const storage = this.manager.getStorage();
+    if (typeof storage.deleteUser === "function") {
+      await storage.deleteUser(id);
+    }
+  }
+  /**
+   * Returns the underlying CredentialsManager instance.
+   */
+  getCredentialsManager() {
+    return this.manager;
+  }
+};
+
 // src/types.ts
 var AccountLinkingStrategy = /* @__PURE__ */ ((AccountLinkingStrategy2) => {
   AccountLinkingStrategy2["AUTO_LINK_BY_VERIFIED_EMAIL"] = "AUTO_LINK_BY_VERIFIED_EMAIL";
@@ -691,10 +793,7 @@ var LocalSessionHandler = class {
     if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
       throw new Error("No valid access token found in OAuth response");
     }
-    const session = {
-      token: tokenData.access_token,
-      raw: tokenData
-    };
+    const session = {};
     return session;
   }
   // PascalCase alias for backward compatibility
@@ -772,6 +871,125 @@ async function extractUserInfo(tokenData, providerMetadata) {
   return { userInfo };
 }
 
+// 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/lixa.ts
 var Lixa = class _Lixa {
   static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
@@ -781,14 +999,19 @@ var Lixa = class _Lixa {
   localStateHandler;
   localSessionHandler;
   localResourceHandler;
+  localAccountHandler;
   userResourceStore = /* @__PURE__ */ new Map();
+  userAccountStore = /* @__PURE__ */ new Map();
   refreshMutexes = /* @__PURE__ */ new Map();
+  identityProvider;
   credentialsManager;
   config;
   stateHandler;
   sessionHandler;
   resourceHandler;
+  accountHandler;
   debug;
+  sessionCookieResolver;
   /**
    * Creates a new Lixa instance with the provided configuration.
    * 
@@ -803,7 +1026,15 @@ var Lixa = class _Lixa {
    * @throws Error when provider is not available and no inline implementation is provided
    */
   constructor(config) {
-    this.config = config;
+    this.sessionCookieResolver = config.sessionCookieName;
+    const federatedOAuthProviders = config.federatedOAuthProviders || config.providers;
+    this.config = {
+      ...config,
+      ...federatedOAuthProviders ? {
+        providers: federatedOAuthProviders,
+        federatedOAuthProviders
+      } : {}
+    };
     this.debug = config.debug || false;
     this.localStateHandler = new LocalStateHandler();
     this.localSessionHandler = new LocalSessionHandler();
@@ -839,19 +1070,70 @@ var Lixa = class _Lixa {
         }
       }
     };
-    this.stateHandler = config.stateHandler || this.localStateHandler;
-    this.sessionHandler = config.sessionHandler || this.localSessionHandler;
-    this.resourceHandler = config.resourceHandler || this.localResourceHandler;
-    if (config.credentials !== void 0 && config.credentials.enabled !== false) {
-      this.credentialsManager = new CredentialsManager(config.credentials);
+    this.localAccountHandler = {
+      accountStorage: {
+        saveAccount: async (userId, provider, account) => {
+          let userMap = this.userAccountStore.get(userId);
+          if (!userMap) {
+            userMap = /* @__PURE__ */ new Map();
+            this.userAccountStore.set(userId, userMap);
+          }
+          userMap.set(provider.toLowerCase(), account);
+        },
+        getAccount: async (userId, provider) => {
+          const userMap = this.userAccountStore.get(userId);
+          return userMap?.get(provider.toLowerCase()) || null;
+        },
+        getUserAccounts: async (userId) => {
+          const userMap = this.userAccountStore.get(userId);
+          const result = {};
+          if (userMap) {
+            for (const [p, a] of userMap.entries()) {
+              result[p] = a;
+            }
+          }
+          return result;
+        },
+        deleteAccount: async (userId, provider) => {
+          const userMap = this.userAccountStore.get(userId);
+          if (userMap) {
+            userMap.delete(provider.toLowerCase());
+          }
+        }
+      }
+    };
+    const storage = config.storage;
+    this.stateHandler = config.stateHandler || (storage?.stateStorage ? { storage: storage.stateStorage } : this.localStateHandler);
+    this.sessionHandler = config.sessionHandler || (storage?.sessionStorage ? { storage: storage.sessionStorage } : this.localSessionHandler);
+    this.resourceHandler = config.resourceHandler || (storage?.resourceStorage ? { resourceStorage: storage.resourceStorage } : this.localResourceHandler);
+    this.accountHandler = storage?.accountStorage ? { accountStorage: storage.accountStorage } : this.localAccountHandler;
+    const identityConfig = config.identityProvider || config.identity;
+    if (identityConfig) {
+      if (typeof identityConfig.signUp === "function") {
+        this.identityProvider = identityConfig;
+        if (this.identityProvider instanceof SelfManagedIdentityProvider) {
+          this.credentialsManager = this.identityProvider.getCredentialsManager();
+        }
+      } else {
+        const selfManaged = new SelfManagedIdentityProvider(identityConfig);
+        this.identityProvider = selfManaged;
+        this.credentialsManager = selfManaged.getCredentialsManager();
+      }
+    } else if (config.credentials !== void 0 && config.credentials.enabled !== false) {
+      const selfManaged = new SelfManagedIdentityProvider(config.credentials);
+      this.identityProvider = selfManaged;
+      this.credentialsManager = selfManaged.getCredentialsManager();
     }
+    const oauthProviders = this.config.providers;
     this.log("INFO", "Init", "Initializing Lixa instance", {
-      providers: config.providers ? Object.keys(config.providers) : [],
-      credentialsEnabled: this.credentialsManager !== void 0,
+      providers: oauthProviders ? Object.keys(oauthProviders) : [],
+      identityProvider: this.identityProvider ? this.identityProvider.name : void 0,
+      identityEnabled: this.identityProvider !== void 0,
+      credentialsEnabled: this.identityProvider !== void 0,
       debug: this.debug
     });
-    if (config.providers) {
-      for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+    if (oauthProviders) {
+      for (const [providerName, providerConfig] of Object.entries(oauthProviders)) {
         const name = providerName.toLowerCase();
         const typedConfig = providerConfig;
         this.validateProviderConfig(providerName, typedConfig);
@@ -880,6 +1162,20 @@ var Lixa = class _Lixa {
    * @throws InvalidProviderConfigError when required fields are missing or invalid
    */
   validateProviderConfig(name, config) {
+    if (!config.scopes || config.scopes.length === 0) {
+      const p = config.provider;
+      if (p?.defaultScopes && Array.isArray(p.defaultScopes) && p.defaultScopes.length > 0) {
+        config.scopes = [...p.defaultScopes];
+      } else if (p?.authScopes && Array.isArray(p.authScopes) && p.authScopes.length > 0) {
+        config.scopes = [...p.authScopes];
+      } else if (name === "google" || name.startsWith("google")) {
+        config.scopes = ["openid", "profile", "email"];
+      } else if (name === "github" || name.startsWith("github")) {
+        config.scopes = ["read:user", "user:email"];
+      } else if (name.startsWith("cognito")) {
+        config.scopes = ["openid", "email", "profile"];
+      }
+    }
     const requiredFields = ["clientId", "clientSecret", "redirectUri", "scopes"];
     const missingFields = requiredFields.filter((field) => {
       const value = config[field];
@@ -1216,7 +1512,7 @@ var Lixa = class _Lixa {
     this.log("INFO", "State", `Saved state for provider: ${providerType}`, { state: stateValue });
     const authNScopes = this.resolveAuthNScopes(
       providerType,
-      providerConfig.scopes,
+      providerConfig.scopes || [],
       providerImpl,
       providerConfig.allowNonAuthScopes
     );
@@ -1302,7 +1598,8 @@ var Lixa = class _Lixa {
   async handleCallback({
     provider,
     code,
-    state
+    state,
+    sessionId
   }) {
     const providerType = String(provider).toLowerCase();
     this.log("INFO", "Auth", `Handling OAuth callback for provider: ${providerType}`);
@@ -1371,19 +1668,40 @@ var Lixa = class _Lixa {
     }
     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";
+    const mode = typeof linkingConfig === "object" ? String(linkingConfig?.mode || "") : "";
+    const isLinkByEmail = linkingConfig === true || linkingConfig === "linkByEmail" || linkingConfig === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || mode === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || mode === "AUTO_LINK_BY_VERIFIED_EMAIL" || mode === "linkByEmail";
     const email = extractedUserInfo?.email;
     const isVerified = extractedUserInfo?.email_verified !== false;
-    const requireVerified = linkingConfig?.requireVerifiedEmail ?? true;
+    const requireVerified = typeof linkingConfig === "object" ? linkingConfig?.requireVerifiedEmail ?? true : true;
     const canLink = isLinkByEmail && email && (!requireVerified || isVerified);
+    if (sessionId) {
+      const activeSession = await sessionStorage.getSession(sessionId);
+      if (activeSession) {
+        this.log("INFO", "AccountLinking", `Linking provider '${providerType}' directly to active session '${sessionId}'`);
+        const linkedAcc2 = {
+          provider: providerType,
+          providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+          email: extractedUserInfo?.email || activeSession.email,
+          accessToken: tokens.access_token,
+          raw: tokens,
+          linkedAt: Date.now()
+        };
+        activeSession.accounts = activeSession.accounts || {};
+        activeSession.accounts[providerType] = linkedAcc2;
+        await sessionStorage.saveSession(sessionId, activeSession, 86400);
+        if (this.accountHandler?.accountStorage) {
+          const userKey = this.getUserKeyFromSession(activeSession);
+          await this.accountHandler.accountStorage.saveAccount(userKey, providerType, linkedAcc2);
+        }
+        return sessionId;
+      }
+    }
     if (canLink && sessionStorage.getSessionByEmail) {
       const existingRecord = await sessionStorage.getSessionByEmail(email);
       if (existingRecord) {
         this.log("INFO", "AccountLinking", `Linking provider '${providerType}' to existing session for email '${email}'`);
         const { sessionId: existingSessionId, session: existingSession } = existingRecord;
-        existingSession.accounts = existingSession.accounts || {};
-        existingSession.accounts[providerType] = {
+        const linkedAcc2 = {
           provider: providerType,
           providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
           email,
@@ -1391,15 +1709,18 @@ var Lixa = class _Lixa {
           raw: tokens,
           linkedAt: Date.now()
         };
+        existingSession.accounts = existingSession.accounts || {};
+        existingSession.accounts[providerType] = linkedAcc2;
         existingSession.provider = providerType;
-        existingSession.token = tokens.access_token;
-        existingSession.raw = tokens;
         await sessionStorage.saveSession(existingSessionId, existingSession, 86400);
+        if (this.accountHandler?.accountStorage) {
+          const userKey = this.getUserKeyFromSession(existingSession);
+          await this.accountHandler.accountStorage.saveAccount(userKey, providerType, linkedAcc2);
+        }
         return existingSessionId;
       }
     }
-    session.accounts = session.accounts || {};
-    session.accounts[providerType] = {
+    const linkedAcc = {
       provider: providerType,
       providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
       email: extractedUserInfo?.email,
@@ -1407,12 +1728,18 @@ var Lixa = class _Lixa {
       raw: tokens,
       linkedAt: Date.now()
     };
-    const sessionId = randomBytes2(32).toString("hex");
-    session.id = sessionId;
-    this.log("INFO", "Session", "Storing session", { sessionId });
-    await sessionStorage.saveSession(sessionId, session, 86400);
-    this.log("INFO", "Session", "Session created successfully", { sessionId });
-    return sessionId;
+    session.accounts = session.accounts || {};
+    session.accounts[providerType] = linkedAcc;
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(session);
+      await this.accountHandler.accountStorage.saveAccount(userKey, providerType, linkedAcc);
+    }
+    const newSessionId = randomBytes2(32).toString("hex");
+    session.sessionId = newSessionId;
+    this.log("INFO", "Session", "Storing session", { sessionId: newSessionId });
+    await sessionStorage.saveSession(newSessionId, session, 86400);
+    this.log("INFO", "Session", "Session created successfully", { sessionId: newSessionId });
+    return newSessionId;
   }
   /**
    * Explicitly link a new OAuth provider account to an active session.
@@ -1498,6 +1825,10 @@ var Lixa = class _Lixa {
     }
     delete session.accounts[providerToUnlink.toLowerCase()];
     await sessionStorage.saveSession(sessionId, session, 86400);
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(session);
+      await this.accountHandler.accountStorage.deleteAccount(userKey, providerToUnlink.toLowerCase());
+    }
     return true;
   }
   /**
@@ -1512,7 +1843,7 @@ var Lixa = class _Lixa {
    * @returns The authorization URL for resource consent
    */
   async getResourceAuthUrl(params) {
-    const { sessionId, provider, scopes, state, prompt, extraConfig } = params;
+    const { sessionId, provider, state, prompt, extraConfig } = params;
     const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const activeSession = await sessionStorage.getSession(sessionId);
     if (!activeSession) {
@@ -1523,6 +1854,10 @@ var Lixa = class _Lixa {
     if (!providerConfig) {
       throw new ProviderNotConfiguredError(String(provider));
     }
+    const requestedScopes = params.scopes && params.scopes.length > 0 ? params.scopes : providerConfig.resourceScopes || [];
+    if (requestedScopes.length === 0) {
+      throw new Error(`No scopes specified for resource '${provider}'. Provide scopes in getResourceAuthUrl() or configure 'resourceScopes' on the provider.`);
+    }
     const providerImpl = this.getProvider(providerType, providerConfig);
     const stateValue = state || randomBytes2(16).toString("hex");
     const codeVerifier = randomBytes2(32).toString("hex");
@@ -1540,7 +1875,7 @@ var Lixa = class _Lixa {
     const searchParams = new URLSearchParams({
       client_id: providerConfig.clientId,
       redirect_uri: providerConfig.redirectUri,
-      scope: scopes.join(" "),
+      scope: requestedScopes.join(" "),
       state: stateValue,
       response_type: "code",
       code_challenge: codeChallenge,
@@ -1552,7 +1887,7 @@ var Lixa = class _Lixa {
     return `${providerImpl.authorizationEndpoint}?${searchParams.toString()}`;
   }
   getUserKeyFromSession(session) {
-    return session.userId || session.email || session.id || "anonymous";
+    return session.userId || session.email || session.sessionId || "anonymous";
   }
   /**
    * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
@@ -1582,12 +1917,13 @@ var Lixa = class _Lixa {
     }
     const tokens = await this.exchangeCodeForToken(code, providerConfig, providerImpl, codeVerifier);
     const expiresAt = tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0;
+    const effectiveScopes = scopes || (tokens.scope ? tokens.scope.split(" ") : providerConfig.resourceScopes || []);
     const connectedResource = {
       provider: providerType,
       accessToken: tokens.access_token,
       refreshToken: tokens.refresh_token,
       expiresAt,
-      scopes: scopes || (tokens.scope ? tokens.scope.split(" ") : []),
+      scopes: effectiveScopes,
       raw: tokens,
       connectedAt: Date.now()
     };
@@ -1599,6 +1935,40 @@ var Lixa = class _Lixa {
     await sessionStorage.saveSession(sessionId, activeSession, 86400);
     return activeSession;
   }
+  /**
+   * Retrieves configured default resource scopes for a provider.
+   * 
+   * @param provider - Provider name (e.g. 'github', 'google')
+   * @returns Array of configured resource scopes, or undefined if not configured
+   */
+  getResourceScopes(provider) {
+    const providerConfig = this.findProviderByType(String(provider).toLowerCase());
+    return providerConfig?.resourceScopes;
+  }
+  /**
+   * Returns the resolved session cookie name.
+   * Dynamically reflects any changes to the active identity provider.
+   * 
+   * @param req - Optional request object for multi-tenant request-scoped cookie resolution
+   * @returns Resolved session cookie name
+   */
+  getSessionCookieName(req) {
+    if (typeof this.sessionCookieResolver === "function") {
+      return this.sessionCookieResolver(this, req);
+    }
+    if (typeof this.sessionCookieResolver === "string" && this.sessionCookieResolver.length > 0) {
+      return this.sessionCookieResolver;
+    }
+    return DEFAULT_SESSION_COOKIE_NAME;
+  }
+  /**
+   * Sets or updates the session cookie name or dynamic resolver on this instance.
+   * 
+   * @param resolver - Static cookie name or dynamic resolver function
+   */
+  setSessionCookieName(resolver) {
+    this.sessionCookieResolver = resolver;
+  }
   /**
    * Retrieves a connected resource for a specific User ID / Email directly (independent of session IDs).
    * Automatically refreshes expired access tokens if a refresh token is present.
@@ -1779,7 +2149,16 @@ var Lixa = class _Lixa {
    */
   async fetchSessionInfo(sessionId) {
     const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
-    return await sessionStorage.getSession(sessionId);
+    const session = await sessionStorage.getSession(sessionId);
+    if (!session) return null;
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(session);
+      const persistentAccounts = await this.accountHandler.accountStorage.getUserAccounts(userKey);
+      if (persistentAccounts && Object.keys(persistentAccounts).length > 0) {
+        session.accounts = { ...persistentAccounts, ...session.accounts || {} };
+      }
+    }
+    return session;
   }
   /**
    * Deletes a session from session storage (e.g. on logout).
@@ -1830,36 +2209,64 @@ var Lixa = class _Lixa {
     return response.json();
   }
   /**
-   * Checks if credentials (username and password) authentication is configured and enabled.
+   * Checks if an identity provider (Self-Managed Database, AWS Cognito, Auth0, Okta, etc.) is configured.
+   * 
+   * @returns True if identity provider is configured and available
+   */
+  isIdentityEnabled() {
+    return this.identityProvider !== void 0;
+  }
+  /**
+   * Checks if credentials / identity authentication is configured and enabled.
    * 
-   * @returns True if credentials authentication is available
+   * @returns True if credentials / identity authentication is available
    */
   isCredentialsEnabled() {
-    return this.credentialsManager !== void 0;
+    return this.identityProvider !== void 0;
+  }
+  /**
+   * Returns the configured IdentityProvider instance.
+   */
+  getIdentityProvider() {
+    return this.identityProvider;
+  }
+  /**
+   * Dynamically sets or updates the active identity provider (e.g. SelfManaged, Cognito, Auth0, Okta).
+   * 
+   * @param provider - Identity provider instance or undefined to disable
+   */
+  setIdentityProvider(provider) {
+    this.identityProvider = provider;
+    if (provider instanceof SelfManagedIdentityProvider) {
+      this.credentialsManager = provider.getCredentialsManager();
+    } else {
+      this.credentialsManager = void 0;
+    }
   }
   /**
-   * Returns the underlying CredentialsManager instance if configured.
+   * Returns the underlying CredentialsManager instance if using Self-Managed identity.
    */
   getCredentialsManager() {
     return this.credentialsManager;
   }
   /**
-   * Registers a new user with username/email and password.
-   * Automatically enforces password policy, hashes password with Scrypt/configured hasher,
-   * stores credentials, and creates a session (unless autoCreateSessionOnSignUp is false).
+   * Registers a new user with the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+   * Automatically creates an active session unless autoCreateSessionOnSignUp is explicitly set to false.
    * 
    * @param params - Registration parameters (identifier, password, email, username, metadata)
-   * @returns Created user (without password hash) and optional active session
+   * @returns Created user identity and optional active session
    * @throws WeakPasswordError if password does not meet policy requirements
    * @throws UserAlreadyExistsError if identifier is already registered
-   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   * @throws IdentityNotConfiguredError if identity authentication is not configured
    */
   async signUp(params) {
-    if (!this.credentialsManager) {
-      throw new CredentialsNotConfiguredError();
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
     }
-    this.log("INFO", "Credentials", "Processing signUp request", { identifier: params.identifier });
-    const user = await this.credentialsManager.signUp(params);
+    const rawProviderName = this.identityProvider.name;
+    const providerName = rawProviderName === "self-managed" ? "credentials" : rawProviderName;
+    this.log("INFO", "Identity", `Processing signUp request via ${providerName}`, { identifier: params.identifier });
+    const user = await this.identityProvider.signUp(params);
     const autoSession = this.config.credentials?.autoCreateSessionOnSignUp ?? true;
     if (!autoSession) {
       return { user };
@@ -1867,8 +2274,9 @@ var Lixa = class _Lixa {
     const sessionId = randomBytes2(16).toString("hex");
     const token = randomBytes2(32).toString("hex");
     const ttl = this.config.credentials?.sessionTtlSeconds ?? 86400;
+    const accountKey = providerName;
     const credentialsAccount = {
-      provider: "credentials",
+      provider: providerName,
       providerUserId: user.id,
       email: user.email,
       accessToken: token,
@@ -1880,67 +2288,71 @@ var Lixa = class _Lixa {
       linkedAt: Date.now()
     };
     const session = {
-      id: sessionId,
+      sessionId,
       userId: user.id,
       email: user.email,
-      token,
-      provider: "credentials",
+      provider: providerName,
       accounts: {
-        credentials: credentialsAccount
+        [accountKey]: credentialsAccount
       }
     };
     const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     await sessionStorage.saveSession(sessionId, session, ttl);
-    this.log("INFO", "Credentials", "Created session on signUp", { userId: user.id, sessionId });
+    this.log("INFO", "Identity", "Created session on signUp", { userId: user.id, sessionId, provider: providerName });
     return { user, sessionId, session };
   }
   /**
-   * Authenticates a user with username/email and password.
-   * Performs constant-time verification with timing attack mitigation, and creates an active session.
-   * If account linking is configured with AUTO_LINK_BY_VERIFIED_EMAIL, merges with existing session.
+   * Authenticates a user with credentials via the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+   * Creates an active session and automatically links with existing sessions when AUTO_LINK_BY_VERIFIED_EMAIL is configured.
    * 
    * @param params - Sign-in parameters (identifier, password)
    * @returns Authenticated user, session ID, and session object
    * @throws InvalidCredentialsError if authentication fails
-   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   * @throws IdentityNotConfiguredError if identity authentication is not configured
    */
   async signIn(params) {
-    if (!this.credentialsManager) {
-      throw new CredentialsNotConfiguredError();
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
     }
     const lookupKey = params.username || params.identifier;
-    this.log("INFO", "Credentials", "Processing signIn request", { identifier: lookupKey });
-    const user = await this.credentialsManager.verifyCredentials(params);
-    if (!user) {
-      this.log("WARN", "Credentials", "Invalid credentials provided", { identifier: lookupKey });
-      throw new InvalidCredentialsError();
-    }
+    const rawProviderName = this.identityProvider.name;
+    const providerName = rawProviderName === "self-managed" ? "credentials" : rawProviderName;
+    this.log("INFO", "Identity", `Processing signIn request via ${providerName}`, { identifier: lookupKey });
+    const authResult = await this.identityProvider.signIn(params);
+    const user = authResult.user;
+    const tokens = authResult.tokens;
     const ttl = this.config.credentials?.sessionTtlSeconds ?? 86400;
-    const token = randomBytes2(32).toString("hex");
+    const token = tokens?.accessToken || randomBytes2(32).toString("hex");
+    const rawTokens = {
+      access_token: token,
+      token_type: tokens?.tokenType || "Bearer",
+      expires_in: tokens?.expiresIn || ttl,
+      id_token: tokens?.idToken,
+      refresh_token: tokens?.refreshToken,
+      ...tokens?.raw
+    };
+    const accountKey = providerName === "self-managed" ? "credentials" : providerName;
     const credentialsAccount = {
-      provider: "credentials",
+      provider: providerName,
       providerUserId: user.id,
       email: user.email,
       accessToken: token,
-      raw: {
-        access_token: token,
-        token_type: "Bearer",
-        expires_in: ttl
-      },
+      raw: rawTokens,
       linkedAt: Date.now()
     };
     const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
-    const linkingMode = this.config.accountLinking?.mode;
-    const isAutoLink = linkingMode === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || linkingMode === "AUTO_LINK_BY_VERIFIED_EMAIL" || linkingMode === "linkByEmail";
+    const linkingConfig = this.config.accountLinking;
+    const linkingMode = typeof linkingConfig === "object" ? linkingConfig?.mode : void 0;
+    const isAutoLink = linkingConfig === true || linkingConfig === "linkByEmail" || linkingConfig === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || linkingMode === "AUTO_LINK_BY_VERIFIED_EMAIL" /* AUTO_LINK_BY_VERIFIED_EMAIL */ || linkingMode === "AUTO_LINK_BY_VERIFIED_EMAIL" || linkingMode === "linkByEmail";
     if (isAutoLink && user.email && sessionStorage.getSessionByEmail) {
       const existing = await sessionStorage.getSessionByEmail(user.email);
       if (existing) {
         const mergedSession = { ...existing.session };
-        mergedSession.accounts = { ...mergedSession.accounts || {}, credentials: credentialsAccount };
+        mergedSession.accounts = { ...mergedSession.accounts || {}, [accountKey]: credentialsAccount };
         if (!mergedSession.userId) mergedSession.userId = user.id;
         if (!mergedSession.email) mergedSession.email = user.email;
         await sessionStorage.saveSession(existing.sessionId, mergedSession, ttl);
-        this.log("INFO", "AccountLinking", "Linked credentials to existing session by email", {
+        this.log("INFO", "AccountLinking", `Linked ${providerName} to existing session by email`, {
           sessionId: existing.sessionId,
           email: user.email
         });
@@ -1953,31 +2365,46 @@ var Lixa = class _Lixa {
     }
     const sessionId = randomBytes2(16).toString("hex");
     const session = {
-      id: sessionId,
+      sessionId,
       userId: user.id,
       email: user.email,
-      token,
-      provider: "credentials",
+      provider: providerName,
       accounts: {
-        credentials: credentialsAccount
+        [accountKey]: credentialsAccount
       }
     };
+    const userKey = this.getUserKeyFromSession(session);
+    if (this.accountHandler?.accountStorage) {
+      const persistentAccounts = await this.accountHandler.accountStorage.getUserAccounts(userKey);
+      if (persistentAccounts && Object.keys(persistentAccounts).length > 0) {
+        session.accounts = { ...persistentAccounts, ...session.accounts };
+      }
+      await this.accountHandler.accountStorage.saveAccount(userKey, accountKey, credentialsAccount);
+    }
     await sessionStorage.saveSession(sessionId, session, ttl);
-    this.log("INFO", "Credentials", "User signed in successfully", { userId: user.id, sessionId });
+    this.log("INFO", "Identity", `User signed in successfully via ${providerName}`, { userId: user.id, sessionId });
     return { user, sessionId, session };
   }
   /**
    * Verifies username/email and password credentials without generating a session.
    * 
    * @param params - Verification parameters (identifier, password)
-   * @returns User credentials (without password hash) or null if invalid
-   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   * @returns User credentials/identity or null if invalid
+   * @throws IdentityNotConfiguredError if identity auth is not configured
    */
   async verifyCredentials(params) {
-    if (!this.credentialsManager) {
-      throw new CredentialsNotConfiguredError();
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
+    }
+    if (typeof this.identityProvider.verifyCredentials === "function") {
+      return this.identityProvider.verifyCredentials(params);
+    }
+    try {
+      const result = await this.identityProvider.signIn(params);
+      return result.user;
+    } catch {
+      return null;
     }
-    return this.credentialsManager.verifyCredentials(params);
   }
   /**
    * Updates a user's password after verifying the current password and enforcing policy on the new password.
@@ -1987,17 +2414,140 @@ var Lixa = class _Lixa {
    * @throws UserNotFoundError if user is not found
    * @throws InvalidCredentialsError if current password is incorrect
    * @throws WeakPasswordError if new password does not meet policy requirements
-   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   * @throws IdentityNotConfiguredError if identity auth is not configured
    */
   async changePassword(params) {
-    if (!this.credentialsManager) {
-      throw new CredentialsNotConfiguredError();
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
     }
-    this.log("INFO", "Credentials", "Processing changePassword request", {
+    if (typeof this.identityProvider.changePassword !== "function") {
+      throw new IdentityProviderError(
+        `Password change is not supported by the '${this.identityProvider.name}' identity provider`,
+        this.identityProvider.name
+      );
+    }
+    this.log("INFO", "Identity", "Processing changePassword request", {
       userId: params.userId,
       identifier: params.identifier
     });
-    return this.credentialsManager.changePassword(params);
+    return this.identityProvider.changePassword(params);
+  }
+  /**
+   * Initiates a password reset (forgot password flow) through the configured identity provider.
+   * 
+   * @param params - Forgot password parameters (identifier, optional metadata)
+   * @returns ForgotPasswordResult indicating status and delivery medium (email/SMS)
+   * @throws IdentityNotConfiguredError if identity auth is not configured
+   */
+  async forgotPassword(params) {
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
+    }
+    if (typeof this.identityProvider.forgotPassword !== "function") {
+      throw new IdentityProviderError(
+        `Password reset request is not supported by the '${this.identityProvider.name}' identity provider`,
+        this.identityProvider.name
+      );
+    }
+    this.log("INFO", "Identity", "Processing forgotPassword request", { identifier: params.identifier });
+    return this.identityProvider.forgotPassword(params);
+  }
+  /**
+   * Confirms a password reset using a verification code / token and sets the new password.
+   * 
+   * @param params - Verification code, identifier, and new password
+   * @returns True if password reset was successfully confirmed
+   * @throws IdentityNotConfiguredError if identity auth is not configured
+   */
+  async confirmPasswordReset(params) {
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
+    }
+    if (typeof this.identityProvider.confirmPasswordReset !== "function") {
+      throw new IdentityProviderError(
+        `Confirm password reset is not supported by the '${this.identityProvider.name}' identity provider`,
+        this.identityProvider.name
+      );
+    }
+    this.log("INFO", "Identity", "Processing confirmPasswordReset request", { identifier: params.identifier });
+    return this.identityProvider.confirmPasswordReset(params);
+  }
+  /**
+   * Confirms user account registration using a verification code.
+   * 
+   * @param params - Verification parameters including identifier and confirmationCode
+   * @returns True if confirmation was successful
+   * @throws IdentityNotConfiguredError if identity auth is not configured
+   * @throws IdentityProviderError if identity provider does not support confirmation
+   */
+  async confirmSignUp(params) {
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
+    }
+    if (typeof this.identityProvider.confirmSignUp !== "function") {
+      throw new IdentityProviderError(
+        `Account confirmation is not supported by the '${this.identityProvider.name}' identity provider`,
+        this.identityProvider.name
+      );
+    }
+    this.log("INFO", "Identity", "Processing confirmSignUp request", { identifier: params.identifier });
+    return this.identityProvider.confirmSignUp(params);
+  }
+  /**
+   * Resends the sign up confirmation code to the user.
+   * 
+   * @param params - Resend parameters including user identifier
+   * @returns Details about the code delivery (medium, destination)
+   * @throws IdentityNotConfiguredError if identity auth is not configured
+   * @throws IdentityProviderError if identity provider does not support resending codes
+   */
+  async resendConfirmationCode(params) {
+    if (!this.identityProvider) {
+      throw new IdentityNotConfiguredError();
+    }
+    if (typeof this.identityProvider.resendConfirmationCode !== "function") {
+      throw new IdentityProviderError(
+        `Resending confirmation code is not supported by the '${this.identityProvider.name}' identity provider`,
+        this.identityProvider.name
+      );
+    }
+    this.log("INFO", "Identity", "Processing resendConfirmationCode request", { identifier: params.identifier });
+    return this.identityProvider.resendConfirmationCode(params);
+  }
+  /**
+   * Retrieves a user by their unique ID from the configured identity provider.
+   * 
+   * @param id - Unique user ID
+   * @returns UserIdentity or null if not found
+   */
+  async getUserById(id) {
+    if (!this.identityProvider || typeof this.identityProvider.getUserById !== "function") {
+      return null;
+    }
+    return this.identityProvider.getUserById(id);
+  }
+  /**
+   * Retrieves a user by their identifier (username or email) from the configured identity provider.
+   * 
+   * @param identifier - Username or email string
+   * @returns UserIdentity or null if not found
+   */
+  async getUserByIdentifier(identifier) {
+    if (!this.identityProvider || typeof this.identityProvider.getUserByIdentifier !== "function") {
+      return null;
+    }
+    return this.identityProvider.getUserByIdentifier(identifier);
+  }
+  /**
+   * Deletes a user account from the configured identity provider.
+   * 
+   * @param id - Unique user ID
+   */
+  async deleteUser(id) {
+    if (!this.identityProvider || typeof this.identityProvider.deleteUser !== "function") {
+      return;
+    }
+    await this.identityProvider.deleteUser(id);
   }
   findProviderByType(providerType) {
     for (const [key, value] of Object.entries(this.config.providers || {})) {
@@ -2009,125 +2559,6 @@ var Lixa = class _Lixa {
   }
 };
 
-// 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/credentials/index.ts
 var credentials_exports = {};
 __export(credentials_exports, {
@@ -2137,6 +2568,12 @@ __export(credentials_exports, {
   ScryptPasswordHasher: () => ScryptPasswordHasher,
   validatePasswordPolicy: () => validatePasswordPolicy
 });
+
+// src/identity/index.ts
+var identity_exports = {};
+__export(identity_exports, {
+  SelfManagedIdentityProvider: () => SelfManagedIdentityProvider
+});
 export {
   AccountLinkingStrategy,
   AccountUnlinkError,
@@ -2147,6 +2584,8 @@ export {
   DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_STATE_MAX_AGE_SECONDS,
   EmailNotVerifiedError,
+  IdentityNotConfiguredError,
+  IdentityProviderError,
   InvalidCredentialsError,
   InvalidOAuthCallbackError,
   InvalidProviderConfigError,
@@ -2158,6 +2597,7 @@ export {
   ProviderNotConfiguredError,
   RefreshTokenError,
   ScryptPasswordHasher,
+  SelfManagedIdentityProvider,
   SessionNotFoundError,
   TokenExchangeError,
   UserAlreadyExistsError,
@@ -2172,6 +2612,7 @@ export {
   determineProviderFromIssuer,
   extractUserInfo,
   fetchUserInfo,
+  identity_exports as identity,
   isProductionEnvironment,
   serializeCookie,
   validatePasswordPolicy