@vunexa/lixa 0.0.1-alpha.3 → 0.0.1-alpha.33

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

@@ -0,0 +1,1220 @@
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+ *
+ * @remarks
+ * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
+ *
+ * Key features:
+ * - OAuth 2.0 authorization code flow with PKCE (RFC 6749, RFC 7636)
+ * - OpenID Connect support
+ * - Built-in providers available in \@vunexa/lixa-providers
+ * - Custom provider support via IProvider interface
+ * - Extensible session management via SessionDao.CreateSession
+ * - Pluggable state and session storage via StateDao and SessionDao
+ * - TypeScript-first with comprehensive type safety
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Type representing the keys of configured providers
+ */
+declare type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
+
+/**
+ * Decode JWT ID token to extract user information
+ *
+ * @public
+ */
+export declare function decodeIdToken(idToken: string): UserInfo;
+
+/**
+ * Determine OAuth provider from ID token issuer
+ *
+ * @public
+ */
+export declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
+
+/**
+ * Extract user info from OAuth token data
+ *
+ * @param tokenData - OAuth token response from provider
+ * @param providerMetadata - Provider metadata containing endpoints configuration
+ * @returns User info extracted from token or fetched from provider
+ *
+ * @remarks
+ * This function attempts to extract user information in the following order:
+ * 1. Decode ID token if present (preferred method for OIDC providers)
+ * 2. Fetch from userinfo endpoint using access token (uses providerMetadata.endpoints.userInfo)
+ *
+ * The function automatically determines the best method based on available token data.
+ * For OIDC providers (like Google), it decodes the JWT ID token.
+ * For OAuth-only providers (like GitHub), it fetches from the userinfo endpoint.
+ *
+ * @throws Error if no ID token or access token is available
+ * @throws Error if userinfo endpoint is required but not provided in providerMetadata
+ *
+ * @example
+ * With ID token (OIDC provider like Google):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @example
+ * Without ID token (OAuth provider like GitHub):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * // Automatically fetches from providerMetadata.endpoints.userInfo
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @public
+ */
+export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<{
+    userInfo: UserInfo;
+}>;
+
+/**
+ * Fetch user info from OAuth provider's userinfo endpoint
+ *
+ * @param accessToken - OAuth access token
+ * @param userInfoEndpoint - The provider's userinfo endpoint URL
+ * @param providerName - Provider name for error messages (optional)
+ * @returns User information from the provider
+ *
+ * @throws Error if the request fails or response is invalid
+ *
+ * @public
+ */
+export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
+
+/**
+ * Interface for OAuth 2.0 and OpenID Connect provider implementations.
+ *
+ * @remarks
+ * Implement this interface to add support for custom OAuth providers.
+ * Each provider defines the three core endpoints required for the OAuth 2.0
+ * authorization code flow with PKCE.
+ *
+ * Built-in providers (Google, GitHub) are available in the \@vunexa/lixa-providers package.
+ *
+ * All implementations must comply with:
+ * - RFC 6749 (OAuth 2.0)
+ * - RFC 7636 (PKCE)
+ * - OpenID Connect Core 1.0 (for OIDC providers)
+ *
+ * @example
+ * Custom provider implementation:
+ * ```typescript
+ * import { IProvider } from '@vunexa/lixa';
+ *
+ * class CustomProvider implements IProvider {
+ *   authorizationEndpoint = 'https://auth.example.com/oauth/authorize';
+ *   tokenEndpoint = 'https://auth.example.com/oauth/token';
+ *   userInfoEndpoint = 'https://api.example.com/user';
+ * }
+ *
+ * // Use in configuration
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: new CustomProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://app.com/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Object literal provider:
+ * ```typescript
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+ *   tokenEndpoint: 'https://auth.example.com/oauth/token',
+ *   userInfoEndpoint: 'https://api.example.com/user'
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare interface IProvider {
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     *
+     * @remarks
+     * This is the URL where users are redirected to authenticate and authorize your application.
+     * The endpoint must support the OAuth 2.0 authorization code flow with PKCE.
+     *
+     * Standard query parameters sent to this endpoint:
+     * - client_id: Your application's client ID
+     * - redirect_uri: Where to redirect after authorization
+     * - response_type: Always "code" for authorization code flow
+     * - scope: Space-separated list of requested scopes
+     * - state: Random string for CSRF protection
+     * - code_challenge: PKCE code challenge (SHA-256 hash)
+     * - code_challenge_method: Always "S256" for SHA-256
+     *
+     * @example
+     * ```typescript
+     * authorizationEndpoint = 'https://accounts.google.com/o/oauth2/v2/auth'
+     * ```
+     */
+    authorizationEndpoint: string;
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     *
+     * @remarks
+     * This is the URL where authorization codes are exchanged for access tokens.
+     * The endpoint must support the OAuth 2.0 token exchange with PKCE.
+     *
+     * Standard parameters sent to this endpoint (POST request):
+     * - grant_type: Always "authorization_code"
+     * - code: The authorization code from the callback
+     * - redirect_uri: Must match the authorization request
+     * - client_id: Your application's client ID
+     * - client_secret: Your application's client secret
+     * - code_verifier: PKCE code verifier (original random string)
+     *
+     * Expected response:
+     * - access_token: OAuth access token
+     * - token_type: Token type (usually "Bearer")
+     * - expires_in: Token expiration time in seconds
+     * - refresh_token: Refresh token (optional)
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @example
+     * ```typescript
+     * tokenEndpoint = 'https://oauth2.googleapis.com/token'
+     * ```
+     */
+    tokenEndpoint: string;
+    /**
+     * The user information endpoint URL.
+     *
+     * @remarks
+     * This is the URL where user profile information can be retrieved using the access token.
+     * For OpenID Connect providers, this is the UserInfo endpoint.
+     *
+     * The endpoint is called with the access token in the Authorization header:
+     * ```
+     * Authorization: Bearer <access_token>
+     * ```
+     *
+     * Common response fields:
+     * - sub: Subject identifier (user ID)
+     * - email: User's email address
+     * - name: User's full name
+     * - picture: User's profile picture URL
+     * - email_verified: Whether email is verified
+     *
+     * Note: This endpoint is not called automatically by Lixa. Your SessionStrategy
+     * can call it if needed to fetch user profile information.
+     *
+     * @example
+     * ```typescript
+     * userInfoEndpoint = 'https://www.googleapis.com/oauth2/v2/userinfo'
+     * ```
+     */
+    userInfoEndpoint: string;
+}
+
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
+ *
+ * @remarks
+ * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ * Providers can be passed inline in the configuration, eliminating the need for pre-registration.
+ *
+ * @example
+ * Using built-in providers from \@vunexa/lixa-providers:
+ * ```typescript
+ * import { Lixa } from '@vunexa/lixa';
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Using custom inline providers:
+ * ```typescript
+ * import { Lixa, IProvider } from '@vunexa/lixa';
+ *
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://custom.com/oauth/authorize',
+ *   tokenEndpoint: 'https://custom.com/oauth/token',
+ *   userInfoEndpoint: 'https://custom.com/api/user'
+ * };
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: customProvider,
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/custom/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+    private static DEFAULT_PROVIDERS;
+    private static CONFIGURED_PROVIDERS;
+    private static LOCAL_STATE_HANDLER;
+    private static LOCAL_SESSION_HANDLER;
+    private config;
+    private stateHandler;
+    private sessionHandler;
+    private debug;
+    /**
+     * Creates a new Lixa instance with the provided configuration.
+     *
+     * @remarks
+     * Providers can be passed inline in the configuration using the `provider` field.
+     * Provider resolution priority: inline custom provider \> default providers \> legacy registry.
+     *
+     * @param config - The configuration object containing provider settings and optional session strategy
+     *
+     * @throws Error when provider configuration is missing required fields
+     * @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);
+    /**
+     * Validates that a provider configuration has all required credentials.
+     *
+     * @param name - The provider name
+     * @param config - The provider configuration
+     * @throws Error when required fields are missing or invalid
+     */
+    private validateProviderConfig;
+    /**
+     * Validates that a provider implementation has all required properties.
+     *
+     * @param name - The provider name
+     * @param provider - The provider implementation
+     * @throws Error when required properties are missing
+     */
+    private validateProviderImplementation;
+    /**
+     * Structured debug logging with standardized format.
+     *
+     * @param level - Log level (INFO, WARN, ERROR)
+     * @param context - Context of the log (Init, Auth, Token, Session, State)
+     * @param message - Log message
+     * @param data - Optional data to log
+     *
+     * @remarks
+     * Format: [Lixa] [timestamp] [level] [context] message
+     * Only logs when debug mode is enabled.
+     */
+    private log;
+    /**
+     * Checks if a provider is configured for this instance.
+     * This is a type guard that narrows the provider type for use with getAuthUrl.
+     *
+     * @param provider - The provider name to check (case-insensitive)
+     * @returns True if the provider is configured, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (lixa.isProviderConfigured(provider)) {
+     *   // TypeScript now knows provider is a valid ConfiguredProviderKey
+     *   const authUrl = lixa.getAuthUrl(provider, state);
+     * }
+     * ```
+     */
+    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    /**
+     * Gets a provider implementation by name.
+     * Resolution priority: inline custom provider \> default providers \> legacy registry
+     *
+     * @param name - The provider name (case-insensitive)
+     * @param config - The provider configuration
+     * @returns The provider implementation
+     * @throws Error when provider is not found
+     */
+    private getProvider;
+    /**
+     * Registers custom OAuth providers for use with Lixa.
+     *
+     * @deprecated This method is maintained for backward compatibility.
+     * The recommended approach is to pass providers inline in the configuration:
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     custom: {
+     *       provider: new CustomProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @param providerMap - A map of provider names to IProvider implementations
+     *
+     * @example
+     * Legacy usage (still supported):
+     * ```typescript
+     * class CustomProvider implements IProvider {
+     *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
+     *   tokenEndpoint = 'https://custom.com/oauth/token';
+     *   userInfoEndpoint = 'https://custom.com/api/user';
+     * }
+     *
+     * Lixa.registerProvider({ custom: new CustomProvider() });
+     * ```
+     */
+    static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void;
+    /**
+     * Gets the list of registered provider names.
+     *
+     * @returns Array of registered provider names
+     */
+    static getRegisteredProviders(): string[];
+    /**
+     * Creates a type-safe configuration.
+     *
+     * @deprecated This method is maintained for backward compatibility.
+     * You can now pass configuration directly to the Lixa constructor without this helper.
+     *
+     * @param config - Configuration object with provider settings
+     * @returns The same configuration object with type safety
+     *
+     * @example
+     * New approach (recommended):
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     google: {
+     *       provider: new GoogleProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<T> & {
+        providers: T;
+    }): LixaConfig<T>;
+    /**
+     * Generates a cryptographically secure random state parameter for OAuth flows.
+     *
+     * @returns A 32-character hexadecimal string
+     *
+     * @remarks
+     * The state parameter is used to prevent CSRF attacks in OAuth flows.
+     */
+    static generateRandomState(): string;
+    /**
+     * Generates a cryptographically secure code verifier for PKCE flows.
+     *
+     * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
+     *
+     * @remarks
+     * This method implements the code verifier generation as specified in RFC 7636 (PKCE).
+     *
+     * **PKCE (Proof Key for Code Exchange)** is a security extension to OAuth 2.0 that
+     * prevents authorization code interception attacks. It's especially important for
+     * public clients (mobile apps, SPAs) but is recommended for all OAuth flows.
+     *
+     * **Generation methodology:**
+     * 1. Generate 32 cryptographically random bytes using Node.js crypto.randomBytes()
+     * 2. Encode the bytes as a hexadecimal string (64 characters)
+     * 3. The verifier is stored securely and used later in the token exchange
+     *
+     * **RFC 7636 Requirements:**
+     * - Minimum length: 43 characters
+     * - Maximum length: 128 characters
+     * - Character set: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+     * - This implementation produces 64 hex characters, meeting the requirements
+     *
+     * The code verifier is:
+     * - Generated when creating the authorization URL
+     * - Stored in state cache with the state parameter
+     * - Retrieved during callback handling
+     * - Sent to the token endpoint to prove the client's identity
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see buildCodeChallenge for the corresponding challenge generation
+     *
+     * @internal
+     */
+    private static generateCodeVerifier;
+    /**
+     * Generates a code challenge from a code verifier for PKCE flows.
+     *
+     * @param codeVerifier - The code verifier string (64 hex characters)
+     * @returns A base64url-encoded SHA-256 hash of the code verifier
+     *
+     * @remarks
+     * This method implements the code challenge generation as specified in RFC 7636 (PKCE)
+     * using the S256 (SHA-256) transformation method.
+     *
+     * **Challenge generation methodology:**
+     * 1. Hash the code verifier using SHA-256
+     * 2. Encode the hash as base64
+     * 3. Convert to base64url format (RFC 4648):
+     *    - Replace '+' with '-'
+     *    - Replace '/' with '_'
+     *    - Remove trailing '=' padding
+     *
+     * **PKCE Flow:**
+     * 1. Client generates code_verifier (random string)
+     * 2. Client creates code_challenge = BASE64URL(SHA256(code_verifier))
+     * 3. Client sends code_challenge to authorization endpoint
+     * 4. Authorization server stores the code_challenge
+     * 5. Client sends code_verifier to token endpoint
+     * 6. Authorization server verifies: SHA256(code_verifier) == code_challenge
+     *
+     * **Security Benefits:**
+     * - Prevents authorization code interception attacks
+     * - Even if an attacker intercepts the authorization code, they cannot
+     *   exchange it for tokens without the original code_verifier
+     * - The challenge is sent in the authorization request (public)
+     * - The verifier is sent in the token request (should be kept secret)
+     *
+     * **RFC 7636 Transformation Methods:**
+     * - plain: code_challenge = code_verifier (not recommended)
+     * - S256: code_challenge = BASE64URL(SHA256(code_verifier)) (recommended, used here)
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5 | RFC 4648 - Base64url Encoding}
+     * @see generateCodeVerifier for the verifier generation
+     *
+     * @internal
+     */
+    private static buildCodeChallenge;
+    /**
+     * Generates the authorization URL for the specified provider.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @param state - The state parameter for CSRF protection
+     * @returns The complete authorization URL to redirect users to
+     *
+     * @throws Error when the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const state = Lixa.generateRandomState();
+     * const authUrl = lixa.getAuthUrl('google', state);
+     * res.redirect(authUrl);
+     * ```
+     */
+    getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @param code - The authorization code from the provider
+     * @param state - The state parameter for validation
+     * @returns A Promise that resolves to the session ID
+     *
+     * @throws Error when code or state is missing/invalid, or provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const sessionId = await lixa.handleCallback({
+     *   provider: 'google',
+     *   code: req.query.code,
+     *   state: req.query.state
+     * });
+     * ```
+     */
+    handleCallback({ provider, code, state, }: {
+        provider: ConfiguredProviderKey<TConfig> | string;
+        code: string;
+        state?: string;
+    }): Promise<string>;
+    fetchSessionInfo(sessionId: string): Promise<Session | null>;
+    private exchangeCodeForToken;
+    private findProviderByType;
+}
+
+/**
+ * Main configuration object for Lixa.
+ * Provides type-safe provider name inference.
+ *
+ * @remarks
+ * The generic type parameter TProviders enables TypeScript to infer provider names
+ * from the configuration object, providing autocomplete and type checking for
+ * provider names in methods like getAuthUrl() and handleCallback().
+ *
+ * @typeParam TProviders - The provider configuration map type, defaults to a generic record
+ *
+ * @example
+ * Basic configuration with built-in providers:
+ * ```typescript
+ * import { Lixa } from '@vunexa/lixa';
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Configuration with custom session and state handlers:
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   },
+ *   stateHandler: {
+ *     storage: {
+ *       saveState: async (state, data, ttl) => await redis.setex(state, ttl, JSON.stringify(data)),
+ *       getState: async (state) => JSON.parse(await redis.get(state) || 'null'),
+ *       deleteState: async (state) => await redis.del(state)
+ *     }
+ *   },
+ *   sessionHandler: {
+ *     GenerateSession: async (tokenData, providerMetadata) => {
+ *       const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *       const user = await db.users.upsert({ email: userInfo.email });
+ *       return { token: tokenData.access_token, raw: { ...tokenData, userId: user.id } };
+ *     },
+ *     storage: {
+ *       saveSession: async (id, session, ttl) => await db.sessions.create({ id, session, ttl }),
+ *       getSession: async (id) => await db.sessions.findOne({ id }),
+ *       deleteSession: async (id) => await db.sessions.delete({ id })
+ *     }
+ *   },
+ *   debug: true
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+    /**
+     * Map of provider names to their configurations.
+     * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
+     */
+    providers: TProviders;
+    /**
+     * Optional custom state handler.
+     * Handles state generation and storage during OAuth authorization flow.
+     *
+     * - GenerateState: Customizes how state parameters and PKCE verifiers are generated
+     * - storage: Provides persistent state storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link StateHandler}
+     */
+    stateHandler?: StateHandler;
+    /**
+     * Optional custom session handler.
+     * Handles session generation and storage after authentication.
+     *
+     * - GenerateSession: Customizes how OAuth tokens are converted into session data
+     * - storage: Provides persistent session storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link SessionHandler}
+     */
+    sessionHandler?: SessionHandler;
+    /**
+     * Enable debug logging.
+     * When enabled, outputs structured logs for initialization, auth flow, and errors.
+     * Format: [Lixa] [timestamp] [level] [context] message
+     */
+    debug?: boolean;
+}
+
+/**
+ * OAuth 2.0 token response structure.
+ * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
+ *
+ * @remarks
+ * This interface represents the standard OAuth 2.0 token response with
+ * optional OpenID Connect extensions. All OAuth providers should return
+ * at minimum the required fields (access_token, token_type).
+ *
+ * @public
+ */
+export declare interface OAuthTokenResponse {
+    /**
+     * OAuth 2.0 access token (required).
+     * Used to access protected resources on behalf of the user.
+     */
+    access_token: string;
+    /**
+     * Token type (required).
+     * Typically "Bearer" for OAuth 2.0.
+     */
+    token_type: string;
+    /**
+     * Token expiration time in seconds (optional).
+     * Time until the access token expires.
+     */
+    expires_in?: number;
+    /**
+     * OAuth 2.0 refresh token (optional).
+     * Used to obtain new access tokens without re-authentication.
+     */
+    refresh_token?: string;
+    /**
+     * Granted OAuth scopes (optional).
+     * Space-separated list of scopes that were granted.
+     */
+    scope?: string;
+    /**
+     * OpenID Connect ID token (optional).
+     * JWT containing user identity claims (only present for OIDC providers).
+     */
+    id_token?: string;
+    /**
+     * Additional provider-specific fields.
+     * Some providers may include extra fields like user_id, account_id, etc.
+     */
+    [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * 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 = {
+    /** The OAuth client ID provided by the provider */
+    clientId: string;
+    /** The OAuth client secret provided by the provider */
+    clientSecret: string;
+    /** The redirect URI registered with the provider */
+    redirectUri: string;
+    /** Array of OAuth scopes to request */
+    scopes: string[];
+    /** Additional provider-specific configuration parameters */
+    extraConfig?: Record<string, string>;
+} & ({
+    provider?: never;
+} | {
+    provider: IProvider;
+});
+
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+export declare interface ProviderMetadata {
+    /** The provider name (e.g., 'google', 'github') */
+    name: string;
+    /** Provider endpoints */
+    endpoints: {
+        /** Authorization endpoint URL */
+        authorization: string;
+        /** Token endpoint URL */
+        token: string;
+        /** UserInfo endpoint URL */
+        userInfo: string;
+    };
+}
+
+/**
+ * Helper type to create a configuration with only registered providers.
+ * Use this with Lixa.createConfig() for type safety.
+ *
+ * @deprecated This type is maintained for backward compatibility.
+ * The new inline provider configuration pattern makes this unnecessary.
+ *
+ * @public
+ */
+export declare type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<TProviders> & {
+    providers: TProviders;
+};
+
+/**
+ * Represents a user session after successful OAuth authentication.
+ *
+ * @remarks
+ * The Session object is returned by SessionStrategy.createSession() and contains
+ * the session identifier and any additional data needed for your application.
+ *
+ * The structure is intentionally flexible to support various session management
+ * approaches (JWT tokens, session IDs, etc.).
+ *
+ * @public
+ */
+export declare interface Session<TRaw = OAuthTokenResponse> {
+    /**
+     * The session token or identifier.
+     * This could be an access token, a session ID, a JWT, or any other identifier
+     * that your application uses to track authenticated users.
+     */
+    token: string;
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     *
+     * Typical OAuth token data includes:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (if requested)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (if using OIDC)
+     * - scope: Granted scopes
+     */
+    raw: TRaw;
+}
+
+/**
+ * Session handler for OAuth authentication.
+ *
+ * @remarks
+ * The SessionHandler manages session generation and storage after successful OAuth authentication.
+ *
+ * - GenerateSession: Optional. Customizes how OAuth tokens are converted into session data.
+ *   If not provided, uses default implementation (access token as session token).
+ *
+ * - storage: Optional. Provides custom session storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement both GenerateSession (for user creation/lookup) and storage
+ * (for persistent session storage with Redis, database, etc.).
+ *
+ * @example
+ * Full implementation with database:
+ * ```typescript
+ * import { SessionHandler, Session, OAuthTokenResponse, ProviderMetadata, extractUserInfo } from '@vunexa/lixa';
+ *
+ * const sessionHandler: SessionHandler = {
+ *   GenerateSession: async (tokenData, providerMetadata) => {
+ *     // Extract user info and create/retrieve user
+ *     const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *     const user = await db.users.upsert({
+ *       email: userInfo.email,
+ *       name: userInfo.name
+ *     });
+ *
+ *     // Return session data (not stored yet)
+ *     return {
+ *       token: tokenData.access_token,
+ *       raw: {
+ *         ...tokenData,
+ *         userId: user.id,
+ *         provider: providerMetadata.name
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+ *       await db.sessions.create({
+ *         id: sessionId,
+ *         token: session.token,
+ *         data: session.raw,
+ *         expiresAt
+ *       });
+ *     },
+ *
+ *     getSession: async (sessionId) => {
+ *       const record = await db.sessions.findOne({
+ *         id: sessionId,
+ *         expiresAt: { $gt: new Date() }
+ *       });
+ *       return record ? { token: record.token, raw: record.data } : null;
+ *     },
+ *
+ *     deleteSession: async (sessionId) => {
+ *       await db.sessions.delete({ id: sessionId });
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const sessionHandler: SessionHandler = {
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       await redis.setex(sessionId, expiresInSeconds, JSON.stringify(session));
+ *     },
+ *     getSession: async (sessionId) => {
+ *       const data = await redis.get(sessionId);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteSession: async (sessionId) => {
+ *       await redis.del(sessionId);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare interface SessionHandler {
+    /**
+     * Generates session data from OAuth token data.
+     *
+     * @param tokenData - The token data received from the OAuth provider's token endpoint
+     * @param providerMetadata - Provider metadata including name and endpoints
+     * @returns A Promise that resolves to session data
+     *
+     * @remarks
+     * This method is responsible for creating session data from OAuth tokens.
+     * It is called after successfully exchanging the authorization code for tokens.
+     *
+     * Token Data:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (optional)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * Provider Metadata:
+     * - name: The provider name (e.g., 'google', 'github')
+     * - endpoints: Provider endpoints (authorization, token, userInfo)
+     *
+     * Your implementation should:
+     * 1. Extract user info (using extractUserInfo or decode ID token)
+     * 2. Create or lookup users in your database
+     * 3. Build and return session data with any custom fields
+     *
+     * Note: This method should NOT store the session. Storage is handled by the storage object.
+     *
+     * If not provided, defaults to using the access token as the session token.
+     *
+     * @example
+     * ```typescript
+     * GenerateSession: async (tokenData, providerMetadata) => {
+     *   const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+     *   const user = await db.users.upsert({ email: userInfo.email });
+     *
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: {
+     *       ...tokenData,
+     *       userId: user.id,
+     *       provider: providerMetadata.name
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+    /**
+     * Session storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting sessions.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    sessionStorage?: SessionStorage;
+    /**
+     * Optional method to generate session data from OAuth tokens.
+     *
+     * @remarks
+     * If not provided, uses default implementation from LocalSessionHandler.
+     */
+    generateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+}
+
+/**
+ * Session storage operations interface.
+ *
+ * @remarks
+ * Groups all session storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+export declare interface SessionStorage {
+    /**
+     * Saves a session with expiration.
+     *
+     * @param sessionId - Unique session identifier
+     * @param session - Session data from GenerateSession()
+     * @param expiresInSeconds - TTL in seconds (typically 86400 for 24 hours)
+     */
+    saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves a session by ID.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Session data or null if not found or expired
+     */
+    getSession<T extends Session>(sessionId: string): Promise<T | null>;
+    /**
+     * Deletes a session (e.g., on logout).
+     *
+     * @param sessionId - Unique session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * OAuth state data structure.
+ *
+ * @remarks
+ * This structure is used internally by Lixa to store OAuth flow state
+ * during the authorization process. It contains the information needed
+ * to complete the PKCE flow and route callbacks to the correct provider.
+ *
+ * @public
+ */
+export declare interface StateData {
+    /**
+     * Provider name for callback routing.
+     * Used to identify which provider configuration to use when handling the callback.
+     *
+     * @example 'google', 'github', 'custom'
+     */
+    provider: string;
+    /**
+     * PKCE code verifier for secure token exchange.
+     * A cryptographically random string (64 hex characters) used in the PKCE flow
+     * to prevent authorization code interception attacks.
+     *
+     * @see RFC 7636 - Proof Key for Code Exchange
+     */
+    codeVerifier: string;
+    /**
+     * Unix timestamp in milliseconds when the state was created.
+     * Used for debugging and validation purposes.
+     */
+    createdAt: number;
+}
+
+/**
+ * State handler for OAuth authorization flow.
+ *
+ * @remarks
+ * The StateHandler manages state generation and storage during the OAuth authorization flow.
+ *
+ * - GenerateState: Optional. Customizes how state parameters and PKCE verifiers are generated.
+ *   If not provided, uses default implementation (cryptographically secure random strings).
+ *
+ * - storage: Optional. Provides custom state storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement storage with Redis, database, or other distributed cache.
+ *
+ * @example
+ * Full implementation with Redis:
+ * ```typescript
+ * import { StateHandler, StateData } from '@vunexa/lixa';
+ *
+ * const stateHandler: StateHandler = {
+ *   GenerateState: async (provider) => {
+ *     const state = generateSecureRandomString(32);
+ *     const codeVerifier = generateSecureRandomString(64);
+ *     return {
+ *       state,
+ *       data: {
+ *         provider,
+ *         codeVerifier,
+ *         createdAt: Date.now()
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(`oauth:state:${state}`, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(`oauth:state:${state}`);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(`oauth:state:${state}`);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const stateHandler: StateHandler = {
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(state, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(state);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(state);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare interface StateHandler {
+    /**
+     * Generates OAuth state parameter and associated data.
+     *
+     * @param provider - The provider name for callback routing
+     * @returns A Promise that resolves to state string and state data
+     *
+     * @remarks
+     * This method generates:
+     * - state: A cryptographically secure random string for CSRF protection
+     * - codeVerifier: A PKCE code verifier for secure token exchange
+     * - createdAt: Timestamp for debugging
+     *
+     * If not provided, defaults to generating 32-byte hex strings for state
+     * and 64-byte hex strings for code verifier.
+     *
+     * @example
+     * ```typescript
+     * GenerateState: async (provider) => {
+     *   const state = crypto.randomBytes(16).toString('hex');
+     *   const codeVerifier = crypto.randomBytes(32).toString('hex');
+     *   return {
+     *     state,
+     *     data: {
+     *       provider,
+     *       codeVerifier,
+     *       createdAt: Date.now()
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateState?(provider: string): Promise<{
+        state: string;
+        data: StateData;
+    }>;
+    /**
+     * State storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting OAuth state.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    stateStorage?: StateStorage;
+}
+
+/**
+ * State storage operations interface.
+ *
+ * @remarks
+ * Groups all state storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+export declare interface StateStorage {
+    /**
+     * Saves OAuth state with expiration.
+     *
+     * @param state - The state parameter value (random string for CSRF protection)
+     * @param data - State data including provider name and PKCE code verifier
+     * @param expiresInSeconds - TTL in seconds (typically 300 for 5 minutes)
+     */
+    saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves OAuth state data.
+     *
+     * @param state - The state parameter value
+     * @returns State data or null if not found or expired
+     */
+    getState(state: string): Promise<StateData | null>;
+    /**
+     * Deletes OAuth state (called after successful validation).
+     *
+     * @param state - The state parameter value
+     */
+    deleteState(state: string): Promise<void>;
+}
+
+/**
+ * User information extracted from OAuth provider
+ *
+ * @public
+ */
+export declare interface UserInfo {
+    email: string;
+    id?: string | undefined;
+    sub?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    name?: string | undefined;
+    picture?: string | undefined;
+    email_verified?: boolean | undefined;
+    iss?: string | undefined;
+}
+
+export { }