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

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

@@ -16,6 +16,15 @@
  * @packageDocumentation
  */
 
+/**
+ * Account handler configuration.
+ *
+ * @public
+ */
+export declare interface AccountHandler {
+    accountStorage?: AccountStorage;
+}
+
 /**
  * Account linking settings for Lixa.
  *
@@ -123,6 +132,18 @@ export declare enum AccountLinkingStrategy {
     ISOLATED = "ISOLATED"
 }
 
+/**
+ * Interface for persistent linked account storage across user sessions.
+ *
+ * @public
+ */
+export declare interface AccountStorage {
+    saveAccount(userId: string, provider: string, account: LinkedAccount): Promise<void>;
+    getAccount(userId: string, provider: string): Promise<LinkedAccount | null>;
+    getUserAccounts(userId: string): Promise<Record<string, LinkedAccount>>;
+    deleteAccount(userId: string, provider: string): Promise<void>;
+}
+
 /**
  * Thrown when unlinking an account violates security constraints (e.g. unlinking the only login provider).
  *
@@ -179,7 +200,33 @@ export declare function clearStateCookie(options?: CookieOptions): CookiePayload
 /**
  * Type representing the keys of configured providers
  */
-declare type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
+declare type ConfiguredProviderKey<TProviders extends Record<string, ProviderConfig>> = keyof TProviders & string;
+
+/**
+ * Parameters for confirming a password reset with a confirmation code or token.
+ *
+ * @public
+ */
+export declare interface ConfirmPasswordResetParams {
+    /** Username or email of the account */
+    identifier: string;
+    /** Verification code (e.g. 6-digit OTP from email/SMS) or reset token */
+    confirmationCode: string;
+    /** New plaintext password */
+    newPassword: string;
+}
+
+/**
+ * Parameters for confirming user registration with a verification code.
+ *
+ * @public
+ */
+export declare interface ConfirmSignUpParams {
+    /** Username or email of the account to confirm */
+    identifier: string;
+    /** Verification code (e.g. 6-digit OTP from email/SMS) */
+    confirmationCode: string;
+}
 
 /**
  * Represents a connected resource provider token (e.g. GitHub Repo access, Google Drive)
@@ -607,6 +654,200 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerM
  */
 export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
