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

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

@@ -16,6 +16,40 @@
  * @packageDocumentation
  */
 
+/**
+ * Account handler configuration.
+ *
+ * @public
+ */
+export declare interface AccountHandler {
+    accountStorage?: AccountStorage;
+}
+
+/**
+ * Thrown when a login attempt matches an existing user under another provider,
+ * requiring step-up verification (e.g. password or original provider login) before linking.
+ *
+ * @public
+ */
+export declare class AccountLinkingChallengeRequiredError extends LixaError {
+    readonly challengeToken: string;
+    readonly email: string;
+    readonly incomingProvider: string;
+    readonly incomingProviderUserId?: string | undefined;
+    readonly existingUserId: string;
+    readonly existingProviders: string[];
+    readonly hasPassword: boolean;
+    constructor(message: string, details: {
+        challengeToken: string;
+        email: string;
+        incomingProvider: string;
+        incomingProviderUserId?: string | undefined;
+        existingUserId: string;
+        existingProviders: string[];
+        hasPassword: boolean;
+    });
+}
+
 /**
  * Account linking settings for Lixa.
  *
@@ -43,7 +77,7 @@ export declare interface AccountLinkingConfig {
  *
  * @public
  */
-export declare type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "linkByEmail" | "separate";
+export declare type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "STEP_UP_VERIFICATION" | "linkByEmail" | "separate" | "stepUp";
 
 /**
  * Main configuration object for Lixa.
@@ -120,7 +154,35 @@ export declare enum AccountLinkingStrategy {
     /** Automatically merge identities matching the same verified primary email address */
     AUTO_LINK_BY_VERIFIED_EMAIL = "AUTO_LINK_BY_VERIFIED_EMAIL",
     /** Keep identity profiles isolated per provider (no automatic account merging) */
-    ISOLATED = "ISOLATED"
+    ISOLATED = "ISOLATED",
+    /** Require password or original provider step-up verification before linking secondary accounts */
+    STEP_UP_VERIFICATION = "STEP_UP_VERIFICATION"
+}
+
+/**
+ * Thrown when a user's account has not been verified/confirmed yet.
+ *
+ * @public
+ */
+export declare class AccountNotVerifiedError extends LixaError {
+    constructor(identifier?: string, details?: Record<string, unknown>);
+}
+
+/**
+ * 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>;
+    findAccountsByEmail?(email: string): Promise<Array<{
+        userId: string;
+        provider: string;
+        account: LinkedAccount;
+    }>>;
 }
 
 /**
@@ -138,6 +200,8 @@ export declare class AccountUnlinkError extends LixaError {
  * @public
  */
 export declare interface ChangePasswordParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username (optional if identifier or userId is provided) */
     username?: string | undefined;
     /** Primary identifier (optional if username or userId is provided) */
@@ -176,10 +240,117 @@ export declare function clearSessionCookie(options?: CookieOptions): CookiePaylo
  */
 export declare function clearStateCookie(options?: CookieOptions): CookiePayload;
 
