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

package/dist/index.d.cts

@@ -58,10 +58,16 @@ 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;
 }
@@ -437,6 +443,11 @@ 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;
+    }>>;
 }
 /**
  * Account handler configuration.
@@ -745,6 +756,8 @@ interface IdentityAuthResult {
  * @public
  */
 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 */
@@ -769,6 +782,8 @@ interface ForgotPasswordResult {
  * @public
  */
 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 */
@@ -782,6 +797,8 @@ interface ConfirmPasswordResetParams {
  * @public
  */
 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) */
@@ -793,6 +810,8 @@ interface ConfirmSignUpParams {
  * @public
  */
 interface ResendConfirmationCodeParams {
+    /** Target identity provider name when using CompositeIdentityProvider */
+    provider?: string | undefined;
     /** Username or email of the account */
     identifier: string;
 }
@@ -979,6 +998,12 @@ 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>;
 }
 /**
  * Interface for password hashing and verification algorithms.
@@ -1131,6 +1156,13 @@ 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;
 }
 /**
  * Parameters for user registration (signUp).
@@ -1138,6 +1170,8 @@ interface CredentialsConfig {
  * @public
  */
 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) */
@@ -1161,6 +1195,8 @@ 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;
 }
 /**
  * Parameters for user authentication (signIn).
@@ -1168,6 +1204,8 @@ interface SignUpResult<TSession = Session, TUser = UserIdentity> {
  * @public
  */
 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) */
@@ -1194,6 +1232,8 @@ interface SignInResult<TSession = Session, TUser = UserIdentity> {
  * @public
  */
 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) */
@@ -1207,6 +1247,8 @@ interface VerifyCredentialsParams {
  * @public
  */
 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) */
@@ -1382,6 +1424,20 @@ 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.
      */
@@ -1413,12 +1469,26 @@ declare class CredentialsManager {
 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.
      */
@@ -1449,6 +1519,68 @@ declare class SelfManagedIdentityProvider implements IIdentityProvider {
     getCredentialsManager(): CredentialsManager;
 }
 
+/**
+ * Options for initializing a CompositeIdentityProvider.
+ *
+ * @public
+ */
+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;
+}
+/**
+ * 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
+ */
+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>;
+}
+
 /**
  * Configuration for an OAuth provider instance.
  *
@@ -1485,6 +1617,27 @@ declare class SelfManagedIdentityProvider implements IIdentityProvider {
  *
  * @public
  */
+/**
+ * Scopes configuration explicitly partitioned into authentication and resource authorization.
+ *
+ * @public
+ */
+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[];
+}
+/**
+ * Configuration for an OAuth provider instance.
+ * @public
+ */
 type ProviderConfig = {
     /** The OAuth client ID provided by the provider */
     clientId: string;
@@ -1492,11 +1645,25 @@ 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[];
     /**
@@ -1505,7 +1672,11 @@ 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;
@@ -1587,14 +1758,16 @@ 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"
 }
 /**
  * Supported mode values for account linking configuration.
  *
  * @public
  */
-type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "linkByEmail" | "separate";
+type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "STEP_UP_VERIFICATION" | "linkByEmail" | "separate" | "stepUp";
 /**
  * Account linking settings for Lixa.
  *
@@ -1628,43 +1801,54 @@ interface StorageAdapter {
     credentialsStorage?: any;
     accountStorage?: any;
 }
+/**
+ * Inferred key of identity providers configured in a CompositeIdentityProvider.
+ *
+ * @public
+ */
+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
+ */
+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;
 /**
  * Main configuration object for Lixa.
  * Provides type-safe provider name inference.
  *
  * @public
  */
-interface LixaConfig<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;
+interface LixaConfig<TIdentity extends IIdentityProvider | IdentityConfig = IIdentityProvider | IdentityConfig, TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     /**
-     * Alias for {@link LixaConfig.federatedOAuthProviders}.
-     */
-    providers?: TProviders;
-    /**
-     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta, or custom IIdentityProvider).
+     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta,
+     * or a CompositeIdentityProvider combining multiple backends and OAuth providers).
      *
      * @example
-     * Self-managed with Prisma:
+     * Composite Identity Provider:
      * ```typescript
-     * identityProvider: { storage: prismaAdapter.credentialsStorage }
-     * ```
-     *
-     * @example
-     * AWS Cognito:
-     * ```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.
@@ -1833,7 +2017,7 @@ type ConfiguredProviderKey<TProviders extends Record<string, ProviderConfig>> =
  *
  * @public
  */
-declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+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;
@@ -1843,6 +2027,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
     private userResourceStore;
     private userAccountStore;
     private refreshMutexes;
+    private linkingChallenges;
     private identityProvider?;
     private credentialsManager?;
     private config;
@@ -1865,7 +2050,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * @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.
      *
@@ -1906,7 +2091,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * }
      * ```
      */
-    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
@@ -2087,7 +2272,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * 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.
      */
@@ -2112,7 +2297,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * ```
      */
     handleCallback({ provider, code, state, sessionId, }: {
-        provider: ConfiguredProviderKey<TProviders> | string;
+        provider: ConfiguredOAuthKey<TIdentity, TProviders> | string;
         code: string;
         state?: string;
         sessionId?: string;
@@ -2137,6 +2322,38 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * @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.
      *
@@ -2150,19 +2367,21 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      */
     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[];
@@ -2173,7 +2392,7 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * @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.
@@ -2235,6 +2454,13 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * 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).
      *
@@ -2278,90 +2504,109 @@ declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<st
      * @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;
 }
 
