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

package/dist/index.d.cts

@@ -101,9 +101,9 @@ interface ConnectedResource {
  */
 interface Session<TRaw = OAuthTokenResponse> {
     /**
-     * Unique session ID generated by Lixa upon authentication.
+     * Unique canonical session ID generated by Lixa upon authentication.
      */
-    id?: string | undefined;
+    sessionId?: string | undefined;
     /**
      * Linked identity provider accounts (AuthN) keyed by provider name.
      * Single source of truth for all authenticated user SSO identities.
@@ -427,6 +427,25 @@ interface ResourceStorage {
 interface ResourceHandler {
     resourceStorage?: ResourceStorage;
 }
+/**
+ * Interface for persistent linked account storage across user sessions.
+ *
+ * @public
+ */
+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>;
+}
+/**
+ * Account handler configuration.
+ *
+ * @public
+ */
+interface AccountHandler {
+    accountStorage?: AccountStorage;
+}
 /**
  * Session handler for OAuth authentication.
  *
@@ -658,8 +677,235 @@ 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[];
 }
 
+/**
+ * Standardized user identity representation across all identity providers
+ * (Self-Managed Database, AWS Cognito, Auth0, Okta, Firebase, etc.).
+ *
+ * @public
+ */
+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;
+}
+/**
+ * Standardized token response from an identity provider.
+ *
+ * @public
+ */
+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;
+}
+/**
+ * Result of user authentication through an identity provider.
+ *
+ * @public
+ */
+interface IdentityAuthResult {
+    /** Authenticated user profile */
+    user: UserIdentity;
+    /** Optional tokens issued by the identity provider */
+    tokens?: IdentityTokens | undefined;
+}
+/**
+ * Parameters for requesting a password reset (forgot password).
+ *
+ * @public
+ */
+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
+ */
+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;
+}
+/**
+ * Parameters for confirming a password reset with a confirmation code or token.
+ *
+ * @public
+ */
+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
+ */
+interface ConfirmSignUpParams {
+    /** Username or email of the account to confirm */
+    identifier: string;
+    /** Verification code (e.g. 6-digit OTP from email/SMS) */
+    confirmationCode: string;
+}
+/**
+ * Parameters for resending a sign up confirmation code.
+ *
+ * @public
+ */
+interface ResendConfirmationCodeParams {
+    /** Username or email of the account */
+    identifier: string;
+}
+/**
+ * Result of resending a sign up confirmation code.
+ *
+ * @public
+ */
+interface ResendConfirmationCodeResult {
+    /** True if code was dispatched */
+    success: boolean;
+    /** Delivery medium (e.g. 'EMAIL' or 'SMS') */
+    deliveryMedium?: string | undefined;
+    /** Obscured destination */
+    destination?: string | 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
+ */
+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>;
+}
+/**
+ * Configuration options for Identity Providers in LixaConfig.
+ *
+ * @public
+ */
+type IdentityConfig = IIdentityProvider | ({
+    provider?: "self-managed";
+} & CredentialsConfig);
+
 /**
  * User credentials entity representing stored account login information.
  *
@@ -908,9 +1154,9 @@ interface SignUpParams {
  *
  * @public
  */
