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

package/dist/export-types/index.d.ts

@@ -7,7 +7,7 @@
  * Key features:
  * - OAuth 2.0 authorization code flow with PKCE (RFC 6749, RFC 7636)
  * - OpenID Connect support
- * - Built-in providers available in \@vunexa/lixa-providers
+ * - Built-in providers available in \@vunexa/lixa-extensions/providers
  * - Custom provider support via IProvider interface
  * - Extensible session management via SessionDao.CreateSession
  * - Pluggable state and session storage via StateDao and SessionDao
@@ -132,6 +132,24 @@ export declare class AccountUnlinkError extends LixaError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
+/**
+ * Parameters for changing a user password.
+ *
+ * @public
+ */
+export declare 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;
+}
+
 /**
  * Generates an expired session cookie payload to clear the session on logout.
  *
@@ -271,6 +289,223 @@ export declare function createSessionCookie(sessionId: string, options?: CookieO
  */
 export declare function createStateCookie(state: string, options?: CookieOptions): CookiePayload;
 
+export declare namespace credentials {
+    export {
+        UserCredentials,
+        CredentialsStorage,
+        IPasswordHasher,
+        PasswordPolicyConfig,
+        PasswordPolicyResult,
+        CredentialsConfig,
+        SignUpParams,
+        SignUpResult,
+        SignInParams,
+        SignInResult,
+        VerifyCredentialsParams,
+        ChangePasswordParams,
+        ScryptHasherOptions,
+        ScryptPasswordHasher,
+        Pbkdf2HasherOptions,
+        Pbkdf2PasswordHasher,
+        validatePasswordPolicy,
+        LocalCredentialsStorage,
+        CredentialsManager
+    }
+}
+
+/**
+ * Configuration options for Credentials authentication in Lixa.
+ *
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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>);
+}
+
+/**
+ * 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 declare 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>;
+}
+
 /**
  * Decode JWT ID token to extract user information
  *
@@ -372,6 +607,15 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerM
  */
 export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
+/**
+ * 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 OAuth callback parameters (e.g. authorization code or state) are missing or malformed.
  *
@@ -399,6 +643,34 @@ export declare class InvalidStateError extends LixaError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
 
+/**
+ * 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 declare 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>;
+}
+
 /**
  * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
@@ -625,6 +897,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
     private localResourceHandler;
     private userResourceStore;
     private refreshMutexes;
+    private credentialsManager?;
     private config;
     private stateHandler;
     private sessionHandler;
@@ -664,7 +937,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * 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
      */
@@ -758,7 +1031,9 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<T> & {
         providers: T;
-    }): LixaConfig<T>;
+    }): LixaConfig<T> & {
+        providers: T;
+    };
     /**
      * Generates a cryptographically secure random state parameter for OAuth flows.
      *
@@ -996,6 +1271,58 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
+    /**
+     * Checks if credentials (username and password) authentication is configured and enabled.
+     *
+     * @returns True if credentials authentication is available
+     */
+    isCredentialsEnabled(): boolean;
+    /**
+     * Returns the underlying CredentialsManager instance if configured.
+     */
+    getCredentialsManager(): CredentialsManager | undefined;
+    /**
+     * 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
+     */
+    signUp(params: SignUpParams): Promise<SignUpResult>;
+    /**
+     * 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
+     */
+    signIn(params: SignInParams): Promise<SignInResult>;
+    /**
+     * 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
+     */
+    verifyCredentials(params: VerifyCredentialsParams): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    /**
+     * 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
+     */
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
     private findProviderByType;
 }
 
@@ -1010,7 +1337,11 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * Map of provider names to their configurations.
      * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
      */
-    providers: TProviders;
+    providers?: TProviders;
+    /**
+     * Credentials (username and password) authentication configuration.
+     */
+    credentials?: CredentialsConfig;
     /**
      * Account linking configuration for multi-SSO user linking.
      */
