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

package/dist/index.js

@@ -1,6 +1,591 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/lixa.ts
 import { randomBytes as randomBytes2 } from "crypto";
 
+// src/credentials/hasher.ts
+import crypto from "crypto";
+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 = crypto.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 crypto.timingSafeEqual(storedKeyBuffer, derivedKeyBuffer);
+  }
+  deriveKey(password, salt, keyLength, cost, blockSize, parallelization) {
+    return new Promise((resolve, reject) => {
+      crypto.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 = crypto.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 crypto.timingSafeEqual(storedKeyBuffer, derivedKeyBuffer);
+  }
+  deriveKey(password, salt, iterations, keyLength, digest) {
+    return new Promise((resolve, reject) => {
+      crypto.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
+import crypto2 from "crypto";
+
+// 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 crypto2.randomUUID === "function" ? crypto2.randomUUID() : crypto2.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) => {
   AccountLinkingStrategy2["AUTO_LINK_BY_VERIFIED_EMAIL"] = "AUTO_LINK_BY_VERIFIED_EMAIL";
@@ -48,7 +633,7 @@ var LocalStateHandler = class {
 };
 
 // src/lixa.ts
-import crypto from "crypto";
+import crypto3 from "crypto";
 
 // src/dao/session-cache.ts
 import NodeCache2 from "node-cache";
@@ -187,80 +772,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();
@@ -272,6 +783,7 @@ var Lixa = class _Lixa {
   localResourceHandler;
   userResourceStore = /* @__PURE__ */ new Map();
   refreshMutexes = /* @__PURE__ */ new Map();
+  credentialsManager;
   config;
   stateHandler;
   sessionHandler;
@@ -330,26 +842,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");
@@ -410,7 +928,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
    */
@@ -447,7 +965,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.
@@ -638,7 +1156,7 @@ var Lixa = class _Lixa {
    * @internal
    */
   static buildCodeChallenge(codeVerifier) {
-    const hash = crypto.createHash("sha256").update(codeVerifier).digest("base64");
+    const hash = crypto3.createHash("sha256").update(codeVerifier).digest("base64");
     return hash.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
   }
   /**
@@ -1311,8 +1829,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 = randomBytes2(16).toString("hex");
+    const token = randomBytes2(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 = randomBytes2(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 = randomBytes2(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;
       }
@@ -1439,32 +2127,53 @@ function clearStateCookie(options) {
     header
   };
 }
+
+// src/credentials/index.ts
+var credentials_exports = {};
+__export(credentials_exports, {
+  CredentialsManager: () => CredentialsManager,
+  LocalCredentialsStorage: () => LocalCredentialsStorage,
+  Pbkdf2PasswordHasher: () => Pbkdf2PasswordHasher,
+  ScryptPasswordHasher: () => ScryptPasswordHasher,
+  validatePasswordPolicy: () => validatePasswordPolicy
+});
 export {
   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_exports as credentials,
   decodeIdToken,
   determineProviderFromIssuer,
   extractUserInfo,
   fetchUserInfo,
   isProductionEnvironment,
-  serializeCookie
+  serializeCookie,
+  validatePasswordPolicy
 };
 //# sourceMappingURL=index.js.map