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

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

@@ -25,6 +25,31 @@ 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.
  *
@@ -52,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.
@@ -129,7 +154,18 @@ 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>);
 }
 
 /**
@@ -142,6 +178,11 @@ export declare interface AccountStorage {
     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;
+    }>>;
 }
 
 /**
@@ -159,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) */
@@ -197,6 +240,83 @@ 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
  */
@@ -208,6 +328,8 @@ declare type ConfiguredProviderKey<TProviders extends Record<string, ProviderCon
  * @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 */
@@ -222,6 +344,8 @@ export declare interface ConfirmPasswordResetParams {
  * @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) */
@@ -425,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;
 }
 
 /**
@@ -473,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.
      */
@@ -551,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>;
 }
 
 /**
@@ -660,6 +811,8 @@ export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: str
  * @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 */
@@ -693,7 +846,9 @@ export declare namespace identity {
         ResendConfirmationCodeResult,
         IIdentityProvider,
         IdentityConfig,
-        SelfManagedIdentityProvider
+        SelfManagedIdentityProvider,
+        CompositeIdentityProviderOptions,
+        CompositeIdentityProvider
     }
 }
 
@@ -1074,10 +1229,16 @@ export declare interface LinkedAccount {
     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;
 }
@@ -1134,7 +1295,7 @@ export declare interface LinkedAccount {
  *
  * @public
  */
-export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+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;
@@ -1144,6 +1305,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
     private userResourceStore;
     private userAccountStore;
     private refreshMutexes;
+    private linkingChallenges;
     private identityProvider?;
     private credentialsManager?;
     private config;
@@ -1166,7 +1328,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * @throws Error when provider implementation is missing required properties
      * @throws Error when provider is not available and no inline implementation is provided
      */
-    constructor(config: LixaConfig<TProviders>);
+    constructor(config: LixaConfig<TIdentity, TProviders>);
     /**
      * Validates that a provider configuration has all required credentials.
      *
@@ -1207,7 +1369,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * }
      * ```
      */
-    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TProviders>;
+    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
@@ -1388,7 +1550,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * res.redirect(authUrl);
      * ```
      */
-    getAuthUrl(provider: ConfiguredProviderKey<TProviders> | 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.
      */
@@ -1413,7 +1575,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * ```
      */
     handleCallback({ provider, code, state, sessionId, }: {
-        provider: ConfiguredProviderKey<TProviders> | string;
+        provider: ConfiguredOAuthKey<TIdentity, TProviders> | string;
         code: string;
         state?: string;
         sessionId?: string;
@@ -1438,6 +1600,38 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * @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.
      *
@@ -1451,19 +1645,21 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      */
     getResourceAuthUrl(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TProviders> | 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<TProviders> | string;
+        provider: ConfiguredOAuthKey<TIdentity, TProviders> | string;
         code: string;
         state?: string;
         scopes?: string[];
@@ -1474,7 +1670,7 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * @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;
+    getResourceScopes(provider: ConfiguredOAuthKey<TIdentity, TProviders> | string): string[] | undefined;
     /**
      * Returns the resolved session cookie name.
      * Dynamically reflects any changes to the active identity provider.
@@ -1536,6 +1732,13 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * 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).
      *
@@ -1579,90 +1782,109 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
      * @throws UserAlreadyExistsError if identifier is already registered
      * @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 credentials via the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+     * 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 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)
+     * @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<UserIdentity | 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 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)
+     * @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): Promise<ForgotPasswordResult>;
+    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, and 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): Promise<boolean>;
+    confirmPasswordReset(params: ConfirmPasswordResetParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<boolean>;
     /**
      * Confirms user account registration using a verification code.
      *
-     * @param params - Verification parameters including identifier and confirmationCode
+     * @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): Promise<boolean>;
+    confirmSignUp(params: ConfirmSignUpParams & {
+        provider?: ConfiguredIdentityKey<TIdentity>;
+    }): Promise<boolean>;
     /**
      * Resends the sign up confirmation code to the user.
      *
-     * @param params - Resend parameters including user identifier
+     * @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): Promise<ResendConfirmationCodeResult>;
+    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): Promise<UserIdentity | null>;
+    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): Promise<UserIdentity | null>;
+    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): Promise<void>;
+    deleteUser(id: string, provider?: ConfiguredIdentityKey<TIdentity>): Promise<void>;
     private findProviderByType;
 }
 
@@ -1672,37 +1894,36 @@ export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Re
  *
  * @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 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 }
-     * ```
+     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta,
+     * or a CompositeIdentityProvider combining multiple backends and OAuth providers).
      *
      * @example
-     * AWS Cognito:
+     * Composite Identity Provider:
      * ```typescript
-     * identityProvider: new CognitoIdentityProvider({ userPoolId: '...', clientId: '...', region: 'us-east-1' })
+     * identityProvider: new CompositeIdentityProvider({
+     *   defaultProvider: 'cognito',
+     *   providers: {
+     *     cognito: new CognitoIdentityProvider(...),
+     *     'self-managed': new SelfManagedIdentityProvider(...)
+     *   },
+     *   oauthProviders: {
+     *     google: { provider: new GoogleProvider(), ... }
+     *   }
+     * })
      * ```
      */
-    identityProvider?: IIdentityProvider | IdentityConfig;
+    identityProvider?: TIdentity;
     /**
      * Alias for {@link LixaConfig.identityProvider}.
      */
-    identity?: IIdentityProvider | IdentityConfig;
+    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.
@@ -1983,38 +2204,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 = {
@@ -2024,11 +2213,25 @@ export declare type ProviderConfig = {
     clientSecret: string;
     /** The redirect URI registered with the provider */
     redirectUri: 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.
+     * 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[];
     /**
@@ -2037,7 +2240,11 @@ export declare type ProviderConfig = {
      * 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;
@@ -2089,6 +2296,8 @@ export declare class RefreshTokenError extends LixaError {
  * @public
  */
 export declare interface ResendConfirmationCodeParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username or email of the account */
     identifier: string;
 }
@@ -2169,6 +2378,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.
  *
@@ -2237,12 +2500,26 @@ export declare class ScryptPasswordHasher implements IPasswordHasher {
 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.
+     * 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.
      */
@@ -2486,6 +2763,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) */
@@ -2514,6 +2793,8 @@ export declare interface SignInResult<TSession = Session, TUser = UserIdentity>
  * @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) */
@@ -2538,6 +2819,20 @@ export declare interface SignUpResult<TSession = Session, TUser = UserIdentity>
     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>);
 }
 
 /**
@@ -2738,7 +3033,7 @@ export declare interface StateStorage {
  * When provided to Lixa via config.storage, automatically configures session, state, and resource storage.
  * @public
  */
-declare interface StorageAdapter {
+export declare interface StorageAdapter {
     sessionStorage?: any;
     resourceStorage?: any;
     stateStorage?: any;
@@ -2859,6 +3154,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) */