@@ -1085,11 +1416,30 @@ export declare interface LixaLogger {
     log(level: LogLevel, context: LogContext, message: string, data?: Record<string, unknown>): void;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Log context for Lixa structured logging.
  * @public
  */
-export declare type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource";
+export declare type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource" | "Credentials";
 
 /**
  * Log level for Lixa structured logging.
@@ -1146,6 +1496,102 @@ export declare interface OAuthTokenResponse {
     [key: string]: string | number | boolean | undefined;
 }
 
+/**
+ * Configuration options for password validation rules.
+ *
+ * @public
+ */
+export declare 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 declare interface PasswordPolicyResult {
+    /** Whether the password satisfied all configured rules */
+    valid: boolean;
+    /** List of human-readable error descriptions if validation failed */
+    errors: string[];
+}
+
+/**
+ * Options for PBKDF2 password hashing.
+ *
+ * @public
+ */
+export declare 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;
+}
+
 /**
  * Configuration for an OAuth provider instance.
  *
@@ -1305,6 +1751,61 @@ export declare type SafeLixaConfig<TProviders extends Record<string, ProviderCon
     providers: TProviders;
 };
 
+/**
+ * Options for Scrypt password hashing.
+ *
+ * @public
+ */
+export declare 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;
+}
+
 /**
  * Serializes a cookie name, value, and options into a standard `Set-Cookie` header string.
  *
@@ -1333,31 +1834,31 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
     /**
      * Unique session ID generated by Lixa upon authentication.
      */
-    id?: string;
+    id?: string | undefined;
     /**
      * Linked identity provider accounts (AuthN) keyed by provider name.
      * Single source of truth for all authenticated user SSO identities.
      */
-    accounts?: Record<string, LinkedAccount>;
+    accounts?: Record<string, LinkedAccount> | undefined;
     /**
      * Connected third-party resource provider tokens (AuthZ) keyed by provider name.
      * Single source of truth for all post-login third-party API permissions.
      */
-    resources?: Record<string, ConnectedResource>;
+    resources?: Record<string, ConnectedResource> | undefined;
     /** Unique unified user ID across linked accounts */
-    userId?: string;
+    userId?: string | undefined;
     /** Primary user email */
-    email?: string;
+    email?: string | undefined;
     /**
      * Optional primary access token or custom session token identifier.
      */
-    token?: string;
+    token?: string | undefined;
     /** Optional current active auth provider for this session turn */
-    provider?: string;
+    provider?: string | undefined;
     /**
      * Optional raw session token response data from provider.
      */
-    raw?: TRaw;
+    raw?: TRaw | undefined;
 }
 
 /**
@@ -1504,6 +2005,66 @@ export declare interface SessionStorage {
     } | null>;
 }
 
+/**
+ * Parameters for user authentication (signIn).
+ *
+ * @public
+ */
+export declare 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 declare 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 user registration (signUp).
+ *
+ * @public
+ */
+export declare 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 declare 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;
+}
+
 /**
  * OAuth state data structure.
  *
@@ -1707,6 +2268,39 @@ export declare class TokenExchangeError extends LixaError {
     constructor(message: string, status?: number, 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>);
+}
+
+/**
+ * User credentials entity representing stored account login information.
+ *
+ * @public
+ */
+export declare 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;
+}
+
 /**
  * User information extracted from OAuth provider
  *
@@ -1724,4 +2318,48 @@ export declare interface UserInfo {
     iss?: string | undefined;
 }
 
+/**
+ * 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>);
+}
+
+/**
+ * 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>;
+
+/**
+ * Parameters for raw credential verification without session creation.
+ *
+ * @public
+ */
+export declare interface VerifyCredentialsParams {
+    /** Username or email of the account */
+    username?: string | undefined;
+    /** Primary identifier (username or email) */
+    identifier?: string | undefined;
+    /** Plaintext password */
+    password: string;
+}
+
+/**
+ * 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>);
+}
+
 export { }