@@ -2596,6 +2841,49 @@ declare class IdentityProviderError extends LixaError {
 declare class IdentityNotConfiguredError extends CredentialsNotConfiguredError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
+/**
+ * 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
+ */
+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;
+    });
+}
+/**
+ * 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
+ */
+declare class SSOAccountAlreadyExistsError extends LixaError {
+    readonly existingProviders: string[];
+    readonly email: string;
+    constructor(email: string, existingProviders: string[], details?: Record<string, unknown>);
+}
+/**
+ * Thrown when a user's account has not been verified/confirmed yet.
+ *
+ * @public
+ */
+declare class AccountNotVerifiedError extends LixaError {
+    constructor(identifier?: string, details?: Record<string, unknown>);
+}
 
 /**
  * Sensible default cookie configuration options.
@@ -2766,6 +3054,9 @@ 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_CompositeIdentityProvider<TProviders extends Record<string, IIdentityProvider> = Record<string, IIdentityProvider>, TOAuthProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> = CompositeIdentityProvider<TProviders, TOAuthProviders>;
+declare const index_CompositeIdentityProvider: typeof CompositeIdentityProvider;
+type index_CompositeIdentityProviderOptions<TProviders extends Record<string, IIdentityProvider> = Record<string, IIdentityProvider>, TOAuthProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> = CompositeIdentityProviderOptions<TProviders, TOAuthProviders>;
 type index_ConfirmPasswordResetParams = ConfirmPasswordResetParams;
 type index_ConfirmSignUpParams = ConfirmSignUpParams;
 type index_ForgotPasswordParams = ForgotPasswordParams;
@@ -2780,7 +3071,7 @@ type index_SelfManagedIdentityProvider = SelfManagedIdentityProvider;
 declare const index_SelfManagedIdentityProvider: typeof SelfManagedIdentityProvider;
 type index_UserIdentity = UserIdentity;
 declare namespace index {
-  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 { index_CompositeIdentityProvider as CompositeIdentityProvider, type index_CompositeIdentityProviderOptions as CompositeIdentityProviderOptions, 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 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 };
+export { type AccountHandler, AccountLinkingChallengeRequiredError, type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, AccountNotVerifiedError, type AccountStorage, AccountUnlinkError, type ChangePasswordParams, CompositeIdentityProvider, type CompositeIdentityProviderOptions, type ConfiguredIdentityKey, type ConfiguredOAuthKey, 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, SSOAccountAlreadyExistsError, type SafeLixaConfig, type ScopesConfig, 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, type StorageAdapter, 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 };