+/**
+ * Composite Identity Provider that aggregates multiple child IIdentityProvider instances
+ * and OAuth 2.0 / OIDC provider configurations under a single unified identityProvider.
+ *
+ * @remarks
+ * Eliminates the need for separate `federatedOAuthProviders` configuration in Lixa.
+ * Provides compile-time autocompletion of configured provider names.
+ * Routing is strictly explicit: uses `params.provider` if provided, or `defaultProvider`.
+ * No silent fallbacks or guesswork.
+ *
+ * @public
+ */
+export declare class CompositeIdentityProvider<TProviders extends Record<string, IIdentityProvider> = Record<string, IIdentityProvider>, TOAuthProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> implements IIdentityProvider {
+    readonly name: string;
+    readonly providers: TProviders;
+    readonly defaultProvider?: (keyof TProviders & string) | undefined;
+    readonly oauthProviders?: TOAuthProviders | undefined;
+    constructor(options: CompositeIdentityProviderOptions<TProviders, TOAuthProviders>);
+    /**
+     * Resolves the target child provider based on explicit parameter or defaultProvider.
+     * Throws an error immediately if the provider cannot be resolved or does not exist.
+     */
+    selectProvider(providerName?: string): IIdentityProvider;
+    /**
+     * Returns all OAuth / OIDC provider configurations aggregated across this composite provider
+     * and any child providers exposing `getOAuthProviders()` or `getProviders()`.
+     */
+    getProviders(): Record<string, ProviderConfig>;
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    signIn(params: SignInParams): Promise<IdentityAuthResult>;
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    forgotPassword(params: ForgotPasswordParams): Promise<ForgotPasswordResult>;
+    confirmPasswordReset(params: ConfirmPasswordResetParams): Promise<boolean>;
+    confirmSignUp(params: ConfirmSignUpParams): Promise<boolean>;
+    resendConfirmationCode(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    getUserById(id: string, providerName?: string): Promise<UserIdentity | null>;
+    getUserByIdentifier(identifier: string, providerName?: string): Promise<UserIdentity | null>;
+    deleteUser(id: string, providerName?: string): Promise<void>;
+}
+
+/**
+ * Options for initializing a CompositeIdentityProvider.
+ *
+ * @public
+ */
+export declare interface CompositeIdentityProviderOptions<TProviders extends Record<string, IIdentityProvider> = Record<string, IIdentityProvider>, TOAuthProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+    /**
+     * Record of child identity providers keyed by unique provider names.
+     * e.g. `{ cognito: new CognitoIdentityProvider(...), okta: new OktaIdentityProvider(...) }`
+     */
+    providers: TProviders;
+    /**
+     * Default provider key to use when a request does not explicitly pass a `provider` parameter.
+     */
+    defaultProvider?: (keyof TProviders & string) | undefined;
+    /**
+     * Record of OAuth 2.0 / OIDC provider configurations (Google, GitHub, etc.)
+     * to register alongside these identity providers.
+     */
+    oauthProviders?: TOAuthProviders | undefined;
+}
+
+/**
+ * Inferred key of identity providers configured in a CompositeIdentityProvider.
+ *
+ * @public
+ */
+export declare type ConfiguredIdentityKey<TIdentity> = TIdentity extends CompositeIdentityProvider<infer TProviders, any> ? (keyof TProviders & string) : string;
+
+/**
+ * Inferred key of OAuth / OIDC providers configured in a CompositeIdentityProvider or inline providers.
+ *
+ * @public
+ */
+export declare type ConfiguredOAuthKey<TIdentity = unknown, TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> = TIdentity extends CompositeIdentityProvider<any, infer TOAuth> ? (keyof TOAuth & string) | (keyof TProviders & string) : keyof TProviders & string;
+
 /**
  * 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 {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
+    /** 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 {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
+    /** 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)
@@ -378,6 +549,13 @@ export declare interface CredentialsConfig {
      * @default 86400 (24 hours)
      */
     sessionTtlSeconds?: number | undefined;
+    /**
+     * Whether identity verification (e.g. email confirmation code) is required before persisting credentials to storage.
+     * When true, signUp creates a pending registration without writing to storage, requiring confirmSignUp() to activate.
+     *
+     * @default false
+     */
+    requireVerification?: boolean | undefined;
 }
 
 /**
@@ -426,6 +604,20 @@ export declare class CredentialsManager {
      * @returns True if password was successfully updated
      */
     changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Sets a password for a user who doesn't have one yet (e.g. SSO-first users),
+     * or updates an existing password without requiring the old one.
+     * This should only be called from an authenticated context (user already verified their identity via SSO).
+     *
+     * @param params - userId and newPassword
+     * @returns True if password was successfully set
+     */
+    setPassword(params: {
+        userId: string;
+        newPassword: string;
+        identifier?: string;
+        email?: string;
+    }): Promise<boolean>;
     /**
      * Finds a user by ID and returns safe user data.
      */
