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

package/dist/index.cjs

@@ -30,8 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AccountLinkingChallengeRequiredError: () => AccountLinkingChallengeRequiredError,
   AccountLinkingStrategy: () => AccountLinkingStrategy,
+  AccountNotVerifiedError: () => AccountNotVerifiedError,
   AccountUnlinkError: () => AccountUnlinkError,
+  CompositeIdentityProvider: () => CompositeIdentityProvider,
   CredentialsManager: () => CredentialsManager,
   CredentialsNotConfiguredError: () => CredentialsNotConfiguredError,
   DEFAULT_SESSION_COOKIE_NAME: () => DEFAULT_SESSION_COOKIE_NAME,
@@ -39,6 +42,8 @@ __export(src_exports, {
   DEFAULT_STATE_COOKIE_NAME: () => DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_STATE_MAX_AGE_SECONDS: () => DEFAULT_STATE_MAX_AGE_SECONDS,
   EmailNotVerifiedError: () => EmailNotVerifiedError,
+  IdentityNotConfiguredError: () => IdentityNotConfiguredError,
+  IdentityProviderError: () => IdentityProviderError,
   InvalidCredentialsError: () => InvalidCredentialsError,
   InvalidOAuthCallbackError: () => InvalidOAuthCallbackError,
   InvalidProviderConfigError: () => InvalidProviderConfigError,
@@ -49,7 +54,9 @@ __export(src_exports, {
   Pbkdf2PasswordHasher: () => Pbkdf2PasswordHasher,
   ProviderNotConfiguredError: () => ProviderNotConfiguredError,
   RefreshTokenError: () => RefreshTokenError,
+  SSOAccountAlreadyExistsError: () => SSOAccountAlreadyExistsError,
   ScryptPasswordHasher: () => ScryptPasswordHasher,
+  SelfManagedIdentityProvider: () => SelfManagedIdentityProvider,
   SessionNotFoundError: () => SessionNotFoundError,
   TokenExchangeError: () => TokenExchangeError,
   UserAlreadyExistsError: () => UserAlreadyExistsError,
@@ -64,6 +71,7 @@ __export(src_exports, {
   determineProviderFromIssuer: () => determineProviderFromIssuer,
   extractUserInfo: () => extractUserInfo,
   fetchUserInfo: () => fetchUserInfo,
+  identity: () => identity_exports,
   isProductionEnvironment: () => isProductionEnvironment,
   serializeCookie: () => serializeCookie,
   validatePasswordPolicy: () => validatePasswordPolicy
@@ -71,7 +79,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/lixa.ts
-var import_crypto4 = require("crypto");
+var import_crypto5 = require("crypto");
 
 // src/credentials/hasher.ts
 var import_crypto = __toESM(require("crypto"), 1);
@@ -453,10 +461,65 @@ 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);
+  }
+};
+var AccountLinkingChallengeRequiredError = class extends LixaError {
+  challengeToken;
+  email;
+  incomingProvider;
+  incomingProviderUserId;
+  existingUserId;
+  existingProviders;
+  hasPassword;
+  constructor(message, details) {
+    super(message, "ACCOUNT_LINKING_CHALLENGE_REQUIRED", details);
+    this.challengeToken = details.challengeToken;
+    this.email = details.email;
+    this.incomingProvider = details.incomingProvider;
+    this.incomingProviderUserId = details.incomingProviderUserId;
+    this.existingUserId = details.existingUserId;
+    this.existingProviders = details.existingProviders;
+    this.hasPassword = details.hasPassword;
+  }
+};
+var SSOAccountAlreadyExistsError = class extends LixaError {
+  existingProviders;
+  email;
+  constructor(email, existingProviders, details) {
+    super(
+      `An account with email '${email}' already exists via ${existingProviders.join(", ")}. Please sign in with your original provider and set a password in Settings.`,
+      "SSO_ACCOUNT_EXISTS",
+      { email, existingProviders, ...details }
+    );
+    this.email = email;
+    this.existingProviders = existingProviders;
+  }
+};
+var AccountNotVerifiedError = class extends LixaError {
+  constructor(identifier, details) {
+    super(
+      `Account${identifier ? ` '${identifier}'` : ""} has not been verified. Please confirm your account with the verification code sent to your email.`,
+      "ACCOUNT_NOT_VERIFIED",
+      { identifier, ...details }
+    );
+  }
+};
 
 // src/credentials/credentials-manager.ts
 var CredentialsManager = class {
@@ -620,6 +683,41 @@ var CredentialsManager = class {
     await this.storage.updatePassword(user.id, newHash);
     return true;
   }
+  /**
+   * Sets a password for a user who doesn't have one yet (e.g. SSO-first users),
+   * or updates an existing password without requiring the old one.
+   * This should only be called from an authenticated context (user already verified their identity via SSO).
+   * 
+   * @param params - userId and newPassword
+   * @returns True if password was successfully set
+   */
+  async setPassword(params) {
+    const policyResult = await validatePasswordPolicy(params.newPassword, this.policy);
+    if (!policyResult.valid) {
+      throw new WeakPasswordError(policyResult.errors);
+    }
+    const newHash = await this.hasher.hash(params.newPassword);
+    const existingUser = await this.storage.findUserById(params.userId);
+    if (existingUser) {
+      await this.storage.updatePassword(params.userId, newHash);
+      return true;
+    }
+    const now = Date.now();
+    const identifier = params.identifier || params.email || params.userId;
+    const normalized = this.normalizeIdentifier(identifier);
+    const isEmail = normalized.includes("@");
+    const user = {
+      id: params.userId,
+      identifier: normalized,
+      email: isEmail ? normalized : params.email?.trim().toLowerCase(),
+      username: !isEmail ? normalized : void 0,
+      passwordHash: newHash,
+      createdAt: now,
+      updatedAt: now
+    };
+    await this.storage.saveUser(user);
+    return true;
+  }
   /**
    * Finds a user by ID and returns safe user data.
    */
@@ -652,16 +750,394 @@ var CredentialsManager = class {
   }
 };
 
+// src/identity/self-managed.ts
+var import_crypto3 = __toESM(require("crypto"), 1);
+var SelfManagedIdentityProvider = class {
+  name = "self-managed";
+  manager;
+  pendingSignups = /* @__PURE__ */ new Map();
+  requireVerification;
+  config;
+  constructor(configOrManager) {
+    if (configOrManager instanceof CredentialsManager) {
+      this.manager = configOrManager;
+      this.config = {};
+      this.requireVerification = false;
+    } else {
+      this.config = configOrManager || {};
+      this.manager = new CredentialsManager(this.config);
+      this.requireVerification = this.config.requireVerification ?? false;
+    }
+  }
+  mapUser(user) {
+    return {
+      id: user.id,
+      identifier: user.identifier,
+      username: user.username,
+      email: user.email,
+      emailVerified: true,
+      createdAt: user.createdAt,
+      updatedAt: user.updatedAt,
+      metadata: user.metadata,
+      provider: this.name
+    };
+  }
+  generateConfirmationCode() {
+    return String(import_crypto3.default.randomInt(1e5, 999999));
+  }
+  /**
+   * Registers a new user with optional pending verification.
+   * When requireVerification is true, credentials are NOT persisted to the database until confirmSignUp() is called.
+   */
+  async signUp(params) {
+    if (!this.requireVerification) {
+      const user = await this.manager.signUp(params);
+      return this.mapUser(user);
+    }
+    const rawIdentifier = params.username || params.identifier || params.email || "";
+    const trimmed = (rawIdentifier || "").trim();
+    if (!trimmed) {
+      throw new InvalidCredentialsError("Identifier cannot be empty");
+    }
+    const identifierType = this.config.identifierType || "both";
+    if (identifierType === "email") {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!emailRegex.test(trimmed)) {
+        throw new InvalidCredentialsError("Identifier must be a valid email address");
+      }
+    }
+    const normalized = trimmed.toLowerCase();
+    const isEmail = normalized.includes("@");
+    const email = params.email ? params.email.trim().toLowerCase() : isEmail ? normalized : void 0;
+    const username = params.username ? params.username.trim() : !isEmail ? normalized : void 0;
+    if (this.config.requireUsername && (!username || username.trim() === "")) {
+      throw new InvalidCredentialsError("Username is required");
+    }
+    if (this.config.requireEmail && (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))) {
+      throw new InvalidCredentialsError("A valid email address is required");
+    }
+    const existing = await this.manager.getUserByIdentifier(normalized);
+    if (existing) {
+      throw new UserAlreadyExistsError(normalized);
+    }
+    const existingPending = this.pendingSignups.get(normalized);
+    if (existingPending && existingPending.expiresAt > Date.now()) {
+      throw new UserAlreadyExistsError(normalized);
+    }
+    const policy = { minLength: 8, maxLength: 128, ...this.config.policy };
+    const policyResult = await validatePasswordPolicy(params.password, policy);
+    if (!policyResult.valid) {
+      throw new WeakPasswordError(policyResult.errors);
+    }
+    const passwordHash = await this.manager.getHasher().hash(params.password);
+    const userId = typeof import_crypto3.default.randomUUID === "function" ? import_crypto3.default.randomUUID() : import_crypto3.default.randomBytes(16).toString("hex");
+    const confirmationCode = this.generateConfirmationCode();
+    const now = Date.now();
+    const pending = {
+      identifier: normalized,
+      email,
+      username,
+      passwordHash,
+      confirmationCode,
+      userId,
+      metadata: params.metadata,
+      createdAt: now,
+      expiresAt: now + 15 * 60 * 1e3
+      // 15 minutes TTL
+    };
+    this.pendingSignups.set(normalized, pending);
+    console.log(`[Lixa Self-Managed] Verification code for '${normalized}': ${confirmationCode}`);
+    return {
+      id: userId,
+      identifier: normalized,
+      username,
+      email,
+      emailVerified: false,
+      createdAt: now,
+      updatedAt: now,
+      metadata: {
+        ...params.metadata,
+        requiresVerification: true,
+        devConfirmationCode: confirmationCode
+      },
+      provider: this.name
+    };
+  }
+  /**
+   * Confirms a pending signup registration using the verification code.
+   * Only after successful confirmation is the user persisted to the database.
+   */
+  async confirmSignUp(params) {
+    const normalized = (params.identifier || "").trim().toLowerCase();
+    const pending = this.pendingSignups.get(normalized);
+    if (!pending) {
+      throw new InvalidCredentialsError("No pending registration found for this identifier. Please sign up first.");
+    }
+    if (pending.expiresAt < Date.now()) {
+      this.pendingSignups.delete(normalized);
+      throw new InvalidCredentialsError("Verification code has expired. Please sign up again.");
+    }
+    const code = (params.confirmationCode || "").trim();
+    if (code !== pending.confirmationCode) {
+      throw new InvalidCredentialsError("Invalid verification code.");
+    }
+    const storage = this.manager.getStorage();
+    const user = {
+      id: pending.userId,
+      identifier: pending.identifier,
+      email: pending.email,
+      username: pending.username,
+      passwordHash: pending.passwordHash,
+      createdAt: pending.createdAt,
+      updatedAt: Date.now(),
+      metadata: pending.metadata
+    };
+    await storage.saveUser(user);
+    this.pendingSignups.delete(normalized);
+    console.log(`[Lixa Self-Managed] User '${normalized}' verified and persisted to database.`);
+    return true;
+  }
+  /**
+   * Resends the verification code for a pending signup.
+   */
+  async resendConfirmationCode(params) {
+    const normalized = (params.identifier || "").trim().toLowerCase();
+    const pending = this.pendingSignups.get(normalized);
+    if (!pending) {
+      throw new InvalidCredentialsError("No pending registration found for this identifier.");
+    }
+    const newCode = this.generateConfirmationCode();
+    pending.confirmationCode = newCode;
+    pending.expiresAt = Date.now() + 15 * 60 * 1e3;
+    this.pendingSignups.set(normalized, pending);
+    console.log(`[Lixa Self-Managed] New verification code for '${normalized}': ${newCode}`);
+    return {
+      success: true,
+      deliveryMedium: "CONSOLE",
+      destination: pending.email || normalized
+    };
+  }
+  /**
+   * 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/identity/composite.ts
+var CompositeIdentityProvider = class {
+  name = "composite";
+  providers;
+  defaultProvider;
+  oauthProviders;
+  constructor(options) {
+    if (!options.providers || Object.keys(options.providers).length === 0) {
+      throw new IdentityProviderError(
+        "CompositeIdentityProvider requires at least one child provider in 'providers'",
+        this.name
+      );
+    }
+    this.providers = options.providers;
+    this.defaultProvider = options.defaultProvider;
+    this.oauthProviders = options.oauthProviders;
+    if (this.defaultProvider && !this.providers[this.defaultProvider]) {
+      throw new IdentityProviderError(
+        `Configured defaultProvider '${String(this.defaultProvider)}' does not exist in 'providers'. Available: ${Object.keys(this.providers).join(", ")}`,
+        this.name
+      );
+    }
+  }
+  /**
+   * Resolves the target child provider based on explicit parameter or defaultProvider.
+   * Throws an error immediately if the provider cannot be resolved or does not exist.
+   */
+  selectProvider(providerName) {
+    const targetKey = providerName || this.defaultProvider;
+    if (!targetKey) {
+      throw new IdentityProviderError(
+        `No provider specified and no defaultProvider configured in CompositeIdentityProvider. Available providers: ${Object.keys(this.providers).join(", ")}`,
+        this.name
+      );
+    }
+    const provider = this.providers[targetKey];
+    if (!provider) {
+      throw new IdentityProviderError(
+        `Provider '${targetKey}' is not configured in CompositeIdentityProvider. Available providers: ${Object.keys(this.providers).join(", ")}`,
+        this.name
+      );
+    }
+    return provider;
+  }
+  /**
+   * Returns all OAuth / OIDC provider configurations aggregated across this composite provider
+   * and any child providers exposing `getOAuthProviders()` or `getProviders()`.
+   */
+  getProviders() {
+    const result = {};
+    if (this.oauthProviders) {
+      Object.assign(result, this.oauthProviders);
+    }
+    for (const child of Object.values(this.providers)) {
+      if (typeof child.getOAuthProviders === "function") {
+        Object.assign(result, child.getOAuthProviders());
+      } else if (typeof child.getProviders === "function") {
+        Object.assign(result, child.getProviders());
+      }
+    }
+    return result;
+  }
+  async signUp(params) {
+    const provider = this.selectProvider(params.provider);
+    return provider.signUp(params);
+  }
+  async signIn(params) {
+    const provider = this.selectProvider(params.provider);
+    return provider.signIn(params);
+  }
+  async verifyCredentials(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.verifyCredentials === "function") {
+      return provider.verifyCredentials(params);
+    }
+    const result = await provider.signIn(params);
+    return result.user;
+  }
+  async changePassword(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.changePassword !== "function") {
+      throw new IdentityProviderError(
+        `Password change is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.changePassword(params);
+  }
+  async forgotPassword(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.forgotPassword !== "function") {
+      throw new IdentityProviderError(
+        `Password reset is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.forgotPassword(params);
+  }
+  async confirmPasswordReset(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.confirmPasswordReset !== "function") {
+      throw new IdentityProviderError(
+        `Confirm password reset is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.confirmPasswordReset(params);
+  }
+  async confirmSignUp(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.confirmSignUp !== "function") {
+      throw new IdentityProviderError(
+        `Account confirmation is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.confirmSignUp(params);
+  }
+  async resendConfirmationCode(params) {
+    const provider = this.selectProvider(params.provider);
+    if (typeof provider.resendConfirmationCode !== "function") {
+      throw new IdentityProviderError(
+        `Resending confirmation code is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.resendConfirmationCode(params);
+  }
+  async getUserById(id, providerName) {
+    const provider = this.selectProvider(providerName);
+    if (typeof provider.getUserById !== "function") {
+      return null;
+    }
+    return provider.getUserById(id);
+  }
+  async getUserByIdentifier(identifier, providerName) {
+    const provider = this.selectProvider(providerName);
+    if (typeof provider.getUserByIdentifier !== "function") {
+      return null;
+    }
+    return provider.getUserByIdentifier(identifier);
+  }
+  async deleteUser(id, providerName) {
+    const provider = this.selectProvider(providerName);
+    if (typeof provider.deleteUser !== "function") {
+      throw new IdentityProviderError(
+        `User deletion is not supported by provider '${provider.name}'`,
+        this.name
+      );
+    }
+    return provider.deleteUser(id);
+  }
+};
+
 // src/types.ts
 var AccountLinkingStrategy = /* @__PURE__ */ ((AccountLinkingStrategy2) => {
   AccountLinkingStrategy2["AUTO_LINK_BY_VERIFIED_EMAIL"] = "AUTO_LINK_BY_VERIFIED_EMAIL";
   AccountLinkingStrategy2["ISOLATED"] = "ISOLATED";
+  AccountLinkingStrategy2["STEP_UP_VERIFICATION"] = "STEP_UP_VERIFICATION";
   return AccountLinkingStrategy2;
 })(AccountLinkingStrategy || {});
 
 // src/dao/state-cache.ts
 var import_node_cache = __toESM(require("node-cache"), 1);
-var import_crypto3 = require("crypto");
+var import_crypto4 = require("crypto");
 var LocalStateHandler = class {
   cache;
   stateStorage;
@@ -681,8 +1157,8 @@ var LocalStateHandler = class {
   }
   // Default generateState implementation
   async generateState(provider) {
-    const state = (0, import_crypto3.randomBytes)(16).toString("hex");
-    const codeVerifier = (0, import_crypto3.randomBytes)(32).toString("hex");
+    const state = (0, import_crypto4.randomBytes)(16).toString("hex");
+    const codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
     return {
       state,
       data: {
@@ -699,7 +1175,7 @@ var LocalStateHandler = class {
 };
 
 // src/lixa.ts
-var import_crypto5 = __toESM(require("crypto"), 1);
+var import_crypto6 = __toESM(require("crypto"), 1);
 
 // src/dao/session-cache.ts
 var import_node_cache2 = __toESM(require("node-cache"), 1);
@@ -757,10 +1233,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
@@ -821,7 +1294,7 @@ async function fetchUserInfo(accessToken, userInfoEndpoint) {
     family_name: "family_name" in data ? String(data.family_name) : void 0,
     name: "name" in data ? String(data.name) : void 0,
     picture: "picture" in data ? String(data.picture) : void 0,
-    email_verified: "email_verified" in data ? Boolean(data.email_verified) : void 0,
+    email_verified: "email_verified" in data ? data.email_verified === true || data.email_verified === "true" : void 0,
     iss: "iss" in data ? String(data.iss) : void 0
   };
 }
@@ -829,68 +1302,213 @@ async function extractUserInfo(tokenData, providerMetadata) {
   let userInfo;
   const userInfoEndpoint = providerMetadata.endpoints.userInfo;
   if (tokenData.id_token) {
-    userInfo = decodeIdToken(tokenData.id_token);
-  } else if (tokenData.access_token) {
+    try {
+      userInfo = decodeIdToken(tokenData.id_token);
+      if (userInfo && userInfo.email_verified !== void 0) {
+        userInfo.email_verified = userInfo.email_verified === true || userInfo.email_verified === "true";
+      }
+    } catch {
+    }
+  }
+  if ((!userInfo || !userInfo.email) && tokenData.access_token && userInfoEndpoint) {
+    try {
+      const fetched = await fetchUserInfo(tokenData.access_token, userInfoEndpoint);
+      userInfo = { ...fetched, ...userInfo || {}, email: fetched.email || userInfo?.email || "" };
+      if (fetched.email_verified !== void 0 && (userInfo.email_verified === void 0 || userInfo.email_verified === false)) {
+        userInfo.email_verified = fetched.email_verified === true || fetched.email_verified === "true";
+      }
+    } catch {
+    }
+  } else if (!userInfo && tokenData.access_token && userInfoEndpoint) {
     userInfo = await fetchUserInfo(tokenData.access_token, userInfoEndpoint);
-  } else {
+  }
+  if (!userInfo) {
     throw new Error("No ID token or access token available to fetch user info");
   }
   return { userInfo };
 }
 
-// src/lixa.ts
-var Lixa = class _Lixa {
-  static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
-  static CONFIGURED_PROVIDERS = /* @__PURE__ */ new Map();
-  // Legacy registry for backward compatibility
-  // Instance-scoped fallback handlers to ensure no cross-instance state pollution
-  localStateHandler;
-  localSessionHandler;
-  localResourceHandler;
-  userResourceStore = /* @__PURE__ */ new Map();
-  refreshMutexes = /* @__PURE__ */ new Map();
-  credentialsManager;
-  config;
-  stateHandler;
-  sessionHandler;
-  resourceHandler;
-  debug;
-  /**
-   * Creates a new Lixa instance with the provided configuration.
-   * 
-   * @remarks
-   * Providers can be passed inline in the configuration using the `provider` field.
-   * Provider resolution priority: inline custom provider \> default providers \> legacy registry.
-   * 
-   * @param config - The configuration object containing provider settings and optional session strategy
-   * 
-   * @throws Error when provider configuration is missing required fields
-   * @throws Error when provider implementation is missing required properties
-   * @throws Error when provider is not available and no inline implementation is provided
-   */
-  constructor(config) {
-    this.config = config;
-    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) {
+// 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();
+  static CONFIGURED_PROVIDERS = /* @__PURE__ */ new Map();
+  // Legacy registry for backward compatibility
+  // Instance-scoped fallback handlers to ensure no cross-instance state pollution
+  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.
+   * 
+   * @remarks
+   * Providers can be passed inline in the configuration using the `provider` field.
+   * Provider resolution priority: inline custom provider \> default providers \> legacy registry.
+   * 
+   * @param config - The configuration object containing provider settings and optional session strategy
+   * 
+   * @throws Error when provider configuration is missing required fields
+   * @throws Error when provider implementation is missing required properties
+   * @throws Error when provider is not available and no inline implementation is provided
+   */
+  constructor(config) {
+    this.sessionCookieResolver = config.sessionCookieName;
+    this.config = {
+      ...config,
+      ...config.providers ? { providers: config.providers } : {}
+    };
+    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;
             }
@@ -905,19 +1523,84 @@ 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 ? { stateStorage: storage.stateStorage } : this.localStateHandler);
+    this.sessionHandler = config.sessionHandler || (storage?.sessionStorage ? { sessionStorage: 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 if (this.identityProvider instanceof CompositeIdentityProvider) {
+          for (const child of Object.values(this.identityProvider.providers)) {
+            if (child instanceof SelfManagedIdentityProvider) {
+              this.credentialsManager = child.getCredentialsManager();
+              break;
+            }
+          }
+        }
+      } 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();
+    }
+    if (this.identityProvider && typeof this.identityProvider.getProviders === "function") {
+      const idpOAuthProviders = this.identityProvider.getProviders();
+      this.config.providers = {
+        ...idpOAuthProviders,
+        ...this.config.providers || {}
+      };
+    }
+    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);
@@ -946,7 +1629,22 @@ var Lixa = class _Lixa {
    * @throws InvalidProviderConfigError when required fields are missing or invalid
    */
   validateProviderConfig(name, config) {
-    const requiredFields = ["clientId", "clientSecret", "redirectUri", "scopes"];
+    const hasScopes = Array.isArray(config.scopes) && config.scopes.length > 0 || config.scopes && typeof config.scopes === "object" && !Array.isArray(config.scopes) && (config.scopes.auth && config.scopes.auth.length > 0 || config.scopes.resource && config.scopes.resource.length > 0) || config.authScopes && config.authScopes.length > 0 || config.resourceScopes && config.resourceScopes.length > 0;
+    if (!hasScopes) {
+      const p = config.provider;
+      if (p?.defaultScopes && Array.isArray(p.defaultScopes) && p.defaultScopes.length > 0) {
+        config.scopes = { auth: [...p.defaultScopes] };
+      } else if (p?.authScopes && Array.isArray(p.authScopes) && p.authScopes.length > 0) {
+        config.scopes = { auth: [...p.authScopes] };
+      } else if (name === "google" || name.startsWith("google")) {
+        config.scopes = { auth: ["openid", "profile", "email"] };
+      } else if (name === "github" || name.startsWith("github")) {
+        config.scopes = { auth: ["read:user", "user:email"] };
+      } else if (name.startsWith("cognito")) {
+        config.scopes = { auth: ["openid", "email", "profile"] };
+      }
+    }
+    const requiredFields = ["clientId", "clientSecret", "redirectUri"];
     const missingFields = requiredFields.filter((field) => {
       const value = config[field];
       return value === void 0 || value === null || typeof value === "string" && value.trim() === "";
@@ -957,16 +1655,33 @@ var Lixa = class _Lixa {
         { provider: name, missingFields }
       );
     }
-    if (!Array.isArray(config.scopes)) {
-      throw new InvalidProviderConfigError(
-        `Provider '${name}' configuration error: 'scopes' must be an array of strings`,
-        { provider: name }
-      );
-    }
-    if (config.scopes.length === 0) {
+    if (config.scopes) {
+      if (Array.isArray(config.scopes)) {
+        if (config.scopes.length === 0) {
+          throw new InvalidProviderConfigError(
+            `Provider '${name}' configuration error: 'scopes' array cannot be empty`,
+            { provider: name }
+          );
+        }
+      } else if (typeof config.scopes === "object") {
+        const hasAuth = Array.isArray(config.scopes.auth) && config.scopes.auth.length > 0;
+        const hasResource = Array.isArray(config.scopes.resource) && config.scopes.resource.length > 0;
+        if (!hasAuth && !hasResource) {
+          throw new InvalidProviderConfigError(
+            `Provider '${name}' configuration error: 'scopes' object must specify non-empty 'auth' or 'resource' array`,
+            { provider: name }
+          );
+        }
+      } else {
+        throw new InvalidProviderConfigError(
+          `Provider '${name}' configuration error: 'scopes' must be an array of strings or { auth?: string[]; resource?: string[] }`,
+          { provider: name }
+        );
+      }
+    } else if (!config.authScopes && !config.resourceScopes) {
       throw new InvalidProviderConfigError(
-        `Provider '${name}' configuration error: 'scopes' array cannot be empty`,
-        { provider: name }
+        `Provider '${name}' configuration is missing required fields: scopes`,
+        { provider: name, missingFields: ["scopes"] }
       );
     }
   }
@@ -1139,7 +1854,7 @@ var Lixa = class _Lixa {
    * The state parameter is used to prevent CSRF attacks in OAuth flows.
    */
   static generateRandomState() {
-    return (0, import_crypto4.randomBytes)(16).toString("hex");
+    return (0, import_crypto5.randomBytes)(16).toString("hex");
   }
   /**
    * Generates a cryptographically secure code verifier for PKCE flows.
@@ -1176,7 +1891,7 @@ var Lixa = class _Lixa {
    * @internal
    */
   static generateCodeVerifier() {
-    return (0, import_crypto4.randomBytes)(32).toString("hex");
+    return (0, import_crypto5.randomBytes)(32).toString("hex");
   }
   /**
    * Generates a code challenge from a code verifier for PKCE flows.
@@ -1222,7 +1937,7 @@ var Lixa = class _Lixa {
    * @internal
    */
   static buildCodeChallenge(codeVerifier) {
-    const hash = import_crypto5.default.createHash("sha256").update(codeVerifier).digest("base64");
+    const hash = import_crypto6.default.createHash("sha256").update(codeVerifier).digest("base64");
     return hash.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
   }
   /**
@@ -1264,8 +1979,8 @@ var Lixa = class _Lixa {
       await storage.saveState(stateValue, generated.data, 300);
     } else {
       this.log("INFO", "State", "Using default state generation");
-      stateValue = state || (0, import_crypto4.randomBytes)(16).toString("hex");
-      codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
+      stateValue = state || (0, import_crypto5.randomBytes)(16).toString("hex");
+      codeVerifier = (0, import_crypto5.randomBytes)(32).toString("hex");
       const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       await storage.saveState(
         stateValue,
@@ -1280,12 +1995,17 @@ var Lixa = class _Lixa {
     }
     const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
     this.log("INFO", "State", `Saved state for provider: ${providerType}`, { state: stateValue });
+    const rawAuthScopes = providerConfig.authScopes || (Array.isArray(providerConfig.scopes) ? providerConfig.scopes : providerConfig.scopes?.auth) || [];
     const authNScopes = this.resolveAuthNScopes(
       providerType,
-      providerConfig.scopes,
+      rawAuthScopes,
       providerImpl,
       providerConfig.allowNonAuthScopes
     );
+    const authorizationParams = {
+      ...providerConfig.extraConfig || {},
+      ...providerConfig.authorizationParams || {}
+    };
     const params = new URLSearchParams({
       client_id: providerConfig.clientId,
       redirect_uri: providerConfig.redirectUri,
@@ -1294,7 +2014,7 @@ var Lixa = class _Lixa {
       response_type: "code",
       code_challenge: codeChallenge,
       code_challenge_method: "S256",
-      ...providerConfig.extraConfig
+      ...authorizationParams
     });
     const authUrl = `${providerImpl.authorizationEndpoint}?${params.toString()}`;
     this.log("INFO", "Auth", `Authorization URL generated successfully`, {
@@ -1368,7 +2088,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}`);
@@ -1432,53 +2153,156 @@ var Lixa = class _Lixa {
     }
     const session = await generateSession(tokens, providerMetadata);
     session.provider = session.provider || providerType;
+    session.token = session.token || tokens.access_token;
+    session.raw = session.raw || tokens;
+    if (extractedUserInfo?.sub && !session.userId) {
+      session.userId = extractedUserInfo.sub;
+    } else if (extractedUserInfo?.id && !session.userId) {
+      session.userId = String(extractedUserInfo.id);
+    }
     if (extractedUserInfo?.email && !session.email) {
       session.email = extractedUserInfo.email;
     }
     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 isStepUpMode = linkingConfig === "STEP_UP_VERIFICATION" || linkingConfig === "STEP_UP_VERIFICATION" /* STEP_UP_VERIFICATION */ || mode === "STEP_UP_VERIFICATION" || mode === "STEP_UP_VERIFICATION" /* STEP_UP_VERIFICATION */ || mode === "stepUp";
     const email = extractedUserInfo?.email;
-    const isVerified = extractedUserInfo?.email_verified !== false;
-    const requireVerified = linkingConfig?.requireVerifiedEmail ?? true;
-    const canLink = isLinkByEmail && email && (!requireVerified || isVerified);
+    const isVerified = extractedUserInfo?.email_verified === true;
+    const requireVerified = typeof linkingConfig === "object" ? linkingConfig?.requireVerifiedEmail ?? true : true;
+    const canLink = (isLinkByEmail || isStepUpMode) && email && (!requireVerified || isVerified);
+    if ((isLinkByEmail || isStepUpMode) && email && !isVerified && requireVerified) {
+      this.log("WARN", "AccountLinking", `Rejected account linking for provider '${providerType}': email '${email}' is not cryptographically verified by the provider.`);
+    }
+    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,
+          linkedAt: Date.now()
+        };
+        if (this.accountHandler?.accountStorage) {
+          const userKey = this.getUserKeyFromSession(activeSession);
+          await this.accountHandler.accountStorage.saveAccount(userKey, providerType, this.sanitizeIdentityForStorage(linkedAcc2));
+        }
+        return sessionId;
+      }
+    }
+    if (canLink) {
+      const existingAccounts = this.accountHandler?.accountStorage?.findAccountsByEmail ? await this.accountHandler.accountStorage.findAccountsByEmail(email) : [];
+      const existingSessionRecord = sessionStorage.getSessionByEmail ? await sessionStorage.getSessionByEmail(email) : null;
+      const existingProviders = /* @__PURE__ */ new Set();
+      let existingUserId;
+      if (existingSessionRecord) {
+        existingUserId = existingSessionRecord.session.userId || existingSessionRecord.session.email;
+        if (existingSessionRecord.session.provider) {
+          existingProviders.add(existingSessionRecord.session.provider.toLowerCase());
+        }
+        if (existingSessionRecord.session.accounts) {
+          Object.keys(existingSessionRecord.session.accounts).forEach(
+            (p) => existingProviders.add(p.toLowerCase())
+          );
+        }
+      }
+      for (const acc of existingAccounts) {
+        if (!existingUserId) existingUserId = acc.userId;
+        existingProviders.add(acc.provider.toLowerCase());
+      }
+      if (existingProviders.size > 0 && !existingProviders.has(providerType.toLowerCase())) {
+        if (isStepUpMode) {
+          let hasPassword = existingProviders.has("credentials") || existingProviders.has("self-managed") || existingProviders.has("cognito");
+          if (!hasPassword && this.credentialsManager) {
+            try {
+              const credUser = await this.credentialsManager.getUserByIdentifier(email);
+              if (credUser) {
+                hasPassword = true;
+              }
+            } catch {
+            }
+          }
+          const challengeToken = (0, import_crypto5.randomBytes)(24).toString("hex");
+          const stateStorage2 = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
+          await stateStorage2.saveState(
+            `linking_challenge:${challengeToken}`,
+            {
+              provider: providerType,
+              codeVerifier: "",
+              createdAt: Date.now(),
+              challengeToken,
+              email,
+              incomingProvider: providerType,
+              incomingProviderUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+              existingUserId: existingUserId || email,
+              existingProviders: Array.from(existingProviders),
+              hasPassword,
+              tokens
+            },
+            600
+          );
+          this.log(
+            "WARN",
+            "AccountLinking",
+            `Step-up challenge required for user '${email}'. Existing: [${Array.from(existingProviders).join(
+              ", "
+            )}], Incoming: '${providerType}'`
+          );
+          throw new AccountLinkingChallengeRequiredError(
+            `An account with email '${email}' already exists. Verification required before linking.`,
+            {
+              challengeToken,
+              email,
+              incomingProvider: providerType,
+              incomingProviderUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
+              existingUserId: existingUserId || email,
+              existingProviders: Array.from(existingProviders),
+              hasPassword
+            }
+          );
+        }
+      }
+    }
     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,
-          accessToken: tokens.access_token,
-          raw: tokens,
           linkedAt: Date.now()
         };
         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, this.sanitizeIdentityForStorage(linkedAcc2));