-interface SignUpResult<TSession = Session> {
-    /** Created user credentials (with passwordHash omitted for safety) */
-    user: Omit<UserCredentials, "passwordHash">;
+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 */
@@ -934,9 +1180,9 @@ interface SignInParams {
  *
  * @public
  */
-interface SignInResult<TSession = Session> {
-    /** Authenticated user credentials (with passwordHash omitted for safety) */
-    user: Omit<UserCredentials, "passwordHash">;
+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 */
@@ -1154,6 +1400,55 @@ declare class CredentialsManager {
     getHasher(): IPasswordHasher;
 }
 
+/**
+ * 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
+ */
+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;
+}
+
 /**
  * Configuration for an OAuth provider instance.
  *
@@ -1197,8 +1492,13 @@ 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
@@ -1316,6 +1616,18 @@ interface AccountLinkingConfig {
      */
     requireVerifiedEmail?: boolean;
 }
+/**
+ * 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
+ */
+interface StorageAdapter {
+    sessionStorage?: any;
+    resourceStorage?: any;
+    stateStorage?: any;
+    credentialsStorage?: any;
+    accountStorage?: any;
+}
 /**
  * Main configuration object for Lixa.
  * Provides type-safe provider name inference.
@@ -1324,18 +1636,50 @@ interface AccountLinkingConfig {
  */
 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().
      */
+    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.
@@ -1379,7 +1723,30 @@ interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<
      * 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
+ */
+interface LixaCookieContext {
+    /**
+     * Retrieves the currently active identity provider.
+     */
+    getIdentityProvider(): IIdentityProvider | 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
+ */
+type SessionCookieResolver<TContext extends LixaCookieContext = LixaCookieContext> = string | ((lixa: TContext, req?: unknown) => string);
 /**
  * Log level for Lixa structured logging.
  * @public
@@ -1389,7 +1756,7 @@ type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
  * Log context for Lixa structured logging.
  * @public
  */
-type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource" | "Credentials";
+type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource" | "Credentials" | "Identity";
 /**
  * Custom logger interface for Lixa.
  * @public
@@ -1413,7 +1780,7 @@ type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaCon
 /**
  * Type representing the keys of configured providers
  */
-type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
+type ConfiguredProviderKey<TProviders extends Record<string, ProviderConfig>> = keyof TProviders & string;
 /**
  * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
  *
@@ -1466,20 +1833,25 @@ type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>>
  *
  * @public
  */
-declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+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.
      *
@@ -1493,7 +1865,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * @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.
      *
@@ -1534,7 +1906,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * }
      * ```
      */
-    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
@@ -1715,7 +2087,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * 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.
      */
@@ -1739,10 +2111,11 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * });
      * ```
      */
-    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.
@@ -1752,7 +2125,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     linkAccount(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
     }): Promise<string>;