@@ -504,6 +696,12 @@ export declare interface CredentialsStorage {
      * @param username - Username string
      */
     findUserByUsername?(username: string): Promise<UserCredentials | null>;
+    /**
+     * Optional helper to find user directly by email address.
+     *
+     * @param email - Verified email address
+     */
+    findUserByEmail?(email: string): Promise<UserCredentials | null>;
 }
 
 /**
@@ -607,6 +805,204 @@ 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 {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
+    /** 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,
+        CompositeIdentityProviderOptions,
+        CompositeIdentityProvider
+    }
+}
+
+/**
+ * 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.
  *
@@ -809,6 +1205,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[];
 }
 
 /**
@@ -822,17 +1222,23 @@ 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 */
     providerUserId?: string | undefined;
     /** User email for this provider */
     email?: string | undefined;
-    /** OAuth access token for this provider */
-    accessToken: string;
-    /** Full raw token response from provider */
-    raw: OAuthTokenResponse;
+    /**
+     * Optional OAuth access token for this provider.
+     * @deprecated Authentication tokens belong strictly to session.token / session.raw for that session alone. Resource tokens belong in ConnectedResource / user_resources.
+     */
+    accessToken?: string | undefined;
+    /**
+     * Optional raw token response from provider.
+     * @deprecated Authentication tokens belong strictly to session.token / session.raw for that session alone. Resource tokens belong in ConnectedResource / user_resources.
+     */
+    raw?: OAuthTokenResponse | undefined;
     /** Unix timestamp in milliseconds when account was linked */
     linkedAt: number;
 }
@@ -889,20 +1295,25 @@ declare interface LinkedAccount {
  *
  * @public
  */
-export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+export declare class Lixa<TIdentity extends IIdentityProvider | IdentityConfig = IIdentityProvider | IdentityConfig, 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.
      *
@@ -916,7 +1327,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<TIdentity, TProviders>);
     /**
      * Validates that a provider configuration has all required credentials.
      *
@@ -957,7 +1368,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 & (ConfiguredOAuthKey<TIdentity, TProviders> | ConfiguredProviderKey<TProviders>);
     /**
      * Gets a provider implementation by name.
      * Resolution priority: inline custom provider \> default providers \> legacy registry
@@ -1138,7 +1549,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: ConfiguredOAuthKey<TIdentity, TProviders> | string, state?: string): Promise<string>;
     /**
      * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
      */
@@ -1162,10 +1573,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: ConfiguredOAuthKey<TIdentity, TProviders> | string;
         code: string;
         state?: string;
+        sessionId?: string;
     }): Promise<string>;
     /**
      * Explicitly link a new OAuth provider account to an active session.
@@ -1175,7 +1587,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>;
@@ -1187,6 +1599,38 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * @returns Promise resolving to true on successful unlink
      */
     unlinkAccount(sessionId: string, providerToUnlink: string): Promise<boolean>;
