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

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
@@ -16,6 +16,15 @@
  * @packageDocumentation
  */
 
+/**
+ * Account handler configuration.
+ *
+ * @public
+ */
+export declare interface AccountHandler {
+    accountStorage?: AccountStorage;
+}
+
 /**
  * Account linking settings for Lixa.
  *
@@ -123,6 +132,18 @@ export declare enum AccountLinkingStrategy {
     ISOLATED = "ISOLATED"
 }
 
+/**
+ * Interface for persistent linked account storage across user sessions.
+ *
+ * @public
+ */
+export declare interface AccountStorage {
+    saveAccount(userId: string, provider: string, account: LinkedAccount): Promise<void>;
+    getAccount(userId: string, provider: string): Promise<LinkedAccount | null>;
+    getUserAccounts(userId: string): Promise<Record<string, LinkedAccount>>;
+    deleteAccount(userId: string, provider: string): Promise<void>;
+}
+
 /**
  * Thrown when unlinking an account violates security constraints (e.g. unlinking the only login provider).
  *
@@ -132,6 +153,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.
  *
@@ -161,7 +200,33 @@ export declare function clearStateCookie(options?: CookieOptions): CookiePayload
 /**
  * Type representing the keys of configured providers
  */
-declare type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
+declare type ConfiguredProviderKey<TProviders extends Record<string, ProviderConfig>> = keyof TProviders & string;
+
+/**
+ * Parameters for confirming a password reset with a confirmation code or token.
+ *
+ * @public
+ */
+export declare interface ConfirmPasswordResetParams {
+    /** Username or email of the account */
+    identifier: string;
+    /** Verification code (e.g. 6-digit OTP from email/SMS) or reset token */
+    confirmationCode: string;
+    /** New plaintext password */
+    newPassword: string;
+}
+
+/**
+ * Parameters for confirming user registration with a verification code.
+ *
+ * @public
+ */
+export declare interface ConfirmSignUpParams {
+    /** Username or email of the account to confirm */
+    identifier: string;
+    /** Verification code (e.g. 6-digit OTP from email/SMS) */
+    confirmationCode: string;
+}
 
 /**
  * Represents a connected resource provider token (e.g. GitHub Repo access, Google Drive)
@@ -271,6 +336,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 +654,209 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerM
  */
 export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
