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

package/README.md

@@ -17,7 +17,7 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 - **Multi-SSO Account Linking**: Seamlessly merge accounts sharing the same verified email address under a single unified user session.
 - **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource tokens on the user session.
 - **Multi-provider OAuth/OIDC support** with unified API.
-- **Pre-built Database Storage Adapters**: Official Prisma and Drizzle ORM adapters via `@vunexa/lixa-adapters` with support for PostgreSQL, MySQL, and SQLite.
+- **Official Extensions Package**: Built-in OAuth Providers (Google, GitHub), Database Storage (Prisma, Drizzle), and HTTP Frameworks (Express) via `@vunexa/lixa-extensions`.
 - **Unified session management** via `SessionHandler` (generation + storage).
 - **Unified state management** via `StateHandler` (PKCE + CSRF protection).
 - **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows.
@@ -34,9 +34,9 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 ## Installation
 
 ```bash
-npm install @vunexa/lixa @vunexa/lixa-providers
+npm install @vunexa/lixa @vunexa/lixa-extensions
 # or
-yarn add @vunexa/lixa @vunexa/lixa-providers
+yarn add @vunexa/lixa @vunexa/lixa-extensions
 ```
 
 ---
@@ -47,7 +47,7 @@ yarn add @vunexa/lixa @vunexa/lixa-providers
 
 ```typescript
 import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
-import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-extensions/providers";
 
 export const lixa = new Lixa({
   // Configure Multi-SSO Account Linking Strategy

package/dist/credentials/credentials-manager.d.ts

@@ -0,0 +1,65 @@
+import type { CredentialsConfig, CredentialsStorage, IPasswordHasher, UserCredentials, SignUpParams, VerifyCredentialsParams, ChangePasswordParams } from "./types";
+/**
+ * Coordinates user registration, authentication, password verification, policy enforcement,
+ * and timing attack protection.
+ *
+ * @public
+ */
+export declare class CredentialsManager {
+    private readonly storage;
+    private readonly hasher;
+    private readonly policy;
+    private readonly identifierType;
+    private readonly requireUsername;
+    private readonly requireEmail;
+    private readonly timingAttackProtection;
+    private dummyHash;
+    constructor(config?: CredentialsConfig);
+    private initDummyHash;
+    /**
+     * Normalizes an identifier string.
+     */
+    private normalizeIdentifier;
+    /**
+     * Validates identifier format based on configured identifierType.
+     */
+    private validateIdentifierFormat;
+    /**
+     * Registers a new user with password hashing and policy enforcement.
+     *
+     * @param params - Registration parameters
+     * @returns Created user credentials without password hash
+     */
+    signUp(params: SignUpParams): Promise<Omit<UserCredentials, "passwordHash">>;
+    /**
+     * Verifies credentials against storage with timing attack protection.
+     *
+     * @param params - Verification parameters
+     * @returns User credentials without password hash, or null if verification fails
+     */
+    verifyCredentials(params: VerifyCredentialsParams): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    /**
+     * 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
+     */
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Finds a user by ID and returns safe user data.
+     */
+    getUserById(id: string): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    /**
+     * Finds a user by identifier and returns safe user data.
+     */
+    getUserByIdentifier(identifier: string): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    /**
+     * Gets the underlying storage instance.
+     */
+    getStorage(): CredentialsStorage;
+    /**
+     * Gets the underlying hasher instance.
+     */
+    getHasher(): IPasswordHasher;
+}
+//# sourceMappingURL=credentials-manager.d.ts.map

package/dist/credentials/credentials-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-manager.d.ts","sourceRoot":"","sources":["../../src/credentials/credentials-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAEf,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAWjB;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAU;IACjD,OAAO,CAAC,SAAS,CAAc;gBAEnB,MAAM,GAAE,iBAAsB;YAqB5B,aAAa;IAI3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;;OAKG;IACU,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;IAsDzF;;;;;OAKG;IACU,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC;IAiCtH;;;;;OAKG;IACU,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAqC3E;;OAEG;IACU,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC;IAO3F;;OAEG;IACU,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC;IAO3G;;OAEG;IACI,UAAU,IAAI,kBAAkB;IAIvC;;OAEG;IACI,SAAS,IAAI,eAAe;CAGpC"}

package/dist/credentials/hasher.d.ts

@@ -0,0 +1,88 @@
+import type { IPasswordHasher } from "./types";
+/**
+ * Options for Scrypt password hashing.
+ *
+ * @public
+ */
+export interface ScryptHasherOptions {
+    /** CPU/memory cost parameter (must be power of 2). Default: 16384 (2^14) */
+    cost?: number;
+    /** Block size parameter. Default: 8 */
+    blockSize?: number;
+    /** Parallelization parameter. Default: 1 */
+    parallelization?: number;
+    /** Salt length in bytes. Default: 16 */
+    saltLength?: number;
+    /** Derived key length in bytes. Default: 64 */
+    keyLength?: number;
+    /** Max memory allocated in bytes. Default: 32MB */
+    maxmem?: number;
+}
+/**
+ * Default secure password hasher utilizing Node.js native `crypto.scrypt`.
+ *
+ * @remarks
+ * Produces PHC-formatted strings: `$scrypt$N=16384,r=8,p=1$<saltHex>$<keyHex>`.
+ * Verification uses constant-time `crypto.timingSafeEqual` to prevent timing attacks.
+ *
+ * @public
+ */
+export declare class ScryptPasswordHasher implements IPasswordHasher {
+    private readonly cost;
+    private readonly blockSize;
+    private readonly parallelization;
+    private readonly saltLength;
+    private readonly keyLength;
+    private readonly maxmem;
+    constructor(options?: ScryptHasherOptions);
+    /**
+     * Hashes a plaintext password using Scrypt.
+     *
+     * @param password - Plaintext password
+     * @returns Formatted Scrypt hash string
+     */
+    hash(password: string): Promise<string>;
+    /**
+     * Verifies a password against a stored Scrypt hash.
+     *
+     * @param password - Plaintext password
+     * @param hash - Formatted Scrypt hash string
+     * @returns True if password matches hash
+     */
+    verify(password: string, hash: string): Promise<boolean>;
+    private deriveKey;
+}
+/**
+ * Options for PBKDF2 password hashing.
+ *
+ * @public
+ */
+export interface Pbkdf2HasherOptions {
+    /** Iteration count. Default: 100000 */
+    iterations?: number;
+    /** HMAC digest algorithm. Default: 'sha512' */
+    digest?: string;
+    /** Salt length in bytes. Default: 16 */
+    saltLength?: number;
+    /** Derived key length in bytes. Default: 64 */
+    keyLength?: number;
+}
+/**
+ * Alternative password hasher using Node.js native `crypto.pbkdf2`.
+ *
+ * @remarks
+ * Produces PHC-formatted strings: `$pbkdf2$i=100000,d=sha512$<saltHex>$<keyHex>`.
+ *
+ * @public
+ */
+export declare class Pbkdf2PasswordHasher implements IPasswordHasher {
+    private readonly iterations;
+    private readonly digest;
+    private readonly saltLength;
+    private readonly keyLength;
+    constructor(options?: Pbkdf2HasherOptions);
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    private deriveKey;
+}
+//# sourceMappingURL=hasher.d.ts.map

package/dist/credentials/hasher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasher.d.ts","sourceRoot":"","sources":["../../src/credentials/hasher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,mBAAwB;IAS7C;;;;;OAKG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcpD;;;;;;OAMG;IACU,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgDrE,OAAO,CAAC,SAAS;CA6BlB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,GAAE,mBAAwB;IAOhC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAavC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8CrE,OAAO,CAAC,SAAS;CAiBlB"}

package/dist/credentials/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./hasher";
+export * from "./policy";
+export * from "./local-storage";
+export * from "./credentials-manager";
+//# sourceMappingURL=index.d.ts.map

package/dist/credentials/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}

package/dist/credentials/local-storage.d.ts

@@ -0,0 +1,20 @@
+import type { CredentialsStorage, UserCredentials } from "./types";
+/**
+ * In-memory credentials storage for development, testing, and isolated environments.
+ *
+ * @remarks
+ * Uses instance-isolated Maps to prevent state leakage across tests or Lixa instances.
+ *
+ * @public
+ */
+export declare class LocalCredentialsStorage implements CredentialsStorage {
+    private usersById;
+    private identifierToId;
+    saveUser(user: UserCredentials): Promise<void>;
+    findUserByIdentifier(identifier: string): Promise<UserCredentials | null>;
+    findUserById(id: string): Promise<UserCredentials | null>;
+    updatePassword(id: string, newPasswordHash: string): Promise<void>;
+    deleteUser(id: string): Promise<void>;
+    clear(): void;
+}
+//# sourceMappingURL=local-storage.d.ts.map

package/dist/credentials/local-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage.d.ts","sourceRoot":"","sources":["../../src/credentials/local-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,OAAO,CAAC,SAAS,CAA2C;IAC5D,OAAO,CAAC,cAAc,CAAkC;IAE3C,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAUzE,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAKzD,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3C,KAAK,IAAI,IAAI;CAIrB"}

package/dist/credentials/policy.d.ts

@@ -0,0 +1,12 @@
+import type { PasswordPolicyConfig, PasswordPolicyResult } from "./types";
+/**
+ * Validates a plaintext password against configured password policy rules.
+ *
+ * @param password - Plaintext password to evaluate
+ * @param policy - Optional custom policy configuration
+ * @returns PasswordPolicyResult containing boolean valid flag and error messages
+ *
+ * @public
+ */
+export declare function validatePasswordPolicy(password: string, policy?: PasswordPolicyConfig): Promise<PasswordPolicyResult>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/credentials/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/credentials/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,oBAAyB,GAChC,OAAO,CAAC,oBAAoB,CAAC,CAsD/B"}

package/dist/credentials/types.d.ts

@@ -0,0 +1,314 @@
+import type { Session } from "../models/session";
+/**
+ * User credentials entity representing stored account login information.
+ *
+ * @public
+ */
+export interface UserCredentials {
+    /** Unique user identifier (UUID or Nanoid) */
+    id: string;
+    /** Primary unique lookup identifier (normalized lowercase username or email) */
+    identifier: string;
+    /** Username of the account */
+    username?: string | undefined;
+    /** Associated email address */
+    email?: string | undefined;
+    /** Securely hashed password string (e.g. Scrypt, Argon2, PBKDF2, Bcrypt) */
+    passwordHash: string;
+    /** Unix timestamp in milliseconds when user credentials were created */
+    createdAt: number;
+    /** Unix timestamp in milliseconds when user credentials were last updated */
+    updatedAt: number;
+    /** Optional custom user metadata or profile attributes */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * Storage interface for managing user credentials.
+ *
+ * @remarks
+ * Implement this interface to persist credentials in custom databases
+ * (e.g. PostgreSQL, MySQL, SQLite, MongoDB, DynamoDB) or use provided adapters
+ * (PrismaCredentialsStorage, DrizzleCredentialsStorage).
+ *
+ * @public
+ */
+export interface CredentialsStorage {
+    /**
+     * Persists a new user credential record.
+     *
+     * @param user - User credentials entity to save
+     */
+    saveUser(user: UserCredentials): Promise<void>;
+    /**
+     * Retrieves user credentials by normalized identifier (username or email).
+     *
+     * @param identifier - Normalized identifier string
+     * @returns UserCredentials record or null if not found
+     */
+    findUserByIdentifier(identifier: string): Promise<UserCredentials | null>;
+    /**
+     * Retrieves user credentials by unique user ID.
+     *
+     * @param id - Unique user ID
+     * @returns UserCredentials record or null if not found
+     */
+    findUserById(id: string): Promise<UserCredentials | null>;
+    /**
+     * Updates the password hash for a user by user ID.
+     *
+     * @param id - Unique user ID
+     * @param newPasswordHash - Newly computed password hash
+     */
+    updatePassword(id: string, newPasswordHash: string): Promise<void>;
+    /**
+     * Optional helper to delete a user by user ID.
+     *
+     * @param id - Unique user ID
+     */
+    deleteUser?(id: string): Promise<void>;
+    /**
+     * Optional helper to find user directly by username.
+     *
+     * @param username - Username string
+     */
+    findUserByUsername?(username: string): Promise<UserCredentials | null>;
+}
+/**
+ * Interface for password hashing and verification algorithms.
+ *
+ * @remarks
+ * Lixa defaults to ScryptPasswordHasher (Node.js crypto.scrypt, 0 dependencies).
+ * Implement this interface to use custom algorithms (e.g. bcrypt, argon2, pbkdf2).
+ *
+ * @public
+ */
+export interface IPasswordHasher {
+    /**
+     * Computes a secure cryptographic hash for a plaintext password.
+     *
+     * @param password - Plaintext password
+     * @returns Formatted hash string containing salt and algorithm parameters
+     */
+    hash(password: string): Promise<string>;
+    /**
+     * Verifies a plaintext password against a stored hash string.
+     * Must use constant-time comparison to prevent timing attacks.
+     *
+     * @param password - Plaintext password to verify
+     * @param hash - Stored hash string
+     * @returns True if password matches hash, false otherwise
+     */
+    verify(password: string, hash: string): Promise<boolean>;
+}
+/**
+ * Configuration options for password validation rules.
+ *
+ * @public
+ */
+export interface PasswordPolicyConfig {
+    /**
+     * Minimum password length in characters.
+     *
+     * @default 8
+     */
+    minLength?: number | undefined;
+    /**
+     * Maximum password length in characters to prevent hashing DoS attacks.
+     *
+     * @default 128
+     */
+    maxLength?: number | undefined;
+    /**
+     * Require at least one uppercase letter [A-Z].
+     *
+     * @default false
+     */
+    requireUppercase?: boolean | undefined;
+    /**
+     * Require at least one lowercase letter [a-z].
+     *
+     * @default false
+     */
+    requireLowercase?: boolean | undefined;
+    /**
+     * Require at least one numeric digit [0-9].
+     *
+     * @default false
+     */
+    requireNumbers?: boolean | undefined;
+    /**
+     * Require at least one special symbol character.
+     *
+     * @default false
+     */
+    requireSpecialChars?: boolean | undefined;
+    /**
+     * Optional custom validator function for enterprise or custom rules.
+     * Return `true` if valid, or `false` / custom error message string if invalid.
+     */
+    customValidator?: ((password: string) => boolean | string | Promise<boolean | string>) | undefined;
+}
+/**
+ * Result of password policy validation.
+ *
+ * @public
+ */
+export interface PasswordPolicyResult {
+    /** Whether the password satisfied all configured rules */
+    valid: boolean;
+    /** List of human-readable error descriptions if validation failed */
+    errors: string[];
+}
+/**
+ * Configuration options for Credentials authentication in Lixa.
+ *
+ * @public
+ */
+export interface CredentialsConfig {
+    /**
+     * Explicitly enable or disable credentials authentication.
+     *
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Custom storage implementation for persisting user credentials.
+     * Defaults to LocalCredentialsStorage (in-memory, suitable for dev & testing).
+     */
+    storage?: CredentialsStorage | undefined;
+    /**
+     * Custom password hashing strategy.
+     * Defaults to ScryptPasswordHasher (Node.js crypto.scrypt).
+     */
+    hasher?: IPasswordHasher | undefined;
+    /**
+     * Password strength policy configuration.
+     */
+    policy?: PasswordPolicyConfig | undefined;
+    /**
+     * Supported identifier types for registration and sign-in:
+     * - 'email': Identifier must be a valid email format
+     * - 'username': Identifier can be any username string
+     * - 'both': Automatically detect email or username
+     *
+     * @default 'both'
+     */
+    identifierType?: ("email" | "username" | "both") | undefined;
+    /**
+     * Whether a username is strictly required during registration (signUp).
+     *
+     * @default false
+     */
+    requireUsername?: boolean | undefined;
+    /**
+     * Whether a valid email address is strictly required during registration (signUp).
+     *
+     * @default false
+     */
+    requireEmail?: boolean | undefined;
+    /**
+     * Whether to perform dummy hash verification on unknown users to mitigate timing attacks.
+     *
+     * @default true
+     */
+    timingAttackProtection?: boolean | undefined;
+    /**
+     * Whether to automatically generate and save a session upon successful registration (signUp).
+     *
+     * @default true
+     */
+    autoCreateSessionOnSignUp?: boolean | undefined;
+    /**
+     * Session expiration time in seconds for credentials-generated sessions.
+     *
+     * @default 86400 (24 hours)
+     */
+    sessionTtlSeconds?: number | undefined;
+}
+/**
+ * Parameters for user registration (signUp).
+ *
+ * @public
+ */
+export interface SignUpParams {
+    /** Username for the user (can be used directly instead of identifier) */
+    username?: string | undefined;
+    /** Primary identifier (username or email) */
+    identifier?: string | undefined;
+    /** Plaintext password */
+    password: string;
+    /** Optional explicit email address */
+    email?: string | undefined;
+    /** Optional custom user metadata */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * Result of user registration (signUp).
+ *
+ * @public
+ */
+export interface SignUpResult<TSession = Session> {
+    /** Created user credentials (with passwordHash omitted for safety) */
+    user: Omit<UserCredentials, "passwordHash">;
+    /** Created session ID if autoCreateSessionOnSignUp is enabled */
+    sessionId?: string | undefined;
+    /** Created session object if autoCreateSessionOnSignUp is enabled */
+    session?: TSession | undefined;
+}
+/**
+ * Parameters for user authentication (signIn).
+ *
+ * @public
+ */
+export interface SignInParams {
+    /** Username or email of the account */
+    username?: string | undefined;
+    /** Primary identifier (username or email) */
+    identifier?: string | undefined;
+    /** Plaintext password */
+    password: string;
+}
+/**
+ * Result of user authentication (signIn).
+ *
+ * @public
+ */
+export interface SignInResult<TSession = Session> {
+    /** Authenticated user credentials (with passwordHash omitted for safety) */
+    user: Omit<UserCredentials, "passwordHash">;
+    /** Active session ID */
+    sessionId: string;
+    /** Active session object */
+    session: TSession;
+}
+/**
+ * Parameters for raw credential verification without session creation.
+ *
+ * @public
+ */
+export interface VerifyCredentialsParams {
+    /** Username or email of the account */
+    username?: string | undefined;
+    /** Primary identifier (username or email) */
+    identifier?: string | undefined;
+    /** Plaintext password */
+    password: string;
+}
+/**
+ * Parameters for changing a user password.
+ *
+ * @public
+ */
+export interface ChangePasswordParams {
+    /** Username (optional if identifier or userId is provided) */
+    username?: string | undefined;
+    /** Primary identifier (optional if username or userId is provided) */
+    identifier?: string | undefined;
+    /** Unique user ID (optional if identifier or username is provided) */
+    userId?: string | undefined;
+    /** Current plaintext password */
+    oldPassword: string;
+    /** New plaintext password */
+    newPassword: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/credentials/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/credentials/types.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -87,4 +87,46 @@ export declare class AccountUnlinkError extends LixaError {
 export declare class RefreshTokenError extends LixaError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * Thrown when user credentials (username/email and password) are invalid during authentication.
+ *
+ * @public
+ */
+export declare class InvalidCredentialsError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when attempting to register a user with an identifier that already exists.
+ *
+ * @public
+ */
+export declare class UserAlreadyExistsError extends LixaError {
+    constructor(identifier: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a user account cannot be found for credential verification or password change.
+ *
+ * @public
+ */
+export declare class UserNotFoundError extends LixaError {
+    constructor(identifierOrId?: string, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a password does not satisfy configured password policy rules.
+ *
+ * @public
+ */
+export declare class WeakPasswordError extends LixaError {
+    readonly validationErrors: string[];
+    constructor(validationErrors?: string[], details?: Record<string, unknown>);
+}
+/**
+ * Thrown when credentials operations (signUp, signIn, etc.) are invoked on a Lixa instance
+ * where credentials authentication is not enabled.
+ *
+ * @public
+ */
+export declare class CredentialsNotConfiguredError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAEjD,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS5F;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,GAAE,MAAmC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG5F;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAShE;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE/B,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIhF;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,GAAE,MAAkD,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3G;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO9D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG/D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}