+    /**
+     * Confirms a pending account linking step-up challenge using the user's password.
+     * On successful verification, links the pending provider to the existing account and creates a session.
+     *
+     * @param params - challengeToken and password
+     * @returns Session ID, Session, and User identity
+     * @throws InvalidStateError if challenge is invalid or expired
+     * @throws InvalidCredentialsError if password verification fails
+     */
+    confirmLinkingWithPassword(params: {
+        challengeToken: string;
+        password: string;
+    }): Promise<{
+        sessionId: string;
+        session: Session;
+        user?: any;
+    }>;
+    /**
+     * Sets a password for an SSO-authenticated user who doesn't have one yet.
+     * Must be called from an authenticated context (user has active session proving identity).
+     *
+     * @param params - userId, newPassword, optional identifier and email
+     * @returns True if password was set successfully
+     * @throws IdentityNotConfiguredError if no identity provider configured
+     * @throws WeakPasswordError if password doesn't meet policy
+     */
+    setPassword(params: {
+        userId: string;
+        newPassword: string;
+        identifier?: string;
+        email?: string;
+    }): Promise<boolean>;
     /**
      * Generates an authorization URL for connecting a resource provider (AuthZ) post-login.
      *
@@ -1200,23 +1644,46 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     getResourceAuthUrl(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
-        scopes: string[];
+        provider: ConfiguredOAuthKey<TIdentity, TProviders> | string;
+        scopes?: string[];
         state?: string;
         prompt?: string;
+        authorizationParams?: Record<string, string>;
         extraConfig?: Record<string, string>;
     }): Promise<string>;
     private getUserKeyFromSession;
+    private sanitizeIdentityForStorage;
     /**
      * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
      */
     handleResourceCallback(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredOAuthKey<TIdentity, 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: ConfiguredOAuthKey<TIdentity, 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.
@@ -1264,6 +1731,13 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * Retrieves active session details from session storage.
      */
     fetchSessionInfo(sessionId: string): Promise<Session | null>;
+    /**
+     * Retrieves all linked accounts for a user from account storage.
+     *
+     * @param userIdOrSessionId - User ID, email, or active session ID
+     * @returns Record mapping provider name to linked account metadata
+     */
+    getUserAccounts(userIdOrSessionId: string): Promise<Record<string, LinkedAccount>>;
     /**
      * Deletes a session from session storage (e.g. on logout).
      *
@@ -1272,57 +1746,144 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
     deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
     /**
-     * Checks if credentials (username and password) authentication is configured and enabled.
+     * 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 authentication is available
+     * @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>;
+    signUp(params: SignUpParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): 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, or Composite).
+     * 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)
+     * @param params - Sign-in parameters (identifier, password, optional provider)
      * @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>;
+    signIn(params: SignInParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): 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
+     * @param params - Verification parameters (identifier, password, optional provider)
+     * @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 & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): 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)
+     * @param params - Change password parameters (userId/identifier, oldPassword, newPassword, optional provider)
      * @returns True if password was updated successfully
      * @throws UserNotFoundError if user is not found
      * @throws InvalidCredentialsError if current password is incorrect
      * @throws WeakPasswordError if new password does not meet policy requirements
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @throws IdentityNotConfiguredError if identity auth is not configured
      */
-    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    changePassword(params: ChangePasswordParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<boolean>;
+    /**
+     * Initiates a password reset (forgot password flow) through the configured identity provider.
+     *
+     * @param params - Forgot password parameters (identifier, optional metadata, optional provider)
+     * @returns ForgotPasswordResult indicating status and delivery medium (email/SMS)
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    forgotPassword(params: ForgotPasswordParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<ForgotPasswordResult>;
+    /**
+     * Confirms a password reset using a verification code / token and sets the new password.
+     *
+     * @param params - Verification code, identifier, new password, and optional provider
+     * @returns True if password reset was successfully confirmed
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    confirmPasswordReset(params: ConfirmPasswordResetParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<boolean>;
+    /**
+     * Confirms user account registration using a verification code.
+     *
+     * @param params - Verification parameters including identifier, confirmationCode, and optional provider
+     * @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 & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<boolean>;
+    /**
+     * Resends the sign up confirmation code to the user.
+     *
+     * @param params - Resend parameters including user identifier and optional provider
+     * @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 & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<ResendConfirmationCodeResult>;
+    /**
+     * Retrieves a user by their unique ID from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     * @param provider - Optional provider key when using CompositeIdentityProvider
+     * @returns UserIdentity or null if not found
+     */
+    getUserById(id: string, provider?: ConfiguredIdentityKey<TIdentity>): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (username or email) from the configured identity provider.
+     *
+     * @param identifier - Username or email string
+     * @param provider - Optional provider key when using CompositeIdentityProvider
+     * @returns UserIdentity or null if not found
+     */
+    getUserByIdentifier(identifier: string, provider?: ConfiguredIdentityKey<TIdentity>): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user account from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     * @param provider - Optional provider key when using CompositeIdentityProvider
+     */
+    deleteUser(id: string, provider?: ConfiguredIdentityKey<TIdentity>): Promise<void>;
     private findProviderByType;
 }
 
@@ -1332,20 +1893,51 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
  *
  * @public
  */
-export declare interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+export declare interface LixaConfig<TIdentity extends IIdentityProvider | IdentityConfig = IIdentityProvider | IdentityConfig, TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     /**
-     * Map of provider names to their configurations.
-     * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
+     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta,
+     * or a CompositeIdentityProvider combining multiple backends and OAuth providers).
+     *
+     * @example
+     * Composite Identity Provider:
+     * ```typescript
+     * identityProvider: new CompositeIdentityProvider({
+     *   defaultProvider: 'cognito',
+     *   providers: {
+     *     cognito: new CognitoIdentityProvider(...),
+     *     'self-managed': new SelfManagedIdentityProvider(...)
+     *   },
+     *   oauthProviders: {
+     *     google: { provider: new GoogleProvider(), ... }
+     *   }
+     * })
+     * ```
+     */
+    identityProvider?: TIdentity;
+    /**
+     * Alias for {@link LixaConfig.identityProvider}.
+     */
+    identity?: TIdentity;
+    /**
+     * Direct OAuth 2.0 / OIDC provider configurations (Google, GitHub, etc.).
+     * When using CompositeIdentityProvider, OAuth providers can also be defined in its `oauthProviders` field.
      */
     providers?: TProviders;
     /**
      * 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.
@@ -1389,6 +1981,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;
 }
 
 /**
@@ -1439,7 +2048,7 @@ export declare class LocalCredentialsStorage implements CredentialsStorage {
  * Log context for Lixa structured logging.
  * @public
  */
-export declare type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource" | "Credentials";
+export declare type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource" | "Credentials" | "Identity";
 
 /**
  * Log level for Lixa structured logging.
@@ -1594,38 +2203,6 @@ export declare class Pbkdf2PasswordHasher implements IPasswordHasher {
 
 /**
  * Configuration for an OAuth provider instance.
- *
- * @remarks
- * For built-in providers (google, github), just provide credentials.
- * For custom providers, include the provider implementation.
- *
- * The provider field uses a discriminated union to ensure type safety:
- * - When omitted or undefined: assumes a built-in provider
- * - When provided: must be a valid IProvider implementation
- *
- * @example
- * Built-in provider configuration:
- * ```typescript
- * {
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- *   redirectUri: 'https://app.com/callback',
- *   scopes: ['openid', 'email']
- * }
- * ```
- *
- * @example
- * Custom provider configuration:
- * ```typescript
- * {
- *   provider: new CustomProvider(),
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- *   redirectUri: 'https://app.com/callback',
- *   scopes: ['read:user']
- * }
- * ```
- *
  * @public
  */
 export declare type ProviderConfig = {
@@ -1635,15 +2212,38 @@ export declare type ProviderConfig = {
     clientSecret: string;
     /** The redirect URI registered with the provider */
     redirectUri: string;
-    /** Array of OAuth scopes to request */
-    scopes: string[];
+    /**
+     * Explicit scopes for authentication and post-login resource authorization.
+     * Can be configured as `{ auth: [...], resource: [...] }` or a shorthand `string[]` for auth scopes.
+     *
+     * @example
+     * ```typescript
+     * scopes: {
+     *   auth: ["openid", "email", "profile"],
+     *   resource: ["https://www.googleapis.com/auth/drive.readonly"],
+     * }
+     * ```
+     */
+    scopes?: ScopesConfig | string[];
+    /**
+     * Flat alias for authentication scopes (AuthN).
+     */
+    authScopes?: string[];
+    /**
+     * Flat alias for post-authentication resource authorization scopes (AuthZ).
+     */
+    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
      * clean AuthN vs AuthZ separation.
      */
     allowNonAuthScopes?: boolean;
-    /** Additional provider-specific configuration parameters */
+    /**
+     * Custom query parameters passed to the OAuth authorization endpoint (e.g. `{ identity_provider: "Google" }`).
+     */
+    authorizationParams?: Record<string, string>;
+    /** Additional provider-specific configuration parameters (alias for authorizationParams) */
     extraConfig?: Record<string, string>;
 } & ({
     provider?: never;
@@ -1689,6 +2289,32 @@ 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 {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
+    /** 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.
  *
@@ -1751,6 +2377,60 @@ export declare type SafeLixaConfig<TProviders extends Record<string, ProviderCon
     providers: TProviders;
 };
 
+/**
+ * Configuration for an OAuth provider instance.
+ *
+ * @remarks
+ * For built-in providers (google, github), just provide credentials.
+ * For custom providers, include the provider implementation.
+ *
+ * The provider field uses a discriminated union to ensure type safety:
+ * - When omitted or undefined: assumes a built-in provider
+ * - When provided: must be a valid IProvider implementation
+ *
+ * @example
+ * Built-in provider configuration:
+ * ```typescript
+ * {
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['openid', 'email']
+ * }
+ * ```
+ *
+ * @example
+ * Custom provider configuration:
+ * ```typescript
+ * {
+ *   provider: new CustomProvider(),
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['read:user']
+ * }
+ * ```
+ *
+ * @public
+ */
+/**
+ * Scopes configuration explicitly partitioned into authentication and resource authorization.
+ *
+ * @public
+ */
+export declare interface ScopesConfig {
+    /**
+     * Explicit identity scopes requested during primary authentication (AuthN) (e.g. ['openid', 'email', 'profile']).
+     * If omitted, uses the provider's default identity scopes.
+     */
+    auth?: string[];
+    /**
+     * Explicit permission scopes requested during post-authentication resource authorization (AuthZ)
+     * (e.g. ['https://www.googleapis.com/auth/drive.readonly'] or ['repo']).
+     */
+    resource?: string[];
+}
+
 /**
  * Options for Scrypt password hashing.
  *
@@ -1806,6 +2486,69 @@ export declare class ScryptPasswordHasher implements IPasswordHasher {
     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;
+    private readonly pendingSignups;
+    private readonly requireVerification;
+    private readonly config;
+    constructor(configOrManager?: CredentialsConfig | CredentialsManager);
+    private mapUser;
+    private generateConfirmationCode;
+    /**
+     * Registers a new user with optional pending verification.
+     * When requireVerification is true, credentials are NOT persisted to the database until confirmSignUp() is called.
+     */
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    /**
+     * Confirms a pending signup registration using the verification code.
+     * Only after successful confirmation is the user persisted to the database.
+     */
+    confirmSignUp(params: ConfirmSignUpParams): Promise<boolean>;
+    /**
+     * Resends the verification code for a pending signup.
+     */
+    resendConfirmationCode(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    /**
+     * 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.
  *
@@ -1832,9 +2575,9 @@ 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 | undefined;
+    sessionId?: string | undefined;
     /**
      * Linked identity provider accounts (AuthN) keyed by provider name.
      * Single source of truth for all authenticated user SSO identities.
@@ -1861,6 +2604,14 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
     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.
  *
@@ -2011,6 +2762,8 @@ export declare interface SessionStorage {
  * @public
  */
 export declare interface SignInParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username or email of the account */
     username?: string | undefined;
     /** Primary identifier (username or email) */
@@ -2024,9 +2777,9 @@ export declare interface SignInParams {
  *
  * @public
  */
-export declare interface SignInResult<TSession = Session> {
-    /** Authenticated user credentials (with passwordHash omitted for safety) */
-    user: Omit<UserCredentials, "passwordHash">;
+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 */
@@ -2039,6 +2792,8 @@ export declare interface SignInResult<TSession = Session> {
  * @public
  */
 export declare interface SignUpParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username for the user (can be used directly instead of identifier) */
     username?: string | undefined;
     /** Primary identifier (username or email) */
@@ -2056,13 +2811,27 @@ export declare interface SignUpParams {
  *
  * @public
  */
-export declare interface SignUpResult<TSession = Session> {
-    /** Created user credentials (with passwordHash omitted for safety) */
-    user: Omit<UserCredentials, "passwordHash">;
+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;
+    requiresVerification?: boolean | undefined;
+    devConfirmationCode?: string | undefined;
+}
+
+/**
+ * Thrown when attempting to sign up with username+password for an email that already has an SSO account.
+ * The user should sign in via their original SSO provider and set a password in Settings.
+ *
+ * @public
+ */
+export declare class SSOAccountAlreadyExistsError extends LixaError {
+    readonly existingProviders: string[];
+    readonly email: string;
+    constructor(email: string, existingProviders: string[], details?: Record<string, unknown>);
 }
 
 /**
@@ -2258,6 +3027,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
+ */
+export 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.
  *
@@ -2301,6 +3083,33 @@ export declare interface UserCredentials {
     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
  *
@@ -2344,6 +3153,8 @@ export declare function validatePasswordPolicy(password: string, policy?: Passwo
  * @public
  */
 export declare interface VerifyCredentialsParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username or email of the account */
     username?: string | undefined;
     /** Primary identifier (username or email) */