+        }
         return existingSessionId;
       }
     }
-    session.accounts = session.accounts || {};
-    session.accounts[providerType] = {
+    const linkedAcc = {
       provider: providerType,
       providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
       email: extractedUserInfo?.email,
-      accessToken: tokens.access_token,
-      raw: tokens,
       linkedAt: Date.now()
     };
-    const sessionId = (0, import_crypto4.randomBytes)(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;
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(session);
+      await this.accountHandler.accountStorage.saveAccount(userKey, providerType, this.sanitizeIdentityForStorage(linkedAcc));
+    }
+    const newSessionId = (0, import_crypto5.randomBytes)(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.
@@ -1527,19 +2351,28 @@ var Lixa = class _Lixa {
       extractedUserInfo = userInfo;
     } catch {
     }
-    existingSession.accounts = existingSession.accounts || {};
-    existingSession.accounts[providerType] = {
+    const linkedAcc = {
       provider: providerType,
       providerUserId: extractedUserInfo?.sub || extractedUserInfo?.id,
       email: extractedUserInfo?.email,
-      accessToken: tokens.access_token,
-      raw: tokens,
       linkedAt: Date.now()
     };
     if (extractedUserInfo?.email && !existingSession.email) {
       existingSession.email = extractedUserInfo.email;
+      await sessionStorage.saveSession(sessionId, existingSession, 86400);
+    }
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(existingSession);
+      await this.accountHandler.accountStorage.saveAccount(
+        userKey,
+        providerType,
+        this.sanitizeIdentityForStorage(linkedAcc)
+      );
     }
-    await sessionStorage.saveSession(sessionId, existingSession, 86400);
+    this.log("INFO", "AccountLinking", `Linked provider '${providerType}' directly to session '${sessionId}'`, {
+      provider: providerType,
+      sessionId
+    });
     return sessionId;
   }
   /**
@@ -1552,46 +2385,203 @@ var Lixa = class _Lixa {
   async unlinkAccount(sessionId, providerToUnlink) {
     const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
     const session = await sessionStorage.getSession(sessionId);
-    if (!session || !session.accounts) {
-      throw new AccountUnlinkError("Session not found or has no linked accounts.", { sessionId });
+    if (!session) {
+      throw new AccountUnlinkError("Session not found.", { sessionId });
+    }
+    const providerKey = providerToUnlink.toLowerCase();
+    const userKey = this.getUserKeyFromSession(session);
+    let allAccounts = {};
+    if (this.accountHandler?.accountStorage) {
+      allAccounts = await this.accountHandler.accountStorage.getUserAccounts(userKey) || {};
+    }
+    if (!allAccounts[providerKey]) {
+      throw new AccountUnlinkError(`Provider '${providerToUnlink}' is not linked to this account.`, {
+        sessionId,
+        provider: providerToUnlink
+      });
     }
-    const linkedProviders = Object.keys(session.accounts);
+    const linkedProviders = Object.keys(allAccounts);
     if (linkedProviders.length <= 1) {
       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);
+    if (this.accountHandler?.accountStorage) {
+      await this.accountHandler.accountStorage.deleteAccount(userKey, providerKey);
+    }
+    if (session.provider?.toLowerCase() === providerKey) {
+      const remaining = linkedProviders.filter((p) => p !== providerKey);
+      session.provider = remaining.length > 0 ? remaining[0] : void 0;
+      await sessionStorage.saveSession(sessionId, session, 86400);
+    }
+    this.log("INFO", "AccountLinking", `Unlinked provider '${providerKey}' for user '${session.userId || session.email}'`, {
+      sessionId,
+      provider: providerKey
+    });
     return true;
   }
   /**
-   * Generates an authorization URL for connecting a resource provider (AuthZ) post-login.
-   * 
-   * @remarks
-   * Resource authorization is kept strictly separate from primary authentication (AuthN).
-   * Call this method after a user is authenticated to request permissions for external API access
-   * (e.g. GitHub repositories, Google Drive, Slack, etc.).
+   * Confirms a pending account linking step-up challenge using the user's password.
+   * On successful verification, links the pending provider to the existing account and creates a session.
    * 
-   * @param params - Object containing sessionId, provider, requested resource scopes, and optional state
-   * @returns The authorization URL for resource consent
+   * @param params - challengeToken and password
+   * @returns Session ID, Session, and User identity
+   * @throws InvalidStateError if challenge is invalid or expired
+   * @throws InvalidCredentialsError if password verification fails
    */
-  async getResourceAuthUrl(params) {
-    const { sessionId, provider, scopes, state, prompt, extraConfig } = params;
-    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
-    const activeSession = await sessionStorage.getSession(sessionId);
-    if (!activeSession) {
-      throw new SessionNotFoundError("Authentication required. Active session must exist to connect resource providers.", { sessionId });
-    }
+  async confirmLinkingWithPassword(params) {
+    const { challengeToken, password } = params;
+    const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
+    const stateKey = `linking_challenge:${challengeToken}`;
+    const cached = await stateStorage.getState(stateKey);
+    if (!cached || !cached.challengeToken) {
+      throw new InvalidStateError("Invalid or expired account linking challenge.");
+    }
+    let verifiedUser = null;
+    let passwordTokens = void 0;
+    if (this.identityProvider) {
+      try {
+        const signInResult = await this.identityProvider.signIn({
+          identifier: cached.email,
+          password
+        });
+        verifiedUser = signInResult.user;
+        passwordTokens = signInResult.tokens;
+      } catch {
+        verifiedUser = await this.verifyCredentials({
+          identifier: cached.email,
+          password
+        });
+      }
+    } else {
+      verifiedUser = await this.verifyCredentials({
+        identifier: cached.email,
+        password
+      });
+    }
+    if (!verifiedUser) {
+      throw new InvalidCredentialsError("Invalid password for account linking verification.");
+    }
+    await stateStorage.deleteState(stateKey);
+    const providerType = String(cached.incomingProvider).toLowerCase();
+    const incomingTokens = cached.tokens;
+    const linkedAcc = {
+      provider: providerType,
+      providerUserId: cached.incomingProviderUserId,
+      email: cached.email,
+      linkedAt: Date.now()
+    };
+    if (this.accountHandler?.accountStorage) {
+      await this.accountHandler.accountStorage.saveAccount(
+        cached.existingUserId,
+        providerType,
+        this.sanitizeIdentityForStorage(linkedAcc)
+      );
+    }
+    const passwordProviderName = verifiedUser && verifiedUser.provider || (this.identityProvider instanceof CompositeIdentityProvider ? this.identityProvider.defaultProvider : this.identityProvider?.name) || "credentials";
+    const passwordAccountKey = passwordProviderName === "self-managed" ? "credentials" : passwordProviderName;
+    if (this.accountHandler?.accountStorage) {
+      await this.accountHandler.accountStorage.saveAccount(
+        cached.existingUserId,
+        passwordAccountKey,
+        this.sanitizeIdentityForStorage({
+          provider: passwordAccountKey,
+          providerUserId: verifiedUser.id,
+          email: verifiedUser.email,
+          linkedAt: Date.now()
+        })
+      );
+    }
+    const sessionId = (0, import_crypto5.randomBytes)(32).toString("hex");
+    const session = {
+      sessionId,
+      userId: cached.existingUserId,
+      email: cached.email,
+      provider: providerType,
+      token: incomingTokens?.access_token,
+      raw: incomingTokens
+    };
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
+    await sessionStorage.saveSession(sessionId, session, 86400);
+    this.log(
+      "INFO",
+      "AccountLinking",
+      `Successfully linked '${providerType}' to user '${cached.existingUserId}' via password step-up.`
+    );
+    return { sessionId, session, user: verifiedUser };
+  }
+  /**
+   * Sets a password for an SSO-authenticated user who doesn't have one yet.
+   * Must be called from an authenticated context (user has active session proving identity).
+   * 
+   * @param params - userId, newPassword, optional identifier and email
+   * @returns True if password was set successfully
+   * @throws IdentityNotConfiguredError if no identity provider configured
+   * @throws WeakPasswordError if password doesn't meet policy
+   */
+  async setPassword(params) {
+    this.log("INFO", "Identity", "Processing setPassword request", { userId: params.userId });
+    if (this.credentialsManager) {
+      const result = await this.credentialsManager.setPassword(params);
+      if (result && this.accountHandler?.accountStorage) {
+        const providerName = this.identityProvider?.name === "self-managed" ? "credentials" : this.identityProvider?.name || "credentials";
+        const credentialsAccount = {
+          provider: providerName,
+          providerUserId: params.userId,
+          email: params.email,
+          linkedAt: Date.now()
+        };
+        await this.accountHandler.accountStorage.saveAccount(
+          params.userId,
+          providerName,
+          this.sanitizeIdentityForStorage(credentialsAccount)
+        );
+      }
+      this.log("INFO", "Identity", "Password set successfully", { userId: params.userId });
+      return result;
+    }
+    if (this.identityProvider && typeof this.identityProvider.changePassword === "function") {
+      throw new IdentityProviderError(
+        "Setting a password for SSO users is only supported with self-managed credentials. Use the provider's admin console instead.",
+        this.identityProvider.name
+      );
+    }
+    throw new CredentialsNotConfiguredError(
+      "Cannot set password: No credentials manager is configured on this Lixa instance."
+    );
+  }
+  /**
+   * Generates an authorization URL for connecting a resource provider (AuthZ) post-login.
+   * 
+   * @remarks
+   * Resource authorization is kept strictly separate from primary authentication (AuthN).
+   * Call this method after a user is authenticated to request permissions for external API access
+   * (e.g. GitHub repositories, Google Drive, Slack, etc.).
+   * 
+   * @param params - Object containing sessionId, provider, requested resource scopes, and optional state
+   * @returns The authorization URL for resource consent
+   */
+  async getResourceAuthUrl(params) {
+    const { sessionId, provider, state, prompt, extraConfig, authorizationParams } = params;
+    const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
+    const activeSession = await sessionStorage.getSession(sessionId);
+    if (!activeSession) {
+      throw new SessionNotFoundError("Authentication required. Active session must exist to connect resource providers.", { sessionId });
+    }
     const providerType = String(provider).toLowerCase();
     const providerConfig = this.findProviderByType(providerType);
     if (!providerConfig) {
       throw new ProviderNotConfiguredError(String(provider));
     }
+    const defaultResourceScopes = providerConfig.resourceScopes || (Array.isArray(providerConfig.scopes) ? void 0 : providerConfig.scopes?.resource) || [];
+    const requestedScopes = params.scopes && params.scopes.length > 0 ? params.scopes : defaultResourceScopes;
+    if (requestedScopes.length === 0) {
+      throw new Error(`No scopes specified for resource '${provider}'. Provide scopes in getResourceAuthUrl() or configure 'scopes.resource' / 'resourceScopes' on the provider.`);
+    }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    const stateValue = state || (0, import_crypto4.randomBytes)(16).toString("hex");
-    const codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
+    const stateValue = state || (0, import_crypto5.randomBytes)(16).toString("hex");
+    const codeVerifier = (0, import_crypto5.randomBytes)(32).toString("hex");
     const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
     await storage.saveState(
       stateValue,
@@ -1603,22 +2593,35 @@ var Lixa = class _Lixa {
       300
     );
     const codeChallenge = _Lixa.buildCodeChallenge(codeVerifier);
+    const mergedAuthParams = {
+      ...providerConfig.extraConfig || {},
+      ...providerConfig.authorizationParams || {},
+      ...extraConfig || {},
+      ...authorizationParams || {}
+    };
     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,
       code_challenge_method: "S256",
       ...prompt ? { prompt } : {},
-      ...providerConfig.extraConfig,
-      ...extraConfig
+      ...mergedAuthParams
     });
     return `${providerImpl.authorizationEndpoint}?${searchParams.toString()}`;
   }
   getUserKeyFromSession(session) {
-    return session.userId || session.email || session.id || "anonymous";
+    return session.userId || session.email || session.sessionId || "anonymous";
+  }
+  sanitizeIdentityForStorage(account) {
+    return {
+      provider: account.provider,
+      providerUserId: account.providerUserId,
+      email: account.email,
+      linkedAt: account.linkedAt || Date.now()
+    };
   }
   /**
    * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
@@ -1636,7 +2639,7 @@ var Lixa = class _Lixa {
       throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    let codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
+    let codeVerifier = (0, import_crypto5.randomBytes)(32).toString("hex");
     if (state) {
       const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       const cachedState = await stateStorage.getState(state);
@@ -1648,12 +2651,14 @@ 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 defaultResourceScopes = providerConfig.resourceScopes || (Array.isArray(providerConfig.scopes) ? void 0 : providerConfig.scopes?.resource) || [];
+    const effectiveScopes = scopes || (tokens.scope ? tokens.scope.split(" ") : defaultResourceScopes);
     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()
     };
@@ -1665,6 +2670,45 @@ 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());
+    if (!providerConfig) return void 0;
+    if (providerConfig.resourceScopes) return providerConfig.resourceScopes;
+    if (providerConfig.scopes && !Array.isArray(providerConfig.scopes)) {
+      return providerConfig.scopes.resource;
+    }
+    return void 0;
+  }
+  /**
+   * 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.
@@ -1845,7 +2889,32 @@ 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 (session.accounts) {
+      delete session.accounts;
+    }
+    return session;
+  }
+  /**
+   * Retrieves all linked accounts for a user from account storage.
+   * 
+   * @param userIdOrSessionId - User ID, email, or active session ID
+   * @returns Record mapping provider name to linked account metadata
+   */
+  async getUserAccounts(userIdOrSessionId) {
+    let userKey = userIdOrSessionId;
+    if (this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage) {
+      const sessionStorage = this.sessionHandler.sessionStorage || this.localSessionHandler.sessionStorage;
+      const session = await sessionStorage.getSession(userIdOrSessionId);
+      if (session) {
+        userKey = this.getUserKeyFromSession(session);
+      }
+    }
+    if (this.accountHandler?.accountStorage) {
+      return await this.accountHandler.accountStorage.getUserAccounts(userKey) || {};
+    }
+    return {};
   }
   /**
    * Deletes a session from session storage (e.g. on logout).
@@ -1896,117 +2965,178 @@ 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 underlying CredentialsManager instance if configured.
+   * 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 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();
+    }
+    const rawProviderName = params.provider || this.identityProvider.name;
+    const providerName = rawProviderName === "self-managed" ? "credentials" : rawProviderName;
+    this.log("INFO", "Identity", `Processing signUp request via ${providerName}`, { identifier: params.identifier });
+    const signUpEmail = params.email || (params.identifier?.includes("@") ? params.identifier : void 0);
+    if (signUpEmail && this.accountHandler?.accountStorage?.findAccountsByEmail) {
+      const normalizedEmail = signUpEmail.trim().toLowerCase();
+      const existingAccounts = await this.accountHandler.accountStorage.findAccountsByEmail(normalizedEmail);
+      if (existingAccounts.length > 0) {
+        const existingProviderNames = existingAccounts.map((a) => a.provider);
+        const hasCredentials = existingProviderNames.some(
+          (p) => p === "credentials" || p === "self-managed" || p === "cognito"
+        );
+        if (!hasCredentials) {
+          this.log("WARN", "Identity", `SignUp blocked: SSO account already exists for '${normalizedEmail}' via [${existingProviderNames.join(", ")}]`);
+          throw new SSOAccountAlreadyExistsError(normalizedEmail, existingProviderNames);
+        }
+      }
+    }
+    const user = await this.identityProvider.signUp(params);
+    const isVerificationRequired = user.metadata?.requiresVerification === true || user.emailVerified === false && (user.metadata?.devConfirmationCode !== void 0 || this.identityProvider.name === "self-managed" || this.identityProvider.name === "cognito");
+    if (isVerificationRequired) {
+      this.log("INFO", "Identity", "SignUp requires verification \u2014 no session created", {
+        identifier: user.identifier,
+        email: user.email
+      });
+      return {
+        user,
+        requiresVerification: true,
+        devConfirmationCode: user.metadata?.devConfirmationCode
+      };
     }
-    this.log("INFO", "Credentials", "Processing signUp request", { identifier: params.identifier });
-    const user = await this.credentialsManager.signUp(params);
     const autoSession = this.config.credentials?.autoCreateSessionOnSignUp ?? true;
     if (!autoSession) {
       return { user };
     }
-    const sessionId = (0, import_crypto4.randomBytes)(16).toString("hex");
-    const token = (0, import_crypto4.randomBytes)(32).toString("hex");
+    const sessionId = (0, import_crypto5.randomBytes)(16).toString("hex");
+    const token = (0, import_crypto5.randomBytes)(32).toString("hex");
     const ttl = this.config.credentials?.sessionTtlSeconds ?? 86400;
+    const activeProviderName = params.provider || user && user.provider || (this.identityProvider instanceof CompositeIdentityProvider ? this.identityProvider.defaultProvider : this.identityProvider.name);
+    const accountKey = activeProviderName === "self-managed" ? "credentials" : activeProviderName || "credentials";
     const credentialsAccount = {
-      provider: "credentials",
+      provider: accountKey,
       providerUserId: user.id,
       email: user.email,
-      accessToken: token,
-      raw: {
-        access_token: token,
-        token_type: "Bearer",
-        expires_in: ttl
-      },
       linkedAt: Date.now()
     };
     const session = {
-      id: sessionId,
+      sessionId,
       userId: user.id,
       email: user.email,
-      token,
-      provider: "credentials",
-      accounts: {
-        credentials: credentialsAccount
-      }
+      provider: accountKey
     };
+    if (this.accountHandler?.accountStorage) {
+      const userKey = this.getUserKeyFromSession(session);
+      await this.accountHandler.accountStorage.saveAccount(userKey, accountKey, this.sanitizeIdentityForStorage(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: accountKey });
     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, or Composite).
+   * 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)
+   * @param params - Sign-in parameters (identifier, password, optional provider)
    * @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 = params.provider || 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 = (0, import_crypto4.randomBytes)(32).toString("hex");
+    const token = tokens?.accessToken || (0, import_crypto5.randomBytes)(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 activeProviderName = params.provider || user && user.provider || (this.identityProvider instanceof CompositeIdentityProvider ? this.identityProvider.defaultProvider : this.identityProvider.name);
+    const accountKey = activeProviderName === "self-managed" ? "credentials" : activeProviderName || "credentials";
     const credentialsAccount = {
-      provider: "credentials",
+      provider: accountKey,
       providerUserId: user.id,
       email: user.email,
-      accessToken: token,
-      raw: {
-        access_token: token,
-        token_type: "Bearer",
-        expires_in: ttl
-      },
       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 };
         if (!mergedSession.userId) mergedSession.userId = user.id;
         if (!mergedSession.email) mergedSession.email = user.email;
+        mergedSession.provider = accountKey;
+        mergedSession.token = token;
+        mergedSession.raw = rawTokens;
+        if (this.accountHandler?.accountStorage) {
+          const userKey = this.getUserKeyFromSession(mergedSession);
+          await this.accountHandler.accountStorage.saveAccount(userKey, accountKey, this.sanitizeIdentityForStorage(credentialsAccount));
+        }
         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
         });
@@ -2017,53 +3147,229 @@ var Lixa = class _Lixa {
         };
       }
     }
-    const sessionId = (0, import_crypto4.randomBytes)(16).toString("hex");
+    const sessionId = (0, import_crypto5.randomBytes)(16).toString("hex");
+    let targetUserId = user.id;
+    const allAccounts = {
+      [accountKey]: credentialsAccount
+    };
+    if (this.accountHandler?.accountStorage) {
+      if (user.email && this.accountHandler.accountStorage.findAccountsByEmail) {
+        const matches = await this.accountHandler.accountStorage.findAccountsByEmail(user.email);
+        if (matches.length > 0) {
+          targetUserId = matches[0].userId;
+          for (const match of matches) {
+            const userAccs = await this.accountHandler.accountStorage.getUserAccounts(match.userId);
+            if (userAccs) {
+              for (const [k, v] of Object.entries(userAccs)) {
+                if (k !== accountKey && !allAccounts[k]) {
+                  allAccounts[k] = v;
+                }
+              }
+            }
+          }
+        }
+      }
+      const directAccounts = await this.accountHandler.accountStorage.getUserAccounts(user.id);
+      if (directAccounts) {
+        for (const [k, v] of Object.entries(directAccounts)) {
+          if (k !== accountKey && !allAccounts[k]) {
+            allAccounts[k] = v;
+          }
+        }
+      }
+      await this.accountHandler.accountStorage.saveAccount(
+        targetUserId,
+        accountKey,
+        this.sanitizeIdentityForStorage(credentialsAccount)
+      );
+      for (const [pKey, pAcc] of Object.entries(allAccounts)) {
+        if (pKey !== accountKey) {
+          await this.accountHandler.accountStorage.saveAccount(
+            targetUserId,
+            pKey,
+            this.sanitizeIdentityForStorage(pAcc)
+          );
+        }
+      }
+    }
     const session = {
-      id: sessionId,
-      userId: user.id,
+      sessionId,
+      userId: targetUserId,
       email: user.email,
+      provider: accountKey,
       token,
-      provider: "credentials",
-      accounts: {
-        credentials: credentialsAccount
-      }
+      raw: rawTokens
     };
     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 ${accountKey}`, { userId: targetUserId, 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
+   * @param params - Verification parameters (identifier, password, optional provider)
+   * @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.
    * 
-   * @param params - Change password parameters (userId/identifier, oldPassword, newPassword)
+   * @param params - Change password parameters (userId/identifier, oldPassword, newPassword, optional provider)
    * @returns True if password was updated successfully
    * @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, optional provider)
+   * @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, new password, and optional provider
+   * @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, confirmationCode, and optional provider
+   * @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 and optional provider
+   * @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
+   * @param provider - Optional provider key when using CompositeIdentityProvider
+   * @returns UserIdentity or null if not found
+   */
+  async getUserById(id, provider) {
+    if (!this.identityProvider || typeof this.identityProvider.getUserById !== "function") {
+      return null;
+    }
+    return this.identityProvider.getUserById(id, provider);
+  }
+  /**
+   * Retrieves a user by their identifier (username or email) from the configured identity provider.
+   * 
+   * @param identifier - Username or email string
+   * @param provider - Optional provider key when using CompositeIdentityProvider
+   * @returns UserIdentity or null if not found
+   */
+  async getUserByIdentifier(identifier, provider) {
+    if (!this.identityProvider || typeof this.identityProvider.getUserByIdentifier !== "function") {
+      return null;
+    }
+    return this.identityProvider.getUserByIdentifier(identifier, provider);
+  }
+  /**
+   * Deletes a user account from the configured identity provider.
+   * 
+   * @param id - Unique user ID
+   * @param provider - Optional provider key when using CompositeIdentityProvider
+   */
+  async deleteUser(id, provider) {
+    if (!this.identityProvider || typeof this.identityProvider.deleteUser !== "function") {
+      return;
+    }
+    await this.identityProvider.deleteUser(id, provider);
   }
   findProviderByType(providerType) {
     for (const [key, value] of Object.entries(this.config.providers || {})) {
@@ -2075,125 +3381,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, {
@@ -2203,10 +3390,20 @@ __export(credentials_exports, {
   ScryptPasswordHasher: () => ScryptPasswordHasher,
   validatePasswordPolicy: () => validatePasswordPolicy
 });
+
+// src/identity/index.ts
+var identity_exports = {};
+__export(identity_exports, {
+  CompositeIdentityProvider: () => CompositeIdentityProvider,
+  SelfManagedIdentityProvider: () => SelfManagedIdentityProvider
+});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AccountLinkingChallengeRequiredError,
   AccountLinkingStrategy,
+  AccountNotVerifiedError,
   AccountUnlinkError,
+  CompositeIdentityProvider,
   CredentialsManager,
   CredentialsNotConfiguredError,
   DEFAULT_SESSION_COOKIE_NAME,
@@ -2214,6 +3411,8 @@ __export(credentials_exports, {
   DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_STATE_MAX_AGE_SECONDS,
   EmailNotVerifiedError,
+  IdentityNotConfiguredError,
+  IdentityProviderError,
   InvalidCredentialsError,
   InvalidOAuthCallbackError,
   InvalidProviderConfigError,
@@ -2224,7 +3423,9 @@ __export(credentials_exports, {
   Pbkdf2PasswordHasher,
   ProviderNotConfiguredError,
   RefreshTokenError,
+  SSOAccountAlreadyExistsError,
   ScryptPasswordHasher,
+  SelfManagedIdentityProvider,
   SessionNotFoundError,
   TokenExchangeError,
   UserAlreadyExistsError,
@@ -2239,6 +3440,7 @@ __export(credentials_exports, {
   determineProviderFromIssuer,
   extractUserInfo,
   fetchUserInfo,
+  identity,
   isProductionEnvironment,
   serializeCookie,
   validatePasswordPolicy