+/**
+ * Parameters for requesting a password reset (forgot password).
+ *
+ * @public
+ */
+export declare interface ForgotPasswordParams {
+    /** Username or email of the account requesting a password reset */
+    identifier: string;
+    /** Optional custom client metadata or redirect URL */
+    metadata?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result of a password reset request.
+ *
+ * @public
+ */
+export declare interface ForgotPasswordResult {
+    /** Whether the password reset request was accepted */
+    success: boolean;
+    /** Delivery destination description (e.g. masked email: a***@example.com or phone) */
+    deliveryMedium?: string | undefined;
+    /** Optional message or status code from provider */
+    message?: string | undefined;
+}
+
+export declare namespace identity {
+    export {
+        UserIdentity,
+        IdentityTokens,
+        IdentityAuthResult,
+        ForgotPasswordParams,
+        ForgotPasswordResult,
+        ConfirmPasswordResetParams,
+        ConfirmSignUpParams,
+        ResendConfirmationCodeParams,
+        ResendConfirmationCodeResult,
+        IIdentityProvider,
+        IdentityConfig,
+        SelfManagedIdentityProvider
+    }
+}
+
+/**
+ * Result of user authentication through an identity provider.
+ *
+ * @public
+ */
+export declare interface IdentityAuthResult {
+    /** Authenticated user profile */
+    user: UserIdentity;
+    /** Optional tokens issued by the identity provider */
+    tokens?: IdentityTokens | undefined;
+}
+
+/**
+ * Configuration options for Identity Providers in LixaConfig.
+ *
+ * @public
+ */
+export declare type IdentityConfig = IIdentityProvider | ({
+    provider?: "self-managed";
+} & CredentialsConfig);
+
+/**
+ * Thrown when identity operations (signUp, signIn, etc.) are invoked on a Lixa instance
+ * where neither identity nor credentials authentication is enabled.
+ *
+ * @public
+ */
+export declare class IdentityNotConfiguredError extends CredentialsNotConfiguredError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when an identity provider operation fails with an upstream provider error.
+ *
+ * @public
+ */
+export declare class IdentityProviderError extends LixaError {
+    readonly provider: string | undefined;
+    readonly statusCode: number | undefined;
+    constructor(message: string, provider?: string, statusCode?: number, details?: Record<string, unknown>);
+}
+
+/**
+ * Standardized token response from an identity provider.
+ *
+ * @public
+ */
+export declare interface IdentityTokens {
+    /** OAuth / IdP Access Token (JWT or opaque token) */
+    accessToken?: string | undefined;
+    /** OpenID Connect ID Token containing user claims */
+    idToken?: string | undefined;
+    /** Refresh token for renewing expired credentials */
+    refreshToken?: string | undefined;
+    /** Token type (usually "Bearer") */
+    tokenType?: string | undefined;
+    /** Token expiration time in seconds */
+    expiresIn?: number | undefined;
+    /** Raw response object returned directly by the provider */
+    raw?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Unified interface for Identity Providers in Lixa.
+ *
+ * @remarks
+ * Implement this interface to create custom identity providers (e.g. Supabase Auth,
+ * Firebase Auth, Keycloak, or proprietary enterprise directories).
+ *
+ * Built-in extensions for AWS Cognito, Auth0, and Okta are available in `@vunexa/lixa-extensions`.
+ *
+ * @public
+ */
+export declare interface IIdentityProvider {
+    /**
+     * Unique name of the identity provider.
+     * Examples: 'self-managed', 'cognito', 'auth0', 'okta'
+     */
+    readonly name: string;
+    /**
+     * Registers a new user with the identity provider.
+     *
+     * @param params - User registration details (identifier, password, email, username, metadata)
+     * @returns Created user identity
+     */
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    /**
+     * Authenticates a user with credentials.
+     *
+     * @param params - Sign in credentials (identifier, password)
+     * @returns Authenticated user identity and optional provider tokens
+     */
+    signIn(params: SignInParams): Promise<IdentityAuthResult>;
+    /**
+     * Verifies credentials without necessarily creating a full session.
+     *
+     * @param params - Verification parameters
+     * @returns User identity if credentials are valid, null otherwise
+     */
+    verifyCredentials?(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
+    /**
+     * Changes a user's password.
+     *
+     * @param params - Old password, new password, and user identifier
+     * @returns True if password was successfully updated
+     */
+    changePassword?(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Requests a password reset (forgot password flow).
+     *
+     * @param params - Forgot password parameters
+     */
+    forgotPassword?(params: ForgotPasswordParams): Promise<ForgotPasswordResult>;
+    /**
+     * Confirms password reset with verification code and new password.
+     *
+     * @param params - Confirm password reset parameters
+     */
+    confirmPasswordReset?(params: ConfirmPasswordResetParams): Promise<boolean>;
+    /**
+     * Confirms user registration using a verification code.
+     *
+     * @param params - Confirm sign up parameters
+     */
+    confirmSignUp?(params: ConfirmSignUpParams): Promise<boolean>;
+    /**
+     * Resends the sign up confirmation code.
+     *
+     * @param params - Resend confirmation code parameters
+     */
+    resendConfirmationCode?(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    /**
+     * Retrieves a user by their unique ID.
+     *
+     * @param id - Unique user ID
+     */
+    getUserById?(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (email or username).
+     *
+     * @param identifier - Username or email string
+     */
+    getUserByIdentifier?(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user account.
+     *
+     * @param id - Unique user ID
+     */
+    deleteUser?(id: string): Promise<void>;
+}
+
 /**
  * Thrown when user credentials (username/email and password) are invalid during authentication.
  *
@@ -809,6 +1050,10 @@ export declare interface IProvider {
      * @example ['openid', 'email', 'profile'] or ['read:user', 'user:email']
      */
     authScopes?: string[];
+    /**
+     * Default OAuth scopes requested when not explicitly specified in ProviderConfig.
+     */
+    defaultScopes?: string[];
 }
 
 /**
@@ -822,7 +1067,7 @@ export declare function isProductionEnvironment(): boolean;
  *
  * @public
  */
-declare interface LinkedAccount {
+export declare interface LinkedAccount {
     /** The provider identifier (e.g. 'github', 'google') */
     provider: string;
     /** Provider user ID if available */
@@ -889,20 +1134,25 @@ declare interface LinkedAccount {
  *
  * @public
  */
-export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+export declare class Lixa<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     private static DEFAULT_PROVIDERS;
     private static CONFIGURED_PROVIDERS;
     private localStateHandler;
     private localSessionHandler;
     private localResourceHandler;
+    private localAccountHandler;
     private userResourceStore;
+    private userAccountStore;
     private refreshMutexes;
+    private identityProvider?;
     private credentialsManager?;
     private config;
     private stateHandler;
     private sessionHandler;
     private resourceHandler;
+    private accountHandler;
     private debug;
+    private sessionCookieResolver?;
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
@@ -916,7 +1166,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * @throws Error when provider implementation is missing required properties
      * @throws Error when provider is not available and no inline implementation is provided
      */
-    constructor(config: TConfig);
+    constructor(config: LixaConfig<TProviders>);
     /**
      * Validates that a provider configuration has all required credentials.
      *
@@ -957,7 +1207,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * }
      * ```
      */
-    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TProviders>;
     /**
      * Gets a provider implementation by name.
      * Resolution priority: inline custom provider \> default providers \> legacy registry
@@ -1138,7 +1388,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * res.redirect(authUrl);
      * ```
      */
-    getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
+    getAuthUrl(provider: ConfiguredProviderKey<TProviders> | string, state?: string): Promise<string>;
     /**
      * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
      */
@@ -1162,10 +1412,11 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * });
      * ```
      */
-    handleCallback({ provider, code, state, }: {
-        provider: ConfiguredProviderKey<TConfig> | string;
+    handleCallback({ provider, code, state, sessionId, }: {
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
+        sessionId?: string;
     }): Promise<string>;
     /**
      * Explicitly link a new OAuth provider account to an active session.
@@ -1175,7 +1426,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     linkAccount(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
     }): Promise<string>;
@@ -1200,8 +1451,8 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     getResourceAuthUrl(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
-        scopes: string[];
+        provider: ConfiguredProviderKey<TProviders> | string;
+        scopes?: string[];
         state?: string;
         prompt?: string;
         extraConfig?: Record<string, string>;
@@ -1212,11 +1463,32 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     handleResourceCallback(params: {
         sessionId: string;
-        provider: ConfiguredProviderKey<TConfig> | string;
+        provider: ConfiguredProviderKey<TProviders> | string;
         code: string;
         state?: string;
         scopes?: string[];
     }): Promise<Session>;
+    /**
+     * Retrieves configured default resource scopes for a provider.
+     *
+     * @param provider - Provider name (e.g. 'github', 'google')
+     * @returns Array of configured resource scopes, or undefined if not configured
+     */
+    getResourceScopes(provider: ConfiguredProviderKey<TProviders> | string): string[] | undefined;
+    /**
+     * Returns the resolved session cookie name.
+     * Dynamically reflects any changes to the active identity provider.
+     *
+     * @param req - Optional request object for multi-tenant request-scoped cookie resolution
+     * @returns Resolved session cookie name
+     */
+    getSessionCookieName(req?: unknown): string;
+    /**
+     * Sets or updates the session cookie name or dynamic resolver on this instance.
+     *
+     * @param resolver - Static cookie name or dynamic resolver function
+     */
+    setSessionCookieName(resolver: SessionCookieResolver<Lixa<TProviders>>): void;
     /**
      * Retrieves a connected resource for a specific User ID / Email directly (independent of session IDs).
      * Automatically refreshes expired access tokens if a refresh token is present.
@@ -1272,46 +1544,60 @@ 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 credentials authentication is available
+     * @returns True if identity provider is configured and available
+     */
+    isIdentityEnabled(): boolean;
+    /**
+     * Checks if credentials / identity authentication is configured and enabled.
+     *
+     * @returns True if credentials / identity authentication is available
      */
     isCredentialsEnabled(): boolean;
     /**
-     * Returns the underlying CredentialsManager instance if configured.
+     * Returns the configured IdentityProvider instance.
+     */
+    getIdentityProvider(): IIdentityProvider | undefined;
+    /**
+     * Dynamically sets or updates the active identity provider (e.g. SelfManaged, Cognito, Auth0, Okta).
+     *
+     * @param provider - Identity provider instance or undefined to disable
+     */
+    setIdentityProvider(provider?: IIdentityProvider): void;
+    /**
+     * Returns the underlying CredentialsManager instance if using Self-Managed identity.
      */
     getCredentialsManager(): CredentialsManager | undefined;
     /**
-     * Registers a new user with username/email and password.
-     * Automatically enforces password policy, hashes password with Scrypt/configured hasher,
-     * stores credentials, and creates a session (unless autoCreateSessionOnSignUp is false).
+     * Registers a new user with the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+     * Automatically creates an active session unless autoCreateSessionOnSignUp is explicitly set to false.
      *
      * @param params - Registration parameters (identifier, password, email, username, metadata)
-     * @returns Created user (without password hash) and optional active session
+     * @returns Created user identity and optional active session
      * @throws WeakPasswordError if password does not meet policy requirements
      * @throws UserAlreadyExistsError if identifier is already registered
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @throws IdentityNotConfiguredError if identity authentication is not configured
      */
     signUp(params: SignUpParams): Promise<SignUpResult>;
     /**
-     * Authenticates a user with username/email and password.
-     * Performs constant-time verification with timing attack mitigation, and creates an active session.
-     * If account linking is configured with AUTO_LINK_BY_VERIFIED_EMAIL, merges with existing session.
+     * Authenticates a user with credentials via the configured identity provider (Self-Managed DB, Cognito, Auth0, Okta).
+     * Creates an active session and automatically links with existing sessions when AUTO_LINK_BY_VERIFIED_EMAIL is configured.
      *
      * @param params - Sign-in parameters (identifier, password)
      * @returns Authenticated user, session ID, and session object
      * @throws InvalidCredentialsError if authentication fails
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @throws IdentityNotConfiguredError if identity authentication is not configured
      */
     signIn(params: SignInParams): Promise<SignInResult>;
     /**
      * Verifies username/email and password credentials without generating a session.
      *
      * @param params - Verification parameters (identifier, password)
-     * @returns User credentials (without password hash) or null if invalid
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @returns User credentials/identity or null if invalid
+     * @throws IdentityNotConfiguredError if identity auth is not configured
      */
-    verifyCredentials(params: VerifyCredentialsParams): Promise<Omit<UserCredentials, "passwordHash"> | null>;
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
     /**
      * Updates a user's password after verifying the current password and enforcing policy on the new password.
      *
@@ -1320,9 +1606,63 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * @throws UserNotFoundError if user is not found
      * @throws InvalidCredentialsError if current password is incorrect
      * @throws WeakPasswordError if new password does not meet policy requirements
-     * @throws CredentialsNotConfiguredError if credentials auth is not configured
+     * @throws IdentityNotConfiguredError if identity auth is not configured
      */
     changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Initiates a password reset (forgot password flow) through the configured identity provider.
+     *
+     * @param params - Forgot password parameters (identifier, optional metadata)
+     * @returns ForgotPasswordResult indicating status and delivery medium (email/SMS)
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    forgotPassword(params: ForgotPasswordParams): Promise<ForgotPasswordResult>;
+    /**
+     * Confirms a password reset using a verification code / token and sets the new password.
+     *
+     * @param params - Verification code, identifier, and new password
+     * @returns True if password reset was successfully confirmed
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     */
+    confirmPasswordReset(params: ConfirmPasswordResetParams): Promise<boolean>;
+    /**
+     * Confirms user account registration using a verification code.
+     *
+     * @param params - Verification parameters including identifier and confirmationCode
+     * @returns True if confirmation was successful
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     * @throws IdentityProviderError if identity provider does not support confirmation
+     */
+    confirmSignUp(params: ConfirmSignUpParams): Promise<boolean>;
+    /**
+     * Resends the sign up confirmation code to the user.
+     *
+     * @param params - Resend parameters including user identifier
+     * @returns Details about the code delivery (medium, destination)
+     * @throws IdentityNotConfiguredError if identity auth is not configured
+     * @throws IdentityProviderError if identity provider does not support resending codes
+     */
+    resendConfirmationCode(params: ResendConfirmationCodeParams): Promise<ResendConfirmationCodeResult>;
+    /**
+     * Retrieves a user by their unique ID from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     * @returns UserIdentity or null if not found
+     */
+    getUserById(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (username or email) from the configured identity provider.
+     *
+     * @param identifier - Username or email string
+     * @returns UserIdentity or null if not found
+     */
+    getUserByIdentifier(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user account from the configured identity provider.
+     *
+     * @param id - Unique user ID
+     */
+    deleteUser(id: string): Promise<void>;
     private findProviderByType;
 }
 
@@ -1334,18 +1674,50 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
  */
 export declare interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
     /**
-     * Map of provider names to their configurations.
+     * Map of federated OAuth 2.0 / OIDC provider names to their configurations (Google, GitHub, etc.)
+     * that federate with and work alongside the primary identityProvider.
      * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
      */
+    federatedOAuthProviders?: TProviders;
+    /**
+     * Alias for {@link LixaConfig.federatedOAuthProviders}.
+     */
     providers?: TProviders;
+    /**
+     * Primary Identity Provider configuration (Self-Managed Database, AWS Cognito, Auth0, Okta, or custom IIdentityProvider).
+     *
+     * @example
+     * Self-managed with Prisma:
+     * ```typescript
+     * identityProvider: { storage: prismaAdapter.credentialsStorage }
+     * ```
+     *
+     * @example
+     * AWS Cognito:
+     * ```typescript
+     * identityProvider: new CognitoIdentityProvider({ userPoolId: '...', clientId: '...', region: 'us-east-1' })
+     * ```
+     */
+    identityProvider?: IIdentityProvider | IdentityConfig;
+    /**
+     * Alias for {@link LixaConfig.identityProvider}.
+     */
+    identity?: IIdentityProvider | IdentityConfig;
     /**
      * Credentials (username and password) authentication configuration.
+     * Automatically maps to a SelfManagedIdentityProvider.
      */
     credentials?: CredentialsConfig;
+    /**
+     * Unified database storage adapter (e.g. createPrismaAdapter or createDrizzleAdapter).
+     * Automatically configures sessionHandler, stateHandler, and resourceHandler.
+     */
+    storage?: StorageAdapter;
     /**
      * Account linking configuration for multi-SSO user linking.
+     * Pass `true` or `"linkByEmail"` for automatic email-verified linking.
      */
-    accountLinking?: AccountLinkingConfig;
+    accountLinking?: boolean | AccountLinkingMode | AccountLinkingConfig;
     /**
      * Optional custom state handler.
      * Handles state generation and storage during OAuth authorization flow.
@@ -1389,6 +1761,23 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * If provided, all Lixa logs will be routed through this logger.
      */
     logger?: LixaLogger;
+    /**
+     * Session cookie name or dynamic resolution function.
+     * Can accept a static string or `(lixa: Lixa, req?: unknown) => string`.
+     * Automatically evaluated live against the instance when getSessionCookieName() is called.
+     */
+    sessionCookieName?: SessionCookieResolver;
+}
+
+/**
+ * Interface exposing identity information for dynamic session cookie name resolution.
+ * @public
+ */
+export declare interface LixaCookieContext {
+    /**
+     * Retrieves the currently active identity provider.
+     */
+    getIdentityProvider(): IIdentityProvider | undefined;
 }
 
 /**
@@ -1439,7 +1828,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.
@@ -1635,8 +2024,13 @@ export declare type ProviderConfig = {
     clientSecret: string;
     /** The redirect URI registered with the provider */
     redirectUri: string;
-    /** Array of OAuth scopes to request */
-    scopes: string[];
+    /** Array of OAuth scopes to request. If omitted, uses provider default identity scopes. */
+    scopes?: string[];
+    /**
+     * Default scopes requested when connecting this provider as a third-party resource (AuthZ).
+     * Used automatically by getResourceAuthUrl() and handleResourceCallback() if not overridden at runtime.
+     */
+    resourceScopes?: string[];
     /**
      * Set to true to allow non-identity (resource) scopes during primary authentication flow.
      * By default (false), Lixa restricts primary AuthN scopes to identity scopes to maintain
@@ -1689,6 +2083,30 @@ export declare class RefreshTokenError extends LixaError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
+/**
+ * Parameters for resending a sign up confirmation code.
+ *
+ * @public
+ */
+export declare interface ResendConfirmationCodeParams {
+    /** Username or email of the account */
+    identifier: string;
+}
+
+/**
+ * Result of resending a sign up confirmation code.
+ *
+ * @public
+ */
+export declare interface ResendConfirmationCodeResult {
+    /** True if code was dispatched */
+    success: boolean;
+    /** Delivery medium (e.g. 'EMAIL' or 'SMS') */
+    deliveryMedium?: string | undefined;
+    /** Obscured destination */
+    destination?: string | undefined;
+}
+
 /**
  * Resource handler configuration.
  *
@@ -1806,6 +2224,55 @@ 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;
+    constructor(configOrManager?: CredentialsConfig | CredentialsManager);
+    private mapUser;
+    /**
+     * Registers a new user.
+     */
+    signUp(params: SignUpParams): Promise<UserIdentity>;
+    /**
+     * Authenticates a user with password.
+     */
+    signIn(params: SignInParams): Promise<IdentityAuthResult>;
+    /**
+     * Verifies credentials without throwing an error if invalid.
+     */
+    verifyCredentials(params: VerifyCredentialsParams): Promise<UserIdentity | null>;
+    /**
+     * Changes a user's password.
+     */
+    changePassword(params: ChangePasswordParams): Promise<boolean>;
+    /**
+     * Retrieves a user by their unique ID.
+     */
+    getUserById(id: string): Promise<UserIdentity | null>;
+    /**
+     * Retrieves a user by their identifier (email or username).
+     */
+    getUserByIdentifier(identifier: string): Promise<UserIdentity | null>;
+    /**
+     * Deletes a user from storage if supported by the storage adapter.
+     */
+    deleteUser(id: string): Promise<void>;
+    /**
+     * Returns the underlying CredentialsManager instance.
+     */
+    getCredentialsManager(): CredentialsManager;
+}
+
 /**
  * Serializes a cookie name, value, and options into a standard `Set-Cookie` header string.
  *
@@ -1832,9 +2299,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 +2328,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.
  *
@@ -2024,9 +2499,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 */
@@ -2056,9 +2531,9 @@ 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 */
@@ -2258,6 +2733,19 @@ export declare interface StateStorage {
     deleteState(state: string): Promise<void>;
 }
 
+/**
+ * Unified storage adapter interface (e.g. Prisma or Drizzle adapter).
+ * When provided to Lixa via config.storage, automatically configures session, state, and resource storage.
+ * @public
+ */
+declare interface StorageAdapter {
+    sessionStorage?: any;
+    resourceStorage?: any;
+    stateStorage?: any;
+    credentialsStorage?: any;
+    accountStorage?: any;
+}
+
 /**
  * Thrown when exchanging an authorization code for OAuth tokens fails at the provider endpoint.
  *
@@ -2301,6 +2789,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
  *