@@ -1777,8 +2150,8 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     getResourceAuthUrl(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
-        scopes: string[];
+        provider: ConfiguredProviderKey<TProviders> | string;
+        scopes?: string[];
         state?: string;
         prompt?: string;
         extraConfig?: Record<string, string>;
@@ -1789,11 +2162,32 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     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.
@@ -1849,46 +2243,60 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
     deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
     /**
-     * Checks if credentials (username and password) authentication is configured and enabled.
+     * Checks if an identity provider (Self-Managed Database, AWS Cognito, Auth0, Okta, etc.) is configured.
      *
-     * @returns True if credentials authentication is available
+     * @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 underlying CredentialsManager instance if configured.
+     * 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 username/email and password.
-     * Automatically enforces password policy, hashes password with Scrypt/configured hasher,
-     * stores credentials, and creates a session (unless autoCreateSessionOnSignUp is false).
+     * 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 (without password hash) and optional active session
+     * @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 CredentialsNotConfiguredError if credentials auth is not configured
+     * @throws IdentityNotConfiguredError if identity authentication 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.
+     * 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 CredentialsNotConfiguredError if credentials auth is not configured
+     * @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 (without password hash) or null if invalid
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @returns User credentials/identity or null if invalid
+     * @throws IdentityNotConfiguredError if identity auth is not configured
      */
-    verifyCredentials(params: VerifyCredentialsParams): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
     /**
      * Updates a user's password after verifying the current password and enforcing policy on the new password.
      *
@@ -1897,9 +2305,63 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      * @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
+     * @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;
 }
 
@@ -2115,6 +2577,25 @@ declare class WeakPasswordError extends LixaError {
 declare class CredentialsNotConfiguredError extends LixaError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
+/**
+ * Thrown when an identity provider operation fails with an upstream provider error.
+ *
+ * @public
+ */
+declare class IdentityProviderError extends LixaError {
+    readonly provider: string | undefined;
+    readonly statusCode: number | undefined;
+    constructor(message: string, provider?: string, statusCode?: number, details?: Record<string, unknown>);
+}
+/**
+ * Thrown when identity operations (signUp, signIn, etc.) are invoked on a Lixa instance
+ * where neither identity nor credentials authentication is enabled.
+ *
+ * @public
+ */
+declare class IdentityNotConfiguredError extends CredentialsNotConfiguredError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
 
 /**
  * Sensible default cookie configuration options.
@@ -2258,31 +2739,48 @@ declare function createStateCookie(state: string, options?: CookieOptions): Cook
  */
 declare function clearStateCookie(options?: CookieOptions): CookiePayload;
 
-type index_ChangePasswordParams = ChangePasswordParams;
-type index_CredentialsConfig = CredentialsConfig;
-type index_CredentialsManager = CredentialsManager;
-declare const index_CredentialsManager: typeof CredentialsManager;
-type index_CredentialsStorage = CredentialsStorage;
-type index_IPasswordHasher = IPasswordHasher;
-type index_LocalCredentialsStorage = LocalCredentialsStorage;
-declare const index_LocalCredentialsStorage: typeof LocalCredentialsStorage;
-type index_PasswordPolicyConfig = PasswordPolicyConfig;
-type index_PasswordPolicyResult = PasswordPolicyResult;
-type index_Pbkdf2HasherOptions = Pbkdf2HasherOptions;
-type index_Pbkdf2PasswordHasher = Pbkdf2PasswordHasher;
-declare const index_Pbkdf2PasswordHasher: typeof Pbkdf2PasswordHasher;
-type index_ScryptHasherOptions = ScryptHasherOptions;
-type index_ScryptPasswordHasher = ScryptPasswordHasher;
-declare const index_ScryptPasswordHasher: typeof ScryptPasswordHasher;
-type index_SignInParams = SignInParams;
-type index_SignInResult<TSession = Session> = SignInResult<TSession>;
-type index_SignUpParams = SignUpParams;
-type index_SignUpResult<TSession = Session> = SignUpResult<TSession>;
-type index_UserCredentials = UserCredentials;
-type index_VerifyCredentialsParams = VerifyCredentialsParams;
-declare const index_validatePasswordPolicy: typeof validatePasswordPolicy;
+type index$1_ChangePasswordParams = ChangePasswordParams;
+type index$1_CredentialsConfig = CredentialsConfig;
+type index$1_CredentialsManager = CredentialsManager;
+declare const index$1_CredentialsManager: typeof CredentialsManager;
+type index$1_CredentialsStorage = CredentialsStorage;
+type index$1_IPasswordHasher = IPasswordHasher;
+type index$1_LocalCredentialsStorage = LocalCredentialsStorage;
+declare const index$1_LocalCredentialsStorage: typeof LocalCredentialsStorage;
+type index$1_PasswordPolicyConfig = PasswordPolicyConfig;
+type index$1_PasswordPolicyResult = PasswordPolicyResult;
+type index$1_Pbkdf2HasherOptions = Pbkdf2HasherOptions;
+type index$1_Pbkdf2PasswordHasher = Pbkdf2PasswordHasher;
+declare const index$1_Pbkdf2PasswordHasher: typeof Pbkdf2PasswordHasher;
+type index$1_ScryptHasherOptions = ScryptHasherOptions;
+type index$1_ScryptPasswordHasher = ScryptPasswordHasher;
+declare const index$1_ScryptPasswordHasher: typeof ScryptPasswordHasher;
+type index$1_SignInParams = SignInParams;
+type index$1_SignInResult<TSession = Session, TUser = UserIdentity> = SignInResult<TSession, TUser>;
+type index$1_SignUpParams = SignUpParams;
+type index$1_SignUpResult<TSession = Session, TUser = UserIdentity> = SignUpResult<TSession, TUser>;
+type index$1_UserCredentials = UserCredentials;
+type index$1_VerifyCredentialsParams = VerifyCredentialsParams;
+declare const index$1_validatePasswordPolicy: typeof validatePasswordPolicy;
+declare namespace index$1 {
+  export { type index$1_ChangePasswordParams as ChangePasswordParams, type index$1_CredentialsConfig as CredentialsConfig, index$1_CredentialsManager as CredentialsManager, type index$1_CredentialsStorage as CredentialsStorage, type index$1_IPasswordHasher as IPasswordHasher, index$1_LocalCredentialsStorage as LocalCredentialsStorage, type index$1_PasswordPolicyConfig as PasswordPolicyConfig, type index$1_PasswordPolicyResult as PasswordPolicyResult, type index$1_Pbkdf2HasherOptions as Pbkdf2HasherOptions, index$1_Pbkdf2PasswordHasher as Pbkdf2PasswordHasher, type index$1_ScryptHasherOptions as ScryptHasherOptions, index$1_ScryptPasswordHasher as ScryptPasswordHasher, type index$1_SignInParams as SignInParams, type index$1_SignInResult as SignInResult, type index$1_SignUpParams as SignUpParams, type index$1_SignUpResult as SignUpResult, type index$1_UserCredentials as UserCredentials, type index$1_VerifyCredentialsParams as VerifyCredentialsParams, index$1_validatePasswordPolicy as validatePasswordPolicy };
+}
+
+type index_ConfirmPasswordResetParams = ConfirmPasswordResetParams;
+type index_ConfirmSignUpParams = ConfirmSignUpParams;
+type index_ForgotPasswordParams = ForgotPasswordParams;
+type index_ForgotPasswordResult = ForgotPasswordResult;
+type index_IIdentityProvider = IIdentityProvider;
+type index_IdentityAuthResult = IdentityAuthResult;
+type index_IdentityConfig = IdentityConfig;
+type index_IdentityTokens = IdentityTokens;
+type index_ResendConfirmationCodeParams = ResendConfirmationCodeParams;
+type index_ResendConfirmationCodeResult = ResendConfirmationCodeResult;
+type index_SelfManagedIdentityProvider = SelfManagedIdentityProvider;
+declare const index_SelfManagedIdentityProvider: typeof SelfManagedIdentityProvider;
+type index_UserIdentity = UserIdentity;
 declare namespace index {
-  export { type index_ChangePasswordParams as ChangePasswordParams, type index_CredentialsConfig as CredentialsConfig, index_CredentialsManager as CredentialsManager, type index_CredentialsStorage as CredentialsStorage, type index_IPasswordHasher as IPasswordHasher, index_LocalCredentialsStorage as LocalCredentialsStorage, type index_PasswordPolicyConfig as PasswordPolicyConfig, type index_PasswordPolicyResult as PasswordPolicyResult, type index_Pbkdf2HasherOptions as Pbkdf2HasherOptions, index_Pbkdf2PasswordHasher as Pbkdf2PasswordHasher, type index_ScryptHasherOptions as ScryptHasherOptions, index_ScryptPasswordHasher as ScryptPasswordHasher, type index_SignInParams as SignInParams, type index_SignInResult as SignInResult, type index_SignUpParams as SignUpParams, type index_SignUpResult as SignUpResult, type index_UserCredentials as UserCredentials, type index_VerifyCredentialsParams as VerifyCredentialsParams, index_validatePasswordPolicy as validatePasswordPolicy };
+  export { type index_ConfirmPasswordResetParams as ConfirmPasswordResetParams, type index_ConfirmSignUpParams as ConfirmSignUpParams, type index_ForgotPasswordParams as ForgotPasswordParams, type index_ForgotPasswordResult as ForgotPasswordResult, type index_IIdentityProvider as IIdentityProvider, type index_IdentityAuthResult as IdentityAuthResult, type index_IdentityConfig as IdentityConfig, type index_IdentityTokens as IdentityTokens, type index_ResendConfirmationCodeParams as ResendConfirmationCodeParams, type index_ResendConfirmationCodeResult as ResendConfirmationCodeResult, index_SelfManagedIdentityProvider as SelfManagedIdentityProvider, type index_UserIdentity as UserIdentity };
 }
 
-export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, AccountUnlinkError, type ChangePasswordParams, type ConnectedResource, type CookieOptions, type CookiePayload, type CredentialsConfig, CredentialsManager, CredentialsNotConfiguredError, type CredentialsStorage, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_COOKIE_NAME, DEFAULT_STATE_MAX_AGE_SECONDS, EmailNotVerifiedError, type IPasswordHasher, type IProvider, InvalidCredentialsError, InvalidOAuthCallbackError, InvalidProviderConfigError, InvalidStateError, Lixa, type LixaConfig, LixaError, type LixaLogger, LocalCredentialsStorage, type LogContext, type LogLevel, type OAuthTokenResponse, type PasswordPolicyConfig, type PasswordPolicyResult, type Pbkdf2HasherOptions, Pbkdf2PasswordHasher, type ProviderConfig, type ProviderMetadata, ProviderNotConfiguredError, RefreshTokenError, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type ScryptHasherOptions, ScryptPasswordHasher, type Session, type SessionHandler, SessionNotFoundError, type SessionStorage, type SignInParams, type SignInResult, type SignUpParams, type SignUpResult, type StateData, type StateHandler, type StateStorage, TokenExchangeError, UserAlreadyExistsError, type UserCredentials, type UserInfo, UserNotFoundError, type VerifyCredentialsParams, WeakPasswordError, clearSessionCookie, clearStateCookie, createSessionCookie, createStateCookie, index as credentials, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo, isProductionEnvironment, serializeCookie, validatePasswordPolicy };
+export { type AccountHandler, type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, type AccountStorage, AccountUnlinkError, type ChangePasswordParams, type ConfirmPasswordResetParams, type ConfirmSignUpParams, type ConnectedResource, type CookieOptions, type CookiePayload, type CredentialsConfig, CredentialsManager, CredentialsNotConfiguredError, type CredentialsStorage, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_COOKIE_NAME, DEFAULT_STATE_MAX_AGE_SECONDS, EmailNotVerifiedError, type ForgotPasswordParams, type ForgotPasswordResult, type IIdentityProvider, type IPasswordHasher, type IProvider, type IdentityAuthResult, type IdentityConfig, IdentityNotConfiguredError, IdentityProviderError, type IdentityTokens, InvalidCredentialsError, InvalidOAuthCallbackError, InvalidProviderConfigError, InvalidStateError, type LinkedAccount, Lixa, type LixaConfig, type LixaCookieContext, LixaError, type LixaLogger, LocalCredentialsStorage, type LogContext, type LogLevel, type OAuthTokenResponse, type PasswordPolicyConfig, type PasswordPolicyResult, type Pbkdf2HasherOptions, Pbkdf2PasswordHasher, type ProviderConfig, type ProviderMetadata, ProviderNotConfiguredError, RefreshTokenError, type ResendConfirmationCodeParams, type ResendConfirmationCodeResult, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type ScryptHasherOptions, ScryptPasswordHasher, SelfManagedIdentityProvider, type Session, type SessionCookieResolver, type SessionHandler, SessionNotFoundError, type SessionStorage, type SignInParams, type SignInResult, type SignUpParams, type SignUpResult, type StateData, type StateHandler, type StateStorage, TokenExchangeError, UserAlreadyExistsError, type UserCredentials, type UserIdentity, type UserInfo, UserNotFoundError, type VerifyCredentialsParams, WeakPasswordError, clearSessionCookie, clearStateCookie, createSessionCookie, createStateCookie, index$1 as credentials, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo, index as identity, isProductionEnvironment, serializeCookie, validatePasswordPolicy };