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

package/dist/index.cjs

@@ -32,35 +32,625 @@ var src_exports = {};
 __export(src_exports, {
   AccountLinkingStrategy: () => AccountLinkingStrategy,
   AccountUnlinkError: () => AccountUnlinkError,
+  CredentialsManager: () => CredentialsManager,
+  CredentialsNotConfiguredError: () => CredentialsNotConfiguredError,
   DEFAULT_SESSION_COOKIE_NAME: () => DEFAULT_SESSION_COOKIE_NAME,
   DEFAULT_SESSION_MAX_AGE_SECONDS: () => DEFAULT_SESSION_MAX_AGE_SECONDS,
   DEFAULT_STATE_COOKIE_NAME: () => DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_STATE_MAX_AGE_SECONDS: () => DEFAULT_STATE_MAX_AGE_SECONDS,
   EmailNotVerifiedError: () => EmailNotVerifiedError,
+  InvalidCredentialsError: () => InvalidCredentialsError,
   InvalidOAuthCallbackError: () => InvalidOAuthCallbackError,
   InvalidProviderConfigError: () => InvalidProviderConfigError,
   InvalidStateError: () => InvalidStateError,
   Lixa: () => Lixa,
   LixaError: () => LixaError,
+  LocalCredentialsStorage: () => LocalCredentialsStorage,
+  Pbkdf2PasswordHasher: () => Pbkdf2PasswordHasher,
   ProviderNotConfiguredError: () => ProviderNotConfiguredError,
   RefreshTokenError: () => RefreshTokenError,
+  ScryptPasswordHasher: () => ScryptPasswordHasher,
   SessionNotFoundError: () => SessionNotFoundError,
   TokenExchangeError: () => TokenExchangeError,
+  UserAlreadyExistsError: () => UserAlreadyExistsError,
+  UserNotFoundError: () => UserNotFoundError,
+  WeakPasswordError: () => WeakPasswordError,
   clearSessionCookie: () => clearSessionCookie,
   clearStateCookie: () => clearStateCookie,
   createSessionCookie: () => createSessionCookie,
   createStateCookie: () => createStateCookie,
+  credentials: () => credentials_exports,
   decodeIdToken: () => decodeIdToken,
   determineProviderFromIssuer: () => determineProviderFromIssuer,
   extractUserInfo: () => extractUserInfo,
   fetchUserInfo: () => fetchUserInfo,
   isProductionEnvironment: () => isProductionEnvironment,
-  serializeCookie: () => serializeCookie
+  serializeCookie: () => serializeCookie,
+  validatePasswordPolicy: () => validatePasswordPolicy
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/lixa.ts
-var import_crypto2 = require("crypto");
+var import_crypto4 = require("crypto");
+
+// src/credentials/hasher.ts
+var import_crypto = __toESM(require("crypto"), 1);
+var ScryptPasswordHasher = class {
+  cost;
+  blockSize;
+  parallelization;
+  saltLength;
+  keyLength;
+  maxmem;
+  constructor(options = {}) {
+    this.cost = options.cost ?? 16384;
+    this.blockSize = options.blockSize ?? 8;
+    this.parallelization = options.parallelization ?? 1;
+    this.saltLength = options.saltLength ?? 16;
+    this.keyLength = options.keyLength ?? 64;
+    this.maxmem = options.maxmem ?? 32 * 1024 * 1024;
+  }
+  /**
+   * Hashes a plaintext password using Scrypt.
+   * 
+   * @param password - Plaintext password
+   * @returns Formatted Scrypt hash string
+   */
+  async hash(password) {
+    const salt = import_crypto.default.randomBytes(this.saltLength).toString("hex");
+    const derivedKey = await this.deriveKey(
+      password,
+      salt,
+      this.keyLength,
+      this.cost,
+      this.blockSize,
+      this.parallelization
+    );
+    return `$scrypt$N=${this.cost},r=${this.blockSize},p=${this.parallelization}$${salt}$${derivedKey.toString("hex")}`;
+  }
+  /**
+   * Verifies a password against a stored Scrypt hash.
+   * 
+   * @param password - Plaintext password
+   * @param hash - Formatted Scrypt hash string
+   * @returns True if password matches hash
+   */
+  async verify(password, hash) {
+    if (!hash || typeof hash !== "string" || !hash.startsWith("$scrypt$")) {
+      return false;
+    }
+    const parts = hash.split("$");
+    if (parts.length !== 5) {
+      return false;
+    }
+    const paramsStr = parts[2];
+    const salt = parts[3];
+    const storedKeyHex = parts[4];
+    if (!paramsStr || !salt || !storedKeyHex) {
+      return false;
+    }
+    const params = /* @__PURE__ */ new Map();
+    for (const param of paramsStr.split(",")) {
+      const [k, v] = param.split("=");
+      if (k && v) {
+        params.set(k.trim(), parseInt(v.trim(), 10));
+      }
+    }
+    const cost = params.get("N") ?? this.cost;
+    const blockSize = params.get("r") ?? this.blockSize;
+    const parallelization = params.get("p") ?? this.parallelization;
+    const storedKeyBuffer = Buffer.from(storedKeyHex, "hex");
+    const derivedKeyBuffer = await this.deriveKey(
+      password,
+      salt,
+      storedKeyBuffer.length,
+      cost,
+      blockSize,
+      parallelization
+    );
+    if (storedKeyBuffer.length !== derivedKeyBuffer.length) {
+      return false;
+    }
+    return import_crypto.default.timingSafeEqual(storedKeyBuffer, derivedKeyBuffer);
+  }
+  deriveKey(password, salt, keyLength, cost, blockSize, parallelization) {
+    return new Promise((resolve, reject) => {
+      import_crypto.default.scrypt(
+        password,
+        salt,
+        keyLength,
+        {
+          N: cost,
+          r: blockSize,
+          p: parallelization,
+          maxmem: this.maxmem
+        },
+        (err, derivedKey) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve(derivedKey);
+          }
+        }
+      );
+    });
+  }
+};
+var Pbkdf2PasswordHasher = class {
+  iterations;
+  digest;
+  saltLength;
+  keyLength;
+  constructor(options = {}) {
+    this.iterations = options.iterations ?? 1e5;
+    this.digest = options.digest ?? "sha512";
+    this.saltLength = options.saltLength ?? 16;
+    this.keyLength = options.keyLength ?? 64;
+  }
+  async hash(password) {
+    const salt = import_crypto.default.randomBytes(this.saltLength).toString("hex");
+    const derivedKey = await this.deriveKey(
+      password,
+      salt,
+      this.iterations,
+      this.keyLength,
+      this.digest
+    );
+    return `$pbkdf2$i=${this.iterations},d=${this.digest}$${salt}$${derivedKey.toString("hex")}`;
+  }
+  async verify(password, hash) {
+    if (!hash || typeof hash !== "string" || !hash.startsWith("$pbkdf2$")) {
+      return false;
+    }
+    const parts = hash.split("$");
+    if (parts.length !== 5) {
+      return false;
+    }
+    const paramsStr = parts[2];
+    const salt = parts[3];
+    const storedKeyHex = parts[4];
+    if (!paramsStr || !salt || !storedKeyHex) {
+      return false;
+    }
+    let iterations = this.iterations;
+    let digest = this.digest;
+    for (const param of paramsStr.split(",")) {
+      const [k, v] = param.split("=");
+      if (k === "i" && v) {
+        iterations = parseInt(v, 10);
+      } else if (k === "d" && v) {
+        digest = v;
+      }
+    }
+    const storedKeyBuffer = Buffer.from(storedKeyHex, "hex");
+    const derivedKeyBuffer = await this.deriveKey(
+      password,
+      salt,
+      iterations,
+      storedKeyBuffer.length,
+      digest
+    );
+    if (storedKeyBuffer.length !== derivedKeyBuffer.length) {
+      return false;
+    }
+    return import_crypto.default.timingSafeEqual(storedKeyBuffer, derivedKeyBuffer);
+  }
+  deriveKey(password, salt, iterations, keyLength, digest) {
+    return new Promise((resolve, reject) => {
+      import_crypto.default.pbkdf2(password, salt, iterations, keyLength, digest, (err, derivedKey) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(derivedKey);
+        }
+      });
+    });
+  }
+};
+
+// src/credentials/policy.ts
+async function validatePasswordPolicy(password, policy = {}) {
+  const errors = [];
+  if (typeof password !== "string") {
+    return {
+      valid: false,
+      errors: ["Password must be a string"]
+    };
+  }
+  const minLength = policy.minLength ?? 8;
+  const maxLength = policy.maxLength ?? 128;
+  if (password.length < minLength) {
+    errors.push(`Password must be at least ${minLength} characters long`);
+  }
+  if (password.length > maxLength) {
+    errors.push(`Password must not exceed ${maxLength} characters`);
+  }
+  if (policy.requireUppercase && !/[A-Z]/.test(password)) {
+    errors.push("Password must contain at least one uppercase letter (A-Z)");
+  }
+  if (policy.requireLowercase && !/[a-z]/.test(password)) {
+    errors.push("Password must contain at least one lowercase letter (a-z)");
+  }
+  if (policy.requireNumbers && !/[0-9]/.test(password)) {
+    errors.push("Password must contain at least one number (0-9)");
+  }
+  if (policy.requireSpecialChars && !/[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?~`]/.test(password)) {
+    errors.push("Password must contain at least one special character");
+  }
+  if (policy.customValidator) {
+    try {
+      const customResult = await policy.customValidator(password);
+      if (customResult === false) {
+        errors.push("Password failed custom validation rule");
+      } else if (typeof customResult === "string" && customResult.trim().length > 0) {
+        errors.push(customResult);
+      }
+    } catch (err) {
+      errors.push(`Custom password validator failed: ${err?.message || "Unknown error"}`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// src/credentials/local-storage.ts
+var LocalCredentialsStorage = class {
+  usersById = /* @__PURE__ */ new Map();
+  identifierToId = /* @__PURE__ */ new Map();
+  async saveUser(user) {
+    const normalizedIdentifier = user.identifier.trim().toLowerCase();
+    this.usersById.set(user.id, { ...user, identifier: normalizedIdentifier });
+    this.identifierToId.set(normalizedIdentifier, user.id);
+    if (user.email) {
+      this.identifierToId.set(user.email.trim().toLowerCase(), user.id);
+    }
+    if (user.username) {
+      this.identifierToId.set(user.username.trim().toLowerCase(), user.id);
+    }
+  }
+  async findUserByIdentifier(identifier) {
+    const normalized = identifier.trim().toLowerCase();
+    const id = this.identifierToId.get(normalized);
+    if (!id) {
+      return null;
+    }
+    const user = this.usersById.get(id);
+    return user ? { ...user } : null;
+  }
+  async findUserById(id) {
+    const user = this.usersById.get(id);
+    return user ? { ...user } : null;
+  }
+  async updatePassword(id, newPasswordHash) {
+    const user = this.usersById.get(id);
+    if (user) {
+      user.passwordHash = newPasswordHash;
+      user.updatedAt = Date.now();
+      this.usersById.set(id, user);
+    }
+  }
+  async deleteUser(id) {
+    const user = this.usersById.get(id);
+    if (user) {
+      this.identifierToId.delete(user.identifier.toLowerCase());
+      if (user.email) this.identifierToId.delete(user.email.toLowerCase());
+      if (user.username) this.identifierToId.delete(user.username.toLowerCase());
+      this.usersById.delete(id);
+    }
+  }
+  clear() {
+    this.usersById.clear();
+    this.identifierToId.clear();
+  }
+};
+
+// src/credentials/credentials-manager.ts
+var import_crypto2 = __toESM(require("crypto"), 1);
+
+// src/errors.ts
+var LixaError = class extends Error {
+  /**
+   * Standard error code string.
+   */
+  code;
+  /**
+   * Additional error context data.
+   */
+  details;
+  constructor(message, code = "LIXA_ERROR", details) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidStateError = class extends LixaError {
+  constructor(message = "Invalid or expired state", details) {
+    super(message, "INVALID_STATE", details);
+  }
+};
+var ProviderNotConfiguredError = class extends LixaError {
+  constructor(provider, details) {
+    const message = details?.message && typeof details.message === "string" ? details.message : `Provider '${provider}' is not available. Either import it from '@vunexa/lixa-providers' and include it in the configuration, or provide a custom implementation using the 'provider' field: { provider: new CustomProvider(), clientId: '...', ... }`;
+    super(message, "PROVIDER_NOT_CONFIGURED", {
+      provider,
+      ...details
+    });
+  }
+};
+var InvalidProviderConfigError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_PROVIDER_CONFIG", details);
+  }
+};
+var InvalidOAuthCallbackError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "INVALID_OAUTH_CALLBACK", details);
+  }
+};
+var TokenExchangeError = class extends LixaError {
+  status;
+  constructor(message, status, details) {
+    super(message, "TOKEN_EXCHANGE_FAILED", { status, ...details });
+    this.status = status;
+  }
+};
+var SessionNotFoundError = class extends LixaError {
+  constructor(message = "Active session not found or has expired", details) {
+    super(message, "SESSION_NOT_FOUND", details);
+  }
+};
+var EmailNotVerifiedError = class extends LixaError {
+  constructor(email, details) {
+    super(
+      `Cannot link account: email '${email || "unknown"}' is not verified by the identity provider`,
+      "EMAIL_NOT_VERIFIED",
+      { email, ...details }
+    );
+  }
+};
+var AccountUnlinkError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "ACCOUNT_UNLINK_ERROR", details);
+  }
+};
+var RefreshTokenError = class extends LixaError {
+  constructor(message, details) {
+    super(message, "REFRESH_TOKEN_ERROR", details);
+  }
+};
+var InvalidCredentialsError = class extends LixaError {
+  constructor(message = "Invalid identifier or password", details) {
+    super(message, "INVALID_CREDENTIALS", details);
+  }
+};
+var UserAlreadyExistsError = class extends LixaError {
+  constructor(identifier, details) {
+    super(`User with identifier '${identifier}' already exists`, "USER_ALREADY_EXISTS", {
+      identifier,
+      ...details
+    });
+  }
+};
+var UserNotFoundError = class extends LixaError {
+  constructor(identifierOrId, details) {
+    super(
+      `User not found${identifierOrId ? `: '${identifierOrId}'` : ""}`,
+      "USER_NOT_FOUND",
+      { identifierOrId, ...details }
+    );
+  }
+};
+var WeakPasswordError = class extends LixaError {
+  validationErrors;
+  constructor(validationErrors = [], details) {
+    const message = validationErrors.length > 0 ? `Password does not meet security requirements: ${validationErrors.join("; ")}` : "Password does not meet security requirements";
+    super(message, "WEAK_PASSWORD", { validationErrors, ...details });
+    this.validationErrors = validationErrors;
+  }
+};
+var CredentialsNotConfiguredError = class extends LixaError {
+  constructor(message = "Credentials authentication is not configured in this Lixa instance. Pass credentials: {} in LixaConfig to enable it.", details) {
+    super(message, "CREDENTIALS_NOT_CONFIGURED", details);
+  }
+};
+
+// src/credentials/credentials-manager.ts
+var CredentialsManager = class {
+  storage;
+  hasher;
+  policy;
+  identifierType;
+  requireUsername;
+  requireEmail;
+  timingAttackProtection;
+  dummyHash = "";
+  constructor(config = {}) {
+    this.storage = config.storage || new LocalCredentialsStorage();
+    this.hasher = config.hasher || new ScryptPasswordHasher();
+    this.policy = {
+      minLength: 8,
+      maxLength: 128,
+      ...config.policy
+    };
+    this.identifierType = config.identifierType || "both";
+    this.requireUsername = config.requireUsername ?? false;
+    this.requireEmail = config.requireEmail ?? false;
+    this.timingAttackProtection = config.timingAttackProtection ?? true;
+    this.initDummyHash().catch(() => {
+      this.dummyHash = "$scrypt$N=16384,r=8,p=1$0123456789abcdef0123456789abcdef$0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    });
+  }
+  async initDummyHash() {
+    this.dummyHash = await this.hasher.hash("dummy_constant_password_12345");
+  }
+  /**
+   * Normalizes an identifier string.
+   */
+  normalizeIdentifier(identifier) {
+    return (identifier || "").trim().toLowerCase();
+  }
+  /**
+   * Validates identifier format based on configured identifierType.
+   */
+  validateIdentifierFormat(identifier) {
+    const trimmed = (identifier || "").trim();
+    if (!trimmed) {
+      throw new InvalidCredentialsError("Identifier cannot be empty");
+    }
+    if (this.identifierType === "email") {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!emailRegex.test(trimmed)) {
+        throw new InvalidCredentialsError("Identifier must be a valid email address");
+      }
+    }
+  }
+  /**
+   * Registers a new user with password hashing and policy enforcement.
+   * 
+   * @param params - Registration parameters
+   * @returns Created user credentials without password hash
+   */
+  async signUp(params) {
+    const rawIdentifier = params.username || params.identifier || params.email || "";
+    this.validateIdentifierFormat(rawIdentifier);
+    const normalized = this.normalizeIdentifier(rawIdentifier);
+    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.requireUsername && (!username || username.trim() === "")) {
+      throw new InvalidCredentialsError("Username is required");
+    }
+    if (this.requireEmail && (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))) {
+      throw new InvalidCredentialsError("A valid email address is required");
+    }
+    const existing = await this.storage.findUserByIdentifier(normalized);
+    if (existing) {
+      throw new UserAlreadyExistsError(normalized);
+    }
+    const policyResult = await validatePasswordPolicy(params.password, this.policy);
+    if (!policyResult.valid) {
+      throw new WeakPasswordError(policyResult.errors);
+    }
+    const passwordHash = await this.hasher.hash(params.password);
+    const now = Date.now();
+    const id = typeof import_crypto2.default.randomUUID === "function" ? import_crypto2.default.randomUUID() : import_crypto2.default.randomBytes(16).toString("hex");
+    const user = {
+      id,
+      identifier: normalized,
+      email,
+      username,
+      passwordHash,
+      createdAt: now,
+      updatedAt: now,
+      metadata: params.metadata
+    };
+    await this.storage.saveUser(user);
+    const { passwordHash: _, ...safeUser } = user;
+    return safeUser;
+  }
+  /**
+   * Verifies credentials against storage with timing attack protection.
+   * 
+   * @param params - Verification parameters
+   * @returns User credentials without password hash, or null if verification fails
+   */
+  async verifyCredentials(params) {
+    const rawIdentifier = params.username || params.identifier;
+    if (!rawIdentifier || typeof params.password !== "string") {
+      return null;
+    }
+    const normalized = this.normalizeIdentifier(rawIdentifier);
+    const user = await this.storage.findUserByIdentifier(normalized);
+    if (!user) {
+      if (this.timingAttackProtection) {
+        try {
+          if (!this.dummyHash) {
+            await this.initDummyHash();
+          }
+          await this.hasher.verify(params.password, this.dummyHash);
+        } catch {
+        }
+      }
+      return null;
+    }
+    const isMatch = await this.hasher.verify(params.password, user.passwordHash);
+    if (!isMatch) {
+      return null;
+    }
+    const { passwordHash: _, ...safeUser } = user;
+    return safeUser;
+  }
+  /**
+   * Changes a user's password with old password verification and new password policy enforcement.
+   * 
+   * @param params - Change password parameters
+   * @returns True if password was successfully updated
+   */
+  async changePassword(params) {
+    let user = null;
+    const lookupKey = params.username || params.identifier;
+    if (params.userId) {
+      user = await this.storage.findUserById(params.userId);
+    } else if (lookupKey) {
+      user = await this.storage.findUserByIdentifier(this.normalizeIdentifier(lookupKey));
+    }
+    if (!user) {
+      if (this.timingAttackProtection) {
+        try {
+          if (!this.dummyHash) await this.initDummyHash();
+          await this.hasher.verify(params.oldPassword, this.dummyHash);
+        } catch {
+        }
+      }
+      throw new UserNotFoundError(params.userId || lookupKey || "unknown");
+    }
+    const isOldValid = await this.hasher.verify(params.oldPassword, user.passwordHash);
+    if (!isOldValid) {
+      throw new InvalidCredentialsError("Current password is incorrect");
+    }
+    const policyResult = await validatePasswordPolicy(params.newPassword, this.policy);
+    if (!policyResult.valid) {
+      throw new WeakPasswordError(policyResult.errors);
+    }
+    const newHash = await this.hasher.hash(params.newPassword);
+    await this.storage.updatePassword(user.id, newHash);
+    return true;
+  }
+  /**
+   * Finds a user by ID and returns safe user data.
+   */
+  async getUserById(id) {
+    const user = await this.storage.findUserById(id);
+    if (!user) return null;
+    const { passwordHash: _, ...safeUser } = user;
+    return safeUser;
+  }
+  /**
+   * Finds a user by identifier and returns safe user data.
+   */
+  async getUserByIdentifier(identifier) {
+    const user = await this.storage.findUserByIdentifier(this.normalizeIdentifier(identifier));
+    if (!user) return null;
+    const { passwordHash: _, ...safeUser } = user;
+    return safeUser;
+  }
+  /**
+   * Gets the underlying storage instance.
+   */
+  getStorage() {
+    return this.storage;
+  }
+  /**
+   * Gets the underlying hasher instance.
+   */
+  getHasher() {
+    return this.hasher;
+  }
+};
 
 // src/types.ts
 var AccountLinkingStrategy = /* @__PURE__ */ ((AccountLinkingStrategy2) => {
@@ -71,7 +661,7 @@ var AccountLinkingStrategy = /* @__PURE__ */ ((AccountLinkingStrategy2) => {
 
 // src/dao/state-cache.ts
 var import_node_cache = __toESM(require("node-cache"), 1);
-var import_crypto = require("crypto");
+var import_crypto3 = require("crypto");
 var LocalStateHandler = class {
   cache;
   stateStorage;
@@ -91,8 +681,8 @@ var LocalStateHandler = class {
   }
   // Default generateState implementation
   async generateState(provider) {
-    const state = (0, import_crypto.randomBytes)(16).toString("hex");
-    const codeVerifier = (0, import_crypto.randomBytes)(32).toString("hex");
+    const state = (0, import_crypto3.randomBytes)(16).toString("hex");
+    const codeVerifier = (0, import_crypto3.randomBytes)(32).toString("hex");
     return {
       state,
       data: {
@@ -109,7 +699,7 @@ var LocalStateHandler = class {
 };
 
 // src/lixa.ts
-var import_crypto3 = __toESM(require("crypto"), 1);
+var import_crypto5 = __toESM(require("crypto"), 1);
 
 // src/dao/session-cache.ts
 var import_node_cache2 = __toESM(require("node-cache"), 1);
@@ -248,80 +838,6 @@ async function extractUserInfo(tokenData, providerMetadata) {
   return { userInfo };
 }
 
-// src/errors.ts
-var LixaError = class extends Error {
-  /**
-   * Standard error code string.
-   */
-  code;
-  /**
-   * Additional error context data.
-   */
-  details;
-  constructor(message, code = "LIXA_ERROR", details) {
-    super(message);
-    this.name = this.constructor.name;
-    this.code = code;
-    this.details = details;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var InvalidStateError = class extends LixaError {
-  constructor(message = "Invalid or expired state", details) {
-    super(message, "INVALID_STATE", details);
-  }
-};
-var ProviderNotConfiguredError = class extends LixaError {
-  constructor(provider, details) {
-    const message = details?.message && typeof details.message === "string" ? details.message : `Provider '${provider}' is not available. Either import it from '@vunexa/lixa-providers' and include it in the configuration, or provide a custom implementation using the 'provider' field: { provider: new CustomProvider(), clientId: '...', ... }`;
-    super(message, "PROVIDER_NOT_CONFIGURED", {
-      provider,
-      ...details
-    });
-  }
-};
-var InvalidProviderConfigError = class extends LixaError {
-  constructor(message, details) {
-    super(message, "INVALID_PROVIDER_CONFIG", details);
-  }
-};
-var InvalidOAuthCallbackError = class extends LixaError {
-  constructor(message, details) {
-    super(message, "INVALID_OAUTH_CALLBACK", details);
-  }
-};
-var TokenExchangeError = class extends LixaError {
-  status;
-  constructor(message, status, details) {
-    super(message, "TOKEN_EXCHANGE_FAILED", { status, ...details });
-    this.status = status;
-  }
-};
-var SessionNotFoundError = class extends LixaError {
-  constructor(message = "Active session not found or has expired", details) {
-    super(message, "SESSION_NOT_FOUND", details);
-  }
-};
-var EmailNotVerifiedError = class extends LixaError {
-  constructor(email, details) {
-    super(
-      `Cannot link account: email '${email || "unknown"}' is not verified by the identity provider`,
-      "EMAIL_NOT_VERIFIED",
-      { email, ...details }
-    );
-  }
-};
-var AccountUnlinkError = class extends LixaError {
-  constructor(message, details) {
-    super(message, "ACCOUNT_UNLINK_ERROR", details);
-  }
-};
-var RefreshTokenError = class extends LixaError {
-  constructor(message, details) {
-    super(message, "REFRESH_TOKEN_ERROR", details);
-  }
-};
-
 // src/lixa.ts
 var Lixa = class _Lixa {
   static DEFAULT_PROVIDERS = /* @__PURE__ */ new Map();
@@ -333,6 +849,7 @@ var Lixa = class _Lixa {
   localResourceHandler;
   userResourceStore = /* @__PURE__ */ new Map();
   refreshMutexes = /* @__PURE__ */ new Map();
+  credentialsManager;
   config;
   stateHandler;
   sessionHandler;
@@ -391,26 +908,32 @@ 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.log("INFO", "Init", "Initializing Lixa instance", {
-      providers: Object.keys(config.providers),
+      providers: config.providers ? Object.keys(config.providers) : [],
+      credentialsEnabled: this.credentialsManager !== void 0,
       debug: this.debug
     });
-    for (const [providerName, providerConfig] of Object.entries(config.providers)) {
-      const name = providerName.toLowerCase();
-      const typedConfig = providerConfig;
-      this.validateProviderConfig(providerName, typedConfig);
-      if (typedConfig.provider) {
-        this.validateProviderImplementation(providerName, typedConfig.provider);
-        this.log("INFO", "Init", `Registered inline provider: ${providerName}`);
-      } else {
-        if (!_Lixa.DEFAULT_PROVIDERS.has(name) && !_Lixa.CONFIGURED_PROVIDERS.has(name)) {
-          this.log("ERROR", "Init", `Provider '${providerName}' not available`);
-          throw new ProviderNotConfiguredError(
-            providerName,
-            { hint: `Ensure the provider is registered via '@vunexa/lixa-providers' or provided inline.` }
-          );
+    if (config.providers) {
+      for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+        const name = providerName.toLowerCase();
+        const typedConfig = providerConfig;
+        this.validateProviderConfig(providerName, typedConfig);
+        if (typedConfig.provider) {
+          this.validateProviderImplementation(providerName, typedConfig.provider);
+          this.log("INFO", "Init", `Registered inline provider: ${providerName}`);
+        } else {
+          if (!_Lixa.DEFAULT_PROVIDERS.has(name) && !_Lixa.CONFIGURED_PROVIDERS.has(name)) {
+            this.log("ERROR", "Init", `Provider '${providerName}' not available`);
+            throw new ProviderNotConfiguredError(
+              providerName,
+              { hint: `Ensure the provider is registered via '@vunexa/lixa-providers' or provided inline.` }
+            );
+          }
+          this.log("INFO", "Init", `Using registered provider: ${providerName}`);
         }
-        this.log("INFO", "Init", `Using registered provider: ${providerName}`);
       }
     }
     this.log("INFO", "Init", "Lixa instance initialized successfully");
@@ -471,7 +994,7 @@ var Lixa = class _Lixa {
    * Structured logging with standardized format and custom logger support.
    * 
    * @param level - Log level (INFO, WARN, ERROR, DEBUG)
-   * @param context - Context of the log (Init, Auth, Token, Session, State, AccountLinking, Resource)
+   * @param context - Context of the log (Init, Auth, Token, Session, State, AccountLinking, Resource, Credentials)
    * @param message - Log message
    * @param data - Optional data to log
    */
@@ -508,7 +1031,7 @@ var Lixa = class _Lixa {
    */
   isProviderConfigured(provider) {
     const providerType = provider.toLowerCase();
-    return this.config.providers.hasOwnProperty(providerType);
+    return Boolean(this.config.providers && this.config.providers.hasOwnProperty(providerType));
   }
   /**
    * Gets a provider implementation by name.
@@ -616,7 +1139,7 @@ var Lixa = class _Lixa {
    * The state parameter is used to prevent CSRF attacks in OAuth flows.
    */
   static generateRandomState() {
-    return (0, import_crypto2.randomBytes)(16).toString("hex");
+    return (0, import_crypto4.randomBytes)(16).toString("hex");
   }
   /**
    * Generates a cryptographically secure code verifier for PKCE flows.
@@ -653,7 +1176,7 @@ var Lixa = class _Lixa {
    * @internal
    */
   static generateCodeVerifier() {
-    return (0, import_crypto2.randomBytes)(32).toString("hex");
+    return (0, import_crypto4.randomBytes)(32).toString("hex");
   }
   /**
    * Generates a code challenge from a code verifier for PKCE flows.
@@ -699,7 +1222,7 @@ var Lixa = class _Lixa {
    * @internal
    */
   static buildCodeChallenge(codeVerifier) {
-    const hash = import_crypto3.default.createHash("sha256").update(codeVerifier).digest("base64");
+    const hash = import_crypto5.default.createHash("sha256").update(codeVerifier).digest("base64");
     return hash.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
   }
   /**
@@ -741,8 +1264,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_crypto2.randomBytes)(16).toString("hex");
-      codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
+      stateValue = state || (0, import_crypto4.randomBytes)(16).toString("hex");
+      codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
       const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       await storage.saveState(
         stateValue,
@@ -950,7 +1473,7 @@ var Lixa = class _Lixa {
       raw: tokens,
       linkedAt: Date.now()
     };
-    const sessionId = (0, import_crypto2.randomBytes)(32).toString("hex");
+    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);
@@ -1067,8 +1590,8 @@ var Lixa = class _Lixa {
       throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    const stateValue = state || (0, import_crypto2.randomBytes)(16).toString("hex");
-    const codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
+    const stateValue = state || (0, import_crypto4.randomBytes)(16).toString("hex");
+    const codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
     const storage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
     await storage.saveState(
       stateValue,
@@ -1113,7 +1636,7 @@ var Lixa = class _Lixa {
       throw new ProviderNotConfiguredError(String(provider));
     }
     const providerImpl = this.getProvider(providerType, providerConfig);
-    let codeVerifier = (0, import_crypto2.randomBytes)(32).toString("hex");
+    let codeVerifier = (0, import_crypto4.randomBytes)(32).toString("hex");
     if (state) {
       const stateStorage = this.stateHandler.stateStorage || this.localStateHandler.stateStorage;
       const cachedState = await stateStorage.getState(state);
@@ -1372,8 +1895,178 @@ var Lixa = class _Lixa {
     this.log("INFO", "Token", "Token exchange response received successfully");
     return response.json();
   }
+  /**
+   * Checks if credentials (username and password) authentication is configured and enabled.
+   * 
+   * @returns True if credentials authentication is available
+   */
+  isCredentialsEnabled() {
+    return this.credentialsManager !== void 0;
+  }
+  /**
+   * Returns the underlying CredentialsManager instance if configured.
+   */
+  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).
+   * 
+   * @param params - Registration parameters (identifier, password, email, username, metadata)
+   * @returns Created user (without password hash) 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
+   */
+  async signUp(params) {
+    if (!this.credentialsManager) {
+      throw new CredentialsNotConfiguredError();
+    }
+    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 ttl = this.config.credentials?.sessionTtlSeconds ?? 86400;
+    const credentialsAccount = {
+      provider: "credentials",
+      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,
+      userId: user.id,
+      email: user.email,
+      token,
+      provider: "credentials",
+      accounts: {
+        credentials: 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 });
+    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.
+   * 
+   * @param params - Sign-in parameters (identifier, password)
+   * @returns Authenticated user, session ID, and session object
+   * @throws InvalidCredentialsError if authentication fails
+   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   */
+  async signIn(params) {
+    if (!this.credentialsManager) {
+      throw new CredentialsNotConfiguredError();
+    }
+    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 ttl = this.config.credentials?.sessionTtlSeconds ?? 86400;
+    const token = (0, import_crypto4.randomBytes)(32).toString("hex");
+    const credentialsAccount = {
+      provider: "credentials",
+      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";
+    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;
+        await sessionStorage.saveSession(existing.sessionId, mergedSession, ttl);
+        this.log("INFO", "AccountLinking", "Linked credentials to existing session by email", {
+          sessionId: existing.sessionId,
+          email: user.email
+        });
+        return {
+          user,
+          sessionId: existing.sessionId,
+          session: mergedSession
+        };
+      }
+    }
+    const sessionId = (0, import_crypto4.randomBytes)(16).toString("hex");
+    const session = {
+      id: sessionId,
+      userId: user.id,
+      email: user.email,
+      token,
+      provider: "credentials",
+      accounts: {
+        credentials: credentialsAccount
+      }
+    };
+    await sessionStorage.saveSession(sessionId, session, ttl);
+    this.log("INFO", "Credentials", "User signed in successfully", { userId: user.id, sessionId });
+    return { user, sessionId, session };
+  }
+  /**
+   * Verifies username/email and password credentials without generating a session.
+   * 
+   * @param params - Verification parameters (identifier, password)
+   * @returns User credentials (without password hash) or null if invalid
+   * @throws CredentialsNotConfiguredError if credentials auth is not configured
+   */
+  async verifyCredentials(params) {
+    if (!this.credentialsManager) {
+      throw new CredentialsNotConfiguredError();
+    }
+    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)
+   * @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
+   */
+  async changePassword(params) {
+    if (!this.credentialsManager) {
+      throw new CredentialsNotConfiguredError();
+    }
+    this.log("INFO", "Credentials", "Processing changePassword request", {
+      userId: params.userId,
+      identifier: params.identifier
+    });
+    return this.credentialsManager.changePassword(params);
+  }
   findProviderByType(providerType) {
-    for (const [key, value] of Object.entries(this.config.providers)) {
+    for (const [key, value] of Object.entries(this.config.providers || {})) {
       if (key.toLowerCase() === providerType.toLowerCase()) {
         return value;
       }
@@ -1500,33 +2193,54 @@ function clearStateCookie(options) {
     header
   };
 }
+
+// src/credentials/index.ts
+var credentials_exports = {};
+__export(credentials_exports, {
+  CredentialsManager: () => CredentialsManager,
+  LocalCredentialsStorage: () => LocalCredentialsStorage,
+  Pbkdf2PasswordHasher: () => Pbkdf2PasswordHasher,
+  ScryptPasswordHasher: () => ScryptPasswordHasher,
+  validatePasswordPolicy: () => validatePasswordPolicy
+});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AccountLinkingStrategy,
   AccountUnlinkError,
+  CredentialsManager,
+  CredentialsNotConfiguredError,
   DEFAULT_SESSION_COOKIE_NAME,
   DEFAULT_SESSION_MAX_AGE_SECONDS,
   DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_STATE_MAX_AGE_SECONDS,
   EmailNotVerifiedError,
+  InvalidCredentialsError,
   InvalidOAuthCallbackError,
   InvalidProviderConfigError,
   InvalidStateError,
   Lixa,
   LixaError,
+  LocalCredentialsStorage,
+  Pbkdf2PasswordHasher,
   ProviderNotConfiguredError,
   RefreshTokenError,
+  ScryptPasswordHasher,
   SessionNotFoundError,
   TokenExchangeError,
+  UserAlreadyExistsError,
+  UserNotFoundError,
+  WeakPasswordError,
   clearSessionCookie,
   clearStateCookie,
   createSessionCookie,
   createStateCookie,
+  credentials,
   decodeIdToken,
   determineProviderFromIssuer,
   extractUserInfo,
   fetchUserInfo,
   isProductionEnvironment,
-  serializeCookie
+  serializeCookie,
+  validatePasswordPolicy
 });
 //# sourceMappingURL=index.cjs.map