+/**
+ * Parameters for requesting a password reset (forgot password).
+ *
+ * @public
+ */
+export declare interface ForgotPasswordParams {
+    /** Username or email of the account requesting a password reset */
+    identifier: string;
+    /** Optional custom client metadata or redirect URL */
+    metadata?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result of a password reset request.
+ *
+ * @public
+ */
+export declare interface ForgotPasswordResult {
+    /** Whether the password reset request was accepted */
+    success: boolean;
+    /** Delivery destination description (e.g. masked email: a***@example.com or phone) */
+    deliveryMedium?: string | undefined;
+    /** Optional message or status code from provider */
+    message?: string | undefined;
+}
+
+export declare namespace identity {
+    export {
+        UserIdentity,
+        IdentityTokens,
+        IdentityAuthResult,
+        ForgotPasswordParams,
+        ForgotPasswordResult,
+        ConfirmPasswordResetParams,
+        ConfirmSignUpParams,
+        ResendConfirmationCodeParams,
+        ResendConfirmationCodeResult,
+        IIdentityProvider,
+        IdentityConfig,
+        SelfManagedIdentityProvider
+    }
+}
+
+/**
+ * Result of user authentication through an identity provider.
+ *
+ * @public
+ */
+export declare interface IdentityAuthResult {
+    /** Authenticated user profile */
+    user: UserIdentity;
+    /** Optional tokens issued by the identity provider */
+    tokens?: IdentityTokens | undefined;
+}
+
+/**
+ * Configuration options for Identity Providers in LixaConfig.
+ *
+ * @public
+ */
+export declare type IdentityConfig = IIdentityProvider | ({
+    provider?: "self-managed";
+} & CredentialsConfig);
+
+/**
+ * Thrown when identity operations (signUp, signIn, etc.) are invoked on a Lixa instance
+ * where neither identity nor credentials authentication is enabled.
+ *
+ * @public
+ */
+export declare class IdentityNotConfiguredError extends CredentialsNotConfiguredError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when an identity provider operation fails with an upstream provider error.
+ *
+ * @public
+ */
+export declare class IdentityProviderError extends LixaError {
+    readonly provider: string | undefined;
+    readonly statusCode: number | undefined;
+    constructor(message: string, provider?: string, statusCode?: number, details?: Record<string, unknown>);
+}
+
+/**
+ * Standardized token response from an identity provider.
+ *
+ * @public
+ */
+export declare interface IdentityTokens {
+    /** OAuth / IdP Access Token (JWT or opaque token) */
+    accessToken?: string | undefined;
+    /** OpenID Connect ID Token containing user claims */
+    idToken?: string | undefined;
+    /** Refresh token for renewing expired credentials */
+    refreshToken?: string | undefined;
+    /** Token type (usually "Bearer") */
+    tokenType?: string | undefined;
+    /** Token expiration time in seconds */
+    expiresIn?: number | undefined;
+    /** Raw response object returned directly by the provider */
+    raw?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Unified interface for Identity Providers in Lixa.
+ *
+ * @remarks
+ * Implement this interface to create custom identity providers (e.g. Supabase Auth,
+ * Firebase Auth, Keycloak, or proprietary enterprise directories).
+ *
+ * Built-in extensions for AWS Cognito, Auth0, and Okta are available in `@vunexa/lixa-extensions`.
+ *
+ * @public
+ */
+export declare interface IIdentityProvider {
+    /**
+     * Unique name of the identity provider.
+     * Examples: 'self-managed', 'cognito', 'auth0', 'okta'
+     */
+    readonly name: string;
+    /**
+     * Registers a new user with the identity provider.
+     *
+     * @param params - User registration details (identifier, password, email, username, metadata)
+     * @returns Created user identity
+     */
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    /**
+     * Authenticates a user with credentials.
+     *
+     * @param params - Sign in credentials (identifier, password)
+     * @returns Authenticated user identity and optional provider tokens
+     */
+    signIn(params: SignInParams): Promise<IdentityAuthResult>;
+    /**
+     * Verifies credentials without necessarily creating a full session.
+     *
+     * @param params - Verification parameters
+     * @returns User identity if credentials are valid, null otherwise
+     */
+    verifyCredentials?(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
+    /**
+     * Changes a user's password.
+     *
+     * @param params - Old password, new password, and user identifier
+     * @returns True if password was successfully updated
+     */
+    changePassword?(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Requests a password reset (forgot password flow).
+     *
+     * @param params - Forgot password parameters
+     */
+    forgotPassword?(params: ForgotPasswordParams): Promise<ForgotPasswordResult>;
+    /**
+     * Confirms password reset with verification code and new password.
+     *
+     * @param params - Confirm password reset parameters
+     */
+    confirmPasswordReset?(params: ConfirmPasswordResetParams): Promise<boolean>;
+    /**
+     * Confirms user registration using a verification code.
+     *
+     * @param params - Confirm sign up parameters
+     */
+    confirmSignUp?(params: ConfirmSignUpParams): Promise<boolean>;
+    /**
+     * Resends the sign up confirmation code.
+     *
+     * @param params - Resend confirmation code parameters
+     */
+    resendConfirmationCode?(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    /**
+     * Retrieves a user by their unique ID.
+     *
+     * @param id - Unique user ID
+     */
+    getUserById?(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (email or username).
+     *
+     * @param identifier - Username or email string
+     */
+    getUserByIdentifier?(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user account.
+     *
+     * @param id - Unique user ID
+     */
+    deleteUser?(id: string): Promise<void>;
+}
+
+/**
+ * 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 +884,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.
  *
@@ -537,6 +1050,10 @@ export declare interface IProvider {
      * @example ['openid', 'email', 'profile'] or ['read:user', 'user:email']
      */
     authScopes?: string[];
+    /**
+     * Default OAuth scopes requested when not explicitly specified in ProviderConfig.
+     */
+    defaultScopes?: string[];
 }
 
 /**
@@ -550,7 +1067,7 @@ export declare function isProductionEnvironment(): boolean;
  *
  * @public
  */
-declare interface LinkedAccount {
+export declare interface LinkedAccount {
     /** The provider identifier (e.g. 'github', 'google') */
     provider: string;
     /** Provider user ID if available */
@@ -617,19 +1134,25 @@ declare interface LinkedAccount {
  *
  * @public
  */
-export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     private static DEFAULT_PROVIDERS;
     private static CONFIGURED_PROVIDERS;
     private localStateHandler;
     private localSessionHandler;
     private localResourceHandler;
+    private localAccountHandler;
     private userResourceStore;
+    private userAccountStore;
     private refreshMutexes;
+    private identityProvider?;
+    private credentialsManager?;
     private config;
     private stateHandler;
     private sessionHandler;
     private resourceHandler;
+    private accountHandler;
     private debug;
+    private sessionCookieResolver?;
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
@@ -643,7 +1166,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * @throws Error when provider implementation is missing required properties
      * @throws Error when provider is not available and no inline implementation is provided
      */
-    constructor(config: TConfig);
+    constructor(config: LixaConfig<TProviders>);
     /**
      * Validates that a provider configuration has all required credentials.
      *
@@ -664,7 +1187,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
      */
@@ -684,7 +1207,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * }
      * ```
      */
-    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TProviders>;
     /**
      * Gets a provider implementation by name.
      * Resolution priority: inline custom provider \> default providers \> legacy registry
@@ -758,7 +1281,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.
      *
@@ -863,7 +1388,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * res.redirect(authUrl);
      * ```
      */
-    getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
+    getAuthUrl(provider: ConfiguredProviderKey<TProviders> | string, state?: string): Promise<string>;
     /**
      * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
      */
@@ -887,10 +1412,11 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * });
      * ```
      */
-    handleCallback({ provider, code, state, }: {
-        provider: ConfiguredProviderKey<TConfig> | string;
+    handleCallback({ provider, code, state, sessionId, }: {
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
+        sessionId?: string;
     }): Promise<string>;
     /**
      * Explicitly link a new OAuth provider account to an active session.
@@ -900,7 +1426,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     linkAccount(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
     }): Promise<string>;
@@ -925,8 +1451,8 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     getResourceAuthUrl(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
-        scopes: string[];
+        provider: ConfiguredProviderKey<TProviders> | string;
+        scopes?: string[];
         state?: string;
         prompt?: string;
         extraConfig?: Record<string, string>;
@@ -937,11 +1463,32 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     handleResourceCallback(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
         scopes?: string[];
     }): Promise<Session>;
+    /**
+     * Retrieves configured default resource scopes for a provider.
+     *
+     * @param provider - Provider name (e.g. 'github', 'google')
+     * @returns Array of configured resource scopes, or undefined if not configured
+     */
+    getResourceScopes(provider: ConfiguredProviderKey<TProviders> | string): string[] | undefined;
+    /**
+     * Returns the resolved session cookie name.
+     * Dynamically reflects any changes to the active identity provider.
+     *
+     * @param req - Optional request object for multi-tenant request-scoped cookie resolution
+     * @returns Resolved session cookie name
+     */
+    getSessionCookieName(req?: unknown): string;
+    /**
+     * Sets or updates the session cookie name or dynamic resolver on this instance.
+     *
+     * @param resolver - Static cookie name or dynamic resolver function
+     */
+    setSessionCookieName(resolver: SessionCookieResolver<Lixa<TProviders>>): void;
     /**
      * Retrieves a connected resource for a specific User ID / Email directly (independent of session IDs).
      * Automatically refreshes expired access tokens if a refresh token is present.
@@ -996,10 +1543,130 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
-    private findProviderByType;
-}
-
-/**
+    /**
+     * Checks if an identity provider (Self-Managed Database, AWS Cognito, Auth0, Okta, etc.) is configured.
+     *
+     * @returns True if identity provider is configured and available
+     */
+    isIdentityEnabled(): boolean;
+    /**
+     * Checks if credentials / identity authentication is configured and enabled.
+     *
+     * @returns True if credentials / identity authentication is available
+     */
+    isCredentialsEnabled(): boolean;
+    /**
+     * Returns the configured IdentityProvider instance.
+     */
+    getIdentityProvider(): IIdentityProvider | undefined;
+    /**
+     * Dynamically sets or updates the active identity provider (e.g. SelfManaged, Cognito, Auth0, Okta).
+     *
+     * @param provider - Identity provider instance or undefined to disable
+     */
+    setIdentityProvider(provider?: IIdentityProvider): void;
+    /**
+     * Returns the underlying CredentialsManager instance if using Self-Managed identity.
+     */
+    getCredentialsManager(): CredentialsManager | undefined;
+    /**
+     * Registers a new user with the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+     * Automatically creates an active session unless autoCreateSessionOnSignUp is explicitly set to false.
+     *
+     * @param params - Registration parameters (identifier, password, email, username, metadata)
+     * @returns Created user identity and optional active session
+     * @throws WeakPasswordError if password does not meet policy requirements
+     * @throws UserAlreadyExistsError if identifier is already registered
+     * @throws IdentityNotConfiguredError if identity authentication is not configured
+     */
+    signUp(params: SignUpParams): Promise<SignUpResult>;
+    /**
+     * Authenticates a user with credentials via the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+     * Creates an active session and automatically links with existing sessions when AUTO_LINK_BY_VERIFIED_EMAIL is configured.
+     *
+     * @param params - Sign-in parameters (identifier, password)
+     * @returns Authenticated user, session ID, and session object
+     * @throws InvalidCredentialsError if authentication fails
+     * @throws IdentityNotConfiguredError if identity authentication 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/identity or null if invalid
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | 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 IdentityNotConfiguredError if identity auth is not configured
+     */
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Initiates a password reset (forgot password flow) through the configured identity provider.
+     *
+     * @param params - Forgot password parameters (identifier, optional metadata)
+     * @returns ForgotPasswordResult indicating status and delivery medium (email/SMS)
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    forgotPassword(params: ForgotPasswordParams): Promise<ForgotPasswordResult>;
+    /**
+     * Confirms a password reset using a verification code / token and sets the new password.
+     *
+     * @param params - Verification code, identifier, and new password
+     * @returns True if password reset was successfully confirmed
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    confirmPasswordReset(params: ConfirmPasswordResetParams): Promise<boolean>;
+    /**
+     * Confirms user account registration using a verification code.
+     *
+     * @param params - Verification parameters including identifier and confirmationCode
+     * @returns True if confirmation was successful
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     * @throws IdentityProviderError if identity provider does not support confirmation
+     */
+    confirmSignUp(params: ConfirmSignUpParams): Promise<boolean>;
+    /**
+     * Resends the sign up confirmation code to the user.
+     *
+     * @param params - Resend parameters including user identifier
+     * @returns Details about the code delivery (medium, destination)
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     * @throws IdentityProviderError if identity provider does not support resending codes
+     */
+    resendConfirmationCode(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    /**
+     * Retrieves a user by their unique ID from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     * @returns UserIdentity or null if not found
+     */
+    getUserById(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (username or email) from the configured identity provider.
+     *
+     * @param identifier - Username or email string
+     * @returns UserIdentity or null if not found
+     */
+    getUserByIdentifier(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user account from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     */
+    deleteUser(id: string): Promise<void>;
+    private findProviderByType;
+}
+
+/**
  * Main configuration object for Lixa.
  * Provides type-safe provider name inference.
  *
@@ -1007,14 +1674,50 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
  */
 export declare interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     /**
-     * Map of provider names to their configurations.
+     * Map of federated OAuth 2.0 / OIDC provider names to their configurations (Google, GitHub, etc.)
+     * that federate with and work alongside the primary identityProvider.
      * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
      */
-    providers: TProviders;
+    federatedOAuthProviders?: TProviders;
+    /**
+     * Alias for {@link LixaConfig.federatedOAuthProviders}.
+     */
+    providers?: TProviders;
+    /**
+     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta, or custom IIdentityProvider).
+     *
+     * @example
+     * Self-managed with Prisma:
+     * ```typescript
+     * identityProvider: { storage: prismaAdapter.credentialsStorage }
+     * ```
+     *
+     * @example
+     * AWS Cognito:
+     * ```typescript
+     * identityProvider: new CognitoIdentityProvider({ userPoolId: '...', clientId: '...', region: 'us-east-1' })
+     * ```
+     */
+    identityProvider?: IIdentityProvider | IdentityConfig;
+    /**
+     * Alias for {@link LixaConfig.identityProvider}.
+     */
+    identity?: IIdentityProvider | IdentityConfig;
+    /**
+     * Credentials (username and password) authentication configuration.
+     * Automatically maps to a SelfManagedIdentityProvider.
+     */
+    credentials?: CredentialsConfig;
+    /**
+     * Unified database storage adapter (e.g. createPrismaAdapter or createDrizzleAdapter).
+     * Automatically configures sessionHandler, stateHandler, and resourceHandler.
+     */
+    storage?: StorageAdapter;
     /**
      * Account linking configuration for multi-SSO user linking.
+     * Pass `true` or `"linkByEmail"` for automatic email-verified linking.
      */
-    accountLinking?: AccountLinkingConfig;
+    accountLinking?: boolean | AccountLinkingMode | AccountLinkingConfig;
     /**
      * Optional custom state handler.
      * Handles state generation and storage during OAuth authorization flow.
@@ -1058,6 +1761,23 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * If provided, all Lixa logs will be routed through this logger.
      */
     logger?: LixaLogger;
+    /**
+     * Session cookie name or dynamic resolution function.
+     * Can accept a static string or `(lixa: Lixa, req?: unknown) => string`.
+     * Automatically evaluated live against the instance when getSessionCookieName() is called.
+     */
+    sessionCookieName?: SessionCookieResolver;
+}
+
+/**
+ * Interface exposing identity information for dynamic session cookie name resolution.
+ * @public
+ */
+export declare interface LixaCookieContext {
+    /**
+     * Retrieves the currently active identity provider.
+     */
+    getIdentityProvider(): IIdentityProvider | undefined;
 }
 
 /**
@@ -1085,11 +1805,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" | "Identity";
 
 /**
  * Log level for Lixa structured logging.
@@ -1146,6 +1885,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.
  *
@@ -1189,8 +2024,13 @@ export declare type ProviderConfig = {
     clientSecret: string;
     /** The redirect URI registered with the provider */
     redirectUri: string;
-    /** Array of OAuth scopes to request */
-    scopes: string[];
+    /** Array of OAuth scopes to request. If omitted, uses provider default identity scopes. */
+    scopes?: string[];
+    /**
+     * Default scopes requested when connecting this provider as a third-party resource (AuthZ).
+     * Used automatically by getResourceAuthUrl() and handleResourceCallback() if not overridden at runtime.
+     */
+    resourceScopes?: string[];
     /**
      * Set to true to allow non-identity (resource) scopes during primary authentication flow.
      * By default (false), Lixa restricts primary AuthN scopes to identity scopes to maintain
@@ -1243,6 +2083,30 @@ export declare class RefreshTokenError extends LixaError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
+/**
+ * Parameters for resending a sign up confirmation code.
+ *
+ * @public
+ */
+export declare interface ResendConfirmationCodeParams {
+    /** Username or email of the account */
+    identifier: string;
+}
+
+/**
+ * Result of resending a sign up confirmation code.
+ *
+ * @public
+ */
+export declare interface ResendConfirmationCodeResult {
+    /** True if code was dispatched */
+    success: boolean;
+    /** Delivery medium (e.g. 'EMAIL' or 'SMS') */
+    deliveryMedium?: string | undefined;
+    /** Obscured destination */
+    destination?: string | undefined;
+}
+
 /**
  * Resource handler configuration.
  *
@@ -1305,6 +2169,110 @@ 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;
+}
+
+/**
+ * Self-Managed Identity Provider implementation for Lixa.
+ *
+ * @remarks
+ * Backed by custom database storage (Prisma, Drizzle, PostgreSQL, SQLite, MongoDB)
+ * or local in-memory storage, with cryptographic password hashing (Scrypt, Argon2, PBKDF2)
+ * and configurable password policy enforcement.
+ *
+ * @public
+ */
+export declare class SelfManagedIdentityProvider implements IIdentityProvider {
+    readonly name: string;
+    private readonly manager;
+    constructor(configOrManager?: CredentialsConfig | CredentialsManager);
+    private mapUser;
+    /**
+     * Registers a new user.
+     */
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    /**
+     * Authenticates a user with password.
+     */
+    signIn(params: SignInParams): Promise<IdentityAuthResult>;
+    /**
+     * Verifies credentials without throwing an error if invalid.
+     */
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
+    /**
+     * Changes a user's password.
+     */
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Retrieves a user by their unique ID.
+     */
+    getUserById(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (email or username).
+     */
+    getUserByIdentifier(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user from storage if supported by the storage adapter.
+     */
+    deleteUser(id: string): Promise<void>;
+    /**
+     * Returns the underlying CredentialsManager instance.
+     */
+    getCredentialsManager(): CredentialsManager;
+}
+
 /**
  * Serializes a cookie name, value, and options into a standard `Set-Cookie` header string.
  *
@@ -1331,35 +2299,43 @@ export declare function serializeCookie(name: string, value: string, options?: C
  */
 export declare interface Session<TRaw = OAuthTokenResponse> {
     /**
-     * Unique session ID generated by Lixa upon authentication.
+     * Unique canonical session ID generated by Lixa upon authentication.
      */
-    id?: string;
+    sessionId?: 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;
 }
 
+/**
+ * Dynamic resolver for session cookie name.
+ * Can be a static string or a dynamic callback receiving the Lixa instance and an optional request context.
+ *
+ * @public
+ */
+export declare type SessionCookieResolver<TContext extends LixaCookieContext = LixaCookieContext> = string | ((lixa: TContext, req?: unknown) => string);
+
 /**
  * Session handler for OAuth authentication.
  *
@@ -1504,6 +2480,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, TUser = UserIdentity> {
+    /** Authenticated user profile / credentials (with passwordHash omitted for safety) */
+    user: TUser;
+    /** 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, TUser = UserIdentity> {
+    /** Created user profile / credentials (with passwordHash omitted for safety) */
+    user: TUser;
+    /** Created session ID if autoCreateSessionOnSignUp is enabled */
+    sessionId?: string | undefined;
+    /** Created session object if autoCreateSessionOnSignUp is enabled */
+    session?: TSession | undefined;
+}
+
 /**
  * OAuth state data structure.
  *
@@ -1697,6 +2733,19 @@ export declare interface StateStorage {
     deleteState(state: string): Promise<void>;
 }
 
+/**
+ * Unified storage adapter interface (e.g. Prisma or Drizzle adapter).
+ * When provided to Lixa via config.storage, automatically configures session, state, and resource storage.
+ * @public
+ */
+declare interface StorageAdapter {
+    sessionStorage?: any;
+    resourceStorage?: any;
+    stateStorage?: any;
+    credentialsStorage?: any;
+    accountStorage?: any;
+}
+
 /**
  * Thrown when exchanging an authorization code for OAuth tokens fails at the provider endpoint.
  *
@@ -1707,6 +2756,66 @@ 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;
+}
+
+/**
+ * Standardized user identity representation across all identity providers
+ * (Self-Managed Database, AWS Cognito, Auth0, Okta, Firebase, etc.).
+ *
+ * @public
+ */
+export declare interface UserIdentity {
+    /** Unique user identifier (UUID, Sub, Auth0 user_id, Okta id) */
+    id: string;
+    /** Primary unique lookup identifier (email or username) */
+    identifier: string;
+    /** Associated email address if available */
+    email?: string | undefined;
+    /** Username of the account if available */
+    username?: string | undefined;
+    /** Whether the email address has been verified by the identity provider */
+    emailVerified?: boolean | undefined;
+    /** Unix timestamp in milliseconds when user was created */
+    createdAt?: number | undefined;
+    /** Unix timestamp in milliseconds when user was last updated */
+    updatedAt?: number | undefined;
+    /** Custom user metadata or profile attributes */
+    metadata?: Record<string, unknown> | undefined;
+    /** Identity provider name (e.g. "self-managed", "cognito", "auth0", "okta") */
+    provider?: string | undefined;
+}
+
 /**
  * User information extracted from OAuth provider
  *
@@ -1724,4 +2833,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 { }